@faicad/faijs 0.13.0

package/dist/lang/code-to-args.js

@@ -0,0 +1,124 @@
+/**
+ * code-to-args — 单语句行 args 提取（编辑回填配套）
+ *
+ * See docs/syntax-design.md §3 (statement model ↔ StatementSummary mapping) and §6.4 (check).
+ *
+ * 宿主编辑回填（FeatureEditor.backfill / editStatement）需要从代码行
+ * 反提参数对象。此能力由 faijs 标配提供（与 parse 语义一致），
+ * 宿主不得用 acorn 自行解析（B3 修正）。
+ *
+ * 无 IR 双通道方案（2026-09-06）后实现换 MetadataExtractor 行级提取：
+ * 单行文本经哨兵参数前置声明（与 MetadataExtractor looseLocalCalls 同构）
+ * 交给 extractMetadata，取末条 op 行摘要的 positional/args。函数名、签名与
+ * 返回契约（CodeToArgsResult）不变；HostArg 引用形态保真（A-5）。
+ *
+ * F1（表达式折叠）：args 含计算表达式（binary/template/conditional/spread）时，
+ * 与 parser 折叠语义一致地**求值后返回字面值**，不抛错。
+ * 单行提取缺失参数真实值 → 前置声明用哨兵字面量 `let <id> = 0`（参数形态），
+ * 使表达式可静态折叠；宿主用 StatementSummary.hasComputedArgs 判定只读降级，
+ * 不得把折叠值写回源码（会丢失原表达式）。
+ */
+import { extractMetadata } from './metadata-extractor.js';
+import { isHostRef } from './host-arg.js';
+/**
+ * 单行提取的前置声明规则（确定性静态规则，非 try/catch 兜底）：
+ * parser 的作用域检查（inputs / 重赋值 LHS / 成员方法 receiver / args 中的
+ * 裸标识符参数引用）要求变量已声明，而单行提取天然缺失声明上下文。
+ * 规则：提取行内全部标识符（剥掉字符串字面量后），为每个非 `cad`/关键字
+ * 标识符前置一行 `let <id> = 0`（哨兵参数）。parser 对该形态只做语法
+ * 检查、不查符号表；多余声明对 varToId 仅是"可查到"，不影响目标行的
+ * args 解析结果。F1 起用哨兵参数（而非 `cad.assembly({})` 语句）——
+ * 参数值已知 → 表达式可静态折叠，满足"参数为表达式时返回折叠字面值"。
+ */
+const IDENT_RE = /[A-Za-z_$][\w$]*/g;
+const STRING_RE = /'(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*"/g;
+const NON_DECL = new Set([
+    'cad', 'const', 'let', 'true', 'false', 'null', 'undefined',
+    'await', 'return', 'new', 'typeof', 'var', 'function',
+]);
+function extractIdentifiers(line, namespaces) {
+    const withoutStrings = line.replace(STRING_RE, "''");
+    const declared = declaredByLine(withoutStrings);
+    const ids = new Set();
+    for (const m of withoutStrings.matchAll(IDENT_RE)) {
+        const id = m[0];
+        if (NON_DECL.has(id) || declared.has(id) || namespaces?.has(id))
+            continue;
+        ids.add(id);
+    }
+    return [...ids];
+}
+/**
+ * 行内自身声明的标识符（前置声明必须跳过，否则 acorn 重声明报错）：
+ * - `const/let x = ...` 的 x
+ * - `const { k1: v1, k2 } = ...` 的绑定名 v1/k2（键名 k1 不是声明，仍需前置声明——无害）
+ */
+function declaredByLine(line) {
+    const ids = new Set();
+    let m = /^\s*(?:const|let)\s+([A-Za-z_$][\w$]*)\s*=/.exec(line);
+    if (m)
+        ids.add(m[1]);
+    m = /^\s*const\s*\{([^}]*)\}\s*=/.exec(line);
+    if (m) {
+        for (const prop of m[1].split(',')) {
+            const bound = (prop.split(':')[1] ?? prop).trim();
+            const id = /^([A-Za-z_$][\w$]*)/.exec(bound);
+            if (id)
+                ids.add(id[1]);
+        }
+    }
+    return ids;
+}
+/**
+ * 解析单条语句行，提取其位置实参槽与选项对象（序列化形态，无 IR 变体语义）。
+ *
+ * true-JS-subset §4.6.3 新契约：返回 `{ positional, args }`——
+ * - `positional`: HostArg[]，按调用顺序的位置实参（字面量原样；var-ref/
+ *   param-ref/call-ref/expr-ref 以 `{kind,...}` 标记对象呈现，宿主据此降级为
+ *   只读编辑）；宿主不接触内部类型（纯数据面）。
+ * - `args`: 尾随选项对象（键值 HostArg 形态；无选项对象时为 `{}`）。
+ * 旧契约（只返回对象槽）在位置形态下会静默丢弃非对象实参——本契约显式保留全部信息。
+ *
+ * 支持的行形态（与 parser 接受的语句一致）：
+ * - `const part0 = cad.box(10, 20, 30)`
+ * - `part0 = cad.fai_drill(part0, { diameter: 5 })`（裸重赋值）
+ * - `const { front: a, back: b } = cad.fai_split(part0, { normal: [0,0,1] })`（解构）
+ * - `asm0.add_constraint({ ... })`（成员方法调用）
+ * - 位置实参为字面量/变量引用/表达式（`cad.box(10, 20, 30)`、`cad.hem(p0.solid, {...})`）
+ * - args 中的裸标识符参数引用（`cad.box(10, 20, height)`）
+ * - args 中的计算表达式（`cad.box(10, 20, base + 20)`）→ 折叠为字面值返回
+ *
+ * @param codeLine 单条语句源码行
+ * @param opts.namespaces 该脚本顶层 import 的绑定名（F2：`mech.makeHeadstock(...)`
+ *   中 `mech` 不得被前置声明为变量）。L0 不感知注册表，由宿主从脚本 imports 提供。
+ * @returns the extracted positional slot and trailing options object (both in
+ *  serialized JSON form).
+ * @throws ParseError — 行文本不是合法语句时抛出（含行号）
+ */
+export function codeToArgs(codeLine, opts) {
+    const namespaces = new Set(opts?.namespaces ?? []);
+    const decls = extractIdentifiers(codeLine, namespaces)
+        .map((id) => `let ${id} = 0`)
+        .join('\n');
+    const code = decls ? `${decls}\n${codeLine}` : codeLine;
+    // 单行提取语义：前置哨兵参数（let id = 0）在 extractMetadata 中按参数行处理；
+    // 末条 op 行摘要 = 目标行。裸本机函数 callee（makeArray 等）放行（looseLocalCalls，
+    // 与现状 codeToArgs 的 MetadataExtractor looseLocalCalls 同语义；ABI 校验延后到完整脚本上下文）。
+    const meta = extractMetadata(code, { namespaces: opts?.namespaces ?? [], looseLocalCalls: true });
+    const last = meta.lines[meta.lines.length - 1];
+    if (!last)
+        return { positional: [], args: {} };
+    // 尾随纯对象（选项槽）从 positional 切出到 args（与现状 splitTrailingOptions
+    // 同构：末位纯数据对象是选项槽；引用形态/字面量留在 positional）。
+    const positional = [...last.positional];
+    const lastArg = positional[positional.length - 1];
+    if (lastArg !== null &&
+        typeof lastArg === 'object' &&
+        !Array.isArray(lastArg) &&
+        !isHostRef(lastArg)) {
+        positional.pop();
+        return { positional, args: { ...lastArg } };
+    }
+    return { positional, args: { ...last.args } };
+}
+//# sourceMappingURL=code-to-args.js.map

