@dooc-dev/dooc 0.0.0-stage → 0.0.1

package/dist/compiler/dialect.d.ts

@@ -0,0 +1,24 @@
+import type { Root } from "mdast";
+import type { TermEntry } from "../core/content-types.js";
+import type { PreviewSettings } from "../core/previewers.js";
+import { type Frontmatter } from "../core/taxonomy.js";
+export { parseMdast } from "../core/markdown.js";
+export interface ParsedDoc {
+    terms: TermEntry[];
+    frontmatter: Frontmatter | undefined;
+    /** Body text without the front-matter (becomes the manifest's body). */
+    body: string;
+    /** Source passed to parse; root position offsets use it. */
+    source: string;
+    root: Root;
+    errors: string[];
+}
+export declare const parseDoc: (input: string, settings?: PreviewSettings, file?: string) => ParsedDoc;
+/**
+ * Collect files referenced by Markdown links and embeds for validation and export.
+ */
+export declare const collectRefs: (root: Root, settings?: PreviewSettings) => {
+    figures: string[];
+    terms: string[];
+    textfiles: string[];
+};

package/dist/compiler/dialect.js

@@ -0,0 +1,198 @@
+import { visit } from "unist-util-visit";
+import { parse as parseYaml } from "yaml";
+import { parseFigureLink, parseFileEmbed } from "../core/file-embed.js";
+import { isLangTag } from "../core/language.js";
+import { contentLinks, embeddedImages, parseMdast } from "../core/markdown.js";
+import { parseDocLink } from "../core/routing.js";
+import { FM_OPTIONAL, FM_REQUIRED } from "../core/taxonomy.js";
+import { parseTermReference } from "../core/term-reference.js";
+import { parseTextfileRange } from "../core/textfile.js";
+import { parseContentCode } from "./code-blocks.js";
+export { parseMdast } from "../core/markdown.js";
+// Unsupported nodes are reported before conversion so source content is never silently dropped.
+const ALLOWED_TYPES = new Set([
+    "root",
+    "yaml",
+    "paragraph",
+    "heading",
+    "list",
+    "listItem",
+    "code",
+    "inlineCode",
+    "table",
+    "tableRow",
+    "tableCell",
+    "text",
+    "link",
+    "image",
+    "strong",
+    "emphasis",
+    "blockquote",
+]);
+const line = (n) => (n.position ? `L${n.position.start.line}` : "L?");
+const checkFrontmatter = (raw, errors) => {
+    if (typeof raw !== "object" || raw == null || Array.isArray(raw)) {
+        errors.push("front-matter: a YAML object is required");
+        return undefined;
+    }
+    const fm = raw;
+    const required = FM_REQUIRED;
+    const allowed = [...FM_REQUIRED, ...FM_OPTIONAL];
+    for (const key of Object.keys(fm)) {
+        if (!allowed.includes(key)) {
+            errors.push(`front-matter: unknown key "${key}" (allowed: ${allowed.join(", ")})`);
+        }
+    }
+    for (const key of required) {
+        if (typeof fm[key] !== "string" || fm[key] === "") {
+            errors.push(`front-matter: "${key}" (string) is required`);
+        }
+    }
+    if (fm.lang !== undefined && !(typeof fm.lang === "string" && isLangTag(fm.lang))) {
+        errors.push('front-matter: "lang" must be a BCP 47 language tag (e.g. "en", "ja", "pt-BR")');
+    }
+    return errors.length === 0 ? fm : undefined;
+};
+const checkHeading = (n, errors) => {
+    if (n.depth < 1 || n.depth > 3) {
+        errors.push(`${line(n)}: only # / ## / ### headings are allowed (not h${n.depth})`);
+    }
+};
+// Quotes retain their block structure even when nested inside list items.
+const checkListItem = (n, errors) => {
+    for (const child of n.children) {
+        if (child.type !== "paragraph" && child.type !== "list" && child.type !== "blockquote") {
+            errors.push(`${line(child)}: ${child.type} is not allowed directly under listItem (paragraph / list / quote only)`);
+        }
+    }
+};
+const checkLink = (n, errors) => {
+    try {
+        parseDocLink(n.url);
+        parseFigureLink(n.url);
+        parseTermReference(n.url);
+    }
+    catch (error) {
+        errors.push(`${line(n)}: ${error instanceof Error ? error.message : error}`);
+    }
+    if (n.url.startsWith("doc:"))
+        errors.push(`${line(n)}: use a Markdown file link instead of doc:`);
+    if (n.url === "") {
+        errors.push(`${line(n)}: link with an empty URL`);
+    }
+};
+export const parseDoc = (input, settings, file) => {
+    const errors = [];
+    const raw = input;
+    const root = parseMdast(raw);
+    const embeds = new Set(embeddedImages(root));
+    const terms = [];
+    const yamlNode = root.children[0];
+    let frontmatter;
+    let body = input;
+    if (yamlNode?.type === "yaml") {
+        try {
+            frontmatter = checkFrontmatter(parseYaml(yamlNode.value), errors);
+        }
+        catch (e) {
+            errors.push(`front-matter: YAML parse failed (${e instanceof Error ? e.message : e})`);
+        }
+        const end = yamlNode.position?.end.offset;
+        body = end != null ? input.slice(end).replace(/^\n+/, "") : raw;
+    }
+    else {
+        errors.push("front-matter (---) is required at the top");
+    }
+    visit(root, (node, _index, parent) => {
+        if (node.type === "text" &&
+            /(?:^|\n)[ \t]*:{2,}[a-z]+\b/.test(raw.slice(node.position?.start.offset, node.position?.end.offset)))
+            errors.push(`${line(node)}: removed directive; use Markdown file links or callouth / schemath / graphth / termth code fences`);
+        if (!ALLOWED_TYPES.has(node.type)) {
+            const hint = node.type === "html" ? ' (put "<" inside backticks or escape it as "\\<")' : "";
+            errors.push(`${line(node)}: ${node.type} is outside the dialect${hint}`);
+            return;
+        }
+        switch (node.type) {
+            case "code": {
+                const parsed = parseContentCode(node, raw, file);
+                if (!parsed)
+                    break;
+                if (parent?.type !== "root") {
+                    errors.push(`${line(node)}: ${node.lang} must be a top-level code block`);
+                    break;
+                }
+                for (const error of parsed.errors)
+                    errors.push(`L${(node.position?.start.line ?? 0) + 1 + error.line}: ${node.lang} ${error.message}`);
+                for (const block of parsed.blocks)
+                    if (block.type === "term")
+                        terms.push(block.entry);
+                break;
+            }
+            case "image": {
+                if (!embeds.has(node)) {
+                    errors.push(`${line(node)}: file previews must occupy a standalone paragraph`);
+                    break;
+                }
+                try {
+                    const { range } = parseFileEmbed(node.url, settings);
+                    if (range !== undefined)
+                        parseTextfileRange(range);
+                }
+                catch (error) {
+                    errors.push(`${line(node)}: ${error instanceof Error ? error.message : error}`);
+                }
+                break;
+            }
+            case "heading":
+                checkHeading(node, errors);
+                break;
+            case "listItem":
+                checkListItem(node, errors);
+                break;
+            case "link":
+                checkLink(node, errors);
+                break;
+            default:
+                break;
+        }
+    });
+    return { frontmatter, body, source: raw, root, errors, terms };
+};
+/**
+ * Collect files referenced by Markdown links and embeds for validation and export.
+ */
+export const collectRefs = (root, settings) => {
+    const figures = [];
+    const terms = [];
+    const textfiles = [];
+    for (const image of embeddedImages(root)) {
+        try {
+            const { file, kind } = parseFileEmbed(image.url, settings);
+            if (kind === "textfile")
+                textfiles.push(file);
+            else if (kind !== "external")
+                figures.push(file);
+        }
+        catch {
+            // Invalid references are reported by parseDoc and must not reach file I/O.
+        }
+    }
+    for (const node of contentLinks(root)) {
+        try {
+            const file = parseTermReference(node.url);
+            if (file)
+                terms.push(file);
+            const figure = parseFigureLink(node.url);
+            if (figure)
+                figures.push(figure.file);
+        }
+        catch {
+            /* Validation reports invalid file paths. */
+        }
+    }
+    return {
+        figures: [...new Set(figures)],
+        terms: [...new Set(terms)],
+        textfiles: [...new Set(textfiles)],
+    };
+};

