@wscytz/dsl 0.0.0-stage → 0.1.0

package/dist/cli.js

@@ -0,0 +1,389 @@
+#!/usr/bin/env node
+/**
+ * cys-dsl CLI — .sift 文件的 validate / render / roundtrip(执行意向书 Step 1 第 3 件)。
+ *
+ * - validate   语法(parse)→ 卫生(sanitize)→ 关系式求解(solve)全链检查,报诊断;
+ * - render     转 JSON Canvas 1.0(Obsidian .canvas / React Flow 等通用格式)到 stdout;
+ * - roundtrip  DSL→元素→DSL 双往返,签名比对验证转义保真(serialize∘parse 不漂移)。
+ *
+ * 退出码:0 = 干净;1 = 有诊断/往返发散;2 = 用法或文件读取错误。
+ *
+ * 结构:纯函数核心(validateText / renderText / roundtripText)进测试与库;
+ * 本文件**不进公开 barrel**(node:fs 不许进 web bundle)。
+ * 运行:`pnpm --filter @wscytz/dsl cli <命令> <file.sift>`(tsx,devDep)。
+ */
+import { readFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { DSL_VERSION } from './dsl-grammar.js';
+import { parseDslWithDiagnostics } from './dsl-parser.js';
+import { sanitizeDslOps } from './dsl-sanitize.js';
+import { solveRelational } from './dsl-relational-solver.js';
+import { serializeCanvas } from './canvas-dsl.js';
+import { toSvg } from './to-svg.js';
+import { toJsonCanvas, JSON_CANVAS_DEFAULT_CARD_W, JSON_CANVAS_DEFAULT_CARD_H, JSON_CANVAS_DEFAULT_TEXT_W, JSON_CANVAS_DEFAULT_TEXT_H, } from './to-json-canvas.js';
+const USAGE = `cys-dsl — cy's Stift 画布 DSL(v${DSL_VERSION})命令行
+
+用法:cys-dsl <命令> <file.sift>
+命令:
+  validate   语法 / 卫生 / 关系式求解全链检查(诊断报告)
+  render     转 JSON Canvas 1.0 到 stdout(Obsidian .canvas 等通用格式);--svg 转 SVG
+  roundtrip  DSL→元素→DSL 双往返签名比对(转义保真检查)
+退出码:0 = 干净(警告不阻断);1 = 有诊断 / 往返发散;2 = 用法或文件错误
+`;
+/** 全链:parse(行级容错丢弃)→ sanitize → solve(关系式→绝对坐标)。 */
+function pipeline(text) {
+    const parsed = parseDslWithDiagnostics(text);
+    const sanitized = sanitizeDslOps(parsed.ops);
+    const solved = solveRelational(sanitized.ops);
+    return { parsed, sanitized, solved };
+}
+/** parse 丢弃行的标准警告行(stderr 用)。 */
+function parseWarnings(parsed) {
+    return parsed.errors.map((e) => `parse 丢弃 行${e.line}:${e.message}(源:${e.text})`);
+}
+// ---------- validate ----------
+export function validateText(text) {
+    const { parsed, sanitized, solved } = pipeline(text);
+    const lines = [`cys-dsl v${DSL_VERSION} · validate`];
+    const errors = [];
+    let code = 0;
+    for (const w of parseWarnings(parsed)) {
+        code = 1;
+        errors.push(`✗ ${w}`);
+    }
+    // 软信号(全角标点/拼写手误):不影响 exit code,只提示 —— 元素已保留,可修可不修
+    for (const w of parsed.warnings) {
+        errors.push(`ℹ 行${w.line}:${w.message}(源:${w.text})`);
+    }
+    for (const d of sanitized.diagnostics)
+        errors.push(`⚠ sanitize op#${d.opIndex}:${d.message}`);
+    for (const d of solved.diagnostics)
+        errors.push(`⚠ solve op#${d.opIndex}:${d.message}`);
+    if (code === 0) {
+        const cards = solved.ops.filter((o) => o.type === 'card').length;
+        const free = solved.ops.filter((o) => o.type === 'free').length;
+        const arrows = solved.ops.filter((o) => o.type === 'arrow').length;
+        const warns = sanitized.diagnostics.length + solved.diagnostics.length;
+        lines.push(warns > 0
+            ? `✓ ${solved.ops.length} op(card ${cards} / free ${free} / arrow ${arrows})——语法通过;${warns} 条警告见 stderr,不阻断`
+            : `✓ ${solved.ops.length} op(card ${cards} / free ${free} / arrow ${arrows})——语法、卫生检查与关系式求解均通过`);
+    }
+    return {
+        code,
+        stdout: lines.join('\n') + '\n',
+        stderr: errors.length > 0 ? errors.join('\n') + '\n' : '',
+    };
+}
+// ---------- render(JSON Canvas 1.0 / SVG)----------
+export function renderText(text, opts) {
+    const { parsed, sanitized, solved } = pipeline(text);
+    const stderrLines = parseWarnings(parsed);
+    for (const d of sanitized.diagnostics)
+        stderrLines.push(`sanitize op#${d.opIndex}:${d.message}`);
+    for (const d of solved.diagnostics)
+        stderrLines.push(`solve op#${d.opIndex}:${d.message}`);
+    if (opts?.svg === true) {
+        const { svg, skipped } = toSvg(solved.ops);
+        for (const s of skipped)
+            stderrLines.push(`跳过 op#${s.opIndex} ${s.op}:${s.reason}`);
+        return {
+            code: parsed.errors.length > 0 ? 1 : 0,
+            stdout: svg,
+            stderr: stderrLines.length > 0 ? stderrLines.join('\n') + '\n' : '',
+        };
+    }
+    const { canvas, skipped } = toJsonCanvas(solved.ops);
+    for (const s of skipped)
+        stderrLines.push(`跳过 op#${s.opIndex} ${s.op}:${s.reason}`);
+    return {
+        code: parsed.errors.length > 0 ? 1 : 0,
+        stdout: JSON.stringify(canvas, null, 2) + '\n',
+        stderr: stderrLines.length > 0 ? stderrLines.join('\n') + '\n' : '',
+    };
+}
+// ---------- roundtrip ----------
+/** toFixed(1) 是 serialize 的数值精度;签名两侧同用,防量化假发散。 */
+function r1(n) {
+    return Number(n.toFixed(1));
+}
+/** 元素 id:无 id 的 free/arrow op 用 op 下标生成确定性兜底名(两侧签名同函数,保对齐)。 */
+function elemId(id, opIndex) {
+    return id ?? `anon-${opIndex}`;
+}
+/** route 兼容规则(parser/serialize 同源):无 route 但有 curve → 视为 curve。 */
+function normRoute(op) {
+    return op.route ?? (op.curve ? 'curve' : null);
+}
+/**
+ * 参与 roundtrip 的 op:输入专用 op 排除(keepExistingPos 卡 / 自由箭头——
+ * 它们依赖宿主画布状态,serializeCanvas 按设计永不输出,双往返中必然消失)。
+ */
+function roundtrippable(ops) {
+    return ops.filter((op) => {
+        if (op.type === 'card' && op.keepExistingPos === true)
+            return false;
+        if (op.type === 'arrow' && (op.freeArrow || !op.from || !op.to))
+            return false;
+        return true;
+    });
+}
+/**
+ * 归一化签名:比较「语义内容」而非字面文本。排除输入专用字段(create / rel /
+ * keepExistingPos),数值过 serialize 同款 toFixed(1) 量化,缺省几何按转换侧同一
+ * 缺省值归一。首轮与二轮 ops 各算一次,逐位比对。
+ */
+function signature(ops) {
+    return ops.map((op, i) => {
+        if (op.type === 'card') {
+            return JSON.stringify([
+                'card',
+                op.cardId,
+                r1(op.x),
+                r1(op.y),
+                r1(op.w ?? JSON_CANVAS_DEFAULT_CARD_W),
+                r1(op.h ?? JSON_CANVAS_DEFAULT_CARD_H),
+                op.color ?? null,
+                op.title ?? null,
+                op.content ?? null,
+                op.cardType ?? null,
+                op.tags ?? null,
+                op.links ?? null,
+                op.code ?? null,
+                op.quotes ?? null,
+                op.group ?? null,
+                op.href ?? null,
+            ]);
+        }
+        if (op.type === 'free') {
+            // text 的 w/h 不进 DSL(serializer 不 emit @size),签名不含。
+            const base = ['free', op.shape, elemId(op.id, i), r1(op.x), r1(op.y)];
+            if (op.shape === 'text') {
+                base.push(op.text ?? null, op.color ?? null, op.group ?? null, op.compute ?? null);
+            }
+            else {
+                base.push(r1(op.w ?? 0), r1(op.h ?? 0), op.shape === 'frame' ? (op.text ?? null) : null, op.color ?? null, op.group ?? null);
+            }
+            return JSON.stringify(base);
+        }
+        return JSON.stringify([
+            'arrow',
+            elemId(op.id, i),
+            op.from,
+            op.to,
+            op.label ?? null,
+            op.color ?? null,
+            op.dash ?? null,
+            op.arrowhead ?? null,
+            op.wikilink ?? null,
+            op.curve ?? null,
+            normRoute(op),
+            op.elbow ?? null,
+        ]);
+    });
+}
+/** solved ops → 最小 CanvasElement[](供 serializeCanvas;与 apply 层同缺省尺寸)。 */
+function opsToElements(ops) {
+    const elements = [];
+    ops.forEach((op, i) => {
+        if (op.type === 'card') {
+            if (op.keepExistingPos === true)
+                return;
+            elements.push({
+                id: op.cardId,
+                kind: 'card',
+                x: op.x,
+                y: op.y,
+                w: op.w ?? JSON_CANVAS_DEFAULT_CARD_W,
+                h: op.h ?? JSON_CANVAS_DEFAULT_CARD_H,
+                rotation: 0,
+                ...(op.color !== undefined ? { color: op.color } : {}),
+                ...(op.group !== undefined || op.href?.length
+                    ? {
+                        meta: {
+                            ...(op.group !== undefined ? { group: op.group } : {}),
+                            ...(op.href?.length ? { href: op.href } : {}),
+                        },
+                    }
+                    : {}),
+            });
+            return;
+        }
+        if (op.type === 'free') {
+            if (op.shape === 'text') {
+                elements.push({
+                    id: elemId(op.id, i),
+                    kind: 'text',
+                    x: op.x,
+                    y: op.y,
+                    w: op.w ?? JSON_CANVAS_DEFAULT_TEXT_W,
+                    h: op.h ?? JSON_CANVAS_DEFAULT_TEXT_H,
+                    rotation: 0,
+                    text: op.text ?? '',
+                    ...(op.color !== undefined ? { color: op.color } : {}),
+                    ...(op.group !== undefined || op.compute !== undefined
+                        ? {
+                            meta: {
+                                ...(op.group !== undefined ? { group: op.group } : {}),
+                                ...(op.compute !== undefined ? { compute: op.compute } : {}),
+                            },
+                        }
+                        : {}),
+                });
+            }
+            else {
+                elements.push({
+                    id: elemId(op.id, i),
+                    kind: op.shape,
+                    x: op.x,
+                    y: op.y,
+                    w: op.w ?? 0,
+                    h: op.h ?? 0,
+                    rotation: 0,
+                    ...(op.shape === 'frame' ? { text: op.text ?? '' } : {}),
+                    ...(op.color !== undefined ? { color: op.color } : {}),
+                    ...(op.group !== undefined ? { meta: { group: op.group } } : {}),
+                });
+            }
+            return;
+        }
+        // arrow:自由箭头(无端点)无法以元素形式往返,跳过(roundtrippable 已排除)。
+        if (op.freeArrow || !op.from || !op.to)
+            return;
+        elements.push({
+            id: elemId(op.id, i),
+            kind: 'arrow',
+            x: 0,
+            y: 0,
+            w: 0,
+            h: 0,
+            rotation: 0,
+            from: op.from,
+            to: op.to,
+            ...(op.label !== undefined ? { text: op.label } : {}),
+            ...(op.color !== undefined ? { color: op.color } : {}),
+            ...(op.dash !== undefined ? { dash: op.dash } : {}),
+            ...(op.arrowhead !== undefined ? { arrowhead: op.arrowhead } : {}),
+            ...(op.curve !== undefined ? { curve: op.curve } : {}),
+            ...(op.route !== undefined ? { route: op.route } : {}),
+            ...(op.elbow !== undefined ? { elbow: op.elbow } : {}),
+            ...(op.wikilink === true ? { meta: { wikilink: true } } : {}),
+        });
+    });
+    return elements;
+}
+/** op₁ 的结构化字段 → CardDslContent(serializeCanvas resolve 注入)。
+ *  占位值:tags 色给 canonical 灰(serialize 只读 .value);links fetchedAt 用 epoch(只读 .url)。 */
+function collectContent(ops) {
+    const map = new Map();
+    for (const op of ops) {
+        if (op.type !== 'card')
+            continue;
+        const content = {};
+        if (op.title !== undefined)
+            content.title = op.title;
+        if (op.content !== undefined)
+            content.content = op.content;
+        if (op.cardType !== undefined)
+            content.type = op.cardType;
+        if (op.tags?.length)
+            content.tags = op.tags.map((value) => ({ value, color: 'var(--color-gray)' }));
+        if (op.links?.length)
+            content.links = op.links.map((url) => ({ url, fetchedAt: new Date(0) }));
+        if (op.code?.length)
+            content.codeSnippets = op.code;
+        if (op.quotes?.length)
+            content.quotes = op.quotes;
+        if (Object.keys(content).length > 0)
+            map.set(op.cardId, content);
+    }
+    return map;
+}
+export function roundtripText(text) {
+    const { parsed, sanitized, solved } = pipeline(text);
+    const stderrLines = parseWarnings(parsed);
+    for (const d of sanitized.diagnostics)
+        stderrLines.push(`sanitize op#${d.opIndex}:${d.message}`);
+    for (const d of solved.diagnostics)
+        stderrLines.push(`solve op#${d.opIndex}:${d.message}`);
+    const pass1 = roundtrippable(solved.ops);
+    const contentById = collectContent(solved.ops);
+    const dsl2 = serializeCanvas(opsToElements(solved.ops), (id) => contentById.get(id));
+    const parsed2 = parseDslWithDiagnostics(dsl2);
+    const sanitized2 = sanitizeDslOps(parsed2.ops);
+    const solved2 = solveRelational(sanitized2.ops);
+    const pass2 = roundtrippable(solved2.ops);
+    const sig1 = signature(pass1);
+    const sig2 = signature(pass2);
+    const lines = [];
+    let code = 0;
+    if (sig1.length !== sig2.length) {
+        code = 1;
+        lines.push(`roundtrip:DIVERGED(op 数 ${sig1.length} → ${sig2.length})`);
+    }
+    else {
+        const diffs = [];
+        for (let i = 0; i < sig1.length; i++)
+            if (sig1[i] !== sig2[i])
+                diffs.push(i);
+        if (diffs.length === 0) {
+            lines.push(`roundtrip:STABLE(${sig1.length} op 签名一致,转义保真)`);
+        }
+        else {
+            code = 1;
+            lines.push(`roundtrip:DIVERGED(${diffs.length}/${sig1.length} op 签名不一致)`);
+            for (const i of diffs.slice(0, 5)) {
+                lines.push(`  op#${i} 首轮:${sig1[i]}`);
+                lines.push(`  op#${i} 二轮:${sig2[i]}`);
+            }
+        }
+    }
+    const inputOnly = solved.ops.length - pass1.length;
+    if (inputOnly > 0) {
+        lines.push(`注:${inputOnly} 个输入专用 op(keepExistingPos 卡 / 自由箭头)不参与往返——它们依赖宿主画布状态,serialize 按设计永不输出`);
+    }
+    return {
+        code,
+        stdout: lines.join('\n') + '\n',
+        stderr: stderrLines.length > 0 ? stderrLines.join('\n') + '\n' : '',
+    };
+}
+// ---------- argv 包装 ----------
+export function main(argv) {
+    const [cmd, file] = argv;
+    if (!cmd || !file || (cmd !== 'validate' && cmd !== 'render' && cmd !== 'roundtrip')) {
+        process.stderr.write(USAGE);
+        return 2;
+    }
+    // flag 解析:目前仅 render 认 --svg;其余 flag 一律用法错误(不静默吞)
+    const rest = argv.slice(2);
+    const unknownFlag = rest.find((f) => f.startsWith('--') && f !== '--svg');
+    if (unknownFlag !== undefined || (rest.includes('--svg') && cmd !== 'render')) {
+        process.stderr.write(USAGE);
+        return 2;
+    }
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch {
+        process.stderr.write(`cys-dsl:读不到文件:${file}\n`);
+        return 2;
+    }
+    const result = cmd === 'validate'
+        ? validateText(text)
+        : cmd === 'render'
+            ? renderText(text, { svg: rest.includes('--svg') })
+            : roundtripText(text);
+    if (result.stdout)
+        process.stdout.write(result.stdout);
+    if (result.stderr)
+        process.stderr.write(result.stderr);
+    return result.code;
+}
+/* 直接执行时才跑 main(被 import / 测试时不触发)。
+ * 用 process.exitCode 而非 process.exit:后者不等 stdout 管道 flush,>64KiB 输出
+ * (大画布 render)在 `| jq` 等管道下会静默截断且仍 exit 0。exitCode 让 Node 在
+ * 写队列排空后自然退出。 */
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    process.exitCode = main(process.argv.slice(2));
+}

