@dooc-dev/dooc 0.0.0-stage → 0.0.2

package/dist/core/content-metadata.js

@@ -0,0 +1,264 @@
+// The content/ contract. Doc bodies sit flat in content/<id>.md, and only dooc.yaml
+// holds the hierarchy and order (docs themselves have no root / child distinction; any doc can
+// have children). id = the file name stem is the resolution key for URLs / file links and is
+// unique site-wide. YAML reading/writing lives in compiler/manifest.ts; this file only does
+// browser-safe tree validation and manipulation.
+import { docFile, localFile, parseFileLayout } from "./files.js";
+import { contentLanguageCode, DEFAULT_LANG, isLangTag } from "./language.js";
+export const MANIFEST_FILE = "dooc.yaml";
+export const DOC_ID_RE = /^[a-z0-9][a-z0-9-]*$/;
+export const isDocId = (s) => DOC_ID_RE.test(s);
+/** Doc file name directly under content/ (`<id>.md`) → id. undefined if the shape differs. */
+export const docIdOfFile = (name) => {
+    const id = name.endsWith(".md") ? name.slice(0, -3) : "";
+    return isDocId(id) ? id : undefined;
+};
+/**
+ * Turn the parsed dooc.yaml (YAML → JS value) into a tree. Each element is `id` (no
+ * children) or `{ id: [children...] }` (a single-key map; a null value also means no children).
+ * Validates id shape and duplicates.
+ */
+export const parseManifest = (value) => {
+    const errors = [];
+    let title;
+    let icon;
+    let defaultLang;
+    let files;
+    let languages;
+    let themes;
+    if (value != null && typeof value === "object" && !Array.isArray(value)) {
+        const manifest = value;
+        for (const key of Object.keys(manifest))
+            if (key !== "title" &&
+                key !== "icon" &&
+                key !== "defaultLang" &&
+                key !== "docs" &&
+                key !== "files" &&
+                key !== "languages" &&
+                key !== "themes")
+                errors.push(`${MANIFEST_FILE}: unknown field "${key}"`);
+        if (manifest.title !== undefined) {
+            if (typeof manifest.title !== "string" || !manifest.title.trim())
+                errors.push(`${MANIFEST_FILE}: title must be a non-empty string`);
+            else
+                title = manifest.title.trim();
+        }
+        if (manifest.icon !== undefined) {
+            if (typeof manifest.icon !== "string" ||
+                !localFile(manifest.icon.trim()) ||
+                !manifest.icon.trim().endsWith(".svg"))
+                errors.push(`${MANIFEST_FILE}: icon must be a local .svg file`);
+            else
+                icon = manifest.icon.trim();
+        }
+        if (manifest.defaultLang !== undefined) {
+            if (typeof manifest.defaultLang !== "string" || !isLangTag(manifest.defaultLang))
+                errors.push(`${MANIFEST_FILE}: defaultLang must be a BCP 47 language tag`);
+            else
+                defaultLang = manifest.defaultLang;
+        }
+        if (manifest.files !== undefined) {
+            try {
+                files = parseFileLayout(manifest.files);
+            }
+            catch (error) {
+                errors.push(`${MANIFEST_FILE}: ${error instanceof Error ? error.message : error}`);
+            }
+        }
+        if (manifest.languages !== undefined) {
+            try {
+                if (!Array.isArray(manifest.languages) ||
+                    !manifest.languages.length ||
+                    manifest.languages.some((tag) => typeof tag !== "string" || !isLangTag(tag)))
+                    throw new Error("languages must be a non-empty list of language tags");
+                languages = manifest.languages.map(contentLanguageCode);
+                if (new Set(languages).size !== languages.length)
+                    throw new Error("languages must contain distinct languages after normalization");
+                if (!languages.includes(contentLanguageCode(defaultLang ?? DEFAULT_LANG)))
+                    throw new Error("languages must include defaultLang");
+            }
+            catch (error) {
+                errors.push(`${MANIFEST_FILE}: ${error instanceof Error ? error.message : error}`);
+            }
+        }
+        if (manifest.themes !== undefined) {
+            if (!Array.isArray(manifest.themes) ||
+                !manifest.themes.length ||
+                manifest.themes.some((theme) => theme !== "light" && theme !== "dark") ||
+                new Set(manifest.themes).size !== manifest.themes.length)
+                errors.push(`${MANIFEST_FILE}: themes must be a non-empty list of distinct light / dark themes supported by the viewer`);
+            else
+                themes = manifest.themes;
+        }
+        if (!Array.isArray(manifest.docs))
+            errors.push(`${MANIFEST_FILE}: docs must be a list`);
+        value = manifest.docs;
+    }
+    const seen = new Set();
+    const walk = (v, path) => {
+        if (v == null) {
+            return [];
+        }
+        if (!Array.isArray(v)) {
+            errors.push(`${MANIFEST_FILE}: ${path} must be a list`);
+            return [];
+        }
+        const nodes = [];
+        for (const [i, item] of v.entries()) {
+            const at = `${path}[${i}]`;
+            let id;
+            let children;
+            if (typeof item === "string") {
+                id = item;
+            }
+            else if (typeof item === "object" &&
+                item != null &&
+                !Array.isArray(item) &&
+                Object.keys(item).length === 1) {
+                [id, children] = Object.entries(item)[0] ?? [];
+            }
+            else {
+                errors.push(`${MANIFEST_FILE}: ${at} must be "id" or "id: [children...]"`);
+                continue;
+            }
+            if (typeof id !== "string" || !isDocId(id)) {
+                errors.push(`${MANIFEST_FILE}: ${at} id "${String(id)}" must be lowercase alphanumerics and hyphens`);
+                continue;
+            }
+            if (seen.has(id)) {
+                errors.push(`${MANIFEST_FILE}: duplicate id "${id}"`);
+                continue;
+            }
+            seen.add(id);
+            nodes.push({ id, children: walk(children, `${at}.${id}`) });
+        }
+        return nodes;
+    };
+    const tree = walk(value, "root");
+    if (files) {
+        for (const id of [...Object.keys(files.documents), ...Object.keys(files.icons ?? {})])
+            if (!seen.has(id))
+                errors.push(`${MANIFEST_FILE}: files references unknown document "${id}"`);
+        const paths = [...seen].map((id) => docFile(id, files));
+        if (new Set(paths).size !== paths.length)
+            errors.push(`${MANIFEST_FILE}: documents must use distinct files`);
+    }
+    return {
+        tree,
+        ...(title === undefined ? {} : { title }),
+        ...(icon === undefined ? {} : { icon }),
+        ...(defaultLang === undefined ? {} : { defaultLang }),
+        ...(files === undefined ? {} : { files }),
+        ...(languages === undefined ? {} : { languages }),
+        ...(themes === undefined ? {} : { themes }),
+        errors,
+    };
+};
+/** Tree → dooc.yaml text (serialized in the hand-written shape, keeping git diffs clean). */
+export const serializeManifest = (tree, { title, icon, defaultLang, files, languages, themes, } = {}) => {
+    const write = (nodes, indent) => nodes.flatMap((n) => n.children.length > 0
+        ? [`${indent}- ${n.id}:`, ...write(n.children, `${indent}    `)]
+        : [`${indent}- ${n.id}`]);
+    if (title !== undefined ||
+        icon !== undefined ||
+        defaultLang !== undefined ||
+        files !== undefined ||
+        languages !== undefined ||
+        themes !== undefined) {
+        const lines = write(tree, "  ");
+        const metadata = `${title === undefined ? "" : `title: ${JSON.stringify(title)}\n`}${icon === undefined ? "" : `icon: ${JSON.stringify(icon)}\n`}${defaultLang === undefined ? "" : `defaultLang: ${JSON.stringify(defaultLang)}\n`}`;
+        return `${metadata}${files ? `files: ${JSON.stringify(files)}\n` : ""}${languages ? `languages: ${JSON.stringify(languages)}\n` : ""}${themes ? `themes: ${JSON.stringify(themes)}\n` : ""}docs:${lines.length ? `\n${lines.join("\n")}\n` : " []\n"}`;
+    }
+    const lines = write(tree, "");
+    return `# Doc hierarchy and order (each id = content/<id>.md)\n${lines.join("\n")}${lines.length > 0 ? "\n" : ""}`;
+};
+/** Flatten the tree into display order (pre-order). parent omitted = top level. */
+export const flattenTree = (tree) => {
+    const out = [];
+    const walk = (nodes, parent, depth) => {
+        for (const n of nodes) {
+            out.push(parent == null ? { id: n.id, depth } : { id: n.id, parent, depth });
+            walk(n.children, n.id, depth + 1);
+        }
+    };
+    walk(tree, undefined, 0);
+    return out;
+};
+const clone = (tree) => tree.map((n) => ({ id: n.id, children: clone(n.children) }));
+const findNode = (tree, id) => {
+    for (const n of tree) {
+        if (n.id === id) {
+            return n;
+        }
+        const hit = findNode(n.children, id);
+        if (hit) {
+            return hit;
+        }
+    }
+    return undefined;
+};
+/** Detach the node with this id (along with its children). Returns the detached node. */
+const detach = (tree, id) => {
+    const i = tree.findIndex((n) => n.id === id);
+    if (i !== -1) {
+        return tree.splice(i, 1)[0];
+    }
+    for (const n of tree) {
+        const hit = detach(n.children, id);
+        if (hit) {
+            return hit;
+        }
+    }
+    return undefined;
+};
+/** Child list of parent (omitted = top level). undefined if parent doesn't exist. */
+const childList = (tree, parent) => parent == null ? tree : findNode(tree, parent)?.children;
+/** Append a new doc to the end of parent's children. Duplicate id / missing parent → undefined. */
+export const insertDoc = (tree, id, parent) => {
+    const next = clone(tree);
+    const list = childList(next, parent);
+    if (!list || findNode(next, id)) {
+        return undefined;
+    }
+    list.push({ id, children: [] });
+    return next;
+};
+/**
+ * Move a doc (with its children) to position index under parent. It can't be moved under
+ * itself or its own descendants (that would create a cycle). An invalid move returns undefined
+ * (no partial update).
+ */
+export const moveDoc = (tree, id, parent, index) => {
+    const node = findNode(tree, id);
+    if (!node || (parent != null && (parent === id || findNode(node.children, parent)))) {
+        return undefined;
+    }
+    const next = clone(tree);
+    const moved = detach(next, id);
+    const list = childList(next, parent);
+    if (!moved || !list || !Number.isInteger(index) || index < 0 || index > list.length) {
+        return undefined;
+    }
+    list.splice(index, 0, moved);
+    return next;
+};
+/** Remove a doc. Docs with children are not removed (we don't decide where the children go). */
+export const removeDoc = (tree, id) => {
+    const node = findNode(tree, id);
+    if (!node || node.children.length > 0) {
+        return undefined;
+    }
+    const next = clone(tree);
+    detach(next, id);
+    return next;
+};
+/** Change a doc's id (position and children stay as they are). */
+export const renameDoc = (tree, oldId, newId) => {
+    const next = clone(tree);
+    const node = findNode(next, oldId);
+    if (!node || findNode(next, newId)) {
+        return undefined;
+    }
+    node.id = newId;
+    return next;
+};

