@rse/specbook 0.9.2 → 0.9.4

package/dst/specbook-export-html.js

@@ -3,7 +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 { marked } from "marked";
+import { Marked } from "marked";
 import { markedSmartypants } from "marked-smartypants";
 import nunjucks from "nunjucks";
 import nunjucksAddons from "@rse/nunjucks-addons";
@@ -30,7 +30,8 @@ const templates = {
                 <script>
                     (function () {
                         let style = null
-                        try { style = localStorage.getItem("specbook-theme") } catch (ex) {}
+                        try { style = localStorage.getItem("specbook-theme") }
+                        catch { /*  an inaccessible storage just means no stored choice  */ }
                         if (style === null) {
                             const m = document.documentElement.className.match(/theme-(light|dark)/)
                             style = m !== null ? m[1] : null
@@ -42,7 +43,8 @@ const templates = {
                     function themeSwitch () {
                         const style = document.documentElement.className === "theme-dark" ? "light" : "dark"
                         document.documentElement.className = "theme-" + style
-                        try { localStorage.setItem("specbook-theme", style) } catch (ex) {}
+                        try { localStorage.setItem("specbook-theme", style) }
+                        catch { /*  an inaccessible storage just loses the choice  */ }
                     }
                 </script>
             </head>
@@ -144,6 +146,32 @@ const templates = {
                 {% endfor %}
             </tbody>
         </table>
+    `,
+    /*  <TableChunked/>  */
+    "TableChunked": textframe `
+        <table class="objects">
+            <thead>
+                <tr>
+                    <th class="object-kind" style="width: {{ Table.width }}%">{{ Table.head }}</th>
+                    <th class="description">Properties</th>
+                </tr>
+            </thead>
+            <tbody>
+                {% for row in Table.rows %}
+                <tr id="{{ row.id }}">
+                    <td>{{ row.name }}{% if row.primary %} <span class="primary-marker">&#x2318;</span>{% endif %}{% if row.paren %} <span class="anchor-paren">({{ row.paren }})</span>{% endif %} <a href="#{{ row.id }}"><span class="anchor-symbol">&#x2693;&#xFE0E;</span></a></td>
+                    <td class="chunks">
+                        <table class="chunks">
+                            {% for chunk in row.chunks %}
+                            <tr>{% for cell in chunk %}<th{% if not cell.desc %} class="property-name"{% endif %}{% if cell.span > 1 %} colspan="{{ cell.span }}"{% endif %}>{{ cell.key }}</th>{% endfor %}</tr>
+                            <tr>{% for cell in chunk %}<td{% if cell.span > 1 %} colspan="{{ cell.span }}"{% endif %}>{{ cell.value }}</td>{% endfor %}</tr>
+                            {% endfor %}
+                        </table>
+                    </td>
+                </tr>
+                {% endfor %}
+            </tbody>
+        </table>
     `
 };
 /*  ==== Rendering ====  */
@@ -168,6 +196,10 @@ const quoteStyles = {
 };
 /*  the active double quote style (set per document during rendering)  */
 let quotes = quoteStyles.en;
+/*  the private Markdown renderer instance, as the hooks below must not
+    leak into the "marked" singleton shared with the parser and with the
+    application embedding SpecBook as a library  */
+const marked = new Marked();
 /*  improve the typography of all rendered Markdown text (curly quotes,
     "--" as the em dash, ellipsis); as smartypants requires unescaped text,
     the extension switches off the text escaping of marked, so the stray
@@ -183,14 +215,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);
+/*  render one of the built-in Nunjucks templates with a context  */
 const render = (name, context) => env.renderString(templates[name], context);
 /*  the active per-document reference expander, fully-qualified
-    anchor paths, enum/tags property value kinds, and pre-rendered
-    diagram SVGs (all set during HTML rendering)  */
+    anchor paths, enum/tags property value kinds, object schema nodes,
+    and pre-rendered diagram SVGs (all set during HTML rendering)  */
 let linker = null;
 let anchors = null;
 let members = null;
+let schemas = null;
 let diagrams = null;
+/*  the cache of the pre-rendered diagram SVGs, keyed by specification,
+    as the PDF export renders the very same document multiple times  */
+const diagramCache = new WeakMap();
 /*  determine the fully-qualified anchor path of an object  */
 const anchorOf = (object) => anchors?.get(object) ?? object.id;
 /*  expand the inline Markdown of a text (code spans, emphasis, etc.),
@@ -252,10 +289,36 @@ const collectMembers = (schemas, result) => {
     }
     return result;
 };
+/*  map the specification objects onto their schema configuration
+    nodes (the schema resolution mirrors the semantic validation)  */
+const collectSchemas = (specification, config) => {
+    const result = new Map();
+    const walk = (object, schema) => {
+        result.set(object, schema);
+        for (const child of object.childs) {
+            const childSchema = (schema.childs ?? []).find((c) => c.kind === child.kind);
+            if (childSchema !== undefined)
+                walk(child, childSchema);
+        }
+    };
+    for (const artifact of specification.artifacts) {
+        for (const object of artifact.objects) {
+            const schema = config.find((s) => (s.kind === object.kind && s.id === object.id) || `${s.kind}-${s.id}` === object.id) ??
+                config.find((s) => (s.name ?? "").toUpperCase() ===
+                    object.name.replace(/`/g, "").toUpperCase());
+            if (schema !== undefined)
+                walk(object, schema);
+        }
+    }
+    return result;
+};
+/*  strip a trailing parenthesized annotation from a
+    property key (e.g. "WHEN (Context)")  */
+const plainKey = (key) => key.replace(/\s*\([^)]*\)\s*$/, "").trim();
 /*  render a property value, badging the individual members of an
     "enum(...)" (a single member) or "tags(...)" (a member set) value  */
 const inlineValue = (kind, key, value) => {
-    const member = members?.get(`${kind}${key.replace(/\s*\([^)]*\)\s*$/, "").trim()}`);
+    const member = members?.get(`${kind}${plainKey(key)}`);
     if (member === undefined)
         return inline(value);
     const items = member === "tags" ? splitItems(value) : [value.trim()];
@@ -264,26 +327,54 @@ const inlineValue = (kind, key, value) => {
 /*  expand the inline Markdown of the property values  */
 const inlineProperties = (kind, properties) => properties.map((property) => ({ key: property.key,
     value: inlineValue(kind, property.key, property.value) }));
-/*  determine the column shape of a potential compact table  */
+/*  resolve the format configuration of an object  */
+const formatOf = (object) => schemas?.get(object)?.format;
+/*  determine the maximum table columns configured on an object (at
+    least two, as a single column cannot carry a name and a value)  */
+const maxColumnsOf = (object) => Math.max(2, formatOf(object)?.maxTableColumns ?? 4);
+/*  determine the effective properties of an object, with
+    "withUnusedProps" injecting the defined but still unused schema
+    properties (in schema order) as empty key/value entries  */
+const effectiveProperties = (object) => {
+    const schema = schemas?.get(object);
+    if (schema?.format?.withUnusedProps !== true)
+        return object.properties;
+    const merged = (schema.props ?? []).flatMap((prop) => {
+        const present = object.properties.filter((property) => plainKey(property.key) === prop.name);
+        return present.length > 0 ? present : [{ key: prop.name, value: "" }];
+    });
+    return [...merged, ...object.properties.filter((property) => !merged.includes(property))];
+};
+/*  determine the column shape of a potential compact table, with
+    "withUnusedProps" injecting the defined but still unused schema
+    properties (in schema order) as additional columns  */
 const tableShape = (childs) => {
-    const keys = new Array();
+    let keys = new Array();
     for (const child of childs)
         for (const property of child.properties)
             if (!keys.includes(property.key))
                 keys.push(property.key);
-    return { keys, desc: childs.some((child) => child.description !== undefined) };
+    const schema = schemas?.get(childs[0]);
+    if (schema?.format?.withUnusedProps === true) {
+        const merged = (schema.props ?? []).flatMap((prop) => {
+            const present = keys.filter((key) => plainKey(key) === prop.name);
+            return present.length > 0 ? present : [prop.name];
+        });
+        keys = [...merged, ...keys.filter((key) => !merged.includes(key))];
+    }
+    return { keys, desc: childs.some((child) => child.description !== undefined || child.childs.length > 0) };
 };
-/*  check whether the childs of an object form the deepest level and every
-    per-kind group is compact enough (at most maxColumns name/property/
-    description columns) for a tabular rendering  */
-const tabularChilds = (object, maxColumns) => {
-    if (object.childs.length === 0
-        || !object.childs.every((child) => child.childs.length === 0))
+/*  decide whether the childs of an object collapse into the concise
+    (tabular) rendering: an explicit "format" type wins, "auto" collapses
+    the deepest level only, and inside an already concise rendering
+    context "auto" childs implicitly stay concise, too  */
+const conciseChilds = (object, schemaMap, concise) => {
+    if (object.childs.length === 0)
         return false;
-    return groupChilds(object.childs).every((group) => {
-        const { keys, desc } = tableShape(group);
-        return 1 + keys.length + (desc ? 1 : 0) <= maxColumns;
-    });
+    const type = schemaMap?.get(object)?.format?.type ?? "auto";
+    if (type !== "auto")
+        return type === "concise";
+    return concise || object.childs.every((child) => child.childs.length === 0);
 };
 /*  group the childs of an object by their kind, preserving order  */
 const groupChilds = (childs) => {
@@ -297,52 +388,103 @@ const groupChilds = (childs) => {
     }
     return [...groups.values()];
 };
-/*  render a single-kind group of leaf childs into one compact table:
-    the name first, then the property columns, then the description  */
-const renderTable = (childs) => {
+/*  render the description cell of a table row: the description of the
+    object followed by its recursively rendered childs (implicitly or
+    explicitly concise childs as nested sub-tables, explicitly complex
+    ones as regular nested object renderings pressed into the cell)  */
+const renderCell = (child) => {
+    let html = child.description !== undefined ? renderDescription(child.description) : "";
+    if (child.childs.length > 0)
+        html += conciseChilds(child, schemas, true) ?
+            groupChilds(child.childs).map((group) => renderTable(group, maxColumnsOf(child))).join("") :
+            child.childs.map((sub) => renderObject(sub, 6, true)).join("");
+    return html;
+};
+/*  render a single-kind group of childs into one compact table:
+    the name first, then the property columns, then the description;
+    a group wider than maxColumns instead chunks the property and
+    description cells of every object into an embedded per-object table  */
+const renderTable = (childs, maxColumns) => {
     const { keys, desc } = tableShape(childs);
-    return render("Table", { Table: {
+    if (1 + keys.length + (desc ? 1 : 0) <= maxColumns)
+        return render("Table", { Table: {
+                head: childs[0].kind !== "" ? childs[0].kind : "Name",
+                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) => ({
+                    id: anchorOf(child),
+                    paren: child.paren,
+                    primary: child.primary,
+                    name: inline(child.name),
+                    values: keys.map((key) => {
+                        const value = child.properties.find((property) => property.key === key)?.value;
+                        return value !== undefined ? inlineValue(child.kind, key, value) : "";
+                    }),
+                    description: safe(renderCell(child))
+                }))
+            } });
+    /*  the embedded rows hold at most maxColumns - 1 cells (of the
+        group-wide union of property keys, plus the trailing description),
+        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",
-            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) => ({
-                id: anchorOf(child),
-                paren: child.paren,
-                primary: child.primary,
-                name: inline(child.name),
-                values: keys.map((key) => {
+            width: Math.round(100 / maxColumns),
+            rows: childs.map((child) => {
+                const cells = keys.map((key) => {
                     const value = child.properties.find((property) => property.key === key)?.value;
-                    return value !== undefined ? inlineValue(child.kind, key, value) : "";
-                }),
-                description: child.description !== undefined ?
-                    safe(renderDescription(child.description)) : ""
-            }))
+                    return { key, desc: false, span: 1,
+                        value: value !== undefined ? inlineValue(child.kind, key, value) : safe("") };
+                });
+                if (desc)
+                    cells.push({ key: "Description", desc: true, span: 1,
+                        value: safe(renderCell(child)) });
+                const chunks = new Array();
+                for (let i = 0; i < cells.length; i += size)
+                    chunks.push(cells.slice(i, i + size));
+                const last = chunks[chunks.length - 1];
+                last[last.length - 1].span = size - last.length + 1;
+                return {
+                    id: anchorOf(child),
+                    paren: child.paren,
+                    primary: child.primary,
+                    name: inline(child.name),
+                    chunks
+                };
+            })
         } });
 };
 /*  recursively render an object into HTML  */
-const renderObject = (object, level, maxColumns) => render("Object", { Object: {
-        level: Math.min(level, 6),
-        kind: object.kind,
-        id: anchorOf(object),
-        paren: object.paren,
-        primary: object.primary,
-        name: inline(object.name),
-        diagram: diagrams?.has(object) === true ?
-            safe(`<div class="diagram">${diagrams.get(object) ?? ""}</div>`) : "",
-        properties: object.properties.length > 0 ?
-            safe(render("Properties", { Properties: inlineProperties(object.kind, object.properties) })) : "",
-        description: object.description !== undefined ?
-            safe(renderDescription(object.description)) : "",
-        childs: tabularChilds(object, maxColumns) ?
-            safe(groupChilds(object.childs).map(renderTable).join("")) :
-            safe(object.childs.map((child) => renderObject(child, level + 1, maxColumns)).join(""))
-    } });
+const renderObject = (object, level, concise) => {
+    const properties = effectiveProperties(object);
+    return render("Object", { Object: {
+            level: Math.min(level, 6),
+            kind: object.kind,
+            id: anchorOf(object),
+            paren: object.paren,
+            primary: object.primary,
+            name: inline(object.name),
+            diagram: diagrams?.has(object) === true ?
+                safe(`<div class="diagram">${diagrams.get(object) ?? ""}</div>`) : "",
+            properties: properties.length > 0 ?
+                safe(render("Properties", { Properties: inlineProperties(object.kind, properties) })) : "",
+            description: object.description !== undefined ?
+                safe(renderDescription(object.description)) : "",
+            childs: conciseChilds(object, schemas, concise) ?
+                safe(groupChilds(object.childs).map((group) => renderTable(group, maxColumnsOf(object))).join("")) :
+                safe(object.childs.map((child) => renderObject(child, level + 1, concise)).join(""))
+        } });
+};
 /*  render the title object into a title page  */
 const renderTitlePage = (object, created, modified) => {
     const prop = (name) => object.properties.find((property) => property.key === name)?.value;
+    const inlineProp = (name) => {
+        const value = prop(name);
+        return value !== undefined ? inline(value) : "";
+    };
     const rest = object.properties.filter((property) => !["LOGO", "TITLE", "SUBTITLE", "AUTHOR", "VERSION",
         "LANG", "CHARSET", "PAPER-SIZE", "THEME-STYLE", "THEME-TONE"].includes(property.key));
     /*  the logo is rendered above the title, from the embedded image content
@@ -354,9 +496,9 @@ const renderTitlePage = (object, created, modified) => {
             logo: logo === undefined ? safe(`<img src="${fallbackLogo()}" alt="SpecBook"/>`) :
                 (image.length > 0 ? safe(image.join("")) : inline(logo.value)),
             title: inline(prop("TITLE") ?? object.name),
-            subtitle: prop("SUBTITLE") !== undefined ? inline(prop("SUBTITLE") ?? "") : "",
-            author: prop("AUTHOR") !== undefined ? inline(prop("AUTHOR") ?? "") : "",
-            version: prop("VERSION") !== undefined ? inline(prop("VERSION") ?? "") : "",
+            subtitle: inlineProp("SUBTITLE"),
+            author: inlineProp("AUTHOR"),
+            version: inlineProp("VERSION"),
             description: object.description !== undefined ?
                 safe(renderDescription(object.description)) : "",
             properties: rest.length > 0 ?
@@ -365,17 +507,18 @@ const renderTitlePage = (object, created, modified) => {
         } });
 };
 /*  render an artifact into HTML  */
-const renderArtifact = (artifact, maxColumns) => render("Artifact", { Artifact: {
-        objects: safe(artifact.objects.map((object) => renderObject(object, 1, maxColumns)).join(""))
+const renderArtifact = (artifact) => render("Artifact", { Artifact: {
+        objects: safe(artifact.objects.map((object) => renderObject(object, 1, false)).join(""))
     } });
 /*  derive the hierarchy of the rendered object headings, skipping the
-    title page object and the leaf childs collapsing into compact tables  */
-export const htmlOutline = (specification, maxColumns) => {
+    title page object and the childs collapsing into compact tables  */
+export const htmlOutline = (specification, config) => {
     const paths = anchorPaths(buildLinkIndex(specification));
+    const schemaMap = config !== undefined ? collectSchemas(specification, config) : null;
     const entry = (object) => ({
         title: (object.kind !== "" ? `${object.kind}: ` : "") + object.name,
         anchor: paths.get(object) ?? object.id,
-        childs: tabularChilds(object, maxColumns) ? [] : object.childs.map(entry)
+        childs: conciseChilds(object, schemaMap, false) ? [] : object.childs.map(entry)
     });
     return specification.artifacts
         .filter((artifact) => !artifact.objects.some(isTitleObject))
@@ -386,10 +529,7 @@ export const htmlOutline = (specification, maxColumns) => {
     with the build-time pre-assembled stylesheet embedded inline, the
     artifact timestamps aggregated into min(Created)/max(Modified), and
     optional per-anchor page numbers attached to the ToC entries  */
-export const renderHtml = async (specification, maxColumns, config, tocPages, css) => {
-    /*  the document language selects the smart typography quote style  */
-    const lang = documentLang(specification);
-    quotes = quoteStyles[lang?.toLowerCase().split(/[-_]/)[0] ?? "en"] ?? quoteStyles.en;
+export const renderHtml = async (specification, config, tocPages, css) => {
     /*  pre-render the configured diagrams as embeddable SVGs (a runtime
         rendering failure omits the diagram, as the statically detectable
         invalid situations are already reported as lint diagnostics),
@@ -397,8 +537,11 @@ export const renderHtml = async (specification, maxColumns, config, tocPages, cs
         (node boxes, font sizes) is dimensioned for a stand-alone
         canvas and would dwarf the document text at 1:1  */
     const scale = 0.75;
+    const cached = diagramCache.get(specification);
     diagrams = null;
-    if (config !== undefined) {
+    if (cached !== undefined && cached.config === config)
+        diagrams = cached.diagrams;
+    else if (config !== undefined) {
         diagrams = new Map();
         for (const [object, result] of specDiagrams(specification, config)) {
             if (result.spec === undefined)
@@ -411,13 +554,18 @@ export const renderHtml = async (specification, maxColumns, config, tocPages, cs
                 /*  intentionally omitted  */
             }
         }
+        diagramCache.set(specification, { config, diagrams });
     }
+    /*  the document language selects the smart typography quote style  */
+    const lang = documentLang(specification);
+    quotes = quoteStyles[lang?.toLowerCase().split(/[-_]/)[0] ?? "en"] ?? quoteStyles.en;
     /*  expand "[[xxx]]" references into hyperlinks (an unresolvable or
         ambiguous reference stays literal, marked as broken), targeting
         the fully-qualified anchor paths of the objects  */
     const index = buildLinkIndex(specification);
     anchors = anchorPaths(index);
     members = config !== undefined ? collectMembers(config, new Map()) : null;
+    schemas = config !== undefined ? collectSchemas(specification, config) : null;
     linker = (text) => expandReferences(text, (reference) => {
         const target = resolveUnique(index, reference).target;
         if (target === undefined)
@@ -447,6 +595,6 @@ export const renderHtml = async (specification, maxColumns, config, tocPages, cs
                 safe(renderTitlePage(title, created.toISOString().slice(0, 10), modified.toISOString().slice(0, 10))) : "",
             search: title !== undefined ? safe(searchScript()) : "",
             toc: entries.length > 0 ? safe(render("Toc", { Toc: { entries } })) : "",
-            artifacts: safe(artifacts.map((artifact) => renderArtifact(artifact, maxColumns)).join(""))
+            artifacts: safe(artifacts.map((artifact) => renderArtifact(artifact)).join(""))
         } });
 };

package/dst/specbook-export-md.js

@@ -31,7 +31,12 @@ const renderConciseMd = (object, level) => {
     segments.push(...object.properties.map((property) => `${property.key}: ${property.value}`));
     if (object.description !== undefined)
         segments.push(renderDescriptionMd(object.description));
-    const item = `${indent}-   ${segments.join("; ").replace(/\.?$/, ".")}`;
+    /*  a description terminates the item with ".", while without one the
+        ";" segment terminator has to remain, as only it lets the item be
+        recognized as a concise object again on re-parsing  */
+    const item = object.description !== undefined ?
+        `${indent}-   ${segments.join("; ").replace(/\.?$/, ".")}` :
+        `${indent}-   ${segments.join("; ")};`;
     return [item, ...object.childs.map((child) => renderConciseMd(child, level + 1))].join("\n");
 };
 /*  render an object in the Complex Format (levels 1-3),
@@ -39,9 +44,8 @@ const renderConciseMd = (object, level) => {
     and the optionally derived Gradia diagram spec embedded
     as a "gradia" fenced code block below the heading  */
 const renderObjectMd = (object, level, diagrams) => {
-    const heading = level === 1 ?
-        `#   ${object.kind}: ${object.name}${nameSuffixMd(object)}` :
-        `${"#".repeat(level)}${" ".repeat(4 - level)}${object.kind}: ${object.name}${nameSuffixMd(object)}`;
+    const heading = `${"#".repeat(level)}${" ".repeat(4 - level)}` +
+        `${object.kind}: ${object.name}${nameSuffixMd(object)}`;
     const parts = [heading];
     const spec = diagrams?.get(object);
     if (spec !== undefined)
@@ -66,9 +70,9 @@ export const renderMarkdown = async (specification, config) => {
         for (const [object, result] of specDiagrams(specification, config))
             if (result.spec !== undefined)
                 diagrams.set(object, result.spec);
-    return specification.artifacts.map((artifact) => artifact.objects.map((object) => "---\n" +
+    return specification.artifacts.map((artifact) => "---\n" +
         `Created:  ${formatTimestamp(artifact.created)}\n` +
         `Modified: ${formatTimestamp(artifact.modified)}\n` +
         "---\n\n" +
-        renderObjectMd(object, 1, diagrams)).join("\n\n")).join("\n\n") + "\n";
+        artifact.objects.map((object) => renderObjectMd(object, 1, diagrams)).join("\n\n")).join("\n\n") + "\n";
 };

package/dst/specbook-export-pdf.js

@@ -153,7 +153,7 @@ export const htmlToPdf = async (renderHtmlPass, heading, outline, verbose, css,
                 "padding-bottom: 1mm; display: flex; justify-content: space-between; " +
                 "align-items: flex-end;\">" +
                 `<span>${headText}</span>` +
-                `<img src="${heading.logo}" alt="" style="height: 3.5mm;"/>` +
+                `<img src="${escapeHtml(heading.logo)}" alt="" style="height: 3.5mm;"/>` +
                 "</div></div>",
             footerTemplate: `<style>${fontFace}</style>` +
                 "<div style=\"width: 100%; margin-bottom: 0.8cm;\">" +
@@ -185,8 +185,9 @@ export const htmlToPdf = async (renderHtmlPass, heading, outline, verbose, css,
         /*  draw the vertical brand bar onto the left edge of the
             physical paper of every page, as Chromium clips print
             content to the page box (0.6rem at the 9pt print root)  */
-        const [r, g, b] = (theme.accent.match(/[0-9a-f]{2}/gi) ?? [])
-            .map((hex) => parseInt(hex, 16) / 255);
+        const hex = theme.accent.match(/^#?([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i);
+        const [r, g, b] = (hex !== null ? hex.slice(1) : ["00", "00", "00"])
+            .map((component) => parseInt(component, 16) / 255);
         for (const pdfPage of merged.getPages())
             pdfPage.drawRectangle({ x: 0, y: 0, width: 5.4,
                 height: pdfPage.getHeight(), color: rgb(r, g, b) });

package/dst/specbook-llm.js

@@ -3,40 +3,30 @@
 **  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
-import { generateText } from "ai";
-/*  the default model per supported provider  */
-const defaults = {
-    anthropic: "claude-sonnet-5",
-    openai: "gpt-5.6-luna",
-    openrouter: "anthropic/claude-sonnet-5",
-    ollama: "qwen3"
+/*  the supported AI providers  */
+const providers = {
+    anthropic: { model: "claude-sonnet-5",
+        create: async (id) => (await import("@ai-sdk/anthropic")).createAnthropic()(id) },
+    openai: { model: "gpt-5.6-luna",
+        create: async (id) => (await import("@ai-sdk/openai")).createOpenAI()(id) },
+    openrouter: { model: "anthropic/claude-sonnet-5",
+        create: async (id) => (await import("@openrouter/ai-sdk-provider")).createOpenRouter()(id) },
+    ollama: { model: "qwen3",
+        create: async (id) => (await import("ollama-ai-provider-v2")).createOllama()(id) }
 };
 /*  resolve the AI provider and model into a language model handle  */
 export const resolveModel = async (options) => {
-    const provider = options.provider ?? process.env.SPECBOOK_AI_PROVIDER ?? "anthropic";
-    const model = options.model ?? process.env.SPECBOOK_AI_MODEL ?? defaults[provider];
-    if (provider === "anthropic") {
-        const { createAnthropic } = await import("@ai-sdk/anthropic");
-        return createAnthropic()(model);
-    }
-    else if (provider === "openai") {
-        const { createOpenAI } = await import("@ai-sdk/openai");
-        return createOpenAI()(model);
-    }
-    else if (provider === "openrouter") {
-        const { createOpenRouter } = await import("@openrouter/ai-sdk-provider");
-        return createOpenRouter()(model);
-    }
-    else if (provider === "ollama") {
-        const { createOllama } = await import("ollama-ai-provider-v2");
-        return createOllama()(model);
-    }
-    else
-        throw new Error(`unknown AI provider "${provider}" ` +
-            "(expected \"anthropic\", \"openai\", \"openrouter\" or \"ollama\")");
+    const name = options.provider ?? process.env.SPECBOOK_AI_PROVIDER ?? "anthropic";
+    const provider = providers[name];
+    if (provider === undefined)
+        throw new Error(`unknown AI provider "${name}" (expected ` +
+            Object.keys(providers).map((n) => `"${n}"`).join(", ") + ")");
+    const model = options.model ?? process.env.SPECBOOK_AI_MODEL ?? provider.model;
+    return provider.create(model);
 };
 /*  perform a single LLM completion  */
 export const complete = async (options, system, prompt) => {
+    const { generateText } = await import("ai");
     const model = await resolveModel(options);
     const result = await generateText({ model, system, prompt });
     return result.text;

package/dst/specbook-mcp.js

@@ -7,7 +7,7 @@ import * as fs from "node:fs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { SpecBook, renderDiagnostic, formats } from "./specbook-api.js";
+import { SpecBook, renderDiagnostic, formats, version } from "./specbook-api.js";
 /*  render an error with its cause chain into a tool error result  */
 const errorResult = (err) => {
     let msg = err instanceof Error ? err.message : String(err);
@@ -20,7 +20,7 @@ const errorResult = (err) => {
 };
 /*  serve the SpecBook functionality as "specbook_<cmd>" MCP tools over stdio  */
 export const serveMcp = async (verbose) => {
-    const server = new McpServer({ name: "specbook", version: "0.9.0" });
+    const server = new McpServer({ name: "specbook", version });
     const specbook = new SpecBook({ verbose });
     server.registerTool("specbook_init", {
         title: "Initialize Specification",
@@ -70,14 +70,12 @@ export const serveMcp = async (verbose) => {
             config: z.string().optional().describe("YAML schema configuration file"),
             basedir: z.string().optional().describe("base directory of the specification Markdown files (default: \".\")"),
             format: z.enum(formats).optional().describe("output format (default: json)"),
-            output: z.string().optional().describe("output file path"),
-            maxTableColumns: z.number().optional().describe("maximum name/property/description " +
-                "columns for the compact table rendering (default: 4)")
+            output: z.string().optional().describe("output file path")
         }
     }, async (args) => {
         try {
             const [data] = await specbook.export({ config: args.config, basedir: args.basedir,
-                formats: [args.format ?? "json"], maxTableColumns: args.maxTableColumns });
+                formats: [args.format ?? "json"] });
             if (args.output !== undefined) {
                 await fs.promises.writeFile(args.output, data);
                 return { content: [{ type: "text", text: `exported specification into "${args.output}" (${data.length} bytes)` }] };