@rse/specbook 1.1.0 → 1.2.1

package/dst/specbook-export-common.js

@@ -116,26 +116,34 @@ export const charsetCodepoints = (charset) => {
         "(expected US-ASCII, ISO-8859-1/ISO-Latin-1, ISO-8859-15/ISO-Latin-9, or UTF-8)");
 };
 /*  the symbol glyphs used by the HTML/PDF rendering (kind and property
-    bullets, link symbol, primary marker, theme switch icon, anchor
-    symbol plus its text presentation variation selector, the search
-    field clearing icon, the active entry pointer of the table of
-    contents side panel, and the title path segment pointer of the
+    bullets, link symbol, primary marker, anchor symbol plus its text
+    presentation variation selector, the search field clearing icon,
+    the absent property marker, the active entry pointer of the table
+    of contents side panel, and the title path segment pointer of the
     description popups)  */
-const symbolGlyphs = [0x25CF, 0x25CB, 0x26AD, 0x2318, 0x25D0, 0x2693, 0xFE0E, 0x00D7, 0x25C0, 0x25B7];
+const symbolGlyphs = [0x25CF, 0x25CB, 0x26AD, 0x2318, 0x2693, 0xFE0E, 0x00D7, 0x2205, 0x25C0, 0x25B7];
 /*  the typographic glyphs producible by the smart typography rendering
     (language-specific quotes, dashes, ellipsis, bullet, nbsp)  */
 const typographyGlyphs = [
     0x00A0, 0x00AB, 0x00BB, 0x2013, 0x2014, 0x2018, 0x2019,
     0x201A, 0x201C, 0x201D, 0x201E, 0x2022, 0x2026, 0x2039, 0x203A
 ];
+/*  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  */
+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 css = stylesheet();
     const codepoints = charset !== undefined ? charsetCodepoints(charset) : undefined;
     if (codepoints === undefined)
-        return css;
+        return stylesheet();
+    const cached = subsetCache.get(codepoints);
+    if (cached !== undefined)
+        return cached;
+    const css = stylesheet();
     const { default: subsetFont } = await import("subset-font");
     const text = String.fromCodePoint(...codepoints, ...symbolGlyphs, ...typographyGlyphs);
     let result = "";
@@ -146,14 +154,20 @@ export const subsetStylesheet = async (charset) => {
             `url("data:font/woff2;base64,${subset.toString("base64")}")`;
         last = m.index + m[0].length;
     }
-    return result + css.slice(last);
+    const subsetted = result + css.slice(last);
+    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)  */
+export const documentTitle = (specification) => {
+    const title = titleProperty(specification, "TITLE")?.trim();
+    return {
+        title: title !== undefined && title !== "" ? title :
+            titleObject(specification)?.name ?? "Specification",
+        subtitle: titleProperty(specification, "SUBTITLE")?.trim()
+    };
 };
