@zvndev/darkmown 2.6.1-next.12.ge562f5d → 2.7.0

package/docs/cli.md

@@ -1,14 +1,26 @@
 # Darkmown CLI
 
-## Install locally
+The published package is `@zvndev/darkmown`; the executable it installs is plain `darkmown`. Nothing here needs a global install.
+
+## Install
+
+Scaffold a new project in one command, with no prior install:
 
 ```sh
+npx @zvndev/darkmown init my-site
+cd my-site
 npm install
-npm link
-darkmown help
+npm run dev
 ```
 
-`package.json` exposes the executable as `darkmown`.
+Or add it to a project you already have, and call it through `npx`:
+
+```sh
+npm install -D @zvndev/darkmown
+npx darkmown help
+```
+
+Working on the framework itself instead? See [Contributing](../CONTRIBUTING.md). From a clone, `npm install` then `npm link` puts a `darkmown` on your `PATH` that points at your working tree.
 
 ## Commands
 
@@ -61,11 +73,13 @@ Rebuilds are **incremental** for `site/` content changes. Every dev build writes
 
 Correctness beats speed: **any uncertainty runs a full rebuild** — a new, deleted, or renamed file; a file no dependency graph accounts for; a change to the site-wide feed link; a missing or stale map. A change under `src/` (the framework's own code) always runs a full rebuild in a child process so fresh modules load. Production `darkmown build` writes no map and is unaffected.
 
-### `darkmown build [--target cloudflare]`
+### `darkmown build [--target cloudflare] [--drafts]`
 
 Compiles `site/pages` into `dist`. The output is always 100% static HTML.
 
-Static pages do not receive `/__wd/runtime.js`; reactive pages do. Pay-for-what-you-use behavior modules (`:sortable`, `:carousel`) emit to `dist/__wd/behaviors/` only on the pages that use them.
+`--drafts` includes pages marked `draft: true` in their frontmatter, which a default `build` leaves out of `dist`, `routes.json`, `sitemap.xml`, and `rss.xml` entirely. Use it for a staging deploy. `darkmown dev` always builds drafts, with a "DRAFT" banner that exists only in the dev server.
+
+Static pages do not receive `/__wd/runtime.js`; reactive pages do. Pay-for-what-you-use behavior modules (`sortable`, `:carousel`) emit to `dist/__wd/behaviors/` only on the pages that use them.
 
 `--target cloudflare` additionally emits `dist/_worker.js` — a Cloudflare Pages worker that routes `/api/*` to the project's `api/*.js` functions and serves everything else from `env.ASSETS`. The default target leaves `api/` for Vercel to run natively. `darkmown deploy` sets the right target automatically.
 
@@ -84,23 +98,19 @@ 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]`
+### `darkmown catalog [--llms|--llms-full]`
 
-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.
+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.
 
-```sh
-darkmown catalog --llms > system-prompt.md
-```
-
-## Smoke checks
-
-From this repository, run:
+- `--llms` prints a compact markdown cheatsheet instead: the artifact to paste into an AI model's system prompt.
+- `--llms-full` prints the complete reference that cheatsheet points at: every directive with its full syntax and example, every clause, action, pipe, operator, and frontmatter key, plus **every compile-error code with its cause and fix**. An edit loop that hits `[WD201]` can resolve it from the same output it learned the syntax from.
 
 ```sh
