@rse/specbook 0.9.2 → 0.9.3

package/README.md

@@ -33,18 +33,46 @@ service with tools `specbook_<cmd>()`.
 Specification Format
 --------------------
 
-A specification consists of Markdown *artifact* files, each carrying a
-frontmatter with `Created:` and `Modified:` timestamps and a tree of
-*objects*. Every object has a mandatory *kind*, a mandatory *name*, an
-optional unique anchor *id*, optional *properties* (key/value pairs),
-an optional *description* statement with an optional rationale, and
-optional *child* objects.
+### Artifact Files
+
+A specification consists of Markdown *artifact* files, which are
+scanned recursively from a base directory. Every file has to start with
+a frontmatter block carrying the `Created:` and `Modified:` timestamps
+(format `yyyy-LL-dd HH:mm`):
+
+```
+---
+Created:  2026-06-18 10:18
+Modified: 2026-06-18 10:18
+---
+```
+
+Every level 1 heading opens a new *artifact*, so usually each file
+carries exactly one. Both ATX headings (`# <text/>`, `## <text/>`, ...)
+and Setext headings (`<text/>` underlined with `===` or `---`) are
+supported.
+
+### Object Model
+
+An artifact carries a tree of *objects*. Every object has a mandatory
+*kind* (e.g. `ENTITY`), a mandatory *name*, a unique anchor *id*
+(explicitly given or derived from the name), an optional *primary*
+marker, optional *properties* (key/value pairs), an optional
+*description* statement with an optional rationale, and optional *child*
+objects. Which kinds, properties, and nestings are allowed is defined by
+the schema configuration (see below); object kinds and property keys are
+case-sensitive and have to be written exactly as configured. Backquotes
+in names and property values are preserved as code markup for rendering,
+but are ignored when matching names, references, and constraints.
 
 Three concrete syntaxes exist:
 
 ### Complex Format
 
-Usually used on object hierarchy levels 1-3 (`#`, `##`, `###`).
+Usually used on object hierarchy levels 1-3 (`#`, `##`, `###`). A
+heading opens the object, an optional unordered list carries its
+properties, and the remaining content up to the next heading is its
+description:
 
 ```
 #   <kind/>: <name/> (<id/>)
@@ -55,16 +83,38 @@ Usually used on object hierarchy levels 1-3 (`#`, `##`, `###`).
 <statement/>, BECAUSE <rationale/>.
 ```
 
+The heading level directly reflects the nesting level: a `##` object
+becomes a child of the preceding `#` object, a `###` object a child of
+the preceding `##` object, etc. Skipping a level (a heading without a
+parent object on the level above) is an error.
+
 ### Concise Format
 
-Usually used on level 4 and deeper, with child objects nested as
-indented list items below their parent item:
+Usually used on level 4 and deeper. A single unordered list item carries
+the entire object as `;`-separated segments -- the `<kind/>: <name/>`
+head, the `<key/>: <value/>` properties, and the trailing description --
+and may wrap over multiple (indented) lines:
 
 ```
 -   <kind/>: <name/>; <key/>: <value/>; [...];
     <statement/>, BECAUSE <rationale/>.
 ```
 
+A list item is recognized as a Concise Format object (instead of a
+property of the enclosing object) by carrying at least one `;` on its
+first line. Every segment of the form `<key/>: <value/>` becomes a
+property (unless it contains a ` BECAUSE `), all remaining segments are
+joined into the description. Child objects nest as indented list items
+below their parent item, where key/value items become properties and
+concise items become child objects of that parent:
+
+```
+-   <kind/>: <name/>; <key/>: <value/>;
+    <statement/>, BECAUSE <rationale/>.
+    -   <kind/>: <name/>; <key/>: <value/>;
+        <statement/>, BECAUSE <rationale/>.
+```
+
 ### Grouped Format
 
 A heading carrying just a *kind* and no `<kind/>: <name/>` pair opens a
