@rse/specbook 1.5.2 → 1.6.1

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

@@ -25,12 +25,12 @@
     /*  let the search icon slide the input field out of the tab (and
         back in again), remembering the choice across page loads  */
     const slide = (open) => {
-        tab.classList.toggle("open", open)
-        if (tab.classList.contains("open"))
+        const opened = tab.classList.toggle("open", open)
+        if (opened)
             input.focus()
         else
             input.blur()
-        try { localStorage.setItem("specbook-search", tab.classList.contains("open") ? "open" : "closed") }
+        try { localStorage.setItem("specbook-search", opened ? "open" : "closed") }
         catch { /*  an inaccessible storage just loses the state  */ }
     }
     try { if (localStorage.getItem("specbook-search") === "open") tab.classList.add("open") }
@@ -83,23 +83,6 @@
                 units.push({ el, id, text, words, keep: false })
             })
         })
-
-        /*  let a hyperlink whose target the filtering hid leave the
-            search mode (like the Escape key) before it jumps: the click
-            is intercepted, the document revealed again, and the click
-            re-issued, so the browser performs the regular jump  */
-        document.querySelectorAll("a[href^='#']").forEach((link) => {
-            link.addEventListener("click", (event) => {
-                const target = document.getElementById(
-                    decodeURIComponent((link.getAttribute("href") ?? "").slice(1)))
-                if (target === null || target.closest(".search-hide") === null)
-                    return
-                event.preventDefault()
-                reset()
-                slide(false)
-                link.click()
-            })
-        })
     }
 
     /*  the Levenshtein edit distance of two words  */
@@ -399,4 +382,19 @@
         reset()
         input.focus()
     })
+
+    /*  let a hyperlink whose target the filtering hid leave the search
+        mode (like the Escape key) before it jumps, so the browser
+        performs the regular jump onto the revealed target  */
+    document.body.addEventListener("click", (event) => {
+        const link = event.target.closest("a[href^='#']")
+        if (link === null || !document.body.classList.contains("searching"))
+            return
+        const target = document.getElementById(
+            decodeURIComponent((link.getAttribute("href") ?? "").slice(1)))
+        if (target === null || target.closest(".search-hide") === null)
+            return
+        reset()
+        slide(false)
+    })
 })()

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