-npm run smoke
+darkmown catalog --llms > system-prompt.md
+darkmown catalog --llms-full > reference.md
 ```
 
-The smoke script packs the local tarball, installs the packed CLI in a temporary driver project, scaffolds a consumer app through that installed bin, installs the same tarball into the app, builds it, verifies the reactive home route, and verifies the plain `.md` about route stays zero-JS.
+Every `darkmown build` also writes both files (`dist/llms.txt` and `dist/llms-full.txt`), and Darkmown ships a generated GBNF grammar (`grammar/wd-directives.gbnf`) for constrained decoding.
 
 ## Backends (`api/`)
 
@@ -123,3 +133,27 @@ export default async function (request, context) {
 ### Cloudflare Pages note
 
 Cloudflare advanced mode (`dist/_worker.js`) does not run a bundler, so an `api/` handler deployed to Cloudflare must be dependency-free (or pre-bundled). The same source still runs on Vercel (which bundles) and in `darkmown dev`.
+
+## Working on the framework itself
+
+Everything from here down is for a clone of the Darkmown repository, not for a project built with it.
+
+### Regenerating the runtime artifact
+
+The runtime that ships is `src/runtime.min.js`, a committed esbuild build of the readable `src/runtime.js` (plus its sourcemap). `darkmown build` copies that artifact byte for byte, so it has to be regenerated whenever the source changes:
+
+```sh
+npm run build:runtime
+```
+
+Nothing regenerates it behind your back. A drift test rebuilds it in memory and fails on any byte difference, and CI runs the same check, so a stale artifact fails the build rather than shipping. `npm run dev` regenerates it first through `predev`, which is why development and production serve the same bytes.
+
+### Smoke checks
+
+From this repository, run:
+
+```sh
+npm run smoke
+```
+
+The smoke script packs the local tarball, installs the packed CLI in a temporary driver project, scaffolds a consumer app through that installed bin, installs the same tarball into the app, builds it, verifies the reactive home route, and verifies the plain `.md` about route stays zero-JS.

package/docs/spec-alignment.md

@@ -2,6 +2,27 @@
 
 This audit compares the current Darkmown implementation with the original MARROW/WhateverDown vision and the follow-up decisions made on 2026-06-11.
 
+## 2.7.0 additions: silent failures closed, and the headroom spent (2026-09-04)
+
+An audit put one question to every path in the compiler, the builder and the runtime: when this goes wrong, does the author find out? Where the answer was no, the behavior is now either correct or a coded refusal. Separately the runtime started shipping minified, which returned roughly 2 KB of the 8 KB budget, and that headroom bought five features the original vision named but the framework could not reach.
+
+- **Interpolation resolves everywhere, or says why not.** A `{ … }` in a link or image destination, a raw HTML attribute, or an html block used to be left as literal text with no diagnostic at all. Build-time values now resolve in every one of those positions (every brace in a destination, not only a leading one), heading ids slug the *resolved* text so an interpolated heading gets a real anchor, and the two positions that cannot bind are warned with `file:line` and the way out named. Values in URL position are percent-encoded and dangerous schemes refused, so data can no longer break out of a destination on an `html: true` page. Inline code spans are masked, so a page can still document the syntax.
+- **Reactive attribute binding (`data-wd-attr` / `data-wd-each-attr`).** The syntax is unchanged (`[label]({ expr })`, `[label](/p/{ expr }/)`, `![alt]({ expr })`); what changed is that a `:state`/`:store`/`:computed`/row/meta value there is a live binding rather than a one-time paint. The compiler emits the destination as literal parts plus readers, and the runtime rebuilds the whole value each render, re-checking the scheme because it is the only layer that can see a value which only exists at runtime. The build-time paint stays the seed, so the pre-hydration page and the crawler both see a real URL. +185 B.
+- **`:state … from-url`, the URL as state.** A third word in the persistence vocabulary, on `:state` only. The key mirrors into the query string via `replaceState` (`cart:items` becomes `cart.items`), a value at its seed drops the parameter, `popstate` re-reads, and boot precedence is URL then storage then seed. `WD260` refuses it on `:store`/`:theme` with the reason (both are shared by every page and tab; a query parameter belongs to one address), and `WD261` names conflicting modifiers instead of folding one into the value.
+- **`:select`/`:radio`/`:checkbox` outside a `:form` bind to state.** The placement decides the meaning: a form field inside a `:form` (byte-identical output, golden-tested), a bound control outside one, exactly like `:bind` and `:slider`. A bound `:checkbox` is a single boolean. `WD450` refuses an undeclared target naming both readings; `WD451` refuses a bound checkbox with several options. +45 B.
+- **Server error bodies.** `<name>_error` is the response body's own `error`/`message` field when the body is JSON, falling back to `HTTP <status>`, and `<name>_error_body` carries the parsed body for field-level messages. Auto-declared for `:fetch` and round-trip `:form`, cleared on the next success. +63 B.
+- **File upload.** A `:form` containing a file field compiles with `enctype="multipart/form-data"` and posts real `FormData` (the browser writes the boundary); bound controls are appended by state key. `WD452` refuses a file field on `method="get"`. The local `api/` runner already forwarded multipart untouched, so the demo is end to end. +61 B.
+- **Seeds inside a closed `:if` branch hydrate when it opens.** A closed branch lives in a `<template>`, which `querySelectorAll` does not enter, so a `:state`/`:store`/`:theme` declared in one was never hydrated and its `persist` was ignored. Claiming is now per **key** rather than per node, so re-opening does not reset the reader's value, and the claimed seed is that key's `reset` baseline.
+- **Accessibility attributes on `:::` and `:button`.** Exactly `role="…"`, `aria-…="…"`, `title="…"`, double-quoted static values, escaped on emit; `WD650` for anything else and `WD651` for a missing quoted value. This is the one place the no-attribute-syntax rule genuinely blocked a correct page, and it is closed without opening an injection surface: compile-time only, zero runtime bytes, and a static page carrying attributes stays `runtime: false`. Aria values are deliberately not interpolated in this release.
+- **Markdown table rows from a static `@loop`.** Rows are spliced into the table above them, or form a headerless table of their own, instead of falling out as `<p>| Ash | 3 |</p>`. A reactive loop over pipe rows is `WD191` rather than silent junk: a cloned row is a `<div>`, which cannot live in a `<table>`, so the hint names the static source and the container alternative.
+- **A bare directive keyword is an error.** A line that was exactly `:state` (or any of 21 other argument-taking directives) rendered as prose with no warning. It now reaches that directive's own handler and throws that directive's coded error with its own `Use:` hint, so there is one owner per hint and no second copy to drift. `:::`, `:theme` and `:carousel` stay valid bare; `\:name` is the escape for showing one as text.
+- **`:every`/`:effect` inside a reactive `@loop` is `WD315`.** A reactive loop clones its body per row, so each row registered its own timer or watcher and a removed row's kept firing. Neither directive has a per-row meaning to salvage, so the placement is refused, mirroring the `WD202` check `declareState` has always had. Static loop bodies and the `@empty` branch still accept them.
+- **The runtime is a committed minified artifact.** `/__wd/runtime.js` was the comment-stripped readable source (8886 B gzipped with these features, against an 8192 B budget). It is now `src/runtime.min.js`, built by `scripts/build-runtime.mjs` with an exact-pinned esbuild, plus an external sourcemap served at `/__wd/runtime.js.map` with `sourcesContent`, so DevTools still shows the readable source. The artifact is committed because `darkmown build` runs on a consumer's machine from the published tarball where esbuild does not exist; a drift test and a `--check` step in CI fail on a stale one, and `predev` regenerates before `npm run dev`. Measured size **6584 B gzipped** against the unchanged 8192 B budget, and `RUNTIME_SIZE` in the catalog is measured from the file rather than written down.
+- **Runtime correctness, from the same audit.** A render settles (a pass that clones a row or injects a branch marks itself dirty, and a render exiting dirty schedules one more); `:fetch`/`:effect`/`:every` are claimed by `scan()` on every render so a directive inside a branch works when the branch opens, and unregistered when a branch, row, or `@empty` swap removes them, so re-opening never double-fires; row placement is prefix-stable so focus and scroll survive; every `localStorage` access is guarded so blocked storage cannot crash boot; `:form` gained the generation guard `:fetch` had; `:effect`/`:every` clone their action values per fire.
+- **Compiler correctness, from the same audit.** `WD250` refuses `__proto__`/`constructor`/`prototype` as a declaration name at the one choke point every declaring directive uses; the include sandbox re-checks canonical paths so a symlink out of `site/` is `WD601`; `{ toString }` is literal text; every state key emitted into a `data-wd-*` attribute is escaped; `append` is no longer read as `prepend`; a clause keyword inside a quoted `where` operand is text; loop keys cannot collide; a per-row `:if` paints the right branch at build; sort is stable and resolves a `{ state }` key for the initial paint; quoted numeric frontmatter stays a string in typed collections.
+- **Feeds and rebuilds.** `rss_limit:` on the home page caps the feed (digits only; `WD950` otherwise); a sitemap over 50,000 URLs shards behind a `<sitemapindex>`; `<lastmod>` is round-trip validated; a paginated dated listing yields one RSS item. Incremental rebuilds guard `site_url` and ancestor titles as whole-site inputs (dep map v2), so an edit can no longer ship a stale canonical or breadcrumb.
+- **Zero new dependencies at runtime.** esbuild is a devDependency used by the minify step, exactly as it already was for the playground bundle. `.size-snapshot.json` remains the single source for the budget, and the behavior modules (`sortable` 1541 B, `carousel` 1380 B) are unminified and budgeted separately.
+
 ## Agent tool surface: `@zvndev/darkmown/tools` (2026-08-16)
 
 The AI-authoring work so far shipped *description*: a catalog, a cheatsheet, a corpus, a GBNF grammar. All of it teaches a model to write a `.wd` file from scratch. None of it helps a model **edit one it did not write**, which is the operation an AI editor actually performs, and the one that fails: measurement showed the failure is not counting lines, it is recalling a string read once, and it gets worse as a file grows.
@@ -49,7 +70,7 @@ The 1.3.0 cycle shipped the crawler *files* (sitemap, rss, robots). This closes
 
 - **Markdown-first authoring:** `.md` is strict CommonMark rendered by a real parser (markdown-it); `.wd` is the same Markdown plus first-party directives. Renaming the file is the upgrade path — extensions genuinely gate functionality.
 - **Content tree over components:** routing, includes, and repeated fragments are file/document based instead of React-style components.
-- **Tiered output:** static routes emit HTML/CSS and no Darkmown runtime; reactive routes opt into `/__wd/runtime.js` (~7.7 KB gzipped, CI-enforced below the 8 KB target).
+- **Tiered output:** static routes emit HTML/CSS and no Darkmown runtime; reactive routes opt into `/__wd/runtime.js`, a minified build of the readable source with a sourcemap beside it (~6.6 KB gzipped, CI-enforced below the 8 KB target).
 - **No virtual DOM:** state changes patch direct DOM bindings, conditional regions, and keyed loop regions.
 - **Keyed list patching:** reactive loops reconcile by item key (`id`/`key`/value) instead of re-rendering the region.
 - **Sections with scoped state:** `::: section #id .class` containers scope `:state`; bindings and actions resolve through the nearest scope chain.
