@wscytz/dsl 0.0.0-stage → 0.1.0

package/dist/dsl-relational-solver.d.ts

@@ -0,0 +1,47 @@
+/**
+ * dsl-relational-solver — 解析后、apply 前,把 relational card op
+ * (`right-of`/`below #anchor`)解成绝对坐标 op。纯函数,永不抛错。
+ *
+ * 【 provenance 】原 apps/web/src/features/ai/relational-solver.ts(B 工程 pilot),
+ * 2026-10-24 引擎剥离(execution-intent 第 1 步)入包:解算器是 DSL 语义的一半,
+ * 应与 parser 同住,任何宿主(web / CLI / 外部项目)都能把文字解成坐标。
+ * 原文件删除,web 侧消费改走本包 barrel。
+ *
+ * 设计(见 cys-derivative/paper/experiment/b-relational-dsl-pilot-design.md):
+ * - 单遍顺序求解:rel op anchor 到**已处理**元素(同批更早 op 的绝对坐标已知,或画布已有的 card)
+ * - right-of #X:x = X.x + X.w + gap;y = X.y
+ * - below    #X:y = X.y + X.h + gap;x = X.x
+ * - v9 组级相对锚:right-of @G = 贴组 G 当前已解成员包围盒右缘(y=bbox.minY);
+ *   below @G = 贴 bbox 下缘(x=bbox.minX)。bbox lazy 求值、顺序敏感(组员先写)。
+ * - anchor 不存在(前向引用 / 指向幽灵 id)→ diagnostic(op 保留占位坐标,apply 自己 skip/create)
+ * - 环检测:单遍天然防环(anchor 必须已在 geom,前向引用直接 diagnostic)
+ * - 默认 card 尺寸 240×120(op.w/h undefined + 非 existing 时);existing card 用其真实 w/h
+ *
+ * 与 sanitize 协作:applyLayout 入口先 sanitize(修正 size/coord/id)再 solve(rel → 绝对)。
+ * diagnostic 复用 SanitizeDiagnostic 形态,apply-layout 合并透出。
+ */
+import type { DslOp, DslCardOp } from './dsl-parser.js';
+import type { SanitizeDiagnostic } from './dsl-sanitize.js';
+/** 已知几何(anchor 查找用)。来自画布现有 card 或同批更早 op。
+ *  v9:group 为可选组名(v9 组级相对锚用;web 侧由 element.meta.group 填充)。 */
+export interface ExistingGeom {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    group?: string;
+}
+export interface SolveResult {
+    ops: DslOp[];
+    diagnostics: SanitizeDiagnostic[];
+}
+/**
+ * 解 relational card op → 绝对坐标 op。
+ *
+ * @param ops sanitize 后的 ops(含 rel card + 绝对 card + free + arrow)
+ * @param existingGeometry 画布现有 card 的 id→几何(seed geom,让 rel 能 anchor 到画布已有 card)
+ * @returns { ops: 全绝对坐标 op(rel 已剥离), diagnostics: anchor 缺失等 }
+ */
+export declare function solveRelational(ops: DslOp[], existingGeometry?: Map<string, ExistingGeom>): SolveResult;
+/** 仅供测试/类型导出:从 DslCardOp 判定是否 relational(apply 层不直接用)。 */
+export declare function isRelationalCard(op: DslCardOp): boolean;

package/dist/dsl-relational-solver.js

