@zvndev/darkmown 2.1.0 → 2.3.0

package/src/grammar.js

@@ -0,0 +1,131 @@
+// ---------------------------------------------------------------------------
+// GBNF grammar generator for `.wd` DIRECTIVE LINES.
+//
+// `generateGrammar()` emits a llama.cpp-compatible GBNF grammar that constrains
+// a small model's decoding to well-formed Darkmown directive lines (plus the
+// `{ path | pipe }` interpolation token). It is generated from the SAME catalog
+// the cheatsheet uses, so the keyword set, `@loop` clauses, comparison operators,
+// and format-pipe names can never drift from what compiles.
+//
+// Scope (stated deliberately): this grammar constrains the SHAPE of a directive
+// line — the leading keyword must be a real directive, `@loop` must be
+// `@loop <src> into <item> …clauses`, a `where`/`:if` condition must be
+// `operand <op> operand`, a `:button` must be `"…" -> <action-chain>`, and an
+// interpolation must pipe through a known formatter. It does NOT try to grammar-
+// check free-form values (arbitrary JSON seeds, URLs, prose) — those are `text`.
+// That is enough to delete the on-device failure class (JS/HTML muscle-memory
+// openers like `::: card class=` or `cart.filter(...)` become unrepresentable)
+// while staying small and maintainable.
+// ---------------------------------------------------------------------------
+
+import { directiveCatalog } from "./catalog.js";
+
+/** Slugify a directive token into a GBNF rule name (`@loop` → `dir-loop`). */
+/** @type {Record<string, string>} */
+const SLUG = {
+  "@include": "dir-include",
+  "@loop": "dir-loop",
+  ":::": "dir-container",
+  ":if": "dir-if",
+  ":state": "dir-state",
+  ":store": "dir-store",
+  ":computed": "dir-computed",
+  ":fetch": "dir-fetch",
+  ":effect": "dir-effect",
+  ":every": "dir-every",
+  ":theme": "dir-theme",
+  ":button": "dir-button",
+  ":form": "dir-form",
+  ":input": "dir-input",
+  ":textarea": "dir-textarea",
+  ":select": "dir-select",
+  ":checkbox": "dir-checkbox",
+  ":radio": "dir-radio",
+  ":submit": "dir-submit",
+  ":bind": "dir-bind",
+  ":slider": "dir-slider",
+  ":video": "dir-video",
+  ":audio": "dir-audio",
+  ":embed": "dir-embed",
+  ":carousel": "dir-carousel"
+};
+
+// The directives given a structured RHS below; every other directive gets the
+// generic `"<keyword>" restofline` rule (keyword pinned, argument tail free).
+const STRUCTURED = new Set(["@loop", ":if", ":button", ":::"]);
+
+/** A GBNF alternation literal list, e.g. `"a" | "b"`. */
+const alt = (/** @type {string[]} */ items) => items.map((s) => `"${s}"`).join(" | ");
+
+/**
+ * Generate the GBNF grammar for `.wd` directive lines from the directive catalog.
+ * @returns {string}
+ */
+export function generateGrammar() {
+  const cat = directiveCatalog();
+  const dirRules = cat.directives.map((d) => SLUG[d.name]).filter(Boolean);
+
+  /** @type {string[]} */
+  const lines = [];
+  lines.push("# Darkmown .wd directive-line grammar — generated by src/grammar.js");
+  lines.push(
+    "# Constrains a directive line (or a { path | pipe } interpolation). Do not edit by hand."
+  );
+  lines.push("");
+  lines.push("root ::= directive | binding");
+  lines.push(`directive ::= ${dirRules.join(" | ")}`);
+  lines.push("");
+
+  // Structured directives.
+  lines.push('dir-loop ::= "@loop" sp operand sp "into" sp ident loop-clauses');
+  lines.push('dir-if ::= ":if" sp ( condition (sp joiner sp condition)* | path )');
+  lines.push('dir-button ::= ":button" sp dqstring sp "->" sp action-chain');
+  lines.push('dir-container ::= ":::" restofline');
+  lines.push("");
+
+  // Generic directives: keyword pinned, argument tail free to end of line.
+  for (const d of cat.directives) {
+    if (STRUCTURED.has(d.name)) continue;
+    lines.push(`${SLUG[d.name]} ::= "${d.name}" restofline`);
+  }
+  lines.push("");
+
+  // @loop clause vocabulary (mirrors the fixed clause order in the catalog).
+  lines.push("loop-clauses ::= ( sp loop-clause )*");
+  lines.push(
+    'loop-clause ::= where-clause | "sort by" sp path ( sp ( "asc" | "desc" ) )? | "reverse" | "offset" sp number | "limit" sp number | "paginate" sp number | "sortable"'
+  );
+  lines.push('where-clause ::= "where" sp condition ( sp joiner sp condition )*');
+  lines.push("condition ::= operand sp op sp operand");
+  lines.push(`op ::= ${alt(cat.predicateOps.map((o) => o.name))}`);
+  lines.push(`joiner ::= ${alt(cat.predicateJoiners.filter((j) => j !== "not"))}`);
+  lines.push("");
+
+  // Button-action vocabulary. Each operator token below is asserted present
+  // against the catalog's action tokens in tests/grammar.test.js.
+  lines.push('action-chain ::= action ( wsopt ";" wsopt action )*');
+  lines.push("action ::= ident action-op");
+  lines.push(
+    'action-op ::= "++" | "--" | sp "+=" sp value | sp "-=" sp value | sp "=" sp value | sp "toggle" ( sp value )? | sp "append" sp value | sp "prepend" sp value | sp "remove" sp value | sp "clear" | sp "merge" sp ident | sp "delete" sp value | sp "reset" | sp "refetch"'
+  );
+  lines.push("");
+
+  // Interpolation binding with format pipes.
+  lines.push('binding ::= "{" wsopt path pipe-chain wsopt "}"');
+  lines.push('pipe-chain ::= ( wsopt "|" wsopt pipe ( ":" value )* )*');
+  lines.push(`pipe ::= ${alt(cat.formatPipes.map((p) => p.name))}`);
+  lines.push("");
+
+  // Terminals.
+  lines.push("operand ::= path | dqstring | number");
+  lines.push("value ::= dqstring | number | path");
+  lines.push("ident ::= [a-zA-Z_$] [a-zA-Z0-9_$]*");
+  lines.push("path ::= [a-zA-Z0-9_$/.~-]+");
+  lines.push("number ::= [0-9]+");
+  lines.push('dqstring ::= "\\"" [^"]* "\\""');
+  lines.push("restofline ::= [^\\n]*");
+  lines.push('sp ::= " "+');
+  lines.push('wsopt ::= " "*');
+  lines.push("");
+  return lines.join("\n");
+}

