@lingfan-engine/editor 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright (c) 2026 MoFeng-02
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@lingfan-engine/editor",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.2",
+  "type": "module",
+  "description": "灵泛叙事作者层：op schema 单一事实源 + 词函数子语言 + 编辑期诊断 + 故事树纯映射器——只读写故事 JSON，不碰运行时与平台",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/script/generate-vocabulary.ts"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@lingfan-engine/core": "^0.1.2",
+    "zod": "^4.6.5"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MoFeng-02/LingFan.Engine.git",
+    "directory": "packages/editor"
+  },
+  "homepage": "https://github.com/MoFeng-02/LingFan.Engine#readme",
+  "bugs": {
+    "url": "https://github.com/MoFeng-02/LingFan.Engine/issues"
+  },
+  "keywords": [
+    "narrative",
+    "editor",
+    "schema",
+    "story",
+    "typescript"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/src/chapters/build.ts

@@ -0,0 +1,180 @@
+/**
+ * 故事章节树 · 判据与装配实现（可测，无 IO / 无 Vue）。
+ *
+ * 域出口 `./index.ts` 只做转发（类型见 `./types.ts`）；实现集中在本文件。
+ * 设计约定（分组只看 type、任意深度、0 层平铺退化）见出口文件头注。
+ */
+
+import {
+  isReplayableColumn,
+  STORIES_DIR,
+  type StoryColumn,
+} from "@lingfan-engine/core";
+import type {
+  ChapterDir,
+  ChapterGroup,
+  ChapterIndex,
+  ChapterInput,
+  ChapterNode,
+} from "./types.ts";
+
+/** 故事文件的容器根（剥掉它，剩下的目录链才是「作者的章节编排」；由引擎 SSOT 常量派生） */
+const STORIES_ROOT = `${STORIES_DIR}/`;
+
+/** 剥掉 `Stories/` 前缀（**容器根不算章节**——否则 `Stories/start.json` 的章节名会变成「Stories」） */
+function insideStories(path: string): string {
+  return path.startsWith(STORIES_ROOT) ? path.slice(STORIES_ROOT.length) : path;
+}
+
+/** 章节目录键（不依赖 `ResourceNode`，直接吃路径集——便于纯测）
+ *
+ * **只取 `Stories/` 之下的目录**（`Stories/start.json` ⇒ `""` ⇒ 平铺，
+ * 因为「深一层」只是把文件分组，**不是编排章节**；只有 `Stories/a/b.story` 才是）。
+ * 容器根 `Stories/` 本身**不算章节**——否则章节名全变成 "Stories"。
+ */
+export function chapterDirOf(path: string): string {
+  const inner = insideStories(path);
+  const idx = inner.lastIndexOf("/");
+  return idx < 0 ? "" : inner.slice(0, idx + 1);
+}
+
+/** 章节显示名：**优先取目录名**（作者的分章意图），0 层平铺时退回文件名去后缀 */
+export function chapterLabelOf(path: string): string {
+  const inner = insideStories(path);
+  const file = inner.slice(inner.lastIndexOf("/") + 1);
+  const dot = file.indexOf(".");
+  const name = dot < 0 ? file : file.slice(0, dot);
+  const dir = chapterDirOf(path);
+  const dirName =
+    dir
+      .slice(0, dir.length - 1)
+      .split("/")
+      .pop() ?? "";
+  // 目录名与文件名同前缀时（如 chapter1/chapter1.story）**取目录名**——
+  // 目录才是「章节」，文件名只是文件。
+  return dirName !== "" ? dirName : name;
+}
+
+/** 章节所属分组（**单一判定点**：直接用引擎的 `isReplayableColumn`，不另写一份） */
+export function chapterGroupOf(
+  column: Pick<StoryColumn, "type">,
+): ChapterGroup {
+  return isReplayableColumn(column) ? "story" : "ui";
+}
+
+/**
+ * 场景类型的**徽标文案**（单一事实源：列侧栏 / 章节树共用，组件不得自写映射）。
+ *
+ * - `"menu"` → 「菜单」；`"ui"` → 「界面」
+ * - 缺省（`undefined`）与 `"game"` → `null`（**game 是常态不标**——满屏「剧情」徽标是噪音）
+ */
+export function sceneTypeBadgeOf(
+  type: StoryColumn["type"],
+): "菜单" | "界面" | null {
+  if (type === "menu") return "菜单";
+  if (type === "ui") return "界面";
+  return null;
+}
+
+/** 命令条数（flow 看 commands、scene 看 entry；缺省 0） */
+function commandCountOf(column: StoryColumn): number {
+  if (column.kind === "scene") return (column.entry ?? []).length;
+  return (column.commands ?? []).length;
+}
+
+/** 按组归并目录（`dirs` 的**分组版本**；同一目录在两个组各出一份，children 不交叉） */
+function dirsOfGroup(
+  nodes: readonly ChapterNode[],
+  group: ChapterGroup,
+): ChapterDir[] {
+  const byDir = new Map<string, ChapterNode[]>();
+  for (const node of nodes) {
+    if (node.group !== group) continue; // ← 关键：只收本组的节点
+    const dir = chapterDirOf(node.path);
+    if (dir === "") continue; // 0 层平铺：不进目录分组
+    const bucket = byDir.get(dir);
+    if (bucket === undefined) byDir.set(dir, [node]);
+    else bucket.push(node);
+  }
+  return [...byDir.entries()]
+    .map(([path, children]) => ({
+      label:
+        path
+          .slice(0, path.length - 1)
+          .split("/")
+          .pop() ?? path,
+      path,
+      children: [...children].sort((a, b) =>
+        a.path < b.path ? -1 : a.path > b.path ? 1 : 0,
+      ),
+    }))
+    .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+
+/**
+ * 构建章节目录。
+ *
+ * **分组只看 `type`，绝不看目录名** —— 作者可能把剧情放进 `system/`、
+ * 把菜单放进 `chapter1/`。按目录分组会把它们错分。
+ * **目录只表达「作者的编排意图」，类型才表达「运行语义」。**
+ */
+export function buildChapterIndex(
+  inputs: readonly ChapterInput[],
+): ChapterIndex {
+  const nodes: ChapterNode[] = inputs.map(({ path, column }) => ({
+    id: column.id,
+    label: chapterLabelOf(path),
+    group: chapterGroupOf(column),
+    type: column.type,
+    path,
+    commandCount: commandCountOf(column),
+  }));
+  const byCodeUnit = (a: ChapterNode, b: ChapterNode): number =>
+    a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
+  const story = nodes.filter((n) => n.group === "story").sort(byCodeUnit);
+  const ui = nodes.filter((n) => n.group === "ui").sort(byCodeUnit);
+
+  // 目录分组：按 `chapterDirOf` 归并（**任意深度**：目录路径原样做键）
+  const dirs = new Map<string, ChapterNode[]>();
+  for (const node of nodes) {
+    const dir = chapterDirOf(node.path);
+    // 0 层平铺：路径不含 `/` ⇒ dir 为空串 ⇒ **不进目录分组**（退化为平铺列表）
+    if (dir === "") continue;
+    const bucket = dirs.get(dir);
+    if (bucket === undefined) dirs.set(dir, [node]);
+    else bucket.push(node);
+  }
+  const dirNodes: ChapterDir[] = [...dirs.entries()]
+    .map(([path, children]) => ({
+      label:
+        path
+          .slice(0, path.length - 1)
+          .split("/")
+          .pop() ?? path,
+      path,
+      children: [...children].sort(byCodeUnit),
+    }))
+    // 排序键用**完整路径**而非显示名——两个不同路径可能同名（同层不同章），
+    // 用显示名排会抖动（两边都叫 chapter1 时顺序不定）
+    .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+
+  return {
+    story,
+    ui,
+    // `dirs` = **全局目录清单**（不分 type；保留给「按目录浏览」这类不分组的视图）
+    dirs: dirNodes,
+    // 面板**按组展示** ⇒ 用分组版（否则界面组的目录会混进剧情节点）
+    storyDirs: dirsOfGroup(nodes, "story"),
+    uiDirs: dirsOfGroup(nodes, "ui"),
+    flat: dirNodes.length === 0,
+  };
+}
+
+/** 汇总文案（面板/状态栏用；**不逐条罗列**） */
+export function chapterSummaryText(index: ChapterIndex): string {
+  if (index.story.length === 0 && index.ui.length === 0) return "无场景";
+  const parts: string[] = [];
+  if (index.story.length > 0) parts.push(`${index.story.length} 个剧情`);
+  if (index.ui.length > 0) parts.push(`${index.ui.length} 个界面`);
+  return parts.join(" · ");
+}

package/src/chapters/index.ts

@@ -0,0 +1,34 @@
+/**
+ * 故事章节树 · **纯判据**（可测，无 IO / 无 Vue）。
+ *
+ * 存在理由：左栏原按「资源种类」平铺，但工程实践揭示了**另一个骨架**——
+ * `Stories/` 与 `Lang/` 常**按章节分目录**
+ * （`chapter1/chapter1.story`、`Lang/en-US/chapter1/chapter1.json`），
+ * 且 `Lang/` 有**三种布局并存**（en 平铺 / en-US 子目录分类 / ja 单文件）。
+ * ⇒ **内容骨架是「章节」，不是文件**；文件怎么摆是**作者的自由**。
+ *
+ * **任意深度递归，不写死「一级 = 章节」**：常见工程恰好只到 1 层
+ * （`Stories/chapter1/chapter1.story`），也有 0 层平铺
+ * （`Stories/start.json`）；而 `Lang/en-US/system/about.json` 已到 2 层
+ * ⇒ 按层数写死会错。
+ * 0 层平铺工程退化为「无章节分组的全平铺列表」，**不报错**。
+ *
+ * 域出口：本文件**只做转发**（类型声明见 `./types`、判据与装配实现见 `./build`）。
+ */
+
+export {
+  buildChapterIndex,
+  chapterDirOf,
+  chapterGroupOf,
+  chapterLabelOf,
+  chapterSummaryText,
+  sceneTypeBadgeOf,
+} from "./build.ts";
+
+export type {
+  ChapterDir,
+  ChapterGroup,
+  ChapterIndex,
+  ChapterInput,
+  ChapterNode,
+} from "./types.ts";

package/src/chapters/types.ts

@@ -0,0 +1,71 @@
+/**
+ * 故事章节树 · **类型声明**（叶子模块：只声明形状，不 import 任何兄弟模块）。
+ *
+ * 类型放叶子：出口 `./index.ts` 与实现 `./build.ts` 都要用这些形状，
+ * 声明在两者任一侧都会让对方反向依赖。
+ *
+ * 语义与设计约定见出口 `./index.ts` 头注。
+ */
+
+import type { StoryColumn } from "@lingfan-engine/core";
+
+/** 章节树分组：剧情（可回溯）/ 界面（不参与历史与存档） */
+export type ChapterGroup = "story" | "ui";
+
+/** 一个章节（= 一个故事场景；**章节名取自所在目录链，不取自文件名**） */
+export interface ChapterNode {
+  /** 章节标识（= 列 id，全局唯一） */
+  readonly id: string;
+  /** 章节显示名（取自路径末级目录；0 层平铺时取文件名去后缀） */
+  readonly label: string;
+  /** 该章节的场景所属分组（由 `type` 决定，**不按目录猜**） */
+  readonly group: ChapterGroup;
+  /**
+   * 原始场景类型（列的 `type` 字段原样透传；`undefined` = 缺省 game）。
+   * 分组判定只吃 `group`；要**精确到 菜单/界面** 的展示走 `sceneTypeBadgeOf(node.type)`
+   * （`group=ui` 只说明「不可回溯」，不说明是哪一种）。
+   */
+  readonly type: StoryColumn["type"];
+  /** 章节在文件树中的位置（逻辑路径，用于联动资源树选中） */
+  readonly path: string;
+  /** 章节内命令条数（展示用；0 = 未知） */
+  readonly commandCount: number;
+}
+
+/** 目录分组（**任意深度**：目录即章节组，叶子才是故事） */
+export interface ChapterDir {
+  /** 目录名（单层展示名；完整路径在 `path`） */
+  readonly label: string;
+  /** 目录逻辑路径（末尾带 `/`） */
+  readonly path: string;
+  readonly children: readonly ChapterNode[];
+}
+
+/** 组装入参：路径 + 列（两者按 `id` 关联） */
+export interface ChapterInput {
+  /** 故事文件的逻辑路径（如 `Stories/chapter1/chapter1.story`） */
+  readonly path: string;
+  readonly column: StoryColumn;
+}
+
+export interface ChapterIndex {
+  /** 剧情组（可回溯）——排序：路径码元序（确定性） */
+  readonly story: readonly ChapterNode[];
+  /** 界面组（menu/ui） */
+  readonly ui: readonly ChapterNode[];
+  /** 目录分组（**只含子目录**；0 层平铺工程为空数组） */
+  readonly dirs: readonly ChapterDir[];
+  /**
+   * **按组过滤的目录**（剧情组）。
+   *
+   * 为何要拆：目录是**作者的编排**，`type` 是**运行语义**——两者**正交**，
+   * 一个目录里可能既有剧情又有界面（如 `system/` 里放 `about`(menu) + `sandbox`(game)）。
+   * 而面板先按 type 分组展示（剧情 / 界面），故目录要**跟着组走**：
+   * 若直接用全局 `dirs`，界面组的目录里会混进剧情节点。
+   */
+  readonly storyDirs: readonly ChapterDir[];
+  /** 按组过滤的目录（界面组） */
+  readonly uiDirs: readonly ChapterDir[];
+  /** 是否为**平铺工程**（无任何子目录分组）—— UI 据此决定要不要显示「章节」标题 */
+  readonly flat: boolean;
+}

package/src/contracts/diagnostics.ts

@@ -0,0 +1,62 @@
+/**
+ * 诊断契约：编辑期诊断统一形态，pointer = RFC 6901 JSON Pointer（指向 Story 树）。
+ */
+
+import type { EditorTexts } from "./texts.ts";
+
+export type DiagnosticSeverity = "error" | "warning";
+
+export interface Diagnostic {
+  /** 诊断码：unknown-op / unknown-field / missing-required / invalid-value / duplicate-column / missing-target / unknown-function / undefined-variable / missing-resource / missing-entry / invalid-structure / unused-translation / missing-translation / invalid-element / unimplemented-element-attr */
+  code: string;
+  severity: DiagnosticSeverity;
+  message: string;
+  /** RFC 6901 JSON Pointer，指向 Story 树内位置（如 /columns/0/commands/3/text） */
+  pointer: string;
+  /** 涉及的 op（结构诊断时附带） */
+  op?: string;
+}
+
+/** 符号索引：columnId / defines 键 / 变量 / 函数 / 跳转目标 / 资源引用 / 可翻译原文 */
+export interface SymbolIndex {
+  /** columnId → 首个同名列的指针（重复列另见 duplicateColumns） */
+  columnPointers: Map<string, string>;
+  duplicateColumns: { id: string; pointer: string }[];
+  entry: string;
+  /** 变量定义键 → 首个定义处指针（含 defines / set / define / let / local / array / dict / random.var / 循环变量 / input.store） */
+  definedKeys: Map<string, string>;
+  /** 函数名 → 参数与定义处（func op） */
+  functions: Map<string, { params: string[]; pointer: string }>;
+  /** 跳转/调用目标引用（jump/menu/navigate → column；call → function） */
+  targets: {
+    pointer: string;
+    target: string;
+    /**
+     * 目标种类：
+     * - `column`：只能指向列（jump / menu 选项）
+     * - `function`：只能指向 func（无）
+     * - `callable`：**两者皆可**（`call` —— 语义是「func 或 label」）
+     */
+    kind: "column" | "function" | "callable";
+  }[];
+  /** 资源逻辑路径引用（resource kind 字段 + say.voice） */
+  resources: { pointer: string; path: string }[];
+  /** 表达式/插值中的变量引用（undefined-variable 诊断与 `_` 豁免的输入） */
+  variableRefs: {
+    pointer: string;
+    name: string;
+    kind: "expression" | "interpolation";
+  }[];
+  /** 可翻译原文集合（say.text/speaker、menu.prompt、menu.options[].text、input.prompt、notify.text、元素 text——走运行期 Translate；character.screen 仅编辑器比对面，运行期不翻） */
+  originals: Set<string>;
+}
+
+/** analyzeStory 可选供给侧数据：缺省时对应诊断族跳过（不误报） */
+export interface AnalyzeOptions {
+  /** 资源根内实际文件集合（相对 Resources/ 的逻辑路径）→ 资源路径缺失诊断 */
+  resourceFiles?: ReadonlySet<string>;
+  /** overlay 译文键集合（Lang/{lang} 合并后）→ 未使用翻译键诊断（翻译缺口检查器） */
+  overlayKeys?: ReadonlySet<string>;
+  /** 集中文案表注入（缺省 defaultEditorTexts，即编辑器的既有文案） */
+  texts?: Partial<EditorTexts>;
+}

package/src/contracts/editing.ts

@@ -0,0 +1,26 @@
+/**
+ * 编辑核心契约：故事树纯映射器（只读写故事 JSON，不碰运行时/Rust）+
+ * 统一 undo（所有视图共享，一次提交 = 一个 undo 单元）。
+ */
+
+import type { Story } from "@lingfan-engine/core";
+
+/** 一次编辑提交（一个 undo 单元）：before/after 以不可变结构共享 */
+export interface UndoEntry {
+  label: string;
+  before: Story;
+  after: Story;
+}
+
+/** 编辑器会话观察者：任何视图提交后收到新故事树（一处改动全视图同步） */
+export type StoryListener = (story: Story) => void;
+
+/** 命令容器（两类列） */
+export type ContainerField = "commands" | "entry" | "elements";
+
+/** 列的命令容器元数据：flow → commands；scene → entry（入口命令）与 elements（元素） */
+export interface ContainerInfo {
+  columnId: string;
+  columnPointer: string;
+  kind: "scene" | "flow";
+}