feat(apps): 重构 UI 架构为 presentation 层并新增 l10n 国际化支持

apps/lib/features/ui_schema/domain/models/ui_schema.dart

@@ -0,0 +1,14 @@
+// UI Schema Protocol Implementation.
+///
+/// This file is the single source of truth for UI Schema.
+/// All implementations must follow docs/protocols/ui-schema.md.
+///
+/// Version: 1.0
+library;
+
+part 'ui_schema/enums.dart';
+part 'ui_schema/common_types.dart';
+part 'ui_schema/actions.dart';
+part 'ui_schema/nodes.dart';
+part 'ui_schema/document.dart';
+part 'ui_schema/builders.dart';

apps/lib/features/ui_schema/domain/models/ui_schema/actions.dart

@@ -0,0 +1,205 @@
+part of '../ui_schema.dart';
+
+abstract class ActionSpec {
+  String get type;
+  Map<String, dynamic> toJson();
+}
+
+class NavigateAction implements ActionSpec {
+  final String path;
+  final Map<String, dynamic>? params;
+
+  const NavigateAction({required this.path, this.params});
+
+  @override
+  String get type => 'navigation';
+
+  @override
+  Map<String, dynamic> toJson() {
+    return {'type': type, 'path': path, if (params != null) 'params': params};
+  }
+}
+
+class LinkAction implements ActionSpec {
+  final String url;
+  final String? target;
+
+  const LinkAction({required this.url, this.target});
+
+  @override
+  String get type => 'url';
+
+  @override
+  Map<String, dynamic> toJson() {
+    return {'type': type, 'url': url, if (target != null) 'target': target};
+  }
+}
+
+class EventAction implements ActionSpec {
+  final String event;
+  final Map<String, dynamic>? payload;
+
+  const EventAction({required this.event, this.payload});
+
+  @override
+  String get type => 'event';
+
+  @override
+  Map<String, dynamic> toJson() {
+    return {
+      'type': type,
+      'event': event,
+      if (payload != null) 'payload': payload,
+    };
+  }
+}
+
+class ToolAction implements ActionSpec {
+  final String toolId;
+  final Map<String, dynamic>? params;
+
+  const ToolAction({required this.toolId, this.params});
+
+  @override
+  String get type => 'tool';
+
+  @override
+  Map<String, dynamic> toJson() {
+    return {
+      'type': type,
+      'toolId': toolId,
+      if (params != null) 'params': params,
+    };
+  }
+}
+
+class CopyAction implements ActionSpec {
+  final String content;
+  final String? successMessage;
+
+  const CopyAction({required this.content, this.successMessage});
+
+  @override
+  String get type => 'copy';
+
+  @override
+  Map<String, dynamic> toJson() {
+    return {
+      'type': type,
+      'content': content,
+      if (successMessage != null) 'successMessage': successMessage,
+    };
+  }
+}
+
+class PayloadAction implements ActionSpec {
+  final Map<String, dynamic> payload;
+  final String? submitTo;
+
+  const PayloadAction({required this.payload, this.submitTo});
+
+  @override
+  String get type => 'payload';
+
+  @override
+  Map<String, dynamic> toJson() {
+    return {
+      'type': type,
+      'payload': payload,
+      if (submitTo != null) 'submitTo': submitTo,
+    };
+  }
+}
+
+ActionSpec actionSpecFromJson(Map<String, dynamic> json) {
+  final type = json['type'] as String? ?? '';
+  switch (type) {
+    case 'navigation':
+      return NavigateAction(
+        path: json['path'] as String? ?? '',
+        params: json['params'] as Map<String, dynamic>?,
+      );
+    case 'url':
+      return LinkAction(
+        url: json['url'] as String? ?? '',
+        target: json['target'] as String?,
+      );
+    case 'event':
+      return EventAction(
+        event: json['event'] as String? ?? '',
+        payload: json['payload'] as Map<String, dynamic>?,
+      );
+    case 'tool':
+      return ToolAction(
+        toolId: json['toolId'] as String? ?? '',
+        params: json['params'] as Map<String, dynamic>?,
+      );
+    case 'copy':
+      return CopyAction(
+        content: json['content'] as String? ?? '',
+        successMessage: json['successMessage'] as String?,
+      );
+    case 'payload':
+      return PayloadAction(
+        payload: json['payload'] as Map<String, dynamic>? ?? {},
+        submitTo: json['submitTo'] as String?,
+      );
+    default:
+      return EventAction(event: 'unknown');
+  }
+}
+
+class UiAction {
+  final String id;
+  final String label;
+  final UiIcon? icon;
+  final ActionStyle? style;
+  final bool disabled;
+  final ActionSpec action;
+  final ActionConfirm? confirm;
+
+  const UiAction({
+    required this.id,
+    required this.label,
+    this.icon,
+    this.style,
+    this.disabled = false,
+    required this.action,
+    this.confirm,
+  });
+
+  factory UiAction.fromJson(Map<String, dynamic> json) {
+    return UiAction(
+      id: json['id'] as String? ?? '',
+      label: json['label'] as String? ?? '',
+      icon: json['icon'] != null
+          ? UiIcon.fromJson(json['icon'] as Map<String, dynamic>)
+          : null,
+      style: json['style'] != null
+          ? ActionStyle.values.firstWhere(
+              (e) => e.value == json['style'],
+              orElse: () => ActionStyle.primary,
+            )
+          : null,
+      disabled: json['disabled'] as bool? ?? false,
+      action: actionSpecFromJson(
+        json['action'] as Map<String, dynamic>? ?? {'type': 'event'},
+      ),
+      confirm: json['confirm'] != null
+          ? ActionConfirm.fromJson(json['confirm'] as Map<String, dynamic>)
+          : null,
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'id': id,
+      'label': label,
+      if (icon != null) 'icon': icon!.toJson(),
+      if (style != null) 'style': style!.value,
+      'disabled': disabled,
+      'action': action.toJson(),
+      if (confirm != null) 'confirm': confirm!.toJson(),
+    };
+  }
+}

apps/lib/features/ui_schema/domain/models/ui_schema/builders.dart

@@ -0,0 +1,47 @@
+part of '../ui_schema.dart';
+
+UiSchemaDocument buildSuccessDocument(
+  List<UiNode> nodes, {
+  String version = '1.0',
+  SchemaType schemaType = SchemaType.toolResult,
+  String? docId,
+  String? timestamp,
+  String locale = 'zh-CN',
+  RendererConfig? renderer,
+  DocumentMeta? meta,
+}) {
+  return UiSchemaDocument(
+    version: version,
+    schemaType: schemaType,
+    docId: docId,
+    timestamp: timestamp,
+    locale: locale,
+    status: UiStatus.success,
+    renderer: renderer,
+    meta: meta,
+    nodes: nodes,
+  );
+}
+
+UiSchemaDocument buildErrorDocument(
+  List<UiNode> nodes, {
+  String version = '1.0',
+  SchemaType schemaType = SchemaType.toolResult,
+  String? docId,
+  String? timestamp,
+  String locale = 'zh-CN',
+  RendererConfig? renderer,
+  DocumentMeta? meta,
+}) {
+  return UiSchemaDocument(
+    version: version,
+    schemaType: schemaType,
+    docId: docId,
+    timestamp: timestamp,
+    locale: locale,
+    status: UiStatus.error,
+    renderer: renderer,
+    meta: meta,
+    nodes: nodes,
+  );
+}

