@rse/specbook 1.3.0 → 1.3.1

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 { embeddingThemes } from "./specbook-parse-common.js";
 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;")
@@ -26,9 +27,9 @@ export const omitAspects = ["diagram:graph", "diagram:hub", "diagram:grid",
     plain "diagram" is the alias of "diagram:1", hence of all diagrams  */
 export const parseOmit = (omit = []) => {
     const aspects = new Set();
-    for (const item of omit.flatMap((list) => list.split(",")).map((item) => item.trim())) {
-        const aspect = item === "diagram" ? "diagram:1" : item;
-        if (!omitAspects.includes(aspect))
+    for (const item of omit.flatMap((list) => list.split(",")).map((entry) => entry.trim())) {
+        const aspect = omitAspects.find((known) => known === (item === "diagram" ? "diagram:1" : item));
+        if (aspect === undefined)
             throw new Error(`unknown omit aspect "${item}" ` +
                 `(expected "diagram" or one of "${omitAspects.join("\", \"")}")`);
         aspects.add(aspect);
@@ -52,22 +53,33 @@ export const titleObject = (specification) => {
     };
     return search(specification.artifacts.flatMap((artifact) => artifact.objects));
 };
-/*  determine a property value of the title object (a present but empty
-    value counting as an absent property, so every consumer falls back
-    onto its own default)  */
+/*  determine the (trimmed) value of a property of the title object (a
+    present but empty value counting as an absent property, so every
+    consumer falls back onto its own default)  */
 const titleProperty = (specification, name) => {
     const value = titleObject(specification)
-        ?.properties.find((property) => property.key === name)?.value;
-    return value !== undefined && value.trim() !== "" ? value : undefined;
+        ?.properties.find((property) => property.key === name)?.value.trim();
+    return value !== undefined && value !== "" ? value : undefined;
 };
 /*  determine the document language (LANG) from the title object  */
-export const documentLang = (specification) => titleProperty(specification, "LANG")?.trim();
+export const documentLang = (specification) => titleProperty(specification, "LANG");
 /*  determine the document character set (CHARSET) from the title object  */
-export const documentCharset = (specification) => titleProperty(specification, "CHARSET")?.trim();
-/*  determine the document theme style (THEME-STYLE) from the title object  */
-export const documentThemeStyle = (specification) => titleProperty(specification, "THEME-STYLE")?.trim();
+export const documentCharset = (specification) => titleProperty(specification, "CHARSET");
+/*  determine the document theme style (THEME-STYLE) from the title
+    object, lower-cased and rejecting an unknown style (the styles being
+    the very themes the "{theme}" image embeddings know)  */
+export const documentThemeStyle = (specification) => {
+    const value = titleProperty(specification, "THEME-STYLE");
+    if (value === undefined)
+        return undefined;
+    const style = embeddingThemes.find((name) => name === value.toLowerCase());
+    if (style === undefined)
+        throw new Error(`unknown theme style "${value}" ` +
+            `(expected ${embeddingThemes.join(", ")})`);
+    return style;
+};
 /*  determine the document theme color tone (THEME-TONE) from the title object  */
-export const documentThemeTone = (specification) => titleProperty(specification, "THEME-TONE")?.trim();
+export const documentThemeTone = (specification) => titleProperty(specification, "THEME-TONE");
 /*  the supported paper sizes for print: ISO A4 in millimeters and the
     two US sizes closest to it in inches, each with the default margins
     of 1in (25mm) at the top/bottom and 0.8in (20mm) at the left/right  */
@@ -86,7 +98,7 @@ export const paperLength = (setup, value) => `${value}${setup.unit}`;
     matched case-insensitively, falling back onto the default if unset
     and rejecting an unknown size  */
 export const documentPaperSize = (specification) => {
-    const value = titleProperty(specification, "PAPER-SIZE")?.trim();
+    const value = titleProperty(specification, "PAPER-SIZE");
     if (value === undefined)
         return paperSizeDefault;
     const paper = paperSizes.find((name) => name.toLowerCase() === value.toLowerCase());
@@ -204,11 +216,10 @@ export const subsetStylesheet = async (charset) => {
     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();
+    const title = titleProperty(specification, "TITLE");
+    const subtitle = titleProperty(specification, "SUBTITLE");
     return {
-        title: plainText(title !== undefined && title !== "" ? title :
-            titleObject(specification)?.name ?? "Specification"),
+        title: plainText(title ?? "Specification"),
         subtitle: subtitle !== undefined ? plainText(subtitle) : undefined
     };
 };

package/dst/specbook-export-html-search.js

@@ -96,7 +96,7 @@
                 event.preventDefault()
                 reset()
                 slide(false)
-                link.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }))
+                link.click()
             })
         })
     }
