@lingfan-engine/editor 0.1.0 → 0.1.3

package/src/script/expr/build.ts

@@ -1,203 +1,203 @@
-/**
- * 表达式标签的装配：把模板字面量拼成 `{…}` 文本，插值按句柄与字面量规则渲染。
- *
- * 组装同时做构建期轻类型校验（判类器在 `./audit`）：警告进池、由
- * `drainExpressionWarnings` 取走；表达式产物与既有行为逐字节一致（校验零侵入）。
- */
-
-import {
-  currentRegistry,
-  isVarHandle,
-  varKeyOf,
-  warningSink,
-  type ExpressionWarning,
-  type VarKind,
-} from "./registry.ts";
-import { ExpressionAuditor, type AuditToken, type OperandKind } from "./audit/index.ts";
-import { defaultEditorTexts } from "../../contracts/index.ts";
-
-/**
- * expr 标签函数的文案取缺省表（例外登记）：模板标签函数无法携带可选参数注入，
- * 这四条是构建期开发者诊断（缺省不可变直引，无模块级 setter）。
- * varKeyOf / ExpressionAuditor 的文案仍走调用点注入。
- */
-const texts = defaultEditorTexts;
-
-/**
- * 表达式标签：`expr\`${vars.player.gold} >= 25\` ⇒ "{player.gold >= 25}"`。
- * 插值规则：VarHandle ⇒ 注册键（未注册抛错）；number/boolean ⇒ 字面量；
- * string ⇒ JSON 字面量（带引号，与引擎字符串字面量口径一致）。
- *
- * 组装同时做轻类型校验（见文件头）：警告进池，由 `drainExpressionWarnings` 取走；
- * 表达式产物与既有行为逐字节一致（校验零侵入）。
- *
- * 产物是 `"{…}"` 表达式串：引擎在**执行到包含它的命令时**求值——
- * 条件语境（{@link when} / whileDo）求出布尔；赋值语境（{@link set} 等）
- * 求出值；台词/通知文本在显示时插值。
- *
- * 必须先经 defineVars 注册变量，否则抛错。
- *
- * @param strings 模板字面量的静态片段。
- * @param parts 插值：变量句柄 / number / boolean / string。
- * @returns `"{…}"` 表达式串（放进故事数据，运行期求值）。
- * @example
- * expr`${vars.player.gold} >= 25`   // ⇒ "{player.gold >= 25}"
- * expr`${vars.greeting}, 旅行者`    // string 插值 ⇒ 带引号字面量
- */
-export function expr(
-  strings: TemplateStringsArray,
-  ...parts: unknown[]
-): string {
-  const registry = currentRegistry;
-  if (registry === null) {
-    throw new Error(texts.exprRequiresDefineVars());
-  }
-  const tokens: AuditToken[] = [];
-  const pending: Array<{ rule: ExpressionWarning["rule"]; message: string }> =
-    [];
-  // 引号状态跨片段/插值跟踪（`"pre${name}post"` 的吞并 footgun：插值会被并进字面量）
-  let quote: string | null = null;
-  let escaped = false;
-
-  /** 片段词法：引号（跨片段）、双字运算符优先、字面量/数字/标识符；括号与结构标点进流 */
-  const lexFragment = (segment: string): void => {
-    for (let i = 0; i < segment.length; i += 1) {
-      const ch = segment[i]!;
-      if (quote !== null) {
-        if (escaped) {
-          escaped = false;
-          continue;
-        }
-        if (ch === "\\") {
-          escaped = true;
-          continue;
-        }
-        if (ch === quote) quote = null;
-        continue;
-      }
-      if (ch === '"' || ch === "'") {
-        quote = ch;
-        tokens.push({ t: "operand", kind: "str", label: "字符串字面量" });
-        continue;
-      }
-      const two = segment.slice(i, i + 2);
-      if (
-        two === "==" ||
-        two === "!=" ||
-        two === "&&" ||
-        two === "||" ||
-        two === ">=" ||
-        two === "<="
-      ) {
-        tokens.push({ t: "op", text: two });
-        i += 1;
-        continue;
-      }
-      if ("+-*/%<>!".includes(ch)) {
-        tokens.push({ t: "op", text: ch });
-        continue;
-      }
-      if ("(),?:.[]".includes(ch)) {
-        tokens.push({ t: "punct", text: ch });
-        continue;
-      }
-      if (/[0-9]/.test(ch)) {
-        let j = i;
-        while (j < segment.length && /[0-9.]/.test(segment[j]!)) j += 1;
-        const literal = segment.slice(i, j);
-        i = j - 1;
-        tokens.push({ t: "operand", kind: "num", label: literal });
-        continue;
-      }
-      if (/[A-Za-z_]/.test(ch)) {
-        let j = i;
-        while (j < segment.length && /[A-Za-z0-9_]/.test(segment[j]!)) j += 1;
-        const word = segment.slice(i, j);
-        i = j - 1;
-        tokens.push(
-          word === "true" || word === "false"
-            ? { t: "operand", kind: "bool", label: word }
-            : { t: "operand", kind: "unknown", label: word },
-        );
-        continue;
-      }
-      // 其余字符（空白等）：词法噪声，不进流
-    }
-  };
-
-  /** 插值贡献（文本 + 判类）：产物文本与既有行为逐字节一致（校验零侵入） */
-  const appendPart = (
-    part: unknown,
-  ): { text: string; kind: OperandKind; label: string } => {
-    if (isVarHandle(part)) {
-      const key = varKeyOf(part, registry, texts);
-      return { text: key, kind: part.kind, label: `变量 ${key}` };
-    }
-    if (typeof part === "number" || typeof part === "boolean") {
-      return {
-        text: String(part),
-        kind: typeof part as VarKind,
-        label: String(part),
-      };
-    }
-    if (typeof part === "string") {
-      return {
-        text: JSON.stringify(part),
-        kind: "str",
-        label: JSON.stringify(part),
-      };
-    }
-    throw new Error(
-      texts.unsupportedInterpolationType(typeof part),
-    );
-  };
-
-  let out = "{";
-  strings.forEach((segment, i) => {
-    lexFragment(segment);
-    out += segment;
-    if (i >= parts.length) return;
-    const part = parts[i];
-    if (quote !== null) {
-      // 校验零侵入：警告照记，但文本照旧并入产物（与既有行为逐字节一致）
-      pending.push({
-        rule: "interpolation-inside-string",
-        message: texts.interpolationInsideString(),
-      });
-      out += appendPart(part).text;
-      return;
-    }
-    const applied = appendPart(part);
-    out += applied.text;
-    tokens.push({ t: "operand", kind: applied.kind, label: applied.label });
-  });
-
-  const finalize = (): string => `${out}}`;
-  if (quote !== null) {
-    // 字面量到表达式末尾都没闭合：引擎将 parse-error——类型核查无意义，只报这一条
-    pending.push({
-      rule: "unclosed-string-literal",
-      message: texts.unclosedStringLiteral(),
-    });
-    warningSink.push(
-      ...pending.map((item) => ({ expression: finalize(), ...item })),
-    );
-    return finalize();
-  }
-  new ExpressionAuditor(tokens, pending, texts).audit();
-  for (const item of pending) {
-    warningSink.push({ expression: finalize(), ...item });
-  }
-  return finalize();
-}
-
-/**
- * `expr` 的别名（条件语境的语义化写法；同一实现、同一校验）。
- *
- * @param strings 模板字面量的静态片段。
- * @param parts 插值：变量句柄 / number / boolean / string。
- * @returns `"{…}"` 条件表达式串（引擎执行条件命令时求值，须产出布尔）。
- * @example
- * when(cond`${vars.door.locked} == false`, [navigate("hall")]);
- */
-export const cond = expr;
+/**
+ * 表达式标签的装配：把模板字面量拼成 `{…}` 文本，插值按句柄与字面量规则渲染。
+ *
+ * 组装同时做构建期轻类型校验（判类器在 `./audit`）：警告进池、由
+ * `drainExpressionWarnings` 取走；表达式产物与既有行为逐字节一致（校验零侵入）。
+ */
+
+import {
+  currentRegistry,
+  isVarHandle,
+  varKeyOf,
+  warningSink,
+  type ExpressionWarning,
+  type VarKind,
+} from "./registry.ts";
+import { ExpressionAuditor, type AuditToken, type OperandKind } from "./audit/index.ts";
+import { defaultEditorTexts } from "../../contracts/index.ts";
+
+/**
+ * expr 标签函数的文案取缺省表（例外登记）：模板标签函数无法携带可选参数注入，
+ * 这四条是构建期开发者诊断（缺省不可变直引，无模块级 setter）。
+ * varKeyOf / ExpressionAuditor 的文案仍走调用点注入。
+ */
+const texts = defaultEditorTexts;
+
+/**
+ * 表达式标签：`expr\`${vars.player.gold} >= 25\` ⇒ "{player.gold >= 25}"`。
+ * 插值规则：VarHandle ⇒ 注册键（未注册抛错）；number/boolean ⇒ 字面量；
+ * string ⇒ JSON 字面量（带引号，与引擎字符串字面量口径一致）。
+ *
+ * 组装同时做轻类型校验（见文件头）：警告进池，由 `drainExpressionWarnings` 取走；
+ * 表达式产物与既有行为逐字节一致（校验零侵入）。
+ *
+ * 产物是 `"{…}"` 表达式串：引擎在**执行到包含它的命令时**求值——
+ * 条件语境（{@link when} / whileDo）求出布尔；赋值语境（{@link set} 等）
+ * 求出值；台词/通知文本在显示时插值。
+ *
+ * 必须先经 defineVars 注册变量，否则抛错。
+ *
+ * @param strings 模板字面量的静态片段。
+ * @param parts 插值：变量句柄 / number / boolean / string。
+ * @returns `"{…}"` 表达式串（放进故事数据，运行期求值）。
+ * @example
+ * expr`${vars.player.gold} >= 25`   // ⇒ "{player.gold >= 25}"
+ * expr`${vars.greeting}, 旅行者`    // string 插值 ⇒ 带引号字面量
+ */
+export function expr(
+  strings: TemplateStringsArray,
+  ...parts: unknown[]
+): string {
+  const registry = currentRegistry;
+  if (registry === null) {
+    throw new Error(texts.exprRequiresDefineVars());
+  }
+  const tokens: AuditToken[] = [];
+  const pending: Array<{ rule: ExpressionWarning["rule"]; message: string }> =
+    [];
+  // 引号状态跨片段/插值跟踪（`"pre${name}post"` 的吞并 footgun：插值会被并进字面量）
+  let quote: string | null = null;
+  let escaped = false;
+
+  /** 片段词法：引号（跨片段）、双字运算符优先、字面量/数字/标识符；括号与结构标点进流 */
+  const lexFragment = (segment: string): void => {
+    for (let i = 0; i < segment.length; i += 1) {
+      const ch = segment[i]!;
+      if (quote !== null) {
+        if (escaped) {
+          escaped = false;
+          continue;
+        }
+        if (ch === "\\") {
+          escaped = true;
+          continue;
+        }
+        if (ch === quote) quote = null;
+        continue;
+      }
+      if (ch === '"' || ch === "'") {
+        quote = ch;
+        tokens.push({ t: "operand", kind: "str", label: "字符串字面量" });
+        continue;
+      }
+      const two = segment.slice(i, i + 2);
+      if (
+        two === "==" ||
+        two === "!=" ||
+        two === "&&" ||
+        two === "||" ||
+        two === ">=" ||
+        two === "<="
+      ) {
+        tokens.push({ t: "op", text: two });
+        i += 1;
+        continue;
+      }
+      if ("+-*/%<>!".includes(ch)) {
+        tokens.push({ t: "op", text: ch });
+        continue;
+      }
+      if ("(),?:.[]".includes(ch)) {
+        tokens.push({ t: "punct", text: ch });
+        continue;
+      }
+      if (/[0-9]/.test(ch)) {
+        let j = i;
+        while (j < segment.length && /[0-9.]/.test(segment[j]!)) j += 1;
+        const literal = segment.slice(i, j);
+        i = j - 1;
+        tokens.push({ t: "operand", kind: "num", label: literal });
+        continue;
+      }
+      if (/[A-Za-z_]/.test(ch)) {
+        let j = i;
+        while (j < segment.length && /[A-Za-z0-9_]/.test(segment[j]!)) j += 1;
+        const word = segment.slice(i, j);
+        i = j - 1;
+        tokens.push(
+          word === "true" || word === "false"
+            ? { t: "operand", kind: "bool", label: word }
+            : { t: "operand", kind: "unknown", label: word },
+        );
+        continue;
+      }
+      // 其余字符（空白等）：词法噪声，不进流
+    }
+  };
+
+  /** 插值贡献（文本 + 判类）：产物文本与既有行为逐字节一致（校验零侵入） */
+  const appendPart = (
+    part: unknown,
+  ): { text: string; kind: OperandKind; label: string } => {
+    if (isVarHandle(part)) {
+      const key = varKeyOf(part, registry, texts);
+      return { text: key, kind: part.kind, label: `变量 ${key}` };
+    }
+    if (typeof part === "number" || typeof part === "boolean") {
+      return {
+        text: String(part),
+        kind: typeof part as VarKind,
+        label: String(part),
+      };
+    }
+    if (typeof part === "string") {
+      return {
+        text: JSON.stringify(part),
+        kind: "str",
+        label: JSON.stringify(part),
+      };
+    }
+    throw new Error(
+      texts.unsupportedInterpolationType(typeof part),
+    );
+  };
+
+  let out = "{";
+  strings.forEach((segment, i) => {
+    lexFragment(segment);
+    out += segment;
+    if (i >= parts.length) return;
+    const part = parts[i];
+    if (quote !== null) {
+      // 校验零侵入：警告照记，但文本照旧并入产物（与既有行为逐字节一致）
+      pending.push({
+        rule: "interpolation-inside-string",
+        message: texts.interpolationInsideString(),
+      });
+      out += appendPart(part).text;
+      return;
+    }
+    const applied = appendPart(part);
+    out += applied.text;
+    tokens.push({ t: "operand", kind: applied.kind, label: applied.label });
+  });
+
+  const finalize = (): string => `${out}}`;
+  if (quote !== null) {
+    // 字面量到表达式末尾都没闭合：引擎将 parse-error——类型核查无意义，只报这一条
+    pending.push({
+      rule: "unclosed-string-literal",
+      message: texts.unclosedStringLiteral(),
+    });
+    warningSink.push(
+      ...pending.map((item) => ({ expression: finalize(), ...item })),
+    );
+    return finalize();
+  }
+  new ExpressionAuditor(tokens, pending, texts).audit();
+  for (const item of pending) {
+    warningSink.push({ expression: finalize(), ...item });
+  }
+  return finalize();
+}
+
+/**
+ * `expr` 的别名（条件语境的语义化写法；同一实现、同一校验）。
+ *
+ * @param strings 模板字面量的静态片段。
+ * @param parts 插值：变量句柄 / number / boolean / string。
+ * @returns `"{…}"` 条件表达式串（引擎执行条件命令时求值，须产出布尔）。
+ * @example
+ * when(cond`${vars.door.locked} == false`, [navigate("hall")]);
+ */
+export const cond = expr;

