@zigrivers/scaffold 3.28.0 → 3.30.0

package/dist/guides/links.test.js

@@ -0,0 +1,72 @@
+import { describe, it, expect } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { findBrokenRelativeLinks } from './links.js';
+function tmpdir() {
+    return fs.mkdtempSync(path.join(os.tmpdir(), 'glinks-'));
+}
+describe('findBrokenRelativeLinks (R2-9: inter-guide links must resolve)', () => {
+    it('reports a relative link whose target is missing', () => {
+        const dir = tmpdir();
+        expect(findBrokenRelativeLinks('See [concepts](../concepts/index.md).', dir)).toEqual([
+            '../concepts/index.md',
+        ]);
+    });
+    it('passes when the relative target exists', () => {
+        const root = tmpdir();
+        const dir = path.join(root, 'pipeline');
+        fs.mkdirSync(dir);
+        fs.mkdirSync(path.join(root, 'concepts'));
+        fs.writeFileSync(path.join(root, 'concepts', 'index.md'), '# c');
+        expect(findBrokenRelativeLinks('See [concepts](../concepts/index.md).', dir)).toEqual([]);
+    });
+    it('accepts an index.html link when the index.md source exists (not yet built)', () => {
+        const root = tmpdir();
+        const dir = path.join(root, 'pipeline');
+        fs.mkdirSync(dir);
+        fs.mkdirSync(path.join(root, 'concepts'));
+        fs.writeFileSync(path.join(root, 'concepts', 'index.md'), '# c');
+        expect(findBrokenRelativeLinks('[c](../concepts/index.html)', dir)).toEqual([]);
+    });
+    it('ignores external URLs, mailto, and pure anchors', () => {
+        const dir = tmpdir();
+        expect(findBrokenRelativeLinks('[e](https://x.com) [a](#sec) [m](mailto:x@y.com)', dir)).toEqual([]);
+    });
+    it('strips a trailing anchor before resolving', () => {
+        const root = tmpdir();
+        const dir = path.join(root, 'pipeline');
+        fs.mkdirSync(dir);
+        fs.mkdirSync(path.join(root, 'concepts'));
+        fs.writeFileSync(path.join(root, 'concepts', 'index.md'), '# c');
+        expect(findBrokenRelativeLinks('[c](../concepts/index.md#worktree)', dir)).toEqual([]);
+    });
+    it('catches broken reference-style links (definitions)', () => {
+        const dir = tmpdir();
+        const md = 'See [concepts][c].\n\n[c]: ../concepts/index.md\n';
+        expect(findBrokenRelativeLinks(md, dir)).toEqual(['../concepts/index.md']);
+    });
+    it('ignores links inside fenced code blocks', () => {
+        const dir = tmpdir();
+        const md = 'Example:\n\n```\n[x](../nope/index.md)\n```\n';
+        expect(findBrokenRelativeLinks(md, dir)).toEqual([]);
+    });
+    it('ignores link-like text inside frontmatter', () => {
+        const dir = tmpdir();
+        const md = '---\ntitle: T\ndescription: see [x](../nope/index.md)\n---\n\n# Body\n';
+        expect(findBrokenRelativeLinks(md, dir)).toEqual([]);
+    });
+    it('handles parentheses in the link target', () => {
+        const root = tmpdir();
+        const dir = path.join(root, 'g');
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, 'file(1).md'), 'x');
+        expect(findBrokenRelativeLinks('[x](<file(1).md>)', dir)).toEqual([]);
+    });
+    it('decodes percent-encoded targets before resolving', () => {
+        const dir = tmpdir();
+        fs.writeFileSync(path.join(dir, 'with space.md'), 'x');
+        expect(findBrokenRelativeLinks('[x](with%20space.md)', dir)).toEqual([]);
+    });
+});
+//# sourceMappingURL=links.test.js.map

package/dist/guides/links.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.test.js","sourceRoot":"","sources":["../../src/guides/links.test.ts"],"names":[],"mappings":"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"}

package/dist/guides/lint.d.ts

@@ -0,0 +1,6 @@
+export interface LintResult {
+    errors: string[];
+    warnings: string[];
+}
+export declare function lintGuide(markdown: string): LintResult;
+//# sourceMappingURL=lint.d.ts.map

package/dist/guides/lint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint.d.ts","sourceRoot":"","sources":["../../src/guides/lint.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IAAG,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE;AAMpE,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,CAoBtD"}

package/dist/guides/lint.js