package/src/index.js

@@ -4,6 +4,7 @@
 // `exports` map; individual modules stay importable by their own path too.
 
 export { buildSite } from "./builder.js";
+export { directiveCatalog, llmsText } from "./catalog.js";
 
 export {
   compileDocument,

package/src/router.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { wdError } from "./compiler/context.js";
 import { parseFrontmatter } from "./compiler.js";
 import { isHiddenName, pageExtensions } from "./config.js";
 
@@ -64,8 +65,9 @@ export function discoverRoutes(routesRoot, options = {}) {
   const seen = new Map();
   for (const route of routes) {
     if (seen.has(route.route)) {
-      throw new Error(
-        `Duplicate route "${route.route}" from ${seen.get(route.route)} and ${route.file}`
+      throw wdError(
+        `Duplicate route "${route.route}" from ${seen.get(route.route)} and ${route.file}`,
+        { code: "WD901", file: route.file }
       );
     }
     seen.set(route.route, route.file);
@@ -114,8 +116,9 @@ export function outputPathForRoute(distRoot, route) {
   const clean = route === "/" ? "" : route.replace(/^\/|\/$/g, "");
   const out = path.join(distRoot, clean, "index.html");
   if (!path.resolve(out).startsWith(path.resolve(distRoot) + path.sep)) {
-    throw new Error(
-      `Route "${route}" resolves outside the build output directory ${distRoot} — routes must not contain traversal segments`
+    throw wdError(
+      `Route "${route}" resolves outside the build output directory ${distRoot} — routes must not contain traversal segments`,
+      { code: "WD902" }
     );
   }
   return out;

package/src/scaffold.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { wdError } from "./compiler/context.js";
 
 const moduleDir = path.dirname(fileURLToPath(import.meta.url));
 const templatesDir = path.join(moduleDir, "templates");
@@ -36,9 +37,10 @@ export function initProject(root, options = {}) {
   const templateDir = path.join(templatesDir, template);
   if (!fs.existsSync(templateDir) || !fs.statSync(templateDir).isDirectory()) {
     const list = availableTemplates().join(", ");
-    throw new Error(
+    throw wdError(
       `Unknown template "${template}". Available templates: ${list || "(none)"}. ` +
-        "Use: darkmown init [dir] --template <name>"
+        "Use: darkmown init [dir] --template <name>",
+      { code: "WD903", hint: "darkmown init [dir] --template <name>" }
     );
   }
 

package/src/skin.js

@@ -1,4 +1,5 @@
 import crypto from "node:crypto";
+import { wdError } from "./compiler/context.js";
 
 const aliases = new Map([
   ["radius", "border-radius"],
@@ -96,7 +97,7 @@ export function compileSkin(source, opts = {}) {
   }
   for (let i = start; i < lines.length; i++) {
     if (lines[i].text === "scoped" && lines[i].indent === 0) {
-      throw new Error('"scoped" must be the first line of a .skin file');
+      throw wdError('"scoped" must be the first line of a .skin file', { code: "WD801" });
     }
   }
 
@@ -184,8 +185,9 @@ export function compileSkin(source, opts = {}) {
     // place a filtered bare `*`/`page` reset would otherwise leak through to), so
     // it errors with the same hint instead of emitting a never-matching rule.
     if (scope && current === ":root") {
-      throw new Error(
-        `page-level declaration "${text}" is not allowed in a scoped .skin — page-level styles belong in a global skin, not a scoped one`
+      throw wdError(
+        `page-level declaration "${text}" is not allowed in a scoped .skin — page-level styles belong in a global skin, not a scoped one`,
+        { code: "WD802" }
       );
     }
     const media = stack.find((frame) => frame.media)?.media;
@@ -235,8 +237,9 @@ function guardPageLevel(text, parent) {
   for (const part of text.split(",")) {
     const clean = part.trim();
     if (PAGE_LEVEL_SELECTORS.has(clean)) {
-      throw new Error(
-        `page-level selector "${clean}" is not allowed in a scoped .skin — page-level styles belong in a global skin, not a scoped one`
+      throw wdError(
+        `page-level selector "${clean}" is not allowed in a scoped .skin — page-level styles belong in a global skin, not a scoped one`,
+        { code: "WD803" }
       );
     }
   }
@@ -308,7 +311,15 @@ function subjectBase(base) {
  */
 function normalizeAttr(bracketed) {
   const m = bracketed.match(/^\[\s*([^\]=\s]+)\s*=\s*"?([^\]"]*)"?\s*\]$/);
-  return m ? `[${m[1]}="${m[2]}"]` : null;
+  if (!m) return null;
+  // The value is quoted on the way out, but the NAME lands in the selector
+  // verbatim — so it must be validated, not just captured. Without this an
+  // input like `tokens [{=v]` emitted `:root[{="v"]`, whose stray brace
+  // unbalances the stylesheet and makes a CSS parser swallow every rule that
+  // follows it. Anything that is not a plain CSS identifier falls through to
+  // the caller's `:root` fallback. (Found by tests/fuzz-skin.test.js.)
+  if (!/^[A-Za-z_-][\w-]*$/.test(m[1])) return null;
+  return `[${m[1]}="${m[2]}"]`;
 }
 
 /**

package/types/api-runner.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The local-dev serverless API runner. Gives `darkmown dev` the SAME `/api/*`
+ * behavior a project gets on Vercel / Cloudflare in production, so a `:fetch
+ * /api/x` or a form POST works identically before you ever deploy.
+ *
+ * The convention is deliberately plain: a backend endpoint is a plain-JS file
+ * under the project's top-level `api/` directory that default-exports a
+ * Web-standard handler `(request: Request, context) => Response | Promise<Response>`.
+ * That is the exact signature Vercel Edge, Cloudflare Pages, Netlify Edge and
+ * Deno already run — Darkmown owns no server, it just emulates the host locally.
+ *
+ * File → route, rooted at the `/api` URL prefix (matching Vercel's `api/`):
+ *   api/echo.js          → /api/echo
+ *   api/users/index.js   → /api/users
+ *   api/users/list.js    → /api/users/list
+ *   api/users/[id].js    → /api/users/:id   (context.params.id)
+ *
+ * Nothing here mutates module state: routes are discovered per call so a newly
+ * added function is picked up without a restart, and each handler is imported
+ * with an mtime cache-buster so edits hot-reload.
+ */
+/**
+ * A discovered API route.
+ * @typedef {object} ApiRoute
+ * @property {string} file Absolute path to the handler module.
+ * @property {string[]} segments Route segments after `/api`; a dynamic segment
+ *   is stored as `[name]` (e.g. `["users", "[id]"]`).
+ */
+/**
+ * Walk `apiDir` and return every `.js`/`.mjs` handler as an {@link ApiRoute}.
+ * Files/dirs whose name starts with `.`, `_`, or `-` are treated as private
+ * (helpers, fixtures) and never routed, matching the router's hidden-path rule.
+ * Returns `[]` when `apiDir` does not exist.
+ * @param {string} apiDir Absolute path to the project's `api/` directory.
+ * @returns {ApiRoute[]}
+ */
+export function discoverApiRoutes(apiDir: string): ApiRoute[];
+/**
+ * Match a request pathname against discovered routes. The pathname is expected
+ * to start with `/api`; anything else returns `null` (caller serves static).
+ * @param {ApiRoute[]} routes
+ * @param {string} pathname Request pathname (no query string).
+ * @returns {{ file: string, params: Record<string, string> } | null}
+ */
+export function matchApiRoute(routes: ApiRoute[], pathname: string): {
+    file: string;
+    params: Record<string, string>;
+} | null;
+/**
+ * Build a Web-standard `Request` from a Node `IncomingMessage`. The body (for
+ * methods that carry one) is buffered fully — dev endpoints are small and this
+ * avoids the `duplex: "half"` streaming dance.
+ * @param {import("node:http").IncomingMessage} req
+ * @returns {Promise<Request>}
+ */
+export function nodeRequestToWeb(req: import("node:http").IncomingMessage): Promise<Request>;
+/**
+ * Write a Web-standard `Response` back onto a Node `ServerResponse`.
+ * @param {Response} response
+ * @param {import("node:http").ServerResponse} res
+ * @returns {Promise<void>}
+ */
+export function writeWebResponse(response: Response, res: import("node:http").ServerResponse): Promise<void>;
+/**
+ * Handle a request as an API call if its pathname matches a function under
+ * `apiDir`. Returns `true` when it owned the request (a route matched, whether
+ * the handler succeeded or threw), `false` when nothing matched so the caller
+ * should fall through to static serving.
+ *
+ * @param {object} io
+ * @param {string} io.apiDir Absolute path to the project's `api/` directory.
+ * @param {import("node:http").IncomingMessage} io.req
+ * @param {import("node:http").ServerResponse} io.res
+ * @returns {Promise<boolean>}
+ */
+export function handleApiRequest({ apiDir, req, res }: {
+    apiDir: string;
+    req: import("node:http").IncomingMessage;
+    res: import("node:http").ServerResponse;
+}): Promise<boolean>;
+/**
+ * A discovered API route.
+ */
+export type ApiRoute = {
+    /**
+     * Absolute path to the handler module.
+     */
+    file: string;
+    /**
+     * Route segments after `/api`; a dynamic segment
+     * is stored as `[name]` (e.g. `["users", "[id]"]`).
+     */
+    segments: string[];
+};

package/types/builder.d.ts

@@ -1,24 +1,127 @@
 /**
  * Compile the whole site under `cwd` into `dist`, returning the route manifest.
+ *
+ * The build is always 100% static, CDN-cacheable HTML. Backend `api/*.js`
+ * functions are NOT compiled — they are the host's concern. `target` only
+ * decides the small amount of host glue Darkmown emits alongside the static
+ * output: the default (`vercel`/anything) leaves `api/` for the platform to pick
+ * up natively; `cloudflare` emits a `dist/_worker.js/` module that routes
+ * `/api/*` to those same functions and serves everything else as a static asset.
+ *
  * @param {string} [cwd] Project working directory (defaults to `process.cwd()`).
- * @returns {{ routes: RouteManifestEntry[], distRoot: string }}
+ * @param {{ target?: string, includeDrafts?: boolean, depMap?: boolean, changed?: string[], quietFeedHints?: boolean }} [options]
+ *   `target: "cloudflare"` emits the Pages worker. `includeDrafts: true` keeps
+ *   `draft: true` pages in the build + feeds (dev / `build --drafts`); default
+ *   excludes them at route discovery so feeds never see a draft. `depMap: true`
+ *   (dev builds) writes the per-route dependency map to `dist/.wd-dev-deps.json`.
+ *   `changed` (project-relative paths, dev only; implies `depMap`) attempts an
+ *   incremental rebuild of just the affected routes, falling back to a full
+ *   rebuild on ANY uncertainty — a stale page is worse than a slow rebuild.
+ * @returns {BuildResult}
  */
-export function buildSite(cwd?: string): {
-    routes: RouteManifestEntry[];
-    distRoot: string;
-};
+export function buildSite(cwd?: string, options?: {
+    target?: string;
+    includeDrafts?: boolean;
+    depMap?: boolean;
+    changed?: string[];
+    quietFeedHints?: boolean;
+}): BuildResult;
 /**
- * Strip JSDoc `/** ... *\/` blocks from the runtime before it ships.
- * The source keeps full type annotations (for `checkJs` + `.d.ts`), but the
- * browser never needs to download them — this keeps the shipped runtime lean
- * and the gzip budget honest (measured against what users actually receive).
- * Only `/** ... *\/` blocks are removed; code and string literals are untouched.
+ * Strip developer comments from the runtime before it ships. The source keeps
+ * full JSDoc type annotations (for `checkJs` + `.d.ts`) and explanatory comments
+ * so it stays readable; the browser downloads neither. This keeps the shipped
+ * runtime lean and the gzip budget honest (measured against what users receive),
+ * WITHOUT minifying — identifiers, structure, and whitespace are all preserved.
+ *
+ * Two passes, each conservative: `/** ... *\/` JSDoc blocks, then whole-line
+ * `//` comments (a line that is nothing but a comment). Trailing `//` after code
+ * and `//` inside strings/URLs are deliberately left untouched, so no string
+ * literal is ever harmed.
  * @param {string} source
  * @returns {string}
  */
 export function stripRuntimeComments(source: string): string;
+/**
+ * Render the Cloudflare Pages `_headers` file from the route manifest.
+ *
+ * Cloudflare applies every matching block in order; when blocks set the same
+ * header, the later block wins. So we emit the catch-all `/*` first (baseline
+ * security headers + the reactive CSP, which since 2.1 is eval-free and satisfies
+ * every page), then one block per static route that re-states the same eval-free
+ * CSP as defense-in-depth. Reactive routes need no override — the catch-all
+ * already carries the eval-free CSP.
+ *
+ * Clean URLs mean a route like `/docs/` is served at both `/docs` and `/docs/`,
+ * so each static route emits a path glob (`/docs`, `/docs/*`) that covers both.
+ * @param {RouteManifestEntry[]} manifest
+ * @returns {string}
+ */
+export function renderCloudflareHeaders(manifest: RouteManifestEntry[]): string;
+/**
+ * @typedef {import("./config.js").Paths} Paths
+ * @typedef {import("./compiler.js").Assets} Assets
+ * @typedef {import("./compiler.js").Meta} Meta
+ * @typedef {import("./router.js").Route} Route
+ */
+/**
+ * A built route entry written to `dist/routes.json`.
+ * @typedef {object} RouteManifestEntry
+ * @property {string} route Public route path.
+ * @property {string} file Source file path, relative to cwd, POSIX-separated.
+ * @property {{ skins: string[], scripts: string[], runtime: boolean }} assets
+ */
+/**
+ * One source route's record in the dev dependency map (`dist/.wd-dev-deps.json`),
+ * written by dev builds so a later `--changed` build can rebuild only the routes
+ * whose dependency graph contains the changed file.
+ * @typedef {object} DepMapEntry
+ * @property {string} file Source file, project-relative, POSIX-separated.
+ * @property {string[]} deps Every source file this route's compile read (the page
+ *   itself, includes, loop JSON data files, colocated `.skin`/`.js`) —
+ *   project-relative, POSIX-separated, sorted.
+ * @property {string[]} collections Collection names the route loops, so a change
+ *   to any entry of the collection rebuilds this route.
+ * @property {RouteManifestEntry[]} pages The manifest entries this route emitted
+ *   (one, or one per pagination page), so `routes.json`/`_headers`/the sitemap
+ *   can be reassembled globally without recompiling untouched routes.
+ */
+/** The dev dependency map's filename under `dist/`. */
+export const DEP_MAP_FILE: ".wd-dev-deps.json";
+/**
+ * The value `buildSite` returns. `incremental` is present only when a `changed`
+ * build actually rebuilt a subset of routes (absent on every full rebuild).
+ */
+export type BuildResult = {
+    routes: RouteManifestEntry[];
+    distRoot: string;
+    feeds: {
+        sitemap: number | null;
+        rss: number | null;
+    };
+    incremental?: {
+        changed: string[];
+        rebuilt: string[];
+        total: number;
+    } | undefined;
+};
+/**
+ * A compiled page bound for a concrete output route. Mirrors `CompiledPage` plus
+ * the public `route` it's written to — for a paginated listing, page 1 keeps the
+ * listing route and pages 2+ get `/<route>/page/<n>/`.
+ */
+export type EmittedPage = {
+    /**
+     * Public route path this page is written to.
+     */
+    route: string;
+    html: string;
+    assets: import("./compiler.js").Assets;
+    warnings: string[];
+};
 export type Paths = import("./config.js").Paths;
 export type Assets = import("./compiler.js").Assets;
+export type Meta = import("./compiler.js").Meta;
+export type Route = import("./router.js").Route;
 /**
  * A built route entry written to `dist/routes.json`.
  */
@@ -37,3 +140,31 @@ export type RouteManifestEntry = {
         runtime: boolean;
     };
 };
+/**
+ * One source route's record in the dev dependency map (`dist/.wd-dev-deps.json`),
+ * written by dev builds so a later `--changed` build can rebuild only the routes
+ * whose dependency graph contains the changed file.
+ */
+export type DepMapEntry = {
+    /**
+     * Source file, project-relative, POSIX-separated.
+     */
+    file: string;
+    /**
+     * Every source file this route's compile read (the page
+     * itself, includes, loop JSON data files, colocated `.skin`/`.js`) —
+     * project-relative, POSIX-separated, sorted.
+     */
+    deps: string[];
+    /**
+     * Collection names the route loops, so a change
+     * to any entry of the collection rebuilds this route.
+     */
+    collections: string[];
+    /**
+     * The manifest entries this route emitted
+     * (one, or one per pagination page), so `routes.json`/`_headers`/the sitemap
+     * can be reassembled globally without recompiling untouched routes.
+     */
+    pages: RouteManifestEntry[];
+};

package/types/catalog.d.ts

@@ -0,0 +1,97 @@
+/**
+ * The structured, machine-readable catalog of the whole `.wd` authoring surface.
+ * @returns {DirectiveCatalog}
+ */
+export function directiveCatalog(): DirectiveCatalog;
+/**
+ * Render the catalog as a compact llms.txt-style markdown cheatsheet — the
+ * artifact an app pastes into a small model's system prompt. Generated entirely
+ * from {@link directiveCatalog}, so it can never disagree with what compiles.
+ * @returns {string}
+ */
+export function llmsText(): string;
+/** The action tokens the catalog exposes — used by the drift guard. */
+export const CATALOG_ACTION_TOKENS: string[];
+/**
+ * Whether the directive
+ *   ships zero JS (static), needs the reactive runtime (reactive), or can be
+ *   either depending on whether it reads `:state`/`:store` (either).
+ */
+export type Reactivity = "static" | "reactive" | "either";
+export type DirectiveEntry = {
+    /**
+     * The directive token (`@loop`, `:state`, `:::`, …).
+     */
+    name: string;
+    /**
+     * A single line, or an opener with a closer.
+     */
+    kind: "line" | "block";
+    /**
+     * One-line schematic (`[…]` = optional, `<…>` = slot).
+     */
+    syntax: string;
+    /**
+     * One-line, plain-language summary.
+     */
+    description: string;
+    /**
+     * One concrete, compilable line.
+     */
+    example: string;
+    reactive: Reactivity;
+};
+/**
+ * A clause / action-op / pipe / operator entry.
+ */
+export type CatalogEntry = {
+    name: string;
+    syntax?: string | undefined;
+    description: string;
+    example?: string | undefined;
+};
+export type DirectiveCatalog = {
+    /**
+     * The installed Darkmown version.
+     */
+    version: string;
+    /**
+     * Always `.wd` — the file extension that gates directives.
+     */
+    format: string;
+    directives: DirectiveEntry[];
+    /**
+     * Clauses of the `@loop` header (fixed order).
+     */
+    loopClauses: CatalogEntry[];
+    /**
+     * Per-row meta variables valid in a loop body.
+     */
+    loopVariables: CatalogEntry[];
+    /**
+     * The `:button`/`:effect`/`:every` action vocabulary.
+     */
+    actionOps: CatalogEntry[];
+    /**
+     * The `{ value | pipe }` formatter whitelist.
+     */
+    formatPipes: CatalogEntry[];
+    /**
+     * Comparison operators for `where`/`:if`/`when`.
+     */
+    predicateOps: CatalogEntry[];
+    /**
+     * Logical joiners (`and`/`or`/`not`).
+     */
+    predicateJoiners: string[];
+    /**
+     * The `WDxxx` code blocks.
+     */
+    errorAreas: import("./errors.js").ErrorArea[];
+    /**
+     * Every stable compile-error
+     * code, with its cause and fix. A thrown error's message starts with its code
+     * (`[WD201] …`) and mirrors it on `err.wd.code`.
+     */
+    errors: import("./errors.js").ErrorEntry[];
+};

package/types/compiler/actions.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleButton(line: string, ctx: Ctx, index: number): string;
+/**
+ * Parse `:effect <watched> -> <actions>` into a zero-output marker the runtime
+ * watches: when `<watched>` state changes, it runs `<actions>` (the same `:button`
+ * action vocabulary, `;`-chained). For arbitrary side effects beyond `:computed`
+ * (derive state) and fetch deps (auto-refetch).
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleEffect(line: string, ctx: Ctx, index: number): string;
+/**
+ * Parse `:every <duration> -> <actions>` into a marker the runtime drives on a
+ * timer: every `<duration>` it runs `<actions>` (the same `:button` vocabulary,
+ * `;`-chained), and the interval auto-pauses while the tab is hidden. The one time
+ * primitive — behind live polling (`:every 5s -> board refetch`), clocks and
+ * countdowns (`:every 1s -> seconds++`), and slideshow autoplay (`:every 4s -> slide++`).
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleEvery(line: string, ctx: Ctx, index: number): string;
+/**
+ * @typedef {import("./context.js").Ctx} Ctx
+ * @typedef {import("./context.js").Action} Action
+ */
+export const BUTTON_EXAMPLE: ":button \"Add one\" -> count++";
+export const EFFECT_EXAMPLE: ":effect query -> searches++";
+export const EVERY_EXAMPLE: ":every 5s -> seconds++";
+export const ACTION_EXAMPLE: "count++";
+export const ACTION_USE: "Use: name++, name--, n += k, n -= k, name = v, flag toggle, list append/prepend v, list toggle v, list remove v, x clear, obj merge other, obj delete key, name reset — chain with \";\" — e.g. count++";
+export type Ctx = import("./context.js").Ctx;
+export type Action = import("./context.js").Action;

package/types/compiler/body.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @typedef {import("./context.js").Ctx} Ctx
+ */
+/**
+ * Parse a `.wd` body line-by-line into HTML, mixing directives and prose.
+ * @param {string[]} lines
+ * @param {Ctx} ctx
+ * @returns {string}
+ */
+export function compileBody(lines: string[], ctx: Ctx): string;
+export type Ctx = import("./context.js").Ctx;