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

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to Darkmown are documented here. Versions follow [semver](https://semver.org); pre-1.0 minor versions may contain breaking changes.
 
+## 2.3.0 — 2026-08-09
+
+A trust release. Every compile error now carries a stable, searchable code; the dependency tree carries zero known advisories; and CI proves the framework on three operating systems and three browser engines instead of one of each. The new coverage found real bugs, including one that had silently broken every Windows user since the project started. No runtime change (7654 B gzipped, unchanged) and no breaking changes.
+
+- **Stable `WDxxx` compile-error codes.** All 138 author-facing compile errors now carry a permanent identifier — `[WD201] Malformed :state in site/pages/index.wd:1: …` — mirrored on the thrown error as `err.wd.code` alongside the existing `file`, `line`, `hint`, and `example`. Codes are grouped by subsystem (`WD1xx` loops, `WD4xx` forms, `WD5xx` fetch, and so on), and a shipped code is a public contract: never renumbered, never reused. The registry (`src/errors.js`) is the single source of truth, [`docs/errors.md`](docs/errors.md) is generated from it, and the catalog exposes it as data. Drift guards run in both directions — an uncoded author-facing throw, a duplicate code, or an undocumented one all fail the build. Genuine internal invariants (the AST parser, the reader contract) deliberately stay plain `Error`s, and that split is enforced by test.
+- **Zero known advisories.** `npm audit --audit-level=high` now exits 0. `image-size` carried a high-severity advisory affecting *every* published version including the latest — no upgrade existed — so its one call site (reading `<img>` dimensions at build time) is now served by an inlined header reader for PNG, JPEG, GIF, WebP, and SVG. Its segment walkers are explicitly bounded, which is the exact failure class the advisory described. `linkify-it` and `esbuild` advisories cleared by upgrade. Runtime code dependencies drop from three to two.
+- **BUGFIX: CRLF source files no longer lose their frontmatter.** `parseFrontmatter` tested for an LF-shaped `---\n` opener, so a file authored on Windows — or checked out anywhere with git's `core.autocrlf`, the default *on* Windows — silently had its entire frontmatter block reclassified as body text. No error was raised: the page just lost its title, layout, `draft` flag, and collection schema fields. Source text is now newline-normalized at the reader boundary and in `parseFrontmatter` itself. If you have ever edited a Darkmown page on Windows, this is the release that fixes it.
+- **CI runs on Windows, macOS, and Linux, across Chromium, Firefox, and WebKit.** Previously ubuntu-only and Chromium-only. The browser matrix is sharded so three engines cost no more wall-clock than one, and browsers are cached by resolved Playwright version. The whole 19-job matrix completes in about two minutes. The Windows job found the CRLF bug on its first run.
+- **TypeScript types actually resolve now.** The `exports` map had no `types` conditions, so consumers on `moduleResolution: node16` / `nodenext` / `bundler` — the default for new TypeScript projects — resolved *no types at all*, and the `./catalog` subpath shipped no declarations. Both entrypoints now carry `types` conditions, `types/catalog.d.ts` is authored, and `@types/markdown-it` moved to `dependencies` (types-only, no runtime code) so the root entrypoint stops erroring. Fixing this exposed that `npm run types` had been failing under TypeScript 6 and emitting nothing, leaving the committed declarations stale; generation is repaired and the output regenerated.
+- **A canary channel.** Merges to `master` publish a prerelease to the `next` dist-tag, so a fix can be exercised before it becomes stable: `npm i @zvndev/darkmown@next`. The tag-triggered stable path is untouched, and the canary job asserts after publishing that it did not become `latest`.
+- **Property tests for the skin compiler and the router,** in the seeded, reproducible style of the existing fuzz suite. They immediately found a real bug: `.skin` token modifiers quoted the attribute *value* but never validated the attribute *name*, so `tokens [{=v]` emitted `:root[{="v"]` — a stray brace that unbalances the stylesheet and makes a CSS parser swallow every rule after it. Fixed, with the case kept as a permanent regression guard.
+- **Internal:** the VS Code extension's `.vsix` is now built and uploaded by CI on every push, so it can be installed from a run without a marketplace listing. `.gitattributes` pins the working tree to LF. The test suite grew from 892 to 989 tests, holding 100% `src` line coverage.
+
+## 2.2.0 — 2026-07-12
+
+AI authoring becomes a first-class framework surface: a machine-readable directive catalog, a generated prompt cheatsheet, a shipped GBNF grammar for constrained decoding, and compile errors that teach by example — all generated from the compiler's own whitelist tables, so none of it can drift from what actually compiles. Zero runtime impact (7654 B, unchanged).
+
+- **`darkmown catalog` — the language, as data.** `directiveCatalog()` (also `import '@zvndev/darkmown/catalog'`) returns every directive, loop clause, action op, format pipe, and predicate operator with syntax, description, a concrete example, and whether it makes a page reactive — 25 directives, 13 action ops, 20 pipes, sourced from the compiler's real tables with drift-guard tests in both directions. `darkmown catalog --llms` renders the same data as a ~92-line cheatsheet, and every build emits it as `dist/llms.txt` — the exact artifact to hand an LLM (or stuff into a small on-device model's system prompt).
+- **A shipped GBNF grammar (`grammar/wd-directives.gbnf`).** Generated from the same tables: directive-line shape, clause order, and the closed op/pipe/action vocabularies as literal alternations, with free-form values left permissive. Point llama.cpp's `grammar` field at it and a local model becomes structurally unable to emit JS/HTML muscle-memory syntax inside `.wd` directives. Kept in sync by test; regenerate with `scripts/gen-grammar.mjs`.
+- **Compile errors now teach by example.** All 24 corrective `Use:` hints with bracket-placeholders gained a trailing concrete line — `… Use: @loop src into item [where …] — e.g. @loop /products.json into p where p.price < 50` — and a test extracts every example from the real thrown error strings and compiles it, so the examples can never rot. Empirically motivated: small local models copy error-message examples verbatim, brackets and all.
+- **Structured error metadata.** Compile errors carry `err.wd = { file, line, hint, example }` alongside the unchanged message string — no more parsing error text in tooling (the playground, editors, agent harnesses).
+
 ## 2.1.0 — 2026-07-11
 
 Two headlines. Reactive pages now run under the **same strict, eval-free CSP as static pages** — the runtime interprets validated expressions instead of building functions, so `'unsafe-eval'` is gone from every page the framework ships. And darkmown.com gained a **browser playground**: the real compiler, bundled, compiling `.wd` live on every keystroke — built on a new fs-free `compileFromMemory` API.