@@ -0,0 +1,27 @@
+const EMBED_OPEN = /^:::embed\{[^}]*\}\s*$/;
+const EMBED_CLOSE = /^:::\s*$/;
+const TEXT_EQUIV = /text[\s-]?equivalent/i;
+export function lintGuide(markdown) {
+    const errors = [];
+    const warnings = [];
+    const lines = markdown.split(/\r?\n/);
+    let embedCount = 0;
+    for (let i = 0; i < lines.length; i++) {
+        if (!EMBED_OPEN.test(lines[i]))
+            continue;
+        embedCount++;
+        let body = '';
+        let j = i + 1;
+        for (; j < lines.length && !EMBED_CLOSE.test(lines[j]); j++)
+            body += lines[j] + '\n';
+        if (!TEXT_EQUIV.test(body)) {
+            errors.push(`:::embed at line ${i + 1} is missing a text-equivalent (required for agent-readability)`);
+        }
+        i = j;
+    }
+    if (embedCount > 3) {
+        warnings.push(`guide uses ${embedCount} escape-hatch embeds (>3) — prefer first-class directives`);
+    }
+    return { errors, warnings };
+}
+//# sourceMappingURL=lint.js.map

package/dist/guides/lint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint.js","sourceRoot":"","sources":["../../src/guides/lint.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAG,wBAAwB,CAAA;AAC3C,MAAM,WAAW,GAAG,UAAU,CAAA;AAC9B,MAAM,UAAU,GAAG,uBAAuB,CAAA;AAE1C,MAAM,UAAU,SAAS,CAAC,QAAgB;IACxC,MAAM,MAAM,GAAa,EAAE,CAAA;IAC3B,MAAM,QAAQ,GAAa,EAAE,CAAA;IAC7B,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;IACrC,IAAI,UAAU,GAAG,CAAC,CAAA;IAClB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAAE,SAAQ;QACxC,UAAU,EAAE,CAAA;QACZ,IAAI,IAAI,GAAG,EAAE,CAAA;QACb,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACb,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE;YAAE,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAA;QACpF,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3B,MAAM,CAAC,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,gEAAgE,CAAC,CAAA;QACxG,CAAC;QACD,CAAC,GAAG,CAAC,CAAA;IACP,CAAC;IACD,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;QACnB,QAAQ,CAAC,IAAI,CAAC,cAAc,UAAU,2DAA2D,CAAC,CAAA;IACpG,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAA;AAC7B,CAAC"}

package/dist/guides/lint.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=lint.test.d.ts.map

package/dist/guides/lint.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint.test.d.ts","sourceRoot":"","sources":["../../src/guides/lint.test.ts"],"names":[],"mappings":""}

package/dist/guides/lint.test.js

@@ -0,0 +1,24 @@
+import { describe, it, expect } from 'vitest';
+import { lintGuide } from './lint.js';
+describe('lintGuide', () => {
+    it('passes a guide with no embeds', () => {
+        const r = lintGuide('# Hi\n\nplain markdown\n');
+        expect(r.errors).toEqual([]);
+        expect(r.warnings).toEqual([]);
+    });
+    it('errors when an :::embed lacks a text-equivalent', () => {
+        const md = ':::embed{src=partials/x.svg}\n:::\n';
+        const r = lintGuide(md);
+        expect(r.errors.some((e) => /text.equivalent/i.test(e))).toBe(true);
+    });
+    it('passes an :::embed that includes a text-equivalent', () => {
+        const md = ':::embed{src=partials/x.svg}\n**Text equivalent:** a diagram.\n:::\n';
+        expect(lintGuide(md).errors).toEqual([]);
+    });
+    it('warns past 3 embeds', () => {
+        const one = ':::embed{src=p.svg}\n**Text equivalent:** x\n:::\n\n';
+        const r = lintGuide(one.repeat(4));
+        expect(r.warnings.some((w) => /embed/i.test(w))).toBe(true);
+    });
+});
+//# sourceMappingURL=lint.test.js.map

package/dist/guides/lint.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint.test.js","sourceRoot":"","sources":["../../src/guides/lint.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAErC,QAAQ,CAAC,WAAW,EAAE,GAAG,EAAE;IACzB,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACvC,MAAM,CAAC,GAAG,SAAS,CAAC,0BAA0B,CAAC,CAAA;QAC/C,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;QAC5B,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;IAChC,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,iDAAiD,EAAE,GAAG,EAAE;QACzD,MAAM,EAAE,GAAG,qCAAqC,CAAA;QAChD,MAAM,CAAC,GAAG,SAAS,CAAC,EAAE,CAAC,CAAA;QACvB,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACrE,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,oDAAoD,EAAE,GAAG,EAAE;QAC5D,MAAM,EAAE,GAAG,sEAAsE,CAAA;QACjF,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;IAC1C,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,qBAAqB,EAAE,GAAG,EAAE;QAC7B,MAAM,GAAG,GAAG,sDAAsD,CAAA;QAClE,MAAM,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAA;QAClC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC7D,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/dist/guides/loader.d.ts

