@rse/specbook 1.5.2 → 1.6.1

package/dst/specbook-export-html.css

@@ -132,6 +132,16 @@ html.theme-light {
   --gradia-color-container-name: var(--theme-color-base-12);
   --gradia-color-container-box: var(--theme-color-base-31);
   --gradia-color-container-border: var(--theme-color-base-24);
+  --gradia-color-composite-border: var(--theme-color-base-24);
+  --gradia-color-node-lifeline: var(--theme-color-accent-26);
+  --gradia-color-node-place-name: var(--theme-color-base-12);
+  --gradia-color-node-place-box: var(--theme-color-base-31);
+  --gradia-color-node-place-border: var(--theme-color-base-24);
+  --gradia-color-node-pseudo-name: var(--theme-color-base-32);
+  --gradia-color-node-pseudo-box: var(--theme-color-accent-12);
+  --gradia-color-node-pseudo-border: var(--theme-color-accent-8);
+  --gradia-color-mark-violation: var(--theme-color-signal-12);
+  --gradia-color-mark-critical: var(--theme-color-accent-14);
   --gradia-color-edge-line: var(--theme-color-base-22);
   --gradia-color-edge-name: var(--theme-color-base-5);
   --gradia-color-edge-arity: var(--theme-color-base-5);
@@ -187,8 +197,18 @@ html.theme-light {
     --gradia-color-group-box: var(--theme-color-accent-1);
     --gradia-color-group-border: var(--theme-color-accent-7);
     --gradia-color-container-name: var(--theme-color-base-24);
-    --gradia-color-container-box: var(--theme-color-base-4);
+    --gradia-color-container-box: var(--theme-color-base-10);
     --gradia-color-container-border: var(--theme-color-base-16);
+    --gradia-color-composite-border: var(--theme-color-base-16);
+    --gradia-color-node-lifeline: var(--theme-color-accent-7);
+    --gradia-color-node-place-name: var(--theme-color-base-24);
+    --gradia-color-node-place-box: var(--theme-color-base-10);
+    --gradia-color-node-place-border: var(--theme-color-base-16);
+    --gradia-color-node-pseudo-name: var(--theme-color-base-1);
+    --gradia-color-node-pseudo-box: var(--theme-color-accent-20);
+    --gradia-color-node-pseudo-border: var(--theme-color-accent-24);
+    --gradia-color-mark-violation: var(--theme-color-signal-22);
+    --gradia-color-mark-critical: var(--theme-color-accent-22);
     --gradia-color-edge-line: var(--theme-color-base-20);
     --gradia-color-edge-name: var(--theme-color-base-29);
     --gradia-color-edge-arity: var(--theme-color-base-29);
@@ -445,17 +465,22 @@ div.info-popup.spec a.link-compact::before {
     display: none;
   }
 }
-/*  the folding tab (screen-only): the tab riding right of the brand
-    bar between the search tab and the table of contents tab (as wide
-    as those, fixed independent of the content scrolling), showing a
-    fold icon (drawn like the search icon), which slides the
-    controls out to the right (and back in), where the tab follows the
-    bar when the table of contents panel shifts it aside; the controls
-    fold and unfold all diagrams of a type, all diagrams from a nesting
-    level on, and all over-long cell texts of the content at once and
-    carry, like the fold icon itself, the mark colors in a rounded box
-    while anything of their kind is folded  */
-div.fold-switch {
+/*  the artifact filter tab (screen-only): the tab riding right of the
+    brand bar between the search tab and the folding tab (as wide as
+    those, fixed independent of the content scrolling), showing a
+    layers icon (drawn like the search icon), which slides a grid out
+    to the right (and back in), hanging from the top of the tab beside
+    the tabs below, where the tab follows the bar when the table of
+    contents panel shifts it aside (a small gap keeping the grid off
+    the tabs below, bridged beside the tab itself, as the panel clips
+    everything outside of it); the grid holds one row per artifact
+    kind -- the kind cell first, toggling the whole row, then one cell
+    per top-level artifact of the kind, labeled by its id -- whose
+    cells are sticky checkboxes, bordered lighter than the panel in
+    both themes to read as buttons, carrying the mark colors while enabled
+    (a kind cell outlined while only some of its row is), like the
+    filter icon itself while any artifact is  */
+div.filter-switch {
   position: fixed;
   top: 10.66rem;
   left: calc(0.6rem - 1px);
@@ -464,22 +489,51 @@ div.fold-switch {
   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 {
+body:has(nav.toc-panel.open) div.filter-switch {
   left: calc(31rem - 1px);
   box-shadow: 0.2rem 0 0.6rem rgba(0,0,0,0.3);
 }
+div.filter-switch,
+div.fold-switch {
+  display: flex;
+  align-items: center;
+}
+div.filter-switch.open,
+div.filter-switch.open div.filter-toggle,
+div.fold-switch.open,
+div.fold-switch.open div.fold-toggle {
+  border-radius: 0;
+}
+div.filter-switch::after,
+div.fold-switch::after {
+  content: "";
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  left: 100%;
+  width: 0.4rem;
+  background-color: var(--theme-color-specbook-accent);
+  visibility: hidden;
+  transition: visibility 0s 0.3s;
+}
+div.filter-switch.open::after,
+div.fold-switch.open::after {
+  visibility: visible;
+  transition-delay: 0s;
+}
+div.filter-switch div.filter-toggle,
 div.fold-switch div.fold-toggle {
   padding: 0.65rem 0.1rem;
   line-height: 0;
   border-radius: 0 0.3rem 0.3rem 0;
   cursor: pointer;
 }
+div.filter-switch div.filter-toggle:hover,
 div.fold-switch div.fold-toggle:hover {
   background-color: var(--theme-color-specbook-accent-soft);
 }
+div.filter-switch svg.filter-icon,
 div.fold-switch svg.fold-icon {
   width: 1.1rem;
   height: 1.1rem;
@@ -487,24 +541,113 @@ div.fold-switch svg.fold-icon {
   border-radius: 0.3rem;
   margin-right: 0.15rem;
 }
-div.fold-switch.folded svg.fold-icon {
+body.filtering div.filter-switch svg.filter-icon {
   color: var(--theme-color-specbook-mark-text);
   background-color: var(--theme-color-specbook-mark-back);
 }
-div.fold-switch div.fold-controls {
-  display: flex;
-  align-items: center;
-  gap: 0.3rem;
+div.filter-switch div.filter-panel,
+div.fold-switch div.fold-panel {
+  position: absolute;
+  top: 0;
+  left: calc(100% + 0.4rem);
+  width: max-content;
   overflow: hidden;
   max-width: 0;
-  padding: 0;
-  transition: max-width 0.3s ease, padding 0.3s ease;
+  border-radius: 0 0.3rem 0.3rem 0.3rem;
+  background-color: var(--theme-color-specbook-accent);
+  transition: max-width 0.3s ease;
+}
+body:has(nav.toc-panel.open) div.filter-switch div.filter-panel,
+body:has(nav.toc-panel.open) div.fold-switch div.fold-panel {
+  box-shadow: 0.2rem 0 0.6rem rgba(0,0,0,0.3);
+}
+div.filter-switch.open div.filter-panel {
+  max-width: 48rem;
+}
+div.filter-switch div.filter-grid {
+  display: grid;
+  gap: 0.3rem;
+  padding: 0.7rem;
+  line-height: 1;
+}
+div.filter-switch div.filter-grid > div {
+  padding: 0.3rem 0.4rem;
+  border: 1px solid rgba(255,255,255,0.45);
+  border-radius: 0.3rem;
+  font-size: 0.8rem;
+  text-align: center;
+  white-space: nowrap;
+  cursor: pointer;
+  -webkit-user-select: none;
+  user-select: none;
 }
-div.fold-switch.open div.fold-controls {
+div.filter-switch div.filter-grid > div:hover {
+  background-color: var(--theme-color-specbook-accent-soft);
+}
+div.filter-switch div.filter-grid > div.on {
+  color: var(--theme-color-specbook-mark-text);
+  background-color: var(--theme-color-specbook-mark-back);
+}
+div.filter-switch div.filter-kind {
+  grid-column: 1;
+  font-weight: bold;
+  text-align: left;
+}
+div.filter-switch div.filter-kind.some {
+  border-color: var(--theme-color-specbook-mark-back);
+}
+@media print {
+  div.filter-switch {
+    display: none;
+  }
+}
+/*  the folding tab (screen-only): the tab riding right of the brand
+    bar between the artifact filter tab and the table of contents tab
+    (as wide as those, fixed independent of the content scrolling),
+    showing a fold icon (drawn like the search icon), which slides a
+    panel out to the right (and back in), hanging from the top of the
+    tab beside the tabs below exactly like the artifact filter grid
+    (the same gap, bridged beside the tab itself); the panel holds the
+    controls in two rows -- the Gradia diagram types first (the row
+    centered on the tab), then the diagrams as code, the images, the
+    listings, the nesting levels, and the cell texts -- which fold and
+    unfold all diagrams of a type, all diagrams from a nesting level
+    on, and all over-long cell texts of the content at once and carry,
+    like the fold icon itself, the mark colors in a rounded box while
+    anything of their kind is folded  */
+div.fold-switch {
+  position: fixed;
+  top: 13.89rem;
+  left: calc(0.6rem - 1px);
+  z-index: 30;
+  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;
+}
+body:has(nav.toc-panel.open) div.fold-switch {
+  left: calc(31rem - 1px);
+  box-shadow: 0.2rem 0 0.6rem rgba(0,0,0,0.3);
+}
+div.fold-switch.folded svg.fold-icon {
+  color: var(--theme-color-specbook-mark-text);
+  background-color: var(--theme-color-specbook-mark-back);
+}
+div.fold-switch.open div.fold-panel {
   max-width: 24rem;
-  padding: 0 0.5rem 0 0.2rem;
 }
-div.fold-switch div.fold-controls > div {
+div.fold-switch div.fold-rows {
+  display: flex;
+  flex-direction: column;
+  gap: 0.3rem;
+  padding: 0.65rem 0.5rem;
+}
+div.fold-switch div.fold-row {
+  display: flex;
+  align-items: center;
+  gap: 0.3rem;
+}
+div.fold-switch div.fold-row > div {
   padding: 0.25rem;
   line-height: 0;
   border-radius: 0.3rem;
@@ -512,14 +655,14 @@ div.fold-switch div.fold-controls > div {
   -webkit-user-select: none;
   user-select: none;
 }
-div.fold-switch div.fold-controls > div:hover {
+div.fold-switch div.fold-row > div:hover {
   background-color: var(--theme-color-specbook-accent-soft);
 }
-div.fold-switch div.fold-controls > div.folded {
+div.fold-switch div.fold-row > div.folded {
   color: var(--theme-color-specbook-mark-text);
   background-color: var(--theme-color-specbook-mark-back);
 }
-div.fold-switch div.fold-controls svg {
+div.fold-switch div.fold-row svg {
   width: 1.1rem;
   height: 1.1rem;
 }
@@ -723,7 +866,7 @@ html.maximized {
     for 2s (toggling every 250ms) after a content reload  */
 div.realtime-status {
   position: fixed;
-  top: 17.12rem;
+  top: 20.35rem;
   left: calc(0.6rem - 2px);
   z-index: 30;
   border-radius: 0 0.3rem 0.3rem 0;
@@ -853,7 +996,7 @@ nav.toc-panel.open div.toc-tab {
 }
 nav.toc-panel div.toc-tab {
   position: absolute;
-  top: 13.89rem;
+  top: 17.12rem;
   left: calc(100% - 1px);
   padding: 0.9rem 0.35rem;
   line-height: 0;
@@ -1191,6 +1334,11 @@ table.objects th {
   background-color: var(--theme-color-specbook-tint);
   box-sizing: border-box;
 }
+/*  the kind label of a reference stays in one piece (not broken at
+    a hyphen), as the column widths account for it anyway  */
+table.objects td .object-kind {
+  white-space: nowrap;
+}
 /*  the name column of every compact table at a fixed width, so that the
     columns of the consecutive tables align  */
 table.objects th.object-kind {
@@ -1466,6 +1614,13 @@ div.description ul {
 div.description li {
   margin: 0.1rem 0;
 }
+/*  the Markdown bold of the descriptions renders semi-bold (unlike the
+    classed <strong> markup of the hyperlinks), so it stands out from the
+    prose without the weight of the headings and object kinds  */
+p.description strong:not([class]),
+div.description strong:not([class]) {
+  font-weight: 600;
+}
 div.embedding {
   margin: 0.5rem 0;
 }
@@ -1550,6 +1705,12 @@ code {
   font-size: 0.89em;
   letter-spacing: -0.03rem;
 }
+/*  an inline code span breaks inside an overlong word (like a long
+    value expression without any space) instead of overflowing its
+    table cell or text column  */
+:not(pre) > code {
+  overflow-wrap: anywhere;
+}
 /*  the code listings: block-level lines on a transparent background with a
     grey gutter for the line numbers, drawn from a counter (in the
     symbol color and excluded from a selection, an empty line kept open by
@@ -1689,14 +1850,14 @@ div.titlepage div.description p + p:not(.rationale) {
   margin-top: 0.4rem;
   text-indent: 3rem;
 }
-/*  the fuzzy search tab (screen-only): the middle tab riding right of
-    the brand bar between the info tab and the folding
-    tab (as wide as those, fixed independent of the content
-    scrolling), showing the search icon, which slides the input field
-    and its clear symbol out to the right (and back in), where the tab
-    follows the bar when the table of contents panel shifts it aside
-    and the icon carries the mark colors in a rounded box while a
-    search filter is active, signalling the filtered content  */
+/*  the fuzzy search tab (screen-only): the tab riding right of the
+    brand bar between the info tab and the artifact filter tab (as
+    wide as those, fixed independent of the content scrolling),
+    showing the search icon, which slides the input field and its clear
+    symbol out to the right (and back in), where the tab follows the bar
+    when the table of contents panel shifts it aside and the icon
+    carries the mark colors in a rounded box while a search filter is
+    active, signalling the filtered content  */
 div.search {
   position: fixed;
   top: 7.43rem;
@@ -1805,6 +1966,15 @@ tspan.search-hit {
 rect.search-hit {
   fill: var(--theme-color-specbook-mark-back);
 }
+/*  the artifact filter hiding (the hidden objects, the emptied tables
+    and articles, and the table of contents entries, where a fold
+    container inside a table cell outranks the bare class), plus the
+    diagram of contents, which spans all artifacts  */
+.filter-hide,
+div.fold.filter-hide,
+body.filtering nav.doc {
+  display: none;
+}
 /*  the table of contents (with page numbers for print only): all
     section headings, numbered like the document (three levels deep,
     the deeper ones unnumbered) and indented per nesting level, where

package/dst/specbook-export-html.js

@@ -4,7 +4,7 @@
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
 import { Gradia } from "@rse/gradia";
-import { buildLinkIndex, anchorPaths, plainText } from "./specbook-link.js";
+import { buildLinkIndex, anchorPaths, plainText, referenceTargets } from "./specbook-link.js";
 import { stylesheet, searchScript, isTitleObject, titleObject, documentTitle, documentLang, documentThemeStyle } from "./specbook-export-common.js";
 import { collectSchemas } from "./specbook-parse-semantic.js";
 import { renderDiagrams } from "./specbook-diagram.js";
@@ -13,7 +13,7 @@ import { renderEmbeddedDiagrams, objectLevels } from "./specbook-export-diagram.
 import { prepareListings } from "./specbook-export-code.js";
 import { specCoverage } from "./specbook-coverage.js";
 import { safe, render } from "./specbook-export-html-template.js";
-import { themeScript, placeholderStylesheet, realtimeScript, scrollProgressScript, maximizeScript, tocPanelScript, infoScript } from "./specbook-export-html-widget.js";
+import { themeScript, placeholderStylesheet, realtimeScript, scrollProgressScript, maximizeScript, tocPanelScript, infoScript, filterScript } from "./specbook-export-html-widget.js";
 import { foldScript, omittedControls } from "./specbook-export-html-fold.js";
 import { withDocument, makeLinker, collectInfo, collectSpec, collectMembers, conciseGroup, flowChildren, groupChildren, formatDate, renderTitlePage, renderArtifact, tocEntries, renderTocPanel } from "./specbook-export-html-render.js";
 /*  derive the hierarchy of the rendered object headings, skipping the
@@ -42,44 +42,40 @@ export const titlePageObject = (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: the scale renders the node
-    names (30 units) at 15px, about the size of the document text, so a
-    diagram narrower than its container is no longer blown up beyond
-    the zoom level of the diagrams the container width caps anyway. The
-    <style> elements are stripped off the diagrams and the union of
-    their CSS rules is returned for the document stylesheet instead, as
-    Gradia names a class after its declarations and hence hundreds of
-    diagrams repeat the very same few rules (which are XML-escaped
-    inside an SVG, but plain text inside the HTML <style> element,
-    which no unescaped "</" of a configured value may close)  */
+/*  pre-render the configured diagrams as embeddable SVGs at half their
+    coordinate scale (the node names of 30 units at about the 15px of the
+    document text), and strip their <style> elements, returning the union
+    of their CSS rules for the document stylesheet instead, as Gradia
+    names a class after its declarations (the rules XML-unescaped, but
+    with every "</" escaped, as they become plain text of the HTML <style>
+    element)  */
 const scaledDiagrams = async (specification, config, verbose, omit) => {
     const scale = 0.5;
     const rendered = new Map();
     const rules = new Set();
     const entities = { amp: "&", lt: "<", gt: ">", quot: "\"" };
-    for (const [object, result] of await renderDiagrams(specification, config, verbose, omit)) {
-        const svg = result.svg.replace(/<style>([\s\S]*?)<\/style>\s*/g, (_, css) => {
-            for (const rule of css.split("\n"))
-                if (rule.trim() !== "")
-                    rules.add(rule.trim()
-                        .replace(/&(amp|lt|gt|quot);/g, (_, name) => entities[name])
-                        .replace(/<\//g, "<\\/"));
-            return "";
-        });
-        /*  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, the leftover space splitting evenly, as
-            the stylesheet centers every diagram  */
-        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}"` +
-            (absent > 0 ? ` style="max-width: ${(Number(w) / (Number(w) + pad) * 100).toFixed(2)}%"` : "")));
+    for (const [object, results] of await renderDiagrams(specification, config, verbose, omit)) {
+        rendered.set(object, results.map((result) => {
+            const svg = result.svg.replace(/<style>([\s\S]*?)<\/style>\s*/g, (_, css) => {
+                for (const rule of css.split("\n"))
+                    if (rule.trim() !== "")
+                        rules.add(rule.trim()
+                            .replace(/&(amp|lt|gt|quot);/g, (_, name) => entities[name])
+                            .replace(/<\//g, "<\\/"));
+                return "";
+            });
+            /*  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, the leftover space splitting evenly, as
+                the stylesheet centers every diagram  */
+            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"]));
+            return { type: result.type, svg: svg.replace(/(<svg[^>]*) width="([0-9.]+)" height="([0-9.]+)"/, (_, head, w, h) => `${head} width="${Number(w) * scale}" height="${Number(h) * scale}"` +
+                    (absent > 0 ? ` style="max-width: ${(Number(w) / (Number(w) + pad) * 100).toFixed(2)}%"` : "")) };
+        }));
     }
     return { svgs: rendered, css: Array.from(rules).join("\n") };
 };
@@ -96,18 +92,44 @@ export const renderPlaceholder = (message) => render("Placeholder", { Placeholde
         realtime: safe(realtimeScript),
         message
     } });
-/*  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 = (svgs, schemas, levels) => {
+/*  wrap the pre-rendered diagrams of every object into their blocks
+    (one per diagram, in their configured order), 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 = (svgs, levels) => {
     const blocks = new Map();
-    for (const [object, svg] of svgs) {
+    for (const [object, diagrams] of svgs) {
         const level = levels.get(object) ?? 1;
-        const type = schemas?.get(object)?.diagram?.type ?? "graph";
-        blocks.set(object, `<div class="diagram" data-type="${type}" data-level="${level}">${svg}</div>`);
+        blocks.set(object, diagrams.map(({ type, svg }) => `<div class="diagram" data-type="${type}" data-level="${level}">${svg}</div>`).join(""));
     }
     return blocks;
 };
+/*  derive a short label out of a name: the upper-cased initials of its
+    words, or the first two letters of a single-word name  */
+const idify = (name) => {
+    const words = name.split(/[^\p{L}\p{N}]+/u).filter((word) => word !== "");
+    return (words.length === 1 ? words[0].slice(0, 2) : words.map((word) => word[0]).join("")).toUpperCase();
+};
+/*  the rows of the artifact filter grid: one per artifact kind (in the
+    order of first occurrence), carrying the top-level objects of the
+    flow artifacts of the kind as cells, each identified by its anchor
+    path, labeled by its explicit anchor or parenthesized id (else by
+    the initials of its name, as its slugified id would be as long as
+    the name), and titled like its heading  */
+const filterRows = (artifacts, paths) => {
+    const rows = new Map();
+    for (const object of artifacts.flatMap((artifact) => artifact.objects)) {
+        let row = rows.get(object.kind);
+        if (row === undefined) {
+            row = { kind: object.kind, cells: [] };
+            rows.set(object.kind, row);
+        }
+        row.cells.push({ id: paths.get(object) ?? object.id,
+            label: object.anchor ?? object.paren ?? idify(plainText(object.name)),
+            title: (object.kind !== "" ? `${object.kind}: ` : "") + plainText(object.name) });
+    }
+    return Array.from(rows.values());
+};
 /*  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),
@@ -135,21 +157,23 @@ export const renderHtml = async (specification, config, tocPages, css, options =
     /*  collect the per-document rendering state, where the description
         popup keys are filled in below, once the state is established  */
     const index = buildLinkIndex(specification);
+    const paths = anchorPaths(index);
     const schemas = config !== undefined ? collectSchemas(specification, config) : null;
     const levels = objectLevels(specification);
     const infoKeys = new Map();
     const infoObjects = new Map();
     /*  wrap the diagrams into their blocks, carrying the diagram type
         and the object tree nesting level the folding distinguishes  */
-    const diagrams = rendered !== null ? wrapDiagrams(rendered.svgs, schemas, levels) : null;
-    /*  the document language selects the smart typography quote style  */
+    const diagrams = rendered !== null ? wrapDiagrams(rendered.svgs, levels) : null;
+    /*  the document language selects the smart typography quote style
+        and the rendered rationale keyword translation  */
     const lang = documentLang(specification);
     /*  establish the per-document rendering state (released again
         afterwards, also on a failure of the collecting or rendering)  */
     return withDocument({
         lang,
         linker: makeLinker(index),
-        anchors: anchorPaths(index),
+        anchors: paths,
         members: config !== undefined ? collectMembers(config, new Map()) : null,
         schemas,
         diagrams,
@@ -194,6 +218,23 @@ export const renderHtml = async (specification, config, tocPages, css, options =
         const doc = meta !== undefined ? diagrams?.get(meta) : undefined;
         const objects = artifacts.flatMap((artifact) => artifact.objects);
         const entries = tocEntries(objects, tocPages);
+        /*  collect the reference table of the artifact filter: per
+            object its parent index, its anchor path segment (the path
+            less the one of its parent), and the indices of the objects
+            its own texts reference  */
+        const positions = new Map(index.map((node) => [node.object, node.pos]));
+        const links = index.map((node) => {
+            const path = paths.get(node.object) ?? node.object.id;
+            const parent = node.parent !== undefined ? paths.get(node.parent.object) : undefined;
+            return [node.parent?.pos ?? -1, parent !== undefined ? path.slice(parent.length + 1) : path,
+                referenceTargets(index, node.object).map((target) => positions.get(target) ?? -1)
+                    .filter((pos) => pos >= 0)];
+        });
+        const rows = filterRows(artifacts, paths);
+        /*  the client-side scripts of the widgets and the side panel of
+            the table of contents serve the screen only, so print (the
+            PDF) neither carries nor runs them  */
+        const screen = !print;
         return render("Document", { Document: {
                 title: documentTitle(specification).title,
                 lang,
@@ -202,17 +243,19 @@ export const renderHtml = async (specification, config, tocPages, css, options =
                 themescript: safe(themeScript),
                 titlepage: title !== undefined ?
                     safe(renderTitlePage(title, formatDate(created), formatDate(modified))) : "",
-                search: safe(searchScript()),
-                progress: safe(scrollProgressScript),
+                search: screen ? safe(searchScript()) : "",
+                filtergrid: { rows, columns: 1 + Math.max(0, ...rows.map((row) => row.cells.length)) },
+                filter: screen ? safe(filterScript(links)) : "",
+                progress: screen ? safe(scrollProgressScript) : "",
                 omitted,
-                fold: safe(foldScript(omit.size > 0, omitted.text)),
-                maximize: safe(maximizeScript),
-                info: info !== null ? safe(infoScript(info, spec)) : "",
-                realtime: options.realtime === true ? safe(realtimeScript) : "",
+                fold: screen ? safe(foldScript(omit.size > 0, omitted.text)) : "",
+                maximize: screen ? safe(maximizeScript) : "",
+                info: screen && info !== null ? safe(infoScript(info, spec)) : "",
+                realtime: screen && options.realtime === true ? safe(realtimeScript) : "",
                 toc: entries.length > 0 ? safe(render("Toc", { Toc: { entries } })) : "",
-                tocpanel: entries.length > 0 ?
+                tocpanel: screen && entries.length > 0 ?
                     safe(renderTocPanel(objects, title !== undefined, doc !== undefined)) : "",
-                tocscript: entries.length > 0 ? safe(tocPanelScript) : "",
+                tocscript: screen && 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.d.ts

@@ -1,7 +1,8 @@
-import type { Spec, SpecArtifact } from "./specbook-format-spec.js";
+import type { Spec, SpecArtifact, SpecObject } from "./specbook-format-spec.js";
 import type { Schema } from "./specbook-format-schema.js";
 import type { Verbose } from "./specbook-verbose.js";
 export declare const formatTimestamp: (date: Date) => string;
+export declare const renderObjectMd: (object: SpecObject, level: number, diagrams?: Map<SpecObject, string[]>) => string;
 export interface MarkdownRebase {
     origins: Map<SpecArtifact, string>;
     dir: string;

package/dst/specbook-export-md.js

@@ -76,14 +76,13 @@ const renderConciseMd = (object, depth = 0) => {
     a description no concise item can carry, so all children (as siblings
     have to share the format) stay in the Complex Format down to heading
     level 6, the deepest one Markdown knows, below which the children 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) => {
+    concise regardless -- and the optionally derived Gradia diagram specs
+    embedded as "gradia" fenced code blocks below the heading  */
+export const renderObjectMd = (object, level, diagrams) => {
     const heading = `${"#".repeat(level)}${" ".repeat(Math.max(1, 4 - level))}` +
         `${object.kind}: ${object.name}${nameSuffixMd(object)}`;
     const parts = [heading];
-    const spec = diagrams?.get(object);
-    if (spec !== undefined)
+    for (const spec of diagrams?.get(object) ?? [])
         parts.push(`\`\`\`gradia\n${spec}\`\`\``);
     if (object.properties.length > 0)
         parts.push(renderKeyValuesMd(object.properties));
@@ -116,9 +115,9 @@ export const renderMarkdown = async (specification, config, rebase, verbose) =>
         the title object is reserved for the HTML/PDF export)  */
     const diagrams = new Map();
     if (config !== undefined)
-        for (const [object, result] of specDiagrams(specification, config))
-            if (result.spec !== undefined && !isTitleObject(object))
-                diagrams.set(object, result.spec);
+        for (const [object, results] of specDiagrams(specification, config))
+            if (!isTitleObject(object))
+                diagrams.set(object, results.flatMap((result) => result.spec !== undefined ? [result.spec] : []));
     /*  embed the images of a text, optimized like the ones of the HTML
         export: an embeddable "![alt](file)" becomes the reference-style
         "![alt][img-N]", whose "[img-N]: data:..." definition ends the

package/dst/specbook-export-pdf.js

@@ -220,7 +220,7 @@ export const htmlToPdf = async (renderHtmlPass, heading, outline, titlePage, ver
         const page = await browser.newPage();
         /*  render an HTML document into a paginated PDF  */
         const renderPdf = async (html, options = {}) => {
-            await page.setContent(html, { waitUntil: "networkidle" });
+            await page.setContent(html, { waitUntil: "load", timeout: 0 });
             await page.evaluate(() => document.fonts.ready);
             return page.pdf({
                 format: paper,

package/dst/specbook-files.d.ts

@@ -0,0 +1,2 @@
+export declare const specFiles: (basedir: string) => string[];
+export declare const isBelow: (file: string, dir: string) => boolean;