@rse/specbook 1.2.1 → 1.2.2

package/README.md

@@ -140,6 +140,7 @@ export class SpecBook {
         basedir?: string,
         formats?: ExportFormat[],
         realtime?: boolean,
+        outputs?: string[],        /*  paths "onExport" writes, refused if observed  */
         onExport: (buffers: Buffer[]) => void | Promise<void>
     }): Promise<void>
 
@@ -357,7 +358,9 @@ Options:
     silent for one second. A failed re-export is reported and leaves the
     observe loop intact, so a transiently invalid specification does not
     end the watch. The outputs have to be regular files, as `-` (stdout)
-    cannot receive a repeated export.
+    cannot receive a repeated export, and none of them may be an observed
+    source file itself, as its own write would re-trigger the observation
+    endlessly.
 
 -   `-a|--addr <ip-addr>`, `-p|--port <tcp-port>` (`preview` only):
     The IP address (default: `127.0.0.1`) and TCP port (default: `12345`)

package/dst/specbook-api.d.ts

@@ -47,6 +47,7 @@ export declare class SpecBook {
         basedir?: string;
         formats?: ExportFormat[];
         realtime?: boolean;
+        outputs?: string[];
         onExport: (buffers: Buffer[]) => void | Promise<void>;
     }): Promise<void>;
     preview(options: {

package/dst/specbook-api.js

@@ -132,6 +132,14 @@ export class SpecBook {
                 observed, too, so a failing export (even one due to an
                 invalid configuration) still keeps the observe loop fed  */
             const result = lint({ config, basedir: options.basedir ?? ".", verbose });
+            const files = [...config.map((file) => path.resolve(file)), ...result.files];
+            /*  an output which is itself an observed source would re-trigger
+                the observation with its own write and hence feed an endless
+                re-export loop, so refuse it before it is ever written  */
+            const collision = options.outputs?.find((output) => files.includes(path.resolve(output)));
+            if (collision !== undefined)
+                throw new Error(`the output "${collision}" is an observed source file, ` +
+                    "which would re-trigger the observation endlessly");
             try {
                 await options.onExport(await this.renderFormats(result, options.formats, verbose, options.realtime));
             }
@@ -139,11 +147,13 @@ export class SpecBook {
                 verbose("export failed: " +
                     (err instanceof Error ? err.message : String(err)), "notice");
             }
-            return [...config.map((file) => path.resolve(file)), ...result.files];
+            return files;
         }, verbose);
     }
     /*  export the specification like "export" and then keep the export
-        in sync with its sources (see "observe")  */
+        in sync with its sources (see "observe"), where "outputs" names the
+        files "onExport" writes, so an output which is itself an observed
+        source can be refused  */
     async watch(options) {
         const verbose = this.verboseOf("export");
         const requested = options.formats ?? ["json"];

package/dst/specbook-cli.js

@@ -148,7 +148,7 @@ withCommonOptions(program.command("export"))
     };
     if (opts.watch)
         await specbook.watch({ config: configOf(opts), basedir: opts.basedir,
-            formats: distinct, onExport: write });
+            formats: distinct, outputs: outputs.map(({ output }) => output), onExport: write });
     else
         await write(await specbook.export({ config: configOf(opts), basedir: opts.basedir,
             formats: distinct }));

package/dst/specbook-cmd-preview.js

@@ -5,14 +5,20 @@
 */
 import Fastify from "fastify";
 import fastifyWebsocket from "@fastify/websocket";
+import { renderPlaceholder } from "./specbook-export-html.js";
 import { literal } from "./specbook-verbose.js";
 /*  the default listening address and port of the preview server  */
 export const previewAddr = "127.0.0.1";
 export const previewPort = 12345;