package/dist/lang/code-to-args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-to-args.js","sourceRoot":"","sources":["../../src/lang/code-to-args.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * code-to-args — 单语句行 args 提取（编辑回填配套）\n *\n * See docs/syntax-design.md §3 (statement model ↔ StatementSummary mapping) and §6.4 (check).\n *\n * 宿主编辑回填（FeatureEditor.backfill / editStatement）需要从代码行\n * 反提参数对象。此能力由 faijs 标配提供（与 parse 语义一致），\n * 宿主不得用 acorn 自行解析（B3 修正）。\n *\n * 无 IR 双通道方案（2026-09-06）后实现换 MetadataExtractor 行级提取：\n * 单行文本经哨兵参数前置声明（与 MetadataExtractor looseLocalCalls 同构）\n * 交给 extractMetadata，取末条 op 行摘要的 positional/args。函数名、签名与\n * 返回契约（CodeToArgsResult）不变；HostArg 引用形态保真（A-5）。\n *\n * F1（表达式折叠）：args 含计算表达式（binary/template/conditional/spread）时，\n * 与 parser 折叠语义一致地**求值后返回字面值**，不抛错。\n * 单行提取缺失参数真实值 → 前置声明用哨兵字面量 `let <id> = 0`（参数形态），\n * 使表达式可静态折叠；宿主用 StatementSummary.hasComputedArgs 判定只读降级，\n * 不得把折叠值写回源码（会丢失原表达式）。\n */\n\nimport type { HostArg } from './host-arg'\nimport { extractMetadata } from './metadata-extractor'\nimport { isHostRef } from './host-arg'\n\n/**\n * 单行提取的前置声明规则（确定性静态规则，非 try/catch 兜底）：\n * parser 的作用域检查（inputs / 重赋值 LHS / 成员方法 receiver / args 中的\n * 裸标识符参数引用）要求变量已声明，而单行提取天然缺失声明上下文。\n * 规则：提取行内全部标识符（剥掉字符串字面量后），为每个非 `cad`/关键字\n * 标识符前置一行 `let <id> = 0`（哨兵参数）。parser 对该形态只做语法\n * 检查、不查符号表；多余声明对 varToId 仅是\"可查到\"，不影响目标行的\n * args 解析结果。F1 起用哨兵参数（而非 `cad.assembly({})` 语句）——\n * 参数值已知 → 表达式可静态折叠，满足\"参数为表达式时返回折叠字面值\"。\n */\nconst IDENT_RE = /[A-Za-z_$][\\w$]*/g\nconst STRING_RE = /'(?:[^'\\\\]|\\\\.)*'|\"(?:[^\"\\\\]|\\\\.)*\"/g\nconst NON_DECL = new Set([\n  'cad', 'const', 'let', 'true', 'false', 'null', 'undefined',\n  'await', 'return', 'new', 'typeof', 'var', 'function',\n])\n\nfunction extractIdentifiers(line: string, namespaces?: Set<string>): string[] {\n  const withoutStrings = line.replace(STRING_RE, \"''\")\n  const declared = declaredByLine(withoutStrings)\n  const ids = new Set<string>()\n  for (const m of withoutStrings.matchAll(IDENT_RE)) {\n    const id = m[0]\n    if (NON_DECL.has(id) || declared.has(id) || namespaces?.has(id)) continue\n    ids.add(id)\n  }\n  return [...ids]\n}\n\n/**\n * 行内自身声明的标识符（前置声明必须跳过，否则 acorn 重声明报错）：\n * - `const/let x = ...` 的 x\n * - `const { k1: v1, k2 } = ...` 的绑定名 v1/k2（键名 k1 不是声明，仍需前置声明——无害）\n */\nfunction declaredByLine(line: string): Set<string> {\n  const ids = new Set<string>()\n  let m = /^\\s*(?:const|let)\\s+([A-Za-z_$][\\w$]*)\\s*=/.exec(line)\n  if (m) ids.add(m[1])\n  m = /^\\s*const\\s*\\{([^}]*)\\}\\s*=/.exec(line)\n  if (m) {\n    for (const prop of m[1].split(',')) {\n      const bound = (prop.split(':')[1] ?? prop).trim()\n      const id = /^([A-Za-z_$][\\w$]*)/.exec(bound)\n      if (id) ids.add(id[1])\n    }\n  }\n  return ids\n}\n\n/**\n * `codeToArgs` 的返回契约：位置实参槽 + 尾随选项对象（HostArg 形态，纯数据无 IR）。\n */\nexport interface CodeToArgsResult {\n  positional: HostArg[]\n  args: Record<string, HostArg>\n}\n\n/**\n * 解析单条语句行，提取其位置实参槽与选项对象（序列化形态，无 IR 变体语义）。\n *\n * true-JS-subset §4.6.3 新契约：返回 `{ positional, args }`——\n * - `positional`: HostArg[]，按调用顺序的位置实参（字面量原样；var-ref/\n *   param-ref/call-ref/expr-ref 以 `{kind,...}` 标记对象呈现，宿主据此降级为\n *   只读编辑）；宿主不接触内部类型（纯数据面）。\n * - `args`: 尾随选项对象（键值 HostArg 形态；无选项对象时为 `{}`）。\n * 旧契约（只返回对象槽）在位置形态下会静默丢弃非对象实参——本契约显式保留全部信息。\n *\n * 支持的行形态（与 parser 接受的语句一致）：\n * - `const part0 = cad.box(10, 20, 30)`\n * - `part0 = cad.fai_drill(part0, { diameter: 5 })`（裸重赋值）\n * - `const { front: a, back: b } = cad.fai_split(part0, { normal: [0,0,1] })`（解构）\n * - `asm0.add_constraint({ ... })`（成员方法调用）\n * - 位置实参为字面量/变量引用/表达式（`cad.box(10, 20, 30)`、`cad.hem(p0.solid, {...})`）\n * - args 中的裸标识符参数引用（`cad.box(10, 20, height)`）\n * - args 中的计算表达式（`cad.box(10, 20, base + 20)`）→ 折叠为字面值返回\n *\n * @param codeLine 单条语句源码行\n * @param opts.namespaces 该脚本顶层 import 的绑定名（F2：`mech.makeHeadstock(...)`\n *   中 `mech` 不得被前置声明为变量）。L0 不感知注册表，由宿主从脚本 imports 提供。\n * @returns the extracted positional slot and trailing options object (both in\n *  serialized JSON form).\n * @throws ParseError — 行文本不是合法语句时抛出（含行号）\n */\nexport function codeToArgs(codeLine: string, opts?: { namespaces?: string[] }): CodeToArgsResult {\n  const namespaces = new Set(opts?.namespaces ?? [])\n  const decls = extractIdentifiers(codeLine, namespaces)\n    .map((id) => `let ${id} = 0`)\n    .join('\\n')\n  const code = decls ? `${decls}\\n${codeLine}` : codeLine\n  // 单行提取语义：前置哨兵参数（let id = 0）在 extractMetadata 中按参数行处理；\n  // 末条 op 行摘要 = 目标行。裸本机函数 callee（makeArray 等）放行（looseLocalCalls，\n  // 与现状 codeToArgs 的 MetadataExtractor looseLocalCalls 同语义；ABI 校验延后到完整脚本上下文）。\n  const meta = extractMetadata(code, { namespaces: opts?.namespaces ?? [], looseLocalCalls: true })\n  const last = meta.lines[meta.lines.length - 1]\n  if (!last) return { positional: [], args: {} }\n  // 尾随纯对象（选项槽）从 positional 切出到 args（与现状 splitTrailingOptions\n  // 同构：末位纯数据对象是选项槽；引用形态/字面量留在 positional）。\n  const positional = [...last.positional]\n  const lastArg = positional[positional.length - 1]\n  if (\n    lastArg !== null &&\n    typeof lastArg === 'object' &&\n    !Array.isArray(lastArg) &&\n    !isHostRef(lastArg as HostArg)\n  ) {\n    positional.pop()\n    return { positional, args: { ...(lastArg as Record<string, HostArg>) } }\n  }\n  return { positional, args: { ...last.args } }\n}\n"]}

