@lingfan-engine/stories-build 0.0.0-stage → 0.1.2

package/src/pipeline/watch.ts

@@ -0,0 +1,244 @@
+/**
+ * 创作期增量监听（`pnpm stories:watch`）：常驻进程内监听源目录变更，防抖合并后
+ * 重跑 `buildStories`。编译始终全量——不引入第二套编译规则，任何一轮的产物都与
+ * `stories:build` 一致；差量落盘由 `emitArtifacts` 完成。
+ *
+ * `affectedStories` 提供改动的波及面报告（反向依赖闭包），仅用于日志呈现，
+ * 不参与编译。
+ */
+import { watch } from "node:fs";
+import { join, resolve } from "node:path";
+import { DEFAULT_SOURCES_DIR, buildStories } from "./index.ts";
+import type { StoryBuildOptions } from "./orchestrate.ts";
+import { walkFiles } from "../shared/index.ts";
+
+/** 相对导入抽取（单双引号皆可；type 导入同算依赖——保守向） */
+const REL_IMPORT_RE = /(?:^|[\s;])from\s+["'](\.{1,2}\/[^"']+)["']/g;
+
+/**
+ * 从一段 TS 源文本抽取相对导入说明符（去扩展名与 /index 后缀的规范化模块路径，
+ * 与图谱层的模块键同形）。
+ */
+function extractRelImports(text: string): string[] {
+  const specs: string[] = [];
+  for (const match of text.matchAll(REL_IMPORT_RE)) {
+    specs.push(match[1]!);
+  }
+  return specs;
+}
+
+/** 规范化相对说明符 → 模块键（`./a/b` → `a/b`、`../lib/x.ts` → `lib/x`、`./x/index` → `x`） */
+function normalizeSpec(spec: string, fromDir: string): string {
+  const parts = `${fromDir}/${spec}`.split("/");
+  const out: string[] = [];
+  for (const part of parts) {
+    if (part === "." || part === "") continue;
+    if (part === "..") out.pop();
+    else out.push(part);
+  }
+  let key = out.join("/");
+  key = key.replace(/\.ts$/, "").replace(/\/index$/, "");
+  return key;
+}
+
+/**
+ * 反向依赖闭包：给「改动文件集合」求「受影响的故事文件集合」。
+ * 输入 = 全部源文件文本（相对工程根 posix 路径 → 文本，含 Stories.src/config.ts）；
+ * 闭包沿「谁导入了我」逐层展开，只有命中故事文件（default 导出列）才算受影响列。
+ */
+export function affectedStories(
+  changed: readonly string[],
+  sourceTexts: ReadonlyMap<string, string>,
+): string[] {
+  // 模块键 → 文件 posix 相对路径（config.ts 与故事/模块文件都进索引）
+  const byModuleKey = new Map<string, string>();
+  for (const rel of sourceTexts.keys()) {
+    const normalized = rel.replace(/\.ts$/, "").replace(/\/index$/, "");
+    byModuleKey.set(normalized, rel);
+  }
+  // 反向边：模块键 → 直接引用它的文件集合
+  const importers = new Map<string, Set<string>>();
+  for (const [rel, text] of sourceTexts) {
+    const dir = rel.includes("/") ? rel.slice(0, rel.lastIndexOf("/")) : "";
+    for (const spec of extractRelImports(text)) {
+      const key = normalizeSpec(spec, dir);
+      const target = byModuleKey.get(key);
+      if (target === undefined) continue;
+      const set = importers.get(target);
+      if (set === undefined) importers.set(target, new Set([rel]));
+      else set.add(rel);
+    }
+  }
+  // 故事文件判据：default export function（与 story-compiler 的故事形态对齐）
+  const storyOf = new Map<string, string>();
+  for (const [rel, text] of sourceTexts) {
+    if (/export\s+default\s+function\s+\w/.test(text)) storyOf.set(rel, rel);
+  }
+  const affected = new Set<string>();
+  const queue = [...changed];
+  while (queue.length > 0) {
+    const rel = queue.pop()!;
+    if (affected.has(rel)) continue;
+    affected.add(rel);
+    for (const importer of importers.get(rel) ?? []) {
+      queue.push(importer);
+    }
+  }
+  return [...affected].filter((rel) => storyOf.has(rel)).sort();
+}
+
+/** `watchStories` 的可配置项：在 `StoryBuildOptions` 之上只加监听节奏两旋钮。 */
+export interface WatchStoriesOptions extends StoryBuildOptions {
+  /** 变更后合并再编译的等待毫秒数（缺省 150） */
+  readonly debounceMs?: number;
+  /** 轮间打印回调（缺省 console.log；可注入收集器静默） */
+  readonly log?: (message: string) => void;
+}
+
+/** 一次变更轮的结果：产物差量 + 受影响故事集 */
+export interface WatchRoundReport {
+  /** 本轮产物差量（相对上一轮落盘状态；语义同 `BuildReport.added/updated/removed`） */
+  added: string[];
+  updated: string[];
+  removed: string[];
+  /** 本轮改动波及的故事源（反向依赖闭包，仅呈现） */
+  affectedStories: string[];
+  /** 本轮是否编译成功（失败时 added/updated/removed 为空数组） */
+  ok: boolean;
+}
+
+/** 源树与字体目录的监听目标（相对工程根） */
+const WATCHED_FONT_DIR = join("Resources", "Fonts");
+
+/**
+ * 常驻增量监听入口：首轮全量构建落基准 → `fs.watch` 监听源目录（与字体目录，
+ * 存在才挂）→ 变更防抖后进程内重跑 `buildStories` 并把差量与受影响故事集交给
+ * 回调/日志。返回停止函数（关 watcher、落当前任务）；失败轮不终止监听——
+ * 下一次改动照常重试（创作期半成品常态）。
+ */
+export async function watchStories(
+  root: string,
+  options: WatchStoriesOptions = {},
+): Promise<() => void> {
+  const log = options.log ?? ((message: string) => console.log(message));
+  const debounceMs = options.debounceMs ?? 150;
+  const sourcesDir = resolve(root, options.sourcesDir ?? DEFAULT_SOURCES_DIR);
+  const fontsDir = resolve(root, WATCHED_FONT_DIR);
+
+  // 首轮：全量构建落基准
+  try {
+    const report = await buildStories(root, options);
+    log(firstRoundLine(report));
+  } catch (error) {
+    log(`[stories:watch] 首轮构建失败：${errorText(error)}`);
+    log("[stories:watch] 监听中——修复后保存即重试。");
+  }
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let running = false;
+  let rerun = false;
+  // 变更文件集合（防抖窗口内累计；"rename"/目录级事件给不准路径时退化为全源扫描）
+  let pending = new Set<string>();
+
+  const runRound = async (): Promise<void> => {
+    if (running) {
+      rerun = true;
+      return;
+    }
+    running = true;
+    const changed = [...pending];
+    pending = new Set();
+    try {
+      const sourceTexts = readSourceTexts(root, options);
+      const affected = affectedStories(changed, sourceTexts);
+      const report = await buildStories(root, options);
+      log(roundLine(report, affected));
+    } catch (error) {
+      log(`[stories:watch] 本轮构建失败（监听继续）：${errorText(error)}`);
+    } finally {
+      running = false;
+      if (rerun) {
+        rerun = false;
+        void runRound();
+      }
+    }
+  };
+
+  const schedule = (relPath: string | undefined): void => {
+    if (relPath !== undefined && relPath !== "") pending.add(relPath);
+    if (timer !== undefined) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = undefined;
+      void runRound();
+    }, debounceMs);
+  };
+
+  const watchers: ReturnType<typeof watch>[] = [];
+  // filename 相对监听目录；prefix 归一成与 readSourceTexts 键同型的工程相对路径
+  const mount = (dir: string, prefix: string): void => {
+    try {
+      const w = watch(dir, { recursive: true }, (_event, filename) => {
+        // filename 为 null = 平台给不准路径，退化记录哨兵（全源扫描）
+        const rel = filename === null ? undefined : String(filename);
+        schedule(
+          rel === undefined ? undefined : `${prefix}${rel.replace(/\\/g, "/")}`,
+        );
+      });
+      watchers.push(w);
+    } catch {
+      // 目录不存在（如 Fonts 未建）——跳过，不阻塞监听主目标
+    }
+  };
+  mount(sourcesDir, `${options.sourcesDir ?? DEFAULT_SOURCES_DIR}/`);
+  mount(fontsDir, `${WATCHED_FONT_DIR}/`);
+
+  return () => {
+    for (const w of watchers) w.close();
+    if (timer !== undefined) clearTimeout(timer);
+  };
+}
+
+/** 读取源文本快照：源树全部 .ts 文本（跳生成物目录），posix 相对路径 → 文本 */
+function readSourceTexts(
+  root: string,
+  options: StoryBuildOptions,
+): Map<string, string> {
+  const sourcesDirName = options.sourcesDir ?? DEFAULT_SOURCES_DIR;
+  const sourcesDir = resolve(root, sourcesDirName);
+  const texts = new Map<string, string>();
+  for (const [rel, text] of walkFiles(sourcesDir)) {
+    const posix = rel.replace(/\\/g, "/");
+    if (posix.startsWith("gen/") || !posix.endsWith(".ts")) continue;
+    texts.set(`${sourcesDirName}/${posix}`, text);
+  }
+  return texts;
+}
+
+function firstRoundLine(report: { storyId: string; columns: number }): string {
+  return `首轮构建完成：story "${report.storyId}"（${report.columns} 列），监听中——保存即重编译。`;
+}
+
+function roundLine(
+  report: { added: string[]; updated: string[]; removed: string[] },
+  affected: readonly string[],
+): string {
+  const parts: string[] = [];
+  const total =
+    report.added.length + report.updated.length + report.removed.length;
+  if (total === 0) {
+    parts.push("产物零差量");
+  } else {
+    if (report.added.length > 0) parts.push(`新增 ${report.added.length}`);
+    if (report.updated.length > 0) parts.push(`更新 ${report.updated.length}`);
+    if (report.removed.length > 0) parts.push(`清理 ${report.removed.length}`);
+  }
+  const affectedLabel =
+    affected.length === 0
+      ? "—"
+      : affected.map((rel) => rel.replace(/\.ts$/, "")).join("、");
+  return `监听轮完成（${parts.join("，")}）；波及故事：${affectedLabel}`;
+}
+
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/shared/errors.ts

