brane 0.1.1 → 0.3.0

package/dist/folds.js

@@ -0,0 +1,72 @@
+/**
+ * Registering a fold — the one implementation behind `POST /api/folds`,
+ * `brane fold`, and `brane absorb --fold`.
+ *
+ * Two callers, one rule with one switch. A phone on the tailnet must not be
+ * able to make `/` or `/etc` a spawn point, so a remote client's folds are
+ * confined to the operator's home directory. The operator's own shell is
+ * not so limited — `brane fold /Volumes/scratch/project` has always worked —
+ * and now that the CLI reaches this through the daemon, "the operator's own
+ * shell" has to be recognized on the wire. It is recognized as **loopback**:
+ * the CLI always talks to `127.0.0.1` (`buildDaemonBaseUrl`), and nothing
+ * outside this machine can. The route decides `confineToHome` from
+ * `req.socket.remoteAddress`; this module only applies it.
+ */
+import { existsSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { homedir } from "node:os";
+import { fromPortablePath, toPortablePath, getBraneId } from "./db/schema.js";
+import { getConfig } from "./commands/config.js";
+/** A registration the daemon refuses. `status` is the HTTP status the route
+ *  answers with — 400 for a bad path, 403 for one outside the caller's reach. */
+export class FoldRegistrationError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+/** The pure decision: is `absolute` a path this caller may register? Exported
+ *  so the rule can be pinned without a database. Returns the refusal, or
+ *  `null` when the path is allowed. */
+export function foldPathRefusal(absolute, opts) {
+    const home = opts.home ?? homedir();
+    if (opts.confineToHome) {
+        if (absolute !== home && !absolute.startsWith(home + "/")) {
+            return new FoldRegistrationError(`Folds must live under your home directory (${home})`, 403);
+        }
+        if (absolute === home) {
+            return new FoldRegistrationError("Refusing to fold your home directory itself; pick a subdirectory", 403);
+        }
+    }
+    if (!existsSync(absolute) || !statSync(absolute).isDirectory()) {
+        return new FoldRegistrationError(`Not a directory: ${absolute}`, 400);
+    }
+    return null;
+}
+/** Register `rawPath` (absolute or `~/portable`) as a fold. Idempotent:
+ *  re-registering an existing fold un-archives it and, when `braneId` is
+ *  given, rebinds it; otherwise it is a no-op. Never deletes. */
+export function registerFold(db, rawPath, opts) {
+    const absolute = resolve(fromPortablePath(rawPath.trim()));
+    const refusal = foldPathRefusal(absolute, opts);
+    if (refusal)
+        throw refusal;
+    const portable = toPortablePath(absolute);
+    const existing = db.prepare("SELECT * FROM folds WHERE path = ?").get(portable);
+    if (existing) {
+        if (existing.archived) {
+            db.prepare("UPDATE folds SET archived = 0 WHERE path = ?").run(portable);
+        }
+        if (opts.braneId && opts.braneId !== existing.brane_id) {
+            db.prepare("UPDATE folds SET brane_id = ? WHERE path = ?").run(opts.braneId, portable);
+        }
+    }
+    else {
+        const braneId = opts.braneId ?? getConfig("default.brane", db) ?? getBraneId(db);
+        db.prepare("INSERT INTO folds (path, created_at, brane_id, archived) VALUES (?, ?, ?, 0)").run(portable, Date.now(), braneId);
+    }
+    const fold = db.prepare("SELECT * FROM folds WHERE path = ?").get(portable);
+    return { fold, created: !existing };
+}
+//# sourceMappingURL=folds.js.map

package/dist/grammars/ebnf.js

@@ -0,0 +1,92 @@
+// TextMate grammar for EBNF / BNF-style rule definitions.
+// Targets ISO EBNF (`rule = ... ;`, `(* comment *)`, `'x'` / `"x"` terminals) and
+// W3C-style EBNF used in XML/HTML specs (`Rule ::= ...`, `#x20`, `[#x0-#x7F]`).
+// BNF angle-bracket non-terminals (`<name>`) are highlighted too.
+export const ebnf = {
+    name: "ebnf",
+    scopeName: "source.ebnf",
+    displayName: "EBNF",
+    aliases: ["bnf"],
+    patterns: [
+        { include: "#comment" },
+        { include: "#rule-definition" },
+        { include: "#angle-nonterminal" },
+        { include: "#char-class" },
+        { include: "#string" },
+        { include: "#hex-number" },
+        { include: "#number" },
+        { include: "#operator" },
+        { include: "#identifier" },
+    ],
+    repository: {
+        comment: {
+            name: "comment.block.ebnf",
+            begin: "\\(\\*",
+            end: "\\*\\)",
+        },
+        "rule-definition": {
+            match: "^\\s*(<[A-Za-z_][^<>\\s]*>|[A-Za-z_][A-Za-z0-9_-]*)\\s*(::=|=)(?!=)",
+            captures: {
+                "1": { name: "entity.name.function.ebnf" },
+                "2": { name: "keyword.operator.definition.ebnf" },
+            },
+        },
+        "angle-nonterminal": {
+            name: "entity.name.tag.ebnf",
+            match: "<[A-Za-z_][A-Za-z0-9_-]*>",
+        },
+        // Regex-style character classes (`[a-zA-Z_]`, `[^']`, `[#x0-#x7F]`).
+        // Swallowed as a single scope so the identifier/number/operator/string
+        // patterns don't fire on the interior — crucial because a bare `'` or
+        // `"` inside `[^'…]` / `[^"…]` would otherwise open a stray string scope
+        // that runs away until the next matching quote anywhere on the line.
+        "char-class": {
+            name: "constant.other.character-class.ebnf",
+            begin: "\\[",
+            beginCaptures: { "0": { name: "punctuation.definition.character-class.ebnf" } },
+            end: "\\]",
+            endCaptures: { "0": { name: "punctuation.definition.character-class.ebnf" } },
+            patterns: [
+                { name: "constant.character.escape.ebnf", match: "\\\\." },
+                { name: "constant.numeric.hex.ebnf", match: "#x[0-9A-Fa-f]+" },
+            ],
+        },
+        string: {
+            patterns: [
+                {
+                    name: "string.quoted.double.ebnf",
+                    begin: '"',
+                    end: '"',
+                    patterns: [
+                        { name: "constant.character.escape.ebnf", match: "\\\\." },
+                    ],
+                },
+                {
+                    name: "string.quoted.single.ebnf",
+                    begin: "'",
+                    end: "'",
+                    patterns: [
+                        { name: "constant.character.escape.ebnf", match: "\\\\." },
+                    ],
+                },
+            ],
+        },
+        "hex-number": {
+            name: "constant.numeric.hex.ebnf",
+            match: "#x[0-9A-Fa-f]+",
+        },
+        number: {
+            name: "constant.numeric.decimal.ebnf",
+            match: "\\b[0-9]+\\b",
+        },
+        operator: {
+            name: "keyword.operator.ebnf",
+            match: "::=|[|,;.*+?()\\[\\]{}=\\-→]",
+        },
+        identifier: {
+            name: "entity.name.tag.ebnf",
+            match: "\\b[A-Za-z_][A-Za-z0-9_]*\\b",
+        },
+    },
+};
+//# sourceMappingURL=ebnf.js.map

package/dist/highlight.js

@@ -0,0 +1,250 @@
+import { extname } from "node:path";
+import { createHash } from "node:crypto";
+import { createHighlighter, bundledLanguages } from "shiki";
+import { ebnf as ebnfGrammar } from "./grammars/ebnf.js";
+export const HIGHLIGHT_THEME = "github-dark-default";
+// Custom (non-bundled) grammars shipped in-repo. Loaded eagerly at highlighter
+// init so the "is this language known?" check below accepts them alongside
+// shiki's bundled set.
+const CUSTOM_GRAMMARS = [ebnfGrammar];
+const CUSTOM_LANG_NAMES = new Set(CUSTOM_GRAMMARS.flatMap((g) => [g.name, ...(g.aliases ?? [])]));
+function isKnownLang(lang) {
+    return lang in bundledLanguages || CUSTOM_LANG_NAMES.has(lang);
+}
+// File extension → shiki bundled language id, for the cases where the two
+// differ (`.rs` → rust, `.py` → python). Extensions that already *are* the
+// language id (`.lean`, `.zig`, `.nix`) need no entry — detectLanguage falls
+// back to the bare extension and lets shiki's own registry decide.
+const EXT_LANG = {
+    ".ts": "typescript",
+    ".tsx": "tsx",
+    ".mts": "typescript",
+    ".cts": "typescript",
+    ".js": "javascript",
+    ".jsx": "jsx",
+    ".mjs": "javascript",
+    ".cjs": "javascript",
+    ".json": "json",
+    ".jsonc": "jsonc",
+    ".sh": "bash",
+    ".bash": "bash",
+    ".zsh": "bash",
+    ".fish": "fish",
+    ".py": "python",
+    ".rb": "ruby",
+    ".go": "go",
+    ".rs": "rust",
+    ".c": "c",
+    ".h": "c",
+    ".cpp": "cpp",
+    ".cc": "cpp",
+    ".hpp": "cpp",
+    ".java": "java",
+    ".kt": "kotlin",
+    ".swift": "swift",
+    ".m": "objective-c",
+    ".mm": "objective-cpp",
+    ".cs": "csharp",
+    ".scala": "scala",
+    ".clj": "clojure",
+    ".ex": "elixir",
+    ".exs": "elixir",
+    ".erl": "erlang",
+    ".hs": "haskell",
+    ".lua": "lua",
+    ".php": "php",
+    ".dart": "dart",
+    ".vue": "vue",
+    ".svelte": "svelte",
+    ".astro": "astro",
+    ".css": "css",
+    ".scss": "scss",
+    ".less": "less",
+    ".html": "html",
+    ".htm": "html",
+    ".xml": "xml",
+    ".svg": "xml",
+    ".yaml": "yaml",
+    ".yml": "yaml",
+    ".toml": "toml",
+    ".ini": "ini",
+    ".sql": "sql",
+    ".graphql": "graphql",
+    ".gql": "graphql",
+    ".proto": "proto",
+    ".nix": "nix",
+    ".zig": "zig",
+    ".r": "r",
+    ".jl": "julia",
+    ".ebnf": "ebnf",
+    ".bnf": "ebnf",
+};
+// Extensions the *client* renders itself rather than as highlighted source —
+// FilesView routes these to MarkdownContent. Shiki does bundle `md`/`mdx`
+// grammars, so without this the extension fallback below would resolve them and
+// we'd ship a full token payload nobody looks at.
+const CLIENT_RENDERED_EXTS = new Set([".md", ".mdx", ".markdown"]);
+const BASENAME_LANG = {
+    "Dockerfile": "docker",
+    "Makefile": "make",
+    "CMakeLists.txt": "cmake",
+    ".gitignore": "shellscript",
+    ".env": "shellscript",
+};
+export function detectLanguage(filePath) {
+    const base = filePath.split("/").pop() ?? filePath;
+    for (const [needle, lang] of Object.entries(BASENAME_LANG)) {
+        // Exact match or "needle.<suffix>" (e.g. Dockerfile.dev, .env.local) — avoids
+        // bare `startsWith` over-matching ".env" into ".environmental".
+        if (base === needle || base.startsWith(needle + "."))
+            return lang;
+    }
+    const ext = extname(base).toLowerCase();
+    if (!ext)
+        return null;
+    if (EXT_LANG[ext])
+        return EXT_LANG[ext];
+    if (CLIENT_RENDERED_EXTS.has(ext))
+        return null;
+    // Long tail: for a great many languages the extension and shiki's language id
+    // are the same string (lean, zig, nix, tex, diff, …). Rather than grow the map
+    // one bug report at a time, ask shiki whether the bare extension names a
+    // grammar it has. The explicit map above still wins wherever they disagree.
+    const bare = ext.slice(1);
+    if (bare && isKnownLang(bare))
+        return bare;
+    return null;
+}
+// Fence tags that name no shiki grammar and aren't extension-shaped either, so
+// the extension fallback in resolveLang can't reach them. Kept deliberately
+// short: the map below is for words people type in fences, not a second
+// language registry.
+const FENCE_LANG = {
+    golang: "go",
+    plist: "xml",
+    xaml: "xml",
+    patch: "diff",
+};
+/**
+ * A fenced block's info string → a grammar shiki can actually load, or null to
+ * render the block as plain text.
+ *
+ * The info string is whatever the author typed, and the two obvious sources of
+ * it disagree about vocabulary. Shiki's `bundledLanguages` is generous with
+ * aliases (`js`, `sh`, `yml`, `c++` all resolve) but has no SVG grammar, so
+ * ```svg fell through to plain text — while the *same bytes* opened from the
+ * Files tab highlighted fine, because that path resolves `.svg` through
+ * EXT_LANG instead. Rather than keep two vocabularies, a tag shiki doesn't know
+ * is retried as if it were a file extension, which inherits EXT_LANG whole and
+ * every entry added to it later.
+ */
+export function resolveLang(lang) {
+    if (!lang)
+        return null;
+    const tag = lang.trim().toLowerCase();
+    if (!tag)
+        return null;
+    if (isKnownLang(tag))
+        return tag;
+    if (FENCE_LANG[tag])
+        return FENCE_LANG[tag];
+    return detectLanguage(`x.${tag}`);
+}
+let highlighterP = null;
+async function getHighlighter() {
+    if (!highlighterP) {
+        highlighterP = createHighlighter({ themes: [HIGHLIGHT_THEME], langs: CUSTOM_GRAMMARS });
+    }
+    return highlighterP;
+}
+// Memoize per-language load promises so concurrent first-loads of the same
+// language collapse to a single underlying loadLanguage call.
+const langLoads = new Map();
+async function ensureLangLoaded(hl, lang) {
+    if (hl.getLoadedLanguages().includes(lang))
+        return true;
+    let p = langLoads.get(lang);
+    if (!p) {
+        p = hl.loadLanguage(lang).then(() => undefined);
+        langLoads.set(lang, p);
+        p.catch(() => {
+            // Failed load — drop the memo so a later retry can try again
+            langLoads.delete(lang);
+        });
+    }
+    try {
+        await p;
+        return true;
+    }
+    catch (err) {
+        console.warn(`[highlight] failed to load grammar for ${lang}:`, err);
+        return false;
+    }
+}
+const CACHE_MAX = 200;
+const cache = new Map();
+function cacheGet(key) {
+    const v = cache.get(key);
+    if (v !== undefined) {
+        cache.delete(key);
+        cache.set(key, v);
+    }
+    return v;
+}
+function cacheSet(key, value) {
+    cache.set(key, value);
+    if (cache.size > CACHE_MAX) {
+        const firstKey = cache.keys().next().value;
+        if (firstKey !== undefined)
+            cache.delete(firstKey);
+    }
+}
+function compactTokens(tokens) {
+    return tokens.map((line) => line.map((tok) => {
+        const out = { c: tok.content };
+        if (tok.color)
+            out.f = tok.color;
+        if (tok.fontStyle && tok.fontStyle > 0)
+            out.s = tok.fontStyle;
+        return out;
+    }));
+}
+/**
+ * Shiki-rendered HTML for a code snippet. Returns null if the tag resolves to
+ * no grammar, or the grammar fails to load — caller falls back to raw text.
+ */
+export async function highlightHtml(content, lang) {
+    const resolved = resolveLang(lang);
+    if (!resolved)
+        return null;
+    const hl = await getHighlighter();
+    if (!(await ensureLangLoaded(hl, resolved)))
+        return null;
+    return hl.codeToHtml(content, { lang: resolved, theme: HIGHLIGHT_THEME });
+}
+export async function highlight(content, lang) {
+    // The resolved id is what gets cached and reported back, so ```svg and
+    // ```xml share one cache entry rather than tokenizing the same bytes twice.
+    const resolved = resolveLang(lang);
+    if (!resolved)
+        return null;
+    const hl = await getHighlighter();
+    if (!(await ensureLangLoaded(hl, resolved)))
+        return null;
+    const sha = createHash("sha1").update(content).digest("hex");
+    const key = `${sha}:${resolved}:${HIGHLIGHT_THEME}`;
+    const cached = cacheGet(key);
+    if (cached)
+        return cached;
+    const result = hl.codeToTokens(content, { lang: resolved, theme: HIGHLIGHT_THEME });
+    const out = {
+        lang: resolved,
+        theme: HIGHLIGHT_THEME,
+        bg: result.bg ?? "#0f0f0f",
+        fg: result.fg ?? "#e0e0e0",
+        tokens: compactTokens(result.tokens),
+    };
+    cacheSet(key, out);
+    return out;
+}
+//# sourceMappingURL=highlight.js.map

package/dist/ids.js

@@ -0,0 +1,24 @@
+import { randomBytes } from "node:crypto";
+/**
+ * Generate a crypto-random string of `len` lowercase base36 characters
+ * (`0-9a-z`). Used for the collision-resistant suffixes of narrative ids
+ * (`<agent>-<8>`), brane ids (`brane-<6>`), and server-minted external ids
+ * (`external-<8>`).
+ */
+export function randomBase36(len) {
+    const alphabet = "0123456789abcdefghijklmnopqrstuvwxyz";
+    // Rejection-sample to avoid modulo bias: 256 is not a multiple of 36, so a
+    // plain `byte % 36` would map the high bytes (252-255) onto 0-3, skewing
+    // those four characters. Discard bytes >= 252 (the largest multiple of 36)
+    // and redraw, so every character is uniform over the 36-symbol alphabet.
+    let s = "";
+    while (s.length < len) {
+        const bytes = randomBytes(len - s.length);
+        for (let i = 0; i < bytes.length && s.length < len; i++) {
+            if (bytes[i] < 252)
+                s += alphabet[bytes[i] % 36];
+        }
+    }
+    return s;
+}
+//# sourceMappingURL=ids.js.map

package/dist/markdown-diagnostics.js

@@ -0,0 +1,233 @@
+/** What a narration is about to look like, told to the agent writing it.
+ *
+ *  Every renderer in this codebase fails *quietly* by design: unparseable
+ *  LaTeX comes back as its own source rather than as KaTeX's red error markup
+ *  (`renderMathHtml`), a `$…$` run that trips the currency guard is escaped
+ *  into prose (`prepareMathMarkdown`), an unclosed fence simply swallows the
+ *  rest of the message. That is the right behaviour for the *reader*, who
+ *  wants a document rather than a diagnostic — and exactly wrong for the
+ *  *writer*, who never finds out that the equation they wrote did not set.
+ *
+ *  This module closes that gap without reopening it for the reader: the
+ *  rendering is unchanged, and the reasoning the renderers were already doing
+ *  is reported back through `narrate` instead of being discarded.
+ *
+ *  Two properties make the report trustworthy enough to act on:
+ *
+ *  **It is the real parse, not a lookalike.** The math run is found by the
+ *  same `prepareMathMarkdown` and rendered by the same micromark pass the
+ *  export uses, so a warning fires if and only if the operator's view differs
+ *  from what was intended. A second scanner written to approximate the first
+ *  would eventually disagree with it, and a linter that cries wolf is worse
+ *  than no linter.
+ *
+ *  **Every warning carries its fallback** — the literal text that will appear
+ *  in place of the intended rendering. Whether a failure *matters* is a
+ *  judgment only the author can make, and it turns almost entirely on that
+ *  text: `$E = mc^2$` shown as source still communicates; a matrix shown as
+ *  source is line noise. Reporting the parser's complaint without the fallback
+ *  would leave that call unmakeable.
+ */
+import { micromark } from "micromark";
+import { gfmTable, gfmTableHtml } from "micromark-extension-gfm-table";
+import { gfmAutolinkLiteral, gfmAutolinkLiteralHtml } from "micromark-extension-gfm-autolink-literal";
+import { gfmTaskListItem, gfmTaskListItemHtml } from "micromark-extension-gfm-task-list-item";
+import { math } from "micromark-extension-math";
+import { mathHtmlExtension } from "./math.js";
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { inspectDiagram } from "./diagram/index.js";
+import { mathContentRejection, prepareMathMarkdown, } from "./shared/markdown-math.js";
+/** Does this rejected `$…$` run look like a failed equation rather than prose?
+ *
+ *  The guard in `mathContentRejection` throws out far more currency and shell
+ *  syntax than it does mathematics, and warning on every one of those would
+ *  bury the real findings. A backslash command or a sub/superscript that opens
+ *  a group is the signal that someone was writing TeX: `$\\theta$`, `$x_{i+1}$`.
+ *  Bare `$PATH` and `$5 to $10` stay silent, which is the whole point.
+ */
+const TEX_ISH = /\\[a-zA-Z]|[\^_]\s*[{(]/;
+/** Cheap enough to run on every narration: a source with no math token at all
+ *  never reaches micromark, and the scan that finds fence and delimiter
+ *  problems is the same single pass `prepareMathMarkdown` already makes. */
+const HAS_MATH_TOKEN = /(?:^|[^\\])\$/;
+/** How many warnings one narration can produce. A message that trips more than
+ *  this is broken in a way the first few already explain. */
+const MAX_DIAGNOSTICS = 10;
+export function diagnoseMarkdown(md) {
+    const out = [];
+    const issues = [];
+    const prepared = prepareMathMarkdown(md, (issue) => issues.push(issue));
+    for (const issue of issues) {
+        const line = lineOf(md, issue.index);
+        switch (issue.kind) {
+            case "dollar_escaped": {
+                const reason = mathContentRejection(issue.content, issue.after);
+                if (!reason || !TEX_ISH.test(issue.content))
+                    break;
+                out.push({
+                    kind: "math_demoted",
+                    message: `\`$${clamp(issue.content, 60)}$\` looks like math, but ${reason} — so it is not treated as math and renders as literal text.`,
+                    fallback: `$${clamp(issue.content, 120)}$`,
+                    line,
+                });
+                break;
+            }
+            case "tex_unmatched":
+                out.push({
+                    kind: "math_unclosed",
+                    message: `${capitalize(issue.reason)} — the LaTeX renders as literal text.`,
+                    fallback: excerptAt(md, issue.index),
+                    line,
+                });
+                break;
+            case "display_unclosed":
+                out.push({
+                    kind: "math_unclosed",
+                    message: "`$$` is never closed — everything after it is swallowed into one display-math block.",
+                    fallback: excerptAt(md, issue.index),
+                    line,
+                });
+                break;
+            case "fence_unclosed":
+                out.push({
+                    kind: "fence_unclosed",
+                    message: "A code fence is never closed — everything after it renders as one code block.",
+                    fallback: excerptAt(md, issue.index),
+                    line,
+                });
+                break;
+        }
+    }
+    if (HAS_MATH_TOKEN.test(prepared)) {
+        // Rendered and thrown away: the HTML is the export's business, and all we
+        // want from this pass is which runs KaTeX refused.
+        micromark(prepared, {
+            extensions: [gfmTable(), gfmAutolinkLiteral(), gfmTaskListItem(), math()],
+            htmlExtensions: [
+                gfmTableHtml(),
+                gfmAutolinkLiteralHtml(),
+                gfmTaskListItemHtml(),
+                mathHtmlExtension((message, fallback) => {
+                    out.push({
+                        kind: "math_parse_error",
+                        message,
+                        fallback: clamp(fallback, 160),
+                        // Best-effort: the LaTeX reaching KaTeX has been normalized, so it
+                        // is not always findable in the source the author typed. A line
+                        // that might be wrong would be worse than none, so it is omitted
+                        // rather than guessed.
+                        line: lineOfValue(md, fallback),
+                    });
+                }),
+            ],
+        });
+    }
+    for (const d of diagnoseDiagramFences(md))
+        out.push(d);
+    return out.slice(0, MAX_DIAGNOSTICS);
+}
+/** ```mermaid fences that will not draw.
+ *
+ *  Same contract as the math warnings: it is the *real* decision, taken by the
+ *  same `diagnoseDiagram` the renderers call, so a warning fires iff the
+ *  operator sees source where a diagram was meant.
+ *
+ *  Which is why the fences come from **a markdown parse and not a regex**. The
+ *  first draft scanned for the fence with a pattern, three lines under a
+ *  comment forbidding exactly that, and it disagreed with the renderers in
+ *  both directions inside a week: a mermaid fence quoted *inside* a longer
+ *  ```` fence — which is how an agent documents this feature — warned about a
+ *  diagram that was never going to draw, while a fence inside a blockquote
+ *  renders and was never diagnosed. `fromMarkdown` sees what micromark sees,
+ *  because it is micromark.
+ *
+ *  `fallback` is the source, because that is literally what appears — the
+ *  highlighted code block a mermaid fence renders as today. Judging whether it
+ *  matters is the author's call and turns on reading it: a four-line flowchart
+ *  shown as source still communicates; a thirty-line one does not.
+ */
+function diagnoseDiagramFences(md) {
+    const out = [];
+    // Cheap gate so an ordinary narration never pays for a parse. Deliberately
+    // just the word: anything narrower has to model where a fence may start, and
+    // a `>`-prefixed one inside a blockquote is exactly what the first attempt
+    // at that missed — which is the bug this function was being rewritten for.
+    if (!/mermaid/i.test(md))
+        return out;
+    let tree;
+    try {
+        tree = fromMarkdown(md);
+    }
+    catch {
+        return out;
+    }
+    const walk = (node) => {
+        if (!node || typeof node !== "object")
+            return;
+        if (node.type === "code" && typeof node.lang === "string" &&
+            node.lang.toLowerCase() === "mermaid") {
+            const body = typeof node.value === "string" ? node.value : "";
+            if (body.trim()) {
+                const { refusal, literal } = inspectDiagram(body);
+                // mdast gives the fence's own line; the body starts on the next one.
+                const bodyLine = (node.position?.start?.line ?? 0) + 1;
+                // The diagram draws, but some label shows its markup as text. The
+                // fallback is the statement's source line, since that is where the
+                // characters the operator sees come from.
+                const bodyLines = body.split("\n");
+                for (const note of literal) {
+                    out.push({
+                        kind: "diagram_label_literal",
+                        message: `In this \`mermaid\` diagram, ${note.message}.`,
+                        fallback: clamp((bodyLines[note.line - 1] ?? "").trim(), 160),
+                        line: bodyLine + note.line - 1,
+                    });
+                }
+                if (refusal) {
+                    out.push({
+                        kind: refusal.kind === "unsupported" ? "diagram_unsupported" : "diagram_parse_error",
+                        message: `This \`mermaid\` diagram will not draw: ${refusal.message}. It renders as its own source.`,
+                        fallback: clamp(body.trim(), 280),
+                        line: refusal.line === undefined ? bodyLine : bodyLine + refusal.line - 1,
+                    });
+                }
+            }
+            return;
+        }
+        for (const child of (node.children ?? []))
+            walk(child);
+    };
+    walk(tree);
+    return out;
+}
+/** The line a failed run sits on, found by its own source, or undefined. */
+function lineOfValue(md, fallback) {
+    // Delimiters and all first: the same LaTeX may appear earlier as a code
+    // listing, and a listing is not the run that failed.
+    let at = md.indexOf(fallback);
+    if (at === -1) {
+        const value = fallback.replace(/^\$\$?|\$\$?$/g, "");
+        at = value ? md.indexOf(value) : -1;
+    }
+    return at === -1 ? undefined : lineOf(md, at);
+}
+function lineOf(md, index) {
+    let line = 1;
+    for (let i = 0; i < index && i < md.length; i++)
+        if (md[i] === "\n")
+            line++;
+    return line;
+}
+/** The rest of the line starting at `index`, capped — enough to recognize the
+ *  spot without pasting a paragraph back at the author. */
+function excerptAt(md, index, max = 80) {
+    const end = md.indexOf("\n", index);
+    return clamp(md.slice(index, end === -1 ? md.length : end), max);
+}
+function clamp(s, max) {
+    return s.length > max ? s.slice(0, max - 1) + "…" : s;
+}
+function capitalize(s) {
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}
+//# sourceMappingURL=markdown-diagnostics.js.map