package/dist/compiler/drawio.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Extract the mxfile XML from the root <svg>'s content attribute.
+ * A prolog / DOCTYPE may precede it, so cut the start tag from the `<svg` position (the first `>`
+ * belongs to the prolog).
+ */
+export declare const extractMxfile: (raw: string) => string | undefined;
+/** The mxfile's first <diagram name="..."> = the draw.io page name (= figure description). */
+export declare const mxfilePageName: (mxfile: string) => string | undefined;
+/**
+ * Whether an svg in figures/ was exported by draw.io. To avoid catching hand-written figures, it
+ * checks for traces only draw.io emits: the mxfile copy (content attribute) / the drawio.com
+ * fallback <switch> / draw.io CSS variables (`--ge-*`) / an inline `color-scheme` on the root.
+ */
+export declare const isDrawioSvg: (raw: string) => boolean;
+export interface DrawioNormalized {
+    markup: string;
+    /** draw.io page name = figure description (for <desc>). Absent if exported without the copy. */
+    desc?: string;
+}
+/**
+ * Normalize a draw.io-exported SVG into an SVG figures.ts can handle. `name` is the figure's name
+ * (= the name in figures/<name>.svg, used for <title>Fig.<name></title>).
+ * The returned markup is still a raw <svg>…</svg> string; figures.ts goes on to do the theme
+ * injection and structural validation.
+ */
+export declare const normalizeDrawioSvg: (name: string, raw: string) => DrawioNormalized;

