@rse/specbook 1.3.2 → 1.4.1

package/dst/specbook-export-common.js

@@ -4,8 +4,9 @@
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
 import fs from "node:fs";
-import { embeddingThemes } from "./specbook-parse-common.js";
+import { embeddingThemes, darkMark } from "./specbook-parse-common.js";
 import { plainText } from "./specbook-link.js";
+import { themeToneDefault } from "./specbook-theme.js";
 /*  escape a text for embedding into template HTML (text and attributes)  */
 export const escapeHtml = (text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
     .replace(/"/g, "&quot;").replace(/'/g, "&#39;");
@@ -19,9 +20,13 @@ export const searchScript = () => fs.readFileSync(new URL("specbook-export-html-
 export const fallbackLogo = (theme) => "data:image/svg+xml;base64," +
     fs.readFileSync(new URL(`specbook-export-logo-${theme}.svg`, import.meta.url)).toString("base64");
 /*  the content aspects an export can omit, each matching the set of a
-    folding control of the HTML export: the diagrams of a type, the
-    diagrams from an object tree nesting level on, and the long texts  */
+    folding control of the HTML export: the diagrams of a type (the
+    derived Gradia ones, the embedded Mermaid/D2 ones as "code", the
+    embedded images and PDF pages as "image", and the code listings as
+    "listing"), the diagrams from an object tree nesting level on, and the
+    long texts  */
 export const omitAspects = ["diagram:graph", "diagram:hub", "diagram:grid",
+    "diagram:code", "diagram:image", "diagram:listing",
     "diagram:1", "diagram:2", "diagram:3", "text:long"];
 /*  parse the (comma-separated) aspects to omit, where the
     plain "diagram" is the alias of "diagram:1", hence of all diagrams  */
@@ -107,6 +112,21 @@ export const documentPaperSize = (specification) => {
             `(expected ${paperSizes.join(", ")})`);
     return paper;
 };
+/*  the properties of the title object the exports interpret themselves,
+    each with the value "init" seeds it with (its rendering default, an
+    empty value counting as an absent property)  */
+export const titleProperties = [
+    { name: "LOGO", init: "" },
+    { name: "TITLE", init: "Specification" },
+    { name: "SUBTITLE", init: "" },
+    { name: "AUTHOR", init: "" },
+    { name: "VERSION", init: "" },
+    { name: "LANG", init: "en" },
+    { name: "CHARSET", init: "UTF-8" },
+    { name: "THEME-STYLE", init: "Light" },
+    { name: "THEME-TONE", init: themeToneDefault },
+    { name: "PAPER-SIZE", init: paperSizeDefault }
+];
 /*  the vertical room (in rem) the introducing heading of a diagram
     claims above it on the same page: without this reserve a maximally
     sized diagram could not share its page with the heading, which
@@ -129,7 +149,7 @@ export const paperStylesheet = (paper) => {
     const avail = setup.height - setup.margin.top - setup.margin.bottom;
     return "@media print {\n" +
         "div.diagram { break-inside: avoid; }\n" +
-        `div.diagram svg { max-height: calc(${paperLength(setup, avail)} - ${headingReserve}rem);` +
+        `div.diagram svg, div.diagram img { max-height: calc(${paperLength(setup, avail)} - ${headingReserve}rem);` +
         " width: auto; height: auto; }\n" +
         `nav.doc div.diagram svg { max-height: calc(${paperLength(setup, avail)} - ${docHeadingReserve}rem); }\n` +
         "}\n";
@@ -223,6 +243,105 @@ export const documentTitle = (specification) => {
         subtitle: subtitle !== undefined ? plainText(subtitle) : undefined
     };
 };
+/*  the luma (0-1, of the gamma-encoded channels) of a CSS color given as
+    "#rgb", "#rrggbb", "rgb(r, g, b)", "white", or "black" (undefined for
+    any other one)  */
+const luminance = (color) => {
+    const value = color.trim().toLowerCase();
+    const named = value === "white" ? "#ffffff" : value === "black" ? "#000000" : value;
+    const hex = named.match(/^#([0-9a-f]{3}|[0-9a-f]{6})$/);
+    const rgb = named.match(/^rgb\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*\)$/);
+    const parts = hex !== null ?
+        (hex[1].length === 3 ? hex[1].split("").map((c) => c + c) : hex[1].match(/../g) ?? [])
+            .map((c) => parseInt(c, 16)) :
+        rgb !== null ? rgb.slice(1, 4).map(Number) : undefined;
+    return parts !== undefined ? (0.2126 * parts[0] + 0.7152 * parts[1] + 0.0722 * parts[2]) / 255 : undefined;
+};
+/*  whether an SVG image is most likely dark ink on a transparent or light
+    canvas and hence safe to invert on the dark theme ("dark=auto"): it
+    neither adapts itself (via "light-dark()" colors, "prefers-color-scheme"
+    rules, or a "color-scheme" declaration), nor embeds a raster image
+    (which would turn into a negative), nor paints a background of its own
+    which is not light (by the style of its root element or by the topmost
+    of the leading shapes covering the whole canvas -- rectangles or
+    rectangular paths, as a rendered PDF page paints its background over
+    the white paper of PDF.js --, an unknown color counting as not light)  */
+export const svgInvertible = (svg) => {
+    if (/light-dark\(|prefers-color-scheme|color-scheme|<image\b/.test(svg))
+        return false;
+    const root = svg.match(/<svg\b[^>]*>/)?.[0] ?? "";
+    const light = (color) => (luminance(color ?? "#000000") ?? 0) >= 0.5;
+    const back = root.match(/background(?:-color)?\s*:\s*([^;"]+)/)?.[1];
+    if (back !== undefined && !/^\s*(?:none|transparent)\s*$/.test(back) && !light(back))
+        return false;
+    /*  the canvas size (in the user units of the viewBox, if any)  */
+    const attr = (element, name) => element.match(new RegExp(`\\s${name}="([^"]*)"`))?.[1] ??
+        element.match(new RegExp(`[\\s;"]${name}\\s*:\\s*([^;"]+)`))?.[1];
+    const box = attr(root, "viewBox")?.trim().split(/[\s,]+/).map(Number) ?? [];
+    const width = box[2] || parseFloat(attr(root, "width") ?? "");
+    const height = box[3] || parseFloat(attr(root, "height") ?? "");
+    /*  whether a shape covers the whole canvas: the corner points of a
+        rectangle or of a path of straight absolute segments only, mapped
+        through its "scale()" or "matrix()" transform (if any)  */
+    const covers = (kind, element) => {
+        const num = (name) => parseFloat(attr(element, name) ?? "0") || 0;
+        let points;
+        if (kind === "rect") {
+            if (attr(element, "width") === "100%" && attr(element, "height") === "100%")
+                return true;
+            const [x, y] = [num("x"), num("y")];
+            points = [[x, y], [x + num("width"), y + num("height")]];
+        }
+        else {
+            const d = attr(element, "d") ?? "";
+            if (kind !== "path" || !/^[\sMLHVZ\d.,-]*$/.test(d))
+                return false;
+            points = [];
+            for (const [, cmd, args] of d.matchAll(/([MLHVZ])([^MLHVZ]*)/g)) {
+                const n = args.trim().split(/[\s,]+/).filter((a) => a !== "").map(Number);
+                const last = points.at(-1) ?? [0, 0];
+                if (cmd === "H")
+                    points.push(...n.map((x) => [x, last[1]]));
+                else if (cmd === "V")
+                    points.push(...n.map((y) => [last[0], y]));
+                else
+                    for (let k = 0; k + 1 < n.length; k += 2)
+                        points.push([n[k], n[k + 1]]);
+            }
+        }
+        const t = attr(element, "transform")?.trim() ?? "";
+        const f = t.match(/^(matrix|scale)\(([^)]*)\)$/);
+        const v = f?.[2].trim().split(/[\s,]+/).map(Number) ?? [];
+        const m = t === "" ? [1, 0, 0, 1, 0, 0] :
+            f?.[1] === "matrix" && v.length === 6 ? v :
+                f?.[1] === "scale" ? [v[0], 0, 0, v[1] ?? v[0], 0, 0] : undefined;
+        if (m === undefined || points.length === 0)
+            return false;
+        const xs = points.map(([x, y]) => m[0] * x + m[2] * y + m[4]);
+        const ys = points.map(([x, y]) => m[1] * x + m[3] * y + m[5]);
+        return Math.min(...xs) <= 1 && Math.min(...ys) <= 1
+            && Math.max(...xs) >= width - 1 && Math.max(...ys) >= height - 1;
+    };
+    /*  the topmost leading canvas-covering shape (outside of any
+        definition) forms the background  */
+    let fill;
+    const body = svg.slice(svg.indexOf(root) + root.length)
+        .replace(/<(clipPath|defs|mask|pattern|symbol)\b[\s\S]*?<\/\1>/g, "");
+    for (const shape of body.matchAll(/<(rect|path|circle|ellipse|line|polyline|polygon|text|use)\b[^>]*>/g)) {
+        if (!covers(shape[1], shape[0]))
+            break;
+        fill = attr(shape[0], "fill") ?? "#000000";
+    }
+    return fill === undefined || fill === "none" || fill === "transparent" || light(fill);
+};
+/*  the treatment of an embedded image on the dark theme: its explicit
+    mark, else the "auto" detection (for a raster image or a PDF page the
+    judgement of "analyzeImages", none where absent)  */
+export const imageDark = (content, rasters) => {
+    const { content: plain, dark } = darkMark(content);
+    return dark ?? ((plain.startsWith("data:") ? rasters?.get(plain) === true : svgInvertible(plain)) ?
+        "invert" : "none");
+};
 /*  determine the document logo as a self-contained data: URL, taken from the
     first embedded image of the LOGO property of the title object -- the light
     variant of a "{theme}" reference -- and falling back onto the built-in
@@ -233,6 +352,7 @@ export const documentLogo = (specification) => {
         ?.properties.find((property) => property.key === "LOGO")?.embedding?.[0];
     if (content === undefined || content === "")
         return fallbackLogo("light");
-    return content.startsWith("data:") ? content :
-        `data:image/svg+xml;base64,${Buffer.from(content, "utf8").toString("base64")}`;
+    const plain = darkMark(content).content;
+    return plain.startsWith("data:") ? plain :
+        `data:image/svg+xml;base64,${Buffer.from(plain, "utf8").toString("base64")}`;
 };

package/dst/specbook-export-diagram.d.ts

@@ -0,0 +1,15 @@
+import type { Spec, SpecObject } from "./specbook-format-spec.js";
+import { type OmitAspect } from "./specbook-export-common.js";
+import { type ThemeStyle } from "./specbook-theme.js";
+import { type Verbose } from "./specbook-verbose.js";
+export type DiagramLanguage = "mermaid" | "d2";
+export type DiagramVariants = Record<ThemeStyle, string>;
+export declare const fenceLanguage: (lang: string | undefined) => DiagramLanguage | undefined;
+export declare const embeddedSource: (content: string) => {
+    language: DiagramLanguage;
+    source: string;
+} | undefined;
+export declare const diagramKey: (language: DiagramLanguage, source: string) => string;
+export declare const omittedDiagram: (language: DiagramLanguage | "image" | "listing", level: number, omit: Set<OmitAspect>) => boolean;
+export declare const objectLevels: (specification: Spec) => Map<SpecObject, number>;
+export declare const renderEmbeddedDiagrams: (specification: Spec, verbose?: Verbose, omit?: Set<"diagram:graph" | "diagram:hub" | "diagram:grid" | "diagram:code" | "diagram:image" | "diagram:listing" | "diagram:1" | "diagram:2" | "diagram:3" | "text:long">) => Promise<Map<string, DiagramVariants>>;

package/dst/specbook-export-diagram.js

@@ -0,0 +1,211 @@
+/*
+**  Specification Book (SpecBook)
+**  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import { marked } from "marked";
+import { documentThemeTone } from "./specbook-export-common.js";
+import { themeColors, themeToneDefault } from "./specbook-theme.js";
+import { plainText } from "./specbook-link.js";
+import { literal } from "./specbook-verbose.js";
+/*  the fenced code block languages of the embedded diagrams  */
+const fenceLanguages = {
+    mermaid: "mermaid",
+    mmd: "mermaid",
+    d2: "d2"
+};
+/*  map the language of a fenced code block onto its diagram language
+    (undefined for a regular code block)  */
+export const fenceLanguage = (lang) => fenceLanguages[(lang ?? "").trim().toLowerCase()];
+/*  decode an embedded diagram source file, which the parser loads as a
+    base64 data: URL of its diagram MIME type (undefined for an image)  */
+export const embeddedSource = (content) => {
+    const m = content.match(/^data:text\/vnd\.(mermaid|d2);base64,(.*)$/s);
+    return m !== null ?
+        { language: m[1], source: Buffer.from(m[2], "base64").toString("utf8") } :
+        undefined;
+};
+/*  the key of an embedded diagram in the map of the rendered ones  */
+export const diagramKey = (language, source) => `${language}\u0000${source}`;
+/*  whether an embedded diagram of a language (a Mermaid/D2 one being of
+    the type "code"), an image, or a code listing, carried by an object of
+    a nesting level, is omitted (exactly like a Gradia diagram: by its
+    type, or from an object tree nesting level on)  */
+export const omittedDiagram = (language, level, omit) => omit.has(language === "image" ? "diagram:image" : language === "listing" ? "diagram:listing" : "diagram:code")
+    || [1, 2, 3].some((n) => n <= level && omit.has(`diagram:${n}`));
+/*  the object tree nesting levels of the objects of a specification
+    (the top-level objects of an artifact being level 1)  */
+export const objectLevels = (specification) => {
+    const levels = new Map();
+    const walk = (object, level) => {
+        levels.set(object, level);
+        for (const child of object.children)
+            walk(child, level + 1);
+    };
+    for (const artifact of specification.artifacts)
+        for (const object of artifact.objects)
+            walk(object, 1);
+    return levels;
+};
+/*  collect the embedded diagrams of an object and its descendants: the
+    fenced code blocks of a diagram language inside its description
+    statement and elaboration and the diagram source files embedded into
+    its description and property values  */
+const collect = (object, level, diagrams) => {
+    for (const text of [object.description?.description ?? "", object.description?.elaboration ?? ""])
+        marked.walkTokens(marked.lexer(text), (token) => {
+            const language = token.type === "code" ? fenceLanguage(token.lang) : undefined;
+            if (language !== undefined)
+                diagrams.push({ language, source: token.text, object, level });
+        });
+    const contents = [...object.description?.embedding ?? [],
+        ...object.properties.flatMap((property) => property.embedding ?? [])];
+    for (const content of contents) {
+        const embedded = embeddedSource(content);
+        if (embedded !== undefined)
+            diagrams.push({ ...embedded, object, level });
+    }
+    for (const child of object.children)
+        collect(child, level + 1, diagrams);
+};
+/*  the colors of the Mermaid diagrams per theme style, picked out of the
+    theme color spreads like the layer-2 mapping of the HTML rendering
+    (Mermaid derives all further colors of a diagram from these)  */
+const mermaidColors = (colors, style) => {
+    const [b, a] = [colors.base, colors.accent];
+    return style === "dark" ?
+        { bg: b[6], fg: b[28], line: b[21], accent: a[21], muted: b[21], surface: a[7], border: a[13] } :
+        { bg: b[31], fg: b[5], line: b[21], accent: a[11], muted: b[21], surface: a[30], border: a[23] };
+};
+/*  the colors of the D2 diagrams per theme style, picked out of the
+    theme color spreads after the shape of the D2 themes "Neutral
+    Default" (light) and "Dark Mauve" (dark): the neutrals "N1" (text)
+    to "N7" (background), the base colors "B1" (strokes) to "B6"
+    (fills), and the alternative accents "AA*"/"AB*"  */
+const d2Colors = (colors, style) => {
+    const [b, a, s] = [colors.base, colors.accent, colors.signal];
+    return style === "dark" ? {
+        N1: b[28], N2: b[25], N3: b[22], N4: b[13], N5: b[10], N6: b[8], N7: b[6],
+        B1: a[21], B2: a[21], B3: a[13], B4: a[10], B5: a[8], B6: a[7],
+        AA2: s[19], AA4: s[10], AA5: s[8], AB4: s[10], AB5: s[8]
+    } : {
+        N1: b[3], N2: b[13], N3: b[19], N4: b[25], N5: b[27], N6: b[29], N7: b[31],
+        B1: a[7], B2: a[11], B3: a[27], B4: a[28], B5: a[29], B6: a[30],
+        AA2: s[13], AA4: s[28], AA5: s[30], AB4: s[28], AB5: s[30]
+    };
+};
+/*  render a Mermaid diagram, stripping the web font import the SVG
+    carries, as an SVG embedded through an <img> never loads it and it
+    would be the only external reference of the exported document  */
+const renderMermaid = async (source, colors) => {
+    const { renderMermaidSVG } = await import("beautiful-mermaid");
+    return renderMermaidSVG(source, { ...colors, transparent: true, padding: 4 })
+        .replace(/^\s*@import url\([^)]*\);\s*$/m, "");
+};
+/*  the D2 compiler, created on first use (as it spins up its WebAssembly
+    build in a worker thread), and the chain of its requests, as it
+    resolves just the latest pending one and hence has to be fed one
+    request at a time: the worker is referenced during a request only,
+    as it would otherwise keep the process alive forever  */
+let d2 = null;
+let d2Chain = Promise.resolve();
+/*  turn a D2 compile failure (a JSON-encoded list of the errors, whose
+    source lines are shifted by the prepended theme line) into a message  */
+const d2Error = (err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    try {
+        return JSON.parse(message)
+            .map((error) => error.errmsg.replace(/^index:(\d+):/, (_, line) => `line ${Number(line) - 1}:`))
+            .join("; ");
+    }
+    catch {
+        return message;
+    }
+};
+/*  render a D2 diagram, with the theme colors prepended as one line of
+    theme overrides (on the theme of the style), so the overrides of the
+    diagram itself still win  */
+const renderD2 = (source, colors, style) => {
+    const overrides = Object.entries(colors).map(([key, color]) => `${key}: "${color}"`).join("; ");
+    const request = d2Chain.then(async () => {
+        d2 ??= import("@terrastruct/d2").then((module) => new module.D2())
+            .catch((err) => {
+            d2 = null;
+            throw err;
+        });
+        const compiler = await d2;
+        const worker = () => compiler.worker;
+        worker()?.ref();
+        try {
+            const result = await compiler.compile({
+                fs: { index: `vars: { d2-config: { theme-overrides: { ${overrides} } } }\n${source}` },
+                options: { themeID: style === "dark" ? 200 : 0, scale: 1, pad: 0, noXMLTag: true }
+            });
+            return await compiler.render(result.diagram, result.renderOptions);
+        }
+        catch (err) {
+            throw new Error(d2Error(err), { cause: err });
+        }
+        finally {
+            worker()?.unref();
+        }
+    });
+    d2Chain = request.catch(() => undefined);
+    return request;
+};
+/*  the in-memory cache of the rendered embedded diagrams, keyed by theme
+    tone and diagram, and swept to the diagrams of the latest rendering,
+    exactly like the one of the Gradia diagrams  */
+let diagramCache = new Map();
+/*  render the embedded diagrams of a specification (the fenced code blocks
+    of a diagram language and the embedded diagram source files) into their
+    theme variants, drawn in the theme colors of the document and keyed by
+    "diagramKey" (a rendering failure omits the diagram and is surfaced as
+    a notice only, like the one of a Gradia diagram), served from the cache
+    where possible; the omitted diagrams are skipped  */
+export const renderEmbeddedDiagrams = async (specification, verbose, omit = new Set()) => {
+    const diagrams = new Array();
+    for (const artifact of specification.artifacts)
+        for (const object of artifact.objects)
+            collect(object, 1, diagrams);
+    const tone = documentThemeTone(specification) ?? themeToneDefault;
+    const colors = themeColors(tone);
+    const cache = new Map();
+    const rendered = new Map();
+    const failed = new Set();
+    let cached = 0;
+    for (const { language, source, object, level } of diagrams) {
+        const key = diagramKey(language, source);
+        if (rendered.has(key) || failed.has(key) || omittedDiagram(language, level, omit))
+            continue;
+        let variants = diagramCache.get(`${tone}\u0000${key}`) ?? cache.get(`${tone}\u0000${key}`);
+        if (variants !== undefined)
+            cached++;
+        else {
+            try {
+                variants = language === "mermaid" ? {
+                    light: await renderMermaid(source, mermaidColors(colors, "light")),
+                    dark: await renderMermaid(source, mermaidColors(colors, "dark"))
+                } : {
+                    light: await renderD2(source, d2Colors(colors, "light"), "light"),
+                    dark: await renderD2(source, d2Colors(colors, "dark"), "dark")
+                };
+            }
+            catch (err) {
+                verbose?.(`rendering ${language} diagram of ${object.kind} ` +
+                    `"${literal(plainText(object.name))}" failed: ` +
+                    (err instanceof Error ? err.message : String(err)));
+                failed.add(key);
+                continue;
+            }
+        }
+        cache.set(`${tone}\u0000${key}`, variants);
+        rendered.set(key, variants);
+    }
+    diagramCache = cache;
+    if (rendered.size > 0)
+        verbose?.(cached === rendered.size ?
+            `reusing ${literal(cached)} cached embedded diagram(s)` :
+            `rendering ${literal(rendered.size)} embedded diagram(s) (${literal(cached)} cached)`);
+    return rendered;
+};

package/dst/specbook-export-html-fold.d.ts

@@ -0,0 +1,20 @@
+import type nunjucks from "nunjucks";
+import type { OmitAspect } from "./specbook-export-common.js";
+export declare const foldScript: (standins: boolean, textless: boolean) => string;
+export declare const omitLong: (omit: Set<OmitAspect> | null, cells: nunjucks.runtime.SafeString[], shares: number[], percent?: number) => nunjucks.runtime.SafeString[];
+export declare const omittedControls: (omit: Set<OmitAspect>) => {
+    omitted: {
+        graph: boolean;
+        hub: boolean;
+        grid: boolean;
+        code: boolean;
+        image: boolean;
+        listing: boolean;
+        level1: boolean;
+        level2: boolean;
+        level3: boolean;
+        text: boolean;
+        all: boolean;
+    };
+    css: string;
+};