@@ -273,8 +273,11 @@
         to two passes, literal substrings first and, only if those match
         nothing at all, the fuzzy variants, as the edit-distance
         neighborhood of a word is wide enough to dilute a correctly
-        spelled query and has to stay a fallback for misspelled ones  */
+        spelled query and has to stay a fallback for misspelled ones;
+        a debounced run a live preview body swap left behind is dropped  */
     const search = () => {
+        if (!tab.isConnected)
+            return
         unmark()
         const parts = input.value.toLowerCase().split(",")
             .map((part) => part.split(/\s+/).filter((word) => word !== ""))
@@ -351,14 +354,17 @@
             panel entries) along: an entry stays visible only while its
             target still is, which covers the front matter entries of
             the panel, too, as their targets are suppressed by the
-            search mode anyway  */
+            search mode anyway, where the entries are hidden only after
+            all targets got measured, as each hiding would force a layout again  */
+        const hidden = []
         document.querySelectorAll("nav.toc table tr, nav.toc-panel div.toc-list li").forEach((entry) => {
             const link   = entry.querySelector(":scope > a, :scope > td > a")
             const target = link !== null ?
                 document.getElementById(decodeURIComponent(link.hash.slice(1))) : null
             if (target === null || target.getClientRects().length === 0)
-                entry.classList.add("search-hide")
+                hidden.push(entry)
         })
+        hidden.forEach((entry) => { entry.classList.add("search-hide") })
     }
 
     /*  run the search debounced on every keystroke (750ms after the

package/dst/specbook-export-html.css

@@ -202,6 +202,10 @@ body::before {
     padding: 0;
   }
 }
+/*  a tab riding right of the brand bar (fixed independent of the
+    content scrolling, at its vertical offset and inset by a pixel or
+    two from the bar), which follows the bar when the table of contents
+    panel shifts it aside  */
 /*  the theme-switching tab (screen-only): the topmost tab riding right
     of the brand bar above the info tab (sized like the table of
     contents tab, fixed independent of the content scrolling), showing
@@ -213,12 +217,12 @@ div.theme-switch {
   top: 0.97rem;
   left: calc(0.6rem - 1px);
   z-index: 30;
-  padding: 0.9rem 0.35rem;
-  line-height: 0;
   border-radius: 0 0.3rem 0.3rem 0;
   color: var(--theme-color-specbook-background);
   background-color: var(--theme-color-specbook-accent);
   transition: left 0.3s ease;
+  padding: 0.9rem 0.35rem;
+  line-height: 0;
   cursor: pointer;
   -webkit-user-select: none;
   user-select: none;
@@ -253,12 +257,12 @@ div.info-switch {
   top: 4.2rem;
   left: calc(0.6rem - 1px);
   z-index: 30;
-  padding: 0.65rem 0.1rem;
-  line-height: 0;
   border-radius: 0 0.3rem 0.3rem 0;
   color: var(--theme-color-specbook-background);
   background-color: var(--theme-color-specbook-accent);
   transition: left 0.3s ease;
+  padding: 0.65rem 0.1rem;
+  line-height: 0;
   cursor: pointer;
   -webkit-user-select: none;
   user-select: none;
@@ -286,6 +290,8 @@ body.info-on div.info-switch svg.info-icon {
     display: none;
   }
 }
+/*  the circle icon leading an object kind (filled) or a property
+    name (not filled), sized and aligned onto the text  */
 /*  the description popup (screen-only): a single shared, script-
     positioned element showing the schema description of the hovered
     object kind or property name, or the corpus description of the
@@ -440,12 +446,12 @@ div.fold-switch {
   top: 10.66rem;
   left: calc(0.6rem - 1px);
   z-index: 30;
-  display: flex;
-  align-items: center;
   border-radius: 0 0.3rem 0.3rem 0;
   color: var(--theme-color-specbook-background);
   background-color: var(--theme-color-specbook-accent);
   transition: left 0.3s ease;
+  display: flex;
+  align-items: center;
 }
 body:has(nav.toc-panel.open) div.fold-switch {
   left: calc(31rem - 1px);
@@ -694,12 +700,12 @@ div.realtime-status {
   top: 17.12rem;
   left: calc(0.6rem - 2px);
   z-index: 30;
-  padding: 0.65rem 0.1rem;
-  line-height: 0;
   border-radius: 0 0.3rem 0.3rem 0;
   color: var(--theme-color-specbook-background);
   background-color: var(--theme-color-specbook-accent);
   transition: left 0.3s ease;
+  padding: 0.65rem 0.1rem;
+  line-height: 0;
   -webkit-user-select: none;
   user-select: none;
 }
@@ -954,7 +960,6 @@ h4 {
   h4,
   h5,
   h6 {
-    page-break-after: avoid;
     break-after: avoid;
   }
 }
@@ -1001,21 +1006,21 @@ a {
 }
 .object-kind::before {
   content: "\25CF";
-  color: var(--theme-color-specbook-accent);
   font-weight: normal;
   font-size: 120%;
   margin-right: 0.25rem;
   vertical-align: -0.075em;
   line-height: 0;
+  color: var(--theme-color-specbook-accent);
 }
 .property-name::before {
   content: "\25CB";
-  color: var(--theme-color-specbook-accent);
   font-weight: normal;
   font-size: 120%;
   margin-right: 0.25rem;
   vertical-align: -0.075em;
   line-height: 0;
+  color: var(--theme-color-specbook-accent);
 }
 span.link-broken {
   color: var(--theme-color-specbook-error);
@@ -1048,12 +1053,12 @@ a.link-compact {
 }
 a.link-compact::before {
   content: "\25CF";
-  color: var(--theme-color-specbook-accent);
   font-weight: normal;
   font-size: 120%;
   margin-right: 0.25rem;
   vertical-align: -0.075em;
   line-height: 0;
+  color: var(--theme-color-specbook-accent);
 }
 span.anchor-paren {
   color: var(--theme-color-specbook-muted);
@@ -1172,14 +1177,12 @@ table.objects table.chunks th:not(.property-name) {
 /*  the diagram leading the chunks of an object, kept in one piece  */
 table.objects table.chunks div.diagram {
   margin: 0.15rem 0;
-  page-break-inside: avoid;
   break-inside: avoid;
 }
 /*  bundle a chunk header row with its value row, so neither the
     "Diagram" header nor the property names are orphaned at a page end  */
 @media print {
   table.objects table.chunks tr:has(> th) {
-    page-break-after: avoid;
     break-after: avoid;
   }
 }