@@ -0,0 +1,4 @@
+import type { GuideFrontmatter, GuideEntry } from './types.js';
+export declare function extractGuideFrontmatter(content: string): GuideFrontmatter | null;
+export declare function buildGuidesIndex(guidesDir: string): Map<string, GuideEntry>;
+//# sourceMappingURL=loader.d.ts.map

package/dist/guides/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/guides/loader.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE9D,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAwBhF;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAwB3E"}

package/dist/guides/loader.js

@@ -0,0 +1,63 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+export function extractGuideFrontmatter(content) {
+    const lines = content.split(/\r?\n/);
+    if (lines[0]?.trim() !== '---')
+        return null;
+    const closeIdx = lines.findIndex((l, i) => i > 0 && l.trim() === '---');
+    if (closeIdx === -1)
+        return null;
+    const yamlText = lines.slice(1, closeIdx).join('\n');
+    let parsed;
+    try {
+        parsed = yaml.load(yamlText, { schema: yaml.JSON_SCHEMA });
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    const p = parsed;
+    if (typeof p.title !== 'string' || typeof p.topic !== 'string' ||
+        typeof p.description !== 'string' || typeof p.category !== 'string' ||
+        typeof p.order !== 'number')
+        return null;
+    const fm = {
+        title: p.title, topic: p.topic, description: p.description,
+        category: p.category, order: p.order,
+    };
+    return fm;
+}
+export function buildGuidesIndex(guidesDir) {
+    const index = new Map();
+    if (!fs.existsSync(guidesDir))
+        return index;
+    let dirents;
+    try {
+        dirents = fs.readdirSync(guidesDir, { withFileTypes: true });
+    }
+    catch {
+        return index;
+    }
+    for (const d of dirents) {
+        if (!d.isDirectory() || d.name.startsWith('.'))
+            continue;
+        const dir = path.join(guidesDir, d.name);
+        const mdPath = path.join(dir, 'index.md');
+        if (!fs.existsSync(mdPath))
+            continue;
+        let fm;
+        try {
+            fm = extractGuideFrontmatter(fs.readFileSync(mdPath, 'utf8'));
+        }
+        catch {
+            continue;
+        }
+        if (!fm || fm.topic !== d.name)
+            continue;
+        index.set(fm.topic, { topic: fm.topic, dir, mdPath, htmlPath: path.join(dir, 'index.html'), frontmatter: fm });
+    }
+    return index;
+}
+//# sourceMappingURL=loader.js.map

package/dist/guides/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/guides/loader.ts"],"names":[],"mappings":"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"}

package/dist/guides/loader.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=loader.test.d.ts.map

package/dist/guides/loader.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.test.d.ts","sourceRoot":"","sources":["../../src/guides/loader.test.ts"],"names":[],"mappings":""}

package/dist/guides/loader.test.js

@@ -0,0 +1,85 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+import { extractGuideFrontmatter, buildGuidesIndex } from './loader.js';
+const tmpDirs = [];
+function tmpGuides(files) {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'guides-'));
+    tmpDirs.push(root);
+    for (const [rel, body] of Object.entries(files)) {
+        const full = path.join(root, rel);
+        fs.mkdirSync(path.dirname(full), { recursive: true });
+        fs.writeFileSync(full, body);
+    }
+    return root;
+}
+afterEach(() => {
+    for (const d of tmpDirs) {
+        try {
+            fs.rmSync(d, { recursive: true, force: true });
+        }
+        catch { /* ignore */ }
+    }
+    tmpDirs.length = 0;
+});
+const VALID_FM = `---
+title: MMR Reference
+topic: mmr
+description: Multi-model review
+category: tools
+order: 10
+---
+
+# Body
+`;
+describe('extractGuideFrontmatter', () => {
+    it('parses required fields', () => {
+        const fm = extractGuideFrontmatter(VALID_FM);
+        expect(fm).toEqual({
+            title: 'MMR Reference', topic: 'mmr',
+            description: 'Multi-model review', category: 'tools', order: 10,
+        });
+    });
+    it('returns null when frontmatter missing required fields', () => {
+        expect(extractGuideFrontmatter('# no frontmatter')).toBeNull();
+    });
+});
+describe('buildGuidesIndex', () => {
+    it('indexes guide dirs by topic and skips invalid ones', () => {
+        const root = tmpGuides({
+            'mmr/index.md': VALID_FM,
+            'broken/index.md': '# missing frontmatter',
+        });
+        const idx = buildGuidesIndex(root);
+        expect([...idx.keys()]).toEqual(['mmr']);
+        const entry = idx.get('mmr');
+        expect(entry.topic).toBe('mmr');
+        expect(entry.mdPath).toBe(path.join(root, 'mmr', 'index.md'));
+        expect(entry.htmlPath).toBe(path.join(root, 'mmr', 'index.html'));
+    });
+    it('returns empty map when dir does not exist', () => {
+        expect(buildGuidesIndex(path.join(os.tmpdir(), 'nope-xyz')).size).toBe(0);
+    });
+    it('skips a guide dir whose frontmatter topic does not match the directory name', () => {
+        const root = tmpGuides({
+            'mmr/index.md': VALID_FM,
+            'not-mmr/index.md': VALID_FM, // frontmatter says topic: mmr, but dir is not-mmr
+        });
+        const idx = buildGuidesIndex(root);
+        expect([...idx.keys()]).toEqual(['mmr']);
+        expect(idx.has('not-mmr')).toBe(false);
+    });
+});
+describe('extractGuideFrontmatter — trailing-whitespace closing delimiter', () => {
+    it('parses frontmatter when closing --- has trailing whitespace', () => {
+        const lines = ['---', 'title: MMR Reference', 'topic: mmr',
+            'description: Multi-model review', 'category: tools', 'order: 10', '---   ', '', '# Body', ''];
+        const content = lines.join('\n');
+        const fm = extractGuideFrontmatter(content);
+        expect(fm).not.toBeNull();
+        expect(fm.title).toBe('MMR Reference');
+        expect(fm.order).toBe(10);
+    });
+});
+//# sourceMappingURL=loader.test.js.map

