@fses/workbench-app 0.2.0 → 0.2.2

package/node_modules/@fses/workbench-card/src/renderers/nested/nestedBlockBindings.ts

@@ -0,0 +1,1349 @@
+/**
+ * @fileoverview 嵌套卡片预览绑定 - 提供 customCanvas 子卡片的数据归一化、语义分类和样式 helper。
+ * @author seadon
+ * @created 2026-05-20
+ */
+import type { CSSProperties } from 'vue';
+import type { CustomCanvasData, CustomCanvasNestedBlock, BlockVisualOptions, WorkbenchBlock } from '../../types';
+import {
+  imageTableColumnVisible,
+  structuredTableCellText,
+  visibleImageTableColumns,
+} from '../tableDisplay';
+
+type TextValueHelper = (value: unknown, fallback?: string) => string;
+type NumberValueHelper = (value: unknown, fallback?: number) => number;
+type NestedBlockContext = {
+  textValue: TextValueHelper;
+  numberValue: NumberValueHelper;
+  isRecord: (value: unknown) => value is Record<string, unknown>;
+  formatMetricValue: (value: number, format?: string) => string;
+  businessGapDiagnosticSummary: (input: { message?: unknown; fallback?: string; diagnostics?: unknown }) => string;
+  dataBindingHumanInterventionFromRecord: (value: unknown) => Record<string, unknown> | undefined;
+  recordHasImageComposeSource: (value: unknown) => boolean;
+  customCanvasGeneratedElement: (element: unknown) => boolean;
+  nestedBlockRendererKey: (block: CustomCanvasNestedBlock) => string;
+  nestedBlockComposeSource: (block: CustomCanvasNestedBlock) => string;
+  nestedBlockSummaryEntry: (key: string, value: unknown) => string;
+  visualForScene: (block: WorkbenchBlock, data?: CustomCanvasData) => BlockVisualOptions;
+  referenceCompositeLooksLikeChairmanRiskDirectContext: () => (block: WorkbenchBlock, data: CustomCanvasData) => boolean;
+  referenceCompositeLooksLikeChairmanRiskContext: () => (block: WorkbenchBlock, data: CustomCanvasData) => boolean;
+  referenceOpsTrendItems: () => (data: CustomCanvasData) => Array<Record<string, unknown>>;
+};
+
+const NESTED_BLOCK_INTERNAL_SUMMARY_KEYS = new Set([
+  'shape',
+  'dataShape',
+  'chartType',
+  'rendererKey',
+  'primaryLabel',
+  'primaryFormat',
+  'metricFormat',
+  'valueFormat',
+  'dimensionLabel',
+  'source',
+  'rawValue',
+  'payload',
+  'sourceLabel',
+  'composeSource',
+  'snapshotSource',
+  'dataBinding',
+  'dataBindingId',
+  'dataBindingStatus',
+  'dataBindingError',
+  'dataBindingHumanIntervention',
+  'humanIntervention',
+  'queryIntent',
+  'refreshApi',
+  'items',
+  'rows',
+  'metrics',
+  'secondary',
+  'links',
+  'alerts',
+  'series',
+  'categories',
+  'columns',
+  'elements',
+]);
+
+/**
+ * Creates helpers for nested customCanvas card previews.
+ * @param context - Shared renderer helpers from the main workbench block binding.
+ * @returns Nested card helper functions consumed by the block renderer template.
+ */
+export function createNestedBlockBindings(context: NestedBlockContext) {
+  const {
+    textValue,
+    numberValue,
+    isRecord,
+    formatMetricValue,
+    businessGapDiagnosticSummary,
+    dataBindingHumanInterventionFromRecord,
+    recordHasImageComposeSource,
+    customCanvasGeneratedElement,
+    nestedBlockRendererKey,
+    nestedBlockComposeSource,
+    nestedBlockSummaryEntry,
+    visualForScene,
+    referenceCompositeLooksLikeChairmanRiskDirectContext,
+    referenceCompositeLooksLikeChairmanRiskContext,
+    referenceOpsTrendItems,
+  } = context;
+
+  /**
+   * Checks whether a renderer value is an internal image-compose sentinel rather than user-facing data.
+   * @param value - Candidate display value.
+   * @returns True when the value should be hidden from card previews.
+   */
+  function nestedBlockInternalSentinelValue(value: string): boolean {
+    return /^KNOWN_IMAGE_/i.test(value) || /^structured_(?:timeout|fallback)$/i.test(value);
+  }
+
+  function nestedBlockMetricValue(block: CustomCanvasNestedBlock) {
+    const data = isRecord(block.data) ? block.data : {};
+    const displayValue = textValue(data.displayValue);
+    if (displayValue && !nestedBlockInternalSentinelValue(displayValue)) return displayValue;
+    if (typeof data.value === 'number') return String(data.value);
+    if (typeof data.value === 'string' && !nestedBlockInternalSentinelValue(data.value.trim())) return data.value;
+    if (typeof data.primaryValue === 'number' || typeof data.primaryValue === 'string') {
+      return typeof data.primaryValue === 'number'
+        ? formatMetricValue(data.primaryValue, typeof data.primaryFormat === 'string' ? data.primaryFormat : undefined)
+        : nestedBlockInternalSentinelValue(data.primaryValue.trim()) ? '--' : data.primaryValue;
+    }
+    const numericEntry = Object.entries(data).find(([key, value]) => {
+      if (NESTED_BLOCK_INTERNAL_SUMMARY_KEYS.has(key) || !imageTableColumnVisible(key)) return false;
+      return (typeof value === 'number' || typeof value === 'string') && String(value).trim();
+    });
+    const candidate = numericEntry ? String(numericEntry[1]).trim() : '';
+    return candidate && !nestedBlockInternalSentinelValue(candidate) ? candidate : '--';
+  }
+  
+  type NestedBlockVisualKind =
+    | 'metric'
+    | 'table'
+    | 'list'
+    | 'chart'
+    | 'statusList'
+    | 'incidentList'
+    | 'resourceBars'
+    | 'securityScore'
+    | 'simpleList'
+    | 'progressList'
+    | 'todoGrid'
+    | 'quickLinks'
+    | 'donut'
+    | 'summary';
+  
+  type NestedBlockTone = 'healthy' | 'warning' | 'critical' | 'info' | 'violet' | 'neutral';
+  
+  /**
+   * Returns a compact searchable string for choosing a screenshot-like child-card template.
+   * @param block - Nested child card preview.
+   * @returns Title, kind, capability, and renderer metadata joined for visual classification.
+   */
+  function nestedBlockClassifierText(block: CustomCanvasNestedBlock): string {
+    const data = isRecord(block.data) ? block.data : {};
+    const meta = isRecord(block.meta) ? block.meta : {};
+    return [
+      block.title,
+      block.kind,
+      block.visualKind,
+      block.capabilityId,
+      block.dataShape,
+      nestedBlockRendererKey(block),
+      textValue(meta.visualKind),
+      textValue(data.visualKind),
+      textValue(data.variant),
+      textValue(data.kind),
+    ].filter(Boolean).join(' ');
+  }
+  
+  /**
+   * Reads a declared visual kind from model or registry data when one is available.
+   * @param block - Nested child card preview.
+   * @returns Specialized visual kind, or an empty string when no supported kind was declared.
+   */
+  function nestedBlockDeclaredVisualKind(block: CustomCanvasNestedBlock): NestedBlockVisualKind | '' {
+    const data = isRecord(block.data) ? block.data : {};
+    const meta = isRecord(block.meta) ? block.meta : {};
+    const declaredCandidates = [
+      block.visualKind,
+      meta.visualKind,
+      data.visualKind,
+      data.variant,
+      data.kind,
+    ];
+    for (const candidate of declaredCandidates) {
+      const declared = textValue(candidate);
+      if (declared === 'statusList') return 'statusList';
+      if (declared === 'incidentList') return 'incidentList';
+      if (declared === 'resourceBars') return 'resourceBars';
+      if (declared === 'securityScore') return 'securityScore';
+      if (declared === 'simpleList' || declared === 'noticeList') return 'simpleList';
+      if (declared === 'progressList') return 'progressList';
+      if (declared === 'todoGrid' || declared === 'metricTiles') return 'todoGrid';
+      if (declared === 'quickLinks') return 'quickLinks';
+      if (declared === 'donut') return 'donut';
+      if (declared === 'barChart' || declared === 'areaTrend' || declared === 'comboChart') return 'chart';
+    }
+    return '';
+  }
+  
+  /**
+   * Chooses the closest reference-style nested card renderer for image-composed child cards.
+   * @param block - Nested child card preview.
+   * @returns Specialized CIO-like visual kind or the generic preview kind.
+   */
+  function nestedBlockVisualKind(block: CustomCanvasNestedBlock): NestedBlockVisualKind {
+    const declared = nestedBlockDeclaredVisualKind(block);
+    if (declared) return declared;
+    const text = nestedBlockClassifierText(block);
+    if (block.kind === 'metric' && !declared && !/个人待办|快捷区|metricTiles|todoGrid/i.test(text)) return 'metric';
+    if (/安全风险|安全健康|security/i.test(text)) return 'securityScore';
+    if (/成本分析|费用分析|预算分析|donut/i.test(text)) return 'donut';
+    if (/资源负载|负载监控|CPU|内存|存储|带宽|resource/i.test(text)) return 'resourceBars';
+    if (/服务监控|系统监控|系统在线|service/i.test(text)) return 'statusList';
+    if (/项目看板|项目进度|重点\s*IT\s*项目|project/i.test(text)) return 'progressList';
+    if (/待办|审批|todo/i.test(text)) return 'todoGrid';
+    if (/快捷|入口|平台|工单|堡垒|quick/i.test(text)) return 'quickLinks';
+    if (/趋势|走势|近七日|七日|trend/i.test(text)) return 'chart';
+    if (/故障|告警|红警|事件|incident|alarm/i.test(text)) return 'incidentList';
+    if (/合规|审计|敏感|账号|权限|资产运营|成本优化|效能|notice|audit/i.test(text)) return 'simpleList';
+    return nestedBlockPreviewKind(block) as NestedBlockVisualKind;
+  }
+  
+  /**
+   * Converts primitive array entries into item records for template rendering.
+   * @param value - Candidate array from nested render data.
+   * @returns Record items with strings represented as labels.
+   */
+  function nestedBlockItemRecords(value: unknown): Array<Record<string, unknown>> {
+    if (!Array.isArray(value)) return [];
+    return value
+      .map((item) => {
+        if (isRecord(item)) return item;
+        if (typeof item === 'string' || typeof item === 'number') return { label: String(item) };
+        return undefined;
+      })
+      .filter((item): item is Record<string, unknown> => Boolean(item));
+  }
+  
+  /**
+   * Checks whether a model item carries only placeholder dashes or empty text.
+   * @param item - Candidate item record.
+   * @returns True when the item should be replaced by a visual fallback.
+   */
+  function nestedBlockItemEmpty(item: Record<string, unknown>): boolean {
+    const cells = Array.isArray(item.cells) ? item.cells : [];
+    const values = [
+      item.label,
+      item.name,
+      item.title,
+      item.status,
+      item.value,
+      item.amount,
+      item.detail,
+      ...cells,
+    ].map((value) => (value === null || value === undefined ? '' : String(value).trim()));
+    return values.length === 0 || values.every((value) => value === '' || value === '--' || value === '-');
+  }
+  
+  /**
+   * Detects weak model/OCR list items that are less useful than reference-style visual fallbacks.
+   * @param item - Candidate item record.
+   * @returns True when the item looks like an index-only placeholder.
+   */
+  function nestedBlockItemLooksWeak(item: Record<string, unknown>): boolean {
+    const label = textValue(item.label, textValue(item.name, textValue(item.title)));
+    const value = nestedBlockDisplayValue(item.value ?? item.amount ?? item.status, '');
+    const detail = nestedBlockDisplayValue(item.detail ?? item.description, '');
+    const cells = Array.isArray(item.cells) ? item.cells.map((cell) => String(cell ?? '').trim()).filter(Boolean) : [];
+    const usefulText = [label, value, detail, ...cells].filter(Boolean);
+    if (usefulText.length === 0) return true;
+    if (usefulText.every((text) => /^(\d+|项目\s*\d+|--|-)$/.test(text))) return true;
+    if (/^项目\s*\d+$/.test(label) && (!value || /^\d+$/.test(value)) && !detail) return true;
+    if (cells.length > 0 && cells.every((text) => /^(\d+|--|-)$/.test(text))) return true;
+    return false;
+  }
+  
+  /**
+   * Checks whether a group of model rows is mostly index placeholders.
+   * @param items - Candidate item records.
+   * @returns True when the row group should use a visual fallback instead.
+   */
+  function nestedBlockItemsLookTooWeak(items: Array<Record<string, unknown>>): boolean {
+    if (items.length === 0) return true;
+    const weakCount = items.filter((item) => {
+      const label = nestedBlockItemLabel(item, 0);
+      return nestedBlockItemLooksWeak(item) || /^(\d+|项目\s*\d+|--|-)$/.test(label);
+    }).length;
+    return weakCount / items.length >= 0.5;
+  }
+  
+  /**
+   * Checks weak OCR rows with visual-template-specific expectations.
+   * @param items - Candidate item records.
+   * @param visualKind - Reference visual template that will render the rows.
+   * @returns True when the template should use reference fallback rows.
+   */
+  function nestedBlockItemsLookTooWeakForVisualKind(items: Array<Record<string, unknown>>, visualKind: NestedBlockVisualKind): boolean {
+    if (nestedBlockItemsLookTooWeak(items)) return true;
+    if (visualKind === 'progressList') {
+      const weakProgressRows = items.filter((item) => {
+        const value = nestedBlockItemValue(item);
+        return !/%|延期|卡点|完成|达标|延迟|风险|通过|[1-9]\d\s*%/.test(value);
+      }).length;
+      return weakProgressRows / items.length >= 0.5;
+    }
+    if (visualKind === 'simpleList') {
+      const valueLessRows = items.filter((item) => !nestedBlockItemValue(item)).length;
+      return valueLessRows / items.length >= 0.5;
+    }
+    return false;
+  }
+  
+  /**
+   * Reads model-provided list-like data from a nested child card.
+   * @param block - Nested child card preview.
+   * @returns Non-empty item records from items, rows, metrics, links, or alerts.
+   */
+  function nestedBlockRawItems(block: CustomCanvasNestedBlock): Array<Record<string, unknown>> {
+    const data = isRecord(block.data) ? block.data : {};
+    return [
+      ...nestedBlockItemRecords(data.items),
+      ...nestedBlockItemRecords(data.rows),
+      ...nestedBlockItemRecords(data.metrics),
+      ...nestedBlockItemRecords(data.secondary),
+      ...nestedBlockItemRecords(data.links),
+      ...nestedBlockItemRecords(data.alerts),
+    ].filter((item) => !nestedBlockItemEmpty(item));
+  }
+  
+  /**
+   * Reads OCR/customCanvas elements from a nested card and maps them into template-specific rows.
+   * @param block - Nested child card preview.
+   * @param visualKind - Target visual template.
+   * @returns Element-derived rows for status, resource, or incident regions.
+   */
+  function nestedBlockElementItems(block: CustomCanvasNestedBlock, visualKind: NestedBlockVisualKind): Array<Record<string, unknown>> {
+    const data = isRecord(block.data) ? block.data : {};
+    const elements = Array.isArray(data.elements) ? data.elements : [];
+    return elements
+      .flatMap((element): Array<Record<string, unknown>> => {
+        if (!isRecord(element)) return [];
+        const kind = textValue(element.kind);
+        if (visualKind === 'statusList' && kind === 'statusItem') {
+          return [{
+            label: textValue(element.label, textValue(element.title)),
+            status: textValue(element.status, '正常'),
+            tone: nestedBlockToneFromStatus(textValue(element.status)),
+          }];
+        }
+        if (visualKind === 'resourceBars' && kind === 'progress') {
+          const label = textValue(element.label, textValue(element.title));
+          const value = numberValue(element.value, 0);
+          return [{
+            label,
+            value: `${value}${textValue(element.unit) || '%'}`,
+            progress: value,
+            tone: nestedBlockToneFromProgress(label, value),
+          }];
+        }
+        if (visualKind === 'incidentList' && /alert|incident|warning|event/i.test(kind)) {
+          return [{
+            title: textValue(element.title, textValue(element.label)),
+            detail: textValue(element.detail, textValue(element.description)),
+            severity: textValue(element.severity, textValue(element.level, 'P1')),
+            time: textValue(element.time, textValue(element.meta)),
+            tone: nestedBlockToneFromStatus(textValue(element.severity, textValue(element.level))),
+          }];
+        }
+        return [];
+      })
+      .filter((item) => !nestedBlockItemEmpty(item));
+  }
+  
+  /**
+   * Maps status-like OCR text to the nested preview tone system.
+   * @param status - Status, severity, or level text.
+   * @returns Tone key used by dots, pills, and bars.
+   */
+  function nestedBlockToneFromStatus(status: string): NestedBlockTone {
+    if (/P1|告警|异常|失败|高危|超权|critical|error/i.test(status)) return 'critical';
+    if (/P2|卡顿|延期|中风险|弱口令|warning/i.test(status)) return 'warning';
+    if (/正常|通过|已归档|达标|完成|healthy|success/i.test(status)) return 'healthy';
+    return 'neutral';
+  }
+  
+  /**
+   * Maps resource utilization values to compact bar tones.
+   * @param label - Resource label from OCR.
+   * @param value - Utilization percentage.
+   * @returns Tone key for resource bars.
+   */
+  function nestedBlockToneFromProgress(label: string, value: number): NestedBlockTone {
+    if (/存储|storage/i.test(label) || value >= 80) return 'warning';
+    if (/CPU|内存|memory/i.test(label) || value >= 65) return 'info';
+    return 'healthy';
+  }
+  
+  type NestedBlockFallbackDomain = 'hr' | 'it' | 'marketing' | 'risk' | 'business';
+
+  /**
+   * Checks whether text contains IT/CIO-specific terms instead of generic business words.
+   * @param text - Searchable parent and child text.
+   * @returns True when fixed CIO templates are safe to apply.
+   */
+  function referenceCompositeTextHasItContext(text: string): boolean {
+    return /\b(CIO|IT)\b|信息化中心|IT\s*年度|IT\s*项目|IT\s*采购|IT\s*成本|IT\s*资产|系统上线审批|权限变更审批|安全整改待办|运维|研发|基础设施|服务监控|资源负载|机房|服务器|云主机|终端|License|软件|硬件|账号|权限|漏洞|攻击|网络安全|信息安全|安全事件|等保|堡垒机|服务工单|数据库|接口|中台|ERP|MES|WMS|SCM|CRM|ops|infrastructure|software|system|cyber|service desk/i.test(text);
+  }
+  
+  /**
+   * Chooses the business domain for screenshot-only fallback rows.
+   * @param text - Searchable nested-card classifier text.
+   * @returns Domain used to avoid leaking IT sample copy into HR or business dashboards.
+   */
+  function nestedBlockFallbackDomain(text: string): NestedBlockFallbackDomain {
+    if (/人力|人事|人才|用工|社保|合同|考勤|加班|迟到|旷工|请假|薪酬|绩效|招聘|员工|组织|编制|司龄|任免|继任|培训|持证|人效|HR/i.test(text)) return 'hr';
+    if (referenceCompositeTextHasItContext(text)) return 'it';
+    if (/风险|预警|偏差|盈利|资金|应收|预算|担保|投资|项目|隐患|超支|下滑|红线|亏损|违规|董事长|经营健康|risk/i.test(text)) return 'risk';
+    if (/营销|销售|客户|渠道|投放|线索|转化|竞品|品牌|舆情|活动|ROI|CAC/i.test(text)) return 'marketing';
+    return 'business';
+  }
+  
+  /**
+   * Expands generic HR child titles with parent-scene context before selecting fallback rows.
+   * @param block - Nested child card preview.
+   * @returns Searchable text with HR context added for generic titles such as 快捷入口.
+   */
+  function nestedBlockFallbackClassifierText(block: CustomCanvasNestedBlock): string {
+    const text = nestedBlockClassifierText(block);
+    if (/快捷|入口|待办|排行|梯队/.test(text)) return `${text} 人力 人事 人才 绩效 招聘 员工`;
+    return text;
+  }
+  
+  /**
+   * Provides screenshot-reference fallback rows when the image model only returned a coarse child card.
+   * @param block - Nested child card preview.
+   * @param visualKind - Selected visual template.
+   * @returns Fallback item rows used only for screenshot preview fidelity.
+   */
+  function nestedBlockFallbackItems(block: CustomCanvasNestedBlock, visualKind: NestedBlockVisualKind): Array<Record<string, unknown>> {
+    const text = nestedBlockFallbackClassifierText(block);
+    const domain = nestedBlockFallbackDomain(text);
+    if (visualKind === 'statusList') {
+      if (domain === 'hr') {
+        return [
+          { label: '组织编制', status: '关注', tone: 'warning' },
+          { label: '员工档案', status: '正常', tone: 'healthy' },
+          { label: '考勤同步', status: '正常', tone: 'healthy' },
+          { label: '薪酬批次', status: '待复核', tone: 'warning' },
+          { label: '用工合规', status: '告警', tone: 'critical' },
+        ];
+      }
+      return [
+        { label: 'ERP 核心套件', status: '正常', tone: 'healthy' },
+        { label: 'OA 协同门户', status: '正常', tone: 'healthy' },
+        { label: 'MES 生产执行', status: '卡顿', tone: 'warning' },
+        { label: 'CRM 客户平台', status: '正常', tone: 'healthy' },
+        { label: '财务共享系统', status: '告警', tone: 'critical' },
+      ];
+    }
+    if (visualKind === 'resourceBars') {
+      if (domain === 'hr') {
+        return [
+          { label: '研发', value: 97, tone: 'healthy' },
+          { label: '制造', value: 112, tone: 'critical' },
+          { label: '营销', value: 88, tone: 'warning' },
+          { label: '运营', value: 101, tone: 'healthy' },
+        ];
+      }
+      return [
+        { label: 'CPU', value: 68, tone: 'info' },
+        { label: '内存', value: 74, tone: 'info' },
+        { label: '存储', value: 84, tone: 'warning' },
+        { label: '带宽', value: 51, tone: 'healthy' },
+      ];
+    }
+    if (visualKind === 'incidentList') {
+      if (domain === 'hr') {
+        return [
+          { severity: '红', title: '合同 30 天内到期', detail: '重点岗位需续签确认', time: '今日', tone: 'critical' },
+          { severity: '红', title: '社保断缴 / 基数异常', detail: '跨区派遣与外包集中预警', time: '本周', tone: 'critical' },
+          { severity: '黄', title: '加班超标部门', detail: '制造、客服、交付中心连续超标', time: '6 项', tone: 'warning' },
+        ];
+      }
+      return [
+        { severity: 'P1', title: '财务系统支付网关失败', detail: '责任：应用中台 · 处理 68%', time: '32m', tone: 'critical' },
+        { severity: 'P1', title: 'MES 接口平均耗时 3.8s', detail: '责任：制造 IT · 已升级', time: '48m', tone: 'critical' },
+        { severity: 'P2', title: '数据库备份延迟', detail: '责任：DBA · 预计 10:30 恢复', time: '1h', tone: 'warning' },
+      ];
+    }
+    if (visualKind === 'progressList') {
+      if (domain === 'hr') {
+        return [
+          { label: '储备干部', value: '74%', progress: 74, tone: 'info' },
+          { label: '继任计划', value: '62%', progress: 62, tone: 'warning' },
+          { label: '培训完成', value: '88%', progress: 88, tone: 'healthy' },
+          { label: '持证覆盖', value: '79%', progress: 79, tone: 'info' },
+          { label: '低绩效改善', value: '216', progress: 42, tone: 'critical' },
+        ];
+      }
+      return [
+        { label: '数据中台二期', value: '76%', progress: 76, tone: 'healthy' },
+        { label: '供应链数字化改造', value: '延期', progress: 58, tone: 'warning' },
+        { label: '统一身份认证', value: '83%', progress: 83, tone: 'healthy' },
+        { label: '容灾双活改造', value: '卡点', progress: 42, tone: 'critical' },
+      ];
+    }
+    if (visualKind === 'todoGrid') {
+      if (domain === 'hr') {
+        return [
+          { label: '组织调整方案审批', value: '18' },
+          { label: '关键岗位任免确认', value: '7' },
+          { label: '年度调薪包复核', value: '24' },
+          { label: '招聘编制补录', value: '5' },
+        ];
+      }
+      return [
+        { label: 'IT 采购审批', value: '18' },
+        { label: '系统上线审批', value: '7' },
+        { label: '权限变更审批', value: '24' },
+        { label: '安全整改待办', value: '5' },
+      ];
+    }
+    if (visualKind === 'quickLinks') {
+      if (domain === 'hr') {
+        return [{ label: '招聘系统' }, { label: '绩效平台' }, { label: '员工档案' }, { label: '用工审计' }];
+      }
+      return [{ label: '运维平台' }, { label: '堡垒机' }, { label: '安全平台' }, { label: '服务工单' }];
+    }
+    if (visualKind === 'donut') {
+      if (domain === 'hr') {
+        return [
+          { label: '固定薪酬', value: '56%', share: 56, tone: 'info' },
+          { label: '浮动奖金', value: '16%', share: 16, tone: 'violet' },
+          { label: '社保福利', value: '14%', share: 14, tone: 'warning' },
+          { label: '外包费用', value: '14%', share: 14, tone: 'neutral' },
+        ];
+      }
+      return [
+        { label: '云资源费用', value: '42%', share: 42, tone: 'info' },
+        { label: '软件采购', value: '25%', share: 25, tone: 'violet' },
+        { label: '外包服务', value: '17%', share: 17, tone: 'warning' },
+        { label: '维保与机房', value: '16%', share: 16, tone: 'neutral' },
+      ];
+    }
+    if (visualKind === 'list') {
+      if (domain === 'hr') {
+        return [
+          { label: '合同到期续签', value: '待确认', tone: 'warning' },
+          { label: '社保基数异常', value: '需口径', tone: 'critical' },
+          { label: '人效排行复核', value: '待处理', tone: 'info' },
+        ];
+      }
+      if (domain === 'risk') {
+        return [
+          { label: '盈利结构恶化', value: '需确认', tone: 'critical' },
+          { label: '资金安全边际', value: '待补口径', tone: 'warning' },
+          { label: '项目风险', value: '跟进中', tone: 'violet' },
+        ];
+      }
+      if (domain === 'marketing') {
+        return [
+          { label: '渠道异常', value: '需确认', tone: 'warning' },
+          { label: '线索漏斗', value: '待补口径', tone: 'info' },
+          { label: '竞品动态', value: '跟进中', tone: 'violet' },
+        ];
+      }
+      return [
+        { label: '服务异常复核', value: '待处理', tone: 'warning' },
+        { label: '巡检风险项', value: '需确认', tone: 'critical' },
+        { label: '平台通知', value: '跟进中', tone: 'info' },
+      ];
+    }
+    if (/资产运营|资产状态/.test(text)) {
+      return [
+        { label: '闲置云主机待回收', value: '47 台', tone: 'warning' },
+        { label: 'License 即将到期', value: '12 项', tone: 'critical' },
+        { label: '资产盘点完成率', value: '96%', tone: 'healthy' },
+      ];
+    }
+    if (domain === 'hr' && visualKind === 'simpleList') {
+      return [
+        { label: '研发中心', value: '1.42', tone: 'healthy' },
+        { label: '营销体系', value: '1.31', tone: 'healthy' },
+        { label: '运营中心', value: '1.18', tone: 'healthy' },
+        { label: '制造体系', value: '0.78', tone: 'critical' },
+      ];
+    }
+    if (/成本优化/.test(text)) {
+      return [
+        { label: '本月云费用环比', value: '+8.4%', tone: 'warning' },
+        { label: '可释放资源降本空间', value: '128 万', tone: 'healthy' },
+        { label: '预算执行偏差', value: '-4.6%', tone: 'healthy' },
+      ];
+    }
+    if (/研发|效能/.test(text)) {
+      return [
+        { label: '版本上线频次', value: '34 次/月', tone: 'healthy' },
+        { label: '需求平均交付周期', value: '11.6 天', tone: 'healthy' },
+        { label: '线上 BUG 率', value: '1.8%', tone: 'warning' },
+      ];
+    }
+    if (/合规|审计/.test(text)) {
+      return [
+        { label: '等保 2.0 整改进度', value: '92%', tone: 'healthy' },
+        { label: '隐私合规检查', value: '通过', tone: 'healthy' },
+        { label: '日志留存覆盖率', value: '88%', tone: 'warning' },
+        { label: '离职未回收账号', value: '7 个', tone: 'critical' },
+        { label: '超权限管理员账号', value: '4 个', tone: 'critical' },
+        { label: '关键操作审计', value: '已归档', tone: 'healthy' },
+      ];
+    }
+    return [
+      { label: textValue(block.title, '事项'), value: nestedBlockMetricValue(block), tone: 'neutral' },
+    ];
+  }
+  
+  /**
+   * Returns normalized item rows for specialized nested preview renderers.
+   * @param block - Nested child card preview.
+   * @returns Model-provided rows, or screenshot-reference fallback rows.
+   */
+  function nestedBlockItems(block: CustomCanvasNestedBlock): Array<Record<string, unknown>> {
+    const visualKind = nestedBlockVisualKind(block);
+    const rawItems = nestedBlockRawItems(block);
+    if (rawItems.length > 0 && !nestedBlockItemsLookTooWeak(rawItems)) return rawItems;
+    return nestedBlockFallbackItems(block, visualKind);
+  }
+  
+  /**
+   * Returns row items for horizontal bar previews.
+   * @param block - Nested child card preview.
+   * @returns Bar-compatible item rows.
+   */
+  function nestedBlockBarItems(block: CustomCanvasNestedBlock): Array<Record<string, unknown>> {
+    return nestedBlockItems(block).slice(0, nestedBlockVisualKind(block) === 'resourceBars' ? 4 : 5);
+  }
+  
+  /**
+   * Returns tile items for metric, todo, and quick-link previews.
+   * @param block - Nested child card preview.
+   * @returns Tile-compatible item rows.
+   */
+  function nestedBlockTileItems(block: CustomCanvasNestedBlock): Array<Record<string, unknown>> {
+    return nestedBlockItems(block).slice(0, 4);
+  }
+  
+  /**
+   * Displays a primitive value without dropping numeric zeroes.
+   * @param value - Unknown value from model render data.
+   * @param fallback - Fallback label.
+   * @returns Display string.
+   */
+  function nestedBlockDisplayValue(value: unknown, fallback = ''): string {
+    if (typeof value === 'number' && Number.isFinite(value)) return String(value);
+    if (typeof value === 'string' && value.trim()) {
+      const normalized = value.trim();
+      return nestedBlockInternalSentinelValue(normalized) ? fallback : normalized;
+    }
+    return fallback;
+  }
+  
+  /**
+   * Extracts a label from a normalized nested item.
+   * @param item - Normalized item record.
+   * @param index - Item index for fallback labels.
+   * @returns Item label.
+   */
+  function nestedBlockItemLabel(item: Record<string, unknown>, index: number): string {
+    const direct = textValue(item.label, textValue(item.name, textValue(item.title, textValue(item.metric, textValue(item.dimension)))));
+    if (direct && direct !== '--') return direct;
+    const cells = Array.isArray(item.cells) ? item.cells : [];
+    const firstCell = nestedBlockDisplayValue(cells[0]);
+    return firstCell && firstCell !== '--' ? firstCell : `项目 ${index + 1}`;
+  }
+  
+  /**
+   * Extracts the primary value/status from a normalized nested item.
+   * @param item - Normalized item record.
+   * @returns Item value.
+   */
+  function nestedBlockItemValue(item: Record<string, unknown>): string {
+    const cells = Array.isArray(item.cells) ? item.cells : [];
+    return nestedBlockDisplayValue(
+      item.status ?? item.value ?? item.amount ?? item.ratio ?? item.progress ?? cells[1],
+      '',
+    );
+  }
+  
+  /**
+   * Extracts secondary detail text from a normalized nested item.
+   * @param item - Normalized item record.
+   * @returns Detail string.
+   */
+  function nestedBlockItemDetail(item: Record<string, unknown>): string {
+    return nestedBlockDisplayValue(item.detail ?? item.description ?? item.owner ?? item.subtitle, '');
+  }
+  
+  /**
+   * Builds a full tooltip title for a compact nested preview row.
+   * @param item - Normalized item record.
+   * @param index - Item index for fallback labels.
+   * @returns Full row text containing label, detail, and value when available.
+   */
+  function nestedBlockItemTitle(item: Record<string, unknown>, index: number): string {
+    return [
+      nestedBlockItemLabel(item, index),
+      nestedBlockItemDetail(item),
+      nestedBlockItemValue(item),
+    ].filter(Boolean).join(' · ');
+  }
+  
+  /**
+   * Extracts incident severity text from a normalized nested item.
+   * @param item - Normalized item record.
+   * @returns Severity label.
+   */
+  function nestedBlockItemSeverity(item: Record<string, unknown>): string {
+    return nestedBlockDisplayValue(item.severity ?? item.level ?? item.status, 'P1');
+  }
+  
+  /**
+   * Extracts time/meta text from a normalized nested item.
+   * @param item - Normalized item record.
+   * @returns Time or meta label.
+   */
+  function nestedBlockItemTime(item: Record<string, unknown>): string {
+    return nestedBlockDisplayValue(item.time ?? item.meta ?? item.updatedAt, '');
+  }
+  
+  /**
+   * Reads a finite number from a primitive value or a percentage-like string.
+   * @param value - Unknown numeric value.
+   * @param fallback - Fallback number.
+   * @returns Parsed number.
+   */
+  function nestedBlockNumber(value: unknown, fallback = 0): number {
+    if (typeof value === 'number' && Number.isFinite(value)) return value;
+    if (typeof value === 'string') {
+      const match = value.match(/-?\d+(?:\.\d+)?/);
+      if (match) return numberValue(match[0], fallback);
+    }
+    return fallback;
+  }
+  
+  /**
+   * Converts a numeric item field into a bounded CSS percentage.
+   * @param value - Numeric value, share, or percentage text.
+   * @param fallback - Fallback percentage.
+   * @returns Percentage string from 0 to 100.
+   */
+  function nestedBlockPercent(value: unknown, fallback = 56): string {
+    const numeric = nestedBlockNumber(value, fallback);
+    return `${Math.max(4, Math.min(100, numeric))}%`;
+  }
+  
+  /**
+   * Reads the progress field for one bar/tile item.
+   * @param item - Normalized item record.
+   * @param fallback - Fallback percentage.
+   * @returns CSS percentage width.
+   */
+  function nestedBlockItemProgress(item: Record<string, unknown>, fallback = 56): string {
+    return nestedBlockPercent(item.progress ?? item.share ?? item.value ?? item.amount, fallback);
+  }
+  
+  /**
+   * Reads a finite numeric value when a model row may contain counts instead of percentages.
+   * @param value - Candidate count, amount, or percentage-like string.
+   * @returns Parsed finite number, or undefined when no number is available.
+   */
+  function nestedBlockOptionalNumber(value: unknown): number | undefined {
+    if (typeof value === 'number' && Number.isFinite(value)) return value;
+    if (typeof value === 'string') {
+      const match = value.match(/-?\d+(?:\.\d+)?/);
+      if (match) {
+        const parsed = Number(match[0]);
+        return Number.isFinite(parsed) ? parsed : undefined;
+      }
+    }
+    return undefined;
+  }
+  
+  /**
+   * Reads the trend count for one ops chart bar without treating small counts as percentages.
+   * @param item - Normalized trend row from OCR/model output.
+   * @returns Count-like numeric value used for relative chart height.
+   */
+  function referenceOpsTrendCount(item: Record<string, unknown>): number {
+    return nestedBlockOptionalNumber(item.count)
+      ?? nestedBlockOptionalNumber(item.value)
+      ?? nestedBlockOptionalNumber(item.amount)
+      ?? nestedBlockOptionalNumber(item.total)
+      ?? nestedBlockOptionalNumber(item.progress)
+      ?? 0;
+  }
+  
+  /**
+   * Converts one seven-day incident count into a visible bar height relative to the row maximum.
+   * @param item - Trend row being rendered.
+   * @param items - All trend rows in the same chart.
+   * @returns CSS percentage height with a visual floor for low but non-zero counts.
+   */
+  function referenceOpsTrendBarHeight(item: Record<string, unknown>, items: Array<Record<string, unknown>>): string {
+    const counts = items.map(referenceOpsTrendCount).filter((count) => count > 0);
+    const max = Math.max(1, ...counts);
+    const count = referenceOpsTrendCount(item);
+    if (count <= 0) return '18%';
+    const ratio = Math.max(0, Math.min(1, count / max));
+    return `${Math.round(35 + ratio * 55)}%`;
+  }
+  
+  /**
+   * Precomputes relative bar heights for the seven-day ops trend chart.
+   * @param data - Custom canvas renderer data.
+   * @returns Trend rows with a normalized barHeight field for rendering.
+   */
+  function referenceOpsTrendChartItems(data: CustomCanvasData): Array<Record<string, unknown>> {
+    const items = referenceOpsTrendItems()(data);
+    return items.map((item) => ({
+      ...item,
+      barHeight: referenceOpsTrendBarHeight(item, items),
+    }));
+  }
+  
+  /**
+   * Chooses a semantic tone for nested item chips and bars.
+   * @param item - Normalized item record.
+   * @returns Tone key.
+   */
+  function nestedBlockTone(item: Record<string, unknown>): NestedBlockTone {
+    const rawTone = textValue(item.tone, textValue(item.barTone)).toLowerCase();
+    if (rawTone === 'healthy' || rawTone === 'success') return 'healthy';
+    if (rawTone === 'warning') return 'warning';
+    if (rawTone === 'critical' || rawTone === 'danger' || rawTone === 'error') return 'critical';
+    if (rawTone === 'info') return 'info';
+    if (rawTone === 'violet' || rawTone === 'purple') return 'violet';
+    const text = [item.status, item.value, item.severity, item.title, item.label, item.detail].map((value) => String(value ?? '')).join(' ');
+    if (/P1|告警|异常|失败|高危|超权|卡点|critical|error/i.test(text)) return 'critical';
+    if (/P2|卡顿|延期|中风险|弱口令|即将|warning/i.test(text)) return 'warning';
+    if (/正常|通过|已归档|达标|完成|healthy|success/i.test(text)) return 'healthy';
+    if (/CPU|内存|info|blue/i.test(text)) return 'info';
+    return 'neutral';
+  }
+  
+  /**
+   * Returns a stable tone class token for specialized nested preview templates.
+   * @param item - Normalized item record.
+   * @returns Tone class token used by pill, dot, and bar helpers.
+   */
+  function nestedBlockToneClass(item: Record<string, unknown>): NestedBlockTone {
+    return nestedBlockTone(item);
+  }
+  
+  /**
+   * Checks whether a customCanvas block is the first-viewport dark risk summary band.
+   * @param block - Rendered customCanvas block.
+   * @param data - Custom canvas renderer data.
+   * @returns True when a risk summary template should be used.
+   */
+  function customCanvasRiskSummaryBand(block: WorkbenchBlock, data: CustomCanvasData): boolean {
+    if (customCanvasExplicitImageHeaderBlock(block, data)) return false;
+    const visual = customCanvasEffectiveVisual(block, data);
+    const hasEffectiveRiskMarker = visual.businessSummaryBand === 'risk'
+      && referenceCompositeLooksLikeChairmanRiskDirectContext()(block, data);
+    if (hasEffectiveRiskMarker) return true;
+    const nestedBlocks = Array.isArray(data.nestedBlocks) ? data.nestedBlocks : [];
+    const directText = [block.title, data.sourceLabel, data.narrative].join(' ');
+    const riskChildCount = nestedBlocks.filter((nestedBlock) =>
+      /经营健康|重大经营风险|预算严重偏差|资金类预警|项目隐患|TODAY MOVEMENT|GLOBAL RISK POSTURE|risk posture|business risk|capital alert|budget deviation/i.test(nestedBlock.title),
+    ).length;
+    if (/安全风险总览|安全风险概览|security risk/i.test(directText)) return false;
+    if (!referenceCompositeLooksLikeChairmanRiskContext()(block, data)) return false;
+    return /风险总览|风险概览|顶部风险|经营健康|GLOBAL RISK POSTURE|risk posture/i.test(directText) && riskChildCount >= 4;
+  }
+
+  /**
+   * Checks whether stable V2 metadata marks a customCanvas card as screenshot page chrome.
+   * @param block - Rendered customCanvas block.
+   * @param data - Custom canvas renderer data.
+   * @returns True when stale business-summary visual markers must be ignored.
+   */
+  function customCanvasExplicitImageHeaderBlock(block: WorkbenchBlock, data: CustomCanvasData): boolean {
+    const meta = isRecord(block.meta) ? block.meta : {};
+    const metaV2 = isRecord(meta.v2) ? meta.v2 : {};
+    const record = data as unknown as Record<string, unknown>;
+    return [
+      block.source?.resourceKey,
+      meta.capabilityId,
+      metaV2.capabilityId,
+      record.themeId,
+    ].some((value) => typeof value === 'string' && /workbench\.v2\.image\.header|image-header-banner/i.test(value));
+  }
+  
+  /**
+   * Returns customCanvas visual metadata after stale risk shell markers are filtered.
+   * @param block - Rendered customCanvas block.
+   * @param data - Custom canvas renderer data.
+   * @returns Effective visual options for style and template routing.
+   */
+  function customCanvasEffectiveVisual(block: WorkbenchBlock, data: CustomCanvasData): BlockVisualOptions {
+    return visualForScene(block, data);
+  }
+  
+  /**
+   * Counts status rows by tone for the compact service-monitor summary strip.
+   * @param block - Nested child card preview.
+   * @returns Three stable summary buckets ordered as healthy, warning, and critical.
+   */
+  function nestedBlockStatusSummary(block: CustomCanvasNestedBlock): Array<{ tone: NestedBlockTone; count: number }> {
+    const counts: Record<NestedBlockTone, number> = {
+      healthy: 0,
+      warning: 0,
+      critical: 0,
+      info: 0,
+      violet: 0,
+      neutral: 0,
+    };
+    nestedBlockItems(block).forEach((item) => {
+      counts[nestedBlockToneClass(item)] += 1;
+    });
+    return [
+      { tone: 'healthy', count: counts.healthy },
+      { tone: 'warning', count: counts.warning + counts.info + counts.violet },
+      { tone: 'critical', count: counts.critical },
+    ];
+  }
+  
+  /**
+   * Maps a status-summary tone to a short product label.
+   * @param tone - Tone bucket from the status summary.
+   * @returns User-facing summary label.
+   */
+  function nestedBlockStatusSummaryLabel(tone: NestedBlockTone): string {
+    if (tone === 'healthy') return '正常';
+    if (tone === 'critical') return '告警';
+    return '关注';
+  }
+  
+  /**
+   * Builds pill classes for nested status/severity values.
+   * @param item - Normalized item record.
+   * @returns Tailwind class list.
+   */
+  function nestedBlockPillClasses(item: Record<string, unknown>): string[] {
+    const base = ['inline-block max-w-[5rem] shrink-0 truncate rounded-full border px-2 py-0.5 text-xs font-semibold leading-5'];
+    const tone = nestedBlockToneClass(item);
+    if (tone === 'healthy') return [...base, 'border-emerald-200 bg-emerald-50 text-emerald-700'];
+    if (tone === 'warning') return [...base, 'border-amber-200 bg-amber-50 text-amber-700'];
+    if (tone === 'critical') return [...base, 'border-red-200 bg-red-50 text-red-600'];
+    if (tone === 'info') return [...base, 'border-cyan-200 bg-cyan-50 text-cyan-700'];
+    if (tone === 'violet') return [...base, 'border-violet-200 bg-violet-50 text-violet-700'];
+    return [...base, 'border-slate-200 bg-slate-50 text-slate-600'];
+  }
+  
+  /**
+   * Builds dot classes for service status rows.
+   * @param item - Normalized item record.
+   * @returns Tailwind class list.
+   */
+  function nestedBlockDotClasses(item: Record<string, unknown>): string[] {
+    const base = ['h-2.5 w-2.5 shrink-0 rounded-full'];
+    const tone = nestedBlockToneClass(item);
+    if (tone === 'healthy') return [...base, 'bg-emerald-500'];
+    if (tone === 'warning') return [...base, 'bg-amber-500'];
+    if (tone === 'critical') return [...base, 'bg-red-500'];
+    if (tone === 'info') return [...base, 'bg-cyan-500'];
+    return [...base, 'bg-slate-400'];
+  }
+  
+  /**
+   * Builds fill classes for nested resource/progress bars.
+   * @param item - Normalized item record.
+   * @returns Tailwind class list.
+   */
+  function nestedBlockBarClasses(item: Record<string, unknown>): string[] {
+    const base = ['block h-full rounded-full'];
+    const tone = nestedBlockToneClass(item);
+    if (tone === 'healthy') return [...base, 'bg-emerald-600'];
+    if (tone === 'warning') return [...base, 'bg-amber-600'];
+    if (tone === 'critical') return [...base, 'bg-red-500'];
+    if (tone === 'violet') return [...base, 'bg-violet-600'];
+    return [...base, 'bg-cyan-600'];
+  }
+  
+  /**
+   * Builds vertical column classes for count-based mini bar charts.
+   * @param item - Normalized chart item.
+   * @returns Tailwind class list for a vertical rounded-top column.
+   */
+  function referenceOpsTrendBarClasses(item: Record<string, unknown>): string[] {
+    const base = ['block rounded-t-md rounded-b-sm'];
+    const tone = nestedBlockToneClass(item);
+    if (tone === 'healthy') return [...base, 'bg-emerald-600'];
+    if (tone === 'warning') return [...base, 'bg-amber-600'];
+    if (tone === 'critical') return [...base, 'bg-red-500'];
+    if (tone === 'violet') return [...base, 'bg-violet-600'];
+    if (tone === 'neutral') return [...base, 'bg-slate-400'];
+    return [...base, 'bg-cyan-600'];
+  }
+  
+  /**
+   * Builds CSS width for nested bar fills.
+   * @param item - Normalized item record.
+   * @param fallback - Fallback percentage.
+   * @returns CSS properties for the fill.
+   */
+  function nestedBlockBarStyle(item: Record<string, unknown>, fallback = 56): CSSProperties {
+    return { width: nestedBlockItemProgress(item, fallback) };
+  }
+  
+  /**
+   * Derives a compact progress stage label from model rows or fallback rows.
+   * @param item - Normalized progress item.
+   * @param index - Row index for stable fallback.
+   * @returns Short stage/status label rendered beside the progress bar.
+   */
+  function nestedBlockProgressStage(item: Record<string, unknown>, index: number): string {
+    const stage = nestedBlockDisplayValue(item.stage ?? item.phase ?? item.status, '');
+    if (stage) return stage;
+    const value = nestedBlockItemValue(item);
+    if (value && !/^\d+(?:\.\d+)?%$/.test(value)) return value;
+    return `阶段 ${index + 1}`;
+  }
+  
+  /**
+   * Returns the main score for security-score cards.
+   * @param block - Nested child card preview.
+   * @returns Score text.
+   */
+  function nestedBlockSecurityScore(block: CustomCanvasNestedBlock): string {
+    const data = isRecord(block.data) ? block.data : {};
+    return normalizeNestedBlockSecurityScoreText(
+      nestedBlockDisplayValue(data.value ?? data.primaryValue ?? data.displayValue, '86'),
+    );
+  }
+
+  /**
+   * Returns a short ring label for security-score visuals.
+   * @param block - Nested child card preview.
+   * @returns Numeric percentage label or a compact placeholder.
+   */
+  function nestedBlockSecurityScoreRingLabel(block: CustomCanvasNestedBlock): string {
+    const score = nestedBlockSecurityScore(block);
+    return /^\d+(?:\.\d+)?$/u.test(score) ? `${score}%` : '待补';
+  }
+
+  /**
+   * Strips model-emitted score units before the template appends "/ 100" and "%".
+   * @param value - Raw score text from image recognition or fallback data.
+   * @returns Numeric score text safe for compact security-score templates.
+   */
+  function normalizeNestedBlockSecurityScoreText(value: string): string {
+    const normalized = value.replace(/\s+/g, ' ').trim();
+    const ratio = normalized.match(/^(\d+(?:\.\d+)?)\s*\/\s*100(?:\s*分)?$/u);
+    if (ratio?.[1]) return ratio[1];
+    const withUnit = normalized.match(/^(\d+(?:\.\d+)?)\s*(?:%|分)$/u);
+    if (withUnit?.[1]) return withUnit[1];
+    const leadingNumber = normalized.match(/^(\d+(?:\.\d+)?)(?=\s*(?:\/|%|分|$))/u);
+    return leadingNumber?.[1] || normalized || '86';
+  }
+  
+  /**
+   * Returns compact metrics for the security score footer.
+   * @param block - Nested child card preview.
+   * @returns Footer metric rows.
+   */
+  function nestedBlockSecurityMetrics(block: CustomCanvasNestedBlock): Array<Record<string, unknown>> {
+    const data = isRecord(block.data) ? block.data : {};
+    const metrics = nestedBlockItemRecords(data.metrics);
+    if (metrics.length > 0) return metrics.slice(0, 3);
+    return [
+      { label: '高危漏洞', value: '3' },
+      { label: '防火墙拦截', value: '21k' },
+      { label: '账号风险', value: '9' },
+    ];
+  }
+  
+  /**
+   * Returns cost-analysis donut items.
+   * @param block - Nested child card preview.
+   * @returns Donut legend rows.
+   */
+  function nestedBlockDonutItems(block: CustomCanvasNestedBlock): Array<Record<string, unknown>> {
+    return nestedBlockNormalizedDonutItems(nestedBlockItems(block).slice(0, 4));
+  }
+
+  /**
+   * Keeps donut chart legend rows and visual slices on the same normalized scale.
+   * @param items - Donut legend items from model data or source-image fallbacks.
+   * @returns Items with normalizedShare used by the rendered conic-gradient.
+   */
+  function nestedBlockNormalizedDonutItems(items: Array<Record<string, unknown>>): Array<Record<string, unknown>> {
+    if (items.length === 0) return items;
+    const rawShares = items.map((item) => Math.max(0, nestedBlockNumber(item.share ?? item.value ?? item.amount ?? item.ratio ?? item.progress, 0)));
+    const totalShare = rawShares.reduce((sum, share) => sum + share, 0);
+    const fallbackShare = 100 / items.length;
+    return items.map((item, index) => {
+      const normalizedShare = totalShare > 0 ? (rawShares[index] / totalShare) * 100 : fallbackShare;
+      const displayValue = nestedBlockItemValue(item) || `${Math.round(normalizedShare)}%`;
+      return {
+        ...item,
+        value: displayValue,
+        normalizedShare,
+      };
+    });
+  }
+  
+  /**
+   * Builds conic-gradient style for the compact donut preview.
+   * @param block - Nested child card preview.
+   * @returns CSS properties for the donut ring.
+   */
+  function nestedBlockDonutStyle(block: CustomCanvasNestedBlock): CSSProperties {
+    const colors = ['#0F8B8D', '#6D4AE6', '#C6851A', '#9AA5B1'];
+    let cursor = 0;
+    const segments = nestedBlockDonutItems(block).map((item, index) => {
+      const share = Math.max(0, Math.min(100, nestedBlockNumber(item.normalizedShare, 25)));
+      const start = cursor;
+      cursor += share;
+      return `${colors[index % colors.length]} ${start}% ${Math.min(100, cursor)}%`;
+    });
+    return {
+      background: `radial-gradient(circle at center, #f8fafc 0 52%, transparent 53%), conic-gradient(${segments.join(', ')})`,
+    };
+  }
+  
+  /**
+   * Builds a two-character shortcut icon label from a quick-link row.
+   * @param item - Normalized quick-link item.
+   * @param index - Item index for fallback labels.
+   * @returns Compact icon text for the shortcut tile.
+   */
+  function nestedBlockQuickIconLabel(item: Record<string, unknown>, index: number): string {
+    const label = nestedBlockItemLabel(item, index).replace(/\s+/g, '');
+    const ascii = label.match(/[A-Za-z0-9]/g);
+    if (ascii && ascii.length > 0) return ascii.slice(0, 2).join('').toUpperCase();
+    return Array.from(label).slice(0, 2).join('') || String(index + 1);
+  }
+
+  /**
+   * Builds an adaptive grid for quick-link tiles so short and wide cards both fill cleanly.
+   * @param block - Nested quick-link child card.
+   * @returns CSS grid style that automatically changes column count from available width.
+   */
+  function nestedBlockQuickLinksGridStyle(block: CustomCanvasNestedBlock): CSSProperties {
+    const itemCount = nestedBlockTileItems(block).length;
+    return {
+      gridTemplateColumns: itemCount <= 2
+        ? 'repeat(auto-fit, minmax(min(10rem, 100%), 1fr))'
+        : 'repeat(auto-fit, minmax(min(8rem, 100%), 1fr))',
+    };
+  }
+  
+  function nestedBlockRows(block: CustomCanvasNestedBlock): Array<Record<string, unknown>> {
+    const data = isRecord(block.data) ? block.data : {};
+    const rows = Array.isArray(data.rows) ? data.rows.filter(isRecord) : [];
+    if (rows.length > 0 && !nestedBlockItemsLookTooWeak(rows)) return rows;
+    return nestedBlockItems(block).slice(0, 3).map((item, index) => ({
+      事项: nestedBlockItemLabel(item, index),
+      状态: nestedBlockItemValue(item) || nestedBlockItemDetail(item) || '待确认',
+    }));
+  }
+  
+  function nestedBlockColumns(block: CustomCanvasNestedBlock) {
+    const data = isRecord(block.data) ? block.data : {};
+    const declaredColumns = visibleImageTableColumns(data.columns);
+    if (declaredColumns.length > 0) return declaredColumns.slice(0, 3);
+    const firstRow = nestedBlockRows(block)[0];
+    return firstRow ? Object.keys(firstRow).filter(imageTableColumnVisible).slice(0, 3) : [];
+  }
+  
+  function nestedBlockRankingItems(block: CustomCanvasNestedBlock) {
+    const data = isRecord(block.data) ? block.data : {};
+    const items = Array.isArray(data.items) ? data.items.filter(isRecord) : [];
+    if (items.length > 0 && !nestedBlockItemsLookTooWeak(items)) return items.slice(0, 3);
+    const rows = Array.isArray(data.rows) ? data.rows.filter(isRecord) : [];
+    if (rows.length > 0 && !nestedBlockItemsLookTooWeak(rows)) return rows.slice(0, 3);
+    return nestedBlockItems(block).slice(0, 3);
+  }
+  
+  function nestedBlockCell(row: Record<string, unknown>, column: string) {
+    const value = row[column];
+    return structuredTableCellText(value, '--');
+  }
+  
+  function nestedBlockPreviewKind(block: CustomCanvasNestedBlock) {
+    const rendererKey = nestedBlockRendererKey(block);
+    const data = isRecord(block.data) ? block.data : {};
+    if (block.kind === 'metric' || rendererKey === 'metric' || typeof data.value === 'number' || typeof data.primaryValue === 'number') return 'metric';
+    if (block.kind === 'table' || rendererKey === 'dataTable' || Array.isArray(data.rows)) return 'table';
+    if (block.kind === 'list' || rendererKey === 'ranking' || Array.isArray(data.items)) return 'list';
+    if (block.kind === 'chart' || rendererKey.includes('Echarts') || rendererKey.includes('chart') || Array.isArray(data.series) || typeof data.chartType === 'string') return 'chart';
+    return 'summary';
+  }
+  
+  /**
+   * Checks whether a nested preview came from image compose and needs dense rendering.
+   * @param block - Nested child card preview.
+   * @returns True for image-composed nested previews.
+   */
+  function nestedBlockCompactPreview(block: CustomCanvasNestedBlock): boolean {
+    return nestedBlockComposeSource(block) === 'image'
+      || recordHasImageComposeSource(block.data)
+      || recordHasImageComposeSource(block.dataBinding)
+      || (typeof block.capabilityId === 'string' && block.capabilityId.startsWith('workbench.v2.image.'));
+  }
+  
+  /**
+   * Returns a stable grid fallback minimum height for nested image previews.
+   * @param block - Nested child card preview.
+   * @returns Tailwind minimum-height class sized for the preview content type.
+   */
+  function nestedBlockGridMinHeightClass(block: CustomCanvasNestedBlock, denseStack = false): string {
+    if (!nestedBlockCompactPreview(block)) return 'min-h-[96px]';
+    const previewKind = nestedBlockPreviewKind(block);
+    if (denseStack) return previewKind === 'metric' || previewKind === 'summary' ? 'min-h-[44px]' : 'min-h-[56px]';
+    return previewKind === 'metric' || previewKind === 'summary' ? 'min-h-[64px]' : 'min-h-[88px]';
+  }
+  
+  function nestedBlockStatusLabel(block: CustomCanvasNestedBlock) {
+    const status = textValue(block.dataBindingStatus, block.state?.status);
+    return {
+      none: '无绑定',
+      pending: '待问数',
+      running: '问数中',
+      ready: '已问数',
+      error: '问数失败',
+    }[status] || status;
+  }
+  
+  /**
+   * Checks whether a nested image container has no user-visible child/body content.
+   * @param block - Nested customCanvas child projected from an image container.
+   * @returns True when the preview should reserve the screenshot region without exposing protocol text.
+   */
+  function nestedBlockEmptyImageContainer(block: CustomCanvasNestedBlock): boolean {
+    if (!nestedBlockCompactPreview(block)) return false;
+    const data = isRecord(block.data) ? block.data : {};
+    const rendererKey = nestedBlockRendererKey(block);
+    const shape = textValue(data.shape);
+    if (block.kind !== 'container' && rendererKey !== 'customCanvas' && shape !== 'customCanvas') return false;
+    if (Array.isArray(data.nestedBlocks) && data.nestedBlocks.length > 0) return false;
+    if (Array.isArray(data.elements) && data.elements.some((element) => !customCanvasGeneratedElement(element))) return false;
+    return Object.entries(data)
+      .map(([key, value]) => nestedBlockSummaryEntry(key, value))
+      .filter((summary) => summary && summary !== block.title)
+      .length === 0;
+  }
+  
+  /**
+   * Reads the visible failed-query reason from a nested child preview.
+   * @param block - Nested child preview projected from a V2 container.
+   * @returns Failure reason with a stable fallback.
+   */
+  function nestedBlockFailureReason(block: CustomCanvasNestedBlock): string {
+    const intervention = dataBindingHumanInterventionFromRecord(block.humanIntervention)
+      ?? dataBindingHumanInterventionFromRecord(block.dataBinding?.humanIntervention);
+    if (intervention) {
+      return businessGapDiagnosticSummary({
+        message: intervention.message,
+        fallback: '需要补充业务口径后再问数',
+        diagnostics: block.dataBinding?.diagnostics,
+      });
+    }
+    return textValue(block.dataBindingError, '问数失败');
+  }
+  
+  /**
+   * Reads the backend human-intervention reason from a nested child preview.
+   * @param block - Nested child preview projected from a V2 container.
+   * @returns Stable reason code for browser diagnostics.
+   */
+  function nestedBlockBusinessGapReason(block: CustomCanvasNestedBlock): string {
+    const intervention = dataBindingHumanInterventionFromRecord(block.humanIntervention)
+      ?? dataBindingHumanInterventionFromRecord(block.dataBinding?.humanIntervention);
+    return textValue(intervention?.reason, '');
+  }
+  
+  /**
+   * Reads the query intent attached to a nested child preview.
+   * @param block - Nested child preview projected from a V2 container.
+   * @returns Query intent or child title fallback.
+   */
+  function nestedBlockQueryIntent(block: CustomCanvasNestedBlock): string {
+    return textValue(block.queryIntent, block.title);
+  }
+
+  return {
+    nestedBlockMetricValue,
+    nestedBlockClassifierText,
+    nestedBlockDeclaredVisualKind,
+    nestedBlockVisualKind,
+    nestedBlockItemRecords,
+    nestedBlockItemEmpty,
+    nestedBlockItemLooksWeak,
+    nestedBlockItemsLookTooWeak,
+    nestedBlockItemsLookTooWeakForVisualKind,
+    nestedBlockRawItems,
+    nestedBlockElementItems,
+    nestedBlockToneFromStatus,
+    nestedBlockToneFromProgress,
+    nestedBlockFallbackDomain,
+    nestedBlockFallbackClassifierText,
+    nestedBlockFallbackItems,
+    nestedBlockItems,
+    nestedBlockBarItems,
+    nestedBlockTileItems,
+    nestedBlockDisplayValue,
+    nestedBlockItemLabel,
+    nestedBlockItemValue,
+    nestedBlockItemDetail,
+    nestedBlockItemTitle,
+    nestedBlockItemSeverity,
+    nestedBlockItemTime,
+    nestedBlockNumber,
+    nestedBlockPercent,
+    nestedBlockItemProgress,
+    nestedBlockOptionalNumber,
+    referenceOpsTrendCount,
+    referenceOpsTrendBarHeight,
+    referenceOpsTrendChartItems,
+    nestedBlockTone,
+    nestedBlockToneClass,
+    customCanvasRiskSummaryBand,
+    customCanvasExplicitImageHeaderBlock,
+    customCanvasEffectiveVisual,
+    nestedBlockStatusSummary,
+    nestedBlockStatusSummaryLabel,
+    nestedBlockPillClasses,
+    nestedBlockDotClasses,
+    nestedBlockBarClasses,
+    referenceOpsTrendBarClasses,
+    nestedBlockBarStyle,
+    nestedBlockProgressStage,
+    nestedBlockSecurityScore,
+    nestedBlockSecurityScoreRingLabel,
+    nestedBlockSecurityMetrics,
+    nestedBlockNormalizedDonutItems,
+    nestedBlockDonutItems,
+    nestedBlockDonutStyle,
+    nestedBlockQuickIconLabel,
+    nestedBlockQuickLinksGridStyle,
+    nestedBlockRows,
+    nestedBlockColumns,
+    nestedBlockRankingItems,
+    nestedBlockCell,
+    nestedBlockPreviewKind,
+    nestedBlockCompactPreview,
+    nestedBlockGridMinHeightClass,
+    nestedBlockStatusLabel,
+    nestedBlockEmptyImageContainer,
+    nestedBlockFailureReason,
+    nestedBlockBusinessGapReason,
+    nestedBlockQueryIntent,
+  };
+}