@@ -0,0 +1,221 @@
+import { DSL_MAX_COORD } from './dsl-sanitize.js';
+/** v9 组级相对锚:求某组**当前已入 geom**成员的包围盒(lazy,求值顺序敏感——
+ *  同批更早的 rel 落点也计入,更晚的不回溯;组内无人 → undefined,由调用方产 diagnostic)。
+ *  broken 占位卡(anchor 缺失 / 组锚失败,坐标无意义)不进 bbox——防 (0,0) 占位
+ *  把包围盒拖向画布原点、污染后续组锚落点。 */
+function groupBBox(geom, group, broken) {
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    let found = false;
+    for (const [id, g] of geom.entries()) {
+        if (g.group !== group || broken.has(id))
+            continue;
+        found = true;
+        if (g.x < minX)
+            minX = g.x;
+        if (g.y < minY)
+            minY = g.y;
+        if (g.x + g.w > maxX)
+            maxX = g.x + g.w;
+        if (g.y + g.h > maxY)
+            maxY = g.y + g.h;
+    }
+    return found ? { x: minX, y: minY, w: maxX - minX, h: maxY - minY } : undefined;
+}
+/** card 默认尺寸(与 apply-layout applyCardOp 一致:op.w ?? 240 / op.h ?? 120)。 */
+const DEFAULT_CARD_W = 240;
+const DEFAULT_CARD_H = 120;
+/**
+ * 解 relational card op → 绝对坐标 op。
+ *
+ * @param ops sanitize 后的 ops(含 rel card + 绝对 card + free + arrow)
+ * @param existingGeometry 画布现有 card 的 id→几何(seed geom,让 rel 能 anchor 到画布已有 card)
+ * @returns { ops: 全绝对坐标 op(rel 已剥离), diagnostics: anchor 缺失等 }
+ */
+export function solveRelational(ops, existingGeometry) {
+    const diagnostics = [];
+    const out = [];
+    // seed:画布现有 card 几何(复制,不污染入参)
+    const geom = new Map(existingGeometry);
+    // anchor 缺失的 card(占位 geom)→ 依赖它的下游 rel 也判 broken,产链式 diagnostic
+    // (否则下游会静默解析到占位坐标,用户看到卡在怪位置无信号)
+    const brokenAnchors = new Set();
+    let i = 0;
+    for (const op of ops) {
+        const idx = i++;
+        if (op.type !== 'card') {
+            // free / arrow:透传(非 pilot 关系式范围)
+            out.push(op);
+            continue;
+        }
+        const cardId = String(op.cardId);
+        // 解析本 card 的几何宽高:op 显式 > existing 真实 > 默认
+        const exist = geom.get(cardId);
+        const w = op.w ?? exist?.w ?? DEFAULT_CARD_W;
+        const h = op.h ?? exist?.h ?? DEFAULT_CARD_H;
+        if (op.rel) {
+            // v9:anchor 双形态 —— #id(单卡 geom 条目)/ @组名(组包围盒,lazy 求当前已解成员;
+            // broken 占位不进 bbox,见 groupBBox)
+            const isGroup = op.rel.anchorGroup === true;
+            const anchorRect = isGroup
+                ? groupBBox(geom, op.rel.anchor, brokenAnchors)
+                : geom.get(op.rel.anchor);
+            if (!anchorRect) {
+                // anchor 不存在(前向引用 / 幽灵 id / 组锚无成员)→ diagnostic,op 保留占位坐标
+                diagnostics.push({
+                    opIndex: idx,
+                    message: isGroup
+                        ? `relational card #${cardId} 的组锚 @${op.rel.anchor} 无已解成员(组不存在,或组员都在本卡之后——组锚按书写顺序解)`
+                        : `relational card #${cardId} 的 anchor #${op.rel.anchor} 不存在(画布/同批更早均无)`,
+                });
+                // 标 broken:下游 anchor 到本卡的 rel 也会得链式 diagnostic(否则静默解析到占位)
+                brokenAnchors.add(cardId);
+                // 剥离 rel,保留占位 x/y(apply 自己 create/skip)
+                // v9:group 继承 —— 同批更新既有卡不带 @group 时沿用 existing 组名(与 web
+                // applyCardMeta 的"不带即保留"语义一致);空串显式清组不受影响。
+                const { rel: _rel, ...rest } = op;
+                out.push({ ...rest, w, h });
+                geom.set(cardId, { x: op.x, y: op.y, w, h, group: op.group ?? exist?.group });
+                continue;
+            }
+            // 传递性断链:anchor 存在但本身是 broken 占位 → 本卡也判 broken + diagnostic(链式传播)
+            // (仅卡锚;组锚无 broken 概念——组内成员各自携带自己的诊断)
+            if (!isGroup && brokenAnchors.has(op.rel.anchor)) {
+                diagnostics.push({
+                    opIndex: idx,
+                    message: `relational card #${cardId} 的 anchor #${op.rel.anchor} 上游 anchor 缺失(链式占位,坐标可能不符预期)`,
+                });
+                brokenAnchors.add(cardId);
+            }
+            const gap = op.rel.gap;
+            // 统一放置公式(组锚即包围盒矩形):right-of → (a.x+a.w+gap, a.y 顶对齐);
+            // below → (a.x 左对齐, a.y+a.h+gap)。组右=贴 bbox 右缘、组下=贴 bbox 下缘。
+            const ax = op.rel.dir === 'right-of' ? anchorRect.x + anchorRect.w + gap : anchorRect.x;
+            const ay = op.rel.dir === 'below' ? anchorRect.y + anchorRect.h + gap : anchorRect.y;
+            // 碰撞避让:沿关系轴(below→y / right-of→x)推开已置 card,消除参照系碰撞
+            const { x, y } = resolveCollision(ax, ay, w, h, op.rel.dir === 'below' ? 'y' : 'x', geom, gap, cardId);
+            const { rel: _rel, ...rest } = op;
+            out.push({ ...rest, x, y, w, h });
+            geom.set(cardId, { x, y, w, h, group: op.group ?? exist?.group });
+            continue;
+        }
+        // 绝对 card:记录几何(供后续 rel anchor),op 原样返回(引用稳定)
+        // v5(E) keepExistingPos:op.x/y 是 parser 占位 (0,0),必须沿用 existing 真实坐标,
+        // 否则下游 rel anchor 到本卡会锚到 (0,0) 飞画布左上角。
+        if (op.keepExistingPos === true && exist) {
+            geom.set(cardId, { x: exist.x, y: exist.y, w, h, group: op.group ?? exist.group });
+        }
+        else {
+            geom.set(cardId, { x: op.x, y: op.y, w, h, group: op.group ?? exist?.group });
+        }
+        out.push(op);
+    }
+    const validated = validateSolvedCoordinates(out, existingGeometry);
+    return {
+        ops: validated.ops,
+        diagnostics: [...diagnostics, ...validated.diagnostics],
+    };
+}
+/** 仅供测试/类型导出:从 DslCardOp 判定是否 relational(apply 层不直接用)。 */
+export function isRelationalCard(op) {
+    return op.rel !== undefined;
+}
+/** AABB 相交(严格 >0 重叠面积)。纯函数,永不抛错。 */
+function rectsOverlap(a, b) {
+    return a.x < b.x + b.w && a.x + a.w > b.x && a.y < b.y + b.h && a.y + a.h > b.y;
+}
+/**
+ * 碰撞避让:card (ax,ay,w,h) 若与 geom 里任何已置 card 相交,沿 axis 单向推进越过障碍,
+ * 直到无相交(单调有界,每轮至少越过一张,≤ geom.size 轮收敛)。
+ *
+ * 为什么沿「关系自己的轴」:below 的 x 由 anchor 固定(列归属)→ 推 y 守列;
+ * right-of 的 y 由 anchor 固定(行归属)→ 推 x 守行。语义最保真。
+ * clearance = 该 card 的 @gap(与 anchor 间距一致,避让后视觉间距均匀)。
+ *
+ * 单遍不破依赖:anchor 在 op 序更早 → 避让时所有相关 card 已最终落位;后续 right-of/below
+ * 本 card 的 op 用本 card 避让后的最终 geom 派生,自动跟随,无需级联。
+ */
+function resolveCollision(ax, ay, w, h, axis, geom, clearance, selfId) {
+    // clearance 钳 ≥0:负 @gap(parser 接受负数)会让推进推不过障碍(新坐标仍相交)→ 残留重叠。
+    // 钳 0 后负 gap 退化为"卡片贴合"(clearance=0,严格 >0 不算重叠),避让仍保证清空。
+    const clr = Math.max(0, clearance);
+    // O(K log K) 排序单扫,替代原 O(N²) 多轮(每轮扫全 geom,最坏 N 轮)。
+    // 等价性:沿关系轴推进 = 跳过所有「垂直轴区间重叠 + 关系轴区间相交」的已置 card。
+    //   先筛垂直轴重叠集(只有它们可能在关系轴相撞),再按关系轴坐标升序单次扫描:
+    //   遇相交则推过其尾 + clr。cur 只增 → 已扫过的(更小坐标)不会被新位置再相交
+    //   → 一遍收敛,与原「多轮取 max」同果(已手验相邻/间隔/负 gap 多 case)。
+    if (axis === 'y') {
+        // below:x 由 anchor 固定(列归属)→ 沿 y 推。筛 x 区间重叠的障碍,按 y 升序。
+        const hit = [];
+        for (const [id, g] of geom) {
+            if (id === selfId)
+                continue;
+            if (ax < g.x + g.w && ax + w > g.x)
+                hit.push(g);
+        }
+        hit.sort((a, b) => a.y - b.y);
+        let y = ay;
+        for (const g of hit) {
+            if (y < g.y + g.h && g.y < y + h)
+                y = g.y + g.h + clr;
+        }
+        return { x: ax, y };
+    }
+    // right-of:y 由 anchor 固定(行归属)→ 沿 x 推。筛 y 区间重叠的障碍,按 x 升序。
+    const hit = [];
+    for (const [id, g] of geom) {
+        if (id === selfId)
+            continue;
+        if (ay < g.y + g.h && ay + h > g.y)
+            hit.push(g);
+    }
+    hit.sort((a, b) => a.x - b.x);
+    let x = ax;
+    for (const g of hit) {
+        if (x < g.x + g.w && g.x < x + w)
+            x = g.x + g.w + clr;
+    }
+    return { x, y: ay };
+}
+/**
+ * solve 后的第二道坐标门。关系偏移和碰撞推进都可能把已 sanitize 的输入重新推到
+ * 边界外；这里钳回统一坐标域，并在钳位造成重叠时明确诊断。
+ */
+function validateSolvedCoordinates(ops, existingGeometry) {
+    const diagnostics = [];
+    const geom = new Map(existingGeometry);
+    const validated = ops.map((op, opIndex) => {
+        if (op.type !== 'card')
+            return op;
+        const id = String(op.cardId);
+        const existing = geom.get(id);
+        const w = op.w ?? existing?.w ?? DEFAULT_CARD_W;
+        const h = op.h ?? existing?.h ?? DEFAULT_CARD_H;
+        const x = Math.min(DSL_MAX_COORD, Math.max(-DSL_MAX_COORD, op.x));
+        const y = Math.min(DSL_MAX_COORD, Math.max(-DSL_MAX_COORD, op.y));
+        const changed = x !== op.x || y !== op.y;
+        const next = { x, y, w, h };
+        if (changed) {
+            diagnostics.push({
+                opIndex,
+                message: `relational card #${id} 的坐标已限制到 +/-${DSL_MAX_COORD} 边界`,
+            });
+            for (const [otherId, other] of geom) {
+                if (otherId === id)
+                    continue;
+                if (rectsOverlap(next, other)) {
+                    diagnostics.push({
+                        opIndex,
+                        message: `card #${id} 在坐标边界钳位后与 #${otherId} 碰撞`,
+                    });
+                    break;
+                }
+            }
+        }
+        geom.set(id, next);
+        return changed ? { ...op, x, y } : op;
+    });
+    return { ops: validated, diagnostics };
+}

