@fses/workbench-app 0.1.0

package/dist/internal/personal-workbench/lib/workbenchEntryParams.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @fileoverview 工作台 iframe 入口参数解析 - 兼容 hash 路由和静态页面 query 入参。
+ * @author seadon
+ * @created 2026-05-18
+ */
+export interface WorkbenchEntryParamsInput {
+    routeQuery?: Record<string, unknown>;
+    locationPathname?: string;
+    locationSearch?: string;
+    locationHash?: string;
+}
+export interface WorkbenchEntryParams {
+    workspaceId: string;
+    userId: string;
+    tenantId: string;
+    appId: string;
+    roleId: string;
+    mode: string;
+    fdeMode: string;
+    workbenchEditable: string;
+    conversationId: string;
+    resourceId: string;
+    fdeResourceId: string;
+    path: string;
+    fdePath: string;
+    name: string;
+    fdeName: string;
+}
+declare global {
+    interface Window {
+        __BT_WORKBENCH_USER__?: {
+            userId?: string;
+            roleId?: string;
+        };
+        __BT_RUNTIME_IDENTITY__?: Record<string, unknown>;
+        __BT_RUNTIME_CONTEXT__?: Record<string, unknown>;
+    }
+}
+/**
+ * 从 Vue Router query、页面 search、hash query 中解析工作台入口参数。
+ * @param input - 路由和浏览器地址栏参数。
+ * @returns 标准化后的入口参数。
+ */
+export declare function resolveWorkbenchEntryParams(input?: WorkbenchEntryParamsInput): WorkbenchEntryParams;
+/**
+ * 从浏览器当前地址解析工作台入口参数。
+ * @param routeQuery - Vue Router 当前 query 对象。
+ * @returns 标准化后的入口参数。
+ */
+export declare function resolveBrowserWorkbenchEntryParams(routeQuery?: Record<string, unknown>): WorkbenchEntryParams;

package/dist/internal/personal-workbench/lib/workbenchGridstackAdapter.d.ts

