@rse/specbook 1.2.14 → 1.2.16

package/dst/specbook-mcp.js

@@ -4,10 +4,11 @@
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
 import * as fs from "node:fs";
+import * as path from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { SpecBook, renderDiagnostic, renderVerbose, formats, parseOutputSpec, describeFormats, describeParts, compressLevels, version } from "./specbook-api.js";
+import { SpecBook, renderDiagnostic, renderVerbose, formats, parseOutputSpec, describeFormats, describeParts, compressLevels, projectFile, omitAspects, 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);
@@ -22,16 +23,31 @@ const errorResult = (err) => {
 export const serveMcp = async (verbose) => {
     const server = new McpServer({ name: "specbook", version });
     const specbook = new SpecBook({ verbose });
+    /*  the input schema fields shared by the specification processing tools  */
+    const config = z.array(z.string()).optional().describe("YAML schema configuration files or glob " +
+        "patterns, merged in order (\"std\" for the bundled standard schema configuration; " +
+        "default: the SPECBOOK_CONFIG environment variable, else the \"config\" entry " +
+        "of the project configuration file, else the bundled standard " +
+        "schema configuration)");
+    const basedir = z.string().optional().describe("base directory of the specification Markdown files " +
+        "(default: the SPECBOOK_BASEDIR environment variable, else the \"basedir\" entry " +
+        "of the project configuration file, else \".\")");
+    const gitignore = z.boolean().optional().describe("skip the artifact files excluded by the Git " +
+        "exclude rules (the \".gitignore\" files, \"info/exclude\", and the global excludes " +
+        "file), treating such a file exactly like an absent one (default: false)");
+    /*  the working directory of the client, which this server does not
+        necessarily share: it anchors the relative paths and starts the
+        upward search for the project configuration file  */
+    const cwd = z.string().optional().describe("absolute working directory of the caller, against which " +
+        "the relative paths are resolved and from which the project configuration file " +
+        `"${projectFile}" is searched upwards (default: the working directory of the server)`);
+    /*  anchor a relative output file path at the working directory of the caller  */
+    const outputOf = (args, output) => args.cwd !== undefined ? path.resolve(args.cwd, output) : output;
     server.registerTool("specbook_init", {
         title: "Initialize Specification",
         description: "Initialize the configured specification artifact files below the base directory " +
             "with their frontmatter and artifact heading, skipping already existing files.",
-        inputSchema: {
-            config: z.array(z.string()).optional().describe("YAML schema configuration files or glob " +
-                "patterns, merged in order (\"std\" for the bundled standard schema configuration; " +
-                "default: the bundled standard schema configuration)"),
-            basedir: z.string().optional().describe("base directory of the specification Markdown files (default: \".\")")
-        }
+        inputSchema: { config, basedir, cwd }
     }, async (args) => {
         try {
             const created = await specbook.init(args);
@@ -47,15 +63,7 @@ export const serveMcp = async (verbose) => {
         title: "Lint Specification",
         description: "Lint the specification Markdown files the YAML schema configuration references " +
             "below the base directory against this configuration and return all diagnostics.",
-        inputSchema: {
-            config: z.array(z.string()).optional().describe("YAML schema configuration files or glob " +
-                "patterns, merged in order (\"std\" for the bundled standard schema configuration; " +
-                "default: the bundled standard schema configuration)"),
-            basedir: z.string().optional().describe("base directory of the specification Markdown files (default: \".\")"),
-            gitignore: z.boolean().optional().describe("skip the artifact files excluded by the Git " +
-                "exclude rules (the \".gitignore\" files, \"info/exclude\", and the global excludes " +
-                "file), treating such a file exactly like an absent one (default: false)")
-        }
+        inputSchema: { config, basedir, gitignore, cwd }
     }, async (args) => {
         try {
             const result = await specbook.lint(args);
@@ -73,18 +81,17 @@ export const serveMcp = async (verbose) => {
         description: "Export the specification Markdown files the YAML schema configuration references " +
             "below the base directory as JSON, JSON5, " +
             "YAML, TOON, HTML, PDF, or normalized Markdown. The result is written to the output file " +
-            "if an output path is given, else it is returned directly (PDF as a base64-encoded resource).",
-        inputSchema: {
-            config: z.array(z.string()).optional().describe("YAML schema configuration files or glob " +
-                "patterns, merged in order (\"std\" for the bundled standard schema configuration; " +
-                "default: the bundled standard schema configuration)"),
-            basedir: z.string().optional().describe("base directory of the specification Markdown files (default: \".\")"),
+            "if an output path is given, else it is returned directly (PDF as a base64-encoded resource). " +
+            "The normalized Markdown embeds its images as \"data:\" URL definitions (so it is large), and " +
+            "its remaining image references are re-based onto the directory of the " +
+            "output file, while a directly returned result keeps them unchanged.",
+        inputSchema: { config, basedir, gitignore, cwd,
             format: z.enum(formats).optional().describe("output format (default: inferred from the " +
                 "output file extension, else json)"),
             output: z.string().optional().describe("output file path (\"-\" or omitted returns the result directly)"),
-            gitignore: z.boolean().optional().describe("skip the artifact files excluded by the Git " +
-                "exclude rules (the \".gitignore\" files, \"info/exclude\", and the global excludes " +
-                "file), treating such a file exactly like an absent one (default: false)")
+            omit: z.array(z.string()).optional().describe("content aspects to omit from the HTML, " +
+                "the PDF, and (the diagrams) the AST output, instead of leaving them foldable: \"diagram\" " +
+                `(all diagrams) or "${omitAspects.join("\", \"")}" (default: none)`)
         }
     }, async (args) => {
         try {
@@ -94,10 +101,15 @@ export const serveMcp = async (verbose) => {
             const spec = args.format !== undefined || args.output === undefined ?
                 { format: args.format ?? "json", output: args.output } :
                 parseOutputSpec(args.output);
+            /*  the image references of the normalized Markdown are re-based
+                onto the directory of the output file (anchored by the API)  */
+            const rebase = spec.format === "md" && spec.output !== undefined && spec.output !== "-" ?
+                path.dirname(spec.output) : undefined;
             const [data] = await specbook.export({ config: args.config, basedir: args.basedir,
-                formats: [spec.format], gitignore: args.gitignore });
+                cwd: args.cwd, formats: [spec.format], rebase: [rebase], omit: args.omit,
+                gitignore: args.gitignore });
             if (spec.output !== undefined && spec.output !== "-") {
-                await fs.promises.writeFile(spec.output, data);
+                await fs.promises.writeFile(outputOf(args, spec.output), data);
                 return { content: [{ type: "text", text: `exported specification into "${spec.output}" (${data.length} bytes)` }] };
             }
             else if (spec.format === "pdf")
@@ -122,27 +134,32 @@ export const serveMcp = async (verbose) => {
         inputSchema: {
             config: z.array(z.string()).optional().describe("YAML schema configuration files or glob " +
                 "patterns, merged in order (\"std\" for the bundled standard schema configuration; " +
-                "default: the bundled standard schema configuration, embedded)"),
-            basedir: z.string().optional().describe("base directory of the specification Markdown files"),
+                "default: the SPECBOOK_CONFIG environment variable, else the \"config\" entry " +
+                "of the project configuration file, else the bundled standard " +
+                "schema configuration, embedded)"),
+            basedir: z.string().optional().describe("base directory of the specification Markdown files " +
+                "(default: the SPECBOOK_BASEDIR environment variable, else the \"basedir\" entry " +
+                "of the project configuration file)"),
             embed: z.boolean().optional().describe("embed the given YAML schema configuration instead " +
                 "of just referencing it (default: false; the bundled standard one is always embedded)"),
             compress: z.literal(compressLevels).optional().describe("compression level of the emitted " +
                 "YAML schema configuration (embedded or raw): 0 for verbatim, 1 for re-emitted with 2-space " +
-                "indentation and without comments, 2 for additionally without its \"refs\" fields, or 3 for " +
-                "additionally without its \"desc\" fields (default: 1)"),
+                "indentation and without comments, 2 for additionally without its \"refs\", \"diagram\", and " +
+                "\"format\" fields, or 3 for additionally without its \"desc\" fields (default: 2)"),
             format: z.enum(describeFormats).optional().describe("output format: \"md\" for Markdown or " +
                 "\"raw\" for the raw original file content of the part (default: \"md\")"),
             part: z.enum(describeParts).optional().describe("document part: \"all\" for the entire " +
                 "description, \"meta\" for the generic models and formats, \"schema\" for the YAML schema " +
                 "configuration, or \"spec\" for the specification files (default: \"all\"; \"raw\" is " +
                 "available for \"meta\" and \"schema\" only)"),
-            output: z.string().optional().describe("output file path (\"-\" or omitted returns the description directly)")
+            output: z.string().optional().describe("output file path (\"-\" or omitted returns the description directly)"),
+            cwd
         }
     }, async (args) => {
         try {
-            const text = await specbook.describe(args);
+            const text = await specbook.describe({ ...args, compress: args.compress ?? 2 });
             if (args.output !== undefined && args.output !== "-") {
-                await fs.promises.writeFile(args.output, text);
+                await fs.promises.writeFile(outputOf(args, args.output), text);
                 return { content: [{ type: "text", text: `described specification format into "${args.output}"` }] };
             }
             return { content: [{ type: "text", text }] };

package/dst/specbook-parse-common.d.ts

@@ -1,4 +1,4 @@
-import { type Spec, type SpecObject, type SpecProperty } from "./specbook-format-spec.js";
+import { type Spec, type SpecArtifact, type SpecObject, type SpecProperty } from "./specbook-format-spec.js";
 import { type Diagnostic, type DiagnosticSeverity } from "./specbook-diagnostic.js";
 import { type LinkIndex } from "./specbook-link.js";
 export interface SourceFile {
@@ -9,6 +9,7 @@ export interface ParseResult {
     specification: Spec;
     diagnostics: Diagnostic[];
     assets: string[];
+    origins: Map<SpecArtifact, string>;
 }
 export interface ObjectMeta {
     file: string;
@@ -31,3 +32,5 @@ export declare const embeddingRegex: RegExp;
 export declare const embeddingThemes: readonly ["light", "dark"];
 export declare const embeddingVariants: (reference: string) => string[];
 export declare const embeddingMimeType: (reference: string) => string | undefined;
+export declare const embeddingCount: (reference: string | undefined) => number;
+export declare const embeddingDataRegex: RegExp;

package/dst/specbook-parse-common.js

@@ -28,8 +28,10 @@ export class ParseContext {
 }
 /*  the marker separating a statement from its rationale  */
 export const becauseRegex = /,\s*(?:\*\*BECAUSE\*\*|BECAUSE)\s+/;
-/*  the Markdown image embedding syntax ("![alt](file)")  */
-export const embeddingRegex = /!\[([^\]]*)\]\(([^()]+)\)/g;
+/*  the Markdown image embedding syntax: inline ("![alt](file)") or
+    reference-style ("![alt][label]", the label naming a "[label]: data:..."
+    definition, as the normalized Markdown export embeds the images)  */
+export const embeddingRegex = /!\[([^\]]*)\](?:\(([^()]+)\)|\[([^[\]]+)\])/g;
 /*  the theme variants of a theme-aware image embedding  */
 export const embeddingThemes = ["light", "dark"];
 /*  expand an image embedding reference into its variants: a reference
@@ -43,7 +45,8 @@ const embeddingTypes = {
     svg: "image/svg+xml",
     png: "image/png",
     jpg: "image/jpeg",
-    jpeg: "image/jpeg"
+    jpeg: "image/jpeg",
+    webp: "image/webp"
 };
 /*  map a local image embedding reference onto its MIME type
     (URLs and other file types are not embeddable)  */
@@ -53,3 +56,12 @@ export const embeddingMimeType = (reference) => {
     const extension = reference.match(/\.([a-z0-9]+)$/i)?.[1].toLowerCase();
     return extension !== undefined ? embeddingTypes[extension] : undefined;
 };
+/*  the number of embedding entries an image embedding markup occupies,
+    given its inline reference: one per variant of an embeddable one, none
+    for any other one, and one for a reference-style markup (no reference)  */
+export const embeddingCount = (reference) => reference === undefined ? 1 :
+    (embeddingMimeType(reference.trim()) !== undefined ?
+        embeddingVariants(reference.trim()).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+/=]+)$/;

package/dst/specbook-parse-semantic.d.ts

@@ -1,6 +1,6 @@
 import { type Spec, type SpecObject, type SpecProperty } from "./specbook-format-spec.js";
 import { type Schema, type SchemaObject } from "./specbook-format-schema.js";
-import { ParseContext } from "./specbook-parse-common.js";
+import { type ParseContext } from "./specbook-parse-common.js";
 export declare const resolveArtifact: (config: Schema, object: SpecObject) => SchemaObject | undefined;
 export declare const collectSchemas: (specification: Spec, config: Schema) => Map<SpecObject, SchemaObject>;
 export declare const collectParenProps: (schemas: Map<SpecObject, SchemaObject>) => Map<SpecObject, SpecProperty>;

package/dst/specbook-parse-syntax.d.ts

@@ -1,3 +1,3 @@
 import { type SpecArtifact } from "./specbook-format-spec.js";
-import { ParseContext, type SourceFile } from "./specbook-parse-common.js";
+import { type ParseContext, type SourceFile } from "./specbook-parse-common.js";
 export declare const parseFile: (ctx: ParseContext, source: SourceFile) => SpecArtifact[];

package/dst/specbook-parse-syntax.js

@@ -6,7 +6,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { marked } from "marked";
-import { becauseRegex, embeddingRegex, embeddingMimeType, embeddingVariants } from "./specbook-parse-common.js";
+import { becauseRegex, embeddingRegex, embeddingDataRegex, embeddingMimeType, embeddingVariants } from "./specbook-parse-common.js";
 /*  split a description text into statement and optional rationale  */
 const splitDescription = (text) => {
     const m = text.match(becauseRegex);
@@ -98,6 +98,7 @@ const parseFrontmatter = (text) => {
     const missing = { date: null, line: 1, value: null };
     if (m === null)
         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"));
         if (km === null || km.index === undefined)
@@ -116,14 +117,24 @@ const parseFrontmatter = (text) => {
     };
 };
 /*  recursively load the image files embedded via "![alt](file)" into the
-    description and the property values of an object (SVG as-is, PNG/JPEG
+    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)  */
-const embed = (ctx, object, file) => {
+    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)) {
+            if (m[2] === undefined) {
+                const label = m[3].trim().toLowerCase().replace(/\s+/g, " ");
+                const image = defs.get(label);
+                target.embedding ??= [];
+                target.embedding.push(image ?? "");
+                if (image === undefined)
+                    ctx.diagnose(file, line, `unresolvable image reference "${m[3].trim()}"`);
+                continue;
+            }
             const reference = m[2].trim();
             const type = embeddingMimeType(reference);
             if (type === undefined)
@@ -145,13 +156,13 @@ const embed = (ctx, object, file) => {
             }
         }
     };
-    const line = ctx.objectMeta.get(object)?.line ?? 1;
+    const line = ctx.metaOf(object).line;
     if (object.description !== undefined)
         load(object.description, object.description.description, line);
     for (const property of object.properties)
         load(property, property.value, ctx.propMeta.get(property)?.line ?? line);
     for (const child of object.children)
-        embed(ctx, child, file);
+        embed(ctx, child, file, defs);
 };
 /*  parse an unordered list of key-values and/or concise-format objects  */
 const parseList = (ctx, list, object, file, line) => {
@@ -343,6 +354,7 @@ export const parseFile = (ctx, source) => {
     };
     let parts = new Array();
     let partsLine = 1;
+    const defs = new Map();
     /*  collect a description part, remembering the line of the first one  */
     const collect = (raw, line) => {
         if (parts.length === 0)
@@ -393,8 +405,15 @@ export const parseFile = (ctx, source) => {
                 collect(token.raw, line);
         }
         else {
+            /*  an image definition of the Markdown renderer is the one
+                supported link definition (its SVG kept as-is again)  */
+            const def = token.type === "def" ? token : undefined;
+            const m = def?.href.match(embeddingDataRegex) ?? null;
             const unsupported = unsupportedTokens[token.type];
-            if (unsupported !== undefined)
+            if (def !== undefined && m !== null)
+                defs.set(def.tag, m[1] === "image/svg+xml" ?
+                    Buffer.from(m[2], "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;
@@ -403,7 +422,8 @@ export const parseFile = (ctx, source) => {
     /*  load the embedded image files of all fully parsed objects  */
     for (const artifact of state.artifacts)
         for (const object of artifact.objects)
-            embed(ctx, object, source.file);
+            embed(ctx, object, source.file, defs);
+    /*  report a source file carrying no artifact at all  */
     if (state.artifacts.length === 0)
         ctx.diagnose(source.file, 1, "no artifact (level 1 heading) found");
     return state.artifacts;

package/dst/specbook-parse.js

@@ -18,8 +18,12 @@ export const parseSpecification = (sources, config) => {
     const ctx = new ParseContext();
     /*  parse all source files into their artifacts  */
     const artifacts = new Array();
+    const origins = new Map();
     for (const source of sources)
-        artifacts.push(...parseFile(ctx, source));
+        for (const artifact of parseFile(ctx, source)) {
+            artifacts.push(artifact);
+            origins.set(artifact, source.file);
+        }
     const specification = { artifacts };
     /*  validate the resulting specification AST  */
     if (artifacts.length > 0) {
@@ -36,7 +40,7 @@ export const parseSpecification = (sources, config) => {
                 ctx.diagnose(sources[0].file, 1, `internal AST invalid at "${path}": ${issue.message}`);
             }
     }
-    return { specification, diagnostics: ctx.diagnostics, assets: Array.from(ctx.assets) };
+    return { specification, diagnostics: ctx.diagnostics, assets: Array.from(ctx.assets), origins };
 };
 /*  the statistics of a specification: the number of defined objects
     (recursively) and of relationships, i.e. the Wiki-style references

package/dst/specbook-project.d.ts

@@ -0,0 +1,7 @@
+export declare const projectFile = ".specbook.yaml";
+export interface Project {
+    file: string;
+    config?: string[];
+    basedir?: string;
+}
+export declare const loadProject: (dir: string) => Project | undefined;

package/dst/specbook-project.js

@@ -0,0 +1,93 @@
+/*
+**  Specification Book (SpecBook)
+**  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parseDocument, LineCounter } from "yaml";
+import * as v from "valibot";
+import { lineColOfPath } from "./specbook-config.js";
+import { renderDiagnostic } from "./specbook-diagnostic.js";
+/*  the name of the YAML project configuration file  */
+export const projectFile = ".specbook.yaml";
+/*  the schema of the YAML project configuration: the files or glob
+    patterns of the YAML schema configuration and the base directory
+    of the specification Markdown files  */
+const Project = v.strictObject({
+    config: v.optional(v.union([v.pipe(v.string(), v.minLength(1)),
+        v.pipe(v.array(v.pipe(v.string(), v.minLength(1))), v.minLength(1))])),
+    basedir: v.optional(v.pipe(v.string(), v.minLength(1)))
+}, (issue) => issue.expected === "never" ? "unknown project configuration entry" :
+    "expected a map of project configuration entries");
+/*  find the project configuration file in the closest ancestor-or-self
+    of the directory (up to the filesystem root, as the file can reside
+    even above a nested Git working tree)  */
+const findProject = (dir) => {
+    let current = path.resolve(dir);
+    for (;;) {
+        const file = path.join(current, projectFile);
+        if (fs.statSync(file, { throwIfNoEntry: false })?.isFile() === true)
+            return file;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+};
+/*  read the project configuration file, reporting an unreadable file
+    as a positioned diagnostic instead of a raw I/O error  */
+const readProject = (file) => {
+    try {
+        return fs.readFileSync(file, "utf8");
+    }
+    catch (err) {
+        throw new Error("invalid project configuration:\n" + renderDiagnostic({
+            file, line: 1, column: 1, severity: "error",
+            message: "cannot read project configuration file: " +
+                (err instanceof Error ? err.message : String(err))
+        }), { cause: err });
+    }
+};
+/*  find, load, and validate the project configuration, failing on any
+    problem, where its relative paths resolve against the directory of
+    the file itself (and not against the perhaps deeper directory the
+    search started at) and the literal "std" still names the bundled
+    standard schema configuration  */
+export const loadProject = (dir) => {
+    const file = findProject(dir);
+    if (file === undefined)
+        return undefined;
+    const diagnostics = new Array();
+    const lines = new LineCounter();
+    const yaml = readProject(file);
+    const doc = parseDocument(yaml, { lineCounter: lines });
+    for (const err of doc.errors)
+        diagnostics.push({
+            file,
+            line: err.linePos?.[0].line ?? 1,
+            column: err.linePos?.[0].col ?? 1,
+            severity: "error",
+            message: "invalid YAML syntax: " + err.message.replace(/ at line \d+, column \d+(?::\n[\s\S]*)?$/, "")
+        });
+    /*  an empty or comment-only file carries no entries at all  */
+    const result = v.safeParse(Project, doc.errors.length === 0 ? (doc.toJS() ?? {}) : {});
+    if (!result.success)
+        for (const issue of result.issues) {
+            const keys = (issue.path ?? []).map((item) => item.key);
+            const where = keys.length > 0 ? `${keys.join(".")}: ` : "";
+            diagnostics.push({ file, ...lineColOfPath(doc, lines, keys), severity: "error",
+                message: `invalid project configuration: ${where}${issue.message}` });
+        }
+    if (diagnostics.length > 0 || !result.success)
+        throw new Error("invalid project configuration:\n" +
+            diagnostics.map(renderDiagnostic).join("\n"));
+    const base = path.dirname(file);
+    const { config, basedir } = result.output;
+    const patterns = typeof config === "string" ? [config] : config;
+    return {
+        file,
+        config: patterns?.map((pattern) => pattern === "std" ? pattern : path.resolve(base, pattern)),
+        basedir: basedir !== undefined ? path.resolve(base, basedir) : undefined
+    };
+};

package/dst/specbook-theme.d.ts

@@ -2,7 +2,7 @@ export type ThemeStyle = "light" | "dark";
 export type ThemeColors = {
     base: string[];
     accent: string[];
-    search: string[];
+    signal: string[];
 };
 export declare const themeColors: (tone: string) => ThemeColors;
 export declare const themeStylesheet: (colors: ThemeColors) => string;

package/dst/specbook-theme.js

@@ -4,23 +4,24 @@
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
 import { parse, generate } from "@rse/mrcs";
-/*  generate the theme color spreads from the theme color tone:
-    a grey base spread, a tone-derived accent spread, and a search
-    spread derived from the complement-transposed tone  */
+/*  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
+    else from the complement-transposed first tone  */
 export const themeColors = (tone) => {
-    const transposed = tone.endsWith("^") ? tone.slice(0, -1) : `${tone}^`;
+    const [accent, signal = `${accent}^`] = tone.trim().split(/\s+/);
     return {
         base: generate(parse("#000000/32")),
-        accent: generate(parse(`${tone}+40-5/32`)),
-        search: generate(parse(`${transposed}+40-5/32`))
+        accent: generate(parse(`${accent}+40-5/32`)),
+        signal: generate(parse(`${signal}+40-5/32`))
     };
 };
 /*  render the theme colors into the layer-1 ":root" CSS variable
-    block "--theme-color-{base,accent,search}-{1..32}"  */
+    block "--theme-color-{base,accent,signal}-{1..32}"  */
 export const themeStylesheet = (colors) => ":root {\n" +
     colors.base.map((color, i) => `    --theme-color-base-${i + 1}: ${color};\n`).join("") +
     colors.accent.map((color, i) => `    --theme-color-accent-${i + 1}: ${color};\n`).join("") +
-    colors.search.map((color, i) => `    --theme-color-search-${i + 1}: ${color};\n`).join("") +
+    colors.signal.map((color, i) => `    --theme-color-signal-${i + 1}: ${color};\n`).join("") +
     "}\n";
 /*  map the theme color spreads onto the semantic theme colors,
     aligned with the layer-2 CSS mapping of the HTML rendering  */

package/dst/specbook-verbose.js

@@ -11,15 +11,10 @@ export const verbosityOf = { none: 0, notice: 1, detail: 2, trace: 3 };
 /*  parse and validate a verbosity specification, where a bare flag (or
     a boolean word) selects the regular processing information  */
 export const parseVerbosity = (value) => {
-    let level;
-    if (typeof value === "boolean")
-        level = value ? 1 : 0;
-    else if (typeof value === "string" && (/^(?:true|yes|on)$/i).test(value))
-        level = 1;
-    else if (typeof value === "string" && (/^(?:false|no|off)$/i).test(value))
-        level = 0;
-    else
-        level = typeof value === "string" && !(/^\d+$/).test(value) ? NaN : Number(value);
+    const text = String(value);
+    const level = (/^(?:true|yes|on)$/i).test(text) ? 1 :
+        (/^(?:false|no|off)$/i).test(text) ? 0 :
+            (/^\d+$/).test(text) ? Number(text) : NaN;
     if (!verbosities.includes(level))
         throw new Error(`unknown verbosity "${value}" ` +
             `(supported: ${verbosities.join(", ")})`);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":                                "@rse/specbook",
-    "version":                             "1.2.14",
+    "version":                             "1.2.16",
     "publishConfig":                       { "access": "public" },
     "description":                         "Markdown-based Specification Format (API, CLI and MCP service)",
     "license":                             "Apache-2.0",
@@ -23,8 +23,10 @@
         "json5":                           "2.2.3",
         "pdf-lib":                         "1.17.1",
         "subset-font":                     "2.7.0",
+        "sharp":                           "0.35.4",
+        "svgo":                            "4.1.0",
         "@rse/mrcs":                       "0.9.2",
-        "@rse/gradia":                     "1.2.3",
+        "@rse/gradia":                     "1.4.2",
         "@toon-format/toon":               "4.1.1",
         "valibot":                         "1.5.0",
         "nunjucks":                        "3.2.4",
@@ -54,14 +56,14 @@
         "neostandard":                     "0.14.0-next.1",
         "globals":                         "17.12.0",
         "markdownlint":                    "0.41.1",
-        "markdownlint-cli2":               "0.23.2",
-        "@types/node":                     "26.6.1",
+        "markdownlint-cli2":               "0.23.3",
+        "@types/node":                     "26.6.2",
         "@types/picomatch":                "4.0.3",
         "@types/subset-font":              "2.3.0",
         "@types/nunjucks":                 "3.2.6",
         "@types/ws":                       "8.18.1",
         "typescript":                      "6.0.3",
-        "tsx":                             "4.23.13",
+        "tsx":                             "4.23.15",
         "source-sans":                     "3.52.0",
         "source-code-pro":                 "2.42.0",
         "@fontsource/noto-sans-symbols":   "5.3.0",
@@ -71,7 +73,13 @@
         "stylus":                          "0.64.0",
         "@rse/stx":                        "1.1.7",
         "shx":                             "0.4.0",
-        "nodemon":                         "3.1.14"
+        "nodemon":                         "3.1.14",
+        "json-asty":                       "1.3.4",
+        "stdver":                          "0.9.17"
+    },
+    "engines": {
+        "npm":                              ">=10.0.0",
+        "node":                             ">=22.13.0"
     },
     "upd":                                 [ "!eslint", "!@eslint/js", "!typescript" ],
     "allowScripts": {