@hankchen/canvas-editor 0.7.1 → 0.9.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { LayerBox, Canvas, TextLayoutPolicies, Layer, LayerType, TableLayer, RenderBackend, Padding, HorizontalAlign, VerticalAlign, Anchor, TableRowLayer, TableCellLayer, TableRowTemplateLayer } from '@hankchen/canvas';
-export { ANCHORS, Anchor, Border, BorderSide, Canvas, HORIZONTAL_ALIGNS, HorizontalAlign, LAYER_TYPES, Layer, LayerBox, LayerType, Padding, TableCellLayer, TableLayer, TableRowLayer, TextLayer, VERTICAL_ALIGNS, VerticalAlign } from '@hankchen/canvas';
+import { LayerBox, Canvas, TextLayoutPolicies, Layer, LayerType, TableLayer, RenderBackend, Padding, HorizontalAlign, VerticalAlign, CanvasBackground, Anchor, TableRowLayer, TableCellLayer, TableRowTemplateLayer } from '@hankchen/canvas';
+export { ANCHORS, Anchor, Border, BorderSide, Canvas, CanvasBackground, HORIZONTAL_ALIGNS, HorizontalAlign, LAYER_TYPES, Layer, LayerBox, LayerType, Padding, TableCellLayer, TableLayer, TableRowLayer, TextLayer, VERTICAL_ALIGNS, VerticalAlign } from '@hankchen/canvas';
 import { Draft, Patch } from 'immer';
 export { canvasFontCssFamily } from '@hankchen/canvas-browser-renderer';
 