package/README.md

@@ -39,6 +39,10 @@ npx darkmown dev
 
 The package is `@zvndev/darkmown`; the command it installs is plain `darkmown`.
 
+Every merge to `master` also publishes a prerelease to the `next` tag, so you can try a
+fix before it ships stable: `npm install -D @zvndev/darkmown@next`. Use `@latest` (the
+default) for anything you care about.
+
 Prefer to see it run before you install? The [browser playground](https://darkmown.com/playground/)
 compiles `.wd`/`.md` live in your browser — the same compiler the CLI ships — with
 no install and no build step.
@@ -59,6 +63,7 @@ npm run dev     # live demo site — the same site that runs darkmown.com
 - `darkmown build [--target cloudflare] [--drafts]` writes static output to `dist` (plus `sitemap.xml`/`rss.xml`/`robots.txt`); `--drafts` includes `draft: true` pages for staging.
 - `darkmown deploy <vercel|cloudflare> [--prod]` builds and deploys via the platform CLI.
 - `darkmown serve` previews the built `dist` locally.
+- `darkmown catalog [--llms]` prints the machine-readable directive catalog (JSON), or with `--llms` a compact cheatsheet — see [AI authoring](#ai-authoring).
 - `darkmown version` prints the installed package version.
 - `darkmown help` prints CLI usage.
 
@@ -984,6 +989,66 @@ const { html, assets } = compileFromMemory(
 
 Includes, colocated `.skin`/`.js` detection, and `@loop` JSON-data reads all resolve against the map (anything not in it is simply "absent"), and it throws the **same `file:line` compile errors** as the CLI — the error DX is identical. This is exactly the entry point the [browser playground](https://darkmown.com/playground/) is built on: markdown-it and the compiler bundled to one asset, compiling `.wd`/`.md` on every keystroke and rendering the result into an iframe. On disk, `compilePage(file, paths)` is the same compile with a filesystem reader injected for you.
 
+### Structured compile errors — `err.wd`
+
+Every compile error is still a plain `Error` with the same `file:line` message, but it now also carries a machine-readable mirror on `err.wd` — so an AI edit loop (or an editor) gets the facts without re-parsing the prose:
+
+```js
+import { compileFromMemory } from "@zvndev/darkmown";
+
+try {
+  compileFromMemory({ "site/pages/index.wd": ":state x" }, "site/pages/index.wd");
+} catch (err) {
+  err.message; // "[WD201] Malformed :state in …/index.wd:1: :state x. Use: :state name = value [persist] — e.g. :state count = 0"
+  err.wd;      // { code: "WD201", file: "…/index.wd", line: 1, hint: ":state name = value [persist] — e.g. …", example: ":state count = 0" }
+}
+```
+
+`example` is always a concrete, **compilable** line (never a `[placeholder]`), and every corrective `Use:` hint that contains bracket-placeholders ends with a matching `— e.g. <valid line>`. This is a deliberate affordance for small local models, which otherwise copy `[optional]`-style placeholders into source verbatim.
+
+## Compile error codes
+
+Every author-facing compile error opens with a stable `WDxxx` code, so it is searchable, linkable, and matchable by tooling without parsing prose:
+
+```
+[WD201] Malformed :state in site/pages/index.wd:1: :state x.
+        Use: :state name = value [persist] — e.g. :state count = 0
+```
+
+The full list lives in [`docs/errors.md`](docs/errors.md) — code, cause, fix, and a compilable example each. Codes are grouped by subsystem:
+
+| Range | Subsystem |
+| --- | --- |
+| `WD0xx` | Source, frontmatter & block structure |
+| `WD1xx` | Loops & collections |
+| `WD2xx` | State & expressions |
+| `WD3xx` | Button, effect & timer actions |
+| `WD4xx` | Forms & form fields |
+| `WD5xx` | Data fetching & URL safety |
+| `WD6xx` | Includes & page structure |
+| `WD7xx` | Media & embeds |
+| `WD8xx` | Skins & styling |
+| `WD9xx` | Project, routing & CLI |
+
+**A shipped code is a public contract:** it is never renumbered and a retired number is never reused, so an error found in an old log or issue always resolves to a meaningful entry. `docs/errors.md` is generated from the compiler's own registry, and drift guards fail the build if an author-facing error is added without a code, if two errors share one, or if a code goes undocumented.
+
+Genuine *internal* invariants — the expression-AST parser reading the compiler's own validated output, the reader contract — deliberately stay plain `Error`s and carry no code, because they signal a framework bug rather than something you can fix in a page.
+
+## AI authoring
+
+Darkmown ships its own description of the `.wd` language — the same tables the compiler validates against — so a tool can teach a model to write `.wd` and constrain its output to what compiles.
+
+- **Directive catalog** — `darkmown catalog` prints structured JSON: every directive, `@loop` clause, loop variable, button action, format pipe, and predicate operator, each with a syntax template, a one-line description, one concrete example, and whether it needs the reactive runtime. Importable too: `import { directiveCatalog } from "@zvndev/darkmown/catalog"`.
+- **Cheatsheet (`llms.txt`)** — `darkmown catalog --llms` prints a compact (~90-line) markdown cheatsheet generated from the same data — the artifact you stuff into a model's system prompt. Every build also writes it to `dist/llms.txt`.
+- **GBNF grammar** — [`grammar/wd-directives.gbnf`](grammar/wd-directives.gbnf) is a generated [GBNF](https://github.com/ggerganov/llama.cpp/blob/master/grammars/README.md) grammar for `.wd` directive lines. Point llama.cpp (or any grammar-constrained decoder) at it to make invalid directive lines — JS idioms like `cart.filter(...)`, HTML muscle-memory like `::: card class="…"` — literally unrepresentable during generation. Regenerate with `node scripts/gen-grammar.mjs`.
+
+```sh
+darkmown catalog --llms > system-prompt.md   # paste into a model's context
+darkmown build                               # also emits dist/llms.txt
+```
+
+Because the catalog, cheatsheet, grammar, and error `example`s are all generated from the compiler's own tables, they cannot drift from what actually compiles (enforced by tests).
+
 ## Editor support
 
 A VS Code extension in [`editors/vscode`](editors/vscode) gives `.wd` and `.skin` files syntax highlighting, snippets, and folding — so a `.wd` file reads as Markdown-plus-directives, never as broken Markdown.

package/docs/cli.md

@@ -82,6 +82,14 @@ The deploy URL is printed when the CLI reports it. If the platform CLI isn't sig
 
 Serves the already-built `dist` directory for local preview (static only — use `darkmown dev` to exercise `api/*` locally). Run `darkmown build` first.
 
+### `darkmown catalog [--llms]`
+
+Prints the machine-readable `.wd` directive catalog as JSON — every directive, `@loop` clause, loop variable, button action, format pipe, and predicate operator, each with a syntax template, description, and concrete example. With `--llms` it prints a compact (~90-line) markdown cheatsheet instead — the artifact to paste into an AI model's system prompt. Every `darkmown build` also writes the cheatsheet to `dist/llms.txt`, and Darkmown ships a generated GBNF grammar (`grammar/wd-directives.gbnf`) for constrained decoding.
+
+```sh
+darkmown catalog --llms > system-prompt.md
+```
+
 ## Smoke checks
 
 From this repository, run:

package/docs/spec-alignment.md

@@ -2,6 +2,16 @@
 
 This audit compares the current Darkmown implementation with the original MARROW/WhateverDown vision and the follow-up decisions made on 2026-06-11.
 
+## 2.3.0 additions — error codes, supply chain, platform coverage (2026-08-09)
+
+- **Every author-facing compile error carries a stable `WDxxx` code.** The original vision treated compile errors as a first-class DX surface ("errors include file path + corrective suggestion"); this closes the last gap by making them *identifiable*. 138 codes, grouped by subsystem, mirrored on `err.wd.code` beside the existing `file`/`line`/`hint`/`example`. `src/errors.js` is the single source of truth, `docs/errors.md` is generated from it, and `directiveCatalog()` exposes it as data for tooling. Drift guards run both directions: an author-facing throw without a code, a duplicate code, or an undocumented code all fail the build. Internal invariants (the AST parser reading the compiler's own validated output, the reader contract) stay plain `Error`s by design — they signal a framework bug, not an authoring mistake — and that split is itself enforced by test.
+- **Zero known advisories, and one fewer runtime dependency.** `image-size` carried a high-severity advisory affecting every published version with no upgrade path, so its single build-time call site is now served by an inlined header reader (PNG/JPEG/GIF/WebP/SVG) with explicitly bounded parse loops. This keeps the project's "few runtime dependencies" posture honest rather than deferring to an unfixable upstream.
+- **BUGFIX — CRLF sources lost their frontmatter.** `parseFrontmatter` tested an LF-shaped `---\n` opener, so any file authored on Windows or checked out with `core.autocrlf` had its whole frontmatter block silently reclassified as body text: no error, but the page lost its title, layout, `draft` flag, and collection schema fields. Newline normalization now happens at the reader boundary and in `parseFrontmatter`. This had been latent since the first commit; it surfaced within minutes of adding a Windows CI job.
+- **Platform coverage is now part of the contract.** CI runs the suite on Linux, Windows, and macOS, and the browser e2e suite against Chromium, Firefox, and WebKit (sharded, so three engines cost roughly one engine's wall-clock). The reactive runtime had only ever been proven in one engine; the CLI's path handling had never executed on Windows at all.
+- **Types resolve for modern TypeScript consumers.** The `exports` map lacked `types` conditions, so `moduleResolution: node16`/`nodenext`/`bundler` consumers got no types from either entrypoint. Fixed, `types/catalog.d.ts` authored, and the declaration build itself repaired (it had been failing silently under TypeScript 6, leaving the committed `.d.ts` stale).
+- **Property tests extended to the skin compiler and the router,** in the existing seeded/reproducible style. They found a real defect on the first run: `.skin` token modifiers quoted the attribute value but never validated the attribute *name*, letting `tokens [{=v]` emit an unbalanced `:root[{="v"]` selector that a CSS parser would use to swallow every following rule.
+- **Release channels:** merges to `master` publish a prerelease to the `next` dist-tag; the tag-triggered stable path is unchanged and the canary job verifies after publishing that it did not take `latest`.
+
 ## 2.1.0 additions — eval-free expression interpreter (2026-07-11)
 
 - **Reactive pages run under a strict CSP with no `'unsafe-eval'`.** This is the headline. Through 2.0.x, the runtime executed validated `:computed` / `@loop … where` / `.class when` / `:if` expressions by building a `new Function` — which forced `script-src 'unsafe-eval'` on every reactive page, the #1 objection from security-minded adopters. The grammar was already a **closed** whitelist (comparisons, `and`/`or`/`not`, arithmetic in `:computed`, the `sum`/`avg`/`min`/`max`/`count` aggregates, literals, and dotted paths with proto-pollution guards), so it is small enough to interpret directly. The compiler now serializes each already-validated expression into a compact **AST** (nested arrays, tags `L`/`S`/`I`/`C`/`A` + the fixed operators — see `src/compiler/expr-ast.js`) emitted into the `data-wd-*` attributes, and the runtime **walks** it with a tiny closed evaluator (`src/runtime.js`). No `new Function`, no `eval`, anywhere on the page. The evaluator applies the *actual* JavaScript operators, so semantics (loose `==`/`!=`, `NaN`/`null` handling, `&&`/`||` short-circuit, string coercion, division) are byte-identical to the old path — guarded by a parity battery (`tests/expr-ast.test.js`) that compares old-`new Function` vs new-AST results across a wide input matrix, plus the fuzz suite (`tests/fuzz.test.js`) which now proves accepted expressions carry only closed op tags (dangerous text can survive only as inert `["L", …]` data) and walk to a pure value.
@@ -204,6 +214,14 @@ The 1.3.0 cycle closes table-stakes gaps a new user expects out of the box. Trac
 - **`compileFromMemory(files, entryPath, options)`** — a new public API (exported from `src/compiler.js` and the package root) that compiles a page from an in-memory map of project-relative path → source, with **zero `node:fs`**. It is the minimal-clean vfs refactor of the compiler: a `Reader` abstraction (`src/compiler/reader.js`) is threaded through the `Compilation`/`Ctx` and the page-shell helpers, replacing every direct `node:fs` call in `src/compiler/{page,includes,loops,collections}.js`. The default **`fsReader()`** (`src/compiler/fs-reader.js`, the ONLY compiler module importing `node:fs`) is injected by the Node-facing barrel, so `compilePage`/`compileDocument`/`enhanceImages` keep their exact signatures and the on-disk build stays **byte-identical** (golden: the demo `dist/` is unchanged across the refactor). `memoryReader(files, cwd)` backs the fs-free path: includes, colocated `.skin`/`.js` detection, and `@loop` JSON-data reads all resolve against the map; missing files are simply "absent"; image measuring degrades to no-dimensions (no image bytes in memory). It throws the **same `file:line` compile errors** as the CLI (a compile↔memory parity test asserts identical HTML and error text). This is strategic surface — a planned mobile host needs exactly a filesystem-free compile.
 - **Browser playground (`/playground/`)** — a live editor + preview page on the demo site. `esbuild` (a new **devDependency only**) bundles `compileFromMemory` + markdown-it + a common-languages highlight.js subset into one self-contained ESM asset (`scripts/build-playground.mjs` → the committed colocated `site/pages/playground/index.js`, rebuilt with `npm run build:playground`); `node:path`/`node:crypto`/`image-size` are aliased to tiny browser shims (`scripts/playground/shims/`). The bundle (~128 KB gzipped) loads **only** on `/playground/` and does **not** count against the 8 KB runtime budget (`src/runtime.js` is untouched by the playground). The preview is an `iframe srcdoc` of the compiled HTML; reactive previews load `/__wd/runtime.js` by same-origin URL and inherit the page's CSP — which since 2.1 is the same strict, **eval-free** policy on every page (the runtime interprets expression ASTs; see the 2.1 entry above), so the preview runs under the shipped CSP with no special allowance (`frame-src` does not block `about:srcdoc`; no `'unsafe-inline'` anywhere). The playground page itself dogfoods a real reactive island (a `:state`/`:button` example picker bridged to the bundle via `window.wd.subscribe`), so it is `runtime: true`.
 
+## AI authoring — catalog, llms.txt, grammar, structured errors (2026-07-12)
+
+- **Machine-readable directive catalog** — `src/catalog.js` (`directiveCatalog()`, exported from the package root and via the `@zvndev/darkmown/catalog` exports subpath) returns structured JSON describing the whole `.wd` surface: every directive, `@loop` clause, loop variable, button-action op, format pipe, and predicate operator, each with a syntax template, one-line description, one **concrete compilable example**, and a reactivity flag. It is sourced from the compiler's own tables — `FORMATTER_NAMES` (format.js), `PREDICATE_OPS` (predicates.js), `LOOP_META` (context.js), the action vocabulary (`ACTION_USE`, actions.js) — and from the shared `*_EXAMPLE` constants the error hints use, so it cannot drift from what compiles (drift-guarded in `tests/catalog.test.js`, which also compiles every example).
+- **`llms.txt` cheatsheet** — `llmsText()` renders a compact (~90-line) markdown cheatsheet from the same catalog; `darkmown catalog` prints the JSON and `darkmown catalog --llms` the cheatsheet, and every build writes `dist/llms.txt`. This is the artifact an app pastes into a small model's system prompt.
+- **Generated GBNF grammar** — `src/grammar.js` (`generateGrammar()`, wrapped by `scripts/gen-grammar.mjs`) emits `grammar/wd-directives.gbnf`, a llama.cpp grammar for `.wd` **directive lines** (plus the `{ path | pipe }` interpolation token). It constrains a line's *shape* — the leading keyword must be a real directive, `@loop` must be `@loop <src> into <item> …clauses`, a condition must be `operand <op> operand`, a `:button` must be `"…" -> <action-chain>` — which deletes the on-device failure class (JS/HTML muscle-memory openers become unrepresentable) while staying small; free-form values remain `text`. Well-formedness + catalog coverage are tested in `tests/grammar.test.js`, and the committed file is kept in sync by the same test.
+- **Structured compile errors** — errors carry a machine-readable mirror on `err.wd = { file, line?, hint?, example? }` (helper `wdError` in context.js) alongside the unchanged string message. Applied across loops, includes, predicates, forms, state, actions, media, fetch, and structure. `example` is always a compilable line.
+- **Concrete examples in error hints** — every corrective `Use:` hint that contained bracket-placeholders now ends with ` — e.g. <concrete valid line>`, drawn from the same `*_EXAMPLE` constants. `tests/error-examples.test.js` extracts each `e.g.` example from the *real* thrown error string and compiles it (enforcement, not convention). Motivation: the on-device model bench (`bench/on-device/RESULTS.md`) found small models echo bracket-placeholders into source verbatim.
+
 ## Demo-only directives (not part of the public surface)
 
 The compiler recognizes three directives — `:note`, `:try`, and `:sprint` — that exist **only to power the demo site** (darkmown.com). They are **not** part of the supported public directive set, are not documented for authors, and may change or be removed without notice. Do not build pages that depend on them. The supported public directives are the ones catalogued above: `:state`, `:store`, `:computed`, `:effect`, `:every`, `:theme`, `:button`, `:bind`, `:if`/`:else if`/`:else`/`:endif`, `:fetch` (with `headers`/`refresh`), `:form`/`:input`/`:submit`, `:slider`, `:carousel`, `:video`/`:audio`/`:embed`, `@loop`/`@empty`/`@endloop` (with `where`, `sort by` — including reactive `{ state }` keys —, `reverse`, `offset`, `limit`, `sortable`), `@include`, and `::: section` (with reactive `.class when`). Interpolation supports **format pipes** (`{ value | name:arg }`) and `:computed`/list-pipe **aggregates** (`sum`/`avg`/`min`/`max`/`count`). The runtime escape hatch is `window.wd` (`get`/`set`/`subscribe`/`state`/`render`).

package/grammar/wd-directives.gbnf

@@ -0,0 +1,58 @@
+# Darkmown .wd directive-line grammar — generated by src/grammar.js
+# Constrains a directive line (or a { path | pipe } interpolation). Do not edit by hand.
+
+root ::= directive | binding
+directive ::= dir-include | dir-loop | dir-container | dir-if | dir-state | dir-store | dir-computed | dir-fetch | dir-effect | dir-every | dir-theme | dir-button | dir-form | dir-input | dir-textarea | dir-select | dir-checkbox | dir-radio | dir-submit | dir-bind | dir-slider | dir-video | dir-audio | dir-embed | dir-carousel
+
+dir-loop ::= "@loop" sp operand sp "into" sp ident loop-clauses
+dir-if ::= ":if" sp ( condition (sp joiner sp condition)* | path )
+dir-button ::= ":button" sp dqstring sp "->" sp action-chain
+dir-container ::= ":::" restofline
+
+dir-include ::= "@include" restofline
+dir-state ::= ":state" restofline
+dir-store ::= ":store" restofline
+dir-computed ::= ":computed" restofline
+dir-fetch ::= ":fetch" restofline
+dir-effect ::= ":effect" restofline
+dir-every ::= ":every" restofline
+dir-theme ::= ":theme" restofline
+dir-form ::= ":form" restofline
+dir-input ::= ":input" restofline
+dir-textarea ::= ":textarea" restofline
+dir-select ::= ":select" restofline
+dir-checkbox ::= ":checkbox" restofline
+dir-radio ::= ":radio" restofline
+dir-submit ::= ":submit" restofline
+dir-bind ::= ":bind" restofline
+dir-slider ::= ":slider" restofline
+dir-video ::= ":video" restofline
+dir-audio ::= ":audio" restofline
+dir-embed ::= ":embed" restofline
+dir-carousel ::= ":carousel" restofline
+
+loop-clauses ::= ( sp loop-clause )*
+loop-clause ::= where-clause | "sort by" sp path ( sp ( "asc" | "desc" ) )? | "reverse" | "offset" sp number | "limit" sp number | "paginate" sp number | "sortable"
+where-clause ::= "where" sp condition ( sp joiner sp condition )*
+condition ::= operand sp op sp operand
+op ::= "contains" | "==" | "!=" | ">=" | "<=" | ">" | "<"
+joiner ::= "and" | "or"
+
+action-chain ::= action ( wsopt ";" wsopt action )*
+action ::= ident action-op
+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"
+
+binding ::= "{" wsopt path pipe-chain wsopt "}"
+pipe-chain ::= ( wsopt "|" wsopt pipe ( ":" value )* )*
+pipe ::= "money" | "number" | "percent" | "round" | "date" | "time" | "datetime" | "upper" | "lower" | "capitalize" | "truncate" | "trim" | "pluralize" | "default" | "sum" | "avg" | "min" | "max" | "count" | "join"
+
+operand ::= path | dqstring | number
+value ::= dqstring | number | path
+ident ::= [a-zA-Z_$] [a-zA-Z0-9_$]*
+path ::= [a-zA-Z0-9_$/.~-]+
+number ::= [0-9]+
+dqstring ::= "\"" [^"]* "\""
+restofline ::= [^\n]*
+sp ::= " "+
+wsopt ::= " "*
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/darkmown",
-  "version": "2.1.0",
+  "version": "2.3.1-next.1.g3a4a8dc",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -12,7 +12,14 @@
   },
   "main": "./src/index.js",
   "exports": {
-    ".": "./src/index.js",
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./catalog": {
+      "types": "./types/catalog.d.ts",
+      "default": "./src/catalog.js"
+    },
     "./package.json": "./package.json"
   },
   "types": "./types/index.d.ts",
@@ -45,6 +52,7 @@
   "files": [
     "src",
     "types",
+    "grammar",
     "site",
     "!site/_/og*.png",
     "docs/cli.md",
@@ -59,18 +67,17 @@
     "node": ">=20"
   },
   "dependencies": {
+    "@types/markdown-it": "^14.1.2",
     "highlight.js": "^11.11.1",
-    "image-size": "^1.2.1",
-    "markdown-it": "^14.2.0"
+    "markdown-it": "^14.3.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.5.1",
-    "@playwright/test": "^1.49.0",
-    "@types/markdown-it": "^14.1.2",
-    "@types/node": "^26.0.0",
-    "esbuild": "^0.24.2",
+    "@biomejs/biome": "^2.5.7",
+    "@playwright/test": "^1.61.1",
+    "@types/node": "^26.1.1",
+    "esbuild": "^0.28.2",
     "husky": "^9.1.7",
-    "lint-staged": "^16.4.0",
+    "lint-staged": "^17.0.0",
     "typescript": "^6.0.3"
   },
   "repository": {

package/site/pages/docs/index.wd

@@ -47,6 +47,7 @@ Darkmown is a Markdown-native framework for mostly-static sites with tiny reacti
 - [Syntax highlighting](#syntax-highlighting)
 - [Trust boundary](#trust-boundary)
 - [Colocation](#colocation)
+- [Compile error codes](#compile-error-codes)
 - [CLI reference](#cli-reference)
 - [Spec status](#spec-status)
 </nav>
@@ -604,6 +605,33 @@ See [SECURITY.md](https://github.com/ZVN-DEV/darkmown/blob/master/SECURITY.md) i
 - Both work for included fragments too, by basename.
 - Any other file under `site/pages/` (an image, font, PDF — anything that isn't a `.md`/`.wd` route or a basename-matched `.skin`/`.js`) copies to `dist/` at its own path with the right content-type. So `site/pages/logo.svg` is served at `/logo.svg`. Assets below hidden path segments (`.`, `-`, or `_`) and symlinked page assets are skipped, matching the routing privacy rule. Use the `site/_/` shelf for assets shared across pages; colocate the ones a single page owns.
 
+## AI authoring
+
+Darkmown ships a machine-readable description of its own language, so an AI tool can learn `.wd` and be constrained to output that compiles. It is all generated from the compiler's own tables, so it never drifts from the real grammar.
+
+- **`darkmown catalog`** prints structured JSON: every directive, `@loop` clause, loop variable, button action, format pipe, and predicate operator — each with a syntax template, a one-line description, one concrete example, and whether it needs the reactive runtime. Import it too: `import { directiveCatalog } from "@zvndev/darkmown/catalog"`.
+- **`darkmown catalog --llms`** prints a compact (~90-line) cheatsheet — the artifact you paste into a model's system prompt. Every build also writes it to `dist/llms.txt`.
+- **`grammar/wd-directives.gbnf`** is a generated GBNF grammar for `.wd` directive lines. Point a grammar-constrained decoder (llama.cpp and friends) at it to make invalid directive lines — JS idioms, HTML muscle-memory — impossible to generate.
+
+```sh
+darkmown catalog --llms > system-prompt.md
+```
+
+Compile errors help here too: every corrective `Use:` hint ends with a concrete `— e.g. <valid line>`, and each thrown error carries a structured `err.wd = { file, line, hint, example }` mirror alongside its message — so an edit-and-retry loop gets the fix without parsing prose.
+
+## Compile error codes
+
+Every author-facing compile error opens with a stable `WDxxx` code, so it is searchable and matchable by tooling without parsing prose:
+
+```
+[WD201] Malformed :state in site/pages/index.wd:1: :state x.
+        Use: :state name = value [persist] — e.g. :state count = 0
+```
+
+The code is mirrored on the thrown error as `err.wd.code`, alongside `file`, `line`, `hint`, and a compilable `example`. Codes are grouped by subsystem — `WD0xx` source and frontmatter, `WD1xx` loops, `WD2xx` state and expressions, `WD3xx` actions, `WD4xx` forms, `WD5xx` fetching, `WD6xx` includes and structure, `WD7xx` media, `WD8xx` skins, `WD9xx` project and CLI.
+
+A shipped code is a public contract: never renumbered, never reused. The full reference — cause, fix, and an example per code — is generated from the compiler's own registry, so it cannot drift from what actually throws.
+
 ## CLI reference
 
 The `darkmown` command (installed by `npx @zvndev/darkmown`) is the whole tool — every command is one word:
@@ -612,6 +640,7 @@ The `darkmown` command (installed by `npx @zvndev/darkmown`) is the whole tool
 - `darkmown dev` — the live compiler: browser reload, an in-browser error overlay, incremental rebuilds, and a local runner for `api/*` functions.
 - `darkmown build [--target cloudflare] [--drafts]` — write 100% static output to `dist/` (plus `sitemap.xml` / `rss.xml` / `robots.txt`); `--drafts` includes `draft: true` pages for a staging deploy.
 - `darkmown serve` — preview the built `dist/` locally (static only; use `dev` to exercise `api/*`).
+- `darkmown catalog [--llms]` — print the `.wd` directive catalog as JSON, or with `--llms` a compact cheatsheet for priming an AI model (see [AI authoring](#ai-authoring)).
 - `darkmown deploy <vercel|cloudflare> [--prod]` — build (target-aware) and deploy through the platform CLI, printing your URL; an unauthenticated CLI surfaces the login to run first.
 - `darkmown version` / `darkmown help` — print the installed version, or the full command summary and directive syntax.