-/*  determine the document title and subtitle from the title object  */
-export const documentTitle = (specification) => ({
-    title: titleProperty(specification, "TITLE") ??
-        titleObject(specification)?.name ?? "Specification",
-    subtitle: titleProperty(specification, "SUBTITLE")
-});
 /*  determine the document logo as a self-contained data: URL, taken from the
     first embedded image of the LOGO property of the title object -- the light
     variant of a "{theme}" reference -- and falling back onto the built-in

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

@@ -1,9 +1,11 @@
-import type { Spec } from "./specbook-format-spec.js";
+import type { Spec, SpecObject } from "./specbook-format-spec.js";
 import type { Schema } from "./specbook-format-schema.js";
+import type { Verbose } from "./specbook-verbose.js";
 export type OutlineEntry = {
     title: string;
     anchor: string;
     childs: OutlineEntry[];
 };
 export declare const htmlOutline: (specification: Spec, config?: Schema) => OutlineEntry[];
-export declare const renderHtml: (specification: Spec, config?: Schema, tocPages?: Map<string, number>, css?: string, realtime?: boolean) => Promise<string>;
+export declare const titlePageObject: (specification: Spec) => SpecObject | undefined;
+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

@@ -14,7 +14,7 @@ import { compileValueExpr, splitItems } from "./specbook-parse-value.js";
 import { embeddingRegex, embeddingMimeType, embeddingThemes, embeddingVariants } from "./specbook-parse-common.js";
 import { escapeHtml, stylesheet, searchScript, fallbackLogo, isTitleObject, titleObject, documentTitle, documentLang, documentThemeStyle } from "./specbook-export-common.js";
 import { collectSchemas } from "./specbook-parse-semantic.js";
-import { specDiagrams } from "./specbook-diagram.js";
+import { renderDiagrams } from "./specbook-diagram.js";
 /*  ==== Templates ====  */
 /*  the built-in Nunjucks templates for the HTML export  */
 const templates = {
@@ -238,7 +238,14 @@ const realtimeScript = textframe `
         }
         let blink = 0
         const update = async () => {
-            const response = await fetch(window.location.pathname, { cache: "no-store" })
+            let response
+            try {
+                response = await fetch(window.location.pathname, { cache: "no-store" })
+            }
+            catch {
+                /*  an unreachable server just skips the update  */
+                return
+            }
             if (!response.ok)
                 return
             const doc = new DOMParser().parseFromString(await response.text(), "text/html")
@@ -386,35 +393,18 @@ const tocPanelScript = textframe `
     })()
 `;
 /*  the client-side script of the description popups: the info tab
-    toggles the popups on and off (default), persisting the choice
-    across page loads, and while they are on, hovering an element
-    carrying a "data-info" key shows the schema description of its
-    object kind (or, with "data-info-prop", of its property), while
-    hovering an element carrying a "data-info-spec" key (an object
-    name) shows the corpus description of the object instance, in a
-    single shared popup -- a hovered diagram node box resolves through
-    its hyperlinked object anchor to the instance popup attributes of
-    the object's heading name or table row name -- opened only after
-    the mouse rested 400ms on the element (so mere mouse movements
-    across the page pop nothing up), titled with the "data-info-path"
-    object path (one filled-circle "KIND: Name" segment per level,
-    arbitrarily deep and separated by the icons alone, ending for
-    a kind in the bare kind and extended for a property with the
-    not-filled-circle property name, styled as in the document
-    content: the kinds and the property bold in the path color, the
-    names bold in the description color)
-    and fed from the injected INFO
-    map of pre-rendered schema description HTML or SPEC map of
-    pre-rendered corpus description HTML (a missing entry pops up
-    the title path alone), the description led by a bold "Schema:"
-    or "Specification:" label naming its origin (a corpus-fed
-    instance popup additionally carrying the page background colors
-    instead of the accent), where the popup is
-    capped at 40% viewport width and attached above or below the
-    hovered element, whichever side offers more viewport space; the
+    toggles the popups (off by default, persisted across page loads),
+    and while they are on, a mouse resting 400ms on an element carrying
+    a "data-info" key (plus "data-info-prop" for a property) pops up the
+    schema description of its object kind (or property), while one
+    carrying a "data-info-spec" key pops up the corpus description of
+    the object instance (a diagram node box resolves through its
+    hyperlinked object anchor), titled with the "data-info-path" object
+    path and fed from the injected INFO/SPEC maps of pre-rendered
+    description HTML; the popup is capped at 40% viewport width and
+    attached above or below, whichever side offers more space; the
     script runs at the end of the body, so a live preview body swap
-    replaces the popup element and the body-bound listeners along
-    with the re-executed script  */
+    replaces the popup and the body-bound listeners along with it  */
 const infoPopupScript = textframe `
     (function (INFO, SPEC) {
         const popup = document.createElement("div")
@@ -516,7 +506,7 @@ const infoPopupScript = textframe `
                 title.appendChild(name)
             }
             popup.replaceChildren(title)
-            const entry = INFO[key]
+            const entry = key !== null ? INFO[key] : undefined
             const desc  = prop !== null ? entry?.p?.[prop] :
                 (spec !== null ? SPEC[spec] : entry?.d)
             if (desc !== undefined) {
@@ -646,19 +636,16 @@ let infoParents = null;
     resolution of the references inside them (nearest object wins),
     established around every object rendering and restored afterwards  */
 let scope = null;
-const scoped = (object, render) => {
+const scoped = (object, body) => {
     const outer = scope;
     scope = object;
     try {
-        return render();
+        return body();
     }
     finally {
         scope = outer;
     }
 };
-/*  the cache of the pre-rendered diagram SVGs, keyed by specification,
-    as the PDF export renders the very same document multiple times  */
-const diagramCache = new WeakMap();
 /*  determine the fully-qualified anchor path of an object  */
 const anchorOf = (object) => anchors?.get(object) ?? object.id;
 /*  determine the description popup key of an object (the qualified
@@ -942,6 +929,12 @@ const renderCell = (child) => {
     html += renderChilds(child, 6, true);
     return html.trim() !== "" ? html : "<span class=\"value-absent\"></span>";
 };
+/*  the pre-rendered diagram of an object as an embeddable block
+    (empty for an object without a configured or renderable diagram)  */
+const diagramOf = (object) => {
+    const diagram = diagrams?.get(object);
+    return diagram !== undefined ? safe(`<div class="diagram">${diagram}</div>`) : "";
+};
 /*  render a single-kind group of childs into one compact table:
     the name first, then the property columns, then the description;
     a group wider than maxColumns, or carrying diagrams, instead chunks
@@ -990,8 +983,8 @@ const renderTable = (childs, maxColumns) => {
                     cells.push({ key: "Description", desc: true, span: 1,
                         value: safe(renderCell(child)) });
                 const chunks = new Array();
-                for (let i = 0; i < cells.length; i += size)
-                    chunks.push(cells.slice(i, i + size));
+                for (let pos = 0; pos < cells.length; pos += size)
+                    chunks.push(cells.slice(pos, pos + size));
                 if (chunks.length > 0) {
                     const last = chunks[chunks.length - 1];
                     last[last.length - 1].span = size - last.length + 1;
@@ -1014,12 +1007,6 @@ const renderTable = (childs, maxColumns) => {
             }))
         } });
 };
-/*  the pre-rendered diagram of an object as an embeddable block
-    (empty for an object without a configured or renderable diagram)  */
-const diagramOf = (object) => {
-    const diagram = diagrams?.get(object);
-    return diagram !== undefined ? safe(`<div class="diagram">${diagram}</div>`) : "";
-};
 /*  recursively render an object into HTML  */
 const renderObject = (object, level, concise) => {
     const properties = effectiveProperties(object);
@@ -1144,63 +1131,67 @@ export const htmlOutline = (specification, config) => {
     has to carry a non-empty "TITLE" property, as without it there is
     nothing to render a title page from (the object stays suppressed in
     the regular flow nevertheless)  */
-const titlePageObject = (specification) => {
+export const titlePageObject = (specification) => {
     const object = titleObject(specification);
     const title = object?.properties.find((property) => property.key === "TITLE");
     return title !== undefined && title.value.trim() !== "" ? object : undefined;
 };
+/*  pre-render the configured diagrams as embeddable SVGs, displayed
+    at a reduced coordinate scale, as the Gradia geometry (node
+    boxes, font sizes) is dimensioned for a stand-alone canvas and
+    would dwarf the document text at 1:1  */
+const scaledDiagrams = async (specification, config, verbose) => {
+    const scale = 0.75;
+    const rendered = new Map();
+    for (const [object, result] of await renderDiagrams(specification, config, verbose)) {
+        /*  a "hub" diagram is capped to the width share it would
+            occupy on its full three-column canvas (padded by the
+            minimum widths of the absent columns and their channels),
+            so all hub diagrams share the zoom level of the
+            three-column ones and are centered in the leftover space  */
+        const absent = result.columns !== undefined ? 3 - result.columns : 0;
+        const pad = absent * ((result.config?.["size-node-width-min"] ?? Gradia.config["size-node-width-min"]) +
+            (result.config?.["hub-channel-width-min"] ?? Gradia.config["hub-channel-width-min"]));
+        rendered.set(object, result.svg.replace(/(<svg[^>]*) width="([0-9.]+)" height="([0-9.]+)"/, (_, head, w, h) => `${head} width="${Number(w) * scale}" height="${Number(h) * scale}"` +
+            (result.columns !== undefined ? " class=\"hub\"" : "") +
+            (absent > 0 ? ` style="max-width: ${(Number(w) / (Number(w) + pad) * 100).toFixed(2)}%"` : "")));
+    }
+    return rendered;
+};
+/*  create the reference expander of a document: "[[xxx]]" references
+    expand into hyperlinks (an unresolvable or ambiguous reference stays
+    literal, marked as broken), resolved from the object currently
+    rendered and targeting the fully-qualified anchor paths of the
+    objects: in the full form (kind, name, and link symbol), or in the
+    compact form for prose (the object icon and the name only, via CSS
+    and markup, with the full form shown by the description popups)  */
+const makeLinker = (index) => (text, compact) => expandReferences(text, (reference) => {
+    const target = resolveUnique(index, reference, scope ?? undefined).target;
+    if (target === undefined)
+        return `<span class="link-broken">[[${escapeHtml(reference)}]]</span>`;
+    /*  the full form carries the popup attributes on its kind and
+        name, with the kind bold in the accent color and the name
+        bold in the regular text color (via the stylesheet)  */
+    const full = `<strong class="object-kind"${infoAttr(target)}>${escapeHtml(target.kind)}:</strong>` +
+        ` <span class="object-name"${specAttr(target)}>${target.name}</span>` +
+        " <span class=\"link-symbol\">&#x26AD;</span>";
+    return compact ?
+        `<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 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),
     optional per-anchor page numbers attached to the ToC entries, and
     optionally the client-side script of the live preview injected  */
-export const renderHtml = async (specification, config, tocPages, css, realtime = false) => {
-    /*  pre-render the configured diagrams as embeddable SVGs (a runtime
-        rendering failure omits the diagram, as the statically detectable
-        invalid situations are already reported as lint diagnostics),
-        displayed at a reduced coordinate scale, as the Gradia geometry
-        (node boxes, font sizes) is dimensioned for a stand-alone
-        canvas and would dwarf the document text at 1:1  */
-    const scale = 0.75;
-    const cached = diagramCache.get(specification);
-    let rendered = null;
-    if (cached !== undefined && cached.config === config)
-        rendered = cached.diagrams;
-    else if (config !== undefined) {
-        rendered = new Map();
-        for (const [object, result] of specDiagrams(specification, config)) {
-            if (result.spec === undefined)
-                continue;
-            try {
-                const svg = await Gradia.render(result.spec, { format: "svg:embedded", config: result.config });
-                /*  a "hub" diagram is capped to the width share it would
-                    occupy on its full three-column canvas (padded by the
-                    minimum widths of the absent columns and their channels),
-                    so all hub diagrams share the zoom level of the
-                    three-column ones and are centered in the leftover space  */
-                const absent = result.columns !== undefined ? 3 - result.columns : 0;
-                const pad = absent * ((result.config?.["size-node-width-min"] ?? Gradia.config["size-node-width-min"]) +
-                    (result.config?.["hub-channel-width-min"] ?? Gradia.config["hub-channel-width-min"]));
-                rendered.set(object, svg.replace(/(<svg[^>]*) width="([0-9.]+)" height="([0-9.]+)"/, (_, head, w, h) => `${head} width="${Number(w) * scale}" height="${Number(h) * scale}"` +
-                    (result.columns !== undefined ? " class=\"hub\"" : "") +
-                    (absent > 0 ? ` style="max-width: ${(Number(w) / (Number(w) + pad) * 100).toFixed(2)}%"` : "")));
-            }
-            catch {
-                /*  intentionally omitted  */
-            }
-        }
-        diagramCache.set(specification, { config, diagrams: rendered });
-    }
+export const renderHtml = async (specification, config, tocPages, css, realtime = false, verbose) => {
+    /*  pre-render the configured diagrams as scaled embeddable SVGs  */
+    const rendered = config !== undefined ?
+        await scaledDiagrams(specification, config, verbose) : null;
     /*  the document language selects the smart typography quote style  */
     const lang = documentLang(specification);
     quotes = quoteStyles[lang?.toLowerCase().split(/[-_]/)[0] ?? "en"] ?? quoteStyles.en;
-    /*  expand "[[xxx]]" references into hyperlinks (an unresolvable or
-        ambiguous reference stays literal, marked as broken), resolved
-        from the object currently rendered and targeting the
-        fully-qualified anchor paths of the objects: in the full form
-        (kind, name, and link symbol), or in the compact form for prose
-        (the object icon and the name only, via CSS and markup, with
-        the full form shown by the description popups)  */
+    /*  establish the per-document rendering state  */
     const index = buildLinkIndex(specification);
     anchors = anchorPaths(index);
     members = config !== undefined ? collectMembers(config, new Map()) : null;
@@ -1214,30 +1205,12 @@ export const renderHtml = async (specification, config, tocPages, css, realtime
         info = {};
         collectInfo(config, "", infoKeys, info);
         const parents = new Map();
-        const link = (object) => {
-            for (const child of object.childs) {
-                parents.set(child, object);
-                link(child);
-            }
-        };
-        for (const artifact of specification.artifacts)
-            artifact.objects.forEach(link);
+        for (const node of index)
+            if (node.parent !== undefined)
+                parents.set(node.object, node.parent.object);
         infoParents = parents;
     }
-    linker = (text, compact) => expandReferences(text, (reference) => {
-        const target = resolveUnique(index, reference, scope ?? undefined).target;
-        if (target === undefined)
-            return `<span class="link-broken">[[${escapeHtml(reference)}]]</span>`;
-        /*  the full form carries the popup attributes on its kind and
-            name, with the kind bold in the accent color and the name
-            bold in the regular text color (via the stylesheet)  */
-        const full = `<strong class="object-kind"${infoAttr(target)}>${escapeHtml(target.kind)}:</strong>` +
-            ` <span class="object-name"${specAttr(target)}>${target.name}</span>` +
-            " <span class=\"link-symbol\">&#x26AD;</span>";
-        return compact ?
-            `<a href="#${escapeHtml(anchorOf(target))}" class="link-compact"${specAttr(target)}>${target.name}</a>` :
-            `<a href="#${escapeHtml(anchorOf(target))}" class="link-full">${full}</a>`;
-    });
+    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)  */
@@ -1247,6 +1220,8 @@ export const renderHtml = async (specification, config, tocPages, css, realtime
         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
@@ -1257,7 +1232,8 @@ export const renderHtml = async (specification, config, tocPages, css, realtime
     const meta = titleObject(specification);
     const doc = meta !== undefined ? rendered?.get(meta) : undefined;
     try {
-        const entries = tocEntries(artifacts.flatMap((artifact) => artifact.objects), tocPages);
+        const objects = artifacts.flatMap((artifact) => artifact.objects);
+        const entries = tocEntries(objects, tocPages);
         return render("Document", { Document: {
                 title: documentTitle(specification).title,
                 lang,
@@ -1270,7 +1246,7 @@ export const renderHtml = async (specification, config, tocPages, css, realtime
                 realtime: realtime ? safe(realtimeScript) : "",
                 toc: entries.length > 0 ? safe(render("Toc", { Toc: { entries } })) : "",
                 tocpanel: entries.length > 0 ?
-                    safe(renderTocPanel(artifacts.flatMap((artifact) => artifact.objects), title !== undefined, doc !== undefined)) : "",
+                    safe(renderTocPanel(objects, title !== undefined, doc !== undefined)) : "",
                 tocscript: entries.length > 0 ? safe(tocPanelScript) : "",
                 doc: doc !== undefined ? safe(render("Doc", { Doc: { diagram: safe(doc) } })) : "",
                 artifacts: safe(artifacts.map((artifact) => renderArtifact(artifact)).join(""))

package/dst/specbook-export-md.js

@@ -67,8 +67,9 @@ const renderConciseMd = (object, depth = 0) => {
     level 4 upwards in the Concise Format -- unless a descendant carries
     a description no concise item can carry, so all childs (as siblings
     have to share the format) stay in the Complex Format down to heading
-    level 6 -- and the optionally derived Gradia diagram spec embedded
-    as a "gradia" fenced code block below the heading  */
+    level 6, the deepest one Markdown knows, below which the childs are
+    concise regardless -- and the optionally derived Gradia diagram spec
+    embedded as a "gradia" fenced code block below the heading  */
 const renderObjectMd = (object, level, diagrams) => {
     const heading = `${"#".repeat(level)}${" ".repeat(Math.max(1, 4 - level))}` +
         `${object.kind}: ${object.name}${nameSuffixMd(object)}`;
@@ -82,7 +83,7 @@ const renderObjectMd = (object, level, diagrams) => {
         parts.push(renderDescriptionMd(object.description));
     /*  the childs share one format, as a concise item following
         a heading would attach to the heading's object instead  */
-    if (level >= 3 && !complexBelowMd(object))
+    if (level >= 6 || (level >= 3 && !complexBelowMd(object)))
         parts.push(object.childs.map((child) => renderConciseMd(child)).join("\n"));
     else
         parts.push(...object.childs.map((child) => renderObjectMd(child, level + 1, diagrams)));

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

@@ -8,5 +8,5 @@ type Heading = {
     logo: string;
 };
 export declare const requireBrowser: (verbose: Verbose) => Promise<LaunchOptions>;
-export declare const htmlToPdf: (renderHtmlPass: (tocPages?: Map<string, number>) => Promise<string>, heading: Heading, outline: OutlineEntry[], verbose: Verbose, css: string, theme: ThemeMapping, paper?: string) => Promise<Buffer>;
+export declare const htmlToPdf: (renderHtmlPass: (tocPages?: Map<string, number>) => Promise<string>, heading: Heading, outline: OutlineEntry[], titlePage: boolean, verbose: Verbose, css: string, theme: ThemeMapping, paper?: string) => Promise<Buffer>;
 export {};

package/dst/specbook-export-pdf.js

@@ -75,7 +75,10 @@ const addOutline = async (doc, entries) => {
     const root = context.nextRef();
     const top = materialize(items, root);
     context.assign(root, context.obj({
-        Type: "Outlines", First: top.first, Last: top.last, Count: items.length
+        Type: "Outlines",
+        First: top.first,
+        Last: top.last,
+        Count: items.length
     }));
     doc.catalog.set(PDFName.of("Outlines"), root);
     doc.catalog.set(PDFName.of("PageMode"), PDFName.of("UseOutlines"));
@@ -167,7 +170,7 @@ export const requireBrowser = async (verbose) => {
 };
 /*  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, verbose, css, theme, paper = paperSizeDefault) => {
+export const htmlToPdf = async (renderHtmlPass, heading, outline, titlePage, verbose, css, theme, paper = paperSizeDefault) => {
     const { chromium } = await import("playwright");
     /*  the page geometry of the chosen paper size  */
     const setup = paperSetup(paper);
@@ -195,8 +198,9 @@ export const htmlToPdf = async (renderHtmlPass, heading, outline, verbose, css,
         };
         /*  determine the ToC page numbers via a fixpoint iteration:
             paginate undecorated, extract the per-anchor pages, and
-            re-render until the HTML is stable, as the ToC page number
-            column itself can shift the pagination  */
+            re-render until the HTML is stable (bounded to three
+            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);
@@ -220,11 +224,11 @@ export const htmlToPdf = async (renderHtmlPass, heading, outline, verbose, css,
             destinations (and hence the internal hyperlinks) intact  */
         const { PDFDocument } = await import("pdf-lib");
         const merged = await PDFDocument.load(decorated);
-        if (html.includes("class=\"titlepage\"")) {
+        if (titlePage) {
             const source = await PDFDocument.load(plain);
-            const [titlePage] = await merged.copyPages(source, [0]);
+            const [first] = await merged.copyPages(source, [0]);
             merged.removePage(0);
-            merged.insertPage(0, titlePage);
+            merged.insertPage(0, first);
         }
         /*  attach the document outline for the viewer side-bar  */
         verbose("attaching PDF outline (bookmarks)");

package/dst/specbook-format.md

@@ -236,7 +236,8 @@ type SchemaGradiaConfig = Partial<{
 
 -   `SchemaObject.automaton?: SchemaAutomaton`:
     finite state machine the child objects of every object of this kind form,
-    BECAUSE a lifecycle is only trustworthy when its dead-ends and livelocks are ruled out
+    BECAUSE a lifecycle is only trustworthy when its dead-ends and
+    livelocks are ruled out
 
 -   `SchemaObject.diagram?: SchemaDiagram`:
     diagram generated for every object of this kind,
@@ -279,11 +280,13 @@ type SchemaGradiaConfig = Partial<{
 
 -   `SchemaAutomaton.initial: string`:
     property of a node object flagging (with the value `true`) an initial node,
-    BECAUSE reachability needs a start (the check is skipped without any initial node)
+    BECAUSE reachability needs a start (the check is skipped without any
+    initial node)
 
 -   `SchemaAutomaton.final: string`:
     property of a node object flagging (with the value `true`) a final node,
-    BECAUSE resting is legal in a final node only (the livelock check is skipped without any final node)
+    BECAUSE resting is legal in a final node only (the livelock check is
+    skipped without any final node)
 
 -   `SchemaDiagram`:
     diagram derived for every object of an object kind,
@@ -431,7 +434,8 @@ type SchemaGradiaConfig = Partial<{
 -   `SchemaProperty.acyclic?: boolean`:
     whether following the reference-valued property from object to object
     must never return to an object already passed (default: `false`),
-    BECAUSE a hierarchy with a loop has no root and an inclusion with a loop never ends
+    BECAUSE a hierarchy with a loop has no root and an inclusion with a
+    loop never ends
 
 -   `SchemaGradiaConfig`:
     the Gradia rendering options, mirrored from `@rse/gradia`,
@@ -823,8 +827,8 @@ ordered list, a blockquote, or multiple paragraphs) or one carrying a
 `;` (which a re-parse would split into a spurious property plus a
 truncated description). All child objects of such an object then stay in
 the Complex Format (as sibling objects have to share the format), with
-headings reaching down to level 6. When **SpecBook** edits existing files, it mirrors the format each
-existing object already uses.
+headings reaching down to level 6. When **SpecBook** edits existing
+files, it mirrors the format each existing object already uses.
 
 ### Names, Anchors, and Ids
 
@@ -865,9 +869,9 @@ whole.
 
 The description of a Complex Format object is all block content below
 its heading (up to the next heading) except the property list:
-paragraphs, blockquotes, ordered lists (e.g. scenario steps or test case procedures), and
-fenced code blocks. A fenced code block
-of language `gradia` is skipped, as it is the derived diagram which
+paragraphs, blockquotes, ordered lists (e.g. scenario steps or test
+case procedures), and fenced code blocks. A fenced code block of
+language `gradia` is skipped, as it is the derived diagram which
 **SpecBook** itself emits into exported Markdown and which must not
 become authored content on a re-parse. In the Concise Format, the
 description is formed by the non-property segments of the item, so a