@@ -1471,6 +1471,11 @@ interface TextEditLayout {
  * 越过死区才插入副本，死区内抬手退化为普通点选。
  */
 declare const ALT_DRAG_DEAD_ZONE_SCREEN_PX = 4;
+/**
+ * 底图转换不可行的原因（canvas-background 工单 05，右键菜单置灰 title 分轨；
+ * null = 可转换）。locked 只由会话查询口产出（ui 分支态，纯函数管不着）。
+ */
+type BaseImageConversionBlock = 'not-head-root' | 'not-image' | 'not-covering' | 'hidden' | 'expression-marked' | 'no-image-src' | 'locked';
 interface EditorSessionOptions {
     scheduleFrame: FrameScheduler;
     /** 缩放范围（可配置，缺省 5%–800%） */
@@ -2090,8 +2095,38 @@ declare class EditorSession {
      * commitTextEdit 先清会话再落库，天然不复入接管。
      */
     private takeoverDraftIfNeeded;
-    /** 更新画布级字段（未选中图层时面板的宽/高写入口）；键由类型收窄为 width/height */
+    /**
+     * 更新画布级字段（未选中图层时面板的写入口）：width/height 数值；background
+     * 整对象一步事务（canvas-background 工单 04）——面板各分量提交折算回整对象，
+     * 归一经 normalizeCanvasBackground（空串分量归 null、两分量皆空 = 清背景 null，
+     * 镜像解码语义；条件写键归 encode）；结构相同的整对象空转（immer 引义换新
+     * 不产生历史步，数值键的零变更语义同门）。
+     */
     updateCanvasProp(key: 'width' | 'height', value: number, options?: TransactOptions): void;
+    updateCanvasProp(key: 'background', value: CanvasBackground | null, options?: TransactOptions): void;
+    /**
+     * 底图转换查询（canvas-background 工单 05，右键菜单门态唯一权威）：路径处
+     * 图层距「转为画布背景」的阻塞原因，null = 可转换。文档面条件见
+     * baseImageConversionBlockInDoc（豁免同门），此处叠加锁定子树（删除面同门
+     * ——转换含删层，锁定层不出路）。无文档/无路径归 not-head-root。
+     */
+    baseImageConversionBlock(path: LayerPath | null): BaseImageConversionBlock | null;
+    /**
+     * 底图右键命中解析（canvas-background 工单 05，豁免的命中缝）：命中豁免使
+     * 头根覆盖图片层的自身盒退出正常命中面，右键菜单却要能选中它（「转为画布
+     * 背景」的入口前提）——宿主在命中未中时按此兜底解析转换候选，选择落地由
+     * 宿主决定（纯查询零副作用）。预览视图上解析（hitTest 同门）并映射回文档
+     * 身份；左键点选路径不经过这里，豁免行为零改动。
+     */
+    baseImageAt(sceneX: number, sceneY: number): LayerPath | null;
+    /**
+     * 转为画布背景（canvas-background 工单 05，存量底图出路）：选中头根图片层
+     * 的图片引用写入画布背景 image 分量 + 删除该图层，单事务一步历史、整体撤销
+     * （背景与图层都还原）。条件经 baseImageConversionBlock 同一门（违例静默
+     * 空转，无历史步）；既有背景色保留（只写 image 分量——先色后图语义不破，
+     * 已有背景图被垫底层的引用接管，同一门下二者本就是同一视觉位）。
+     */
+    convertSelectionToBackground(): boolean;
     /**
      * 注入数据源 schema 声明（载荷形态，D1 钉定：声明即 compile(canvas, dataset)
      * 收到的 data 载荷形状，根上下文候选 = 载荷顶层键）。声明经
@@ -2441,6 +2476,15 @@ interface HitTestOptions {
      */
     readonly lockedPaths?: readonly LayerPath[];
 }
+/**
+ * 全幅判定：底层自身盒 ⊇ 画布矩形（负溢出照算），与视口/缩放无关。
+ * spec「渲染与交互」2026-09-27 拍板的底图豁免（Fabric backgroundImage 不入命中图、
+ * Konva listening(false) 同构）：只作用于数组头根层——「数组按 priority 降序、
+ * 头先画垫底」的叠放不变量决定了它是唯一的视觉垫底层。
+ * 双消费者（canvas-background 工单 05）：命中豁免与「转为画布背景」转换门同门——
+ * 判定一处收口，两处语义永不漂移。
+ */
+declare function coversCanvas(box: LayerBox, canvasWidth: number, canvasHeight: number): boolean;
 /**
  * 场景坐标命中：返回视觉最上被中图层的路径（未中返回 null）。
  * 隐藏根层（layer-panel-ux 工单 10）与锁定根层（canvas-web-layer-lock 工单 01）
@@ -2448,6 +2492,23 @@ interface HitTestOptions {
  * 被锁定即不可点选，命中穿透其下方的层。
  */
 declare function hitTest(canvas: Canvas, sceneX: number, sceneY: number, policies?: TextLayoutPolicies, options?: HitTestOptions): LayerPath | null;
+/**
+ * 头根层盒解析（底图判定共用来料）：数组头缺失返回 null。命中豁免与「转为画布
+ * 背景」转换门共用此唯一进料（同层、同参盒解析），两处几何语义永不漂移
+ * （canvas-background 工单 05）。
+ */
+declare function headRootBox(canvas: Canvas, policies?: TextLayoutPolicies): {
+    layer: Layer;
+    box: LayerBox;
+} | null;
+/**
+ * 底图右键命中解析（canvas-background 工单 05）：豁免使头根覆盖图片层的自身盒
+ * 退出正常命中面，右键菜单却要能选中它（「转为画布背景」的入口缝）——命中未中
+ * 时按此解析兜底。只解析转换候选：数组头 + 图片层 + 覆盖画布（coversCanvas
+ * 同门）+ 可见 + 未锁定；表达式标记与无图引用照常解析（菜单要能选中它置灰说明）。
+ * 纯查询零副作用——选择落地由调用方决定。
+ */
+declare function baseImageCandidateAt(canvas: Canvas, sceneX: number, sceneY: number, policies?: TextLayoutPolicies, options?: HitTestOptions): LayerPath | null;
 
 /**
  * 画拉建层橡皮筋求位几何（drag-create 工单 01，术语见根 CONTEXT.md「画拉建层」
@@ -3144,6 +3205,16 @@ declare function enumerateExpressionCandidates(schema: ExpressionSchemaNode | nu
  * 给根 schema 表根起点，故独立落件不改 expressionContext）；任一层解析不出
  * （rowsPath 无 items 声明/漂移/途经非表）→ null 降级无候选。
  *
+ * 点选器剪枝枚举件（rows-path-picker 工单 01，spec D5/D3）：级联点选器每层的
+ * 候选条目——在补全枚举语义上加剪枝谓词 leadsToArray，候选面收敛至「通往行数组
+ * 的路径」：标量子段不出现；对象子段仅当子树内沿 properties 链至少含一个可达
+ * 数组才出现；数组子段 = 终点条目（isArray 标记），不透传 items（数组套数组的
+ * 内层不可达）。无 partial 概念（纯点选无输入期），前缀 = 已积累点路径、逐段
+ * 全量已消费、尾段取子层；空层/漂移/畸形前缀一律返回空数组（空态呈现归 vue
+ * 面）。起点判别不在此重复造：调用方经 resolveRowsPathStartSchema 得起点后再
+ * 进本件。元信息同表达式补全先例（D8）：description/title 两字段分离透传，展示
+ * 回落 description ?? title 归呈现层。
+ *
  * 全模块纯函数、零 DOM；层内依赖仅 expressionSchema / expressionCandidates
  * （候选类型面）/ layerPath。
  */
@@ -3166,6 +3237,31 @@ interface RowsPathCandidateResult {
  * 阻）；枚举落点为对象层 → 该层全量合法子项。
  */
 declare function enumerateRowsPathCandidates(startSchema: ExpressionSchemaNode | null, input: string): RowsPathCandidateResult | null;
+/**
+ * 一条 rowsPath 点选器条目（rows-path-picker 工单 01）：级联一层的可点项。
+ * 与 RowsPathCandidate 的分叉：无 partial/徽标面，换显式数组终点标记——点选器
+ * 按 isArray 分流「点选提交 / 只可下钻」，不再经「带尾点探一层」推断。
+ */
+interface RowsPathPickerEntry {
+    /** 提交/下钻的完整点路径（起点相对；点选器 v-model 面就是它） */
+    path: string;
+    /** 本段名（无元信息时的显示回落） */
+    segment: string;
+    /** 显示名注解（D8 两字段分离透传；展示回落 description ?? title 归呈现层） */
+    title?: string;
+    /** 说明（未声明为 undefined） */
+    description?: string;
+    /** 数组终点标记：true = 行数组终点（点选即提交）；false = 对象中间站（只可下钻） */
+    isArray: boolean;
+}
+/**
+ * 枚举点选器某层的候选条目（rows-path-picker 工单 01）：prefix 为已积累点路径，
+ * 逐段全量已消费、尾段取子层（'' = 起点层）；下钻域规则走 descendToLayer，每层
+ * 条目经 leadsToArray 剪枝至「通往行数组的路径」。起点 schema null / 前缀漂移
+ * （段缺失/标量落点）/ 畸形（双点/尾点/头点）/ 数组落点（数组不展开）→ 空数组，
+ * 全程不抛错——空态呈现归 vue 面（spec D6）。
+ */
+declare function enumerateRowsPathPickerEntries(startSchema: ExpressionSchemaNode | null, prefix: string): readonly RowsPathPickerEntry[];
 /**
  * rowsPath 编辑起点的三分流判别（D3）：无 template 祖先 → 载荷根 schema（根层
  * 表；建表表单恒根起点同款）；有 template 祖先 → 沿选中路径每个 template 段行
@@ -3221,4 +3317,4 @@ declare function memoizeTextPolicies(policies?: TextLayoutPolicies, options?: Me
  */
 declare const PACKAGE_NAME: "@hankchen/canvas-editor";
 
-export { ALIGN_CORNER_MARGIN_PX, ALT_DRAG_DEAD_ZONE_SCREEN_PX, ARM_CREATE_LAYER_TYPES, type AlignBoxGeometry, type AlignToCanvasMode, type AlignToCanvasOptions, type ArmCreateShortcutAction, CREATE_DEAD_ZONE_SCREEN_PX, type CanvasEditorState, type CreateGesture, type CreateRectResult, DATE_FORMAT_SUGGESTIONS, DEFAULT_EDITOR_SHORTCUTS, DEFAULT_ZOOM_BOUNDS, type DataSourceSchemaRejection, type DeletedLayerRef, type DocRecipe, type DragGesture, EDITOR_STATE_SCHEMA_VERSION, EXPRESSION_FUNCTIONS, type EditorChange, type EditorPrefsState, EditorSession, type EditorSessionOptions, type EditorShortcutAction, type EditorShortcutBinding, type EditorShortcutGroup, type EditorShortcutInput, EditorStore, type EditorUi, type ExpressionCallArg, type ExpressionCallErrorKind, type ExpressionCallParse, type ExpressionCallSlotContext, type ExpressionCandidate, type ExpressionCandidateQuery, type ExpressionCandidateResult, type ExpressionContextKind, type ExpressionErrorRange, type ExpressionFormatSuggestion, type ExpressionFragmentDiagnostic, type ExpressionFragmentErrorKind, type ExpressionFunctionMeta, type ExpressionPathHead, type ExpressionPathParse, type ExpressionScan, type ExpressionScanFragment, type ExpressionScanLiteral, type ExpressionScanOpen, type ExpressionScanPart, type ExpressionSchemaChildEntry, type ExpressionSchemaChildView, type ExpressionSchemaDiagnostic, type ExpressionSchemaDiagnosticCode, type ExpressionSchemaNode, type ExpressionSchemaParse, type ExpressionSchemaRejectReason, type ExpressionSyntaxError, type FindSession, type FindTextHit, FontCatalog, type FontCatalogEntry, type FrameScheduler, type Guide, type GuideOrientation, type HistoryStep, type HitTestOptions, type InvalidateTarget, type LayerOutlineNode, type LayerOutlineRole, type LayerPath, MAX_HISTORY_STEPS, type MemoTextPoliciesOptions, type MovedSubtreeRef, NUMBER_FUNCTION_SUGGESTIONS, type NextTextStyle, type OverlayPaintArgs, type OverlayPainter, PACKAGE_NAME, PAN_TO_BOX_MARGIN_PX, PASTE_OFFSET_PX, PHP_TRIM_CHARS, type Point, type ProportionalDrivingAxis, RATIO_PRESETS, RESIZE_HANDLES, RESIZE_HANDLE_HIT_PX, RESIZE_MIN_SIZE_PX, type RatioPreset, type RatioPresetId, type Rect, type ResizeAxes, type ResizeBoxGeometry, type ResizeBoxResult, type ResizeHandle, type ResourceStatus, type ResourceStatusMap, type RowsPathCandidate, type RowsPathCandidateResult, SNAP_THRESHOLD_SCREEN_PX, STYLE_FIELD_KEYS_BY_TYPE, type ShortcutCombo, type Size, type SnapAxis, type SnapAxisSource, type SnapBoxGeometry, type SnapPoints, type SnapResolution, type StyleSnapshot, TEXT_PRESETS, type TextEditLayout, type TextEditingSession, type TextPreset, type TextPresetId, type TransactOptions, type UploadFile, type UploadHandler, UploadHandlerMissingError, type UploadImagePlacement, type Viewport, WHEEL_ZOOM_STEP, type WheelInput, type WheelIntent, type ZoomBounds, addRootLayerInDraft, addTableCellInDraft, addTableRowInDraft, addTemplateCellInDraft, alignToCanvasTarget, applyStyleFieldsInDraft, buildLayerOutline, canCopyLayerAt, canonicalizeTableSyncInDraft, captureStyleSnapshot, clampZoom, classifyEditorShortcut, classifyWheel, cloneLayerSubtree, convertTableToRowsInDraft, convertTableToTemplateInDraft, createDefaultLayer, createRubberBandRect, createTemplateTable, defaultNextTextStyle, defaultSizeForRatio, deleteLayerInDraft, enumerateExpressionCandidates, enumerateRowsPathCandidates, expressionCallSlotAtEnd, expressionDiagnostics, expressionFragmentAtCursor, findPresetEntry, fitRect, fitViewport, growRowToCellInDraft, handleResizesHeight, handleResizesWidth, hitTest, insertRootLayerAdjacentInDraft, insertRootLayerInDraft, isCallFragment, isImageContentUndrawn, isLayerPath, isLockedPath, isRootLayerPath, isRootPasteableType, isTemplateSubtreePath, layerBoxByPath, memoizeTextPolicies, moveGuard, moveRootLayerInDraft, moveTableCellInDraft, moveTableCellToRowInDraft, moveTableRowInDraft, moveTableRowToTableInDraft, nextZoomByWheel, normalizeExpressionSchemaSource, panBy, panToBox, parseExpressionCall, parseExpressionPath, parseExpressionSchema, pastePosition, pathStartsWith, pathsEqual, phpTrim, pickNextTextStylePatch, prepareRootPaste, proportionalDrivingAxis, ratioValue, readSpecField, remapPathAfterSplice, replaceHitsInDraft, resizableAxesAt, resizeBox, resizeBoxProportional, resizeHandleAt, resizeHandlePoint, resizeHandlesAt, resizeProportionalSnapPoints, resizeSnapPoints, resolveLayer, resolveRowSchema, resolveRowsPathStartSchema, resolveSnap, resolveSnapPoints, resourcePathDiagnostics, rootLayerOf, scanExpressionFragments, scanTextMatches, sceneToScreen, schemaChildEntries, schemaNodeAtPath, screenToScene, selectionParentPath, setCellAutoHeightInDraft, snapAxesFromBoxes, snapThresholdScene, snapViewportToPhysicalPixels, syncContentIntoCellInDraft, syncRowWidthInDraft, uploadDisplayName, visibleRootBoxes, writeSpecField, zoomAtPoint };
+export { ALIGN_CORNER_MARGIN_PX, ALT_DRAG_DEAD_ZONE_SCREEN_PX, ARM_CREATE_LAYER_TYPES, type AlignBoxGeometry, type AlignToCanvasMode, type AlignToCanvasOptions, type ArmCreateShortcutAction, type BaseImageConversionBlock, CREATE_DEAD_ZONE_SCREEN_PX, type CanvasEditorState, type CreateGesture, type CreateRectResult, DATE_FORMAT_SUGGESTIONS, DEFAULT_EDITOR_SHORTCUTS, DEFAULT_ZOOM_BOUNDS, type DataSourceSchemaRejection, type DeletedLayerRef, type DocRecipe, type DragGesture, EDITOR_STATE_SCHEMA_VERSION, EXPRESSION_FUNCTIONS, type EditorChange, type EditorPrefsState, EditorSession, type EditorSessionOptions, type EditorShortcutAction, type EditorShortcutBinding, type EditorShortcutGroup, type EditorShortcutInput, EditorStore, type EditorUi, type ExpressionCallArg, type ExpressionCallErrorKind, type ExpressionCallParse, type ExpressionCallSlotContext, type ExpressionCandidate, type ExpressionCandidateQuery, type ExpressionCandidateResult, type ExpressionContextKind, type ExpressionErrorRange, type ExpressionFormatSuggestion, type ExpressionFragmentDiagnostic, type ExpressionFragmentErrorKind, type ExpressionFunctionMeta, type ExpressionPathHead, type ExpressionPathParse, type ExpressionScan, type ExpressionScanFragment, type ExpressionScanLiteral, type ExpressionScanOpen, type ExpressionScanPart, type ExpressionSchemaChildEntry, type ExpressionSchemaChildView, type ExpressionSchemaDiagnostic, type ExpressionSchemaDiagnosticCode, type ExpressionSchemaNode, type ExpressionSchemaParse, type ExpressionSchemaRejectReason, type ExpressionSyntaxError, type FindSession, type FindTextHit, FontCatalog, type FontCatalogEntry, type FrameScheduler, type Guide, type GuideOrientation, type HistoryStep, type HitTestOptions, type InvalidateTarget, type LayerOutlineNode, type LayerOutlineRole, type LayerPath, MAX_HISTORY_STEPS, type MemoTextPoliciesOptions, type MovedSubtreeRef, NUMBER_FUNCTION_SUGGESTIONS, type NextTextStyle, type OverlayPaintArgs, type OverlayPainter, PACKAGE_NAME, PAN_TO_BOX_MARGIN_PX, PASTE_OFFSET_PX, PHP_TRIM_CHARS, type Point, type ProportionalDrivingAxis, RATIO_PRESETS, RESIZE_HANDLES, RESIZE_HANDLE_HIT_PX, RESIZE_MIN_SIZE_PX, type RatioPreset, type RatioPresetId, type Rect, type ResizeAxes, type ResizeBoxGeometry, type ResizeBoxResult, type ResizeHandle, type ResourceStatus, type ResourceStatusMap, type RowsPathCandidate, type RowsPathCandidateResult, type RowsPathPickerEntry, SNAP_THRESHOLD_SCREEN_PX, STYLE_FIELD_KEYS_BY_TYPE, type ShortcutCombo, type Size, type SnapAxis, type SnapAxisSource, type SnapBoxGeometry, type SnapPoints, type SnapResolution, type StyleSnapshot, TEXT_PRESETS, type TextEditLayout, type TextEditingSession, type TextPreset, type TextPresetId, type TransactOptions, type UploadFile, type UploadHandler, UploadHandlerMissingError, type UploadImagePlacement, type Viewport, WHEEL_ZOOM_STEP, type WheelInput, type WheelIntent, type ZoomBounds, addRootLayerInDraft, addTableCellInDraft, addTableRowInDraft, addTemplateCellInDraft, alignToCanvasTarget, applyStyleFieldsInDraft, baseImageCandidateAt, buildLayerOutline, canCopyLayerAt, canonicalizeTableSyncInDraft, captureStyleSnapshot, clampZoom, classifyEditorShortcut, classifyWheel, cloneLayerSubtree, convertTableToRowsInDraft, convertTableToTemplateInDraft, coversCanvas, createDefaultLayer, createRubberBandRect, createTemplateTable, defaultNextTextStyle, defaultSizeForRatio, deleteLayerInDraft, enumerateExpressionCandidates, enumerateRowsPathCandidates, enumerateRowsPathPickerEntries, expressionCallSlotAtEnd, expressionDiagnostics, expressionFragmentAtCursor, findPresetEntry, fitRect, fitViewport, growRowToCellInDraft, handleResizesHeight, handleResizesWidth, headRootBox, hitTest, insertRootLayerAdjacentInDraft, insertRootLayerInDraft, isCallFragment, isImageContentUndrawn, isLayerPath, isLockedPath, isRootLayerPath, isRootPasteableType, isTemplateSubtreePath, layerBoxByPath, memoizeTextPolicies, moveGuard, moveRootLayerInDraft, moveTableCellInDraft, moveTableCellToRowInDraft, moveTableRowInDraft, moveTableRowToTableInDraft, nextZoomByWheel, normalizeExpressionSchemaSource, panBy, panToBox, parseExpressionCall, parseExpressionPath, parseExpressionSchema, pastePosition, pathStartsWith, pathsEqual, phpTrim, pickNextTextStylePatch, prepareRootPaste, proportionalDrivingAxis, ratioValue, readSpecField, remapPathAfterSplice, replaceHitsInDraft, resizableAxesAt, resizeBox, resizeBoxProportional, resizeHandleAt, resizeHandlePoint, resizeHandlesAt, resizeProportionalSnapPoints, resizeSnapPoints, resolveLayer, resolveRowSchema, resolveRowsPathStartSchema, resolveSnap, resolveSnapPoints, resourcePathDiagnostics, rootLayerOf, scanExpressionFragments, scanTextMatches, sceneToScreen, schemaChildEntries, schemaNodeAtPath, screenToScene, selectionParentPath, setCellAutoHeightInDraft, snapAxesFromBoxes, snapThresholdScene, snapViewportToPhysicalPixels, syncContentIntoCellInDraft, syncRowWidthInDraft, uploadDisplayName, visibleRootBoxes, writeSpecField, zoomAtPoint };

package/dist/index.js

@@ -306,6 +306,19 @@ function hitTest(canvas, sceneX, sceneY, policies, options) {
   }
   return null;
 }
+function headRootBox(canvas, policies) {
+  const layer = canvas.layers[0];
+  if (!layer) return null;
+  return { layer, box: resolveLayerBox2(layer, 0, 0, canvas.width, canvas.height, policies) };
+}
+function baseImageCandidateAt(canvas, sceneX, sceneY, policies, options) {
+  const head = headRootBox(canvas, policies);
+  if (head === null || head.layer.type !== "ImageLayer" || head.layer.visible === false) return null;
+  const lockedPaths = options?.lockedPaths;
+  if (lockedPaths !== void 0 && isLockedPath(["layers", 0], lockedPaths)) return null;
+  if (!coversCanvas(head.box, canvas.width, canvas.height)) return null;
+  return contains(head.box, sceneX, sceneY) ? ["layers", 0] : null;
+}
 
 // src/spatial/snap.ts
 import { resolveLayerBox as resolveLayerBox3 } from "@hankchen/canvas";
@@ -2317,6 +2330,29 @@ var ALT_DRAG_DEAD_ZONE_SCREEN_PX = 4;
 var NUDGE_STEP_PX = 1;
 var NUDGE_COARSE_STEP_PX = 10;
 var nudgeMergeKey = (path) => `nudge:${path.join(":")}`;
+function normalizeCanvasBackground(value) {
+  if (value === null) return null;
+  const trim = (raw) => typeof raw === "string" && raw.trim() !== "" ? raw : null;
+  const color = trim(value.color);
+  const image = trim(value.image);
+  return color === null && image === null ? null : { color, image };
+}
+function sameCanvasBackground(a, b) {
+  if (a === null || b === null) return a === b;
+  return a.color === b.color && a.image === b.image;
+}
+function baseImageConversionBlockInDoc(doc, path, policies) {
+  if (path.length !== 2 || path[0] !== "layers" || path[1] !== 0) return "not-head-root";
+  const head = headRootBox(doc, policies);
+  if (head === null) return "not-head-root";
+  if (head.layer.type !== "ImageLayer") return "not-image";
+  if (!coversCanvas(head.box, doc.width, doc.height)) return "not-covering";
+  const layer = head.layer;
+  if (layer.visible === false) return "hidden";
+  if (layer.expression !== null) return "expression-marked";
+  if (layer.src === null || layer.src.trim() === "") return "no-image-src";
+  return null;
+}
 function clampFindCursor(cursor, count) {
   if (count <= 0) return 0;
   return Math.min(Math.max(cursor, 0), count - 1);
@@ -3660,12 +3696,69 @@ var EditorSession = class {
     if (!paths.some((path) => pathsEqual(path, editing.path))) return;
     this.store.setEditing({ ...editing, draftSeq: (editing.draftSeq ?? 0) + 1 });
   }
-  /** 更新画布级字段（未选中图层时面板的宽/高写入口）；键由类型收窄为 width/height */
   updateCanvasProp(key, value, options = {}) {
     this.store.transact((draft) => {
+      if (key === "background") {
+        const next = normalizeCanvasBackground(value);
+        const current = draft.background ?? null;
+        if (sameCanvasBackground(current, next)) return;
+        draft.background = next;
+        return;
+      }
       draft[key] = value;
     }, options);
   }
+  /**
+   * 底图转换查询（canvas-background 工单 05，右键菜单门态唯一权威）：路径处
+   * 图层距「转为画布背景」的阻塞原因，null = 可转换。文档面条件见
+   * baseImageConversionBlockInDoc（豁免同门），此处叠加锁定子树（删除面同门
+   * ——转换含删层，锁定层不出路）。无文档/无路径归 not-head-root。
+   */
+  baseImageConversionBlock(path) {
+    const doc = this.store.doc;
+    if (!doc || path === null) return "not-head-root";
+    const block = baseImageConversionBlockInDoc(doc, path, this.textPolicies);
+    if (block !== null) return block;
+    return this.isLocked(path) ? "locked" : null;
+  }
+  /**
+   * 底图右键命中解析（canvas-background 工单 05，豁免的命中缝）：命中豁免使
+   * 头根覆盖图片层的自身盒退出正常命中面，右键菜单却要能选中它（「转为画布
+   * 背景」的入口前提）——宿主在命中未中时按此兜底解析转换候选，选择落地由
+   * 宿主决定（纯查询零副作用）。预览视图上解析（hitTest 同门）并映射回文档
+   * 身份；左键点选路径不经过这里，豁免行为零改动。
+   */
+  baseImageAt(sceneX, sceneY) {
+    const view = this.previewCanvas;
+    if (!view) return null;
+    const hit = baseImageCandidateAt(view, sceneX, sceneY, this.textPolicies, {
+      lockedPaths: this.store.ui.lockedPaths
+    });
+    if (hit === null) return null;
+    const docPath = viewPathToDocPath(view, hit);
+    return docPath ? docPath : null;
+  }
+  /**
+   * 转为画布背景（canvas-background 工单 05，存量底图出路）：选中头根图片层
+   * 的图片引用写入画布背景 image 分量 + 删除该图层，单事务一步历史、整体撤销
+   * （背景与图层都还原）。条件经 baseImageConversionBlock 同一门（违例静默
+   * 空转，无历史步）；既有背景色保留（只写 image 分量——先色后图语义不破，
+   * 已有背景图被垫底层的引用接管，同一门下二者本就是同一视觉位）。
+   */
+  convertSelectionToBackground() {
+    const doc = this.store.doc;
+    const path = this.store.ui.selection;
+    if (!doc || path === null) return false;
+    if (this.baseImageConversionBlock(path) !== null) return false;
+    const src = resolveLayer(doc, path).src;
+    this.store.transact((draft) => {
+      const current = normalizeCanvasBackground(draft.background ?? null);
+      draft.background = { color: current?.color ?? null, image: src };
+      deleteLayerInDraft(draft, path);
+    });
+    this.remapPathSlices([], "layers", 0, 0);
+    return true;
+  }
   // ---- 数据源 schema 声明（content-completion 工单 03/08）：D2 宿主随会话注入 ----
   /**
    * 注入数据源 schema 声明（载荷形态，D1 钉定：声明即 compile(canvas, dataset)
@@ -4761,13 +4854,29 @@ function isArrayNode(node) {
 function isScalarNode(node) {
   return !isArrayNode(node) && node.properties === void 0;
 }
+function joinSegment(prefix, key) {
+  return prefix === "" ? key : `${prefix}.${key}`;
+}
+function withMeta(target, node) {
+  if (node.description !== void 0) target.description = node.description;
+  if (node.title !== void 0) target.title = node.title;
+  return target;
+}
+function descendToLayer(start, segments) {
+  let base = start;
+  for (const segment of segments) {
+    if (isArrayNode(base)) return null;
+    const child = schemaNodeAtPath(base, [segment]);
+    if (child === null) return null;
+    base = child;
+  }
+  return isArrayNode(base) || isScalarNode(base) ? null : base;
+}
 function childCandidate2(key, node, prefix) {
-  const candidate = {
-    path: prefix === "" ? key : `${prefix}.${key}`,
-    segment: key
-  };
-  if (node.description !== void 0) candidate.description = node.description;
-  if (node.title !== void 0) candidate.title = node.title;
+  const candidate = withMeta(
+    { path: joinSegment(prefix, key), segment: key },
+    node
+  );
   if (isArrayNode(node)) candidate.type = "array";
   return candidate;
 }
@@ -4786,17 +4895,40 @@ function enumerateRowsPathCandidates(startSchema, input) {
   const segments = input.split(".");
   const partial = input.endsWith(".") ? "" : segments[segments.length - 1];
   const completed = segments.slice(0, -1);
-  let base = startSchema;
-  for (const segment of completed) {
-    if (isArrayNode(base)) return null;
-    const child = schemaNodeAtPath(base, [segment]);
-    if (child === null) return null;
-    base = child;
-  }
-  if (isArrayNode(base) || isScalarNode(base)) return null;
+  const base = descendToLayer(startSchema, completed);
+  if (base === null) return null;
   const view = levelCandidates(base, completed.join("."));
   return { partial, candidates: view };
 }
+function leadsToArray(node) {
+  if (isArrayNode(node)) return true;
+  if (node.properties === void 0) return false;
+  for (const child of node.properties.values()) {
+    if (leadsToArray(child)) return true;
+  }
+  return false;
+}
+function pickerEntry(key, node, prefix) {
+  return withMeta(
+    { path: joinSegment(prefix, key), segment: key, isArray: isArrayNode(node) },
+    node
+  );
+}
+function enumerateRowsPathPickerEntries(startSchema, prefix) {
+  if (startSchema === null) return [];
+  const segments = prefix === "" ? [] : prefix.split(".");
+  if (segments.includes("")) return [];
+  const base = descendToLayer(startSchema, segments);
+  if (base === null) return [];
+  const entries = [];
+  if (base.properties !== void 0) {
+    for (const [key, child] of base.properties) {
+      if (!leadsToArray(child)) continue;
+      entries.push(pickerEntry(key, child, prefix));
+    }
+  }
+  return entries;
+}
 function resolveRowsPathStartSchema(doc, path, rootSchema) {
   if (rootSchema === null) return null;
   if (doc === null || path === null) return rootSchema;
@@ -4930,6 +5062,7 @@ export {
   addTemplateCellInDraft,
   alignToCanvasTarget,
   applyStyleFieldsInDraft,
+  baseImageCandidateAt,
   buildLayerOutline,
   canCopyLayerAt,
   canonicalizeTableSyncInDraft,
@@ -4941,6 +5074,7 @@ export {
   cloneLayerSubtree,
   convertTableToRowsInDraft,
   convertTableToTemplateInDraft,
+  coversCanvas,
   createDefaultLayer,
   createRubberBandRect,
   createTemplateTable,
@@ -4949,6 +5083,7 @@ export {
   deleteLayerInDraft,
   enumerateExpressionCandidates,
   enumerateRowsPathCandidates,
+  enumerateRowsPathPickerEntries,
   expressionCallSlotAtEnd,
   expressionDiagnostics,
   expressionFragmentAtCursor,
@@ -4958,6 +5093,7 @@ export {
   growRowToCellInDraft,
   handleResizesHeight,
   handleResizesWidth,
+  headRootBox,
   hitTest,
   insertRootLayerAdjacentInDraft,
   insertRootLayerInDraft,