package/dist/lang/codegen.d.ts

@@ -0,0 +1,72 @@
+/**
+ * codegen — 纯数据 → 文本 打印工具（宿主编辑器/测试用；L0，仅依赖 host-arg）
+ *
+ * 宿主 buildCode / 编辑重排行（editStatement → replaceCodeAt）统一走此入口。
+ * 输入是纯数据（HostArg 面），不依赖任何 IR 类型。
+ *
+ * 扁平代码格式（无 export/async/await/return/参数声明）：
+ * ```js
+ * let part0 = cad.box(10, 20, 30)
+ * part0 = cad.translate(part0, { offset: [1, 2, 3] })
+ * ```
+ *
+ * 值格式约定（确定性输出）：
+ * - vec3 → `[1,2,3]`（紧凑无空格）
+ * - 数字 → 整数直出；小数最多保留 6 位有效小数并去尾零
+ * - 字符串 → 单引号包裹
+ * - HostVarRef → 裸变量名（members 元素）
+ * - HostCallRef → `cad.faceNormal(part0)`（嵌套调用）
+ * - HostExprRef → `(expr text)`（原文加括号）
+ * - 对象字面量 → `{key:value}`（冒号，合法 JS）
+ */
+import type { HostArg } from './host-arg.js';
+/**
+ * Format a number as text: integers emit as-is; decimals retain at most 6
+ * significant fractional digits with trailing zeros stripped.
+ * @param n - the number to format.
+ * @returns the formatted text representation.
+ */
+export declare function fmtNum(n: number): string;
+/**
+ * Pure-data input for printing one faijs source line, decoupled from IR types.
+ *
+ * `positional` and `args` use `HostArg` (host-friendly types with `kind`-based
+ * discrimination).
+ */
+export interface FormatCodeLineInput {
+    callee: string;
+    /** 成员方法调用接收者变量名 */
+    receiver?: string;
+    /**
+     * 位置实参槽（HostArg 形态）：宿主可传字面量、
+     * 变量引用（`{kind:'var-ref',name}`）、参数引用（`{kind:'param-ref',name}`）、
+     * 嵌套调用（`{kind:'call-ref',callee,args,namespace?}`）、
+     * 表达式（`{kind:'expr-ref',text,refs,params}`）或纯 JsonValue，按序打印。
+     */
+    positional: HostArg[];
+    /** 产出变量名 */
+    outputs: string[];
+    /** 解构键（与 outputs 一一对应） */
+    outputKeys?: string[];
+    /**
+     * （过渡兼容）选项对象：positional 末位不是纯对象时追加为尾随选项对象。
+     * 新代码应把选项对象直接放进 positional。
+     */
+    args?: Record<string, HostArg>;
+    /** 调用命名空间（F2：第三方库 `mech.makeHeadstock(...)` → 'mech'；缺省 'cad'） */
+    namespace?: string;
+    /**
+     * outputs[0] 是否已在代码中声明：true → 裸重赋值（`part0 = ...`），
+     * false/省略 → let 声明；解构/成员调用/无输出时忽略。
+     */
+    outputDeclared?: boolean;
+}
+/**
+ * 从纯数据（非 IR 类型）打印一行 faijs 源代码。
+ *
+ * 宿主 buildCode / 编辑重排行（editStatement → replaceCodeAt）统一走此入口。
+ * @param input - the pure-data line description.
+ * @returns the printed single-line code text.
+ */
+export declare function formatCodeLine(input: FormatCodeLineInput): string;
+//# sourceMappingURL=codegen.d.ts.map