@@ -81,13 +131,126 @@ with the (optionally backquoted) name directly:
 
 The heading kind is singularized by stripping one trailing `S`, so both
 `### STATES` and `### STATE` group objects of kind `STATE`. The grouped
-objects become childs of the object the heading is nested under.
+objects become childs of the object the heading is nested under. An
+unquoted name must not contain a `:` (else the item would look like a
+key/value pair) -- backquote it in this case.
 
 When **SpecBook** itself generates specification Markdown, it emits
 the Complex Format on levels 1-3 and the Concise Format from level 4
 upwards. When **SpecBook** edits existing files, it mirrors the format
 each existing object already uses.
 
+### Names, Anchors, and Ids
+
+In all formats, the `<name/>` may carry trailing decorations, in any
+order:
+
+-   `{{<id/>}}`: the explicit Wiki-style anchor, setting the object id
+    (e.g. `## ENTITY: Attendee Browser {{attendee}}`).
+
+-   `(*)`: the *primary* marker, flagging the object as primary (e.g.
+    the primary attributes of an entity).
+
+-   `(<token/>)`: a parenthesized token with three possible roles: on
+    level 1 it becomes the artifact id (e.g. `# SPEC: Data Model (DM)`);
+    on deeper levels it is either accepted as the value of a still
+    missing configured property whose constraint it matches (e.g.
+    `### SCENARIO: Successful Token Login (Main)` satisfying an
+    `enum(Main,Alternative,Exceptional)` property), or else acts as the
+    implicit anchor id.
+
+-   `<a id="<id/>"></a>`: an HTML anchor at the very end of a heading,
+    as an alternative to `{{<id/>}}` (emitted by **SpecBook** itself
+    when exporting normalized Markdown).
+
+When no explicit id is given, the id is derived by slugifying the name
+(lowercased, with non-alphanumeric character runs dashed). An explicit
+`{{<id/>}}` anchor always takes precedence over a `(<token/>)` id. When
+the schema configures a fixed `id` for an object, it has to be
+explicitly written in the input, via either `{{<id/>}}` or `(<id/>)`.
+
+### Properties
+
+In the Complex Format, each property is an unordered list item of the
+form `<key/>: <value/>`, whose value may continue on the following
+indented lines of the item (joined with spaces). In the Concise Format,
+each property is a `<key/>: <value/>` segment. A property key may carry
+a trailing parenthesized annotation (e.g. `WHEN (Context)`), which is
+kept for rendering but ignored when matching the key against the schema.
+
+A multi-token convenience exists for pattern-constrained properties:
+when a property value fails its (regex or enum) constraint as a whole,
+but consists of multiple whitespace-separated tokens of which one
+matches the property's own constraint, that token is kept as the value
+and the remaining tokens are distributed (case-insensitively) across the
+other still unset pattern-constrained properties of the object. Tokens
+assignable to no property are reported as errors.
+
+### Descriptions and Rationales
+
+The description of a Complex Format object is all block content below
+its heading (up to the next heading) except the property list:
+paragraphs, blockquotes, ordered lists (e.g. scenario steps), and
+fenced code blocks. A fenced code block
+of language `gradia` is skipped, as it is the derived diagram which
+**SpecBook** itself emits into exported Markdown and which must not
+become authored content on a re-parse. In the Concise Format, the
+description is formed by the non-property segments of the item.
+
+A description is split into its *statement* and *rationale* at the first
+`, BECAUSE ` (or `, **BECAUSE** `) occurrence:
+
+```
+The event is created and configured but not visible to attendees,
+BECAUSE an event needs a private setup phase.
+```
+
+### Wiki-Style References
+
+A `[[<reference/>]]` anywhere in a name, property value, description, or
+rationale is a Wiki-style reference to another object, which is checked
+for unique resolvability and rendered as a hyperlink in the HTML/PDF
+exports. A reference is a `.`-separated path of segments, where each
+segment matches a single object as:
+
+-   `<id/>`: the object id or explicit anchor (e.g. `[[attendee]]`)
+-   `<name/>`: the object name (e.g. `[[Attendee Browser]]`)
+-   `<kind/>:<name-or-id/>`: kind-qualified (e.g. `[[ENTITY:Event]]`)
+-   `<kind/>:*` or `*`: wildcards (for match sets, see below)
+
+Each part can be double-quoted to allow spaces, dots, and colons inside
+it (e.g. `[["Vue.js"]]`, whose dot would otherwise be taken as a path
+separator). A multi-segment path matches object chains connected by
+direct parent-to-child steps, where the leading segments up to the root
+may be omitted (e.g. `[[FV.relay]]` matches the object `relay` directly
+below the artifact with id `FV`).
+
+A reference has to resolve to exactly one object: a single-segment
+reference tries the variants (1) id/anchor, (2) name, and (3)
+`<kind/>:<name-or-id/>` in order, where the first variant yielding any
+matches decides; several matches are an ambiguity and zero matches an
+unresolvable reference, both reported by the linter. Wildcard references
+resolve into match *sets* and are used in the schema configuration to
+constrain reference-valued properties (e.g. `[[PERSONA:*]]` or
+`[[DM.ENTITY:*]]`).
+
+### Image Embeddings
+
+A Markdown image `![<alt/>](<file/>)` inside a description or property
+value embeds a local image file, resolved relative to the artifact file:
+SVG files are inlined as-is, PNG/JPEG files are embedded as base64
+`data:` URLs. URLs and other file types are left untouched.
+
+### Normalization
+
+The semantic phase validates the parsed objects against the schema
+configuration (unknown kinds and properties, missing required properties
+and child kinds, and violated value constraints are reported with
+file/line-precise diagnostics) and then normalizes the specification:
+artifacts, child objects, and properties are stably reordered along the
+schema definition, so the exports always present them in their
+configured canonical order.
+
 Schema Configuration
 --------------------
 