apps/lib/features/ui_schema/domain/models/ui_schema/common_types.dart

@@ -0,0 +1,273 @@
+part of '../ui_schema.dart';
+
+class UiIcon {
+  final IconSource source;
+  final String value;
+  final String? color;
+  final int? size;
+
+  const UiIcon({
+    required this.source,
+    required this.value,
+    this.color,
+    this.size,
+  });
+
+  factory UiIcon.fromJson(Map<String, dynamic> json) {
+    return UiIcon(
+      source: IconSource.values.firstWhere(
+        (e) => e.value == json['source'],
+        orElse: () => IconSource.icon,
+      ),
+      value: json['value'] as String? ?? '',
+      color: json['color'] as String?,
+      size: json['size'] as int?,
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'source': source.value,
+      'value': value,
+      if (color != null) 'color': color,
+      if (size != null) 'size': size,
+    };
+  }
+}
+
+class UiBadge {
+  final String label;
+  final BadgeVariant variant;
+
+  const UiBadge({required this.label, this.variant = BadgeVariant.def});
+
+  factory UiBadge.fromJson(Map<String, dynamic> json) {
+    return UiBadge(
+      label: json['label'] as String? ?? '',
+      variant: BadgeVariant.values.firstWhere(
+        (e) => e.value == json['variant'],
+        orElse: () => BadgeVariant.def,
+      ),
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {'label': label, 'variant': variant.value};
+  }
+}
+
+class Pagination {
+  final int page;
+  final int pageSize;
+  final int total;
+  final bool hasMore;
+
+  const Pagination({
+    required this.page,
+    required this.pageSize,
+    required this.total,
+    required this.hasMore,
+  });
+
+  factory Pagination.fromJson(Map<String, dynamic> json) {
+    return Pagination(
+      page: json['page'] as int? ?? 1,
+      pageSize: json['pageSize'] as int? ?? 20,
+      total: json['total'] as int? ?? 0,
+      hasMore: json['hasMore'] as bool? ?? false,
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'page': page,
+      'pageSize': pageSize,
+      'total': total,
+      'hasMore': hasMore,
+    };
+  }
+}
+
+class ActionConfirm {
+  final String? title;
+  final String? message;
+  final String? confirmLabel;
+  final String? cancelLabel;
+
+  const ActionConfirm({
+    this.title,
+    this.message,
+    this.confirmLabel,
+    this.cancelLabel,
+  });
+
+  factory ActionConfirm.fromJson(Map<String, dynamic> json) {
+    return ActionConfirm(
+      title: json['title'] as String?,
+      message: json['message'] as String?,
+      confirmLabel: json['confirmLabel'] as String?,
+      cancelLabel: json['cancelLabel'] as String?,
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      if (title != null) 'title': title,
+      if (message != null) 'message': message,
+      if (confirmLabel != null) 'confirmLabel': confirmLabel,
+      if (cancelLabel != null) 'cancelLabel': cancelLabel,
+    };
+  }
+}
+
+class KeyValuePair {
+  final String key;
+  final String? label;
+  final dynamic value;
+  final bool? copyable;
+
+  const KeyValuePair({
+    required this.key,
+    this.label,
+    required this.value,
+    this.copyable,
+  });
+
+  factory KeyValuePair.fromJson(Map<String, dynamic> json) {
+    return KeyValuePair(
+      key: json['key'] as String? ?? '',
+      label: json['label'] as String?,
+      value: json['value'],
+      copyable: json['copyable'] as bool?,
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'key': key,
+      if (label != null) 'label': label,
+      'value': value,
+      if (copyable != null) 'copyable': copyable,
+    };
+  }
+}
+
+class TableColumn {
+  final String key;
+  final String label;
+  final String? width;
+  final String? align;
+
+  const TableColumn({
+    required this.key,
+    required this.label,
+    this.width,
+    this.align,
+  });
+
+  factory TableColumn.fromJson(Map<String, dynamic> json) {
+    return TableColumn(
+      key: json['key'] as String? ?? '',
+      label: json['label'] as String? ?? '',
+      width: json['width'] as String?,
+      align: json['align'] as String?,
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'key': key,
+      'label': label,
+      if (width != null) 'width': width,
+      if (align != null) 'align': align,
+    };
+  }
+}
+
+class TableRow {
+  final String id;
+  final Map<String, dynamic> cells;
+  final Map<String, dynamic>? metadata;
+  final List<UiAction>? actions;
+
+  const TableRow({
+    required this.id,
+    required this.cells,
+    this.metadata,
+    this.actions,
+  });
+
+  factory TableRow.fromJson(Map<String, dynamic> json) {
+    return TableRow(
+      id: json['id'] as String? ?? '',
+      cells: json['cells'] as Map<String, dynamic>? ?? {},
+      metadata: json['metadata'] as Map<String, dynamic>?,
+      actions: (json['actions'] as List<dynamic>?)
+          ?.map((e) => UiAction.fromJson(e as Map<String, dynamic>))
+          .toList(),
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'id': id,
+      'cells': cells,
+      if (metadata != null) 'metadata': metadata,
+      if (actions != null) 'actions': actions!.map((e) => e.toJson()).toList(),
+    };
+  }
+}
+
+class ListItem {
+  final String id;
+  final String title;
+  final String? subtitle;
+  final String? description;
+  final UiIcon? icon;
+  final UiBadge? badge;
+  final Map<String, dynamic>? metadata;
+  final List<UiAction>? actions;
+
+  const ListItem({
+    required this.id,
+    required this.title,
+    this.subtitle,
+    this.description,
+    this.icon,
+    this.badge,
+    this.metadata,
+    this.actions,
+  });
+
+  factory ListItem.fromJson(Map<String, dynamic> json) {
+    return ListItem(
+      id: json['id'] as String? ?? '',
+      title: json['title'] as String? ?? '',
+      subtitle: json['subtitle'] as String?,
+      description: json['description'] as String?,
+      icon: json['icon'] != null
+          ? UiIcon.fromJson(json['icon'] as Map<String, dynamic>)
+          : null,
+      badge: json['badge'] != null
+          ? UiBadge.fromJson(json['badge'] as Map<String, dynamic>)
+          : null,
+      metadata: json['metadata'] as Map<String, dynamic>?,
+      actions: (json['actions'] as List<dynamic>?)
+          ?.map((e) => UiAction.fromJson(e as Map<String, dynamic>))
+          .toList(),
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'id': id,
+      'title': title,
+      if (subtitle != null) 'subtitle': subtitle,
+      if (description != null) 'description': description,
+      if (icon != null) 'icon': icon!.toJson(),
+      if (badge != null) 'badge': badge!.toJson(),
+      if (metadata != null) 'metadata': metadata,
+      if (actions != null) 'actions': actions!.map((e) => e.toJson()).toList(),
+    };
+  }
+}

apps/lib/features/ui_schema/domain/models/ui_schema/document.dart

@@ -0,0 +1,128 @@
+part of '../ui_schema.dart';
+
+class RendererConfig {
+  final String? renderer;
+  final RendererTheme? theme;
+
+  const RendererConfig({this.renderer, this.theme});
+
+  factory RendererConfig.fromJson(Map<String, dynamic> json) {
+    return RendererConfig(
+      renderer: json['renderer'] as String?,
+      theme: json['theme'] != null
+          ? RendererTheme.values.firstWhere(
+              (e) => e.value == json['theme'],
+              orElse: () => RendererTheme.def,
+            )
+          : null,
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      if (renderer != null) 'renderer': renderer,
+      if (theme != null) 'theme': theme!.value,
+    };
+  }
+}
+
+class DocumentMeta {
+  final String? requestId;
+  final String? toolId;
+  final String? traceId;
+  final String? userId;
+  final Map<String, dynamic>? extra;
+
+  const DocumentMeta({
+    this.requestId,
+    this.toolId,
+    this.traceId,
+    this.userId,
+    this.extra,
+  });
+
+  factory DocumentMeta.fromJson(Map<String, dynamic> json) {
+    return DocumentMeta(
+      requestId: json['requestId'] as String?,
+      toolId: json['toolId'] as String?,
+      traceId: json['traceId'] as String?,
+      userId: json['userId'] as String?,
+      extra: json,
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      if (requestId != null) 'requestId': requestId,
+      if (toolId != null) 'toolId': toolId,
+      if (traceId != null) 'traceId': traceId,
+      if (userId != null) 'userId': userId,
+    };
+  }
+}
+
+class UiSchemaDocument {
+  final String version;
+  final SchemaType schemaType;
+  final String? docId;
+  final String? timestamp;
+  final String? locale;
+  final UiStatus status;
+  final RendererConfig? renderer;
+  final DocumentMeta? meta;
+  final List<UiNode> nodes;
+
+  const UiSchemaDocument({
+    required this.version,
+    required this.schemaType,
+    this.docId,
+    this.timestamp,
+    this.locale,
+    required this.status,
+    this.renderer,
+    this.meta,
+    required this.nodes,
+  });
+
+  factory UiSchemaDocument.fromJson(Map<String, dynamic> json) {
+    return UiSchemaDocument(
+      version: json['version'] as String? ?? '1.0',
+      schemaType: SchemaType.values.firstWhere(
+        (e) => e.value == json['schemaType'],
+        orElse: () => SchemaType.toolResult,
+      ),
+      docId: json['docId'] as String?,
+      timestamp: json['timestamp'] as String?,
+      locale: json['locale'] as String?,
+      status: UiStatus.values.firstWhere(
+        (e) => e.value == json['status'],
+        orElse: () => UiStatus.info,
+      ),
+      renderer: json['renderer'] != null
+          ? RendererConfig.fromJson(json['renderer'] as Map<String, dynamic>)
+          : null,
+      meta: json['meta'] != null
+          ? DocumentMeta.fromJson(json['meta'] as Map<String, dynamic>)
+          : null,
+      nodes:
+          (json['nodes'] as List<dynamic>?)
+              ?.map((e) => UiNode.fromJson(e as Map<String, dynamic>))
+              .toList() ??
+          [],
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'version': version,
+      'schemaType': schemaType.value,
+      if (docId != null) 'docId': docId,
+      if (timestamp != null) 'timestamp': timestamp,
+      if (locale != null) 'locale': locale,
+      'status': status.value,
+      if (renderer != null) 'renderer': renderer!.toJson(),
+      if (meta != null) 'meta': meta!.toJson(),
+      'nodes': nodes.map((e) => (e as dynamic).toJson()).toList(),
+    };
+  }
+}

apps/lib/features/ui_schema/domain/models/ui_schema/enums.dart

@@ -0,0 +1,104 @@
+part of '../ui_schema.dart';
+
+enum SchemaType {
+  toolResult('tool_result'),
+  agentResponse('agent_response'),
+  notification('notification');
+
+  final String value;
+  const SchemaType(this.value);
+}
+
+enum UiStatus {
+  info('info'),
+  success('success'),
+  warning('warning'),
+  error('error'),
+  pending('pending');
+
+  final String value;
+  const UiStatus(this.value);
+}
+
+enum IconSource {
+  icon('icon'),
+  emoji('emoji'),
+  url('url');
+
+  final String value;
+  const IconSource(this.value);
+}
+
+enum OperationType {
+  create('create'),
+  update('update'),
+  delete('delete'),
+  execute('execute');
+
+  final String value;
+  const OperationType(this.value);
+}
+
+enum OperationResult {
+  success('success'),
+  failure('failure'),
+  partial('partial');
+
+  final String value;
+  const OperationResult(this.value);
+}
+
+enum ContainerDirection {
+  vertical('vertical'),
+  horizontal('horizontal');
+
+  final String value;
+  const ContainerDirection(this.value);
+}
+
+enum TextFormat {
+  plain('plain'),
+  markdown('markdown');
+
+  final String value;
+  const TextFormat(this.value);
+}
+
+enum KvLayout {
+  vertical('vertical'),
+  horizontal('horizontal'),
+  grid('grid');
+
+  final String value;
+  const KvLayout(this.value);
+}
+
+enum BadgeVariant {
+  def('default'),
+  success('success'),
+  warning('warning'),
+  error('error'),
+  info('info');
+
+  final String value;
+  const BadgeVariant(this.value);
+}
+
+enum ActionStyle {
+  primary('primary'),
+  secondary('secondary'),
+  ghost('ghost'),
+  danger('danger');
+
+  final String value;
+  const ActionStyle(this.value);
+}
+
+enum RendererTheme {
+  def('default'),
+  dark('dark'),
+  light('light');
+
+  final String value;
+  const RendererTheme(this.value);
+}

apps/lib/features/ui_schema/domain/models/ui_schema/nodes.dart

@@ -0,0 +1,595 @@
+part of '../ui_schema.dart';
+
+abstract class UiNode {
+  String get type;
+  String? get id;
+
+  factory UiNode.fromJson(Map<String, dynamic> json) {
+    final type = json['type'] as String? ?? '';
+    switch (type) {
+      case 'text':
+        return UiTextNode.fromJson(json);
+      case 'card':
+        return UiCardNode.fromJson(json);
+      case 'list':
+        return UiListNode.fromJson(json);
+      case 'table':
+        return UiTableNode.fromJson(json);
+      case 'kv':
+        return UiKvNode.fromJson(json);
+      case 'operation':
+        return UiOperationNode.fromJson(json);
+      case 'error':
+        return UiErrorNode.fromJson(json);
+      case 'container':
+        return UiContainerNode.fromJson(json);
+      default:
+        return UiTextNode(content: 'Unknown node type: $type');
+    }
+  }
+}
+
+class UiTextNode implements UiNode {
+  @override
+  final String? id;
+  @override
+  String get type => 'text';
+  final String content;
+  final TextFormat format;
+  final UiIcon? icon;
+  final List<UiAction>? actions;
+
+  const UiTextNode({
+    this.id,
+    required this.content,
+    this.format = TextFormat.plain,
+    this.icon,
+    this.actions,
+  });
+
+  factory UiTextNode.fromJson(Map<String, dynamic> json) {
+    return UiTextNode(
+      id: json['id'] as String?,
+      content: json['content'] as String? ?? '',
+      format: TextFormat.values.firstWhere(
+        (e) => e.value == json['format'],
+        orElse: () => TextFormat.plain,
+      ),
+      icon: json['icon'] != null
+          ? UiIcon.fromJson(json['icon'] as Map<String, dynamic>)
+          : null,
+      actions: (json['actions'] as List<dynamic>?)
+          ?.map((e) => UiAction.fromJson(e as Map<String, dynamic>))
+          .toList(),
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'id': id,
+      'type': type,
+      'content': content,
+      'format': format.value,
+      if (icon != null) 'icon': icon!.toJson(),
+      if (actions != null) 'actions': actions!.map((e) => e.toJson()).toList(),
+    };
+  }
+}
+
+class UiCardNode implements UiNode {
+  @override
+  final String? id;
+  @override
+  String get type => 'card';
+  final String? title;
+  final String? description;
+  final UiIcon? icon;
+  final UiStatus? status;
+  final String? timestamp;
+  final List<UiNode>? children;
+  final UiTextNode? footer;
+  final Map<String, dynamic>? extensions;
+  final List<UiAction>? actions;
+
+  const UiCardNode({
+    this.id,
+    this.title,
+    this.description,
+    this.icon,
+    this.status,
+    this.timestamp,
+    this.children,
+    this.footer,
+    this.extensions,
+    this.actions,
+  });
+
+  factory UiCardNode.fromJson(Map<String, dynamic> json) {
+    return UiCardNode(
+      id: json['id'] as String?,
+      title: json['title'] as String?,
+      description: json['description'] as String?,
+      icon: json['icon'] != null
+          ? UiIcon.fromJson(json['icon'] as Map<String, dynamic>)
+          : null,
+      status: json['status'] != null
+          ? UiStatus.values.firstWhere(
+              (e) => e.value == json['status'],
+              orElse: () => UiStatus.info,
+            )
+          : null,
+      timestamp: json['timestamp'] as String?,
+      children: (json['children'] as List<dynamic>?)
+          ?.map((e) => UiNode.fromJson(e as Map<String, dynamic>))
+          .toList(),
+      footer: json['footer'] != null
+          ? UiTextNode.fromJson(json['footer'] as Map<String, dynamic>)
+          : null,
+      extensions: json['extensions'] as Map<String, dynamic>?,
+      actions: (json['actions'] as List<dynamic>?)
+          ?.map((e) => UiAction.fromJson(e as Map<String, dynamic>))
+          .toList(),
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'id': id,
+      'type': type,
+      if (title != null) 'title': title,
+      if (description != null) 'description': description,
+      if (icon != null) 'icon': icon!.toJson(),
+      if (status != null) 'status': status!.value,
+      if (timestamp != null) 'timestamp': timestamp,
+      if (children != null)
+        'children': children!.map((e) => (e as dynamic).toJson()).toList(),
+      if (footer != null) 'footer': footer!.toJson(),
+      if (extensions != null) 'extensions': extensions,
+      if (actions != null) 'actions': actions!.map((e) => e.toJson()).toList(),
+    };
+  }
+}
+
+class UiListNode implements UiNode {
+  @override
+  final String? id;
+  @override
+  String get type => 'list';
+  final String? title;
+  final String? description;
+  final UiIcon? icon;
+  final UiStatus? status;
+  final List<ListItem> items;
+  final Pagination? pagination;
+  final String? emptyText;
+  final Map<String, dynamic>? extensions;
+  final List<UiAction>? actions;
+
+  const UiListNode({
+    this.id,
+    this.title,
+    this.description,
+    this.icon,
+    this.status,
+    required this.items,
+    this.pagination,
+    this.emptyText,
+    this.extensions,
+    this.actions,
+  });
+
+  factory UiListNode.fromJson(Map<String, dynamic> json) {
+    return UiListNode(
+      id: json['id'] as String?,
+      title: json['title'] as String?,
+      description: json['description'] as String?,
+      icon: json['icon'] != null
+          ? UiIcon.fromJson(json['icon'] as Map<String, dynamic>)
+          : null,
+      status: json['status'] != null
+          ? UiStatus.values.firstWhere(
+              (e) => e.value == json['status'],
+              orElse: () => UiStatus.info,
+            )
+          : null,
+      items:
+          (json['items'] as List<dynamic>?)
+              ?.map((e) => ListItem.fromJson(e as Map<String, dynamic>))
+              .toList() ??
+          [],
+      pagination: json['pagination'] != null
+          ? Pagination.fromJson(json['pagination'] as Map<String, dynamic>)
+          : null,
+      emptyText: json['emptyText'] as String?,
+      extensions: json['extensions'] as Map<String, dynamic>?,
+      actions: (json['actions'] as List<dynamic>?)
+          ?.map((e) => UiAction.fromJson(e as Map<String, dynamic>))
+          .toList(),
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'id': id,
+      'type': type,
+      if (title != null) 'title': title,
+      if (description != null) 'description': description,
+      if (icon != null) 'icon': icon!.toJson(),
+      if (status != null) 'status': status!.value,
+      'items': items.map((e) => e.toJson()).toList(),
+      if (pagination != null) 'pagination': pagination!.toJson(),
+      if (emptyText != null) 'emptyText': emptyText,
+      if (extensions != null) 'extensions': extensions,
+      if (actions != null) 'actions': actions!.map((e) => e.toJson()).toList(),
+    };
+  }
+}
+
+class UiTableNode implements UiNode {
+  @override
+  final String? id;
+  @override
+  String get type => 'table';
+  final String? title;
+  final String? description;
+  final UiIcon? icon;
+  final UiStatus? status;
+  final List<TableColumn> columns;
+  final List<TableRow> rows;
+  final Pagination? pagination;
+  final Map<String, dynamic>? extensions;
+  final List<UiAction>? actions;
+
+  const UiTableNode({
+    this.id,
+    this.title,
+    this.description,
+    this.icon,
+    this.status,
+    required this.columns,
+    required this.rows,
+    this.pagination,
+    this.extensions,
+    this.actions,
+  });
+
+  factory UiTableNode.fromJson(Map<String, dynamic> json) {
+    return UiTableNode(
+      id: json['id'] as String?,
+      title: json['title'] as String?,
+      description: json['description'] as String?,
+      icon: json['icon'] != null
+          ? UiIcon.fromJson(json['icon'] as Map<String, dynamic>)
+          : null,
+      status: json['status'] != null
+          ? UiStatus.values.firstWhere(
+              (e) => e.value == json['status'],
+              orElse: () => UiStatus.info,
+            )
+          : null,
+      columns:
+          (json['columns'] as List<dynamic>?)
+              ?.map((e) => TableColumn.fromJson(e as Map<String, dynamic>))
+              .toList() ??
+          [],
+      rows:
+          (json['rows'] as List<dynamic>?)
+              ?.map((e) => TableRow.fromJson(e as Map<String, dynamic>))
+              .toList() ??
+          [],
+      pagination: json['pagination'] != null
+          ? Pagination.fromJson(json['pagination'] as Map<String, dynamic>)
+          : null,
+      extensions: json['extensions'] as Map<String, dynamic>?,
+      actions: (json['actions'] as List<dynamic>?)
+          ?.map((e) => UiAction.fromJson(e as Map<String, dynamic>))
+          .toList(),
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'id': id,
+      'type': type,
+      if (title != null) 'title': title,
+      if (description != null) 'description': description,
+      if (icon != null) 'icon': icon!.toJson(),
+      if (status != null) 'status': status!.value,
+      'columns': columns.map((e) => e.toJson()).toList(),
+      'rows': rows.map((e) => e.toJson()).toList(),
+      if (pagination != null) 'pagination': pagination!.toJson(),
+      if (extensions != null) 'extensions': extensions,
+      if (actions != null) 'actions': actions!.map((e) => e.toJson()).toList(),
+    };
+  }
+}
+
+class UiKvNode implements UiNode {
+  @override
+  final String? id;
+  @override
+  String get type => 'kv';
+  final String? title;
+  final String? description;
+  final UiIcon? icon;
+  final UiStatus? status;
+  final List<KeyValuePair> pairs;
+  final KvLayout layout;
+  final Map<String, dynamic>? extensions;
+  final List<UiAction>? actions;
+
+  const UiKvNode({
+    this.id,
+    this.title,
+    this.description,
+    this.icon,
+    this.status,
+    required this.pairs,
+    this.layout = KvLayout.vertical,
+    this.extensions,
+    this.actions,
+  });
+
+  factory UiKvNode.fromJson(Map<String, dynamic> json) {
+    return UiKvNode(
+      id: json['id'] as String?,
+      title: json['title'] as String?,
+      description: json['description'] as String?,
+      icon: json['icon'] != null
+          ? UiIcon.fromJson(json['icon'] as Map<String, dynamic>)
+          : null,
+      status: json['status'] != null
+          ? UiStatus.values.firstWhere(
+              (e) => e.value == json['status'],
+              orElse: () => UiStatus.info,
+            )
+          : null,
+      pairs:
+          (json['pairs'] as List<dynamic>?)
+              ?.map((e) => KeyValuePair.fromJson(e as Map<String, dynamic>))
+              .toList() ??
+          [],
+      layout: KvLayout.values.firstWhere(
+        (e) => e.value == json['layout'],
+        orElse: () => KvLayout.vertical,
+      ),
+      extensions: json['extensions'] as Map<String, dynamic>?,
+      actions: (json['actions'] as List<dynamic>?)
+          ?.map((e) => UiAction.fromJson(e as Map<String, dynamic>))
+          .toList(),
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'id': id,
+      'type': type,
+      if (title != null) 'title': title,
+      if (description != null) 'description': description,
+      if (icon != null) 'icon': icon!.toJson(),
+      if (status != null) 'status': status!.value,
+      'pairs': pairs.map((e) => e.toJson()).toList(),
+      'layout': layout.value,
+      if (extensions != null) 'extensions': extensions,
+      if (actions != null) 'actions': actions!.map((e) => e.toJson()).toList(),
+    };
+  }
+}
+
+class UiOperationNode implements UiNode {
+  @override
+  final String? id;
+  @override
+  String get type => 'operation';
+  final String? title;
+  final String? description;
+  final UiIcon? icon;
+  final UiStatus? status;
+  final OperationType operation;
+  final OperationResult result;
+  final String? message;
+  final int? affectedCount;
+  final UiNode? details;
+  final UiAction? rollback;
+  final Map<String, dynamic>? extensions;
+  final List<UiAction>? actions;
+
+  const UiOperationNode({
+    this.id,
+    this.title,
+    this.description,
+    this.icon,
+    this.status,
+    required this.operation,
+    required this.result,
+    this.message,
+    this.affectedCount,
+    this.details,
+    this.rollback,
+    this.extensions,
+    this.actions,
+  });
+
+  factory UiOperationNode.fromJson(Map<String, dynamic> json) {
+    return UiOperationNode(
+      id: json['id'] as String?,
+      title: json['title'] as String?,
+      description: json['description'] as String?,
+      icon: json['icon'] != null
+          ? UiIcon.fromJson(json['icon'] as Map<String, dynamic>)
+          : null,
+      status: json['status'] != null
+          ? UiStatus.values.firstWhere(
+              (e) => e.value == json['status'],
+              orElse: () => UiStatus.info,
+            )
+          : null,
+      operation: OperationType.values.firstWhere(
+        (e) => e.value == json['operation'],
+        orElse: () => OperationType.execute,
+      ),
+      result: OperationResult.values.firstWhere(
+        (e) => e.value == json['result'],
+        orElse: () => OperationResult.failure,
+      ),
+      message: json['message'] as String?,
+      affectedCount: json['affectedCount'] as int?,
+      details: json['details'] != null
+          ? UiNode.fromJson(json['details'] as Map<String, dynamic>)
+          : null,
+      rollback: json['rollback'] != null
+          ? UiAction.fromJson(json['rollback'] as Map<String, dynamic>)
+          : null,
+      extensions: json['extensions'] as Map<String, dynamic>?,
+      actions: (json['actions'] as List<dynamic>?)
+          ?.map((e) => UiAction.fromJson(e as Map<String, dynamic>))
+          .toList(),
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'id': id,
+      'type': type,
+      if (title != null) 'title': title,
+      if (description != null) 'description': description,
+      if (icon != null) 'icon': icon!.toJson(),
+      if (status != null) 'status': status!.value,
+      'operation': operation.value,
+      'result': result.value,
+      if (message != null) 'message': message,
+      if (affectedCount != null) 'affectedCount': affectedCount,
+      if (details != null) 'details': (details as dynamic).toJson(),
+      if (rollback != null) 'rollback': rollback!.toJson(),
+      if (extensions != null) 'extensions': extensions,
+      if (actions != null) 'actions': actions!.map((e) => e.toJson()).toList(),
+    };
+  }
+}
+
+class UiErrorNode implements UiNode {
+  @override
+  final String? id;
+  @override
+  String get type => 'error';
+  final String? title;
+  final UiIcon? icon;
+  final String errorCode;
+  final String message;
+  final String? details;
+  final String? stack;
+  final bool retryable;
+  final List<String>? suggestions;
+  final UiAction? retry;
+  final UiAction? support;
+  final List<UiAction>? actions;
+
+  const UiErrorNode({
+    this.id,
+    this.title,
+    this.icon,
+    required this.errorCode,
+    required this.message,
+    this.details,
+    this.stack,
+    this.retryable = false,
+    this.suggestions,
+    this.retry,
+    this.support,
+    this.actions,
+  });
+
+  factory UiErrorNode.fromJson(Map<String, dynamic> json) {
+    return UiErrorNode(
+      id: json['id'] as String?,
+      title: json['title'] as String?,
+      icon: json['icon'] != null
+          ? UiIcon.fromJson(json['icon'] as Map<String, dynamic>)
+          : null,
+      errorCode: json['errorCode'] as String? ?? 'UNKNOWN',
+      message: json['message'] as String? ?? 'An error occurred',
+      details: json['details'] as String?,
+      stack: json['stack'] as String?,
+      retryable: json['retryable'] as bool? ?? false,
+      suggestions: (json['suggestions'] as List<dynamic>?)
+          ?.map((e) => e as String)
+          .toList(),
+      retry: json['retry'] != null
+          ? UiAction.fromJson(json['retry'] as Map<String, dynamic>)
+          : null,
+      support: json['support'] != null
+          ? UiAction.fromJson(json['support'] as Map<String, dynamic>)
+          : null,
+      actions: (json['actions'] as List<dynamic>?)
+          ?.map((e) => UiAction.fromJson(e as Map<String, dynamic>))
+          .toList(),
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'id': id,
+      'type': type,
+      if (title != null) 'title': title,
+      if (icon != null) 'icon': icon!.toJson(),
+      'errorCode': errorCode,
+      'message': message,
+      if (details != null) 'details': details,
+      if (stack != null) 'stack': stack,
+      'retryable': retryable,
+      if (suggestions != null) 'suggestions': suggestions,
+      if (retry != null) 'retry': retry!.toJson(),
+      if (support != null) 'support': support!.toJson(),
+      if (actions != null) 'actions': actions!.map((e) => e.toJson()).toList(),
+    };
+  }
+}
+
+class UiContainerNode implements UiNode {
+  @override
+  final String? id;
+  @override
+  String get type => 'container';
+  final ContainerDirection direction;
+  final int? gap;
+  final List<UiNode> children;
+  final List<UiAction>? actions;
+
+  const UiContainerNode({
+    this.id,
+    this.direction = ContainerDirection.vertical,
+    this.gap,
+    required this.children,
+    this.actions,
+  });
+
+  factory UiContainerNode.fromJson(Map<String, dynamic> json) {
+    return UiContainerNode(
+      id: json['id'] as String?,
+      direction: ContainerDirection.values.firstWhere(
+        (e) => e.value == json['direction'],
+        orElse: () => ContainerDirection.vertical,
+      ),
+      gap: json['gap'] as int?,
+      children:
+          (json['children'] as List<dynamic>?)
+              ?.map((e) => UiNode.fromJson(e as Map<String, dynamic>))
+              .toList() ??
+          [],
+      actions: (json['actions'] as List<dynamic>?)
+          ?.map((e) => UiAction.fromJson(e as Map<String, dynamic>))
+          .toList(),
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'id': id,
+      'type': type,
+      'direction': direction.value,
+      if (gap != null) 'gap': gap,
+      'children': children.map((e) => (e as dynamic).toJson()).toList(),
+      if (actions != null) 'actions': actions!.map((e) => e.toJson()).toList(),
+    };
+  }
+}

apps/lib/features/ui_schema/presentation/navigation/ui_schema_navigation.dart

@@ -0,0 +1,35 @@
+bool isValidInternalNavigationPath(String path) {
+  if (path.isEmpty || !path.startsWith('/')) {
+    return false;
+  }
+  return !path.startsWith('//') &&
+      !path.contains('://') &&
+      !path.contains('?') &&
+      !path.contains('#') &&
+      !path.contains(':');
+}
+
+String buildUiSchemaNavigationTarget({
+  required String path,
+  Map<String, dynamic>? params,
+}) {
+  final baseUri = Uri.parse(path);
+  final queryParams = <String, String>{};
+
+  if (params != null) {
+    for (final entry in params.entries) {
+      final value = entry.value;
+      if (value is String && value.isNotEmpty) {
+        queryParams[entry.key] = value;
+      } else if (value is num || value is bool) {
+        queryParams[entry.key] = value.toString();
+      }
+    }
+  }
+
+  final mergedQueryParams = {...baseUri.queryParameters, ...queryParams};
+  final targetUri = baseUri.replace(
+    queryParameters: mergedQueryParams.isEmpty ? null : mergedQueryParams,
+  );
+  return targetUri.toString();
+}

apps/lib/features/ui_schema/presentation/widgets/ui_schema_renderer.dart

@@ -0,0 +1,486 @@
+import 'package:flutter/material.dart';
+import 'package:go_router/go_router.dart';
+
+import 'package:social_app/core/l10n/l10n.dart';
+import 'package:social_app/core/theme/design_tokens.dart';
+import 'package:social_app/shared/widgets/toast/toast.dart';
+import 'package:social_app/shared/widgets/toast/toast_type.dart';
+import '../navigation/ui_schema_navigation.dart';
+
+class UiSchemaRenderer {
+  static Widget renderSchema(Map<String, dynamic>? schema) {
+    if (schema == null || schema.isEmpty) {
+      return const SizedBox.shrink();
+    }
+    final root = _asMap(schema['root']);
+    if (root == null) {
+      return _fallback(L10n.current.uiSchemaInvalid);
+    }
+    return _renderLayoutNode(root);
+  }
+
+  static Widget _renderLayoutNode(Map<String, dynamic> node) {
+    final type = _asString(node['type']);
+    return switch (type) {
+      'stack' => _renderStack(node),
+      'grid' => _renderGrid(node),
+      _ => _fallback(L10n.current.uiSchemaUnsupportedLayout(type)),
+    };
+  }
+
+  static Widget _renderNode(Map<String, dynamic> node) {
+    final type = _asString(node['type']);
+    if (node['visible'] == false) {
+      return const SizedBox.shrink();
+    }
+    return switch (type) {
+      'text' => _renderText(node),
+      'icon' => _renderIcon(node),
+      'badge' => _renderBadge(node),
+      'button' => _renderButton(node),
+      'kv' => _renderKv(node),
+      'divider' => _renderDivider(node),
+      'stack' => _renderStack(node),
+      'grid' => _renderGrid(node),
+      _ => _fallback(L10n.current.uiSchemaUnknownNode(type)),
+    };
+  }
+
+  static Widget _renderStack(Map<String, dynamic> node) {
+    final children = _asList(
+      node['children'],
+    ).whereType<Map<String, dynamic>>().map(_renderNode).toList();
+    final gap = _asDouble(node['gap'], fallback: AppSpacing.sm);
+    final direction = _asString(node['direction'], fallback: 'vertical');
+
+    Widget content;
+    if (direction == 'horizontal') {
+      content = Wrap(
+        direction: Axis.horizontal,
+        spacing: gap,
+        runSpacing: gap,
+        crossAxisAlignment: WrapCrossAlignment.center,
+        children: children,
+      );
+    } else {
+      content = Column(
+        crossAxisAlignment: CrossAxisAlignment.start,
+        children: _withGap(children, gap),
+      );
+    }
+    return _wrapSurface(node, content);
+  }
+
+  static Widget _renderGrid(Map<String, dynamic> node) {
+    final children = _asList(
+      node['children'],
+    ).whereType<Map<String, dynamic>>().map(_renderNode).toList();
+    final columns = _asInt(node['columns'], fallback: 2).clamp(1, 3);
+    final gap = _asDouble(node['gap'], fallback: AppSpacing.sm);
+    return _wrapSurface(
+      node,
+      GridView.count(
+        crossAxisCount: columns,
+        crossAxisSpacing: gap,
+        mainAxisSpacing: gap,
+        childAspectRatio: 1.6,
+        physics: const NeverScrollableScrollPhysics(),
+        shrinkWrap: true,
+        children: children,
+      ),
+    );
+  }
+
+  static Widget _renderText(Map<String, dynamic> node) {
+    final role = _asString(node['role'], fallback: 'body');
+    final status = _asString(node['status']);
+    final style = switch (role) {
+      'title' => const TextStyle(
+        fontSize: 18,
+        fontWeight: FontWeight.w700,
+        color: AppColors.slate900,
+        height: 1.2,
+      ),
+      'subtitle' => const TextStyle(
+        fontSize: 14,
+        fontWeight: FontWeight.w600,
+        color: AppColors.slate800,
+      ),
+      'caption' => const TextStyle(
+        fontSize: 11,
+        color: AppColors.slate500,
+        height: 1.4,
+      ),
+      'code' => const TextStyle(
+        fontSize: 12,
+        color: AppColors.slate700,
+        fontFamily: 'monospace',
+      ),
+      _ => const TextStyle(
+        fontSize: 13,
+        color: AppColors.slate700,
+        height: 1.35,
+      ),
+    };
+    return Text(
+      _asString(node['content']),
+      maxLines: _asIntOrNull(node['maxLines']),
+      overflow: TextOverflow.ellipsis,
+      style: style.copyWith(color: _statusTextColor(status, style.color)),
+    );
+  }
+
+  static Widget _renderIcon(Map<String, dynamic> node) {
+    final value = _asString(node['value']);
+    if (_asString(node['source']) == 'emoji' && value.isNotEmpty) {
+      return Text(value, style: const TextStyle(fontSize: 18));
+    }
+    return Icon(Icons.bubble_chart_rounded, color: _statusTextColor('', null));
+  }
+
+  static Widget _renderBadge(Map<String, dynamic> node) {
+    final status = _asString(node['status']);
+    final fg =
+        _statusTextColor(status, AppColors.slate700) ?? AppColors.slate700;
+    final bg = _statusBackground(status);
+    return Container(
+      padding: const EdgeInsets.symmetric(
+        horizontal: AppSpacing.md,
+        vertical: AppSpacing.xs,
+      ),
+      decoration: BoxDecoration(
+        color: bg,
+        borderRadius: BorderRadius.circular(AppRadius.full),
+        border: Border.all(color: _statusBorder(status)),
+      ),
+      child: Text(
+        _asString(node['label']),
+        style: TextStyle(fontSize: 12, fontWeight: FontWeight.w700, color: fg),
+      ),
+    );
+  }
+
+  static Widget _renderButton(Map<String, dynamic> node) {
+    final style = _asString(node['style'], fallback: 'secondary');
+    final action = _asMap(node['action']);
+    final disabled = node['disabled'] == true;
+    return Builder(
+      builder: (context) {
+        return ElevatedButton(
+          onPressed: disabled
+              ? null
+              : () {
+                  _handleAction(context, action);
+                },
+          style: ElevatedButton.styleFrom(
+            elevation: 0,
+            padding: const EdgeInsets.symmetric(
+              horizontal: AppSpacing.lg,
+              vertical: AppSpacing.sm,
+            ),
+            backgroundColor: style == 'primary'
+                ? AppColors.authPrimaryButton
+                : AppColors.surfaceInfoLight,
+            foregroundColor: style == 'primary'
+                ? AppColors.white
+                : AppColors.slate700,
+            shape: RoundedRectangleBorder(
+              borderRadius: BorderRadius.circular(AppRadius.full),
+              side: style == 'primary'
+                  ? BorderSide.none
+                  : const BorderSide(color: AppColors.borderTertiary),
+            ),
+          ),
+          child: Text(
+            _asString(
+              node['label'],
+              fallback: L10n.current.uiSchemaActionFallback,
+            ),
+            style: const TextStyle(fontSize: 12, fontWeight: FontWeight.w600),
+          ),
+        );
+      },
+    );
+  }
+
+  static void _handleAction(
+    BuildContext context,
+    Map<String, dynamic>? action,
+  ) {
+    final actionType = _asString(action?['type']);
+    switch (actionType) {
+      case 'copy':
+        Toast.show(
+          context,
+          L10n.current.commonCopySuccess,
+          type: ToastType.success,
+        );
+        return;
+      case 'navigation':
+        _handleNavigationAction(context, action);
+        return;
+      default:
+        Toast.show(
+          context,
+          L10n.current.uiSchemaActionNotImplemented,
+          type: ToastType.info,
+        );
+        return;
+    }
+  }
+
+  static void _handleNavigationAction(
+    BuildContext context,
+    Map<String, dynamic>? action,
+  ) {
+    if (action == null) {
+      Toast.show(
+        context,
+        L10n.current.uiSchemaNavigationInvalidParams,
+        type: ToastType.warning,
+      );
+      return;
+    }
+
+    final path = _asString(action['path']).trim();
+    if (!isValidInternalNavigationPath(path)) {
+      Toast.show(
+        context,
+        L10n.current.uiSchemaNavigationInvalidPath,
+        type: ToastType.warning,
+      );
+      return;
+    }
+
+    final params = _asMap(action['params']);
+    final shouldReplace = action['replace'] == true;
+    try {
+      final target = buildUiSchemaNavigationTarget(path: path, params: params);
+      if (shouldReplace) {
+        context.replace(target);
+        return;
+      }
+      context.push(target);
+    } on FormatException {
+      Toast.show(
+        context,
+        L10n.current.uiSchemaNavigationInvalidPath,
+        type: ToastType.warning,
+      );
+    }
+  }
+
+  static Widget _renderKv(Map<String, dynamic> node) {
+    final items = _asList(
+      node['items'],
+    ).whereType<Map<String, dynamic>>().toList();
+    if (items.isEmpty) {
+      return const SizedBox.shrink();
+    }
+    return Column(
+      crossAxisAlignment: CrossAxisAlignment.start,
+      children: _withGap(
+        items.map((item) {
+          final label = _asString(
+            item['label'],
+            fallback: _asString(item['key']),
+          );
+          final value = item['value']?.toString() ?? '-';
+          return Container(
+            width: double.infinity,
+            padding: const EdgeInsets.symmetric(
+              horizontal: AppSpacing.md,
+              vertical: AppSpacing.xs,
+            ),
+            decoration: BoxDecoration(
+              color: AppColors.surfaceSecondary,
+              borderRadius: BorderRadius.circular(AppRadius.md),
+            ),
+            child: Row(
+              crossAxisAlignment: CrossAxisAlignment.start,
+              children: [
+                Expanded(
+                  flex: 3,
+                  child: Text(
+                    label,
+                    style: const TextStyle(
+                      fontSize: 11,
+                      color: AppColors.slate500,
+                    ),
+                  ),
+                ),
+                const SizedBox(width: AppSpacing.sm),
+                Expanded(
+                  flex: 5,
+                  child: Text(
+                    value,
+                    style: const TextStyle(
+                      fontSize: 12,
+                      color: AppColors.slate800,
+                      fontWeight: FontWeight.w600,
+                    ),
+                  ),
+                ),
+              ],
+            ),
+          );
+        }).toList(),
+        AppSpacing.xs,
+      ),
+    );
+  }
+
+  static Widget _renderDivider(Map<String, dynamic> node) {
+    final inset = _asDouble(node['inset'], fallback: 0);
+    return Padding(
+      padding: EdgeInsets.symmetric(horizontal: inset),
+      child: const Divider(height: 1, color: AppColors.slate200),
+    );
+  }
+
+  static Widget _wrapSurface(Map<String, dynamic> node, Widget child) {
+    final appearance = _asString(node['appearance'], fallback: 'plain');
+    final status = _asString(node['status']);
+    if (appearance == 'plain') {
+      return child;
+    }
+    final bg = switch (appearance) {
+      'section' => AppColors.surfaceSecondary,
+      'card' => AppColors.white,
+      _ => _statusBackground(status),
+    };
+    final borderColor = switch (status) {
+      'success' => AppColors.feedbackSuccessBorder,
+      'warning' => AppColors.feedbackWarningBorder,
+      'error' => AppColors.feedbackErrorBorder,
+      _ => AppColors.homeConversationBorder,
+    };
+    return Container(
+      width: double.infinity,
+      padding: const EdgeInsets.all(AppSpacing.md),
+      decoration: BoxDecoration(
+        color: bg,
+        borderRadius: BorderRadius.circular(AppRadius.lg),
+        border: Border.all(color: borderColor),
+        boxShadow: [
+          BoxShadow(
+            color: AppColors.slate200.withValues(alpha: 0.35),
+            blurRadius: 12,
+            offset: const Offset(0, 6),
+          ),
+        ],
+      ),
+      child: child,
+    );
+  }
+
+  static Widget _fallback(String text) {
+    return Container(
+      padding: const EdgeInsets.all(AppSpacing.md),
+      decoration: BoxDecoration(
+        color: AppColors.feedbackWarningSurface,
+        border: Border.all(color: AppColors.feedbackWarningBorder),
+        borderRadius: BorderRadius.circular(AppRadius.md),
+      ),
+      child: Text(
+        text,
+        style: const TextStyle(
+          fontSize: 12,
+          color: AppColors.feedbackWarningText,
+        ),
+      ),
+    );
+  }
+
+  static List<Widget> _withGap(List<Widget> widgets, double gap) {
+    if (widgets.isEmpty) return const [];
+    return [
+      widgets.first,
+      for (int i = 1; i < widgets.length; i++) ...[
+        SizedBox(height: gap),
+        widgets[i],
+      ],
+    ];
+  }
+
+  static Color _statusBackground(String status) {
+    return switch (status) {
+      'success' => AppColors.feedbackSuccessSurface,
+      'warning' => AppColors.feedbackWarningSurface,
+      'error' => AppColors.feedbackErrorSurface,
+      'pending' => AppColors.feedbackInfoSurface,
+      _ => AppColors.surfaceSecondary,
+    };
+  }
+
+  static Color _statusBorder(String status) {
+    return switch (status) {
+      'success' => AppColors.feedbackSuccessBorder,
+      'warning' => AppColors.feedbackWarningBorder,
+      'error' => AppColors.feedbackErrorBorder,
+      'pending' => AppColors.feedbackInfoBorder,
+      _ => AppColors.borderTertiary,
+    };
+  }
+
+  static Color? _statusTextColor(String status, Color? fallback) {
+    return switch (status) {
+      'success' => AppColors.feedbackSuccessText,
+      'warning' => AppColors.feedbackWarningText,
+      'error' => AppColors.feedbackErrorText,
+      'pending' => AppColors.feedbackInfoText,
+      _ => fallback,
+    };
+  }
+
+  static Map<String, dynamic>? _asMap(Object? value) {
+    if (value is Map<String, dynamic>) {
+      return value;
+    }
+    if (value is Map) {
+      return Map<String, dynamic>.from(value);
+    }
+    return null;
+  }
+
+  static List<dynamic> _asList(Object? value) {
+    return value is List ? value : const [];
+  }
+
+  static String _asString(Object? value, {String fallback = ''}) {
+    return value is String ? value : fallback;
+  }
+
+  static int _asInt(Object? value, {int fallback = 0}) {
+    if (value is int) {
+      return value;
+    }
+    if (value is double) {
+      return value.toInt();
+    }
+    if (value is String) {
+      return int.tryParse(value) ?? fallback;
+    }
+    return fallback;
+  }
+
+  static int? _asIntOrNull(Object? value) {
+    if (value == null) {
+      return null;
+    }
+    return _asInt(value);
+  }
+
+  static double _asDouble(Object? value, {double fallback = 0}) {
+    if (value is double) {
+      return value;
+    }
+    if (value is int) {
+      return value.toDouble();
+    }
+    if (value is String) {
+      return double.tryParse(value) ?? fallback;
+    }
+    return fallback;
+  }
+}