package/dist/lang/codegen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegen.d.ts","sourceRoot":"","sources":["../../src/lang/codegen.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAKzC;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAKxC;AAmDD;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAA;IACd,mBAAmB;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;OAKG;IACH,UAAU,EAAE,OAAO,EAAE,CAAA;IACrB,YAAY;IACZ,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,0BAA0B;IAC1B,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;IACrB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9B,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAOD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,CAoDjE"}

package/dist/lang/codegen.js

@@ -0,0 +1,148 @@
+/**
+ * codegen — 纯数据 → 文本 打印工具（宿主编辑器/测试用；L0，仅依赖 host-arg）
+ *
+ * 宿主 buildCode / 编辑重排行（editStatement → replaceCodeAt）统一走此入口。
+ * 输入是纯数据（HostArg 面），不依赖任何 IR 类型。
+ *
+ * 扁平代码格式（无 export/async/await/return/参数声明）：
+ * ```js
+ * let part0 = cad.box(10, 20, 30)
+ * part0 = cad.translate(part0, { offset: [1, 2, 3] })
+ * ```
+ *
+ * 值格式约定（确定性输出）：
+ * - vec3 → `[1,2,3]`（紧凑无空格）
+ * - 数字 → 整数直出；小数最多保留 6 位有效小数并去尾零
+ * - 字符串 → 单引号包裹
+ * - HostVarRef → 裸变量名（members 元素）
+ * - HostCallRef → `cad.faceNormal(part0)`（嵌套调用）
+ * - HostExprRef → `(expr text)`（原文加括号）
+ * - 对象字面量 → `{key:value}`（冒号，合法 JS）
+ */
+import { isHostVarRef, isHostParamRef, isHostCallRef, isHostExprRef, isHostRef } from './host-arg.js';
+// ── 数值格式化 ──
+/**
+ * Format a number as text: integers emit as-is; decimals retain at most 6
+ * significant fractional digits with trailing zeros stripped.
+ * @param n - the number to format.
+ * @returns the formatted text representation.
+ */
+export function fmtNum(n) {
+    if (!Number.isFinite(n))
+        return String(n);
+    if (Number.isInteger(n))
+        return String(n);
+    const s = n.toFixed(6);
+    return s.replace(/\.?0+$/, '');
+}
+// ── 字符串转义 ──
+/** 字符串转义：转义反斜杠、单引号与控制字符（多行 SDF code 等字符串参数用）。
+ *  逐一字符映射（避开 regex 控制字符字面量，满足 eslint no-control-regex），
+ *  保证 fmtValue ⇄ analyzeCode 往返一致：嵌入 '…' 后仍是合法 JS，可被精确还原。 */
+const STRING_ESCAPES = {
+    '\\': '\\\\',
+    "'": "\\'",
+    '\u0008': '\\b', // backspace
+    '\u000C': '\\f', // form feed
+    '\u000A': '\\n', // line feed
+    '\u000D': '\\r', // carriage return
+    '\u0009': '\\t', // tab
+    '\u000B': '\\v', // vertical tab
+};
+function escapeStr(s) {
+    let out = '';
+    for (let i = 0; i < s.length; i++) {
+        const esc = STRING_ESCAPES[s[i]];
+        out += esc ?? s[i];
+    }
+    return out;
+}
+/** 参数值 → 文本（递归，HostArg 面） */
+function fmtValue(value) {
+    if (value === null)
+        return 'null';
+    if (typeof value === 'number')
+        return fmtNum(value);
+    if (typeof value === 'boolean')
+        return String(value);
+    if (typeof value === 'string')
+        return `'${escapeStr(value)}'`;
+    if (isHostVarRef(value))
+        return value.name;
+    if (isHostParamRef(value))
+        return value.name;
+    if (isHostCallRef(value)) {
+        const { callee, args, namespace } = value;
+        const inner = args.map(fmtValue).join(', ');
+        return `${namespace ?? 'cad'}.${callee}(${inner})`;
+    }
+    if (isHostExprRef(value))
+        return `(${value.text})`;
+    if (Array.isArray(value))
+        return `[${value.map(fmtValue).join(',')}]`;
+    if (typeof value === 'object') {
+        const entries = Object.entries(value);
+        return `{${entries.map(([k, v]) => `${k}:${fmtValue(v)}`).join(', ')}}`;
+    }
+    return String(value);
+}
+/** 检测 HostArg 是否为纯数据对象（非引用形态）。 */
+function isPlainObjArg(arg) {
+    return arg !== null && typeof arg === 'object' && !Array.isArray(arg) && !isHostRef(arg);
+}
+/**
+ * 从纯数据（非 IR 类型）打印一行 faijs 源代码。
+ *
+ * 宿主 buildCode / 编辑重排行（editStatement → replaceCodeAt）统一走此入口。
+ * @param input - the pure-data line description.
+ * @returns the printed single-line code text.
+ */
+export function formatCodeLine(input) {
+    const positional = input.positional;
+    const argsInput = input.args ?? {};
+    // 位置实参按序打印
+    const positionalParts = positional.map((arg) => {
+        if (isPlainObjArg(arg)) {
+            const entries = Object.entries(arg);
+            return `{ ${entries.map(([k, v]) => `${k}:${fmtValue(v)}`).join(', ')} }`;
+        }
+        return fmtValue(arg);
+    });
+    // args 槽（过渡兼容：positional 末位非纯对象时追加为独立选项槽）
+    const argsParts = Object.entries(argsInput).map(([k, v]) => `${k}:${fmtValue(v)}`);
+    const lastIsPlainObject = positional.length > 0 && isPlainObjArg(positional[positional.length - 1]);
+    let callArgs;
+    if (positionalParts.length > 0) {
+        callArgs = positionalParts.join(', ');
+        if (!lastIsPlainObject && argsParts.length > 0) {
+            callArgs = [...positionalParts, `{ ${argsParts.join(', ')} }`].join(', ');
+        }
+    }
+    else if (input.receiver) {
+        callArgs = argsParts.length > 0 ? `{ ${argsParts.join(', ')} }` : '';
+    }
+    else {
+        callArgs = argsParts.length > 0 ? `{ ${argsParts.join(', ')} }` : '{}';
+    }
+    // F2：命名空间前缀（缺省 cad）；本机函数调用 callee 无命名空间前缀
+    const nsExpr = input.namespace === undefined ? `cad.${input.callee}` : `${input.namespace}.${input.callee}`;
+    // 1) 解构：outputKeys + outputs 一一对应
+    if (input.outputKeys && input.outputKeys.length > 0) {
+        const destructure = input.outputKeys.map((k, i) => `${k}: ${input.outputs[i]}`).join(', ');
+        return `const { ${destructure} } = ${nsExpr}(${callArgs})`;
+    }
+    // 2) 成员调用
+    if (input.receiver) {
+        return `${input.receiver}.${input.callee}(${callArgs})`;
+    }
+    // 3) 无赋值调用
+    if (input.outputs.length === 0) {
+        return `${nsExpr}(${callArgs})`;
+    }
+    // 4) 赋值：outputDeclared → 裸重赋值；否则 let 声明
+    const out = input.outputs[0];
+    if (input.outputDeclared)
+        return `${out} = ${nsExpr}(${callArgs})`;
+    return `let ${out} = ${nsExpr}(${callArgs})`;
+}
+//# sourceMappingURL=codegen.js.map

