@rse/specbook 1.2.1 → 1.2.3

package/dst/specbook-export-common.js

@@ -4,6 +4,7 @@
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
 import fs from "node:fs";
+import { plainText } from "./specbook-link.js";
 /*  escape a text for embedding into template HTML (text and attributes)  */
 export const escapeHtml = (text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
     .replace(/"/g, "&quot;").replace(/'/g, "&#39;");
@@ -128,24 +129,16 @@ const typographyGlyphs = [
     0x00A0, 0x00AB, 0x00BB, 0x2013, 0x2014, 0x2018, 0x2019,
     0x201A, 0x201C, 0x201D, 0x201E, 0x2022, 0x2026, 0x2039, 0x203A
 ];
-/*  the memoized subsetted stylesheets, keyed by the (shared) codepoint
-    set of the charset, as the font subsetting is expensive and the
-    formats of a single export, the watch and preview re-exports, and
-    the MCP service request the very same subset over and over again  */
+/*  the memoized subsetted stylesheets (as pending or settled promises,
+    so concurrent requests share a single subsetting), keyed by the
+    (shared) codepoint set of the charset, as the font subsetting is
+    expensive and the formats of a single export, the watch and preview
+    re-exports, and the MCP service request the very same subset over
+    and over again  */
 const subsetCache = new Map();
-/*  provide the stylesheet with its embedded fonts subsetted to the
-    codepoints of a charset plus the always-used symbol and typography
-    glyphs (no charset or a full Unicode charset keeps the fonts complete)  */
-export const subsetStylesheet = async (charset) => {
-    const codepoints = charset !== undefined ? charsetCodepoints(charset) : undefined;
-    if (codepoints === undefined)
-        return stylesheet();
-    const cached = subsetCache.get(codepoints);
-    if (cached !== undefined)
-        return cached;
-    const css = stylesheet();
+/*  subset the embedded fonts of a stylesheet to the glyphs of a text  */
+const subsetFonts = async (css, text) => {
     const { default: subsetFont } = await import("subset-font");
-    const text = String.fromCodePoint(...codepoints, ...symbolGlyphs, ...typographyGlyphs);
     let result = "";
     let last = 0;
     for (const m of css.matchAll(/url\("data:font\/woff2;base64,([^"]+)"\)/g)) {
@@ -154,18 +147,36 @@ export const subsetStylesheet = async (charset) => {
             `url("data:font/woff2;base64,${subset.toString("base64")}")`;
         last = m.index + m[0].length;
     }
-    const subsetted = result + css.slice(last);
-    subsetCache.set(codepoints, subsetted);
+    return result + css.slice(last);
+};
+/*  provide the stylesheet with its embedded fonts subsetted to the
+    codepoints of a charset plus the always-used symbol and typography
+    glyphs (no charset or a full Unicode charset keeps the fonts complete),
+    where a failed subsetting leaves the cache, so the next request retries  */
+export const subsetStylesheet = async (charset) => {
+    const codepoints = charset !== undefined ? charsetCodepoints(charset) : undefined;
+    if (codepoints === undefined)
+        return stylesheet();
+    let subsetted = subsetCache.get(codepoints);
+    if (subsetted === undefined) {
+        const text = String.fromCodePoint(...codepoints, ...symbolGlyphs, ...typographyGlyphs);
+        subsetted = subsetFonts(stylesheet(), text);
+        subsetted.catch(() => { subsetCache.delete(codepoints); });
+        subsetCache.set(codepoints, subsetted);
+    }
     return subsetted;
 };
 /*  determine the document title and subtitle from the title object (an
-    empty TITLE counts as absent, exactly like for the title page)  */
+    empty TITLE counts as absent, exactly like for the title page), with
+    the inline code markup stripped, as the plain-text targets (the HTML
+    <title>, the PDF metadata and page header) render no Markdown  */
 export const documentTitle = (specification) => {
     const title = titleProperty(specification, "TITLE")?.trim();
+    const subtitle = titleProperty(specification, "SUBTITLE")?.trim();
     return {
-        title: title !== undefined && title !== "" ? title :
-            titleObject(specification)?.name ?? "Specification",
-        subtitle: titleProperty(specification, "SUBTITLE")?.trim()
+        title: plainText(title !== undefined && title !== "" ? title :
+            titleObject(specification)?.name ?? "Specification"),
+        subtitle: subtitle !== undefined ? plainText(subtitle) : undefined
     };
 };
 /*  determine the document logo as a self-contained data: URL, taken from the

package/dst/specbook-export-html.css

@@ -81,6 +81,8 @@ html.theme-light {
   --theme-color-specbook-popup-schema-desc: var(--theme-color-base-32);
   --theme-color-specbook-popup-spec-path: var(--theme-color-accent-12);
   --theme-color-specbook-popup-spec-desc: var(--theme-color-base-5);
+  --theme-color-specbook-progress-done: var(--theme-color-accent-12);
+  --theme-color-specbook-progress-todo: var(--theme-color-accent-31);
   --gradia-font-family: "Source Sans 3";
   --gradia-color-node-regular-name: var(--theme-color-accent-12);
   --gradia-color-node-regular-box: var(--theme-color-accent-30);
@@ -122,6 +124,8 @@ html.theme-light {
     --theme-color-specbook-popup-schema-desc: var(--theme-color-base-7);
     --theme-color-specbook-popup-spec-path: var(--theme-color-accent-24);
     --theme-color-specbook-popup-spec-desc: var(--theme-color-base-29);
+    --theme-color-specbook-progress-done: var(--theme-color-accent-24);
+    --theme-color-specbook-progress-todo: var(--theme-color-accent-4);
     --gradia-color-node-regular-name: var(--theme-color-accent-21);
     --gradia-color-node-regular-box: var(--theme-color-accent-3);
     --gradia-color-node-regular-border: var(--theme-color-accent-7);
@@ -437,6 +441,64 @@ div.realtime-status.reloaded svg.realtime-icon {
     display: none;
   }
 }
+/*  the scroll progress meter (screen-only): a ring at the bottom right
+    corner of the viewport (fixed independent of the content scrolling),
+    whose DONE part (the arc drawn clockwise from the top, together with
+    the upward arrow in its center, drawn like the tab icons) reflects
+    the scrolled fraction of the document over the TODO part (the full
+    circle in the lighter progress color beneath), which stays hidden
+    while the page is scrolled near the top (fading in once scrolled
+    beyond 400px) and scrolls the page back to the top on click, where
+    the DONE part and the arrow brighten on hover like the tabs  */
+div.scroll-progress {
+  position: fixed;
+  right: 1.5rem;
+  bottom: 1.5rem;
+  z-index: 30;
+  width: 3rem;
+  height: 3rem;
+  line-height: 0;
+  color: var(--theme-color-specbook-progress-done);
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.3s ease;
+  cursor: pointer;
+  -webkit-user-select: none;
+  user-select: none;
+}
+div.scroll-progress.shown {
+  opacity: 1;
+  pointer-events: auto;
+}
+div.scroll-progress:hover {
+  color: var(--theme-color-specbook-accent-soft);
+}
+div.scroll-progress svg.scroll-ring {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  transform: rotate(-90deg);
+}
+div.scroll-progress svg.scroll-ring circle.scroll-todo {
+  stroke: var(--theme-color-specbook-progress-todo);
+}
+div.scroll-progress svg.scroll-ring circle.scroll-done {
+  stroke: currentColor;
+}
+div.scroll-progress svg.scroll-icon {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 1.1rem;
+  height: 1.1rem;
+  transform: translate(-50%, -50%);
+}
+@media print {
+  div.scroll-progress {
+    display: none;
+  }
+}
 /*  the side panel of the table of contents (screen-only): a fixed
     full-height drawer at the left viewport edge, carrying a replica of
     the brand bar on its right edge, which exactly covers the brand bar

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>
@@ -60,18 +43,40 @@ const templates = {
                         <span class="search-clear" id="search-clear" title="clear search">&#x00D7;</span>
                     </div>
                 </div>
+                <div class="scroll-progress" title="scroll to top"><svg class="scroll-ring" viewBox="0 0 44 44" fill="none" stroke-width="2.5"><circle class="scroll-todo" cx="22" cy="22" r="20"/><circle class="scroll-done" cx="22" cy="22" r="20" stroke-linecap="round" pathLength="1" stroke-dasharray="1" stroke-dashoffset="1"/></svg><svg class="scroll-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="M12 19V5"/><path d="M5 12l7-7 7 7"/></svg></div>
                 {{ Document.tocpanel }}
                 {{ Document.titlepage }}
                 {{ Document.toc }}
                 {{ Document.doc }}
                 {{ Document.artifacts }}
                 {% if Document.search %}<script>{{ Document.search }}</script>{% endif %}
+                <script>{{ Document.progress }}</script>
                 {% if Document.tocpanel %}<script>{{ Document.tocscript }}</script>{% endif %}
                 {% if Document.info %}<script>{{ Document.info }}</script>{% endif %}
                 {% if Document.realtime %}<script class="realtime">{{ Document.realtime }}</script>{% endif %}
             </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,8 +218,43 @@ const templates = {
         </table>
     `
 };
-/*  the client-side script of the live preview: it connects back to the
-    own page over WebSocket (the URL scheme "http"/"https" replaced with
+/*  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
+    its own page over WebSocket (the URL scheme "http"/"https" replaced with
     "ws"/"wss"), re-connects every second after a lost connection, and
     updates the page on a received "RELOAD" command as well as on every
     re-established connection (as the server was restarted meanwhile).
@@ -237,7 +277,11 @@ const realtimeScript = textframe `
                 icon.className = "realtime-status " + state
         }
         let blink = 0
+        let seq   = 0
         const update = async () => {
+            /*  a superseded update (an overlapping newer one started
+                meanwhile) is dropped, as its stale page could arrive last  */
+            const mine = ++seq
             let response
             try {
                 response = await fetch(window.location.pathname, { cache: "no-store" })
@@ -248,7 +292,10 @@ const realtimeScript = textframe `
             }
             if (!response.ok)
                 return
-            const doc = new DOMParser().parseFromString(await response.text(), "text/html")
+            const html = await response.text()
+            if (mine !== seq)
+                return
+            const doc = new DOMParser().parseFromString(html, "text/html")
             const x = window.scrollX
             const y = window.scrollY
             document.title = doc.title
@@ -294,6 +341,47 @@ const realtimeScript = textframe `
         connect()
     })()
 `;
+/*  the client-side script of the scroll progress meter: it drives the
+    DONE arc of the ring (through the dash offset of its unit-length
+    circle) with the scrolled fraction of the document, shows the meter
+    once the page is scrolled beyond 400px, and scrolls the page back
+    to the top on a click (stripping the URL hash, so a later reload
+    stays at the top). The updates are throttled onto animation frames,
+    and the window-bound listeners retire themselves once a live preview
+    body swap replaced the meter (whose fresh script re-attaches)  */
+const scrollProgressScript = textframe `
+    (function () {
+        const meter = document.querySelector("div.scroll-progress")
+        const ring  = meter.querySelector("circle.scroll-done")
+        let ticking = false
+        const update = () => {
+            ticking = false
+            if (!meter.isConnected) {
+                window.removeEventListener("scroll", schedule)
+                window.removeEventListener("resize", schedule)
+                return
+            }
+            const doc = document.documentElement
+            const max = doc.scrollHeight - doc.clientHeight
+            ring.setAttribute("stroke-dashoffset", String(1 - (max > 0 ? doc.scrollTop / max : 0)))
+            meter.classList.toggle("shown", doc.scrollTop > 400)
+        }
+        const schedule = () => {
+            if (!ticking) {
+                ticking = true
+                requestAnimationFrame(update)
+            }
+        }
+        meter.addEventListener("click", () => {
+            window.scrollTo({ top: 0, behavior: "smooth" })
+            if (window.location.hash)
+                history.replaceState(null, "", window.location.pathname + window.location.search)
+        })
+        window.addEventListener("scroll", schedule, { passive: true })
+        window.addEventListener("resize", schedule)
+        update()
+    })()
+`;
 /*  the client-side script of the table of contents side panel: it
     slides the panel out of and back into the viewport edge (closing it
     also on a jump, on "Escape", and on a click outside), remembers the
@@ -618,8 +706,19 @@ const env = new nunjucks.Environment(null, { autoescape: true });
 nunjucksAddons(env);
 /*  mark pre-rendered HTML as safe for template interpolation  */
 const safe = (html) => new nunjucks.runtime.SafeString(html);
+/*  the built-in Nunjucks templates compiled on first use, as
+    renderString() would re-compile a template on every single call
+    (i.e. for every rendered object, property table, and description)  */
+const compiled = new Map();
 /*  render one of the built-in Nunjucks templates with a context  */
-const render = (name, context) => env.renderString(templates[name], context);
+const render = (name, context) => {
+    let template = compiled.get(name);
+    if (template === undefined) {
+        template = new nunjucks.Template(templates[name], env, undefined, true);
+        compiled.set(name, template);
+    }
+    return template.render(context);
+};
 /*  the active per-document reference expander, fully-qualified
     anchor paths, member-carrying property value constraints, object
     schema nodes, pre-rendered diagram SVGs, description popup keys
@@ -944,8 +1043,8 @@ const diagramOf = (object) => {
     headers of a plain table  */
 const renderTable = (childs, maxColumns) => {
     const { keys, desc } = tableShape(childs);
-    const diagrams = childs.some((child) => diagramOf(child) !== "");
-    if (!diagrams && 1 + keys.length + (desc ? 1 : 0) <= maxColumns)
+    const diagrammed = childs.some((child) => diagramOf(child) !== "");
+    if (!diagrammed && 1 + keys.length + (desc ? 1 : 0) <= maxColumns)
         return render("Table", { Table: {
                 head: childs[0].kind !== "" ? childs[0].kind : "Name",
                 info: infoKeyOf(childs[0]),
@@ -1179,6 +1278,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),
@@ -1191,47 +1303,48 @@ export const renderHtml = async (specification, config, tocPages, css, realtime
     /*  the document language selects the smart typography quote style  */
     const lang = documentLang(specification);
     quotes = quoteStyles[lang?.toLowerCase().split(/[-_]/)[0] ?? "en"] ?? quoteStyles.en;
-    /*  establish the per-document rendering state  */
+    /*  establish the per-document rendering state (released again
+        below, also on a failure of the collecting or rendering)  */
     const index = buildLinkIndex(specification);
-    anchors = anchorPaths(index);
-    members = config !== undefined ? collectMembers(config, new Map()) : null;
-    schemas = config !== undefined ? collectSchemas(specification, config) : null;
-    diagrams = rendered;
-    /*  collect the schema descriptions for the description popups,
-        plus the object parents composing their title paths  */
-    let info = null;
-    if (config !== undefined) {
-        infoKeys = new Map();
-        info = {};
-        collectInfo(config, "", infoKeys, info);
-        const parents = new Map();
-        for (const node of index)
-            if (node.parent !== undefined)
-                parents.set(node.object, node.parent.object);
-        infoParents = parents;
-    }
-    linker = makeLinker(index);
-    /*  collect the corpus descriptions of the object instances for the
-        description popups (after the linker is in place, as the
-        pre-rendered descriptions expand their references, too)  */
-    let spec = null;
-    if (info !== null) {
-        spec = {};
-        for (const artifact of specification.artifacts)
-            collectSpec(artifact.objects, spec);
-    }
-    /*  the artifact timestamps aggregate into the earliest creation
-        and the latest modification timestamp of the document  */
-    const created = new Date(Math.min(...specification.artifacts.map((artifact) => artifact.created.getTime())));
-    const modified = new Date(Math.max(...specification.artifacts.map((artifact) => artifact.modified.getTime())));
-    /*  a "META: Title" object becomes the title page and leaves the regular
-        flow, while its diagram becomes the "Diagram of Contents" page  */
-    const title = titlePageObject(specification);
-    const artifacts = specification.artifacts
-        .filter((artifact) => !artifact.objects.some(isTitleObject));
-    const meta = titleObject(specification);
-    const doc = meta !== undefined ? rendered?.get(meta) : undefined;
     try {
+        anchors = anchorPaths(index);
+        members = config !== undefined ? collectMembers(config, new Map()) : null;
+        schemas = config !== undefined ? collectSchemas(specification, config) : null;
+        diagrams = rendered;
+        /*  collect the schema descriptions for the description popups,
+            plus the object parents composing their title paths  */
+        let info = null;
+        if (config !== undefined) {
+            infoKeys = new Map();
+            info = {};
+            collectInfo(config, "", infoKeys, info);
+            const parents = new Map();
+            for (const node of index)
+                if (node.parent !== undefined)
+                    parents.set(node.object, node.parent.object);
+            infoParents = parents;
+        }
+        linker = makeLinker(index);
+        /*  collect the corpus descriptions of the object instances for the
+            description popups (after the linker is in place, as the
+            pre-rendered descriptions expand their references, too)  */
+        let spec = null;
+        if (info !== null) {
+            spec = {};
+            for (const artifact of specification.artifacts)
+                collectSpec(artifact.objects, spec);
+        }
+        /*  the artifact timestamps aggregate into the earliest creation
+            and the latest modification timestamp of the document  */
+        const created = new Date(Math.min(...specification.artifacts.map((artifact) => artifact.created.getTime())));
+        const modified = new Date(Math.max(...specification.artifacts.map((artifact) => artifact.modified.getTime())));
+        /*  a "META: Title" object becomes the title page and leaves the regular
+            flow, while its diagram becomes the "Diagram of Contents" page  */
+        const title = titlePageObject(specification);
+        const artifacts = specification.artifacts
+            .filter((artifact) => !artifact.objects.some(isTitleObject));
+        const meta = titleObject(specification);
+        const doc = meta !== undefined ? rendered?.get(meta) : undefined;
         const objects = artifacts.flatMap((artifact) => artifact.objects);
         const entries = tocEntries(objects, tocPages);
         return render("Document", { Document: {
@@ -1239,9 +1352,11 @@ 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()),
+                progress: safe(scrollProgressScript),
                 info: info !== null ? safe(infoScript(info, spec ?? {})) : "",
                 realtime: realtime ? safe(realtimeScript) : "",
                 toc: entries.length > 0 ? safe(render("Toc", { Toc: { entries } })) : "",

package/dst/specbook-export-md.js

@@ -33,13 +33,15 @@ const renderDescriptionMd = (description) => description.description + (descript
 const nameSuffixMd = (object) => (object.primary === true ? " (*)" : "") +
     (object.paren !== undefined ? ` (${object.paren})` : "") +
     (object.anchor !== undefined ? ` {{${object.anchor}}}` : "");
-/*  whether any descendant of an object carries a description which no
-    Concise Format item can carry -- a multi-line one (a fenced code
-    block, an ordered list, a blockquote, or multiple paragraphs) or one
-    carrying a ";", as only a ";"-free description stays a single segment
-    on re-parsing instead of splitting off a spurious property  */
-const complexBelowMd = (object) => object.childs.some((child) => (child.description !== undefined
-    && /[\n;]/.test(renderDescriptionMd(child.description))) || complexBelowMd(child));
+/*  whether any descendant of an object carries a name or a description
+    which no Concise Format item can carry -- a name carrying a ";" (it
+    would split the head segment), or a multi-line description (a fenced
+    code block, an ordered list, a blockquote, or multiple paragraphs) or
+    one carrying a ";", as only a ";"-free description stays a single
+    segment on re-parsing instead of splitting off a spurious property  */
+const complexBelowMd = (object) => object.childs.some((child) => child.name.includes(";")
+    || (child.description !== undefined
+        && /[\n;]/.test(renderDescriptionMd(child.description))) || complexBelowMd(child));
 /*  render an object in the Concise Format as a list item of the
     given nesting depth, with its childs as nested list items  */
 const renderConciseMd = (object, depth = 0) => {

package/dst/specbook-export-pdf.js

@@ -39,8 +39,10 @@ const addOutline = async (doc, entries) => {
     if (dests !== undefined) {
         for (const [name] of dests.entries()) {
             const dest = dests.lookup(name);
-            const page = dest instanceof PDFArray ? dest.get(0) : undefined;
-            if (dest instanceof PDFArray && page instanceof PDFRef && live.has(page.toString()))
+            if (!(dest instanceof PDFArray))
+                continue;
+            const page = dest.get(0);
+            if (page instanceof PDFRef && live.has(page.toString()))
                 targets.set(name.decodeText(), dest);
         }
     }
@@ -168,6 +170,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 +204,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-schema.js

@@ -16,6 +16,8 @@ const GradiaConfigSchemas = Object.fromEntries(Object.entries(Gradia.config).map
         typeof value === "number" ? v.pipe(v.number(), v.finite(), v.minValue(0)) : v.string()]));
 const SchemaDiagramConfig = v.partial(v.strictObject(GradiaConfigSchemas, (issue) => issue.expected === "never" ? "unknown Gradia rendering option" :
     "expected a map of Gradia rendering options"));
+/*  the Valibot schemas mirroring the types above, with the object
+    kind schema referencing itself lazily for the nested childs  */
 const SchemaProperty = v.strictObject({
     name: v.string(),
     desc: v.optional(v.string()),

package/dst/specbook-format-spec.js

@@ -5,6 +5,8 @@
 */
 import * as v from "valibot";
 /*  ==== Schema ====  */
+/*  the Valibot schemas mirroring the types above, with the object
+    schema referencing itself lazily for the nested childs  */
 const SpecProperty = v.object({
     key: v.string(),
     value: v.string(),

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`: