@rse/specbook 1.3.2 → 1.4.1

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
@@ -321,6 +324,10 @@ validated (an unknown entry or a wrongly typed value fails the command),
 and both an explicitly supplied option and its environment variable
 win over its entry.
 
+`specbook init` creates such a file in the current working directory
+(unless one already applies), so the options of the initialization
+stick for all subsequent commands.
+
 The default value of every CLI option `--xxx` can be overridden
 by a corresponding `SPECBOOK_XXX` environment variable (e.g.
 `SPECBOOK_BASEDIR`, `SPECBOOK_CONFIG`, `SPECBOOK_OUTPUT`,
@@ -419,7 +426,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.d.ts

@@ -28,6 +28,10 @@ export interface ProjectOptions {
     basedir?: string;
     cwd?: string;
 }
+export interface InitResult {
+    files: string[];
+    project?: string;
+}
 export interface ExportRequest extends ProjectOptions {
     formats?: ExportFormat[];
     realtime?: boolean;
@@ -46,7 +50,7 @@ export declare class SpecBook {
     private project;
     private configFiles;
     private requireConfig;
-    init(options: ProjectOptions): Promise<string[]>;
+    init(options: ProjectOptions): Promise<InitResult>;
     lint(options: ProjectOptions & {
         gitignore?: boolean;
     }): Promise<LintResult>;

package/dst/specbook-api.js

@@ -8,7 +8,7 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { glob } from "glob";
 import { loadConfig, configStatistics } from "./specbook-config.js";
-import { loadProject, projectFile } from "./specbook-project.js";
+import { loadProject, writeProject, projectFile } from "./specbook-project.js";
 import { renderDiagnostic, renderDiagnosticVerbose } from "./specbook-diagnostic.js";
 import { initSpecification } from "./specbook-cmd-init.js";
 import { lint } from "./specbook-cmd-lint.js";
@@ -62,6 +62,7 @@ export class SpecBook {
         const given = (value) => options.cwd !== undefined ? path.resolve(cwd, value) : value;
         const derived = (value) => options.cwd !== undefined ? value : path.relative(cwd, value) || ".";
         return {
+            file: project?.file,
             config: config !== undefined && config.length > 0 ?
                 config.map((pattern) => pattern === "std" ? pattern : given(pattern)) :
                 project?.config?.map((pattern) => pattern === "std" ? pattern : derived(pattern)),
@@ -105,13 +106,24 @@ export class SpecBook {
             `and ${literal(stats.links)} link relationship(s)`);
         return config;
     }
-    /*  initialize the configured specification artifact files
-        below the base directory  */
+    /*  initialize the configured specification artifact files below the
+        base directory and persist the effective project options into a
+        new project configuration file in the working directory, unless
+        one already applies (as a new one would shadow it)  */
     async init(options) {
         const verbose = this.verboseOf("init");
         const project = this.project(options, verbose);
-        return initSpecification({ config: this.requireConfig(await this.configFiles(project.config), verbose),
+        const files = initSpecification({ config: this.requireConfig(await this.configFiles(project.config), verbose),
             basedir: project.basedir ?? ".", verbose });
+        if (project.file !== undefined) {
+            verbose(`skipping existing project configuration "${literal(project.file)}"`);
+            return { files };
+        }
+        const cwd = path.resolve(options.cwd ?? ".");
+        const relative = (value) => path.relative(cwd, path.resolve(cwd, value)) || ".";
+        const file = writeProject(cwd, project.config?.map((pattern) => pattern === "std" ? pattern : relative(pattern)) ?? ["std"], relative(project.basedir ?? "."));
+        verbose(`created project configuration "${literal(file)}"`);
+        return { files, project: options.cwd !== undefined ? file : path.relative(process.cwd(), file) };
     }
     /*  lint the specification Markdown files below the base directory,
         where "gitignore" treats an artifact file Git excludes from its
@@ -125,10 +137,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 +176,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-cli.js

@@ -130,15 +130,18 @@ withVerboseOption(program.command("mcp"))
     verboseOf(opts)("mcp", "starting MCP server on stdio", "notice");
     await serveMcp(verboseOf(opts, "mcp"));
 });
-/*  the init command creates the configured artifact files  */
+/*  the init command creates the configured artifact files and,
+    unless one already applies, the project configuration file  */
 withCommonOptions(program.command("init"))
     .description("initialize the configured specification artifact files below the base directory")
     .action(async (opts) => {
     const specbook = new SpecBook({ verbose: verboseOf(opts) });
-    const created = await specbook.init({ config: configOf(opts), basedir: opts.basedir });
-    await writeStdout(created.length > 0 ?
-        `initialized artifact file(s): ${created.join(", ")}\n` :
-        "no artifact files were created\n");
+    const result = await specbook.init({ config: configOf(opts), basedir: opts.basedir });
+    await writeStdout((result.files.length > 0 ?
+        `initialized artifact file(s): ${result.files.join(", ")}\n` :
+        "no artifact files were created\n") +
+        (result.project !== undefined ?
+            `created project configuration file: ${result.project}\n` : ""));
 });
 /*  the lint command reports all diagnostics and fails on any error  */
 withGitignoreOption(withCommonOptions(program.command("lint")))

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-cmd-init.js

@@ -7,8 +7,22 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { literal } from "./specbook-verbose.js";
 import { formatTimestamp } from "./specbook-export-md.js";
+import { titleProperties } from "./specbook-export-common.js";
+/*  render the property list of the title artifact, seeding the properties
+    the exports interpret themselves with their rendering defaults (as far
+    as the schema configures them, as any other is reported as unknown)  */
+const titleList = (artifact) => {
+    if (artifact.kind !== "META" || artifact.name?.toUpperCase() !== "TITLE")
+        return "";
+    const props = titleProperties.filter((prop) => artifact.props?.some((p) => p.name === prop.name) === true);
+    if (props.length === 0)
+        return "";
+    const width = Math.max(...props.map((prop) => prop.name.length)) + 2;
+    return props.map((prop) => `-   ${`${prop.name}:`.padEnd(width)}${prop.init}`.trimEnd() + "\n").join("") + "\n";
+};
 /*  initialize the configured specification artifact files below the
-    base directory with their frontmatter and artifact headings, where
+    base directory with their frontmatter and artifact headings (plus
+    the title properties), where
     all artifacts configured onto the same file reside in it side by
     side, following each other on level 1  */
 export const initSpecification = (options) => {
@@ -38,7 +52,7 @@ export const initSpecification = (options) => {
         const headings = artifacts.map((artifact) => {
             const name = artifact.name ?? "";
             const paren = artifact.id !== undefined ? ` (${artifact.id})` : "";
-            return `#   ${artifact.kind}: ${name}${paren}\n\n`;
+            return `#   ${artifact.kind}: ${name}${paren}\n\n` + titleList(artifact);
         }).join("");
         const text = "---\n" +
             `Created:  ${now}\n` +

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)) {
@@ -342,14 +344,10 @@ const deriveCenter = (ctx, object, diagram, nodes, nodeSet, errors) => {
                 return undefined;
             }
             centerUrl = `#${anchors.get(source) ?? source.id}`;
-            if (centerCfg.property !== undefined) {
-                const value = propValue(parenProps, source, centerCfg.property);
-                if (value === undefined) {
-                    errors.push({ reason: `diagram "center" source lacks the property "${centerCfg.property}"` });
-                    return undefined;
-                }
+            const value = centerCfg.property !== undefined ?
+                propValue(parenProps, source, centerCfg.property) : undefined;
+            if (value !== undefined)
                 label = plainText(expandReferences(value, (ref) => resolveUnique(index, ref, source).target?.name ?? ref));
-            }
             else if (label === undefined)
                 label = plainText(source.name);
         }
@@ -512,7 +510,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 +599,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 {
@@ -31,6 +31,10 @@ export declare const paperSizeDefault = "A4";
 export declare const paperSetup: (paper: string) => PaperSetup;
 export declare const paperLength: (setup: PaperSetup, value: number) => string;
 export declare const documentPaperSize: (specification: Spec) => string;
+export declare const titleProperties: {
+    name: string;
+    init: string;
+}[];
 export declare const paperStylesheet: (paper: string) => string;
 export declare const charsetCodepoints: (charset: string) => number[] | undefined;
 export declare const subsetStylesheet: (charset?: string) => Promise<string>;
@@ -38,4 +42,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;