@rse/specbook 1.2.4 → 1.2.5

package/dst/specbook-export-html.js

@@ -43,6 +43,13 @@ const templates = {
                         <span class="search-clear" id="search-clear" title="clear search">&#x00D7;</span>
                     </div>
                 </div>
+                <div class="fold-switch">
+                    <div class="fold-toggle" title="toggle folding controls"><svg class="fold-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="M7 3.5l5 5 5-5"/><path d="M7 20.5l5-5 5 5"/></svg></div>
+                    <div class="fold-controls">
+                        <div class="fold-diagrams" title="fold/unfold all diagrams"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><circle cx="5.5" cy="5.5" r="3"/><circle cx="18.5" cy="5.5" r="3"/><circle cx="12" cy="18.5" r="3"/><path d="M7.3 8.1 10.6 15.9"/><path d="M16.7 8.1 13.4 15.9"/></svg></div>
+                        <div class="fold-texts" title="fold/unfold all cell texts"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="M4.5 7V4.5h15V7"/><path d="M12 4.5v15"/><path d="M8.5 19.5h7"/></svg></div>
+                    </div>
+                </div>
                 <div class="scroll-progress" title="scroll to top"><svg class="scroll-ring" viewBox="0 0 44 44" fill="none" stroke-width="2.5"><circle class="scroll-todo" cx="22" cy="22" r="20"/><circle class="scroll-done" cx="22" cy="22" r="20" stroke-linecap="round" pathLength="1" stroke-dasharray="1" stroke-dashoffset="1"/></svg><svg class="scroll-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="M12 19V5"/><path d="M5 12l7-7 7 7"/></svg></div>
                 {{ Document.tocpanel }}
                 {{ Document.titlepage }}
@@ -51,6 +58,7 @@ const templates = {
                 {{ Document.artifacts }}
                 {% if Document.search %}<script>{{ Document.search }}</script>{% endif %}
                 <script>{{ Document.progress }}</script>
+                <script>{{ Document.fold }}</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 %}
@@ -151,7 +159,7 @@ const templates = {
     `,
     /*  <Properties/>  */
     "Properties": textframe `
-        <table class="props">
+        <table class="props"{% if Fold %} data-fold-height="{{ Fold }}"{% endif %}>
             {% for property in Properties %}
             <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 %}
@@ -172,7 +180,7 @@ const templates = {
     `,
     /*  <Table/>  */
     "Table": textframe `
-        <table class="objects">
+        <table class="objects"{% if Table.fold %} data-fold-height="{{ Table.fold }}"{% endif %}>
             <thead>
                 <tr>
                     <th class="object-kind"><span{% if Table.info %} data-info="{{ Table.info }}" data-info-path="{{ Table.infopath }}"{% endif %}>{{ Table.head }}</span></th>
@@ -193,7 +201,7 @@ const templates = {
     `,
     /*  <TableChunked/>  */
     "TableChunked": textframe `
-        <table class="objects">
+        <table class="objects"{% if Table.fold %} data-fold-height="{{ Table.fold }}"{% endif %}>
             <thead>
                 <tr>
                     <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>
@@ -382,6 +390,255 @@ const scrollProgressScript = textframe `
         update()
     })()
 `;
+/*  the client-side script of the folding: it wraps every diagram of the
+    content into a fold container carrying a chevron mark at its top
+    left corner, folds the
+    text of every table cell towering over the other cells of its row
+    behind a chevron mark of its own, and lets the two
+    controls of the fold tab fold and unfold all diagrams and all cell
+    texts at once, with their state persisted across page loads and
+    their icons (plus the tab icon) marked while anything of their kind
+    is folded. The script
+    runs at the end of the body, as the content it wraps has to exist
+    already, and a live preview body swap replaces the containers and
+    their listeners along with the body  */
+const foldScript = textframe `
+    (function () {
+        const tab = document.querySelector("div.fold-switch")
+        if (tab === null)
+            return
+        const controls = { diagram: tab.querySelector("div.fold-diagrams"),
+            text: tab.querySelector("div.fold-texts") }
+
+        /*  let the fold icon slide the two controls out of the tab (and
+            back in again), remembering the choice across page loads  */
+        try { if (localStorage.getItem("specbook-fold") === "open") tab.classList.add("open") }
+        catch { /*  an inaccessible storage just means no stored state  */ }
+        tab.querySelector("div.fold-toggle").addEventListener("click", () => {
+            tab.classList.toggle("open")
+            try { localStorage.setItem("specbook-fold", tab.classList.contains("open") ? "open" : "closed") }
+            catch { /*  an inaccessible storage just loses the state  */ }
+        })
+
+        /*  the default percentage by which the text of a table cell may
+            exceed the height of every other cell of its row before it
+            folds, overridden per object kind by the "data-fold-height"
+            attribute the schema configuration puts onto its table  */
+        const cellHeight = 40
+
+        /*  the chevron mark of a foldable element, rotated by the
+            stylesheet while the element is folded  */
+        const svgNS = "http://www.w3.org/2000/svg"
+        const mark = (name, title) => {
+            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")
+            const path = document.createElementNS(svgNS, "path")
+            path.setAttribute("d", "M5 9l7 7 7-7")
+            svg.appendChild(path)
+            span.appendChild(svg)
+            return span
+        }
+
+        /*  wrap every diagram into its fold container, carrying the
+            chevron mark plus the muted placeholder the diagram leaves
+            behind while folded, which is the very icon of its tab
+            control  */
+        const folds = { diagram: [], text: [] }
+        document.querySelectorAll("article div.diagram, nav.doc div.diagram").forEach((el) => {
+            const fold = document.createElement("div")
+            fold.className = "fold"
+            el.parentNode.insertBefore(fold, el)
+            const chevron = mark("fold-mark", "fold/unfold this diagram")
+            const label   = document.createElement("span")
+            label.className = "fold-label"
+            label.appendChild(controls.diagram.querySelector("svg").cloneNode(true))
+            fold.append(chevron, label, el)
+            chevron.addEventListener("click", () => {
+                fold.classList.toggle("folded")
+                sync()
+            })
+            folds.diagram.push(fold)
+        })
+
+        /*  the rendered height of the content of a table cell, or of its
+            leading part up to a word position: a cell box itself always
+            spans the whole row, so only a range over the content
+            measures the text  */
+        const range = document.createRange()
+        const height = (cell, upto) => {
+            if (upto === undefined)
+                range.selectNodeContents(cell)
+            else {
+                range.setStart(cell, 0)
+                range.setEnd(upto.node, upto.offset)
+            }
+            return range.getBoundingClientRect().height
+        }
+
+        /*  the word positions of a table cell, each right behind one word  */
+        const positions = (cell) => {
+            const walker = document.createTreeWalker(cell, NodeFilter.SHOW_TEXT)
+            const list = []
+            let node
+            while ((node = walker.nextNode()) !== null) {
+                const regex = /\\S+/g
+                let m
+                while ((m = regex.exec(node.nodeValue ?? "")) !== null)
+                    list.push({ node, offset: m.index + m[0].length })
+            }
+            return list
+        }
+
+        /*  a cell taking part in the comparison of its row: one with
+            content of its own, i.e. neither empty (a not given property
+            draws its marker through the stylesheet alone) nor holding
+            further cells (a chunked or nested table, whose own cells are
+            compared instead) nor a diagram (which folds on its own and
+            whose SVG text cannot carry the wrapper of a hidden
+            remainder)  */
+        const candidate = (cell) =>
+            cell.querySelector("td") === null
+            && cell.querySelector("div.diagram") === null
+            && (cell.textContent.trim() !== "" || cell.querySelector("img") !== null)
+
+        /*  decide which table cells fold: one which is taller than the
+            configured percentage above every other cell of its row (the
+            leading name column of a compact table excluded, as it is no
+            text of its own). All rows are measured before the first cut,
+            as every cut shifts the layout of the ones still to come  */
+        const cuts = []
+        document.querySelectorAll("article table tr").forEach((row) => {
+            const table = row.closest("table")
+            let cells = Array.from(row.children).filter((el) => el.tagName === "TD")
+            if (!table.classList.contains("chunks"))
+                cells = cells.slice(1)
+            cells = cells.filter(candidate)
+            if (cells.length < 2)
+                return
+            const configured = row.closest("table[data-fold-height]")
+            const percent = Number(configured?.getAttribute("data-fold-height")) || cellHeight
+            const heights = cells.map((cell) => height(cell))
+            cells.forEach((cell, i) => {
+                const other = Math.max(...heights.filter((_, j) => j !== i))
+                const limit = other * (1 + percent / 100)
+                if (heights[i] > limit)
+                    cuts.push({ cell, limit, full: heights[i] })
+            })
+        })
+
+        /*  hide a node of the folded remainder of a table cell: an
+            element carries the class itself, a text node gets wrapped  */
+        const rest = (node) => {
+            if (node.nodeType === Node.ELEMENT_NODE)
+                node.classList.add("fold-rest")
+            else if (node.nodeType === Node.TEXT_NODE) {
+                const span = document.createElement("span")
+                span.className = "fold-rest"
+                node.parentNode.insertBefore(span, node)
+                span.appendChild(node)
+            }
+        }
+
+        /*  the minimum percentage of its own height a cell has to gain
+            by folding, as hiding less than that is no visible relief
+            and only costs the reader a chevron to click (measured after
+            the cut, as the chevron itself can claim a line of its own)  */
+        const cellGain = 25
+
+        /*  fold the decided cells back onto their height limit: the last
+            word position still fitting is found by a binary search over
+            the measured word positions, the text node is split there and
+            the chevron mark takes its place, followed by the remainder
+            hidden up the ancestor chain of the cell  */
+        for (const cut of cuts) {
+            const list = positions(cut.cell)
+            if (list.length === 0)
+                continue
+            let lo = 0
+            let hi = list.length - 1
+            while (lo < hi) {
+                const mid = Math.ceil((lo + hi) / 2)
+                if (height(cut.cell, list[mid]) <= cut.limit)
+                    lo = mid
+                else
+                    hi = mid - 1
+            }
+            const tail    = list[lo].node.splitText(list[lo].offset)
+            const chevron = mark("fold-more", "fold/unfold the remaining text")
+            tail.parentNode.insertBefore(chevron, tail)
+            let current = chevron
+            while (current !== cut.cell) {
+                let next = current.nextSibling
+                while (next !== null) {
+                    const following = next.nextSibling
+                    rest(next)
+                    next = following
+                }
+                current = current.parentNode
+            }
+            /*  the gain is measured on the applied fold, as only that
+                one tells the real one, and a fold gaining less than the
+                minimum share is taken back again, which the chevron
+                alone has to leave behind, as the hidden remainder stays
+                inert without the class -- which a kept fold sheds
+                again, too, as every cell starts out unfolded  */
+            cut.cell.classList.add("folded")
+            const gained = height(cut.cell) <= cut.full * (1 - cellGain / 100)
+            cut.cell.classList.remove("folded")
+            if (!gained) {
+                chevron.remove()
+                continue
+            }
+            folds.text.push(cut.cell)
+            chevron.addEventListener("click", (event) => {
+                /*  the cut can land inside a hyperlink, whose navigation
+                    the chevron has to suppress for its own click alone,
+                    so the remaining link text still follows the link  */
+                event.preventDefault()
+                cut.cell.classList.toggle("folded")
+                sync()
+            })
+        }
+
+        /*  mark the control of a kind while anything of that kind is
+            folded, and the tab itself while any kind at all is  */
+        const sync = () => {
+            let any = false
+            for (const kind of Object.keys(folds)) {
+                const folded = folds[kind].some((fold) => fold.classList.contains("folded"))
+                controls[kind].classList.toggle("folded", folded)
+                any ||= folded
+            }
+            tab.classList.toggle("folded", any)
+        }
+        for (const kind of Object.keys(folds)) {
+            /*  without a stored state the rendered one stands, which is
+                everything unfolded  */
+            let stored = null
+            try { stored = localStorage.getItem("specbook-fold-" + kind) }
+            catch { /*  an inaccessible storage just means no stored state  */ }
+            if (stored !== null)
+                folds[kind].forEach((fold) => { fold.classList.toggle("folded", stored === "folded") })
+            controls[kind].addEventListener("click", () => {
+                const all = !folds[kind].every((fold) => fold.classList.contains("folded"))
+                folds[kind].forEach((fold) => { fold.classList.toggle("folded", all) })
+                try { localStorage.setItem("specbook-fold-" + kind, all ? "folded" : "unfolded") }
+                catch { /*  an inaccessible storage just loses the state  */ }
+                sync()
+            })
+        }
+        sync()
+
+    })()
+`;
 /*  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
@@ -470,6 +727,7 @@ const tocPanelScript = textframe `
                 && event.target.closest("div.search")          === null
                 && event.target.closest("div.theme-switch")    === null
                 && event.target.closest("div.info-switch")     === null
+                && event.target.closest("div.fold-switch")     === null
                 && event.target.closest("div.realtime-status") === null)
                 toggle(false)
         }
@@ -1051,6 +1309,7 @@ const renderTable = (children, maxColumns) => {
                 infopath: infoPathOf(children[0], false),
                 keys,
                 desc,
+                fold: formatOf(children[0])?.maxCellHeight,
                 /*  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)),
@@ -1074,6 +1333,7 @@ const renderTable = (children, maxColumns) => {
             head: children[0].kind !== "" ? children[0].kind : "Name",
             info: infoKeyOf(children[0]),
             infopath: infoPathOf(children[0], false),
+            fold: formatOf(children[0])?.maxCellHeight,
             width: Math.round(100 / maxColumns),
             rows: children.map((child, i) => scoped(child, () => {
                 const cells = keys.map((key) => ({ key, desc: false, span: 1,
@@ -1122,7 +1382,8 @@ const renderObject = (object, level, concise) => {
             name: inline(object.name),
             diagram: diagramOf(object),
             properties: properties.length > 0 ?
-                safe(render("Properties", { Properties: inlineProperties(object, properties) })) : "",
+                safe(render("Properties", { Properties: inlineProperties(object, properties),
+                    Fold: formatOf(object)?.maxCellHeight })) : "",
             description: object.description !== undefined ?
                 safe(renderDescription(object.description)) : "",
             children: safe(renderChildren(object, level + 1, concise))
@@ -1357,6 +1618,7 @@ export const renderHtml = async (specification, config, tocPages, css, realtime
                     safe(renderTitlePage(title, formatDate(created), formatDate(modified))) : "",
                 search: safe(searchScript()),
                 progress: safe(scrollProgressScript),
+                fold: safe(foldScript),
                 info: info !== null ? safe(infoScript(info, spec ?? {})) : "",
                 realtime: realtime ? safe(realtimeScript) : "",
                 toc: entries.length > 0 ? safe(render("Toc", { Toc: { entries } })) : "",

package/dst/specbook-export-pdf.js

@@ -133,11 +133,36 @@ const drawBrandBar = async (doc, accent) => {
     Chrome has to actually launch it and as the export preflight and the
     renderer both ask for the very same browser  */
 let browserOptions;
-/*  resolve the browser printing the PDF: the downloaded Playwright
-    Chromium is a plain file check, while a system-installed Google
-    Chrome is only detectable by launching it  */
+/*  the remedy of an unavailable Playwright Chromium, shared by the
+    fallback notice and the missing-browser error, as both have to point
+    at the very same one-time command  */
+const chromiumRemedy = `run "${literal("npx playwright install chromium")}" once to download the Playwright Chromium`;
+/*  resolve the browser printing the PDF: an explicitly configured one
+    wins, then the downloaded Playwright Chromium as a plain file check,
+    while a system-installed Google Chrome is only detectable by
+    launching it  */
 const resolveBrowser = async (verbose) => {
     const { chromium } = await import("playwright");
+    /*  an explicitly configured browser is taken as an executable path
+        once it carries a path separator and as a Playwright channel
+        name otherwise, and it never falls back onto another browser, as
+        an explicit choice has to be either honored or reported  */
+    const configured = process.env.SPECBOOK_BROWSER ?? "";
+    if (configured !== "") {
+        const options = /[\\/]/.test(configured) ?
+            { executablePath: configured } : { channel: configured };
+        try {
+            const browser = await chromium.launch(options);
+            await browser.close();
+        }
+        catch (err) {
+            throw new Error(`the browser "${literal(configured)}" configured by ` +
+                `"${literal("SPECBOOK_BROWSER")}" failed to launch`, { cause: err });
+        }
+        verbose(`using the browser "${literal(configured)}" configured by ` +
+            `"${literal("SPECBOOK_BROWSER")}"`);
+        return options;
+    }
     let executable = "";
     try {
         executable = chromium.executablePath();
@@ -151,7 +176,7 @@ const resolveBrowser = async (verbose) => {
         const chrome = await chromium.launch({ channel: "chrome" });
         await chrome.close();
         verbose("Playwright Chromium unavailable -- falling back to the " +
-            "system-installed Google Chrome", "notice");
+            `system-installed Google Chrome (${chromiumRemedy})`, "notice");
         return { channel: "chrome" };
     }
     catch {
@@ -166,8 +191,7 @@ export const requireBrowser = async (verbose) => {
     const options = await browserOptions;
     if (options === undefined)
         throw new Error("the PDF export requires a Chromium-class browser, but neither the " +
-            "Playwright Chromium nor a system-installed Google Chrome was found -- run " +
-            `"${literal("npx playwright install chromium")}" once to download the Playwright Chromium`);
+            `Playwright Chromium nor a system-installed Google Chrome was found -- ${chromiumRemedy}`);
     return options;
 };
 /*  the bound of the ToC page number fixpoint iteration, as the page

package/dst/specbook-format-schema.d.ts

@@ -37,6 +37,13 @@ export type SchemaDiagramCenterEdges = {
     both?: string;
     labeled?: string;
 };
+export type SchemaDiagramNest = {
+    properties?: string[];
+    parent?: boolean;
+    kind?: boolean;
+    layout?: "graph" | "hub" | "grid";
+    crossing?: "nodes" | "target" | "both";
+};
 export type SchemaDiagram = {
     type?: "graph" | "hub" | "grid";
     nodes?: string;
@@ -53,12 +60,15 @@ export type SchemaDiagram = {
     onlyConnected?: boolean;
     collapse?: boolean;
     qualified?: boolean;
+    ordered?: boolean;
+    nest?: SchemaDiagramNest;
     properties?: string[];
     config?: Partial<GradiaConfig>;
 };
 export type SchemaFormat = {
     type?: "auto" | "complex" | "concise";
     maxTableColumns?: number;
+    maxCellHeight?: number;
     withUnusedProps?: boolean;
 };
 export type SchemaProperty = {

package/dst/specbook-format-schema.js

@@ -50,6 +50,13 @@ const SchemaDiagramCenterEdges = v.strictObject({
     both: v.optional(v.string()),
     labeled: v.optional(v.string())
 });
+const SchemaDiagramNest = v.strictObject({
+    properties: v.optional(v.array(v.string())),
+    parent: v.optional(v.boolean()),
+    kind: v.optional(v.boolean()),
+    layout: v.optional(v.picklist(["graph", "hub", "grid"])),
+    crossing: v.optional(v.picklist(["nodes", "target", "both"]))
+});
 const SchemaDiagram = v.strictObject({
     type: v.optional(v.picklist(["graph", "hub", "grid"])),
     nodes: v.optional(v.string()),
@@ -66,12 +73,15 @@ const SchemaDiagram = v.strictObject({
     onlyConnected: v.optional(v.boolean()),
     collapse: v.optional(v.boolean()),
     qualified: v.optional(v.boolean()),
+    ordered: v.optional(v.boolean()),
+    nest: v.optional(SchemaDiagramNest),
     properties: v.optional(v.array(v.string())),
     config: v.optional(SchemaDiagramConfig)
 });
 const SchemaFormat = v.strictObject({
     type: v.optional(v.picklist(["auto", "complex", "concise"])),
     maxTableColumns: v.optional(v.pipe(v.number(), v.integer(), v.minValue(2))),
+    maxCellHeight: v.optional(v.pipe(v.number(), v.integer(), v.minValue(0))),
     withUnusedProps: v.optional(v.boolean())
 });
 const SchemaObject = v.strictObject({

package/dst/specbook-format.md

@@ -123,6 +123,7 @@ type SchemaDiagram = {
 type SchemaFormat = {
     type?:             "auto" | "complex" | "concise"
     maxTableColumns?:  number
+    maxCellHeight?:    number
     withUnusedProps?:  boolean
 }
 type SchemaProperty = {
@@ -350,7 +351,7 @@ type SchemaGradiaConfig = Partial<{
 
 -   `SchemaDiagram.deep?: boolean`:
     whether the references of the descendants of a node count as its own,
-    lifted to their nearest node and counted as the arity (default: `false`),
+    counted as the arity (default: `false`),
     BECAUSE the relations between coarse objects live in their fine parts
 
 -   `SchemaDiagram.onlyConnected?: boolean`:
@@ -365,6 +366,40 @@ type SchemaGradiaConfig = Partial<{
     whether every node is labeled with its kind (default: `false`),
     BECAUSE names alone are ambiguous across multiple object kinds
 
+-   `SchemaDiagram.ordered?: boolean`:
+    whether the nodes are placed in document order instead of by the
+    layered layout, the top-level ones stacked top-down and the members
+    of a container lined up left-to-right (default: `false`),
+    BECAUSE in a coarse-to-fine specification the references then all
+    point backward, i.e. upward
+
+-   `SchemaDiagram.nest?: SchemaDiagramNest`:
+    nesting of the nodes into container nodes,
+    BECAUSE a containment drawn as a box beats one drawn as an edge
+
+-   `SchemaDiagramNest.properties?: string[]`:
+    properties whose single referenced object is the container of a node,
+    BECAUSE a `PART-OF` or `TIER` reference is a containment, not a relation
+
+-   `SchemaDiagramNest.parent?: boolean`:
+    whether the parent object is the container of a node (default: `false`),
+    BECAUSE the nesting of the objects is a containment, too
+
+-   `SchemaDiagramNest.kind?: boolean`:
+    whether a synthetic container per object kind holds the nodes
+    (default: `false`),
+    BECAUSE a kind is a grouping no object models
+
+-   `SchemaDiagramNest.layout?: "graph" | "hub" | "grid"`:
+    shape the members of every container are laid out with
+    (default: the diagram type),
+    BECAUSE the inside of a container may tell a different story than the whole
+
+-   `SchemaDiagramNest.crossing?: "nodes" | "target" | "both"`:
+    ends of a boundary-crossing edge lifted onto the containers
+    (default: `nodes`, i.e. none),
+    BECAUSE a bundle of references into a container reads as one edge onto it
+
 -   `SchemaDiagram.properties?: string[]`:
     property names attached to the nodes as key/value annotations,
     BECAUSE the node name alone rarely makes the nodes comparable
@@ -385,6 +420,10 @@ type SchemaGradiaConfig = Partial<{
     maximum column count of the table of the kind (default: `4`),
     BECAUSE the fixed print/PDF page width bounds the table width
 
+-   `SchemaFormat.maxCellHeight?: number`:
+    percent a table cell may tower over its row before it folds (default: `40`),
+    BECAUSE a cell of rich prose otherwise dwarfs the whole table
+
 -   `SchemaFormat.withUnusedProps?: boolean`:
     whether unused properties still render (default: `false`),
     BECAUSE empty entries are noise, unless the gap is the message
@@ -474,9 +513,10 @@ type SchemaGradiaConfig = Partial<{
 
 The edges are derived from the `[[xxx]]` references of the node objects
 -- from their property values only, or, with `links: all`, from their
-descriptions as well. With `deep: true` the references of all
-descendants of a node object count as its own, every referenced object
-is lifted to its nearest ancestor-or-self within the node set, and the
+descriptions as well. Every referenced object is lifted to its nearest
+ancestor-or-self within the node set, so a reference onto the scenario
+of a use case yields an edge onto the use case. With `deep: true` the
+references of all descendants of a node object count as its own and the
 number of references behind an edge becomes its arity, so a diagram of
 coarse objects (like the artifacts of a whole specification) shows the
 relations living in their fine-grained parts. With `labeled: true` an
@@ -527,6 +567,34 @@ nodes as key/value annotations (with every `[[xxx]]` reference stripped
 to its target object name), and `config` passes arbitrary Gradia
 rendering options (e.g. `grid-columns-max: 5`) through to the diagram.
 
+`ordered` replaces the layered layout of a `graph` by the document
+order of the objects: the top-level nodes stack top-down in that order
+(a synthetic container at the position of its first member), while the
+members of a container line up left-to-right in it, wrapped by the
+Gradia option `graph-columns-max`, so the references of a coarse-to-fine
+specification all point backward, i.e. upward or leftward.
+
+`nest` nests the nodes into *container* nodes, drawn as boxes around
+their members with the edges crossing the box borders: the first of its
+`properties` carrying exactly one resolvable reference names the
+container of a node (a container outside the node set is added to it,
+labeled and linked like a node, and nested on its own in turn, so a
+`NODE` sits in its `TIER` and the tier in the tier it is `PART-OF`),
+else with `parent: true` the parent object is the container when part
+of the node set, else with `kind: true` a synthetic container per object
+kind is. An edge between a container and one of its own members is
+dropped, as the nesting already shows it, `layout` selects the shape
+the members of every container are laid out with (default: the diagram
+type), a `hub` carries no containers, as every container would need a
+primary node of its own, and a node nested into itself or into a cycle
+is reported. With `crossing: target` an edge crossing a container
+boundary ends at the outermost container of its target not enclosing
+its source, too, and with `crossing: both` it also starts at the
+corresponding container of its source, where the edges coinciding
+afterwards merge into one with their arities summed, so the edges
+inside a container stay node-to-node while the bundles of references
+into a container become single edges onto it.
+
 ### Format
 
 An object kind can furthermore carry a `format` field, which controls
@@ -542,7 +610,10 @@ Inside a `concise` table, unconfigured child kinds implicitly stay
 an explicitly configured `type` is always honored, even a `complex`
 rendering pressed into a cell. `maxTableColumns` (default: `4`) bounds
 the columns of the compact table of the kind (a wider group chunks
-its properties into embedded per-object tables), and `withUnusedProps`
+its properties into embedded per-object tables), `maxCellHeight`
+(default: `40`) is the percentage a table cell of the kind may exceed
+the height of every other non-empty cell of its row before the HTML
+export folds its remaining text away, and `withUnusedProps`
 (default: `false`) unconditionally renders the defined but unused
 properties of that kind, as property table lines or table columns. In
 the HTML/PDF export, a property absent from an object shows an "empty