@@ -0,0 +1,231 @@
+/**
+ * @fileoverview GridStack 布局适配器 - 提供工作台 V4 外层布局协议与旧布局桥接。
+ * @author seadon
+ * @created 2026-05-23
+ */
+import type { GridStackWidget } from 'gridstack';
+import type { BlockLayout, CustomCanvasData, CustomCanvasNestedBlock, LayoutConfig, MaterializedBlock, WorkbenchGridLayoutNode, WorkbenchLayoutV4, WorkbenchSnapshot } from '@fses/workbench-app/types';
+export declare const WORKBENCH_LAYOUT_V4_VERSION = 4;
+export declare const WORKBENCH_GRIDSTACK_COLUMNS = 100;
+export declare const WORKBENCH_GRIDSTACK_NESTED_COLUMNS = 12;
+export declare const WORKBENCH_GRIDSTACK_ROW_HEIGHT = 8;
+export declare const WORKBENCH_GRIDSTACK_GAP = 6;
+export declare const WORKBENCH_GRIDSTACK_NESTED_GAP = 4;
+export declare const WORKBENCH_NESTED_CONTAINER_CAPABILITY_ID = "card.custom.nestedContainer";
+export declare const WORKBENCH_NESTED_CONTAINER_ROLE = "nested-card-container";
+/**
+ * Normalizes a nested child after it has been promoted onto the top-level GridStack.
+ * @param node - Top-level node emitted by GridStack for the promoted child.
+ * @param previousParentNode - Previous top-level parent node that owned the child.
+ * @returns Top-level layout stripped of nested-only ownership and constraints.
+ */
+export declare function promotedNestedTopLevelLayout(node: WorkbenchGridLayoutNode, previousParentNode: WorkbenchGridLayoutNode | undefined, previousNestedNode: WorkbenchGridLayoutNode | undefined): BlockLayout;
+type CompactImageGridstackHeaderSuccessorGapOptions = {
+    isHeader: (node: WorkbenchGridLayoutNode) => boolean;
+    isSuccessorStrip: (node: WorkbenchGridLayoutNode) => boolean;
+    maxGapRows?: number;
+    targetGapRows?: number;
+};
+/**
+ * Removes large source-screenshot blank bands between a compact image header and its first KPI/list row.
+ * @param nodes - GridStack render nodes in current canvas coordinates.
+ * @param options - Predicates that identify the compact header and the first business strip after it.
+ * @returns Nodes with the successor strip and later top-level rows shifted upward when a large blank band exists.
+ */
+export declare function compactImageGridstackHeaderSuccessorGap(nodes: WorkbenchGridLayoutNode[], options: CompactImageGridstackHeaderSuccessorGapOptions): WorkbenchGridLayoutNode[];
+/**
+ * Repairs source-order image rows before GridStack can push a compacted header below KPI cards.
+ * @param nodes - Normalized V4 nodes.
+ * @param preserveNodeIds - Manual image node ids that must keep user-authored coordinates.
+ * @returns Nodes with later image rows shifted below earlier overlapping rows.
+ */
+export declare function repairImageGridstackSourceOrderOverlaps(nodes: WorkbenchGridLayoutNode[], preserveNodeIds?: ReadonlySet<string>): WorkbenchGridLayoutNode[];
+/**
+ * Recovers collapsed source-bbox image GridStack geometry from normalized display/layoutBasis geometry.
+ * @param sourceTree - GridStack tree derived from source screenshot bboxes.
+ * @param displayTree - GridStack tree derived from normalized display/layoutBasis blocks.
+ * @returns Source tree with collapsed image nodes replaced by display geometry while preserving source row metrics.
+ */
+export declare function recoverCollapsedImageSourceGridstackTreeFromDisplay(sourceTree: WorkbenchLayoutV4, displayTree: WorkbenchLayoutV4 | null | undefined): WorkbenchLayoutV4;
+/**
+ * Converts a legacy block layout into a GridStack V4 node.
+ * @param layout - Legacy block layout.
+ * @param sourceCols - Column count used by the source layout.
+ * @param targetCols - Target GridStack columns.
+ * @param parentId - Optional parent node id.
+ * @returns GridStack layout node.
+ */
+export declare function blockLayoutToGridNode(layout: BlockLayout, sourceCols: number, targetCols?: number, parentId?: string): WorkbenchGridLayoutNode;
+/**
+ * 将 V3 物化区块列表转换为 V4 顶层布局树。
+ * @param blocks - 当前快照中的物化区块
+ * @param layoutConfig - 旧版布局配置
+ * @returns V4 外层布局树
+ */
+export declare function v3BlocksToLayoutV4(blocks: readonly MaterializedBlock[], layoutConfig: LayoutConfig): WorkbenchLayoutV4;
+type NormalizeGridstackLayoutTreeOptions = {
+    fallbackTree?: WorkbenchLayoutV4;
+    missingNodeFallbackTree?: WorkbenchLayoutV4;
+    maxItemRows?: number;
+    repairStaleImageFallback?: boolean;
+    preserveManualImageNodeIds?: ReadonlySet<string>;
+    preserveManualNestedImageParentIds?: ReadonlySet<string>;
+};
+/**
+ * Normalizes a V4 GridStack tree before it is rendered or saved.
+ * @param layoutTree - Persisted or draft V4 layout tree.
+ * @param options - Fallback tree and sanity limits.
+ * @returns Tree migrated to the current integer GridStack basis.
+ */
+export declare function normalizeGridstackLayoutTree(layoutTree: WorkbenchLayoutV4, options?: NormalizeGridstackLayoutTreeOptions): WorkbenchLayoutV4;
+/**
+ * 将 V4 顶层节点导出为旧版布局数组，供现有画布逻辑桥接使用。
+ * @param layoutTree - V4 布局树
+ * @returns 不含嵌套子节点的顶层旧布局
+ */
+/**
+ * Clears persisted static locks before rendering a layout tree in config mode.
+ * @param layoutTree - Candidate V4 layout tree entering an editable GridStack.
+ * @returns Editable tree whose top-level and nested nodes can be moved and resized.
+ */
+export declare function unlockGridstackLayoutTreeForEditing(layoutTree: WorkbenchLayoutV4): WorkbenchLayoutV4;
+export declare function layoutV4ToLegacyTopLevelLayouts(layoutTree: WorkbenchLayoutV4): BlockLayout[];
+/**
+ * 将 V4 布局节点转换为 GridStack widget 配置。
+ * @param node - V4 布局节点
+ * @returns GridStack 可加载的 widget
+ */
+export declare function layoutNodeToGridStackWidget(node: WorkbenchGridLayoutNode): GridStackWidget;
+/**
+ * 读取 GridStack 保存结果并合并回当前 V4 布局树。
+ * @param widgets - GridStack.save(false) 返回的顶层 widget 列表
+ * @param currentTree - 当前 V4 布局树，用于保留嵌套 children
+ * @returns 合并位置后的 V4 布局树
+ */
+type GridStackSaveToLayoutV4Options = {
+    editedWidgetIds?: ReadonlySet<string>;
+};
+export declare function gridStackSaveToLayoutV4(widgets: readonly GridStackWidget[], currentTree: WorkbenchLayoutV4, options?: GridStackSaveToLayoutV4Options): WorkbenchLayoutV4;
+/**
+ * 从现有布局配置生成 GridStack 外层布局配置。
+ * @param current - 当前旧版布局配置
+ * @returns V4 GridStack 布局配置
+ */
+export declare function gridstackLayoutConfigFrom(current: LayoutConfig): LayoutConfig;
+/**
+ * 将 V4 布局树写入快照 visualConfig，并保留原有视觉配置。
+ * @param current - 当前快照视觉配置
+ * @param layoutTree - 待写入的 V4 布局树
+ * @returns 带 layoutTree 的视觉配置
+ */
+export declare function visualConfigWithLayoutTree(current: WorkbenchSnapshot['visualConfig'] | null | undefined, layoutTree: WorkbenchLayoutV4): WorkbenchSnapshot['visualConfig'];
+/**
+ * Checks whether a materialized block is the system nested-card container.
+ * @param block - Candidate materialized block.
+ * @returns True when registry metadata or persisted data marks the block as a nested container.
+ */
+export declare function isNestedCardContainerBlock(block: MaterializedBlock): boolean;
+/**
+ * Removes top-level duplicates for nodes that already have nested ownership.
+ * @param layoutTree - Candidate V4 layout tree.
+ * @returns Layout tree whose child ids appear in only one ownership scope.
+ */
+export declare function normalizeGridstackNestedOwnership(layoutTree: WorkbenchLayoutV4): WorkbenchLayoutV4;
+/**
+ * Checks whether a block data payload is customCanvas data.
+ * @param value - Block data.
+ * @returns True when value has the customCanvas shape.
+ */
+export declare function isCustomCanvasData(value: unknown): value is CustomCanvasData;
+/**
+ * Checks whether a customCanvas block should keep its nested children in the legacy renderer.
+ * @param block - Parent materialized block.
+ * @returns True when nested GridStack editing must be disabled.
+ */
+export declare function shouldLockNestedGrid(block: MaterializedBlock): boolean;
+/**
+ * Checks whether a materialized block can render its nested children as an editable GridStack.
+ * @param block - Candidate materialized block.
+ * @returns True when the block is customCanvas and not locked by visual/layout policy.
+ */
+export declare function isEditableGridContainerBlock(block: MaterializedBlock): boolean;
+/**
+ * Converts a customCanvas nested preview record into a renderer-ready materialized block.
+ * @param nestedBlock - Nested preview record saved inside parent customCanvas data.
+ * @param parentBlock - Parent customCanvas materialized block.
+ * @returns Materialized child block suitable for WorkbenchBlockRenderer.
+ */
+export declare function nestedBlockToMaterializedBlock(nestedBlock: CustomCanvasNestedBlock, parentBlock: MaterializedBlock): MaterializedBlock;
+type NestedConversionOptions = {
+    parentId?: string;
+    layout?: BlockLayout | WorkbenchGridLayoutNode;
+};
+/**
+ * Converts a top-level workbench card into a customCanvas nested block without losing runtime metadata.
+ * @param block - Top-level materialized card being moved into a parent container.
+ * @param options - Parent-local layout and ownership options.
+ * @returns Nested block payload suitable for parent customCanvas data.
+ */
+export declare function materializedBlockToNestedBlock(block: MaterializedBlock, options?: NestedConversionOptions): CustomCanvasNestedBlock;
+/**
+ * Restores a nested customCanvas child into a top-level materialized block.
+ * @param nestedBlock - Nested child payload being promoted to the canvas.
+ * @param parentBlock - Parent customCanvas card that previously owned the child.
+ * @param options - Top-level layout override.
+ * @returns Materialized card that can live in snapshot.blocks.
+ */
+export declare function nestedBlockToTopLevelBlock(nestedBlock: CustomCanvasNestedBlock, parentBlock: MaterializedBlock, options?: NestedConversionOptions): MaterializedBlock;
+type RepairOverlappingImageNestedGridChildrenOptions = {
+    parentRows?: number;
+};
+/**
+ * Repairs image-composed nested children that the vision model projected onto the same parent-local slot.
+ * @param children - Parent-local nested children from customCanvas nestedBlocks.
+ * @param options - Optional parent row budget used to size the repaired grid.
+ * @returns A readable grid when severe sibling overlap exists; otherwise cloned original children.
+ */
+export declare function repairOverlappingImageNestedGridChildren(children: readonly WorkbenchGridLayoutNode[], options?: RepairOverlappingImageNestedGridChildrenOptions): WorkbenchGridLayoutNode[];
+type CompactSparseImageNestedGridChildrenOptions = {
+    parentRows?: number;
+};
+/**
+ * Compacts sparse image nested children into an even matrix while preserving child ids and bindings.
+ * @param children - Parent-local nested children.
+ * @param options - Optional parent row span used to detect sparse shells.
+ * @returns Children arranged as two or three compact columns when the source layout is too sparse.
+ */
+export declare function compactSparseImageNestedGridChildren(children: readonly WorkbenchGridLayoutNode[], options?: CompactSparseImageNestedGridChildrenOptions): WorkbenchGridLayoutNode[];
+/**
+ * Returns the compact parent row span required by image nested child cards.
+ * @param children - Parent-local nested children after display compaction.
+ * @returns Parent row span including card chrome.
+ */
+export declare function imageNestedGridCompactParentRows(children: readonly WorkbenchGridLayoutNode[]): number;
+/**
+ * Returns whether persisted image nested children came from a stale edit layout.
+ * @param existingChildren - Children currently carried by persisted or draft V4 layout.
+ * @param fallbackChildren - Children derived from the current image nested payload.
+ * @returns True when edit mode should seed from fallback children instead of persisted geometry.
+ */
+export declare function shouldReplaceStaleImageNestedChildren(existingChildren: readonly WorkbenchGridLayoutNode[] | undefined, fallbackChildren: readonly WorkbenchGridLayoutNode[]): boolean;
+/**
+ * Converts a customCanvas block's nestedBlocks into parent-local V4 children.
+ * @param block - Parent materialized block.
+ * @returns Children using the nested 12-column grid.
+ */
+export declare function customCanvasNestedBlocksToChildren(block: MaterializedBlock): WorkbenchGridLayoutNode[];
+/**
+ * Rebuilds customCanvas nestedBlocks from V4 children while preserving nested content payloads when possible.
+ * @param parentBlock - Parent materialized block.
+ * @param children - Children that now belong to this parent.
+ * @returns Nested block records with updated parent-local layouts.
+ */
+export declare function childrenToCustomCanvasNestedBlocks(parentBlock: MaterializedBlock, children: readonly WorkbenchGridLayoutNode[], nestedPayloadById?: ReadonlyMap<string, CustomCanvasNestedBlock>): CustomCanvasNestedBlock[];
+/**
+ * Merges top-level and nested V4 positions back into materialized blocks.
+ * @param blocks - Current materialized blocks.
+ * @param layoutTree - V4 layout tree.
+ * @returns Blocks with top-level layout and nestedBlocks updated.
+ */
+export declare function mergeLayoutV4IntoBlocks(blocks: readonly MaterializedBlock[], layoutTree: WorkbenchLayoutV4): MaterializedBlock[];
+export {};

