@rse/specbook 1.2.15 → 1.2.16

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

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

package/dst/specbook-export-image.js

@@ -0,0 +1,121 @@
+/*
+**  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 { 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  */
+const maxWidth = 60 * 16 * 2;
+/*  the lossy encoding quality of the re-encoded raster images  */
+const quality = 85;
+/*  the in-memory caches of the optimized images (one per target medium,
+    as the two optimize a PNG differently), keyed by the embedded image
+    content and swept to the images of the latest optimization for the
+    medium, so they serve the repeated renderings of a process (watch,
+    preview, MCP, and the passes and formats of a single export) without
+    growing over a long-running one  */
+const imageCaches = {
+    screen: new Map(),
+    print: new Map()
+};
+/*  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
+    draw.io leaves on the root element: it carries the entire
+    entity-escaped diagram source, which is needless for the rendering
+    and exceeds the entity limit of the SVGO parser (an SVG which SVGO
+    still rejects stays just stripped)  */
+const optimizeSvg = async (content) => {
+    const stripped = content.replace(/(<svg\b[^>]*?)\s+content="[^"]*"/, "$1");
+    try {
+        const { optimize } = await import("svgo");
+        return optimize(stripped, { multipass: true }).data;
+    }
+    catch {
+        return stripped;
+    }
+};
+/*  optimize a single raster image given as a base64 data: URL with
+    Sharp: an image wider than the cap is downscaled and a JPEG stays a
+    JPEG, while a PNG is converted to WebP for the screen and to JPEG
+    for print, as Chromium passes just this format through into the PDF
+    unchanged and embeds every other one losslessly (as JPEG knows no
+    transparency, the image is flattened onto the white of the paper); a
+    WebP is treated like a PNG, but for the screen one within the cap
+    stays untouched, as re-encoding it again would just degrade it  */
+const optimizeRaster = async (content, print) => {
+    const m = content.match(/^data:(image\/(?:png|jpeg|webp));base64,(.*)$/s);
+    if (m === null)
+        return content;
+    const { default: sharp } = await import("sharp");
+    const source = sharp(Buffer.from(m[2], "base64"));
+    if (m[1] === "image/webp" && !print && ((await source.metadata()).width ?? 0) <= maxWidth)
+        return content;
+    const image = source
+        .rotate()
+        .resize({ width: maxWidth, withoutEnlargement: true });
+    const webp = m[1] !== "image/jpeg" && !print;
+    const data = webp ?
+        await image.webp({ quality }).toBuffer() :
+        await image.flatten({ background: "#ffffff" }).jpeg({ quality, mozjpeg: true }).toBuffer();
+    const type = webp ? "image/webp" : "image/jpeg";
+    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)  */
+const collect = (object, contents) => {
+    for (const content of object.description?.embedding ?? [])
+        if (content !== "")
+            contents.add(content);
+    for (const property of object.properties)
+        for (const content of property.embedding ?? [])
+            if (content !== "")
+                contents.add(content);
+    for (const child of object.children)
+        collect(child, contents);
+};
+/*  optimize the embedded images of a specification 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
+    libraries cannot process, or a platform Sharp provides no binary
+    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) => {
+    const medium = print ? "print" : "screen";
+    const contents = new Set();
+    for (const artifact of specification.artifacts)
+        for (const object of artifact.objects)
+            collect(object, contents);
+    const cache = new Map();
+    let cached = 0;
+    let before = 0;
+    let after = 0;
+    for (const content of contents) {
+        let optimized = imageCaches[medium].get(content);
+        if (optimized !== undefined)
+            cached++;
+        else {
+            try {
+                optimized = content.startsWith("data:") ?
+                    await optimizeRaster(content, print) : await optimizeSvg(content);
+            }
+            catch {
+                optimized = content;
+            }
+            if (optimized.length >= content.length)
+                optimized = content;
+        }
+        cache.set(content, optimized);
+        before += content.length;
+        after += optimized.length;
+    }
+    imageCaches[medium] = cache;
+    if (contents.size > 0)
+        verbose?.((cached === contents.size ?
+            `reusing ${literal(cached)} cached image(s) for ${medium}: ` :
+            `optimizing ${literal(contents.size)} image(s) for ${medium} (${literal(cached)} cached): `) +
+            `${literal(Math.round(before / 1024))} KB -> ${literal(Math.round(after / 1024))} KB`);
+    return cache;
+};

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

@@ -1,3 +1,9 @@
-import type { Spec } from "./specbook-format-spec.js";
+import type { Spec, SpecArtifact } from "./specbook-format-spec.js";
 import type { Schema } from "./specbook-format-schema.js";
-export declare const renderMarkdown: (specification: Spec, config?: Schema) => string;
+import type { Verbose } from "./specbook-verbose.js";
+export declare const formatTimestamp: (date: Date) => string;
+export interface MarkdownRebase {
+    origins: Map<SpecArtifact, string>;
+    dir: string;
+}
+export declare const renderMarkdown: (specification: Spec, config?: Schema, rebase?: MarkdownRebase, verbose?: Verbose) => Promise<string>;

package/dst/specbook-export-md.js

@@ -3,11 +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 { specDiagrams } from "./specbook-diagram.js";
-import { becauseRegex } from "./specbook-parse-common.js";
+import { becauseRegex, embeddingRegex, embeddingCount } from "./specbook-parse-common.js";
 import { isTitleObject } from "./specbook-export-common.js";
+import { optimizeImages } from "./specbook-export-image.js";
 /*  format a timestamp in the frontmatter format  */
