@zvndev/darkmown 0.17.0 → 0.19.0

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to Darkmown are documented here. Versions follow [semver](https://semver.org); pre-1.0 minor versions may contain breaking changes.
 
+## 0.19.0 — 2026-06-25
+
+Post-review sprint: deeper reactive loops, hardened deploys, and OS-aware theming.
+
+- **Nested reactive loops (one level).** A reactive `@loop` can now contain an inner reactive `@loop <outerItem>.<field> into x` — the inner source is a dotted path on the outer row, so each reconciled row renders its own keyed inner list and both stay live. Interpolation resolves the inner item first, then the outer (`{ line.qty }` and `{ order.ref }` both in scope). Build-time loop nesting over JSON/frontmatter was already supported; what's new is reactive-inside-reactive. Nesting is **one level only** — an inner reactive loop may not contain a third.
+- **Security headers / CSP on deploy.** Builds now emit security response headers so a deployed site is hardened by default: a `dist/_headers` file (Cloudflare Pages format), with the Vercel and local `serve` paths applying the equivalent. Every page carries `X-Content-Type-Options: nosniff`, a `Referrer-Policy`, and a `frame-ancestors` directive. The **Content-Security-Policy is tiered**: static pages get a tight policy, and reactive pages (those shipping `/__wd/runtime.js`) add `script-src 'unsafe-eval' 'unsafe-inline'` for the runtime's `new Function` expression compiler. The default CSP allows same-origin connections only — a `:fetch`/`:form action=` to another host must widen `connect-src` by hand. It is defense-in-depth, not a host allowlist; SSRF protection stays the author's responsibility.
+- **Dark-mode theming — `tokens dark`.** A `.skin` file can add a `tokens dark` block beside its base `tokens`; the dark tokens compile to `@media (prefers-color-scheme: dark) :root { … }`, overriding the matching base tokens under the visitor's OS dark preference. Rules keep referencing the same `$name` tokens, so dark mode is a zero-JavaScript palette swap. A skin with no `tokens dark` block is unchanged.
+- **Runtime test backfill.** Added runtime/compiler tests covering the new reactive-loop nesting and the security-header and theming output.
+- **Compile errors carry a line number.** A compile error now includes the offending line number alongside the file path and corrective suggestion, so the source of a directive mistake is easier to find.
+
+## 0.18.0 — 2026-06-24
+
+Navigation goes instant and flash-free, and images are hardened at compile time.
+
+- **Prerendered, gap-free navigation.** `transitions: true` now also emits a declarative `<script type="speculationrules">` that **prerenders** same-origin links on hover/pointerdown (eagerness `moderate`). The next page is fully rendered before the click, so activation is instant — eliminating the white render-gap flash that plain navigation (and even prefetch, which only warms the cache) leaves for the view transition to paper over. It is browser-interpreted JSON, not framework runtime JS, so static pages stay zero-JS; unsupported browsers (or those with preloading disabled) ignore it and navigate normally. Mark a link `{.no-prefetch}` to opt it out; `rel=nofollow` links are never speculated. (Chrome disables prerendering while DevTools is open — verify on the built site with DevTools closed.)
+- **Directional view transition.** The root transition is no longer the UA cross-fade, which left both pages superimposed at ~50 % opacity mid-navigation — a visible double-exposure ghost. `transitions: true` now emits a short directional fade+slide (old lifts up and out, new rises up and in, 200 ms eased) so pages move past each other instead of stacking. Honors `prefers-reduced-motion`.
+- **Compile-time image hardening.** Every `<img>` is stamped with its intrinsic `width`/`height` (read from the file on disk via `image-size`, a new build-time dependency — no runtime cost), `decoding="async"`, and a load-priority split: the first image stays eager with `fetchpriority="high"` (the LCP candidate), the rest get `loading="lazy"`. This removes the layout-shift "jump" as images decode and stops below-the-fold images competing for bandwidth. Author-set attributes are never overwritten; remote or unreadable sources degrade gracefully (no dimensions, no error).
+- All three are compile-time only — the shipped reactive runtime is unchanged (still ~5.8 KB gzipped, under the 6 KB budget). The demo site (`site/pages/`) now opts into `transitions: true` to dogfood the navigation.
+
 ## 0.17.0 — 2026-06-23
 
 Multi-select and single-choice form groups: **`:checkbox` and `:radio`**.

package/README.md

@@ -82,7 +82,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).
 