package/dist/guides/loader.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.test.js","sourceRoot":"","sources":["../../src/guides/loader.test.ts"],"names":[],"mappings":"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"}

package/dist/guides/mermaid-sanitize.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=mermaid-sanitize.test.d.ts.map

package/dist/guides/mermaid-sanitize.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mermaid-sanitize.test.d.ts","sourceRoot":"","sources":["../../src/guides/mermaid-sanitize.test.ts"],"names":[],"mappings":""}

package/dist/guides/mermaid-sanitize.test.js

@@ -0,0 +1,57 @@
+import { describe, it, expect } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { renderGuideBody } from './render.js';
+import { remarkMermaid } from './mermaid.js';
+describe('mermaid SVG through full render pipeline', () => {
+    it('keeps <rect> and <svg> but strips <script> (double-defence: sanitizeSvg + rehype-sanitize)', async () => {
+        // Stub renderer returns SVG that contains a script tag (to prove double-defence).
+        const stubbedRender = async (_source) => '<svg viewBox="0 0 100 50"><rect x="0" y="0" width="100" height="50"/><script>evil()</script></svg>';
+        const md = '```mermaid\nflowchart LR\nA-->B\n```\n';
+        // remarkMermaid needs a guideDir for cache. We pass the stub renderer so no browser is involved.
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mmd-san-'));
+        const { body } = await renderGuideBody(md, {
+            plugins: [remarkMermaid({ guideDir: dir, render: stubbedRender })],
+        });
+        // SVG structural tags must survive rehype-sanitize
+        expect(body).toContain('<svg');
+        expect(body).toContain('<rect');
+        // <script> must be stripped — sanitizeSvg removes it before rehype-sanitize sees it,
+        // and rehype-sanitize would strip any that somehow slipped through.
+        expect(body).not.toContain('<script');
+        expect(body).not.toContain('evil()');
+        // figure wrapper must survive
+        expect(body).toContain('class="mermaid"');
+    });
+    it('preserves mermaid arrowhead structure (marker/use/marker-end) through sanitize', async () => {
+        // Realistic mermaid-style SVG with arrowhead wiring: <defs><marker …>, marker-end="url(#id)", <use href="#id">
+        const stubbedRender = async (_source) => '<svg viewBox="0 0 100 50">' +
+            '<defs>' +
+            '<marker id="arrow" markerWidth="10" markerHeight="10" orient="auto" refX="5" refY="5">' +
+            '<path d="M0,0 L10,5 L0,10 z"/>' +
+            '</marker>' +
+            '</defs>' +
+            '<path d="M0,25 L90,25" marker-end="url(#arrow)" stroke="black"/>' +
+            '<use href="#arrow"/>' +
+            '</svg>';
+        const md = '```mermaid\nflowchart LR\nA-->B\n```\n';
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mmd-arrow-'));
+        const { body } = await renderGuideBody(md, {
+            plugins: [remarkMermaid({ guideDir: dir, render: stubbedRender })],
+        });
+        // <marker> element and its key attributes must survive
+        expect(body).toContain('<marker');
+        expect(body).toContain('id="arrow"');
+        expect(body).toContain('orient="auto"');
+        // marker-end attribute wiring the path to the marker must survive
+        // hast/rehype-stringify preserves SVG presentation attributes in their original hyphenated form
+        expect(body).toContain('marker-end="url(#arrow)"');
+        // <use> element referencing the marker must survive
+        expect(body).toContain('<use');
+        expect(body).toContain('href="#arrow"');
+        // The path element itself must survive
+        expect(body).toContain('<path');
+    });
+});
+//# sourceMappingURL=mermaid-sanitize.test.js.map

