@rse/specbook 1.2.7 → 1.2.9

package/README.md

@@ -6,6 +6,8 @@ SpecBook
 
 **Markdown-based Specification Format**
 
+[specbook.tools](https://specbook.tools)
+
 [![github (author stars)](https://img.shields.io/github/stars/rse?logo=github&label=author%20stars&color=%233377aa)](https://github.com/rse)
 [![github (author followers)](https://img.shields.io/github/followers/rse?label=author%20followers&logo=github&color=%234477aa)](https://github.com/rse)
 
@@ -84,6 +86,7 @@ CLI with commands `specbook <xxx>`, and an MCP service with tools
     reference coverage tables (e.g. the share of the use cases, scenarios,
     requirements, and rules the test cases verify), a
     scroll progress meter (which also scrolls back to the top on click),
+    diagram maximization (into the viewport or the fullscreen),
     description popups (which show the schema and corpus description of
     an object kind, property, or object instance on hover), and a
     light/dark theme toggle. It is intended for the day-to-day online

package/dst/specbook-cmd-export.js

@@ -3,6 +3,7 @@
 **  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
+import * as fs from "node:fs";
 /*  Chokidar is aliased in "package.json", as Nunjucks declares the
     (unused) Chokidar 3 as an optional peer dependency and the current
     Chokidar under its plain name would raise a peer warning on install  */
@@ -56,16 +57,38 @@ export const parseOutputSpec = (spec) => {
 /*  the quiet period the observed files have to stay silent for before a
     burst of changes is coalesced into a single re-export  */
 const watchDelay = 1000;
+/*  the interval of the safety-net scan, which catches the changes the
+    file-system watcher missed: a watcher can die unnoticed -- macOS
+    tears down its FSEvents streams across a sleep/wake cycle -- and
+    would then leave the export stale for the rest of the process life  */
+const scanDelay = 30 * 1000;
+/*  take the modification time snapshot of the observed files, where an
+    absent file (a still missing artifact) is remembered as absent, too,
+    so its creation and removal are noticed like a modification  */
+const snapshot = (files) => {
+    const times = new Map();
+    for (const file of files) {
+        try {
+            times.set(file, fs.statSync(file).mtimeMs);
+        }
+        catch {
+            times.set(file, 0);
+        }
+    }
+    return times;
+};
 /*  keep a specification export in sync with its sources, where "run"
     performs one export and returns the files to observe: the initial
     export is performed up-front and every observed change triggers a
     re-export once the sources fell silent again. The observed set is
     re-synchronized after every run, as an edit can add or drop an
     embedded asset. The returned promise settles once the initial export
-    is done, while the active watcher keeps the process alive afterwards  */
+    is done, while the active watcher and the safety-net scan keep the
+    process alive afterwards  */
 export const watchSpecification = async (run, verbose) => {
     /*  perform the regular export before entering the observe loop  */
     let observed = await run();
+    let times = snapshot(observed);
     const watcher = watch(observed, { ignoreInitial: true });
     verbose(`observing ${literal(observed.length)} specification file(s) for changes`);
     /*  report the failures of the observation itself, as an unhandled
@@ -80,6 +103,7 @@ export const watchSpecification = async (run, verbose) => {
         watcher.unwatch(observed.filter((file) => !files.includes(file)));
         watcher.add(files.filter((file) => !observed.includes(file)));
         observed = files;
+        times = snapshot(files);
     };
     /*  restart the quiet period on every change, so a burst collapses
         into a single re-export, and chain the runs onto each other, so a
@@ -88,7 +112,7 @@ export const watchSpecification = async (run, verbose) => {
         and hence silently ending the observe loop)  */
     let chain = Promise.resolve();
     let timer;
-    watcher.on("all", () => {
+    const schedule = () => {
         if (timer !== undefined)
             clearTimeout(timer);
         timer = setTimeout(() => {
@@ -98,7 +122,24 @@ export const watchSpecification = async (run, verbose) => {
                     (err instanceof Error ? err.message : String(err)), "none");
             });
         }, watchDelay);
-    });
+    };
+    watcher.on("all", schedule);
+    /*  compare the modification times regularly, so a change the
+        watcher never reported still reaches the export, and re-establish
+        the watchers on such a miss, as a watcher which lost a file never
+        regains it on its own and the following changes would be caught
+        by the scan only  */
+    setInterval(() => {
+        for (const [file, time] of snapshot(observed))
+            if (times.get(file) !== time) {
+                verbose(`observing missed the change of "${literal(file)}" ` +
+                    "-- re-establishing the file observation", "none");
+                watcher.unwatch(observed);
+                watcher.add(observed);
+                schedule();
+                break;
+            }
+    }, scanDelay);
 };
 /*  render a specification into the requested format, where "realtime"
     injects the client-side script of the live preview into the HTML  */

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

@@ -74,6 +74,23 @@
                     units.push({ el, text, words, keep: false })
                 })
         })
