npm - @rse/specbook - Versions diffs - 1.0.3 → 1.1.0 - Mend

@rse/specbook 1.0.3 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (40) hide show

package/README.md +106 -19
package/dst/specbook-api.d.ts +29 -9
package/dst/specbook-api.js +108 -33
package/dst/specbook-cli.js +84 -25
package/dst/specbook-cmd-describe.d.ts +7 -1
package/dst/specbook-cmd-describe.js +56 -11
package/dst/specbook-cmd-export.d.ts +2 -1
package/dst/specbook-cmd-export.js +46 -3
package/dst/specbook-cmd-lint.d.ts +2 -1
package/dst/specbook-cmd-lint.js +12 -8
package/dst/specbook-cmd-preview.d.ts +12 -0
package/dst/specbook-cmd-preview.js +57 -0
package/dst/specbook-config.d.ts +1 -1
package/dst/specbook-config.js +187 -37
package/dst/specbook-diagnostic.d.ts +2 -0
package/dst/specbook-diagnostic.js +4 -2
package/dst/specbook-diagram.d.ts +1 -0
package/dst/specbook-diagram.js +0 -0
package/dst/specbook-export-ast.js +4 -2
package/dst/specbook-export-common.js +5 -3
package/dst/specbook-export-html-search.js +118 -30
package/dst/specbook-export-html.css +1140 -233
package/dst/specbook-export-html.d.ts +1 -1
package/dst/specbook-export-html.js +764 -120
package/dst/specbook-export-md.js +4 -2
package/dst/specbook-format-schema.d.ts +33 -1
package/dst/specbook-format-schema.js +34 -2
package/dst/specbook-format.md +193 -25
package/dst/specbook-format.yaml +2291 -299
package/dst/specbook-link.d.ts +2 -1
package/dst/specbook-link.js +43 -3
package/dst/specbook-mcp.js +19 -10
package/dst/specbook-parse-common.d.ts +4 -2
package/dst/specbook-parse-common.js +6 -3
package/dst/specbook-parse-semantic.js +290 -30
package/dst/specbook-parse-syntax.js +3 -1
package/dst/specbook-parse-value.d.ts +1 -0
package/dst/specbook-parse-value.js +17 -3
package/dst/specbook-parse.js +1 -1
package/package.json +14 -6

package/dst/specbook-export-html.js CHANGED Viewed