package/dist/guides/mermaid-sanitize.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mermaid-sanitize.test.js","sourceRoot":"","sources":["../../src/guides/mermaid-sanitize.test.ts"],"names":[],"mappings":"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"}

package/dist/guides/mermaid.d.ts

@@ -0,0 +1,18 @@
+import type { AnyPlugin } from './render.js';
+export declare function computeFingerprint(source: string): string;
+export declare function sanitizeSvg(svg: string): string;
+export declare function renderMermaid(source: string): Promise<string>;
+export interface ResolveArgs {
+    guideDir: string;
+    diagramId: string;
+    source: string;
+    render?: (source: string) => Promise<string>;
+}
+export declare function resolveDiagram(args: ResolveArgs): Promise<string>;
+export declare function pruneDiagrams(guideDir: string, keepIds: string[]): void;
+export declare function remarkMermaid(opts: {
+    guideDir: string;
+    render?: (s: string) => Promise<string>;
+    collect?: string[];
+}): AnyPlugin;
+//# sourceMappingURL=mermaid.d.ts.map

package/dist/guides/mermaid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mermaid.d.ts","sourceRoot":"","sources":["../../src/guides/mermaid.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAY5C,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKzD;AAGD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM/C;AAGD,wBAAsB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAkBnE;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CAC7C;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAkCvE;AAGD,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAkBvE;AAMD,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAClC,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IACvC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACnB,GAAG,SAAS,CAwBZ"}

package/dist/guides/mermaid.js

