@lingfan-engine/editor 0.0.0-stage → 0.1.2

package/src/script/words/narrative.ts

@@ -0,0 +1,261 @@
+/**
+ * Script 词汇层 · **叙事域**（say / menu / input / notify / nvl / character）。
+ * 产物 = StoryCommand 数据（与 JSON 同族）；形状知识只在此处，作者只说人话。
+ * 返回类型 = `CommandOf<op>`（派生自 OP_SCHEMA_MAP，与 validateCommand 同源）——
+ * builder 形状漂移（漏字段 / 错字段）编译期报红，不再只靠互锁测试兜底。
+ */
+import type { CommandOf } from "../../schema/index.ts";
+import type { KnownColumnName, KnownInterpolationKey } from "./cells.ts";
+
+// —— `{key}` 插值键的编译期校验（纯类型层，零运行期成本）——
+//
+// 只在**字符串字面量**上生效：模板串、变量、宽 string 全部放行（动态文本没法查，
+// 也不该吓唬作者）；键表来自生成物 `Stories.src/gen/stories.gen.d.ts`。
+// 富文本行内标记必须豁免——`{b}`/`{color=#FFD700}` 这类与插值共用一个花括号语法，
+// 豁免表对齐引擎 `runtime/expr/interpolate.ts` 的行内标记集。
+type TrimText<S extends string> = S extends ` ${infer R}`
+  ? TrimText<R>
+  : S extends `${infer R} `
+    ? TrimText<R>
+    : S;
+
+type InlineTextTag =
+  | "b"
+  | "/b"
+  | "i"
+  | "/i"
+  | "u"
+  | "/u"
+  | "w"
+  | "fast"
+  | "p"
+  | `color=${string}`
+  | "/color"
+  | `font=${string}`
+  | "/font"
+  | `size=${string}`
+  | "/size";
+
+/** `{key:00}` 的 `:格式` 后缀先剥掉再查表 */
+type StripTextFormat<S extends string> = S extends `${infer K}:${string}`
+  ? TrimText<K>
+  : TrimText<S>;
+
+/** 查表失败时把这个键留在参数类型里，报错信息即可读出是哪个键 */
+type BadInterpolationKey<K extends string> = {
+  readonly __插值键未登记: K;
+};
+
+type CheckTextAt<
+  S extends string,
+  Whole extends string,
+> = S extends `${string}{${infer Inner}}${infer Rest}`
+  ? StripTextFormat<Inner> extends InlineTextTag
+    ? CheckTextAt<Rest, Whole>
+    : StripTextFormat<Inner> extends KnownInterpolationKey
+      ? CheckTextAt<Rest, Whole>
+      : BadInterpolationKey<StripTextFormat<Inner>>
+  : Whole;
+
+/** 文本参数类型：字面量按 `{…}` 逐键校验，非字面量原样放行 */
+export type InterpolatedText<S extends string> = S & CheckTextAt<S, S>;
+
+/** say 的可选项（say 负载中除 text / speaker 外的全部字段，均可省略） */
+export type SayOptions = Omit<CommandOf<"say">, "op" | "text" | "speaker">;
+
+/**
+ * 让角色说一句话：玩家看到一句对话，点击或按键后故事才继续。
+ *
+ * - 文本先查翻译表，再做 `{var}` 插值（`{var:00}` 保留两位小数）；插值失败
+ *   保留原文显示并发出错误事件，不中断故事。
+ * - 进入等待的这一刻就是回溯检查点；开启 autoSave 时这里是自动存档点。
+ * - `color` 只覆盖本句说话人颜色（优先于角色定义）；`voice` 播放本句语音，
+ *   句子推进后自动停止；`instant` / `typewriter` 控制打字机显示；
+ *   `template` 指定本句对话框模板（优先于角色定义的 screen）。
+ *
+ * @param text 台词；可含 `{var}` 插值，在显示时求值。必填非空。
+ *   字面量文本的插值键在编译期对表（生成物注册表），拼错即红；富文本行内标记豁免。
+ * @param speaker 说话人显示名（同样支持翻译与插值）；省略则本句不显示说话人名。
+ * @param opts 其余可选项，见 {@link SayOptions}。
+ * @returns `say` 故事命令，写进当前列即为一句对话。
+ * @example
+ * say("欢迎来到 {place}！", "向导");
+ * say("上好绸缎，客官……", "商人", { color: "#FFD700", voice: "audio/hi.ogg" });
+ */
+export function say<const S extends string>(
+  text: InterpolatedText<S>,
+  speaker?: string,
+  opts?: SayOptions,
+): CommandOf<"say"> {
+  return {
+    op: "say",
+    text,
+    ...(speaker === undefined ? {} : { speaker }),
+    ...opts,
+  };
+}
+
+/**
+ * 菜单选项的**命令参数**形态：一项显示文字 + 选中后跳去的目标列名（列名收窄到已知列）。
+ *
+ * 与运行期的读取面（引擎 `MenuChoice`：文本与目标列成对）不是同一条链：这里供作者写脚本，
+ * 目标列名会在生成物存在时收窄成字面量联合，故单独命名，避免与读取面的同形状类型混用。
+ */
+export type MenuOptionSpec = CommandOf<"menu">["options"][number];
+
+/**
+ * 构造一个菜单选项，配合 {@link menu} 使用：玩家点中这一项后，
+ * 故事跳进 `target` 指向的那一列（列名即标签）继续。
+ * @param text 选项上显示的文字（支持翻译与插值）。
+ * @param target 选中后进入的目标列名（`stories.gen.d.ts` 存在时收窄为列名字面量联合）。
+ * @returns 菜单选项数据。
+ * @example
+ * menu("去哪儿？", [
+ *   option("酒馆", "to_inn"),
+ *   option("广场", "to_square"),
+ * ]);
+ */
+export function option(text: string, target: KnownColumnName): MenuOptionSpec {
+  return { text, target };
+}
+
+/**
+ * 弹出一张选项菜单：玩家看到 `prompt`（可省略）与若干选项，选中一项后
+ * 故事跳进该选项的目标列继续。
+ *
+ * - 选项文字与提示语都走翻译表；等待期间建立回溯检查点。
+ * - 菜单出现前会清掉上一句对话的残留画面。
+ *
+ * @param prompt 菜单上方的问题/提示语；省略则只显示选项。
+ * @param options 选项列表（至少一项），用 {@link option} 构造。
+ * @returns `menu` 故事命令。
+ * @example
+ * menu("先做什么？", [
+ *   option("买药水", "shop"),
+ *   option("打听消息", "gossip"),
+ * ]);
+ */
+export function menu(
+  prompt: string | undefined,
+  options: readonly MenuOptionSpec[],
+): CommandOf<"menu"> {
+  return {
+    op: "menu",
+    ...(prompt === undefined ? {} : { prompt }),
+    options: [...options],
+  };
+}
+
+/**
+ * 向玩家要一段文字：弹出输入框显示 `prompt`，玩家提交后，输入内容写进
+ * 状态键 `store`，故事从下一句继续。
+ *
+ * 等待期间建立回溯检查点；开启 autoSave 时此处自动存档。
+ *
+ * @param prompt 输入框上方显示的问题/提示语（必填非空）。
+ * @param store 收纳玩家输入的状态变量名（写进全局状态，之后可用 `{store}` 插值显示）。
+ * @returns `input` 故事命令。
+ * @example
+ * input("主角叫什么名字？", "playerName");
+ * say("你好，{playerName}！");
+ */
+export function input(prompt: string, store: string): CommandOf<"input"> {
+  return { op: "input", prompt, store };
+}
+
+/** type 保持手写的窄联合（schema 是 string）——作者侧补全优于校验面放宽 */
+export interface NotifyOptions {
+  type?: "info" | "success" | "warning" | "error";
+  duration?: number;
+  z?: number;
+}
+
+/**
+ * 弹一条系统通知（toast）：在画面上短暂显示 `text` 后自动消失，
+ * 故事不等待、立即执行下一句。
+ *
+ * - 通知是一次性画面效果，不进存档/回溯状态。
+ * - 文本先查翻译表再做 `{var}` 插值（同 {@link say}）。
+ *
+ * @param text 通知内容（必填非空）；插值键同 {@link say} 在编译期对表。
+ * @param opts 可选项：type 决定样式（info/success/warning/error，缺省 info）、
+ *   duration 控制停留时长、z 控制层级。
+ * @returns `notify` 故事命令。
+ * @example
+ * notify("已保存", { type: "success" });
+ */
+export function notify<const S extends string>(
+  text: InterpolatedText<S>,
+  opts?: NotifyOptions,
+): CommandOf<"notify"> {
+  return { op: "notify", text, ...opts };
+}
+
+/**
+ * NVL 命令的模式参数：作者在脚本里写的动作（`enter` 进入累积层 / `auto` 跟随 / `clear` 清屏 / `exit` 退出）。
+ *
+ * 与引擎的 `NvlMode`（`none` / `active` / `clear` / `exit`）**不是同一套取值**：那是运行期
+ * `__nvl_mode` 的状态值，这里是命令参数，两者语义不同、不可互换。
+ */
+export type NvlCommandMode = NonNullable<CommandOf<"nvl">["mode"]>;
+
+/**
+ * 切换 NVL（整屏文本）模式。本命令立即生效、故事继续，不等待。
+ *
+ * - `"enter"`（缺省）：激活 NVL，此后每句 {@link say} 的文本都会累积
+ *   显示在整屏文本框里，直到退出。
+ * - `"auto"`：同 enter，激活累积层。
+ * - `"clear"`：清空已累积的文本，但仍处于 NVL 模式。
+ * - `"exit"`：清空并退出 NVL，回到普通对话框显示。
+ *
+ * 累积文本属于核心状态：回溯、存档/读档自动保持一致。
+ *
+ * @param mode NVL 动作，缺省 `"enter"`。
+ * @returns `nvl` 故事命令。
+ * @example
+ * nvl();            // 进入整屏文本模式
+ * say("第一段……");
+ * nvl("clear");     // 清屏，继续整屏
+ * nvl("exit");      // 退出整屏，恢复对话框
+ */
+export function nvl(mode?: NvlCommandMode): CommandOf<"nvl"> {
+  return { op: "nvl", ...(mode === undefined ? {} : { mode }) };
+}
+
+export type CharacterOptions = Omit<CommandOf<"character">, "op" | "key">;
+
+/**
+ * 注册（或更新）一名角色：说话人名字、颜色、字号、字体、文字颜色、
+ * 对话框模板。立即生效、故事继续，不等待。
+ *
+ * 注意：对同一 `key` 重复调用会**整体替换**定义——本次没传的字段
+ * 会回到无定义状态，而不是保留上次值。
+ *
+ * @param key 角色键（say 的 speaker 名按它查表取样式）。
+ * @param opts 角色属性：name 显示名、color 说话人颜色、size 字号、
+ *   font 字体、textColor 台词文字颜色、screen 对话框模板。
+ * @returns `character` 故事命令。
+ * @example
+ * character("向导", { name: "阿岚", color: "#7FD4FF" });
+ * say("跟上我。", "向导");
+ */
+export function character(
+  key: string,
+  opts?: CharacterOptions,
+): CommandOf<"character"> {
+  return { op: "character", key, ...opts };
+}
+
+/**
+ * 注销一名角色：之后以该 `key` 作说话人的 say 不再套角色样式。
+ * 键不存在时发 `character.missing` 知情事件（故事继续，不停机）——
+ * 创作者可在宿主的事件回调里自行处置（记日志/提示等）。
+ * 注销会随回溯自然回滚（回到注册后的检查点即恢复角色）。
+ * @param key 角色键（与 character 的 key 同一面）。
+ * @returns `uncharacter` 故事命令。
+ * @example
+ * uncharacter("向导");
+ */
+export function uncharacter(key: string): CommandOf<"uncharacter"> {
+  return { op: "uncharacter", key };
+}