package/dist/internal/personal-workbench/lib/workbenchGridstackSaveLayout.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview GridStack 布局保存选择 - 统一决定配置保存时使用的布局树来源
+ * @author seadon
+ * @created 2026-07-03
+ */
+import type { WorkbenchLayoutV4 } from '@fses/workbench-app/types';
+export type GridstackLayoutTreeForSaveInput = {
+    programmaticLayoutTree: WorkbenchLayoutV4 | null;
+    draftUserEdited: boolean;
+    latestRenderedLayoutTree: () => WorkbenchLayoutV4 | null;
+    draftLayoutTree: WorkbenchLayoutV4 | null;
+    activeLayoutTree: WorkbenchLayoutV4;
+};
+export type GridstackAutoArrangeSaveState = {
+    draftLayoutTree: WorkbenchLayoutV4;
+    programmaticLayoutTreeForSave: WorkbenchLayoutV4;
+    draftUserEdited: true;
+};
+export type GridstackDeleteSaveState = GridstackAutoArrangeSaveState;
+export type GridstackUserEditSaveState = {
+    draftLayoutTree: WorkbenchLayoutV4;
+    programmaticLayoutTreeForSave: null;
+    draftUserEdited: true;
+};
+/**
+ * 选择配置保存时应持久化的 GridStack 布局树。
+ * @param input - 保存布局候选来源。
+ * @returns 本次保存应使用的 V4 布局树，或无可用布局时返回 null。
+ */
+export declare function resolveGridstackLayoutTreeForSave(input: GridstackLayoutTreeForSaveInput): WorkbenchLayoutV4 | null;
+/**
+ * 生成自动排列后的 GridStack 保存状态。
+ * @param arrangedLayoutTree - 自动排列产生的目标布局树。
+ * @returns 同时写入草稿和程序化保存槽的状态。
+ */
+export declare function resolveGridstackAutoArrangeSaveState(arrangedLayoutTree: WorkbenchLayoutV4): GridstackAutoArrangeSaveState;
+/**
+ * 生成删除卡片压缩后的 GridStack 保存状态。
+ * @param compactedLayoutTree - 删除卡片后压缩产生的目标布局树。
+ * @returns 同时写入草稿和程序化保存槽的状态。
+ */
+export declare function resolveGridstackDeleteSaveState(compactedLayoutTree: WorkbenchLayoutV4): GridstackDeleteSaveState;
+/**
+ * 生成用户直接拖拽/缩放后的 GridStack 保存状态。
+ * @param editedLayoutTree - 用户交互产生的最新布局树。
+ * @returns 清空程序化保存槽后的用户编辑状态。
+ */
+export declare function resolveGridstackUserEditSaveState(editedLayoutTree: WorkbenchLayoutV4): GridstackUserEditSaveState;