package/dist/lang/codegen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegen.js","sourceRoot":"","sources":["../../src/lang/codegen.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * codegen — 纯数据 → 文本 打印工具（宿主编辑器/测试用；L0，仅依赖 host-arg）\n *\n * 宿主 buildCode / 编辑重排行（editStatement → replaceCodeAt）统一走此入口。\n * 输入是纯数据（HostArg 面），不依赖任何 IR 类型。\n *\n * 扁平代码格式（无 export/async/await/return/参数声明）：\n * ```js\n * let part0 = cad.box(10, 20, 30)\n * part0 = cad.translate(part0, { offset: [1, 2, 3] })\n * ```\n *\n * 值格式约定（确定性输出）：\n * - vec3 → `[1,2,3]`（紧凑无空格）\n * - 数字 → 整数直出；小数最多保留 6 位有效小数并去尾零\n * - 字符串 → 单引号包裹\n * - HostVarRef → 裸变量名（members 元素）\n * - HostCallRef → `cad.faceNormal(part0)`（嵌套调用）\n * - HostExprRef → `(expr text)`（原文加括号）\n * - 对象字面量 → `{key:value}`（冒号，合法 JS）\n */\n\nimport type { HostArg } from './host-arg'\nimport { isHostVarRef, isHostParamRef, isHostCallRef, isHostExprRef, isHostRef } from './host-arg'\n\n// ── 数值格式化 ──\n\n/**\n * Format a number as text: integers emit as-is; decimals retain at most 6\n * significant fractional digits with trailing zeros stripped.\n * @param n - the number to format.\n * @returns the formatted text representation.\n */\nexport function fmtNum(n: number): string {\n  if (!Number.isFinite(n)) return String(n)\n  if (Number.isInteger(n)) return String(n)\n  const s = n.toFixed(6)\n  return s.replace(/\\.?0+$/, '')\n}\n\n// ── 字符串转义 ──\n\n/** 字符串转义：转义反斜杠、单引号与控制字符（多行 SDF code 等字符串参数用）。\n *  逐一字符映射（避开 regex 控制字符字面量，满足 eslint no-control-regex），\n *  保证 fmtValue ⇄ analyzeCode 往返一致：嵌入 '…' 后仍是合法 JS，可被精确还原。 */\nconst STRING_ESCAPES: Record<string, string> = {\n  '\\\\': '\\\\\\\\',\n  \"'\": \"\\\\'\",\n  '\\u0008': '\\\\b', // backspace\n  '\\u000C': '\\\\f', // form feed\n  '\\u000A': '\\\\n', // line feed\n  '\\u000D': '\\\\r', // carriage return\n  '\\u0009': '\\\\t', // tab\n  '\\u000B': '\\\\v', // vertical tab\n}\n\nfunction escapeStr(s: string): string {\n  let out = ''\n  for (let i = 0; i < s.length; i++) {\n    const esc = STRING_ESCAPES[s[i]]\n    out += esc ?? s[i]\n  }\n  return out\n}\n\n/** 参数值 → 文本（递归，HostArg 面） */\nfunction fmtValue(value: HostArg): string {\n  if (value === null) return 'null'\n  if (typeof value === 'number') return fmtNum(value)\n  if (typeof value === 'boolean') return String(value)\n  if (typeof value === 'string') return `'${escapeStr(value)}'`\n  if (isHostVarRef(value)) return value.name\n  if (isHostParamRef(value)) return value.name\n  if (isHostCallRef(value)) {\n    const { callee, args, namespace } = value\n    const inner = args.map(fmtValue).join(', ')\n    return `${namespace ?? 'cad'}.${callee}(${inner})`\n  }\n  if (isHostExprRef(value)) return `(${value.text})`\n  if (Array.isArray(value)) return `[${value.map(fmtValue).join(',')}]`\n  if (typeof value === 'object') {\n    const entries = Object.entries(value as Record<string, HostArg>)\n    return `{${entries.map(([k, v]) => `${k}:${fmtValue(v)}`).join(', ')}}`\n  }\n  return String(value)\n}\n\n// ── 纯数据 → 代码行（宿主代码生成入口） ──\n\n/**\n * Pure-data input for printing one faijs source line, decoupled from IR types.\n *\n * `positional` and `args` use `HostArg` (host-friendly types with `kind`-based\n * discrimination).\n */\nexport interface FormatCodeLineInput {\n  callee: string\n  /** 成员方法调用接收者变量名 */\n  receiver?: string\n  /**\n   * 位置实参槽（HostArg 形态）：宿主可传字面量、\n   * 变量引用（`{kind:'var-ref',name}`）、参数引用（`{kind:'param-ref',name}`）、\n   * 嵌套调用（`{kind:'call-ref',callee,args,namespace?}`）、\n   * 表达式（`{kind:'expr-ref',text,refs,params}`）或纯 JsonValue，按序打印。\n   */\n  positional: HostArg[]\n  /** 产出变量名 */\n  outputs: string[]\n  /** 解构键（与 outputs 一一对应） */\n  outputKeys?: string[]\n  /**\n   * （过渡兼容）选项对象：positional 末位不是纯对象时追加为尾随选项对象。\n   * 新代码应把选项对象直接放进 positional。\n   */\n  args?: Record<string, HostArg>\n  /** 调用命名空间（F2：第三方库 `mech.makeHeadstock(...)` → 'mech'；缺省 'cad'） */\n  namespace?: string\n  /**\n   * outputs[0] 是否已在代码中声明：true → 裸重赋值（`part0 = ...`），\n   * false/省略 → let 声明；解构/成员调用/无输出时忽略。\n   */\n  outputDeclared?: boolean\n}\n\n/** 检测 HostArg 是否为纯数据对象（非引用形态）。 */\nfunction isPlainObjArg(arg: HostArg): boolean {\n  return arg !== null && typeof arg === 'object' && !Array.isArray(arg) && !isHostRef(arg)\n}\n\n/**\n * 从纯数据（非 IR 类型）打印一行 faijs 源代码。\n *\n * 宿主 buildCode / 编辑重排行（editStatement → replaceCodeAt）统一走此入口。\n * @param input - the pure-data line description.\n * @returns the printed single-line code text.\n */\nexport function formatCodeLine(input: FormatCodeLineInput): string {\n  const positional = input.positional\n  const argsInput: Record<string, HostArg> = input.args ?? {}\n\n  // 位置实参按序打印\n  const positionalParts = positional.map((arg) => {\n    if (isPlainObjArg(arg)) {\n      const entries = Object.entries(arg as Record<string, HostArg>)\n      return `{ ${entries.map(([k, v]) => `${k}:${fmtValue(v)}`).join(', ')} }`\n    }\n    return fmtValue(arg)\n  })\n\n  // args 槽（过渡兼容：positional 末位非纯对象时追加为独立选项槽）\n  const argsParts = Object.entries(argsInput).map(([k, v]) => `${k}:${fmtValue(v)}`)\n  const lastIsPlainObject = positional.length > 0 && isPlainObjArg(positional[positional.length - 1])\n\n  let callArgs: string\n  if (positionalParts.length > 0) {\n    callArgs = positionalParts.join(', ')\n    if (!lastIsPlainObject && argsParts.length > 0) {\n      callArgs = [...positionalParts, `{ ${argsParts.join(', ')} }`].join(', ')\n    }\n  } else if (input.receiver) {\n    callArgs = argsParts.length > 0 ? `{ ${argsParts.join(', ')} }` : ''\n  } else {\n    callArgs = argsParts.length > 0 ? `{ ${argsParts.join(', ')} }` : '{}'\n  }\n\n  // F2：命名空间前缀（缺省 cad）；本机函数调用 callee 无命名空间前缀\n  const nsExpr = input.namespace === undefined ? `cad.${input.callee}` : `${input.namespace}.${input.callee}`\n\n  // 1) 解构：outputKeys + outputs 一一对应\n  if (input.outputKeys && input.outputKeys.length > 0) {\n    const destructure = input.outputKeys.map((k, i) => `${k}: ${input.outputs[i]}`).join(', ')\n    return `const { ${destructure} } = ${nsExpr}(${callArgs})`\n  }\n\n  // 2) 成员调用\n  if (input.receiver) {\n    return `${input.receiver}.${input.callee}(${callArgs})`\n  }\n\n  // 3) 无赋值调用\n  if (input.outputs.length === 0) {\n    return `${nsExpr}(${callArgs})`\n  }\n\n  // 4) 赋值：outputDeclared → 裸重赋值；否则 let 声明\n  const out = input.outputs[0]\n  if (input.outputDeclared) return `${out} = ${nsExpr}(${callArgs})`\n  return `let ${out} = ${nsExpr}(${callArgs})`\n}\n"]}

