@rse/specbook 1.2.14 → 1.2.16

package/dst/specbook-cmd-describe.js

@@ -20,8 +20,9 @@ export const parseDescribeFormat = (value) => parseChoice(describeFormats, "form
 export const parseDescribePart = (value) => parseChoice(describeParts, "part", value);
 /*  the supported compression levels of the emitted YAML schema
     configuration: verbatim (0), re-emitted with 2-space indentation and
-    without comments (1), additionally without its "refs" fields (2), and
-    additionally without its "desc" fields of objects and properties (3)  */
+    without comments (1), additionally without its "refs", "diagram", and
+    "format" fields (2), and additionally without its "desc" fields of
+    objects and properties (3)  */
 export const compressLevels = [0, 1, 2, 3];
 /*  parse and validate a compression level specification,
     where a bare flag selects the plain re-emitting  */
@@ -43,7 +44,7 @@ const compressYaml = (yaml, level) => {
     if (level === 0)
         return yaml;
     const doc = parseDocument(yaml);
-    const drop = ["refs", "desc"].slice(0, level - 1);
+    const drop = [["refs", "diagram", "format"], ["desc"]].slice(0, level - 1).flat();
     doc.commentBefore = null;
     doc.comment = null;
     visit(doc, {
@@ -76,9 +77,12 @@ const schemaSection = (config, schema, embed, standard, compress) => {
     if (standard)
         yaml = yaml.replace(/^(?:[ \t]*##.*\n)+\s*/, "");
     yaml = compressYaml(yaml, compress);
+    /*  the fence has to outgrow every backtick run inside the content,
+        so an embedded code block can never break out of it  */
+    const fence = "`".repeat(Math.max(3, ...Array.from(yaml.matchAll(/^[ \t]*(`{3,})/gm), (match) => match[1].length + 1)));
     return textframe(`
         The **SpecBook SCHEMA Model** is the following YAML schema configuration:
-    `) + "\n```yaml\n" + yaml.replace(/\n*$/, "\n") + "```\n";
+    `) + `\n${fence}yaml\n` + yaml.replace(/\n*$/, "\n") + `${fence}\n`;
 };
 /*  render the reference to the specification Markdown files  */
 const specSection = (basedir) => textframe(`

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

@@ -1,8 +1,11 @@
 import type { Spec } from "./specbook-format-spec.js";
 import type { Schema } from "./specbook-format-schema.js";
+import { parseOmit, omitAspects, type ExportOptions } from "./specbook-export-common.js";
+import { type MarkdownRebase } from "./specbook-export-md.js";
 import { requireBrowser } from "./specbook-export-pdf.js";
 import { type Verbose } from "./specbook-verbose.js";
 export { requireBrowser };
+export { parseOmit, omitAspects, type ExportOptions };
 export declare const formats: readonly ["json", "json5", "yaml", "toon", "html", "pdf", "md"];
 export type ExportFormat = typeof formats[number];
 export declare const parseOutputSpec: (spec: string) => {
@@ -10,4 +13,4 @@ export declare const parseOutputSpec: (spec: string) => {
     output: string;
 };
 export declare const watchSpecification: (run: () => Promise<string[]>, verbose: Verbose) => Promise<void>;
-export declare const exportSpecification: (specification: Spec, format: ExportFormat, verbose: Verbose, config?: Schema, realtime?: boolean) => Promise<Buffer>;
+export declare const exportSpecification: (specification: Spec, format: ExportFormat, verbose: Verbose, config?: Schema, options?: ExportOptions, rebase?: MarkdownRebase) => Promise<Buffer>;

package/dst/specbook-cmd-export.js

@@ -9,7 +9,7 @@ import * as fs from "node:fs";
     Chokidar under its plain name would raise a peer warning on install  */
 import { watch } from "chokidar5";
 import { minify } from "@swc/html";
-import { documentTitle, documentLogo, documentCharset, documentThemeTone, subsetStylesheet, documentPaperSize, paperStylesheet, charsetCodepoints } from "./specbook-export-common.js";
+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 { renderAst } from "./specbook-export-ast.js";
 import { renderMarkdown } from "./specbook-export-md.js";
@@ -19,6 +19,8 @@ import { literal } from "./specbook-verbose.js";
 /*  re-export the browser pre-check of the PDF renderer, so the API
     facade reaches the renderers through this command module only  */
 export { requireBrowser };
+/*  re-export the omit aspects of the renderers for the very same reason  */
+export { parseOmit, omitAspects };
 /*  the supported export formats  */
 export const formats = ["json", "json5", "yaml", "toon", "html", "pdf", "md"];
 /*  the format names and filename extensions mapping onto the export formats  */
@@ -111,16 +113,18 @@ export const watchSpecification = async (run, verbose) => {
         chained catch keeps an unexpected failure from breaking the chain
         and hence silently ending the observe loop)  */
     let chain = Promise.resolve();
+    let pending = 0;
     let timer;
     const schedule = () => {
         if (timer !== undefined)
             clearTimeout(timer);
         timer = setTimeout(() => {
             timer = undefined;
+            pending += 1;
             chain = chain.then(cycle).catch((err) => {
                 verbose("re-export failed: " +
                     (err instanceof Error ? err.message : String(err)), "none");
-            });
+            }).finally(() => { pending -= 1; });
         }, watchDelay);
     };
     watcher.on("all", schedule);
@@ -130,6 +134,9 @@ export const watchSpecification = async (run, verbose) => {
         regains it on its own and the following changes would be caught
         by the scan only  */
     setInterval(() => {
+        /*  a pending or running re-export legitimately lags behind  */
+        if (timer !== undefined || pending > 0)
+            return;
         for (const [file, time] of snapshot(observed))
             if (times.get(file) !== time) {
                 verbose(`observing missed the change of "${literal(file)}" ` +
@@ -141,13 +148,14 @@ export const watchSpecification = async (run, verbose) => {
             }
     }, scanDelay);
 };
-/*  render a specification into the requested format, where "realtime"
-    injects the client-side script of the live preview into the HTML  */
-const renderFormat = async (specification, format, verbose, config, realtime = false) => {
+/*  render a specification into the requested format, where "options"
+    carries the rendering options of the HTML, PDF, and AST formats and
+    "rebase" re-bases the image references of the normalized Markdown  */
+const renderFormat = async (specification, format, verbose, config, options = {}, rebase) => {
     if (format === "json" || format === "json5" || format === "yaml" || format === "toon")
-        return renderAst(specification, format, config);
+        return renderAst(specification, format, config, verbose, options.omit);
     else if (format === "md")
-        return Buffer.from(renderMarkdown(specification, config), "utf8");
+        return Buffer.from(await renderMarkdown(specification, config, rebase, verbose), "utf8");
     /*  the HTML-based formats share the stylesheet, with the embedded
         fonts subsetted to the CHARSET of the specification (if any)  */
     const charset = documentCharset(specification);
@@ -164,7 +172,7 @@ const renderFormat = async (specification, format, verbose, config, realtime = f
     const css = themeStylesheet(colors) + await subsetStylesheet(charset) + paperStylesheet(paper);
     if (format === "html") {
         /*  compress the rendered HTML (whitespace, comments, and inline CSS/JS)  */
-        const html = await renderHtml(specification, config, undefined, css, realtime, verbose);
+        const html = await renderHtml(specification, config, undefined, css, options, verbose);
         const minified = await minify(Buffer.from(html, "utf8"), {
             collapseWhitespaces: "smart",
             removeComments: true,
@@ -173,19 +181,21 @@ const renderFormat = async (specification, format, verbose, config, realtime = f
         });
         return Buffer.from(minified.code, "utf8");
     }
-    else
+    else {
         /*  the PDF export (like print in general) always uses the light
             theme, so its decoration colors are the light mapping, too  */
-        return htmlToPdf((tocPages) => renderHtml(specification, config, tocPages, css, false, verbose), { ...documentTitle(specification), logo: documentLogo(specification) }, htmlOutline(specification, config), titlePageObject(specification) !== undefined, verbose, css, themeMapping(colors, "light"), paper);
+        const pass = (tocPages) => renderHtml(specification, config, tocPages, css, { omit: options.omit }, verbose, true);
+        return htmlToPdf(pass, { ...documentTitle(specification), logo: documentLogo(specification) }, htmlOutline(specification, config), titlePageObject(specification) !== undefined, verbose, css, themeMapping(colors, "light"), paper);
+    }
 };
 /*  export a specification into the requested format (see "renderFormat"),
     reporting the duration of the rendering in the verbose output  */
-export const exportSpecification = async (specification, format, verbose, config, realtime = false) => {
+export const exportSpecification = async (specification, format, verbose, config, options = {}, rebase) => {
     if (!formats.includes(format))
         throw new Error(`unknown export format "${format}"`);
     verbose(`exporting specification as "${literal(format)}"`);
     const started = performance.now();
-    const buffer = await renderFormat(specification, format, verbose, config, realtime);
+    const buffer = await renderFormat(specification, format, verbose, config, options, rebase);
     const seconds = ((performance.now() - started) / 1000).toFixed(3);
     verbose(`exported specification as "${literal(format)}" in ${literal(seconds)}s`);
     return buffer;

package/dst/specbook-cmd-init.js

@@ -6,20 +6,14 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { literal } from "./specbook-verbose.js";
-/*  the current time in the frontmatter timestamp format  */
-const timestamp = () => {
-    const d = new Date();
-    const pad = (n) => String(n).padStart(2, "0");
-    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ` +
-        `${pad(d.getHours())}:${pad(d.getMinutes())}`;
-};
+import { formatTimestamp } from "./specbook-export-md.js";
 /*  initialize the configured specification artifact files below the
     base directory with their frontmatter and artifact headings, where
     all artifacts configured onto the same file reside in it side by
     side, following each other on level 1  */
 export const initSpecification = (options) => {
     fs.mkdirSync(options.basedir, { recursive: true });
-    const now = timestamp();
+    const now = formatTimestamp(new Date());
     const created = new Array();
     /*  group the configured artifacts by their file, preserving the
         schema order both of the files and of the artifacts within  */

package/dst/specbook-cmd-lint.d.ts

@@ -1,6 +1,6 @@
 import { type Verbose } from "./specbook-verbose.js";
 import { type Diagnostic } from "./specbook-diagnostic.js";
-import { type Spec } from "./specbook-format-spec.js";
+import { type Spec, type SpecArtifact } from "./specbook-format-spec.js";
 import { type Schema } from "./specbook-format-schema.js";
 export interface LintOptions {
     config: string[];
@@ -13,5 +13,6 @@ export interface LintResult {
     diagnostics: Diagnostic[];
     config?: Schema;
     files: string[];
+    origins: Map<SpecArtifact, string>;
 }
 export declare const lint: (options: LintOptions) => LintResult;

package/dst/specbook-cmd-lint.js

@@ -23,6 +23,32 @@ const schemaFiles = (config) => {
     }
     return files;
 };
+/*  report the reference coverage the "referenced"-flagged object kinds
+    receive and the "coverage"-configured objects report as additional
+    figures, the unreferenced objects of the latter by name as a lengthy
+    detail (the ones of the former are already reported as warnings)  */
+const reportCoverage = (specification, config, verbose) => {
+    const index = buildLinkIndex(specification);
+    const schemas = collectSchemas(specification, config);
+    const label = (object) => `${object.kind} "${literal(plainText(object.name))}"`;
+    const ratio = (covered, uncovered) => `${literal(covered.length)} of ${literal(covered.length + uncovered.length)} ` +
+        `(${literal(coverageRatio(covered.length, covered.length + uncovered.length))}%)`;
+    for (const { schema, covered, uncovered } of referencedCoverage(index, schemas)) {
+        const chain = chainOf(index, covered[0] ?? uncovered[0]);
+        verbose((schema.referenced ?? []).map((entry) => `"${literal(entry)}"`).join(" or ") +
+            ` references ${ratio(covered, uncovered)} ${schema.kind} object(s)` +
+            (chain.length > 1 ? ` below ${label(chain[0])}` : ""), "detail");
+    }
+    for (const [object, entries] of specCoverage(index, schemas))
+        for (const { pattern, covered, uncovered } of entries) {
+            verbose(`${label(object)} references ${ratio(covered, uncovered)} ` +
+                `"${literal(pattern)}" object(s)`, "detail");
+            if (uncovered.length > 0)
+                verbose(`${label(object)} leaves ${literal(uncovered.length)} ` +
+                    `"${literal(pattern)}" object(s) unreferenced: ` +
+                    uncovered.map(label).join(", "), "trace");
+        }
+};
 /*  lint the specification Markdown files below the base directory
     against the configuration  */
 export const lint = (options) => {
@@ -87,33 +113,9 @@ export const lint = (options) => {
     const stats = specStatistics(result.specification);
     options.verbose(`parsed specification defining ${literal(stats.objects)} object(s) ` +
         `and ${literal(stats.links)} link relationship(s)`);
-    /*  report the reference coverage the "referenced"-flagged object
-        kinds receive and the "coverage"-configured objects report as
-        additional figures, the unreferenced objects of the latter by
-        name as a lengthy detail (the ones of the former are already
-        reported as warnings)  */
-    if (config !== undefined && result.specification.artifacts.length > 0) {
-        const index = buildLinkIndex(result.specification);
-        const schemas = collectSchemas(result.specification, config);
-        const label = (object) => `${object.kind} "${literal(plainText(object.name))}"`;
-        const ratio = (covered, uncovered) => `${literal(covered.length)} of ${literal(covered.length + uncovered.length)} ` +
-            `(${literal(coverageRatio(covered.length, covered.length + uncovered.length))}%)`;
-        for (const { schema, covered, uncovered } of referencedCoverage(index, schemas)) {
-            const chain = chainOf(index, covered[0] ?? uncovered[0]);
-            options.verbose((schema.referenced ?? []).map((entry) => `"${literal(entry)}"`).join(" or ") +
-                ` references ${ratio(covered, uncovered)} ${schema.kind} object(s)` +
-                (chain.length > 1 ? ` below ${label(chain[0])}` : ""), "detail");
-        }
-        for (const [object, entries] of specCoverage(index, schemas))
-            for (const { pattern, covered, uncovered } of entries) {
-                options.verbose(`${label(object)} references ${ratio(covered, uncovered)} ` +
-                    `"${literal(pattern)}" object(s)`, "detail");
-                if (uncovered.length > 0)
-                    options.verbose(`${label(object)} leaves ${literal(uncovered.length)} ` +
-                        `"${literal(pattern)}" object(s) unreferenced: ` +
-                        uncovered.map(label).join(", "), "trace");
-            }
-    }
+    /*  report the reference coverage as additional figures  */
+    if (config !== undefined && result.specification.artifacts.length > 0)
+        reportCoverage(result.specification, config, options.verbose);
     /*  report the non-optional artifacts absent from the specification,
         against their loaded artifact file (an absent or unreadable file
         is already reported above) or else against the configuration  */
@@ -135,5 +137,6 @@ export const lint = (options) => {
                 message: `missing artifact "${schema.kind}: ${schema.name ?? ""}${paren}"` });
         }
     }
-    return { specification: result.specification, diagnostics, config, files: watched };
+    return { specification: result.specification, diagnostics, config, files: watched,
+        origins: result.origins };
 };

package/dst/specbook-config.d.ts

@@ -1,5 +1,11 @@
+import { LineCounter, type Document } from "yaml";
 import { Schema } from "./specbook-format-schema.js";
 import { type Diagnostic } from "./specbook-diagnostic.js";
+type YamlPath = (string | number)[];
+export declare const lineColOfPath: (doc: Document, lines: LineCounter, path: YamlPath) => {
+    line: number;
+    column: number;
+};
 export declare const configStatistics: (config: Schema) => {
     objects: number;
     links: number;
@@ -8,3 +14,4 @@ export declare const loadConfig: (files: string[]) => {
     config?: Schema;
     diagnostics: Diagnostic[];
 };
+export {};

package/dst/specbook-config.js

@@ -11,7 +11,7 @@ import { Schema } from "./specbook-format-schema.js";
 import { compileValueExpr, anchored, admitsReferences } from "./specbook-parse-value.js";
 /*  determine line/column of a YAML document path via the node ranges
     of the parsed document, falling back to the closest ancestor node  */
-const lineColOfPath = (doc, lines, path) => {
+export const lineColOfPath = (doc, lines, path) => {
     for (let i = path.length; i >= 0; i--) {
         const node = doc.getIn(path.slice(0, i), true);
         const start = isNode(node) ? node.range?.[0] : undefined;
@@ -214,6 +214,11 @@ const checkConstraints = (config, posOfPath) => {
                 seen.add(ident);
             if (depth > 1 && object.file !== undefined)
                 diagnose([...at, "file"], `"file" field is only allowed on the first (artifact) level (found on level ${depth})`);
+            /*  an artifact file is placed below the base directory, so
+                it must neither be absolute nor escape that directory  */
+            if (object.file !== undefined
+                && ((/^[/\\]/).test(object.file) || (/(?:^|[/\\])\.\.(?:[/\\]|$)/).test(object.file)))
+                diagnose([...at, "file"], `"file" field "${object.file}" is not a relative path below the base directory`);
             checkProperties(object.props ?? [], at, diagnose);
             checkAutomaton(object, at, diagnose);
             for (const field of ["referenced", "coverage"])

package/dst/specbook-coverage.js

@@ -39,15 +39,14 @@ const isCovered = (index, referrers, sources, object, lifting) => {
 };
 /*  the objects matching the reference patterns of a schema field  */
 const matchingObjects = (index, patterns) => {
-    const objects = new Array();
+    const objects = new Set();
     for (const pattern of patterns) {
         const expr = compileValueExpr(pattern);
         if (expr.kind === "reference")
             for (const object of resolveSet(index, expr.pattern))
-                if (!objects.includes(object))
-                    objects.push(object);
+                objects.add(object);
     }
-    return objects;
+    return Array.from(objects);
 };
 /*  determine the coverage the objects of every "referenced"-flagged
     kind receive, one entry per flagged schema node (in the order of

package/dst/specbook-diagram.d.ts

@@ -1,6 +1,7 @@
 import type { Spec, SpecObject } from "./specbook-format-spec.js";
 import type { Schema, SchemaDiagram } from "./specbook-format-schema.js";
 import type { ParseContext } from "./specbook-parse-common.js";
+import type { OmitAspect } from "./specbook-export-common.js";
 import { type Verbose } from "./specbook-verbose.js";
 export interface DiagramError {
     reason: string;
@@ -13,7 +14,8 @@ export interface DiagramResult {
     errors: DiagramError[];
 }
 export declare const specDiagrams: (specification: Spec, config: Schema) => Map<SpecObject, DiagramResult>;
-export declare const renderDiagrams: (specification: Spec, config: Schema, verbose?: Verbose) => Promise<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 & {
     svg: string;
 }>>;
 export declare const validateDiagrams: (ctx: ParseContext, specification: Spec, config: Schema) => void;

package/dst/specbook-diagram.js

@@ -10,10 +10,43 @@ import { literal } from "./specbook-verbose.js";
 /*  the single Wiki-style reference match (the non-global sibling of
     the imported, global "referenceRegex")  */
 const referenceOnce = new RegExp(referenceRegex.source);
+/*  the Gradia rendering options preset for every diagram, which the
+    "config" of a diagram configuration overrides: inside a document
+    the diagrams are rendered compactly, as their defaults are
+    dimensioned for a stand-alone canvas -- no canvas margin beyond the
+    box strokes (the document spaces the diagram), the node boxes at
+    their content height, tighter gaps between the stacked nodes and
+    the tiles, a "hub" column of more than six nodes wrapped into
+    two staggered sub-columns, and four tiles per "grid" row, as the
+    square derivation of the column count otherwise leaves a third of
+    the document width unused at the reduced coordinate scale. The node
+    types and the edge labels are raised by about 20% over their Gradia
+    defaults, as that very coordinate scale would otherwise shrink them
+    below a comfortably readable size (the "--gradia-size-font-*" custom
+    properties of the stylesheet mirror them for a display-time tweak).
+    The parallel edges are spread further apart for the same reason, and
+    the "graph" channels are practically uncapped, as a capped channel
+    squeezes its many edges into an unreadable bundle  */
+const diagramPresets = {
+    "size-canvas-margin": 8,
+    "size-node-height-scale": 2,
+    "size-font-type": 19,
+    "size-font-edge": 19,
+    "size-font-arity": 19,
+    "size-edge-track-gap": 20,
+    "graph-channel-width-max": 1000,
+    "hub-node-gap": 10,
+    "hub-node-count-max": 6,
+    "grid-gap-horizontal": 24,
+    "grid-gap-vertical": 12,
+    "grid-columns-min": 4
+};
+/*  render a text as a double-quoted Gradia string, with the
+    backslashes and the double quotes escaped  */
+const quoted = (text) => `"${text.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
 /*  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);
@@ -44,7 +77,7 @@ const propValue = (parenProps, object, key) => propsOf(parenProps, object).find(
     derived edge  */
 const renderSpec = (diagram, type, center, centerUrl, nodes, edges, nesting, index, anchors, positions, parenProps) => {
     const lines = [`#type ${type}`];
-    const config = diagram.config ?? {};
+    const config = { ...diagramPresets, ...diagram.config };
     for (const [key, value] of Object.entries(config))
         if (value !== undefined)
             lines.push(`#config ${key} ${configValue(value)}`);
@@ -221,16 +254,10 @@ const deriveEdges = (diagram, type, nodes, nodeSet, edgeObjects, index, anchors,
             }
     }
     else {
-        if (diagram.edges !== undefined)
-            errors.push({ reason: "\"grid\" diagram cannot carry an \"edges\" configuration" });
-        if (diagram.hierarchy === true)
-            errors.push({ reason: "\"grid\" diagram cannot carry a \"hierarchy\" configuration" });
-        if (diagram.deep === true)
-            errors.push({ reason: "\"grid\" diagram cannot carry a \"deep\" configuration" });
-        if (diagram.labeled === true)
-            errors.push({ reason: "\"grid\" diagram cannot carry a \"labeled\" configuration" });
-        if (diagram.onlyConnected === true)
-            errors.push({ reason: "\"grid\" diagram cannot carry an \"onlyConnected\" configuration" });
+        for (const field of ["edges", "hierarchy", "deep", "labeled", "onlyConnected"])
+            if (diagram[field] !== undefined && diagram[field] !== false)
+                errors.push({ reason: "\"grid\" diagram cannot carry " +
+                        `${(/^[aeiou]/).test(field) ? "an" : "a"} "${field}" configuration` });
     }
     return edges;
 };
@@ -457,8 +484,8 @@ const liftEdges = (edges, parentOf, mode, anchors) => {
         const source = mode === "both" ? lift(edge.source, edge.target) : edge.source;
         if (source === target)
             continue;
-        const key = `${anchors.get(source) ?? source.id}${anchors.get(target) ?? target.id}` +
-            `${edge.name ?? ""}`;
+        const key = `${anchors.get(source) ?? source.id}\u0000${anchors.get(target) ?? target.id}` +
+            `\u0000${edge.name ?? ""}`;
         const known = merged.get(key);
         if (known === undefined)
             merged.set(key, { source, target, name: edge.name, arity: edge.arity });
@@ -518,18 +545,17 @@ const deriveDiagram = (object, diagram, index, anchors, positions, parents, pare
     edges = dedupEdges(edges, anchors);
     /*  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 (and the
-        occupied columns are the center plus the input column, when
-        an edge targets the center, plus the output column, when an
-        edge originates from the center)  */
+        connected through them remain, as Gradia requires exactly this
+        constrained topology (and the occupied columns are the center
+        plus the input column, when an edge of another node targets the
+        center, plus the output column, when an edge originates from the
+        center, where Gradia places the target of its self-loop, too)  */
     let columns;
     if (type === "hub") {
         if (!nodeSet.has(center))
             errors.push({ reason: `"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);
+            edges = edges.filter((edge) => edge.source === center || edge.target === center);
             const connected = new Set([center]);
             for (const edge of edges) {
                 connected.add(edge.source);
@@ -537,7 +563,7 @@ const deriveDiagram = (object, diagram, index, anchors, positions, parents, pare
             }
             nodes = nodes.filter((node) => connected.has(node));
             columns = 1 +
-                (edges.some((edge) => edge.target === center) ? 1 : 0) +
+                (edges.some((edge) => edge.target === center && edge.source !== center) ? 1 : 0) +
                 (edges.some((edge) => edge.source === center) ? 1 : 0);
         }
     }
@@ -578,7 +604,7 @@ const deriveDiagram = (object, diagram, index, anchors, positions, parents, pare
     if (nodes.length === 0
         || (diagram.collapse !== false && nodes.length === 1 && edges.length === 0))
         return { errors };
-    return { spec: renderSpec(diagram, type, center, centerUrl, nodes, edges, nesting, index, anchors, positions, parenProps), config: diagram.config, columns, errors };
+    return { spec: renderSpec(diagram, type, center, centerUrl, nodes, edges, nesting, index, anchors, positions, parenProps), config: { ...diagramPresets, ...diagram.config }, columns, errors };
 };
 /*  the memoized diagram derivations, keyed by specification, as the
     lint validation and every renderer of an export derive the very
@@ -610,6 +636,27 @@ export const specDiagrams = (specification, config) => {
     derivations.set(specification, { config, results });
     return results;
 };
+/*  determine the diagram-configured objects whose diagrams the given
+    aspects omit: the ones of a diagram type and the ones from an object
+    tree nesting level on (the top-level objects being level 1)  */
+export const omittedDiagrams = (specification, config, omit) => {
+    const omitted = new Set();
+    if (omit.size === 0)
+        return omitted;
+    const schemas = collectSchemas(specification, config);
+    for (const node of buildLinkIndex(specification)) {
+        const diagram = schemas.get(node.object)?.diagram;
+        if (diagram === undefined)
+            continue;
+        let level = 1;
+        for (let parent = node.parent; parent !== undefined; parent = parent.parent)
+            level++;
+        if (omit.has(`diagram:${diagram.type ?? "graph"}`)
+            || [1, 2, 3].some((n) => n <= level && omit.has(`diagram:${n}`)))
+            omitted.add(node.object);
+    }
+    return omitted;
+};
 /*  the in-memory cache of the rendered diagram SVGs, keyed by Gradia
     spec text plus rendering options, as a long-running process (the
     live preview, the export watch, the MCP service) and the multiple
@@ -622,13 +669,14 @@ let svgCache = new Map();
     detectable invalid situations are already reported as lint
     diagnostics), served from the cache where possible, which is
     afterwards swept to the diagrams of this very rendering, so it never
-    grows beyond a single document  */
-export const renderDiagrams = async (specification, config, verbose) => {
+    grows beyond a single document; the omitted diagrams are skipped  */
+export const renderDiagrams = async (specification, config, verbose, omit = new Set()) => {
     const cache = new Map();
     const rendered = new Map();
+    const omitted = omittedDiagrams(specification, config, omit);
     let cached = 0;
     for (const [object, result] of specDiagrams(specification, config)) {
-        if (result.spec === undefined)
+        if (result.spec === undefined || omitted.has(object))
             continue;
         const key = result.spec + JSON.stringify(result.config ?? {});
         let svg = svgCache.get(key) ?? cache.get(key);
@@ -648,7 +696,10 @@ export const renderDiagrams = async (specification, config, verbose) => {
         rendered.set(object, { ...result, svg });
     }
     svgCache = cache;
-    verbose?.(`rendering ${literal(rendered.size)} diagram(s) (${literal(cached)} cached)`);
+    if (cached > 0 && cached === rendered.size)
+        verbose?.(`reusing ${literal(cached)} cached diagram(s)`);
+    else
+        verbose?.(`rendering ${literal(rendered.size)} diagram(s) (${literal(cached)} cached)`);
     return rendered;
 };
 /*  validate all configured diagrams of a specification, reporting

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

@@ -1,4 +1,5 @@
 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) => Buffer;
+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>;

package/dst/specbook-export-ast.js

@@ -6,29 +6,37 @@
 import JSON5 from "json5";
 import { stringify as stringifyYaml } from "yaml";
 import { encode as encodeToon } from "@toon-format/toon";
-import { specDiagrams } from "./specbook-diagram.js";
+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";
-/*  render the specification AST into a serialization format  */
-export const renderAst = (specification, format, config) => {
-    /*  reduce the specification to plain JSON values (ISO date strings)  */
-    const plain = JSON.parse(JSON.stringify(specification));
+import { optimizeImages } from "./specbook-export-image.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  */
+    const optimized = await optimizeImages(specification, false, verbose);
+    const plain = JSON.parse(JSON.stringify(specification, (key, value) => key !== "embedding" ? value :
+        value.map((content) => optimized.get(content) ?? content)));
     /*  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, and the diagram of
-        the title object is reserved for the HTML/PDF export), and
+        already reported as a lint diagnostic, the diagram of the
+        title object is reserved for the HTML/PDF export, and the
+        diagrams of the omitted aspects are left out), and
         the reference coverage of the coverage-configured objects as
         "coverage" fields (the counts only, as the export is intended
         for machine consumption)  */
     if (config !== undefined) {
         const diagrams = specDiagrams(specification, config);
+        const omitted = omittedDiagrams(specification, config, omit);
         const coverages = specCoverage(buildLinkIndex(specification), collectSchemas(specification, config));
         const walk = (object, node) => {
             const result = diagrams.get(object);
-            if (result?.spec !== undefined && !isTitleObject(object))
+            if (result?.spec !== undefined && !isTitleObject(object) && !omitted.has(object))
                 node.diagram = result.spec;
             const coverage = coverages.get(object);
             if (coverage !== undefined)

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

@@ -4,6 +4,13 @@ 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 type OmitAspect = typeof omitAspects[number];
+export declare const parseOmit: (omit?: string[]) => Set<OmitAspect>;
+export interface ExportOptions {
+    realtime?: boolean;
+    omit?: Set<OmitAspect>;
+}
 export declare const isTitleObject: (object: SpecObject) => boolean;
 export declare const titleObject: (specification: Spec) => SpecObject | undefined;
 export declare const documentLang: (specification: Spec) => string | undefined;