package/dist/internal/personal-workbench/lib/workbenchImageCanvasSizing.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview Image-composed workbench canvas sizing - resolves responsive display and stable edit widths.
+ * @author seadon
+ * @created 2026-06-09
+ */
+interface ImageCanvasWidthOptions {
+    availableWidth: number;
+    sourceContentWidth: number;
+    maxWidth: number;
+    configMode: boolean;
+}
+interface ImageCanvasHeightOptions {
+    layoutHeight: number;
+    sourceFrameHeight?: number;
+    sourceScale?: number;
+    renderedContentHeight?: number;
+    fallbackHeight?: number;
+    configMode: boolean;
+    sourceBoxSafetyFallbackActive: boolean;
+}
+interface ImageGridstackCanvasMinHeightOptions {
+    requestedMinHeight: number;
+    renderedLayoutBottom: number;
+    configMode: boolean;
+    preserveSourceMinHeight: boolean;
+}
+/**
+ * Resolves image-composed board width for responsive display while preserving edit-mode source width.
+ * @param options - Available viewport, source frame, and edit-mode sizing inputs.
+ * @returns Board width in CSS pixels.
+ */
+export declare function resolveImageComposeCanvasWidth(options: ImageCanvasWidthOptions): number;
+/**
+ * Resolves image-composed board height without keeping stale full-source blank space in display mode.
+ * @param options - Layout, source-frame, and safety-fallback sizing inputs.
+ * @returns Board height in CSS pixels.
+ */
+export declare function resolveImageComposeCanvasHeight(options: ImageCanvasHeightOptions): number;
+/**
+ * Resolves the final GridStack canvas min-height for image-composed dashboards.
+ * @param options - Requested parent min-height, rendered card bottom, and mode flags.
+ * @returns GridStack canvas min-height in CSS pixels.
+ */
+export declare function resolveImageComposeGridstackCanvasMinHeight(options: ImageGridstackCanvasMinHeightOptions): number;
+export {};

