@rse/specbook 1.3.2 → 1.4.1

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

@@ -1,3 +1,5 @@
 import type { Spec } from "./specbook-format-spec.js";
 import { type Verbose } from "./specbook-verbose.js";
+export declare const isDocument: (content: string) => boolean;
 export declare const optimizeImages: (specification: Spec, print: boolean, verbose?: Verbose) => Promise<Map<string, string>>;
+export declare const analyzeImages: (specification: Spec, verbose?: Verbose) => Promise<Map<string, boolean>>;

package/dst/specbook-export-image.js

@@ -3,6 +3,13 @@
 **  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
+import * as path from "node:path";
+import { createRequire } from "node:module";
+import { embeddedSource } from "./specbook-export-diagram.js";
+import { embeddedListing } from "./specbook-export-code.js";
+import { svgInvertible } from "./specbook-export-common.js";
+import { darkMark, markDark, pdfType } from "./specbook-parse-common.js";
+import { plainText } from "./specbook-link.js";
 import { literal } from "./specbook-verbose.js";
 /*  the pixel width the raster images are capped to: the 60rem content
     width of the document (at 16px per rem) at a 2x device pixel ratio  */
@@ -19,6 +26,73 @@ const imageCaches = {
     screen: new Map(),
     print: new Map()
 };
+/*  whether an embedded content is a page of a PDF document, which is
+    converted into an SVG image and then treated exactly like one  */
+export const isDocument = (content) => darkMark(content).content.startsWith(`data:${pdfType};`);
+/*  render the selected page of a PDF document (given as its embedding
+    data: URL carrying the 1-based "page" parameter, the first by default)
+    with PDF.js onto an SVG canvas of @napi-rs/canvas, i.e. as vector
+    graphics with the glyphs drawn as outlines, where PDF.js takes the
+    standard fonts, CMaps, ICC profiles, and WebAssembly decoders of
+    non-self-contained documents from its own package  */
+const renderPdf = async (content) => {
+    const page = Number(content.match(/^data:[^,]*?;page=(\d+)[;,]/)?.[1] ?? "1");
+    const data = content.slice(content.indexOf(",") + 1);
+    const { getDocument } = await import("pdfjs-dist/legacy/build/pdf.mjs");
+    const { createCanvas, SvgExportFlag } = await import("@napi-rs/canvas");
+    const dir = path.dirname(createRequire(import.meta.url).resolve("pdfjs-dist/package.json"));
+    const task = getDocument({ data: new Uint8Array(Buffer.from(data, "base64")), verbosity: 0,
+        standardFontDataUrl: `${dir}/standard_fonts/`, cMapUrl: `${dir}/cmaps/`,
+        iccUrl: `${dir}/iccs/`, wasmUrl: `${dir}/wasm/` });
+    try {
+        const doc = await task.promise;
+        if (page < 1 || page > doc.numPages)
+            throw new Error(`document has no page ${page}`);
+        const sheet = await doc.getPage(page);
+        const viewport = sheet.getViewport({ scale: 1 });
+        const canvas = createCanvas(Math.ceil(viewport.width), Math.ceil(viewport.height), SvgExportFlag.NoPrettyXML);
+        await sheet.render({ viewport,
+            canvas: canvas,
+            canvasContext: canvas.getContext("2d") }).promise;
+        return canvas.getContent().toString("utf8");
+    }
+    finally {
+        await task.destroy();
+    }
+};
+/*  the in-memory cache of the SVG renderings of the embedded PDF pages
+    (null for a failed one), keyed by their plain embedded content and
+    swept to the pages of the latest conversion, like the optimized images  */
+let documentCache = new Map();
+/*  convert the embedded PDF pages of a specification into SVG images,
+    served from the cache where possible, where a rendering failure (e.g.
+    an absent page) is surfaced as a notice only and omits the page  */
+const convertDocuments = async (specification, verbose) => {
+    const cache = new Map();
+    const walk = async (object) => {
+        const contents = [...object.description?.embedding ?? [],
+            ...object.properties.flatMap((property) => property.embedding ?? [])];
+        for (const plain of contents.filter(isDocument).map((content) => darkMark(content).content)) {
+            if (cache.has(plain))
+                continue;
+            let svg = documentCache.get(plain);
+            if (svg === undefined)
+                svg = await renderPdf(plain).catch((err) => {
+                    verbose?.(`rendering PDF page of ${object.kind} "${literal(plainText(object.name))}" failed: ` +
+                        (err instanceof Error ? err.message : String(err)));
+                    return null;
+                });
+            cache.set(plain, svg);
+        }
+        for (const child of object.children)
+            await walk(child);
+    };
+    for (const artifact of specification.artifacts)
+        for (const object of artifact.objects)
+            await walk(object);
+    documentCache = cache;
+    return cache;
+};
 /*  optimize a single SVG image with SVGO (the identifiers and classes
     are free to be minified, as the image is rendered in isolation
     through an <img> element), after stripping the "content" attribute
@@ -63,19 +137,23 @@ const optimizeRaster = async (content, print) => {
     return `data:${type};base64,${data.toString("base64")}`;
 };
 /*  collect the embedded image contents of an object and its descendants
-    (the empty entries of the unreadable files left out)  */
+    (the empty entries of the unreadable files, the embedded diagram
+    sources, which are rendered instead, and the embedded source code
+    files, which are listed instead, left out)  */
+const isImage = (content) => content !== "" && embeddedSource(content) === undefined && embeddedListing(content) === undefined;
 const collect = (object, contents) => {
     for (const content of object.description?.embedding ?? [])
-        if (content !== "")
+        if (isImage(content))
             contents.add(content);
     for (const property of object.properties)
         for (const content of property.embedding ?? [])
-            if (content !== "")
+            if (isImage(content))
                 contents.add(content);
     for (const child of object.children)
         collect(child, contents);
 };
