@dooc-dev/dooc 0.0.0-stage → 0.0.1

package/dist/core/html.js

@@ -0,0 +1,444 @@
+// Normalized Block AST → HTML (renderer for the local preview). The preview goes through the same
+// "just map blocks + inline segments to output" pipeline as consumers (= prevents rendering
+// semantics from drifting). Headings and body text share the same weight (headings are also
+// font-weight 400).
+import { figureFrameHtml } from "./figure-frame.js";
+import { parseFigureLink } from "./file-embed.js";
+import { GRAPH_LAYOUT_MARGIN, GRAPH_LEGEND, graphUid, layoutGraph, } from "./graph.js";
+import { CHECK_ICON } from "./icons.js";
+import { inlineSegmenter, termMap } from "./inline.js";
+import { termComparator } from "./language.js";
+import { parseDocLink } from "./routing.js";
+import { layoutSchemaGraph, SCHEMA_LAYOUT_MARGIN, schemaGraphClientData, schemaGraphUid, } from "./schema-graph.js";
+import { docDisplayName } from "./taxonomy.js";
+import { termAnchor } from "./term-reference.js";
+import { textfileName } from "./textfile.js";
+export const emptyCtx = { figures: new Map(), terms: [] };
+export const escapeHtml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+// File links open their resource page; SVGs and terms also have hover previews.
+const segmentsHtml = (text, ctx, seg) => inlineHtml(seg(text), ctx);
+const inlineHtml = (segments, ctx) => segments
+    .map((s) => {
+    switch (s.kind) {
+        case "text":
+            return escapeHtml(s.text);
+        case "code":
+            return `<code>${escapeHtml(s.text)}</code>`;
+        case "strong":
+            return `<strong>${inlineHtml(s.children, ctx)}</strong>`;
+        case "emphasis":
+            return `<em>${inlineHtml(s.children, ctx)}</em>`;
+        case "link": {
+            const label = s.children ? inlineHtml(s.children, ctx) : escapeHtml(s.text);
+            let href = s.url;
+            try {
+                const ref = parseDocLink(s.url);
+                const target = ref && ctx.docLinks?.get(ref.file);
+                if (target && ref)
+                    href =
+                        target +
+                            (ref.fragment ? `#${encodeURIComponent(ref.fragment)}` : "");
+                const figureRef = parseFigureLink(s.url);
+                const fig = figureRef &&
+                    [...ctx.figures.values()].find((fig) => fig.file === figureRef.file);
+                if (fig && figureRef) {
+                    href =
+                        `/_files/file/${encodeURIComponent(fig.file)}` +
+                            (figureRef.fragment
+                                ? `#${encodeURIComponent(figureRef.fragment)}`
+                                : "");
+                    const pop = fig.kind === "svg"
+                        ? `<span class="figpop">${figureFrameHtml(fig, "fig-frame figpop-frame")}</span>`
+                        : "";
+                    return `<a class="figref" href="${escapeHtml(href)}">${label}${pop}</a>`;
+                }
+            }
+            catch {
+                /* Invalid drafts retain their source link; validation reports the error. */
+            }
+            return `<a href="${escapeHtml(href)}">${label}</a>`;
+        }
+        case "term": {
+            const label = s.children ? inlineHtml(s.children, ctx) : escapeHtml(s.text);
+            const entry = termMap(ctx.terms).get(s.id);
+            if (!entry)
+                return label;
+            const href = ctx.termLinks?.get(s.id) ??
+                `/_files/terms#${encodeURIComponent(termAnchor(s.id))}`;
+            return `<a class="dictref" href="${escapeHtml(href)}">${label}<span class="dictpop">${escapeHtml(entry.definition)}${entry.description ? `<span class="dictpop-description">${escapeHtml(entry.description)}</span>` : ""}</span></a>`;
+        }
+        default:
+            return "";
+    }
+})
+    .join("");
+const listHtml = (items, ctx, seg, ordered = false) => {
+    const tag = ordered ? "ol" : "ul";
+    const lis = items
+        .map((it) => {
+        if (typeof it !== "string" && "blocks" in it)
+            return `<li>${it.blocks.map((block) => blockHtml(block, ctx, seg)).join("\n")}</li>`;
+        const text = typeof it === "string" ? it : it.text;
+        const children = typeof it === "string" || it.children.length === 0
+            ? ""
+            : listHtml(it.children, ctx, seg, it.ordered === true);
+        return `<li>${segmentsHtml(text, ctx, seg)}${children}</li>`;
+    })
+        .join("");
+    return `<${tag}>${lis}</${tag}>`;
+};
+// caption: line 1 = the label "Fig.<name>", then a newline and the description (.cap keeps it via
+// pre-line). The figure content is figure-frame.ts's sandboxed iframe (fully isolates svg / html;
+// raster images use <img>).
+const figureHtml = (fig, withLabel = true, caption) => {
+    const label = caption ?? fig.title ?? `Fig.${fig.name}`;
+    const cap = [withLabel ? label : undefined, fig.desc].filter(Boolean).join("\n");
+    return `<figure class="fig">${figureFrameHtml(fig, "fig-frame", caption)}${cap ? `<figcaption class="cap">${escapeHtml(cap)}</figcaption>` : ""}</figure>`;
+};
+const tableHtml = (b, ctx, seg) => {
+    if (b.dataSource) {
+        const rows = [b.headers, ...b.rows];
+        const mode = b.tableMode ?? "data";
+        const header = mode === "header";
+        const body = rows.slice(header ? 1 : 0);
+        const headings = b.headers
+            .map((cell, index) => `<th scope="col">${header ? escapeHtml(cell) : `<span data-i18n="Column">Column</span> ${index + 1}`}</th>`)
+            .join("");
+        const content = body
+            .map((row, index) => `<tr><th scope="row">${index + (header ? 2 : 1)}</th>${row.map((cell) => `<td>${escapeHtml(cell)}</td>`).join("")}</tr>`)
+            .join("");
+        return `<section class="data-table" data-table-source="${escapeHtml(b.dataSource)}" data-table-mode="${mode}">
+<div class="data-table-scroll" tabindex="0" role="region" aria-label="${escapeHtml(b.alt ?? b.caption ?? b.dataSource)}"><table><thead title="Click a column to sort; row numbers refer to the source" data-i18n-title="Click a column to sort; row numbers refer to the source"><tr><th scope="col">#</th>${headings}</tr></thead><tbody>${content}</tbody></table></div>
+<div class="data-table-resize" role="separator" tabindex="0" aria-orientation="horizontal" aria-label="Resize table" data-i18n-aria-label="Resize table"></div>
+<span hidden data-table-column-label data-i18n="Column">Column</span>
+<template data-table-rows>${escapeHtml(JSON.stringify(rows))}</template></section>`;
+    }
+    const th = b.headers.map((h) => `<th>${segmentsHtml(h, ctx, seg)}</th>`).join("");
+    const trs = b.rows
+        .map((r) => `<tr>${r.map((c) => `<td>${segmentsHtml(c, ctx, seg)}</td>`).join("")}</tr>`)
+        .join("");
+    const table = `<table><thead><tr>${th}</tr></thead><tbody>${trs}</tbody></table>`;
+    if (b.collapsible) {
+        return `<details><summary>${escapeHtml(b.caption ?? "table")}</summary>${table}</details>`;
+    }
+    return `${table}${b.caption ? `<div class="cap">${escapeHtml(b.caption)}</div>` : ""}`;
+};
+// Numbers are rounded to one decimal place (keeps the SVG stable and short).
+const n1 = (v) => String(Math.round(v * 10) / 10);
+// One table box: header (rounded top edge) + field rows + note rows + transparent rects for hover
+// hit-testing.
+const schemaBoxHtml = (t) => {
+    const r = t.radius;
+    const head = [
+        `M${n1(t.x)},${n1(t.y + r)}`,
+        `a${r},${r} 0 0 1 ${r},-${r}`,
+        `h${n1(t.w - r * 2)}`,
+        `a${r},${r} 0 0 1 ${r},${r}`,
+        `v${n1(t.headerH - r)}`,
+        `h-${n1(t.w)}`,
+        "z",
+    ].join(" ");
+    const rows = t.rows
+        .map((row) => {
+        if (row.kind === "note") {
+            return `<text class="sg-note" x="${n1(row.x)}" y="${n1(row.baseline)}">${escapeHtml(row.name)}</text>`;
+        }
+        const typeCls = row.kind === "pk" ? " sg-key" : row.kind === "scalar" ? "" : " sg-ref";
+        return [
+            `<text class="sg-fname" x="${n1(row.x)}" y="${n1(row.baseline)}">${escapeHtml(row.name)}</text>`,
+            `<text class="sg-ftype${typeCls}" x="${n1(row.typeX)}" y="${n1(row.baseline)}" text-anchor="end">${escapeHtml(row.type)}</text>`,
+        ].join("");
+    })
+        .join("");
+    // Hover targets = the whole box (table) + fk rows (field). Field targets come last so they sit
+    // on top.
+    const hits = t.rows
+        .filter((row) => row.fieldIndex != null && (row.kind === "fk" || row.kind === "fkList"))
+        .map((row) => `<rect class="sg-hit sg-hf${t.index}-${row.fieldIndex}" x="${n1(t.x)}" y="${n1(row.y - 9.5)}" width="${n1(t.w)}" height="19"></rect>`)
+        .join("");
+    // data-sg-t = key the interaction layer (schema-graph-client.ts) uses to look up drag targets.
+    return [
+        `<g class="sg-g" data-sg-t="${t.index}">`,
+        `<rect class="sg-box sg-b${t.index}" x="${n1(t.x)}" y="${n1(t.y)}" width="${n1(t.w)}" height="${n1(t.h)}" rx="${r}"></rect>`,
+        `<path class="sg-head" d="${head}"></path>`,
+        `<text class="sg-tname" x="${n1(t.rows[0]?.x ?? t.x)}" y="${n1(t.headerBaseline)}">${escapeHtml(t.name)}</text>`,
+        rows,
+        `<rect class="sg-hit sg-h${t.index}" x="${n1(t.x)}" y="${n1(t.y)}" width="${n1(t.w)}" height="${n1(t.h)}"></rect>`,
+        hits,
+        "</g>",
+    ].join("");
+};
+// schema graph (`schemath`) → self-contained SVG. Geometry comes from schema-graph.ts
+// (deterministic layout); this is markup only. Colors reference `var(--doc-*, fallback)` like
+// figures, and linked hover (highlighting related edges) is done entirely with CSS :has() (no JS =
+// same behavior on every consumer). Classes / marker ids are namespaced by the model hash, so
+// multiple graphs on the same page don't collide.
+const schemaGraphHtml = (b) => {
+    if (b.graph.tables.length === 0) {
+        return `<div class="ph">${escapeHtml(b.alt || "schema graph")}<span> — no tables declared</span></div>`;
+    }
+    const layout = layoutSchemaGraph(b.graph);
+    const cls = `sg-${schemaGraphUid(b.graph)}`;
+    const arrow = `${cls}-arw`;
+    const accent = "var(--doc-accent-2, #0277bd)";
+    const rules = [
+        `.${cls}{width:100%;max-width:${layout.width}px;height:auto;font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}`,
+        `.${cls} .sg-frame{fill:color-mix(in srgb, var(--doc-fg, #000000) 3%, transparent);stroke:var(--doc-border, #dde3eb);stroke-width:1;stroke-dasharray:5 4}`,
+        `.${cls} .sg-glabel{font-size:11.5px;fill:var(--doc-fg-3, #5b6271)}`,
+        `.${cls} .sg-box{fill:var(--doc-panel, #ffffff);stroke:var(--doc-border, #dde3eb);stroke-width:1}`,
+        `.${cls} .sg-head{fill:color-mix(in srgb, ${accent} 10%, transparent)}`,
+        `.${cls} .sg-tname{font-size:12.5px;fill:var(--doc-fg, #000000)}`,
+        `.${cls} .sg-fname{font-size:11.5px;fill:var(--doc-fg-2, #2a3140)}`,
+        `.${cls} .sg-ftype{font-size:10.5px;fill:var(--doc-fg-3, #5b6271)}`,
+        `.${cls} .sg-key{fill:${accent}}`,
+        `.${cls} .sg-ref{fill:var(--doc-accent, #1b4994)}`,
+        `.${cls} .sg-note{font-size:10.5px;fill:var(--doc-fg-4, #9099a8)}`,
+        `.${cls} .sg-e{fill:none;stroke:color-mix(in srgb, var(--doc-fg, #000000) 26%, transparent);stroke-width:1.2}`,
+        `.${cls} .sg-list{stroke-dasharray:5 4}`,
+        `.${cls} .sg-hit{fill:transparent}`,
+        `.${cls} .sg-legend{font-size:10.5px;fill:var(--doc-fg-3, #5b6271)}`,
+        // Classes added by the interaction layer (schema-graph-client.ts). Where JS doesn't run
+        // they never appear, so the SVG stays static (= progressive enhancement).
+        `.${cls}.sg-live{touch-action:none}`,
+        `.${cls}.sg-live .sg-g{cursor:grab}`,
+        `.${cls}.sg-grabbing .sg-g{cursor:grabbing}`,
+        `.${cls} .sg-tool{opacity:0.35;transition:opacity .12s}`,
+        `.${cls}:hover .sg-tool,.${cls}.sg-expanded .sg-tool{opacity:1}`,
+        `.${cls} .sg-btn{cursor:pointer}`,
+        `.${cls} .sg-btn-bg{fill:var(--doc-panel, #ffffff);stroke:var(--doc-border, #dde3eb);stroke-width:1}`,
+        `.${cls} .sg-btn:hover .sg-btn-bg{stroke:${accent}}`,
+        `.${cls} .sg-btn-t{font-size:12px;fill:var(--doc-fg-2, #2a3140)}`,
+    ];
+    // Table hover = highlight every edge connected to that table (dimming the rest); fk row hover =
+    // strongest highlight on that one edge.
+    for (const t of layout.tables) {
+        rules.push(`.${cls}:has(.sg-h${t.index}:hover) .sg-e{opacity:0.12}`, `.${cls}:has(.sg-h${t.index}:hover) .sg-et${t.index}{opacity:1;stroke:${accent};stroke-width:1.8}`, `.${cls}:has(.sg-h${t.index}:hover) .sg-b${t.index}{stroke:${accent}}`);
+    }
+    for (const e of layout.edges) {
+        rules.push(`.${cls}:has(.sg-hf${e.from}-${e.fieldIndex}:hover) .sg-ef${e.from}-${e.fieldIndex}{opacity:1;stroke:${accent};stroke-width:2.4}`);
+    }
+    const frames = layout.groups
+        .map((g) => `<rect class="sg-frame" x="${n1(g.x)}" y="${n1(g.y)}" width="${n1(g.w)}" height="${n1(g.h)}" rx="14"></rect><text class="sg-glabel" x="${n1(g.x + 4)}" y="${n1(g.y - 7)}">${escapeHtml(g.label)}</text>`)
+        .join("");
+    // data-sg-e = index the interaction layer uses to replace d after a drag (in lockstep with
+    // layout.edges).
+    const edges = layout.edges
+        .map((e, i) => `<path class="sg-e sg-et${e.from} sg-et${e.to} sg-ef${e.from}-${e.fieldIndex}${e.list ? " sg-list" : ""}" data-sg-e="${i}" d="${e.d}" marker-end="url(#${arrow})"></path>`)
+        .join("");
+    const legend = layout.legendY == null
+        ? ""
+        : `<text class="sg-legend" x="${SCHEMA_LAYOUT_MARGIN}" y="${n1(layout.legendY)}">Solid = fk (1:1) / dashed = fk[] (1:N) / hover to highlight related references</text>`;
+    const desc = `${b.graph.tables.length} tables, ${b.graph.edges.length} references: ${b.graph.tables
+        .map((t) => t.name)
+        .join(", ")}`;
+    // Data read by the interactive UI (React Flow). It starts from the same model / same initial
+    // placement, so the picture doesn't jump when switching from static SVG → interactive graph
+    // (before mount / without JS, this SVG is the fallback as-is).
+    const clientData = schemaGraphClientData(cls, b.graph, layout, b.source);
+    const svg = [
+        `<svg xmlns="http://www.w3.org/2000/svg" class="${cls}" viewBox="0 0 ${layout.width} ${layout.height}" role="img" data-sg-layout="${escapeHtml(JSON.stringify(clientData))}">`,
+        `<title>${escapeHtml(b.alt ?? b.caption ?? "schema graph")}</title>`,
+        `<desc>${escapeHtml(desc)}</desc>`,
+        `<defs><marker id="${arrow}" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" style="fill:context-stroke"></path></marker></defs>`,
+        `<style>${rules.join("\n")}</style>`,
+        // sg-view = target of zoom / pan (the toolbar band and legend stay in screen coordinates).
+        '<g class="sg-view">',
+        frames,
+        edges,
+        layout.tables.map(schemaBoxHtml).join(""),
+        "</g>",
+        legend,
+        "</svg>",
+    ].join("");
+    return `<figure class="fig"${b.alt ? ` aria-label="${escapeHtml(b.alt)}"` : ""}>${svg}${b.caption ? `<figcaption class="cap">${escapeHtml(b.caption)}</figcaption>` : ""}</figure>`;
+};
+// One node box (rounded rect + centered label + transparent rect for hover hit-testing).
+const graphBoxHtml = (n) => [
+    `<g class="gr-g" data-gr-n="${n.index}">`,
+    `<rect class="gr-box gr-b${n.index}" x="${n1(n.x)}" y="${n1(n.y)}" width="${n1(n.w)}" height="${n1(n.h)}" rx="${n.radius}"></rect>`,
+    `<text class="gr-nlabel" x="${n1(n.textX)}" y="${n1(n.baseline)}" text-anchor="middle">${escapeHtml(n.label)}</text>`,
+    `<rect class="gr-hit gr-h${n.index}" x="${n1(n.x)}" y="${n1(n.y)}" width="${n1(n.w)}" height="${n1(n.h)}"></rect>`,
+    "</g>",
+].join("");
+// Relationship graph (`graphth`) → self-contained SVG. Geometry comes from graph.ts
+// (deterministic layout); this is markup only. Colors reference `var(--doc-*, fallback)` like
+// figures / schema graph, and linked hover (highlighting related edges) is done entirely with CSS
+// :has() (no JS = same behavior on every consumer). Classes / marker ids are namespaced by the
+// model hash, so multiple graphs on the same page don't collide.
+const graphHtml = (b) => {
+    if (b.graph.nodes.length === 0) {
+        return `<div class="ph">${escapeHtml(b.alt || "graph")}<span> — no nodes declared</span></div>`;
+    }
+    const layout = layoutGraph(b.graph);
+    const cls = `gr-${graphUid(b.graph)}`;
+    const arrow = `${cls}-arw`;
+    const accent = "var(--doc-accent-2, #0277bd)";
+    const rules = [
+        `.${cls}{width:100%;max-width:${layout.width}px;height:auto;font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}`,
+        `.${cls} .gr-frame{fill:color-mix(in srgb, var(--doc-fg, #000000) 3%, transparent);stroke:var(--doc-border, #dde3eb);stroke-width:1;stroke-dasharray:5 4}`,
+        `.${cls} .gr-glabel{font-size:11.5px;fill:var(--doc-fg-3, #5b6271)}`,
+        `.${cls} .gr-box{fill:var(--doc-panel, #ffffff);stroke:var(--doc-border, #dde3eb);stroke-width:1}`,
+        `.${cls} .gr-nlabel{font-size:12.5px;fill:var(--doc-fg, #000000)}`,
+        `.${cls} .gr-e{fill:none;stroke:color-mix(in srgb, var(--doc-fg, #000000) 26%, transparent);stroke-width:1.2}`,
+        `.${cls} .gr-dashed{stroke-dasharray:5 4}`,
+        `.${cls} .gr-elabel{font-size:10.5px;fill:var(--doc-fg-3, #5b6271)}`,
+        `.${cls} .gr-hit{fill:transparent}`,
+        `.${cls} .gr-legend{font-size:10.5px;fill:var(--doc-fg-3, #5b6271)}`,
+    ];
+    // Node hover = highlight every edge connected to that node (dimming the rest).
+    for (const n of layout.nodes) {
+        rules.push(`.${cls}:has(.gr-h${n.index}:hover) .gr-e{opacity:0.12}`, `.${cls}:has(.gr-h${n.index}:hover) .gr-et${n.index}{opacity:1;stroke:${accent};stroke-width:1.8}`, `.${cls}:has(.gr-h${n.index}:hover) .gr-b${n.index}{stroke:${accent}}`);
+    }
+    const frames = layout.regions
+        .map((g) => `<rect class="gr-frame" x="${n1(g.x)}" y="${n1(g.y)}" width="${n1(g.w)}" height="${n1(g.h)}" rx="14"></rect><text class="gr-glabel" x="${n1(g.x + 4)}" y="${n1(g.y - 7)}">${escapeHtml(g.label)}</text>`)
+        .join("");
+    const edges = layout.edges
+        .map((e, i) => {
+        const marker = e.kind === "undirected" ? "" : ` marker-end="url(#${arrow})"`;
+        const dash = e.kind === "dashed" ? " gr-dashed" : "";
+        const path = `<path class="gr-e gr-et${e.from} gr-et${e.to}${dash}" data-gr-e="${i}" d="${e.d}"${marker}></path>`;
+        if (e.label == null) {
+            return path;
+        }
+        return `${path}<text class="gr-elabel" x="${n1(e.labelX ?? 0)}" y="${n1(e.labelY ?? 0)}" text-anchor="${e.labelAnchor === "middle" ? "middle" : "start"}">${escapeHtml(e.label)}</text>`;
+    })
+        .join("");
+    const legend = layout.legendY == null
+        ? ""
+        : `<text class="gr-legend" x="${GRAPH_LAYOUT_MARGIN}" y="${n1(layout.legendY)}">${escapeHtml(GRAPH_LEGEND)}</text>`;
+    const desc = `${b.graph.nodes.length} nodes, ${b.graph.edges.length} edges: ${b.graph.nodes
+        .map((n) => n.label)
+        .join(", ")}`;
+    const svg = [
+        `<svg xmlns="http://www.w3.org/2000/svg" class="${cls}" viewBox="0 0 ${layout.width} ${layout.height}" role="img">`,
+        `<title>${escapeHtml(b.alt ?? b.caption ?? "graph")}</title>`,
+        `<desc>${escapeHtml(desc)}</desc>`,
+        `<defs><marker id="${arrow}" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" style="fill:context-stroke"></path></marker></defs>`,
+        `<style>${rules.join("\n")}</style>`,
+        frames,
+        edges,
+        layout.nodes.map(graphBoxHtml).join(""),
+        legend,
+        "</svg>",
+    ].join("");
+    return `<figure class="fig"${b.alt ? ` aria-label="${escapeHtml(b.alt)}"` : ""}>${svg}${b.caption ? `<figcaption class="cap">${escapeHtml(b.caption)}</figcaption>` : ""}</figure>`;
+};
+const TERM_ICON = '<svg class="term-icon" viewBox="0 0 20 20" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M5 3h11v14H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2Zm-2 12a2 2 0 0 1 2-2h11M7 10l2-5 2 5M8 8h2"/></svg>';
+/** Shared dictionary entries for definitions and the Resources list. */
+export const termsHtml = (terms, language, sortable = false) => {
+    const entries = terms
+        .map((entry, sourceOrder) => ({ ...entry, sourceOrder }))
+        .sort(termComparator(language));
+    return `<section class="terms" aria-label="Terms">${sortable ? `<div class="dict-toolbar"><span>${entries.length} terms</span><label>Sort <select data-dict-sort><option value="asc">Name A → Z</option><option value="desc">Name Z → A</option><option value="source">Source order</option></select></label></div>` : ""}<div class="dict">${entries
+        .map((e, i) => `<fieldset class="dict-card" data-source-order="${e.sourceOrder}" data-sort-order="${i}" data-term="${escapeHtml(e.id)}"><legend id="${termAnchor(e.id)}">${TERM_ICON}<a class="term-name" href="/_files/terms#${encodeURIComponent(termAnchor(e.id))}"${e.description ? ` aria-describedby="term-description-${encodeURIComponent(e.id)}"` : ""}>${escapeHtml(e.name)}${e.description ? `<span class="term-description" role="tooltip" id="term-description-${encodeURIComponent(e.id)}">${escapeHtml(e.description)}</span>` : ""}</a></legend><p class="term-definition">${escapeHtml(e.definition)}</p></fieldset>`)
+        .join("")}</div></section>`;
+};
+const blockHtml = (b, ctx, seg) => {
+    switch (b.type) {
+        case "themeVariants":
+            return `<div data-theme-variants><div data-theme-variant="">${blockHtml(b.default, ctx, seg)}</div>${Object.entries(b.variants)
+                .map(([theme, block]) => `<div data-theme-variant="${escapeHtml(theme)}" hidden>${blockHtml(block, ctx, seg)}</div>`)
+                .join("")}</div>`;
+        case "external": {
+            const url = new URL(b.url);
+            if (!/^https?:$/.test(url.protocol) || url.username || url.password)
+                return `<p>${escapeHtml(b.url)}</p>`;
+            return `<div class="external-embed" data-embed-url="${escapeHtml(b.url)}"><a href="${escapeHtml(b.url)}" target="_blank" rel="noopener noreferrer">${escapeHtml(b.alt || b.url)}</a></div>`;
+        }
+        case "h":
+            // id = slug (a single-doc page, so no namespace is needed).
+            return `<h${b.level} id="${escapeHtml(b.slug)}">${segmentsHtml(b.text, ctx, seg)}${ctx.sectionUrl === undefined ? "" : `<button class="section-copy" type="button" data-section-url="${escapeHtml(ctx.sectionUrl)}#${encodeURIComponent(b.slug)}" title="Copy section URL" aria-label="Copy section URL" data-i18n-title="Copy section URL" data-i18n-aria-label="Copy section URL"><svg viewBox="0 0 20 20" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" aria-hidden="true"><path d="m8 12 4-4m-5 2-2 2a3 3 0 0 0 4 4l2-2m-2-8 2-2a3 3 0 0 1 4 4l-2 2"/></svg>${CHECK_ICON}</button>`}</h${b.level}>`;
+        case "p":
+            return `<p>${segmentsHtml(b.text, ctx, seg)}</p>`;
+        case "quote":
+            return `<blockquote>${b.blocks.map((block) => blockHtml(block, ctx, seg)).join("\n")}</blockquote>`;
+        case "list":
+            return listHtml(b.items, ctx, seg, b.ordered === true);
+        case "code": {
+            if (b.lang === "mermaid" && !b.unavailable)
+                return `<pre data-mermaid="pending" aria-label="${escapeHtml(b.alt || "Mermaid diagram")}" style="overflow:auto;background:var(--doc-bg);color:var(--doc-fg);padding:1rem">${escapeHtml(b.lines.join("\n"))}</pre>`;
+            const filename = b.filename ? textfileName(b.filename) : "";
+            const lang = b.filename ? /^.+(\.[^.]+)$/.exec(filename)?.[1] : (b.lang ?? "text");
+            const langLabel = lang ? `<span class="codeblk-lang">${escapeHtml(lang)}</span>` : "";
+            const filenameLabel = filename
+                ? `<span class="codeblk-filename">${escapeHtml(filename)}</span>`
+                : "";
+            const title = b.filename
+                ? ` title="${escapeHtml(`${b.filename}${b.range ?? ""}`)}"${b.alt ? ` role="region" aria-label="${escapeHtml(b.alt)}"` : ""}`
+                : "";
+            if (b.filename && b.unavailable) {
+                const message = b.unavailable === "missing" ? "File not found" : "File could not be loaded";
+                return `<div class="codeblk textfile unavailable"${title}><span class="codeblk-head">${langLabel}${filenameLabel}</span><p class="textfile-unavailable" role="status">${b.alt ? `${escapeHtml(b.alt)} — ` : ""}<span data-i18n="${message}">${message}</span></p></div>`;
+            }
+            // Copy/fold behavior and border-label styling are shared by the page shell.
+            return `<div class="codeblk${b.filename ? " textfile" : ""}" data-lang="${escapeHtml(b.lang ?? "text")}"${title}><span class="codeblk-head">${langLabel}${filenameLabel}<button class="codecopy" type="button" title="copy" aria-label="copy code"><svg class="ic-copy" viewBox="0 0 24 24" width="14" height="14" aria-hidden="true"><path fill="currentColor" d="M16 1H4c-1.1 0-2 .9-2 2v14h2V3h12V1zm3 4H8c-1.1 0-2 .9-2 2v14c0 1.1.9 2 2 2h11c1.1 0 2-.9 2-2V7c0-1.1-.9-2-2-2zm0 16H8V7h11v14z"/></svg>${CHECK_ICON}</button><button class="codefold" type="button" aria-expanded="true" aria-label="Collapse code" title="Collapse code" data-i18n-aria-label="Collapse code" data-i18n-title="Collapse code"><svg viewBox="0 0 20 20" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m5 7.5 5 5 5-5"/></svg></button></span><pre><code>${escapeHtml(b.lines.join("\n"))}</code></pre></div>`;
+        }
+        case "table":
+            return tableHtml(b, ctx, seg);
+        case "callout": {
+            const title = b.title ? `<div class="callout-title">${escapeHtml(b.title)}</div>` : "";
+            const body = b.body
+                .map((it) => it.type === "p"
+                ? `<p>${segmentsHtml(it.text, ctx, seg)}</p>`
+                : listHtml(it.items, ctx, seg, it.ordered === true))
+                .join("");
+            return `<aside class="callout"${b.alt ? ` aria-label="${escapeHtml(b.alt)}"` : ""}>${title}<div class="callout-body">${body}</div></aside>`;
+        }
+        case "figureRef": {
+            const fig = ctx.figures.get(b.name);
+            if (fig) {
+                if (b.alt !== undefined)
+                    return `<figure class="fig">${figureFrameHtml(fig, "fig-frame", b.alt)}</figure>`;
+                return figureHtml(fig, true, b.caption);
+            }
+            return `<div class="ph">${escapeHtml(b.alt || `Fig. ${b.name}`)}<span> — not found in figures/</span></div>`;
+        }
+        case "term":
+            return termsHtml([b.entry], ctx.language);
+        case "figures":
+            // Figure list. The h2 doubles as the label, so captions omit it. h2 id = fig name
+            // (anchor).
+            return [...ctx.figures.values()]
+                .map((f) => `<h2 id="${escapeHtml(f.name)}">${escapeHtml(f.title ?? f.name)}</h2>${figureHtml(f, false)}`)
+                .join("\n");
+        case "schemaGraph":
+            // table DSL → ER diagram. The parsed model is turned into SVG with a
+            // deterministic layout, so every consumer gets the same picture (no references outside
+            // the data).
+            return schemaGraphHtml(b);
+        case "graph":
+            // node / edge DSL → relationship graph. Like schemaGraph: model → deterministic layout
+            // → SVG.
+            return graphHtml(b);
+        default:
+            // Unknown block — degrade to a placeholder
+            // instead of emitting "undefined".
+            return `<div class="ph">${escapeHtml(`Unknown block (${b.type})`)}<span> — docs viewer needs an update</span></div>`;
+    }
+};
+export const blocksHtml = (blocks, ctx = emptyCtx) => {
+    const seg = inlineSegmenter({
+        terms: ctx.terms,
+    });
+    return blocks
+        .map((b) => blockHtml(b, ctx, seg))
+        .filter((h) => h !== "")
+        .join("\n");
+};
+// The viewer moves this navigation into the fixed document header.
+const inPageTocHtml = (toc, title = "Contents") => {
+    if (toc.length === 0) {
+        return "";
+    }
+    const items = toc
+        .map((t) => `<li class="lvl${t.depth}"><a href="#${escapeHtml(t.slug)}" data-toc-target="${escapeHtml(t.slug)}" title="${escapeHtml(t.text)}">${escapeHtml(t.text)}</a></li>`)
+        .join("");
+    return `<nav class="in-toc" aria-label="${escapeHtml(title)}"><button class="toc-current" type="button" aria-expanded="false">${escapeHtml(toc[0]?.text ?? "")}</button><ul class="toc-options" popover>${items}</ul><input class="toc-seek" type="range" min="0" max="1000" step="1" value="0" aria-label="${escapeHtml(title)}" disabled></nav>`;
+};
+export const docHtml = (fm, blocks, errors, ctx = emptyCtx, toc = []) => {
+    const errBox = errors.length > 0
+        ? `<div class="errors">${errors.map((e) => `<div>${escapeHtml(e)}</div>`).join("")}</div>`
+        : "";
+    const lang = ctx.lang ? ` lang="${escapeHtml(ctx.lang)}"` : "";
+    return `<article${lang}>${errBox}<h1>${escapeHtml(docDisplayName(fm, ""))}</h1>${inPageTocHtml(toc, ctx.tocTitle)}${blocksHtml(blocks, ctx)}</article>`;
+};

