@zvndev/darkmown 2.6.1-next.11.g82bb8d7 → 2.7.0

package/README.md

@@ -7,19 +7,9 @@
 
 **[darkmown.com](https://darkmown.com)** · Markdown that runs.
 
-Darkmown is a Markdown-native web framework. Two formats, one rule: `.md` stays plain CommonMark forever, and renaming a file to `.wd` ("whateverdown") is what unlocks directives — includes, loops, state, conditionals, and sections. Static pages ship **zero** framework JavaScript; reactive pages share one runtime around ~7.7 KB gzipped, CI-enforced under 8 KB.
+Darkmown is a Markdown-native web framework. Two formats, one rule: `.md` stays plain CommonMark forever, and renaming a file to `.wd` ("whateverdown") is what unlocks directives — includes, loops, state, conditionals, and sections. Static pages ship **zero** framework JavaScript; reactive pages share one runtime around ~6.6 KB gzipped, CI-enforced under 8 KB.
 
-## Showcase
-
-Five complete apps, each a readable `.wd` file — see them at **[darkmown.com/showcase](https://darkmown.com/showcase/)**:
-
-- **[Folio](https://darkmown.com/folio/)** — a boutique storefront whose cart persists across pages, reloads, and browser tabs (`:store`), with live search and a checkout form.
-- **[Pulse](https://darkmown.com/pulse/)** — a service dashboard driven by `:fetch`: loading / error / empty states, live refresh (`:every`), and status badges, with no hand-written JavaScript.
-- **[Forge](https://darkmown.com/forge/)** — a plan configurator where `:computed` recomputes the price as you toggle features and seats, with conditional upsell hints.
-- **[Compass](https://darkmown.com/compass/)** — a product-finder quiz: a branching state machine expressed entirely as `:if` steps over scored answers.
-- **[Ledger](https://darkmown.com/ledger/)** — a spreadsheet-grade expense table: clickable-header reactive sort, a live filter, running totals via `sum`/`avg`/`max`, `| money`/`| date` format pipes, and a `:theme` toggle.
-
-Plus focused feature demos: a draggable, keyboard-navigable **[Swiper](https://darkmown.com/carousel/)** (the `wd.subscribe` escape hatch) and a zero-JS **[Media](https://darkmown.com/media/)** page (`:video` / `:audio` / `:embed`).
+**Who it is for.** Content sites that need a few interactive islands: documentation, blogs, marketing sites, changelogs, small storefronts and dashboards. You get real Markdown files, real static HTML, and a handful of directives when a page needs to react. It is not a general-purpose application framework, and the [Limits](#limits) section says exactly where the line is before you build against it.
 
 ## Quick start
 
@@ -47,6 +37,27 @@ Prefer to see it run before you install? The [browser playground](https://darkmo
 compiles `.wd`/`.md` live in your browser — the same compiler the CLI ships — with
 no install and no build step.
 
+**On this page**
+
+- [Quick start](#quick-start) · [Showcase](#showcase) · [Working from this repo](#working-from-this-repo) · [Commands](#commands)
+- **Authoring:** [Authoring model](#authoring-model) · [Directive lines](#directive-lines) · [Interpolation](#interpolation) · [Frontmatter](#frontmatter) · [Static assets](#static-assets) · [SEO & feeds](#seo--feeds-sitemap-rss-robots) · [Loops](#loops) · [Content collections](#content-collections) · [Sections](#sections)
+- **Reactivity:** [Reactive directives](#reactive-directives) · [Fetching data](#fetching-data) · [Global state](#global-state--store) · [URL as state](#url-as-state-from-url) · [Forms and persistence](#forms-and-persistence) · [Backends & deploy](#backends--deploy) · [Interactions](#interactions--slider-sortable-carousel)
+- **Presentation:** [Inline attributes](#inline-attributes) · [Media](#media--video-audio-embed) · [Syntax highlighting](#syntax-highlighting) · [Dark mode](#dark-mode--tokens-dark) · [Scoped styles](#scoped-styles--scoped)
+- **Extending:** [The escape hatch](#the-escape-hatch) · [Programmatic compile](#programmatic-compile--compilefrommemory) · [Compile error codes](#compile-error-codes) · [AI authoring](#ai-authoring) · [Editor support](#editor-support)
+- **Before you commit:** [Accessibility](#accessibility) · [Security](#security) · [**Limits**](#limits) · [Spec status](#spec-status)
+
+## Showcase
+
+Five complete apps, each a readable `.wd` file — see them at **[darkmown.com/showcase](https://darkmown.com/showcase/)**:
+
+- **[Folio](https://darkmown.com/folio/)** — a boutique storefront whose cart persists across pages, reloads, and browser tabs (`:store`), with live search and a checkout form.
+- **[Pulse](https://darkmown.com/pulse/)** — a service dashboard driven by `:fetch`: loading / error / empty states, live refresh (`:every`), and status badges, with no hand-written JavaScript.
+- **[Forge](https://darkmown.com/forge/)** — a plan configurator where `:computed` recomputes the price as you toggle features and seats, with conditional upsell hints.
+- **[Compass](https://darkmown.com/compass/)** — a product-finder quiz: a branching state machine expressed entirely as `:if` steps over scored answers.
+- **[Ledger](https://darkmown.com/ledger/)** — a spreadsheet-grade expense table: clickable-header reactive sort, a live filter, running totals via `sum`/`avg`/`max`, `| money`/`| date` format pipes, and a `:theme` toggle.
+
+Plus focused feature demos: a draggable, keyboard-navigable **[Swiper](https://darkmown.com/carousel/)** (the `wd.subscribe` escape hatch) and a zero-JS **[Media](https://darkmown.com/media/)** page (`:video` / `:audio` / `:embed`).
+
 ## Working from this repo
 
 ```sh
@@ -63,7 +74,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 catalog [--llms|--llms-full]` prints the machine-readable directive catalog (JSON), a compact cheatsheet with `--llms`, or the complete reference including every error code with `--llms-full`. See [AI authoring](#ai-authoring).
 - `darkmown version` prints the installed package version.
 - `darkmown help` prints CLI usage.
 
@@ -74,9 +85,18 @@ npm run dev     # live demo site — the same site that runs darkmown.com
 - Files or folders starting with `.`, `-`, or `_` are hidden from routing.
 - `site/_` is the include shelf for `@include /name.wd`.
 - Matching `page.skin` and `page.js` colocate styling and behavior by basename.
-- Static pages ship zero Darkmown runtime. Reactive pages share `/__wd/runtime.js` (currently ~7.7 KB gzipped, CI-enforced under 8 KB).
+- Static pages ship zero Darkmown runtime. Reactive pages share `/__wd/runtime.js`, a minified build of the readable `src/runtime.js` (currently ~6.6 KB gzipped, CI-enforced under 8 KB). An external sourcemap ships beside it at `/__wd/runtime.js.map` with the original source inlined, so DevTools shows real names and real comments. Development serves the same bytes as production.
 - Shelf `.json` files are published at `/__wd/data/` so `:fetch` works on any static host.
 
+## Directive lines
+
+A directive is a whole line, written flush against the left margin. Four rules cover everything the compiler will and will not accept there.
+
+- **One directive per line, unindented.** An indented `:state` (inside a list item, say) is prose, and a directive inside a fenced code block is code.
+- **A bare keyword is an error.** A line that is exactly `:state`, `:button`, `@loop`, or any other directive that needs arguments used to render as literal text with no warning at all. It now reaches that directive's own handler and fails with that directive's coded message and `Use:` hint, so `:state` alone gives `[WD201]` and `:button` alone gives `[WD301]`. Three keywords stay valid bare, because they mean something bare: `:::` opens or closes a container, `:theme` declares the theme store, and `:carousel` opens a carousel with no autoplay.
+- **To show a directive name as text, escape it.** `\:fetch` renders the literal text `:fetch`. That is the ordinary CommonMark backslash escape, so it works anywhere Markdown does, including inside a container.
+- **There is no comment syntax.** A trailing `#` or arrow note on a directive line is parsed as part of the value, not as a comment. `html: true  ← required` seeds the *string* `true  ← required`, which compiles clean while doing the opposite of what it looks like. Put explanations in the prose around the line.
+
 ## Interpolation
 
 One syntax everywhere: `{ name }` or `{ name.path }`.
@@ -85,7 +105,37 @@ One syntax everywhere: `{ name }` or `{ name.path }`.
 - Declared `:state` becomes a live binding.
 - The page's own frontmatter is in scope as `meta` — `{ meta.title }` prints a field.
 - Anything else stays literal text — braces in prose never break a page or pull in the runtime.
-- Build-time values also resolve **inside a link or image destination** — `[{ item.label }]({ item.url })` or `![{ p.alt }]({ p.src })` — so an `@loop` can drive an `href`/`src` and the page stays static. (Reactive `:state` cannot live in a destination.)
+- Values resolve **inside a link or image destination** too (`[{ item.label }]({ item.url })`, `![{ p.alt }]({ p.src })`), so an `@loop` can drive an `href`/`src` and the page stays static. Every brace in the destination resolves, not just one filling the whole value: `[Docs](/docs/{ region }/)` works. A reactive value there becomes a live binding; see [Destinations that bind](#destinations-that-bind) below.
+- Values resolve in **raw HTML** too (attributes and html blocks, HTML-escaped) on an `html: true` page. Those are painted once at build time, not bound. Fenced code blocks and inline code spans are never rewritten, so a page can still show `` `[x](/p/{ p.slug }/)` `` as syntax.
+
+### Destinations that bind
+
+A destination that reads `:state`, `:store`, `:computed`, a reactive loop row, or a loop meta variable is a **live binding**: the compiler emits the destination as a small template and the runtime rebuilds the value on every render.
+
+```wd
+:state region = "eu"
+
+:button "EU" -> region = "eu"
+:button "US" -> region = "us"
+
+[Open the docs for this region](/docs/{ region }/)
+```
+
+Clicking a button rewrites the `href`. The build-time paint is still the seed (`/docs/eu/`), so the link works before the runtime loads and a crawler sees a real URL. Per-row destinations work the same way inside a reactive `@loop`:
+
+```wd
+:state products = [{"slug": "aurora", "name": "Aurora Lamp"}]
+
+@loop products into p
+- [{ p.name }](/products/{ p.slug }/)
+@endloop
+```
+
+Three rules worth knowing:
+
+- **Values in URL position are percent-encoded.** A `)`, a space, or an angle bracket coming from your data cannot end the link and hand the remainder back to the Markdown parser.
+- **Dangerous schemes are refused twice.** The compiler vets what you wrote; the runtime re-checks what it assembled (control characters stripped first) and applies an **empty** attribute rather than a half-applied one if the value resolves to `javascript:`, `data:`, or `vbscript:`.
+- **Raw HTML attributes do not bind.** `<a href="{ url }">` is painted once with a build warning that names the position that does bind. Move the value into a Markdown destination, or drive the attribute from a colocated `.js` with `wd.subscribe`.
 
 ### Format pipes — `{ value | name:arg }`
 
@@ -126,7 +176,7 @@ tags: [sales, revenue, "q1, q2"]
 
 Three keys also drive the document `<head>`: `title` sets `<title>`, `description` adds the meta description plus Open Graph / Twitter tags, and `image` (an absolute URL) sets the social-share preview (`og:image` / `twitter:image` and a `summary_large_image` card). `lang:` sets the document language on `<html lang>` (`lang: fr`, `lang: pt-BR`, …) — it defaults to `en`.
 
-A few reserved keys drive **drafts and feeds** (see [SEO & feeds](#seo--feeds-sitemap-rss-robots) below): `draft: true` excludes a page from production builds; `site_url` on the home page turns on `sitemap.xml` + `rss.xml`; `date:` marks a page as a blog post (it lands in `rss.xml` and sets the page's `<lastmod>`); `excerpt:` is the RSS summary. The same frontmatter is queryable when the page is an entry in a [content collection](#content-collections) — `{ post.date }`, `{ post.excerpt }`, `{ post.tags }`, and any custom key resolve in an `@loop` over the folder.
+A few reserved keys drive **drafts and feeds** (see [SEO & feeds](#seo--feeds-sitemap-rss-robots) below): `draft: true` excludes a page from production builds; `site_url` on the home page turns on `sitemap.xml` + `rss.xml`; `rss_limit:` on the home page caps how many posts the feed carries; `date:` marks a page as a blog post (it lands in `rss.xml` and sets the page's `<lastmod>`); `excerpt:` is the RSS summary. The same frontmatter is queryable when the page is an entry in a [content collection](#content-collections): `{ post.date }`, `{ post.excerpt }`, `{ post.tags }`, and any custom key resolve in an `@loop` over the folder.
 
 `transitions: true` opts a page into **instant, flash-free navigation** — zero JavaScript, all declarative. It emits a directional fade+slide **view transition** for the page swap (old lifts up and out, new rises up and in — replacing the default cross-fade, which left both pages ghosted at ~50 % opacity mid-navigation), plus a **`<script type="speculationrules">` prerender** hint that renders the next same-origin page on hover/pointerdown so the click activates an already-painted page (no white render-gap flash). It honors `prefers-reduced-motion`. Only same-origin pages that both opt in transition; browsers without support — or with page-preloading disabled — navigate normally. Off by default; opt out with `transitions: false`. Mark a link `{.no-prefetch}` to exclude it from prerendering. (Chrome disables prerendering while DevTools is open, so test the built site with DevTools closed.)
 
@@ -166,6 +216,20 @@ site_url: https://example.com
 - **`robots.txt`** is *always* emitted; the `Sitemap:` line is added only when `site_url` is set. See [AI crawlers](#ai-crawlers) below for the explicit per-crawler groups.
 - **`sitemap.xml`** lists every built page (reactive pages included — they're indexable HTML). Each `<lastmod>` is the page's frontmatter `date:` if set, else its git last-commit date, else the file's mtime. No `<priority>`/`<changefreq>`.
 - **`rss.xml`** syndicates your **posts** — any page with a `date:` in its frontmatter. Newest first, capped at the 20 most recent. Each item's `<description>` is the page's `excerpt:`, else its `description:`, else (for a plain `.md` post) its first paragraph. Every page links the feed with `<link rel="alternate" type="application/rss+xml">` so readers can autodiscover it.
+- **`rss_limit:`** on the home page changes that cap: `rss_limit: 50` carries the 50 newest posts. It takes digits only (a positive whole number of items), so `1e3`, `0x10`, and `7.0` are refused with `[WD950]` rather than silently coerced. Leave it out for the default of 20.
+
+A post is just a page that carries a `date:`. Add `excerpt:` to control the summary the feed shows for it:
+
+```md
+---
+title: Hello, Darkmown
+date: 2026-01-15
+excerpt: Why I rewrote my blog as plain Markdown files.
+---
+
+# Hello, Darkmown
+…
+```
 
 ### Canonical URLs
 
@@ -234,17 +298,6 @@ ai_crawlers: deny
 
 `allow` is the default (and matches what `User-agent: *` already grants). A value that is neither `allow` nor `deny` **fails the build** rather than defaulting: the intent behind a typo like `ai_crawlers: block` is almost always to opt *out*, and silently allowing would be the one unrecoverable outcome.
 
-```md
----
-title: Hello, Darkmown
-date: 2026-01-15
-excerpt: Why I rewrote my blog as plain Markdown files.
----
-
-# Hello, Darkmown
-…
-```
-
 Without `site_url`, `robots.txt` still emits and the build prints a one-line hint telling you which field to set; it never crashes.
 
 ### Drafts
@@ -333,6 +386,7 @@ Shape a loop without writing JavaScript. Clauses come in a fixed order after `in
 - `offset <N>` / `limit <N>` — `<N>` is a non-negative integer **or** a `:state`/`:store` key, which makes pagination reactive:
 
 ```wd
+:state products = [{"name": "Aurora Lamp"}, {"name": "Briza Fan"}]
 :state pageSize = 10
 
 @loop products into product limit pageSize
@@ -353,6 +407,8 @@ Each row exposes five meta variables, relative to the rendered slice:
 They work in interpolation and in `:if`:
 
 ```wd
+:state products = [{"name": "Aurora Lamp"}, {"name": "Briza Fan"}]
+
 @loop products into product
 :if $first
 **Top pick:**
@@ -366,6 +422,8 @@ They work in interpolation and in `:if`:
 Add an `@empty` branch to show a fallback when the loop renders no rows (after `where`, `limit`, and the rest):
 
 ```wd
+:state todos = []
+
 @loop todos into todo
 - { todo.title }
 @empty
@@ -377,6 +435,25 @@ A **missing** in-scope source is an empty list, not an error: `@loop meta.tags i
 
 > **Note:** All of these clauses stay build-time when the source and every clause argument are static — a sorted, limited loop over a JSON file ships **zero JavaScript**. The loop becomes reactive only when the source is `:state`/`:store`/`:fetch` data, or a clause reads reactive state (like `limit pageSize`).
 
+### Table rows from a loop
+
+A **static** loop whose body is bare `| … |` cells fills a Markdown table. Write the header in prose and let the loop supply the rows:
+
+```wd
+| Item | Price |
+| --- | --- |
+@loop /products.json into row
+| **{ row.name }** | { row.price } |
+@endloop
+```
+
+That renders one `<table>` with one `<tr>` per row, and each cell holds ordinary inline Markdown, links included (`| [buy](/buy/{ row.id }/) |`). A format pipe works too, but its `|` has to be escaped inside a table cell: `{ row.price \| money }`. Put the whole table inside the loop instead and you get a headerless `<table>` of the same shape; give the loop body its own `| --- |` separator and each row is a complete table, collapsed into one when the headers match.
+
+Two limits to know before you build on it:
+
+- A pipe row written in prose **after** `@endloop` (a totals row) does not join the table. It stays a paragraph.
+- A **reactive** loop over pipe rows is `[WD191]`, not silent breakage. A reactive row is cloned into a `<div>`, which is not a legal child of `<table>`, so there is no correct HTML to emit. Loop a static source for a Markdown table, or build reactive rows out of containers (`::: trow` / `::: td`) and style them with `display: table-row` / `table-cell`.
+
 ### Editable lists — per-row actions
 
 A `:button` inside a reactive `@loop` can act on its own row. `cart += product` carries the current row into another list; `cart remove line` drops the current row from the looped list:
@@ -407,7 +484,7 @@ That is a full add-to-cart / remove-line flow — and a to-do list with delete
 
 ### Nested reactive loops
 
-*New in 0.19.0.* A reactive `@loop` may contain an inner reactive `@loop` over one of the outer row's fields — one level of nesting. The inner source is a dotted path rooted at the outer item (`order.lines`), so each row renders its own list and both stay live as state changes:
+A reactive `@loop` may contain an inner reactive `@loop` over one of the outer row's fields — one level of nesting. The inner source is a dotted path rooted at the outer item (`order.lines`), so each row renders its own list and both stay live as state changes:
 
 ```wd
 :state orders = [
@@ -518,11 +595,39 @@ State declared inside a section is scoped to it — two sections can both own a
 
 A container named `nav` or `main` emits the real landmark element (`<nav class="nav">`, `<main class="main">`) instead of a `<div>`, so scaffolded pages keep proper landmarks — a skip link skips a `::: nav`, and `::: main` becomes the page's `<main id="main">`. Any other name stays a `<div>` with that class.
 
+### Accessibility attributes
+
+Darkmown has no general attribute syntax on purpose: styling is `.class` tokens and behavior is `->` actions, which is what keeps output predictable and static pages script-free. That left one thing genuinely unreachable, the ARIA vocabulary a screen reader needs. Exactly three attribute names now compile, on exactly two directives (`:::` and `:button`), always with a **double-quoted static value**:
+
+```wd
+:state open = false
+
+::: card .note role="region" aria-label="Release notes" title="What changed"
+Notes go here.
+:::
+
+::: nav .menu role="navigation" aria-label="Main"
+[Docs](/docs/)
+:::
+
+:button "Menu" aria-expanded="false" aria-controls="m" -> open toggle
+```
+
+- On a container, attributes interleave freely with `.class` and `#id` tokens and coexist with `.class when <predicate>`.
+- On a `:button`, they sit between the label and the `->`. An arrow inside a quoted value is safe: attributes are peeled before the action arrow is looked for.
+- Values are HTML-escaped on emit, so nothing you write can close the attribute or open another.
+- Anything outside the whitelist is `[WD650]`: `onclick=`, `style=`, `href=`, `class=`, `id=`, `data-*` are all refused, and so is `ARIA-LABEL` (the match is case-sensitive) or a single-quoted value. A name on the whitelist with no double-quoted value is `[WD651]`.
+- **Values are static text.** There is no `{ state }` interpolation inside an aria value in this release: `aria-label="{ who }"` emits the literal braces. For a live accessible name, write the element in raw HTML on an `html: true` page, or set it from a colocated `.js`.
+
+This is compile-time only. It costs zero runtime bytes, and a static page carrying attributes stays `runtime: false`.
+
 ### Reactive classes — `.class when <predicate>`
 
 A container class can be toggled by a predicate. Static `.class` tokens are unchanged; add `when <predicate>` to make one reactive:
 
 ```wd
+:state products = [{"id": 1, "name": "Aurora", "price": 49, "featured": true}]
+
 @loop products into p
 ::: card .product .on-sale when p.price < 50 .featured when p.featured
 **{ p.name }** — ${ p.price }
@@ -552,7 +657,7 @@ Count is still zero.
 
 A condition reads the same predicate grammar as `.class when`: a bare path (truthy), or the comparisons `==` `!=` `<` `<=` `>` `>=` `contains`, joined with `and`, `or`, and `not`. (`@loop … where` is the comparison-only subset — operators with `and`/`or`.) Chain with `:else if` (any number; an optional bare `:else` must be the last branch):
 
-```wd
+```wd-fragment
 :if plan == "pro" or seats >= 5
 Pro plan
 :else if trialDays > 0 and not expired
@@ -564,6 +669,8 @@ Free plan
 
 A whole chain compiles to nested conditional regions, so it stays reactive (or folds at build time when every value is static) exactly like a single `:if`.
 
+**Declarations inside a closed branch are live.** A `:state`, `:store`, or `:theme` written inside an `:if` branch that starts closed is hydrated the moment the branch opens, `persist` included. The seed is claimed once per **key**, not per node, so closing and re-opening the branch does not reset the value the reader set, and the claimed seed is that key's `reset` baseline. (A `:computed` inside a closed branch stays dormant until the branch opens, by design.)
+
 Directive actions are intentionally narrow and compile-time checked. Arbitrary JavaScript belongs in colocated `.js` files.
 
 ### Button actions
@@ -599,15 +706,17 @@ Values are literals: a `"string"`, number, `true`/`false`/`null`, or inline JSON
 
 **One button can run several actions** with `;`. They apply in order, then the page renders once:
 
-```wd
+```wd-fragment
 :button "Add to cart" -> cart.count++ ; cart.total += 9
 ```
 
+A `:button` also accepts the three [accessibility attributes](#accessibility-attributes), written between the label and the `->`: `:button "Menu" aria-expanded="false" -> open toggle`.
+
 > **Pitfall:** `list toggle v` and `list remove v` match members by value (`===`). That is exact for strings, numbers, and booleans, but not reliable for object members — two equal-looking objects are different values. To remove a row object, loop the list and use the per-row `remove` action below.
 
 ### Computed values — `:computed`
 
-`:computed name = <expression>` derives state from other state with a compile-time-checked expression — names, numbers, arithmetic (`+ - * /`), comparisons, and the five **aggregates** over a list: `sum(list, field)`, `avg(list, field)`, `min(list, field)`, `max(list, field)`, and `count(list)`. It recomputes whenever an input changes and reads like any other binding (so it pairs naturally with [format pipes](#format-pipes--value--namearg)):
+`:computed name = <expression>` derives state from other state with a compile-time-checked expression — names, numbers, arithmetic (`+ - * /`), comparisons, and the five **aggregates** over a list: `sum(list, field)`, `avg(list, field)`, `min(list, field)`, `max(list, field)`, and `count(list)`. It recomputes whenever an input changes and reads like any other binding (so it pairs naturally with [format pipes](#format-pipes---value--namearg-)):
 
 ```wd
 :store cart = [{"price": 89}, {"price": 12}]
@@ -626,14 +735,18 @@ The aggregate's field argument is a bare key on each row (`price`, not `item.pri
 
 ```wd
 :fetch board from "/status.json"
-:every 10s -> board refetch        # live-refresh a dashboard
+:every 10s -> board refetch
 
 :state secs = 0
-:every 1s -> secs++                # a ticking counter
+:every 1s -> secs++
 ```
 
+The first line live-refreshes a dashboard; the second is a ticking counter. There is no comment syntax on a directive line, so a trailing `#` note would be parsed as part of the action.
+
 Intervals **pause while the tab is hidden** (via `visibilitychange`) and resume on return, so a backgrounded dashboard stops firing requests and draining battery.
 
+**`:every` is a page-level registration, not a per-row one.** A reactive `@loop` compiles its body once into a template and the runtime clones it per row, so a timer written inside that body would be registered once per row (three rows, three intervals), and a removed row's interval would keep firing. That placement is `[WD315]`. Declare the timer once outside the loop, at page level or inside the `::: section`, and act on the whole list (`:every 5s -> rows refetch`). It stays legal at page level, inside a `:::`, inside a **static** loop (which produces N literal copies that never churn), and in a reactive loop's `@empty` branch. `:button` inside a reactive loop is unaffected.
+
 ### Effects — `:effect`
 
 `:effect <watched> -> <actions>` runs actions whenever a watched state path changes. The actions are the same `:button` vocabulary (`;`-chained) — this is the escape hatch for side effects beyond `:computed` (which derives state) and `:fetch` deps (which auto-refetch):
@@ -647,6 +760,8 @@ Intervals **pause while the tab is hidden** (via `visibilitychange`) and resume
 
 Effects run after a render, against settled state, and an effect that mutates state triggers another pass — bounded by a 10-pass settle cap that warns (and stops) if an effect never settles. They do not fire on the initial load, only on a real change.
 
+Like `:every`, `:effect` is page-level: written inside a reactive `@loop` body it is `[WD315]`, because an effect watches a top-level state key and its actions target one, so there is no per-row meaning to give it. Declare it once outside the loop.
+
 ## Fetching data
 
 `:fetch name from "url"` declares state and fills it from JSON over the network:
@@ -662,6 +777,7 @@ Each fetch automatically declares four state keys you can branch on:
 | `name` | the data | `null` until the response arrives |
 | `name_loading` | boolean | `true` while the request is in flight |
 | `name_error` | string | the error message, or `null` |
+| `name_error_body` | object | the parsed JSON error body, or `null` |
 | `name_empty` | boolean | `true` when the data is `null`, `[]`, or `{}` |
 
 ### The four-state pattern
@@ -686,6 +802,28 @@ No team members yet.
 
 The lifecycle regions announce themselves: a bare `:if name_loading` compiles with `role="status" aria-live="polite"` and `:if name_error` with `role="alert"`, so assistive tech hears the flips with no extra markup. Author-supplied `role`/`aria-live` inside a region always wins.
 
+### What the server said: `name_error` and `name_error_body`
+
+A real API explains why it refused, and Darkmown surfaces that instead of a status line. When the failing response has a JSON body:
+
+- **`name_error`** is the body's own `error` field, then its `message` field, falling back to `HTTP <status>` when the body carries neither or is not JSON at all.
+- **`name_error_body`** is the whole parsed body (`null` when the response was not JSON), so per-field messages render without a line of your own JavaScript.
+
+Given a `422` whose body is `{"error": "Pick a file first.", "fields": {"photo": "No file was attached."}}`:
+
+```wd
+:fetch signup from "/api/signup" method=POST
+
+:if signup_error
+**{ signup_error }**
+:if signup_error_body
+Photo: { signup_error_body.fields.photo }
+:endif
+:endif
+```
+
+The first line renders *Pick a file first.*, not *Error: HTTP 422*. Both keys are declared automatically by `:fetch` and by a round-trip `:form` (one with both `into` and `action=`), and both are cleared at the start of the next request, so a stale message never outlives the failure that produced it.
+
 ### Options
 
 - `method=` — `GET` (default), `POST`, `PUT`, `PATCH`, or `DELETE`.
@@ -700,17 +838,28 @@ The lifecycle regions announce themselves: a bare `:if name_loading` compiles wi
 
 ### Authenticated requests and token refresh
 
-`headers=<key>` sends a state object as request headers — pair it with `:store` to persist a bearer token across reloads:
+`headers=<key>` sends a state object as request headers; pair it with `:store` to keep the token across reloads.
+
+**Seed the store empty.** A `:state`/`:store` value is a *build-time* seed: it is inlined into the page's public HTML, so a literal token written into a `.wd` file ships to every visitor. The token has to arrive at runtime, from your own `api/` endpoint:
 
 ```wd
-:store session = { "Authorization": "Bearer …" }
+:store session = {}
+
+:form action="/api/login" into login
+:input email type=email required
+:input password type=password required
+:submit "Sign in"
+:endform
+
+:effect login -> session merge login
+
 :fetch feed from "/api/feed" headers=session
 ```
 
 Add `refresh="<url>"` and Darkmown manages the token lifecycle: when a request comes back `401`, it POSTs the current `headers` object to the refresh URL, writes the returned headers (the new token) back into the `session` state — persisting it, since `session` is a `:store` — and retries the original request once. Concurrent `401`s sharing a refresh URL are de-duplicated into a single in-flight refresh.
 
 ```wd
-:store session = { "Authorization": "Bearer …" }
+:store session = {}
 
 :fetch feed from "/api/feed" headers=session refresh="/auth/refresh"
 ```
@@ -729,7 +878,7 @@ A URL can interpolate state with `{ }`. The fetch re-runs automatically when tha
 
 Trigger a reload by hand with the `refetch` action:
 
-```wd
+```wd-fragment
 :button "Reload" -> roster refetch
 ```
 
@@ -797,10 +946,49 @@ The declared value is a **seed**: it is used only the first time, when the store
 
 Writing the token that matches the default is redundant but never wrong, so `:store cart = [] persist` compiles and means exactly what it says. If a value genuinely ends in one of these words, quote it: `:state note = "0 persist"` seeds the string.
 
+There is a third word, [`from-url`](#url-as-state-from-url), which says the value also lives in the query string. It composes with `persist` and belongs to `:state` only. Writing `persist` and `ephemeral` on one line (or the same word twice) is `[WD261]` rather than a token silently folded into the value.
+
 `:computed` takes neither: computed values are derived rather than stored, so persist the state they derive from instead (that mistake is a compile error, `WD211`).
 
 > **Pitfall:** A store name must be unique. Declaring the same name as both a `:store` and a `:state` on one page is a compile error.
 
+## URL as state: `from-url`
+
+A filter nobody can link to is half a feature. Add `from-url` to a `:state` and the value lives in the query string as well as in memory: a reload keeps it, a shared link arrives with it applied, and the back button walks through it.
+
+```wd
+:state q = "" from-url
+:state tier = "all" from-url
+
+:bind q placeholder="Search products"
+
+:radio tier
+- all
+- budget
+- premium
+
+:state products = [{"name": "Aurora Lamp", "tier": "budget"}]
+
+@loop products into p where p.name contains q
+- **{ p.name }** ({ p.tier })
+@empty
+Nothing matches that search.
+@endloop
+```
+
+Type in the box and the address bar becomes `?q=aurora`. Reload, and the search comes back. Copy the URL into a new tab and it opens on the same view.
+
+The rules:
+
+- **The parameter is named after the state key.** A section-scoped key like `cart:items` becomes the parameter `cart.items`, so the name stays readable and stays unique.
+- **A value equal to its declared seed drops its parameter,** so the default page keeps a clean URL.
+- **Writes go through `history.replaceState`,** so filtering never fills the back button with one entry per keystroke. `popstate` re-reads on back and forward, and a parameter that is gone restores the seed.
+- **It composes with `persist`,** and the boot precedence is URL, then stored value, then seed. A link somebody sent you beats what this browser remembers. When back navigation lands on a clean URL, the stored value follows the seed too.
+- **Strings stay strings.** For any other seed type the parameter is JSON-parsed, falling back to the raw string.
+- **`from-url` is `:state` only.** A `:store` is shared by every page and every tab while a query parameter belongs to one page's address, so `from-url` on a `:store` or a `:theme` is `[WD260]` rather than a guess. On a `:computed` it is `[WD211]`: derive the value from a state key that does come from the URL.
+
+Live demo: [darkmown.com/url-state/](https://darkmown.com/url-state/).
+
 ## Forms and persistence
 
 Fetched data and a form live happily on the same page:
@@ -837,6 +1025,55 @@ Fetched data and a form live happily on the same page:
 - `:computed total = items.length * 4` derives state from state with a compile-time-checked expression — names, numbers, arithmetic, comparisons, and list aggregates (`sum`/`avg`/`min`/`max`/`count`). See [Computed values](#computed-values--computed).
 - `:if item.path` works inside reactive loops for per-row branches, and nests — an inner `:if` resolves after the outer branch and stays reactive.
 
+### Bound controls outside a form
+
+`:select`, `:radio`, and `:checkbox` mean two different things, and **where they sit decides which**. Inside a `:form` they are form fields, submitted by name (unchanged). Outside one they bind to a declared `:state` or `:store` of that name, exactly like `:bind` and `:slider`: move the control and the state changes, change the state and the control moves.
+
+```wd
+:state density = "Comfortable"
+:state previews = true
+
+:select density
+- Compact
+- Comfortable
+- Spacious
+
+:checkbox previews
+- Show image previews
+
+:if density == "Compact"
+Rows sit tight together.
+:endif
+```
+
+- **The state has to exist first.** A bound field naming state that is not declared is `[WD450]`, which spells out both readings: declare the state, or move the field inside a `:form`.
+- **A bound `:checkbox` is a single boolean,** so it takes exactly one `- Label` line (the label shown beside it). Several options is `[WD451]`; for a set of choices use a `:radio` group. The multi-value checkbox group is the in-form behavior and is unchanged.
+- **A bound `:radio` group keeps its shared `name`,** which is what makes the browser treat it as mutually exclusive, and carries the chosen option's text.
+
+### File upload
+
+A `:form` that contains a file field posts **multipart**, so the file itself travels:
+
+```wd
+:form into reply action="/api/upload/"
+:input photo type=file required
+:input caption placeholder="A caption (optional)"
+:submit "Upload"
+:endform
+
+:if reply
+Uploaded **{ reply.name }**, { reply.size } bytes.
+:endif
+
+:if reply_error
+**{ reply_error }**
+:endif
+```
+
+The compiler writes `enctype="multipart/form-data"` for the browser's native submit, and the runtime sends real `FormData` with **no** content type of its own so the browser writes the boundary. A raw `<input type="file">` on an `html: true` page counts as a file field too.
+
+Bound controls inside the form carry no `name`, so `FormData` would never see them; on the multipart path they are appended by their state key instead of being silently dropped. A file field on a `method="get"` form is `[WD452]`: a GET request has no body, so only the file's name would ever travel, which is the kind of failure that looks like it worked.
+
 ## Backends & deploy
 
 Darkmown builds **100% static, CDN-cacheable HTML** — never per-request server rendering. Reactive pages hydrate from data-attributes client-side; dynamic data arrives via `:fetch`. When you need a backend, you don't learn a new syntax — you write a plain serverless function, and *it just comes with wherever you deploy*.
@@ -860,9 +1097,9 @@ export default async function (request, context) {
 
 Templates get you to a running, deployable app fast: `darkmown init shop --template store` ships a cart **and** an `api/checkout.js`; `--template dashboard` ships a `:fetch` view **and** an `api/metrics.js`; `--template blog` ships a typed posts collection (`_schema.wd` + one `@loop` over the folder) — adding a post is adding a `.md` file.
 
-## Interactions — `:slider`, `:sortable`, `:carousel`
+## Interactions — `:slider`, `sortable`, `:carousel`
 
-Rich interactions are **pay-for-what-you-use**: `:sortable`/`:carousel` compile to a tiny `/__wd/behaviors/<name>.js` module injected **only** on pages that use them, budgeted separately from the ≤8 KB core runtime. `:slider` is compile-time only — zero extra JS.
+Rich interactions are **pay-for-what-you-use**: `sortable`/`:carousel` compile to a tiny `/__wd/behaviors/<name>.js` module injected **only** on pages that use them, budgeted separately from the ≤8 KB core runtime. `:slider` is compile-time only — zero extra JS.
 
 ```wd
 :slider volume = 50 min=0 max=100 step=5
@@ -884,7 +1121,7 @@ Second slide
 ```
 
 - **`:slider name = v min max step`** renders a range input two-way bound through `:bind`; range values coerce to Number so `:computed`/math see a number. Ships no behavior module.
-- **`:sortable`** (a `@loop` clause) drag-reorders the underlying `:state`/`:store` list via Pointer Events (mouse + touch), with full keyboard support (Arrow Up/Down on a focused row, screen-reader instructions + a live "Moved to position N of M" announcement), rewriting the list through the public `window.wd` API so the keyed loop repaints. Valid only on a plain reactive loop (no `where`/`sort`/`reverse`/`offset`/`limit`).
+- **`sortable`** (a bare `@loop` clause, written without a leading colon) drag-reorders the underlying `:state`/`:store` list via Pointer Events (mouse + touch), with full keyboard support (Arrow Up/Down on a focused row, screen-reader instructions + a live "Moved to position N of M" announcement), rewriting the list through the public `window.wd` API so the keyed loop repaints. Valid only on a plain reactive loop (no `where`/`sort`/`reverse`/`offset`/`limit`).
 - **`:carousel [autoplay=N]`** treats **each direct child block as one slide** (wrap each in its own block, e.g. `::: slide`, and size it in your skin), using native CSS scroll-snap (touch swipe is free) plus prev/next buttons, dot navigation, and mouse drag. `autoplay` is suppressed under `prefers-reduced-motion`.
 
 ## Inline attributes
@@ -896,13 +1133,13 @@ A trailing `{.class .class #id}` attaches classes / an id to the inline element
 ![logo](/logo.svg){.brand}
 ```
 
-The block must follow the element with no space, and works on links, images, emphasis, and inline code. It never collides with `{ name }` interpolation — an interpolation always starts with a name, never a `.` or `#`.
+The block must follow the element with no space, and works on links, images, and emphasis. It does **not** attach to inline code: `` `x` ``{.hl} leaves the braces in the output as literal text. It never collides with `{ name }` interpolation, because an interpolation always starts with a name, never a `.` or `#`.
 
 **Headings get anchors for free.** Every markdown heading carries a stable, GitHub-style slug `id` at build time (lowercased, punctuation stripped, whitespace → hyphens; duplicates dedupe with `-1`/`-2` suffixes across the whole document), so any section of any page is deep-linkable with a plain `#the-slug` fragment — zero JS. The [docs page's](https://darkmown.com/docs/) "On this page" table of contents is just markdown links to those anchors.
 
 ## Media — `:video`, `:audio`, `:embed`
 
-*New in 1.0.* Three one-line directives replace hand-written `<video>` / `<iframe>` markup. They are **compile-time only** — they emit no `data-wd-*`, so a media-only page still ships **zero** framework JavaScript.
+Three one-line directives replace hand-written `<video>` / `<iframe>` markup. They are **compile-time only** — they emit no `data-wd-*`, so a media-only page still ships **zero** framework JavaScript.
 
 ```wd
 :video /clip.mp4 poster=/clip.jpg controls
@@ -917,7 +1154,7 @@ Darkmown's shipped CSP pre-authorizes exactly the two embed origins (`youtube-no
 
 ## Syntax highlighting
 
-*New in 1.3.* Fenced code blocks with a language are highlighted at **build time** — HTML and CSS only, no client JavaScript. Tag the fence with a language and it just works:
+Fenced code blocks with a language are highlighted at **build time** — HTML and CSS only, no client JavaScript. Tag the fence with a language and it just works:
 
 ````md
 ```js
@@ -950,7 +1187,7 @@ See it recolor live on the [Syntax highlighting demo](https://darkmown.com/highl
 
 ## Dark mode — `tokens dark`
 
-*New in 0.19.0.* A colocated `.skin` file already declares its palette in a `tokens` block (`name value` pairs referenced elsewhere as `$name`). Add a second `tokens dark` block to override any of those tokens under the visitor's OS dark preference — it compiles to a `@media (prefers-color-scheme: dark) :root { … }` rule, so the page follows the system theme with **zero JavaScript**.
+A colocated `.skin` file already declares its palette in a `tokens` block (`name value` pairs referenced elsewhere as `$name`). Add a second `tokens dark` block to override any of those tokens under the visitor's OS dark preference — it compiles to a `@media (prefers-color-scheme: dark) :root { … }` rule, so the page follows the system theme with **zero JavaScript**.
 
 ```skin
 tokens
@@ -970,7 +1207,7 @@ A single `tokens dark` block powers **both** theming paths: it compiles to `:roo
 
 ### Manual toggle — `:theme`
 
-*New in 1.0.* For an explicit light/dark switch alongside (or instead of) the OS preference, declare `:theme` once and drive it with ordinary buttons. It registers a durable `theme` store and reflects its value onto `<html data-theme="…">`:
+For an explicit light/dark switch alongside (or instead of) the OS preference, declare `:theme` once and drive it with ordinary buttons. It registers a durable `theme` store and reflects its value onto `<html data-theme="…">`:
 
 ```wd
 :theme
@@ -983,7 +1220,7 @@ Because `tokens dark` already emits the `[data-theme="dark"]` rule, **no extra s
 
 ## Scoped styles — `scoped`
 
-*New in 1.4.0.* By default a colocated `.skin` is **global** — its selectors match the whole page, exactly like a stylesheet. That's the right default for a design system. But when two components both want a class called `.card`, global CSS makes them fight. Opt a skin into **scoping** so its selectors only ever match the component it ships with: make the **first line** of the `.skin` file the word `scoped`.
+By default a colocated `.skin` is **global** — its selectors match the whole page, exactly like a stylesheet. That's the right default for a design system. But when two components both want a class called `.card`, global CSS makes them fight. Opt a skin into **scoping** so its selectors only ever match the component it ships with: make the **first line** of the `.skin` file the word `scoped`.
 
 ```skin
 scoped
@@ -1097,7 +1334,7 @@ Every author-facing compile error opens with a stable `WDxxx` code, so it is sea
         Use: :state name = value [persist|ephemeral] — 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:
+The full list lives in [`docs/errors.md`](https://github.com/ZVN-DEV/darkmown/blob/master/docs/errors.md): code, cause, fix, and a compilable example each. (It is generated into the repository, not the published tarball; `darkmown catalog --llms-full` prints the same content offline.) Codes are grouped by subsystem:
 
 | Range | Subsystem |
 | --- | --- |
@@ -1168,7 +1405,7 @@ session.call("validate", {});
 
 ## 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.
+A VS Code extension in [`editors/vscode`](https://github.com/ZVN-DEV/darkmown/tree/master/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.
 
 Install from a `.vsix` today:
 
@@ -1177,7 +1414,7 @@ npm run pack:extension   # builds editors/vscode/darkmown-<version>.vsix
 code --install-extension editors/vscode/darkmown-*.vsix
 ```
 
-Or inside VS Code: Extensions panel → `…` menu → **Install from VSIX…** and pick the built file. A Visual Studio Marketplace listing is pending (see [`editors/vscode/PUBLISHING.md`](editors/vscode/PUBLISHING.md)); until it lands, the `.vsix` route above is the supported install.
+Or inside VS Code: Extensions panel → `…` menu → **Install from VSIX…** and pick the built file. A Visual Studio Marketplace listing is pending (see [`editors/vscode/PUBLISHING.md`](https://github.com/ZVN-DEV/darkmown/blob/master/editors/vscode/PUBLISHING.md)); until it lands, the `.vsix` route above is the supported install.
 
 ## Accessibility
 
@@ -1187,6 +1424,7 @@ Every compiled page ships with landmark-and-announcement basics baked in at buil
 - **Document language.** `lang:` frontmatter sets `<html lang>` per page (default `en`).
 - **Live `:fetch` regions.** A bare `:if name_loading` region over a `:fetch` key compiles to `role="status" aria-live="polite"` and `:if name_error` to `role="alert"`, so screen readers announce loading and error flips for free. Write your own `role`/`aria-live` inside the region and Darkmown adds nothing.
 - **Accessible names on form controls.** Generated `:input`/`:bind`/`:textarea`/`:select` controls without an author-supplied `aria-label`/`aria-describedby` get an `aria-label` derived from the placeholder or field name; `:slider` and choice groups do the same.
+- **`role`, `aria-*`, and `title` on containers and buttons.** `::: card role="region" aria-label="Notes"` and `:button "Menu" aria-expanded="false" -> open toggle` compile without raw HTML. Values are static, double-quoted, and escaped on emit. See [Accessibility attributes](#accessibility-attributes) for the whole rule.
 
 ## Security
 
@@ -1211,6 +1449,35 @@ Builds emit security response headers so a deployed site gets sane defaults with
 
 **If you use `:fetch` or `:form action=` against another host, widen `connect-src`.** The shipped CSP allows same-origin connections; calling a third-party API is otherwise blocked by the policy. Add the host to `connect-src` in your deploy config (it is not auto-derived from your page sources). The CSP is a defense-in-depth layer — it does not replace the trust-boundary rules above; see [SECURITY.md](SECURITY.md) for tightening guidance.
 
+## Limits
+
+Darkmown is small on purpose. Here is what it deliberately refuses and what it genuinely cannot do today, collected in one place so you can decide before you build rather than after.
+
+**Refusals that will not change:**
+
+- **`.md` never gets directives.** The extension is the feature gate, and it holds transitively: an `.md` page that `@include`s a `.wd` still ships `runtime: false` and inert text.
+- **No `eval`, and a closed expression vocabulary.** Predicates, `:computed`, and directive actions are compile-time whitelists interpreted by a closed evaluator. There are no custom format pipes and no user-supplied functions anywhere in the language. (That is also why reactive pages need no `'unsafe-eval'`.)
+- **No backend DSL.** `api/` is plain Web-standard JavaScript. Darkmown owns no server and never will.
+- **No built-in sanitizer.** The model is trusted-author; see [Security](#security).
+
+**Structural limits, true today:**
+
+- **No per-request rendering.** Everything is build time. A `:state`-seeded `@loop` *does* bake its rows into the initial HTML, so that content is indexable, but anything behind `:fetch` is invisible to crawlers and to your own `sitemap.xml`. No personalization, no draft preview URLs.
+- **Auth is a public shell with `api/`-gated data.** A `:if session` gate ships *both* branches into the HTML, and a `:state`/`:store` seed is inlined into public HTML, so a token must never be written into a page (see [Authenticated requests](#authenticated-requests-and-token-refresh)). The workable architecture is a public page whose data is gated behind your own endpoint.
+- **No layout or shell inheritance.** Every page includes its own nav and footer. There is no template a page extends and no slot to fill.
+- **No arbitrary `<head>` content.** The document head is what frontmatter drives; you cannot inject your own tags.
+- **No route generation from data.** Collections are folders of files. A JSON array cannot become routes. `paginate N` is the one route multiplier, and only over an existing collection listing.
+- **Only accessibility attributes on containers and buttons.** `:::` and `:button` accept `role="…"`, `aria-…="…"`, and `title="…"`, and nothing else: `class=`, `id=`, `style=`, `data-*`, and event handlers are compile errors by design. Style with `.class` tokens, act with `->` actions, and reach for raw HTML on an `html: true` page when you genuinely need another attribute.
+- **Aria values are static text.** There is no `{ state }` interpolation inside `role`/`aria-*`/`title`, so a live accessible name means raw HTML or a colocated `.js`.
+- **Raw HTML attributes do not bind.** A Markdown link or image destination does ([Destinations that bind](#destinations-that-bind)), but `<a href="{ url }">` on an `html: true` page is painted once at build time and warned about. There is no element for the compiler to mark up.
+- **Reactive rows cannot fill a Markdown table.** A reactive row is cloned into a `<div>`, which is not a legal child of `<table>`, so `[WD191]` refuses it. Static loops fill tables fine; for reactive rows, build them from containers (`::: trow` / `::: td`) and style them as a table.
+- **No i18n beyond `lang:`.** No `hreflang`, no message catalog, no ambient locale, no locale routing. A multilingual site means duplicating the tree per locale.
+- **Every framework asset URL is absolute** (`/__wd/...`), so a Darkmown site cannot be mounted at a subpath. It is all-or-nothing per origin.
+- **Includes are macros, not components.** No children, no slots, no default arguments, and a missing argument renders `{ title }` literally rather than erroring.
+- **No `darkmown test`.** There is no built-in way to assert your own site's behavior. Use [`compileFromMemory`](#programmatic-compile--compilefrommemory) against your own pages, or a browser test runner.
+
+**Migrating out is easy, and that is on purpose.** `dist/` is portable static HTML plus one runtime file of ~6.6 KB gzipped. There is no server to port, no proprietary component format, no framework runtime baked through the output, and nothing to un-eject. Point any host at the folder, or hand it to whatever you move to next, and the site keeps working. The lock-in is a directory of Markdown files you already own.
+
 ## Spec status
 
 See [docs/spec-alignment.md](docs/spec-alignment.md) for the deep alignment audit against the original vision.