package/src/script/expr/registry.ts

@@ -1,130 +1,130 @@
-/**
- * 变量注册表与句柄：显式注册制的声明面。
- *
- * 引擎表达式是字符串、求值归引擎，本层只负责生成表达式文本——
- * `defineVars` 声明一个故事源用到的变量（IDE 补全与拼写检查由此而来），
- * 句柄树的叶子是 `VarHandle`，装配期按注册表核对：未注册的引用直接抛错。
- *
- * 注册表与警告池是模块态，一次导入 = 一个故事源。
- */
-
-import type { EditorTexts } from "../../contracts/index.ts";
-import { resolveEditorTexts } from "../../contracts/index.ts";
-
-/** 变量种类（注册时声明；构建期轻校验的判类依据） */
-export type VarKind = "num" | "str" | "bool";
-
-export interface VarHandle {
-  readonly kind: VarKind;
-  /** 引擎状态键（如 `player.gold`） */
-  readonly key: string;
-}
-
-const VAR_KINDS: ReadonlySet<string> = new Set(["num", "str", "bool"]);
-
-/** 真句柄 = kind 为三种之一且 key 为字符串——未注册子树 Proxy 的 kind 是对象，判否 */
-export function isVarHandle(value: unknown): value is VarHandle {
-  if (typeof value !== "object" || value === null) return false;
-  const candidate = value as { kind?: unknown; key?: unknown };
-  return (
-    typeof candidate.kind === "string" &&
-    VAR_KINDS.has(candidate.kind) &&
-    typeof candidate.key === "string"
-  );
-}
-
-/** 嵌套句柄树（`vars.player.gold` ⇒ handle{key: "player.gold"}） */
-export interface VarTree {
-  [prop: string]: VarTree | VarHandle;
-}
-
-/** 当前注册表（`expr` 标签读取；`defineVars` 绑定——每个故事源文件声明一次） */
-export let currentRegistry: ReadonlyMap<string, VarKind> | null = null;
-
-/** 构建期警告池（与 currentRegistry 同范式的模块态：一次导入 = 一个故事源；drain 后清零；装配层写入） */
-export let warningSink: ExpressionWarning[] = [];
-
-/**
- * 取走并清空构建期警告。stories-build 在源模块导入完成后调用一次进 BuildReport；
- * 连续两次调用，第二次必为空（drain 即清零）。
- */
-export function drainExpressionWarnings(): readonly ExpressionWarning[] {
-  const out = warningSink;
-  warningSink = [];
-  return out;
-}
-
-/**
- * 构建期轻类型校验警告（引擎 type-error 的构建期预告；不拦构建）。
- * 规则名与引擎 `runtime/expr/` 的类型规则一一对应（见 `ExpressionAuditor`）。
- */
-export interface ExpressionWarning {
-  /** 完整表达式文本（含 `{}` 包装） */
-  readonly expression: string;
-  readonly rule:
-    | "arith-non-num"
-    | "compare-non-num"
-    | "equality-kind-mismatch"
-    | "logical-non-bool"
-    | "unary-not-non-bool"
-    | "unary-minus-non-num"
-    | "ternary-cond-non-bool"
-    | "interpolation-inside-string"
-    | "unclosed-string-literal";
-  /** 人话说明（含引擎将抛的 type-error 语义与出错操作数） */
-  readonly message: string;
-}
-
-function makeTree(
-  prefix: string,
-  handles: ReadonlyMap<string, VarHandle>,
-  texts: EditorTexts,
-): VarTree {
-  return new Proxy({} as VarTree, {
-    get(_target, prop): VarTree | VarHandle {
-      if (typeof prop !== "string" || prop === "then") {
-        throw new Error(texts.invalidVarHandlePath(String(prop), prefix || "(根)"));
-      }
-      const key = prefix === "" ? prop : `${prefix}.${prop}`;
-      const handle = handles.get(key);
-      if (handle !== undefined) return handle;
-      // 未注册路径：继续给子树 Proxy（链式展开），expr 求值时校验终值
-      return makeTree(key, handles, texts);
-    },
-  });
-}
-
-/**
- * 声明变量清单并绑定为本文件的 `expr` 上下文。
- * 每个故事源文件调用一次（重复调用 = 覆盖前一份注册表——源文件间的变量清单
- * 各自独立声明，不共享）。
- *
- * ```ts
- * const vars = defineVars({ "player.gold": "num", "player.name": "str" });
- * cond`${vars.player.gold} >= 25` // ⇒ "{player.gold >= 25}"
- * ```
- */
-export function defineVars(
-  spec: Record<string, VarKind>,
-  texts: Partial<EditorTexts> = {},
-): VarTree {
-  const t = resolveEditorTexts(texts);
-  currentRegistry = new Map(Object.entries(spec));
-  const handles = new Map<string, VarHandle>(
-    Object.entries(spec).map(([key, kind]) => [key, { kind, key }]),
-  );
-  return makeTree("", handles, t);
-}
-
-/** 句柄对应的注册键（expr 内部用；未注册 ⇒ 抛错——拼写错误在构建期就红） */
-export function varKeyOf(
-  handle: VarHandle,
-  registry: ReadonlyMap<string, VarKind>,
-  texts: Partial<EditorTexts> = {},
-): string {
-  const t = resolveEditorTexts(texts);
-  if (!registry.has(handle.key)) {
-    throw new Error(t.unregisteredVariable(handle.key));
-  }
-  return handle.key;
-}
+/**
+ * 变量注册表与句柄：显式注册制的声明面。
+ *
+ * 引擎表达式是字符串、求值归引擎，本层只负责生成表达式文本——
+ * `defineVars` 声明一个故事源用到的变量（IDE 补全与拼写检查由此而来），
+ * 句柄树的叶子是 `VarHandle`，装配期按注册表核对：未注册的引用直接抛错。
+ *
+ * 注册表与警告池是模块态，一次导入 = 一个故事源。
+ */
+
+import type { EditorTexts } from "../../contracts/index.ts";
+import { resolveEditorTexts } from "../../contracts/index.ts";
+
+/** 变量种类（注册时声明；构建期轻校验的判类依据） */
+export type VarKind = "num" | "str" | "bool";
+
+export interface VarHandle {
+  readonly kind: VarKind;
+  /** 引擎状态键（如 `player.gold`） */
+  readonly key: string;
+}
+
+const VAR_KINDS: ReadonlySet<string> = new Set(["num", "str", "bool"]);
+
+/** 真句柄 = kind 为三种之一且 key 为字符串——未注册子树 Proxy 的 kind 是对象，判否 */
+export function isVarHandle(value: unknown): value is VarHandle {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as { kind?: unknown; key?: unknown };
+  return (
+    typeof candidate.kind === "string" &&
+    VAR_KINDS.has(candidate.kind) &&
+    typeof candidate.key === "string"
+  );
+}
+
+/** 嵌套句柄树（`vars.player.gold` ⇒ handle{key: "player.gold"}） */
+export interface VarTree {
+  [prop: string]: VarTree | VarHandle;
+}
+
+/** 当前注册表（`expr` 标签读取；`defineVars` 绑定——每个故事源文件声明一次） */
+export let currentRegistry: ReadonlyMap<string, VarKind> | null = null;
+
+/** 构建期警告池（与 currentRegistry 同范式的模块态：一次导入 = 一个故事源；drain 后清零；装配层写入） */
+export let warningSink: ExpressionWarning[] = [];
+
+/**
+ * 取走并清空构建期警告。stories-build 在源模块导入完成后调用一次进 BuildReport；
+ * 连续两次调用，第二次必为空（drain 即清零）。
+ */
+export function drainExpressionWarnings(): readonly ExpressionWarning[] {
+  const out = warningSink;
+  warningSink = [];
+  return out;
+}
+
+/**
+ * 构建期轻类型校验警告（引擎 type-error 的构建期预告；不拦构建）。
+ * 规则名与引擎 `runtime/expr/` 的类型规则一一对应（见 `ExpressionAuditor`）。
+ */
+export interface ExpressionWarning {
+  /** 完整表达式文本（含 `{}` 包装） */
+  readonly expression: string;
+  readonly rule:
+    | "arith-non-num"
+    | "compare-non-num"
+    | "equality-kind-mismatch"
+    | "logical-non-bool"
+    | "unary-not-non-bool"
+    | "unary-minus-non-num"
+    | "ternary-cond-non-bool"
+    | "interpolation-inside-string"
+    | "unclosed-string-literal";
+  /** 人话说明（含引擎将抛的 type-error 语义与出错操作数） */
+  readonly message: string;
+}
+
+function makeTree(
+  prefix: string,
+  handles: ReadonlyMap<string, VarHandle>,
+  texts: EditorTexts,
+): VarTree {
+  return new Proxy({} as VarTree, {
+    get(_target, prop): VarTree | VarHandle {
+      if (typeof prop !== "string" || prop === "then") {
+        throw new Error(texts.invalidVarHandlePath(String(prop), prefix || "(根)"));
+      }
+      const key = prefix === "" ? prop : `${prefix}.${prop}`;
+      const handle = handles.get(key);
+      if (handle !== undefined) return handle;
+      // 未注册路径：继续给子树 Proxy（链式展开），expr 求值时校验终值
+      return makeTree(key, handles, texts);
+    },
+  });
+}
+
+/**
+ * 声明变量清单并绑定为本文件的 `expr` 上下文。
+ * 每个故事源文件调用一次（重复调用 = 覆盖前一份注册表——源文件间的变量清单
+ * 各自独立声明，不共享）。
+ *
+ * ```ts
+ * const vars = defineVars({ "player.gold": "num", "player.name": "str" });
+ * cond`${vars.player.gold} >= 25` // ⇒ "{player.gold >= 25}"
+ * ```
+ */
+export function defineVars(
+  spec: Record<string, VarKind>,
+  texts: Partial<EditorTexts> = {},
+): VarTree {
+  const t = resolveEditorTexts(texts);
+  currentRegistry = new Map(Object.entries(spec));
+  const handles = new Map<string, VarHandle>(
+    Object.entries(spec).map(([key, kind]) => [key, { kind, key }]),
+  );
+  return makeTree("", handles, t);
+}
+
+/** 句柄对应的注册键（expr 内部用；未注册 ⇒ 抛错——拼写错误在构建期就红） */
+export function varKeyOf(
+  handle: VarHandle,
+  registry: ReadonlyMap<string, VarKind>,
+  texts: Partial<EditorTexts> = {},
+): string {
+  const t = resolveEditorTexts(texts);
+  if (!registry.has(handle.key)) {
+    throw new Error(t.unregisteredVariable(handle.key));
+  }
+  return handle.key;
+}