package/dist/core/icons.d.ts

@@ -0,0 +1 @@
+export declare const CHECK_ICON = "<svg class=\"ic-ok\" viewBox=\"0 0 20 20\" width=\"14\" height=\"14\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\" stroke-linecap=\"round\" stroke-linejoin=\"round\" aria-hidden=\"true\"><path d=\"m4 10 4 4 8-8\"/></svg>";

package/dist/core/icons.js

@@ -0,0 +1 @@
+export const CHECK_ICON = '<svg class="ic-ok" viewBox="0 0 20 20" width="14" height="14" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m4 10 4 4 8-8"/></svg>';

package/dist/core/inline.d.ts

@@ -0,0 +1,27 @@
+import type { TermEntry } from "./content-types.js";
+export type InlineSegment = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "code";
+    text: string;
+} | {
+    kind: "strong" | "emphasis";
+    text: string;
+    children: InlineSegment[];
+} | {
+    kind: "link";
+    text: string;
+    url: string;
+    children?: InlineSegment[];
+} | {
+    kind: "term";
+    id: string;
+    text: string;
+    children?: InlineSegment[];
+};
+export declare const termMap: (terms: readonly TermEntry[]) => Map<string, TermEntry>;
+export interface InlineContext {
+    terms?: readonly TermEntry[];
+}
+export declare const inlineSegmenter: (ctx?: InlineContext) => ((text: string) => InlineSegment[]);