@@ -110,8 +273,11 @@ object itself plus all objects below it), `center` names the object a
 `hub` is projected onto (default: `self`), `onlyConnected` drops the
 edge-less nodes of a `graph`, `collapse` (default: `true`) omits a
 degenerated diagram consisting of a single node only, `qualified` labels
-every node with its object kind, and `config` passes arbitrary Gradia
-rendering options (e.g. `grid-columns-max: 5`) through to the diagram.
+every node with its object kind, `properties` lists the property names
+whose values are attached to the 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.
 
 The edges are derived from the `[[xxx]]` references of the node objects
 -- from their property values only, or, with `links: all`, from their
@@ -133,6 +299,22 @@ demonstrate:
 A `grid` is edge-less by definition and hence accepts neither `edges`
 nor `hierarchy`.
 
+An object kind can furthermore carry a `format` field, which controls
+how the HTML/PDF export renders the child objects of every object of
+that kind. Its `type` selects the rendering: `complex` (nested
+sections), `concise` (compact per-kind tables), or the default `auto`,
+which collapses only the deepest level into tables. Below a `concise`
+object, unconfigured childs implicitly stay `concise` and render as
+sub-tables inside the description cells, while an explicitly configured
+`type` is always honored, even a `complex` rendering pressed into a
+cell. `maxTableColumns` (default: `4`) bounds the columns of the compact
+tables below the object (wider groups chunk their properties into
+embedded per-object tables), and `withUnusedProps` (default: `false`)
+unconditionally renders the defined but unused properties of that kind,
+as empty property table lines or table columns. Objects collapsed into
+tables carry no headings and hence leave the table of contents and the
+PDF outline.
+
 Usage
 -----
 
@@ -142,7 +324,6 @@ Usage
 $ specbook init     [-v] [-c <yaml-file>] [-b <basedir>]
 $ specbook lint     [-v] [-c <yaml-file>] [-b <basedir>]
 $ specbook export   [-v] [-c <yaml-file>] [-b <basedir>] [-o [<format>:]<output-file>] [...]