package/dist/dsl-sanitize.d.ts

@@ -0,0 +1,56 @@
+/**
+ * DSL Sanitize 层 —— 解析后、apply 前,纯函数修正 LLM 常见错误 + 产 diagnostic。
+ *
+ * 学 tldraw agent sanitization(corrects non-existent IDs / ensures unique IDs /
+ * normalizes coordinates):不指望 LLM 算对,用引擎层兜底。
+ *
+ * 契约(不可破):
+ * - 纯函数,永不抛错(继承 dsl-robustness.test.ts 的 36 测试契约)
+ * - 合法 op 原样返回(引用稳定 —— sanitize 是 opt-in 修正,不改合规输入)
+ * - free arrow 的 w/h 不动(负值编码方向,dsl-parser.ts:143)
+ * - 不破坏 roundtrip byte-equal(dsl-e2e-roundtrip.test.ts):合法小卡(如 10×10)原样往返
+ * - 无 ctx 时不产 diagnostic(case 6 等不依赖 ctx 的路径仍可用)
+ *
+ * 接入:apply-layout.ts 的 applyLayout 入口(所有 5+ 调用点必经,零调用方改)。
+ * case 清单见 cys-stift-docs/docs/specs/2026-07-07-dsl-sanitize-layer-draft.md。
+ * 当前实现:case 6(非法 size)+ case 1/11(card 不存在 diagnostic)+ case 7(arrow 端点 diagnostic)
+ *              + case 3(free op 跨 kind 告警)。
+ */
+import type { DslOp } from './dsl-parser.js';
+/** Sanitize 诊断:亮给用户/AI 看(让 AgentConfirmCard/dsl-dialog 把"引用了不存在的卡 #X"反馈出来)。 */
+export type SanitizeDiagnostic = {
+    opIndex: number;
+    message: string;
+};
+export interface SanitizeResult {
+    ops: DslOp[];
+    diagnostics: SanitizeDiagnostic[];
+}
+/** 上下文:画布上已有的 card/free id(case 1/11/7 判断 id 是否存在用)。可选 —— 无 ctx 时不产 diagnostic。
+ *  existingFreeKinds(case 3 跨 kind 告警):host 的 free 元素 id → kind(rect/text/frame),
+ *  用来检测 free op 带了 host 已有但 kind 不同的 id(apply 会 mint 新 id 而非更新)。 */
+export interface SanitizeCtx {
+    existingCardIds?: Set<string>;
+    existingFreeIds?: Set<string>;
+    existingFreeKinds?: Map<string, 'rect' | 'text' | 'frame'>;
+}
+/** card/rect/frame 的 w/h MAX 上限(防 LLM 生成超大跑出可视区)。
+ *  不设 MIN 下界 —— 合法小卡(如 10×10)必须原样往返(commit fac88bb 负坐标契约的同理)。 */
+export declare const DSL_MAX_SIZE = 2000;
+export declare const DSL_MAX_GAP = 2000;
+/** v5:@title/@content 长度截断共用 dsl-grammar 的 truncateDslText(代理对安全;G/H)——
+ *  parser 已截断,sanitize 是 apply 前第二道防线(幂等,合规输入原样)。 */
+/** x/y 坐标 MAX 绝对值(防 LLM 生成 1e6 跑出可视区)。保负向 —— 负坐标合法(画布 pan 允许,
+ *  commit fac88bb 契约),只钳极端有限值,不钳合理负值(如 -100)。 */
+export declare const DSL_MAX_COORD = 10000;
+/**
+ * Sanitize 一批 DSL ops。纯函数,永不抛错。
+ *
+ * 单个 op sanitize 失败(异常或未知类型)→ 原样保留,让 apply 自己 skip。
+ * 保守策略:宁可让 apply 阶段 diagnostic,也不在 sanitize 丢数据。
+ *
+ * @param ops parseDslWithDiagnostics 输出的 ops
+ * @param ctx 画布现有 id(case 1/11/7 diagnostic 用;可选,无则不产 diagnostic)
+ * @returns { ops: 修正后的 ops, diagnostics: 诊断 }
+ */
+export declare function sanitizeDslOps(ops: DslOp[], ctx?: SanitizeCtx): SanitizeResult;