package/dist/lang/compile.d.ts

@@ -0,0 +1,50 @@
+/**
+ * compile — ScriptIR → 零 import ESM 模块（VM 执行方案 Phase 1）
+ *
+ *
+ * `compileToModule(script)` 把校验过的 ScriptIR IR 编译为**不含任何 import 语句**的
+ * ESM 文本（`export const statements = [...]`）。产物零 import 是关键决策——Node 的
+ * `data:` URL 与浏览器的 Blob URL 动态 import 都无法解析裸说明符，零 import 使模块在
+ * 两个平台都能直接 `import()`，无需 import map / 打包器 / 文件系统。
+ *
+ * 编译规则：
+ * - 每条语句一个 `{ id, deps, fn }`：`id` 是独立 StmtId（参数语句占 s1..sK，语句 s(K+1)..s(K+N)）；
+ *   `deps` 由 parser 收集的 `stmt.refs`（inputs + $param + $geom.of + members）翻译为定义语句的 id；
+ *   `fn` 是 `async (ctx, ns) => {...}`（ns = 命名空间集合，无隐式参数）。
+ * - 参数即变量：`const r = 20` 编译为普通语句 `ctx.r = 20`。
+ * - 变量引用编译为 `ctx.x`（持久变量容器，跨增量执行存活）。
+ * - $param → `ctx.<name>`；$geom → `ns.cad.<feature>(ctx.<of>, ...)`；$asset → `await ns.cad.asset(key)`。
+ * - 编译输入只有 IR，用户原文不进 VM（先解析后执行红线）。
+ */
+import type { ScriptIR } from './types.js';
+import { type StmtId } from '../identity.js';
+/** 编译后单条语句的元数据（与模块文本中的 `{ id, deps, fn }` 并行）。 */
+export interface CompiledStatementMeta {
+    /** 独立 StmtId（模块语句 id） */
+    id: StmtId;
+    /** 依赖语句 id（定义被引用变量的语句） */
+    deps: StmtId[];
+    /** 本语句写入 ctx 的键（变量名）：普通语句 [id]、split 双输出、参数 [paramName]、add_constraint/do_assemble 空 */
+    writes: string[];
+    /** 在 script.statements 中的下标（参数语句为 undefined） */
+    sourceIndex?: number;
+}
+/** compileToModule 的返回：模块文本 + 并行元数据（供 ModuleExecutor 建 sourceById / reconcileCtx）。 */
+export interface CompiledModule {
+    code: string;
+    statements: CompiledStatementMeta[];
+}
+/**
+ * 把 ScriptIR 编译为零 import ESM 模块文本 + 语句元数据。
+ *
+ * 同一份 ScriptIR 编译结果确定（StmtId 按语句顺序稳定分配）。
+ */
+/**
+ * Compile a validated ScriptIR into a zero-import ESM module text plus parallel
+ * statement metadata. The output of compiling the same ScriptIR is
+ * deterministic (StmtIds are assigned stably in statement order).
+ * @param script - the validated ScriptIR to compile.
+ * @returns the compiled module code and its statement metadata.
+ */
+export declare function compileToModule(script: ScriptIR): CompiledModule;
+//# sourceMappingURL=compile.d.ts.map

package/dist/lang/compile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../src/lang/compile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAKV,QAAQ,EAIT,MAAM,SAAS,CAAA;AAIhB,OAAO,EAAY,KAAK,MAAM,EAAE,MAAM,aAAa,CAAA;AAInD,kDAAkD;AAClD,MAAM,WAAW,qBAAqB;IACpC,yBAAyB;IACzB,EAAE,EAAE,MAAM,CAAA;IACV,0BAA0B;IAC1B,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,wFAAwF;IACxF,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,sFAAsF;AACtF,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,qBAAqB,EAAE,CAAA;CACpC;AAiQD;;;;GAIG;AACH;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,QAAQ,GAAG,cAAc,CAiFhE"}