@rse/specbook 1.2.10 → 1.2.12

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

@@ -11,7 +11,9 @@
     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  */
+    the table of contents (page and side panel) is filtered along; the
+    explicit anchor id of an object (invisible in the document) is
+    searched like its text, a hit marking the anchor symbol instead  */
 (function () {
     const tab    = document.getElementById("search")
     const toggle = document.getElementById("search-toggle")
@@ -52,7 +54,9 @@
         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  */
+        as its raw text content would run them together, and where the
+        explicit anchor id of an object heading or table row joins the
+        searched text  */
     const index = () => {
         if (indexed)
             return
@@ -66,12 +70,13 @@
                             return
                         parent = parent.parentElement
                     }
-                    const text  = (el.classList.contains("diagram") ?
+                    const id    = (el.dataset.id ?? "").toLowerCase()
+                    const text  = ((el.classList.contains("diagram") ?
                         Array.from(el.querySelectorAll("text")).map((t) => t.textContent ?? "").join(" ") :
-                        (el.textContent ?? "")).toLowerCase()
+                        (el.textContent ?? "")) + " " + id).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 })
+                    units.push({ el, id, text, words, keep: false })
                 })
         })
 
@@ -319,12 +324,24 @@
                 el.classList.add("search-hide")
         })
 
-        /*  highlight every matched word within the kept units  */
+        /*  highlight every matched word within the kept units, plus the
+            anchor symbol of a unit whose explicit anchor id matched, as
+            the id itself is nowhere visible  */
         const words = Array.from(new Set(parts.flat()))
         const regex = buildRegex(words, Array.from(variants))
         units.forEach((unit) => {
-            if (unit.el.classList.contains("search-keep"))
-                highlight(unit.el, regex)
+            if (!unit.el.classList.contains("search-keep"))
+                return
+            highlight(unit.el, regex)
+            regex.lastIndex = 0
+            const symbol = unit.el.querySelector("span.anchor-symbol")
+            if (unit.id === "" || symbol === null || !regex.test(unit.id))
+                return
+            const mark = document.createElement("mark")
+            mark.classList.add("search-hit")
+            while (symbol.firstChild !== null)
+                mark.appendChild(symbol.firstChild)
+            symbol.appendChild(mark)
         })
 
         /*  filter the table of contents (its page rows and its side

package/dst/specbook-export-html.css

@@ -282,7 +282,9 @@ body.info-on div.info-switch svg.info-icon {
     icon leading each, the kinds bold in the path color and the names
     semi-bold in the description color, as in the document content,
     and a pointer separating the segments), extended for properties
-    with the not-filled circle icon and the bold property name, and
+    with the not-filled circle icon and the bold property name, trailed
+    for instances by the anchor id of the object in the description
+    color (its "(#...)" wrapping normal, the id itself semi-bold), and
     the description led by a "Schema" or "Specification" origin label
     (its word in normal weight in a rounded box filled with the path
     color), where
@@ -329,6 +331,13 @@ div.info-popup span.info-name {
 div.info-popup.spec span.info-name {
   color: var(--theme-color-specbook-popup-spec-desc);
 }
+div.info-popup.spec span.info-id {
+  color: var(--theme-color-specbook-popup-spec-desc);
+  font-weight: normal;
+}
+div.info-popup.spec span.info-id-name {
+  font-weight: 600;
+}
 div.info-popup span.info-object::before {
   content: "\25CF";
   font-weight: normal;

package/dst/specbook-export-html.js

@@ -109,7 +109,7 @@ const templates = {
             <h1>Table of Contents</h1>
             <table>
                 {% for entry in Toc.entries %}
-                <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>
+                <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-id="{{ entry.specid }}" 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>
@@ -132,7 +132,7 @@ const templates = {
     "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.children }}</li>
+            <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-id="{{ entry.specid }}" data-info-path="{{ entry.specpath }}"{% endif %}>{{ entry.name }}</span></span></a>{{ entry.children }}</li>
             {% endfor %}
         </ul>
     `,
@@ -152,7 +152,7 @@ const templates = {
     /*  <Object/>  */
     "Object": textframe `
         <section>
-            <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 }}>
+            <h{{ Object.level }} id="{{ Object.id }}"{% if Object.anchor %} data-id="{{ Object.anchor }}"{% endif %}><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-id="{{ Object.specid }}" 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 }}
@@ -206,8 +206,8 @@ const templates = {
             </thead>
             <tbody>
                 {% for row in Table.rows %}
-                <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>
+                <tr id="{{ row.id }}"{% if row.anchor %} data-id="{{ row.anchor }}"{% endif %}{% if row.even %} class="even"{% endif %}>
+                    <td><span{% if row.spec %} data-info-spec="{{ row.spec }}" data-info-id="{{ row.specid }}" 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>
@@ -226,8 +226,8 @@ const templates = {
             </thead>
             <tbody>
                 {% for row in Table.rows %}
-                <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>
+                <tr id="{{ row.id }}"{% if row.anchor %} data-id="{{ row.anchor }}"{% endif %}{% if row.even %} class="even"{% endif %}>
+                    <td><span{% if row.spec %} data-info-spec="{{ row.spec }}" data-info-id="{{ row.specid }}" 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 %}
@@ -866,7 +866,8 @@ const tocPanelScript = textframe `
     carrying a "data-info-spec" key pops up the corpus description of
     the object instance (a diagram node box resolves through its
     hyperlinked object anchor), titled with the "data-info-path" object