@@ -0,0 +1,2 @@
+/** 构建失败（fail-closed）。消息即 CLI 打印的失败原因，逐字稳定——不要在别处重写措辞 */
+export class StoryBuildError extends Error {}

package/src/shared/index.ts

@@ -0,0 +1,11 @@
+/**
+ * 通用出口：失败类型、文件遍历与集中文案表。
+ *
+ * 这三样跨域用得多——`StoryBuildError` 被十来个文件当统一失败口径，
+ * `walkFiles` 被发现、写盘、编译器三处共同依赖，`StoriesBuildTexts` 是
+ * 构建期全部可注入文案的唯一出处（缺省实现 = 现场字符串）——放进任何
+ * 业务域都会让别的域为了一个工具反向依赖它，故单独成域。
+ */
+export { StoryBuildError } from "./errors.ts";
+export { walkFiles } from "./walk-files.ts";
+export { defaultStoriesBuildTexts, type StoriesBuildTexts } from "./texts.ts";

package/src/shared/texts.ts

@@ -0,0 +1,85 @@
+/**
+ * 集中文案表：stories-build 全部可注入的构建失败/诊断文案。
+ *
+ * 形态照 engine 的 `contracts/messages.ts`：具名方法接口 + 缺省实现对象；
+ * 缺省实现即构建层的既有文案，不传 texts 行为不变。
+ * 注入走编译入口 options（`StoryBuildOptions.texts` / `compileStories`
+ * input.texts，均接受 Partial），入口处
+ * `{ ...defaultStoriesBuildTexts, ...texts }` 合并后作为完整对象逐层透传——
+ * 纯函数管道，无模块级可变状态、无注册表。
+ *
+ * 错误码前缀（E06/E10 等）是协议值，保留在文案内：自定义文案须自行保留
+ * 前缀，否则按码检索的诊断路径（测试/工具）会失配。
+ */
+export interface StoriesBuildTexts {
+  /** E06：列 id 为空或含不安全字符（story-compiler checkColumnIds） */
+  columnIdUnsafe(id: string): string;
+  /** E06：列 id 与先前列 id 重复（大小写不敏感；story-compiler checkColumnIds） */
+  columnIdDuplicate(id: string, prev: string): string;
+  /** E10：列体顶层 return（translate/statements） */
+  topLevelReturn(): string;
+  /** E10：break 出现在循环/switch 之外（translate/statements） */
+  breakOutsideLoop(): string;
+  /** E10：continue 出现在循环之外（translate/statements） */
+  continueOutsideLoop(): string;
+  /** unknown-op 闸门长文（pipeline/gates；detail = 已折叠的 op 明细行集） */
+  unknownOpsGate(
+    detail: string,
+    resourcesDir: string,
+    manifestFile: string,
+  ): string;
+  /** guard-unknown 闸门长文（pipeline/gates；firstGuard = 首个未声明守卫名） */
+  unknownGuardsGate(
+    detail: string,
+    sourcesDir: string,
+    firstGuard: string,
+  ): string;
+  /** 覆盖外 default 导出拒绝长文（discovery；files = 覆盖外文件相对路径列表） */
+  uncoveredDefaults(files: readonly string[], sourcesDirName: string): string;
+  /** 故事文件 node_modules 值导入的失败行（const-eval-pass；含 `dir/rel:line:col` 前缀） */
+  storyNpmValueImport(
+    rel: string,
+    line: number,
+    col: number,
+    spec: string,
+    sourcesDirName: string,
+  ): string;
+  /** 模块层 const 引用了 node_modules 值导入（graph/bindings） */
+  constNpmReference(): string;
+  /** node_modules 值导入被函数体/其他语句引用（graph/bindings） */
+  npmNameConstOnly(name: string): string;
+  /** config.ts 缺失（const-eval/config-eval） */
+  configMissing(sourcesDirName: string, configFile: string): string;
+}
+
+/** 缺省文案：即 stories-build 的既有文案。 */
+export const defaultStoriesBuildTexts: StoriesBuildTexts = {
+  columnIdUnsafe: (id) => `列 id \`${id}\` 为空或含不安全字符（E06）`,
+  columnIdDuplicate: (id, prev) =>
+    `列 id \`${id}\` 与 ${prev} 重复（大小写不敏感，E06）`,
+  topLevelReturn: () => "列体顶层不能 return（E10）：return 只能在函数体内",
+  breakOutsideLoop: () => "break 在循环/switch 之外（E10）",
+  continueOutsideLoop: () => "continue 在循环之外（E10）",
+  unknownOpsGate: (detail, resourcesDir, manifestFile) =>
+    `故事使用了既非内建、也未被清单 extensions 声明扩展提供的 op（运行期必 unknown-op，构建期拦截）：\n${detail}\n` +
+    `→ 在 ${resourcesDir}/${manifestFile} 的 extensions 声明提供该 op 的扩展模块，或改用内建 op`,
+  unknownGuardsGate: (detail, sourcesDir, firstGuard) =>
+    `故事使用了未在源内 cell(...) 声明的守卫（运行期必 guard-unknown，构建期拦截）：\n${detail}\n` +
+    `→ 在 ${sourcesDir} 源里用 cell("${firstGuard}", impl) 声明实现，或改用已声明的守卫`,
+  uncoveredDefaults: (files, sourcesDirName) =>
+    [
+      "以下文件含 default 导出但未被 folders 覆盖——Stories.src 全量管理构建产物，未登记的故事会在构建时被当作陈旧产物删除：",
+      ...files.map((rel) => `- ${sourcesDirName}/${rel}`),
+      '请把所在目录加入 config.ts 的 folders（或使用 "*" 兜底）。',
+    ].join("\n"),
+  storyNpmValueImport: (rel, line, col, spec, sourcesDirName) =>
+    `- ${sourcesDirName}/${rel}:${line}:${col} 故事文件不支持 node_modules 值导入 \`${spec}\`——npm 值请收敛为纯模块的导出 const（编译期求值仅作用于纯模块），再经相对导入使用（编译期求值引用域规则）`,
+  constNpmReference: () =>
+    "模块层 const 引用了 node_modules 值导入——仅导出的 const 可经编译期求值内联（请把 npm 值收敛为导出 const，见编译期求值规则）",
+  npmNameConstOnly: (name) =>
+    `node_modules 值导入 \`${name}\` 仅限模块层 const 初始化链（编译期求值引用域规则）：函数体与其他语句不得引用`,
+  configMissing: (sourcesDirName, configFile) =>
+    `${sourcesDirName}/${configFile} 不存在——多目录 TS 源工程需要布局声明` +
+    `（export const folders/start/vars/state）：folders 声明源目录（可含 "*" 全量兜底），` +
+    `start 声明入口故事文件名`,
+};