package/dist/core/content-types.d.ts

@@ -0,0 +1,45 @@
+import type { Block, TocEntry } from "./blocks.js";
+import type { Frontmatter } from "./taxonomy.js";
+export interface TermEntry {
+    /** Root-relative .termth path, or a document position for an inline definition. */
+    id: string;
+    name: string;
+    description?: string;
+    /** Definition text (plain text). */
+    definition: string;
+}
+export interface FigureEntry {
+    name: string;
+    file: string;
+    kind: "svg" | "html" | "image" | "video";
+    /**
+     * Full figure content (SVG / HTML fragment / <img> data URI for rasters). Consumers render it
+     * inline; MCP can pass it as text.
+     */
+    markup: string;
+    /** By convention "Fig.<name>" (svg = <title>, html = `title:` in the meta comment). */
+    title?: string;
+    /** Figure description (used both for the displayed caption and as an explanation for LLMs). */
+    desc?: string;
+}
+export type CompiledDoc = Frontmatter & {
+    id: string;
+    /** Parent doc id (SoT: dooc.yaml). Omitted = top level. docs[] is in pre-order. */
+    parent?: string;
+    /** `content/<id>.md`. */
+    file: string;
+    /** Resolved language (BCP 47): front-matter `lang`, else the site default (language.ts). */
+    lang: string;
+    /** Sidebar icon (full content of icons/<id>.svg, 1:1). Omitted if there is none. */
+    icon?: string;
+    /** Source md (excluding front-matter). For MCP / copy; rendering uses blocks. */
+    body: string;
+    /** Normalized Block AST (the blocks.ts contract). Consumers just map it to rendering. */
+    blocks: Block[];
+    toc: TocEntry[];
+    /** Referenced figures and terms. */
+    refs: {
+        figures: string[];
+        terms: string[];
+    };
+};