package/dist/core/inline.js

@@ -0,0 +1,42 @@
+import { parseMdast } from "./markdown.js";
+import { parseTermReference } from "./term-reference.js";
+export const termMap = (terms) => new Map(terms.map((entry) => [entry.id, entry]));
+export const inlineSegmenter = (ctx = {}) => {
+    const terms = termMap(ctx.terms ?? []);
+    const segments = (nodes) => nodes.flatMap((node) => {
+        if (node.type === "inlineCode")
+            return [{ kind: "code", text: node.value }];
+        if ("value" in node)
+            return [{ kind: "text", text: node.value }];
+        if (!("children" in node))
+            return [];
+        const children = segments(node.children);
+        const text = children.map((child) => child.text).join("");
+        if (node.type === "strong" || node.type === "emphasis")
+            return [{ kind: node.type, text, children }];
+        if (node.type === "link") {
+            let id;
+            try {
+                id = parseTermReference(node.url);
+            }
+            catch {
+                /* The compiler reports invalid paths. */
+            }
+            const formatted = children.some((child) => child.kind !== "text")
+                ? { children }
+                : {};
+            return [
+                id
+                    ? {
+                        kind: "term",
+                        id,
+                        text: text || terms.get(id)?.name || node.url,
+                        ...formatted,
+                    }
+                    : { kind: "link", text, url: node.url, ...formatted },
+            ];
+        }
+        return children;
+    });
+    return (text) => segments(parseMdast(text).children);
+};