package/dist/dsl-sanitize.js

@@ -0,0 +1,257 @@
+import { DSL_MAX_TEXT_LEN, DSL_MAX_CONTENT_LEN, DSL_MAX_HREF_TARGETS, DSL_MAX_TAG_COUNT, DSL_MAX_LINK_COUNT, DSL_MAX_CODE_BLOCKS, DSL_MAX_QUOTES, DSL_CARD_TYPES, DSL_RESERVED_GROUP_ANCHOR_WORDS, truncateDslText, } from './dsl-grammar.js';
+/** card/rect/frame 的 w/h MAX 上限(防 LLM 生成超大跑出可视区)。
+ *  不设 MIN 下界 —— 合法小卡(如 10×10)必须原样往返(commit fac88bb 负坐标契约的同理)。 */
+export const DSL_MAX_SIZE = 2000;
+export const DSL_MAX_GAP = 2000;
+/** w/h sanitize:非正(≤0)/非有限 → undefined(让 apply 用 shape 默认 240×120 等);
+ *  超大 → MAX;合法正数(含小卡)原样保留。 */
+function sanitizeSize(n) {
+    if (n === undefined)
+        return undefined;
+    if (!Number.isFinite(n) || n <= 0)
+        return undefined;
+    return Math.min(DSL_MAX_SIZE, n);
+}
+/** v5:@title/@content 长度截断共用 dsl-grammar 的 truncateDslText(代理对安全;G/H)——
+ *  parser 已截断,sanitize 是 apply 前第二道防线(幂等,合规输入原样)。 */
+/** x/y 坐标 MAX 绝对值(防 LLM 生成 1e6 跑出可视区)。保负向 —— 负坐标合法(画布 pan 允许,
+ *  commit fac88bb 契约),只钳极端有限值,不钳合理负值(如 -100)。 */
+export const DSL_MAX_COORD = 10000;
+/** 坐标钳位:n 已是有限数(parse POS_RE 保证) → 钳 [-MAX_COORD, MAX_COORD];防御性防非有限(→0)。 */
+function clampCoord(n) {
+    if (!Number.isFinite(n))
+        return 0;
+    return Math.min(DSL_MAX_COORD, Math.max(-DSL_MAX_COORD, n));
+}
+/** card op:case 6(size)+ case 1/11(id 不存在)+ case 2b(create id 冲突预检)diagnostic。 */
+function sanitizeCard(op, idx, ctx, diagnostics) {
+    // case 1+11:无 create flag + id 不在 existingCardIds → diagnostic
+    // (apply 会 skip,sanitize 额外提示让用户/AI 知道"引用了不存在的卡,想新建加 create")
+    if (ctx?.existingCardIds !== undefined && !op.create && !ctx.existingCardIds.has(String(op.cardId))) {
+        diagnostics.push({
+            opIndex: idx,
+            message: `card #${op.cardId} 不存在于画布(若想新建需加 create 标记)`,
+        });
+    }
+    // create flag + id 已存在 → plan 阶段跳过,不把 create 偷换成 update。
+    if (op.create && ctx?.existingCardIds !== undefined && ctx.existingCardIds.has(String(op.cardId))) {
+        diagnostics.push({
+            opIndex: idx,
+            message: `create card #${op.cardId} id 已存在(冲突,建卡将失败)`,
+        });
+    }
+    // 关系间距必须非负且有上限。solver 会沿关系轴累加 gap,所以它与坐标本身
+    // 一样属于输入边界,不能等 solve 后才处理。
+    let rel = op.rel;
+    if (op.rel) {
+        // v9:锚位裸名与内建指令同名(grammar 故意放行以保精确报错,见 dsl.peggy groupRef)→
+        // 诊断 + 剥 rel。引号形式 @"gap" 是显式意图,不受此限。
+        if (op.rel.anchorGroup === true &&
+            op.rel.anchorQuoted !== true &&
+            DSL_RESERVED_GROUP_ANCHOR_WORDS.includes(op.rel.anchor)) {
+            diagnostics.push({
+                opIndex: idx,
+                message: `card #${op.cardId} 的组锚 @${op.rel.anchor} 与内建指令同名,已剥除——组名避开指令词;确有同名组用 @"${op.rel.anchor}" 引用;组间距写在锚后(如 right-of @组名 @gap(30))`,
+            });
+            rel = undefined;
+        }
+        else {
+            const gap = Number.isFinite(op.rel.gap)
+                ? Math.min(DSL_MAX_GAP, Math.max(0, op.rel.gap))
+                : 0;
+            if (gap !== op.rel.gap) {
+                diagnostics.push({
+                    opIndex: idx,
+                    message: `card #${op.cardId} 的 gap 已限制到 0..${DSL_MAX_GAP}`,
+                });
+                rel = { ...op.rel, gap };
+            }
+        }
+    }
+    // case 6:size 修正 + case 5:坐标钳位 + v5:title/content 截断
+    const w = sanitizeSize(op.w);
+    const h = sanitizeSize(op.h);
+    const x = clampCoord(op.x);
+    const y = clampCoord(op.y);
+    const title = op.title !== undefined ? truncateDslText(op.title, DSL_MAX_TEXT_LEN) : op.title;
+    const content = op.content !== undefined ? truncateDslText(op.content, DSL_MAX_CONTENT_LEN) : op.content;
+    // v7:group 二次截断 + href 二次截断到上限(幂等 —— parser 已截,这里防程序构造 op 绕过)。
+    //     href.slice 仅在超长时发生,否则保引用(不破坏合规输入引用稳定 / round-trip byte-equal)。
+    const group = op.group !== undefined ? truncateDslText(op.group, DSL_MAX_TEXT_LEN) : op.group;
+    const href = op.href !== undefined && op.href.length > DSL_MAX_HREF_TARGETS
+        ? op.href.slice(0, DSL_MAX_HREF_TARGETS)
+        : op.href;
+    // v8:结构化字段二次防线(幂等 —— parser 已截/校验,这里防程序构造 op 绕过)。
+    //     引用稳定:仅在真被改时才产新数组/对象,合规输入原样(不破 round-trip byte-equal)。
+    const cardType = op.cardType !== undefined && !DSL_CARD_TYPES.includes(op.cardType)
+        ? undefined
+        : op.cardType;
+    const tags = op.tags !== undefined && op.tags.length > DSL_MAX_TAG_COUNT
+        ? op.tags.slice(0, DSL_MAX_TAG_COUNT)
+        : op.tags;
+    const links = op.links !== undefined && op.links.length > DSL_MAX_LINK_COUNT
+        ? op.links.slice(0, DSL_MAX_LINK_COUNT)
+        : op.links;
+    let code = op.code;
+    if (code !== undefined) {
+        const capped = code.length > DSL_MAX_CODE_BLOCKS ? code.slice(0, DSL_MAX_CODE_BLOCKS) : code;
+        let changed = capped !== code;
+        const mapped = capped.map((b) => {
+            const c = truncateDslText(b.code, DSL_MAX_CONTENT_LEN);
+            if (c !== b.code) {
+                changed = true;
+                return { ...b, code: c };
+            }
+            return b;
+        });
+        code = changed ? mapped : op.code;
+    }
+    let quotes = op.quotes;
+    if (quotes !== undefined) {
+        const capped = quotes.length > DSL_MAX_QUOTES ? quotes.slice(0, DSL_MAX_QUOTES) : quotes;
+        let changed = capped !== quotes;
+        const mapped = capped.map((q) => {
+            const t = truncateDslText(q.text, DSL_MAX_CONTENT_LEN);
+            if (t !== q.text) {
+                changed = true;
+                return { ...q, text: t };
+            }
+            return q;
+        });
+        quotes = changed ? mapped : op.quotes;
+    }
+    if (w === op.w && h === op.h && x === op.x && y === op.y && rel === op.rel &&
+        title === op.title && content === op.content && group === op.group && href === op.href &&
+        cardType === op.cardType && tags === op.tags && links === op.links && code === op.code && quotes === op.quotes) {
+        return op;
+    }
+    return { ...op, w, h, x, y, rel, title, content, group, href, cardType, tags, links, code, quotes };
+}
+/** free shape(rect/text/frame)op:case 6(size)+ case 3(跨 kind 告警)。
+ *  case 3:op.id 命中 host 已有但 kind 不同的元素 → diagnostic(apply 会 mint 新 id,提示用户/AI)。 */
+function sanitizeFree(op, idx, ctx, diagnostics) {
+    // case 3:跨 kind 告警(op shape ≠ host 已有同 id 元素的 kind)
+    // applyFreeOp update 路径有 kind 守卫 → 不命中 → create 路径 mint uid(不覆盖,安全);
+    // sanitize 额外产 diagnostic 让用户/AI 知道 id 被复用了。
+    if (op.id && ctx?.existingFreeKinds !== undefined) {
+        const hostKind = ctx.existingFreeKinds.get(op.id);
+        if (hostKind !== undefined && hostKind !== op.shape) {
+            diagnostics.push({
+                opIndex: idx,
+                message: `${op.shape} #${op.id} 与已有 ${hostKind} 跨 kind,将新建而非更新`,
+            });
+        }
+    }
+    // case 6:size 修正 + case 5:坐标钳位
+    const w = sanitizeSize(op.w);
+    const h = sanitizeSize(op.h);
+    const x = clampCoord(op.x);
+    const y = clampCoord(op.y);
+    // v7:group 二次截断(幂等;compute 仅 text,parser 已截断,这里不重复以避联合类型分支)。
+    const group = op.group !== undefined ? truncateDslText(op.group, DSL_MAX_TEXT_LEN) : op.group;
+    if (w === op.w && h === op.h && x === op.x && y === op.y && group === op.group)
+        return op;
+    return { ...op, w, h, x, y, group };
+}
+/** arrow op:case 7(端点不存在 diagnostic)。free arrow 不检查(无端点)。
+ *  case 4(端点重写)待后续。 */
+function sanitizeArrow(op, idx, existingIds, diagnostics) {
+    const isFreeArrow = op.freeArrow || (!op.from && !op.to);
+    if (!isFreeArrow && existingIds !== undefined) {
+        if (op.from && !existingIds.has(op.from)) {
+            diagnostics.push({ opIndex: idx, message: `arrow from #${op.from} 不存在于画布` });
+        }
+        if (op.to && !existingIds.has(op.to)) {
+            diagnostics.push({ opIndex: idx, message: `arrow to #${op.to} 不存在于画布` });
+        }
+    }
+    // case 5:free arrow x/y 钳位(位置);curve 控制点 / elbow 折点 同为页坐标,一并钳
+    //  (同 case-5 防 LLM 生成超大跑出可视区;applyArrowOp 原样写 host 无二次钳)。
+    //  w/h 不动(负值编码方向)。关系箭头无 x/y/curve/elbow(undefined 透传)。
+    const x = op.x !== undefined ? clampCoord(op.x) : undefined;
+    const y = op.y !== undefined ? clampCoord(op.y) : undefined;
+    const curve = op.curve !== undefined ? { cx: clampCoord(op.curve.cx), cy: clampCoord(op.curve.cy) } : undefined;
+    const elbow = op.elbow !== undefined ? op.elbow.map((p) => ({ x: clampCoord(p.x), y: clampCoord(p.y) })) : undefined;
+    // 引用稳定:仅在某值实际被钳时才算改(合法 curve/elbow 原样往返 byte-equal)。
+    // NaN 经 clampCoord→0,0!==NaN 为 true → 必判为改(顺带修非有限 curve/elbow)。
+    const curveChanged = op.curve !== undefined && (curve.cx !== op.curve.cx || curve.cy !== op.curve.cy);
+    const elbowChanged = op.elbow !== undefined &&
+        op.elbow.some((p, i) => elbow[i].x !== p.x || elbow[i].y !== p.y);
+    if (x === op.x && y === op.y && !curveChanged && !elbowChanged)
+        return op;
+    return { ...op, x, y, curve, elbow };
+}
+/**
+ * Sanitize 一批 DSL ops。纯函数,永不抛错。
+ *
+ * 单个 op sanitize 失败(异常或未知类型)→ 原样保留,让 apply 自己 skip。
+ * 保守策略:宁可让 apply 阶段 diagnostic,也不在 sanitize 丢数据。
+ *
+ * @param ops parseDslWithDiagnostics 输出的 ops
+ * @param ctx 画布现有 id(case 1/11/7 diagnostic 用;可选,无则不产 diagnostic)
+ * @returns { ops: 修正后的 ops, diagnostics: 诊断 }
+ */
+export function sanitizeDslOps(ops, ctx) {
+    const diagnostics = [];
+    const out = [];
+    // 永不抛错契约:非数组入参(null/undefined/非数组,仅可能由 as any 误传)→ 当空,不抛。
+    const src = Array.isArray(ops) ? ops : [];
+    // 预合并 existingIds(arrow 端点检查用 —— 端点可能是 card 或 free 元素)
+    let existingIds;
+    if (ctx?.existingCardIds || ctx?.existingFreeIds) {
+        existingIds = new Set();
+        ctx.existingCardIds?.forEach((id) => existingIds.add(id));
+        ctx.existingFreeIds?.forEach((id) => existingIds.add(id));
+    }
+    // Same-batch declarations are valid arrow endpoints. Persistence may still
+    // fail later; commitApplyPlan handles that dependency failure explicitly.
+    if (existingIds) {
+        for (const op of src) {
+            if (op.type === 'card' && op.create)
+                existingIds.add(String(op.cardId));
+            if (op.type === 'free' && op.id)
+                existingIds.add(op.id);
+        }
+    }
+    let i = 0;
+    // 重复 id 探测(card/free 同名空间):下游 geom 按 id 覆盖 → 后者静默覆盖前者。
+    // 以前零信号(两个 #c1 无声合并);现记 diagnostic,不丢数据(保守策略不变)。
+    const seenIds = new Set();
+    for (const op of src) {
+        const idx = i++;
+        try {
+            switch (op.type) {
+                case 'card':
+                    if (op.cardId != null) {
+                        const id = String(op.cardId);
+                        if (seenIds.has(id)) {
+                            diagnostics.push({ opIndex: idx, message: `duplicate element id #${id} — later op overrides earlier` });
+                        }
+                        seenIds.add(id);
+                    }
+                    out.push(sanitizeCard(op, idx, ctx, diagnostics));
+                    break;
+                case 'free':
+                    if (op.id != null) {
+                        if (seenIds.has(op.id)) {
+                            diagnostics.push({ opIndex: idx, message: `duplicate element id #${op.id} — later op overrides earlier` });
+                        }
+                        seenIds.add(op.id);
+                    }
+                    out.push(sanitizeFree(op, idx, ctx, diagnostics));
+                    break;
+                case 'arrow':
+                    out.push(sanitizeArrow(op, idx, existingIds, diagnostics));
+                    break;
+                default:
+                    // 未知类型:原样保留(保守,让 apply 自己处理)
+                    out.push(op);
+            }
+        }
+        catch {
+            // 永不抛错契约:单个 op sanitize 失败 → 原样保留
+            out.push(op);
+        }
+    }
+    return { ops: out, diagnostics };
+}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @wscytz/dsl — cys-dsl 文本格式包(画布的双向文字表示 / 转义)。
+ *
+ * 公开 API:grammar 单一源(DSL_VERSION / KINDS / COLORS / GRAMMAR_REFERENCE)+
+ * serializer(serializeCanvas / serializeCanvasReadable / serializeElement)+
+ * Peggy parser(parseDsl / parseDslWithDiagnostics / parseDslStrictWithDiagnostics)+
+ * sanitize(sanitizeDslOps,防 LLM 产非法值不崩的 opt-in 修正层)+
+ * relational solver(solveRelational,right-of/below #anchor → 绝对坐标)+
+ * JSON Canvas 适配器(toJsonCanvas,cys-dsl → Obsidian .canvas 等通用格式)+
+ * 边界类型(types.ts,包内自持的结构性复制,compat 测试钉住)。
+ *
+ * 依赖:**零运行时依赖**——边界类型包内自持(2026-10-24 引擎剥离,execution-intent 第 1 步;
+ * 原依赖 canvas-engine/domain 仅为类型,已由 types.ts 结构性复制替代,devDependencies 保留
+ * 供 compat 测试比对)。纯逻辑,框架无关。
+ * freedraw 不在 DSL(程序自管 R2 + 渲染)。详细见仓库 README。
+ * 注意:cli.ts(node:fs)不进 barrel——CLI 经 `pnpm --filter @wscytz/dsl cli` 跑。
+ */
+export * from './dsl-grammar.js';
+export * from './canvas-dsl.js';
+export * from './dsl-parser.js';
+export * from './dsl-sanitize.js';
+export * from './dsl-compute.js';
+export * from './dsl-relational-solver.js';
+export * from './to-json-canvas.js';
+export * from './to-svg.js';
+export * from './types.js';

package/dist/index.js

@@ -0,0 +1,26 @@
+/**
+ * @wscytz/dsl — cys-dsl 文本格式包(画布的双向文字表示 / 转义)。
+ *
+ * 公开 API:grammar 单一源(DSL_VERSION / KINDS / COLORS / GRAMMAR_REFERENCE)+
+ * serializer(serializeCanvas / serializeCanvasReadable / serializeElement)+
+ * Peggy parser(parseDsl / parseDslWithDiagnostics / parseDslStrictWithDiagnostics)+
+ * sanitize(sanitizeDslOps,防 LLM 产非法值不崩的 opt-in 修正层)+
+ * relational solver(solveRelational,right-of/below #anchor → 绝对坐标)+
+ * JSON Canvas 适配器(toJsonCanvas,cys-dsl → Obsidian .canvas 等通用格式)+
+ * 边界类型(types.ts,包内自持的结构性复制,compat 测试钉住)。
+ *
+ * 依赖:**零运行时依赖**——边界类型包内自持(2026-10-24 引擎剥离,execution-intent 第 1 步;
+ * 原依赖 canvas-engine/domain 仅为类型,已由 types.ts 结构性复制替代,devDependencies 保留
+ * 供 compat 测试比对)。纯逻辑,框架无关。
+ * freedraw 不在 DSL(程序自管 R2 + 渲染)。详细见仓库 README。
+ * 注意:cli.ts(node:fs)不进 barrel——CLI 经 `pnpm --filter @wscytz/dsl cli` 跑。
+ */
+export * from './dsl-grammar.js';
+export * from './canvas-dsl.js';
+export * from './dsl-parser.js';
+export * from './dsl-sanitize.js';
+export * from './dsl-compute.js';
+export * from './dsl-relational-solver.js';
+export * from './to-json-canvas.js';
+export * from './to-svg.js';
+export * from './types.js';