package/dist/compiler/drawio.js

@@ -0,0 +1,176 @@
+// Normalization of SVGs exported from draw.io = this module is the SoT.
+//
+// Two ways to place them (see also the top of figures.ts):
+//   - figures/<name>.drawio.svg = File > Save as (Editable SVG). Carries a copy of the mxfile, so
+//              one file is both the editing source and the output (open in draw.io and Save to
+//              update it). Recommended
+//   - figures/<name>.svg = File > Export as > SVG (the editing source can live anywhere).
+//              Drift between the two (only the svg is stale) is handled by people re-exporting;
+//              the build doesn't verify the relationship (= no machinery beyond "make draw.io
+//              easy to work with locally")
+// figures.ts passes .drawio.svg through here unconditionally, and .svg only when it comes from
+// draw.io (`isDrawioSvg`), then feeds it to the same parseSvg as hand-written SVGs.
+//
+// **Colors stay in draw.io's scheme (not mapped to the var(--doc-*) of hand-written figures).**
+// Because draw.io itself emits both light and dark values via CSS light-dark() on export:
+//     stroke: light-dark(rgb(0,0,0), rgb(255,255,255))
+//     fill:   light-dark(rgb(218,232,252), rgb(29,41,59))   ← auto dark version of chosen color
+//     --ge-adaptive-bg: light-dark(#ffffff, var(--ge-dark-color, #121212))
+// Figures are fully self-contained in terms of color. Mapping them onto the docs palette (=
+// erroring on colors not in the table) is rejected: it takes away drawing freedom and would
+// duplicate draw.io's own dark support. Some mismatch with the docs color scheme is acceptable.
+//
+// Only four things happen here:
+//   1. Drop the XML prolog / DOCTYPE (figures.ts requires a single root <svg>; if left in, the
+//      theme injection breaks the prolog)
+//   2. Drop the content attribute (the mxfile copy) from rendered output — it's editing data, not
+//      needed for distribution. Works whether "include a copy of the diagram" is ON or OFF at
+//      export
+//   3. Drop the trailing "Text is not SVG - cannot display" fallback — it embeds an external
+//      link to drawio.com, and shipped figures shouldn't keep needless external links
+//   4. Adjust the root's inline style so resolving light-dark() is left to the docs (below)
+//
+// What 4 does = hand only the "control over switching" light/dark to the docs:
+//   - draw.io writes `color-scheme: light dark` inline on the root. Inline beats the
+//     [data-doc-figure] style injected by figures.ts, so as-is the figure alone would follow the
+//     **OS setting** for light/dark and not the docs theme toggle (data-theme="dark"). So only
+//     the root's color-scheme declaration is removed, leaving it to figures.ts's theme injection.
+//   - For the background, point `--ge-dark-color` (the variable draw.io uses for dark surfaces)
+//     at the docs panel color. draw.io reads it through the variable, so this is a "stable
+//     override point".
+//
+// title / desc follow the hand-written figure convention: title is fixed to `Fig.<name>`
+// (injected mechanically); desc = the figure description comes from the mxfile's <diagram name>
+// (= the draw.io page name) — only available when "include a copy of the diagram" was ON at
+// export. If OFF, there's no desc (not an error).
+/** Unescape XML entities, numeric ones included (to extract the mxfile from content). */
+const unescapeXml = (s) => s
+    .replace(/&#(\d+);/g, (_, d) => String.fromCodePoint(Number(d)))
+    .replace(/&#x([0-9a-fA-F]+);/g, (_, h) => String.fromCodePoint(Number.parseInt(h, 16)))
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&amp;/g, "&");
+/** draw.io's default page names — meaningless as a description, so not turned into <desc>. */
+const DEFAULT_PAGE_NAMES = new Set(["page-1", "ページ-1", "page 1", "untitled", ""]);
+// The content attribute is "one long attribute carrying the mxfile".
+const CONTENT_ATTR = /\scontent="(?:[^"\\]|\\.)*"/;
+const rootHead = (raw) => {
+    const start = raw.indexOf("<svg");
+    if (start < 0) {
+        return undefined;
+    }
+    const end = raw.indexOf(">", start);
+    return raw.slice(start, end < 0 ? undefined : end + 1);
+};
+/**
+ * Extract the mxfile XML from the root <svg>'s content attribute.
+ * A prolog / DOCTYPE may precede it, so cut the start tag from the `<svg` position (the first `>`
+ * belongs to the prolog).
+ */
+export const extractMxfile = (raw) => {
+    const head = rootHead(raw);
+    const m = head ? /\scontent="([^"]*)"/.exec(head) : null;
+    const xml = m?.[1] ? unescapeXml(m[1]) : undefined;
+    return xml?.includes("<mxfile") || xml?.includes("<mxGraphModel") ? xml : undefined;
+};
+/** The mxfile's first <diagram name="..."> = the draw.io page name (= figure description). */
+export const mxfilePageName = (mxfile) => {
+    const m = /<diagram[^>]*\sname="([^"]*)"/.exec(mxfile);
+    const name = m?.[1] ? unescapeXml(m[1]).trim() : "";
+    return name ? name : undefined;
+};
+/**
+ * Whether an svg in figures/ was exported by draw.io. To avoid catching hand-written figures, it
+ * checks for traces only draw.io emits: the mxfile copy (content attribute) / the drawio.com
+ * fallback <switch> / draw.io CSS variables (`--ge-*`) / an inline `color-scheme` on the root.
+ */
+export const isDrawioSvg = (raw) => {
+    if (extractMxfile(raw)) {
+        return true;
+    }
+    if (raw.includes("Text is not SVG - cannot display") || raw.includes("--ge-")) {
+        return true;
+    }
+    const head = rootHead(raw);
+    return !!head && /\sstyle="[^"]*color-scheme\s*:/.test(head);
+};
+// Strip the whole leading prolog. draw.io emits `<?xml?>` → `<!-- Do not edit this file with
+// editors other than draw.io -->` → `<!DOCTYPE>` in that order (the .drawio.svg Save format inserts
+// the comment), so peel items off until the root <svg> comes first, without assuming kind or order.
+const PROLOG_ITEM = /^\s*(?:<\?xml[^>]*\?>|<!DOCTYPE[^>[]*(?:\[[\s\S]*?\])?>|<!--[\s\S]*?-->)\s*/i;
+const stripProlog = (s) => {
+    let out = s.replace(/^\uFEFF/, "");
+    for (let m = PROLOG_ITEM.exec(out); m; m = PROLOG_ITEM.exec(out)) {
+        out = out.slice(m[0].length);
+    }
+    return out.trim();
+};
+// For renderers that can't draw foreignObject, draw.io appends a <switch> embedding an <a> link
+// to drawio.com. Drop it so shipped figures don't keep a needless external link.
+const stripFallbackLink = (s) => s.replace(/<switch>\s*<g\s+requiredFeatures="[^"]*"\s*\/>\s*<a\b[^>]*>[\s\S]*?<\/a>\s*<\/switch>/g, "");
+/** Background the docs side can override (the variable draw.io uses for dark surfaces). */
+const DARK_SURFACE = "--ge-dark-color: var(--doc-panel, #161b22)";
+/**
+ * Remove the `color-scheme` declaration from the root <svg>'s inline style and point only the
+ * dark surface color at the docs. If color-scheme stayed, its inline strength would beat
+ * figures.ts's theme injection and the figure alone would follow the OS light/dark setting
+ * (= not follow the docs theme toggle).
+ */
+const adaptRootStyle = (markup) => {
+    const open = markup.indexOf(">");
+    if (!markup.startsWith("<svg") || open < 0) {
+        return markup;
+    }
+    const head = markup.slice(0, open);
+    const rest = markup.slice(open);
+    const m = /\sstyle="([^"]*)"/.exec(head);
+    if (!m) {
+        return `${head} style="${DARK_SURFACE}"${rest}`;
+    }
+    const decls = (m[1] ?? "")
+        .split(";")
+        .map((d) => d.trim())
+        .filter((d) => d && !/^color-scheme\s*:/i.test(d));
+    decls.push(DARK_SURFACE);
+    return `${head.slice(0, m.index)} style="${decls.join("; ")}"${head.slice(m.index + m[0].length)}${rest}`;
+};
+/**
+ * Normalize a draw.io-exported SVG into an SVG figures.ts can handle. `name` is the figure's name
+ * (= the name in figures/<name>.svg, used for <title>Fig.<name></title>).
+ * The returned markup is still a raw <svg>…</svg> string; figures.ts goes on to do the theme
+ * injection and structural validation.
+ */
+export const normalizeDrawioSvg = (name, raw) => {
+    const mxfile = extractMxfile(raw);
+    let markup = stripProlog(raw);
+    // Drop the content attribute — editing data doesn't go into the rendered output.
+    const headEnd = markup.indexOf(">");
+    if (headEnd >= 0) {
+        markup = markup.slice(0, headEnd).replace(CONTENT_ATTR, "") + markup.slice(headEnd);
+    }
+    markup = stripFallbackLink(markup).trim();
+    markup = adaptRootStyle(markup);
+    // Follow the same convention as hand-written figures: <title> fixed to Fig.<name>, <desc> is
+    // the description. The description is the draw.io page name (tab name) — only available from
+    // the mxfile copy included in the export.
+    //
+    // A default page name / no copy is **not an error**. <desc> is optional for figures/*.svg too
+    // (parseSvg accepts it missing); a figure without one just falls back to a caption of
+    // "Fig.<name>" and still renders = it isn't "unshippable".
+    const page = mxfile ? mxfilePageName(mxfile) : undefined;
+    const desc = page && !DEFAULT_PAGE_NAMES.has(page.toLowerCase()) ? page : undefined;
+    const esc = (v) => v.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+    const open = markup.indexOf(">");
+    if (open >= 0) {
+        // draw.io doesn't write <title>/<desc>, but drop any existing ones to avoid duplicates.
+        const body = markup
+            .slice(open + 1)
+            .replace(/^\s*<title[^>]*>[\s\S]*?<\/title>/, "")
+            .replace(/^\s*<desc[^>]*>[\s\S]*?<\/desc>/, "");
+        const meta = `<title>Fig.${esc(name)}</title>${desc ? `<desc>${esc(desc)}</desc>` : ""}`;
+        markup = `${markup.slice(0, open + 1)}${meta}${body}`;
+    }
+    return { markup, desc };
+};