package/dist/core/language.d.ts

@@ -0,0 +1,41 @@
+import type { TermEntry } from "./content-types.js";
+export declare const DEFAULT_LANG = "en";
+export declare const isContentLanguage: (code: string) => boolean;
+/** Normalize site language declarations and translation directory names consistently. */
+export declare const contentLanguageCode: (tag: string) => string;
+/** BCP 47-shaped tag (`en`, `ja`, `pt-BR`, `zh-Hant-TW`). Not checked against a registry. */
+export declare const LANG_TAG_RE: RegExp;
+export declare const isLangTag: (s: string) => boolean;
+/** One prose-lint finding. range = 0-indexed [start, end) offsets into the linted body string. */
+export interface LintFinding {
+    ruleId: string;
+    message: string;
+    range: readonly [number, number];
+}
+export interface LanguageAdapter {
+    /**
+     * BCP 47 tag this adapter handles. A doc tag matches exactly, else by its primary subtag
+     * (`ja-JP` → `ja`).
+     */
+    readonly code: string;
+    /** Order of term listings. Default: Intl.Collator for code, by name. */
+    compareTerms?: (a: TermEntry, b: TermEntry) => number;
+    /** Language of the editor's browser spellcheck. Default: the doc's tag. */
+    spellcheckLang?: string;
+    /**
+     * Prose lint shown in the editor (Node only; runs on the server, so it may load heavy
+     * dependencies lazily). Offsets are relative to the body string. Absent = no lint.
+     */
+    lint?: (body: string) => Promise<LintFinding[]>;
+}
+/** Shape of `<docs root>/docs.config.mjs` (its default export). */
+export interface DocsConfig {
+    /** Extra adapters. They take precedence over the built-in ones with the same code. */
+    languages?: LanguageAdapter[];
+}
+/**
+ * Adapter for a doc tag: exact code match, then the primary subtag, else a generic adapter
+ * carrying the tag (so collation still follows the language via Intl).
+ */
+export declare const resolveLanguage: (lang: string | undefined, adapters?: readonly LanguageAdapter[]) => LanguageAdapter;
+export declare const termComparator: (language: LanguageAdapter | undefined) => NonNullable<LanguageAdapter["compareTerms"]>;

