@zvndev/darkmown 2.2.0 → 2.3.1-next.1.g3a4a8dc

package/types/src/compiler/page.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Compile a page source file into a full HTML document plus its assets.
+ * @param {string} file Absolute path to the source `.md`/`.wd` file.
+ * @param {Paths} context Resolved project paths.
+ * @param {{ feed?: { href: string, title: string }, collections?: Map<string, import("./collections.js").CollectionRow[]>, vars?: Record<string, unknown>, reader?: import("./reader.js").Reader }} [options]
+ *   When a site-wide RSS feed is emitted (the home page set `site_url` and the
+ *   site has dated posts), `feed` carries its absolute href + title so every page
+ *   links it. `collections` is the build-time collection index a bare-name
+ *   `@loop` resolves against; `vars` seeds the document scope (the pager `page`
+ *   object on a paginated route). `reader` is the source reader (fs-backed by
+ *   default via `src/compiler.js`; in-memory for `compileFromMemory`).
+ * @returns {CompiledPage}
+ */
+export function compilePage(file: string, context: Paths, options?: {
+    feed?: {
+        href: string;
+        title: string;
+    };
+    collections?: Map<string, import("./collections.js").CollectionRow[]>;
+    vars?: Record<string, unknown>;
+    reader?: import("./reader.js").Reader;
+}): CompiledPage;
+/**
+ * Harden every `<img>` in the assembled page body — compile-time only, zero
+ * runtime JS. Bare markdown images reflow the page as they decode (cumulative
+ * layout shift — the literal "jump" on navigation) and load eagerly. This
+ * stamps intrinsic `width`/`height` (read from the file on disk so the browser
+ * reserves space), `decoding="async"` on all, and a load-priority split: the
+ * first image is the LCP candidate (eager + `fetchpriority="high"`), the rest
+ * lazy-load. Author-set attributes are never overwritten.
+ * @param {string} html Assembled page body HTML.
+ * @param {Paths} paths Resolved project paths.
+ * @param {import("./reader.js").Reader} reader Source reader for the image bytes.
+ * @returns {string}
+ */
+export function enhanceImages(html: string, paths: Paths, reader: import("./reader.js").Reader): string;
+/**
+ * Compile a source file into its body HTML, frontmatter, and assets (no page shell).
+ * @param {string} file Absolute path to the source file.
+ * @param {Paths} context Resolved project paths.
+ * @param {string[]} [stack] Include stack for cycle detection.
+ * @param {Record<string, unknown>} [vars] Initial static scope variables.
+ * @param {Map<string, import("./collections.js").CollectionRow[]>} [collections]
+ *   Build-time collection index a bare-name `@loop` resolves against.
+ * @param {import("./reader.js").Reader} [reader] Source reader (fs-backed when
+ *   omitted via `src/compiler.js`; in-memory for `compileFromMemory`).
+ * @returns {CompiledDocument}
+ */
+export function compileDocument(file: string, context: Paths, stack?: string[], vars?: Record<string, unknown>, collections?: Map<string, import("./collections.js").CollectionRow[]>, reader?: import("./reader.js").Reader): CompiledDocument;
+/**
+ * Compile a single file: parse frontmatter, collect assets, render body.
+ * @param {string} file
+ * @param {Paths} context
+ * @param {string[]} stack
+ * @param {Scope} scope
+ * @param {Compilation} comp
+ * @param {string[]} sections
+ * @param {string | null} loopItem
+ * @param {number} [reactiveDepth] Enclosing REACTIVE `@loop` levels, threaded in
+ *   from the including page so an include's body can't bypass the two-level
+ *   reactive-nesting limit at the `@include` boundary.
+ * @param {{ at: string, line: string } | null} [loopOpener] The enclosing `@loop`
+ *   opener, threaded in so a depth error inside the include names the right opener.
+ * @returns {{ meta: Meta, html: string }}
+ */
+export function compileFile(file: string, context: Paths, stack: string[], scope: Scope, comp: Compilation, sections: string[], loopItem: string | null, reactiveDepth?: number, loopOpener?: {
+    at: string;
+    line: string;
+} | null): {
+    meta: Meta;
+    html: string;
+};
+/**
+ * Compile a page entirely from an in-memory file map — no filesystem, no
+ * `node:fs`. `files` maps PROJECT-RELATIVE POSIX paths (`site/pages/index.wd`,
+ * `site/_/nav.wd`) to their source strings; `entryPath` is the project-relative
+ * path of the page to compile. Includes, colocated `.skin`/`.js` detection, and
+ * `@loop` JSON-data reads all resolve against the same map (anything not in it
+ * is simply "absent"), so `@include`s work as long as their targets are present.
+ *
+ * This is the strategic fs-free entry point the browser playground and a planned
+ * mobile host use: the entire module graph reachable from here is free of
+ * `node:fs`, so it bundles for the browser. It returns the same
+ * {@link CompiledPage} shape as {@link compilePage} and throws the same
+ * `file:line` compile errors, so the error DX is identical in-browser.
+ * @param {Record<string, string> | Map<string, string>} files Project-relative
+ *   path → source content.
+ * @param {string} entryPath Project-relative path of the page to compile.
+ * @param {{ feed?: { href: string, title: string }, collections?: Map<string, import("./collections.js").CollectionRow[]>, vars?: Record<string, unknown>, cwd?: string }} [options]
+ *   Same shell options as {@link compilePage}; `cwd` overrides the virtual
+ *   project root the relative keys resolve against (defaults to `/`).
+ * @returns {CompiledPage}
+ */
+export function compileFromMemory(files: Record<string, string> | Map<string, string>, entryPath: string, options?: {
+    feed?: {
+        href: string;
+        title: string;
+    };
+    collections?: Map<string, import("./collections.js").CollectionRow[]>;
+    vars?: Record<string, unknown>;
+    cwd?: string;
+}): CompiledPage;
+export type Paths = import("./context.js").Paths;
+export type Meta = import("./context.js").Meta;
+export type Scope = import("./context.js").Scope;
+export type Compilation = import("./context.js").Compilation;
+export type Ctx = import("./context.js").Ctx;
+export type CompiledDocument = import("./context.js").CompiledDocument;
+export type CompiledPage = import("./context.js").CompiledPage;

