@fses/workbench-app 0.2.0 → 0.2.1

package/node_modules/@fses/workbench-card/src/renderers/custom-canvas/canvasLayoutBindings.ts

@@ -0,0 +1,660 @@
+/**
+ * @fileoverview 自定义画布布局绑定 - 提供 customCanvas 子卡片布局、绝对定位和外壳样式 helper。
+ * @author seadon
+ * @created 2026-05-20
+ */
+import type { CSSProperties } from 'vue';
+import { workbenchCardShellStyle, workbenchShellDensityClasses } from '../../shell/workbenchVisualShell';
+import type { CustomCanvasData, CustomCanvasNestedBlock, WorkbenchBlock } from '../../types';
+import type { WorkbenchBlockRendererProps } from '../useWorkbenchBlockRendererBindings';
+
+type CanvasLayoutContext = Record<string, any> & { props: WorkbenchBlockRendererProps };
+
+type NestedStackTailPlacement = {
+  start: number;
+  span: number;
+};
+
+/**
+ * Creates layout helpers for customCanvas and nested previews.
+ * @param context - Shared renderer helpers and state.
+ * @returns Layout and shell helper functions.
+ */
+export function createCanvasLayoutBindings(context: CanvasLayoutContext) {
+  const {
+    props,
+    isRecord,
+    numberValue,
+    visualFor,
+    nestedBlockStyle,
+    nestedBlockGridMinHeightClass,
+    customCanvasEffectiveVisual,
+    customCanvasUsesStackNestedBlocks,
+    customCanvasNestedBlockGroups,
+    customCanvasDenseNestedStack,
+    customCanvasShowsStructureLabels,
+    customCanvasHeaderBannerBlock,
+    customCanvasPageHeaderBlock,
+    customCanvasEmptyPageHeaderPlaceholder,
+    recordHasImageComposeSource,
+  } = context;
+
+  const CUSTOM_CANVAS_NESTED_STACK_OUTLIER_WEIGHT_RATIO = 0.5;
+  const CUSTOM_CANVAS_SPARSE_ABSOLUTE_ROW_MAX_CHILDREN = 3;
+  const CUSTOM_CANVAS_SPARSE_ABSOLUTE_ROW_MIN_WIDTH_COVERAGE = 0.72;
+  const CUSTOM_CANVAS_SPARSE_ABSOLUTE_ROW_MAX_HEIGHT_COVERAGE = 0.62;
+  const CUSTOM_CANVAS_SPARSE_ABSOLUTE_ROW_MAX_TOP_RATIO = 0.18;
+  const CUSTOM_CANVAS_SPARSE_ABSOLUTE_ROW_ALIGNMENT_RATIO = 0.18;
+  const CUSTOM_CANVAS_ABSOLUTE_GRID_MIN_CHILDREN = 5;
+  const CUSTOM_CANVAS_ABSOLUTE_GRID_MAX_CHILDREN = 9;
+  const CUSTOM_CANVAS_ABSOLUTE_GRID_ROW_TOLERANCE_RATIO = 0.35;
+  const CUSTOM_CANVAS_ABSOLUTE_GRID_SIZE_TOLERANCE_RATIO = 0.35;
+  const CUSTOM_CANVAS_STACK_TAIL_FILL_MAX_CHILDREN = 4;
+
+  function customCanvasNestedStackContainerStyle(data: CustomCanvasData): CSSProperties | undefined {
+    if (!customCanvasUsesStackNestedBlocks(data)) return undefined;
+    const weights = customCanvasReadableNestedStackColumnWeights(customCanvasNestedStackColumnWeights(data));
+    const style: CSSProperties = {
+      gridTemplateColumns: weights.map((weight) => `minmax(0, ${weight}fr)`).join(' '),
+    };
+    if (customCanvasDenseNestedStack(data)) {
+      style.gridAutoRows = 'minmax(0, 1fr)';
+    }
+    return style;
+  }
+  
+  /**
+   * Builds proportional column weights for inferred nested stacks.
+   * @param data - Custom canvas renderer data.
+   * @returns Column weights derived from child width hints, with one column fallback.
+   */
+  function customCanvasNestedStackColumnWeights(data: CustomCanvasData): number[] {
+    const groups = customCanvasNestedBlockGroups(data);
+    if (groups.length === 0) return [1];
+    return groups.map((group: { blocks: CustomCanvasNestedBlock[] }) => Math.max(
+      1,
+      ...group.blocks.map((block: CustomCanvasNestedBlock) => customCanvasNestedLayoutItem(block.id, data).columnSpan),
+    ));
+  }
+  
+  /**
+   * Lifts one-off narrow OCR stack weights so nested cards stay readable in the browser.
+   * @param weights - Column weights derived from V2 child width hints.
+   * @returns Weights with very narrow outliers raised to the common readable width.
+   */
+  function customCanvasReadableNestedStackColumnWeights(weights: number[]): number[] {
+    if (weights.length < 2) return weights;
+    const finiteWeights = weights.filter((weight) => Number.isFinite(weight) && weight > 0).sort((left, right) => left - right);
+    if (finiteWeights.length < 2) return weights;
+    const maxWeight = finiteWeights[finiteWeights.length - 1] ?? 0;
+    const minWeight = finiteWeights[0] ?? 0;
+    if (maxWeight <= 0 || minWeight / maxWeight >= CUSTOM_CANVAS_NESTED_STACK_OUTLIER_WEIGHT_RATIO) return weights;
+    if (finiteWeights.length === 2) {
+      return weights.map((weight) => (weight === minWeight ? maxWeight : weight));
+    }
+    const readableWeight = finiteWeights.find((weight) => weight / maxWeight >= CUSTOM_CANVAS_NESTED_STACK_OUTLIER_WEIGHT_RATIO) ?? maxWeight;
+    return weights.map((weight) => (weight / maxWeight < CUSTOM_CANVAS_NESTED_STACK_OUTLIER_WEIGHT_RATIO ? readableWeight : weight));
+  }
+  
+  /**
+   * Builds the visual style for one nested preview in grid/stack/absolute modes.
+   * @param block - Nested child card preview.
+   * @param data - Custom canvas renderer data.
+   * @param usesAbsolute - Whether the current container is using absolute positioning.
+   * @returns CSS properties for the nested child card.
+   */
+  function nestedBlockCanvasStyle(
+    block: CustomCanvasNestedBlock,
+    data: CustomCanvasData,
+    usesAbsolute: boolean,
+  ): CSSProperties {
+    if (usesAbsolute) return nestedBlockAbsoluteStyle(block, data);
+    return {
+      ...nestedBlockStyle(block),
+      ...nestedBlockStackGridStyle(block, data),
+    };
+  }
+  
+  /**
+   * Positions a nested child inside the inferred stack grid.
+   * @param block - Nested child card preview.
+   * @param data - Custom canvas renderer data.
+   * @returns CSS grid placement for stack mode.
+   */
+  function nestedBlockStackGridStyle(block: CustomCanvasNestedBlock, data: CustomCanvasData): CSSProperties {
+    if (!customCanvasUsesStackNestedBlocks(data)) return {};
+    const groups = customCanvasNestedBlockGroups(data);
+    const item = customCanvasNestedLayoutItem(block.id, data);
+    for (let columnIndex = 0; columnIndex < groups.length; columnIndex += 1) {
+      const rowIndex = groups[columnIndex].blocks.findIndex((item: CustomCanvasNestedBlock) => item.id === block.id);
+      if (rowIndex >= 0) {
+        return {
+          gridColumn: `${columnIndex + 1}`,
+          gridRow: item.rowSpan > 1 ? `${rowIndex + 1} / span ${item.rowSpan}` : `${rowIndex + 1}`,
+        };
+      }
+    }
+    return {};
+  }
+
+  /**
+   * Detects regular multi-column stack grids that have only a sparse final row.
+   * @param data - Custom canvas renderer data containing stack groups.
+   * @returns Tail-row placement metadata when the stack represents a regular grid.
+   */
+  function customCanvasRegularNestedStackGrid(data: CustomCanvasData): { tailRowIndex: number; placements: Map<string, NestedStackTailPlacement> } | undefined {
+    if (!customCanvasUsesStackNestedBlocks(data)) return undefined;
+    const columns = customCanvasNestedBlockGroups(data).map((group: { blocks: CustomCanvasNestedBlock[] }) => group.blocks).filter((blocks: CustomCanvasNestedBlock[]) => blocks.length > 0);
+    const childCount = columns.reduce((sum: number, column: CustomCanvasNestedBlock[]) => sum + column.length, 0);
+    if (childCount > CUSTOM_CANVAS_STACK_TAIL_FILL_MAX_CHILDREN) return undefined;
+    if (columns.length < 2 || columns.length > 4) return undefined;
+    const lengths = columns.map((column: CustomCanvasNestedBlock[]) => column.length);
+    const minRows = Math.min(...lengths);
+    const maxRows = Math.max(...lengths);
+    if (minRows < 1 || maxRows <= 1 || maxRows - minRows !== 1) return undefined;
+    const tailColumnIndexes = lengths
+      .map((length: number, index: number) => (length === maxRows ? index : -1))
+      .filter((index: number) => index >= 0);
+    if (tailColumnIndexes.length === 0 || tailColumnIndexes.length >= columns.length) return undefined;
+    if (!tailColumnIndexes.every((columnIndex: number, index: number) => columnIndex === index)) return undefined;
+    const tailRowIndex = maxRows - 1;
+    const baseSpan = Math.floor(columns.length / tailColumnIndexes.length);
+    const remainder = columns.length % tailColumnIndexes.length;
+    const placements = new Map<string, NestedStackTailPlacement>();
+    let start = 0;
+    tailColumnIndexes.forEach((columnIndex: number, order: number) => {
+      const span = baseSpan + (order >= tailColumnIndexes.length - remainder ? 1 : 0);
+      const block = columns[columnIndex][tailRowIndex];
+      if (block?.id) {
+        placements.set(block.id, { start, span });
+      }
+      start += span;
+    });
+    return placements.size > 0 ? { tailRowIndex, placements } : undefined;
+  }
+
+  /**
+   * Expands sparse tail rows in inferred stack grids so the row fills the parent width.
+   * @param block - Nested child card preview.
+   * @param data - Custom canvas renderer data containing stack groups.
+   * @returns CSS grid placement override for sparse stack tail children.
+   */
+  function nestedBlockStackTailPlacementStyle(block: CustomCanvasNestedBlock, data: CustomCanvasData): CSSProperties {
+    const grid = customCanvasRegularNestedStackGrid(data);
+    const placement = grid?.placements.get(block.id);
+    if (!grid || !placement) return {};
+    return {
+      gridColumn: `${placement.start + 1} / span ${placement.span}`,
+      gridRow: `${grid.tailRowIndex + 1}`,
+    };
+  }
+  
+  /**
+   * Reads per-child stack sizing hints emitted by the V2 image adapter.
+   * @param blockId - Nested child id.
+   * @param data - Custom canvas renderer data.
+   * @returns Safe row/column spans for stack grid placement.
+   */
+  function customCanvasNestedLayoutItem(blockId: string, data: CustomCanvasData): { rowSpan: number; columnSpan: number } {
+    const items = (isRecord(data.nestedLayoutItems) ? data.nestedLayoutItems : {}) as Record<string, unknown>;
+    const item = (isRecord(items[blockId]) ? items[blockId] : {}) as Record<string, unknown>;
+    return {
+      rowSpan: Math.max(1, Math.round(numberValue(item.rowSpan, 1))),
+      columnSpan: Math.max(1, Math.round(numberValue(item.columnSpan, 1))),
+    };
+  }
+  
+  /**
+   * Checks whether a nested preview has a complete layout box.
+   * @param block - Nested child card preview.
+   * @returns True when x/y/w/h can be converted into percentages.
+   */
+  function nestedBlockHasLayout(block: CustomCanvasNestedBlock): boolean {
+    return ['x', 'y', 'w', 'h'].every((key) => Number.isFinite(numberValue((block.layout as unknown as Record<string, unknown> | undefined)?.[key], Number.NaN)));
+  }
+  
+  /**
+   * Converts a nested preview layout to parent-local coordinates for runtime safety checks.
+   * @param block - Nested child card preview.
+   * @param data - Custom canvas renderer data containing parent basis.
+   * @returns Parent-local layout box, or undefined when layout data is incomplete.
+   */
+  function customCanvasAbsoluteNestedBox(block: CustomCanvasNestedBlock, data: CustomCanvasData): { x: number; y: number; w: number; h: number } | undefined {
+    const layout = (isRecord(block.layout) ? block.layout : {}) as Record<string, unknown>;
+    if (!nestedBlockHasLayout(block)) return undefined;
+    const basis = (isRecord(data.nestedLayoutBasis) ? data.nestedLayoutBasis : {}) as Record<string, unknown>;
+    const usesGlobalCoordinates = nestedBlockUsesGlobalCoordinates(layout, basis);
+    return {
+      x: nestedBlockLocalCoordinate(numberValue(layout['x']), numberValue(basis.x), usesGlobalCoordinates),
+      y: nestedBlockLocalCoordinate(numberValue(layout['y']), numberValue(basis.y), usesGlobalCoordinates),
+      w: Math.max(1, numberValue(layout['w'])),
+      h: Math.max(1, numberValue(layout['h'])),
+    };
+  }
+  
+  /**
+   * Calculates pairwise overlap area for nested preview boxes.
+   * @param boxes - Parent-local nested preview boxes.
+   * @returns Summed pairwise overlap area.
+   */
+  function customCanvasAbsoluteNestedOverlapArea(boxes: Array<{ x: number; y: number; w: number; h: number }>): number {
+    let overlapArea = 0;
+    for (let leftIndex = 0; leftIndex < boxes.length; leftIndex += 1) {
+      for (let rightIndex = leftIndex + 1; rightIndex < boxes.length; rightIndex += 1) {
+        const left = boxes[leftIndex];
+        const right = boxes[rightIndex];
+        const overlapW = Math.max(0, Math.min(left.x + left.w, right.x + right.w) - Math.max(left.x, right.x));
+        const overlapH = Math.max(0, Math.min(left.y + left.h, right.y + right.h) - Math.max(left.y, right.y));
+        overlapArea += overlapW * overlapH;
+      }
+    }
+    return overlapArea;
+  }
+
+  /**
+   * Finds the horizontal span covered by absolute nested child cards.
+   * @param boxes - Parent-local nested preview boxes.
+   * @returns Combined horizontal coverage span.
+   */
+  function customCanvasAbsoluteNestedWidthSpan(boxes: Array<{ x: number; y: number; w: number; h: number }>): number {
+    if (boxes.length === 0) return 0;
+    const left = Math.min(...boxes.map((box) => box.x));
+    const right = Math.max(...boxes.map((box) => box.x + box.w));
+    return Math.max(0, right - left);
+  }
+
+  /**
+   * Detects source-image child cards that form one sparse row inside a tall parent panel.
+   * @param block - Nested child card preview.
+   * @param data - Custom canvas renderer data containing all sibling previews.
+   * @returns True when this child should fill the parent body height.
+   */
+  function customCanvasSparseAbsoluteNestedRowFill(block: CustomCanvasNestedBlock, data: CustomCanvasData): boolean {
+    const children = Array.isArray(data.nestedBlocks) ? data.nestedBlocks : [];
+    if (children.length < 2 || children.length > CUSTOM_CANVAS_SPARSE_ABSOLUTE_ROW_MAX_CHILDREN) return false;
+    if (!children.some((child) => child.id === block.id)) return false;
+    const boxes = children
+      .map((child) => customCanvasAbsoluteNestedBox(child, data))
+      .filter((box): box is { x: number; y: number; w: number; h: number } => Boolean(box));
+    if (boxes.length !== children.length) return false;
+    const basis = (isRecord(data.nestedLayoutBasis) ? data.nestedLayoutBasis : {}) as Record<string, unknown>;
+    const basisW = Math.max(1, numberValue(basis.w, 24));
+    const basisH = Math.max(1, numberValue(basis.h, 1));
+    const top = Math.min(...boxes.map((box) => box.y));
+    const bottom = Math.max(...boxes.map((box) => box.y + box.h));
+    const maxTopDelta = Math.max(1, basisH * CUSTOM_CANVAS_SPARSE_ABSOLUTE_ROW_ALIGNMENT_RATIO);
+    const sameVisualRow = boxes.every((box) => Math.abs(box.y - top) <= maxTopDelta);
+    const widthCoverage = customCanvasAbsoluteNestedWidthSpan(boxes) / basisW;
+    const heightCoverage = Math.max(0, bottom - top) / basisH;
+    if (!sameVisualRow) return false;
+    if (top / basisH > CUSTOM_CANVAS_SPARSE_ABSOLUTE_ROW_MAX_TOP_RATIO) return false;
+    if (widthCoverage < CUSTOM_CANVAS_SPARSE_ABSOLUTE_ROW_MIN_WIDTH_COVERAGE) return false;
+    return heightCoverage < CUSTOM_CANVAS_SPARSE_ABSOLUTE_ROW_MAX_HEIGHT_COVERAGE;
+  }
+
+  /**
+   * Groups absolute child boxes into source rows when the model produced a grid-like layout.
+   * @param data - Custom canvas renderer data containing sibling preview boxes.
+   * @returns Ordered rows of child boxes, or an empty list when the layout is not grid-like.
+   */
+  function customCanvasAbsoluteNestedRows(
+    data: CustomCanvasData,
+  ): Array<Array<{ block: CustomCanvasNestedBlock; box: { x: number; y: number; w: number; h: number } }>> {
+    const children = Array.isArray(data.nestedBlocks) ? data.nestedBlocks : [];
+    if (children.length < CUSTOM_CANVAS_ABSOLUTE_GRID_MIN_CHILDREN || children.length > CUSTOM_CANVAS_ABSOLUTE_GRID_MAX_CHILDREN) return [];
+    const entries = children
+      .map((block) => {
+        const box = customCanvasAbsoluteNestedBox(block, data);
+        return box ? { block, box } : undefined;
+      })
+      .filter((entry): entry is { block: CustomCanvasNestedBlock; box: { x: number; y: number; w: number; h: number } } => Boolean(entry))
+      .sort((left, right) => left.box.y - right.box.y || left.box.x - right.box.x);
+    if (entries.length !== children.length) return [];
+    const medianHeight = medianPositive(entries.map((entry) => entry.box.h));
+    const medianWidth = medianPositive(entries.map((entry) => entry.box.w));
+    if (medianHeight <= 0 || medianWidth <= 0) return [];
+    const rowTolerance = Math.max(1, medianHeight * CUSTOM_CANVAS_ABSOLUTE_GRID_ROW_TOLERANCE_RATIO);
+    const rows: Array<Array<{ block: CustomCanvasNestedBlock; box: { x: number; y: number; w: number; h: number } }>> = [];
+    entries.forEach((entry) => {
+      const row = rows.find((candidate) => Math.abs(candidate[0].box.y - entry.box.y) <= rowTolerance);
+      if (row) {
+        row.push(entry);
+      } else {
+        rows.push([entry]);
+      }
+    });
+    rows.forEach((row) => row.sort((left, right) => left.box.x - right.box.x));
+    if (rows.length < 2) return [];
+    const fullRowSize = Math.max(...rows.map((row) => row.length));
+    if (fullRowSize < 2) return [];
+    const fullRows = rows.filter((row) => row.length === fullRowSize);
+    if (fullRows.length === 0) return [];
+    const gridLikeSizes = entries.every((entry) => (
+      Math.abs(entry.box.w - medianWidth) / medianWidth <= CUSTOM_CANVAS_ABSOLUTE_GRID_SIZE_TOLERANCE_RATIO
+      && Math.abs(entry.box.h - medianHeight) / medianHeight <= CUSTOM_CANVAS_ABSOLUTE_GRID_SIZE_TOLERANCE_RATIO
+    ));
+    return gridLikeSizes ? rows : [];
+  }
+
+  /**
+   * Returns the median of positive finite numbers.
+   * @param values - Candidate numeric values.
+   * @returns Median positive value, or zero when no usable value exists.
+   */
+  function medianPositive(values: number[]): number {
+    const sorted = values.filter((value) => Number.isFinite(value) && value > 0).sort((left, right) => left - right);
+    if (sorted.length === 0) return 0;
+    return sorted[Math.floor(sorted.length / 2)] ?? 0;
+  }
+
+  /**
+   * Expands a single sparse absolute-grid tail child to the row end.
+   * @param block - Nested child card preview.
+   * @param data - Custom canvas renderer data containing sibling preview boxes.
+   * @returns Adjusted absolute box for tail-row fill, or undefined when no adjustment is needed.
+   */
+  function absoluteNestedBlockGridTailPlacementStyle(
+    block: CustomCanvasNestedBlock,
+    data: CustomCanvasData,
+  ): { x: number; y: number; w: number; h: number } | undefined {
+    const rows = customCanvasAbsoluteNestedRows(data);
+    if (rows.length === 0) return undefined;
+    const tailBlocks = rows[rows.length - 1] ?? [];
+    if (tailBlocks.length === 0) return undefined;
+    const fullRowSize = Math.max(...rows.slice(0, -1).map((row) => row.length), 0);
+    if (fullRowSize < 2 || tailBlocks.length >= fullRowSize) return undefined;
+    if (tailBlocks.length === 1 && tailBlocks[0].block.id !== block.id) return undefined;
+    const basis = (isRecord(data.nestedLayoutBasis) ? data.nestedLayoutBasis : {}) as Record<string, unknown>;
+    const basisW = Math.max(1, numberValue(basis.w, 24));
+    const baseBox = tailBlocks.find((entry) => entry.block.id === block.id)?.box;
+    if (!baseBox) return undefined;
+    const tailBox = tailBlocks[0].box;
+    const adjustedWidth = tailBlocks.length === 1
+      ? basisW - tailBox.x
+      : baseBox.w;
+    return {
+      ...baseBox,
+      w: Math.max(baseBox.w, adjustedWidth),
+    };
+  }
+
+  /**
+   * Removes excessive leading whitespace from sparse absolute nested previews.
+   * @param data - Custom canvas renderer data containing sibling preview boxes.
+   * @returns Parent-local row offset that should be subtracted from every sparse child.
+   */
+  function customCanvasSparseAbsoluteNestedTopOffset(data: CustomCanvasData): number {
+    const children = Array.isArray(data.nestedBlocks) ? data.nestedBlocks : [];
+    if (children.length === 0 || children.length > CUSTOM_CANVAS_SPARSE_ABSOLUTE_ROW_MAX_CHILDREN) return 0;
+    if (customCanvasAbsoluteNestedRows(data).length > 0) return 0;
+    const boxes = children
+      .map((child) => customCanvasAbsoluteNestedBox(child, data))
+      .filter((box): box is { x: number; y: number; w: number; h: number } => Boolean(box));
+    if (boxes.length !== children.length) return 0;
+    const basis = (isRecord(data.nestedLayoutBasis) ? data.nestedLayoutBasis : {}) as Record<string, unknown>;
+    const basisH = Math.max(1, numberValue(basis.h, 1));
+    const top = Math.min(...boxes.map((box) => box.y));
+    return top / basisH > CUSTOM_CANVAS_SPARSE_ABSOLUTE_ROW_MAX_TOP_RATIO ? top : 0;
+  }
+  
+  /**
+   * Converts a layout number to a bounded percentage.
+   * @param value - Raw ratio value.
+   * @returns Percentage string clamped to the container.
+   */
+  function layoutPercent(value: number): string {
+    return `${Math.max(0, Math.min(100, value))}%`;
+  }
+  
+  /**
+   * Checks whether a nested child layout looks like global screenshot coordinates.
+   * @param layout - Child layout emitted by image recognition.
+   * @param basis - Parent layout basis in the same V2 coordinate space.
+   * @returns True when the child's x/y are outside the parent-local range.
+   */
+  function nestedBlockUsesGlobalCoordinates(layout: Record<string, unknown>, basis: Record<string, unknown>): boolean {
+    const x = numberValue(layout['x']);
+    const y = numberValue(layout['y']);
+    const w = Math.max(1, numberValue(layout['w']));
+    const h = Math.max(1, numberValue(layout['h']));
+    const basisW = Math.max(1, numberValue(basis.w, 24));
+    const basisH = Math.max(1, numberValue(basis.h, 1));
+    return x + w > basisW || y + h > basisH;
+  }
+  
+  /**
+   * Converts a child coordinate into the parent-local coordinate space.
+   * @param value - Child x or y coordinate.
+   * @param offset - Parent x or y coordinate.
+   * @param usesGlobalCoordinates - Whether the child coordinate is global.
+   * @returns Parent-local coordinate.
+   */
+  function nestedBlockLocalCoordinate(value: number, offset: number, usesGlobalCoordinates: boolean): number {
+    return usesGlobalCoordinates ? Math.max(0, value - offset) : value;
+  }
+  
+  /**
+   * Builds screenshot-relative positioning for a nested child preview.
+   * @param block - Nested child card preview.
+   * @param data - Custom canvas renderer data containing parent basis.
+   * @returns CSS properties combining child shell style and absolute layout.
+   */
+  function nestedBlockAbsoluteStyle(block: CustomCanvasNestedBlock, data: CustomCanvasData): CSSProperties {
+    const style = nestedBlockStyle(block);
+    const layout = (isRecord(block.layout) ? block.layout : {}) as Record<string, unknown>;
+    const basis = (isRecord(data.nestedLayoutBasis) ? data.nestedLayoutBasis : {}) as Record<string, unknown>;
+    const usesGlobalCoordinates = nestedBlockUsesGlobalCoordinates(layout, basis);
+    const basisW = Math.max(1, numberValue(basis.w, 24));
+    const basisH = Math.max(1, numberValue(basis.h, 1));
+    const x = nestedBlockLocalCoordinate(numberValue(layout['x']), numberValue(basis.x), usesGlobalCoordinates);
+    const y = nestedBlockLocalCoordinate(numberValue(layout['y']), numberValue(basis.y), usesGlobalCoordinates);
+    const w = Math.max(1, numberValue(layout['w'], basisW));
+    const h = Math.max(1, numberValue(layout['h'], basisH));
+    const baseBox = { x, y, w, h };
+    const adjustedBox = absoluteNestedBlockGridTailPlacementStyle(block, data) ?? baseBox;
+    const sparseRowFill = customCanvasSparseAbsoluteNestedRowFill(block, data);
+    const sparseTopOffset = customCanvasSparseAbsoluteNestedTopOffset(data);
+    const top = Math.max(0, adjustedBox.y - sparseTopOffset);
+    return {
+      ...style,
+      position: 'absolute',
+      left: layoutPercent((adjustedBox.x / basisW) * 100),
+      top: sparseRowFill ? '0%' : layoutPercent((top / basisH) * 100),
+      width: layoutPercent((adjustedBox.w / basisW) * 100),
+      height: sparseRowFill ? '100%' : layoutPercent((h / basisH) * 100),
+      overflow: 'hidden',
+    };
+  }
+  
+  function nestedBlockAccentStyle(block: CustomCanvasNestedBlock): CSSProperties | undefined {
+    const visual = (isRecord(block.visual) ? block.visual : {}) as Record<string, unknown>;
+    return typeof visual.accentColor === 'string' ? { color: visual.accentColor } : undefined;
+  }
+  
+  /**
+   * Converts a finite number into a bounded percentage for positioned screenshot elements.
+   * @param value - Raw coordinate or dimension from image recognition.
+   * @returns Percentage string when the value is finite.
+   */
+  function customCanvasPercent(value: unknown): string | undefined {
+    if (typeof value !== 'number' || !Number.isFinite(value)) return undefined;
+    return `${Math.max(0, Math.min(100, value))}%`;
+  }
+  
+  /**
+   * Reads safe CSS properties from an image-recognized customCanvas element.
+   * @param style - Raw model style object.
+   * @returns CSS properties allowed for screenshot text/badge fidelity.
+   */
+  function customCanvasSafeElementStyle(style: unknown): CSSProperties {
+    if (!isRecord(style)) return {};
+    const allowedKeys = new Set([
+      'background',
+      'backgroundColor',
+      'borderColor',
+      'borderRadius',
+      'color',
+      'fontSize',
+      'fontWeight',
+      'lineHeight',
+      'opacity',
+      'textAlign',
+    ]);
+    return Object.fromEntries(
+      Object.entries(style as Record<string, unknown>).filter(([key, value]) =>
+        allowedKeys.has(key) && (typeof value === 'string' || typeof value === 'number'),
+      ),
+    ) as CSSProperties;
+  }
+  
+  /**
+   * Builds absolute-position CSS for OCR/header customCanvas elements.
+   * @param element - Model-recognized customCanvas element with optional x/y/w/h.
+   * @returns CSS properties used to place the element within its screenshot container.
+   */
+  function customCanvasElementStyle(element: CustomCanvasData['elements'][number]): CSSProperties {
+    const style: CSSProperties = {
+      ...customCanvasSafeElementStyle(element.style),
+      left: customCanvasPercent(element.x) ?? '0%',
+      top: customCanvasPercent(element.y) ?? '0%',
+    };
+    const width = customCanvasPercent(element.w);
+    const height = customCanvasPercent(element.h);
+    if (width) style.width = width;
+    if (height) style.minHeight = height;
+    return style;
+  }
+  
+  /**
+   * Builds classes for absolute-position customCanvas elements.
+   * @param element - Model-recognized customCanvas element.
+   * @returns Tailwind class list for text, badge, metric, and divider elements.
+   */
+  function customCanvasElementClasses(element: CustomCanvasData['elements'][number]): string[] {
+    const base = ['absolute', 'min-w-0', 'overflow-hidden'];
+    if (element.kind === 'badge') {
+      return [...base, 'inline-flex', 'items-center', 'justify-center', 'rounded', 'border', 'border-white/20', 'bg-white/12', 'px-2', 'py-1', 'text-xs', 'font-medium', 'leading-5'];
+    }
+    if (element.kind === 'metric') {
+      return [...base, 'text-sm', 'font-semibold', 'leading-5'];
+    }
+    if (element.kind === 'divider') {
+      return [...base, 'border-t', 'border-white/25'];
+    }
+    return [...base, 'text-sm', 'font-semibold', 'leading-5'];
+  }
+  
+  function customCanvasStyle(block: WorkbenchBlock, data: CustomCanvasData): CSSProperties {
+    if (typeof customCanvasEmptyPageHeaderPlaceholder === 'function' && customCanvasEmptyPageHeaderPlaceholder(block, data)) {
+      return {
+        background: 'transparent',
+        borderColor: 'transparent',
+        boxShadow: 'none',
+        color: 'transparent',
+      };
+    }
+    const visual = customCanvasEffectiveVisual()(block, data);
+    const background = typeof data.background === 'string' && data.background.trim()
+      ? data.background
+      : visual.backgroundColor || '#f8fafc';
+    const style = workbenchCardShellStyle(visual, { background });
+    if (recordHasImageComposeSource()(block.meta) && !style.color && /^#?(0f172a|111827|141414|1f2937)$/i.test(String(background).replace(/\s+/g, ''))) {
+      style.color = '#F8FAFC';
+    }
+    return style;
+  }
+
+  /**
+   * Invokes the page-header detector regardless of whether the caller passed it directly
+   * or through the same lazy helper wrapper used by sibling canvas bindings.
+   * @param block - Custom canvas block being rendered.
+   * @param data - Custom canvas data for the block.
+   * @returns True when the canvas should render as source-image page chrome.
+   */
+  function callCustomCanvasPageHeaderBlock(block: WorkbenchBlock, data: CustomCanvasData): boolean {
+    if (typeof customCanvasPageHeaderBlock !== 'function') return false;
+    try {
+      const directResult = customCanvasPageHeaderBlock(block, data);
+      if (typeof directResult === 'boolean') return directResult;
+      if (typeof directResult === 'function') return Boolean(directResult(block, data));
+      return Boolean(directResult);
+    } catch {
+      const wrapped = customCanvasPageHeaderBlock();
+      return typeof wrapped === 'function' ? Boolean(wrapped(block, data)) : Boolean(wrapped);
+    }
+  }
+  
+  /**
+   * Builds density-aware classes for a V2 container projected as customCanvas.
+   * @param block - Container block carrying screenshot appearance metadata.
+   * @returns Tailwind class list for customCanvas spacing.
+   */
+  function customCanvasShellClasses(block: WorkbenchBlock): string[] {
+    const densityValue = visualFor(block).density || props.density;
+    const data = block.data as CustomCanvasData | undefined;
+    const headerBanner = customCanvasHeaderBannerBlock()(block)
+      || (data ? callCustomCanvasPageHeaderBlock(block, data) : false);
+    return [
+      headerBanner
+        ? 'flex h-full min-h-0 w-full flex-col overflow-hidden border-0'
+        : 'relative flex h-full min-h-0 w-full flex-col overflow-hidden border border-slate-100',
+      customCanvasShowsStructureLabels()(block) ? 'workbench-custom-canvas-show-structure' : 'workbench-custom-canvas-image',
+      headerBanner
+        ? 'p-0'
+        : workbenchShellDensityClasses(densityValue, { compact: 'space-y-2 p-3', standard: 'space-y-3 p-4' }),
+    ];
+  }
+  
+  /**
+   * Builds density-aware classes for a nested child preview.
+   * @param block - Nested preview block carrying child appearance metadata.
+   * @returns Tailwind class list for nested preview spacing.
+   */
+  function nestedBlockShellClasses(block: CustomCanvasNestedBlock, absoluteLayout = false, denseStack = false, naturalGrid = false): string[] {
+    const densityValue = block.visual?.density || props.density;
+    return [
+      'workbench-nested-card-preview-shell flex flex-col min-w-0 rounded-md border border-slate-300 bg-white text-left shadow-[inset_0_0_0_1px_rgba(76,120,252,0.08)] transition hover:border-[#4C78FC] hover:bg-[#f8fbff] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#4C78FC] focus-visible:ring-offset-2',
+      absoluteLayout ? 'ring-1 ring-slate-200/80' : '',
+      absoluteLayout || naturalGrid ? `overflow-hidden ${nestedBlockGridMinHeightClass(block, denseStack)}` : `h-full overflow-hidden ${nestedBlockGridMinHeightClass(block, denseStack)}`,
+      workbenchShellDensityClasses(densityValue, { compact: 'px-2 py-2', standard: 'px-3 py-2' }),
+    ];
+  }
+  
+  /**
+   * Applies screenshot-level visual appearance to a manual placeholder shell.
+   * @param block - Placeholder block projected from image compose.
+   * @returns CSS properties for the placeholder container.
+   */
+
+  return {
+    customCanvasNestedStackContainerStyle,
+    customCanvasNestedStackColumnWeights,
+    customCanvasReadableNestedStackColumnWeights,
+    nestedBlockCanvasStyle,
+    nestedBlockStackGridStyle,
+    customCanvasNestedLayoutItem,
+    customCanvasRegularNestedStackGrid,
+    nestedBlockStackTailPlacementStyle,
+    nestedBlockHasLayout,
+    customCanvasAbsoluteNestedBox,
+    customCanvasAbsoluteNestedOverlapArea,
+    customCanvasAbsoluteNestedWidthSpan,
+    customCanvasSparseAbsoluteNestedRowFill,
+    customCanvasAbsoluteNestedRows,
+    absoluteNestedBlockGridTailPlacementStyle,
+    customCanvasSparseAbsoluteNestedTopOffset,
+    layoutPercent,
+    nestedBlockUsesGlobalCoordinates,
+    nestedBlockLocalCoordinate,
+    nestedBlockAbsoluteStyle,
+    nestedBlockAccentStyle,
+    customCanvasPercent,
+    customCanvasSafeElementStyle,
+    customCanvasElementStyle,
+    customCanvasElementClasses,
+    customCanvasStyle,
+    callCustomCanvasPageHeaderBlock,
+    customCanvasShellClasses,
+    nestedBlockShellClasses,
+  };
+}