@rse/specbook 1.3.1 → 1.4.0

package/dst/specbook-parse-common.js

@@ -3,6 +3,7 @@
 **  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
+import { bundledLanguagesInfo } from "shiki/langs";
 /*  the state shared between the syntactic and semantic parsing phases  */
 export class ParseContext {
     diagnostics = new Array();
@@ -40,21 +41,129 @@ export const embeddingThemes = ["light", "dark"];
 export const embeddingVariants = (reference) => reference.includes("{theme}") ?
     embeddingThemes.map((theme) => reference.replace(/\{theme\}/g, theme)) :
     [reference];
-/*  the embeddable file types and their MIME types  */
-const embeddingTypes = {
+/*  the MIME type of a PDF document  */
+export const pdfType = "application/pdf";
+/*  the MIME type of a source code file, carrying its language as the
+    "lang" parameter  */
+export const codeType = "text/x-code";
+/*  the embeddable file types and their MIME types: the images plus the
+    diagram sources (Mermaid and D2) and the documents (PDF), which the
+    exports render  */
+const fileTypes = {
     svg: "image/svg+xml",
     png: "image/png",
     jpg: "image/jpeg",
     jpeg: "image/jpeg",
-    webp: "image/webp"
+    webp: "image/webp",
+    mmd: "text/vnd.mermaid",
+    mermaid: "text/vnd.mermaid",
+    d2: "text/vnd.d2",
+    pdf: pdfType
 };
-/*  map a local image embedding reference onto its MIME type
-    (URLs and other file types are not embeddable)  */
-export const embeddingMimeType = (reference) => {
+/*  the code languages of the code listings, keyed by every id and alias
+    of the Shiki languages (except those the file types above take) and
+    mapped onto the language id  */
+const codeLanguages = new Map(bundledLanguagesInfo
+    .flatMap((info) => [info.id, ...info.aliases ?? []].map((name) => [name, info.id]))
+    .filter(([name]) => fileTypes[name] === undefined));
+/*  map a language name (of a fenced code block) onto the language id
+    of a code listing (undefined for no or an unknown language)  */
+export const codeLanguage = (name) => codeLanguages.get(name.toLowerCase());
+/*  the embeddable file types plus the source code files, whose file
+    extensions are the language ids and aliases  */
+const embeddingTypes = new Map([
+    ...Array.from(codeLanguages, ([name, id]) => [name, `${codeType};lang=${id}`]),
+    ...Object.entries(fileTypes)
+]);
+/*  the patterns of the parameters: a 1-based line or page number, a
+    range of lines, and the hunks of lines to mark  */
+const ordinal = /^[1-9]\d*$/;
+const lineRange = /^[1-9]\d*(?:-[1-9]\d*)?$/;
+const lineHunks = /^[1-9]\d*(?:-[1-9]\d*)?(?:,[1-9]\d*(?:-[1-9]\d*)?)*$/;
+/*  turn the hunks of a "mark" parameter into a line number membership test
+    (checking the ranges instead of expanding them, as a range is unbounded)  */
+export const markedLines = (mark) => {
+    const hunks = mark.split(",").filter((hunk) => hunk !== "").map((hunk) => {
+        const [first, last = first] = hunk.split("-").map(Number);
+        return { first, last };
+    });
+    return { has: (line) => hunks.some((hunk) => line >= hunk.first && line <= hunk.last) };
+};
+/*  split the info string of a fenced code block into its language and its
+    whitespace-separated listing parameters ("start" and "mark"), plus an
+    error message for an unknown or repeated key or an invalid value  */
+const fenceParams = { start: ordinal, mark: lineHunks };
+export const fenceInfo = (info) => {
+    const [lang = "", ...pairs] = (info ?? "").trim().split(/\s+/);
+    const params = {};
+    for (const pair of pairs) {
+        const m = pair.match(/^([a-z]+)=(.*)$/s);
+        if (m === null || params[m[1]] !== undefined || !(fenceParams[m[1]]?.test(m[2]) ?? false))
+            return { lang, params, error: `invalid parameter "${pair}" of fenced code block` };
+        params[m[1]] = m[2];
+    }
+    return { lang, params };
+};
+/*  the fragment parameters ("#<key>=<value>&...") each file type accepts,
+    with the patterns of their values: the treatment on the dark theme
+    of an image and a document, the 1-based page of a document, and the
+    excerpt and the marked lines of a source code file  */
+const darkAuto = /^(?:auto|invert|none)$/;
+const fragmentParams = {
+    "image/svg+xml": { dark: darkAuto },
+    "image/png": { dark: darkAuto },
+    "image/jpeg": { dark: darkAuto },
+    "image/webp": { dark: darkAuto },
+    [pdfType]: { page: ordinal, dark: darkAuto },
+    [codeType]: { lines: lineRange, mark: lineHunks }
+};
+/*  split an embedding reference into its file and its fragment parameters
+    (URI-decoded and in the canonical order of its type), or undefined for
+    a fragment its type does not accept (an unknown or repeated key, or an
+    invalid value)  */
+export const embeddingFragment = (reference, type) => {
+    const hash = reference.indexOf("#", reference.lastIndexOf("/") + 1);
+    if (hash < 0)
+        return { file: reference, params: {} };
+    const accepted = fragmentParams[type.replace(/;.*$/, "")] ?? {};
+    const given = new Map();
+    for (const pair of reference.slice(hash + 1).split("&")) {
+        const m = pair.match(/^([a-z]+)=(.*)$/s);
+        if (m === null || given.has(m[1]))
+            return undefined;
+        let value = m[2];
+        try {
+            value = decodeURIComponent(value);
+        }
+        catch {
+            /*  an invalid escape sequence is taken literally  */
+        }
+        if (!Object.hasOwn(accepted, m[1]) || !accepted[m[1]].test(value))
+            return undefined;
+        given.set(m[1], value);
+    }
+    const params = {};
+    for (const key of Object.keys(accepted)) {
+        const value = given.get(key);
+        if (value !== undefined)
+            params[key] = value;
+    }
+    return { file: reference.slice(0, hash), params };
+};
+/*  map a local image embedding reference onto the MIME type of its file
+    (URLs and other file types are not embeddable), regardless of any
+    fragment  */
+export const embeddingFileType = (reference) => {
     if (/^[a-z][a-z0-9+.-]+:/i.test(reference))
         return undefined;
-    const extension = reference.match(/\.([a-z0-9]+)$/i)?.[1].toLowerCase();
-    return extension !== undefined ? embeddingTypes[extension] : undefined;
+    const m = reference.match(/^.*?\.([a-z0-9]+)(?:#.*)?$/is);
+    return m !== null ? embeddingTypes.get(m[1].toLowerCase()) : undefined;
+};
+/*  map a local image embedding reference onto its MIME type, provided its
+    fragment (if any) is one its type accepts  */
+export const embeddingMimeType = (reference) => {
+    const type = embeddingFileType(reference);
+    return type !== undefined && embeddingFragment(reference, type) !== undefined ? type : undefined;
 };
 /*  the number of embedding entries an image embedding markup occupies,
     given its inline reference: one per variant of an embeddable one, none
@@ -66,5 +175,23 @@ export const embeddingCount = (reference) => {
     return embeddingMimeType(trimmed) !== undefined ? embeddingVariants(trimmed).length : 0;
 };
 /*  the image definition ("[label]: data:...") a reference-style image
-    embedding refers to: a base64 data: URL of an embeddable image type  */
-export const embeddingDataRegex = /^data:(image\/(?:svg\+xml|png|jpeg|webp));base64,([A-Za-z0-9+/=]+)$/;
+    embedding refers to: a base64 data: URL of an embeddable image type,
+    optionally marked with its treatment on the dark theme, or of a source
+    code file, carrying its language, start line, and marked lines  */
+export const embeddingDataRegex = /^data:(image\/(?:svg\+xml|png|jpeg|webp)|text\/x-code;lang=[^;,]+;start=\d+(?:;mark=[^;,]+)?)(;dark=(?:invert|none))?;base64,([A-Za-z0-9+/=]+)$/;
+/*  split an embedded image or document content (an SVG text or a data:
+    URL) into its plain content and its explicit treatment on the dark
+    theme, which a "#dark=invert" or "#dark=none" fragment (deviating from
+    the default "auto") turns into the "dark" data: URL parameter directly
+    behind the MIME type (an SVG hence becoming a data: URL, too)  */
+export const darkMark = (content) => {
+    const m = content.match(/^data:([^;,]+);dark=(invert|none)((?:;[a-z]+=[^;,]*)*);base64,(.*)$/s);
+    if (m === null)
+        return { content };
+    return { dark: m[2], content: m[1] === "image/svg+xml" && m[3] === "" ?
+            Buffer.from(m[4], "base64").toString("utf8") : `data:${m[1]}${m[3]};base64,${m[4]}` };
+};
+/*  mark a plain embedded image or document content with its explicit
+    treatment on the dark theme  */
+export const markDark = (content, dark) => content.startsWith("data:") ? content.replace(/^(data:[^;,]+)/, `$1;dark=${dark}`) :
+    `data:image/svg+xml;dark=${dark};base64,${Buffer.from(content, "utf8").toString("base64")}`;

package/dst/specbook-parse-semantic.js

@@ -516,6 +516,8 @@ export const validateReferences = (ctx, specification) => {
             check(object, object.description.description, meta.file, meta.line);
             if (object.description.rationale !== undefined)
                 check(object, object.description.rationale, meta.file, meta.line);
+            if (object.description.elaboration !== undefined)
+                check(object, object.description.elaboration, meta.file, meta.line);
         }
         object.children.forEach(walk);
     };

package/dst/specbook-parse-syntax.js

@@ -6,15 +6,22 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { marked } from "marked";
-import { becauseRegex, embeddingRegex, embeddingDataRegex, embeddingMimeType, embeddingVariants } from "./specbook-parse-common.js";
-/*  split a description text into statement and optional rationale  */
+import { becauseRegex, embeddingRegex, embeddingDataRegex, embeddingMimeType, embeddingFileType, embeddingVariants, embeddingFragment, markDark, pdfType, codeType, codeLanguage, fenceInfo } from "./specbook-parse-common.js";
+/*  split a description text into statement and optional rationale, where
+    the rationale ends with its paragraph and any blocks following it
+    (further paragraphs, images, diagrams) form the elaboration  */
 const splitDescription = (text) => {
     const m = text.match(becauseRegex);
     if (m === null || m.index === undefined)
         return { description: text };
+    const rest = text.slice(m.index + m[0].length);
+    const end = rest.search(/\n[ \t]*\n/);
+    if (end < 0)
+        return { description: text.slice(0, m.index), rationale: rest };
     return {
         description: text.slice(0, m.index),
-        rationale: text.slice(m.index + m[0].length)
+        rationale: rest.slice(0, end),
+        elaboration: rest.slice(end).trim()
     };
 };
 /*  strip the trailing explicit Wiki-style anchor ("{{xxx}}"), the
@@ -100,7 +107,7 @@ const parseFrontmatter = (text) => {
         return { present: false, created: missing, modified: missing, body: text, offset: 0 };
     /*  grab a single timestamp key with its raw value and source line  */
     const grab = (key) => {
-        const km = m[1].match(new RegExp(`^${key}:\\s*(.+)$`, "m"));
+        const km = m[1].match(new RegExp(`^${key}:[ \\t]*(.+)$`, "m"));
         if (km === null || km.index === undefined)
             return missing;
         const line = 2 + (m[1].slice(0, km.index).match(/\n/g) ?? []).length;
@@ -116,13 +123,15 @@ const parseFrontmatter = (text) => {
         offset: (m[0].match(/\n/g) ?? []).length
     };
 };
-/*  recursively load the image files embedded via "![alt](file)" into the
-    description and the property values of an object (SVG as-is, PNG/JPEG/WebP
-    as base64 data: URLs), resolving the references relative to the source
-    file and expanding a "{theme}" reference into its theme variants,
-    which are loaded into consecutive embedding entries (an unreadable
-    file leaves an empty entry, keeping the positions aligned), while a
-    reference-style "![alt][label]" takes the image of its definition  */
+/*  recursively load the files embedded via "![alt](file)" into the
+    description and the property values of an object (SVG as-is, the
+    PNG/JPEG/WebP images, PDF documents, Mermaid/D2 diagram sources, and
+    source code excerpts as base64 data: URLs), resolving the references
+    relative to the source file and expanding a "{theme}" reference into
+    its theme variants, which are loaded into consecutive embedding
+    entries (an unreadable file leaves an empty entry, keeping the
+    positions aligned), while a reference-style "![alt][label]" takes
+    the image of its definition  */
 const embed = (ctx, object, file, defs) => {
     const load = (target, text, line) => {
         for (const m of text.matchAll(embeddingRegex)) {
@@ -137,16 +146,58 @@ const embed = (ctx, object, file, defs) => {
             }
             const reference = m[2].trim();
             const type = embeddingMimeType(reference);
-            if (type === undefined)
+            if (type === undefined) {
+                if (embeddingFileType(reference) !== undefined)
+                    ctx.diagnose(file, line, `invalid fragment of embedding "${reference}"`);
                 continue;
+            }
             for (const variant of embeddingVariants(reference)) {
+                /*  the page a fragment of a document selects travels as a
+                    parameter of its data: URL, while an image or document
+                    gets marked with an explicit treatment on the dark theme
+                    deviating from its default ("auto"), unless its "{theme}"
+                    variants already serve the dark theme  */
                 target.embedding ??= [];
-                const asset = path.resolve(path.dirname(file), variant);
+                const split = embeddingFragment(variant, type) ?? { file: variant, params: {} };
+                const image = type.startsWith("image/") || type === pdfType;
+                const asset = path.resolve(path.dirname(file), split.file);
+                const params = Object.entries(split.params).filter(([key]) => key !== "dark")
+                    .map(([key, value]) => `;${key}=${encodeURIComponent(value)}`).join("");
                 ctx.assets.add(asset);
+                if (type.startsWith(`${codeType};`)) {
+                    /*  a source code file is embedded as the excerpt of its
+                        lines, numbered from its first line, with the hunks
+                        of its marked lines  */
+                    try {
+                        const lines = fs.readFileSync(asset, "utf8").replace(/\r?\n$/, "").split(/\r?\n/);
+                        const range = split.params.lines ?? `1-${lines.length}`;
+                        const [first, last = first] = range.split("-").map(Number);
+                        if (first > lines.length || last < first) {
+                            target.embedding.push("");
+                            ctx.diagnose(file, line, `empty line range "${range}" of embedding "${variant}"`);
+                            continue;
+                        }
+                        const mark = split.params.mark !== undefined ?
+                            `;mark=${encodeURIComponent(split.params.mark)}` : "";
+                        const code = lines.slice(first - 1, last).join("\n");
+                        target.embedding.push(`data:${type};start=${first}${mark};base64,` +
+                            Buffer.from(code, "utf8").toString("base64"));
+                    }
+                    catch (err) {
+                        target.embedding.push("");
+                        ctx.diagnose(file, line, `unreadable embedding file "${variant}": ` +
+                            (err instanceof Error ? err.message : String(err)));
+                    }
+                    continue;
+                }
                 try {
                     const data = fs.readFileSync(asset);
-                    target.embedding.push(type === "image/svg+xml" ?
-                        data.toString("utf8") : `data:${type};base64,${data.toString("base64")}`);
+                    const content = type === "image/svg+xml" ?
+                        data.toString("utf8") : `data:${type}${params};base64,${data.toString("base64")}`;
+                    const dark = split.params.dark;
+                    const mark = image && !reference.includes("{theme}")
+                        && (dark === "invert" || dark === "none") ? dark : undefined;
+                    target.embedding.push(mark !== undefined ? markDark(content, mark) : content);
                 }
                 catch (err) {
                     target.embedding.push("");
@@ -157,8 +208,17 @@ const embed = (ctx, object, file, defs) => {
         }
     };
     const line = ctx.metaOf(object).line;
-    if (object.description !== undefined)
+    if (object.description !== undefined) {
         load(object.description, object.description.description, line);
+        load(object.description, object.description.elaboration ?? "", line);
+        /*  validate the listing parameters of the fenced code blocks  */
+        for (const text of [object.description.description, object.description.elaboration ?? ""])
+            marked.walkTokens(marked.lexer(text), (token) => {
+                const info = token.type === "code" ? fenceInfo(token.lang) : undefined;
+                if (info?.error !== undefined && codeLanguage(info.lang) !== undefined)
+                    ctx.diagnose(file, line, info.error);
+            });
+    }
     for (const property of object.properties)
         load(property, property.value, ctx.propMeta.get(property)?.line ?? line);
     for (const child of object.children)
@@ -415,20 +475,21 @@ export const parseFile = (ctx, source) => {
         }
         else {
             /*  an image definition of the Markdown renderer is the one
-                supported link definition (its SVG kept as-is again)  */
+                supported link definition (its SVG kept as-is again,
+                unless marked as inverted on the dark theme)  */
             const def = token.type === "def" ? token : undefined;
             const m = def?.href.match(embeddingDataRegex) ?? null;
             const unsupported = unsupportedTokens[token.type];
             if (def !== undefined && m !== null)
-                defs.set(def.tag, m[1] === "image/svg+xml" ?
-                    Buffer.from(m[2], "base64").toString("utf8") : def.href);
+                defs.set(def.tag, m[1] === "image/svg+xml" && m[2] === undefined ?
+                    Buffer.from(m[3], "base64").toString("utf8") : def.href);
             else if (unsupported !== undefined)
                 ctx.diagnose(source.file, line, `unsupported ${unsupported} content ignored`);
         }
         line += (token.raw.match(/\n/g) ?? []).length;
     }
     flush();
-    /*  load the embedded image files of all fully parsed objects  */
+    /*  load the embedded files of all fully parsed objects  */
     for (const artifact of state.artifacts)
         for (const object of artifact.objects)
             embed(ctx, object, source.file, defs);

package/dst/specbook-parse.js

@@ -52,7 +52,7 @@ export const specStatistics = (specification) => {
         objects++;
         const texts = [object.name, ...object.properties.map((p) => p.value)];
         if (object.description !== undefined)
-            texts.push(object.description.description, object.description.rationale ?? "");
+            texts.push(object.description.description, object.description.rationale ?? "", object.description.elaboration ?? "");
         for (const text of texts)
             links += (plainText(text).match(referenceRegex) ?? []).length;
         object.children.forEach(walk);

package/dst/specbook-theme.d.ts

@@ -4,6 +4,7 @@ export type ThemeColors = {
     accent: string[];
     signal: string[];
 };
+export declare const themeToneDefault = "#336699";
 export declare const themeColors: (tone: string) => ThemeColors;
 export declare const themeStylesheet: (colors: ThemeColors) => string;
 export type ThemeMapping = {

package/dst/specbook-theme.js

@@ -4,6 +4,8 @@
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
 import { parse, generate } from "@rse/mrcs";
+/*  the theme color tone of a document carrying no THEME-TONE  */
+export const themeToneDefault = "#336699";
 /*  generate the theme color spreads from the theme color tone(s):
     a grey base spread, an accent spread derived from the first tone,
     and a signal spread derived from the second tone (if given) or

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":                                "@rse/specbook",
-    "version":                             "1.3.1",
+    "version":                             "1.4.0",
     "publishConfig":                       { "access": "public" },
     "description":                         "Markdown-based Specification Format (API, CLI and MCP service)",
     "license":                             "Apache-2.0",
@@ -23,49 +23,55 @@
         "json5":                           "2.2.3",
         "pdf-lib":                         "1.17.1",
         "subset-font":                     "2.9.0",
-        "sharp":                           "0.35.4",
+        "sharp":                           "0.35.5",
         "svgo":                            "4.1.0",
         "@rse/mrcs":                       "0.9.2",
         "@rse/gradia":                     "1.4.2",
+        "beautiful-mermaid":               "1.1.3",
+        "@terrastruct/d2":                 "0.1.33",
+        "shiki":                           "4.5.0",
+        "pdfjs-dist":                      "6.4.299",
+        "@napi-rs/canvas":                 "1.0.10",
         "@toon-format/toon":               "4.1.1",
         "valibot":                         "1.5.0",
         "nunjucks":                        "3.2.4",
         "@rse/nunjucks-addons":            "2.2.0",
         "textframe":                       "1.2.1",
-        "@swc/html":                       "1.16.2",
+        "@swc/html":                       "1.16.13",
         "tokenizr":                        "2.2.1",
         "playwright":                      "1.63.0",
         "source-code-error":               "1.2.0",
         "commander":                       "15.0.0",
-        "chalk":                           "6.0.0",
+        "chalk":                           "6.0.1",
         "chokidar5":                       "npm:chokidar@5.0.0",
         "glob":                            "13.0.6",
         "picomatch":                       "4.0.7",
         "es-toolkit":                      "1.52.0",
         "fastify":                         "5.12.5",
-        "@fastify/websocket":              "11.3.1",
-        "@modelcontextprotocol/sdk":       "1.30.0",
+        "@fastify/websocket":              "11.3.3",
+        "@modelcontextprotocol/sdk":       "1.32.0",
         "zod":                             "4.6.5"
     },
     "devDependencies": {
         "chokidar-cli":                    "3.0.0",
         "eslint":                          "10.9.0",
         "@eslint/js":                      "10.0.1",
-        "typescript-eslint":               "8.70.1",
+        "typescript-eslint":               "8.71.0",
         "eslint-plugin-promise":           "7.3.0",
         "neostandard":                     "0.14.0-next.1",
-        "globals":                         "17.12.0",
+        "globals":                         "17.13.0",
+        "eslint-plugin-yml":               "3.8.1",
         "markdownlint":                    "0.41.1",
         "markdownlint-cli2":               "0.23.3",
-        "@types/node":                     "26.6.2",
+        "@types/node":                     "26.6.4",
         "@types/picomatch":                "4.0.3",
         "@types/subset-font":              "2.3.0",
         "@types/nunjucks":                 "3.2.6",
-        "@types/ws":                       "8.18.1",
+        "@types/ws":                       "8.18.2",
         "typescript":                      "6.0.3",
         "tsx":                             "4.23.15",
         "source-sans":                     "3.52.0",
-        "source-code-pro":                 "2.42.0",
+        "@fontsource/dejavu-mono":         "5.3.0",
         "@fontsource/noto-sans-symbols":   "5.3.0",
         "postcss":                         "8.5.28",
         "postcss-cli":                     "12.0.0",