package/types/src/compiler/predicates.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @param {string} raw
+ * @param {string} itemName
+ * @param {Ctx} ctx
+ * @returns {Predicate}
+ */
+export function compilePredicate(raw: string, itemName: string, ctx: Ctx): Predicate;
+/**
+ * Evaluate a compiled predicate against a row at build time by walking its AST —
+ * the same closed evaluator the runtime uses, so the fold matches. No eval.
+ * @param {string} body
+ * @param {unknown} item
+ * @param {Ctx} ctx
+ * @returns {boolean}
+ */
+export function evalPredicate(body: string, item: unknown, ctx: Ctx): boolean;
+/**
+ * Compile a `::: … .class when <predicate>`. Allows `:if`-style bare truthy
+ * paths and `where`-style `left <op> right` conditions joined by `and`/`or`.
+ * Folds to a static verdict when every operand is build-known, else returns a
+ * runtime body over I()/S()/C() plus whether it reads the reactive loop item
+ * (which decides data-wd-each-class vs the global data-wd-class).
+ * @param {string} raw
+ * @param {Ctx} ctx
+ * @param {string} [what] Directive label for error messages.
+ * @returns {{ static: true, value: boolean } | { static: false, body: string, item: boolean }}
+ */
+export function compileWhen(raw: string, ctx: Ctx, what?: string): {
+    static: true;
+    value: boolean;
+} | {
+    static: false;
+    body: string;
+    item: boolean;
+};
+/**
+ * Compile a `:computed` expression into safe JS over the `S(key, path)` reader.
+ * @param {string} raw
+ * @param {Ctx} ctx
+ * @returns {string}
+ */
+export function compileComputedExpr(raw: string, ctx: Ctx): string;
+/**
+ * @typedef {import("./context.js").Ctx} Ctx
+ * @typedef {import("./context.js").Predicate} Predicate
+ */
+export const PREDICATE_OPS: string[];
+export const PREDICATE_JOINERS: string[];
+export type Ctx = import("./context.js").Ctx;
+export type Predicate = import("./context.js").Predicate;