+
+        /*  let a hyperlink whose target the filtering hid leave the
+            search mode (like the Escape key) before it jumps: the click
+            is intercepted, the document revealed again, and the click
+            re-issued, so the browser performs the regular jump  */
+        document.querySelectorAll("a[href^='#']").forEach((link) => {
+            link.addEventListener("click", (event) => {
+                const target = document.getElementById(
+                    decodeURIComponent((link.getAttribute("href") ?? "").slice(1)))
+                if (target === null || target.closest(".search-hide") === null)
+                    return
+                event.preventDefault()
+                reset()
+                slide(false)
+                link.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }))
+            })
+        })
     }
 
     /*  the Levenshtein edit distance of two words  */

package/dst/specbook-export-html.css

@@ -574,6 +574,87 @@ span.fold-label svg {
     display: none;
   }
 }
+/*  the maximization of the diagrams (screen-only): every diagram
+    carries two controls at its top right corner (drawn like the fold
+    chevron of an over-long cell, in rounded boxes on the page
+    background), faded in while the diagram is hovered, which maximize
+    the diagram temporarily in the shared overlay covering the whole
+    viewport (or, taken into the browser fullscreen, the whole screen)
+    on the page background, where the cloned diagram scales to fit the
+    padded area (aspect ratio kept, centered) and a close mark sits at
+    the top right corner, while the document beneath stops scrolling  */
+span.maximize-controls {
+  position: absolute;
+  top: 0.35rem;
+  right: 0.35rem;
+  display: flex;
+  gap: 0.25rem;
+  line-height: 0;
+  opacity: 0;
+  transition: opacity 0.2s ease;
+}
+div.diagram:hover span.maximize-controls {
+  opacity: 1;
+}
+span.maximize-controls > span,
+span.maximize-close {
+  display: inline-block;
+  padding: 0.2rem;
+  line-height: 0;
+  color: var(--theme-color-specbook-symbol);
+  background-color: var(--theme-color-specbook-background);
+  border: 1px solid var(--theme-color-specbook-border);
+  border-radius: 0.25rem;
+  cursor: pointer;
+  -webkit-user-select: none;
+  user-select: none;
+}
+span.maximize-controls > span:hover,
+span.maximize-close:hover {
+  color: var(--theme-color-specbook-accent);
+  border-color: var(--theme-color-specbook-accent);
+}
+span.maximize-controls svg,
+span.maximize-close svg {
+  width: 1rem;
+  height: 1rem;
+}
+div.maximize {
+  display: none;
+  position: fixed;
+  inset: 0;
+  z-index: 40;
+  box-sizing: border-box;
+  padding: 2rem;
+  background-color: var(--theme-color-specbook-background);
+}
+div.maximize.open {
+  display: block;
+}
+div.maximize span.maximize-close {
+  position: absolute;
+  top: 0.6rem;
+  right: 0.6rem;
+}
+div.maximize div.maximize-content {
+  width: 100%;
+  height: 100%;
+}
+div.maximize div.maximize-content svg {
+  display: block;
+  width: 100%;
+  height: 100%;
+  max-width: none;
+}
+html.maximized {
+  overflow: hidden;
+}
+@media print {
+  span.maximize-controls,
+  div.maximize {
+    display: none;
+  }
+}
 /*  the connection status tab of the live preview (screen-only): the
     bottommost tab riding right of the brand bar below the table of
     contents tab (sized like the search tab, fixed independent of the
@@ -1204,6 +1285,7 @@ span.theme-dark-only {
 }
 /*  the diagrams, rationales, keywords, and code spans  */
 div.diagram {
+  position: relative;
   margin: 1rem 0;
 }
 div.diagram svg {

package/dst/specbook-export-html.js

@@ -60,6 +60,7 @@ const templates = {
                 {% if Document.search %}<script>{{ Document.search }}</script>{% endif %}
                 <script>{{ Document.progress }}</script>
                 <script>{{ Document.fold }}</script>
+                <script>{{ Document.maximize }}</script>
                 {% if Document.tocpanel %}<script>{{ Document.tocscript }}</script>{% endif %}
                 {% if Document.info %}<script>{{ Document.info }}</script>{% endif %}
                 {% if Document.realtime %}<script class="realtime">{{ Document.realtime }}</script>{% endif %}
@@ -654,6 +655,110 @@ const foldScript = textframe `
 
     })()
 `;
+/*  the client-side script of the diagram maximization: it attaches two
+    controls to the top right corner of every diagram, revealed by the
+    stylesheet while the diagram is hovered, which maximize the diagram
+    temporarily in a single shared overlay covering the viewport (the
+    SVG cloned into it and fitted by the stylesheet), the second one
+    additionally taking the overlay into the browser fullscreen (a
+    refused request leaves the viewport overlay), where the close mark
+    at the top right corner, "Escape", a click beside the diagram, and
+    a jump through a node hyperlink close the overlay again (a browser
+    leaving the fullscreen on its own closes it, too). The script runs
+    at the end of the body, as the diagrams it decorates have to exist
+    already, and a live preview body swap replaces the overlay and the
+    body-bound listeners along with the body, while the document-bound
+    fullscreen listener retires itself  */
+const maximizeScript = textframe `
+    (function () {
+        /*  an icon control drawn like the tab icons  */
+        const svgNS = "http://www.w3.org/2000/svg"
+        const mark = (name, title, paths) => {
+            const span = document.createElement("span")
+            span.className = name
+            span.title = title
+            const svg = document.createElementNS(svgNS, "svg")
+            svg.setAttribute("viewBox", "0 0 24 24")
+            svg.setAttribute("fill", "none")
+            svg.setAttribute("stroke", "currentColor")
+            svg.setAttribute("stroke-width", "2.5")
+            svg.setAttribute("stroke-linecap", "round")
+            svg.setAttribute("stroke-linejoin", "round")
+            for (const d of paths) {
+                const path = document.createElementNS(svgNS, "path")
+                path.setAttribute("d", d)
+                svg.appendChild(path)
+            }
+            span.appendChild(svg)
+            return span
+        }
+
+        /*  the shared overlay: the close mark plus the content holding
+            the clone of the maximized diagram  */
+        const overlay = document.createElement("div")
+        overlay.className = "maximize"
+        const close   = mark("maximize-close", "close the maximized diagram",
+            [ "M18 6 6 18", "M6 6l12 12" ])
+        const content = document.createElement("div")
+        content.className = "maximize-content"
+        overlay.append(close, content)
+        document.body.appendChild(overlay)
+
+        /*  open the overlay onto a diagram, optionally in the browser
+            fullscreen, and close it again (leaving the fullscreen, too),
+            with the document scrolling locked while it is open  */
+        const open = (diagram, fullscreen) => {
+            const svg = diagram.querySelector("svg").cloneNode(true)
+            svg.removeAttribute("style")
+            content.replaceChildren(svg)
+            overlay.classList.add("open")
+            document.documentElement.classList.add("maximized")
+            if (fullscreen)
+                overlay.requestFullscreen().catch(() => {})
+        }
+        const shut = () => {
+            overlay.classList.remove("open")
+            document.documentElement.classList.remove("maximized")
+            content.replaceChildren()
+            if (document.fullscreenElement === overlay)
+                document.exitFullscreen().catch(() => {})
+        }
+        close.addEventListener("click", shut)
+        overlay.addEventListener("click", (event) => {
+            /*  a node hyperlink navigates on its own, the overlay just
+                gets out of its way, while a click beside the diagram
+                closes the overlay alone  */
+            if (event.target.closest("a") !== null || event.target.closest("svg") === null)
+                shut()
+        })
+        document.body.addEventListener("keydown", (event) => {
+            if (event.key === "Escape" && overlay.classList.contains("open"))
+                shut()
+        })
+        const left = () => {
+            if (!overlay.isConnected)
+                document.removeEventListener("fullscreenchange", left)
+            else if (document.fullscreenElement === null && overlay.classList.contains("open"))
+                shut()
+        }
+        document.addEventListener("fullscreenchange", left)
+
+        /*  attach the two controls to every diagram  */
+        document.querySelectorAll("article div.diagram, nav.doc div.diagram").forEach((diagram) => {
+            const controls = document.createElement("span")
+            controls.className = "maximize-controls"
+            const view = mark("maximize-view", "maximize this diagram in the viewport",
+                [ "M15 3h6v6", "M21 3l-7 7", "M9 21H3v-6", "M3 21l7-7" ])
+            const full = mark("maximize-full", "maximize this diagram in fullscreen",
+                [ "M3 7V5a2 2 0 0 1 2-2h2", "M17 3h2a2 2 0 0 1 2 2v2",
+                  "M21 17v2a2 2 0 0 1-2 2h-2", "M7 21H5a2 2 0 0 1-2-2v-2" ])
+            view.addEventListener("click", () => { open(diagram, false) })
+            full.addEventListener("click", () => { open(diagram, true) })
+            controls.append(view, full)
+            diagram.appendChild(controls)
+        })
+    })()
+`;
 /*  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
@@ -1661,6 +1766,7 @@ export const renderHtml = async (specification, config, tocPages, css, realtime
                 search: safe(searchScript()),
                 progress: safe(scrollProgressScript),
                 fold: safe(foldScript),
+                maximize: safe(maximizeScript),
                 info: info !== null ? safe(infoScript(info, spec ?? {})) : "",
                 realtime: realtime ? safe(realtimeScript) : "",
                 toc: entries.length > 0 ? safe(render("Toc", { Toc: { entries } })) : "",

package/dst/specbook-format.md

@@ -185,6 +185,7 @@ type SchemaGradiaConfig = Partial<{
     "grid-gap-horizontal":       number
     "grid-gap-vertical":         number
     "grid-node-width-equal":     boolean
+    "grid-node-height-equal":    boolean
 }>
 ```
 

package/dst/specbook-format.yaml

@@ -1239,7 +1239,27 @@
         type: graph
         nodes: "[[DM.ENTITY:*]]"
         edges: "[[RELATION:*]]"
+        nest:
+            properties:
+                -   GROUP
+        config:
+            graph-columns-max: 2
     children:
+        -   kind: GROUP
+            name: "[A-Z][a-zA-Z0-9]*"
+            desc: >
+                A named group of strongly related entities, carrying a Pascal-cased, 1-3 word long,
+                per-artifact unique name, distinct from the names of its entities (e.g. `Statistics`
+                for the snapshot entities, `Messages` for a message and its texts), and described by
+                a 1-sentence description ("what") plus a 1-sentence rationale ("why") of the
+                cohesion. A group is either an aggregate (a root entity with the part entities it
+                owns) or a subject area (entities sharing one concern), affects the overview diagram
+                only, where its entities are drawn next to each other inside a box, and carries no
+                semantics of its own: the relations between its entities stay explicit. The groups
+                are listed before the entities, and every entity belongs to at most one group.
+            optional: true
+            referenced:
+                -   "[[DM.ENTITY:*]]"
         -   kind: ENTITY
             name: "[A-Z][a-zA-Z0-9]*"
             desc: >
@@ -1281,6 +1301,13 @@
                         is anchored in the ubiquitous language and every term shows its data.
                     value: list([[TERM:*]])
                     optional: true
+                -   name: GROUP
+                    desc: >
+                        Reference to the DATA-MODEL group the entity belongs to, placing it next to
+                        the other entities of the group in the overview diagram; omitted for an
+                        entity standing on its own.
+                    value: "[[DM.GROUP:*]]"
+                    optional: true
             children:
                 -   kind: ATTRIBUTE
                     name: "[a-z][a-zA-Z0-9]*"
@@ -2872,7 +2899,7 @@
             -   PRODUCT
         config:
             size-node-width-max: 440
-            grid-columns-max: 3
+            grid-columns-max: 2
     children:
         -   kind: TIER
             desc: |

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":                                "@rse/specbook",
-    "version":                             "1.2.7",
+    "version":                             "1.2.9",
     "publishConfig":                       { "access": "public" },
     "description":                         "Markdown-based Specification Format (API, CLI and MCP service)",
     "license":                             "Apache-2.0",
@@ -17,16 +17,16 @@
     },
     "files":                               [ "dst" ],
     "dependencies": {
-        "marked":                          "18.0.11",
+        "marked":                          "18.0.12",
         "marked-smartypants":              "1.1.12",
         "yaml":                            "2.9.0",
         "json5":                           "2.2.3",
         "pdf-lib":                         "1.17.1",
         "subset-font":                     "2.7.0",
         "@rse/mrcs":                       "0.9.2",
-        "@rse/gradia":                     "1.2.1",
+        "@rse/gradia":                     "1.2.3",
         "@toon-format/toon":               "4.1.1",
-        "valibot":                         "1.4.2",
+        "valibot":                         "1.5.0",
         "nunjucks":                        "3.2.4",
         "@rse/nunjucks-addons":            "2.2.0",
         "textframe":                       "1.2.1",
@@ -42,19 +42,19 @@
         "fastify":                         "5.12.3",
         "@fastify/websocket":              "11.3.0",
         "@modelcontextprotocol/sdk":       "1.30.0",
-        "zod":                             "4.5.4"
+        "zod":                             "4.6.1"
     },
     "devDependencies": {
         "chokidar-cli":                    "3.0.0",
         "eslint":                          "10.9.0",
         "@eslint/js":                      "10.0.1",
-        "typescript-eslint":               "8.69.0",
+        "typescript-eslint":               "8.70.0",
         "eslint-plugin-promise":           "7.3.0",
         "neostandard":                     "0.14.0-next.1",
         "globals":                         "17.12.0",
         "markdownlint":                    "0.41.1",
         "markdownlint-cli2":               "0.23.2",
-        "@types/node":                     "26.4.1",
+        "@types/node":                     "26.5.0",
         "@types/subset-font":              "2.3.0",
         "@types/nunjucks":                 "3.2.6",
         "@types/ws":                       "8.18.1",