@rse/specbook 1.3.1 → 1.4.0

package/README.md

@@ -83,6 +83,8 @@ CLI with commands `specbook <xxx>`, and an MCP service with tools
     The HTML export is a self-contained single document with a title page,
     a table-of-contents (also as a slide-in side panel for quick navigation),
     a diagram-of-contents, a fuzzy full-text search, embedded images,
+    embedded Mermaid and D2 diagrams (inline or as files, in the theme colors),
+    embedded PDF pages,
     reference coverage tables (e.g. the share of the use cases, scenarios,
     requirements, and rules the test cases verify), a
     scroll progress meter (which also scrolls back to the top on click),
@@ -242,7 +244,8 @@ Options:
     Omit content aspects (comma-separated, repeatable) from the HTML and
     PDF outputs at generation time, instead of just leaving them foldable
     in the browser. The aspects match the folding controls of the HTML
-    export: `diagram:graph`, `diagram:hub`, and `diagram:grid` omit all
+    export: `diagram:graph`, `diagram:hub`, `diagram:grid`,
+    `diagram:code` (Mermaid/D2), and `diagram:image` (images and PDF pages) omit all
     diagrams of a type, `diagram:1` (alias: `diagram`), `diagram:2`, and
     `diagram:3` omit all diagrams from an object tree nesting level on
     (level 1 hence all, including the "Diagram of Contents" page), and
@@ -419,7 +422,7 @@ application, based on **SpecBook**'s built-in "standard" schema:
 ### Sources
 
 -   [Specification](smp/broadcast/)
--   [Schema](src/specbook-format.d/)
+-   [Schema](src/specbook-format-schema.d/)
 
 ### Generation
 

package/dst/specbook-api.js