package/types/src/compiler/reader.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The narrow filesystem surface the compiler needs. Every method takes an
+ * ABSOLUTE path (the compiler resolves includes/assets to absolute paths before
+ * reading), so a reader only has to map absolute paths to bytes/existence.
+ * @typedef {object} Reader
+ * @property {(absPath: string) => string} readText Read a UTF-8 text file.
+ * @property {(absPath: string) => Uint8Array} readBinary Read raw bytes (images).
+ * @property {(absPath: string) => boolean} exists Whether the path exists.
+ * @property {(absPath: string) => string} realpath Canonical path (symlinks
+ *   resolved on a real fs; a no-op normalize in memory) — used for cycle keys.
+ */
+/**
+ * A reader backed by an in-memory map of PROJECT-RELATIVE path → content. Keys
+ * are POSIX, project-relative (e.g. `site/pages/index.wd`, `site/_/nav.wd`);
+ * lookups translate an absolute compile path back to its key via `cwd`. There
+ * are no symlinks in memory, so `realpath` just normalizes. Binary reads are
+ * unsupported (the playground has no image files, and image measuring degrades
+ * to "no dimensions" on a throw), so `readBinary` throws — callers already
+ * try/catch it.
+ * @param {Record<string, string> | Map<string, string>} files
+ * @param {string} [cwd] Virtual project root the keys are relative to.
+ * @returns {Reader}
+ */
+export function memoryReader(files: Record<string, string> | Map<string, string>, cwd?: string): Reader;
+/**
+ * The narrow filesystem surface the compiler needs. Every method takes an
+ * ABSOLUTE path (the compiler resolves includes/assets to absolute paths before
+ * reading), so a reader only has to map absolute paths to bytes/existence.
+ */
+export type Reader = {
+    /**
+     * Read a UTF-8 text file.
+     */
+    readText: (absPath: string) => string;
+    /**
+     * Read raw bytes (images).
+     */
+    readBinary: (absPath: string) => Uint8Array;
+    /**
+     * Whether the path exists.
+     */
+    exists: (absPath: string) => boolean;
+    /**
+     * Canonical path (symlinks
+     * resolved on a real fs; a no-op normalize in memory) — used for cycle keys.
+     */
+    realpath: (absPath: string) => string;
+};

package/types/src/compiler/state.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleState(line: string, ctx: Ctx, index: number): string;
+/**
+ * Register a state key in the current section scope, enabling the runtime.
+ * @param {string} name
+ * @param {unknown} value
+ * @param {Ctx} ctx
+ * @returns {string} The fully-qualified state key.
+ */
+export function declareState(name: string, value: unknown, ctx: Ctx): string;
+/**
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleStore(line: string, ctx: Ctx, index: number): string;
+/**
+ * Register a page-global store. The bare name is added to `comp.state` so every
+ * resolver (interpolation, :if, @loop, :computed, actions) sees it, and tracked
+ * in `comp.stores` for collision checks. Never section-scoped.
+ * @param {string} name
+ * @param {unknown} value
+ * @param {Ctx} ctx
+ * @returns {string} The store name (also its bare state key).
+ */
+export function declareStore(name: string, value: unknown, ctx: Ctx): string;
+/**
+ * Seed a `<name>_error` state key (null) if absent. Shared by :fetch and the
+ * round-trip :form so error fallbacks have a key to bind.
+ * @param {string} key
+ * @param {Ctx} ctx
+ * @returns {void}
+ */
+export function declareErrorState(key: string, ctx: Ctx): void;
+/**
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleComputed(line: string, ctx: Ctx, index: number): string;
+/**
+ * `:theme [name] [= "auto"]` declares a durable `:store` (default name `theme`,
+ * seed `"auto"`) and reflects its value onto `<html data-theme>`. This layers a
+ * manual light/dark switch over the OS preference: `"auto"` follows the skin's
+ * `tokens dark` media query, while `"light"`/`"dark"` force the matching
+ * `:root[data-theme]` scope. Wire a switch with ordinary store actions —
+ * `:button "Dark" -> theme = "dark"`. Durable, so the choice survives reloads.
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleTheme(line: string, ctx: Ctx, index: number): string;
+/**
+ * @typedef {import("./context.js").Ctx} Ctx
+ */
+export const STATE_EXAMPLE: ":state count = 0";
+export const STORE_EXAMPLE: ":store cart = []";
+export const COMPUTED_EXAMPLE: ":computed total = items.length * 4";
+export const THEME_EXAMPLE: ":theme";
+export type Ctx = import("./context.js").Ctx;