@@ -233,7 +254,7 @@ The 1.3.0 cycle closes table-stakes gaps a new user expects out of the box. Trac
 
 - **Serverless `api/` model:** backend endpoints are plain-JS Web-standard handlers — `export default (request, context) => Response` — in a top-level `api/` directory (`api/echo.js` → `/api/echo`; `api/users/[id].js` → `/api/users/:id` with `context.params.id`). Darkmown owns no server; it *adapts* to the host. The build stays 100% static. On Vercel the `api/` functions run natively (Edge); `darkmown deploy cloudflare` (or `build --target cloudflare`) emits `dist/_worker.js` that routes `/api/*` to the same functions and serves everything else from `env.ASSETS`. `darkmown dev` runs a local runner so `/api/*` behaves identically before deploy. No `.wd` backend DSL — minimal new learning, zero lock-in. `form-action 'self'` was added to both CSP variants (and `vercel.json`) so a native `:form action="/api/…"` POST is allowed.
 - **Templates + deploy CLI:** `darkmown init --template <starter|blog|store|dashboard|landing>` scaffolds from in-package templates (each a real, deployable site; `store`/`dashboard` ship an example `api/` function). `darkmown deploy <vercel|cloudflare> [--prod]` writes platform config, runs a target-aware build, and wraps the platform CLI (`npx vercel` / `npx wrangler pages deploy`), printing the deploy URL; an unauthenticated CLI surfaces a login hint.