package/dist/dsl-compute.d.ts

@@ -0,0 +1,48 @@
+/**
+ * dsl-compute — v7 `@compute` 的**安全**公式求值器(纯函数,框架无关)。
+ *
+ * 设计铁律(安全):
+ *  - **绝不 eval / new Function**。公式经手写 tokenizer + 递归下降 parser 求值,只认一个
+ *    固定的小语言(数字 / + - * / / 括号 / min,max,abs,round / `#id.x|y|w|h` 几何引用)。
+ *    任何越界字符 → 求值失败(返回 undefined),不执行。
+ *  - **只引用元素几何**(x/y/w/h),**不碰卡片内容**(title/body)→ 无隐私泄漏
+ *    (对齐 AI 隐私:content 不外发;这里连内部求值都只读几何)。
+ *  - 除零 → 0;非有限结果(NaN/Infinity)→ 0。递归深度上限,防 `((((…))))` 栈炸(DoS)。
+ *
+ * 语义:apply 时(snapshot 批量)求值,结果写 text 元素的 text;原式存 element.meta.compute
+ * 往返对称。**live 重算**(被引用元素一动就重算)是文档化的后续增强,v7 只在每次 apply 重算。
+ *
+ * 语言(EBNF):
+ *   expr   = term (('+'|'-') term)*
+ *   term   = factor (('*'|'/') factor)*
+ *   factor = '-' factor | number | ref | func '(' args ')' | '(' expr ')'
+ *   ref    = '#' idChar+ '.' ('x'|'y'|'w'|'h')
+ *   func   = 'min' | 'max' | 'abs' | 'round'     # min/max ≥1 参,abs/round 恰 1 参
+ *   args   = expr (',' expr)*
+ */
+/** 求值器的几何解析器:给元素 id 返回几何,不存在 → undefined(该引用求值失败 → 整式失败)。 */
+export interface ComputeGeom {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export type ComputeResolver = (id: string) => ComputeGeom | undefined;
+/** 数字格式化:去浮点噪声,最多 2 位小数,去尾 0(12.00→12, 3.50→3.5)。 */
+export declare function formatComputeNumber(n: number): string;
+/** 求值结果:成功→value(有限数);失败→value undefined + error(原因,供 apply 诊断)。 */
+export interface ComputeResult {
+    value: number | undefined;
+    error?: string;
+}
+/**
+ * 求值 `@compute` 公式(同 evalCompute,但暴露失败原因 error 供 apply 诊断)。
+ * 成功 → { value: 有限数 };任何失败(语法 / 未解析引用 / 越界)→ { value: undefined, error }。
+ * 永不抛错。resolve 用来把 `#id.field` 解析成几何值。
+ */
+export declare function evalComputeDetail(expr: string, resolve: ComputeResolver): ComputeResult;
+/**
+ * 求值 `@compute` 公式(薄封装,仅返回 value);需失败原因用 {@link evalComputeDetail}。
+ * 成功 → 有限数;任何失败 → undefined。永不抛错。
+ */
+export declare function evalCompute(expr: string, resolve: ComputeResolver): number | undefined;

package/dist/dsl-compute.js

@@ -0,0 +1,248 @@
+/**
+ * dsl-compute — v7 `@compute` 的**安全**公式求值器(纯函数,框架无关)。
+ *
+ * 设计铁律(安全):
+ *  - **绝不 eval / new Function**。公式经手写 tokenizer + 递归下降 parser 求值,只认一个
+ *    固定的小语言(数字 / + - * / / 括号 / min,max,abs,round / `#id.x|y|w|h` 几何引用)。
+ *    任何越界字符 → 求值失败(返回 undefined),不执行。
+ *  - **只引用元素几何**(x/y/w/h),**不碰卡片内容**(title/body)→ 无隐私泄漏
+ *    (对齐 AI 隐私:content 不外发;这里连内部求值都只读几何)。
+ *  - 除零 → 0;非有限结果(NaN/Infinity)→ 0。递归深度上限,防 `((((…))))` 栈炸(DoS)。
+ *
+ * 语义:apply 时(snapshot 批量)求值,结果写 text 元素的 text;原式存 element.meta.compute
+ * 往返对称。**live 重算**(被引用元素一动就重算)是文档化的后续增强,v7 只在每次 apply 重算。
+ *
+ * 语言(EBNF):
+ *   expr   = term (('+'|'-') term)*
+ *   term   = factor (('*'|'/') factor)*
+ *   factor = '-' factor | number | ref | func '(' args ')' | '(' expr ')'
+ *   ref    = '#' idChar+ '.' ('x'|'y'|'w'|'h')
+ *   func   = 'min' | 'max' | 'abs' | 'round'     # min/max ≥1 参,abs/round 恰 1 参
+ *   args   = expr (',' expr)*
+ */
+/** 递归深度上限(防嵌套括号栈炸;200 字公式远到不了,纯防御)。 */
+const MAX_DEPTH = 64;
+/** 数字格式化:去浮点噪声,最多 2 位小数,去尾 0(12.00→12, 3.50→3.5)。 */
+export function formatComputeNumber(n) {
+    if (!Number.isFinite(n))
+        return '0';
+    const rounded = Math.round(n * 100) / 100;
+    return String(rounded);
+}
+const FUNC_NAMES = new Set(['min', 'max', 'abs', 'round']);
+const FIELDS = new Set(['x', 'y', 'w', 'h']);
+// id 字符集(与 dsl.peggy idChars 一致);`-` 在内,但 ref 必以 `#` 起头,故不与减号冲突。
+const ID_CHAR = /[a-zA-Z0-9_:-]/;
+/** tokenize:越界字符直接 throw(求值失败)。行级无换行(公式单行)。 */
+function tokenize(src) {
+    const toks = [];
+    let i = 0;
+    const n = src.length;
+    while (i < n) {
+        const ch = src[i];
+        if (ch === ' ' || ch === '\t') {
+            i += 1;
+            continue;
+        }
+        if (ch === '#') {
+            i += 1;
+            let id = '';
+            while (i < n && ID_CHAR.test(src[i])) {
+                id += src[i];
+                i += 1;
+            }
+            if (id === '')
+                throw new Error('empty ref id');
+            if (src[i] !== '.')
+                throw new Error('ref missing .field');
+            i += 1; // consume '.'
+            let field = '';
+            while (i < n && /[a-z]/.test(src[i])) {
+                field += src[i];
+                i += 1;
+            }
+            if (!FIELDS.has(field))
+                throw new Error(`bad ref field: ${field}`);
+            toks.push({ t: 'ref', id, field: field });
+            continue;
+        }
+        if ((ch >= '0' && ch <= '9') || ch === '.') {
+            let num = '';
+            while (i < n && ((src[i] >= '0' && src[i] <= '9') || src[i] === '.')) {
+                num += src[i];
+                i += 1;
+            }
+            const v = Number(num);
+            if (!Number.isFinite(v))
+                throw new Error(`bad number: ${num}`);
+            toks.push({ t: 'num', v });
+            continue;
+        }
+        if ((ch >= 'a' && ch <= 'z') || (ch >= 'A' && ch <= 'Z')) {
+            let name = '';
+            while (i < n && /[a-zA-Z]/.test(src[i])) {
+                name += src[i];
+                i += 1;
+            }
+            if (!FUNC_NAMES.has(name))
+                throw new Error(`unknown func: ${name}`);
+            toks.push({ t: 'func', name: name });
+            continue;
+        }
+        if (ch === '+' || ch === '-' || ch === '*' || ch === '/') {
+            toks.push({ t: 'op', v: ch });
+            i += 1;
+            continue;
+        }
+        if (ch === '(') {
+            toks.push({ t: 'lp' });
+            i += 1;
+            continue;
+        }
+        if (ch === ')') {
+            toks.push({ t: 'rp' });
+            i += 1;
+            continue;
+        }
+        if (ch === ',') {
+            toks.push({ t: 'comma' });
+            i += 1;
+            continue;
+        }
+        throw new Error(`bad char: ${ch}`);
+    }
+    return toks;
+}
+function errMsg(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/**
+ * 求值 `@compute` 公式(同 evalCompute,但暴露失败原因 error 供 apply 诊断)。
+ * 成功 → { value: 有限数 };任何失败(语法 / 未解析引用 / 越界)→ { value: undefined, error }。
+ * 永不抛错。resolve 用来把 `#id.field` 解析成几何值。
+ */
+export function evalComputeDetail(expr, resolve) {
+    if (typeof expr !== 'string' || expr.trim() === '')
+        return { value: undefined };
+    let toks;
+    try {
+        toks = tokenize(expr);
+    }
+    catch (e) {
+        return { value: undefined, error: errMsg(e) };
+    }
+    if (toks.length === 0)
+        return { value: undefined };
+    let pos = 0;
+    const peek = () => toks[pos];
+    const next = () => toks[pos++];
+    function parseExpr(depth) {
+        if (depth > MAX_DEPTH)
+            throw new Error('too deep');
+        let left = parseTerm(depth + 1);
+        for (;;) {
+            const tk = peek();
+            if (tk && tk.t === 'op' && (tk.v === '+' || tk.v === '-')) {
+                next();
+                const right = parseTerm(depth + 1);
+                left = tk.v === '+' ? left + right : left - right;
+            }
+            else {
+                return left;
+            }
+        }
+    }
+    function parseTerm(depth) {
+        if (depth > MAX_DEPTH)
+            throw new Error('too deep');
+        let left = parseFactor(depth + 1);
+        for (;;) {
+            const tk = peek();
+            if (tk && tk.t === 'op' && (tk.v === '*' || tk.v === '/')) {
+                next();
+                const right = parseFactor(depth + 1);
+                if (tk.v === '*')
+                    left = left * right;
+                else
+                    left = right === 0 ? 0 : left / right; // 除零 → 0(安全,不产 Infinity)
+            }
+            else {
+                return left;
+            }
+        }
+    }
+    function parseFactor(depth) {
+        if (depth > MAX_DEPTH)
+            throw new Error('too deep');
+        const tk = next();
+        if (!tk)
+            throw new Error('unexpected end');
+        // 一元负号
+        if (tk.t === 'op' && tk.v === '-')
+            return -parseFactor(depth + 1);
+        if (tk.t === 'num')
+            return tk.v;
+        if (tk.t === 'ref') {
+            const g = resolve(tk.id);
+            if (g === undefined)
+                throw new Error(`unresolved ref: #${tk.id}`);
+            const v = g[tk.field];
+            if (!Number.isFinite(v))
+                throw new Error(`non-finite geom: #${tk.id}.${tk.field}`);
+            return v;
+        }
+        if (tk.t === 'func') {
+            const lp = next();
+            if (!lp || lp.t !== 'lp')
+                throw new Error('func missing (');
+            const args = [];
+            // 允许 min() 空?不 —— 至少 1 参。
+            args.push(parseExpr(depth + 1));
+            while (peek() && peek().t === 'comma') {
+                next();
+                args.push(parseExpr(depth + 1));
+            }
+            const rp = next();
+            if (!rp || rp.t !== 'rp')
+                throw new Error('func missing )');
+            switch (tk.name) {
+                case 'min':
+                    return Math.min(...args);
+                case 'max':
+                    return Math.max(...args);
+                case 'abs':
+                    if (args.length !== 1)
+                        throw new Error('abs expects 1 arg');
+                    return Math.abs(args[0]);
+                case 'round':
+                    if (args.length !== 1)
+                        throw new Error('round expects 1 arg');
+                    return Math.round(args[0]);
+            }
+        }
+        if (tk.t === 'lp') {
+            const v = parseExpr(depth + 1);
+            const rp = next();
+            if (!rp || rp.t !== 'rp')
+                throw new Error('missing )');
+            return v;
+        }
+        throw new Error('unexpected token');
+    }
+    try {
+        const result = parseExpr(0);
+        if (pos !== toks.length)
+            return { value: undefined, error: 'trailing tokens' }; // 尾部残余 → 语法错
+        return { value: Number.isFinite(result) ? result : 0 };
+    }
+    catch (e) {
+        return { value: undefined, error: errMsg(e) };
+    }
+}
+/**
+ * 求值 `@compute` 公式(薄封装,仅返回 value);需失败原因用 {@link evalComputeDetail}。
+ * 成功 → 有限数;任何失败 → undefined。永不抛错。
+ */
+export function evalCompute(expr, resolve) {
+    return evalComputeDetail(expr, resolve).value;
+}