package/types/src/compiler/structure.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleInclude(line: string, ctx: Ctx, index: number): string;
+/**
+ * @param {string} header
+ * @param {string[]} bodyLines
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleContainer(header: string, bodyLines: string[], ctx: Ctx, index: number): string;
+/**
+ * `:carousel [autoplay=N]` … `:endcarousel` — a horizontally scroll-snapping
+ * carousel. Contract: each DIRECT child element of the track is one slide, so put
+ * each slide in its own block (e.g. a `::: slide` container) and give that block
+ * the slide sizing in your skin — loose prose lines would each count as a slide.
+ * Registers the `carousel` behavior (prev/next, dot nav, optional autoplay, mouse
+ * drag); native CSS scroll-snap + the page skin handle layout and touch swipe.
+ * `autoplay` is suppressed under `prefers-reduced-motion`. No runtime required.
+ * @param {string} line
+ * @param {string[]} bodyLines
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleCarousel(line: string, bodyLines: string[], ctx: Ctx, index: number): string;
+/**
+ * @param {string} line
+ * @param {string[]} truthyLines
+ * @param {string[]} falsyLines
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @param {number} [falsyStart] 0-based index the falsy body starts at in the
+ *   current slice, so nested errors in that branch report the true file line.
+ * @returns {string}
+ */
+export function handleIf(line: string, truthyLines: string[], falsyLines: string[], ctx: Ctx, index: number, falsyStart?: number): string;
+/**
+ * Render the documentation-demo directives (`:try`, `:note`, `:sprint`).
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @returns {string}
+ */
+export function renderDemoDirective(line: string, ctx: Ctx): string;
+/**
+ * @typedef {import("./context.js").Ctx} Ctx
+ */
+export const INCLUDE_EXAMPLE: "@include /header.wd";
+export const CONTAINER_EXAMPLE: "::: card .featured";
+export const IF_EXAMPLE: ":if count > 0";
+export const CAROUSEL_EXAMPLE: ":carousel autoplay=3000";
+export type Ctx = import("./context.js").Ctx;

package/types/src/compiler.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Compile a page source file into a full HTML document plus its assets, reading
+ * from the real filesystem by default. Pass `options.reader` to compile against
+ * a different source (see `compileFromMemory`).
+ * @param {string} file Absolute path to the source `.md`/`.wd` file.
+ * @param {import("./config.js").Paths} context Resolved project paths.
+ * @param {{ feed?: { href: string, title: string }, collections?: Map<string, import("./compiler/collections.js").CollectionRow[]>, vars?: Record<string, unknown>, reader?: import("./compiler/reader.js").Reader }} [options]
+ * @returns {CompiledPage}
+ */
+export function compilePage(file: string, context: import("./config.js").Paths, options?: {
+    feed?: {
+        href: string;
+        title: string;
+    };
+    collections?: Map<string, import("./compiler/collections.js").CollectionRow[]>;
+    vars?: Record<string, unknown>;
+    reader?: import("./compiler/reader.js").Reader;
+}): CompiledPage;
+/**
+ * Compile a source file into its body HTML, frontmatter, and assets (no page
+ * shell), reading from the real filesystem by default.
+ * @param {string} file Absolute path to the source file.
+ * @param {import("./config.js").Paths} context Resolved project paths.
+ * @param {string[]} [stack] Include stack for cycle detection.
+ * @param {Record<string, unknown>} [vars] Initial static scope variables.
+ * @param {Map<string, import("./compiler/collections.js").CollectionRow[]>} [collections]
+ * @param {import("./compiler/reader.js").Reader} [reader] Source reader.
+ * @returns {CompiledDocument}
+ */
+export function compileDocument(file: string, context: import("./config.js").Paths, stack?: string[], vars?: Record<string, unknown>, collections?: Map<string, import("./compiler/collections.js").CollectionRow[]>, reader?: import("./compiler/reader.js").Reader): CompiledDocument;
+/**
+ * Harden every `<img>` in an assembled page body, reading intrinsic dimensions
+ * from the real filesystem by default.
+ * @param {string} html Assembled page body HTML.
+ * @param {import("./config.js").Paths} paths Resolved project paths.
+ * @param {import("./compiler/reader.js").Reader} [reader] Source reader for image bytes.
+ * @returns {string}
+ */
+export function enhanceImages(html: string, paths: import("./config.js").Paths, reader?: import("./compiler/reader.js").Reader): string;
+export type Meta = import("./compiler/context.js").Meta;
+export type FrontmatterValue = import("./compiler/context.js").FrontmatterValue;
+export type Assets = import("./compiler/context.js").Assets;
+export type Compilation = import("./compiler/context.js").Compilation;
+export type Scope = import("./compiler/context.js").Scope;
+export type Ctx = import("./compiler/context.js").Ctx;
+export type CompiledDocument = import("./compiler/context.js").CompiledDocument;
+export type CompiledPage = import("./compiler/context.js").CompiledPage;
+export { compileFromMemory, escapeHtml, loopKeyOf, parseFrontmatter, stampScope } from "./compiler/index.js";