-- **Interaction behaviors (pay-for-what-you-use):** `:slider name = v min max step` is compile-time only — a range input bound through `:bind` (range values coerce to Number), ships **no** JS module. `:sortable` (a `@loop` clause) and `:carousel` compile to tiny `/__wd/behaviors/<name>.js` modules injected **only** on pages that use them, built on the public `window.wd` API. They are budgeted **separately** from the 8 KB core runtime (each in `.size-snapshot.json`), so core stays untaxed. `:sortable` requires a plain reactive `:state`/`:store` loop (no where/sort/reverse/offset/limit) and reorders via Pointer Events + keyboard; `:carousel` uses native CSS scroll-snap plus prev/next/dots/autoplay/mouse-drag.
+- **Interaction behaviors (pay-for-what-you-use):** `:slider name = v min max step` is compile-time only — a range input bound through `:bind` (range values coerce to Number), ships **no** JS module. `sortable` (a bare `@loop` clause, written without a leading colon) and `:carousel` compile to tiny `/__wd/behaviors/<name>.js` modules injected **only** on pages that use them, built on the public `window.wd` API. They are budgeted **separately** from the 8 KB core runtime (each in `.size-snapshot.json`), so core stays untaxed. `sortable` requires a plain reactive `:state`/`:store` loop (no where/sort/reverse/offset/limit) and reorders via Pointer Events + keyboard; `:carousel` uses native CSS scroll-snap plus prev/next/dots/autoplay/mouse-drag.
 
 ## Browser playground + fs-free compile — `compileFromMemory` (2026-07-11)
 
