@hankchen/canvas-editor 0.8.0 → 0.9.0

package/dist/index.d.ts

@@ -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%） */
@@ -2099,6 +2104,29 @@ declare class EditorSession {
      */
     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 载荷形状，根上下文候选 = 载荷顶层键）。声明经
@@ -2448,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）
@@ -2455,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「画拉建层」
@@ -3263,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, 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, buildLayerOutline, canCopyLayerAt, canonicalizeTableSyncInDraft, captureStyleSnapshot, clampZoom, classifyEditorShortcut, classifyWheel, cloneLayerSubtree, convertTableToRowsInDraft, convertTableToTemplateInDraft, createDefaultLayer, createRubberBandRect, createTemplateTable, defaultNextTextStyle, defaultSizeForRatio, deleteLayerInDraft, enumerateExpressionCandidates, enumerateRowsPathCandidates, enumerateRowsPathPickerEntries, 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";
@@ -2328,6 +2341,18 @@ 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);
@@ -3683,6 +3708,57 @@ var EditorSession = class {
       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)
@@ -4986,6 +5062,7 @@ export {
   addTemplateCellInDraft,
   alignToCanvasTarget,
   applyStyleFieldsInDraft,
+  baseImageCandidateAt,
   buildLayerOutline,
   canCopyLayerAt,
   canonicalizeTableSyncInDraft,
@@ -4997,6 +5074,7 @@ export {
   cloneLayerSubtree,
   convertTableToRowsInDraft,
   convertTableToTemplateInDraft,
+  coversCanvas,
   createDefaultLayer,
   createRubberBandRect,
   createTemplateTable,
@@ -5015,6 +5093,7 @@ export {
   growRowToCellInDraft,
   handleResizesHeight,
   handleResizesWidth,
+  headRootBox,
   hitTest,
   insertRootLayerAdjacentInDraft,
   insertRootLayerInDraft,