package/dist/internal/personal-workbench/lib/workbenchImageComposeEntry.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @fileoverview Workbench image compose entry helpers - normalizes AI chat image upload payloads for V2 compose.
+ * @author seadon
+ * @created 2026-05-12
+ */
+export declare const defaultWorkbenchImageComposePrompt = "\u8BF7\u8BC6\u522B\u622A\u56FE\u5E76\u751F\u6210 V2 \u5DE5\u4F5C\u53F0\u5361\u7247";
+export interface WorkbenchImageUploadEntryPayload {
+    base64: string;
+    file?: File;
+    fileName?: string;
+    messageId?: string;
+    mimeType: string;
+    text?: string;
+}
+export interface WorkbenchImageComposeV2Payload {
+    content: string;
+    image: {
+        base64: string;
+        mimeType: string;
+    };
+    imageContext?: {
+        fileName?: string;
+        originalWidth?: number;
+        originalHeight?: number;
+        optimizedWidth?: number;
+        optimizedHeight?: number;
+    };
+    messageId?: string;
+}
+export type WorkbenchImageComposeOptimizer = (image: {
+    base64: string;
+    mimeType: string;
+}) => Promise<{
+    base64: string;
+    mimeType: string;
+    originalWidth?: number;
+    originalHeight?: number;
+    optimizedWidth?: number;
+    optimizedHeight?: number;
+}>;
+/**
+ * Builds the V2 compose request shape from the AI chat image-upload event payload.
+ * @param payload - Image payload emitted by the shared AI chat component.
+ * @returns Normalized runtime payload for composeImageV2.
+ */
+export declare function buildWorkbenchImageComposeV2Payload(payload: WorkbenchImageUploadEntryPayload): WorkbenchImageComposeV2Payload;
+/**
+ * Builds a V2 compose payload and lets the workbench page optimize large screenshots before model upload.
+ * @param payload - Image payload emitted by the shared AI chat component.
+ * @param optimizer - Optional image optimizer for browser canvas compression.
+ * @returns Runtime payload for composeImageV2.
+ */
+export declare function buildOptimizedWorkbenchImageComposeV2Payload(payload: WorkbenchImageUploadEntryPayload, optimizer?: WorkbenchImageComposeOptimizer): Promise<WorkbenchImageComposeV2Payload>;