package/types/src/config.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Resolved project paths used across the build pipeline.
+ * @typedef {object} Paths
+ * @property {string} cwd Project working directory.
+ * @property {string} routesRoot Absolute path to `site/pages`.
+ * @property {string} shelfRoot Absolute path to the include shelf `site/_`.
+ * @property {string} distRoot Absolute path to the build output `dist`.
+ */
+/**
+ * Build the absolute project paths for a given working directory.
+ * @param {string} [cwd] Project working directory (defaults to `process.cwd()`).
+ * @returns {Paths}
+ */
+export function createPaths(cwd?: string): Paths;
+/**
+ * Whether a file or directory name is hidden from routing (starts with `.`, `-`, or `_`).
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function isHiddenName(name: string): boolean;
+export const routesDir: "site/pages";
+export const shelfDir: "site/_";
+export const distDir: "dist";
+export const pageExtensions: Set<string>;
+/**
+ * Resolved project paths used across the build pipeline.
+ */
+export type Paths = {
+    /**
+     * Project working directory.
+     */
+    cwd: string;
+    /**
+     * Absolute path to `site/pages`.
+     */
+    routesRoot: string;
+    /**
+     * Absolute path to the include shelf `site/_`.
+     */
+    shelfRoot: string;
+    /**
+     * Absolute path to the build output `dist`.
+     */
+    distRoot: string;
+};

package/types/src/dev.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Serialize the dev server's rebuilds: at most ONE child build runs at a time.
+ * Every build read-modify-writes the dependency map (`dist/.wd-dev-deps.json`),
+ * so overlapping children could persist a stale map missing deps a concurrent
+ * build just recorded — after which the affected routes silently stop
+ * rebuilding. Changes debounce into a batch; changes arriving MID-build
+ * accumulate into the next batch (duplicate paths coalesce via the Set, and a
+ * `null` — a `src/` change or an unattributable event, forcing a full rebuild —
+ * swallows the whole batch into one full build).
+ * @param {(changed: string[]) => Promise<void> | void} runBuild Runs one child
+ *   build over the changed `site/` paths (`[]` = full rebuild). Build failures
+ *   are its own concern (report + resolve); a rejection still frees the queue.
+ * @param {number} [debounceMs] Debounce window for batching change events.
+ * @returns {{ change: (path: string | null) => void, close: () => void }}
+ */
+export function createRebuildQueue(runBuild: (changed: string[]) => Promise<void> | void, debounceMs?: number): {
+    change: (path: string | null) => void;
+    close: () => void;
+};
+/**
+ * Inject the dev-client `<script>` before `</body>` (or append it if absent),
+ * plus — for a `draft: true` page — an inline draft-banner script. Both are
+ * injected at dev-SERVE time only, so neither ever touches the shipped HTML on
+ * disk (a production build excludes drafts entirely; a `build --drafts` staging
+ * build emits clean HTML with no banner).
+ * @param {string} html Page HTML to augment.
+ * @param {{ draft?: boolean }} [options] `draft: true` adds the visible banner.
+ * @returns {string}
+ */
+export function injectDevClient(html: string, options?: {
+    draft?: boolean;
+}): string;
+/**
+ * The inline dev-only draft banner: a fixed bar marking the page as an unpublished
+ * draft, so it's unmistakable in `darkmown dev` that this content is excluded from
+ * a production build. Inert (`pointer-events:none`) and high-z so it never blocks
+ * the page; dev-serve-injected, so it's never in shipped output.
+ * @returns {string}
+ */
+export function draftBannerScript(): string;
+/**
+ * The page the dev server serves for a route with no dist output while the last
+ * build is FAILED — the honest alternative to the production 404 copy, which
+ * would claim the route "is hidden or has not been created" when the real cause
+ * is a compile error. The message renders inline (works without JS) and the
+ * injected dev client replays the `builderror` overlay on connect, then reloads
+ * the real page on the next successful build.
+ * @param {string} message The recorded build failure.
+ * @returns {string}
+ */
+export function buildFailedPage(message: string): string;
+/**
+ * The dev-client browser script that opens the SSE channel for live reload.
+ * @returns {string}
+ */
+export function devClientScript(): string;
+export const devClientPath: "/__wd/dev-client.js";
+export const devEventsPath: "/__wd/dev-events";