+/*  the placeholder page answering a GET before the first successful
+    export: it still carries the live preview client, so the browser
+    subscribes to the "RELOAD" command right away and replaces itself
+    with the document once the first export arrives  */
+const placeholder = renderPlaceholder("no specification export available yet");
 /*  serve the live HTML preview: a plain GET on "/" answers with the
-    most recent HTML export (or with 503 before the first successful
-    one), while a WebSocket upgrade on "/" subscribes the client to the
-    "RELOAD" command every fresh export broadcasts  */
+    most recent HTML export (or with the 503 placeholder page before the
+    first successful one), while a WebSocket upgrade on "/" subscribes
+    the client to the "RELOAD" command every fresh export broadcasts  */
 export const servePreview = async (options) => {
     let html;
     const clients = new Set();
@@ -24,8 +30,8 @@ export const servePreview = async (options) => {
         url: "/",
         handler: (_request, reply) => {
             if (html === undefined)
-                return reply.code(503).type("text/plain; charset=utf-8")
-                    .send("no specification export available yet\n");
+                return reply.code(503).type("text/html; charset=utf-8")
+                    .header("cache-control", "no-store").send(placeholder);
             return reply.type("text/html; charset=utf-8")
                 .header("cache-control", "no-store").send(html);
         },
@@ -53,7 +59,7 @@ export const servePreview = async (options) => {
     options.verbose(`listening on ${literal(url)}`, "notice");
     return {
         update: (buffer) => {
-            /*  the first export turns the 503 answers into the document  */
+            /*  the first export turns the 503 placeholder into the document  */
             if (html === undefined)
                 options.verbose(`serving ${literal(url)}`, "notice");
             html = buffer;

package/dst/specbook-config.js

@@ -43,7 +43,11 @@ const identityOf = (item, list) => {
     matched by their identity, so a matching element is merged into its
     counterpart and an unmatched one is appended  */
 const mergeConfig = (target, source, list) => {
-    if (Array.isArray(target) && Array.isArray(source)) {
+    /*  an empty or comment-only YAML document carries no content at
+        all, so it leaves the target intact instead of discarding it  */
+    if (source === null || source === undefined)
+        return target;
+    else if (Array.isArray(target) && Array.isArray(source)) {
         for (const item of source) {
             const i = target.findIndex((existing) => identityOf(existing, list) === identityOf(item, list));
             if (i < 0)
@@ -58,6 +62,17 @@ const mergeConfig = (target, source, list) => {
     else
         return source;
 };
+/*  deep copy a converted YAML document, as the conversion resolves all
+    aliases of an anchor onto one shared object, which the in-place
+    merge otherwise would alter through every alias at once  */
+const unshared = (value) => {
+    if (Array.isArray(value))
+        return value.map((item) => unshared(item));
+    else if (isPlainObject(value))
+        return Object.fromEntries(Object.entries(value).map(([key, val]) => [key, unshared(val)]));
+    else
+        return value;
+};
 /*  determine file and line/column of a path into the merged
     configuration by translating the path into every document (from the
     last to the first one, as a later document overrides an earlier one),
@@ -267,10 +282,10 @@ export const loadConfig = (files) => {
     }
     if (diagnostics.length > 0)
         return { diagnostics };
-    /*  merge the documents in order, out of fresh conversions, as the
-        merge mutates its target while the raw ones have to stay intact
-        for the path translation  */
-    const merged = docs.map(({ doc }) => doc.toJS())
+    /*  merge the documents in order, out of fresh and unshared
+        conversions, as the merge mutates its target while the raw ones
+        have to stay intact for the path translation  */
+    const merged = docs.map(({ doc }) => unshared(doc.toJS()))
         .reduce((target, source) => mergeConfig(target, source));
     /*  semantically validate the merged result against the schema of the configuration  */
     const posOfPath = (path) => posOfMergedPath(docs, merged, path);

package/dst/specbook-diagram.js

@@ -5,7 +5,7 @@
 */
 import { Gradia } from "@rse/gradia";
 import { referenceRegex, buildLinkIndex, resolveUnique, resolveSet, anchorPaths, expandReferences, plainText } from "./specbook-link.js";
-import { collectSchemas } from "./specbook-parse-semantic.js";
+import { collectSchemas, collectParenProps } from "./specbook-parse-semantic.js";
 import { literal } from "./specbook-verbose.js";
 /*  the single Wiki-style reference match (the non-global sibling of
     the imported, global "referenceRegex")  */
@@ -29,12 +29,19 @@ const configValue = (value) => {
     const text = String(value).replace(/\s+/g, " ").trim();
     return /^[^\s"]+$/.test(text) ? text : quoted(text);
 };
+/*  the properties of an object, the synthetic one included  */
+const propsOf = (parenProps, object) => {
+    const synthetic = parenProps.get(object);
+    return synthetic !== undefined ? [...object.properties, synthetic] : object.properties;
+};
+/*  the value of a single property of an object, by its key  */
+const propValue = (parenProps, object, key) => propsOf(parenProps, object).find((property) => property.key === key)?.value;
 /*  generate the Gradia spec text of a derived diagram, 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 renderSpec = (diagram, type, center, centerUrl, nodes, edges, index, anchors) => {
+const renderSpec = (diagram, type, center, centerUrl, nodes, edges, index, anchors, parenProps) => {
     const lines = [`#type ${type}`];
     const config = diagram.config ?? {};
     for (const [key, value] of Object.entries(config))
@@ -58,7 +65,7 @@ const renderSpec = (diagram, type, center, centerUrl, nodes, edges, index, ancho
             the node set can mix objects of different kinds), with every
             "[[...]]" reference stripped to its target object name  */
         for (const key of diagram.properties ?? []) {
-            const value = node.properties.find((property) => property.key === key)?.value;
+            const value = propValue(parenProps, node, key);
             if (value !== undefined) {
                 const text = expandReferences(value, (reference) => resolveUnique(index, reference, node).target?.name ?? reference);
                 attrs.push(`${atom(key)}: ${atom(plainText(text))}`);
@@ -84,7 +91,7 @@ const renderSpec = (diagram, type, center, centerUrl, nodes, edges, index, ancho
     property key when "labeled", and for a "deep" diagram also of their
     descendants, with every target lifted to its nearest node and the
     reference count as the arity)  */
-const deriveReferenceEdges = (diagram, nodes, nodeSet, index, anchors, parents) => {
+const deriveReferenceEdges = (diagram, nodes, nodeSet, index, anchors, parents, parenProps) => {
     const edges = new Array();
     /*  lift an object to its nearest ancestor-or-self within the
         node set, as a "deep" diagram attributes the references of
@@ -109,7 +116,7 @@ const deriveReferenceEdges = (diagram, nodes, nodeSet, index, anchors, parents)
         walk(node);
         const counts = new Map();
         for (const object of objects) {
-            const texts = object.properties.map((property) => ({
+            const texts = propsOf(parenProps, object).map((property) => ({
                 text: property.value,
                 name: diagram.labeled === true ? property.key.toLowerCase() : undefined
             }));
@@ -141,15 +148,15 @@ const deriveReferenceEdges = (diagram, nodes, nodeSet, index, anchors, parents)
     convention (source: parent object, target: first reference in the
     property values, name: object name, arity: "ARITY" property),
     overridable via "edgeSource"/"edgeTarget"/"edgeArity"  */
-const deriveObjectEdges = (diagram, nodeSet, edgeObjects, index, parents, errors) => {
+const deriveObjectEdges = (diagram, nodeSet, edgeObjects, index, parents, parenProps, errors) => {
     const edges = new Array();
     /*  resolve the node an edge object references through a named
         property, or through its first single-reference property when
         no name is configured (skipping the source property)  */
     const edgeNode = (edgeObject, key) => {
         const value = key !== undefined ?
-            edgeObject.properties.find((property) => property.key === key)?.value :
-            edgeObject.properties.filter((property) => property.key !== diagram.edgeSource)
+            propValue(parenProps, edgeObject, key) :
+            propsOf(parenProps, edgeObject).filter((property) => property.key !== diagram.edgeSource)
                 .map((property) => property.value).find((v) => referenceOnce.test(v));
         const reference = value?.match(referenceOnce)?.[1].trim();
         return reference !== undefined ? resolveUnique(index, reference, edgeObject).target : undefined;
@@ -170,7 +177,7 @@ const deriveObjectEdges = (diagram, nodeSet, edgeObjects, index, parents, errors
         }
         if (!nodeSet.has(source) || !nodeSet.has(target))
             continue;
-        const arity = edgeObject.properties.find((property) => property.key === (diagram.edgeArity ?? "ARITY"))?.value;
+        const arity = propValue(parenProps, edgeObject, diagram.edgeArity ?? "ARITY");
         edges.push({ source, target, name: plainText(edgeObject.name),
             arity: arity !== undefined ? plainText(arity) : undefined });
     }
@@ -180,11 +187,11 @@ const deriveObjectEdges = (diagram, nodeSet, edgeObjects, index, parents, errors
     objects, the object edges of the edge objects, and the containment
     edges of the object hierarchy (a "grid" diagram is edge-less by
     definition, so no edges are derived at all)  */
-const deriveEdges = (diagram, type, nodes, nodeSet, edgeObjects, index, anchors, parents, errors) => {
+const deriveEdges = (diagram, type, nodes, nodeSet, edgeObjects, index, anchors, parents, parenProps, errors) => {
     const edges = new Array();
     if (type !== "grid") {
-        edges.push(...deriveReferenceEdges(diagram, nodes, nodeSet, index, anchors, parents));
-        edges.push(...deriveObjectEdges(diagram, nodeSet, edgeObjects, index, parents, errors));
+        edges.push(...deriveReferenceEdges(diagram, nodes, nodeSet, index, anchors, parents, parenProps));
+        edges.push(...deriveObjectEdges(diagram, nodeSet, edgeObjects, index, parents, parenProps, errors));
         /*  derive the containment edges from the object hierarchy, as
             the nesting of the objects carries no "[[...]]" reference  */
         if (diagram.hierarchy === true)
@@ -253,7 +260,7 @@ const resolvePatterns = (index, errors, value, field) => {
     itself, e.g., is no specification object, yet a context
     diagram places it in the middle) and injected into the node
     set (the center is absent whenever the configuration is invalid)  */
-const deriveCenter = (object, diagram, nodes, nodeSet, index, anchors, errors) => {
+const deriveCenter = (object, diagram, nodes, nodeSet, index, anchors, parenProps, errors) => {
     if (typeof diagram.center === "string" && diagram.center !== "self") {
         const reference = diagram.center.match(referenceOnce)?.[1].trim();
         const resolved = reference !== undefined ? resolveUnique(index, reference, object) : undefined;
@@ -283,7 +290,7 @@ const deriveCenter = (object, diagram, nodes, nodeSet, index, anchors, errors) =
             }
             centerUrl = `#${anchors.get(source) ?? source.id}`;
             if (centerCfg.property !== undefined) {
-                const value = source.properties.find((property) => property.key === centerCfg.property)?.value;
+                const value = propValue(parenProps, source, centerCfg.property);
                 if (value === undefined) {
                     errors.push({ reason: `diagram "center" source lacks the property "${centerCfg.property}"` });
                     return undefined;
@@ -312,12 +319,12 @@ const deriveCenter = (object, diagram, nodes, nodeSet, index, anchors, errors) =
     maps onto a node-to-center edge, the "outbound" value onto a
     center-to-node edge, and the "both" value onto both (which
     Gradia renders as an input node plus an output "ghost" node)  */
-const deriveCenterEdges = (cfg, nodes, center, index, errors) => {
+const deriveCenterEdges = (cfg, nodes, center, index, parenProps, errors) => {
     const edges = new Array();
     for (const node of nodes) {
         if (node === center)
             continue;
-        const value = node.properties.find((property) => property.key === cfg.property)?.value;
+        const value = propValue(parenProps, node, cfg.property);
         const inbound = cfg.inbound !== undefined && value === cfg.inbound;
         const outbound = cfg.outbound !== undefined && value === cfg.outbound;
         const both = cfg.both !== undefined && value === cfg.both;
@@ -328,7 +335,7 @@ const deriveCenterEdges = (cfg, nodes, center, index, errors) => {
             continue;
         }
         const label = cfg.labeled !== undefined ?
-            node.properties.find((property) => property.key === cfg.labeled)?.value : undefined;
+            propValue(parenProps, node, cfg.labeled) : undefined;
         const name = label !== undefined ? plainText(expandReferences(label, (reference) => resolveUnique(index, reference, node).target?.name ?? reference)) : undefined;
         if (inbound || both)
             edges.push({ source: node, target: center, name });
@@ -340,7 +347,7 @@ const deriveCenterEdges = (cfg, nodes, center, index, errors) => {
 /*  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 deriveDiagram = (object, diagram, index, anchors, parents, parenProps) => {
     const type = diagram.type ?? "graph";
     const errors = new Array();
     /*  determine the node objects (default: the current object plus
@@ -362,7 +369,7 @@ const deriveDiagram = (object, diagram, index, anchors, parents) => {
     nodes = nodes.filter((node) => !edgeSet.has(node));
     const nodeSet = new Set(nodes);
     /*  derive the (deduplicated) edges of the diagram  */
-    let edges = deriveEdges(diagram, type, nodes, nodeSet, edgeObjects, index, anchors, parents, errors);
+    let edges = deriveEdges(diagram, type, nodes, nodeSet, edgeObjects, index, anchors, parents, parenProps, errors);
     /*  determine the center of a "hub" diagram (the only shape
         carrying a center at all)  */
     if (type !== "hub") {
@@ -372,14 +379,14 @@ const deriveDiagram = (object, diagram, index, anchors, parents) => {
             errors.push({ reason: `"${type}" diagram cannot carry a "centerEdges" configuration` });
     }
     const derived = type === "hub" ?
-        deriveCenter(object, diagram, nodes, nodeSet, index, anchors, errors) : { center: object };
+        deriveCenter(object, diagram, nodes, nodeSet, index, anchors, parenProps, errors) : { center: object };
     if (derived === undefined)
         return { errors };
     const { center, centerUrl } = derived;
     /*  synthesize the center edges of a "hub" diagram, as the nodes
         carry no "[[...]]" reference to a synthetic center  */
     if (type === "hub" && diagram.centerEdges !== undefined)
-        edges.push(...deriveCenterEdges(diagram.centerEdges, nodes, center, index, errors));
+        edges.push(...deriveCenterEdges(diagram.centerEdges, nodes, center, index, parenProps, errors));
     /*  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
@@ -415,16 +422,17 @@ const deriveDiagram = (object, diagram, index, anchors, parents) => {
         }
         nodes = nodes.filter((node) => connected.has(node));
     }
-    if (nodes.length === 0)
-        errors.push({ reason: "diagram yields no nodes" });
     if (errors.length > 0)
         return { errors };
-    /*  the "collapse" handling (enabled by default) silently omits a
-        degenerate 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)
+    /*  an empty node set silently omits the diagram, as a wildcard
+        "nodes" pattern legitimately matches nothing when an optional
+        kind is absent, and the "collapse" handling (enabled by default)
+        does the same for the degenerate diagram of a single node, as
+        such a diagram carries no information beyond the object itself  */
+    if (nodes.length === 0
+        || (diagram.collapse !== false && nodes.length === 1 && edges.length === 0))
         return { errors };
-    return { spec: renderSpec(diagram, type, center, centerUrl, nodes, edges, index, anchors),
+    return { spec: renderSpec(diagram, type, center, centerUrl, nodes, edges, index, anchors, parenProps),
         config: diagram.config, columns, errors };
 };
 /*  the memoized diagram derivations, keyed by specification, as the
@@ -442,10 +450,15 @@ export const specDiagrams = (specification, config) => {
     const parents = new Map();
     for (const node of index)
         parents.set(node.object, node.parent?.object);
+    const schemas = collectSchemas(specification, config);
+    /*  re-derive the synthetic properties of the consumed parenthesized
+        name tokens, as the derivation sees the AST alone, while the
+        parsing context holding them is long gone by export time  */
+    const parenProps = collectParenProps(schemas);
     const results = new Map();
-    for (const [object, schema] of collectSchemas(specification, config))
+    for (const [object, schema] of schemas)
         if (schema.diagram !== undefined)
-            results.set(object, deriveDiagram(object, schema.diagram, index, anchors, parents));
+            results.set(object, deriveDiagram(object, schema.diagram, index, anchors, parents, parenProps));
     derivations.set(specification, { config, results });
     return results;
 };

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

@@ -8,4 +8,5 @@ export type OutlineEntry = {
 };
 export declare const htmlOutline: (specification: Spec, config?: Schema) => OutlineEntry[];
 export declare const titlePageObject: (specification: Spec) => SpecObject | undefined;
+export declare const renderPlaceholder: (message: string) => string;
 export declare const renderHtml: (specification: Spec, config?: Schema, tocPages?: Map<string, number>, css?: string, realtime?: boolean, verbose?: Verbose) => Promise<string>;

package/dst/specbook-export-html.js

@@ -29,24 +29,7 @@ const templates = {
                     {{ Document.css }}
                 </style>
                 <script>
-                    (function () {
-                        let style = null
-                        try { style = localStorage.getItem("specbook-theme") }
-                        catch { /*  an inaccessible storage just means no stored choice  */ }
-                        if (style === null) {
-                            const m = document.documentElement.className.match(/theme-(light|dark)/)
-                            style = m !== null ? m[1] : null
-                        }
-                        if (style === null)
-                            style = window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light"
-                        document.documentElement.className = "theme-" + style
-                    })()
-                    function themeSwitch () {
-                        const style = document.documentElement.className === "theme-dark" ? "light" : "dark"
-                        document.documentElement.className = "theme-" + style
-                        try { localStorage.setItem("specbook-theme", style) }
-                        catch { /*  an inaccessible storage just loses the choice  */ }
-                    }
+                    {{ Document.themescript }}
                 </script>
             </head>
             <body>
@@ -72,6 +55,26 @@ const templates = {
             </body>
         </html>
     `,
+    /*  <Placeholder/>  */
+    "Placeholder": textframe `
+        <!DOCTYPE html>
+        <html>
+            <head>
+                <meta charset="utf-8"/>
+                <title>{{ Placeholder.title }}</title>
+                <style>
+                    {{ Placeholder.css }}
+                </style>
+                <script>
+                    {{ Placeholder.themescript }}
+                </script>
+            </head>
+            <body>
+                <div class="placeholder">{{ Placeholder.message }}</div>
+                <script class="realtime">{{ Placeholder.realtime }}</script>
+            </body>
+        </html>
+    `,
     /*  <TitlePage/>  */
     "TitlePage": textframe `
         <div class="titlepage" id="titlepage">
@@ -213,6 +216,41 @@ const templates = {
         </table>
     `
 };
+/*  the client-side script of the color theme: it applies the stored
+    choice (or, without one, the document default and finally the system
+    preference) before the first paint and toggles it on demand. The
+    live preview placeholder page carries it, too, as an in-place
+    document update never re-executes a head script  */
+const themeScript = textframe `
+    (function () {
+        let style = null
+        try { style = localStorage.getItem("specbook-theme") }
+        catch { /*  an inaccessible storage just means no stored choice  */ }
+        if (style === null) {
+            const m = document.documentElement.className.match(/theme-(light|dark)/)
+            style = m !== null ? m[1] : null
+        }
+        if (style === null)
+            style = window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light"
+        document.documentElement.className = "theme-" + style
+    })()
+    function themeSwitch () {
+        const style = document.documentElement.className === "theme-dark" ? "light" : "dark"
+        document.documentElement.className = "theme-" + style
+        try { localStorage.setItem("specbook-theme", style) }
+        catch { /*  an inaccessible storage just loses the choice  */ }
+    }
+`;
+/*  the minimal stylesheet of the live preview placeholder page: it also
+    provides the <style> element the in-place document update swaps with
+    the real stylesheet, so it carries the centered message only  */
+const placeholderStylesheet = textframe `
+    html.theme-light body { color: #333333; background-color: #ffffff }
+    html.theme-dark  body { color: #cccccc; background-color: #1a1a1a }
+    body { font-family: sans-serif; margin: 0 }
+    div.placeholder { position: absolute; top: 50%; left: 0; right: 0;
+        transform: translateY(-50%); text-align: center; opacity: 0.6 }
+`;
 /*  the client-side script of the live preview: it connects back to the
     own page over WebSocket (the URL scheme "http"/"https" replaced with
     "ws"/"wss"), re-connects every second after a lost connection, and
@@ -1179,6 +1217,19 @@ const makeLinker = (index) => (text, compact) => expandReferences(text, (referen
         `<a href="#${escapeHtml(anchorOf(target))}" class="link-compact"${specAttr(target)}>${target.name}</a>` :
         `<a href="#${escapeHtml(anchorOf(target))}" class="link-full">${full}</a>`;
 });
+/*  render the placeholder page of the live preview, served instead of
+    the document before the first successful export: it carries the very
+    same client-side script as the regular export, so the page recovers
+    on its own -- as the usual in-place document update -- once the
+    specification becomes exportable, plus a <style> element and the
+    color theme script the update expects to find in the head  */
+export const renderPlaceholder = (message) => render("Placeholder", { Placeholder: {
+        title: "SpecBook",
+        css: safe(placeholderStylesheet),
+        themescript: safe(themeScript),
+        realtime: safe(realtimeScript),
+        message
+    } });
 /*  render the entire specification into a self-contained HTML document,
     with the build-time pre-assembled stylesheet embedded inline, the
     artifact timestamps aggregated into min(Created)/max(Modified),
@@ -1239,6 +1290,7 @@ export const renderHtml = async (specification, config, tocPages, css, realtime
                 lang,
                 theme: documentThemeStyle(specification)?.toLowerCase(),
                 css: safe(css ?? stylesheet()),
+                themescript: safe(themeScript),
                 titlepage: title !== undefined ?
                     safe(renderTitlePage(title, formatDate(created), formatDate(modified))) : "",
                 search: safe(searchScript()),

package/dst/specbook-export-pdf.js

@@ -168,6 +168,10 @@ export const requireBrowser = async (verbose) => {
             `"${literal("npx playwright install chromium")}" once to download the Playwright Chromium`);
     return options;
 };
+/*  the bound of the ToC page number fixpoint iteration, as the page
+    number column itself shifts the pagination and hence the iteration
+    can oscillate instead of ever reaching a stable rendering  */
+const tocPasses = 3;
 /*  render a self-contained HTML document into a PDF via Playwright,
     re-rendering the HTML with the discovered ToC page numbers  */
 export const htmlToPdf = async (renderHtmlPass, heading, outline, titlePage, verbose, css, theme, paper = paperSizeDefault) => {
@@ -198,19 +202,27 @@ export const htmlToPdf = async (renderHtmlPass, heading, outline, titlePage, ver
         };
         /*  determine the ToC page numbers via a fixpoint iteration:
             paginate undecorated, extract the per-anchor pages, and
-            re-render until the HTML is stable (bounded to three
+            re-render until the HTML is stable (bounded to "tocPasses"
             passes), as the ToC page number column itself can shift
             the pagination  */
         verbose("determining ToC page numbers");
         let html = await renderHtmlPass();
         let plain = await renderPdf(html);
-        for (let i = 0; i < 3; i++) {
+        let stable = false;
+        for (let i = 0; i < tocPasses && !stable; i++) {
             const next = await renderHtmlPass(await anchorPages(plain));
-            if (next === html)
-                break;
-            html = next;
-            plain = await renderPdf(html);
+            stable = next === html;
+            if (!stable) {
+                html = next;
+                plain = await renderPdf(html);
+            }
         }
+        /*  report an unconverged iteration, as the ToC then carries the
+            page numbers of a pagination other than the final one and
+            would otherwise ship silently wrong page numbers  */
+        if (!stable)
+            verbose(`the ToC page numbers did not stabilize within ${literal(tocPasses)} ` +
+                "passes -- they can be off by a page", "notice");
         /*  render the final document, decorated with header/footer  */
         const decorated = await renderPdf(html, {
             displayHeaderFooter: true,

package/dst/specbook-format.md

@@ -416,8 +416,9 @@ type SchemaGradiaConfig = Partial<{
 
 -   `SchemaProperty.present?: boolean | string`:
     whether some value (`true`) or a value matching a regexp or enum
-    expression has to occur on at least one of the (existing) sibling
-    objects of the kind, so that `unique` plus `present` demand exactly one,
+    expression has to occur on at least one sibling object of the kind,
+    so that `unique` plus `present` demand exactly one and `present` on
+    an optional kind demands at least one object of that kind,
     BECAUSE some markers, like an initial state, are not just single but indispensable
 
 -   `SchemaProperty.local?: boolean`:

package/dst/specbook-link.d.ts

@@ -8,6 +8,7 @@ interface LinkNode {
     name: string;
 }
 export type LinkIndex = LinkNode[];
+export declare const assignId: (index: LinkIndex, object: SpecObject, id: string) => void;
 export declare const chainOf: (index: LinkIndex, object: SpecObject) => SpecObject[];
 export interface LinkTarget {
     target?: SpecObject;

package/dst/specbook-link.js

@@ -34,6 +34,13 @@ const lookup = (index) => {
     }
     return result;
 };
+/*  assign the id of an indexed object, dropping the lookup structures
+    of its index (and with them the memoized resolutions), as they are
+    keyed on the ids as of their build and would freeze the old one  */
+export const assignId = (index, object, id) => {
+    object.id = id;
+    lookups.delete(index);
+};
 /*  the ancestor-or-self chain of an object, root first
     (empty for an object unknown to the index)  */
 export const chainOf = (index, object) => {

package/dst/specbook-parse-semantic.d.ts

@@ -1,7 +1,8 @@
-import { type Spec, type SpecObject } from "./specbook-format-spec.js";
+import { type Spec, type SpecObject, type SpecProperty } from "./specbook-format-spec.js";
 import { type Schema, type SchemaObject } from "./specbook-format-schema.js";
 import { ParseContext } from "./specbook-parse-common.js";
 export declare const resolveArtifact: (config: Schema, object: SpecObject) => SchemaObject | undefined;
 export declare const collectSchemas: (specification: Spec, config: Schema) => Map<SpecObject, SchemaObject>;
+export declare const collectParenProps: (schemas: Map<SpecObject, SchemaObject>) => Map<SpecObject, SpecProperty>;
 export declare const validate: (ctx: ParseContext, specification: Spec, config: Schema) => void;
 export declare const validateReferences: (ctx: ParseContext, specification: Spec) => void;

package/dst/specbook-parse-semantic.js

@@ -3,7 +3,7 @@
 **  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
-import { referenceRegex, resolveUnique, resolveSet, chainOf, plainText } from "./specbook-link.js";
+import { referenceRegex, resolveUnique, resolveSet, chainOf, plainText, assignId } from "./specbook-link.js";
 import { compileValueExpr, splitItems, anchored } from "./specbook-parse-value.js";
 /*  the syntax of a value consisting of exactly one Wiki-style reference  */
 const singleReferenceRegex = /^\[\[([^[\]]+)\]\]$/;
@@ -112,21 +112,23 @@ const checkPropValue = (ctx, object, prop, expr, property, meta) => {
             `property "${prop.name}" value "${property.value}" is not a member of "${prop.value}"` :
             `property "${prop.name}" value "${property.value}" does not match pattern "${prop.value}"`);
 };
-/*  find the configured property whose value the trailing parenthesized
-    name token of an object is accepted for: the first still missing
+/*  derive the synthetic property the trailing parenthesized name token
+    of an object is consumed as: the first still missing configured
     property whose pattern the token matches  */
 const parenProp = (object, props) => {
     const paren = object.paren;
     if (paren === undefined)
         return undefined;
-    return props.find((prop) => prop.value !== undefined && !object.properties.some((p) => p.key === prop.name)
-        && directMatches(compileValueExpr(prop.value), paren));
+    const prop = props.find((p) => p.value !== undefined && !object.properties.some((q) => q.key === p.name)
+        && directMatches(compileValueExpr(p.value), paren));
+    return prop !== undefined ? { key: prop.name, value: paren } : undefined;
 };
 /*  check the property values flagged unique for distinctness among
     the sibling objects of the same kind and the ones flagged present
-    for occurring on at least one of the (existing) siblings (all
-    values, or only the values matching the regexp or enum expression
-    of the flag)  */
+    for occurring on at least one sibling (all values, or only the
+    values matching the regexp or enum expression of the flag), where
+    a kind without any sibling fails a present flag, too, but only for
+    an optional kind, as the missing-kind check reports a required one  */
 const checkSiblingFlags = (ctx, object, childs, meta) => {
     const marker = (flag) => flag === undefined || flag === false ? undefined :
         { filter: typeof flag === "string" ? compileValueExpr(flag) : undefined };
@@ -157,7 +159,7 @@ const checkSiblingFlags = (ctx, object, childs, meta) => {
                         `already used by preceding ${sibling.kind} "${first.name}"`);
                 }
             }
-            if (present !== undefined && siblings.length > 0 && !found)
+            if (present !== undefined && (siblings.length > 0 || child.optional === true) && !found)
                 ctx.diagnose(meta.file, meta.line, `no ${child.kind} below ${object.kind} "${object.name}" carries property "${prop.name}"` +
                     (typeof prop.present === "string" ? ` with a value matching "${prop.present}"` : ""));
         }
@@ -255,6 +257,19 @@ export const collectSchemas = (specification, config) => {
     }
     return schemas;
 };
+/*  derive the synthetic properties supplied by the consumed parenthesized
+    name tokens of a schema mapping, so a consumer without a parsing
+    context -- the diagram derivation of an export -- sees exactly the
+    properties the validation sees  */
+export const collectParenProps = (schemas) => {
+    const parenProps = new Map();
+    for (const [object, schema] of schemas) {
+        const property = parenProp(object, schema.props ?? []);
+        if (property !== undefined)
+            parenProps.set(object, property);
+    }
+    return parenProps;
+};
 /*  report the objects colliding on kind and id among their siblings
     (recursively from the artifacts down), as such objects derive
     identical anchor paths and hence cannot be addressed distinctly  */
@@ -469,19 +484,16 @@ export const validate = (ctx, specification, config) => {
         precedence), which has to happen before any property check, as
         those resolve references by id across all artifacts  */
     const schemas = collectSchemas(specification, config);
+    for (const [object, property] of collectParenProps(schemas))
+        ctx.parenProps.set(object, property);
     const promote = (object) => {
         /*  an object below an unresolved artifact or an unknown kind
             carries no schema and hence no property able to consume the
             token, so the token still acts as the id and a single
             unresolved heading no longer cascades into unresolvable
             references all over the corpus  */
-        if (object.paren !== undefined) {
-            const prop = parenProp(object, schemas.get(object)?.props ?? []);
-            if (prop !== undefined)
-                ctx.parenProps.set(object, { key: prop.name, value: object.paren });
-            else if (object.anchor === undefined)
-                object.id = object.paren;
-        }
+        if (object.paren !== undefined && object.anchor === undefined && !ctx.parenProps.has(object))
+            assignId(ctx.linkIndex, object, object.paren);
         object.childs.forEach(promote);
     };
     for (const artifact of specification.artifacts)

package/dst/specbook-parse-syntax.js

@@ -201,13 +201,15 @@ const parseConcise = (ctx, item, parent, file, line, group) => {
     let kind;
     let name;
     if (group !== undefined) {
-        const nm = head.match(/^`([^`]+)`$|^([^`:]+)$/);
+        const nm = head.match(/^`([^`]+)`\s*([^`]*)$|^([^`:]+)$/);
         if (nm === null) {
             ctx.diagnose(file, line, `unrecognized ${group} item "${text}"`);
             return;
         }
         kind = group;
-        name = (nm[1] ?? nm[2]).trim();
+        /*  a backquoted name keeps its trailing decorations outside the
+            backquotes, so they are re-joined for the marker detection below  */
+        name = (nm[1] !== undefined ? `${nm[1]} ${nm[2]}` : nm[3]).trim();
     }
     else {
         const km = head.match(/^([^:]+):\s*(.*)$/);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":                                "@rse/specbook",
-    "version":                             "1.2.1",
+    "version":                             "1.2.2",
     "publishConfig":                       { "access": "public" },
     "description":                         "Markdown-based Specification Format (API, CLI and MCP service)",
     "license":                             "Apache-2.0",