@wscytz/dsl 0.0.0-stage → 0.1.1

package/dist/dsl-parser.js

@@ -0,0 +1,683 @@
+/**
+ * DSL Parser — parses AI output (or pasted/edited DSL) for canvas layout.
+ *
+ * 架构(正则 → PEG 升级,2026-07):
+ *   dsl.peggy(Peggy 语法,结构 tokenizer)—— `pnpm --filter @wscytz/dsl gen` → dsl-parser.gen.js
+ *   本文件(TS 包装层)—— 按行调用生成 parser,做语义 coercion:
+ *     Number / finite 守卫 / escape unescape / 颜色枚举校验 / elbow 拆分 / DSL_MAX_TEXT_LEN 截断
+ *   永不抛错 + 坐标恒有限 + byte-equal round-trip 契约不变(见 dsl-* 测试)。
+ *
+ * 行级解析:按 \n 切行,逐行 parse Line 规则 → {kind, ds} 结构 → build{Card,Arrow,Free}
+ * 组装 DslOp / 记 diagnostic。`#id` 也是 directive(等价旧"整行任意位置提取");directive*
+ * 内的 skipChunk 吃未知残余 → 复刻旧正则的任意位置/任意顺序容错。
+ */
+import { DSL_COLORS, DSL_COLOR_ALIASES, 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_MAX_OPS, DSL_CARD_TYPES, truncateDslText, } from './dsl-grammar.js';
+// Peggy 生成;类型垫片见 dsl-parser.gen.d.ts
+import { parse as parseLine } from './dsl-parser.gen.js';
+// ── 语义 coercion(算法搬迁自旧 extract*,行为等价)──────────────────────────────
+/** parser 接受的颜色集合 = DSL_COLORS ∪ aliases 键(dsl-sync 锁)。grey 存原样不归一。 */
+const ACCEPTED_COLORS = new Set([
+    ...DSL_COLORS,
+    ...Object.keys(DSL_COLOR_ALIASES),
+]);
+/** 字符串 → 有限数;非有限(NaN/Infinity)归 0 —— 守 robustness 契约"坐标恒有限"。 */
+function finiteNum(raw) {
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : 0;
+}
+/** 颜色校验:接受 canonical ∪ 别名键;越界(green 等)→ undefined(不静默变黑)。 */
+function validColor(raw) {
+    return ACCEPTED_COLORS.has(raw) ? raw : undefined;
+}
+/** 枚举校验:grammar 捕获原始串(`[^)]+`),这里收窄到合法值;越界 → undefined。 */
+function validEnum(raw, list) {
+    return list.includes(raw) ? raw : undefined;
+}
+/** 默认截断到 DSL_MAX_TEXT_LEN(@text/@label/@title,int 级)。@content 用
+ *  truncateDslText(…, DSL_MAX_CONTENT_LEN)(long 级)。截断实现共用 dsl-grammar 的
+ *  truncateDslText —— 代理对安全(不劈开 emoji),且 parser/sanitize 单一实现(G/H)。 */
+function truncate(v) {
+    return truncateDslText(v, DSL_MAX_TEXT_LEN);
+}
+/** quoted-string 解码,是 escapeQuoted 的逆。Peggy escChar = '\\' . —— 任何 \X 转义对;
+ *  \n→换行(v5,@content 多行 markdown),其余 \X→X(\"→", \\→\)。 */
+function unescapeQuoted(v) {
+    return v.replace(/\\(.)/g, (_, c) => (c === 'n' ? '\n' : c));
+}
+/** @elbow(x,y;x,y) 拆分:分号分隔,每个折点 x,y(支持负);过滤坏点,保好点(复刻 extractElbow)。 */
+function parseElbow(raw) {
+    const pts = raw
+        .split(';')
+        .map((pair) => pair.trim().match(/^(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)$/))
+        .filter(Boolean)
+        .map((pm) => ({ x: Number(pm[1]), y: Number(pm[2]) }));
+    return pts.length >= 1 ? pts.slice(0, 2) : undefined;
+}
+/** @href(#a;#b) 拆分(v7):`;` 分隔目标 id,每个可有可无 `#` 前缀(归一去掉)。
+ *  校验每个目标匹配 idChars(字母/数字/_/:-);过滤坏目标保好的,去重(保序),
+ *  截断到 DSL_MAX_HREF_TARGETS(防 LLM 失控膨胀)。无有效目标 → undefined。 */
+function parseHref(raw) {
+    const seen = new Set();
+    const out = [];
+    for (const part of raw.split(';')) {
+        const id = part.trim().replace(/^#/, '');
+        if (!/^[a-zA-Z0-9_:-]+$/.test(id))
+            continue; // 空 / 含非法字符 → 丢
+        if (seen.has(id))
+            continue; // 去重保序
+        seen.add(id);
+        out.push(id);
+        if (out.length >= DSL_MAX_HREF_TARGETS)
+            break; // 截断到上限
+    }
+    return out.length >= 1 ? out : undefined;
+}
+/** v8:卡片类型枚举用 dsl-grammar 的 DSL_CARD_TYPES(单一可信源;parser/sanitize 共用)。 */
+/** v8:可重复指令(strict 模式 dup 检查豁免)—— @code/@quote 一指令一块/条,多个是合法的多块/多引文,
+ *  不是重复错误。@tags/@links 仍是单指令列表(重复算 dup)。 */
+const REPEATABLE_DIRECTIVES = new Set(['code', 'quote']);
+/** @tags(a;b;c) 拆分(v8):`;` 分隔,每个 trim + decodeURIComponent(序列化侧 encode 防碰撞);
+ *  过滤空值,去重保序,截断到 DSL_MAX_TAG_COUNT。无有效 tag → undefined。是 metaTags 的逆。 */
+function parseTagList(raw) {
+    const seen = new Set();
+    const out = [];
+    for (const part of raw.split(';')) {
+        let value = part.trim();
+        if (value === '')
+            continue;
+        try {
+            value = decodeURIComponent(value);
+        }
+        catch {
+            // 非法百分号编码(如裸 `%`)→ 用原串,不丢
+        }
+        if (value === '' || seen.has(value))
+            continue;
+        seen.add(value);
+        out.push(value);
+        if (out.length >= DSL_MAX_TAG_COUNT)
+            break;
+    }
+    return out.length >= 1 ? out : undefined;
+}
+/** @links(<enc-url>;…) 拆分(v8):`;` 分隔,每个 trim + decodeURIComponent(序列化侧 encode,
+ *  URL 含 `;`/`=`/`&`);过滤空值,去重保序,截断到 DSL_MAX_LINK_COUNT。无有效 url → undefined。
+ *  产出 **URL 字符串列表**(apply 层映射 LinkPreview + fetchedAt)。是 metaLinks 的逆。 */
+function parseLinkList(raw) {
+    const seen = new Set();
+    const out = [];
+    for (const part of raw.split(';')) {
+        let url = part.trim();
+        if (url === '')
+            continue;
+        try {
+            url = decodeURIComponent(url);
+        }
+        catch {
+            // 非法百分号编码 → 用原串,不丢
+        }
+        if (url === '' || seen.has(url))
+            continue;
+        seen.add(url);
+        out.push(url);
+        if (out.length >= DSL_MAX_LINK_COUNT)
+            break;
+    }
+    return out.length >= 1 ? out : undefined;
+}
+function fold(ds, warns) {
+    const a = {};
+    for (const d of ds) {
+        if (!Array.isArray(d))
+            continue; // null(skipChunk)/非元组 → 跳过
+        const [tag, v1, v2, v3] = d;
+        switch (tag) {
+            case 'id':
+                if (a.id === undefined)
+                    a.id = String(v1);
+                break;
+            case 'pos':
+                if (!a.pos)
+                    a.pos = [finiteNum(String(v1)), finiteNum(String(v2))];
+                break;
+            case 'size':
+                if (!a.size)
+                    a.size = { w: finiteNum(String(v1)), h: finiteNum(String(v2)) };
+                break;
+            case 'color':
+                if (a.color === undefined)
+                    a.color = validColor(String(v1));
+                break;
+            case 'label':
+                if (a.label === undefined)
+                    a.label = truncate(unescapeQuoted(String(v1)));
+                break;
+            case 'text':
+                if (a.text === undefined)
+                    a.text = truncate(unescapeQuoted(String(v1)));
+                break;
+            case 'title':
+                if (a.title === undefined)
+                    a.title = truncate(unescapeQuoted(String(v1)));
+                break;
+            case 'content':
+                if (a.content === undefined)
+                    a.content = truncateDslText(unescapeQuoted(String(v1)), DSL_MAX_CONTENT_LEN);
+                break;
+            case 'dash':
+                if (!a.dash)
+                    a.dash = validEnum(String(v1), ['solid', 'dashed', 'dotted']);
+                break;
+            case 'arrowhead':
+                if (!a.arrowhead)
+                    a.arrowhead = validEnum(String(v1), ['arrow', 'triangle', 'none']);
+                break;
+            case 'route':
+                if (!a.route)
+                    a.route = validEnum(String(v1), ['straight', 'curve', 'elbow']);
+                break;
+            case 'curve':
+                if (!a.curve)
+                    a.curve = { cx: finiteNum(String(v1)), cy: finiteNum(String(v2)) };
+                break;
+            case 'elbow':
+                if (!a.elbow)
+                    a.elbow = parseElbow(String(v1));
+                break;
+            case 'rel': {
+                if (!a.rel) {
+                    // v9:锚位三形态 —— '#id'(卡锚)/ '@裸名'(组锚,CJK 可)/ '@Q引号名'(组锚,任意名)。
+                    // 保留指令词裸名 grammar 故意放行,由 sanitize 产诊断并剥 rel(保精确报错)。
+                    const anchor = String(v2);
+                    if (anchor.startsWith('@Q')) {
+                        a.rel = {
+                            dir: String(v1),
+                            anchor: unescapeQuoted(anchor.slice(2)),
+                            anchorGroup: true,
+                            anchorQuoted: true,
+                        };
+                    }
+                    else if (anchor.startsWith('@')) {
+                        a.rel = { dir: String(v1), anchor: anchor.slice(1), anchorGroup: true };
+                    }
+                    else {
+                        a.rel = { dir: String(v1), anchor };
+                    }
+                }
+                break;
+            }
+            case 'gap':
+                if (a.gap === undefined)
+                    a.gap = finiteNum(String(v1));
+                break;
+            case 'create':
+                if (!a.create)
+                    a.create = true;
+                break;
+            case 'from':
+                if (!a.from)
+                    a.from = String(v1);
+                break;
+            case 'to':
+                if (!a.to)
+                    a.to = String(v1);
+                break;
+            case 'wikilink':
+                if (!a.wikilink)
+                    a.wikilink = true;
+                break;
+            case 'group':
+                if (a.group === undefined)
+                    a.group = truncate(unescapeQuoted(String(v1)));
+                break;
+            case 'href': {
+                if (!a.href) {
+                    const raw = String(v1);
+                    a.href = parseHref(raw);
+                    // 超限截断信号(2026-10-29):此前 30→20 静默,数据丢失无信号
+                    if (a.href && warns && raw.split(';').filter((s) => s.trim() !== '').length > a.href.length) {
+                        warns.push(`@href truncated to ${DSL_MAX_HREF_TARGETS} targets (多余的 ${DSL_MAX_HREF_TARGETS} 之后的条目被截断)`);
+                    }
+                }
+                break;
+            }
+            case 'compute':
+                if (a.compute === undefined)
+                    a.compute = truncate(unescapeQuoted(String(v1)));
+                break;
+            case 'type': {
+                if (a.cardType === undefined) {
+                    const t = validEnum(String(v1), DSL_CARD_TYPES);
+                    if (t !== undefined)
+                        a.cardType = t; // 非法 type(green 等)→ 不设,不静默变 note
+                }
+                break;
+            }
+            case 'tags': {
+                if (!a.tags) {
+                    const raw = String(v1);
+                    a.tags = parseTagList(raw);
+                    if (a.tags && warns && raw.split(';').filter((s) => s.trim() !== '').length > a.tags.length) {
+                        warns.push(`@tags truncated to ${DSL_MAX_TAG_COUNT} entries`);
+                    }
+                }
+                break;
+            }
+            case 'links': {
+                if (!a.links) {
+                    const raw = String(v1);
+                    a.links = parseLinkList(raw);
+                    if (a.links && warns && raw.split(';').filter((s) => s.trim() !== '').length > a.links.length) {
+                        warns.push(`@links truncated to ${DSL_MAX_LINK_COUNT} entries`);
+                    }
+                }
+                break;
+            }
+            case 'code': {
+                // 可重复指令 → 累积成数组(非首遇优先);截断到 DSL_MAX_CODE_BLOCKS。code 走 long 级截断。
+                if (a.code === undefined)
+                    a.code = [];
+                if (a.code.length < DSL_MAX_CODE_BLOCKS) {
+                    const code = truncateDslText(unescapeQuoted(String(v2)), DSL_MAX_CONTENT_LEN);
+                    const caption = v3 == null ? undefined : unescapeQuoted(String(v3));
+                    a.code.push({
+                        language: String(v1),
+                        code,
+                        ...(caption ? { caption } : {}),
+                    });
+                }
+                else if (warns && !warns.some((w) => w.includes('@code'))) {
+                    warns.push(`@code truncated to ${DSL_MAX_CODE_BLOCKS} blocks (第 ${DSL_MAX_CODE_BLOCKS + 1} 块起被截断)`);
+                }
+                break;
+            }
+            case 'quote': {
+                // 可重复指令 → 累积成数组;截断到 DSL_MAX_QUOTES。text 走 long 级截断;空串占位归一 undefined。
+                if (a.quotes === undefined)
+                    a.quotes = [];
+                if (a.quotes.length < DSL_MAX_QUOTES) {
+                    const text = truncateDslText(unescapeQuoted(String(v1)), DSL_MAX_CONTENT_LEN);
+                    const attribution = v2 == null ? undefined : unescapeQuoted(String(v2));
+                    const sourceUrl = v3 == null ? undefined : unescapeQuoted(String(v3));
+                    a.quotes.push({
+                        text,
+                        ...(attribution ? { attribution } : {}),
+                        ...(sourceUrl ? { sourceUrl } : {}),
+                    });
+                }
+                else if (warns && !warns.some((w) => w.includes('@quote'))) {
+                    warns.push(`@quote truncated to ${DSL_MAX_QUOTES} entries (第 ${DSL_MAX_QUOTES + 1} 条起被截断)`);
+                }
+                break;
+            }
+        }
+    }
+    return a;
+}
+/** v8:把 fold 出的结构化字段(type/tags/links/code/quotes)拷到 card op —— 镜像 title/content/group/href
+ *  的 if-set(缺省不带,apply 侧"缺省不改")。三个 buildCard 分支共用,消除重复。 */
+function applyCardFieldsV8(op, d) {
+    if (d.cardType !== undefined)
+        op.cardType = d.cardType;
+    if (d.tags !== undefined)
+        op.tags = d.tags;
+    if (d.links !== undefined)
+        op.links = d.links;
+    if (d.code !== undefined)
+        op.code = d.code;
+    if (d.quotes !== undefined)
+        op.quotes = d.quotes;
+}
+function buildCard(ds) {
+    const warns = [];
+    const d = fold(ds, warns);
+    if (d.id === undefined)
+        return { diag: 'missing #id' };
+    if (d.rel) {
+        const op = {
+            type: 'card',
+            cardId: d.id,
+            x: d.pos ? d.pos[0] : 0,
+            y: d.pos ? d.pos[1] : 0,
+            w: d.size?.w,
+            h: d.size?.h,
+            color: d.color,
+            rel: {
+                ...d.rel, // v9:保留 anchorGroup(组锚)
+                dir: d.rel.dir,
+                gap: d.gap ?? 20,
+            },
+        };
+        if (d.create)
+            op.create = true;
+        if (d.title !== undefined)
+            op.title = d.title;
+        if (d.content !== undefined)
+            op.content = d.content;
+        if (d.group !== undefined)
+            op.group = d.group;
+        if (d.href !== undefined)
+            op.href = d.href;
+        applyCardFieldsV8(op, d);
+        return warns.length ? { op, warns } : { op };
+    }
+    if (d.pos) {
+        const op = {
+            type: 'card',
+            cardId: d.id,
+            x: d.pos[0],
+            y: d.pos[1],
+            w: d.size?.w,
+            h: d.size?.h,
+            color: d.color,
+        };
+        if (d.create)
+            op.create = true;
+        if (d.title !== undefined)
+            op.title = d.title;
+        if (d.content !== undefined)
+            op.content = d.content;
+        if (d.group !== undefined)
+            op.group = d.group;
+        if (d.href !== undefined)
+            op.href = d.href;
+        applyCardFieldsV8(op, d);
+        return warns.length ? { op, warns } : { op };
+    }
+    // v5(E):无 @pos 的非 create 卡片行,若携带 title/content/color/size 之一 = "纯属性/内容编辑"
+    // (几何沿用现有卡,由 planCard 处理)。x/y 占位(0,0);裸行(无任何字段)与 create 仍 missing @pos。
+    // v7:group/href 同为"无几何属性编辑"——给现有卡分组/加出链不该要求 @pos。
+    // v8:type/tags/links/code/quotes 同理——给现有卡改结构化字段不要求 @pos。
+    if (!d.create &&
+        (d.title !== undefined || d.content !== undefined || d.color !== undefined || d.size !== undefined ||
+            d.group !== undefined || d.href !== undefined || d.cardType !== undefined || d.tags !== undefined ||
+            d.links !== undefined || d.code !== undefined || d.quotes !== undefined)) {
+        const op = {
+            type: 'card',
+            cardId: d.id,
+            x: 0,
+            y: 0,
+            keepExistingPos: true,
+            ...(d.color !== undefined ? { color: d.color } : {}),
+            ...(d.size ? { w: d.size.w, h: d.size.h } : {}),
+            ...(d.title !== undefined ? { title: d.title } : {}),
+            ...(d.content !== undefined ? { content: d.content } : {}),
+            ...(d.group !== undefined ? { group: d.group } : {}),
+            ...(d.href !== undefined ? { href: d.href } : {}),
+        };
+        applyCardFieldsV8(op, d);
+        return { op };
+    }
+    return { diag: 'missing @pos' };
+}
+function buildArrow(ds) {
+    const d = fold(ds);
+    const common = {
+        id: d.id,
+        label: d.label,
+        color: d.color,
+        dash: d.dash,
+        arrowhead: d.arrowhead,
+        curve: d.curve,
+        route: d.route,
+        elbow: d.elbow,
+        wikilink: d.wikilink || undefined,
+    };
+    if (d.from && d.to) {
+        const op = {
+            type: 'arrow',
+            from: d.from,
+            to: d.to,
+            ...common,
+        };
+        return { op };
+    }
+    if (d.pos && d.size) {
+        const op = {
+            type: 'arrow',
+            from: '',
+            to: '',
+            freeArrow: true,
+            x: d.pos[0],
+            y: d.pos[1],
+            w: d.size.w,
+            h: d.size.h,
+            ...common,
+        };
+        return { op };
+    }
+    return { diag: 'free arrow missing @pos/@size' };
+}
+function buildFree(kind, ds) {
+    const d = fold(ds);
+    if (d.id === undefined)
+        return { diag: 'missing #id' };
+    if (!d.pos)
+        return { diag: 'missing @pos' };
+    if (kind === 'rect') {
+        const op = {
+            type: 'free', shape: 'rect', id: d.id,
+            x: d.pos[0], y: d.pos[1], w: d.size?.w, h: d.size?.h, color: d.color,
+            ...(d.group !== undefined ? { group: d.group } : {}),
+        };
+        return { op };
+    }
+    if (kind === 'text') {
+        const op = {
+            type: 'free', shape: 'text', id: d.id,
+            x: d.pos[0], y: d.pos[1], text: d.text, color: d.color,
+            ...(d.group !== undefined ? { group: d.group } : {}),
+            ...(d.compute !== undefined ? { compute: d.compute } : {}),
+        };
+        return { op };
+    }
+    const op = {
+        type: 'free', shape: 'frame', id: d.id,
+        x: d.pos[0], y: d.pos[1], w: d.size?.w, h: d.size?.h, text: d.text, color: d.color,
+        ...(d.group !== undefined ? { group: d.group } : {}),
+    };
+    return { op };
+}
+function buildOp(r) {
+    if (r === null)
+        return null; // 静默 skip
+    if (r.kind === 'unknown')
+        return { diag: 'unrecognized element kind' };
+    if (r.kind === 'card')
+        return buildCard(r.ds);
+    if (r.kind === 'arrow')
+        return buildArrow(r.ds);
+    return buildFree(r.kind, r.ds); // rect / text / frame
+}
+// ── Parser ───────────────────────────────────────────────────────────────────
+/**
+ * Parse a DSL block into ops AND per-line diagnostics for dropped lines.
+ *
+ * 行分类(保留 1-based 原始行号,编辑器告诉用户哪行被丢、为什么 —— 转义核心卖点的反信任问题):
+ *
+ * - empty / `# comment` / 非 `[` 散文 / 围栏 → 静默 skip(无 error)
+ * - `[` 行解析后缺关键字段 → 记 {@link DslDiagnostic}
+ *
+ * 永不抛错:grammar 本身因尾部 `.*` 对任何 `[` 行都 succeed;极端输入(控制字符等)若仍
+ * 抛 → 该行静默跳过(不崩整块)。坐标恒 finite(finiteNum 守卫)。
+ */
+export function parseDslWithDiagnostics(dslText) {
+    const ops = [];
+    const errors = [];
+    const warnings = [];
+    const rawLines = dslText.split('\n');
+    for (let i = 0; i < rawLines.length; i++) {
+        const lineNo = i + 1;
+        const line = rawLines[i].trim();
+        if (!line)
+            continue;
+        let result;
+        try {
+            result = parseLine(line, { startRule: 'Line' });
+        }
+        catch {
+            // grammar 理论上不抛(尾部 .* 兜底);真抛了 → 静默跳过该行(永不抛错契约)
+            continue;
+        }
+        const built = buildOp(result);
+        if (built === null)
+            continue; // prose skip
+        if ('op' in built) {
+            if (ops.length >= DSL_MAX_OPS) {
+                errors.push({ line: lineNo, text: line, message: `元素数已达上限 ${DSL_MAX_OPS},本行及后续被截断` });
+                break;
+            }
+            ops.push(built.op);
+            // 自然语言体验(2026-10-29 精确化):skipChunk 的 null 是 `]`(每行常客,设计内静默);
+            // string 才是真 junk 原文。junk 存在才分类;@词/关系词检查只看 junk——旧整行 @ 正则
+            // 会把合法裸组锚 @g/@methods 误报成 unknown @(v9 文档形态!),junk 视角根除。
+            if (result !== null && result.kind !== 'unknown' && Array.isArray(result.ds)) {
+                const junk = result.ds.filter((e) => typeof e === 'string');
+                if (junk.length > 0) {
+                    const hint = classifyResidue(junk, line);
+                    if (hint)
+                        warnings.push({ line: lineNo, text: line, message: hint });
+                }
+            }
+            // 可重复指令/列表超限截断信号(30→8 之类此前零信号)
+            if ('warns' in built && built.warns) {
+                for (const w of built.warns)
+                    warnings.push({ line: lineNo, text: line, message: w });
+            }
+        }
+        else {
+            errors.push({ line: lineNo, text: line, message: built.diag });
+        }
+    }
+    return { ops, errors, warnings };
+}
+/** grammar 全部 @指令名(来源:dsl.peggy 逐条 Dir 规则的 '@' 字面量,实测 22 个)。
+ *  注意 from/to/create/关系词是**裸词**(fromDir='from' sp id 等,不带 @);
+ *  adversarial.test.ts 与 DSL_RESERVED_GROUP_ANCHOR_WORDS 做双向闭合锁,漂移即炸。 */
+export const AT_DIRECTIVES = new Set([
+    'pos', 'size', 'color', 'label', 'text', 'title', 'content', 'dash', 'arrowhead',
+    'curve', 'route', 'elbow', 'gap', 'wikilink', 'group', 'href',
+    'compute', 'type', 'tags', 'links', 'code', 'quote',
+]);
+/** 保留词表里的裸关键词(非 @ 指令):createDir / relationDir / fromDir / toDir。 */
+export const BARE_KEYWORDS = new Set(['create', 'right-of', 'below', 'from', 'to']);
+const REL_KEYWORDS = new Set(['right-of', 'below']);
+/**
+ * junk 分类(2026-10-29 起 junk 是 skipChunk 返回的原文数组):错误型 → 一句话可操作
+ * hint;恢复型(:1 等)→ null(静默)。@词与关系词检查只看 junk(锚位的合法 @组名
+ * 已被 grammar 消费,不会出现在 junk 里);全角/中文方位词看引号外的整行。
+ */
+function classifyResidue(junk, line) {
+    const outsideQuotes = line.replace(/"(?:[^"\\]|\\.)*"/g, '');
+    if (/[（）｛｝【】「」：；，。、]/.test(outsideQuotes)) {
+        return 'full-width punctuation （），: outside quotes — use ASCII ( ) , : (全角标点请用半角)';
+    }
+    const joined = junk.join(' ');
+    for (const m of joined.matchAll(/@([a-zA-Z][a-zA-Z0-9_-]*)/g)) {
+        if (!AT_DIRECTIVES.has(m[1])) {
+            return `unknown @${m[1]} directive — known: @pos @size @title …(见语法参考)`;
+        }
+    }
+    for (const w of joined.split(/\s+/).filter(Boolean)) {
+        // 方向词开头但不是合法关系词(leftof / left_of / aboves…)→ 反方向用 right-of 表达
+        if (/^(left|right|above|below)/i.test(w) && !REL_KEYWORDS.has(w.toLowerCase()) && !w.startsWith('#')) {
+            return `unknown relation "${w}" — relations are right-of / below (opposite direction: swap operands)`;
+        }
+    }
+    // 中文方位词(在#a左边/往右侧/上方…)→ 同类 hint(引号内不误报;行尾 .* 兜尾本就静默)
+    if (/[上下左右][边面方侧]/.test(outsideQuotes)) {
+        return 'CJK direction word — relational forms are right-of / below, anchor first (中文方位词请用 right-of/below,锚在前)';
+    }
+    return null;
+}
+/**
+ * Strict AI mode. User-pasted legacy text keeps using the compatibility parser,
+ * while model output must contain only complete directives. Unknown residual
+ * chunks and duplicate directives are errors instead of being swallowed by
+ * Peggy's compatibility skipChunk rule.
+ */
+export function parseDslStrictWithDiagnostics(dslText) {
+    const ops = [];
+    const errors = [];
+    const rawLines = dslText.split('\n');
+    for (let index = 0; index < rawLines.length; index += 1) {
+        const line = rawLines[index].trim();
+        const lineNo = index + 1;
+        if (!line)
+            continue;
+        // grammar 承诺"Lines starting with # are comments and ignored";strict 比 graceful 严在
+        // 拒散文,但**注释行照放行**(与 grammar 一致,也让 AI 输出里夹带的 # 注释不报错)。
+        if (line.startsWith('#'))
+            continue;
+        if (!line.startsWith('[')) {
+            errors.push({ line: lineNo, text: line, message: 'unexpected prose or markdown' });
+            continue;
+        }
+        let result;
+        try {
+            result = parseLine(line, { startRule: 'Line' });
+        }
+        catch {
+            errors.push({ line: lineNo, text: line, message: 'malformed directive' });
+            continue;
+        }
+        if (result === null || result.kind === 'unknown') {
+            errors.push({ line: lineNo, text: line, message: 'unrecognized directive' });
+            continue;
+        }
+        const tuples = result.ds.filter(Array.isArray);
+        const seen = new Set();
+        const duplicate = tuples.find(([tag]) => {
+            if (REPEATABLE_DIRECTIVES.has(tag))
+                return false; // v8:@code/@quote 可重复(一指令一块/条),不算 dup
+            if (seen.has(tag))
+                return true;
+            seen.add(tag);
+            return false;
+        });
+        if (duplicate) {
+            errors.push({ line: lineNo, text: line, message: `duplicate ${duplicate[0]} directive` });
+            continue;
+        }
+        const headerClosed = result.kind === 'arrow'
+            ? /^\[arrow(?:\s+#[a-zA-Z0-9_:-]+)?\]/.test(line)
+            : new RegExp(`^\\[${result.kind}\\s+#[a-zA-Z0-9_:-]+(?:\\s+create)?\\]`).test(line);
+        const allowedClosingChunk = line.startsWith('[arrow]') ? 0 : 1;
+        const unknownChunks = result.ds.filter((entry) => entry === null).length;
+        // 2026-10-29:skipChunk 语义化后,junk 原文以 string 落 ds(null 只剩 `]` 工件)——
+        // strict 的"未知残余"判定同步看 string(null 是 ] 豁免,allowedClosingChunk 管它)
+        const junkChunks = result.ds.filter((entry) => typeof entry === 'string').length;
+        if (!headerClosed || unknownChunks > allowedClosingChunk || junkChunks > 0) {
+            errors.push({ line: lineNo, text: line, message: 'unknown residual text' });
+            continue;
+        }
+        const built = buildOp(result);
+        if (built === null) {
+            errors.push({ line: lineNo, text: line, message: 'unsupported directive' });
+        }
+        else if ('op' in built) {
+            if (ops.length >= DSL_MAX_OPS) {
+                errors.push({ line: lineNo, text: line, message: `元素数已达上限 ${DSL_MAX_OPS},本行及后续被截断` });
+                break;
+            }
+            ops.push(built.op);
+        }
+        else {
+            errors.push({ line: lineNo, text: line, message: built.diag });
+        }
+    }
+    return { ops, errors };
+}
+/**
+ * Parse a DSL block (the AI's output) into a list of layout operations.
+ *
+ * Graceful: unrecognized lines are skipped (no throw). The DSL is
+ * intended for AI-to-machine communication — if the AI produces
+ * invalid syntax, we silently ignore bad lines.
+ *
+ * Thin wrapper over {@link parseDslWithDiagnostics}: returns only the ops
+ * (the diagnostics are irrelevant for the AI path). Behavior is unchanged.
+ */
+export function parseDsl(dslText) {
+    return parseDslWithDiagnostics(dslText).ops;
+}