@rse/specbook 1.0.2 → 1.0.4

package/dst/specbook-config.js

@@ -6,8 +6,9 @@
 import * as fs from "node:fs";
 import { parseDocument, isNode, LineCounter } from "yaml";
 import * as v from "valibot";
+import { mergeWith, isPlainObject } from "es-toolkit";
 import { Schema } from "./specbook-format-schema.js";
-import { compileValueExpr, anchored } from "./specbook-parse-value.js";
+import { compileValueExpr, anchored, admitsReferences } from "./specbook-parse-value.js";
 /*  determine line/column of a YAML document path via the node ranges
     of the parsed document, falling back to the closest ancestor node  */
 const lineColOfPath = (doc, lines, path) => {
@@ -21,17 +22,86 @@ const lineColOfPath = (doc, lines, path) => {
     }
     return { line: 1, column: 1 };
 };
+/*  the identity by which the elements of the lists of the configuration
+    are matched on merging: the artifacts by their kind plus id or name
+    and the nested objects by their kind alone (exactly like the sibling
+    resolution), the properties by their name, and the scalar entries
+    by their value  */
+const identityOf = (item, list) => {
+    if (!isPlainObject(item))
+        return String(item);
+    const object = item;
+    if (list === "props")
+        return String(object.name ?? "");
+    else if (list === "childs")
+        return String(object.kind ?? "");
+    else
+        return `${String(object.kind ?? "")}:${String(object.id ?? object.name ?? "")}`;
+};
+/*  merge a source configuration (or a nested part of it) into a target
+    one: the objects merge deeply, while the elements of the lists are
+    matched by their identity, so a matching element is merged into its
+    counterpart and an unmatched one is appended  */
+const mergeConfig = (target, source, list) => {
+    if (Array.isArray(target) && Array.isArray(source)) {
+        for (const item of source) {
+            const i = target.findIndex((existing) => identityOf(existing, list) === identityOf(item, list));
+            if (i < 0)
+                target.push(item);
+            else
+                target[i] = mergeConfig(target[i], item, list);
+        }
+        return target;
+    }
+    else if (isPlainObject(target) && isPlainObject(source))
+        return mergeWith(target, source, (t, s, key) => Array.isArray(t) && Array.isArray(s) ? mergeConfig(t, s, key) : undefined);
+    else
+        return source;
+};
+/*  determine file and line/column of a path into the merged
+    configuration by translating the path into every document (from the
+    last to the first one, as a later document overrides an earlier one),
+    where a list index is translated through the identity of the merged
+    element, and by taking the deepest reaching translation, whose path
+    is returned, too (or the original one if it does not reach fully)  */
+const posOfMergedPath = (docs, merged, path) => {
+    const at = (value, key) => value?.[key];
+    let best = { file: docs[docs.length - 1].file, line: 1, column: 1, path, depth: -1 };
+    for (const { file, doc, lines, raw } of docs.slice().reverse()) {
+        const translated = [];
+        let node = merged;
+        let own = raw;
+        let list;
+        for (const segment of path) {
+            const key = typeof segment === "number" && Array.isArray(own) ?
+                own.findIndex((item) => identityOf(item, list) === identityOf(at(node, segment), list)) : segment;
+            if (typeof key === "number" ? !Array.isArray(own) || key < 0 : !isPlainObject(own) || !(key in own))
+                break;
+            translated.push(key);
+            node = at(node, segment);
+            own = at(own, key);
+            if (typeof segment === "string")
+                list = segment;
+        }
+        if (translated.length > best.depth)
+            best = { file, ...lineColOfPath(doc, lines, translated), path: translated, depth: translated.length };
+    }
+    return { file: best.file, line: best.line, column: best.column,
+        path: best.depth === path.length ? best.path : path };
+};
 /*  check the constraints of a structurally valid configuration which
     are beyond its schema: sibling objects have to stay distinctly
     resolvable, "file" fields are allowed on the first (artifact) level
-    only, property value expressions have to be syntactically valid, and
-    the names of non-artifact objects have to be valid patterns (as they
-    are compiled into regular expressions)  */
-const checkConstraints = (config, file, posOfPath) => {
+    only, property value and marker expressions have to be syntactically
+    valid, "referenced" entries have to be reference expressions, an
+    "automaton" has to name existing child kinds and properties, and the
+    names of non-artifact objects have to be valid patterns (as they are
+    compiled into regular expressions)  */
+const checkConstraints = (config, posOfPath) => {
     const diagnostics = new Array();
     const diagnose = (path, message) => {
-        const pos = posOfPath(path);
-        diagnostics.push({ file, line: pos.line, column: pos.column, message });
+        const { file, line, column } = posOfPath(path);
+        diagnostics.push({ file, line, column, severity: "error", message });
     };
     const check = (objects, path, depth) => {
         /*  the sibling objects are resolved by kind and id on the first
@@ -48,15 +118,86 @@ const checkConstraints = (config, file, posOfPath) => {
             if (depth > 1 && object.file !== undefined)
                 diagnose([...at, "file"], `"file" field is only allowed on the first (artifact) level (found on level ${depth})`);
             for (const [j, prop] of (object.props ?? []).entries()) {
-                if (prop.value === undefined)
-                    continue;
+                /*  the relation shape flags apply to reference-valued
+                    properties only (an invalid expression is reported on
+                    its own, without a cascading flag diagnostic)  */
+                let expr;
+                if (prop.value !== undefined) {
+                    try {
+                        expr = compileValueExpr(prop.value);
+                    }
+                    catch (err) {
+                        diagnose([...at, "props", j, "value"], `invalid value expression "${prop.value}": ` +
+                            (err instanceof Error ? err.message : String(err)));
+                        continue;
+                    }
+                }
+                for (const flag of ["local", "symmetric", "acyclic"])
+                    if (prop[flag] === true && (expr === undefined || !admitsReferences(expr)))
+                        diagnose([...at, "props", j, flag], `"${flag}" flag requires a reference-valued property`);
+                /*  the sibling marker flags optionally carry a regexp or
+                    enum expression selecting the values they apply to  */
+                for (const flag of ["unique", "present"]) {
+                    const marker = prop[flag];
+                    if (typeof marker !== "string")
+                        continue;
+                    let kind;
+                    try {
+                        kind = compileValueExpr(marker).kind;
+                    }
+                    catch (err) {
+                        diagnose([...at, "props", j, flag], `invalid "${flag}" expression "${marker}": ` +
+                            (err instanceof Error ? err.message : String(err)));
+                    }
+                    if (kind !== undefined && kind !== "regex" && kind !== "enum")
+                        diagnose([...at, "props", j, flag], `"${flag}" expression "${marker}" is neither a regexp nor an enum`);
+                }
+            }
+            if (object.automaton !== undefined) {
+                /*  an automaton names the child kinds acting as nodes and
+                    edges, the reference-valued edge properties referencing
+                    the source and target nodes, and the node properties
+                    flagging the initial and final nodes  */
+                const automaton = object.automaton;
+                const childOf = (kind) => (object.childs ?? []).find((c) => c.kind === kind);
+                const propOf = (child, name) => (child?.props ?? []).find((p) => p.name === name);
+                const isReference = (prop) => {
+                    try {
+                        return prop.value !== undefined && admitsReferences(compileValueExpr(prop.value));
+                    }
+                    catch {
+                        return false;
+                    }
+                };
+                const nodes = childOf(automaton.nodes);
+                const edges = childOf(automaton.edges);
+                for (const [field, child] of [["nodes", nodes], ["edges", edges]])
+                    if (child === undefined)
+                        diagnose([...at, "automaton", field], `"automaton" ${field} kind "${automaton[field]}" is not a child object kind`);
+                for (const field of ["source", "target"]) {
+                    const prop = propOf(edges, automaton[field]);
+                    if (edges !== undefined && prop === undefined)
+                        diagnose([...at, "automaton", field], `"automaton" ${field} property "${automaton[field]}" is not a property of "${automaton.edges}"`);
+                    else if (prop !== undefined && !isReference(prop))
+                        diagnose([...at, "automaton", field], `"automaton" ${field} property "${automaton[field]}" is not reference-valued`);
+                }
+                for (const field of ["initial", "final"])
+                    if (nodes !== undefined && propOf(nodes, automaton[field]) === undefined)
+                        diagnose([...at, "automaton", field], `"automaton" ${field} property "${automaton[field]}" is not a property of "${automaton.nodes}"`);
+            }
+            for (const [j, entry] of (object.referenced ?? []).entries()) {
+                /*  a reference coverage entry has to be a single
+                    (usually wildcard) reference expression  */
+                let expr;
                 try {
-                    compileValueExpr(prop.value);
+                    expr = compileValueExpr(entry);
                 }
                 catch (err) {
-                    diagnose([...at, "props", j, "value"], `invalid value expression "${prop.value}": ` +
+                    diagnose([...at, "referenced", j], `invalid "referenced" entry "${entry}": ` +
                         (err instanceof Error ? err.message : String(err)));
                 }
+                if (expr !== undefined && expr.kind !== "reference")
+                    diagnose([...at, "referenced", j], `"referenced" entry "${entry}" is not a single "[[xxx]]" reference`);
             }
             if (depth > 1 && object.name !== undefined) {
                 try {
@@ -74,25 +215,28 @@ const checkConstraints = (config, file, posOfPath) => {
     check(config, [], 1);
     return diagnostics;
 };
-/*  load and validate a YAML schema configuration file  */
-export const loadConfig = (file) => {
+/*  load and validate the YAML schema configuration, merged in order out
+    of its files (the later ones into the earlier ones), where every file
+    has to be readable and syntactically valid on its own, while the
+    merged result alone is validated  */
+export const loadConfig = (files) => {
     const diagnostics = new Array();
-    /*  read the configuration file  */
-    let yaml;
-    try {
-        yaml = fs.readFileSync(file, "utf8");
-    }
-    catch (err) {
-        diagnostics.push({ file, line: 1, column: 1,
-            message: "cannot read configuration file: " +
-                (err instanceof Error ? err.message : String(err)) });
-        return { diagnostics };
-    }
-    /*  syntactically parse the YAML content into its document, keeping
-        the line positions for the diagnostics  */
-    const lines = new LineCounter();
-    const doc = parseDocument(yaml, { lineCounter: lines });
-    if (doc.errors.length > 0) {
+    /*  read and syntactically parse every configuration file into its
+        document, keeping the line positions for the diagnostics  */
+    const docs = new Array();
+    for (const file of files) {
+        let yaml;
+        try {
+            yaml = fs.readFileSync(file, "utf8");
+        }
+        catch (err) {
+            diagnostics.push({ file, line: 1, column: 1, severity: "error",
+                message: "cannot read configuration file: " +
+                    (err instanceof Error ? err.message : String(err)) });
+            continue;
+        }
+        const lines = new LineCounter();
+        const doc = parseDocument(yaml, { lineCounter: lines });
         /*  strip the position and the source snippet the YAML parser
             appends to its message, as the diagnostic carries the
             position itself  */
@@ -101,25 +245,31 @@ export const loadConfig = (file) => {
                 file,
                 line: err.linePos?.[0].line ?? 1,
                 column: err.linePos?.[0].col ?? 1,
+                severity: "error",
                 message: "invalid YAML syntax: " + err.message.replace(/ at line \d+, column \d+(?::\n[\s\S]*)?$/, "")
             });
-        return { diagnostics };
+        if (doc.errors.length === 0)
+            docs.push({ file, doc, lines, raw: doc.toJS() });
     }
-    const obj = doc.toJS();
-    /*  semantically validate against the schema of the configuration  */
-    const posOfPath = (path) => lineColOfPath(doc, lines, path);
+    if (diagnostics.length > 0)
+        return { diagnostics };
+    /*  merge the documents in order  */
+    const obj = docs.map(({ doc }) => doc.toJS())
+        .reduce((target, source) => mergeConfig(target, source));
+    /*  semantically validate the merged result against the schema of the configuration  */
+    const posOfPath = (path) => posOfMergedPath(docs, obj, path);
     const result = v.safeParse(Schema, obj);
     if (!result.success) {
         for (const issue of result.issues) {
-            const path = (issue.path ?? []).map((item) => item.key);
-            const pos = posOfPath(path);
+            /*  the path is rendered as it is in the positioned file  */
+            const { file, line, column, path } = posOfPath((issue.path ?? []).map((item) => item.key));
             const where = path.length > 0 ? `${path.join(".")}: ` : "";
-            diagnostics.push({ file, line: pos.line, column: pos.column,
+            diagnostics.push({ file, line, column, severity: "error",
                 message: `invalid configuration: ${where}${issue.message}` });
         }
         return { diagnostics };
     }
     /*  check the constraints beyond the structural schema  */
-    diagnostics.push(...checkConstraints(result.output, file, posOfPath));
+    diagnostics.push(...checkConstraints(result.output, posOfPath));
     return { config: diagnostics.length === 0 ? result.output : undefined, diagnostics };
 };

package/dst/specbook-diagnostic.d.ts

@@ -1,7 +1,9 @@
+export type DiagnosticSeverity = "error" | "warning";
 export interface Diagnostic {
     file: string;
     line: number;
     column: number;
+    severity: DiagnosticSeverity;
     message: string;
 }
 export declare const renderDiagnostic: (diagnostic: Diagnostic) => string;

package/dst/specbook-diagnostic.js

@@ -5,8 +5,10 @@
 */
 import * as fs from "node:fs";
 import sourceCodeError from "source-code-error";
+/*  render the message of a diagnostic, qualifying a warning as such  */
+const renderMessage = (diagnostic) => diagnostic.severity === "warning" ? `warning: ${diagnostic.message}` : diagnostic.message;
 /*  render a diagnostic as a standard single-line message  */
-export const renderDiagnostic = (diagnostic) => `${diagnostic.file}:${diagnostic.line}:${diagnostic.column}: ${diagnostic.message}`;
+export const renderDiagnostic = (diagnostic) => `${diagnostic.file}:${diagnostic.line}:${diagnostic.column}: ${renderMessage(diagnostic)}`;
 /*  render a diagnostic as a multi-line message with the affected
     source snippet, falling back to the single-line message when the
     source file is unreadable (e.g. the file is a directory) or empty
@@ -21,6 +23,6 @@ export const renderDiagnosticVerbose = (diagnostic, colors = false) => {
     }
     if (code === "")
         return `${renderDiagnostic(diagnostic)}\n`;
-    return sourceCodeError({ message: diagnostic.message, filename: diagnostic.file,
+    return sourceCodeError({ message: renderMessage(diagnostic), filename: diagnostic.file,
         code, line: diagnostic.line, column: diagnostic.column, colors });
 };

package/dst/specbook-diagram.d.ts

@@ -8,6 +8,7 @@ export interface DiagramError {
 export interface DiagramResult {
     spec?: string;
     config?: SchemaDiagram["config"];
+    columns?: number;
     errors: DiagramError[];
 }
 export declare const specDiagrams: (specification: Spec, config: Schema) => Map<SpecObject, DiagramResult>;

package/dst/specbook-export-ast.js

@@ -7,6 +7,7 @@ import JSON5 from "json5";
 import { stringify as stringifyYaml } from "yaml";
 import { encode as encodeToon } from "@toon-format/toon";
 import { specDiagrams } from "./specbook-diagram.js";
+import { isTitleObject } from "./specbook-export-common.js";
 /*  render the specification AST into a serialization format  */
 export const renderAst = (specification, format, config) => {
     /*  reduce the specification to plain JSON values (ISO date strings)  */
@@ -14,12 +15,13 @@ export const renderAst = (specification, format, config) => {
     /*  attach the Gradia specs of the diagram-configured objects as
         "diagram" fields onto the corresponding plain object nodes
         (an invalid diagram situation omits the diagram, as it is
-        already reported as a lint diagnostic)  */
+        already reported as a lint diagnostic, and the diagram of
+        the title object is reserved for the HTML/PDF export)  */
     if (config !== undefined) {
         const diagrams = specDiagrams(specification, config);
         const walk = (object, node) => {
             const result = diagrams.get(object);
-            if (result?.spec !== undefined)
+            if (result?.spec !== undefined && !isTitleObject(object))
                 node.diagram = result.spec;
             object.childs.forEach((child, i) => walk(child, node.childs[i]));
         };

package/dst/specbook-export-common.js

@@ -117,9 +117,11 @@ export const charsetCodepoints = (charset) => {
 };
 /*  the symbol glyphs used by the HTML/PDF rendering (kind and property
     bullets, link symbol, primary marker, theme switch icon, anchor
-    symbol plus its text presentation variation selector, and the
-    search field clearing icon)  */
-const symbolGlyphs = [0x25CF, 0x25CB, 0x26AD, 0x2318, 0x25D0, 0x2693, 0xFE0E, 0x00D7];
+    symbol plus its text presentation variation selector, the search
+    field clearing icon, the active entry pointer of the table of
+    contents side panel, and the title path segment pointer of the
+    description popups)  */
+const symbolGlyphs = [0x25CF, 0x25CB, 0x26AD, 0x2318, 0x25D0, 0x2693, 0xFE0E, 0x00D7, 0x25C0, 0x25B7];
 /*  the typographic glyphs producible by the smart typography rendering
     (language-specific quotes, dashes, ellipsis, bullet, nbsp)  */
 const typographyGlyphs = [

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

@@ -7,22 +7,41 @@
 /*  the client-side fuzzy search over the rendered specification: the
     whitespace-separated words of a comma-separated query part are
     (fuzzy) matched and AND-combined, while the parts are OR-combined;
-    a match keeps its complete paragraph or table row, plus the table
-    header and the headings of all enclosing objects, and every
-    matched word is highlighted with a <mark> element  */
+    a match keeps its complete paragraph, table row, or diagram, plus
+    the table header and the headings of all enclosing objects, and
+    every matched word is highlighted with a <mark> element (an SVG
+    <tspan> element underlaid with a <rect> inside a diagram), while
+    the table of contents (page and side panel) is filtered along  */
 (function () {
-    const input = document.getElementById("search-input")
-    const clear = document.getElementById("search-clear")
-    if (input === null || clear === null)
+    const tab    = document.getElementById("search")
+    const toggle = document.getElementById("search-toggle")
+    const input  = document.getElementById("search-input")
+    const clear  = document.getElementById("search-clear")
+    if (tab === null || toggle === null || input === null || clear === null)
         return
 
+    /*  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"))
+            input.focus()
+        else
+            input.blur()
+        try { localStorage.setItem("specbook-search", tab.classList.contains("open") ? "open" : "closed") }
+        catch { /*  an inaccessible storage just loses the state  */ }
+    }
+    try { if (localStorage.getItem("specbook-search") === "open") tab.classList.add("open") }
+    catch { /*  an inaccessible storage just means no stored state  */ }
+    toggle.addEventListener("click", () => { slide() })
+
     /*  shortest word still eligible for fuzzy matching: below it the
         edit distance would equate it with almost any short word  */
     const fuzzyMin = 4
 
-    /*  the searchable units (paragraphs, list items, table rows, and
-        headings), the corpus vocabulary, and the per-word cache of the
-        fuzzy-equivalent vocabulary words  */
+    /*  the searchable units (paragraphs, list items, table rows,
+        headings, and diagrams), the corpus vocabulary, and the per-word
+        cache of the fuzzy-equivalent vocabulary words  */
     const units = []
     const vocab = new Set()
     const fuzzy = new Map()
@@ -30,14 +49,16 @@
 
     /*  fill the unit and vocabulary indices once on first use: a unit
         is an outermost paragraph-level element within an article, i.e.
-        one not nested inside another unit (like a paragraph in a table
-        cell, which is covered by its table row)  */
+        one not nested inside another unit (like a paragraph or diagram
+        in a table cell, which is covered by its table row), where a
+        diagram is searched by its SVG text labels, joined by spaces,
+        as its raw text content would run them together  */
     const index = () => {
         if (indexed)
             return
         indexed = true
         document.querySelectorAll("article").forEach((article) => {
-            article.querySelectorAll("p, li, tr, pre, blockquote, h1, h2, h3, h4, h5, h6")
+            article.querySelectorAll("p, li, tr, pre, blockquote, h1, h2, h3, h4, h5, h6, div.diagram")
                 .forEach((el) => {
                     let parent = el.parentElement
                     while (parent !== null && parent.tagName !== "ARTICLE") {
@@ -45,7 +66,9 @@
                             return
                         parent = parent.parentElement
                     }
-                    const text  = (el.textContent ?? "").toLowerCase()
+                    const text  = (el.classList.contains("diagram") ?
+                        Array.from(el.querySelectorAll("text")).map((t) => t.textContent ?? "").join(" ") :
+                        (el.textContent ?? "")).toLowerCase()
                     const words = new Set(text.split(/[^\p{L}\p{N}]+/u).filter((w) => w !== ""))
                     words.forEach((w) => { vocab.add(w) })
                     units.push({ el, text, words, keep: false })
@@ -138,16 +161,27 @@
         return new RegExp(alts.map((alt) => alt.src).join("|"), "giu")
     }
 
-    /*  wrap every match in the text nodes of a unit into a <mark>;
-        walking the text nodes (instead of replacing in the raw HTML)
-        keeps the tags and attributes untouched  */
+    /*  wrap every match in the text nodes of a unit into a <mark>, or
+        into a <tspan> inside the SVG text labels of a diagram (as a
+        foreign <mark> renders nothing there), leaving all other SVG
+        text nodes (like an embedded font style) untouched; walking the
+        text nodes (instead of replacing in the raw HTML) keeps the tags
+        and attributes untouched  */
+    const svgNS = "http://www.w3.org/2000/svg"
     const highlight = (el, regex) => {
         const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT)
         const nodes  = []
         let node
         while ((node = walker.nextNode()) !== null)
             nodes.push(node)
+        const spans = []
         nodes.forEach((text) => {
+            const parent = text.parentNode
+            if (parent === null)
+                return
+            const svg = parent.namespaceURI === svgNS
+            if (svg && !/^(text|tspan)$/.test(parent.localName))
+                return
             const value = text.nodeValue ?? ""
             const frag  = document.createDocumentFragment()
             let last = 0
@@ -156,26 +190,49 @@
             while ((m = regex.exec(value)) !== null) {
                 if (m.index > last)
                     frag.appendChild(document.createTextNode(value.slice(last, m.index)))
-                const mark = document.createElement("mark")
-                mark.className   = "search-hit"
+                const mark = svg ?
+                    document.createElementNS(svgNS, "tspan") :
+                    document.createElement("mark")
+                mark.classList.add("search-hit")
                 mark.textContent = m[0]
                 frag.appendChild(mark)
+                if (svg)
+                    spans.push(mark)
                 last = m.index + m[0].length
             }
             if (last === 0)
                 return
             if (last < value.length)
                 frag.appendChild(document.createTextNode(value.slice(last)))
-            if (text.parentNode !== null)
-                text.parentNode.replaceChild(frag, text)
+            parent.replaceChild(frag, text)
+        })
+
+        /*  underlay every <tspan> with a rounded <rect> (placed below
+            its <text> label, padded and rounded relative to the label
+            height like a <mark>), as SVG text has no background of its
+            own; all extents are measured up-front, as every insertion
+            would invalidate the layout again  */
+        const boxes = spans.map((span) => span.getBBox())
+        spans.forEach((span, i) => {
+            const label = span.closest("text")
+            const box   = boxes[i]
+            const pad   = box.height * 0.1
+            const rect  = document.createElementNS(svgNS, "rect")
+            rect.classList.add("search-hit")
+            rect.setAttribute("x",      String(box.x - pad))
+            rect.setAttribute("y",      String(box.y))
+            rect.setAttribute("width",  String(box.width + 2 * pad))
+            rect.setAttribute("height", String(box.height))
+            rect.setAttribute("rx",     String(box.height * 0.2))
+            label.parentNode.insertBefore(rect, label)
         })
     }
 
-    /*  undo a previous search: unwrap the injected <mark> elements
-        (re-normalizing the fragmented text nodes), drop the filtering
-        classes, and leave the search mode  */
+    /*  undo a previous search: unwrap the injected <mark>, <tspan>,
+        and <rect> elements (re-normalizing the fragmented text nodes),
+        drop the filtering classes, and leave the search mode  */
     const unmark = () => {
-        document.querySelectorAll("mark.search-hit").forEach((mark) => {
+        document.querySelectorAll(".search-hit").forEach((mark) => {
             const parent = mark.parentNode
             while (mark.firstChild !== null)
                 parent.insertBefore(mark.firstChild, mark)
@@ -252,19 +309,50 @@
             if (unit.el.classList.contains("search-keep"))
                 highlight(unit.el, regex)
         })
+
+        /*  filter the table of contents (its page rows and its side
+            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  */
+        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")
+        })
     }
 
-    /*  run the search debounced on every keystroke and let the "X"
-        clear the input field and the search results again  */
+    /*  run the search debounced on every keystroke (750ms after the
+        last one, as re-filtering the whole document is not cheap), let
+        the "X" clear the input field and the search results again, let
+        the Escape key additionally slide the input field back in, and
+        let the Enter key slide it back in with the query kept (and
+        applied immediately)  */
     let debounce = 0
+    const reset = () => {
+        window.clearTimeout(debounce)
+        input.value = ""
+        unmark()
+    }
     input.addEventListener("input", () => {
         window.clearTimeout(debounce)
-        debounce = window.setTimeout(search, 200)
+        debounce = window.setTimeout(search, 750)
+    })
+    input.addEventListener("keydown", (event) => {
+        if (event.key === "Escape")
+            reset()
+        else if (event.key === "Enter") {
+            window.clearTimeout(debounce)
+            search()
+        }
+        else
+            return
+        slide(false)
     })
     clear.addEventListener("click", () => {
-        window.clearTimeout(debounce)
-        input.value = ""
-        unmark()
+        reset()
         input.focus()
     })
 })()