@@ -50,17 +50,31 @@ const templates = {
                 </script>
             </head>
             <body>
-                <div class="theme-switch" onclick="themeSwitch()" title="switch color theme">&#x25D0;</div>
+                {% if Document.realtime %}<div class="realtime-status disconnected" title="live preview connection"><svg class="realtime-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="M9 8V2"/><path d="M15 8V2"/><path d="M18 8v5a4 4 0 0 1-4 4h-4a4 4 0 0 1-4-4V8Z"/><path d="M12 22v-5"/></svg></div>{% endif %}
+                <div class="theme-switch" onclick="themeSwitch()" title="switch color theme"><svg class="theme-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round"><circle cx="12" cy="12" r="8.5"/><path d="M12 3.5 A 8.5 8.5 0 0 0 12 20.5 Z" fill="currentColor" stroke="none"/></svg></div>
+                {% if Document.info %}<div class="info-switch" title="toggle description popups"><svg class="info-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round"><circle cx="12" cy="12" r="8.5"/><line x1="12" y1="11" x2="12" y2="16"/><line x1="12" y1="7.75" x2="12.01" y2="7.75"/></svg></div>{% endif %}
+                <div class="search" id="search">
+                    <div class="search-toggle" id="search-toggle" title="toggle search field"><svg class="search-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round"><circle cx="10" cy="10" r="6.5"/><line x1="15" y1="15" x2="21" y2="21"/></svg></div>
+                    <div class="search-field">
+                        <input type="text" id="search-input" placeholder="Search&hellip;" autocomplete="off" spellcheck="false"/>
+                        <span class="search-clear" id="search-clear" title="clear search">&#x00D7;</span>
+                    </div>
+                </div>
+                {{ Document.tocpanel }}
                 {{ Document.titlepage }}
                 {{ Document.toc }}
+                {{ Document.doc }}
                 {{ Document.artifacts }}
                 {% if Document.search %}<script>{{ Document.search }}</script>{% endif %}
+                {% if Document.tocpanel %}<script>{{ Document.tocscript }}</script>{% endif %}
+                {% if Document.info %}<script>{{ Document.info }}</script>{% endif %}
+                {% if Document.realtime %}<script class="realtime">{{ Document.realtime }}</script>{% endif %}
             </body>
         </html>
     `,
     /*  <TitlePage/>  */
     "TitlePage": textframe `
-        <div class="titlepage">
+        <div class="titlepage" id="titlepage">
             {% if TitlePage.logo %}<div class="logo">{{ TitlePage.logo }}</div>{% endif %}
             <div class="title">{{ TitlePage.title }}</div>
             {% if TitlePage.subtitle %}<div class="subtitle">{{ TitlePage.subtitle }}</div>{% endif %}
@@ -72,23 +86,48 @@ const templates = {
             </table>
             {{ TitlePage.description }}
             {{ TitlePage.properties }}
-            <div class="search">
-                <input type="text" id="search-input" placeholder="Search&hellip;" autocomplete="off" spellcheck="false"/>
-                <span class="search-clear" id="search-clear" title="clear search">&#x00D7;</span>
-            </div>
         </div>
     `,
     /*  <Toc/>  */
     "Toc": textframe `
-        <nav class="toc">
+        <nav class="toc" id="toc">
             <h1>Table of Contents</h1>
             <table>
                 {% for entry in Toc.entries %}
-                <tr><td><a href="#{{ entry.id }}"><span class="object-kind">{{ entry.kind }}:</span> {{ entry.name }} <span class="link-symbol">&#x26AD;</span></a></td>{% if entry.page %}<td class="page"><a href="#{{ entry.id }}">{{ entry.page }}</a></td>{% endif %}</tr>
+                <tr class="level-{{ entry.level }}"><td><a href="#{{ entry.id }}"><span class="object-kind"{% if entry.info %} data-info="{{ entry.info }}" data-info-path="{{ entry.infopath }}"{% endif %}>{{ entry.kind }}:</span> <span class="object-name"{% if entry.spec %} data-info-spec="{{ entry.spec }}" data-info-path="{{ entry.specpath }}"{% endif %}>{{ entry.name }}</span> <span class="link-symbol">&#x26AD;</span></a></td>{% if entry.page %}<td class="page"><a href="#{{ entry.id }}">{{ entry.page }}</a></td>{% endif %}</tr>
                 {% endfor %}
             </table>
         </nav>
     `,
+    /*  <TocPanel/>  */
+    "TocPanel": textframe `
+        <nav class="toc-panel">
+            <div class="toc-tab" title="toggle table of contents"><svg class="toc-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round"><line x1="3" y1="6" x2="21" y2="6"/><line x1="3" y1="12" x2="21" y2="12"/><line x1="3" y1="18" x2="21" y2="18"/></svg></div>
+            <div class="toc-list">
+                <ul class="extra">
+                    {% if TocPanel.title %}<li><a href="#titlepage"><span class="entry">Title</span></a></li>{% endif %}
+                    <li><a href="#toc"><span class="entry">Table of Contents</span></a></li>
+                    {% if TocPanel.doc %}<li><a href="#doc"><span class="entry">Diagram of Contents</span></a></li>{% endif %}
+                </ul>
+                {{ TocPanel.entries }}
+            </div>
+        </nav>
+    `,
+    /*  <TocPanelEntries/>  */
+    "TocPanelEntries": textframe `
+        <ul>
+            {% for entry in Entries %}
+            <li><a href="#{{ entry.id }}"><span class="entry"><span class="object-kind"{% if entry.info %} data-info="{{ entry.info }}" data-info-path="{{ entry.infopath }}"{% endif %}>{{ entry.kind }}:</span> <span class="object-name"{% if entry.spec %} data-info-spec="{{ entry.spec }}" data-info-path="{{ entry.specpath }}"{% endif %}>{{ entry.name }}</span></span></a>{{ entry.childs }}</li>
+            {% endfor %}
+        </ul>
+    `,
+    /*  <Doc/>  */
+    "Doc": textframe `
+        <nav class="doc" id="doc">
+            <h1>Diagram of Contents</h1>
+            <div class="diagram">{{ Doc.diagram }}</div>
+        </nav>
+    `,
     /*  <Artifact/>  */
     "Artifact": textframe `
         <article>
@@ -98,7 +137,7 @@ const templates = {
     /*  <Object/>  */
     "Object": textframe `
         <section>
-            <h{{ Object.level }} id="{{ Object.id }}"><span class="object-kind">{{ Object.kind }}:</span> {{ Object.name }}{% if Object.primary %} <span class="primary-marker">&#x2318;</span>{% endif %}{% if Object.paren %} <span class="anchor-paren">({{ Object.paren }})</span>{% endif %} <a href="#{{ Object.id }}"><span class="anchor-symbol">&#x2693;&#xFE0E;</span></a></h{{ Object.level }}>
+            <h{{ Object.level }} id="{{ Object.id }}"><span class="object-kind"{% if Object.info %} data-info="{{ Object.info }}" data-info-path="{{ Object.infopath }}"{% endif %}>{{ Object.kind }}:</span> <span class="object-name"{% if Object.spec %} data-info-spec="{{ Object.spec }}" data-info-path="{{ Object.specpath }}"{% endif %}>{{ Object.name }}</span>{% if Object.primary %} <span class="primary-marker">&#x2318;</span>{% endif %}{% if Object.paren %} <span class="anchor-paren">({{ Object.paren }})</span>{% endif %} <a href="#{{ Object.id }}"><span class="anchor-symbol">&#x2693;&#xFE0E;</span></a></h{{ Object.level }}>
             {{ Object.diagram }}
             {{ Object.properties }}
             {{ Object.description }}
@@ -109,7 +148,7 @@ const templates = {
     "Properties": textframe `
         <table class="props">
             {% for property in Properties %}
-            <tr><td class="key property-name">{{ property.key }}</td><td>{{ property.value }}</td></tr>
+            <tr><td class="key property-name"><span{% if property.info %} data-info="{{ property.info }}" data-info-path="{{ property.infopath }}" data-info-prop="{{ property.key }}"{% endif %}>{{ property.key }}</span></td><td>{{ property.value }}</td></tr>
             {% endfor %}
         </table>
     `,
@@ -131,15 +170,15 @@ const templates = {
         <table class="objects">
             <thead>
                 <tr>
-                    <th class="object-kind">{{ Table.head }}</th>
-                    {%- for key in Table.keys %}<th class="property-name">{{ key }}</th>{% endfor %}
+                    <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 %}
                 </tr>
             </thead>
             <tbody>
                 {% for row in Table.rows %}
-                <tr id="{{ row.id }}">
-                    <td>{{ row.name }}{% 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>
+                <tr id="{{ row.id }}"{% if row.even %} class="even"{% endif %}>
+                    <td><span{% if row.spec %} data-info-spec="{{ row.spec }}" data-info-path="{{ row.specpath }}"{% 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>
                     {%- for value in row.values %}<td>{{ value }}</td>{% endfor %}
                     {%- if Table.desc %}<td>{{ row.description }}</td>{% endif %}
                 </tr>
@@ -152,18 +191,18 @@ const templates = {
         <table class="objects">
             <thead>
                 <tr>
-                    <th class="object-kind" style="width: {{ Table.width }}%">{{ Table.head }}</th>
+                    <th class="object-kind" style="width: {{ Table.width }}%"><span{% if Table.info %} data-info="{{ Table.info }}" data-info-path="{{ Table.infopath }}"{% endif %}>{{ Table.head }}</span></th>
                     <th class="description">Properties</th>
                 </tr>
             </thead>
             <tbody>
                 {% for row in Table.rows %}
-                <tr id="{{ row.id }}">
-                    <td>{{ row.name }}{% 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>
+                <tr id="{{ row.id }}"{% if row.even %} class="even"{% endif %}>
+                    <td><span{% if row.spec %} data-info-spec="{{ row.spec }}" data-info-path="{{ row.specpath }}"{% 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">
                             {% 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 %}>{{ cell.key }}</th>{% endfor %}</tr>
+                            <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.specpath }}" 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>
                             {% endfor %}
                         </table>
@@ -174,6 +213,368 @@ const templates = {
         </table>
     `
 };
+/*  the client-side script of the live preview: it connects back to the
+    own page over WebSocket (the URL scheme "http"/"https" replaced with
+    "ws"/"wss"), re-connects every second after a lost connection, and
+    updates the page on a received "RELOAD" command as well as on every
+    re-established connection (as the server was restarted meanwhile).
+    The update fetches the fresh page and replaces the document in place
+    -- instead of reloading the page -- so the scroll position and the
+    theme choice survive: the title, the stylesheet (if changed), and
+    the body are swapped, and the scripts of the fresh body re-executed
+    through clones (as parsed scripts never execute), except this
+    realtime script itself, whose connection stays alive. The status
+    icon (re-created by every body swap) reflects the connection state
+    and blinks for 2s after every update, unless the connection is
+    lost meanwhile  */
+const realtimeScript = textframe `
+    (function () {
+        const url = window.location.protocol.replace(/^http/, "ws") + "//" +
+            window.location.host + window.location.pathname
+        const status = (state) => {
+            const icon = document.querySelector("div.realtime-status")
+            if (icon !== null)
+                icon.className = "realtime-status " + state
+        }
+        let blink = 0
+        const update = async () => {
+            const response = await fetch(window.location.pathname, { cache: "no-store" })
+            if (!response.ok)
+                return
+            const doc = new DOMParser().parseFromString(await response.text(), "text/html")
+            const x = window.scrollX
+            const y = window.scrollY
+            document.title = doc.title
+            const style = document.head.querySelector("style")
+            const fresh = doc.head.querySelector("style")
+            if (style !== null && fresh !== null && style.textContent !== fresh.textContent)
+                style.replaceWith(fresh)
+            document.body.replaceWith(doc.body)
+            for (const script of document.body.querySelectorAll("script:not(.realtime)")) {
+                const clone = document.createElement("script")
+                clone.textContent = script.textContent
+                script.replaceWith(clone)
+            }
+            window.scrollTo(x, y)
+            status("reloaded")
+            clearTimeout(blink)
+            blink = setTimeout(() => { status("connected") }, 2000)
+        }
+        let lost = false
+        const connect = () => {
+            const ws = new WebSocket(url)
+            ws.onopen = () => {
+                status("connected")
+                if (lost) {
+                    console.log("specbook: live preview connection re-established")
+                    lost = false
+                    update()
+                }
+            }
+            ws.onmessage = (event) => {
+                if (event.data === "RELOAD")
+                    update()
+            }
+            ws.onclose = () => {
+                clearTimeout(blink)
+                status("disconnected")
+                if (!lost)
+                    console.log("specbook: live preview connection lost")
+                lost = true
+                setTimeout(connect, 1000)
+            }
+        }
+        connect()
+    })()
+`;
+/*  the client-side script of the table of contents side panel: it
+    slides the panel out of and back into the viewport edge (closing it
+    also on a jump, on "Escape", and on a click outside), remembers the
+    open state across page loads, and marks the active entry (the first
+    heading visible in the viewport, or, without any, the last heading
+    above the viewport, i.e. the section scrolled into), scrolling it
+    into the middle of the panel whenever it changes and is not visible
+    in the panel already (even while the panel is slid in, so it opens
+    at the right position), plus the anchored entry (the one the URL
+    hash currently addresses, which a jump synchronizes with the active
+    one, while a subsequent scrolling moves the active one only). The
+    script runs at the end of the body, as the headings it targets
+    have to exist already, and a live preview body swap replaces the
+    body-bound listeners along with the panel, while the document- and
+    window-bound ones (the outside click, as the body does not span
+    the viewport margins, plus scroll and hash change) retire
+    themselves  */
+const tocPanelScript = textframe `
+    (function () {
+        const panel   = document.querySelector("nav.toc-panel")
+        const list    = panel.querySelector("div.toc-list")
+        const links   = Array.from(panel.querySelectorAll("a"))
+        const targets = links.map((a) => document.getElementById(decodeURIComponent(a.hash.slice(1))))
+        let active = null
+        const reveal = () => {
+            const top = active.getBoundingClientRect().top - list.getBoundingClientRect().top
+            if (top < 0 || top + active.offsetHeight > list.clientHeight)
+                list.scrollTop += top - (list.clientHeight - active.offsetHeight) / 2
+        }
+        const spy = () => {
+            if (!panel.isConnected) {
+                window.removeEventListener("scroll", spy)
+                return
+            }
+            let current = null
+            for (let i = 0; i < targets.length; i++) {
+                if (targets[i] === null)
+                    continue
+                const top = targets[i].getBoundingClientRect().top
+                if (top >= -1 && top < window.innerHeight) {
+                    current = links[i]
+                    break
+                }
+                if (top < -1)
+                    current = links[i]
+            }
+            if (current === active)
+                return
+            if (active !== null)
+                active.classList.remove("active")
+            active = current
+            if (active !== null) {
+                active.classList.add("active")
+                reveal()
+            }
+        }
+        let anchored = null
+        const anchor = () => {
+            if (!panel.isConnected) {
+                window.removeEventListener("hashchange", anchor)
+                return
+            }
+            const current = links.find((a) => a.hash === window.location.hash) ?? null
+            if (current === anchored)
+                return
+            if (anchored !== null)
+                anchored.classList.remove("anchored")
+            anchored = current
+            if (anchored !== null)
+                anchored.classList.add("anchored")
+        }
+        const toggle = (open) => {
+            panel.classList.toggle("open", open)
+            try { localStorage.setItem("specbook-toc", panel.classList.contains("open") ? "open" : "closed") }
+            catch { /*  an inaccessible storage just loses the state  */ }
+        }
+        try { if (localStorage.getItem("specbook-toc") === "open") panel.classList.add("open") }
+        catch { /*  an inaccessible storage just means no stored state  */ }
+        panel.querySelector("div.toc-tab").addEventListener("click", () => { toggle() })
+        links.forEach((a) => { a.addEventListener("click", () => { toggle(false) }) })
+        document.body.addEventListener("keydown", (event) => { if (event.key === "Escape") toggle(false) })
+        const outside = (event) => {
+            if (!panel.isConnected)
+                document.removeEventListener("click", outside)
+            else if (!panel.contains(event.target)
+                && event.target.closest("div.search")          === null
+                && event.target.closest("div.theme-switch")    === null
+                && event.target.closest("div.info-switch")     === null
+                && event.target.closest("div.realtime-status") === null)
+                toggle(false)
+        }
+        document.addEventListener("click", outside)
+        window.addEventListener("scroll", spy, { passive: true })
+        window.addEventListener("hashchange", anchor)
+        spy()
+        anchor()
+    })()
+`;
+/*  the client-side script of the description popups: the info tab
+    toggles the popups on and off (default), persisting the choice
+    across page loads, and while they are on, hovering an element
+    carrying a "data-info" key shows the schema description of its
+    object kind (or, with "data-info-prop", of its property), while
+    hovering an element carrying a "data-info-spec" key (an object
+    name) shows the corpus description of the object instance, in a
+    single shared popup -- a hovered diagram node box resolves through
+    its hyperlinked object anchor to the instance popup attributes of
+    the object's heading name or table row name -- opened only after
+    the mouse rested 400ms on the element (so mere mouse movements
+    across the page pop nothing up), titled with the "data-info-path"
+    object path (one filled-circle "KIND: Name" segment per level,
+    arbitrarily deep and separated by the icons alone, ending for
+    a kind in the bare kind and extended for a property with the
+    not-filled-circle property name, styled as in the document
+    content: the kinds and the property bold in the path color, the
+    names bold in the description color)
+    and fed from the injected INFO
+    map of pre-rendered schema description HTML or SPEC map of
+    pre-rendered corpus description HTML (a missing entry pops up
+    the title path alone), the description led by a bold "Schema:"
+    or "Specification:" label naming its origin (a corpus-fed
+    instance popup additionally carrying the page background colors
+    instead of the accent), where the popup is
+    capped at 40% viewport width and attached above or below the
+    hovered element, whichever side offers more viewport space; the
+    script runs at the end of the body, so a live preview body swap
+    replaces the popup element and the body-bound listeners along
+    with the re-executed script  */
+const infoPopupScript = textframe `
+    (function (INFO, SPEC) {
+        const popup = document.createElement("div")
+        popup.className = "info-popup"
+        document.body.appendChild(popup)
+        let enabled = false
+        try { enabled = localStorage.getItem("specbook-info") === "on" }
+        catch { /*  an inaccessible storage just means no stored choice  */ }
+        let current   = null
+        let pending   = null
+        let pendingId = 0
+        const cancel = () => {
+            clearTimeout(pendingId)
+            pending = null
+        }
+        const hide = () => {
+            popup.classList.remove("open")
+            current = null
+        }
+        const apply = () => {
+            document.body.classList.toggle("info-on", enabled)
+            if (!enabled) {
+                cancel()
+                hide()
+            }
+        }
+        apply()
+        document.querySelector("div.info-switch").addEventListener("click", () => {
+            enabled = !enabled
+            try { localStorage.setItem("specbook-info", enabled ? "on" : "off") }
+            catch { /*  an inaccessible storage just loses the choice  */ }
+            apply()
+        })
+        const show = (el) => {
+            /*  a diagram node box carries no popup attributes itself, but
+                hyperlinks its object, whose heading name or table row name
+                carries the instance popup attributes  */
+            let source = el
+            if (!el.hasAttribute("data-info") && !el.hasAttribute("data-info-spec")) {
+                const target = document.getElementById(
+                    decodeURIComponent((el.getAttribute("href") ?? "").replace(/^#/, "")))
+                source = target === null ? null :
+                    (target.hasAttribute("data-info-spec") ? target : target.querySelector("[data-info-spec]"))
+                if (source === null)
+                    return
+            }
+            current = el
+            const key   = source.getAttribute("data-info")
+            const spec  = source.getAttribute("data-info-spec")
+            const prop  = source.getAttribute("data-info-prop")
+            popup.classList.toggle("spec", spec !== null)
+            const title = document.createElement("div")
+            title.className = "info-title"
+            /*  create a pointer, separating the title path segments  */
+            const pointer = () => {
+                const span = document.createElement("span")
+                span.className = "info-pointer"
+                span.textContent = "▷"
+                return span
+            }
+            const segments = (source.getAttribute("data-info-path") ?? key ?? spec).split(" . ")
+            for (const [ i, segment ] of segments.entries()) {
+                if (i > 0)
+                    title.appendChild(pointer())
+                const path = document.createElement("span")
+                path.className = "info-object"
+                /*  a segment renders as in the document content (the kind
+                    bold in the path color, the name semi-bold in the
+                    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) {
+                    const kind = document.createElement("span")
+                    kind.className = "info-kind"
+                    kind.textContent = m !== null ? m[1] + ":" : segment
+                    path.appendChild(kind)
+                    if (m !== null) {
+                        name.textContent = m[2]
+                        path.append(" ", name)
+                    }
+                }
+                else {
+                    name.textContent = segment
+                    path.appendChild(name)
+                }
+                title.appendChild(path)
+            }
+            if (prop !== null) {
+                title.appendChild(pointer())
+                const name = document.createElement("span")
+                name.className = "info-property"
+                name.textContent = prop
+                title.appendChild(name)
+            }
+            popup.replaceChildren(title)
+            const entry = INFO[key]
+            const desc  = prop !== null ? entry?.p?.[prop] :
+                (spec !== null ? SPEC[spec] : entry?.d)
+            if (desc !== undefined) {
+                const text = document.createElement("div")
+                text.className = "info-desc"
+                text.innerHTML = desc
+                /*  the origin label leads the description inline, so it is
+                    hoisted into the leading paragraph (if there is one),
+                    with its prefix word in a span of its own for the
+                    rounded box styling  */
+                const label = document.createElement("strong")
+                label.className = "info-label"
+                const origin = document.createElement("span")
+                origin.className = "info-origin"
+                origin.textContent = spec !== null ? "Specification" : "Schema"
+                label.append(origin, " ")
+                const lead = text.firstElementChild
+                if (lead !== null && lead.tagName === "P")
+                    lead.insertBefore(label, lead.firstChild)
+                else
+                    text.insertBefore(label, text.firstChild)
+                popup.appendChild(text)
+            }
+            /*  measure the popup at the viewport origin first, as a
+                position near the right or bottom edge would clamp it  */
+            popup.style.left = "0px"
+            popup.style.top  = "0px"
+            popup.classList.add("open")
+            const rect  = el.getBoundingClientRect()
+            const left  = Math.max(8, Math.min(rect.left, window.innerWidth - popup.offsetWidth - 8))
+            const above = rect.top > window.innerHeight - rect.bottom
+            popup.style.left = left + "px"
+            popup.style.top  = (above ? rect.top - popup.offsetHeight - 6 : rect.bottom + 6) + "px"
+        }
+        const targets = "[data-info], [data-info-spec], div.diagram a"
+        document.body.addEventListener("mouseover", (event) => {
+            if (!enabled)
+                return
+            const el = event.target.closest(targets)
+            if (el === null || el === current || el === pending)
+                return
+            cancel()
+            pending   = el
+            pendingId = setTimeout(() => { pending = null; show(el) }, 400)
+        })
+        document.body.addEventListener("mouseout", (event) => {
+            const el = event.target.closest(targets)
+            if (el === null || (event.relatedTarget instanceof Node && el.contains(event.relatedTarget)))
+                return
+            if (el === pending)
+                cancel()
+            if (el === current)
+                hide()
+        })
+    })(@INFO@, @SPEC@)
+`;
 /*  ==== Rendering ====  */
 /*  the per-language double quote styles for the smart typography
     (single quotes stay curly, as smartypants cannot distinguish a
@@ -230,24 +631,105 @@ const safe = (html) => new nunjucks.runtime.SafeString(html);
 /*  render one of the built-in Nunjucks templates with a context  */
 const render = (name, context) => env.renderString(templates[name], context);
 /*  the active per-document reference expander, fully-qualified
-    anchor paths, enum/tags property value kinds, object schema nodes,
-    and pre-rendered diagram SVGs (all set during HTML rendering)  */
+    anchor paths, member-carrying property value constraints, object
+    schema nodes, pre-rendered diagram SVGs, description popup keys
+    of the schema nodes, and object parents of the description popup
+    title paths (all set during HTML rendering)  */
 let linker = null;
 let anchors = null;
 let members = null;
 let schemas = null;
 let diagrams = null;
+let infoKeys = null;
+let infoParents = null;
+/*  the object whose texts are currently rendered, scoping the
+    resolution of the references inside them (nearest object wins),
+    established around every object rendering and restored afterwards  */
+let scope = null;
+const scoped = (object, render) => {
+    const outer = scope;
+    scope = object;
+    try {
+        return render();
+    }
+    finally {
+        scope = outer;
+    }
+};
 /*  the cache of the pre-rendered diagram SVGs, keyed by specification,
     as the PDF export renders the very same document multiple times  */
 const diagramCache = new WeakMap();
 /*  determine the fully-qualified anchor path of an object  */
 const anchorOf = (object) => anchors?.get(object) ?? object.id;
+/*  determine the description popup key of an object (the qualified
+    title path of its schema node)  */
+const infoKeyOf = (object) => {
+    const schema = schemas?.get(object);
+    return schema !== undefined ? infoKeys?.get(schema) : undefined;
+};
+/*  determine the description popup title path of an object: the chain
+    of "KIND: Name" segments from the artifact down to the object
+    (arbitrarily deep), where "named = false" keeps the last segment
+    kind-only, as the kind popups (and the group headers of the compact
+    tables) describe the object class instead of the single instance  */
+const infoPathOf = (object, named = true) => {
+    const parent = infoParents?.get(object);
+    const prefix = parent !== undefined ? `${infoPathOf(parent)} . ` : "";
+    const name = named ? plainText(object.name).trim() : "";
+    const segment = name !== "" && object.kind !== "" ? `${object.kind}: ${name}` :
+        (name !== "" ? name : object.kind);
+    return prefix + segment;
+};
+/*  render the schema description popup key and kind-ending title path
+    of an object as "data-info" attributes for the manually assembled
+    hyperlink markup (the kind popup of the full hyperlinks)  */
+const infoAttr = (object) => {
+    const key = infoKeyOf(object);
+    return key !== undefined ?
+        ` data-info="${escapeHtml(key)}" data-info-path="${escapeHtml(infoPathOf(object, false))}"` : "";
+};
+/*  render the corpus description popup key (the fully-qualified anchor
+    path) and name-ending title path of an object as "data-info-spec"
+    attributes for the manually assembled hyperlink markup (the
+    instance popup of the compact and full hyperlinks)  */
+const specAttr = (object) => infoParents !== null ?
+    ` data-info-spec="${escapeHtml(anchorOf(object))}" data-info-path="${escapeHtml(infoPathOf(object))}"` : "";
+/*  collect the description popup map and the qualified title paths of
+    the schema nodes (the artifact kind leading its name, the nested
+    kinds appended), with the description Markdown of the objects and
+    properties pre-rendered to HTML  */
+const collectInfo = (nodes, prefix, keys, info) => {
+    for (const schema of nodes) {
+        const path = prefix !== "" ? `${prefix} . ${schema.kind}` :
+            (schema.name !== undefined ? `${schema.kind}: ${schema.name}` : schema.kind);
+        keys.set(schema, path);
+        const entry = {};
+        if (schema.desc !== undefined)
+            entry.d = marked.parse(schema.desc, { async: false }).trim();
+        for (const property of schema.props ?? []) {
+            if (property.desc === undefined)
+                continue;
+            entry.p ??= {};
+            entry.p[property.name] = marked.parse(property.desc, { async: false }).trim();
+        }
+        if (entry.d !== undefined || entry.p !== undefined)
+            info[path] = entry;
+        collectInfo(schema.childs ?? [], path, keys, info);
+    }
+};
+/*  inject the description popup maps into their client-side script ("<"
+    escaped, so no embedded HTML can close the surrounding <script>
+    element)  */
+const infoScript = (info, spec) => infoPopupScript
+    .replace("@INFO@", () => JSON.stringify(info).replace(/</g, "\\u003c"))
+    .replace("@SPEC@", () => JSON.stringify(spec).replace(/</g, "\\u003c"));
 /*  expand the inline Markdown of a text (code spans, emphasis, etc.),
-    with Wiki-style references expanded upfront  */
-const inline = (text) => safe(marked.parseInline(linker !== null ? linker(text) : text, { async: false }));
+    with Wiki-style references expanded upfront (in their compact form
+    for prose, i.e. descriptions, in their full form otherwise)  */
+const inline = (text, compact = false) => safe(marked.parseInline(linker !== null ? linker(text, compact) : text, { async: false }));
 /*  expand the full Markdown of a text, keeping its block-level
     constructs (lists, quotes, code blocks, tables) intact  */
-const block = (text) => safe(marked.parse(linker !== null ? linker(text) : text, { async: false }));
+const block = (text, compact = false) => safe(marked.parse(linker !== null ? linker(text, compact) : text, { async: false }));
 /*  check whether a text carries any block-level Markdown, i.e. is
     anything other than the single paragraph a description usually is  */
 const isBlock = (text) => {
@@ -303,14 +785,34 @@ const renderDescription = (description) => {
     const blocked = isBlock(text);
     return render("Description", { Description: {
             block: blocked,
-            description: text !== "" ? (blocked ? block(text) : inline(text)) : "",
+            description: text !== "" ? (blocked ? block(text, true) : inline(text, true)) : "",
             rationale: description.rationale !== undefined ?
-                inline(description.rationale) : undefined,
+                inline(description.rationale, true) : undefined,
             embeddings
         } });
 };
-/*  collect the "enum(...)"/"tags(...)" constrained properties of the
-    schema configuration, keyed by object kind and property name  */
+/*  collect the description popup map of the object instances: the
+    corpus description Markdown of every object, pre-rendered to HTML
+    and keyed by the fully-qualified anchor path (the embedded images
+    and the rationale are left out, as the popup shows the prose alone)  */
+const collectSpec = (objects, spec) => {
+    for (const object of objects) {
+        const text = (object.description?.description ?? "")
+            .replace(embeddingMarkup, (markup, _alt, reference) => embeddingMimeType(reference.trim()) !== undefined ? "" : markup)
+            .trim();
+        if (text !== "")
+            spec[anchorOf(object)] = scoped(object, () => block(text, true).toString().trim());
+        collectSpec(object.childs, spec);
+    }
+};
+/*  the literal members of an "enum(...)"/"tags(...)" expression, or
+    of the "enum(...)"/"tags(...)" alternatives of a "list(...)" one
+    (empty for every other expression)  */
+const literalMembers = (expr) => expr.kind === "enum" || expr.kind === "tags" ? expr.members :
+    expr.kind === "list" ? expr.alternatives.flatMap(literalMembers) : [];
+/*  collect the properties of the schema configuration constrained by
+    literal members (an "enum(...)", a "tags(...)", or a "list(...)"
+    with such alternatives), keyed by object kind and property name  */
 const collectMembers = (nodes, result) => {
     for (const schema of nodes) {
         for (const property of schema.props ?? []) {
@@ -318,8 +820,8 @@ const collectMembers = (nodes, result) => {
                 continue;
             try {
                 const expr = compileValueExpr(property.value);
-                if (expr.kind === "enum" || expr.kind === "tags")
-                    result.set(`${schema.kind}${property.name}`, expr.kind);
+                if (literalMembers(expr).length > 0)
+                    result.set(`${schema.kind} ${property.name}`, expr);
             }
             catch {
                 /*  an invalid expression is the concern of lint  */
@@ -331,70 +833,85 @@ const collectMembers = (nodes, result) => {
 };
 /*  render a property value, badging the individual members of an
     "enum(...)" (a single member) or "tags(...)" (a member set) value
-    and moving its image embeddings behind the value, rendered from the
-    embedded image contents (as for a description), not from the markup  */
-const inlineValue = (kind, { key, value, embedding }) => {
-    const member = members?.get(`${kind}${key}`);
+    and the literal member items of a "list(...)" value (the other items,
+    like references, stay prose), moving its image embeddings behind the
+    value, rendered from the embedded image contents (as for a
+    description), not from the markup; an absent property renders as the
+    marker telling it apart from a property given with an empty value  */
+const inlineValue = (kind, property) => {
+    if (property === undefined)
+        return safe("<span class=\"value-absent\"></span>");
+    const { key, value, embedding } = property;
+    const expr = members?.get(`${kind} ${key}`);
     const text = value
         .replace(embeddingMarkup, (markup, _alt, reference) => embeddingMimeType(reference.trim()) !== undefined ? "" : markup)
         .trim();
     const embeddings = renderEmbeddings(value, embedding ?? [])
         .map((content) => `<div class="embedding">${content}</div>`).join("");
-    if (member === undefined || text === "")
+    if (expr === undefined || text === "")
         return safe(`${inline(text)}${embeddings}`);
-    const items = member === "tags" ?
-        splitItems(text).filter((item) => item !== "") : [text];
-    return safe(items.map((item) => `<span class="value-member">${inline(item)}</span>`).join(" ") + embeddings);
+    const badge = (item) => `<span class="value-member">${inline(item)}</span>`;
+    if (expr.kind === "enum")
+        return safe(badge(text) + embeddings);
+    const items = splitItems(text).filter((item) => item !== "");
+    if (expr.kind === "tags")
+        return safe(items.map(badge).join(" ") + embeddings);
+    const literals = new Set(literalMembers(expr));
+    return safe(items.map((item) => literals.has(item) ? badge(item) : inline(item)).join(", ") + embeddings);
 };
-/*  expand the inline Markdown of the property values  */
-const inlineProperties = (kind, properties) => properties.map((property) => ({ key: property.key,
-    value: inlineValue(kind, property) }));
-/*  resolve the format configuration of an object  */
+/*  expand the inline Markdown of the property values, with the
+    entries injected for unused properties (foreign to the object)
+    rendered as absent  */
+const inlineProperties = (object, properties) => properties.map((property) => ({ key: property.key,
+    info: infoKeyOf(object), infopath: infoPathOf(object),
+    value: inlineValue(object.kind, object.properties.includes(property) ? property : undefined) }));
+/*  resolve the format configuration of the kind of an object  */
 const formatOf = (object) => schemas?.get(object)?.format;
-/*  determine the maximum table columns configured on an object (at
-    least two, as a single column cannot carry a name and a value)  */
+/*  determine the maximum table columns configured on the kind of an
+    object (at least two, as a single column cannot carry a name and a
+    value)  */
 const maxColumnsOf = (object) => Math.max(2, formatOf(object)?.maxTableColumns ?? 4);
-/*  determine the effective properties of an object, with
-    "withUnusedProps" injecting the defined but still unused schema
-    properties (in schema order) as empty key/value entries  */
+/*  determine the effective properties of an object in schema order
+    (unknown keys appended in document order), with "withUnusedProps"
+    injecting the defined but still unused schema properties as empty
+    key/value entries  */
 const effectiveProperties = (object) => {
     const schema = schemas?.get(object);
-    if (schema?.format?.withUnusedProps !== true)
+    if (schema === undefined)
         return object.properties;
+    const unused = schema.format?.withUnusedProps === true;
     const merged = (schema.props ?? []).flatMap((prop) => {
         const present = object.properties.filter((property) => property.key === prop.name);
-        return present.length > 0 ? present : [{ key: prop.name, value: "" }];
+        return present.length > 0 ? present : (unused ? [{ key: prop.name, value: "" }] : []);
     });
     return [...merged, ...object.properties.filter((property) => !merged.includes(property))];
 };
-/*  determine the column shape of a potential compact table, with
+/*  determine the column shape of a potential compact table in schema
+    order (unknown keys appended in occurrence order), with
     "withUnusedProps" injecting the defined but still unused schema
-    properties (in schema order) as additional columns  */
+    properties as additional columns  */
 const tableShape = (childs) => {
-    let keys = [...new Set(childs.flatMap((child) => child.properties.map((property) => property.key)))];
+    const used = [...new Set(childs.flatMap((child) => child.properties.map((property) => property.key)))];
     const schema = schemas?.get(childs[0]);
-    if (schema?.format?.withUnusedProps === true) {
-        const names = (schema.props ?? []).map((prop) => prop.name);
-        keys = [...names, ...keys.filter((key) => !names.includes(key))];
-    }
+    const names = (schema?.props ?? []).map((prop) => prop.name);
+    const known = schema?.format?.withUnusedProps === true ?
+        names : names.filter((name) => used.includes(name));
+    const keys = [...known, ...used.filter((key) => !names.includes(key))];
     return { keys, desc: childs.some((child) => child.description !== undefined || child.childs.length > 0) };
 };
 /*  provide the childs of an object taking part in the regular document
     flow: a nested title object leaves the flow, as it is rendered as the
     title page instead (a top-level one instead removes its whole artifact)  */
 const flowChilds = (object) => object.childs.filter((child) => !isTitleObject(child));
-/*  decide whether the childs of an object collapse into the concise
-    (tabular) rendering: an explicit "format" type wins, "auto" collapses
-    the deepest level only, and inside an already concise rendering
-    context "auto" childs implicitly stay concise, too  */
-const conciseChilds = (object, schemaMap, concise) => {
-    const childs = flowChilds(object);
-    if (childs.length === 0)
-        return false;
-    const type = schemaMap?.get(object)?.format?.type ?? "auto";
+/*  decide whether a single-kind group of childs collapses into the
+    concise (tabular) rendering: an explicit "format" type of the kind
+    wins, "auto" collapses the deepest level only, and inside an already
+    concise rendering context "auto" groups implicitly stay concise, too  */
+const conciseGroup = (group, schemaMap, concise) => {
+    const type = schemaMap?.get(group[0])?.format?.type ?? "auto";
     if (type !== "auto")
         return type === "concise";
-    return concise || childs.every((child) => child.childs.length === 0);
+    return concise || group.every((child) => child.childs.length === 0);
 };
 /*  group the childs of an object by their kind, preserving order  */
 const groupChilds = (childs) => {
@@ -408,44 +925,54 @@ const groupChilds = (childs) => {
     }
     return [...groups.values()];
 };
+/*  render the childs of an object group-wise by kind: a concise group
+    as one compact table, a complex group as regular nested object
+    renderings  */
+const renderChilds = (object, level, concise) => groupChilds(flowChilds(object)).map((group) => conciseGroup(group, schemas, concise) ?
+    renderTable(group, maxColumnsOf(group[0])) :
+    group.map((child) => renderObject(child, level, concise)).join("")).join("");
 /*  render the description cell of a table row: the description of the
     object followed by its recursively rendered childs (implicitly or
-    explicitly concise childs as nested sub-tables, explicitly complex
-    ones as regular nested object renderings pressed into the cell)  */
+    explicitly concise groups as nested sub-tables, explicitly complex
+    ones as regular nested object renderings pressed into the cell);
+    a cell left without any content renders as the absent marker,
+    exactly like a property cell of a not given property  */
 const renderCell = (child) => {
     let html = child.description !== undefined ? renderDescription(child.description) : "";
-    const childs = flowChilds(child);
-    if (childs.length > 0)
-        html += conciseChilds(child, schemas, true) ?
-            groupChilds(childs).map((group) => renderTable(group, maxColumnsOf(child))).join("") :
-            childs.map((sub) => renderObject(sub, 6, true)).join("");
-    return html;
+    html += renderChilds(child, 6, true);
+    return html.trim() !== "" ? html : "<span class=\"value-absent\"></span>";
 };
 /*  render a single-kind group of childs into one compact table:
     the name first, then the property columns, then the description;
-    a group wider than maxColumns instead chunks the property and
-    description cells of every object into an embedded per-object table  */
+    a group wider than maxColumns, or carrying diagrams, instead chunks
+    the property and description cells (and the leading diagram) of
+    every object into an embedded per-object table, as a diagram is
+    identifiable only under a header of its own, not under the column
+    headers of a plain table  */
 const renderTable = (childs, maxColumns) => {
     const { keys, desc } = tableShape(childs);
-    if (1 + keys.length + (desc ? 1 : 0) <= maxColumns)
+    const diagrams = childs.some((child) => diagramOf(child) !== "");
+    if (!diagrams && 1 + keys.length + (desc ? 1 : 0) <= maxColumns)
         return render("Table", { Table: {
                 head: childs[0].kind !== "" ? childs[0].kind : "Name",
+                info: infoKeyOf(childs[0]),
+                infopath: infoPathOf(childs[0], false),
                 keys,
                 desc,
                 /*  under the fixed table layout the description column claims
                     twice the share of a regular column, compressing the others  */
                 width: Math.round(200 / (keys.length + 3)),
-                rows: childs.map((child) => ({
+                rows: childs.map((child, i) => scoped(child, () => ({
                     id: anchorOf(child),
                     paren: child.paren,
                     primary: child.primary,
+                    spec: infoParents !== null ? anchorOf(child) : undefined,
+                    specpath: infoPathOf(child),
                     name: inline(child.name),
-                    values: keys.map((key) => {
-                        const property = child.properties.find((property) => property.key === key);
-                        return property !== undefined ? inlineValue(child.kind, property) : "";
-                    }),
+                    even: i % 2 === 1,
+                    values: keys.map((key) => inlineValue(child.kind, child.properties.find((property) => property.key === key))),
                     description: safe(renderCell(child))
-                }))
+                })))
             } });
     /*  the embedded rows hold at most maxColumns - 1 cells (of the
         group-wide union of property keys, plus the trailing description),
@@ -453,51 +980,67 @@ const renderTable = (childs, maxColumns) => {
     const size = Math.max(1, maxColumns - 1);
     return render("TableChunked", { Table: {
             head: childs[0].kind !== "" ? childs[0].kind : "Name",
+            info: infoKeyOf(childs[0]),
+            infopath: infoPathOf(childs[0], false),
             width: Math.round(100 / maxColumns),
-            rows: childs.map((child) => {
-                const cells = keys.map((key) => {
-                    const property = child.properties.find((property) => property.key === key);
-                    return { key, desc: false, span: 1,
-                        value: property !== undefined ? inlineValue(child.kind, property) : "" };
-                });
+            rows: childs.map((child, i) => scoped(child, () => {
+                const cells = keys.map((key) => ({ key, desc: false, span: 1,
+                    value: inlineValue(child.kind, child.properties.find((property) => property.key === key)) }));
                 if (desc)
                     cells.push({ key: "Description", desc: true, span: 1,
                         value: safe(renderCell(child)) });
                 const chunks = new Array();
                 for (let i = 0; i < cells.length; i += size)
                     chunks.push(cells.slice(i, i + size));
-                const last = chunks[chunks.length - 1];
-                last[last.length - 1].span = size - last.length + 1;
+                if (chunks.length > 0) {
+                    const last = chunks[chunks.length - 1];
+                    last[last.length - 1].span = size - last.length + 1;
+                }
+                /*  the diagram leads the chunks as a full-width chunk of its
+                    own, headed like the description  */
+                const diagram = diagramOf(child);
+                if (diagram !== "")
+                    chunks.unshift([{ key: "Diagram", desc: true, span: size, value: diagram }]);
                 return {
                     id: anchorOf(child),
                     paren: child.paren,
                     primary: child.primary,
+                    spec: infoParents !== null ? anchorOf(child) : undefined,
+                    specpath: infoPathOf(child),
                     name: inline(child.name),
+                    even: i % 2 === 1,
                     chunks
                 };
-            })
+            }))
         } });
 };
+/*  the pre-rendered diagram of an object as an embeddable block
+    (empty for an object without a configured or renderable diagram)  */
+const diagramOf = (object) => {
+    const diagram = diagrams?.get(object);
+    return diagram !== undefined ? safe(`<div class="diagram">${diagram}</div>`) : "";
+};
 /*  recursively render an object into HTML  */
 const renderObject = (object, level, concise) => {
     const properties = effectiveProperties(object);
-    const diagram = diagrams?.get(object);
-    return render("Object", { Object: {
+    return scoped(object, () => render("Object", { Object: {
             level: Math.min(level, 6),
             kind: object.kind,
+            info: infoKeyOf(object),
+            infopath: infoPathOf(object, false),
+            spec: infoParents !== null ? anchorOf(object) : undefined,
+            specpath: infoPathOf(object),
             id: anchorOf(object),
             paren: object.paren,
             primary: object.primary,
             name: inline(object.name),
-            diagram: diagram !== undefined ? safe(`<div class="diagram">${diagram}</div>`) : "",
+            diagram: diagramOf(object),
             properties: properties.length > 0 ?
-                safe(render("Properties", { Properties: inlineProperties(object.kind, properties) })) : "",
+                safe(render("Properties", { Properties: inlineProperties(object, properties) })) : "",
             description: object.description !== undefined ?
                 safe(renderDescription(object.description)) : "",
-            childs: conciseChilds(object, schemas, concise) ?
-                safe(groupChilds(flowChilds(object)).map((group) => renderTable(group, maxColumnsOf(object))).join("")) :
-                safe(flowChilds(object).map((child) => renderObject(child, level + 1, concise)).join(""))
-        } });
+            childs: safe(renderChilds(object, level + 1, concise))
+        } }));
 };
 /*  format a timestamp as its calendar date in local time (the
     frontmatter timestamps are parsed in local time, too, so the UTC
@@ -519,7 +1062,7 @@ const renderTitlePage = (object, created, modified) => {
         in both its theme variants  */
     const logo = object.properties.find((property) => property.key === "LOGO");
     const image = logo !== undefined ? renderEmbeddings(logo.value, logo.embedding ?? []) : [];
-    return render("TitlePage", { TitlePage: {
+    return scoped(object, () => render("TitlePage", { TitlePage: {
             logo: logo === undefined ?
                 safe(renderThemed(embeddingThemes.map((theme) => `<img src="${fallbackLogo(theme)}" alt="SpecBook"/>`))) :
                 (image.length > 0 ? safe(image.join("")) : inline(logo.value)),
@@ -530,23 +1073,67 @@ const renderTitlePage = (object, created, modified) => {
             description: object.description !== undefined ?
                 safe(renderDescription(object.description)) : "",
             properties: rest.length > 0 ?
-                safe(render("Properties", { Properties: inlineProperties(object.kind, rest) })) : "",
+                safe(render("Properties", { Properties: inlineProperties(object, rest) })) : "",
             created, modified
-        } });
+        } }));
 };
 /*  render an artifact into HTML  */
 const renderArtifact = (artifact) => render("Artifact", { Artifact: {
         objects: safe(artifact.objects.map((object) => renderObject(object, 1, false)).join(""))
     } });
+/*  provide the childs of an object rendered with headings of their own
+    (skipping the child groups collapsing into compact tables), which
+    are the ones taking part in the table of contents and its side panel  */
+const headingChilds = (object) => groupChilds(flowChilds(object))
+    .filter((group) => !conciseGroup(group, schemas, false))
+    .flat();
+/*  flatten the hierarchy of the rendered object headings (exactly like
+    the PDF outline) into the entries of the table of contents, each
+    carrying its nesting level and its optional page number  */
+const tocEntries = (objects, pages) => {
+    const entries = [];
+    const collect = (objects, level) => {
+        for (const object of objects) {
+            const id = anchorOf(object);
+            entries.push({ id, kind: object.kind,
+                info: infoKeyOf(object), infopath: infoPathOf(object, false),
+                spec: infoParents !== null ? id : undefined, specpath: infoPathOf(object),
+                name: inline(object.name), level: Math.min(level, 6), page: pages?.get(id) });
+            collect(headingChilds(object), level + 1);
+        }
+    };
+    collect(objects, 1);
+    return entries;
+};
+/*  render the side panel of the table of contents (its behavior is
+    driven by the client-side script above): the unnumbered entries of
+    the front matter (title page, table and diagram of contents, as far
+    as present) are followed by the hierarchical entries of the rendered
+    object headings, exactly like the table of contents itself  */
+const renderTocPanel = (objects, title, doc) => {
+    const entries = (objects) => objects.length === 0 ? "" : render("TocPanelEntries", { Entries: objects.map((object) => ({
+            id: anchorOf(object),
+            kind: object.kind,
+            info: infoKeyOf(object),
+            infopath: infoPathOf(object, false),
+            spec: infoParents !== null ? anchorOf(object) : undefined,
+            specpath: infoPathOf(object),
+            name: inline(object.name),
+            childs: safe(entries(headingChilds(object)))
+        })) });
+    return render("TocPanel", { TocPanel: { title, doc, entries: safe(entries(objects)) } });
+};
 /*  derive the hierarchy of the rendered object headings, skipping the
-    title page object and the childs collapsing into compact tables  */
+    title page object and the child groups collapsing into compact tables  */
 export const htmlOutline = (specification, config) => {
     const paths = anchorPaths(buildLinkIndex(specification));
     const schemaMap = config !== undefined ? collectSchemas(specification, config) : null;
     const entry = (object) => ({
         title: (object.kind !== "" ? `${object.kind}: ` : "") + plainText(object.name),
         anchor: paths.get(object) ?? object.id,
-        childs: conciseChilds(object, schemaMap, false) ? [] : flowChilds(object).map(entry)
+        childs: groupChilds(flowChilds(object))
+            .filter((group) => !conciseGroup(group, schemaMap, false))
+            .flatMap((group) => group.map(entry))
     });
     return specification.artifacts
         .filter((artifact) => !artifact.objects.some(isTitleObject))
@@ -564,9 +1151,10 @@ const titlePageObject = (specification) => {
 };
 /*  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), and
-    optional per-anchor page numbers attached to the ToC entries  */
-export const renderHtml = async (specification, config, tocPages, css) => {
+    artifact timestamps aggregated into min(Created)/max(Modified),
+    optional per-anchor page numbers attached to the ToC entries, and
+    optionally the client-side script of the live preview injected  */
+export const renderHtml = async (specification, config, tocPages, css, realtime = false) => {
     /*  pre-render the configured diagrams as embeddable SVGs (a runtime
         rendering failure omits the diagram, as the statically detectable
         invalid situations are already reported as lint diagnostics),
@@ -585,7 +1173,17 @@ export const renderHtml = async (specification, config, tocPages, css) => {
                 continue;
             try {
                 const svg = await Gradia.render(result.spec, { format: "svg:embedded", config: result.config });
-                rendered.set(object, svg.replace(/(<svg[^>]*) width="([0-9.]+)" height="([0-9.]+)"/, (_, head, w, h) => `${head} width="${Number(w) * scale}" height="${Number(h) * scale}"`));
+                /*  a "hub" diagram is capped to the width share it would
+                    occupy on its full three-column canvas (padded by the
+                    minimum widths of the absent columns and their channels),
+                    so all hub diagrams share the zoom level of the
+                    three-column ones and are centered in the leftover space  */
+                const absent = result.columns !== undefined ? 3 - result.columns : 0;
+                const pad = absent * ((result.config?.["size-node-width-min"] ?? Gradia.config["size-node-width-min"]) +
+                    (result.config?.["hub-channel-width-min"] ?? Gradia.config["hub-channel-width-min"]));
+                rendered.set(object, svg.replace(/(<svg[^>]*) width="([0-9.]+)" height="([0-9.]+)"/, (_, head, w, h) => `${head} width="${Number(w) * scale}" height="${Number(h) * scale}"` +
+                    (result.columns !== undefined ? " class=\"hub\"" : "") +
+                    (absent > 0 ? ` style="max-width: ${(Number(w) / (Number(w) + pad) * 100).toFixed(2)}%"` : "")));
             }
             catch {
                 /*  intentionally omitted  */
@@ -597,31 +1195,69 @@ export const renderHtml = async (specification, config, tocPages, css) => {
     const lang = documentLang(specification);
     quotes = quoteStyles[lang?.toLowerCase().split(/[-_]/)[0] ?? "en"] ?? quoteStyles.en;
     /*  expand "[[xxx]]" references into hyperlinks (an unresolvable or
-        ambiguous reference stays literal, marked as broken), targeting
-        the fully-qualified anchor paths of the objects  */
+        ambiguous reference stays literal, marked as broken), resolved
+        from the object currently rendered and targeting the
+        fully-qualified anchor paths of the objects: in the full form
+        (kind, name, and link symbol), or in the compact form for prose
+        (the object icon and the name only, via CSS and markup, with
+        the full form shown by the description popups)  */
     const index = buildLinkIndex(specification);
     anchors = anchorPaths(index);
     members = config !== undefined ? collectMembers(config, new Map()) : null;
     schemas = config !== undefined ? collectSchemas(specification, config) : null;
     diagrams = rendered;
-    linker = (text) => expandReferences(text, (reference) => {
-        const target = resolveUnique(index, reference).target;
+    /*  collect the schema descriptions for the description popups,
+        plus the object parents composing their title paths  */
+    let info = null;
+    if (config !== undefined) {
+        infoKeys = new Map();
+        info = {};
+        collectInfo(config, "", infoKeys, info);
+        const parents = new Map();
+        const link = (object) => {
+            for (const child of object.childs) {
+                parents.set(child, object);
+                link(child);
+            }
+        };
+        for (const artifact of specification.artifacts)
+            artifact.objects.forEach(link);
+        infoParents = parents;
+    }
+    linker = (text, compact) => expandReferences(text, (reference) => {
+        const target = resolveUnique(index, reference, scope ?? undefined).target;
         if (target === undefined)
             return `<span class="link-broken">[[${escapeHtml(reference)}]]</span>`;
-        return `<a href="#${escapeHtml(anchorOf(target))}">` +
-            `<span class="object-kind">${escapeHtml(target.kind)}:</span> <strong>${target.name}</strong>` +
-            " <span class=\"link-symbol\">&#x26AD;</span></a>";
+        /*  the full form carries the popup attributes on its kind and
+            name, with the kind bold in the accent color and the name
+            bold in the regular text color (via the stylesheet)  */
+        const full = `<strong class="object-kind"${infoAttr(target)}>${escapeHtml(target.kind)}:</strong>` +
+            ` <span class="object-name"${specAttr(target)}>${target.name}</span>` +
+            " <span class=\"link-symbol\">&#x26AD;</span>";
+        return compact ?
+            `<a href="#${escapeHtml(anchorOf(target))}" class="link-compact"${specAttr(target)}>${target.name}</a>` :
+            `<a href="#${escapeHtml(anchorOf(target))}" class="link-full">${full}</a>`;
     });
+    /*  collect the corpus descriptions of the object instances for the
+        description popups (after the linker is in place, as the
+        pre-rendered descriptions expand their references, too)  */
+    let spec = null;
+    if (info !== null) {
+        spec = {};
+        for (const artifact of specification.artifacts)
+            collectSpec(artifact.objects, spec);
+    }
     const created = new Date(Math.min(...specification.artifacts.map((artifact) => artifact.created.getTime())));
     const modified = new Date(Math.max(...specification.artifacts.map((artifact) => artifact.modified.getTime())));
-    /*  a "META: Title" object becomes the title page and leaves the regular flow  */
+    /*  a "META: Title" object becomes the title page and leaves the regular
+        flow, while its diagram becomes the "Diagram of Contents" page  */
     const title = titlePageObject(specification);
     const artifacts = specification.artifacts
         .filter((artifact) => !artifact.objects.some(isTitleObject));
+    const meta = titleObject(specification);
+    const doc = meta !== undefined ? rendered?.get(meta) : undefined;
     try {
-        const entries = artifacts.flatMap((artifact) => artifact.objects)
-            .map((object) => ({ id: anchorOf(object), kind: object.kind, name: inline(object.name),
-            page: tocPages?.get(anchorOf(object)) }));
+        const entries = tocEntries(artifacts.flatMap((artifact) => artifact.objects), tocPages);
         return render("Document", { Document: {
                 title: documentTitle(specification).title,
                 lang,
@@ -629,8 +1265,14 @@ export const renderHtml = async (specification, config, tocPages, css) => {
                 css: safe(css ?? stylesheet()),
                 titlepage: title !== undefined ?
                     safe(renderTitlePage(title, formatDate(created), formatDate(modified))) : "",
-                search: title !== undefined ? safe(searchScript()) : "",
+                search: safe(searchScript()),
+                info: info !== null ? safe(infoScript(info, spec ?? {})) : "",
+                realtime: realtime ? safe(realtimeScript) : "",
                 toc: entries.length > 0 ? safe(render("Toc", { Toc: { entries } })) : "",
+                tocpanel: entries.length > 0 ?
+                    safe(renderTocPanel(artifacts.flatMap((artifact) => artifact.objects), title !== undefined, doc !== undefined)) : "",
+                tocscript: entries.length > 0 ? safe(tocPanelScript) : "",
+                doc: doc !== undefined ? safe(render("Doc", { Doc: { diagram: safe(doc) } })) : "",
                 artifacts: safe(artifacts.map((artifact) => renderArtifact(artifact)).join(""))
             } });
     }
@@ -643,5 +1285,7 @@ export const renderHtml = async (specification, config, tocPages, css) => {
         members = null;
         schemas = null;
         diagrams = null;
+        infoKeys = null;
+        infoParents = null;
     }
 };