package/dist/compiler/figures.d.ts

@@ -0,0 +1,14 @@
+import type { FigureEntry } from "../core/content-types.js";
+/** File relative to figures/ → the figure's registered name (stem without the extension). */
+export declare const figureName: (file: string) => string;
+/**
+ * Original file name of a figure added from the editing UI → a name following the figures/
+ * convention (svg / drawio.svg / html / raster). The stem is coerced to lowercase alphanumerics
+ * and _-, or "figure" if nothing remains. Unsupported extensions yield undefined.
+ */
+export declare const figureUploadName: (raw: string) => string | undefined;
+export type { FigureEntry } from "../core/content-types.js";
+export declare const loadFigures: (figuresDir: string, extraFiles?: string[]) => {
+    figures: FigureEntry[];
+    errors: string[];
+};

package/dist/compiler/figures.js

@@ -0,0 +1,221 @@
+import { createHash } from "node:crypto";
+// figures/ = the SoT for HTML-based Figs (figures). Two formats:
+//   - <name>.svg  : self-contained SVG (xmlns + viewBox + <title>Fig.<name></title> +
+//                   optional <desc>description</desc>)
+//   - <name>.html : self-contained HTML fragment (leading <!--fig title/desc --> meta comment,
+//                   styles such as CSS animations bundled in <style>, no scripts)
+// Both use var(--doc-*, fallback) for colors (follows the theme + works standalone). Content
+// references them via `![alt text](figures/<file>)` (png / webp / jpeg become
+// data-URI <img>s).
+//
+// Figures drawn in draw.io live in the same figures/. Two ways to place them; in both, name is
+// the stem without the extension:
+//   - <name>.drawio.svg : output of draw.io's File > Save as (Editable SVG). Carries an mxfile
+//                         copy (content=), so **one file is both editing source and output**
+//                         (open in draw.io and Save to update; no re-export needed). Error if
+//                         there's no mxfile
+//   - <name>.svg        : output of File > Export as > SVG (the editing source can live
+//                         anywhere). isDrawioSvg tells whether it's from draw.io (it coexists
+//                         with hand-written figures)
+// Both go through drawio.ts normalization (stripping prolog / mxfile copy / external links,
+// injecting title) before the same validation as hand-written SVGs. Colors stay in draw.io's
+// scheme (see the top of drawio.ts).
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { extractMxfile, isDrawioSvg, normalizeDrawioSvg } from "./drawio.js";
+import { textfilePath } from "./textfile.js";
+const EXT_RE = /\.(drawio\.svg|svg|html|png|webp|gif|mp4|webm|jpe?g)$/;
+const FILE_RE = /^[a-z0-9][a-z0-9_-]*\.(drawio\.svg|svg|html|png|webp|gif|mp4|webm|jpe?g)$/;
+const IMAGE_MIME = {
+    png: "image/png",
+    webp: "image/webp",
+    gif: "image/gif",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+};
+/** File relative to figures/ → the figure's registered name (stem without the extension). */
+export const figureName = (file) => !FILE_RE.test(file.replace(/^figures\//, ""))
+    ? `file-${createHash("sha256").update(file).digest("hex").slice(0, 24)}`
+    : file.replace(/^figures\//, "").replace(EXT_RE, "");
+/**
+ * Original file name of a figure added from the editing UI → a name following the figures/
+ * convention (svg / drawio.svg / html / raster). The stem is coerced to lowercase alphanumerics
+ * and _-, or "figure" if nothing remains. Unsupported extensions yield undefined.
+ */
+export const figureUploadName = (raw) => {
+    const lower = raw.toLowerCase().split(/[\\/]/).pop() ?? "";
+    const ext = /\.(drawio\.svg|svg|html|png|webp|gif|mp4|webm|jpe?g)$/.exec(lower)?.[1];
+    if (ext == null) {
+        return undefined;
+    }
+    const stem = lower
+        .slice(0, -ext.length - 1)
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/^[^a-z0-9]+|-+$/g, "");
+    return `${stem || "figure"}.${ext}`;
+};
+const LIGHT_VARS = "--doc-bg:#ffffff;--doc-bg-2:#f6f8fb;--doc-bg-3:#eef2f7;--doc-panel:#ffffff;--doc-panel-2:#f1f5fa;--doc-rail:#f3f6fa;--doc-border:#dde3eb;--doc-border-2:#c4ccd8;--doc-fg:#000000;--doc-fg-2:#2a3140;--doc-fg-3:#5b6271;--doc-fg-4:#9099a8;--doc-accent:#1b4994;--doc-accent-2:#0277bd;--doc-accent-fg:#ffffff;--doc-ok:#1f7a32;--doc-ok-2:#2ea043;--doc-warn:#b97600;--doc-warn-2:#f59f00;--doc-danger:#b53030;--doc-danger-2:#f04848;--doc-info:#0277bd;--doc-info-2:#4a8bff;";
+const DARK_VARS = "--doc-bg:#000000;--doc-bg-2:#0a0d12;--doc-bg-3:#11161c;--doc-panel:#161b22;--doc-panel-2:#1e2530;--doc-rail:#0d1117;--doc-border:#222831;--doc-border-2:#323a47;--doc-fg:#ffffff;--doc-fg-2:#c9d1d9;--doc-fg-3:#8b939e;--doc-fg-4:#525a66;--doc-accent:#4a8bff;--doc-accent-2:#1b4994;--doc-accent-fg:#ffffff;--doc-ok:#2ea043;--doc-ok-2:#56d364;--doc-warn:#f59f00;--doc-warn-2:#ffc14d;--doc-danger:#f04848;--doc-danger-2:#ff7a7a;--doc-info:#4a8bff;--doc-info-2:#79b0ff;";
+const FIGURE_THEME_STYLE = `<style data-doc-figure-theme>[data-doc-figure]{color-scheme:light;${LIGHT_VARS}}@media (prefers-color-scheme: dark){[data-doc-figure]{color-scheme:dark;${DARK_VARS}}}:root[data-theme="light"] [data-doc-figure],[data-doc-theme="light"] [data-doc-figure],[data-doc-figure][data-doc-theme="light"]{color-scheme:light;${LIGHT_VARS}}:root[data-theme="dark"] [data-doc-figure],[data-doc-theme="dark"] [data-doc-figure],[data-doc-figure][data-doc-theme="dark"]{color-scheme:dark;${DARK_VARS}}</style>`;
+const firstTag = (svg, tag) => {
+    const m = new RegExp(`<${tag}[^>]*>([\\s\\S]*?)</${tag}>`).exec(svg);
+    return m ? m[1]?.replace(/&lt;/g, "<").replace(/&gt;/g, ">").trim() : undefined;
+};
+const HTML_META_RE = /^<!--fig\n([\s\S]*?)-->\n?/;
+const normalizeHardcodedSurfaces = (markup) => markup
+    .replace(/background-color:\s*#fff(?:fff)?(?=[;}])/gi, "background-color:var(--doc-panel, #ffffff)")
+    .replace(/background:\s*#fff(?:fff)?(?=[;}])/gi, "background:var(--doc-panel, #ffffff)");
+const withSvgTheme = (markup) => {
+    const headEnd = markup.indexOf(">");
+    if (headEnd < 0) {
+        return markup;
+    }
+    const head = markup.slice(0, headEnd);
+    const taggedHead = head.includes("data-doc-figure") ? head : `${head} data-doc-figure=""`;
+    return `${taggedHead}>${FIGURE_THEME_STYLE}${markup.slice(headEnd + 1)}`;
+};
+const withHtmlTheme = (markup) => {
+    const themed = normalizeHardcodedSurfaces(markup);
+    if (themed.includes("data-doc-figure") || !themed.startsWith("<")) {
+        return themed;
+    }
+    // A fragment can start with <style>; keep the theme outside authored elements.
+    return `<div data-doc-figure="">${FIGURE_THEME_STYLE}${themed}</div>`;
+};
+const parseSvg = (file, raw, errors) => {
+    const markup = withSvgTheme(normalizeHardcodedSurfaces(raw.trim()));
+    if (!markup.startsWith("<svg") || !markup.endsWith("</svg>")) {
+        errors.push(`${file}: a single root <svg>…</svg> is required`);
+    }
+    const head = markup.slice(0, markup.indexOf(">"));
+    if (!head.includes("xmlns=")) {
+        errors.push(`${file}: root <svg> requires xmlns (for standalone publishing)`);
+    }
+    if (!head.includes("viewBox=")) {
+        errors.push(`${file}: root <svg> requires viewBox (to scale with the width)`);
+    }
+    return {
+        kind: "svg",
+        markup,
+        title: firstTag(markup, "title"),
+        desc: firstTag(markup, "desc"),
+    };
+};
+const parseHtml = (file, raw, errors) => {
+    const m = HTML_META_RE.exec(raw);
+    if (!m) {
+        errors.push(`${file}: a <!--fig\\ntitle: ...\\n--> meta comment is required at the top`);
+        return { kind: "html", markup: raw.trim() };
+    }
+    const meta = new Map((m[1] ?? "")
+        .split("\n")
+        .filter((l) => l.includes(":"))
+        .map((l) => [l.slice(0, l.indexOf(":")).trim(), l.slice(l.indexOf(":") + 1).trim()]));
+    const markup = withHtmlTheme(raw.slice(m[0].length).trim());
+    if (!meta.get("title")) {
+        errors.push(`${file}: the meta comment requires title:`);
+    }
+    if (!markup.startsWith("<")) {
+        errors.push(`${file}: the meta comment must be followed by an HTML fragment`);
+    }
+    if (/<script/i.test(markup)) {
+        errors.push(`${file}: <script> is not allowed (self-contained static fragments only)`);
+    }
+    return { kind: "html", markup, title: meta.get("title"), desc: meta.get("desc") };
+};
+export const loadFigures = (figuresDir, extraFiles = []) => {
+    const errors = [];
+    const figures = [];
+    let files = [];
+    try {
+        files = readdirSync(figuresDir)
+            .filter((f) => /\.(svg|html|png|webp|gif|mp4|webm|jpe?g)$/.test(f))
+            .sort();
+    }
+    catch {
+        // A missing figures/ is valid.
+    }
+    files = [...new Set([...files.map((file) => `figures/${file}`), ...extraFiles])];
+    const keyframeOwner = new Map();
+    for (const file of files) {
+        if (file.startsWith("figures/") &&
+            !file.slice(8).includes("/") &&
+            !FILE_RE.test(file.slice(8))) {
+            errors.push(`${file}: file name must be <name>.svg|.drawio.svg|.html|.png|.webp|.jpg|.jpeg ([a-z0-9_-])`);
+            continue;
+        }
+        const name = figureName(file);
+        const dup = figures.find((f) => f.name === name);
+        if (dup) {
+            errors.push(`${file}: duplicate name "${name}" (also used by ${dup.file})`);
+            continue;
+        }
+        if (/\.(mp4|webm)$/.test(file)) {
+            const data = readFileSync(file.startsWith("figures/")
+                ? textfilePath(figuresDir, file.slice(8))
+                : textfilePath(dirname(figuresDir), file));
+            figures.push({
+                name,
+                file,
+                kind: "video",
+                markup: `<video data-dooc-video controls playsinline preload="metadata" aria-label="Video preview" src="data:video/${file.endsWith(".mp4") ? "mp4" : "webm"};base64,${data.toString("base64")}"></video>`,
+            });
+            continue;
+        }
+        const mime = IMAGE_MIME[file.slice(file.lastIndexOf(".") + 1)];
+        if (mime != null) {
+            // Rasters are inlined as data URIs; Markdown embeds supply their alternative text.
+            const data = readFileSync(file.startsWith("figures/")
+                ? textfilePath(figuresDir, file.slice(8))
+                : textfilePath(dirname(figuresDir), file)).toString("base64");
+            figures.push({
+                name,
+                file,
+                kind: "image",
+                markup: `<img src="data:${mime};base64,${data}" alt="${name}">`,
+            });
+            continue;
+        }
+        const raw = readFileSync(file.startsWith("figures/")
+            ? textfilePath(figuresDir, file.slice(8))
+            : textfilePath(dirname(figuresDir), file), "utf8");
+        // The point of .drawio.svg is "can be reopened in draw.io", so the mxfile copy is required
+        // (rejects an Export as > SVG output without the copy that was merely renamed).
+        const editable = file.endsWith(".drawio.svg");
+        if (editable && !extractMxfile(raw)) {
+            errors.push(`${file}: .drawio.svg doubles as the editable source, so it requires a copy of the mxfile (content=) (save it as .drawio.svg via File > Save as in draw.io)`);
+        }
+        const parsed = file.endsWith(".svg")
+            ? parseSvg(file, editable || isDrawioSvg(raw) ? normalizeDrawioSvg(name, raw).markup : raw, errors)
+            : parseHtml(file, raw, errors);
+        if (/var\(--doc-[a-z0-9-]+\)/.test(parsed.markup)) {
+            errors.push(`${file}: contains var(--doc-*) without a fallback (use the var(--doc-x, #hex) form)`);
+        }
+        // @keyframes names must not collide when several figures are inlined on one page.
+        // The same name with an identical body is harmless (e.g. xyflow's dashdraw, present in
+        // every capture figure), so that's allowed.
+        for (const km of parsed.markup.matchAll(/@keyframes\s+([A-Za-z0-9_-]+)\s*\{/g)) {
+            const kname = km[1] ?? "";
+            let depth = 1;
+            let i = (km.index ?? 0) + km[0].length;
+            while (i < parsed.markup.length && depth > 0) {
+                const ch = parsed.markup[i];
+                depth += ch === "{" ? 1 : ch === "}" ? -1 : 0;
+                i += 1;
+            }
+            const body = parsed.markup.slice((km.index ?? 0) + km[0].length, i).replace(/\s+/g, "");
+            const key = `${kname}`;
+            const owner = keyframeOwner.get(key);
+            if (owner && owner.file !== file && owner.body !== body) {
+                errors.push(`${file}: @keyframes "${kname}" conflicts with a different definition in ${owner.file}`);
+            }
+            keyframeOwner.set(key, { file, body });
+        }
+        figures.push({
+            name,
+            file,
+            ...parsed,
+        });
+    }
+    return { figures, errors };
+};