package/dist/core/content-types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/extension-package.d.ts

@@ -0,0 +1,34 @@
+export declare const MAX_EXTENSION_BYTES: number;
+export declare const MAX_EXTENSION_FILES = 256;
+export interface ExtensionFile {
+    name: string;
+    data: Uint8Array;
+}
+export interface ExtensionPackage {
+    name: string;
+    version: string;
+    main: string;
+    icon?: {
+        light: string;
+        dark?: string;
+    };
+    files: ExtensionFile[];
+}
+export interface ExtensionSummary {
+    file: string;
+    name: string;
+    version: string;
+    hash: string;
+    size: number;
+    enabled: boolean;
+    plugins: string[];
+    icon?: ExtensionPackage["icon"];
+    error?: string;
+    readonly?: boolean;
+}
+export declare const extensionFile: (value: unknown) => string;
+export declare const extensionPath: (value: string) => boolean;
+export declare const extensionCrc: (data: Uint8Array) => number;
+export declare const extensionManifest: (files: ExtensionFile[]) => ExtensionPackage;
+/** Read bounded, single-disk ZIPs without extracting paths supplied by the archive. */
+export declare const readExtensionZip: (bytes: Uint8Array, inflate: (data: Uint8Array, size: number) => Promise<Uint8Array>) => Promise<ExtensionPackage>;

