@hankchen/canvas-editor 0.7.0 → 0.8.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';
 
@@ -958,6 +958,12 @@ interface FindSession {
     replacement: string;
     cursor: number;
 }
+/** 数据源声明拒绝详情（声明被拒呈现面，死端态整改 2b）：reason 为声明期拒绝码、
+ *  detail 为教学性明细（直取 parseExpressionSchema 拒绝面） */
+interface DataSourceSchemaRejection {
+    reason: ExpressionSchemaRejectReason;
+    detail: string;
+}
 interface EditorUi {
     viewport: Viewport;
     /** 当前选中图层路径（数组路径，patch path 前缀）；null = 无选择 */
@@ -1027,6 +1033,14 @@ interface EditorUi {
      * 文档不重置（声明随会话，重注入/清除走同一入口）。
      */
     dataSourceSchema: ExpressionSchemaNode | null;
+    /**
+     * 数据源声明拒绝详情（声明被拒呈现面，死端态整改 2b）：仅被拒注入在场——
+     * reason/detail 直取 parseExpressionSchema 拒绝面（reserved_root_key /
+     * invalid_schema / open_map_unsupported），宿主读数与绑定面据此区分「未注入」
+     * 与「注入被拒」。只住会话态随 dataSourceSchema 同步置换：合法注入与清除
+     * 归 null；不进 graph、不落 localStorage、不进 wire。
+     */
+    dataSourceSchemaRejection: DataSourceSchemaRejection | null;
     /**
      * 参考线（ruler-guides-snap 工单 01，ADR 0012）：使用者从标尺拖出的会话级
      * 对位轴（水平/垂直、场景坐标）。零契约面——不进历史、不写 graph、保存零
@@ -1169,10 +1183,11 @@ declare class EditorStore {
     setNextTextStyle(patch: Partial<NextTextStyle>): void;
     /**
      * 数据源 schema 声明替换（归一产物或降级 null，校验收口在注入缝不在这里）：
-     * 同引用短路（重复注入同一归一产物不惊动订阅方）；仅 ui 通知，不参与重绘
+     * 声明与拒绝详情成对置换（rejection 仅被拒注入在场，2b 呈现面），同引用且
+     * 同拒绝态短路（重复注入同一归一产物不惊动订阅方）；仅 ui 通知，不参与重绘
      * 脏标（onStoreChange 对该分支短路）。
      */
-    setDataSourceSchema(schema: ExpressionSchemaNode | null): void;
+    setDataSourceSchema(schema: ExpressionSchemaNode | null, rejection?: DataSourceSchemaRejection | null): void;
     /** 参考线列表替换（增删动作在会话门面收口）；仅 ui 通知，不参与历史 */
     setGuides(guides: readonly Guide[]): void;
     /** 标尺显隐：布尔值等短路（重复置同态不重绘） */
@@ -2048,8 +2063,11 @@ declare class EditorSession {
     updateDataExpression(path: LayerPath, expression: string | null, options?: TransactOptions): void;
     /**
      * 数据字段取值方式切换（静态 ⇆ 表达式，工单 02 自面板收编内核）：表达式现态
-     * → 字面接管（updateData，值保持现镜像）；静态现态 → 打标（updateDataExpression，
-     * 初值 = 值字段原文）。各为独立一步历史（无 mergeKey）。三内容层分派各取值
+     * → 字面接管（updateData，值保持现镜像）；静态现态 → 打标，初值分内容面——
+     * 文本层镜像原文（字面可含合法插值混排），资源层（Image/Qr）只镜像**已合法
+     * 的单引用字面**（静态 ⇆ 表达式往返无损），违例字面（URL/拼接文案）落
+     * 「未选择」空态不镜像——切换自身不得制造必违例初值（死端态整改条目 4；旧
+     * 值可经撤销一步找回）。各为独立一步历史（无 mergeKey）。三内容层分派各取值
      * 字段，表/行/格/悬空路径空转。
      *
      * 活标志防御路由（ADR 0019）：路径即编辑中的层时只翻会话活标志（零文档变更
@@ -2057,6 +2075,8 @@ declare class EditorSession {
      * 草稿；面板锁定段/pill 显式调用与宿主旁路调用都安全收敛到同一语义。
      */
     toggleDataMode(path: LayerPath): void;
+    /** 资源面切换初值：字面已是合法单引用（含空串为「未选择」）才镜像，违例落空态 */
+    private resourceToggleInitial;
     /**
      * 内容写事务的统一形（会话内容独占工单 02）：transact 落库 + 命中编辑层的
      * 草稿接管收口——updateData/updateDataExpression/replaceOne/replaceAll 四个
@@ -2070,8 +2090,15 @@ 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;
     /**
      * 注入数据源 schema 声明（载荷形态，D1 钉定：声明即 compile(canvas, dataset)
      * 收到的 data 载荷形状，根上下文候选 = 载荷顶层键）。声明经
@@ -3124,6 +3151,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。
  */
@@ -3146,6 +3183,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 段行
@@ -3201,4 +3263,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 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, 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 };

package/dist/index.js

@@ -1004,6 +1004,20 @@ function expressionFragmentAtCursor(scan, cursor) {
   return null;
 }
 
+// src/shared/resourcePath.ts
+function wholeTemplateDiagnostic(template, kind) {
+  return { kind, start: 0, end: template.length, at: { start: 0, end: template.length } };
+}
+function resourcePathDiagnostics(template) {
+  const anchored = template.endsWith("\n") ? template.slice(0, -1) : template;
+  const matched = /^\{\{([^{}]*)\}\}$/.exec(anchored);
+  if (matched === null) return [wholeTemplateDiagnostic(template, "resource_not_single_ref")];
+  const path = phpTrim2(matched[1] ?? "");
+  if (path === "") return [wholeTemplateDiagnostic(template, "empty_fragment")];
+  if (path.includes("(")) return [wholeTemplateDiagnostic(template, "resource_function_call")];
+  return [];
+}
+
 // src/editing/alignCanvas.ts
 var ALIGN_CORNER_MARGIN_PX = 40;
 function alignToCanvasTarget(mode, box, canvasWidth, canvasHeight, margin) {
@@ -1748,6 +1762,7 @@ var EditorStore = class {
     anchorExpanded: false,
     nextTextStyle: defaultNextTextStyle(),
     dataSourceSchema: null,
+    dataSourceSchemaRejection: null,
     guides: [],
     rulersVisible: true,
     snapAxes: [],
@@ -1940,12 +1955,13 @@ var EditorStore = class {
   }
   /**
    * 数据源 schema 声明替换（归一产物或降级 null，校验收口在注入缝不在这里）：
-   * 同引用短路（重复注入同一归一产物不惊动订阅方）；仅 ui 通知，不参与重绘
+   * 声明与拒绝详情成对置换（rejection 仅被拒注入在场，2b 呈现面），同引用且
+   * 同拒绝态短路（重复注入同一归一产物不惊动订阅方）；仅 ui 通知，不参与重绘
    * 脏标（onStoreChange 对该分支短路）。
    */
-  setDataSourceSchema(schema) {
-    if (this.uiValue.dataSourceSchema === schema) return;
-    this.uiValue = { ...this.uiValue, dataSourceSchema: schema };
+  setDataSourceSchema(schema, rejection = null) {
+    if (this.uiValue.dataSourceSchema === schema && this.uiValue.dataSourceSchemaRejection === rejection) return;
+    this.uiValue = { ...this.uiValue, dataSourceSchema: schema, dataSourceSchemaRejection: rejection };
     this.notify({ scope: "ui", branch: "dataSourceSchema" });
   }
   /** 参考线列表替换（增删动作在会话门面收口）；仅 ui 通知，不参与历史 */
@@ -2301,6 +2317,17 @@ 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 clampFindCursor(cursor, count) {
   if (count <= 0) return 0;
   return Math.min(Math.max(cursor, 0), count - 1);
@@ -3582,8 +3609,11 @@ var EditorSession = class {
   }
   /**
    * 数据字段取值方式切换（静态 ⇆ 表达式，工单 02 自面板收编内核）：表达式现态
-   * → 字面接管（updateData，值保持现镜像）；静态现态 → 打标（updateDataExpression，
-   * 初值 = 值字段原文）。各为独立一步历史（无 mergeKey）。三内容层分派各取值
+   * → 字面接管（updateData，值保持现镜像）；静态现态 → 打标，初值分内容面——
+   * 文本层镜像原文（字面可含合法插值混排），资源层（Image/Qr）只镜像**已合法
+   * 的单引用字面**（静态 ⇆ 表达式往返无损），违例字面（URL/拼接文案）落
+   * 「未选择」空态不镜像——切换自身不得制造必违例初值（死端态整改条目 4；旧
+   * 值可经撤销一步找回）。各为独立一步历史（无 mergeKey）。三内容层分派各取值
    * 字段，表/行/格/悬空路径空转。
    *
    * 活标志防御路由（ADR 0019）：路径即编辑中的层时只翻会话活标志（零文档变更
@@ -3605,16 +3635,20 @@ var EditorSession = class {
         return;
       case "ImageLayer":
         if (layer.expression !== null) this.updateData(path, layer.src ?? "");
-        else this.updateDataExpression(path, layer.src ?? "");
+        else this.updateDataExpression(path, this.resourceToggleInitial(layer.src ?? ""));
         return;
       case "QrCodeLayer":
         if (layer.expression !== null) this.updateData(path, layer.value);
-        else this.updateDataExpression(path, layer.value);
+        else this.updateDataExpression(path, this.resourceToggleInitial(layer.value));
         return;
       default:
         return;
     }
   }
+  /** 资源面切换初值：字面已是合法单引用（含空串为「未选择」）才镜像，违例落空态 */
+  resourceToggleInitial(literal) {
+    return resourcePathDiagnostics(literal).length === 0 ? literal : "";
+  }
   /**
    * 内容写事务的统一形（会话内容独占工单 02）：transact 落库 + 命中编辑层的
    * 草稿接管收口——updateData/updateDataExpression/replaceOne/replaceAll 四个
@@ -3637,9 +3671,15 @@ 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);
   }
@@ -3658,9 +3698,20 @@ var EditorSession = class {
    * 换文档不重置，重注入/清除走同一入口。签名与「注入即整体替换」语义不变（D6）。
    */
   setDataSourceSchema(raw) {
-    this.store.setDataSourceSchema(
-      raw === null || raw === void 0 ? null : normalizeExpressionSchemaSource(raw)
-    );
+    if (raw === null || raw === void 0) {
+      this.store.setDataSourceSchema(null);
+      return;
+    }
+    const schema = normalizeExpressionSchemaSource(raw);
+    if (schema === null) {
+      const parsed = parseExpressionSchema(raw);
+      this.store.setDataSourceSchema(
+        null,
+        parsed.ok ? null : { reason: parsed.reason, detail: parsed.detail }
+      );
+      return;
+    }
+    this.store.setDataSourceSchema(schema);
   }
   // ---- 上传（工单 13）：本机资源 → 可物化引用，实现经 uploadHandler 注入 ----
   /** 上传可用性：未注入 uploadHandler 时为 false（宿主据此隐藏/禁用上传入口） */
@@ -4526,20 +4577,6 @@ function expressionDiagnostics(template) {
   return found;
 }
 
-// src/shared/resourcePath.ts
-function wholeTemplateDiagnostic(template, kind) {
-  return { kind, start: 0, end: template.length, at: { start: 0, end: template.length } };
-}
-function resourcePathDiagnostics(template) {
-  const anchored = template.endsWith("\n") ? template.slice(0, -1) : template;
-  const matched = /^\{\{([^{}]*)\}\}$/.exec(anchored);
-  if (matched === null) return [wholeTemplateDiagnostic(template, "resource_not_single_ref")];
-  const path = phpTrim2(matched[1] ?? "");
-  if (path === "") return [wholeTemplateDiagnostic(template, "empty_fragment")];
-  if (path.includes("(")) return [wholeTemplateDiagnostic(template, "resource_function_call")];
-  return [];
-}
-
 // src/shared/expressionFunctions.ts
 var EXPRESSION_FUNCTIONS = [
   { name: "date", signature: "date(path[, format])", summary: "\u65E5\u671F\u683C\u5F0F\u5316\uFF08moment \u98CE\u683C token\uFF0C\u9884\u8BBE date/datetime\uFF09" },
@@ -4741,13 +4778,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;
 }
@@ -4766,17 +4819,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;
@@ -4929,6 +5005,7 @@ export {
   deleteLayerInDraft,
   enumerateExpressionCandidates,
   enumerateRowsPathCandidates,
+  enumerateRowsPathPickerEntries,
   expressionCallSlotAtEnd,
   expressionDiagnostics,
   expressionFragmentAtCursor,