-                    [--max-table-columns <count>]
 $ specbook describe [-v] [-c <yaml-file>] [-o <markdown-file>]
 $ specbook import   [-v] [-c <yaml-file>] [-b <basedir>] <input-files...>
 $ specbook edit     [-v] [-c <yaml-file>] [-b <basedir>] <query>

package/dst/specbook-api.d.ts

@@ -25,7 +25,6 @@ export declare class SpecBook {
         config?: string;
         basedir?: string;
         formats?: ExportFormat[];
-        maxTableColumns?: number;
     }): Promise<Buffer[]>;
     describe(options: {
         config?: string;

package/dst/specbook-api.js

@@ -55,7 +55,7 @@ export class SpecBook {
                 result.diagnostics.map(renderDiagnostic).join("\n"));
         const buffers = [];
         for (const format of options.formats ?? ["json"])
-            buffers.push(await exportSpecification(result.specification, format, this.verbose, options.maxTableColumns, result.config));
+            buffers.push(await exportSpecification(result.specification, format, this.verbose, result.config));
         return buffers;
     }
     /*  describe the configured specification format as Markdown  */

package/dst/specbook-cli.js

@@ -95,7 +95,6 @@ common(program.command("export"))
     .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir", "."))
     .option("-o, --output [<format>:]<output-file>", "output file (\"-\" for stdout, repeatable), with the format inferred " +
     "from the filename extension unless explicitly prefixed", (value, previous) => previous.concat(value), [])
-    .option("--max-table-columns <count>", "maximum name/property/description columns for the compact table rendering", (value) => parseInt(value, 10), parseInt(envDefault("max-table-columns", "4") ?? "4", 10))
     .action(async (opts) => {
     const specbook = new SpecBook({ verbose: verboseOf(opts) });
     const outputs = (opts.output.length > 0 ? opts.output : [envDefault("output") ?? "-"])
@@ -103,7 +102,7 @@ common(program.command("export"))
     /*  parse the input once and export each distinct format once  */
     const distinct = Array.from(new Set(outputs.map(({ format }) => format)));
     const buffers = await specbook.export({ config: opts.config, basedir: opts.basedir,
-        formats: distinct, maxTableColumns: opts.maxTableColumns });
+        formats: distinct });
     for (const { format, output } of outputs)
         await writeOutput(output, buffers[distinct.indexOf(format)], verboseOf(opts));
 });

package/dst/specbook-cmd-export.d.ts

@@ -6,4 +6,4 @@ export declare const parseOutputSpec: (spec: string) => {
     format: ExportFormat;
     output: string;
 };
-export declare const exportSpecification: (specification: Specification, format: ExportFormat, verbose: (msg: string) => void, maxTableColumns?: number, config?: SchemaSpecification) => Promise<Buffer>;
+export declare const exportSpecification: (specification: Specification, format: ExportFormat, verbose: (msg: string) => void, config?: SchemaSpecification) => Promise<Buffer>;

package/dst/specbook-cmd-export.js

@@ -38,7 +38,7 @@ export const parseOutputSpec = (spec) => {
         "(use an explicit \"<format>:<filename>\" specification)");
 };
 /*  export a specification into the requested format  */