package/src/shared/walk-files.ts

@@ -0,0 +1,18 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+/** 收集目录下全部文件（posix 相对路径 → 文本）；目录不存在 = 空集 */
+export function walkFiles(dir: string, rel = ""): Map<string, string> {
+  const out = new Map<string, string>();
+  if (!existsSync(dir)) return out;
+  for (const name of readdirSync(dir).sort()) {
+    const path = join(dir, name);
+    const key = rel === "" ? name : `${rel}/${name}`;
+    if (statSync(path).isDirectory()) {
+      for (const [child, text] of walkFiles(path, key)) out.set(child, text);
+    } else {
+      out.set(key, readFileSync(path, "utf8"));
+    }
+  }
+  return out;
+}

package/src/typegen/collect.ts

@@ -0,0 +1,107 @@
+/**
+ * 声明名收集：从产物 op 流里把「作者声明过的名字」捞出来。
+ *
+ * 这些名字是运行期变量表的内容（`{ticket}`、`{thing}` 这类插值键），既不在 stateSchema
+ * 里也不在 defineVars 清单里，只能从编译产物读——这正是「插值键校验漏报」最容易漏的一类。
+ * 字段名是引擎 op 契约，逐类照着 op 定义写死；出现新 op 时在此补一行即可。
+ */
+
+/** 声明名所在的字段：op → 该 op 里承载名字的字段名 */
+const DECL_NAME_FIELDS: Readonly<Record<string, string>> = {
+  set: "key",
+  define: "key",
+  let: "key",
+  local: "key",
+  undef: "key",
+  array: "key",
+  array_push: "key",
+  array_pop: "key",
+  dict: "key",
+  dict_set: "key",
+  // 结果绑定名：语句级 `const r = f(1)` 降糖成 call op 后唯一携带声明名的字段——
+  // 引擎把 into 无条件声明成调用方局部变量（无带值 return 时绑 null）。
+  call: "into",
+  for: "var",
+  foreach: "var",
+  random: "var",
+  input: "store",
+  minigame: "game",
+};
+
+/** op 名 → 名字取值的键；无映射返回 undefined */
+function declaredFieldOf(op: string): string | undefined {
+  return DECL_NAME_FIELDS[op];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** 读一个 op 的声明名；字段缺失或非字符串都忽略（产物形态异常不在本模块职责内） */
+function readDeclaredName(op: unknown): string | undefined {
+  if (!isRecord(op)) return undefined;
+  const opName = op.op;
+  if (typeof opName !== "string") return undefined;
+  const field = declaredFieldOf(opName);
+  if (field === undefined) return undefined;
+  const value = op[field];
+  return typeof value === "string" && value !== "" ? value : undefined;
+}
+
+/**
+ * 递归收集一段命令流里的声明名：
+ * 控制流（if/while/for/switch/when）把名字藏在 body/then/else/cases 里，
+ * `func` 自带 body、`call` 带 args 与 into 绑定名，都要照走；
+ * `minigame.reward[].key` 是奖励发到哪个变量。
+ */
+function collectFromCommands(
+  commands: readonly unknown[],
+  into: Set<string>,
+): void {
+  for (const command of commands) {
+    if (!isRecord(command)) continue;
+
+    const declared = readDeclaredName(command);
+    if (declared !== undefined) into.add(declared);
+
+    // 容器字段：值为命令数组的（body/then/else 等）
+    for (const [field, value] of Object.entries(command)) {
+      if (!Array.isArray(value)) continue;
+      if (field === "options" || field === "cases" || field === "reward")
+        continue;
+      collectFromCommands(value, into);
+    }
+
+    // cases：[{ when: string; body: Command[] }]
+    if (Array.isArray(command.cases)) {
+      for (const item of command.cases) {
+        if (!isRecord(item)) continue;
+        if (Array.isArray(item.body)) collectFromCommands(item.body, into);
+      }
+    }
+
+    // reward：[{ key: string; amount: number }]——奖励发到哪个变量也属插值键域
+    if (Array.isArray(command.reward)) {
+      for (const item of command.reward) {
+        if (!isRecord(item)) continue;
+        if (typeof item.key === "string" && item.key !== "") into.add(item.key);
+      }
+    }
+  }
+}
+
+/**
+ * 从编译产物的列集合里收集所有声明名。
+ * 排序去重后返回——同输入同输出是渲染器零随机的前提。
+ */
+export function collectDeclaredNames(
+  columns: readonly { readonly commands?: readonly unknown[] }[],
+): string[] {
+  const names = new Set<string>();
+  for (const column of columns) {
+    const commands = column.commands;
+    if (!Array.isArray(commands)) continue;
+    collectFromCommands(commands, names);
+  }
+  return [...names].sort();
+}

package/src/typegen/font-render.ts

@@ -0,0 +1,30 @@
+/**
+ * 字体名注册表的 ambient 类型面渲染器（`font` 全局常量字面量类型）。
+ *
+ * 输出 = `Stories.src/gen/font.gen.d.ts` 全文：`declare const font` 的键与值都取
+ * 注册表字体名（引号键保非标识符名可用），未注册名在 TS 面即不存在——IDE 补全只给
+ * 正名，改拼直接 TS2551。纯编译期声明，不注入运行时对象；模块自有 `font` 声明按
+ * TS 遮蔽语义优先。空注册表产出 `Record<never, never>`：TS 里空对象字面量 `{}` 会
+ * 放开任意键访问，等于放弃改拼保护，这里必须给封闭空类型。
+ */
+
+import type { FontEntry } from "../fonts/font-registry.ts";
+
+const HEADER = [
+  "/* GENERATED by stories:build (font-typegen) — 构建期自动生成，手改会在下次构建被覆盖。",
+  "   字体名注册表（Resources/Fonts 文件名去扩展名）的全局字面量类型面：键 = 值 = 字体名；",
+  "   未注册名不在本类型面，运行期字符串形态 {font=名} 仍走构建期注册表校验。 */",
+].join("\n");
+
+/** 渲染 font.gen.d.ts 全文；空注册表 = 封闭空对象（键访问改拼必报 TS2551） */
+export function renderFontTypegen(entries: readonly FontEntry[]): string {
+  const lines = entries.map(
+    (entry) =>
+      `  readonly ${JSON.stringify(entry.name)}: ${JSON.stringify(entry.name)};`,
+  );
+  const declaration =
+    lines.length === 0
+      ? "declare const font: Record<never, never>;"
+      : ["declare const font: {", ...lines, "};"].join("\n");
+  return `${HEADER}\n\n${declaration}\n`;
+}

package/src/typegen/index.ts

@@ -0,0 +1,18 @@
+/**
+ * 类型面生成器出口（唯一出口）。
+ *
+ * 生成物落 `Stories.src/gen/stories.gen.d.ts`：列名与插值键在此收窄为字面量联合类型，
+ * 拼错列名/插值键在 IDE 与 `tsc --noEmit` 阶段即红，而不是等运行期才发现。
+ */
+export { collectDeclaredNames } from "./collect.ts";
+export {
+  collectEnumTypeSlots,
+  collectEnumTypeSlotsForBuild,
+} from "./state-enum-ast.ts";
+export type { EnumSlotBuildInput, EnumTypeSlot } from "./state-enum-ast.ts";
+export { renderStateTypegen } from "./state-render.ts";
+export type { StateTypegenInput } from "./state-render.ts";
+export { renderScriptTypegen } from "./script-render.ts";
+export { renderFontTypegen } from "./font-render.ts";
+export { renderTypegen } from "./render.ts";
+export type { TypegenInput } from "./types.ts";

package/src/typegen/render.ts

@@ -0,0 +1,68 @@
+/**
+ * 类型面渲染：把收集好的字符串域落成 `Stories.src/gen/stories.gen.d.ts`。
+ *
+ * 生成物只做一件事——往 `@lingfan-engine/editor` 的注册表接口里塞字面量键。接口声明在词汇层，
+ * 经包根再导出后才可被合并；本文件必须带 `export {};`（没有它就是全局脚本，
+ * `declare module` 会整体覆盖该模块而不是合并，包出口会被抹掉）。
+ *
+ * 空集合也照常产出两个空接口：文件在、结构在，但派生类型退化为 `string`——
+ * 不拿空注册表把作者的正常写法判红。
+ */
+import type { TypegenInput } from "./types.ts";
+
+/** 生成物首行：与 gen/fun_register.g.ts 同一惯例，提醒手改会被覆盖 */
+const HEADER =
+  "/* GENERATED by stories:build (typegen) — 手改会在下次构建被覆盖 */";
+
+/** 渲染时统一走排序去重：语法树里的键序不保证稳定，同输入必须同输出 */
+function normalize(values: readonly string[]): string[] {
+  return [...new Set(values)].sort();
+}
+
+/** 渲染一段接口体；空集产出空接口（保留类型扩充点） */
+function renderRegistry(
+  lines: string[],
+  name: string,
+  keys: readonly string[],
+  extra: readonly string[] = [],
+): void {
+  lines.push(`  interface ${name} {`);
+  for (const key of normalize(keys)) {
+    lines.push(`    ${JSON.stringify(key)}: 1;`);
+  }
+  for (const line of extra) lines.push(`    ${line}`);
+  lines.push("  }");
+}
+
+/**
+ * 扩展 id → 模式索引签名行。
+ *
+ * 扩展键由扩展 op 在运行期写入（`extOp("quest", { step })` → `ext.demoquest.step`），
+ * 键集静态不可知 ⇒ 只能用模板字面量模式签名表达，枚举字面量键是错形态。
+ * 这一行是模板语法而非键名，因此**不能走 `JSON.stringify`**（那会渲染成带引号的普通键，
+ * 模式语义全丢）。id 已排序去重，行序稳定。
+ */
+function extensionSignatures(ids: readonly string[]): string[] {
+  return normalize(ids).map((id) => `[k: \`ext.${id}.\${string}\`]: 1;`);
+}
+
+/** 渲染类型面全文；末尾带换行，与 renderFunRegister 的收尾一致 */
+export function renderTypegen(input: TypegenInput): string {
+  const lines: string[] = [];
+  lines.push(HEADER);
+  lines.push("export {};");
+  lines.push("");
+  lines.push('declare module "@lingfan-engine/editor" {');
+  renderRegistry(lines, "ColumnNameRegistry", input.columns);
+
+  // 插值键域 = state 键、config.vars 键、产物声明名、扩展 id 模式四源并集（合并去重后再排序；
+  // defineKeys 现取自 config.ts 的 vars 导出——config 化换道后图谱层不再扫 defineVars）
+  renderRegistry(
+    lines,
+    "InterpolationKeyRegistry",
+    [...input.schemaKeys, ...input.defineKeys, ...input.declaredNames],
+    extensionSignatures(input.extensionPrefixes),
+  );
+  lines.push("}");
+  return `${lines.join("\n")}\n`;
+}

package/src/typegen/script-render.ts

@@ -0,0 +1,21 @@
+/**
+ * script 词汇层命名空间的 ambient 类型面渲染器（免导入直呼）。
+ *
+ * 输出 = `Stories.src/gen/script.gen.d.ts` 全文：一条全局 `declare const script`
+ * 指向 `@lingfan-engine/editor` 根出口的 `script` 命名空间类型。纯编译期声明——不注入
+ * 任何运行时对象；模块层自有同名声明按 TS 遮蔽语义优先于本全局声明，显式
+ * import 与解构形态（含重命名）不受影响。内容恒定、与工程状态无关，同输入逐字节同输出。
+ */
+
+const HEADER = [
+  "/* GENERATED by stories:build (script-typegen) — 构建期自动生成，手改会在下次构建被覆盖。",
+  "   script 词汇层命名空间的免导入直呼声明：纯编译期类型面，不注入任何运行时对象；",
+  "   显式 import 与解构形态优先于本声明（TS 遮蔽语义，重命名不受影响）。 */",
+].join("\n");
+
+const DECLARATION =
+  'declare const script: typeof import("@lingfan-engine/editor").script;';
+
+export function renderScriptTypegen(): string {
+  return `${HEADER}\n\n${DECLARATION}\n`;
+}