brane 0.1.1 → 0.3.1

package/dist/diagram/index.js

@@ -0,0 +1,85 @@
+/** ```mermaid source → SVG, or a refusal.
+ *
+ *  The one entry point, and deliberately the *same* one for both targets: the
+ *  app fetches it through `POST /api/diagram`, the HTML export calls it
+ *  directly in its fence loop. That is the "one renderer, two targets" rule
+ *  the KaTeX path already follows — an export is a snapshot of the live view
+ *  rather than a lookalike of it.
+ *
+ *  Unlike KaTeX it runs only on the daemon. Inline math is ubiquitous and
+ *  light, so it is worth bundling; diagrams are rare and heavy, like the
+ *  syntax highlighting that already lives behind `POST /api/highlight`.
+ *
+ *  `null` is the fallback signal, and both call sites already handle it: the
+ *  export substitutes only non-null results, and the app's code view renders
+ *  plain when its fetch comes back empty. So a refused diagram is the
+ *  highlighted code block a mermaid fence renders as today — no new path.
+ */
+import { createHash } from "node:crypto";
+import { parseDiagram } from "./parse.js";
+import { layoutDiagram } from "./layout.js";
+import { renderSvg } from "./svg.js";
+export { parseLabel, wrapRuns, MARKDOWN_WRAP_WIDTH } from "./label.js";
+export { parseDiagram } from "./parse.js";
+export { layoutDiagram, projectAttachment, faceOffset } from "./layout.js";
+export { basisPath, renderSvg, esc } from "./svg.js";
+export { textWidth, charWidth, runWidth, measureNode, measureEdgeLabel } from "./metrics.js";
+/** A source larger than this is not a diagram anyone will read, and layout is
+ *  synchronous on the daemon's only thread. */
+export const MAX_SOURCE_BYTES = 24_000;
+/** Likewise: dagre is O(V·E)-ish and a pathological graph must not stall the
+ *  daemon. Both bounds refuse rather than truncate. */
+export const MAX_NODES = 300;
+export const MAX_EDGES = 600;
+/** Parse once, and check the bounds against the result. `diagnoseDiagram` and
+ *  `renderDiagram` both need exactly this, and calling the former from the
+ *  latter parsed the same source twice on the rendering path. */
+function parseWithin(source) {
+    if (source.length > MAX_SOURCE_BYTES) {
+        return { ok: false, refusal: { kind: "unsupported", message: `diagram source is over ${MAX_SOURCE_BYTES} bytes` } };
+    }
+    const parsed = parseDiagram(source);
+    if (!parsed.ok)
+        return { ok: false, refusal: parsed.refusal };
+    if (parsed.ir.nodes.length > MAX_NODES) {
+        return { ok: false, refusal: { kind: "unsupported", message: `diagram has more than ${MAX_NODES} nodes` } };
+    }
+    if (parsed.ir.edges.length > MAX_EDGES) {
+        return { ok: false, refusal: { kind: "unsupported", message: `diagram has more than ${MAX_EDGES} edges` } };
+    }
+    return { ok: true, ir: parsed.ir };
+}
+export function diagnoseDiagram(source) {
+    return inspectDiagram(source).refusal;
+}
+/** Everything `narrate` reports about one fence, from one parse: whether it
+ *  draws at all, and if it does, which label markup draws as typed. */
+export function inspectDiagram(source) {
+    const checked = parseWithin(source);
+    return checked.ok
+        ? { refusal: null, literal: checked.ir.literal }
+        : { refusal: checked.refusal, literal: [] };
+}
+export function renderDiagram(source, opts = {}) {
+    const parsed = parseWithin(source);
+    if (!parsed.ok)
+        return null;
+    try {
+        const placed = layoutDiagram(parsed.ir);
+        if (!Number.isFinite(placed.width) || !Number.isFinite(placed.height) ||
+            placed.width <= 0 || placed.height <= 0) {
+            return null;
+        }
+        const idSuffix = createHash("sha256").update(source).digest("hex").slice(0, 8);
+        return {
+            svg: renderSvg(placed, { hrefFor: opts.hrefFor, idSuffix, edgeHighlight: opts.edgeHighlight }),
+            labels: parsed.ir.nodes.map((n) => n.lines.join(" ")),
+        };
+    }
+    catch {
+        // dagre throws on graph shapes it cannot rank. A thrown layout is a
+        // fallback, never a 500 — the reader still gets the source.
+        return null;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/diagram/label.js

@@ -0,0 +1,455 @@
+/** Label text → styled lines.
+ *
+ *  Mermaid has two label grammars, and agents write both:
+ *
+ *  - **Plain** (`A[text]`, `A["text"]`). Mermaid's HTML labels honour a few
+ *    tags in here — `<br/>`, `<b>`, `<i>` and their kin — and nothing else:
+ *    `**x**` in a plain label is two asterisks on GitHub too.
+ *  - **Markdown strings** (``A["`text`"]``, mermaid ≥10). The backticks inside
+ *    the quotes are the marker, not over-quoting: `**bold**` and `*italic*`
+ *    render, a newline in the source is a line break, and mermaid wraps long
+ *    lines to a fixed width.
+ *
+ *  Before this module brane read only `<br/>` from either, so ``"`**Plan**`"``
+ *  drew its backticks and asterisks as text (claude-cdouqlgt:19 on another
+ *  daemon, where an agent tried three spellings of bold and got none).
+ *
+ *  **Nothing here builds markup.** A label becomes runs of plain text with
+ *  flags, and `svg.ts` escapes each run into a `<tspan>` whose attributes it
+ *  writes itself. A `<script>` in a label is text, exactly as before.
+ *
+ *  **One parse, never a second scanner.** A markdown string goes through
+ *  `fromMarkdown`, the parser `markdown-diagnostics.ts` already uses, so what
+ *  counts as bold here is what counts as bold everywhere else in brane. The
+ *  plain grammar is a fixed set of tags, so a linear scanner over that set
+ *  is its whole definition.
+ *
+ *  **Tables are brane's own.** A node's markdown string may hold a GFM table,
+ *  which mermaid shows as "Unsupported markdown". Brane draws it as a grid,
+ *  as static SVG, so the HTML export carries no logic for it. In an edge
+ *  label or a subgraph title there is no box for a grid, so there a table
+ *  shows as its source and is reported.
+ *
+ *  **What still shows as source is reported.** Each label returns `literal`:
+ *  markup that will be drawn as the characters it is made of. `narrate`
+ *  turns those into `diagram_label_literal` warnings, so an agent that writes
+ *  `**x**` in a plain label learns to write a markdown string, instead of
+ *  getting a clean receipt for a diagram showing asterisks.
+ */
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { gfmTable } from "micromark-extension-gfm-table";
+import { gfmTableFromMarkdown } from "mdast-util-gfm-table";
+import { FONT_SIZE, runWidth } from "./metrics.js";
+export const isTable = (l) => !Array.isArray(l);
+/** Line slots a label line takes up. */
+export const slotsOf = (l) => (isTable(l) ? 1 + l.rows.length : 1);
+/** A table as plain lines, for the places that can only hold text. */
+export function tableText(t) {
+    return [t.header, ...t.rows].map((cells) => cells.map(lineText).join(" | "));
+}
+/** Label lines with every table flattened to text lines: for edge labels and
+ *  subgraph titles, where a table is never drawn as one. */
+export function textLines(lines) {
+    return lines.flatMap((l) => (isTable(l) ? tableText(l).map((text) => [{ text }]) : [l]));
+}
+/** Mermaid's `flowchart.wrappingWidth` (200px) at mermaid's 16px, scaled to
+ *  brane's font size. Markdown strings wrap to it; plain labels never wrap,
+ *  also as mermaid does. Scaled because it is the *em* width that decides
+ *  where a line breaks: 200px at 14px would keep words together that GitHub
+ *  splits (`planner picks the operations` is one line at 200px/14px and two
+ *  on GitHub). */
+export const MARKDOWN_WRAP_WIDTH = (200 * FONT_SIZE) / 16;
+const TAGS = {
+    b: "bold", strong: "bold",
+    i: "italic", em: "italic",
+    code: "code",
+    s: "strike", del: "strike", strike: "strike",
+    u: "underline",
+};
+/** Every tag-shaped token: `<b>`, `</em>`, `<br/>`, `<br />`, `<foo bar>`. */
+const TAG = /<(\/?)([A-Za-z][A-Za-z0-9]*)\b[^<>]*?(\/?)>/g;
+/** A markdown string: ``"`…`"``, quotes and backticks wrapping the whole. */
+const MD_STRING = /^"`([\s\S]*)`"$/;
+/** `**x**`, `__x__` and `` `x` `` in a plain label are drawn as typed, here
+ *  and in mermaid. Worth saying, because the fix is one character pair away. */
+const MARKDOWN_IN_PLAIN = /\*\*[^*\s][^*]*\*\*|__[^_\s][^_]*__|`[^`\s][^`]*`/;
+export function parseLabel(raw, opts = {}) {
+    const t = raw.trim();
+    const md = MD_STRING.exec(t);
+    return md ? parseMarkdownLabel(md[1], opts) : parsePlainLabel(t);
+}
+function plainLines(runs) {
+    return runs.flatMap((l) => (isTable(l) ? tableText(l) : [lineText(l)]));
+}
+/** A label that is just text — the node id, for one written without a label. */
+export function plainLabel(text) {
+    return { lines: [text], runs: [[{ text }]], literal: [] };
+}
+// ── Plain labels ─────────────────────────────────────────────────────────────
+function parsePlainLabel(raw) {
+    // One pair of wrapping quotes is label quoting, not text. The old splitter
+    // stripped a backtick pair as well; kept, since dropping it would put
+    // backticks into diagrams that drew without them yesterday.
+    const s = raw.replace(/^(["'`])([\s\S]*)\1$/, "$2");
+    const literal = [];
+    const b = new LineBuilder();
+    const style = {};
+    const depth = {};
+    const unknown = new Set();
+    let at = 0;
+    for (const m of s.matchAll(TAG)) {
+        b.text(decodeEntities(s.slice(at, m.index)), style);
+        at = m.index + m[0].length;
+        const [, close, nameRaw, selfClose] = m;
+        const name = nameRaw.toLowerCase();
+        if (name === "br") {
+            b.newline();
+            continue;
+        }
+        const flag = TAGS[name];
+        if (!flag || selfClose) {
+            b.text(m[0], style);
+            // Once per tag name: `<span>…</span>` is one mistake, not two.
+            if (!unknown.has(name)) {
+                unknown.add(name);
+                literal.push(`\`<${name}>\` is not a tag diagrams draw, so it shows as text`);
+            }
+            continue;
+        }
+        // Counted, so `<b><b>x</b> y</b>` keeps `y` bold, and a stray `</b>`
+        // closes nothing rather than going negative.
+        const d = (depth[flag] ?? 0) + (close ? -1 : 1);
+        depth[flag] = Math.max(0, d);
+        if (depth[flag])
+            style[flag] = true;
+        else
+            delete style[flag];
+    }
+    b.text(decodeEntities(s.slice(at)), style);
+    const out = b.finish(/* dropBlank */ true);
+    // Only text outside `<code>`: inside it, `**` is meant literally, and saying
+    // otherwise was a false warning.
+    const prose = out.runs.map((l) => (isTable(l) ? "" : l.filter((r) => !r.code).map((r) => r.text).join(""))).join("\n");
+    const md = MARKDOWN_IN_PLAIN.exec(prose);
+    if (md) {
+        literal.push(`\`${md[0]}\` shows as typed in a plain label. To style it, make the label a markdown string: backticks just inside the quotes, as in \`A["\`**bold**\`"]\``);
+    }
+    return { ...out, literal };
+}
+// ── Markdown strings ─────────────────────────────────────────────────────────
+function parseMarkdownLabel(inner, opts) {
+    // Continuation lines carry the diagram's indentation, which in markdown
+    // would read as an indented code block. Mermaid dedents; trimming each line
+    // is the same thing for text that is never meant to be indented.
+    const src = inner.split("\n").map((l) => l.trim()).join("\n");
+    const literal = [];
+    // Swapped while a table cell is read, so the inline walk below fills the
+    // cell rather than the label.
+    let b = new LineBuilder();
+    let tree;
+    try {
+        // The table extension is loaded whether or not tables are drawn: without
+        // it a table parses as paragraphs of pipes, which draw as typed and could
+        // not be reported, since nothing would know they were a table.
+        tree = fromMarkdown(src, { extensions: [gfmTable()], mdastExtensions: [gfmTableFromMarkdown()] });
+    }
+    catch {
+        b.text(src, {});
+        return { ...b.finish(true), literal: ["the markdown string could not be parsed, so it shows as typed"] };
+    }
+    const sourceOf = (node) => {
+        const s = node?.position?.start?.offset, e = node?.position?.end?.offset;
+        return typeof s === "number" && typeof e === "number" ? src.slice(s, e) : "";
+    };
+    const tagStyle = {};
+    const inline = (node, style) => {
+        const eff = { ...style, ...tagStyle };
+        switch (node.type) {
+            case "text":
+                b.text(node.value, eff);
+                return;
+            case "break":
+                b.newline();
+                return;
+            case "strong":
+                for (const c of node.children)
+                    inline(c, { ...style, bold: true });
+                return;
+            case "emphasis":
+                for (const c of node.children)
+                    inline(c, { ...style, italic: true });
+                return;
+            case "inlineCode":
+                b.text(node.value, { ...eff, code: true });
+                return;
+            case "html": {
+                // Inline HTML arrives one tag per node. The tags plain labels honour
+                // mean the same here; anything else is shown and reported.
+                const m = /^<(\/?)([A-Za-z][A-Za-z0-9]*)\b[^<>]*?(\/?)>$/.exec(node.value);
+                const name = m?.[2].toLowerCase();
+                if (name === "br") {
+                    b.newline();
+                    return;
+                }
+                const flag = name ? TAGS[name] : undefined;
+                if (m && flag && !m[3]) {
+                    if (m[1])
+                        delete tagStyle[flag];
+                    else
+                        tagStyle[flag] = true;
+                    return;
+                }
+                b.text(node.value, eff);
+                literal.push(`\`${clip(node.value)}\` is not something diagrams draw, so it shows as text`);
+                return;
+            }
+            case "link":
+            case "linkReference":
+                for (const c of node.children ?? [])
+                    inline(c, style);
+                literal.push(`links in diagram labels are drawn as their text and are not followed`);
+                return;
+            default: {
+                const text = sourceOf(node);
+                if (text) {
+                    b.text(text, eff);
+                    literal.push(`\`${clip(text)}\` is markdown diagrams do not draw, so it shows as typed`);
+                }
+            }
+        }
+    };
+    const block = (node, prefix) => {
+        switch (node.type) {
+            case "root":
+            case "blockquote":
+                node.children.forEach((c) => block(c, prefix));
+                return;
+            case "paragraph":
+            case "heading":
+                b.startBlock();
+                if (prefix)
+                    b.text(prefix, {});
+                for (const c of node.children)
+                    inline(c, node.type === "heading" ? { bold: true } : {});
+                return;
+            case "list":
+                node.children.forEach((item, i) => {
+                    const marker = node.ordered ? `${(node.start ?? 1) + i}. ` : "• ";
+                    (item.children ?? []).forEach((c, j) => block(c, j === 0 ? marker : ""));
+                });
+                return;
+            case "table": {
+                if (!opts.tables) {
+                    literalBlock(node, "tables are drawn only in node labels, so this one");
+                    return;
+                }
+                const cellRuns = (cell, header) => {
+                    const outer = b;
+                    b = new LineBuilder();
+                    for (const c of cell.children ?? [])
+                        inline(c, header ? { bold: true } : {});
+                    // A cell is one line: a `<br>` inside one becomes a space.
+                    const line = textLines(b.finish(true).runs).reduce((acc, l, i) => (i ? [...acc, { text: " " }, ...l] : l), []);
+                    b = outer;
+                    return line;
+                };
+                const [head, ...body] = node.children ?? [];
+                const width = head?.children?.length ?? 0;
+                // GFM pads short rows with empty cells and drops extra ones.
+                const row = (r, header) => Array.from({ length: width }, (_, i) => (r.children?.[i] ? cellRuns(r.children[i], header) : []));
+                b.startBlock();
+                b.table({
+                    table: true,
+                    align: Array.from({ length: width }, (_, i) => node.align?.[i] ?? null),
+                    header: row(head, true),
+                    rows: body.map((r) => row(r, false)),
+                });
+                return;
+            }
+            case "code":
+                b.startBlock();
+                node.value.split("\n").forEach((l, i) => {
+                    if (i)
+                        b.newline();
+                    b.text(l, { code: true });
+                });
+                return;
+            default:
+                literalBlock(node);
+        }
+    };
+    const literalBlock = (node, what) => {
+        const text = sourceOf(node);
+        if (!text)
+            return;
+        b.startBlock();
+        b.text(text, {});
+        literal.push(what
+            ? `${what} shows as typed`
+            : `\`${clip(text)}\` is markdown diagrams do not draw, so it shows as typed`);
+    };
+    block(tree, "");
+    const out = b.finish(/* dropBlank */ true);
+    const runs = out.runs.flatMap((line) => (isTable(line) ? [line] : wrapRuns(line, MARKDOWN_WRAP_WIDTH)));
+    return { lines: plainLines(runs), runs, literal };
+}
+// ── Lines ────────────────────────────────────────────────────────────────────
+/** Accumulates runs into lines, merging adjacent runs of the same style and
+ *  splitting text on its own newlines (a markdown soft break is a `\n` inside
+ *  a text node, and in a markdown string it is a line break). */
+class LineBuilder {
+    lines = [[]];
+    blocks = 0;
+    text(s, style) {
+        if (!s)
+            return;
+        s.split("\n").forEach((part, i) => {
+            if (i)
+                this.newline();
+            if (part)
+                this.push({ text: part, ...clean(style) });
+        });
+    }
+    newline() { this.lines.push([]); }
+    /** A new paragraph, heading or list item starts on its own line. */
+    startBlock() {
+        if (this.blocks++ > 0)
+            this.newline();
+    }
+    /** A table takes the current line if it is empty, and nothing after it
+     *  shares its slots. */
+    table(t) {
+        const cur = this.lines[this.lines.length - 1];
+        if (!isTable(cur) && cur.length === 0)
+            this.lines[this.lines.length - 1] = t;
+        else
+            this.lines.push(t);
+        this.newline();
+    }
+    push(run) {
+        let line = this.lines[this.lines.length - 1];
+        if (isTable(line)) {
+            line = [];
+            this.lines.push(line);
+        }
+        const last = line[line.length - 1];
+        if (last && sameStyle(last, run))
+            last.text += run.text;
+        else
+            line.push(run);
+    }
+    finish(dropBlank) {
+        let runs = this.lines.map((l) => (isTable(l) ? l : trimLine(l)));
+        // `A<br/><br/>B` drew as two lines before, not three; an empty label
+        // still draws as one empty line.
+        if (dropBlank) {
+            const kept = runs.filter((l) => isTable(l) || l.length > 0);
+            runs = kept.length ? kept : [[]];
+        }
+        return { lines: plainLines(runs), runs };
+    }
+}
+const FLAGS = ["bold", "italic", "code", "strike", "underline"];
+function clean(style) {
+    const out = {};
+    for (const f of FLAGS)
+        if (style[f])
+            out[f] = true;
+    return out;
+}
+function sameStyle(a, b) {
+    return FLAGS.every((f) => !!a[f] === !!b[f]);
+}
+/** Leading and trailing whitespace of the *line*, not of each run: the space
+ *  in `**Plan** mixin` belongs to the second run and must stay. */
+function trimLine(line) {
+    const out = line.map((r) => ({ ...r }));
+    while (out.length && !(out[0].text = out[0].text.replace(/^\s+/, "")))
+        out.shift();
+    while (out.length && !(out[out.length - 1].text = out[out.length - 1].text.replace(/\s+$/, "")))
+        out.pop();
+    return out;
+}
+export function lineText(line) {
+    return line.map((r) => r.text).join("");
+}
+/** Greedy word wrap of one line of runs to `max` px.
+ *
+ *  Words are split at spaces and never broken, so a word longer than the
+ *  width overflows as it does in mermaid. A run boundary inside a word
+ *  (`**Plan**s`) is not a break opportunity. */
+export function wrapRuns(line, max, fontSize = FONT_SIZE) {
+    const pieces = [];
+    for (const r of line) {
+        for (const m of r.text.matchAll(/\s+|\S+/g)) {
+            pieces.push({ run: { ...r, text: m[0] }, space: /^\s/.test(m[0]) });
+        }
+    }
+    const words = [];
+    for (const p of pieces) {
+        const prev = words[words.length - 1];
+        if (!prev || p.space || prev[0].space)
+            words.push([p]);
+        else
+            prev.push(p);
+    }
+    const width = (ps) => ps.reduce((w, p) => w + runWidth(p.run, fontSize), 0);
+    const out = [[]];
+    let w = 0;
+    for (const word of words) {
+        const cur = out[out.length - 1];
+        if (word[0].space) {
+            if (cur.length) {
+                cur.push(...word);
+                w += width(word);
+            }
+            continue;
+        }
+        const ww = width(word);
+        if (cur.length && w + ww > max) {
+            if (cur[cur.length - 1].space)
+                cur.pop();
+            out.push([...word]);
+            w = ww;
+        }
+        else {
+            cur.push(...word);
+            w += ww;
+        }
+    }
+    return out.map((ps) => {
+        const merged = [];
+        for (const p of ps) {
+            const last = merged[merged.length - 1];
+            if (last && sameStyle(last, p.run))
+                last.text += p.run.text;
+            else
+                merged.push({ ...p.run });
+        }
+        return trimLine(merged);
+    });
+}
+function clip(s, max = 40) {
+    const one = s.replace(/\s+/g, " ");
+    return one.length > max ? one.slice(0, max - 1) + "…" : one;
+}
+/** The character references a label is likely to hold. Mermaid's HTML labels
+ *  decode them, so `A[x &lt; y]` reads `x < y` there; brane drew the entity.
+ *  Decoded after tags are scanned, so a decoded `<` is never read as one. */
+const NAMED = {
+    amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: "\u00a0",
+    ndash: "–", mdash: "—", hellip: "…", rarr: "→", larr: "←", harr: "↔",
+    le: "≤", ge: "≥", ne: "≠", times: "×", middot: "·", bull: "•", deg: "°",
+};
+function decodeEntities(s) {
+    if (!s.includes("&"))
+        return s;
+    return s.replace(/&(#x[0-9a-f]{1,6}|#[0-9]{1,7}|[a-z]{2,8});/gi, (whole, ref) => {
+        if (ref[0] === "#") {
+            const cp = ref[1] === "x" || ref[1] === "X" ? parseInt(ref.slice(2), 16) : parseInt(ref.slice(1), 10);
+            return cp > 0 && cp <= 0x10ffff && !(cp >= 0xd800 && cp <= 0xdfff) ? String.fromCodePoint(cp) : whole;
+        }
+        return NAMED[ref.toLowerCase()] ?? whole;
+    });
+}
+//# sourceMappingURL=label.js.map