package/src/script/words/save.ts

@@ -0,0 +1,54 @@
+/**
+ * Script 词汇层 · **存档域**（save / load / auto_save / save_delete）。
+ */
+import type { CommandOf } from "../../schema/index.ts";
+
+/**
+ * 声明一个存档点：把「存进槽位 `slot`」记下来，等到**下一个玩家所见
+ * 等待画面**（对话/菜单/输入等）出现时才真正写盘——保证存档画面
+ * 可重放重建。声明本身立即继续，不等待。
+ * @param slot 槽位名（字母/数字/_/-，1–64 字符）。
+ * @param title 存档显示名（可省略）。
+ * @returns `save` 故事命令。
+ * @example
+ * say("要休息了吗？");
+ * save("inn", "客栈过夜");
+ */
+export function save(slot: string, title?: string): CommandOf<"save"> {
+  return { op: "save", slot, ...(title === undefined ? {} : { title }) };
+}
+
+/**
+ * 读档传送：从槽位 `slot` 异步读档，画面与状态整体回到存档时刻，
+ * 故事从存档时的等待画面继续。
+ * @param slot 槽位名。
+ * @returns `load` 故事命令。
+ * @example
+ * menu("回到存档点？", [option("是", "do_load"), option("否", "stay")]);
+ */
+export function load(slot: string): CommandOf<"load"> {
+  return { op: "load", slot };
+}
+
+/**
+ * 开关自动存档：开启后，每个玩家所见等待画面建立时都会自动写入
+ * 自动存档槽。开关本身随存档/读档一并恢复。
+ * @param enabled true = 开启自动存档。
+ * @returns `auto_save` 故事命令。
+ * @example
+ * autoSave(true);
+ */
+export function autoSave(enabled: boolean): CommandOf<"auto_save"> {
+  return { op: "auto_save", enabled };
+}
+
+/**
+ * 删除槽位 `slot` 的存档（异步执行；不影响回档基准）。
+ * @param slot 槽位名。
+ * @returns `save_delete` 故事命令。
+ * @example
+ * saveDelete("inn");
+ */
+export function saveDelete(slot: string): CommandOf<"save_delete"> {
+  return { op: "save_delete", slot };
+}