package/dist/core/language.js

@@ -0,0 +1,44 @@
+import { iso6393, iso6393To1 } from "iso-639-3";
+export const DEFAULT_LANG = "en";
+const contentCodes = new Set(iso6393.map((language) => language.iso6393));
+const from1 = new Map(Object.entries(iso6393To1).map(([three, two]) => [two, three]));
+export const isContentLanguage = (code) => contentCodes.has(code);
+/** Normalize site language declarations and translation directory names consistently. */
+export const contentLanguageCode = (tag) => {
+    const primary = tag.toLowerCase().split("-")[0] ?? "";
+    const code = from1.get(primary) ?? primary;
+    if (!isContentLanguage(code))
+        throw new Error(`Unknown ISO 639-3 language: ${tag}`);
+    return code;
+};
+/** BCP 47-shaped tag (`en`, `ja`, `pt-BR`, `zh-Hant-TW`). Not checked against a registry. */
+export const LANG_TAG_RE = /^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$/;
+export const isLangTag = (s) => LANG_TAG_RE.test(s);
+/**
+ * Adapter for a doc tag: exact code match, then the primary subtag, else a generic adapter
+ * carrying the tag (so collation still follows the language via Intl).
+ */
+export const resolveLanguage = (lang, adapters = []) => {
+    const tag = lang || DEFAULT_LANG;
+    const lower = tag.toLowerCase();
+    const code = lower.split("-")[0] ?? lower;
+    const primary = iso6393To1[code] ?? code;
+    return (adapters.find((a) => a.code.toLowerCase() === lower) ??
+        adapters.find((a) => a.code.toLowerCase() === primary) ?? { code: tag });
+};
+const collator = (code) => {
+    try {
+        return new Intl.Collator(code, { sensitivity: "base" });
+    }
+    catch {
+        // A tag Intl rejects falls back to the default language's order.
+        return new Intl.Collator(DEFAULT_LANG, { sensitivity: "base" });
+    }
+};
+export const termComparator = (language) => {
+    if (language?.compareTerms) {
+        return language.compareTerms;
+    }
+    const c = collator(language?.code ?? DEFAULT_LANG);
+    return (a, b) => c.compare(a.name, b.name);
+};

package/dist/core/languages/ja.d.ts

@@ -0,0 +1,2 @@
+import type { LanguageAdapter } from "../language.js";
+export declare const ja: LanguageAdapter;

package/dist/core/languages/ja.js

@@ -0,0 +1,5 @@
+export const ja = {
+    code: "ja",
+    // Browsers do not spellcheck Japanese; check embedded English words instead.
+    spellcheckLang: "en",
+};