-`transitions: true` opts a page into **cross-document view transitions** — a smooth same-origin cross-fade on navigation, emitted as the CSS-only `@view-transition { navigation: auto; }` rule. It ships zero JavaScript, only animates between same-origin pages that both opt in, and is silently ignored by browsers without support (the navigation just doesn't fade). Off by default; opt out explicitly with `transitions: false`.
+`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.)
 
 ## Static assets
 
@@ -93,6 +93,8 @@ Images, fonts, icons, and other non-page files live on the include shelf at `sit
 
 Reference them with a normal URL: `![logo](/__wd/media/logo.svg)`. The preview/`serve` layer returns the correct `Content-Type` per extension.
 
+**Images are hardened at compile time.** Every `<img>` the compiler emits is stamped with its intrinsic `width`/`height` (read from the source file, so the browser reserves space and the page doesn't reflow as images decode), `decoding="async"`, and a load-priority split — the first image on the page stays eager with `fetchpriority="high"` (the LCP candidate), the rest get `loading="lazy"`. Author-set attributes always win, and remote or unreadable sources just skip the dimensions. The compiler **measures**, it doesn't resize — keep source images web-sized (modern formats, sensible dimensions).
+
 **Or colocate an asset next to the page that uses it.** Any non-page file under `site/pages/` (anything but `.md`/`.wd` routes and the colocated `.skin`/`.js`) is copied to `dist/` at its own path, so a clean relative URL just works:
 
 - `site/pages/logo.svg` → `dist/logo.svg` → `![logo](/logo.svg)`
@@ -238,6 +240,34 @@ A `:button` inside a reactive `@loop` can act on its own row. `cart += product`
 
 That is a full add-to-cart / remove-line flow — and a to-do list with delete — in plain Markdown, no JavaScript.
 
+### 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:
+
+```wd
+:state orders = [
+  {"id": 1, "ref": "A-100", "lines": [{"sku": "x1", "qty": 2}, {"sku": "x2", "qty": 1}]},
+  {"id": 2, "ref": "A-101", "lines": [{"sku": "y9", "qty": 5}]}
+]
+
+@loop orders into order
+::: card
+**{ order.ref }**
+@loop order.lines into line
+- { line.sku } × { line.qty }
+@endloop
+:::
+@endloop
+```
+
+- The inner loop is keyed and reconciled per outer row, like any reactive loop.
+- Interpolation inside the inner body resolves the inner item first, then the outer item — `{ line.qty }` and `{ order.ref }` are both in scope.
+- Build-time loops over JSON/frontmatter already nest freely (the "loops nest" behavior above); what's new is **reactive-inside-reactive** over a `:state`/`:store`/`:fetch` row field.
+
+> **Honest caveat:** nesting is **one level only** — an inner reactive loop may not itself contain a third reactive loop. Build-time loop nesting is unaffected by this limit.
+>
+> **Per-row actions inside an inner loop:** `cart += member` (append-row) works from an inner loop — it carries the inner item into a top-level `:state`/`:store` list. But a per-row **`remove`** needs a top-level list as its source, and an inner loop's source is a path off the outer row (`team.members`), so deleting an inner row in place is **not** supported — the compiler rejects it with a corrective message. Carry the row into a top-level list and remove it there.
+
 ## Sections
 
 ```wd
@@ -526,6 +556,26 @@ A trailing `{.class .class #id}` attaches classes / an id to the inline element
 
 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 `#`.
 
+## 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**.
+
+```skin
+tokens
+  paper #ffffff
+  ink #171717
+
+tokens dark
+  paper #0b0b0f
+  ink #f4f4f5
+
+page
+  bg $paper
+  color $ink
+```
+
+The `tokens dark` values override the matching base tokens only when the OS reports a dark preference; the rules below keep referencing the same `$paper` / `$ink`. The base `tokens` block stays the light default, so a skin with no `tokens dark` block is unchanged.
+
 ## The escape hatch
 
 Reactive pages expose `window.wd` — `wd.get(key)`, `wd.set(key, value)`, `wd.state`, `wd.render()` — so colocated `.js` can do anything the directives can't. Section-scoped keys are addressed as `sectionId:name`.
@@ -546,10 +596,19 @@ Darkmown is a **trusted-author** site generator: you compile content you wrote,
 - **Raw HTML passes through by default.** Darkmown runs `markdown-it` with `html: true`, so raw HTML in your content is emitted verbatim — by design, like every Markdown site generator. There is no built-in sanitizer; a raw `<script>` or event-handler attribute in untrusted content would execute in the visitor's browser. A page can opt into strict mode with `html: false` frontmatter, which drops raw HTML entirely.
 - **`:fetch` and `:form action=` have no host allowlist, and reactive pages need `unsafe-eval`.** A fetch/form URL is taken straight from the page source; the compiler rejects non-http(s) schemes but does not restrict which hosts you call, so SSRF/exfiltration protection is the author's responsibility. Reactive pages also require `script-src 'unsafe-eval'` in your Content-Security-Policy, because the runtime compiles validated `:computed` / `@loop … where` / `.class when` expressions via `new Function` — a strict CSP without `unsafe-eval` will break reactive pages (static pages are unaffected).
 
-> **The single biggest footgun:** do not compile untrusted or user-submitted Markdown without sanitizing it first. There is no built-in sanitizer.
+> **The single biggest footgun:** do not compile untrusted or user-submitted Markdown without sanitizing it first. There is no built-in sanitizer. A page can flip to strict mode with `html: false` frontmatter, which drops raw HTML entirely (see [SECURITY.md](SECURITY.md)).
 
 Directive actions and `:computed`/`@loop … where` expressions are never `eval`'d as raw user content — they compile to a whitelisted grammar (item paths, declared `:state`, numbers, strings) that runs via `new Function`. See [SECURITY.md](SECURITY.md) for the full security model.
 
+### Shipped security headers
+
+Builds emit security response headers so a deployed site gets sane defaults without hand-writing a config. The build writes a `dist/_headers` file (Cloudflare Pages format), and the Vercel/local `serve` paths apply the equivalent. On every page:
+
+- **`Content-Security-Policy`** — static pages get a tight policy; **reactive pages** (those that ship `/__wd/runtime.js`) add `script-src 'unsafe-eval' 'unsafe-inline'`, which the runtime needs to compile validated `:computed` / `@loop … where` / `.class when` expressions via `new Function`. Static pages stay strict.
+- **`X-Content-Type-Options: nosniff`**, **`Referrer-Policy`**, and a **`frame-ancestors`** directive (clickjacking protection) on every page.
+
+**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.
+
 ## Spec status
 
 See [docs/spec-alignment.md](docs/spec-alignment.md) for the deep alignment audit against the original vision.

package/SECURITY.md

@@ -31,10 +31,45 @@ Things Darkmown deliberately guards at compile time and runtime:
 - **Output escaping.** Interpolated values are HTML-escaped; state scripts escape `<` to prevent script-tag breakout.
 - **Static server path containment.** The dev/preview servers resolve requests strictly inside `dist`.
 
-## The biggest footgun: raw HTML passthrough
+## The #1 footgun: raw HTML passthrough (`html: true`)
 
-Darkmown configures markdown-it with `html: true`, so **raw HTML in `.md`/`.wd` files is passed through verbatim** — by design, like every Markdown site generator. This is the single most important thing to understand about Darkmown's security model.
+This is the single most important thing to understand about Darkmown's security model. **Read this before pointing Darkmown at anything you did not write yourself.**
 
-- Treat all content files as **trusted input**, the same way you trust your own source code.
-- **Do not compile untrusted or user-submitted Markdown** (comments, form input, third-party docs) without sanitizing it first. Darkmown ships no built-in sanitizer; raw `<script>` and event-handler attributes in untrusted content would execute in the visitor's browser.
+Darkmown configures markdown-it with `html: true`, so **raw HTML in `.md`/`.wd` files is passed through verbatim** — by design, like every Markdown site generator. A raw `<script>` or an `onerror=` attribute in your content reaches the visitor's browser and runs.
+
+- **Treat every content file as trusted input**, the same way you trust your own source code.
+- **Never compile untrusted or user-submitted Markdown** (comments, form input, third-party docs, scraped content) without sanitizing it first. Darkmown ships **no built-in sanitizer**.
 - If you must render untrusted content, sanitize it (for example with a library like DOMPurify) before it reaches the compiler.
+
+### The `html: false` per-page opt-out
+
+The built-in mitigation is per-page strict mode. Add `html: false` to a page's frontmatter and that page's Markdown renders through a strict renderer that **escapes raw HTML entirely** — a stray `<script>` becomes inert text instead of executing.
+
+```wd
+---
+title: User comments
+html: false
+---
+```
+
+Use it for any page whose content is even partly out of your hands. The default stays `html: true` because the framework targets trusted authors; `html: false` is the switch for the pages where that assumption doesn't hold.
+
+> **Note:** `html: false` is a *per-page* frontmatter key — there is no global/site-wide `html: false` default today (no config loader exists yet). Flipping the global default to strict-by-default is a deliberate future option, not a shipped setting; until then, set `html: false` on each page that needs it.
+
+## Deploying with a Content-Security-Policy
+
+Builds emit security response headers so a deployed site is hardened by default rather than relying on hand-written config. The build writes a `dist/_headers` file (Cloudflare Pages format) and the Vercel and local `serve` paths apply the equivalent. Every page gets:
+
+- **`Content-Security-Policy`** — **static pages** (no runtime) get a tight policy. **Reactive pages** (those that ship `/__wd/runtime.js`) additionally need `script-src 'unsafe-eval' 'unsafe-inline'`, because the runtime compiles validated `:computed` / `@loop … where` / `.class when` expressions via `new Function`. A strict CSP without `unsafe-eval` breaks reactive pages; static pages are unaffected and stay strict.
+- **`X-Content-Type-Options: nosniff`** — stops MIME-type sniffing.
+- **`Referrer-Policy`** — limits referrer leakage.
+- **`frame-ancestors`** — clickjacking protection (controls who may frame the page).
+
+### Tightening the policy
+
+The shipped CSP is a sensible default, not a finished policy for every site. Tighten or widen it for your deployment:
+
+- **`:fetch` / `:form action=` to another host needs a wider `connect-src`.** The default CSP permits same-origin connections; a call to a third-party API is otherwise blocked. Add each external host to `connect-src` explicitly — it is **not** auto-derived from your page sources.
+- **Remote images, fonts, or embeds** need their hosts added to `img-src` / `font-src` / `frame-src`.
+- **Reactive pages** require `unsafe-eval` in `script-src`; do not remove it on a page that ships the runtime. If you can keep a page static, it can run under a stricter policy.
+- The CSP is **defense-in-depth** — it limits the blast radius of a mistake but does **not** replace the trust-boundary rules above. It is not a substitute for sanitizing untrusted content, and it does not add a host allowlist to `:fetch`/`:form` (SSRF/exfiltration protection remains the author's responsibility).

package/docs/spec-alignment.md

@@ -79,6 +79,20 @@ Three capability gaps from the 2026-06-16 audit, closed together over a shared `
 - **Interpolation in link/image destinations:** `{ name.path }` now resolves inside a markdown destination — `[{ it.label }]({ it.url })`, `![{ p.alt }]({ p.src })` — so a build-time `@loop` can drive `href`/`src` and the page stays static. Only build-time (static-scope) values substitute; reactive `:state` is left untouched (it cannot live in a destination).
 - **Inline attributes (`{.class #id}`):** a trailing attribute block attaches classes / an id to the inline element before it (link, image, emphasis, code), so a link can be styled as a button without a wrapper container. The block must follow with no space; it never collides with `{ name }` interpolation (which always starts with a name, not `.`/`#`).
 
+## Stage 14 additions (2026-06-24, v0.18.0)
+
+- **Instant, flash-free navigation under `transitions: true`:** alongside the cross-document view transition, the page emits a declarative `<script type="speculationrules">` that **prerenders** same-origin links at `moderate` eagerness (hover/pointerdown). A prerendered page activates instantly, so there is no render-gap white flash for the transition to cover; the transition itself is now a directional fade+slide (old lifts out, new rises in, 200 ms eased) instead of the UA cross-fade that superimposed both pages at ~50 % opacity. Browser-interpreted JSON, not framework JS — static pages stay zero-JS; `prefers-reduced-motion` is honored; `{.no-prefetch}` / `rel=nofollow` opt links out. (Chrome disables prerendering while DevTools is open.)
+- **Compile-time image hardening:** every emitted `<img>` is stamped with intrinsic `width`/`height` (read from disk via the `image-size` build-time dependency — no runtime cost), `decoding="async"`, and `fetchpriority="high"` on the first image / `loading="lazy"` on the rest. Eliminates cumulative layout shift and de-prioritizes below-the-fold images. Author attributes are never overwritten; remote/unreadable sources degrade to no dimensions.
+
+## Stage 15 additions (2026-06-25, v0.19.0)
+
+The post-8/10-review sprint: one reactive-loop capability, a deploy-hardening layer, and a theming primitive — plus a test backfill and clearer compile errors. Tracks landed in parallel; behavior below reflects the intended surface, and any item gated on the runtime-size budget is flagged.
+
+- **Nested reactive loops (one level):** a reactive `@loop` may contain an inner reactive `@loop <outerItem>.<field> into x` — the inner source is a dotted path rooted at the outer row, so each reconciled outer row renders its own keyed inner list and both stay live. Interpolation inside the inner body resolves the inner item first, then the outer (`{ line.qty }` and `{ order.ref }` both in scope). Build-time loop nesting over JSON/frontmatter was already supported; what's new is reactive-inside-reactive over a `:state`/`:store`/`:fetch` row field. **Honest caveat:** nesting is **one level only** — an inner reactive loop may not contain a third reactive loop. It shipped within the runtime-size budget (5910 B gzipped, no minification). A second caveat: per-row `cart += member` (append-row) works from an inner loop, but a per-row **`remove`** needs a top-level `:state`/`:store` list as its source — an inner loop's source is a path off the outer row, so deleting an inner row in place is unsupported and the compiler rejects it with a corrective hint (carry the row into a top-level list, remove it there).
+- **Security headers / CSP on deploy:** the build emits security response headers so a deployed site is hardened by default — `dist/_headers` (Cloudflare Pages format), with the Vercel and local `serve` paths applying the equivalent. Every page carries `X-Content-Type-Options: nosniff`, a `Referrer-Policy`, and a `frame-ancestors` directive. **Content-Security-Policy is tiered like the runtime:** static pages get a tight policy; reactive pages (those shipping `/__wd/runtime.js`) add `script-src 'unsafe-eval' 'unsafe-inline'`, which the runtime needs to run validated `:computed` / `@loop … where` / `.class when` expressions via `new Function`. **Honest caveat:** the shipped CSP allows only same-origin connections — a `:fetch`/`:form action=` to another host must widen `connect-src` by hand (it is not derived from page sources), and the CSP remains defense-in-depth, **not** a host allowlist for `:fetch` (SSRF stays the author's responsibility per the trust boundary). The `html: false` per-page strict-render opt-out is unchanged; a global strict-by-default `html` setting remains a deliberate future option (no config loader exists yet).
+- **Dark-mode theming — `tokens dark`:** a `.skin` file may add a `tokens dark` block alongside its base `tokens`; the dark tokens compile to `@media (prefers-color-scheme: dark) :root { … }`, overriding the matching base tokens under the visitor's OS dark preference. Rules keep referencing the same `$name` tokens, so dark mode is a palette swap with **zero JavaScript** — consistent with the existing zero-JS `.skin` output. A skin with no `tokens dark` block is unchanged.
+- **Test backfill + compile-error line numbers:** the sprint backfilled runtime/compiler tests for the new surface, and compile errors now carry the offending **line number** alongside the file path and corrective suggestion. **Honest caveat:** this entry documents the intended sprint scope; the exact assertion count and the precise error-message format are owned by the test/compiler tracks and were not verified from this docs track.
+
 ## Stage 13 additions (2026-06-23, v0.17.0)
 
 - **`:checkbox` and `:radio` field groups:** `:checkbox name` / `:radio name` (with `- Label` option lines) render a labelled `role="group"` / `role="radiogroup"` of `<input>`s that share one `name`, each wrapped in its own `<label>` and deriving an aria-label like the other fields. A `:checkbox` group is marked `data-wd-multi` so the runtime's submit handler collects **every** checked value into an array (`FormData.getAll`) instead of collapsing to the last — the one runtime change (compile-time only otherwise; shipped runtime stays ~5.8 KB). A `:radio` group captures a single value like `:input`. Closes the multi-select / single-choice gap that previously forced raw HTML and lost `:form into` capture.
@@ -107,7 +121,7 @@ The compiler recognizes three directives — `:note`, `:try`, and `:sprint` —
 ## Still missing from the full vision
 
 - First-party server runtime (`site/api/`), HTML-fragment `swap` semantics, and cart server sync — parked behind the adapter decision until a real project needs them.
-- **View transitions:** named/typed transitions (`view-transition-name`, per-element morphs) and `@starting-style` emission on top of the opt-in cross-document fade shipped in 0.16.0 (see Stage 4).
+- **View transitions:** named/typed transitions (`view-transition-name`, per-element morphs) and `@starting-style` emission, on top of the directional fade + speculation-rules prerender shipped in 0.18.0 (see Stage 4 / Stage 14).
 - Richer diagnostics and package-consumer QA in regular CI. Editor tooling exists as a source-installable VS Code extension; public Marketplace/Open VSX distribution remains a launch/distribution follow-up.
 
 ## Current claim

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/darkmown",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -42,13 +42,14 @@
     "node": ">=20"
   },
   "dependencies": {
+    "image-size": "^1.2.1",
     "markdown-it": "^14.2.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.49.0",
     "@types/markdown-it": "^14.1.2",
-    "@types/node": "^22.19.21",
-    "typescript": "^5.9.3"
+    "@types/node": "^26.0.0",
+    "typescript": "^6.0.3"
   },
   "repository": {
     "type": "git",

package/site/_/nav.wd

@@ -6,6 +6,7 @@
   <a href="/reactive/">Reactive</a>
   <a href="/loops/">Loops</a>
   <a href="/store/">Store</a>
+  <a href="/theme/">Theme</a>
   <a href="/data/">Data &amp; Forms</a>
   <a href="/app/">Live app</a>
 </nav>

package/site/pages/data.wd

@@ -1,5 +1,6 @@
 ---
 title: Data, forms, and persistence
+transitions: true
 ---
 
 @include /nav.wd

package/site/pages/docs/index.wd

@@ -1,6 +1,7 @@
 ---
 title: Darkmown docs
 description: Learn Darkmown routing, directives, state, loops, forms, and the static-to-reactive model.
+transitions: true
 ---
 
 @include /nav.wd
@@ -164,6 +165,14 @@ tags: [sales, revenue, "q1, q2"]
 
 `{ meta.title }` prints a scalar and `{ meta.tags }` joins an array with `, `. You can loop a frontmatter array at build time — `@loop meta.tags into tag` — and the page stays static. Arrays are inline flow only (`[a, b]`); quoted items keep their commas.
 
+## Instant navigation
+
+Add `transitions: true` to a page's frontmatter for **instant, flash-free navigation** — zero JavaScript. It emits a directional fade+slide view transition for the page swap and a `<script type="speculationrules">` prerender hint, so the browser renders the next same-origin page on hover/pointerdown and the click activates an already-painted page (no white render-gap). It honors `prefers-reduced-motion`, and only same-origin pages that both opt in transition. Off by default; opt out with `transitions: false`, or exclude a single link from prerendering with `{.no-prefetch}`. (Chrome turns prerendering off while DevTools is open — test the built site with DevTools closed.)
+
+## Images
+
+You don't size images by hand. Every `<img>` the compiler emits gets its intrinsic `width`/`height` read from the source file (so the page doesn't reflow as images decode), `decoding="async"`, and a priority split — the first image stays eager with `fetchpriority="high"`, the rest `loading="lazy"`. Anything you set yourself wins. The compiler measures, it doesn't resize, so keep source images web-sized.
+
 ## Sections
 
 `::: section #id .class` opens a container and `:::` closes it. Sections scope state: a `:state` declared inside a section belongs to that section, so two sections can both declare `count` without colliding. Bindings and buttons resolve to the nearest scope.

package/site/pages/index.wd

@@ -2,6 +2,7 @@
 title: Darkmown — Markdown that runs, not Markdown that needs React
 description: A live store widget — search filter, add-to-cart, running total — written as one Markdown file that runs. The same outcome in Markdoc needs a React component, hydration, and a build step. Compare them side by side.
 image: https://darkmown.com/__wd/media/og.png
+transitions: true
 ---
 
 @include /nav.wd

package/site/pages/loops.wd

@@ -1,5 +1,6 @@
 ---
 title: Loop ergonomics
+transitions: true
 ---
 
 @include /nav.wd
@@ -83,4 +84,26 @@ No sort key needed — `reverse` walks the list back to front:
 - { r.label }
 @endloop
 
+## Nested reactive loops
+
+*New in 0.19.0.* A reactive `@loop` can hold an inner reactive `@loop` over a
+field of the outer row — one level of nesting. Type to filter the teams: the
+outer list re-filters live and every team keeps its own member list.
+
+:state teams = [{"id": 1, "name": "Platform", "members": [{"id": 11, "name": "Ada"}, {"id": 12, "name": "Bao"}]}, {"id": 2, "name": "Growth", "members": [{"id": 21, "name": "Cyrus"}, {"id": 22, "name": "Dax"}]}, {"id": 3, "name": "Research", "members": [{"id": 31, "name": "Esme"}]}]
+:state teamQuery = ""
+
+:bind teamQuery placeholder="Filter teams…"
+
+@loop teams into team where team.name contains teamQuery
+::: card .person-row
+**{ team.name }**
+@loop team.members into member
+- { member.name }
+@endloop
+:::
+@empty
+No teams match.
+@endloop
+
 </main>

package/site/pages/markdown.md

@@ -1,5 +1,6 @@
 ---
 title: Plain Markdown
+transitions: true
 ---
 
 # Plain Markdown stays plain

package/site/pages/reactive.wd

@@ -1,5 +1,6 @@
 ---
 title: Reactive Markdown
+transitions: true
 ---
 
 @include /nav.wd

package/site/pages/store.wd

@@ -1,5 +1,6 @@
 ---
 title: Global store
+transitions: true
 ---
 
 @include /nav.wd

package/site/pages/theme.skin

@@ -0,0 +1,53 @@
+tokens
+  ink #1a1a1a
+  paper #ffffff
+  panel #ffffff
+  line #dedbd3
+  accent #16645a
+  radius 8px
+
+tokens dark
+  ink #f0f0f0
+  paper #14140f
+  panel #1e1d18
+  line #34322b
+  accent #5fd0c0
+
+page
+  margin 0
+  font ui-serif, Georgia, Cambria, serif
+  color $ink
+  bg $paper
+  line-height 1.7
+
+main
+  max-width 820px
+  margin 0 auto
+  padding 3rem 2rem 5rem
+
+h1
+  font-size 3rem
+  line-height 1
+
+h2
+  margin-top 2.4rem
+  border-top 1px solid $line
+  padding-top 1.2rem
+
+a
+  color $accent
+
+pre
+  bg $panel
+  border 1px solid $line
+  padding 1rem
+  radius $radius
+  overflow-x auto
+
+.swatch
+  border 1px solid $line
+  bg $panel
+  color $ink
+  padding 1.4rem
+  margin 1.5rem 0
+  radius $radius

package/site/pages/theme.wd

@@ -0,0 +1,58 @@
+---
+title: Dark-mode tokens
+transitions: true
+---
+
+@include /nav.wd
+
+<main>
+
+# Dark-mode tokens
+
+Darkmown skins get automatic, OS-driven theming with **zero JavaScript**. Declare
+your design tokens once under `tokens`, then declare the dark overrides under
+`tokens dark`. The light values land on `:root`; the dark values compile to a
+`prefers-color-scheme: dark` media query over the same custom properties.
+
+```
+tokens
+  ink #1a1a1a
+  paper #ffffff
+tokens dark
+  ink #f0f0f0
+  paper #14140f
+```
+
+Every `$ink` / `$paper` reference keeps working unchanged — the variables simply
+resolve to their dark values when the operating system asks for dark mode.
+
+## See it live
+
+This page's `theme.skin` uses exactly that pattern. Switch your OS (or browser)
+appearance between light and dark and watch the panel below recolor itself — no
+toggle, no runtime, no flash.
+
+::: card .swatch
+The card surface, border, ink, and accent below are all driven by `tokens` plus
+a `tokens dark` override. Nothing on this page ships framework JavaScript.
+:::
+
+[A link tinted with the accent token](/docs/) sits in the same scope, so it
+recolors with the theme too.
+
+## Manual toggle (optional variant)
+
+For an author who wants an explicit switch instead of (or alongside) the OS
+preference, a bracketed modifier scopes the same tokens to a `:root` attribute:
+
+```
+tokens [data-theme=dark]
+  ink #f0f0f0
+  paper #14140f
+```
+
+That compiles to `:root[data-theme="dark"] { … }`, so setting `data-theme="dark"`
+on the document root flips the palette — pair it with your own toggle when you
+need manual control.
+
+</main>

package/src/builder.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { compilePage } from "./compiler.js";
 import { createPaths } from "./config.js";
+import { BASE_SECURITY_HEADERS, REACTIVE_CSP, STATIC_CSP } from "./headers.js";
 import { discoverRoutes, outputPathForRoute } from "./router.js";
 import { compileSkin } from "./skin.js";
 
@@ -72,6 +73,12 @@ export function buildSite(cwd = process.cwd()) {
 
   fs.writeFileSync(path.join(paths.distRoot, "routes.json"), JSON.stringify(manifest, null, 2));
 
+  // Cloudflare Pages reads dist/_headers for security headers (Vercel reads
+  // vercel.json; the local server adds them in src/statics.js). Static routes
+  // get the stricter CSP (no 'unsafe-eval'); reactive routes get the relaxed
+  // one. A catch-all keeps assets and any future path covered.
+  fs.writeFileSync(path.join(paths.distRoot, "_headers"), renderCloudflareHeaders(manifest));
+
   // Page-colocated static assets (images, SVG, fonts, …) copy last, so the guard
   // sees every emitted route/framework file already on disk.
   emitPageAssets(paths);
@@ -103,6 +110,49 @@ export function stripRuntimeComments(source) {
     .replace(/^[ \t]*\n/gm, "");
 }
 
+/**
+ * Render the Cloudflare Pages `_headers` file from the route manifest.
+ *
+ * Cloudflare applies every matching block in order; when blocks set the same
+ * header, the later block wins. So we emit the catch-all `/*` first (baseline
+ * security headers + the relaxed reactive CSP that satisfies every page), then
+ * one block per static route that overrides `Content-Security-Policy` with the
+ * stricter, eval-free CSP. Reactive routes need no override — the catch-all
+ * already carries the relaxed CSP.
+ *
+ * Clean URLs mean a route like `/docs/` is served at both `/docs` and `/docs/`,
+ * so each static route emits a path glob (`/docs`, `/docs/*`) that covers both.
+ * @param {RouteManifestEntry[]} manifest
+ * @returns {string}
+ */
+export function renderCloudflareHeaders(manifest) {
+  const baseLines = Object.entries(BASE_SECURITY_HEADERS).map(([name, value]) => `  ${name}: ${value}`);
+  const blocks = [
+    ["/*", [...baseLines, `  Content-Security-Policy: ${REACTIVE_CSP}`]]
+  ];
+
+  for (const entry of manifest) {
+    if (entry.assets.runtime) continue; // reactive routes keep the catch-all (relaxed) CSP
+    for (const pattern of cloudflarePathPatterns(entry.route)) {
+      blocks.push([pattern, [`  Content-Security-Policy: ${STATIC_CSP}`]]);
+    }
+  }
+
+  return `${blocks.map(([pattern, lines]) => [pattern, ...lines].join("\n")).join("\n\n")}\n`;
+}
+
+/**
+ * Cloudflare `_headers` path patterns covering a clean-URL route. `/` →
+ * `["/", "/index.html"]`; `/docs/` → `["/docs", "/docs/*"]`.
+ * @param {string} route Route path from the manifest (always trailing-slashed).
+ * @returns {string[]}
+ */
+function cloudflarePathPatterns(route) {
+  if (route === "/") return ["/", "/index.html"];
+  const trimmed = route.replace(/\/$/, ""); // "/docs/" -> "/docs"
+  return [trimmed, `${trimmed}/*`];
+}
+
 /**
  * A minimal, zero-JS fallback 404 page used only when no `404.wd` route exists.
  * @returns {string}