-    path and fed from the injected INFO/SPEC maps of pre-rendered
+    path (an instance popup trailing the "data-info-id" anchor id of
+    the object) and fed from the injected INFO/SPEC maps of pre-rendered
     description HTML; the popup is capped at 40% viewport width and
     attached above or below, whichever side offers more space; the
     script runs at the end of the body, so a live preview body swap
@@ -964,6 +965,20 @@ const infoPopupScript = textframe `
                 }
                 title.appendChild(path)
             }
+
+            /*  the anchor id of an object instance (explicit or derived
+                from its name, carried by the "data-info-id" key) trails
+                the last segment  */
+            const anchor = source.getAttribute("data-info-id")
+            if (spec !== null && anchor !== null) {
+                const id = document.createElement("span")
+                id.className = "info-id"
+                const name = document.createElement("span")
+                name.className = "info-id-name"
+                name.textContent = anchor
+                id.append(" (#", name, ")")
+                title.appendChild(id)
+            }
             if (prop !== null) {
                 title.appendChild(pointer())
                 const name = document.createElement("span")
@@ -1154,11 +1169,12 @@ const infoAttr = (object) => {
         ` 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
+    path), anchor id, 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))}"` : "";
+    ` data-info-spec="${escapeHtml(anchorOf(object))}" data-info-id="${escapeHtml(object.id)}"` +
+        ` 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
@@ -1460,9 +1476,11 @@ const renderTable = (children, maxColumns) => {
                 width: Math.round(200 / (keys.length + 3)),
                 rows: children.map((child, i) => scoped(child, () => ({
                     id: anchorOf(child),
+                    anchor: child.anchor,
                     paren: child.paren,
                     primary: child.primary,
                     spec: infoParents !== null ? anchorOf(child) : undefined,
+                    specid: child.id,
                     specpath: infoPathOf(child),
                     name: inline(child.name),
                     even: i % 2 === 1,
@@ -1500,9 +1518,11 @@ const renderTable = (children, maxColumns) => {
                     chunks.unshift([{ key: "Diagram", desc: true, span: size, value: diagram }]);
                 return {
                     id: anchorOf(child),
+                    anchor: child.anchor,
                     paren: child.paren,
                     primary: child.primary,
                     spec: infoParents !== null ? anchorOf(child) : undefined,
+                    specid: child.id,
                     specpath: infoPathOf(child),
                     name: inline(child.name),
                     even: i % 2 === 1,
@@ -1520,8 +1540,10 @@ const renderObject = (object, level, concise) => {
             info: infoKeyOf(object),
             infopath: infoPathOf(object, false),
             spec: infoParents !== null ? anchorOf(object) : undefined,
+            specid: object.id,
             specpath: infoPathOf(object),
             id: anchorOf(object),
+            anchor: object.anchor,
             paren: object.paren,
             primary: object.primary,
             name: inline(object.name),
@@ -1590,7 +1612,7 @@ const tocEntries = (objects, pages) => {
             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),
+                spec: infoParents !== null ? id : undefined, specid: object.id, specpath: infoPathOf(object),
                 name: inline(object.name), level: Math.min(level, 6), page: pages?.get(id) });
             collect(headingChildren(object), level + 1);
         }
@@ -1610,6 +1632,7 @@ const renderTocPanel = (objects, title, doc) => {
             info: infoKeyOf(object),
             infopath: infoPathOf(object, false),
             spec: infoParents !== null ? anchorOf(object) : undefined,
+            specid: object.id,
             specpath: infoPathOf(object),
             name: inline(object.name),
             children: safe(entries(headingChildren(object)))

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":                                "@rse/specbook",
-    "version":                             "1.2.10",
+    "version":                             "1.2.12",
     "publishConfig":                       { "access": "public" },
     "description":                         "Markdown-based Specification Format (API, CLI and MCP service)",
     "license":                             "Apache-2.0",
@@ -17,9 +17,9 @@
     },
     "files":                               [ "dst" ],
     "dependencies": {
-        "marked":                          "18.0.12",
+        "marked":                          "18.0.13",
         "marked-smartypants":              "1.1.12",
-        "yaml":                            "2.9.0",
+        "yaml":                            "2.9.1",
         "json5":                           "2.2.3",
         "pdf-lib":                         "1.17.1",
         "subset-font":                     "2.7.0",
@@ -40,10 +40,10 @@
         "glob":                            "13.0.6",
         "picomatch":                       "4.0.7",
         "es-toolkit":                      "1.52.0",
-        "fastify":                         "5.12.3",
+        "fastify":                         "5.12.4",
         "@fastify/websocket":              "11.3.0",
         "@modelcontextprotocol/sdk":       "1.30.0",
-        "zod":                             "4.6.1"
+        "zod":                             "4.6.5"
     },
     "devDependencies": {
         "chokidar-cli":                    "3.0.0",
@@ -55,7 +55,7 @@
         "globals":                         "17.12.0",
         "markdownlint":                    "0.41.1",
         "markdownlint-cli2":               "0.23.2",
-        "@types/node":                     "26.5.0",
+        "@types/node":                     "26.5.1",
         "@types/picomatch":                "4.0.3",
         "@types/subset-font":              "2.3.0",
         "@types/nunjucks":                 "3.2.6",