@@ -1359,7 +1362,6 @@ code {
 div.titlepage {
   text-align: center;
   margin: 6rem 0 4rem 0;
-  page-break-after: always;
   break-after: page;
 }
 div.titlepage .logo {
@@ -1424,12 +1426,12 @@ div.search {
   top: 7.43rem;
   left: calc(0.6rem - 1px);
   z-index: 30;
-  display: flex;
-  align-items: center;
   border-radius: 0 0.3rem 0.3rem 0;
   color: var(--theme-color-specbook-background);
   background-color: var(--theme-color-specbook-accent);
   transition: left 0.3s ease;
+  display: flex;
+  align-items: center;
 }
 body:has(nav.toc-panel.open) div.search {
   left: calc(31rem - 1px);
@@ -1506,7 +1508,8 @@ div.search span.search-clear:hover {
 /*  the search result filtering and matched word highlighting, where
     the SVG text labels of the diagrams (having no background) mimic
     the <mark> look with a rounded <rect> placed below the glyphs  */
-.search-hide {
+.search-hide,
+div.fold:has(> div.diagram.search-hide) {
   display: none;
 }
 body.searching nav.doc,
@@ -1531,7 +1534,6 @@ rect.search-hit {
     the deeper ones unnumbered) and indented per nesting level, where
     the (potentially multi-page) table paginates between its rows only  */
 nav.toc {
-  page-break-after: always;
   break-after: page;
   counter-reset: toc1;
 }
@@ -1585,7 +1587,6 @@ nav.toc table {
   width: 100%;
 }
 nav.toc tr {
-  page-break-inside: avoid;
   break-inside: avoid;
 }
 nav.toc td {
@@ -1607,7 +1608,6 @@ nav.toc a {
 }
 /*  the diagram of contents (the diagram of the title object)  */
 nav.doc {
-  page-break-after: always;
   break-after: page;
 }
 nav.doc h1 {

package/dst/specbook-export-html.js

@@ -258,17 +258,19 @@ const themeScript = textframe `
         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
-        }
+        const html = document.documentElement.classList
+        if (style === null)
+            style = html.contains("theme-dark") ? "dark" : (html.contains("theme-light") ? "light" : null)
         if (style === null)
             style = window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light"
-        document.documentElement.className = "theme-" + style
+        html.remove("theme-light", "theme-dark")
+        html.add("theme-" + style)
     })()
     function themeSwitch () {
-        const style = document.documentElement.className === "theme-dark" ? "light" : "dark"
-        document.documentElement.className = "theme-" + style
+        const html  = document.documentElement.classList
+        const style = html.contains("theme-dark") ? "light" : "dark"
+        html.remove("theme-light", "theme-dark")
+        html.add("theme-" + style)
         try { localStorage.setItem("specbook-theme", style) }
         catch { /*  an inaccessible storage just loses the choice  */ }
     }
@@ -415,6 +417,13 @@ const scrollProgressScript = textframe `
         update()
     })()
 `;
+/*  the default percentage by which the text of a table cell may exceed
+    the height of every other cell of its row before it folds (or is
+    omitted), overridden per object kind by "maxCellHeight", and the
+    minimum percentage of its own height a cell has to gain by that,
+    shared by the client-side folding and the server-side omitting  */
+const cellHeightDefault = 40;
+const cellGainMin = 25;
 /*  the client-side script of the folding: it wraps every diagram of the
     content into a fold container carrying a chevron mark at its top
     left corner, folds the text of every table cell towering over the
@@ -461,7 +470,7 @@ const foldScript = (standins, textless) => textframe `
             exceed the height of every other cell of its row before it
             folds, overridden per object kind by the "data-fold-height"
             attribute the schema configuration puts onto its table  */
-        const cellHeight = 40
+        const cellHeight = ${cellHeightDefault}
 
         /*  the chevron mark of a foldable element, rotated by the
             stylesheet while the element is folded  */
@@ -584,7 +593,7 @@ const foldScript = (standins, textless) => textframe `
             by folding, as hiding less than that is no visible relief
             and only costs the reader a chevron to click (measured after
             the cut, as the chevron itself can claim a line of its own)  */
-        const cellGain = 25
+        const cellGain = ${cellGainMin}
 
         /*  lay out the text folds, which holds for the current line
             breaks only and hence is redone on every change of them: the
@@ -709,7 +718,7 @@ const foldScript = (standins, textless) => textframe `
         if (stored.text !== null)
             folds.text.forEach((fold) => { fold.classList.toggle("folded", stored.text === "folded") })
         if (stored.diagrams !== null) {
-            stored.diagrams.split(",").filter((kind) => kind !== "text" && folds[kind] !== undefined)
+            stored.diagrams.split(",").filter((kind) => kind !== "text" && Object.hasOwn(folds, kind))
                 .forEach((kind) => { active.add(kind) })
             apply()
         }
@@ -1026,21 +1035,12 @@ const infoPopupScript = textframe `
             catch { /*  an inaccessible storage just loses the choice  */ }
             apply()
         })
-        const show = (el) => {
-            /*  a diagram node box carries no popup attributes itself, but
-                hyperlinks its object, whose heading name or table row name
-                carries the instance popup attributes  */
-            let source = el
-            if (!el.hasAttribute("data-info") && !el.hasAttribute("data-info-spec")) {
-                const target = document.getElementById(
-                    decodeURIComponent((el.getAttribute("href") ?? "").replace(/^#/, "")))
-                source = target === null ? null :
-                    (target.hasAttribute("data-info-spec") ? target : target.querySelector("[data-info-spec]"))
-                if (source === null)
-                    return
-            }
-            current = el
 
+        /*  compose the title of a popup: the title path segments of the
+            object (the last one kind-only for a kind popup), the anchor
+            id trailing an instance popup, and the property name trailing
+            a property popup  */
+        const titleOf = (source, spec, prop) => {
             /*  compose the title path segments of an object  */
             const pathOf = (n, named) => {
                 const [ , up, kind, title ] = SPEC[n]
@@ -1048,10 +1048,6 @@ const infoPopupScript = textframe `
                 return [ ...(up >= 0 ? pathOf(up, true) : []),
                     name !== "" && kind !== "" ? kind + ": " + name : (name !== "" ? name : kind) ]
             }
-            const key   = source.getAttribute("data-info")
-            const spec  = source.getAttribute("data-info-spec")
-            const prop  = source.getAttribute("data-info-prop")
-            popup.classList.toggle("spec", spec !== null)
             const title = document.createElement("div")
             title.className = "info-title"
 
@@ -1076,7 +1072,7 @@ const infoPopupScript = textframe `
                     description color), where a segment without a kind
                     prefix is the kind-only ending of a kind popup or the
                     name of a kind-less object  */
-                const m    = /^([^\s:]+): (.*)$/.exec(segment)
+                const m    = /^([^\\s:]+): (.*)$/.exec(segment)
                 const bare = i === segments.length - 1 && spec === null && prop === null
                 const name = document.createElement("span")
                 name.className = "info-name"
@@ -1116,7 +1112,27 @@ const infoPopupScript = textframe `
                 name.textContent = prop
                 title.appendChild(name)
             }
-            popup.replaceChildren(title)
+            return title
+        }
+        const show = (el) => {
+            /*  a diagram node box carries no popup attributes itself, but
+                hyperlinks its object, whose heading name or table row name
+                carries the instance popup attributes  */
+            let source = el
+            if (!el.hasAttribute("data-info") && !el.hasAttribute("data-info-spec")) {
+                const target = document.getElementById(
+                    decodeURIComponent((el.getAttribute("href") ?? "").replace(/^#/, "")))
+                source = target === null ? null :
+                    (target.hasAttribute("data-info-spec") ? target : target.querySelector("[data-info-spec]"))
+                if (source === null)
+                    return
+            }
+            current = el
+            const key   = source.getAttribute("data-info")
+            const spec  = source.getAttribute("data-info-spec")
+            const prop  = source.getAttribute("data-info-prop")
+            popup.classList.toggle("spec", spec !== null)
+            popup.replaceChildren(titleOf(source, spec, prop))
             const entry = key !== null ? INFO[key] : undefined
             const desc  = prop !== null ? entry?.p?.[prop] :
                 (spec !== null ? SPEC[spec]?.[4] : entry?.d)
@@ -1608,9 +1624,10 @@ const omitLong = (cells, shares, percent = 0) => {
         html.split(/<\/(?:p|li|div|pre)>|<br\s*\/?>/)
             .reduce((sum, block) => sum + Math.ceil(plain(block) / chars[i]), 0));
     return htmls.map((html, i) => {
-        const limit = Math.floor(Math.max(...lines.filter((_, j) => j !== i)) *
-            (1 + (percent > 0 ? percent : 40) / 100)) * chars[i] - " [...]".length;
-        if (lines[i] === 0 || limit > lengths[i] * 0.75)
+        const other = Math.max(...lines.filter((_, j) => j !== i)) *
+            (1 + (percent > 0 ? percent : cellHeightDefault) / 100);
+        const limit = Math.floor(other) * chars[i] - " [...]".length;
+        if (lines[i] === 0 || lines[i] <= other || limit > lengths[i] * (1 - cellGainMin / 100))
             return cells[i];
         const open = new Array();
         let out = "";
@@ -1620,7 +1637,7 @@ const omitLong = (cells, shares, percent = 0) => {
                 const tag = (/^<(\/?)([a-zA-Z][^\s/>]*)[^>]*?(\/?)>$/).exec(token);
                 if (tag?.[1] === "/")
                     open.pop();
-                else if (tag !== null && tag[3] !== "/" && !(/^(?:br|hr|img|wbr)$/).test(tag[2]))
+                else if (tag !== null && tag[3] !== "/" && !(/^(?:br|hr|img|input|wbr)$/).test(tag[2]))
                     open.push(tag[2]);
             }
             else if (count + token.length > limit)
@@ -1656,8 +1673,9 @@ const renderTable = (children, maxColumns) => {
                     twice the share of a regular column, compressing the others  */
                 width: Math.round(200 / (keys.length + 3)),
                 rows: children.map((child, i) => scoped(child, () => {
-                    const cells = omitLong([...keys.map((key) => inlineValue(child.kind, child.properties.find((property) => property.key === key))),
-                        safe(renderCell(child))].slice(0, keys.length + (desc ? 1 : 0)), [...keys.map(() => 1), 2].map((share) => share / (keys.length + (desc ? 3 : 1))), formatOf(children[0])?.maxCellHeight);
+                    const values = keys.map((key) => inlineValue(child.kind, child.properties.find((property) => property.key === key)));
+                    const shares = desc ? [...keys.map(() => 1), 2] : keys.map(() => 1);
+                    const cells = omitLong(desc ? [...values, safe(renderCell(child))] : values, shares.map((share) => share / (keys.length + (desc ? 3 : 1))), formatOf(children[0])?.maxCellHeight);
                     return {
                         id: anchorOf(child),
                         anchor: child.anchor,
@@ -1750,15 +1768,15 @@ const renderTitlePage = (object, created, modified) => {
     const prop = (name) => object.properties.find((property) => property.key === name)?.value;
     const inlineProp = (name) => {
         const value = prop(name);
-        return value !== undefined ? inline(value) : "";
+        return value !== undefined && value.trim() !== "" ? inline(value) : "";
     };
     const rest = object.properties.filter((property) => !["LOGO", "TITLE", "SUBTITLE", "AUTHOR", "VERSION",
         "LANG", "CHARSET", "PAPER-SIZE", "THEME-STYLE", "THEME-TONE"].includes(property.key));
     /*  the logo is rendered above the title, from the embedded image content
         of the LOGO property or, for a non-embeddable reference, as its inline
-        Markdown; without a LOGO property the built-in SpecBook logo is used,
-        in both its theme variants  */
-    const logo = object.properties.find((property) => property.key === "LOGO");
+        Markdown; without a (non-empty) LOGO property the built-in SpecBook
+        logo is used, in both its theme variants  */
+    const logo = object.properties.find((property) => property.key === "LOGO" && property.value.trim() !== "");
     const image = logo !== undefined ? renderEmbeddings(logo.value, logo.embedding ?? []) : [];
     return scoped(object, () => render("TitlePage", { TitlePage: {
             logo: logo === undefined ?
@@ -1920,24 +1938,13 @@ export const renderPlaceholder = (message) => render("Placeholder", { Placeholde
         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),
-    optional per-anchor page numbers attached to the ToC entries,
-    optionally the client-side script of the live preview injected and
-    aspects omitted (see "ExportOptions"), and the embedded images
-    optimized for the screen or for print (the PDF)  */
-export const renderHtml = async (specification, config, tocPages, css, options = {}, verbose, print = false) => {
-    /*  pre-render the configured diagrams as scaled embeddable SVGs
-        (except for the omitted ones, which hence leave no trace at all)  */
-    const omit = options.omit ?? new Set();
-    const rendered = config !== undefined ?
-        await scaledDiagrams(specification, config, verbose, omit) : null;
-    /*  the fold controls of the omitted aspects leave along with the
-        implied ones (no type control without diagrams of that type, no
-        level control without diagrams from that level on, no fold tab
-        without any control, which lets the tabs below it move up), and
-        the omitted long texts bring the style of their "[...]" mark  */
+/*  the fold controls the omitted aspects drop, along with the implied
+    ones (no type control without diagrams of that type, no level
+    control without diagrams from that level on, no fold tab without
+    any control, which lets the tabs below it move up), plus the extra
+    style rules the omission brings (the "[...]" mark of the omitted
+    long texts and the moved-up tabs of a dropped fold tab)  */
+const omittedControls = (omit) => {
     const none = omit.has("diagram:1")
         || (omit.has("diagram:graph") && omit.has("diagram:hub") && omit.has("diagram:grid"));
     const omitted = {
@@ -1950,9 +1957,43 @@ export const renderHtml = async (specification, config, tocPages, css, options =
         text: omit.has("text:long"),
         all: none && omit.has("text:long")
     };
-    const omitCss = (omitted.text ? "\nspan.omit { color: var(--theme-color-specbook-muted) }" : "") +
+    const css = (omitted.text ? "\nspan.omit { color: var(--theme-color-specbook-muted) }" : "") +
         (omitted.all ? "\nnav.toc-panel div.toc-tab { top: 10.66rem }" +
             "\ndiv.realtime-status { top: 13.89rem }" : "");
+    return { omitted, css };
+};
+/*  wrap the pre-rendered diagrams into their blocks, carrying the
+    diagram type and the object tree nesting level the folding
+    distinguishes (the top-level objects of an artifact being level 1)  */
+const wrapDiagrams = (index, svgs) => {
+    const blocks = new Map();
+    for (const node of index) {
+        const svg = svgs.get(node.object);
+        if (svg === undefined)
+            continue;
+        let level = 1;
+        for (let parent = node.parent; parent !== undefined; parent = parent.parent)
+            level++;
+        const type = schemas?.get(node.object)?.diagram?.type ?? "graph";
+        blocks.set(node.object, `<div class="diagram" data-type="${type}" data-level="${level}">${svg}</div>`);
+    }
+    return blocks;
+};
+/*  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,
+    optionally the client-side script of the live preview injected and
+    aspects omitted (see "ExportOptions"), and the embedded images
+    optimized for the screen or for print (the PDF)  */
+export const renderHtml = async (specification, config, tocPages, css, options = {}, verbose, print = false) => {
+    /*  pre-render the configured diagrams as scaled embeddable SVGs
+        (except for the omitted ones, which hence leave no trace at all)  */
+    const omit = options.omit ?? new Set();
+    const rendered = config !== undefined ?
+        await scaledDiagrams(specification, config, verbose, omit) : null;
+    /*  the fold controls and the extra style rules of the omitted aspects  */
+    const { omitted, css: omitCss } = omittedControls(omit);
     /*  pre-optimize the embedded images (downscaled and re-encoded)  */
     const optimized = await optimizeImages(specification, print, verbose);
     /*  the document language selects the smart typography quote style  */
@@ -1970,17 +2011,7 @@ export const renderHtml = async (specification, config, tocPages, css, options =
         omits = omit;
         /*  wrap the diagrams into their blocks, carrying the diagram type
             and the object tree nesting level the folding distinguishes  */
-        diagrams = rendered !== null ? new Map() : null;
-        for (const node of index) {
-            const svg = rendered?.svgs.get(node.object);
-            if (svg === undefined)
-                continue;
-            let level = 1;
-            for (let parent = node.parent; parent !== undefined; parent = parent.parent)
-                level++;
-            const type = schemas?.get(node.object)?.diagram?.type ?? "graph";
-            diagrams?.set(node.object, `<div class="diagram" data-type="${type}" data-level="${level}">${svg}</div>`);
-        }
+        diagrams = rendered !== null ? wrapDiagrams(index, rendered.svgs) : null;
         /*  collect the schema descriptions for the description popups,
             plus the object table composing their title paths  */
         let info = null;
@@ -2020,7 +2051,7 @@ export const renderHtml = async (specification, config, tocPages, css, options =
         return render("Document", { Document: {
                 title: documentTitle(specification).title,
                 lang,
-                theme: documentThemeStyle(specification)?.toLowerCase(),
+                theme: documentThemeStyle(specification),
                 css: safe((css ?? stylesheet()) + (rendered !== null ? `\n${rendered.css}` : "") + omitCss),
                 themescript: safe(themeScript),
                 titlepage: title !== undefined ?

package/dst/specbook-export-image.js

@@ -83,11 +83,15 @@ const collect = (object, contents) => {
     for) or which does not shrink the image keeps the original, so the
     export never depends on it  */
 export const optimizeImages = async (specification, print, verbose) => {
+    /*  collect the distinct embedded image contents of the specification  */
     const medium = print ? "print" : "screen";
     const contents = new Set();
     for (const artifact of specification.artifacts)
         for (const object of artifact.objects)
             collect(object, contents);
+    /*  optimize every image the cache of the medium cannot serve (an
+        optimization which fails or does not shrink keeps the original),
+        accounting the sizes for the report below  */
     const cache = new Map();
     let cached = 0;
     let before = 0;
@@ -101,7 +105,9 @@ export const optimizeImages = async (specification, print, verbose) => {
                 optimized = content.startsWith("data:") ?
                     await optimizeRaster(content, print) : await optimizeSvg(content);
             }
-            catch {
+            catch (err) {
+                verbose?.("optimizing image failed (keeping the original): " +
+                    (err instanceof Error ? err.message : String(err)));
                 optimized = content;
             }
             if (optimized.length >= content.length)
@@ -111,6 +117,8 @@ export const optimizeImages = async (specification, print, verbose) => {
         before += content.length;
         after += optimized.length;
     }
+    /*  sweep the cache of the medium to the images of this
+        optimization and report its figures  */
     imageCaches[medium] = cache;
     if (contents.size > 0)
         verbose?.((cached === contents.size ?