@rse/specbook 1.0.1 → 1.0.3

package/README.md

@@ -22,63 +22,63 @@ CLI with commands `specbook <xxx>`, and an MCP service with tools
 
 **SpecBook** provides the following distinct features:
 
-- **Hierarchical Object Model**:
-  A specification is a tree of typed objects, each with a kind and
-  name, an optional id, optional properties, optional description, and
-  optional child objects. The allowed object hierarchy is defined per
-  context by the YAML schema configuration.
-
-- **Versatile Object to Markdown Mapping**:
-  Objects are authored as plain Markdown headings, property lists,
-  and description prose. The objects can be mapped to nested sections
-  ("complex" format) or compact bullet point lists ("concise" and
-  "group" format).
-
-- **Wiki-Style Object Linking**:
-  Objects can hierarchically reference each other through Wiki-style
-  `[[xxx]]` references, which are resolved against the locally-unique
-  ids and names of all objects. In the HTML and PDF exports they become
-  navigable links onto precise anchors.
-
-- **Strict Validation with Custom Schema**:
-  The YAML schema configuration strictly defines the allowed object
-  kinds, hierarchies, and properties, whose values are constrained by an
-  expression language (regex, enum, tags, list, and reference). Violations
-  are reported as file- and line-precise diagnostics. A bundled standard
-  schema configuration applies if no particular one is given.
-
-- **Object Model Diagram Visualisation**:
-  Object kinds can declare "graph", "hub", or "grid" diagrams in the
-  schema, whose nodes and edges are automatically derived from the
-  object model and its references. The diagrams are rendered with the
-  sibling project [Gradia](https://github.com/rse/gradia), which is
-  specialized in rendering object models.
-
-- **CLI, MCP, and API Interface**:
-  All commands are implemented once in the API class `SpecBook`, on
-  which both the CLI and the MCP service are just thin wrappers.
-  This way, humans, scripts, and AI agents use exactly the same
-  functionality.
-
-- **AST Exports for AI/LLMs**:
-  The parsed specification Abstract Syntax Tree (AST) can be exported in
-  JSON, JSON5, YAML, or TOON format for machine consumption. Together
-  with the `describe` command, which explains the models and formats,
-  this enables LLMs to both read and write specifications.
-
-- **HTML Export for Developers**:
-  The HTML export is a self-contained single document with a
-  table-of-contents, full-text search, embedded images, and a light/dark
-  theme toggle. It is intended for the day-to-day online reading during
-  development. The HTML export can map all object kinds to nested
-  sections or compact tables, or an automatic mixture which collapses
-  only the deepest level into tables.
-
-- **PDF Export for Customers**:
-  The PDF export prints the HTML rendering via Chromium and post-processes
-  it with page numbers, headers/footers, and a hierarchical PDF outline.
-  It is intended as a polished, paginated offline document for handing
-  over to customers.
+-   **Hierarchical Object Model**:
+    A specification is a tree of typed objects, each with a kind and
+    name, an optional id, optional properties, optional description, and
+    optional child objects. The allowed object hierarchy is defined per
+    context by the YAML schema configuration.
+
+-   **Versatile Object to Markdown Mapping**:
+    Objects are authored as plain Markdown headings, property lists,
+    and description prose. The objects can be mapped to nested sections
+    ("complex" format) or compact bullet point lists ("concise" and
+    "group" format).
+
+-   **Wiki-Style Object Linking**:
+    Objects can hierarchically reference each other through Wiki-style
+    `[[xxx]]` references, which are resolved against the locally-unique
+    ids and names of all objects. In the HTML and PDF exports they become
+    navigable links onto precise anchors.
+
+-   **Strict Validation with Custom Schema**:
+    The YAML schema configuration strictly defines the allowed object
+    kinds, hierarchies, and properties, whose values are constrained by an
+    expression language (regex, enum, tags, list, and reference). Violations
+    are reported as file- and line-precise diagnostics. A bundled standard
+    schema configuration applies if no particular one is given.
+
+-   **Object Model Diagram Visualisation**:
+    Object kinds can declare "graph", "hub", or "grid" diagrams in the
+    schema, whose nodes and edges are automatically derived from the
+    object model and its references. The diagrams are rendered with the
+    sibling project [Gradia](https://github.com/rse/gradia), which is
+    specialized in rendering object models.
+
+-   **CLI, MCP, and API Interface**:
+    All commands are implemented once in the API class `SpecBook`, on
+    which both the CLI and the MCP service are just thin wrappers.
+    This way, humans, scripts, and AI agents use exactly the same
+    functionality.
+
+-   **AST Exports for AI/LLMs**:
+    The parsed specification Abstract Syntax Tree (AST) can be exported in
+    JSON, JSON5, YAML, or TOON format for machine consumption. Together
+    with the `describe` command, which explains the models and formats,
+    this enables LLMs to both read and write specifications.
+
+-   **HTML Export for Developers**:
+    The HTML export is a self-contained single document with a
+    table-of-contents, full-text search, embedded images, and a light/dark
+    theme toggle. It is intended for the day-to-day online reading during
+    development. The HTML export can map all object kinds to nested
+    sections or compact tables, or an automatic mixture which collapses
+    only the deepest level into tables.
+
+-   **PDF Export for Customers**:
+    The PDF export prints the HTML rendering via Chromium and post-processes
+    it with page numbers, headers/footers, and a hierarchical PDF outline.
+    It is intended as a polished, paginated offline document for handing
+    over to customers.
 
 Overview
 --------
@@ -97,84 +97,235 @@ $ npm install -g @rse/specbook
 Usage
 -----
 
-### CLI
+### API
 
-```bash
-$ 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>] [...]
-$ specbook describe [-v] [-c <yaml-file>] [-b <basedir>] [-e] [-f <format>] [-p <part>] [-o <markdown-file>]
-$ specbook mcp      [-v]
+```ts
+/*  the SpecBook API, providing all commands the CLI and MCP service expose  */
+export class SpecBook {
+    constructor (options?: SpecBookOptions)
+
+    /*  initialize the configured specification artifact files below the
+        base directory and return the list of the generated files  */
+    init (options: {
+        config?:  string,          /*  YAML schema configuration (default: bundled standard one)  */
+        basedir?: string           /*  base directory (default: ".")  */
+    }): Promise<string[]>
+
+    /*  parse and validate the specification Markdown files below the base directory  */
+    lint (options: {
+        config?:  string,
+        basedir?: string
+    }): Promise<LintResult>
+
+    /*  export the specification, parsing the input just once and
+        returning one buffer per requested format (strict: any diagnostic
+        rejects the export with an "Error")  */
+    export (options: {
+        config?:  string,
+        basedir?: string,
+        formats?: ExportFormat[]   /*  requested output formats (default: [ "json" ])  */
+    }): Promise<Buffer[]>
+
+    /*  describe the SpecBook models and formats, optionally pointing to
+        the artifacts of the particular project  */
+    describe (options: {
+        config?:  string,
+        basedir?: string,
+        embed?:   boolean,         /*  embed the schema configuration instead of referencing it  */
+        format?:  DescribeFormat,  /*  output format (default: "md")  */
+        part?:    DescribePart     /*  document part (default: "all")  */
+    }): Promise<string>
+}
+
+/*  the constructor options and the sink of the verbose messages,
+    receiving the emitting command and the message  */
+export interface SpecBookOptions {
+    verbose?:      VerboseSink
+}
+export type VerboseSink = (cmd: string, msg: string) => void
+
+/*  the result of the "lint" command and its file- and line-precise diagnostics  */
+export interface LintResult {
+    specification: Spec
+    diagnostics:   Diagnostic[]
+    config?:       Schema
+}
+export interface Diagnostic {
+    file:          string
+    line:          number
+    column:        number
+    message:       string
+}
+
+/*  the supported export formats and describe formats/parts  */
+export const formats:         readonly [ "json", "json5", "yaml", "toon", "html", "pdf", "md" ]
+export const describeFormats: readonly [ "md", "raw" ]
+export const describeParts:   readonly [ "all", "meta", "schema", "spec" ]
+export type  ExportFormat   = typeof formats[number]
+export type  DescribeFormat = typeof describeFormats[number]
+export type  DescribePart   = typeof describeParts[number]
+
+/*  the Abstract Syntax Tree (AST) of a parsed specification  */
+export type Spec = {
+    artifacts:     SpecArtifact[]
+}
+export type SpecArtifact = {
+    created:       Date
+    modified:      Date
+    objects:       SpecObject[]
+}
+export type SpecObject = {
+    kind:          string
+    id:            string
+    anchor?:       string
+    paren?:        string
+    name:          string
+    primary?:      boolean
+    description?:  SpecDescription
+    properties:    SpecProperty[]
+    childs:        SpecObject[]
+}
+export type SpecDescription = {
+    description:   string
+    rationale?:    string
+    embedding?:    string[]
+}
+export type SpecProperty = {
+    key:           string
+    value:         string
+    embedding?:    string[]
+}
+
+/*  the YAML schema configuration, where the nested "diagram" and
+    "format" structures are detailed in the "describe" output  */
+export type Schema = SchemaObject[]
+export type SchemaObject = {
+    kind:          string
+    name?:         string
+    id?:           string
+    file?:         string
+    desc?:         string
+    optional?:     boolean
+    diagram?:      SchemaDiagram
+    format?:       SchemaFormat
+    props?:        SchemaProperty[]
+    childs?:       SchemaObject[]
+}
+export type SchemaProperty = {
+    name:          string
+    desc?:         string
+    value?:        string
+    optional?:     boolean
+}
 ```
 
-The YAML schema configuration `-c`/`--config` (default: the bundled
-standard schema configuration `specbook-format.yaml`) determines the
-specification: exactly the artifact files its `file` fields reference
-are loaded and parsed; all other Markdown files below the base
-directory are ignored. A referenced
-file which is absent is reported, unless all of its artifacts are
-`optional`, and so is an artifact absent from its present file, unless
-it is `optional` itself. Both `lint` and `export` report all
-diagnostics and fail on any of them, so a partial or invalid
-specification is never exported.
-
-The base directory `-b`/`--basedir` (default: `.`) is the directory the
-referenced artifact files are resolved against, and generated
-specification Markdown files are placed inside it, too.
-
-The export output option `-o`/`--output` (default: `-` for stdout) can
-occur multiple times. The format (`json`, `json5`, `yaml`, `toon`,
-`html`, `pdf`, or `md`) is inferred from the filename extension, unless
-it is explicitly given as a `<format>:` prefix, and plain `-` (stdout)
-defaults to JSON.
-
-The `md` format normalizes the entire corpus into a *single* Markdown
-document, whose single frontmatter block carries the earliest `Created:`
-and the latest `Modified:` timestamp of all artifacts, so the
-per-artifact timestamps do not survive this round-trip.
-
-The `describe` command outputs the description of the SpecBook models
-and formats, extended by a *SpecBook Project Instantiation* section which
-points to the YAML schema configuration `-c`/`--config` and the base
-directory `-b`/`--basedir`. The schema configuration falls back onto the
-bundled standard one, embedded verbatim, as long as no particular
-configuration file `-c`/`--config` is given. With `-e`/`--embed` the
-given YAML schema configuration is embedded verbatim instead of just
-being referenced, so the resulting document describes the specification
-format entirely on its own.
-
-The `describe` document part `-p`/`--part` (default: `all`) reduces the
-output to a single part: `meta` for the description of the generic
-SpecBook models and formats, `schema` for the YAML schema configuration
-(the given one, referenced or embedded with `-e`/`--embed`, else the
-bundled standard one, embedded), or `spec` for the reference to
-the base directory. The output format `-f`/`--format` (default: `md`)
-switches from this rendered Markdown onto the raw original file content
-with `raw`, which is available for the file-backed parts `meta` and
-`schema` only.
-
-The default value of every CLI option `--xxx` can be overridden by a
-corresponding `SPECBOOK_XXX` environment variable (e.g.
-`SPECBOOK_BASEDIR`, `SPECBOOK_CONFIG`, `SPECBOOK_OUTPUT`,
-`SPECBOOK_VERBOSE`), while an explicitly supplied option always wins.
-
-### API
+Example:
 
 ```ts
-import { SpecBook, renderVerbose } from "@rse/specbook"
+import { SpecBook } from "@rse/specbook"
 
 const specbook = new SpecBook({
-    verbose: (cmd, msg) => console.error(`specbook: ${cmd}: ${renderVerbose(msg)}`)
+    verbose: (cmd, msg) => console.error(`specbook: ${cmd}: ${msg}`)
 })
 const result = await specbook.lint({
     basedir: "smp/broadcast"
 })
 ```
 
-### MCP
+### CLI
+
+Commands:
 
-Run `specbook mcp` to serve the tools `specbook_init`, `specbook_lint`,
-`specbook_export`, and `specbook_describe` over stdio.
+```bash
+$ specbook init \
+  [-v|--verbose] \
+  [-c|--config <schema-yaml-file>] \
+  [-b|--basedir <spec-md-file-basedir>]
+
+$ specbook lint \
+  [-v|--verbose] \
+  [-c|--config <schema-yaml-file>] \
+  [-b|--basedir <spec-md-file-basedir>]
+
+$ specbook export \
+  [-v|--verbose] \
+  [-c|--config <schema-yaml-file>] \
+  [-b|--basedir <spec-md-file-basedir>] \
+  [-o|--output [<format>:]<output-file>] [...]
+
+$ specbook describe \
+  [-v|--verbose] \
+  [-c|--config <schema-yaml-file>] \
+  [-b|--basedir <spec-md-file-basedir>] \
+  [-e|--embed] \
+  [-f|--format <format>] \
+  [-p|--part <part>] \
+  [-o|--output <output-file>]
+
+$ specbook mcp \
+  [-v|--verbose]
+```
+
+Options:
+
+-   `-v|--verbose`:
+    Enable verbose logging of processing information to `stderr`.
+
+-   `-c|--config <schema-yaml-file>`:
+    The YAML schema configuration (default: the bundled standard schema
+    configuration `specbook-format.yaml`) determines the specification:
+    exactly the artifact files its `file` fields reference are loaded and
+    parsed; all other Markdown files below the base directory are ignored.
+    A referenced file which is absent is reported, unless all of its
+    artifacts are `optional`, and so is an artifact absent from its present
+    file, unless it is `optional` itself. Both `lint` and `export` report
+    all diagnostics and fail on any of them, so a partial or invalid
+    specification is never exported.
+
+-   `-b|--basedir <spec-md-file-basedir>`:
+    The base directory (default: `.`) is the directory the referenced
+    artifact files are resolved against, and generated specification
+    Markdown files are placed inside it, too.
+
+-   `-o|--output [<format>:]<output-file>` (`export` only):
+    The output file (default: `-` for stdout) can be given multiple times.
+    The format (`json`, `json5`, `yaml`, `toon`, `html`, `pdf`, or `md`)
+    is inferred from the filename extension, unless it is explicitly given
+    as a `<format>:` prefix, and plain `-` (stdout) defaults to JSON.
+    The `md` export format normalizes the entire corpus into a *single*
+    Markdown document.
+
+-   `-o|--output <output-file>` (`describe` only):
+    The output file (default: `-` for stdout) receives the described
+    Markdown document.
+
+-   `-e|--embed` (`describe` only):
+    Embed the given YAML schema configuration verbatim instead of just
+    referencing it, so the resulting document describes the specification
+    format entirely on its own.
+
+-   `-f|--format <format>` (`describe` only):
+    The output format (default: `md`) switches from the rendered Markdown
+    onto the raw original file content with `raw`, which is available for
+    the file-backed parts `meta` and `schema` only.
+
+-   `-p|--part <part>` (`describe` only):
+    The document part (default: `all`) reduces the output to a single part:
+    `meta` for the description of the generic SpecBook models and formats,
+    `schema` for the YAML schema configuration (the given one, referenced
+    or embedded with `-e|--embed`, else the bundled standard one,
+    embedded), or `spec` for the reference to the base directory.
+
+The default value of every CLI option `--xxx` can be overridden
+by a corresponding `SPECBOOK_XXX` environment variable (e.g.
+`SPECBOOK_BASEDIR`, `SPECBOOK_CONFIG`, `SPECBOOK_OUTPUT`,
+`SPECBOOK_VERBOSE`), while an explicitly supplied option always wins.
+
+Example:
+
+```bash
+$ specbook lint -v -b smp/broadcast
+```
 
 Rendering Examples
 ------------------

package/dst/specbook-api.d.ts

@@ -2,8 +2,8 @@ import { renderDiagnostic, renderDiagnosticVerbose, type Diagnostic } from "./sp
 import { type LintResult } from "./specbook-cmd-lint.js";
 import { parseOutputSpec, formats, type ExportFormat } from "./specbook-cmd-export.js";
 import { describeFormats, describeParts, parseDescribeFormat, parseDescribePart, type DescribeFormat, type DescribePart } from "./specbook-cmd-describe.js";
-import { literal, renderVerbose } from "./specbook-verbose.js";
-export { literal, renderVerbose };
+import { literal, renderVerbose, type Verbose, type VerboseLevel } from "./specbook-verbose.js";
+export { literal, renderVerbose, type Verbose, type VerboseLevel };
 export { formats, parseOutputSpec, type ExportFormat };
 export { describeFormats, describeParts, parseDescribeFormat, parseDescribePart };
 export { type DescribeFormat, type DescribePart };
@@ -13,7 +13,7 @@ export type { Spec, SpecArtifact, SpecObject, SpecDescription, SpecProperty } fr
 export type { Schema, SchemaObject, SchemaProperty } from "./specbook-format-schema.js";
 export declare const version: string;
 export declare const standardConfig: string;
-export type VerboseSink = (cmd: string, msg: string) => void;
+export type VerboseSink = (cmd: string, msg: string, level: VerboseLevel) => void;
 export interface SpecBookOptions {
     verbose?: VerboseSink;
 }

package/dst/specbook-api.js

@@ -11,6 +11,7 @@ import { initSpecification } from "./specbook-cmd-init.js";
 import { lint } from "./specbook-cmd-lint.js";
 import { exportSpecification, parseOutputSpec, formats } from "./specbook-cmd-export.js";
 import { describeFormat, describeFormats, describeParts, parseDescribeFormat, parseDescribePart } from "./specbook-cmd-describe.js";
+import { requireBrowser } from "./specbook-export-pdf.js";
 import { literal, renderVerbose } from "./specbook-verbose.js";
 /*  re-export the central types for API consumers  */
 export { literal, renderVerbose };
@@ -32,7 +33,7 @@ export class SpecBook {
     }
     /*  bind the verbose sink to a particular command  */
     verboseOf(cmd) {
-        return (msg) => this.verbose(cmd, msg);
+        return (msg, level = "debug") => this.verbose(cmd, msg, level);
     }
     /*  determine the file of the YAML schema configuration, falling
         back onto the bundled standard schema configuration  */
@@ -68,6 +69,11 @@ export class SpecBook {
         as a partial or invalid specification must never be emitted)  */
     async export(options) {
         const verbose = this.verboseOf("export");
+        const requested = options.formats ?? ["json"];
+        /*  a missing browser is an environment problem, so let the PDF
+            export fail before the specification is even parsed  */
+        if (requested.includes("pdf"))
+            await requireBrowser(verbose);
         const result = lint({ config: this.configFile(options.config),
             basedir: options.basedir ?? ".", verbose });
         if (result.diagnostics.length > 0)
@@ -76,7 +82,7 @@ export class SpecBook {
         if (result.specification.artifacts.length === 0)
             throw new Error("unexportable specification: no artifacts found");
         const buffers = new Array();
-        for (const format of options.formats ?? ["json"])
+        for (const format of requested)
             buffers.push(await exportSpecification(result.specification, format, verbose, result.config));
         return buffers;
     }

package/dst/specbook-cli.js

@@ -12,9 +12,11 @@ import { serveMcp } from "./specbook-mcp.js";
 /*  route verbose messages to stderr, keeping stdout reserved for the
     command outputs and the MCP protocol, and qualify every message with
     the tool name plus the scope path of the emitting command, where
-    Chalk styles the output only if the terminal supports colors  */
-const verboseOf = (opts, ...scope) => (cmd, msg) => {
-    if (opts.verbose) {
+    Chalk styles the output only if the terminal supports colors; the
+    "notice" messages pass regardless of the verbose option, as they
+    report environment problems the user has to see  */
+const verboseOf = (opts, ...scope) => (cmd, msg, level) => {
+    if (opts.verbose || level === "notice") {
         const scopePath = [...scope, cmd].map((segment) => chalk.bold(segment)).join(": ");
         process.stderr.write(`specbook: ${scopePath}: ${renderVerbose(msg, chalk.blue)}\n`);
     }
@@ -38,7 +40,7 @@ const writeOutput = async (output, data, cmd, verbose) => {
         await writeStdout(data);
     else {
         await fs.promises.writeFile(output, data);
-        verbose(cmd, `wrote "${literal(output)}" (${literal(Buffer.byteLength(data))} bytes)`);
+        verbose(cmd, `wrote "${literal(output)}" (${literal(Buffer.byteLength(data))} bytes)`, "debug");
     }
 };
 /*  determine an option default value, overridable via a
@@ -71,7 +73,7 @@ program.name("specbook")
 withVerboseOption(program.command("mcp"))
     .description("run as MCP stdio server")
     .action(async (opts) => {
-    verboseOf(opts)("mcp", "starting MCP server on stdio");
+    verboseOf(opts)("mcp", "starting MCP server on stdio", "debug");
     await serveMcp(verboseOf(opts, "mcp"));
 });
 /*  the init command creates the configured artifact files  */
@@ -97,7 +99,7 @@ withCommonOptions(program.command("lint"))
     if (result.diagnostics.length > 0)
         process.exitCode = 1;
     else
-        verboseOf(opts)("lint", "specification valid");
+        verboseOf(opts)("lint", "specification valid", "debug");
 });
 /*  the export command parses the input once and writes every output  */
 withCommonOptions(program.command("export"))
@@ -143,5 +145,5 @@ catch (err) {
     let msg = err instanceof Error ? err.message : String(err);
     for (let cause = err instanceof Error ? err.cause : undefined; cause instanceof Error; cause = cause.cause)
         msg += `: ${cause.message}`;
-    process.stderr.write(`specbook: ERROR: ${msg}\n`, () => process.exit(1));
+    process.stderr.write(`specbook: ${chalk.red("ERROR:")} ${renderVerbose(msg, chalk.blue)}\n`, () => process.exit(1));
 }

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

@@ -1,9 +1,10 @@
 import type { Spec } from "./specbook-format-spec.js";
 import type { Schema } from "./specbook-format-schema.js";
+import type { Verbose } from "./specbook-verbose.js";
 export declare const formats: readonly ["json", "json5", "yaml", "toon", "html", "pdf", "md"];
 export type ExportFormat = typeof formats[number];
 export declare const parseOutputSpec: (spec: string) => {
     format: ExportFormat;
     output: string;
 };
-export declare const exportSpecification: (specification: Spec, format: ExportFormat, verbose: (msg: string) => void, config?: Schema) => Promise<Buffer>;
+export declare const exportSpecification: (specification: Spec, format: ExportFormat, verbose: Verbose, config?: Schema) => Promise<Buffer>;

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

@@ -1,7 +1,8 @@
+import { type Verbose } from "./specbook-verbose.js";
 import { type Schema } from "./specbook-format-schema.js";
 export interface InitOptions {
     config: Schema;
     basedir: string;
-    verbose: (msg: string) => void;
+    verbose: Verbose;
 }
 export declare const initSpecification: (options: InitOptions) => string[];

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

@@ -1,10 +1,11 @@
+import { type Verbose } from "./specbook-verbose.js";
 import { type Diagnostic } from "./specbook-diagnostic.js";
 import { type Spec } from "./specbook-format-spec.js";
 import { type Schema } from "./specbook-format-schema.js";
 export interface LintOptions {
     config: string;
     basedir: string;
-    verbose: (msg: string) => void;
+    verbose: Verbose;
 }
 export interface LintResult {
     specification: Spec;

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

@@ -1,9 +1,12 @@
+import type { LaunchOptions } from "playwright";
 import type { OutlineEntry } from "./specbook-export-html.js";
 import type { ThemeMapping } from "./specbook-theme.js";
+import { type Verbose } from "./specbook-verbose.js";
 type Heading = {
     title: string;
     subtitle?: string;
     logo: string;
 };
-export declare const htmlToPdf: (renderHtmlPass: (tocPages?: Map<string, number>) => Promise<string>, heading: Heading, outline: OutlineEntry[], verbose: (msg: string) => void, css: string, theme: ThemeMapping, paper?: string) => Promise<Buffer>;
+export declare const requireBrowser: (verbose: Verbose) => Promise<LaunchOptions>;
+export declare const htmlToPdf: (renderHtmlPass: (tocPages?: Map<string, number>) => Promise<string>, heading: Heading, outline: OutlineEntry[], verbose: Verbose, css: string, theme: ThemeMapping, paper?: string) => Promise<Buffer>;
 export {};

package/dst/specbook-export-pdf.js

@@ -3,7 +3,9 @@
 **  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
+import fs from "node:fs";
 import { escapeHtml, paperSetup, paperLength, paperSizeDefault } from "./specbook-export-common.js";
+import { literal } from "./specbook-verbose.js";
 /*  extract the per-anchor page numbers from a Chromium-generated PDF,
     which records the internal link targets as named PDF destinations  */
 const anchorPages = async (pdf) => {
@@ -121,6 +123,48 @@ const drawBrandBar = async (doc, accent) => {
         page.drawRectangle({ x: 0, y: 0, width: 5.4,
             height: page.getHeight(), color: rgb(r, g, b) });
 };
+/*  the launch options of the Chromium-class browser printing the PDF,
+    resolved just once per process, as probing a system-installed Google
+    Chrome has to actually launch it and as the export preflight and the
+    renderer both ask for the very same browser  */
+let browserOptions;
+/*  resolve the browser printing the PDF: the downloaded Playwright
+    Chromium is a plain file check, while a system-installed Google
+    Chrome is only detectable by launching it  */
+const resolveBrowser = async (verbose) => {
+    const { chromium } = await import("playwright");
+    let executable = "";
+    try {
+        executable = chromium.executablePath();
+    }
+    catch {
+        /*  Playwright knows no Chromium distribution at all  */
+    }
+    if (executable !== "" && fs.existsSync(executable))
+        return {};
+    try {
+        const chrome = await chromium.launch({ channel: "chrome" });
+        await chrome.close();
+        verbose("Playwright Chromium unavailable -- falling back to the " +
+            "system-installed Google Chrome", "notice");
+        return { channel: "chrome" };
+    }
+    catch {
+        return undefined;
+    }
+};
+/*  ensure a browser printing the PDF is available, so a missing browser
+    fails the export early and with an actionable remedy instead of deep
+    inside the rendering and with a Playwright-internal message  */
+export const requireBrowser = async (verbose) => {
+    browserOptions ??= resolveBrowser(verbose);
+    const options = await browserOptions;
+    if (options === undefined)
+        throw new Error("the PDF export requires a Chromium-class browser, but neither the " +
+            "Playwright Chromium nor a system-installed Google Chrome was found -- run " +
+            `"${literal("npx playwright install chromium")}" once to download the Playwright Chromium`);
+    return options;
+};
 /*  render a self-contained HTML document into a PDF via Playwright,
     re-rendering the HTML with the discovered ToC page numbers  */
 export const htmlToPdf = async (renderHtmlPass, heading, outline, verbose, css, theme, paper = paperSizeDefault) => {
@@ -128,22 +172,8 @@ export const htmlToPdf = async (renderHtmlPass, heading, outline, verbose, css,
     /*  the page geometry of the chosen paper size  */
     const setup = paperSetup(paper);
     const margin = setup.margin;
-    /*  launch the Playwright Chromium browser, falling back to a
-        system-installed Google Chrome if the Chromium download is missing  */
-    let browser;
-    try {
-        browser = await chromium.launch();
-    }
-    catch (err) {
-        verbose("Playwright Chromium unavailable -- falling back to installed Google Chrome");
-        try {
-            browser = await chromium.launch({ channel: "chrome" });
-        }
-        catch {
-            /*  report the original, more instructive error  */
-            throw err;
-        }
-    }
+    /*  launch the browser resolved for this process  */
+    const browser = await chromium.launch(await requireBrowser(verbose));
     try {
         const page = await browser.newPage();
         /*  render an HTML document into a paginated PDF  */

package/dst/specbook-mcp.js

@@ -7,7 +7,7 @@ import * as fs from "node:fs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { SpecBook, renderDiagnostic, formats, parseOutputSpec, describeFormats, describeParts, version } from "./specbook-api.js";
+import { SpecBook, renderDiagnostic, renderVerbose, formats, parseOutputSpec, describeFormats, describeParts, 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);
@@ -15,7 +15,7 @@ const errorResult = (err) => {
         msg += `: ${cause.message}`;
     return {
         isError: true,
-        content: [{ type: "text", text: `ERROR: ${msg}` }]
+        content: [{ type: "text", text: `ERROR: ${renderVerbose(msg)}` }]
     };
 };
 /*  serve the SpecBook functionality as "specbook_<cmd>" MCP tools over stdio  */

package/dst/specbook-verbose.d.ts

@@ -1,2 +1,4 @@
+export type VerboseLevel = "debug" | "notice";
+export type Verbose = (msg: string, level?: VerboseLevel) => void;
 export declare const literal: (value: string | number) => string;
 export declare const renderVerbose: (msg: string, style?: (value: string) => string) => string;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":                                "@rse/specbook",
-    "version":                             "1.0.1",
+    "version":                             "1.0.3",
     "publishConfig":                       { "access": "public" },
     "description":                         "Markdown-based Specification Format (API, CLI and MCP service)",
     "license":                             "Apache-2.0",