@@ -250,7 +271,7 @@ The 1.3.0 cycle closes table-stakes gaps a new user expects out of the box. Trac
 
 ## 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`).
+The compiler recognizes one directive, `:try`, that exists **only to power the demo site** (darkmown.com). It is **not** part of the supported public directive set, is not documented for authors, and may change or be removed without notice. Do not build pages that depend on it. (`:note` and `:sprint` were two more of these; both were removed in 2.7.0, and those lines now render as text with an unknown-directive warning.) 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`/`:textarea`/`:select`/`:checkbox`/`:radio`/`: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`).
 
 ## Still missing from the full vision
 
@@ -262,4 +283,4 @@ The compiler recognizes three directives — `:note`, `:try`, and `:sprint` —
 
 Darkmown is faithful to the core thesis: Markdown remains the authoring center, static pages ship zero framework JavaScript, and reactive behavior compiles into tiny direct-DOM islands only where declared. The extension is the feature gate, the loop is one concept with progressive disclosure, and state scopes to document structure.
 
-As of **v1.0.0** the public npm package is published as `@zvndev/darkmown`, the project is MIT licensed, and the directive surface is stable. The 1.0 release closes the audit-flagged display/time/theme/sort/media/escape-hatch gaps; the remaining items above are explicitly scoped as post-launch product/distribution work rather than missing core claims. **2.0.0** made one breaking change to that stable surface — raw HTML in markdown is now escaped by default (`html: false`), with `html: true` the per-page opt-in — a security default flip, not a directive change (see the 2.0.0 entry above and CHANGELOG).
+As of **v2.7.0** the public npm package is published as `@zvndev/darkmown`, the project is MIT licensed, and the directive surface is stable at the 25 directives `darkmown catalog` prints. Three releases have moved that surface since 1.0, and each is recorded above: **2.0.0** made the one breaking change, escaping raw HTML in markdown by default (`html: false`), with `html: true` as the per-page opt-in, a security default flip rather than a directive change. **2.1.0** replaced the runtime's `new Function` with a closed interpreter over a validated expression AST, so reactive pages now run under the same strict, `'unsafe-eval'`-free CSP as static ones. **2.5.0** added the agent tool surface (`@zvndev/darkmown/tools`). The remaining items above stay scoped as post-launch product and distribution work rather than missing core claims.

package/grammar/wd-directives.gbnf

@@ -1,12 +1,13 @@
 # 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
+root ::= directive | closer | 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
+closer ::= "@endloop" | "@empty" | ":endif" | ":endform" | ":endcarousel" | ":::" | ":else if" sp condition ( sp joiner sp condition )* | ":else if" sp path | ":else"
 
 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-button ::= ":button" sp dqstring ( sp a11y-attr )* sp "->" sp action-chain
 dir-container ::= ":::" restofline
 
 dir-include ::= "@include" restofline
@@ -32,20 +33,27 @@ 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"
+loop-clause ::= where-clause | "sort by" sp sort-key ( sp sort-dir )? | "reverse" | "offset" sp count | "limit" sp count | "paginate" sp number | "sortable"
+sort-key ::= path | statebinding
+sort-dir ::= "asc" | "desc" | statebinding
+count ::= number | ident
+statebinding ::= "{" wsopt ident wsopt "}"
 where-clause ::= "where" sp condition ( sp joiner sp condition )*
-condition ::= operand sp op sp operand
+condition ::= ( "not" sp )? 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"
+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 value | 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"
 
+a11y-attr ::= a11y-name "=" dqstring
+a11y-name ::= "role" | "title" | "aria-" [a-z] [a-z0-9-]*
+
 operand ::= path | dqstring | number
 value ::= dqstring | number | path
 ident ::= [a-zA-Z_$] [a-zA-Z0-9_$]*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/darkmown",
-  "version": "2.6.1-next.12.ge562f5d",
+  "version": "2.7.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -30,7 +30,9 @@
   "scripts": {
     "build": "node src/cli.js build",
     "build:playground": "node scripts/build-playground.mjs",
+    "build:runtime": "node scripts/build-runtime.mjs",
     "runtime:size": "node scripts/size-check.mjs",
+    "predev": "node scripts/build-runtime.mjs",
     "dev": "node src/cli.js dev",
     "test": "node --test tests/*.test.js",
     "test:cov": "node scripts/test-coverage-gate.mjs 100",
@@ -45,7 +47,7 @@
     "format:check": "biome format .",
     "size:check": "node scripts/size-check.mjs",
     "prepare": "husky || true",
-    "prepublish:check": "npm run typecheck && npm run test:cov && npm run build && npm run runtime:size && npm audit --audit-level=high && npm run smoke",
+    "prepublish:check": "npm run typecheck && node scripts/build-runtime.mjs --check && npm run test:cov && npm run build && npm run runtime:size && npm audit --audit-level=high && npm run smoke",
     "prepublishOnly": "npm run prepublish:check",
     "og": "node scripts/og-image.mjs",
     "bench:build": "node scripts/bench-build.mjs"
@@ -55,6 +57,8 @@
   },
   "files": [
     "src",
+    "src/runtime.min.js",
+    "src/runtime.min.js.map",
     "types",
     "grammar",
     "site",
@@ -79,7 +83,7 @@
     "@biomejs/biome": "^2.5.7",
     "@playwright/test": "^1.61.1",
     "@types/node": "^26.1.1",
-    "esbuild": "^0.28.2",
+    "esbuild": "0.28.2",
     "husky": "^9.1.7",
     "lint-staged": "^17.0.0",
     "typescript": "^6.0.3"

package/site/_/base.skin

@@ -463,7 +463,7 @@ label
   border 1px solid $line
   color $ink-soft
 
-/* ── Callout (the demo :note directive renders <aside class="note">) ─ */
+/* ── Callout ───────────────────────────────────────────────────── */
 
 .note, .callout
   margin 1.6rem 0

package/site/_/footer.wd

@@ -6,7 +6,7 @@ html: true
   <div class="foot-inner">
     <div>
       <strong>Darkmown</strong>. Markdown that runs.
-      <div class="small">Zero JS on static pages · one ~7.7&nbsp;KB runtime when reactive.</div>
+      <div class="small">Zero JS on static pages · one ~6.6&nbsp;KB runtime when reactive.</div>
     </div>
     <nav class="foot-links">
       <a href="/docs/">Docs</a>

package/site/pages/api-errors/index.wd

@@ -0,0 +1,81 @@
+---
+html: true
+title: Server error bodies: what the API actually said
+description: A failed :fetch or :form now surfaces the server's own error message, and the whole parsed JSON body lands in a second state key so a page can render field-level errors.
+---
+
+@include /nav.wd
+@include /base.wd
+
+<main>
+
+<section class="intro">
+  <span class="eyebrow">Darkmown 2.7</span>
+
+# What the API actually said
+
+A real API explains why it refused. `<name>_error` used to read `Error: HTTP 422` no matter what came back. It is now the body's own `error` or `message` string, and the whole parsed body lands in `<name>_error_body`, so a page can render per-field errors without a line of its own JavaScript.
+
+</section>
+
+<section>
+
+## A refusal, rendered
+
+`/api/echo` only accepts POST, so a plain `:fetch` gets a `405` whose JSON body carries an `error` string.
+
+:fetch probe from "/api/echo/"
+
+:if probe_loading
+Asking the endpoint…
+:endif
+
+:if probe_error
+The endpoint said: **{ probe_error }**
+:endif
+
+:if probe_error_body
+And the whole body is available too: `ok` came back as { probe_error_body.ok }.
+:endif
+
+</section>
+
+<section>
+
+## Field-level errors
+
+`/api/upload` answers a fileless POST with a `422` whose body carries both a sentence and a per-field map:
+
+```json
+{ "error": "Pick a file first.", "fields": { "photo": "No file was attached." } }
+```
+
+A page renders each half where it belongs:
+
+```wd-fragment
+:if signup_error
+{ signup_error }
+:endif
+
+{ signup_error_body.fields.email }
+```
+
+The [upload demo](/upload/) has this wired up end to end.
+
+</section>
+
+<section>
+
+## The rules
+
+- `<name>_error` prefers the body's `error` field, then its `message` field, and falls back to `HTTP <status>` when the body has neither or is not JSON at all.
+- `<name>_error_body` is the parsed JSON body, or `null` when the response was not JSON.
+- Both keys are auto-declared by `:fetch` and by a round-trip `:form`, and both are cleared on the next success.
+
+<a class="btn primary" href="/docs/#what-the-server-said">Read the docs on fetching data</a>
+
+</section>
+
+</main>
+
+@include /footer.wd

package/site/pages/app.wd

@@ -20,7 +20,7 @@ This whole section is plain Markdown. The list below is unrolled **at build time
 - **{ feature.title }**: { feature.body }
 @endloop
 
-<aside class="boundary">If you deleted everything below this line, this page would ship <strong>zero</strong> bytes of JavaScript. Everything above is static HTML. Below is where the one ~7.7&nbsp;KB gzipped runtime loads (CI-enforced under 8 KB), and only because the document asks for it.</aside>
+<aside class="boundary">If you deleted everything below this line, this page would ship <strong>zero</strong> bytes of JavaScript. Everything above is static HTML. Below is where the one ~6.6&nbsp;KB gzipped runtime loads (CI-enforced under 8 KB), and only because the document asks for it.</aside>
 
 ## Fetched data, looped, with nested conditions
 

package/site/pages/attr-binding/index.wd

@@ -0,0 +1,84 @@
+---
+html: true
+title: Reactive links: a destination that follows state
+description: A markdown link destination that reads :state or a loop row now binds, so the href and src keep up with the page instead of being painted once at build time. Dangerous schemes are refused at paint time, in the browser.
+---
+
+@include /nav.wd
+@include /base.wd
+
+<main>
+
+<section class="intro">
+  <span class="eyebrow">Darkmown 2.7</span>
+
+# Reactive links
+
+A `{ … }` inside a link or image destination used to be painted once at build time and then went stale. Now it binds: the compiler emits the destination as a small template, and the runtime rebuilds the whole value on every render.
+
+</section>
+
+<section>
+
+## The destination follows the state
+
+:state region = "eu"
+
+Pick a region and watch the link underneath it change. The link is written as ordinary markdown: `[Open the EU docs](/docs/{ region }/)`.
+
+:button "EU" -> region = "eu"
+:button "US" -> region = "us"
+:button "APAC" -> region = "apac"
+
+Current region: **{ region }**
+
+[Open the docs for this region](/docs/{ region }/)
+
+The `href` is rebuilt from the literal parts (`/docs/` and `/`) plus the live value, so a value in the middle of a path works exactly like one that fills the whole destination.
+
+</section>
+
+<section>
+
+## One template, every row
+
+:state products = [
+  { "slug": "aurora", "name": "Aurora Lamp" },
+  { "slug": "briza", "name": "Briza Fan" },
+  { "slug": "cove", "name": "Cove Shelf" }
+]
+
+A reactive `@loop` shares ONE row template, so a per-row destination has no single build-time value: it paints empty and the runtime fills each row from its own item.
+
+@loop products into p
+- [{ p.name }](/products/{ p.slug }/)
+@endloop
+
+:button "Add a product" -> products append { "slug": "dune", "name": "Dune Rug" }
+
+</section>
+
+<section>
+
+## A bound URL is checked where it lands
+
+The compiler vets URLs an author writes. A bound `href` carries a value that only exists at runtime, so the scheme is checked again in the browser: `javascript:`, `data:` and `vbscript:` are refused and the attribute is left empty, with control characters stripped first so `java&#9;script:` cannot sneak through.
+
+:state danger = "/safe/place/"
+
+:button "Set a safe URL" -> danger = "/safe/place/"
+:button "Try a javascript: URL" -> danger = "javascript:alert(1)"
+
+The value in state: `{ danger }`
+
+[This link's href]({ danger })
+
+Click the second button and inspect the anchor: the whole attribute is emptied rather than half-applied, because the guard runs on the value the runtime assembled, not on the literal parts the author wrote.
+
+<a class="btn primary" href="/docs/#destinations-that-bind">Read the docs on destinations that bind</a>
+
+</section>
+
+</main>
+
+@include /footer.wd