@hankchen/canvas-editor 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -932,6 +932,35 @@ interface EditorShortcutInput {
  */
 declare function classifyEditorShortcut(input: EditorShortcutInput, bindings?: readonly EditorShortcutBinding[]): EditorShortcutAction | null;
 
+/**
+ * 编辑器状态切片与偏好（project-data 工单 01，spec §3/§5）：内核导出的「单画布
+ * 切片 + 偏好 + schemaVersion 常量」三件，EditorSession 实例方法（editor.ts）消费。
+ *
+ * 分层纪律（内核帧盲）：帧名/帧缓冲/文档是宿主领域——frames 容器（帧名 → 切片）
+ * 与完整快照聚合类型（schemaVersion/frames/prefs）归宿主拼装，宿主只透传切片
+ * 内容、不解释 guides/lockedPaths 语义；本模块只出两型 + 版本常量 + restore 的
+ * 轻结构校验。零契约面：切片不进 wire、不进历史栈、不是第二种文档格式——graph
+ * 仍是内核唯一保存物。
+ */
+
+/** 快照格式版本：随格式演化单调递增；v1 = 1（宽容读贯彻，restore 不分支此值） */
+declare const EDITOR_STATE_SCHEMA_VERSION = 1;
+/** 帧作用域切片：当前打开画布的编辑器状态（工程数据快照的 frames[帧名] 值） */
+interface CanvasEditorState {
+    /**
+     * 参考线（场景坐标）：id 是会话内自增值、无持久语义——export 原样带出，
+     * restore 端清空后逐条 addGuide 重取号，快照 id 出方向即失效。
+     */
+    guides: readonly Guide[];
+    /** 锁定根层路径集合（随工程数据持久化，仍零 wire 面） */
+    lockedPaths: readonly LayerPath[];
+}
+/** 编辑器级偏好：跨文档、跨会话内核自持（工程数据快照的 prefs 桶，分类学终裁两项） */
+interface EditorPrefsState {
+    rulersVisible: boolean;
+    anchorExpanded: boolean;
+}
+
 /**
  * 字体清单（工单 13）：编辑会话级的字体可选清单——「清单 ≠ 物化」，core 只持有
  * 引用与展示名，字体的加载仍走渲染端物化管线（FontFace 注册），本模块零 I/O。
@@ -1144,8 +1173,13 @@ declare class EditorSession {
     setDevicePixelRatio(dpr: number): void;
     setSurfaceSize(width: number, height: number): void;
     getSurfaceSize(): Readonly<Size>;
-    /** 打开/替换文档（转发 store；解码在宿主侧完成，内核只消费领域结构） */
-    openDocument(canvas: Canvas): void;
+    /**
+     * 打开/替换文档（转发 store；解码在宿主侧完成，内核只消费领域结构）。
+     * state 传切片即按 restoreEditorState 同一管线原子应用（reset → apply 切片 →
+     * prune）——「开了就恢复」，宿主切帧处不可能忘记重放；切片形状不合法整体拒
+     * （画布照常以默认态打开），现网单参调用零破坏。
+     */
+    openDocument(canvas: Canvas, state?: CanvasEditorState): void;
     /**
      * 预览视图（只读衍生）：模板态表格在视图中获得一行预览行（文本格 = 表达式
      * 原文、标记图片/二维码格走占位盒），渲染/命中/导出据此呈现「一行输出效果」；
@@ -1422,6 +1456,13 @@ declare class EditorSession {
     }): Guide | null;
     /** 删除参考线（拖回标尺语义）：按 id 移除；未知 id 空转返回 false */
     removeGuide(id: number): boolean;
+    /**
+     * 移动参考线（抓取拖动再定位的写入口）：按 id 原地改位（取向不变），
+     * ui 分支同门——不进历史、不写 graph（ADR 0012），广播 guides 分支通知
+     * （覆盖层失效重绘）。非有限坐标/未知 id 空转返回 false（不产生通知）；
+     * 同位空转返回 true（无变化不惊动订阅方——抓取未动的松手路径）。
+     */
+    updateGuide(id: number, position: number): boolean;
     /**
      * 清空全部参考线（工具栏「清空参考线」写入口，工单 03 消费）：ui 分支整体置空，
      * 与 removeGuide 同型广播 guides 分支通知（覆盖层失效重绘）。会话级语义同门——
@@ -1432,6 +1473,34 @@ declare class EditorSession {
     listGuides(): readonly Guide[];
     /** 标尺显隐开关（⇧R 分派口）：翻转 ui 偏好，不进历史 */
     toggleRulers(): void;
+    /**
+     * 导出当前打开画布的编辑器状态切片：guides 原样带出（id 是会话内自增值，
+     * 宿主不持久化其语义——restore 端重排重取号）、lockedPaths 原样。无文档也可
+     * 导出（ui 分支自成事实，addGuide 无 doc 守卫同门）。内核帧盲：宿主把各帧
+     * 切片按帧名组装成 frames 容器，加上 schemaVersion（EDITOR_STATE_SCHEMA_VERSION）
+     * 与 getEditorPrefs() 才是完整工程数据快照，经宿主层存储——容器不进内核。
+     */
+    exportEditorState(): CanvasEditorState;
+    /**
+     * 恢复当前画布的状态切片（prefs 不在此——内核跨 openDocument 自持）：轻结构
+     * 校验（形状不合法整体拒，返 false 宿主记因）→ 整体替换 lockedPaths →
+     * pruneDanglingPaths（悬空锁路径剔除——合法但内容悬空不算拒，prune 兜底）→
+     * guide id 重排（清空后逐条 addGuide 重取号：快照 id 无持久语义，原样入栈必
+     * 与新会话 guideIdSeq 撞号致 removeGuide 误删）。不进历史、不写 graph（红线
+     * 同门）。
+     */
+    restoreEditorState(state: CanvasEditorState): boolean;
+    /**
+     * 只读偏好（保存 prefs 的读取口）：与 store.ui 同源，给宿主一个不用下钻
+     * store 的口。读 = getEditorPrefs，写 = applyEditorPrefs，对称成对；帧切片
+     * 走 restoreEditorState，两不相混。
+     */
+    getEditorPrefs(): EditorPrefsState;
+    /**
+     * 应用偏好（会话建立时一次性，跨会话恢复 prefs 的写入口）：整体替换
+     * rulersVisible/anchorExpanded，不进历史；值等写入经 store 短路零通知。
+     */
+    applyEditorPrefs(prefs: EditorPrefsState): void;
     /**
      * 对齐画布 action 族（对齐画布/贴边/贴角，ADR 0011）：把 path 处图层盒整体
      * 对齐到画布几何——mode 十种：贴边 left/right/top/bottom（零边距）、居中
@@ -2675,4 +2744,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 CreateGesture, type CreateRectResult, DEFAULT_EDITOR_SHORTCUTS, DEFAULT_ZOOM_BOUNDS, type DeletedLayerRef, type DocRecipe, type DragGesture, type EditorChange, EditorSession, type EditorSessionOptions, type EditorShortcutAction, type EditorShortcutBinding, type EditorShortcutGroup, type EditorShortcutInput, EditorStore, type EditorUi, type ExpressionCandidate, type ExpressionCandidateQuery, type ExpressionCandidateResult, type ExpressionContextKind, 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, type OverlayPaintArgs, type OverlayPainter, PACKAGE_NAME, PAN_TO_BOX_MARGIN_PX, PASTE_OFFSET_PX, PHP_TRIM_CHARS, type Point, RESIZE_HANDLES, RESIZE_HANDLE_HIT_PX, RESIZE_MIN_SIZE_PX, 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, type TextEditLayout, type TextEditingSession, 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, deleteLayerInDraft, enumerateExpressionCandidates, enumerateRowsPathCandidates, expressionFragmentAtCursor, fitRect, fitViewport, growRowToCellInDraft, handleResizesHeight, handleResizesWidth, hitTest, insertRootLayerAdjacentInDraft, insertRootLayerInDraft, isImageContentUndrawn, isLayerPath, isLockedPath, isRootLayerPath, isRootPasteableType, isTemplateSubtreePath, layerBoxByPath, memoizeTextPolicies, moveGuard, moveRootLayerInDraft, moveTableCellInDraft, moveTableCellToRowInDraft, moveTableRowInDraft, moveTableRowToTableInDraft, nextZoomByWheel, normalizeExpressionSchemaSource, panBy, panToBox, parseExpressionPath, parseExpressionSchema, pastePosition, pathStartsWith, pathsEqual, prepareRootPaste, readSpecField, remapPathAfterSplice, replaceHitsInDraft, resizableAxesAt, resizeBox, resizeHandleAt, resizeHandlePoint, resizeHandlesAt, resizeSnapPoints, resolveLayer, resolveRowSchema, resolveRowsPathStartSchema, resolveSnap, resolveSnapPoints, 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, CREATE_DEAD_ZONE_SCREEN_PX, type CanvasEditorState, type CreateGesture, type CreateRectResult, DEFAULT_EDITOR_SHORTCUTS, DEFAULT_ZOOM_BOUNDS, type DeletedLayerRef, type DocRecipe, type DragGesture, EDITOR_STATE_SCHEMA_VERSION, type EditorChange, type EditorPrefsState, EditorSession, type EditorSessionOptions, type EditorShortcutAction, type EditorShortcutBinding, type EditorShortcutGroup, type EditorShortcutInput, EditorStore, type EditorUi, type ExpressionCandidate, type ExpressionCandidateQuery, type ExpressionCandidateResult, type ExpressionContextKind, 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, type OverlayPaintArgs, type OverlayPainter, PACKAGE_NAME, PAN_TO_BOX_MARGIN_PX, PASTE_OFFSET_PX, PHP_TRIM_CHARS, type Point, RESIZE_HANDLES, RESIZE_HANDLE_HIT_PX, RESIZE_MIN_SIZE_PX, 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, type TextEditLayout, type TextEditingSession, 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, deleteLayerInDraft, enumerateExpressionCandidates, enumerateRowsPathCandidates, expressionFragmentAtCursor, fitRect, fitViewport, growRowToCellInDraft, handleResizesHeight, handleResizesWidth, hitTest, insertRootLayerAdjacentInDraft, insertRootLayerInDraft, isImageContentUndrawn, isLayerPath, isLockedPath, isRootLayerPath, isRootPasteableType, isTemplateSubtreePath, layerBoxByPath, memoizeTextPolicies, moveGuard, moveRootLayerInDraft, moveTableCellInDraft, moveTableCellToRowInDraft, moveTableRowInDraft, moveTableRowToTableInDraft, nextZoomByWheel, normalizeExpressionSchemaSource, panBy, panToBox, parseExpressionPath, parseExpressionSchema, pastePosition, pathStartsWith, pathsEqual, prepareRootPaste, readSpecField, remapPathAfterSplice, replaceHitsInDraft, resizableAxesAt, resizeBox, resizeHandleAt, resizeHandlePoint, resizeHandlesAt, resizeSnapPoints, resolveLayer, resolveRowSchema, resolveRowsPathStartSchema, resolveSnap, resolveSnapPoints, rootLayerOf, scanExpressionFragments, scanTextMatches, sceneToScreen, schemaChildEntries, schemaNodeAtPath, screenToScene, selectionParentPath, setCellAutoHeightInDraft, snapAxesFromBoxes, snapThresholdScene, snapViewportToPhysicalPixels, syncContentIntoCellInDraft, syncRowWidthInDraft, uploadDisplayName, visibleRootBoxes, writeSpecField, zoomAtPoint };

package/dist/index.js

@@ -1797,6 +1797,27 @@ function classifyEditorShortcut(input, bindings = DEFAULT_EDITOR_SHORTCUTS) {
   return null;
 }
 
+// src/session/editorState.ts
+var EDITOR_STATE_SCHEMA_VERSION = 1;
+function parseCanvasEditorState(state) {
+  const raw = state;
+  if (raw === null || typeof raw !== "object") return null;
+  const source = raw;
+  if (!Array.isArray(source.guides) || !Array.isArray(source.lockedPaths)) return null;
+  const guides = [];
+  for (const entry of source.guides) {
+    if (entry === null || typeof entry !== "object" || Array.isArray(entry)) return null;
+    const { orientation, position } = entry;
+    if (orientation !== "horizontal" && orientation !== "vertical") return null;
+    if (typeof position !== "number" || !Number.isFinite(position)) return null;
+    guides.push({ orientation, position });
+  }
+  for (const path of source.lockedPaths) {
+    if (!Array.isArray(path)) return null;
+  }
+  return { guides, lockedPaths: source.lockedPaths };
+}
+
 // src/editing/fontCatalog.ts
 var FontCatalog = class {
   builtin;
@@ -2024,9 +2045,16 @@ var EditorSession = class {
     return this.surfaceSize;
   }
   // ---- 相机动作（视口 {x, y, zoom} 走 ui 分支，不进历史） ----
-  /** 打开/替换文档（转发 store；解码在宿主侧完成，内核只消费领域结构） */
-  openDocument(canvas) {
+  /**
+   * 打开/替换文档（转发 store；解码在宿主侧完成，内核只消费领域结构）。
+   * state 传切片即按 restoreEditorState 同一管线原子应用（reset → apply 切片 →
+   * prune）——「开了就恢复」，宿主切帧处不可能忘记重放；切片形状不合法整体拒
+   * （画布照常以默认态打开），现网单参调用零破坏。
+   */
+  openDocument(canvas, state) {
     this.store.openDocument(canvas);
+    if (state === void 0) return;
+    this.restoreEditorState(state);
   }
   /**
    * 预览视图（只读衍生）：模板态表格在视图中获得一行预览行（文本格 = 表达式
@@ -2705,6 +2733,21 @@ var EditorSession = class {
     this.store.setGuides(next);
     return true;
   }
+  /**
+   * 移动参考线（抓取拖动再定位的写入口）：按 id 原地改位（取向不变），
+   * ui 分支同门——不进历史、不写 graph（ADR 0012），广播 guides 分支通知
+   * （覆盖层失效重绘）。非有限坐标/未知 id 空转返回 false（不产生通知）；
+   * 同位空转返回 true（无变化不惊动订阅方——抓取未动的松手路径）。
+   */
+  updateGuide(id, position) {
+    if (!Number.isFinite(position)) return false;
+    const guides = this.store.ui.guides;
+    const target = guides.find((guide) => guide.id === id);
+    if (target === void 0) return false;
+    if (target.position === position) return true;
+    this.store.setGuides(guides.map((guide) => guide.id === id ? { ...guide, position } : guide));
+    return true;
+  }
   /**
    * 清空全部参考线（工具栏「清空参考线」写入口，工单 03 消费）：ui 分支整体置空，
    * 与 removeGuide 同型广播 guides 分支通知（覆盖层失效重绘）。会话级语义同门——
@@ -2723,6 +2766,51 @@ var EditorSession = class {
   toggleRulers() {
     this.store.setRulersVisible(!this.store.ui.rulersVisible);
   }
+  // ---- 编辑器状态导出与恢复（project-data 工单 01，spec §5）：与 addGuide/toggleLayerLock 同门——ui 分支写、不进历史、不写 graph ----
+  /**
+   * 导出当前打开画布的编辑器状态切片：guides 原样带出（id 是会话内自增值，
+   * 宿主不持久化其语义——restore 端重排重取号）、lockedPaths 原样。无文档也可
+   * 导出（ui 分支自成事实，addGuide 无 doc 守卫同门）。内核帧盲：宿主把各帧
+   * 切片按帧名组装成 frames 容器，加上 schemaVersion（EDITOR_STATE_SCHEMA_VERSION）
+   * 与 getEditorPrefs() 才是完整工程数据快照，经宿主层存储——容器不进内核。
+   */
+  exportEditorState() {
+    return { guides: this.store.ui.guides, lockedPaths: this.store.ui.lockedPaths };
+  }
+  /**
+   * 恢复当前画布的状态切片（prefs 不在此——内核跨 openDocument 自持）：轻结构
+   * 校验（形状不合法整体拒，返 false 宿主记因）→ 整体替换 lockedPaths →
+   * pruneDanglingPaths（悬空锁路径剔除——合法但内容悬空不算拒，prune 兜底）→
+   * guide id 重排（清空后逐条 addGuide 重取号：快照 id 无持久语义，原样入栈必
+   * 与新会话 guideIdSeq 撞号致 removeGuide 误删）。不进历史、不写 graph（红线
+   * 同门）。
+   */
+  restoreEditorState(state) {
+    const slice = parseCanvasEditorState(state);
+    if (slice === null) return false;
+    this.store.setLockedPaths(slice.lockedPaths);
+    this.pruneDanglingPaths();
+    if (this.store.ui.guides.length > 0) this.store.setGuides([]);
+    for (const guide of slice.guides) this.addGuide(guide);
+    return true;
+  }
+  /**
+   * 只读偏好（保存 prefs 的读取口）：与 store.ui 同源，给宿主一个不用下钻
+   * store 的口。读 = getEditorPrefs，写 = applyEditorPrefs，对称成对；帧切片
+   * 走 restoreEditorState，两不相混。
+   */
+  getEditorPrefs() {
+    const ui = this.store.ui;
+    return { rulersVisible: ui.rulersVisible, anchorExpanded: ui.anchorExpanded };
+  }
+  /**
+   * 应用偏好（会话建立时一次性，跨会话恢复 prefs 的写入口）：整体替换
+   * rulersVisible/anchorExpanded，不进历史；值等写入经 store 短路零通知。
+   */
+  applyEditorPrefs(prefs) {
+    this.store.setRulersVisible(prefs.rulersVisible);
+    this.store.setAnchorExpanded(prefs.anchorExpanded);
+  }
   // ---- 对齐画布（layer-align-snap 工单 01）：图层盒整体对齐画布几何 ----
   /**
    * 对齐画布 action 族（对齐画布/贴边/贴角，ADR 0011）：把 path 处图层盒整体
@@ -4146,6 +4234,7 @@ export {
   CREATE_DEAD_ZONE_SCREEN_PX,
   DEFAULT_EDITOR_SHORTCUTS,
   DEFAULT_ZOOM_BOUNDS,
+  EDITOR_STATE_SCHEMA_VERSION,
   EditorSession,
   EditorStore,
   FontCatalog,