package/src/script/words/vars.ts

@@ -0,0 +1,155 @@
+/**
+ * Script 词汇层 · **变量域**（set / define / let / local / undef / array / dict）。
+ * value 参数 = 引擎 StateValue（字面量 / null / `{expr}` 表达式串 / `+=` 复合赋值串——
+ * 口径同 JSON v1；状态槽允许 null 空值，销毁走 undef）。
+ */
+import type { CommandOf, StateScriptValue } from "../../schema/index.ts";
+
+/**
+ * 把值写进状态变量：沿作用域链找到 `key` 已声明的层写入；
+ * 找不到声明层就写进全局状态（全局变量随快照/存档/回溯走）。
+ *
+ * - `value` 传字面量直接存；传 `"{expr}"` 表达式串则在运行到这里时求值。
+ * - 支持复合赋值串 `"+= 1"` / `"-= 2"` / `"*= 3"` / `"/= 4"` / `"%= 5"`
+ *   （只对数字有意义；除以 0 直接报错停机）。
+ *
+ * @param key 变量名（之后用 `{key}` 插值显示）。
+ * @param value 字面量（含 null 空值）或 `"{expr}"` 表达式串。
+ * @returns `set` 故事命令。
+ * @example
+ * set("gold", 100);
+ * set("medal", null);           // 状态槽空值占位
+ * set("gold", "{gold + 50}");   // 表达式在运行期求值
+ * set("gold", "+= 10");
+ */
+export function set(key: string, value: StateScriptValue): CommandOf<"set"> {
+  return { op: "set", key, value };
+}
+
+/**
+ * 声明全局变量的初值：**只在变量不存在时生效**（重复执行/重复经过
+ * 不会覆盖已有值）。适合做关卡开场的默认设定。
+ * @param key 全局变量名。
+ * @param value 初值（字面量或 `"{expr}"` 表达式串）。
+ * @returns `define` 故事命令。
+ * @example
+ * define("visitedInn", false);
+ */
+export function define(key: string, value: StateScriptValue): CommandOf<"define"> {
+  return { op: "define", key, value };
+}
+
+/**
+ * 在**当前最内层作用域**声明一个临时变量（块/列级）：出了这段作用域
+ * 自动销毁，不进存档。适合循环计数、分支内临时值。
+ * @param key 变量名。
+ * @param value 初值（字面量或 `"{expr}"` 表达式串）。
+ * @returns `let` 故事命令。
+ * @example
+ * letVar("i", 0);
+ */
+export function letVar(key: string, value: StateScriptValue): CommandOf<"let"> {
+  return { op: "let", key, value };
+}
+
+/**
+ * 同 {@link letVar}：在当前最内层作用域声明临时变量（不进存档）。
+ * @param key 变量名。
+ * @param value 初值（字面量或 `"{expr}"` 表达式串）。
+ * @returns `local` 故事命令。
+ * @example
+ * localVar("tmp", "{gold * 2}");
+ */
+export function localVar(key: string, value: StateScriptValue): CommandOf<"local"> {
+  return { op: "local", key, value };
+}
+
+/**
+ * 销毁变量（沿作用域链与全局层查找）。变量不存在时故事报错停机
+ * （fail-closed），便于暴露拼写错误。
+ * @param key 要销毁的变量名。
+ * @returns `undef` 故事命令。
+ */
+export function undef(key: string): CommandOf<"undef"> {
+  return { op: "undef", key };
+}
+
+/**
+ * 创建全局数组：`items` 逐项求值（项可为 `"{expr}"`）后存进全局状态。
+ * `once: true` 时数组已存在则跳过，不覆盖（幂等声明）。
+ * @param key 数组变量名。
+ * @param items 初始元素列表。
+ * @param opts 可选项：once 已存在则跳过。
+ * @returns `array` 故事命令。
+ * @example
+ * newArray("party", ["alice", "bob"], { once: true });
+ */
+export function newArray(
+  key: string,
+  items: readonly StateScriptValue[],
+  opts?: { once?: boolean },
+): CommandOf<"array"> {
+  return { op: "array", key, items: [...items], ...opts };
+}
+
+/**
+ * 向**已存在**的数组末尾追加一个值（值可为 `"{expr}"`）。目标不存在或
+ * 不是数组时故事报错停机。逐个压入：多件就多次调用。
+ * @param key 目标数组变量名。
+ * @param value 要追加的值。
+ * @returns `array_push` 故事命令。
+ * @example
+ * arrayPush("party", "carol");
+ */
+export function arrayPush(
+  key: string,
+  value: StateScriptValue,
+): CommandOf<"array_push"> {
+  return { op: "array_push", key, value };
+}
+
+/**
+ * 移除数组末尾一个元素（移除即丢弃）。目标不存在、非数组或已空时
+ * 故事报错停机。
+ * @param key 目标数组变量名。
+ * @returns `array_pop` 故事命令。
+ */
+export function arrayPop(key: string): CommandOf<"array_pop"> {
+  return { op: "array_pop", key };
+}
+
+/**
+ * 创建全局字典（JSON 对象：字段名 → 值，值可为 `"{expr}"`）。
+ * `once: true` 时字典已存在则跳过，不覆盖。
+ * @param key 字典变量名。
+ * @param record 字段与初值的映射。
+ * @param opts 可选项：once 已存在则跳过。
+ * @returns `dict` 故事命令。
+ * @example
+ * dict("hero", { hp: 30, mp: 10 }, { once: true });
+ */
+export function dict(
+  key: string,
+  record: Record<string, StateScriptValue>,
+  opts?: { once?: boolean },
+): CommandOf<"dict"> {
+  return { op: "dict", key, value: { ...record }, ...opts };
+}
+
+/**
+ * 修改字典的单个字段（值可为 `"{expr}"`）。目标不存在或不是字典时
+ * 故事报错停机。
+ * @param key 目标字典变量名。
+ * @param field 字段名。
+ * @param value 新值。
+ * @returns `dict_set` 故事命令。
+ * @example
+ * dictSet("hero", "hp", "{hero.hp - 5}");
+ */
+export function dictSet(
+  key: string,
+  field: string,
+  value: StateScriptValue,
+): CommandOf<"dict_set"> {
+  return { op: "dict_set", key, field, value };
+}

