@rse/specbook 1.2.2 → 1.2.4

package/dst/specbook-export-html.js

@@ -43,12 +43,14 @@ const templates = {
                         <span class="search-clear" id="search-clear" title="clear search">&#x00D7;</span>
                     </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 }}
                 {{ Document.toc }}
                 {{ Document.doc }}
                 {{ Document.artifacts }}
                 {% if Document.search %}<script>{{ Document.search }}</script>{% endif %}
+                <script>{{ Document.progress }}</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 %}
@@ -120,7 +122,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.childs }}</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-path="{{ entry.specpath }}"{% endif %}>{{ entry.name }}</span></span></a>{{ entry.children }}</li>
             {% endfor %}
         </ul>
     `,
@@ -144,7 +146,7 @@ const templates = {
             {{ Object.diagram }}
             {{ Object.properties }}
             {{ Object.description }}
-            {{ Object.childs }}
+            {{ Object.children }}
         </section>
     `,
     /*  <Properties/>  */
@@ -251,8 +253,8 @@ const placeholderStylesheet = textframe `
     div.placeholder { position: absolute; top: 50%; left: 0; right: 0;
         transform: translateY(-50%); text-align: center; opacity: 0.6 }
 `;
-/*  the client-side script of the live preview: it connects back to the
-    own page over WebSocket (the URL scheme "http"/"https" replaced with
+/*  the client-side script of the live preview: it connects back to
+    its 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).
@@ -275,7 +277,11 @@ const realtimeScript = textframe `
                 icon.className = "realtime-status " + state
         }
         let blink = 0
+        let seq   = 0
         const update = async () => {
+            /*  a superseded update (an overlapping newer one started
+                meanwhile) is dropped, as its stale page could arrive last  */
+            const mine = ++seq
             let response
             try {
                 response = await fetch(window.location.pathname, { cache: "no-store" })
@@ -286,7 +292,10 @@ const realtimeScript = textframe `
             }
             if (!response.ok)
                 return
-            const doc = new DOMParser().parseFromString(await response.text(), "text/html")
+            const html = await response.text()
+            if (mine !== seq)
+                return
+            const doc = new DOMParser().parseFromString(html, "text/html")
             const x = window.scrollX
             const y = window.scrollY
             document.title = doc.title
@@ -332,6 +341,47 @@ const realtimeScript = textframe `
         connect()
     })()
 `;
+/*  the client-side script of the scroll progress meter: it drives the
+    DONE arc of the ring (through the dash offset of its unit-length
+    circle) with the scrolled fraction of the document, shows the meter
+    once the page is scrolled beyond 400px, and scrolls the page back
+    to the top on a click (stripping the URL hash, so a later reload
+    stays at the top). The updates are throttled onto animation frames,
+    and the window-bound listeners retire themselves once a live preview
+    body swap replaced the meter (whose fresh script re-attaches)  */
+const scrollProgressScript = textframe `
+    (function () {
+        const meter = document.querySelector("div.scroll-progress")
+        const ring  = meter.querySelector("circle.scroll-done")
+        let ticking = false
+        const update = () => {
+            ticking = false
+            if (!meter.isConnected) {
+                window.removeEventListener("scroll", schedule)
+                window.removeEventListener("resize", schedule)
+                return
+            }
+            const doc = document.documentElement
+            const max = doc.scrollHeight - doc.clientHeight
+            ring.setAttribute("stroke-dashoffset", String(1 - (max > 0 ? doc.scrollTop / max : 0)))
+            meter.classList.toggle("shown", doc.scrollTop > 400)
+        }
+        const schedule = () => {
+            if (!ticking) {
+                ticking = true
+                requestAnimationFrame(update)
+            }
+        }
+        meter.addEventListener("click", () => {
+            window.scrollTo({ top: 0, behavior: "smooth" })
+            if (window.location.hash)
+                history.replaceState(null, "", window.location.pathname + window.location.search)
+        })
+        window.addEventListener("scroll", schedule, { passive: true })
+        window.addEventListener("resize", schedule)
+        update()
+    })()
+`;
 /*  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
@@ -656,8 +706,19 @@ const env = new nunjucks.Environment(null, { autoescape: true });
 nunjucksAddons(env);
 /*  mark pre-rendered HTML as safe for template interpolation  */
 const safe = (html) => new nunjucks.runtime.SafeString(html);
+/*  the built-in Nunjucks templates compiled on first use, as
+    renderString() would re-compile a template on every single call
+    (i.e. for every rendered object, property table, and description)  */
+const compiled = new Map();
 /*  render one of the built-in Nunjucks templates with a context  */
-const render = (name, context) => env.renderString(templates[name], context);
+const render = (name, context) => {
+    let template = compiled.get(name);
+    if (template === undefined) {
+        template = new nunjucks.Template(templates[name], env, undefined, true);
+        compiled.set(name, template);
+    }
+    return template.render(context);
+};
 /*  the active per-document reference expander, fully-qualified
     anchor paths, member-carrying property value constraints, object
     schema nodes, pre-rendered diagram SVGs, description popup keys
@@ -739,7 +800,7 @@ const collectInfo = (nodes, prefix, keys, info) => {
         }
         if (entry.d !== undefined || entry.p !== undefined)
             info[path] = entry;
-        collectInfo(schema.childs ?? [], path, keys, info);
+        collectInfo(schema.children ?? [], path, keys, info);
     }
 };
 /*  inject the description popup maps into their client-side script ("<"
@@ -827,7 +888,7 @@ const collectSpec = (objects, spec) => {
             .trim();
         if (text !== "")
             spec[anchorOf(object)] = scoped(object, () => block(text, true).toString().trim());
-        collectSpec(object.childs, spec);
+        collectSpec(object.children, spec);
     }
 };
 /*  the literal members of an "enum(...)"/"tags(...)" expression, or
@@ -852,7 +913,7 @@ const collectMembers = (nodes, result) => {
                 /*  an invalid expression is the concern of lint  */
             }
         }
-        collectMembers(schema.childs ?? [], result);
+        collectMembers(schema.children ?? [], result);
     }
     return result;
 };
@@ -915,20 +976,20 @@ const effectiveProperties = (object) => {
     order (unknown keys appended in occurrence order), with
     "withUnusedProps" injecting the defined but still unused schema
     properties as additional columns  */
-const tableShape = (childs) => {
-    const used = [...new Set(childs.flatMap((child) => child.properties.map((property) => property.key)))];
-    const schema = schemas?.get(childs[0]);
+const tableShape = (children) => {
+    const used = [...new Set(children.flatMap((child) => child.properties.map((property) => property.key)))];
+    const schema = schemas?.get(children[0]);
     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) };
+    return { keys, desc: children.some((child) => child.description !== undefined || child.children.length > 0) };
 };
-/*  provide the childs of an object taking part in the regular document
+/*  provide the children 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 a single-kind group of childs collapses into the
+const flowChildren = (object) => object.children.filter((child) => !isTitleObject(child));
+/*  decide whether a single-kind group of children 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  */
@@ -936,12 +997,12 @@ const conciseGroup = (group, schemaMap, concise) => {
     const type = schemaMap?.get(group[0])?.format?.type ?? "auto";
     if (type !== "auto")
         return type === "concise";
-    return concise || group.every((child) => child.childs.length === 0);
+    return concise || group.every((child) => child.children.length === 0);
 };
-/*  group the childs of an object by their kind, preserving order  */
-const groupChilds = (childs) => {
+/*  group the children of an object by their kind, preserving order  */
+const groupChildren = (children) => {
     const groups = new Map();
-    for (const child of childs) {
+    for (const child of children) {
         const group = groups.get(child.kind);
         if (group === undefined)
             groups.set(child.kind, [child]);
@@ -950,21 +1011,21 @@ const groupChilds = (childs) => {
     }
     return [...groups.values()];
 };
-/*  render the childs of an object group-wise by kind: a concise group
+/*  render the children 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) ?
+const renderChildren = (object, level, concise) => groupChildren(flowChildren(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
+    object followed by its recursively rendered children (implicitly or
     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) : "";
-    html += renderChilds(child, 6, true);
+    html += renderChildren(child, 6, true);
     return html.trim() !== "" ? html : "<span class=\"value-absent\"></span>";
 };
 /*  the pre-rendered diagram of an object as an embeddable block
@@ -973,27 +1034,27 @@ const diagramOf = (object) => {
     const diagram = diagrams?.get(object);
     return diagram !== undefined ? safe(`<div class="diagram">${diagram}</div>`) : "";
 };
-/*  render a single-kind group of childs into one compact table:
+/*  render a single-kind group of children into one compact table:
     the name first, then the property columns, then the description;
     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);
-    const diagrams = childs.some((child) => diagramOf(child) !== "");
-    if (!diagrams && 1 + keys.length + (desc ? 1 : 0) <= maxColumns)
+const renderTable = (children, maxColumns) => {
+    const { keys, desc } = tableShape(children);
+    const diagrammed = children.some((child) => diagramOf(child) !== "");
+    if (!diagrammed && 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),
+                head: children[0].kind !== "" ? children[0].kind : "Name",
+                info: infoKeyOf(children[0]),
+                infopath: infoPathOf(children[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, i) => scoped(child, () => ({
+                rows: children.map((child, i) => scoped(child, () => ({
                     id: anchorOf(child),
                     paren: child.paren,
                     primary: child.primary,
@@ -1010,11 +1071,11 @@ const renderTable = (childs, maxColumns) => {
         with the last cell spanning the leftover columns of the final row  */
     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),
+            head: children[0].kind !== "" ? children[0].kind : "Name",
+            info: infoKeyOf(children[0]),
+            infopath: infoPathOf(children[0], false),
             width: Math.round(100 / maxColumns),
-            rows: childs.map((child, i) => scoped(child, () => {
+            rows: children.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)
@@ -1064,7 +1125,7 @@ const renderObject = (object, level, concise) => {
                 safe(render("Properties", { Properties: inlineProperties(object, properties) })) : "",
             description: object.description !== undefined ?
                 safe(renderDescription(object.description)) : "",
-            childs: safe(renderChilds(object, level + 1, concise))
+            children: safe(renderChildren(object, level + 1, concise))
         } }));
 };
 /*  format a timestamp as its calendar date in local time (the
@@ -1106,10 +1167,10 @@ const renderTitlePage = (object, created, modified) => {
 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
+/*  provide the children 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))
+const headingChildren = (object) => groupChildren(flowChildren(object))
     .filter((group) => !conciseGroup(group, schemas, false))
     .flat();
 /*  flatten the hierarchy of the rendered object headings (exactly like
@@ -1124,7 +1185,7 @@ const tocEntries = (objects, pages) => {
                 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(headingChildren(object), level + 1);
         }
     };
     collect(objects, 1);
@@ -1144,7 +1205,7 @@ const renderTocPanel = (objects, title, doc) => {
             spec: infoParents !== null ? anchorOf(object) : undefined,
             specpath: infoPathOf(object),
             name: inline(object.name),
-            childs: safe(entries(headingChilds(object)))
+            children: safe(entries(headingChildren(object)))
         })) });
     return render("TocPanel", { TocPanel: { title, doc, entries: safe(entries(objects)) } });
 };
@@ -1156,7 +1217,7 @@ export const htmlOutline = (specification, config) => {
     const entry = (object) => ({
         title: (object.kind !== "" ? `${object.kind}: ` : "") + plainText(object.name),
         anchor: paths.get(object) ?? object.id,
-        childs: groupChilds(flowChilds(object))
+        children: groupChildren(flowChildren(object))
             .filter((group) => !conciseGroup(group, schemaMap, false))
             .flatMap((group) => group.map(entry))
     });
@@ -1242,47 +1303,48 @@ export const renderHtml = async (specification, config, tocPages, css, realtime
     /*  the document language selects the smart typography quote style  */
     const lang = documentLang(specification);
     quotes = quoteStyles[lang?.toLowerCase().split(/[-_]/)[0] ?? "en"] ?? quoteStyles.en;
-    /*  establish the per-document rendering state  */
+    /*  establish the per-document rendering state (released again
+        below, also on a failure of the collecting or rendering)  */
     const index = buildLinkIndex(specification);
-    anchors = anchorPaths(index);
-    members = config !== undefined ? collectMembers(config, new Map()) : null;
-    schemas = config !== undefined ? collectSchemas(specification, config) : null;
-    diagrams = rendered;
-    /*  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();
-        for (const node of index)
-            if (node.parent !== undefined)
-                parents.set(node.object, node.parent.object);
-        infoParents = parents;
-    }
-    linker = makeLinker(index);
-    /*  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);
-    }
-    /*  the artifact timestamps aggregate into the earliest creation
-        and the latest modification timestamp of the document  */
-    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, 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 {
+        anchors = anchorPaths(index);
+        members = config !== undefined ? collectMembers(config, new Map()) : null;
+        schemas = config !== undefined ? collectSchemas(specification, config) : null;
+        diagrams = rendered;
+        /*  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();
+            for (const node of index)
+                if (node.parent !== undefined)
+                    parents.set(node.object, node.parent.object);
+            infoParents = parents;
+        }
+        linker = makeLinker(index);
+        /*  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);
+        }
+        /*  the artifact timestamps aggregate into the earliest creation
+            and the latest modification timestamp of the document  */
+        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, 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;
         const objects = artifacts.flatMap((artifact) => artifact.objects);
         const entries = tocEntries(objects, tocPages);
         return render("Document", { Document: {
@@ -1294,6 +1356,7 @@ export const renderHtml = async (specification, config, tocPages, css, realtime
                 titlepage: title !== undefined ?
                     safe(renderTitlePage(title, formatDate(created), formatDate(modified))) : "",
                 search: safe(searchScript()),
+                progress: safe(scrollProgressScript),
                 info: info !== null ? safe(infoScript(info, spec ?? {})) : "",
                 realtime: realtime ? safe(realtimeScript) : "",
                 toc: entries.length > 0 ? safe(render("Toc", { Toc: { entries } })) : "",

package/dst/specbook-export-md.js

@@ -33,15 +33,17 @@ const renderDescriptionMd = (description) => description.description + (descript
 const nameSuffixMd = (object) => (object.primary === true ? " (*)" : "") +
     (object.paren !== undefined ? ` (${object.paren})` : "") +
     (object.anchor !== undefined ? ` {{${object.anchor}}}` : "");
-/*  whether any descendant of an object carries a description which no
-    Concise Format item can carry -- a multi-line one (a fenced code
-    block, an ordered list, a blockquote, or multiple paragraphs) or one
-    carrying a ";", as only a ";"-free description stays a single segment
-    on re-parsing instead of splitting off a spurious property  */
-const complexBelowMd = (object) => object.childs.some((child) => (child.description !== undefined
-    && /[\n;]/.test(renderDescriptionMd(child.description))) || complexBelowMd(child));
+/*  whether any descendant of an object carries a name or a description
+    which no Concise Format item can carry -- a name carrying a ";" (it
+    would split the head segment), or a multi-line description (a fenced
+    code block, an ordered list, a blockquote, or multiple paragraphs) or
+    one carrying a ";", as only a ";"-free description stays a single
+    segment on re-parsing instead of splitting off a spurious property  */
+const complexBelowMd = (object) => object.children.some((child) => child.name.includes(";")
+    || (child.description !== undefined
+        && /[\n;]/.test(renderDescriptionMd(child.description))) || complexBelowMd(child));
 /*  render an object in the Concise Format as a list item of the
-    given nesting depth, with its childs as nested list items  */
+    given nesting depth, with its children as nested list items  */
 const renderConciseMd = (object, depth = 0) => {
     const indent = " ".repeat(depth * 4);
     const segments = [`${object.kind}: ${object.name}${nameSuffixMd(object)}`];
@@ -60,14 +62,14 @@ const renderConciseMd = (object, depth = 0) => {
         `${indent}-   ${segments.join("; ").replace(/\.?$/, ".")}` :
         `${indent}-   ${segments.join("; ")};`;
     return [item, renderKeyValuesMd(wrapped, `${indent}    `),
-        ...object.childs.map((child) => renderConciseMd(child, depth + 1))]
+        ...object.children.map((child) => renderConciseMd(child, depth + 1))]
         .filter((part) => part !== "").join("\n");
 };
-/*  render an object in the Complex Format (levels 1-3), with childs from
+/*  render an object in the Complex Format (levels 1-3), with children from
     level 4 upwards in the Concise Format -- unless a descendant carries
-    a description no concise item can carry, so all childs (as siblings
+    a description no concise item can carry, so all children (as siblings
     have to share the format) stay in the Complex Format down to heading
-    level 6, the deepest one Markdown knows, below which the childs are
+    level 6, the deepest one Markdown knows, below which the children are
     concise regardless -- and the optionally derived Gradia diagram spec
     embedded as a "gradia" fenced code block below the heading  */
 const renderObjectMd = (object, level, diagrams) => {
@@ -81,12 +83,12 @@ const renderObjectMd = (object, level, diagrams) => {
         parts.push(renderKeyValuesMd(object.properties));
     if (object.description !== undefined)
         parts.push(renderDescriptionMd(object.description));
-    /*  the childs share one format, as a concise item following
+    /*  the children share one format, as a concise item following
         a heading would attach to the heading's object instead  */
     if (level >= 6 || (level >= 3 && !complexBelowMd(object)))
-        parts.push(object.childs.map((child) => renderConciseMd(child)).join("\n"));
+        parts.push(object.children.map((child) => renderConciseMd(child)).join("\n"));
     else
-        parts.push(...object.childs.map((child) => renderObjectMd(child, level + 1, diagrams)));
+        parts.push(...object.children.map((child) => renderObjectMd(child, level + 1, diagrams)));
     return parts.filter((part) => part !== "").join("\n\n");
 };
 /*  render the entire specification into normalized Markdown  */

package/dst/specbook-export-pdf.js

@@ -28,7 +28,7 @@ const anchorPages = async (pdf) => {
 };
 /*  attach a hierarchical PDF outline (the "bookmarks" of the viewer
     side-bar) to a document, resolving the entry anchors against the
-    named destinations and hoisting the childs of an unresolvable entry  */
+    named destinations and hoisting the children of an unresolvable entry  */
 const addOutline = async (doc, entries) => {
     const { PDFName, PDFDict, PDFArray, PDFRef, PDFHexString } = await import("pdf-lib");
     const context = doc.context;
@@ -39,15 +39,17 @@ const addOutline = async (doc, entries) => {
     if (dests !== undefined) {
         for (const [name] of dests.entries()) {
             const dest = dests.lookup(name);
-            const page = dest instanceof PDFArray ? dest.get(0) : undefined;
-            if (dest instanceof PDFArray && page instanceof PDFRef && live.has(page.toString()))
+            if (!(dest instanceof PDFArray))
+                continue;
+            const page = dest.get(0);
+            if (page instanceof PDFRef && live.has(page.toString()))
                 targets.set(name.decodeText(), dest);
         }
     }
     const resolve = (entries) => entries.flatMap((entry) => {
         const dest = targets.get(entry.anchor);
-        const childs = resolve(entry.childs);
-        return dest !== undefined ? [{ title: entry.title, dest, childs }] : childs;
+        const children = resolve(entry.children);
+        return dest !== undefined ? [{ title: entry.title, dest, children }] : children;
     });
     const items = resolve(entries);
     if (items.length === 0)
@@ -57,16 +59,16 @@ const addOutline = async (doc, entries) => {
     const materialize = (items, parent) => {
         const refs = items.map(() => context.nextRef());
         items.forEach((item, i) => {
-            const childs = item.childs.length > 0 ? materialize(item.childs, refs[i]) : undefined;
+            const children = item.children.length > 0 ? materialize(item.children, refs[i]) : undefined;
             context.assign(refs[i], context.obj({
                 Title: PDFHexString.fromText(item.title),
                 Parent: parent,
                 Prev: i > 0 ? refs[i - 1] : undefined,
                 Next: i < refs.length - 1 ? refs[i + 1] : undefined,
-                First: childs?.first,
-                Last: childs?.last,
+                First: children?.first,
+                Last: children?.last,
                 /*  a negative count keeps the sub-tree initially collapsed  */
-                Count: childs !== undefined ? -item.childs.length : undefined,
+                Count: children !== undefined ? -item.children.length : undefined,
                 Dest: item.dest
             }));
         });

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

@@ -14,7 +14,7 @@ export type SchemaObject = {
     diagram?: SchemaDiagram;
     format?: SchemaFormat;
     props?: SchemaProperty[];
-    childs?: SchemaObject[];
+    children?: SchemaObject[];
 };
 export type SchemaAutomaton = {
     nodes: string;

package/dst/specbook-format-schema.js

@@ -16,6 +16,8 @@ const GradiaConfigSchemas = Object.fromEntries(Object.entries(Gradia.config).map
         typeof value === "number" ? v.pipe(v.number(), v.finite(), v.minValue(0)) : v.string()]));
 const SchemaDiagramConfig = v.partial(v.strictObject(GradiaConfigSchemas, (issue) => issue.expected === "never" ? "unknown Gradia rendering option" :
     "expected a map of Gradia rendering options"));
+/*  the Valibot schemas mirroring the types above, with the object
+    kind schema referencing itself lazily for the nested children  */
 const SchemaProperty = v.strictObject({
     name: v.string(),
     desc: v.optional(v.string()),
@@ -85,6 +87,6 @@ const SchemaObject = v.strictObject({
     diagram: v.optional(SchemaDiagram),
     format: v.optional(SchemaFormat),
     props: v.optional(v.array(SchemaProperty)),
-    childs: v.optional(v.array(v.lazy(() => SchemaObject)))
+    children: v.optional(v.array(v.lazy(() => SchemaObject)))
 });
 export const Schema = v.pipe(v.array(SchemaObject), v.minLength(1));

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

@@ -16,7 +16,7 @@ export type SpecObject = {
     primary?: boolean;
     description?: SpecDescription;
     properties: SpecProperty[];
-    childs: SpecObject[];
+    children: SpecObject[];
 };
 export type SpecDescription = {
     description: string;

package/dst/specbook-format-spec.js

@@ -5,6 +5,8 @@
 */
 import * as v from "valibot";
 /*  ==== Schema ====  */
+/*  the Valibot schemas mirroring the types above, with the object
+    schema referencing itself lazily for the nested children  */
 const SpecProperty = v.object({
     key: v.string(),
     value: v.string(),
@@ -24,7 +26,7 @@ const SpecObject = v.object({
     primary: v.optional(v.boolean()),
     description: v.optional(SpecDescription),
     properties: v.array(SpecProperty),
-    childs: v.array(v.lazy(() => SpecObject))
+    children: v.array(v.lazy(() => SpecObject))
 });
 const SpecArtifact = v.object({
     created: v.date(),

package/dst/specbook-format.md

@@ -78,7 +78,7 @@ type SchemaObject = {
     diagram?:          SchemaDiagram
     format?:           SchemaFormat
     props?:            SchemaProperty[]
-    childs?:           SchemaObject[]
+    children?:         SchemaObject[]
 }
 type SchemaAutomaton = {
     nodes:             string
@@ -251,7 +251,7 @@ type SchemaGradiaConfig = Partial<{
     properties allowed on objects of this kind,
     BECAUSE they carry the structured, machine-checkable content
 
--   `SchemaObject.childs?: SchemaObject[]`:
+-   `SchemaObject.children?: SchemaObject[]`:
     object kinds allowed one level below this object (RECURSION),
     BECAUSE the nesting defines and bounds the document structure
 
@@ -579,7 +579,7 @@ type SpecObject = {
     primary?:          boolean
     description?:      SpecDescription
     properties:        SpecProperty[]
-    childs:            SpecObject[]
+    children:          SpecObject[]
 }
 type SpecDescription = {
     description:       string
@@ -653,7 +653,7 @@ type SpecProperty = {
     key/value properties of the object, in canonical order,
     BECAUSE properties carry the structured, machine-checkable content
 
--   `SpecObject.childs: SpecObject[]`:
+-   `SpecObject.children: SpecObject[]`:
     child objects nested one level below this object (RECURSION),
     BECAUSE a specification is a tree, not a flat list of statements