@@ -125,10 +125,11 @@ export class SpecBook {
     /*  render an already parsed specification into the requested formats
         (strict: any error diagnostic prevents the export, as a partial or
         invalid specification must never be emitted, while the warnings
-        are just surfaced as notices), where "rendering" carries the
-        rendering options (the live preview script, the omitted aspects)
-        and "rebase" names, per requested format, the directory the image
-        references of the normalized Markdown are re-based onto  */
+        are just surfaced as unconditional verbose messages), where
+        "rendering" carries the rendering options (the live preview
+        script, the omitted aspects) and "rebase" names, per requested
+        format, the directory the image references of the normalized
+        Markdown are re-based onto  */
     async renderFormats(result, requested, verbose, rendering, rebase) {
         if (result.diagnostics.some((diagnostic) => diagnostic.severity === "error"))
             throw new Error("invalid specification:\n" +
@@ -163,11 +164,12 @@ export class SpecBook {
         const requested = options.formats ?? ["json"];
         const omit = parseOmit(options.omit);
         const project = this.project(options, verbose);
+        const config = await this.configFiles(project.config);
         /*  a missing browser is an environment problem, so let the PDF
             export fail before the specification is even parsed  */
         if (requested.includes("pdf"))
             await requireBrowser(verbose);
-        const result = lint({ config: await this.configFiles(project.config),
+        const result = lint({ config,
             basedir: project.basedir ?? ".", gitignore: options.gitignore === true, verbose });
         return this.renderFormats(result, requested, verbose, { realtime: options.realtime === true, omit }, this.rebaseOf(options));
     }

package/dst/specbook-cmd-export.js

@@ -10,7 +10,7 @@ import * as fs from "node:fs";
 import { watch } from "chokidar5";
 import { minify } from "@swc/html";
 import { documentTitle, documentLogo, documentCharset, documentThemeTone, subsetStylesheet, documentPaperSize, paperStylesheet, charsetCodepoints, parseOmit, omitAspects } from "./specbook-export-common.js";
-import { themeColors, themeStylesheet, themeMapping } from "./specbook-theme.js";
+import { themeColors, themeToneDefault, themeStylesheet, themeMapping } from "./specbook-theme.js";
 import { renderAst } from "./specbook-export-ast.js";
 import { renderMarkdown } from "./specbook-export-md.js";
 import { renderHtml, htmlOutline, titlePageObject } from "./specbook-export-html.js";
@@ -169,7 +169,7 @@ const renderFormat = async (specification, format, verbose, config, options = {}
         verbose(`subsetting embedded fonts to charset "${literal(charset)}"`);
     /*  the theme tone (THEME-TONE) drives the layer-1 color spread
         variables and the PDF decoration colors  */
-    const tone = documentThemeTone(specification) ?? "#336699";
+    const tone = documentThemeTone(specification) ?? themeToneDefault;
     verbose(`generating theme color spreads (tone "${literal(tone)}")`);
     const colors = themeColors(tone);
     /*  the paper size (PAPER-SIZE) drives the PDF page setup and the

package/dst/specbook-coverage.js

@@ -17,7 +17,7 @@ const referrerIndex = (index) => {
         const chain = chainOf(index, object);
         const texts = [object.name, ...object.properties.map((p) => p.value)];
         if (object.description !== undefined)
-            texts.push(object.description.description, object.description.rationale ?? "");
+            texts.push(object.description.description, object.description.rationale ?? "", object.description.elaboration ?? "");
         for (const text of texts)
             for (const m of plainText(text).matchAll(referenceRegex)) {
                 const target = resolveUnique(index, m[1].trim(), object).target;

package/dst/specbook-diagram.d.ts

@@ -15,7 +15,7 @@ export interface DiagramResult {
 }
 export declare const specDiagrams: (specification: Spec, config: Schema) => Map<SpecObject, DiagramResult>;
 export declare const omittedDiagrams: (specification: Spec, config: Schema, omit: Set<OmitAspect>) => Set<SpecObject>;
-export declare const renderDiagrams: (specification: Spec, config: Schema, verbose?: Verbose, omit?: Set<"diagram:graph" | "diagram:hub" | "diagram:grid" | "diagram:1" | "diagram:2" | "diagram:3" | "text:long">) => Promise<Map<SpecObject, DiagramResult & {
+export declare const renderDiagrams: (specification: Spec, config: Schema, 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<SpecObject, DiagramResult & {
     svg: string;
 }>>;
 export declare const validateDiagrams: (ctx: ParseContext, specification: Spec, config: Schema) => void;

package/dst/specbook-diagram.js

@@ -180,6 +180,8 @@ const deriveReferenceEdges = (ctx, diagram, nodes, nodeSet) => {
                 texts.push({ text: object.description.description });
                 if (object.description.rationale !== undefined)
                     texts.push({ text: object.description.rationale });
+                if (object.description.elaboration !== undefined)
+                    texts.push({ text: object.description.elaboration });
             }
             for (const { text, name } of texts)
                 for (const m of plainText(text).matchAll(referenceRegex)) {
@@ -512,7 +514,8 @@ const deriveNodes = (index, object, diagram, errors) => {
     const nodes = new Array();
     const walk = (o) => {
         nodes.push(o);
-        o.children.forEach(walk);
+        for (const child of o.children)
+            walk(child);
     };
     walk(object);
     return nodes;
@@ -600,14 +603,17 @@ const deriveDiagram = (ctx, object, diagram) => {
     }
     /*  the "onlyConnected" filtering keeps only the nodes with at
         least one incident edge (sensible for "graph" diagrams only),
-        and the container nodes, whose members connect them  */
+        and the containers enclosing such a node  */
     if (diagram.onlyConnected === true && type === "graph") {
         const connected = new Set();
         for (const edge of edges) {
             connected.add(edge.source);
             connected.add(edge.target);
         }
-        nodes = nodes.filter((node) => connected.has(node) || nesting.containers.has(node));
+        for (const node of Array.from(connected))
+            for (let p = nesting.parentOf.get(node); p !== undefined; p = nesting.parentOf.get(p))
+                connected.add(p);
+        nodes = nodes.filter((node) => connected.has(node));
     }
     if (errors.length > 0)
         return { errors };

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

@@ -2,4 +2,4 @@ import type { Spec } from "./specbook-format-spec.js";
 import type { Schema } from "./specbook-format-schema.js";
 import type { Verbose } from "./specbook-verbose.js";
 export type AstFormat = "json" | "json5" | "yaml" | "toon";
-export declare const renderAst: (specification: Spec, format: AstFormat, config?: Schema, verbose?: Verbose, omit?: Set<"diagram:graph" | "diagram:hub" | "diagram:grid" | "diagram:1" | "diagram:2" | "diagram:3" | "text:long">) => Promise<Buffer>;
+export declare const renderAst: (specification: Spec, format: AstFormat, config?: Schema, 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<Buffer>;

package/dst/specbook-export-ast.js

@@ -10,17 +10,34 @@ import { specDiagrams, omittedDiagrams } from "./specbook-diagram.js";
 import { specCoverage } from "./specbook-coverage.js";
 import { buildLinkIndex } from "./specbook-link.js";
 import { collectSchemas } from "./specbook-parse-semantic.js";
-import { isTitleObject } from "./specbook-export-common.js";
-import { optimizeImages } from "./specbook-export-image.js";
+import { isTitleObject, imageDark } from "./specbook-export-common.js";
+import { optimizeImages, analyzeImages, isDocument } from "./specbook-export-image.js";
+import { renderEmbeddedDiagrams, embeddedSource, diagramKey } from "./specbook-export-diagram.js";
+import { darkMark, markDark } from "./specbook-parse-common.js";
 /*  render the specification AST into a serialization format,
     where "omit" names the aspects whose diagrams are left out  */
 export const renderAst = async (specification, format, config, verbose, omit = new Set()) => {
     /*  reduce the specification to plain JSON values (ISO date strings),
         with the embedded images (by far the bulk of the export)
-        optimized like the ones of the HTML export  */
+        optimized like the ones of the HTML export and the embedded
+        diagram source files replaced by their rendered SVGs (the light
+        variant), an image (a PDF page as its converted SVG) marked as
+        inverted where the "auto" detection inverts it, and an omitted or
+        failed diagram or PDF page leaving an empty entry, like an
+        unreadable file)  */
     const optimized = await optimizeImages(specification, false, verbose);
+    const rasters = await analyzeImages(specification, verbose);
+    const sources = await renderEmbeddedDiagrams(specification, verbose, omit);
     const plain = JSON.parse(JSON.stringify(specification, (key, value) => key !== "embedding" ? value :
-        value.map((content) => optimized.get(content) ?? content)));
+        value.map((content) => {
+            const diagram = embeddedSource(content);
+            if (diagram === undefined) {
+                const image = optimized.get(content) ?? (isDocument(content) ? "" : content);
+                return image !== "" && darkMark(image).dark === undefined
+                    && imageDark(content, rasters) === "invert" ? markDark(image, "invert") : image;
+            }
+            return sources.get(diagramKey(diagram.language, diagram.source))?.light ?? "";
+        })));
     /*  attach the Gradia specs of the diagram-configured objects as
         "diagram" fields onto the corresponding plain object nodes
         (an invalid diagram situation omits the diagram, as it is

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

@@ -0,0 +1,14 @@
+import { type Tokens } from "marked";
+import type { Spec } from "./specbook-format-spec.js";
+import { type Verbose } from "./specbook-verbose.js";
+export interface Listing {
+    lang: string;
+    source: string;
+    start: number;
+    mark: string;
+}
+export type ListingRenderer = (listing: Listing) => string;
+export declare const embeddedListing: (content: string) => Listing | undefined;
+export declare const fencedListing: (token: Tokens.Code) => Listing | undefined;
+export declare const listingFence: (listing: Listing) => string;
+export declare const prepareListings: (specification: Spec, verbose?: Verbose) => Promise<ListingRenderer>;

package/dst/specbook-export-code.js

@@ -0,0 +1,155 @@
+/*
+**  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 { codeLanguage, fenceInfo, markedLines } from "./specbook-parse-common.js";
+import { escapeHtml } from "./specbook-export-common.js";
+import { literal } from "./specbook-verbose.js";
+/*  decode an embedded source code file, which the parser loads as a base64
+    data: URL of its code MIME type (undefined for any other content)  */
+export const embeddedListing = (content) => {
+    const m = content.match(/^data:text\/x-code;lang=([^;,]+);start=(\d+)(?:;mark=([^;,]+))?;base64,(.*)$/s);
+    return m !== null ? {
+        lang: m[1],
+        source: Buffer.from(m[4], "base64").toString("utf8"),
+        start: Number(m[2]),
+        mark: decodeURIComponent(m[3] ?? "")
+    } : undefined;
+};
+/*  determine the code listing of a fenced code block (undefined for a
+    block of no or an unknown language, and for invalid parameters, which
+    the parser reports)  */
+export const fencedListing = (token) => {
+    const info = fenceInfo(token.lang);
+    const lang = codeLanguage(info.lang);
+    if (lang === undefined || info.error !== undefined)
+        return undefined;
+    return { lang, source: token.text, start: Number(info.params.start ?? "1"), mark: info.params.mark ?? "" };
+};
+/*  render a code listing back into a fenced code block, with its
+    parameters deviating from the defaults (the fence outgrowing the
+    longest backtick run of the source code)  */
+export const listingFence = (listing) => {
+    const run = Math.max(2, ...Array.from(listing.source.matchAll(/`+/g), (m) => m[0].length));
+    const fence = "`".repeat(run + 1);
+    const params = [listing.start !== 1 ? ` start=${listing.start}` : "",
+        listing.mark !== "" ? ` mark=${listing.mark}` : ""].join("");
+    return `${fence}${listing.lang}${params}\n${listing.source}\n${fence}`;
+};
+/*  the marker theme of the syntax highlighting: it maps the TextMate
+    scopes onto marker colors, which the rendering turns into the token
+    classes, so no color enters the HTML and the stylesheet alone colors
+    the tokens (the more specific scope wins, e.g. the string quotes
+    over the other punctuation, and the code embedded into a string
+    turns regular again)  */
+const tokenClasses = {
+    "#000001": "code-keyword",
+    "#000002": "code-literal",
+    "#000003": "code-comment"
+};
+const markerTheme = {
+    name: "specbook",
+    type: "light",
+    settings: [
+        { settings: { foreground: "#000000", background: "#ffffff" } },
+        { scope: ["keyword", "storage", "punctuation", "meta.brace", "variable.language", "entity.name.tag"],
+            settings: { foreground: "#000001" } },
+        { scope: ["string", "constant", "support.constant", "punctuation.definition.string"],
+            settings: { foreground: "#000002" } },
+        { scope: ["comment", "punctuation.definition.comment"],
+            settings: { foreground: "#000003" } },
+        { scope: ["meta.template.expression", "meta.embedded"],
+            settings: { foreground: "#000000" } }
+    ]
+};
+/*  the syntax highlighter, created on first use (with the JavaScript
+    regular expression engine, so no WebAssembly is needed) and loading
+    the grammars of the languages on demand  */
+let highlighter = null;
+/*  render a code listing into a "pre" block: one block-level line per
+    source line (marked ones carrying a class), whose number the stylesheet
+    draws from a counter (so it neither is copied nor searched), and the
+    highlighted tokens of a loaded language as token class spans (adjacent
+    tokens of the same class merged)  */
+const renderListing = (shiki, listing) => {
+    const tokens = shiki !== null && shiki.getLoadedLanguages().includes(listing.lang) ?
+        shiki.codeToTokensBase(listing.source, { lang: listing.lang, theme: markerTheme.name })
+            .map((line) => line.map((token) => ({ content: token.content, cls: tokenClasses[(token.color ?? "").toLowerCase()] }))) :
+        listing.source.split(/\r?\n/).map((line) => [{ content: line, cls: undefined }]);
+    const marks = markedLines(listing.mark);
+    const digits = String(listing.start + tokens.length - 1).length;
+    const lines = tokens.map((line, i) => {
+        const spans = new Array();
+        for (const token of line) {
+            const prev = spans.at(-1);
+            if (prev !== undefined && prev.cls === token.cls)
+                prev.content += token.content;
+            else
+                spans.push({ ...token });
+        }
+        return `<span class="line${marks.has(listing.start + i) ? " marked" : ""}">` +
+            spans.map((span) => span.cls !== undefined ?
+                `<span class="${span.cls}">${escapeHtml(span.content)}</span>` : escapeHtml(span.content)).join("") +
+            "</span>";
+    });
+    return `<pre class="listing" style="--listing-start: ${listing.start}; --listing-digits: ${digits}">` +
+        `<code>${lines.join("")}</code></pre>`;
+};
+/*  collect the languages of the code listings of an object and its
+    descendants: the fenced code blocks of a known language inside its
+    description statement and elaboration and the source code files
+    embedded into its description and property values  */
+const collect = (object, langs) => {
+    for (const text of [object.description?.description ?? "", object.description?.elaboration ?? ""])
+        marked.walkTokens(marked.lexer(text), (token) => {
+            const listing = token.type === "code" ? fencedListing(token) : undefined;
+            if (listing !== undefined)
+                langs.add(listing.lang);
+        });
+    const contents = [...object.description?.embedding ?? [],
+        ...object.properties.flatMap((property) => property.embedding ?? [])];
+    for (const content of contents) {
+        const listing = embeddedListing(content);
+        if (listing !== undefined)
+            langs.add(listing.lang);
+    }
+    for (const child of object.children)
+        collect(child, langs);
+};
+/*  prepare the rendering of the code listings of a specification: the
+    syntax highlighter is loaded (on first use) together with the grammars
+    of all languages used, as the Markdown rendering is synchronous, and
+    a failure to load is surfaced as a notice only, leaving the listings
+    of the affected languages unhighlighted  */
+export const prepareListings = async (specification, verbose) => {
+    const langs = new Set();
+    for (const artifact of specification.artifacts)
+        for (const object of artifact.objects)
+            collect(object, langs);
+    if (langs.size === 0)
+        return (listing) => renderListing(null, listing);
+    let shiki = null;
+    try {
+        highlighter ??= Promise.all([import("shiki/core"), import("shiki/engine/javascript")])
+            .then(([{ createHighlighterCore }, { createJavaScriptRegexEngine }]) => createHighlighterCore({ themes: [markerTheme], langs: [], engine: createJavaScriptRegexEngine() }));
+        shiki = await highlighter;
+    }
+    catch (err) {
+        highlighter = null;
+        verbose?.("loading syntax highlighter failed: " + (err instanceof Error ? err.message : String(err)));
+    }
+    if (shiki !== null) {
+        const { bundledLanguages } = await import("shiki/langs");
+        const missing = Array.from(langs).filter((lang) => !shiki.getLoadedLanguages().includes(lang));
+        for (const lang of missing)
+            await shiki.loadLanguage(bundledLanguages[lang]).catch((err) => {
+                verbose?.(`loading syntax highlighting of language "${literal(lang)}" failed: ` +
+                    (err instanceof Error ? err.message : String(err)));
+            });
+        verbose?.(`highlighting code listings of ${literal(langs.size)} language(s) ` +
+            `(${literal(missing.length)} newly loaded)`);
+    }
+    return (listing) => renderListing(shiki, listing);
+};

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

@@ -1,10 +1,10 @@
 import type { Spec, SpecObject } from "./specbook-format-spec.js";
-import { embeddingThemes } from "./specbook-parse-common.js";
+import { embeddingThemes, type DarkMark } from "./specbook-parse-common.js";
 export declare const escapeHtml: (text: string) => string;
 export declare const stylesheet: () => string;
 export declare const searchScript: () => string;
 export declare const fallbackLogo: (theme: (typeof embeddingThemes)[number]) => string;
-export declare const omitAspects: readonly ["diagram:graph", "diagram:hub", "diagram:grid", "diagram:1", "diagram:2", "diagram:3", "text:long"];
+export declare const omitAspects: readonly ["diagram:graph", "diagram:hub", "diagram:grid", "diagram:code", "diagram:image", "diagram:listing", "diagram:1", "diagram:2", "diagram:3", "text:long"];
 export type OmitAspect = typeof omitAspects[number];
 export declare const parseOmit: (omit?: string[]) => Set<OmitAspect>;
 export interface ExportOptions {
@@ -38,4 +38,6 @@ export declare const documentTitle: (specification: Spec) => {
     title: string;
     subtitle?: string;
 };
+export declare const svgInvertible: (svg: string) => boolean;
+export declare const imageDark: (content: string, rasters?: Map<string, boolean>) => DarkMark;
 export declare const documentLogo: (specification: Spec) => string;

package/dst/specbook-export-common.js

@@ -4,7 +4,7 @@
 **  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";
 /*  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;")
@@ -19,9 +19,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  */
@@ -129,7 +133,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 +227,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 +336,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>>;