package/src/script/words/video.ts

@@ -0,0 +1,80 @@
+/**
+ * Script 词汇层 · **视频域**（video / cutscene / seek / pause / resume / stop / skipable）。
+ * Options 派生自 schema（零漂移）；返回类型 = `CommandOf<op>` 判别联合成员。
+ */
+import type { CommandOf } from "../../schema/index.ts";
+
+/** video / cutscene 共用的可选项：volume 音量、loop 循环、z 视频层层级 */
+export type VideoOptions = Omit<CommandOf<"video">, "op" | "resource">;
+
+/**
+ * 播放视频（非阻塞）：画面切到视频层，故事**立即继续**执行下一句，
+ * 视频在背景里继续播。
+ * @param resource 视频资源路径。
+ * @param opts 可选项：volume 音量、loop 循环、z 层级。
+ * @returns `video` 故事命令。
+ * @example
+ * video("video/opening.mp4");
+ */
+export function video(
+  resource: string,
+  opts?: VideoOptions,
+): CommandOf<"video"> {
+  return { op: "video", resource, ...opts };
+}
+
+export type CutsceneOptions = Omit<CommandOf<"cutscene">, "op" | "resource">;
+
+/**
+ * 播放过场（阻塞）：故事**等待**视频播完（或被玩家跳过）才继续。
+ * 过场开始时建立回溯检查点；开启 autoSave 时此处自动存档。
+ *
+ * 可跳过性：显式传 `skipable` 优先；否则用 {@link videoSkipable} 的全局
+ * 开关；两者都未设置时缺省可跳过。
+ *
+ * @param resource 视频资源路径。
+ * @param opts 可选项：volume 音量、loop 循环、skipable 可点击跳过、z 层级。
+ * @returns `cutscene` 故事命令。
+ * @example
+ * cutscene("video/intro.mp4", { skipable: true });
+ */
+export function cutscene(
+  resource: string,
+  opts?: CutsceneOptions,
+): CommandOf<"cutscene"> {
+  return { op: "cutscene", resource, ...opts };
+}
+
+/**
+ * 把当前视频跳转到第 `seconds` 秒（立即生效，故事继续）。
+ * @param seconds 目标时刻（秒）。
+ * @returns `seek_video` 故事命令。
+ */
+export function seekVideo(seconds: number): CommandOf<"seek_video"> {
+  return { op: "seek_video", seconds };
+}
+
+/** 暂停当前视频（立即生效，故事继续）。@returns `pause_video` 故事命令。 */
+export function pauseVideo(): CommandOf<"pause_video"> {
+  return { op: "pause_video" };
+}
+
+/** 继续播放已暂停的视频（立即生效，故事继续）。@returns `resume_video` 故事命令。 */
+export function resumeVideo(): CommandOf<"resume_video"> {
+  return { op: "resume_video" };
+}
+
+/** 停止并关闭当前视频层（立即生效，故事继续）。@returns `stop_video` 故事命令。 */
+export function stopVideo(): CommandOf<"stop_video"> {
+  return { op: "stop_video" };
+}
+
+/**
+ * 设置「视频可跳过」全局开关（持久生效，影响之后的视频与过场；
+ * 过场显式传 skipable 时以其为准）。立即生效、故事继续。
+ * @param value true = 允许玩家跳过视频。
+ * @returns `video_skipable` 故事命令。
+ */
+export function videoSkipable(value: boolean): CommandOf<"video_skipable"> {
+  return { op: "video_skipable", value };
+}