package/types/src/errors.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The full error-code registry, in code order. Each entry carries the stable
+ * code, its subsystem, a short title, what causes it, and how to fix it.
+ * @returns {ErrorEntry[]}
+ */
+export function errorCatalog(): ErrorEntry[];
+/**
+ * Look up one code, or undefined when it is not registered.
+ * @param {string} code
+ * @returns {ErrorEntry | undefined}
+ */
+export function errorForCode(code: string): ErrorEntry | undefined;
+/**
+ * Render `docs/errors.md` from the registry. Generated, never hand-edited, so
+ * the reference page cannot drift from the codes the compiler actually throws
+ * (`scripts/gen-errors.mjs` writes it; tests/error-codes.test.js re-checks it).
+ * @returns {string}
+ */
+export function errorsMarkdown(): string;
+/**
+ * One subsystem block of the numbering scheme.
+ * @typedef {object} ErrorArea
+ * @property {number} block The hundreds digit (0-9).
+ * @property {string} range Human label for the block, e.g. `WD1xx`.
+ * @property {string} name Short machine name, e.g. `loops`.
+ * @property {string} title One-line description of what the block covers.
+ */
+/**
+ * A registered error code.
+ * @typedef {object} ErrorEntry
+ * @property {string} code The stable `WDxxx` identifier.
+ * @property {string} area The subsystem name (derived from the hundreds digit).
+ * @property {string} title Short name for the mistake.
+ * @property {string} cause What the author wrote that triggers it.
+ * @property {string} fix The corrective action, in one line.
+ * @property {string} [example] A concrete, compilable line, sourced from the
+ *   compiler's own `*_EXAMPLE` constants.
+ */
+/** The subsystem blocks, in code order. */
+/** @type {ErrorArea[]} */
+export const ERROR_AREAS: ErrorArea[];
+/**
+ * Codes that were withdrawn. They are NEVER reused: a retired number stays
+ * listed here so the next free number in its block is always genuinely free,
+ * and so an old error message found in a log or an issue still resolves to a
+ * meaningful (if historical) entry. Empty today.
+ * @type {string[]}
+ */
+export const RETIRED_CODES: string[];
+/**
+ * One subsystem block of the numbering scheme.
+ */
+export type ErrorArea = {
+    /**
+     * The hundreds digit (0-9).
+     */
+    block: number;
+    /**
+     * Human label for the block, e.g. `WD1xx`.
+     */
+    range: string;
+    /**
+     * Short machine name, e.g. `loops`.
+     */
+    name: string;
+    /**
+     * One-line description of what the block covers.
+     */
+    title: string;
+};
+/**
+ * A registered error code.
+ */
+export type ErrorEntry = {
+    /**
+     * The stable `WDxxx` identifier.
+     */
+    code: string;
+    /**
+     * The subsystem name (derived from the hundreds digit).
+     */
+    area: string;
+    /**
+     * Short name for the mistake.
+     */
+    title: string;
+    /**
+     * What the author wrote that triggers it.
+     */
+    cause: string;
+    /**
+     * The corrective action, in one line.
+     */
+    fix: string;
+    /**
+     * A concrete, compilable line, sourced from the
+     * compiler's own `*_EXAMPLE` constants.
+     */
+    example?: string | undefined;
+};