-export const exportSpecification = async (specification, format, verbose, maxTableColumns = 4, config) => {
+export const exportSpecification = async (specification, format, verbose, config) => {
     if (!formats.includes(format))
         throw new Error(`unknown export format "${format}"`);
     verbose(`exporting specification as "${format}"`);
@@ -62,7 +62,7 @@ export const exportSpecification = async (specification, format, verbose, maxTab
     const css = themeStylesheet(colors) + await subsetStylesheet(charset) + paperStylesheet(paper);
     if (format === "html") {
         /*  compress the rendered HTML (whitespace, comments, and inline CSS/JS)  */
-        const html = await renderHtml(specification, maxTableColumns, config, undefined, css);
+        const html = await renderHtml(specification, config, undefined, css);
         const minified = await minify(Buffer.from(html, "utf8"), {
             collapseWhitespaces: "smart",
             removeComments: true,
@@ -74,5 +74,5 @@ export const exportSpecification = async (specification, format, verbose, maxTab
     else
         /*  the PDF export (like print in general) always uses the light
             theme, so its decoration colors are the light mapping, too  */
-        return htmlToPdf((tocPages) => renderHtml(specification, maxTableColumns, config, tocPages, css), { ...documentTitle(specification), logo: documentLogo(specification) }, htmlOutline(specification, maxTableColumns), verbose, css, themeMapping(colors, "light"), paper);
+        return htmlToPdf((tocPages) => renderHtml(specification, config, tocPages, css), { ...documentTitle(specification), logo: documentLogo(specification) }, htmlOutline(specification, config), verbose, css, themeMapping(colors, "light"), paper);
 };

package/dst/specbook-diagram.js

@@ -210,6 +210,20 @@ const deriveDiagram = (object, diagram, index, anchors, parents) => {
             attrs.push(`type: ${atom(node.kind)}`);
         if (type === "hub" ? node === center : node.primary === true)
             attrs.push("primary: true");
+        /*  attach the values of the configured properties as Gradia
+            key/value attributes (a node lacking a property is fine, as
+            the node set can mix objects of different kinds), with every
+            "[[...]]" reference stripped to its target object name  */
+        for (const key of diagram.properties ?? []) {
+            const value = node.properties.find((property) => plainKey(property.key) === key)?.value;
+            if (value !== undefined) {
+                const text = value.replace(referenceRegex, (_, reference) => {
+                    const target = resolveUnique(index, reference.trim()).target;
+                    return target !== undefined ? target.name : reference.trim();
+                });
+                attrs.push(`${atom(key)}: ${atom(plainText(text))}`);
+            }
+        }
         lines.push(`${atom(anchor)}: ${atom(plainText(node.name))} [ ${attrs.join(", ")} ]`);
     }
     if (edges.length > 0) {

package/dst/specbook-export-html.css

@@ -192,6 +192,20 @@ table.objects div.description { margin: 0; }
 table.objects div.description > :first-child { margin-top: 0; }
 table.objects div.description > :last-child  { margin-bottom: 0; }
 
+/*  the embedded per-object chunk tables of the over-wide compact tables  */
+table.objects td.chunks     { padding: 0; }
+table.chunks                { border-collapse: collapse; table-layout: fixed;
+                              width: 100%; }
+table.objects table.chunks tr td { background-color: transparent; }
+table.objects table.chunks td:first-child { font-weight: normal; }
+
+/*  the nested renderings inside the description cells of the compact
+    tables ("concise" sub-tables and pressed-in "complex" objects),
+    reduced in size to fit into the cell  */
+table.objects td table.objects { font-size: 85%; margin: 0.5rem 0; }
+table.objects td section    { font-size: 85%; margin: 0.5rem 0; }
+table.objects td section h6 { margin: 0.5rem 0 0.25rem 0; }
+
 p.description,
 div.description             { margin: 1.0rem 0 0.5rem 0; }
 div.description p           { margin: 0.5rem 0; }

package/dst/specbook-export-html.d.ts

@@ -5,5 +5,5 @@ export type OutlineEntry = {
     anchor: string;
     childs: OutlineEntry[];
 };
-export declare const htmlOutline: (specification: Specification, maxColumns: number) => OutlineEntry[];
-export declare const renderHtml: (specification: Specification, maxColumns: number, config?: SchemaSpecification, tocPages?: Map<string, number>, css?: string) => Promise<string>;
+export declare const htmlOutline: (specification: Specification, config?: SchemaSpecification) => OutlineEntry[];
+export declare const renderHtml: (specification: Specification, config?: SchemaSpecification, tocPages?: Map<string, number>, css?: string) => Promise<string>;

package/dst/specbook-export-html.js

@@ -144,6 +144,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 ====  */
@@ -185,11 +211,12 @@ nunjucksAddons(env);
 const safe = (html) => new nunjucks.runtime.SafeString(html);
 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;
 /*  determine the fully-qualified anchor path of an object  */
 const anchorOf = (object) => anchors?.get(object) ?? object.id;
@@ -252,6 +279,32 @@ 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) => {
@@ -264,26 +317,53 @@ 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  */
+const maxColumnsOf = (object) => 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,49 +377,96 @@ 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;
@@ -365,17 +492,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,7 +514,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) => {
+export const renderHtml = async (specification, 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;
@@ -418,6 +546,7 @@ export const renderHtml = async (specification, maxColumns, config, tocPages, cs
     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 +576,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-mcp.js

@@ -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)` }] };

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

@@ -9,6 +9,7 @@ export type SchemaObject = {
     desc?: string;
     optional?: boolean;
     diagram?: SchemaDiagram;
+    format?: SchemaFormat;
     props?: SchemaProperty[];
     childs?: SchemaObject[];
 };
@@ -24,8 +25,14 @@ export type SchemaDiagram = {
     onlyConnected?: boolean;
     collapse?: boolean;
     qualified?: boolean;
+    properties?: string[];
     config?: Partial<GradiaConfig>;
 };
+export type SchemaFormat = {
+    type?: "auto" | "complex" | "concise";
+    maxTableColumns?: number;
+    withUnusedProps?: boolean;
+};
 export type SchemaProperty = {
     name: string;
     desc?: string;

package/dst/specbook-struct-schema.js

@@ -31,8 +31,14 @@ const SchemaDiagram = v.object({
     onlyConnected: v.optional(v.boolean()),
     collapse: v.optional(v.boolean()),
     qualified: v.optional(v.boolean()),
+    properties: v.optional(v.array(v.string())),
     config: v.optional(SchemaDiagramConfig)
 });
+const SchemaFormat = v.object({
+    type: v.optional(v.picklist(["auto", "complex", "concise"])),
+    maxTableColumns: v.optional(v.number()),
+    withUnusedProps: v.optional(v.boolean())
+});
 const SchemaObject = v.object({
     kind: v.string(),
     name: v.optional(v.string()),
@@ -41,6 +47,7 @@ const SchemaObject = v.object({
     desc: v.optional(v.string()),
     optional: v.optional(v.boolean()),
     diagram: v.optional(SchemaDiagram),
+    format: v.optional(SchemaFormat),
     props: v.optional(v.array(SchemaProperty)),
     childs: v.optional(v.array(v.lazy(() => SchemaObject)))
 });

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":                                "@rse/specbook",
-    "version":                             "0.9.2",
+    "version":                             "0.9.3",
     "publishConfig":                       { "access": "public" },
     "description":                         "Markdown-based Specification Format (API, CLI and MCP service)",
     "license":                             "Apache-2.0",
@@ -23,8 +23,8 @@
         "json5":                           "2.2.3",
         "pdf-lib":                         "1.17.1",
         "subset-font":                     "2.5.0",
-        "@rse/mrcs":                       "0.9.1",
-        "@rse/gradia":                     "0.9.4",
+        "@rse/mrcs":                       "0.9.2",
+        "@rse/gradia":                     "0.9.8",
         "@toon-format/toon":               "4.1.1",
         "valibot":                         "1.4.2",
         "nunjucks":                        "3.2.4",
@@ -33,7 +33,7 @@
         "@swc/html":                       "1.16.1",
         "tokenizr":                        "2.2.1",
         "playwright":                      "1.62.1",
-        "ai":                              "7.0.68",
+        "ai":                              "7.0.69",
         "@ai-sdk/anthropic":               "4.0.39",
         "@ai-sdk/openai":                  "4.0.43",
         "@openrouter/ai-sdk-provider":     "3.0.0",