package/src/shared/guards.ts

@@ -0,0 +1,19 @@
+/**
+ * 通用取值判据：编辑器包多个域（诊断、i18n、布局）都要对「这个值是不是一条记录」下判断。
+ *
+ * 为什么放在共享层：判据本身不含业务含义，任何层都可以引用；而它一旦分叉，
+ * 分叉点就是静默的行为差异——同一棵树，两处判定不同就会出现「这边认、那边不认」。
+ * 所以编辑器包只有这一处实现，缺人少写一个 `!Array.isArray` 就是症状的来源。
+ */
+
+/**
+ * 是否是**普通对象**（JSON 意义上的记录）：`null` 与数组都不算。
+ *
+ * 关键在最后那个 `!Array.isArray`：数组也是 `typeof === "object"`，
+ * 少了它就会让数组通过「记录」校验，下游会拿下标当字段名继续走。
+ */
+export function isPlainObject(
+  value: unknown,
+): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/shared/index.ts

@@ -0,0 +1,6 @@
+/**
+ * 共享层出口：没有业务含义、任何域都可以引用的取值判据与小工具。
+ * 实现按用途分文件，域外消费方只从这里取。
+ */
+export { escapePointerToken, joinPointer } from "./pointer.ts";
+export { isPlainObject } from "./guards.ts";

package/src/shared/pointer.ts

@@ -0,0 +1,23 @@
+/**
+ * JSON Pointer（RFC 6901）的拼装工具：转义单段、拼出整串。
+ *
+ * 为什么放在共享层：诊断、结构校验、步骤布局都要产出指向 Story 树的 pointer，
+ * 契约层只声明「pointer 是一个字符串」，拼法本身是可执行逻辑。
+ * 规则只有这一处实现——改口径则全部消费方同步，不会出现半套转义。
+ */
+
+/**
+ * 转义 JSON Pointer 的单段：`~` 写 `~0`，`/` 写 `~1`。
+ *
+ * 顺序要紧：必须先替换 `~`。反过来的话，先产出的 `~1` 会被随后的 `~` 替换
+ * 二次转义成 `~01`，解析回去得到的是另一条路径。
+ */
+export function escapePointerToken(token: string | number): string {
+  return String(token).replaceAll("~", "~0").replaceAll("/", "~1");
+}
+
+/** 由段序列组装 JSON Pointer：没有段即根（空串），否则每段前加 `/` 并逐段转义 */
+export function joinPointer(...segments: (string | number)[]): string {
+  if (segments.length === 0) return "";
+  return "/" + segments.map(escapePointerToken).join("/");
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.