package/dist/core/extension-package.js

@@ -0,0 +1,147 @@
+export const MAX_EXTENSION_BYTES = 16 * 1024 * 1024;
+export const MAX_EXTENSION_FILES = 256;
+export const extensionFile = (value) => {
+    if (typeof value !== "string" || !/^[\w][\w. -]{0,119}\.zip$/.test(value))
+        throw new Error("Choose a plugin ZIP file");
+    return value;
+};
+export const extensionPath = (value) => !!value &&
+    value.length <= 240 &&
+    !/[\\:]/.test(value) &&
+    [...value].every((char) => char.charCodeAt(0) >= 32 && char.charCodeAt(0) !== 127) &&
+    value
+        .split("/")
+        .every((part) => !!part &&
+        part !== "." &&
+        part !== ".." &&
+        !part.endsWith(".") &&
+        !part.endsWith(" "));
+const table = new Uint32Array(256).map((_, value) => {
+    let crc = value;
+    for (let bit = 0; bit < 8; bit++)
+        crc = (crc >>> 1) ^ (crc & 1 ? 0xedb88320 : 0);
+    return crc >>> 0;
+});
+export const extensionCrc = (data) => {
+    let crc = 0xffffffff;
+    for (const byte of data)
+        crc = (crc >>> 8) ^ (table[(crc ^ byte) & 255] ?? 0);
+    return (crc ^ 0xffffffff) >>> 0;
+};
+export const extensionManifest = (files) => {
+    const entry = files.find((file) => file.name === "package.json");
+    if (!entry || entry.data.length > 65536)
+        throw new Error("The ZIP needs package.json at its root");
+    const manifest = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(entry.data));
+    if (!manifest ||
+        typeof manifest.name !== "string" ||
+        !/^(?:@[\w.-]+\/)?[\w.-]{1,100}$/.test(manifest.name) ||
+        typeof manifest.version !== "string" ||
+        !/^\d+\.\d+\.\d+(?:-[\w.-]+)?(?:\+[\w.-]+)?$/.test(manifest.version) ||
+        manifest.type !== "module" ||
+        typeof manifest.main !== "string" ||
+        !extensionPath(manifest.main) ||
+        !/\.m?js$/.test(manifest.main) ||
+        !files.some((file) => file.name === manifest.main))
+        throw new Error("package.json needs name, version, type: module and a bundled JavaScript main");
+    if (manifest.dependencies && Object.keys(manifest.dependencies).length)
+        throw new Error("Bundle dependencies into the JavaScript entry before packaging");
+    let icon;
+    if (manifest.icon !== undefined) {
+        const asset = files.find((file) => file.name === manifest.icon);
+        if (typeof manifest.icon !== "string" ||
+            !extensionPath(manifest.icon) ||
+            !manifest.icon.endsWith(".svg") ||
+            !asset ||
+            !asset.data.length ||
+            asset.data.length > 65536)
+            throw new Error("package.json icon must reference an SVG asset up to 64 KiB");
+        icon = {
+            light: `data:image/svg+xml;base64,${btoa(Array.from(asset.data, (byte) => String.fromCharCode(byte)).join(""))}`,
+        };
+    }
+    return { name: manifest.name, version: manifest.version, main: manifest.main, files, icon };
+};
+/** Read bounded, single-disk ZIPs without extracting paths supplied by the archive. */
+export const readExtensionZip = async (bytes, inflate) => {
+    const invalid = () => new Error("Invalid or unsupported plugin ZIP");
+    if (bytes.length < 22 || bytes.length > MAX_EXTENSION_BYTES)
+        throw invalid();
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    let end = bytes.length - 22;
+    while (end >= Math.max(0, bytes.length - 65557) &&
+        (view.getUint32(end, true) !== 0x06054b50 ||
+            end + 22 + view.getUint16(end + 20, true) !== bytes.length))
+        end--;
+    if (end < Math.max(0, bytes.length - 65557) ||
+        view.getUint16(end + 4, true) ||
+        view.getUint16(end + 6, true))
+        throw invalid();
+    const count = view.getUint16(end + 10, true);
+    const directory = view.getUint32(end + 16, true);
+    if (!count ||
+        count > MAX_EXTENSION_FILES ||
+        view.getUint16(end + 8, true) !== count ||
+        directory + view.getUint32(end + 12, true) !== end)
+        throw invalid();
+    const files = [];
+    const names = new Set();
+    const ranges = [];
+    let at = directory, total = 0;
+    for (let index = 0; index < count; index++) {
+        if (at + 46 > end || view.getUint32(at, true) !== 0x02014b50)
+            throw invalid();
+        const flags = view.getUint16(at + 8, true), method = view.getUint16(at + 10, true);
+        const compressed = view.getUint32(at + 20, true), size = view.getUint32(at + 24, true);
+        const length = view.getUint16(at + 28, true), extra = view.getUint16(at + 30, true), comment = view.getUint16(at + 32, true);
+        const offset = view.getUint32(at + 42, true), type = (view.getUint32(at + 38, true) >>> 16) & 0xf000;
+        total += size;
+        if (flags & ~0x080e ||
+            ![0, 8].includes(method) ||
+            (method === 0 && size !== compressed) ||
+            total > MAX_EXTENSION_BYTES ||
+            at + 46 + length + extra + comment > end ||
+            offset + 30 > directory ||
+            view.getUint16(at + 34, true) ||
+            ![0, 0x8000, 0x4000].includes(type))
+            throw invalid();
+        const name = new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(at + 46, at + 46 + length));
+        const folder = name.endsWith("/");
+        const path = folder ? name.slice(0, -1) : name;
+        const key = path.normalize("NFC").toLowerCase();
+        if (!extensionPath(path) ||
+            names.has(key) ||
+            (folder && size !== 0) ||
+            (!folder && type === 0x4000))
+            throw invalid();
+        names.add(key);
+        if (view.getUint32(offset, true) !== 0x04034b50 ||
+            view.getUint16(offset + 6, true) !== flags ||
+            view.getUint16(offset + 8, true) !== method)
+            throw invalid();
+        const localName = view.getUint16(offset + 26, true), localExtra = view.getUint16(offset + 28, true);
+        const start = offset + 30 + localName + localExtra;
+        if (start + compressed > directory ||
+            new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(offset + 30, offset + 30 + localName)) !== name)
+            throw invalid();
+        if (ranges.some(([from, to]) => offset < to && start + compressed > from))
+            throw invalid();
+        ranges.push([offset, start + compressed]);
+        const input = bytes.subarray(start, start + compressed);
+        const data = method === 0 ? input.slice() : await inflate(input, size);
+        if (data.length !== size || extensionCrc(data) !== view.getUint32(at + 16, true))
+            throw invalid();
+        if (!folder)
+            files.push({ name, data });
+        at += 46 + length + extra + comment;
+    }
+    if (at !== end)
+        throw invalid();
+    for (const file of files)
+        if (files.some((other) => file.name
+            .normalize("NFC")
+            .toLowerCase()
+            .startsWith(`${other.name.normalize("NFC").toLowerCase()}/`)))
+            throw invalid();
+    return extensionManifest(files);
+};