@@ -0,0 +1,137 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { visit } from 'unist-util-visit';
+const MMDC_VERSION_FINGERPRINT = 'mmdc12'; // bump when render options/version change
+const RENDER_OPTS = ['-t', 'neutral', '-b', 'transparent'];
+// Mermaid config passed to mmdc via `-c`. `htmlLabels: false` forces node/edge
+// labels to render as native SVG <text>/<tspan> instead of <foreignObject> HTML.
+// This is REQUIRED: sanitizeSvg() strips <foreignObject> for security, so with
+// the mmdc default (HTML labels) every node label would vanish, leaving empty
+// boxes. The fingerprint includes this JSON so cache invalidates when it changes.
+const MERMAID_CONFIG = JSON.stringify({ htmlLabels: false, flowchart: { htmlLabels: false } });
+export function computeFingerprint(source) {
+    return createHash('sha256')
+        .update(`${MMDC_VERSION_FINGERPRINT}\n${RENDER_OPTS.join(' ')}\n${MERMAID_CONFIG}\n${source}`)
+        .digest('hex')
+        .slice(0, 16);
+}
+// Strict SVG hardening: remove dangerous elements/attrs.
+export function sanitizeSvg(svg) {
+    return svg
+        .replace(/<script[\s\S]*?<\/script>/gi, '')
+        .replace(/<foreignObject[\s\S]*?<\/foreignObject>/gi, '')
+        .replace(/\son\w+\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/gi, '')
+        .replace(/((?:xlink:)?href)\s*=\s*("javascript:[^"]*"|'javascript:[^']*')/gi, '');
+}
+// Default renderer: shells out to mmdc (build-time; needs a browser).
+export async function renderMermaid(source) {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'mmdc-'));
+    try {
+        const inFile = path.join(tmp, 'in.mmd');
+        const outFile = path.join(tmp, 'out.svg');
+        const cfgFile = path.join(tmp, 'config.json');
+        fs.writeFileSync(inFile, source);
+        fs.writeFileSync(cfgFile, MERMAID_CONFIG);
+        const npx = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+        execFileSync(npx, ['--no-install', 'mmdc', '-i', inFile, '-o', outFile, '-c', cfgFile, ...RENDER_OPTS], { stdio: 'pipe' });
+        return fs.readFileSync(outFile, 'utf8');
+    }
+    finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+export async function resolveDiagram(args) {
+    const { guideDir, diagramId, source } = args;
+    const render = args.render ?? renderMermaid;
+    const cacheDir = path.join(guideDir, '.diagrams');
+    const svgPath = path.join(cacheDir, `${diagramId}.svg`);
+    const manifestPath = path.join(cacheDir, 'manifest.json');
+    const fp = computeFingerprint(source);
+    let manifest = {};
+    if (fs.existsSync(manifestPath)) {
+        try {
+            manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+        }
+        catch {
+            // Corrupt manifest (e.g. partially-written from a crashed build) — treat as empty.
+            manifest = {};
+        }
+    }
+    if (manifest[diagramId] === fp && fs.existsSync(svgPath)) {
+        return fs.readFileSync(svgPath, 'utf8');
+    }
+    let raw;
+    try {
+        raw = await render(source);
+    }
+    catch (e) {
+        throw new Error(`mermaid render failed for "${diagramId}" ` +
+            `(no browser? install per dev-setup.md). Cache: ${svgPath}\n${String(e)}`);
+    }
+    const clean = sanitizeSvg(raw);
+    fs.mkdirSync(cacheDir, { recursive: true });
+    fs.writeFileSync(svgPath, clean);
+    manifest[diagramId] = fp;
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
+    return clean;
+}
+// Prune cached SVGs whose diagramId is no longer present.
+export function pruneDiagrams(guideDir, keepIds) {
+    const cacheDir = path.join(guideDir, '.diagrams');
+    if (!fs.existsSync(cacheDir))
+        return;
+    const keep = new Set(keepIds);
+    for (const f of fs.readdirSync(cacheDir)) {
+        if (f.endsWith('.svg') && !keep.has(f.replace(/\.svg$/, '')))
+            fs.rmSync(path.join(cacheDir, f));
+    }
+    const manifestPath = path.join(cacheDir, 'manifest.json');
+    if (fs.existsSync(manifestPath)) {
+        let m = {};
+        try {
+            m = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+        }
+        catch {
+            // Corrupt manifest — self-heal by writing back an empty one after pruning.
+        }
+        for (const k of Object.keys(m))
+            if (!keep.has(k))
+                delete m[k];
+        fs.writeFileSync(manifestPath, JSON.stringify(m, null, 2) + '\n');
+    }
+}
+// remark plugin: replace ```mermaid code blocks with the resolved inline SVG.
+// Diagram id = `diagram-<n>` by document order.
+// Diagrams are resolved SEQUENTIALLY to avoid concurrent read+write races on the
+// shared manifest.json (each resolveDiagram reads and then writes the file).
+export function remarkMermaid(opts) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return () => async (tree) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const jobs = [];
+        let n = 0;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        visit(tree, 'code', (node) => {
+            if (node.lang !== 'mermaid')
+                return;
+            const diagramId = `diagram-${n++}`;
+            if (opts.collect)
+                opts.collect.push(diagramId);
+            jobs.push({ node, diagramId, source: node.value });
+        });
+        for (const job of jobs) {
+            const svg = await resolveDiagram({
+                guideDir: opts.guideDir,
+                diagramId: job.diagramId,
+                source: job.source,
+                render: opts.render,
+            });
+            job.node.type = 'html';
+            job.node.value = `<figure class="mermaid">${svg}</figure>`;
+        }
+    };
+}
+//# sourceMappingURL=mermaid.js.map

package/dist/guides/mermaid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mermaid.js","sourceRoot":"","sources":["../../src/guides/mermaid.ts"],"names":[],"mappings":"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"}

package/dist/guides/mermaid.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=mermaid.test.d.ts.map

package/dist/guides/mermaid.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mermaid.test.d.ts","sourceRoot":"","sources":["../../src/guides/mermaid.test.ts"],"names":[],"mappings":""}