@rse/specbook 1.3.1 → 1.4.0

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({

package/dst/specbook-format.md

@@ -123,7 +123,7 @@ type SchemaDiagram = {
     config?:           Partial<GradiaConfig>
 }
 type SchemaFormat = {
-    type?:             "auto" | "complex" | "concise"
+    type?:             "auto" | "complex" | "compact" | "concise"
     maxTableColumns?:  number
     maxCellHeight?:    number
     withUnusedProps?:  boolean
@@ -429,8 +429,9 @@ type SchemaGradiaConfig = Partial<{
     HTML/PDF rendering of the objects of an object kind among their siblings,
     BECAUSE one uniform rendering fits neither rich nor numerous objects
 
--   `SchemaFormat.type?: "auto" | "complex" | "concise"`:
-    rendering: `complex` (sections), `concise` (tables), or `auto`,
+-   `SchemaFormat.type?: "auto" | "complex" | "compact" | "concise"`:
+    rendering: `complex` (sections), `concise` (tables), `compact`
+    (tables of section-like cells), or `auto`,
     BECAUSE sections bury small objects, tables truncate rich ones
 
 -   `SchemaFormat.maxTableColumns?: number`:
@@ -649,15 +650,20 @@ how the HTML/PDF export renders the objects of that kind among their
 siblings, so that the sibling kinds below one parent can render
 differently (e.g. one kind as a table, another as sections). Its `type`
 selects the rendering: `complex` (nested sections), `concise` (one
-compact table of all sibling objects of the kind), or the default
-`auto`, which collapses only the deepest level into tables.
+compact table of all sibling objects of the kind), `compact` (one
+table of the name and a single cell per object, which renders the
+object like `complex`, but without its heading: diagram, properties as
+key/value lines, and description, for a kind whose many properties a
+table row cannot hold), or the default `auto`, which collapses only the
+deepest level into tables.
 
 Inside a `concise` table, unconfigured child kinds implicitly stay
 `concise` and render as sub-tables inside the description cells, while
 an explicitly configured `type` is always honored, even a `complex`
 rendering pressed into a cell. `maxTableColumns` (default: `4`) bounds
 the columns of the compact table of the kind (a wider group chunks
-its properties into embedded per-object tables), `maxCellHeight`
+its properties into embedded per-object tables, while a `compact`
+one ignores it), `maxCellHeight`
 (default: `40`) is the percentage a table cell of the kind may exceed
 the height of every other non-empty cell of its row before the HTML
 export folds its remaining text away, and `withUnusedProps`
@@ -702,6 +708,7 @@ type SpecObject = {
 type SpecDescription = {
     description:       string
     rationale?:        string
+    elaboration?:      string
     embedding?:        string[]
 }
 type SpecProperty = {
@@ -776,7 +783,7 @@ type SpecProperty = {
     BECAUSE a specification is a tree, not a flat list of statements
 
 -   `SpecDescription`:
-    description of an object: statement, rationale, and images,
+    description of an object: statement, rationale, elaboration, and images,
     BECAUSE the WHAT and the WHY are stored apart to be rendered apart
 
 -   `SpecDescription.description: string`:
@@ -785,11 +792,18 @@ type SpecProperty = {
 
 -   `SpecDescription.rationale?: string`:
     rationale text behind the `, BECAUSE ` split (the WHY),
+    up to the end of its paragraph,
     BECAUSE a statement without its WHY cannot be judged or revised
 
+-   `SpecDescription.elaboration?: string`:
+    blocks following the paragraph of the rationale (e.g. images or diagrams),
+    BECAUSE further content must not end up inside the WHY
+
 -   `SpecDescription.embedding?: string[]`:
-    image files embedded via `![xxx](yyy)`, inlined at parse time,
-    one entry per file in markup order (empty for an unreadable file),
+    image, diagram source, and source code files embedded via `![xxx](yyy)`,
+    inlined at parse time, one entry per file in markup order (those of
+    the statement first, those of the elaboration second, and empty for
+    an unreadable file),
     BECAUSE the exports have to stand alone, without the image files
 
 -   `SpecProperty`:
@@ -805,7 +819,8 @@ type SpecProperty = {
     BECAUSE constraints and references are checked against this text
 
 -   `SpecProperty.embedding?: string[]`:
-    image files embedded in the value, inlined at parse time,
+    image, diagram source, and source code files embedded in the value,
+    inlined at parse time,
     one entry per file in markup order (empty for an unreadable file),
     BECAUSE the exports have to stand alone, without the image files
 
@@ -992,10 +1007,15 @@ paragraphs, blockquotes, ordered lists (e.g. scenario steps or test
 case procedures), and fenced code blocks. A fenced code block of
 language `gradia` is skipped, as it is the derived diagram which
 **SpecBook** itself emits into exported Markdown and which must not
-become authored content on a re-parse. In the Concise Format, the
-description is formed by the non-property segments of the item, so a
-description carrying a `;` cannot be a segment either and forces its
-object into the Complex Format.
+become authored content on a re-parse. A fenced code block of language
+`mermaid` (alias `mmd`) or `d2` is a [Mermaid](https://mermaid.js.org/)
+or [D2](https://d2lang.com/) diagram, which the HTML/PDF export renders
+as a diagram instead of as code (see "Diagram Embeddings" below). A
+fenced code block of any other known language is a syntax-highlighted
+code listing (see "Code Listings" below). In
+the Concise Format, the description is formed by the non-property
+segments of the item, so a description carrying a `;` cannot be a
+segment either and forces its object into the Complex Format.
 
 A description is split into its *statement* and *rationale* at the first
 `, BECAUSE ` (or `, **BECAUSE** `) occurrence:
@@ -1005,10 +1025,25 @@ The event is created and configured but not visible to attendees,
 BECAUSE an event needs a private setup phase.
 ```
 
+The rationale ends with its paragraph: all blocks following it (further
+paragraphs, embedded images, and diagrams) form the *elaboration*, which
+is rendered below the statement and its rationale, so the description
+of a Complex Format object can state its WHAT and WHY first and
+illustrate them afterwards:
+
+````
+The event is created and configured but not visible to attendees,
+BECAUSE an event needs a private setup phase.
+
+![Event Lifecycle](event-lifecycle.mmd)
+````
+
 ### Wiki-Style References
 
 A `[[<reference/>]]` anywhere in a name, property value, description, or
-rationale is a Wiki-style reference to another object, which is checked
+rationale (except inside a fenced code block, whose code stays verbatim,
+so e.g. a shell test `[[ -f x ]]` is no reference) is a Wiki-style
+reference to another object, which is checked
 for unique resolvability and rendered as a hyperlink in the HTML/PDF
 exports. A reference is a `.`-separated path of segments, where each
 segment matches a single object as:
@@ -1046,7 +1081,21 @@ SVG files are inlined as-is; PNG/JPEG/WebP files are embedded as base64
 `data:` URLs. URLs and other file types are left untouched. The
 HTML/PDF export optimizes the embedded images on its own (downscaled
 and re-encoded PNG/JPEG/WebP, minified SVG), so the files can stay in their
-original resolution.
+original resolution. Like a diagram, an embedded image (except the logo
+of the title page) folds, maximizes, and is omitted (`-O diagram:image`,
+or by nesting level) in the HTML/PDF export, while the AST exports keep
+it.
+
+A page of a PDF document is embedded like an image --
+`![<alt/>](<file/>.pdf)` for the first page, or
+`![<alt/>](<file/>.pdf#page=<n/>)` for the 1-based page number `<n/>` --
+where the document is inlined at parse time. The exports convert the
+page through `pdfjs-dist` into a vector SVG with its texts as glyph
+outlines and then treat it exactly like an embedded SVG image, while a
+page failing to render (e.g. an absent page number) is omitted with a
+notice. A presentation (e.g. PowerPoint), a spreadsheet (e.g. Excel), or
+any other office document is embedded through its PDF export, which
+carries its exact rendering and fonts.
 
 A reference carrying the `{theme}` placeholder -- e.g.
 `![Logo](logo-{theme}.svg)` -- is a *theme-aware* embedding: it expands
@@ -1056,10 +1105,113 @@ HTML export shows just the variant matching the color theme currently
 active in the document, while the PDF export (like print in general)
 always uses the `light` variant.
 
+An image without a dark variant is treated on the dark theme of the HTML
+export as its `dark` fragment parameter says (see "Fragment Parameters"
+below), while print always keeps it as it is. An image defaults to
+`dark=auto`, which inverts it (with its hues rotated back) if it most
+likely draws dark lines onto a transparent or light canvas: an SVG if it
+neither adapts itself (via `light-dark()` colors, `prefers-color-scheme`
+rules, or a `color-scheme` declaration, which follows the color theme of
+the document anyway), nor embeds a raster image, nor paints a background
+which is not light, and a raster image (PNG/JPEG/WebP) if at least 60%
+of its pixels are transparent or near-white and the others are dark on
+average and of a few colors only (unlike a photo or a colorful
+screenshot). As the detection cannot tell a logo or illustration with
+brand colors from a line drawing, `#dark=none` keeps such an image as it
+is, while `#dark=invert` forces the inversion (e.g.
+`![Overview](overview.svg#dark=invert)`). A
+[draw.io](https://www.drawio.com/) diagram is best embedded as its
+editable SVG (`.drawio.svg`, which draw.io keeps current on every save)
+with its "Adaptive Colors" page setting on "Automatic", as it then
+adapts all its colors itself. A theme-aware embedding ignores the
+fragment, as its `dark` variant already serves the dark theme.
+
 The reference-style image `![<alt/>][<label/>]` embeds the image of its
 definition `[<label/>]: data:image/<type/>;base64,<data/>` (SVG, PNG,
-JPEG, or WebP) in the same file, the only supported link definition.
+JPEG, or WebP, where a `;dark=invert` or `;dark=none` parameter behind
+the type carries the treatment on the dark theme, which the export
+always resolves for an SVG) in the same file, the only supported link
+definition.
 This is the form the normalized Markdown export emits for every embedded
 image (a theme-aware one by its `light` variant), with the definitions
 at the end of the document, so it stands alone without the image files.
 Author the inline form; the reference-style one is for re-parsing only.
+
+### Diagram Embeddings
+
+A [Mermaid](https://mermaid.js.org/) or [D2](https://d2lang.com/)
+diagram is either written inline into a description as a fenced code
+block of language `mermaid` (alias `mmd`) or `d2`, or kept in a file of
+its own and embedded like an image -- `![<alt/>](<file/>.mmd)`,
+`![<alt/>](<file/>.mermaid)`, or `![<alt/>](<file/>.d2)` -- inside a
+description or property value, where its source is inlined at parse time.
+The HTML/PDF export renders every such diagram (Mermaid through
+`beautiful-mermaid`, D2 through `@terrastruct/d2`) in the theme colors of
+the document, once per color theme, like a theme-aware image. It folds,
+maximizes, and is omitted (`-O diagram:code`, for diagrams as code, or
+by nesting level) like a derived Gradia diagram. A diagram failing to render
+is omitted with a notice. The normalized Markdown and the AST exports
+carry the source of a fenced diagram as part of the description, and an
+embedded diagram file as its rendered SVG (the `light` variant).
+
+### Code Listings
+
+A code snippet is either written inline into a description as a fenced
+code block of a known language (any language id or alias of
+[Shiki](https://shiki.style/), like `ts`, `java`, `css`, or `html`), or
+kept in a source code file of its own and embedded like an image --
+`![<alt/>](<file/>.<ext/>)`, where `<ext/>` is such a language id or
+alias (e.g. `.ts`, `.java`, `.css`, `.html`) -- inside a description or
+property value, where its source is inlined at parse time. A fenced code
+block of no or an unknown language stays plain preformatted text.
+
+The HTML/PDF export renders every such snippet as a *code listing* in
+DejaVu Sans Mono, with line numbers and with its keywords, operators,
+and punctuation in the accent color and bold, its literals in the signal
+color, and its comments in the dim color and italic. A code listing
+folds, maximizes, and is omitted (`-O diagram:listing`, or by nesting
+level) like a diagram.
+
+A fenced code listing takes whitespace-separated parameters behind its
+language, and an embedded one takes them as its fragment (see "Fragment
+Parameters" below):
+
+-   `start=<n/>` (fenced only): the number of the first line (default `1`).
+-   `lines=<a/>-<b/>` or `lines=<a/>` (embedded only): the excerpt of the
+    1-based lines `<a/>` to `<b/>` (or line `<a/>` alone), numbered from
+    `<a/>`, where an empty range is reported as an error.
+-   `mark=<a/>[-<b/>][,...]`: the lines or line ranges to mark (in the
+    shown line numbers) on a very light signal background.
+
+````
+```ts start=10 mark=12-13
+const greeter = new Greeter("World")
+```
+
+![Greeter Class](greeter.ts#lines=5-20&mark=8,12-14)
+````
+
+The AST exports carry an embedded source code file as its
+`data:text/x-code;lang=<lang/>;start=<n/>[;mark=<hunks/>];base64,<data/>`
+URL, while the normalized Markdown export turns one of a description into
+a fenced code block (with its `start` and `mark` parameters) at the end
+of the elaboration, and keeps one of a property value as a
+reference-style image definition of that URL.
+
+#### Fragment Parameters
+
+The fragment of an embedding reference is a list of `<key/>=<value/>`
+parameters joined by `&`, in any order and each at most once, with the
+values optionally URI-encoded (e.g. `%20` for a space): `page`
+(documents), `dark` (documents and images), and `lines` and `mark`
+(source code files, see "Code Listings" above). A fragment carrying any
+other key or an invalid value is reported as an error. The `dark`
+parameter selects the treatment on the dark theme of the HTML export,
+while print always shows the original: `dark=invert` inverts the
+embedding with its hues rotated back, `dark=none` shows it as it is, and
+`dark=auto` (the default) decides by the content of the image or the
+rendered document page (inverting a light canvas with dark ink, but
+neither a dark one nor one carrying a photo), as an image and a document
+page can be anything (line drawings, photos, logos); e.g.
+`![<alt/>](<file/>.pdf#page=3&dark=none)` keeps a page which the
+detection would invert, but whose colors have to stay.