package/dist/internal/personal-workbench/lib/workbenchImageGridstackRowRecovery.d.ts

@@ -0,0 +1,93 @@
+/**
+ * @fileoverview 图生卡 GridStack 行恢复工具 - 归并同源截图行并生成整齐的 24 列布局
+ * @author seadon
+ * @created 2026-06-23
+ */
+import type { WorkbenchGridLayoutNode } from '@fses/workbench-app/types';
+/**
+ * Checks whether a sparse metric row is the tail of the previous dense KPI row.
+ * @param previousRow - Dense upper metric row.
+ * @param currentRow - Candidate lower sparse metric row.
+ * @returns True when the rows should render as one responsive KPI strip.
+ */
+export declare function shouldMergeSplitImageMetricSummaryGridstackRow(previousRow: readonly WorkbenchGridLayoutNode[], currentRow: readonly WorkbenchGridLayoutNode[]): boolean;
+/**
+ * Merges split KPI tail rows before render-time width normalization.
+ * @param rows - Visual metric rows ordered from top to bottom.
+ * @returns Rows with dense KPI tails folded into the preceding row.
+ */
+export declare function mergeSplitImageMetricSummaryGridstackRows(rows: readonly WorkbenchGridLayoutNode[][]): WorkbenchGridLayoutNode[][];
+export type ImageLayoutBasisGridstackRowBasis = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    baseCols?: number;
+};
+export type ImageLayoutBasisGridstackRowCandidate = {
+    basis: ImageLayoutBasisGridstackRowBasis;
+};
+export type ImageLayoutBasisGridstackRowPlacement = {
+    x: number;
+    w: number;
+};
+export type ImageSparseCustomCanvasParentRowsMetrics = {
+    childCount: number;
+    totalChildRows: number;
+    sourceRows: number;
+    paddingRows: number;
+    preserveSourceRows?: boolean;
+};
+export type ImageGridstackParentRowsForNestedChildrenOptions = {
+    minRows?: number;
+    paddingRows?: number;
+};
+/**
+ * Computes the parent rows required by nested image cards.
+ * @param children - Parent-local nested GridStack children.
+ * @param options - Minimum parent rows and chrome padding rows.
+ * @returns Parent row span that covers the nested child bounding box.
+ */
+export declare function imageGridstackParentRowsForNestedChildren(children: readonly WorkbenchGridLayoutNode[], options?: ImageGridstackParentRowsForNestedChildrenOptions): number;
+/**
+ * Computes readable rows for sparse image customCanvas parents.
+ * @param metrics - Child count, child row usage, source bbox rows, and chrome padding.
+ * @returns Parent rows that compact whitespace without clipping nested child cards.
+ */
+export declare function imageSparseCustomCanvasParentRowsFromMetrics(metrics: ImageSparseCustomCanvasParentRowsMetrics): number;
+/**
+ * 判断 layoutBasis 候选是否属于当前截图源行。
+ * @param row - 当前已归并的源行候选。
+ * @param entry - 待追加候选。
+ * @returns 同源且宽度预算可容纳时返回 true。
+ */
+export declare function canAppendImageLayoutBasisGridstackRow<T extends ImageLayoutBasisGridstackRowCandidate>(row: T[], entry: T): boolean;
+/**
+ * 为同源截图行计算 24 列 GridStack 位置，密集多卡行按整行均分。
+ * @param row - 已归并的同源行候选。
+ * @returns 每个候选对应的 x/w 位置。
+ */
+export declare function imageLayoutBasisGridstackRowPlacements<T extends ImageLayoutBasisGridstackRowCandidate>(row: T[]): ImageLayoutBasisGridstackRowPlacement[];
+/**
+ * 将行内位置写回 GridStack 节点，并保持原节点其它交互属性。
+ * @param row - 同源候选行。
+ * @param rowHeight - 该行统一高度。
+ * @param cursorY - 当前输出行 y 坐标。
+ * @returns 恢复后的 GridStack 节点。
+ */
+export declare function recoverImageLayoutBasisGridstackRowNodes<T extends ImageLayoutBasisGridstackRowCandidate & {
+    node: WorkbenchGridLayoutNode;
+}>(row: T[], rowHeight: number, cursorY: number): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    parentId?: string;
+    children?: WorkbenchGridLayoutNode[];
+    i: string;
+    minW?: number;
+    minH?: number;
+    maxW?: number;
+    maxH?: number;
+    static?: boolean;
+}[];