-/*  optimize the embedded images of a specification for the HTML export
+/*  optimize the embedded images of a specification (the PDF pages as
+    their converted SVGs, a failed one left out) for the HTML export
     (the screen) or the PDF export (print), yielding the map from the
     embedded image contents onto their optimized ones, served from the
     cache where possible: an optimization which fails (an image the
@@ -83,7 +161,9 @@ const collect = (object, contents) => {
     for) or which does not shrink the image keeps the original, so the
     export never depends on it  */
 export const optimizeImages = async (specification, print, verbose) => {
-    /*  collect the distinct embedded image contents of the specification  */
+    /*  collect the distinct embedded image contents of the specification
+        and convert its PDF pages  */
+    const documents = await convertDocuments(specification, verbose);
     const medium = print ? "print" : "screen";
     const contents = new Set();
     for (const artifact of specification.artifacts)
@@ -97,20 +177,29 @@ export const optimizeImages = async (specification, print, verbose) => {
     let before = 0;
     let after = 0;
     for (const content of contents) {
+        const plain = darkMark(content);
+        const document = isDocument(content) ? documents.get(plain.content) ?? null : undefined;
+        if (document === null)
+            continue;
         let optimized = imageCaches[medium].get(content);
         if (optimized !== undefined)
             cached++;
         else {
             try {
-                optimized = content.startsWith("data:") ?
-                    await optimizeRaster(content, print) : await optimizeSvg(content);
+                /*  an image marked with its treatment on the dark theme is
+                    optimized plain and marked again, a PDF page as its SVG  */
+                optimized = document !== undefined ? await optimizeSvg(document) :
+                    plain.content.startsWith("data:") ?
+                        await optimizeRaster(plain.content, print) : await optimizeSvg(plain.content);
+                if (plain.dark !== undefined)
+                    optimized = markDark(optimized, plain.dark);
             }
             catch (err) {
                 verbose?.("optimizing image failed (keeping the original): " +
                     (err instanceof Error ? err.message : String(err)));
-                optimized = content;
+                optimized = document !== undefined ? document : content;
             }
-            if (optimized.length >= content.length)
+            if (document === undefined && optimized.length >= content.length)
                 optimized = content;
         }
         cache.set(content, optimized);
@@ -127,3 +216,66 @@ export const optimizeImages = async (specification, print, verbose) => {
             `${literal(Math.round(before / 1024))} KB -> ${literal(Math.round(after / 1024))} KB`);
     return cache;
 };
+/*  the in-memory cache of the "auto" judgements of the raster images,
+    keyed by the embedded image content and swept to the images of the
+    latest analysis, exactly like the optimized images  */
+let rasterCache = new Map();
+/*  whether a raster image (given as a base64 data: URL) is most likely
+    dark ink on a transparent or light canvas and hence safe to invert on
+    the dark theme ("dark=auto"), judged on a downscaled copy of its
+    pixels: at least 60% of them are transparent or near-white (the
+    canvas), the others (the ink) exist, are dark on average, and consist
+    of a few colors only (the quantized colors holding at least 2% of the
+    ink cover at least 85% of it), unlike a photo or a colorful screenshot  */
+const rasterInvertible = async (content) => {
+    const m = content.match(/^data:image\/(?:png|jpeg|webp);base64,(.*)$/s);
+    if (m === null)
+        return false;
+    const { default: sharp } = await import("sharp");
+    const { data, info } = await sharp(Buffer.from(m[1], "base64"))
+        .resize({ width: 128, height: 128, fit: "inside", withoutEnlargement: true })
+        .ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+    let canvas = 0;
+    let ink = 0;
+    let luma = 0;
+    const bins = new Map();
+    for (let p = 0; p < data.length; p += info.channels) {
+        const [r, g, b, a] = [data[p], data[p + 1], data[p + 2], data[p + 3]];
+        if (a < 32 || Math.min(r, g, b) >= 235)
+            canvas++;
+        else {
+            ink++;
+            luma += (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255;
+            const bin = ((r >> 5) << 6) | ((g >> 5) << 3) | (b >> 5);
+            bins.set(bin, (bins.get(bin) ?? 0) + 1);
+        }
+    }
+    const few = Array.from(bins.values()).filter((n) => n >= ink * 0.02).reduce((sum, n) => sum + n, 0);
+    return ink > 0 && canvas / (canvas + ink) >= 0.6 && luma / ink < 0.6 && few >= ink * 0.85;
+};
+/*  judge the raster images and PDF pages of a specification without an
+    explicit treatment on the dark theme for the "auto" one, yielding the
+    map from their embedded contents onto whether they are invertible,
+    served from the cache where possible (an image Sharp cannot process
+    and a failed PDF page count as not invertible), where a PDF page is
+    judged on its converted SVG like an SVG image  */
+export const analyzeImages = async (specification, verbose) => {
+    const documents = await convertDocuments(specification, verbose);
+    const contents = new Set();
+    for (const artifact of specification.artifacts)
+        for (const object of artifact.objects)
+            collect(object, contents);
+    const cache = new Map();
+    for (const content of contents) {
+        if (!content.startsWith("data:") || darkMark(content).dark !== undefined)
+            continue;
+        if (isDocument(content)) {
+            const document = documents.get(content);
+            cache.set(content, typeof document === "string" && svgInvertible(document));
+        }
+        else
+            cache.set(content, rasterCache.get(content) ?? await rasterInvertible(content).catch(() => false));
+    }
+    rasterCache = new Map(Array.from(cache).filter(([content]) => !isDocument(content)));
+    return cache;
+};

package/dst/specbook-export-md.js

@@ -5,9 +5,11 @@
 */
 import * as path from "node:path";
 import { specDiagrams } from "./specbook-diagram.js";
-import { becauseRegex, embeddingRegex, embeddingCount } from "./specbook-parse-common.js";
-import { isTitleObject } from "./specbook-export-common.js";
-import { optimizeImages } from "./specbook-export-image.js";
+import { becauseRegex, embeddingRegex, embeddingCount, darkMark, markDark } from "./specbook-parse-common.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 { embeddedListing, listingFence } from "./specbook-export-code.js";
 /*  format a timestamp in the frontmatter format  */
 export const formatTimestamp = (date) => {
     const pad = (n) => String(n).padStart(2, "0");
@@ -27,9 +29,11 @@ const renderKeyValuesMd = (properties, indent = "") => {
     a ";" would split the segment, and a value carrying the rationale
     marker would not be taken for a property at all on re-parsing  */
 const segmentableMd = (property) => !property.value.includes(";") && !becauseRegex.test(property.value);
-/*  render a description statement with its optional rationale  */
+/*  render a description statement with its optional rationale and
+    its optional elaboration blocks  */
 const renderDescriptionMd = (description) => description.description + (description.rationale !== undefined ?
-    `, BECAUSE ${description.rationale}` : "");
+    `, BECAUSE ${description.rationale}` : "") + (description.elaboration !== undefined ?
+    `\n\n${description.elaboration}` : "");
 /*  render the "(*)" primary marker plus the implicit "(xxx)"
     and/or explicit "{{xxx}}" anchor suffix  */
 const nameSuffixMd = (object) => (object.primary === true ? " (*)" : "") +
@@ -119,10 +123,22 @@ export const renderMarkdown = async (specification, config, rebase, verbose) =>
         export: an embeddable "![alt](file)" becomes the reference-style
         "![alt][img-N]", whose "[img-N]: data:..." definition ends the
         document (a "{theme}" one takes its light variant, as Markdown
-        knows no themes), and only the remaining ones are re-based  */
+        knows no themes), an embedded diagram source file becomes its
+        rendered SVG (the light variant, too, marked as inverted on the
+        dark theme where the diagram is), where every emitted SVG is marked
+        with its resolved treatment on the dark theme (an adapting diagram
+        flattened onto its light variant as the "auto" detection judges
+        it), so a re-parse keeps it, even where the "auto" detection would
+        judge a re-optimized SVG differently, an embedded source code file
+        of a description leaves its markup for a fenced code block collected
+        into "fences" (and one of a property value becomes a "data:"
+        definition, too), and only the remaining ones (including a failed
+        diagram) are re-based  */
     const optimized = await optimizeImages(specification, false, verbose);
+    const rasters = await analyzeImages(specification, verbose);
+    const sources = await renderEmbeddedDiagrams(specification, verbose);
     const labels = new Map();
-    const embedMd = (text, embedding, from, to) => {
+    const embedMd = (text, embedding, from, to, fences) => {
         let i = 0;
         const embedded = text.replace(embeddingRegex, (match, alt, reference) => {
             const count = embeddingCount(reference);
@@ -130,9 +146,24 @@ export const renderMarkdown = async (specification, config, rebase, verbose) =>
             i += count;
             if (content === undefined || content === "")
                 return match;
-            const image = optimized.get(content) ?? content;
-            const url = image.startsWith("data:") ? image :
-                `data:image/svg+xml;base64,${Buffer.from(image, "utf8").toString("base64")}`;
+            const listing = embeddedListing(content);
+            if (listing !== undefined && fences !== undefined) {
+                fences.push(listingFence(listing));
+                return "";
+            }
+            else if (listing !== undefined) {
+                const label = labels.get(content) ?? `img-${labels.size + 1}`;
+                labels.set(content, label);
+                return `![${alt}][${label}]`;
+            }
+            const diagram = embeddedSource(content);
+            const variants = diagram !== undefined ? sources.get(diagramKey(diagram.language, diagram.source)) : undefined;
+            const light = diagram !== undefined ? variants?.light :
+                optimized.get(content) ?? (isDocument(content) ? undefined : content);
+            if (light === undefined)
+                return match;
+            const url = diagram !== undefined ? markDark(light, imageDark(light)) :
+                markDark(darkMark(light).content, imageDark(content, rasters));
             const label = labels.get(url) ?? `img-${labels.size + 1}`;
             labels.set(url, label);
             return `![${alt}][${label}]`;
@@ -148,9 +179,26 @@ export const renderMarkdown = async (specification, config, rebase, verbose) =>
             properties: object.properties.map((property) => ({ ...property, value: embedMd(property.value, property.embedding ?? [], from, to) })),
             children: object.children.map((child) => embedObjectMd(child, from, to))
         };
-        if (object.description !== undefined)
+        if (object.description !== undefined) {
+            /*  the embeddings of the elaboration follow those of the statement,
+                and the fenced code blocks of the embedded source code files
+                end the elaboration  */
+            const embedding = object.description.embedding ?? [];
+            const skip = Array.from(object.description.description.matchAll(embeddingRegex))
+                .reduce((sum, m) => sum + embeddingCount(m[2]), 0);
+            const fences = new Array();
             clone.description = { ...object.description,
-                description: embedMd(object.description.description, object.description.embedding ?? [], from, to) };
+                description: embedMd(object.description.description, embedding, from, to, fences) };
+            if (object.description.elaboration !== undefined)
+                clone.description.elaboration = embedMd(object.description.elaboration, embedding.slice(skip), from, to, fences);
+            if (fences.length > 0) {
+                /*  the removed markups leave no empty paragraphs behind  */
+                const collapse = (text) => text.replace(/\n[ \t]*(?:\n[ \t]*)+\n/g, "\n\n").trim();
+                clone.description.description = collapse(clone.description.description);
+                clone.description.elaboration = [collapse(clone.description.elaboration ?? ""), ...fences]
+                    .filter((block) => block !== "").join("\n\n");
+            }
+        }
         const spec = diagrams.get(object);
         if (spec !== undefined)
             diagrams.set(clone, spec);

package/dst/specbook-format-schema.d.ts

@@ -68,7 +68,7 @@ export type SchemaDiagram = {
     config?: Partial<GradiaConfig>;
 };
 export type SchemaFormat = {
-    type?: "auto" | "complex" | "concise";
+    type?: "auto" | "complex" | "compact" | "concise";
     maxTableColumns?: number;
     maxCellHeight?: number;
     withUnusedProps?: boolean;

package/dst/specbook-format-schema.js

@@ -80,7 +80,7 @@ const SchemaDiagram = v.strictObject({
     config: v.optional(SchemaDiagramConfig)
 });
 const SchemaFormat = v.strictObject({
-    type: v.optional(v.picklist(["auto", "complex", "concise"])),
+    type: v.optional(v.picklist(["auto", "complex", "compact", "concise"])),
     maxTableColumns: v.optional(v.pipe(v.number(), v.integer(), v.minValue(2))),
     maxCellHeight: v.optional(v.pipe(v.number(), v.integer(), v.minValue(0))),
     withUnusedProps: v.optional(v.boolean())

package/dst/specbook-format-spec.d.ts

@@ -21,6 +21,7 @@ export type SpecObject = {
 export type SpecDescription = {
     description: string;
     rationale?: string;
+    elaboration?: string;
     embedding?: string[];
 };
 export type SpecProperty = {

package/dst/specbook-format-spec.js

@@ -15,6 +15,7 @@ const SpecProperty = v.object({
 const SpecDescription = v.object({
     description: v.string(),
     rationale: v.optional(v.string()),
+    elaboration: v.optional(v.string()),
     embedding: v.optional(v.array(v.string()))
 });
 const SpecObject = v.object({