-const formatTimestamp = (date) => {
+export const formatTimestamp = (date) => {
     const pad = (n) => String(n).padStart(2, "0");
     return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ` +
         `${pad(date.getHours())}:${pad(date.getMinutes())}`;
@@ -91,8 +93,19 @@ const renderObjectMd = (object, level, diagrams) => {
         parts.push(...object.children.map((child) => renderObjectMd(child, level + 1, diagrams)));
     return parts.filter((part) => part !== "").join("\n\n");
 };
-/*  render the entire specification into normalized Markdown  */
-export const renderMarkdown = (specification, config) => {
+/*  re-base the local relative image references of a text from the
+    directory of their source file onto the one of the output file  */
+const rebaseMd = (text, from, to) => text.replace(embeddingRegex, (match, alt, reference) => {
+    const file = reference?.trim();
+    if (file === undefined || /^[a-z][a-z0-9+.-]+:/i.test(file) || path.isAbsolute(file))
+        return match;
+    const rebased = path.relative(to, path.resolve(from, file)).split(path.sep).join("/");
+    return `![${alt}](${rebased})`;
+});
+/*  render the entire specification into normalized Markdown, embedding
+    the images (so the export stands alone) and optionally re-basing the
+    remaining image references onto the output directory  */
+export const renderMarkdown = async (specification, config, rebase, verbose) => {
     /*  derive the Gradia specs of the diagram-configured objects
         (an invalid diagram situation omits the diagram, as it is
         already reported as a lint diagnostic, and the diagram of
@@ -102,6 +115,54 @@ export const renderMarkdown = (specification, config) => {
         for (const [object, result] of specDiagrams(specification, config))
             if (result.spec !== undefined && !isTitleObject(object))
                 diagrams.set(object, result.spec);
+    /*  embed the images of a text, optimized like the ones of the HTML
+        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  */
+    const optimized = await optimizeImages(specification, false, verbose);
+    const labels = new Map();
+    const embedMd = (text, embedding, from, to) => {
+        let i = 0;
+        const embedded = text.replace(embeddingRegex, (match, alt, reference) => {
+            const count = embeddingCount(reference);
+            const content = count > 0 ? embedding[i] : undefined;
+            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 label = labels.get(url) ?? `img-${labels.size + 1}`;
+            labels.set(url, label);
+            return `![${alt}][${label}]`;
+        });
+        return from !== undefined && to !== undefined && from !== to ?
+            rebaseMd(embedded, from, to) : embedded;
+    };
+    /*  embed and re-base on clones of the objects (as the AST is shared
+        with the other exports), moving the diagrams along  */
+    const localized = (object, from, to) => {
+        const clone = {
+            ...object,
+            properties: object.properties.map((property) => ({ ...property, value: embedMd(property.value, property.embedding ?? [], from, to) })),
+            children: object.children.map((child) => localized(child, from, to))
+        };
+        if (object.description !== undefined)
+            clone.description = { ...object.description,
+                description: embedMd(object.description.description, object.description.embedding ?? [], from, to) };
+        const spec = diagrams.get(object);
+        if (spec !== undefined)
+            diagrams.set(clone, spec);
+        return clone;
+    };
+    const objects = specification.artifacts.flatMap((artifact) => {
+        const origin = rebase?.origins.get(artifact);
+        const from = origin !== undefined ? path.resolve(path.dirname(origin)) : undefined;
+        const to = rebase !== undefined ? path.resolve(rebase.dir) : undefined;
+        return artifact.objects.map((object) => localized(object, from, to));
+    });
+    const definitions = Array.from(labels, ([url, label]) => `[${label}]: ${url}\n`).join("");
     /*  the single frontmatter block (only recognized at the start of a
         file on re-parse) carries the earliest creation and the latest
         modification timestamp of all artifacts  */
@@ -111,6 +172,6 @@ export const renderMarkdown = (specification, config) => {
         `Created:  ${formatTimestamp(created)}\n` +
         `Modified: ${formatTimestamp(modified)}\n` +
         "---\n\n" +
-        specification.artifacts.flatMap((artifact) => artifact.objects)
-            .map((object) => renderObjectMd(object, 1, diagrams)).join("\n\n") + "\n";
+        objects.map((object) => renderObjectMd(object, 1, diagrams)).join("\n\n") + "\n" +
+        (definitions !== "" ? `\n${definitions}` : "");
 };

package/dst/specbook-export-pdf.js

@@ -13,6 +13,7 @@ const anchorPages = async (pdf) => {
     const doc = await PDFDocument.load(pdf);
     const indexes = new Map();
     doc.getPages().forEach((page, index) => indexes.set(page.ref.toString(), index + 1));
+    /*  map every named destination onto the page number of its target  */
     const pages = new Map();
     const dests = doc.catalog.lookupMaybe(PDFName.of("Dests"), PDFDict);
     if (dests !== undefined) {
@@ -46,7 +47,7 @@ const addOutline = async (doc, entries) => {
                 targets.set(name.decodeText(), dest);
         }
     }
-    const resolve = (entries) => entries.flatMap((entry) => {
+    const resolve = (list) => list.flatMap((entry) => {
         const dest = targets.get(entry.anchor);
         const children = resolve(entry.children);
         return dest !== undefined ? [{ title: entry.title, dest, children }] : children;
@@ -56,9 +57,9 @@ const addOutline = async (doc, entries) => {
         return;
     /*  recursively materialize the outline items, wiring up the
         Parent/Prev/Next/First/Last cross-references of the tree  */
-    const materialize = (items, parent) => {
-        const refs = items.map(() => context.nextRef());
-        items.forEach((item, i) => {
+    const materialize = (list, parent) => {
+        const refs = list.map(() => context.nextRef());
+        list.forEach((item, i) => {
             const children = item.children.length > 0 ? materialize(item.children, refs[i]) : undefined;
             context.assign(refs[i], context.obj({
                 Title: PDFHexString.fromText(item.title),
@@ -163,6 +164,8 @@ const resolveBrowser = async (verbose) => {
             `"${literal("SPECBOOK_BROWSER")}"`);
         return options;
     }
+    /*  prefer the downloaded Playwright Chromium and
+        else probe a system-installed Google Chrome  */
     let executable = "";
     try {
         executable = chromium.executablePath();

package/dst/specbook-format.md

@@ -151,6 +151,9 @@ type SchemaGradiaConfig = Partial<{
     "color-node-ghost-name":     string
     "color-node-ghost-box":      string
     "color-node-ghost-border":   string
+    "color-node-self-name":      string
+    "color-node-self-box":       string
+    "color-node-self-border":    string
     "color-group-name":          string
     "color-group-box":           string
     "color-group-border":        string
@@ -251,11 +254,13 @@ type SchemaGradiaConfig = Partial<{
     livelocks are ruled out
 
 -   `SchemaObject.diagram?: SchemaDiagram`:
-    diagram generated for every object of this kind,
+    diagram generated for every object of this kind (left out when the
+    configuration is emitted compressed by level 2 or higher),
     BECAUSE relations buried in references are graspable only when drawn
 
 -   `SchemaObject.format?: SchemaFormat`:
-    HTML/PDF rendering format of the objects of this kind,
+    HTML/PDF rendering format of the objects of this kind (left out when
+    the configuration is emitted compressed by level 2 or higher),
     BECAUSE rich objects need sections, uniform ones read as tables
 
 -   `SchemaObject.props?: SchemaProperty[]`:
@@ -417,7 +422,7 @@ type SchemaGradiaConfig = Partial<{
     BECAUSE the node name alone rarely makes the nodes comparable
 
 -   `SchemaDiagram.config?: SchemaGradiaConfig`:
-    arbitrary Gradia rendering options (e.g. `grid-columns-max: 5`),
+    arbitrary Gradia rendering options (e.g. `grid-columns-max: 2`),
     BECAUSE layout tuning is cosmetics, not a schema concern
 
 -   `SchemaFormat`:
@@ -498,7 +503,8 @@ type SchemaGradiaConfig = Partial<{
     BECAUSE an embedded font renders alike where it is not installed
 
 -   `SchemaGradiaConfig."color-node-*": string`:
-    colors of the node boxes in their regular, primary, and ghost role,
+    colors of the node boxes in their regular, primary, ghost, and self
+    role,
     BECAUSE the role of a node has to be readable at a glance
 
 -   `SchemaGradiaConfig."color-group-*", "color-edge-*": string`:
@@ -557,7 +563,9 @@ that kind. Its `type` selects the diagram shape (`graph`, `hub`, or
 `grid`), `nodes` and `edges` select the participating objects through
 comma-separated `[[xxx]]` reference patterns (`nodes` defaults to the
 object itself plus all objects below it), and `center` names the object
-a `hub` is projected onto (default: `self`).
+a `hub` is projected onto (default: `self`). An edge object of the
+center targeting the center itself (a self-reference) places the center
+a second time among its outputs, rendered as a dashed "self" node.
 
 Instead of naming an existing object, `center` can also declare a
 *synthetic* center node, which represents something no specification
@@ -577,7 +585,15 @@ node only, `qualified` labels every node with its object kind,
 `properties` lists the property names whose values are attached to the
 nodes as key/value annotations (with every `[[xxx]]` reference stripped
 to its target object name), and `config` passes arbitrary Gradia
-rendering options (e.g. `grid-columns-max: 5`) through to the diagram.
+rendering options (e.g. `grid-columns-max: 2`) through to the diagram.
+As the Gradia defaults are dimensioned for a stand-alone canvas,
+SpecBook presets a compact geometry for every diagram, which `config`
+overrides: `size-canvas-margin: 8`, `size-node-height-scale: 2`,
+`hub-node-gap: 10`, `hub-node-count-max: 6` (a `hub` column of more
+nodes wraps into two staggered sub-columns), `grid-gap-horizontal: 24`,
+`grid-gap-vertical: 12`, and `grid-columns-min: 4` (the square
+derivation of the column count otherwise leaves a third of the document
+width unused).
 
 `ordered` replaces the layered layout of a `graph` by the document
 order of the objects: the top-level nodes stack top-down in that order
@@ -1026,8 +1042,11 @@ constrain reference-valued properties (e.g. `[[PERSONA:*]]` or
 
 A Markdown image `![<alt/>](<file/>)` inside a description or property
 value embeds a local image file, resolved relative to the artifact file:
-SVG files are inlined as-is; PNG/JPEG files are embedded as base64
-`data:` URLs. URLs and other file types are left untouched.
+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.
 
 A reference carrying the `{theme}` placeholder -- e.g.
 `![Logo](logo-{theme}.svg)` -- is a *theme-aware* embedding: it expands
@@ -1036,3 +1055,11 @@ both of which are embedded, as two consecutive entries in this order. The
 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.
+
+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.
+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.

package/dst/specbook-format.yaml

@@ -154,8 +154,8 @@
             value: enum(Dark,Light)
             optional: true
         -   name: THEME-TONE
-            desc: The theme color tone.
-            value: /^#[0-9a-fA-F]{6}$/
+            desc: The theme color tone, optionally followed by the complement color tone (else derived).
+            value: /^#[0-9a-fA-F]{6}(\s+#[0-9a-fA-F]{6})?$/
             optional: true
 
 -   kind: REQS
@@ -250,7 +250,7 @@
         config:
             size-node-width-max: 440
             size-node-height-scale: 1.75
-            grid-columns-max: 5
+            grid-columns-max: 4
     children:
         -   kind: PREMISE
             desc: >
@@ -643,7 +643,7 @@
             -   PRIORITY
         config:
             size-node-width-max: 440
-            grid-columns-max: 5
+            grid-columns-max: 4
     children:
         -   kind: REQUIREMENT
             desc: >
@@ -702,7 +702,7 @@
             -   CATEGORY
         config:
             size-node-width-max: 440
-            grid-columns-max: 5
+            grid-columns-max: 4
     children:
         -   kind: REQUIREMENT
             desc: >
@@ -799,7 +799,7 @@
             -   SOURCE
         config:
             size-node-width-max: 440
-            grid-columns-max: 5
+            grid-columns-max: 4
     children:
         -   kind: RULE
             desc: >
@@ -1426,7 +1426,7 @@
         config:
             size-node-width-max: 440
             size-node-height-scale: 2
-            grid-columns-max: 5
+            grid-columns-max: 4
     children:
         -   kind: LIFECYCLE
             desc: >
@@ -1582,8 +1582,11 @@
         onlyConnected: true
         qualified: true
         config:
+            size-node-width-min: 300
             size-node-width-max: 440
-            graph-channel-width-max: 340
+            graph-channel-width-max: 700
+            graph-node-degree-max: 8
+            size-edge-port-gap: 18
     children:
         -   kind: PERMISSION
             desc: >
@@ -3900,7 +3903,7 @@
             -   STATUS
         config:
             size-node-width-max: 440
-            grid-columns-max: 5
+            grid-columns-max: 4
     children:
         -   kind: DECISION
             desc: |

package/dst/specbook-ignore.js

@@ -34,8 +34,8 @@ const compileRule = (line, base) => {
     if (pattern.startsWith("/"))
         pattern = pattern.slice(1);
     const glob = anchored ? (base === "" ? pattern : `${base}/${pattern}`) : `**/${pattern}`;
-    const isMatch = picomatch(glob, { dot: true });
-    return { matcher: (p) => isMatch(p), negated, dirOnly };
+    const isMatch = picomatch(glob, { dot: true, nobrace: true, noextglob: true, nonegate: true });
+    return { matcher: isMatch, negated, dirOnly };
 };
 /*  load the rules of a single exclude file, given as an absolute "file"
     and the working-tree-relative "base" its anchored patterns resolve
@@ -73,10 +73,10 @@ const workingTree = (dir) => {
 /*  resolve the global Git excludes file: the configured
     "core.excludesFile", or else the XDG location Git falls back onto
     when that configuration value is unset  */
-const globalFile = () => {
+const globalFile = (root) => {
     let file = "";
     try {
-        file = execFileSync("git", ["config", "--get", "core.excludesFile"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+        file = execFileSync("git", ["config", "--get", "core.excludesFile"], { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
     }
     catch {
         /*  no such configuration value, or no Git at all  */
@@ -123,7 +123,7 @@ export const excluder = (dir) => {
         return () => false;
     /*  the rules which no directory of the working tree owns and which
         hence govern it as a whole, in ascending Git precedence  */
-    const base = [...loadRules(globalFile(), ""), ...loadRules(infoFile(root), "")];
+    const base = [...loadRules(globalFile(root), ""), ...loadRules(infoFile(root), "")];
     /*  the per-directory ".gitignore" rules, loaded on first use, as one
         run queries many files sharing the very same directories  */
     const cache = new Map();

package/dst/specbook-link.js

@@ -142,7 +142,7 @@ const nearest = (index, matches, from) => {
         return i;
     };
     const proximities = matches.map((object) => proximity(object));
-    const best = Math.max(...proximities);
+    const best = proximities.reduce((max, p) => Math.max(max, p), 0);
     return matches.filter((_, i) => proximities[i] === best);
 };
 /*  resolve a reference into a unique target: a single segment tries the