@rse/specbook 0.9.2

package/dst/specbook-diagram.js

@@ -0,0 +1,271 @@
+/*
+**  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 { referenceRegex, buildLinkIndex, resolveUnique, resolveSet, anchorPaths } from "./specbook-link.js";
+/*  strip the inline code markup of a name or property value
+    (preserved in the AST for rendering) for labeling purposes  */
+const plainText = (text) => text.replace(/`/g, "");
+/*  strip a trailing parenthesized annotation from a
+    property key (e.g. "WHEN (Context)")  */
+const plainKey = (key) => key.replace(/\s*\([^)]*\)\s*$/, "").trim();
+/*  render a text as a Gradia atom: a bareword where possible
+    (no whitespace, no special characters, no "--"), a quoted
+    string otherwise  */
+const quoted = (text) => `"${text.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
+const atom = (text) => {
+    const plain = text.replace(/\s+/g, " ").trim();
+    return /^[^\s[\]():,">#]+$/.test(plain) && !plain.includes("--") ? plain : quoted(plain);
+};
+/*  render a text as a Gradia edge name or edge arity token
+    (each with its own, more lenient character set)  */
+const nameToken = (text) => /^[^\s()"]+$/.test(text) ? text : quoted(text);
+const arityToken = (text) => /^[^\s[\]"]+$/.test(text) ? text : quoted(text);
+/*  render a value as a Gradia "#config" directive value: a bareword
+    where possible, a quoted string otherwise (with the whitespace
+    collapsed, as a directive is a single line)  */
+const configValue = (value) => {
+    const text = String(value).replace(/\s+/g, " ").trim();
+    return /^\S+$/.test(text) ? text : quoted(text);
+};
+/*  derive the Gradia spec of a single object from its "diagram:"
+    schema configuration (the returned spec is absent whenever the
+    configured diagram situation is invalid)  */
+const deriveDiagram = (object, diagram, index, anchors, parents) => {
+    const type = diagram.type ?? "graph";
+    const errors = new Array();
+    /*  resolve a comma-separated "[[...]]" reference pattern string
+        into its (deduplicated, order-preserving) object match set  */
+    const resolvePatterns = (value, field) => {
+        const matches = new Array();
+        const seen = new Set();
+        for (const m of value.matchAll(referenceRegex)) {
+            const pattern = m[1].trim();
+            const set = resolveSet(index, pattern);
+            if (set.length === 0)
+                errors.push(`unresolvable diagram "${field}" pattern "[[${pattern}]]"`);
+            for (const match of set) {
+                if (!seen.has(match)) {
+                    seen.add(match);
+                    matches.push(match);
+                }
+            }
+        }
+        return matches;
+    };
+    /*  determine the node objects (default: the current object plus
+        all objects below it) and the edge objects (default: none),
+        with the edge objects never acting as nodes themselves  */
+    let nodes;
+    if (diagram.nodes !== undefined)
+        nodes = resolvePatterns(diagram.nodes, "nodes");
+    else {
+        nodes = new Array();
+        const walk = (o) => {
+            nodes.push(o);
+            o.childs.forEach(walk);
+        };
+        walk(object);
+    }
+    const edgeObjects = diagram.edges !== undefined ? resolvePatterns(diagram.edges, "edges") : [];
+    nodes = nodes.filter((node) => !edgeObjects.includes(node));
+    const nodeSet = new Set(nodes);
+    /*  derive the edges: from the "[[...]]" references of the node
+        objects (per the "links" selection) and from the edge objects by
+        convention (source: parent object, target: first reference in the
+        property values, name: object name, arity: "ARITY" property),
+        overridable via "edgeTarget"/"edgeArity" (a "grid" diagram is
+        edge-less by definition, so no edges are derived for it at all)  */
+    let edges = new Array();
+    if (type !== "grid") {
+        for (const node of nodes) {
+            const texts = node.properties.map((property) => property.value);
+            if (diagram.links === "all" && node.description !== undefined) {
+                texts.push(node.description.description);
+                if (node.description.rationale !== undefined)
+                    texts.push(node.description.rationale);
+            }
+            for (const text of texts)
+                for (const m of text.matchAll(referenceRegex)) {
+                    const target = resolveUnique(index, m[1].trim()).target;
+                    if (target !== undefined && target !== node && nodeSet.has(target))
+                        edges.push({ source: node, target });
+                }
+        }
+        for (const edgeObject of edgeObjects) {
+            const source = parents.get(edgeObject);
+            const value = diagram.edgeTarget !== undefined ?
+                edgeObject.properties.find((property) => plainKey(property.key) === diagram.edgeTarget)?.value :
+                edgeObject.properties.map((property) => property.value)
+                    .find((v) => /\[\[[^[\]]+\]\]/.test(v));
+            const reference = value?.match(/\[\[([^[\]]+)\]\]/)?.[1].trim();
+            const target = reference !== undefined ? resolveUnique(index, reference).target : undefined;
+            if (source === undefined) {
+                errors.push(`diagram edge object "${edgeObject.name}" has no parent object as source`);
+                continue;
+            }
+            if (target === undefined) {
+                errors.push(`diagram edge object "${edgeObject.name}" carries no resolvable target reference`);
+                continue;
+            }
+            if (!nodeSet.has(source) || !nodeSet.has(target))
+                continue;
+            const arity = edgeObject.properties.find((property) => plainKey(property.key) === (diagram.edgeArity ?? "ARITY"))?.value;
+            edges.push({ source, target, name: plainText(edgeObject.name),
+                arity: arity !== undefined ? plainText(arity) : undefined });
+        }
+        /*  derive the containment edges from the object hierarchy, as
+            the nesting of the objects carries no "[[...]]" reference  */
+        if (diagram.hierarchy === true)
+            for (const node of nodes) {
+                const parent = parents.get(node);
+                if (parent !== undefined && nodeSet.has(parent))
+                    edges.push({ source: parent, target: node });
+            }
+    }
+    else if (diagram.edges !== undefined)
+        errors.push("\"grid\" diagram cannot carry an \"edges\" configuration");
+    else if (diagram.hierarchy === true)
+        errors.push("\"grid\" diagram cannot carry a \"hierarchy\" configuration");
+    /*  deduplicate the edges (the same reference can occur in
+        multiple texts of the same node object)  */
+    const seenEdges = new Set();
+    edges = edges.filter((edge) => {
+        const key = `${anchors.get(edge.source)}\u0000${anchors.get(edge.target)}` +
+            `\u0000${edge.name ?? ""}\u0000${edge.arity ?? ""}`;
+        if (seenEdges.has(key))
+            return false;
+        seenEdges.add(key);
+        return true;
+    });
+    /*  determine the center object of a "hub" diagram: the current
+        object for the default "self" configuration, the uniquely
+        resolved object of an explicit "[[...]]" reference otherwise  */
+    let center = object;
+    if (type === "hub" && diagram.center !== undefined && diagram.center !== "self") {
+        const reference = diagram.center.match(/\[\[([^[\]]+)\]\]/)?.[1].trim();
+        const resolved = reference !== undefined ? resolveUnique(index, reference) : undefined;
+        if (resolved?.target === undefined) {
+            errors.push(`${resolved?.ambiguous === true ? "ambiguous" : "unresolvable"}` +
+                ` diagram "center" reference "${diagram.center}"`);
+            return { errors };
+        }
+        center = resolved.target;
+    }
+    /*  a "hub" diagram is the hub-projection onto its center object:
+        only the edges incident to the center and only the nodes
+        connected through them remain, with self-loops dropped, as
+        Gradia requires exactly this constrained topology  */
+    if (type === "hub") {
+        if (!nodeSet.has(center))
+            errors.push(`"hub" diagram center "${center.name}" is not part of the node set`);
+        else {
+            edges = edges.filter((edge) => (edge.source === center || edge.target === center)
+                && edge.source !== edge.target);
+            const connected = new Set([center]);
+            for (const edge of edges) {
+                connected.add(edge.source);
+                connected.add(edge.target);
+            }
+            nodes = nodes.filter((node) => connected.has(node));
+        }
+    }
+    /*  the "onlyConnected" filtering keeps only the nodes with at
+        least one incident edge (sensible for "graph" diagrams only)  */
+    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));
+    }
+    if (nodes.length === 0)
+        errors.push("diagram yields no nodes");
+    if (errors.length > 0)
+        return { errors };
+    /*  the "collapse" handling (enabled by default) silently omits a
+        degenerated diagram, consisting of a single node only, as such a
+        diagram carries no information beyond the object itself  */
+    if (diagram.collapse !== false && nodes.length === 1 && edges.length === 0)
+        return { errors };
+    /*  generate the Gradia spec text, opened by a "#type" directive and
+        the configured "#config" directives so every embedded spec is
+        self-contained: one node statement per object (the unique anchor
+        path as the node id, the object name as the displayed label)
+        and one edge statement per derived edge  */
+    const lines = [`#type ${type}`];
+    const config = diagram.config ?? {};
+    for (const key of Object.keys(config)) {
+        const value = config[key];
+        if (value !== undefined)
+            lines.push(`#config ${key} ${configValue(value)}`);
+    }
+    lines.push("");
+    for (const node of nodes) {
+        const anchor = anchors.get(node) ?? node.id;
+        const attrs = [`url: ${atom(`#${anchor}`)}`];
+        if (diagram.qualified === true && node.kind !== "")
+            attrs.push(`type: ${atom(node.kind)}`);
+        if (type === "hub" ? node === center : node.primary === true)
+            attrs.push("primary: true");
+        lines.push(`${atom(anchor)}: ${atom(plainText(node.name))} [ ${attrs.join(", ")} ]`);
+    }
+    if (edges.length > 0) {
+        lines.push("");
+        for (const edge of edges) {
+            const op = "--" +
+                (edge.name !== undefined && edge.name !== "" ? `(${nameToken(edge.name)})--` : "") + ">" +
+                (edge.arity !== undefined && edge.arity !== "" ? `[${arityToken(edge.arity)}]` : "");
+            lines.push(`${atom(anchors.get(edge.source) ?? edge.source.id)} ${op} ` +
+                atom(anchors.get(edge.target) ?? edge.target.id));
+        }
+    }
+    return { spec: lines.join("\n") + "\n", errors };
+};
+/*  collect the objects whose schema configuration carries a "diagram:"
+    field (the schema resolution mirrors the semantic validation)  */
+const collectDiagrams = (specification, config) => {
+    const diagrams = new Map();
+    const walk = (object, schema) => {
+        if (schema.diagram !== undefined)
+            diagrams.set(object, schema.diagram);
+        for (const child of object.childs) {
+            const childSchema = (schema.childs ?? []).find((c) => c.kind === child.kind);
+            if (childSchema !== undefined)
+                walk(child, childSchema);
+        }
+    };
+    for (const artifact of specification.artifacts) {
+        for (const object of artifact.objects) {
+            const schema = config.find((s) => (s.kind === object.kind && s.id === object.id) || `${s.kind}-${s.id}` === object.id) ??
+                config.find((s) => (s.name ?? "").toUpperCase() === plainText(object.name).toUpperCase());
+            if (schema !== undefined)
+                walk(object, schema);
+        }
+    }
+    return diagrams;
+};
+/*  derive the Gradia specs of all diagram-configured objects
+    of a specification  */
+export const specDiagrams = (specification, config) => {
+    const index = buildLinkIndex(specification);
+    const anchors = anchorPaths(index);
+    const parents = new Map();
+    for (const node of index)
+        parents.set(node.object, node.parent?.object);
+    const results = new Map();
+    for (const [object, diagram] of collectDiagrams(specification, config))
+        results.set(object, deriveDiagram(object, diagram, index, anchors, parents));
+    return results;
+};
+/*  validate all configured diagrams of a specification, reporting
+    every invalid diagram situation as a file/line-precise diagnostic  */
+export const validateDiagrams = (ctx, specification, config) => {
+    for (const [object, result] of specDiagrams(specification, config)) {
+        const meta = ctx.objectMeta.get(object) ?? { file: "", line: 1 };
+        for (const error of result.errors)
+            ctx.diagnose(meta.file, meta.line, `invalid diagram on ${object.kind} "${object.name}": ${error}`);
+    }
+};

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

@@ -0,0 +1,4 @@
+import type { Specification } from "./specbook-struct-spec.js";
+import type { SchemaSpecification } from "./specbook-struct-schema.js";
+export type AstFormat = "json" | "json5" | "yaml" | "toon";
+export declare const renderAst: (specification: Specification, format: AstFormat, config?: SchemaSpecification) => Promise<Buffer>;

package/dst/specbook-export-ast.js

@@ -0,0 +1,36 @@
+/*
+**  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 JSON5 from "json5";
+import { stringify as stringifyYaml } from "yaml";
+import { encode as encodeToon } from "@toon-format/toon";
+import { specDiagrams } from "./specbook-diagram.js";
+/*  render the specification AST into a serialization format  */
+export const renderAst = async (specification, format, config) => {
+    /*  reduce the specification to plain JSON values (ISO date strings)  */
+    const plain = JSON.parse(JSON.stringify(specification));
+    /*  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
+        already reported as a lint diagnostic)  */
+    if (config !== undefined) {
+        const diagrams = specDiagrams(specification, config);
+        const walk = (object, node) => {
+            const result = diagrams.get(object);
+            if (result?.spec !== undefined)
+                node.diagram = result.spec;
+            object.childs.forEach((child, i) => walk(child, node.childs[i]));
+        };
+        specification.artifacts.forEach((artifact, i) => artifact.objects.forEach((object, j) => walk(object, plain.artifacts[i].objects[j])));
+    }
+    if (format === "json")
+        return Buffer.from(JSON.stringify(plain, null, 4) + "\n", "utf8");
+    else if (format === "json5")
+        return Buffer.from(JSON5.stringify(plain, null, 4) + "\n", "utf8");
+    else if (format === "yaml")
+        return Buffer.from(stringifyYaml(plain), "utf8");
+    else
+        return Buffer.from(encodeToon(plain) + "\n", "utf8");
+};

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

@@ -0,0 +1,33 @@
+import type { Specification, Object as SpecObject } from "./specbook-struct-spec.js";
+export declare const escapeHtml: (text: string) => string;
+export declare const stylesheet: () => string;
+export declare const searchScript: () => string;
+export declare const fallbackLogo: () => string;
+export declare const isTitleObject: (object: SpecObject) => boolean;
+export declare const documentLang: (specification: Specification) => string | undefined;
+export declare const documentCharset: (specification: Specification) => string | undefined;
+export declare const documentThemeStyle: (specification: Specification) => string | undefined;
+export declare const documentThemeTone: (specification: Specification) => string | undefined;
+export type PaperSetup = {
+    unit: "mm" | "in";
+    height: number;
+    margin: {
+        top: number;
+        bottom: number;
+        left: number;
+        right: number;
+    };
+};
+export declare const paperSizes: string[];
+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: Specification) => string;
+export declare const paperStylesheet: (paper: string) => string;
+export declare const charsetCodepoints: (charset: string) => number[] | undefined;
+export declare const subsetStylesheet: (charset?: string) => Promise<string>;
+export declare const documentTitle: (specification: Specification) => {
+    title: string;
+    subtitle?: string;
+};
+export declare const documentLogo: (specification: Specification) => string;

package/dst/specbook-export-common.js

@@ -0,0 +1,142 @@
+/*
+**  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 path from "node:path";
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+/*  escape a text for embedding into template HTML  */
+export const escapeHtml = (text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+/*  provide the build-time pre-assembled stylesheet (with the
+    font faces already inlined as base64 data: URIs)  */
+export const stylesheet = () => fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "specbook-export-html.css"), "utf8");
+/*  provide the build-time bundled client-side fuzzy search script  */
+export const searchScript = () => fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "specbook-export-html-search.js"), "utf8");
+/*  provide the build-time bundled fallback logo of SpecBook itself
+    (as a self-contained data: URL, to keep its styles isolated)  */
+export const fallbackLogo = () => "data:image/svg+xml;base64," + fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "specbook-export-logo.svg")).toString("base64");
+/*  check whether an object is the specification title object  */
+export const isTitleObject = (object) => object.kind === "META" && object.name.toUpperCase() === "TITLE";
+/*  determine a property value of the title object  */
+const titleProperty = (specification, name) => specification.artifacts.flatMap((artifact) => artifact.objects).find(isTitleObject)
+    ?.properties.find((property) => property.key === name)?.value;
+/*  determine the document language (LANG) from the title object  */
+export const documentLang = (specification) => titleProperty(specification, "LANG")?.trim();
+/*  determine the document character set (CHARSET) from the title object  */
+export const documentCharset = (specification) => titleProperty(specification, "CHARSET")?.trim();
+/*  determine the document theme style (THEME-STYLE) from the title object  */
+export const documentThemeStyle = (specification) => titleProperty(specification, "THEME-STYLE")?.trim();
+/*  determine the document theme color tone (THEME-TONE) from the title object  */
+export const documentThemeTone = (specification) => titleProperty(specification, "THEME-TONE")?.trim();
+/*  the supported paper sizes for print: ISO A4 in millimeters and the
+    two US sizes closest to it in inches, each with the default margins
+    of 1in (25mm) at the top/bottom and 0.8in (20mm) at the left/right  */
+const papers = {
+    "A4": { unit: "mm", height: 297, margin: { top: 25, bottom: 25, left: 20, right: 20 } },
+    "Letter": { unit: "in", height: 11, margin: { top: 1, bottom: 1, left: 0.8, right: 0.8 } },
+    "Legal": { unit: "in", height: 14, margin: { top: 1, bottom: 1, left: 0.8, right: 0.8 } }
+};
+export const paperSizes = Object.keys(papers);
+export const paperSizeDefault = "A4";
+/*  provide the setup of a paper size, falling back onto the default  */
+export const paperSetup = (paper) => papers[paper] ?? papers[paperSizeDefault];
+/*  render a paper dimension as its CSS length  */
+export const paperLength = (setup, value) => `${value}${setup.unit}`;
+/*  determine the document paper size (PAPER-SIZE) from the title object,
+    matched case-insensitively and falling back onto the default  */
+export const documentPaperSize = (specification) => {
+    const value = titleProperty(specification, "PAPER-SIZE")?.trim().toLowerCase();
+    return paperSizes.find((name) => name.toLowerCase() === value) ?? paperSizeDefault;
+};
+/*  provide the paper-dependent print stylesheet: a diagram is scaled
+    down to still fit onto a single page (the paper height less the
+    print margins and the own vertical margins of the diagram) and is
+    never broken across a page boundary  */
+export const paperStylesheet = (paper) => {
+    const setup = paperSetup(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)} - 2rem);` +
+        " width: auto; height: auto; }\n" +
+        "}\n";
+};
+/*  generate a contiguous codepoint range  */
+const range = (from, to) => Array.from({ length: to - from + 1 }, (_, i) => from + i);
+/*  the codepoints of US-ASCII and ISO-8859-1 (ISO Latin 1), plus the
+    ISO-8859-15 (ISO Latin 9) revision, which replaces eight Latin 1
+    codepoints with the Euro sign and the missing French/Finnish letters  */
+const codepointsAscii = range(0x20, 0x7E);
+const codepointsLatin1 = [...codepointsAscii, ...range(0xA0, 0xFF)];
+const codepointsLatin9 = [
+    ...codepointsLatin1.filter((cp) => ![0xA4, 0xA6, 0xA8, 0xB4, 0xB8, 0xBC, 0xBD, 0xBE].includes(cp)),
+    0x20AC, 0x160, 0x161, 0x17D, 0x17E, 0x152, 0x153, 0x178
+];
+/*  map a charset name (under its usual aliases) onto its codepoints,
+    with the full Unicode charsets mapping onto undefined (no subsetting)  */
+export const charsetCodepoints = (charset) => {
+    const name = charset.toLowerCase().replace(/[^a-z0-9]+/g, "");
+    if (name === "ascii" || name === "usascii")
+        return codepointsAscii;
+    else if (name === "iso88591" || name === "isolatin1" || name === "latin1")
+        return codepointsLatin1;
+    else if (name === "iso885915" || name === "isolatin15" || name === "latin15"
+        || name === "isolatin9" || name === "latin9")
+        return codepointsLatin9;
+    else if (name === "utf8" || name === "utf16" || name === "unicode")
+        return undefined;
+    throw new Error(`unknown charset "${charset}" ` +
+        "(expected US-ASCII, ISO-8859-1/ISO-Latin-1, ISO-8859-15/ISO-Latin-15, or UTF-8)");
+};
+/*  the symbol glyphs used by the HTML/PDF rendering (kind and property
+    bullets, link symbol, primary marker, theme switch icon, anchor
+    symbol plus its text presentation variation selector, and the
+    search field clearing icon)  */
+const symbolGlyphs = [0x25CF, 0x25CB, 0x26AD, 0x2318, 0x25D0, 0x2693, 0xFE0E, 0x00D7];
+/*  the typographic glyphs producible by the smart typography rendering
+    (language-specific quotes, dashes, ellipsis, bullet, nbsp)  */
+const typographyGlyphs = [
+    0x00A0, 0x00AB, 0x00BB, 0x2013, 0x2014, 0x2018, 0x2019,
+    0x201A, 0x201C, 0x201D, 0x201E, 0x2022, 0x2026, 0x2039, 0x203A
+];
+/*  provide the stylesheet with its embedded fonts subsetted to the
+    codepoints of a charset plus the always-used symbol and typography
+    glyphs (no charset or a full Unicode charset keeps the fonts complete)  */
+export const subsetStylesheet = async (charset) => {
+    const css = stylesheet();
+    if (charset === undefined)
+        return css;
+    const codepoints = charsetCodepoints(charset);
+    if (codepoints === undefined)
+        return css;
+    const { default: subsetFont } = await import("subset-font");
+    const text = String.fromCodePoint(...codepoints, ...symbolGlyphs, ...typographyGlyphs);
+    let result = "";
+    let last = 0;
+    for (const m of css.matchAll(/url\("data:font\/woff2;base64,([^"]+)"\)/g)) {
+        const subset = await subsetFont(Buffer.from(m[1], "base64"), text, { targetFormat: "woff2" });
+        result += css.slice(last, m.index) +
+            `url("data:font/woff2;base64,${subset.toString("base64")}")`;
+        last = m.index + m[0].length;
+    }
+    return result + css.slice(last);
+};
+/*  determine the document title and subtitle from the title object  */
+export const documentTitle = (specification) => {
+    const object = specification.artifacts.flatMap((artifact) => artifact.objects).find(isTitleObject);
+    const prop = (name) => object?.properties.find((property) => property.key === name)?.value;
+    return { title: prop("TITLE") ?? object?.name ?? "Specification", subtitle: prop("SUBTITLE") };
+};
+/*  determine the document logo as a self-contained data: URL, taken from the
+    embedded image of the LOGO property of the title object, and falling back
+    onto the built-in SpecBook logo (for use in isolated rendering contexts,
+    like the print header/footer, which load no external resources)  */
+export const documentLogo = (specification) => {
+    const object = specification.artifacts.flatMap((artifact) => artifact.objects).find(isTitleObject);
+    const content = object?.properties.find((property) => property.key === "LOGO")?.embedding?.[0];
+    if (content === undefined)
+        return fallbackLogo();
+    return content.startsWith("data:") ? content :
+        `data:image/svg+xml;base64,${Buffer.from(content, "utf8").toString("base64")}`;
+};