@@ -34,18 +34,45 @@ const templates = {
                         <span class="search-clear" id="search-clear" title="clear search">&#x00D7;</span>
                     </div>
                 </div>
+                <div class="filter-switch">
+                    <div class="filter-toggle" title="toggle artifact filter"><svg class="filter-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="M12 3l-9 4.5 9 4.5 9-4.5z"/><path d="M3 12.25l9 4.5 9-4.5"/><path d="M3 17l9 4.5 9-4.5"/></svg></div>
+                    <div class="filter-panel">
+                        <div class="filter-grid" style="grid-template-columns: repeat({{ Document.filtergrid.columns }}, max-content)">
+                            {% for row in Document.filtergrid.rows %}
+                            <div class="filter-kind" title="toggle all {{ row.kind }} artifacts">{{ row.kind }}</div>
+                            {%- for cell in row.cells %}<div class="filter-cell" data-id="{{ cell.id }}" title="{{ cell.title }}">{{ cell.label }}</div>{% endfor %}
+                            {% endfor %}
+                        </div>
+                    </div>
+                </div>
                 {%- if not Document.omitted.all %}
                 <div class="fold-switch">
                     <div class="fold-toggle" title="toggle folding controls"><svg class="fold-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="M7 3.5l5 5 5-5"/><path d="M7 20.5l5-5 5 5"/></svg></div>
-                    <div class="fold-controls">
+                    <div class="fold-panel">
+                        <div class="fold-rows">
+                        {%- if not Document.omitted.gradia %}
+                        <div class="fold-row">
                         {% if not Document.omitted.graph %}<div class="fold-graphs" title="fold/unfold all graph diagrams"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><circle cx="5.5" cy="5.5" r="3"/><circle cx="18.5" cy="5.5" r="3"/><circle cx="12" cy="18.5" r="3"/><path d="M7.3 8.1 10.6 15.9"/><path d="M16.7 8.1 13.4 15.9"/></svg></div>{% endif %}
                         {% if not Document.omitted.hub %}<div class="fold-hubs" title="fold/unfold all hub diagrams"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="3.5"/><circle cx="3.5" cy="4.5" r="2"/><circle cx="3.5" cy="19.5" r="2"/><circle cx="20.5" cy="4.5" r="2"/><circle cx="20.5" cy="19.5" r="2"/><path d="M5.5 4.5H10V9.1"/><path d="M18.5 4.5H14V9.1"/><path d="M5.5 19.5H10V14.9"/><path d="M18.5 19.5H14V14.9"/></svg></div>{% endif %}
                         {% if not Document.omitted.grid %}<div class="fold-grids" title="fold/unfold all grid diagrams"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><rect x="3.5" y="3.5" width="7" height="7" rx="1"/><rect x="13.5" y="3.5" width="7" height="7" rx="1"/><rect x="3.5" y="13.5" width="7" height="7" rx="1"/><rect x="13.5" y="13.5" width="7" height="7" rx="1"/></svg></div>{% endif %}
+                        {% if not Document.omitted.state %}<div class="fold-states" title="fold/unfold all state diagrams"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><circle cx="3.5" cy="12" r="2" fill="currentColor"/><path d="M6.5 12h4"/><path d="M8.5 10 10.5 12l-2 2"/><rect x="12.5" y="7" width="9.5" height="10" rx="3"/></svg></div>{% endif %}
+                        {% if not Document.omitted.layer %}<div class="fold-layers" title="fold/unfold all layer diagrams"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><rect x="3.5" y="3.5" width="17" height="4" rx="1"/><rect x="3.5" y="10" width="17" height="4" rx="1"/><rect x="3.5" y="16.5" width="17" height="4" rx="1"/></svg></div>{% endif %}
+                        {% if not Document.omitted.slice %}<div class="fold-slices" title="fold/unfold all slice diagrams"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><rect x="3.5" y="3.5" width="4" height="17" rx="1"/><rect x="10" y="3.5" width="4" height="17" rx="1"/><rect x="16.5" y="3.5" width="4" height="17" rx="1"/></svg></div>{% endif %}
+                        {% if not Document.omitted.tree %}<div class="fold-trees" title="fold/unfold all tree diagrams"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="2.5" width="6" height="5" rx="1"/><rect x="2.5" y="16.5" width="6" height="5" rx="1"/><rect x="15.5" y="16.5" width="6" height="5" rx="1"/><path d="M12 7.5v4.5"/><path d="M5.5 16.5V12h13v4.5"/></svg></div>{% endif %}
+                        {% if not Document.omitted.matrix %}<div class="fold-matrices" title="fold/unfold all matrix diagrams"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><rect x="3.5" y="3.5" width="17" height="17" rx="1.5"/><path d="M9.5 3.5v17"/><path d="M3.5 9.5h17"/><path d="M13 13h.01"/><path d="M17 17h.01"/></svg></div>{% endif %}
+                        {% if not Document.omitted.sequence %}<div class="fold-sequences" title="fold/unfold all sequence diagrams"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><rect x="2.5" y="2.5" width="7" height="4" rx="1"/><rect x="14.5" y="2.5" width="7" height="4" rx="1"/><path d="M6 6.5v15" stroke-dasharray="1.5 2.5"/><path d="M18 6.5v15" stroke-dasharray="1.5 2.5"/><path d="M6 12h10"/><path d="M14 9.5l2.5 2.5-2.5 2.5"/></svg></div>{% endif %}
+                        {% if not Document.omitted.petri %}<div class="fold-petris" title="fold/unfold all Petri net diagrams"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><circle cx="6.5" cy="12" r="4.5"/><path d="M6.5 12h.01"/><path d="M11 12h5"/><path d="M14 9.5l2.5 2.5-2.5 2.5"/><path d="M19.5 5.5v13"/></svg></div>{% endif %}
+                        {% if not Document.omitted.gantt %}<div class="fold-gantts" title="fold/unfold all Gantt charts"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><rect x="2.5" y="3.5" width="8" height="4" rx="1"/><rect x="7.5" y="10" width="9" height="4" rx="1"/><rect x="12.5" y="16.5" width="9" height="4" rx="1"/></svg></div>{% endif %}
+                        </div>
+                        {%- endif %}
+                        <div class="fold-row">
                         {% if not Document.omitted.code %}<div class="fold-codes" title="fold/unfold all diagrams as code"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="M8 7l-5 5 5 5"/><path d="M16 7l5 5-5 5"/><path d="M13.5 4l-3 16"/></svg></div>{% endif %}
                         {% if not Document.omitted.image %}<div class="fold-images" title="fold/unfold all images"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><rect x="2.5" y="3.5" width="19" height="17" rx="2"/><circle cx="8.5" cy="9" r="2"/><path d="M21.5 15.5l-5-5-11 10"/></svg></div>{% endif %}
                         {% if not Document.omitted.listing %}<div class="fold-listings" title="fold/unfold all code listings"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="M9 6h11.5"/><path d="M9 12h11.5"/><path d="M9 18h7"/><path d="M3.5 6h.01"/><path d="M3.5 12h.01"/><path d="M3.5 18h.01"/></svg></div>{% endif %}
                         {% for level in [ 1, 2, 3 ] %}{% if not Document.omitted["level" ~ level] %}<div class="fold-level{{ level }}" title="fold/unfold all diagrams from nesting level {{ level }} on"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><rect x="2.5" y="2.5" width="11" height="11" rx="1.5"/><rect x="6.5" y="6.5" width="3" height="3" rx="0.5"/><text x="19.5" y="23" text-anchor="middle" font-size="14.5" font-weight="bold" fill="currentColor" stroke="none">{{ level }}</text></svg></div>{% endif %}{% endfor %}
                         {% if not Document.omitted.text %}<div class="fold-texts" title="fold/unfold all cell texts"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="M4.5 7V4.5h15V7"/><path d="M12 4.5v15"/><path d="M8.5 19.5h7"/></svg></div>{% endif %}
+                        </div>
+                        </div>
                     </div>
                 </div>
                 {%- endif %}
@@ -56,10 +83,11 @@ const templates = {
                 {{ Document.doc }}
                 {{ Document.artifacts }}
                 {% if Document.search %}<script>{{ Document.search }}</script>{% endif %}
-                <script>{{ Document.progress }}</script>
-                <script>{{ Document.fold }}</script>
-                <script>{{ Document.maximize }}</script>
-                {% if Document.tocpanel %}<script>{{ Document.tocscript }}</script>{% endif %}
+                {% if Document.progress %}<script>{{ Document.progress }}</script>{% endif %}
+                {% if Document.fold %}<script>{{ Document.fold }}</script>{% endif %}
+                {% if Document.filter %}<script>{{ Document.filter }}</script>{% endif %}
+                {% if Document.maximize %}<script>{{ Document.maximize }}</script>{% endif %}
+                {% if Document.tocscript %}<script>{{ Document.tocscript }}</script>{% endif %}
                 {% if Document.info %}<script>{{ Document.info }}</script>{% endif %}
                 {% if Document.realtime %}<script class="realtime">{{ Document.realtime }}</script>{% endif %}
             </body>
@@ -183,10 +211,10 @@ const templates = {
     "Description": textframe `
         {%- if Description.block %}
         <div class="description">{{ Description.description }}{% if Description.rationale %}
-            <p class="rationale">&mdash; <span class="keyword">BECAUSE</span> {{ Description.rationale }}</p>{% endif %}</div>
+            <p class="rationale">&mdash; <span class="keyword">BECAUSE</span>{% if Description.keyword %} ({{ Description.keyword }}){% endif %} {{ Description.rationale }}</p>{% endif %}</div>
         {%- elif Description.description or Description.rationale %}
         <p class="description">{{ Description.description }}{% if Description.rationale %}
-            <span class="rationale">&mdash; <span class="keyword">BECAUSE</span> {{ Description.rationale }}</span>{% endif %}</p>
+            <span class="rationale">&mdash; <span class="keyword">BECAUSE</span>{% if Description.keyword %} ({{ Description.keyword }}){% endif %} {{ Description.rationale }}</span>{% endif %}</p>
         {%- endif %}
         {%- if Description.elaboration %}
         <div class="description">{{ Description.elaboration }}</div>
@@ -201,8 +229,8 @@ const templates = {
             <thead>
                 <tr>
                     <th class="object-kind"><span{% if Table.info %} data-info="{{ Table.info }}" data-info-path="{{ Table.infopath }}"{% endif %}>{{ Table.head }}</span></th>
-                    {%- for key in Table.keys %}<th class="property-name"><span{% if Table.info %} data-info="{{ Table.info }}" data-info-path="{{ Table.infopath }}" data-info-prop="{{ key }}"{% endif %}>{{ key }}</span></th>{% endfor %}
-                    {%- if Table.desc %}<th class="description" style="width: {{ Table.width }}%">Description</th>{% endif %}
+                    {%- for key in Table.keys %}<th class="property-name" style="width: {{ Table.widths[loop.index0] }}%"><span{% if Table.info %} data-info="{{ Table.info }}" data-info-path="{{ Table.infopath }}" data-info-prop="{{ key }}"{% endif %}>{{ key }}</span></th>{% endfor %}
+                    {%- if Table.desc %}<th class="description" style="width: {{ Table.widths[Table.keys.length] }}%">Description</th>{% endif %}
                 </tr>
             </thead>
             <tbody>
@@ -231,6 +259,7 @@ const templates = {
                     <td><span{% if row.spec %} data-info-spec="{{ row.spec }}"{% endif %}>{{ row.name }}</span>{% if row.primary %} <span class="primary-marker">&#x2318;</span>{% endif %}{% if row.paren %} <span class="anchor-paren">({{ row.paren }})</span>{% endif %} <a href="#{{ row.id }}"><span class="anchor-symbol">&#x2693;&#xFE0E;</span></a></td>
                     <td class="chunks">
                         <table class="chunks">
+                            <colgroup>{% for width in Table.widths %}<col style="width: {{ width }}%">{% endfor %}</colgroup>
                             {% for chunk in row.chunks %}
                             <tr>{% for cell in chunk %}<th{% if not cell.desc %} class="property-name"{% endif %}{% if cell.span > 1 %} colspan="{{ cell.span }}"{% endif %}><span{% if not cell.desc and Table.info %} data-info="{{ Table.info }}" data-info-path="{{ row.spec }}" data-info-prop="{{ cell.key }}"{% endif %}>{{ cell.key }}</span></th>{% endfor %}</tr>
                             <tr>{% for cell in chunk %}<td{% if cell.span > 1 %} colspan="{{ cell.span }}"{% endif %}>{{ cell.value }}</td>{% endfor %}</tr>

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

@@ -4,6 +4,8 @@ export declare const realtimeScript: string;
 export declare const scrollProgressScript: string;
 export declare const maximizeScript: string;
 export declare const tocPanelScript: string;
+export type FilterEntry = [parent: number, segment: string, targets: number[]];
+export declare const filterScript: (links: FilterEntry[]) => string;
 export type InfoEntry = {
     d?: string;
     p?: Record<string, string>;

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

@@ -235,10 +235,10 @@ export const maximizeScript = textframe `
                 .find((el) => el.getClientRects().length > 0)
             if (shown === undefined)
                 return
-            const svg = shown.cloneNode(true)
-            if (svg.tagName !== "PRE")
-                svg.removeAttribute("style")
-            content.replaceChildren(svg)
+            const clone = shown.cloneNode(true)
+            if (clone.tagName !== "PRE")
+                clone.removeAttribute("style")
+            content.replaceChildren(clone)
             overlay.classList.add("open")
             document.documentElement.classList.add("maximized")
             if (fullscreen)
@@ -323,7 +323,7 @@ export const tocPanelScript = textframe `
             }
             let current = null
             for (let i = 0; i < targets.length; i++) {
-                if (targets[i] === null)
+                if (targets[i] === null || targets[i].getClientRects().length === 0)
                     continue
                 const top = targets[i].getBoundingClientRect().top
                 if (top >= -1 && top < window.innerHeight) {
@@ -359,8 +359,8 @@ export const tocPanelScript = textframe `
                 anchored.classList.add("anchored")
         }
         const toggle = (open) => {
-            panel.classList.toggle("open", open)
-            try { localStorage.setItem("specbook-toc", panel.classList.contains("open") ? "open" : "closed") }
+            const opened = panel.classList.toggle("open", open)
+            try { localStorage.setItem("specbook-toc", opened ? "open" : "closed") }
             catch { /*  an inaccessible storage just loses the state  */ }
         }
         try { if (localStorage.getItem("specbook-toc") === "open") panel.classList.add("open") }
@@ -375,6 +375,7 @@ export const tocPanelScript = textframe `
                 && event.target.closest("div.search")          === null
                 && event.target.closest("div.theme-switch")    === null
                 && event.target.closest("div.info-switch")     === null
+                && event.target.closest("div.filter-switch")   === null
                 && event.target.closest("div.fold-switch")     === null
                 && event.target.closest("div.realtime-status") === null)
                 toggle(false)
@@ -445,12 +446,11 @@ const infoPopupScript = textframe `
             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  */
+            /*  compose the title path segments of an object, each a pair
+                of its kind and its name (empty for a kind-only segment)  */
             const pathOf = (n, named) => {
                 const [ , up, kind, title ] = SPEC[n]
-                const name = named ? title : ""
-                return [ ...(up >= 0 ? pathOf(up, true) : []),
-                    name !== "" && kind !== "" ? kind + ": " + name : (name !== "" ? name : kind) ]
+                return [ ...(up >= 0 ? pathOf(up, true) : []), [ kind, named ? title : "" ] ]
             }
             const title = document.createElement("div")
             title.className = "info-title"
@@ -465,7 +465,7 @@ const infoPopupScript = textframe `
             const ref      = spec ?? source.getAttribute("data-info-path") ?? ""
             const index    = parseInt(ref, 10)
             const segments = SPEC[index] !== undefined ? pathOf(index, !ref.endsWith("^")) : []
-            for (const [ i, segment ] of segments.entries()) {
+            for (const [ i, [ kindText, nameText ] ] of segments.entries()) {
                 if (i > 0)
                     title.appendChild(pointer())
                 const path = document.createElement("span")
@@ -476,22 +476,21 @@ 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 bare = i === segments.length - 1 && spec === null && prop === null
                 const name = document.createElement("span")
                 name.className = "info-name"
-                if (m !== null || bare) {
+                if (kindText !== "" && (nameText !== "" || bare)) {
                     const kind = document.createElement("span")
                     kind.className = "info-kind"
-                    kind.textContent = m !== null ? m[1] + ":" : segment
+                    kind.textContent = nameText !== "" ? kindText + ":" : kindText
                     path.appendChild(kind)
-                    if (m !== null) {
-                        name.textContent = m[2]
+                    if (nameText !== "") {
+                        name.textContent = nameText
                         path.append(" ", name)
                     }
                 }
                 else {
-                    name.textContent = segment
+                    name.textContent = nameText !== "" ? nameText : kindText
                     path.appendChild(name)
                 }
                 title.appendChild(path)
@@ -583,7 +582,10 @@ const infoPopupScript = textframe `
                 return
             cancel()
             pending   = el
-            pendingId = setTimeout(() => { pending = null; show(el) }, 400)
+            pendingId = setTimeout(() => {
+                pending = null
+                show(el)
+            }, 400)
         })
         document.body.addEventListener("mouseout", (event) => {
             const el = event.target.closest(targets)
@@ -596,6 +598,204 @@ const infoPopupScript = textframe `
         })
     })(@INFO@, @SPEC@)
 `;
+/*  the client-side script of the artifact filter: the filter tab
+    slides a grid out, holding one row per artifact kind -- the kind
+    cell first, then one cell per top-level artifact of the kind --,
+    whose cells are sticky checkboxes (persisted across page loads as
+    the anchor paths of the enabled artifacts), a kind cell toggling
+    all artifacts of its row. Every enabled artifact is an origin shown
+    entirely, while in all other artifacts only the objects stay
+    visible which the closure reaches from the origin objects through
+    the outgoing references (the own references of a reached object
+    continuing it, not those of its hidden children), each shown
+    without its child objects, plus the headings of its enclosing
+    objects; the table of contents (page and side panel) is filtered
+    along and the diagram of contents hidden. The closure is computed
+    from the injected LINKS table (per object: parent index, anchor
+    path segment, and referenced object indices), from which the anchor
+    paths identifying the DOM elements are composed. A hyperlink whose
+    target the filter hid clears the filter before it jumps. The script
+    runs at the end of the body, as the content it hides has to exist
+    already, and a live preview body swap replaces the tab and its
+    listeners along with the body  */
+const artifactFilterScript = textframe `
+    (function (LINKS) {
+        const tab = document.querySelector("div.filter-switch")
+        if (tab === null)
+            return
+
+        /*  let the filter icon slide the grid out of the tab (and
+            back in again), remembering the choice across page loads  */
+        try { if (localStorage.getItem("specbook-filter") === "open") tab.classList.add("open") }
+        catch { /*  an inaccessible storage just means no stored state  */ }
+        tab.querySelector("div.filter-toggle").addEventListener("click", () => {
+            const opened = tab.classList.toggle("open")
+            try { localStorage.setItem("specbook-filter", opened ? "open" : "closed") }
+            catch { /*  an inaccessible storage just loses the state  */ }
+        })
+
+        /*  the anchor path of every object (composed from the segments
+            along its ancestor chain), the object index per path, and
+            the top-level object (the artifact) of every object  */
+        const paths  = []
+        const roots  = []
+        const byPath = new Map()
+        LINKS.forEach(([ parent, segment ], n) => {
+            paths[n] = parent >= 0 ? paths[parent] + "." + segment : segment
+            roots[n] = parent >= 0 ? roots[parent] : n
+            byPath.set(paths[n], n)
+        })
+
+        /*  the grid rows: the kind cell leading a row toggles the
+            artifact cells following it, each identified by the anchor
+            path (and hence the index) of its top-level object  */
+        const rows  = []
+        const cells = new Map()
+        for (const el of tab.querySelector("div.filter-grid").children) {
+            if (el.classList.contains("filter-kind"))
+                rows.push({ kind: el, cells: [] })
+            else {
+                const n = byPath.get(el.getAttribute("data-id"))
+                if (n === undefined || rows.length === 0)
+                    continue
+                cells.set(n, el)
+                rows[rows.length - 1].cells.push(n)
+            }
+        }
+
+        /*  the active origins (the indices of the enabled artifacts),
+            persisted across page loads as the list of their anchor paths  */
+        const active = new Set()
+        const store = () => {
+            try { localStorage.setItem("specbook-filter-origins", Array.from(active).map((n) => paths[n]).join(",")) }
+            catch { /*  an inaccessible storage just loses the state  */ }
+        }
+        try {
+            for (const path of (localStorage.getItem("specbook-filter-origins") ?? "").split(",")) {
+                const n = byPath.get(path)
+                if (n !== undefined && cells.has(n))
+                    active.add(n)
+            }
+        }
+        catch { /*  an inaccessible storage just means no stored state  */ }
+
+        /*  apply the active origins onto the cells and the content  */
+        const apply = () => {
+            document.querySelectorAll(".filter-hide").forEach((el) => { el.classList.remove("filter-hide") })
+            document.body.classList.toggle("filtering", active.size > 0)
+            for (const [ n, cell ] of cells)
+                cell.classList.toggle("on", active.has(n))
+            for (const row of rows) {
+                const count = row.cells.filter((n) => active.has(n)).length
+                row.kind.classList.toggle("on",   count > 0 && count === row.cells.length)
+                row.kind.classList.toggle("some", count > 0 && count !== row.cells.length)
+            }
+            if (active.size === 0)
+                return
+
+            /*  the visibility state of every object: the objects of the
+                origin artifacts are shown entirely (3), the objects the
+                closure reaches from them through the own references of
+                a reached object are shown without their children (2),
+                the ancestors of those as headings only (1), and all
+                other objects are hidden (0)  */
+            const state = LINKS.map((_, n) => active.has(roots[n]) ? 3 : 0)
+            const queue = LINKS.map((_, n) => n).filter((n) => state[n] === 3)
+            for (let i = 0; i < queue.length; i++) {
+                for (const target of LINKS[queue[i]][2]) {
+                    if (state[target] >= 2)
+                        continue
+                    state[target] = 2
+                    queue.push(target)
+                    for (let p = LINKS[target][0]; p >= 0 && state[p] === 0; p = LINKS[p][0])
+                        state[p] = 1
+                }
+            }
+
+            /*  hide a hidden object entirely (its section or table row)
+                and the own content of a heading-only one (everything in
+                its section but the heading and the child containers,
+                whose objects carry states of their own), plus the tables
+                and articles which ran entirely empty in the process  */
+            state.forEach((s, n) => {
+                if (s >= 2)
+                    return
+                const el = document.getElementById(paths[n])
+                if (el === null)
+                    return
+                const box = el.tagName === "TR" ? el : el.closest("section")
+                if (box === null)
+                    return
+                if (s === 0)
+                    box.classList.add("filter-hide")
+                else if (box !== el)
+                    for (const child of box.children)
+                        if (child !== el && child.tagName !== "SECTION" && !child.classList.contains("objects"))
+                            child.classList.add("filter-hide")
+            })
+            document.querySelectorAll("article table.objects").forEach((table) => {
+                if (table.querySelector(":scope > tbody > tr:not(.filter-hide)") === null)
+                    table.classList.add("filter-hide")
+            })
+            document.querySelectorAll("article").forEach((article) => {
+                if (article.querySelector(":scope > section:not(.filter-hide)") === null)
+                    article.classList.add("filter-hide")
+            })
+
+            /*  filter the table of contents (its page rows and its side
+                panel entries) along: an entry stays visible only while
+                its target still is (the diagram of contents, spanning
+                all artifacts, is hidden by the stylesheet)  */
+            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.closest(".filter-hide") !== null || target.closest("nav.doc") !== null))
+                    entry.classList.add("filter-hide")
+            })
+        }
+        for (const [ n, cell ] of cells)
+            cell.addEventListener("click", () => {
+                if (!active.delete(n))
+                    active.add(n)
+                store()
+                apply()
+            })
+        for (const row of rows)
+            row.kind.addEventListener("click", () => {
+                const all = row.cells.every((n) => active.has(n))
+                for (const n of row.cells) {
+                    if (all)
+                        active.delete(n)
+                    else
+                        active.add(n)
+                }
+                store()
+                apply()
+            })
+
+        /*  let a hyperlink whose target the filter hid clear the filter
+            before it jumps, so the browser performs the regular jump
+            onto the revealed target  */
+        document.body.addEventListener("click", (event) => {
+            const link = event.target.closest("a[href^='#']")
+            if (link === null || active.size === 0)
+                return
+            const target = document.getElementById(
+                decodeURIComponent((link.getAttribute("href") ?? "").slice(1)))
+            if (target === null || target.closest(".filter-hide") === null)
+                return
+            active.clear()
+            store()
+            apply()
+        })
+        apply()
+    })(@LINKS@)
+`;
+/*  inject the reference table of the artifact filter into its
+    client-side script ("<" escaped, so no embedded text can close the
+    surrounding <script> element)  */
+export const filterScript = (links) => artifactFilterScript.replace("@LINKS@", () => JSON.stringify(links).replace(/</g, "\\u003c"));
 /*  inject the description popup tables into their client-side script ("<"
     escaped, so no embedded HTML can close the surrounding <script>
     element, and the trailing table first, so a placeholder text