package/dist/core/figure-frame.d.ts

@@ -0,0 +1,12 @@
+import type { FigureEntry } from "./content-types.js";
+export type FigureTheme = "auto" | "light" | "dark";
+export declare const figureSrcdoc: (fig: FigureEntry, theme?: FigureTheme) => string;
+/** One figure → an isolated iframe (rasters stay as <img>). */
+export declare const figureFrameHtml: (fig: FigureEntry, cls?: string, label?: string) => string;
+/**
+ * Parent side of figure iframes: theme following (rewrites the srcdoc's data-doc-theme when
+ * <html data-theme> or the OS setting changes) and applying html figure heights. Also works for
+ * iframes inserted later (e.g. when edit swaps out the main content). Self-contained (it is
+ * stringified with toString and embedded in the page) — do not reference outside identifiers.
+ */
+export declare function mountFigureFrames(doc: Document): void;

package/dist/core/figure-frame.js

@@ -0,0 +1,108 @@
+const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+const BASE_STYLE = "<style>html,body{margin:0;padding:0;height:100%;background:transparent;overflow:hidden}" +
+    'html{color-scheme:light dark}html[data-doc-theme="light"]{color-scheme:light}html[data-doc-theme="dark"]{color-scheme:dark}' +
+    'body{font:14px/1.6 system-ui,-apple-system,"Segoe UI","Noto Sans JP",sans-serif}' +
+    "body>svg{display:block;width:100%;height:100%}</style>";
+// html figures only: report the content height to the parent (the parent finds its own iframe
+// via event.source).
+const HEIGHT_SCRIPT = '<script>(()=>{const s=()=>parent.postMessage({docFigureHeight:Math.ceil(document.body.scrollHeight)},"*");' +
+    'document.documentElement.style.height="auto";document.body.style.height="auto";' +
+    "new ResizeObserver(s).observe(document.body);s();})()</script>";
+export const figureSrcdoc = (fig, theme = "auto") => `<!doctype html><html data-doc-theme="${theme}"><head><meta charset="utf-8">${BASE_STYLE}</head><body>${fig.markup}${fig.kind === "html" ? HEIGHT_SCRIPT : ""}</body></html>`;
+/**
+ * Display width of the svg root (width attribute, or the viewBox width if absent) and its aspect
+ * ratio. undefined if they can't be read.
+ */
+const svgBox = (markup) => {
+    const root = /<svg\b[^>]*>/i.exec(markup)?.[0] ?? "";
+    const attr = (n) => new RegExp(`\\s${n}\\s*=\\s*["']([^"']*)["']`, "i").exec(root)?.[1];
+    const vb = attr("viewBox")
+        ?.trim()
+        .split(/[\s,]+/)
+        .map(Number);
+    const [w, h] = vb && vb.length === 4
+        ? [vb[2], vb[3]]
+        : [Number.parseFloat(attr("width") ?? ""), Number.parseFloat(attr("height") ?? "")];
+    if (!w || !h || !(w > 0) || !(h > 0)) {
+        return undefined;
+    }
+    const px = Number.parseFloat(attr("width") ?? "");
+    return { width: px > 0 && !/%/.test(attr("width") ?? "") ? px : w, w, h };
+};
+/** One figure → an isolated iframe (rasters stay as <img>). */
+export const figureFrameHtml = (fig, cls = "fig-frame", label) => {
+    if (fig.kind === "video")
+        return label
+            ? fig.markup.replace(/\baria-label="[^"]*"/, () => `aria-label="${esc(label)}"`)
+            : fig.markup;
+    if (fig.kind === "image") {
+        return label === undefined
+            ? fig.markup
+            : fig.markup.replace(/\balt="[^"]*"/, () => `alt="${esc(label)}"`);
+    }
+    const box = fig.kind === "svg" ? svgBox(fig.markup) : undefined;
+    const style = box
+        ? `width:${box.width}px;aspect-ratio:${box.w} / ${box.h}`
+        : fig.kind === "svg"
+            ? "width:100%;height:240px"
+            : "width:100%;height:120px";
+    return `<iframe class="${cls}" data-doc-figure-frame="${fig.kind}" sandbox="${fig.kind === "html" ? "allow-scripts" : ""}" scrolling="no" loading="lazy" title="${esc(label || fig.title || `Fig.${fig.name}`)}" style="${style}" srcdoc="${esc(figureSrcdoc(fig))}"></iframe>`;
+};
+/**
+ * Parent side of figure iframes: theme following (rewrites the srcdoc's data-doc-theme when
+ * <html data-theme> or the OS setting changes) and applying html figure heights. Also works for
+ * iframes inserted later (e.g. when edit swaps out the main content). Self-contained (it is
+ * stringified with toString and embedded in the page) — do not reference outside identifiers.
+ */
+export function mountFigureFrames(doc) {
+    const SEL = "iframe[data-doc-figure-frame]";
+    const media = window.matchMedia("(prefers-color-scheme: dark)");
+    const theme = (element) => {
+        const t = element.closest("[data-theme]")?.dataset.theme ??
+            doc.documentElement.dataset.theme;
+        return t === "light" || t === "dark" ? t : media.matches ? "dark" : "light";
+    };
+    const apply = (f) => {
+        const src = f.getAttribute("srcdoc") ?? "";
+        const next = src.replace(/^(<!doctype html><html data-doc-theme=")[a-z]+"/, `$1${theme(f)}"`);
+        if (next !== src) {
+            f.setAttribute("srcdoc", next);
+        }
+    };
+    const all = () => {
+        for (const f of doc.querySelectorAll(SEL))
+            apply(f);
+    };
+    new MutationObserver((records) => {
+        for (const r of records) {
+            if (r.type === "attributes") {
+                all();
+                return;
+            }
+            for (const n of r.addedNodes) {
+                if (!(n instanceof Element))
+                    continue;
+                if (n.matches(SEL))
+                    apply(n);
+                for (const f of n.querySelectorAll(SEL))
+                    apply(f);
+            }
+        }
+    }).observe(doc.documentElement, {
+        attributes: true,
+        attributeFilter: ["data-theme"],
+        childList: true,
+        subtree: true,
+    });
+    media.addEventListener("change", all);
+    window.addEventListener("message", (ev) => {
+        const h = ev.data?.docFigureHeight;
+        if (typeof h !== "number")
+            return;
+        for (const f of doc.querySelectorAll(`${SEL}[data-doc-figure-frame="html"]`)) {
+            if (f.contentWindow === ev.source)
+                f.style.height = `${h}px`;
+        }
+    });
+    all();
+}

package/dist/core/file-embed.d.ts

@@ -0,0 +1,13 @@
+import { type PreviewSettings } from "./previewers.js";
+/** Local visual links share the same asset catalog as image embeds. */
+export declare const parseFigureLink: (source: string) => {
+    file: string;
+    fragment: string;
+} | undefined;
+/** Line fragments show source code; visual assets use the existing figures/ catalog. */
+export declare const parseFileEmbed: (source: string, settings?: PreviewSettings) => {
+    file: string;
+    range?: string;
+    tableMode?: "header";
+    kind: "textfile" | "figure" | "html" | "external";
+};

package/dist/core/file-embed.js

@@ -0,0 +1,43 @@
+import { localFile } from "./files.js";
+import { resolvePreviewer } from "./previewers.js";
+import { parseFileReference } from "./textfile.js";
+/** Local visual links share the same asset catalog as image embeds. */
+export const parseFigureLink = (source) => {
+    if (/^(?:[a-z][a-z\d+.-]*:|\/)/i.test(source))
+        return undefined;
+    const path = decodeURIComponent(source.split(/[?#]/)[0] ?? "");
+    if (!/\.(svg|html|png|webp|gif|mp4|webm|jpe?g)$/.test(path))
+        return undefined;
+    const ref = parseFileReference(source);
+    const file = ref.file.replace(/^(\.\/)+/, "");
+    if (!localFile(file))
+        throw new Error("Figure links require a file inside the docs root");
+    return { file, fragment: ref.range?.slice(1) ?? "" };
+};
+/** Line fragments show source code; visual assets use the existing figures/ catalog. */
+export const parseFileEmbed = (source, settings) => {
+    if (/^https?:\/\//i.test(source)) {
+        const url = new URL(source);
+        if (url.username || url.password)
+            throw new Error("Embed URLs must not contain credentials");
+        return { file: source, kind: "external" };
+    }
+    const ref = parseFileReference(source);
+    const previewer = resolvePreviewer(source, settings);
+    if (ref.range === "#H") {
+        if (previewer !== "table")
+            throw new Error("#H requires a CSV or TSV file");
+        return {
+            file: ref.file,
+            tableMode: "header",
+            kind: "textfile",
+        };
+    }
+    if (ref.range !== undefined ||
+        (previewer !== "image" && previewer !== "html" && previewer !== "video"))
+        return { ...ref, kind: "textfile" };
+    const file = ref.file.replace(/^(\.\/)+/, "");
+    if (!localFile(file))
+        throw new Error("Image and HTML previews require a local file inside the docs root");
+    return { file, kind: previewer === "html" ? "html" : "figure" };
+};