@zvndev/darkmown 0.18.0 → 0.20.0

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to Darkmown are documented here. Versions follow [semver](https://semver.org); pre-1.0 minor versions may contain breaking changes.
 
+## 0.20.0 — 2026-06-26
+
+Engineering hardening: a real programmatic API, plus a gold-standard pass on tooling, tests, and internals. No behavior change for existing sites — the runtime is byte-for-byte the same (~5.8 KB gzipped).
+
+- **Programmatic API.** `@zvndev/darkmown` now ships a proper entry point: `import { buildSite, compilePage, compileDocument, parseFrontmatter, escapeHtml, … } from "@zvndev/darkmown"` resolves through an `exports` map and a `src/index.js` barrel that mirrors the public surface already declared in `types/index.d.ts`. The package was CLI-only before; the `darkmown` CLI is unchanged.
+- **Compiler internals split.** The ~2,900-line `src/compiler.js` is now a `src/compiler/` folder along its existing seams (page shell, frontmatter, includes, interpolation, predicates, markdown plugin, loops, directives, body). Public exports and output are identical — `src/compiler.js` stays as a thin re-export barrel. Purely internal.
+- **Sharper compile errors.** Malformed-directive errors now report `file:line` (matching the unclosed-block errors that already did), and action-literal failures name the offending page. Easier to trace a mistake back to its source.
+- **Lint + format with Biome.** Added Biome (one binary, lint + format) with `npm run lint` / `npm run format:check`, a `lint` CI job, and a husky + lint-staged pre-commit that checks staged files. `src/runtime.js` is excluded from the formatter so the byte budget is never moved by a reformat. Style commands are documented in CONTRIBUTING.md.
+- **100% line coverage, CI-gated.** The test suite now covers every line of `src/`, and the coverage gate is raised from 90% to 100%. Covering the CLI and dev-server paths surfaced and fixed two real bugs: symlinked-bin entry-point detection and a dev-server response that wrote headers before reading the file.
+- **Runtime size trend.** A committed `.size-snapshot.json` baseline lets CI report the gzipped-runtime delta on every change, alongside the existing hard < 6 KB gate.
+- **Fixed a production-breaking `vercel.json`.** An invalid `comment` property was rejected by Vercel's strict schema and failed every deploy before install; removed, with a regression test that rejects any non-allowlisted key in a `headers[]` rule.
+
+## 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.

package/README.md

@@ -7,7 +7,7 @@
 
 **[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 ~5.7 KB gzipped, CI-enforced under 6 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 ~5.8 KB gzipped, CI-enforced under 6 KB.
 
 ## Quick start
 
@@ -52,7 +52,7 @@ 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 ~5.7 KB gzipped, CI-enforced under 6 KB).
+- Static pages ship zero Darkmown runtime. Reactive pages share `/__wd/runtime.js` (currently ~5.8 KB gzipped, CI-enforced under 6 KB).
 - Shelf `.json` files are published at `/__wd/data/` so `:fetch` works on any static host.
 
 ## Interpolation
@@ -240,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
@@ -528,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`.
@@ -548,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

@@ -84,6 +84,15 @@ Three capability gaps from the 2026-06-16 audit, closed together over a shared `
 - **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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/darkmown",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -10,26 +10,41 @@
   "bin": {
     "darkmown": "./src/cli.js"
   },
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./package.json": "./package.json"
+  },
   "types": "./types/index.d.ts",
   "scripts": {
     "build": "node src/cli.js build",
     "runtime:size": "node -e \"const fs=require('fs'),zlib=require('zlib'); const size=zlib.gzipSync(fs.readFileSync('dist/__wd/runtime.js')).length; console.log('shipped runtime gzipped: '+size+' bytes (budget: 6144)'); if (size >= 6144) process.exit(1)\"",
     "dev": "node src/cli.js dev",
     "test": "node --test tests/*.test.js",
-    "test:cov": "node scripts/test-coverage-gate.mjs 90",
+    "test:cov": "node scripts/test-coverage-gate.mjs 100",
     "test:e2e": "playwright test",
     "test:extension": "npm --prefix editors/vscode ci && npm --prefix editors/vscode test",
     "pack:extension": "cd editors/vscode && npx --yes @vscode/vsce package",
     "typecheck": "tsc --noEmit",
     "types": "tsc -p tsconfig.types.json",
     "smoke": "node scripts/smoke-consumer.mjs",
+    "lint": "biome check .",
+    "format": "biome format --write .",
+    "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",
-    "prepublishOnly": "npm run prepublish:check"
+    "prepublishOnly": "npm run prepublish:check",
+    "og": "node scripts/og-image.mjs"
+  },
+  "lint-staged": {
+    "*.{js,json}": "biome check --no-errors-on-unmatched --files-ignore-unknown=true"
   },
   "files": [
     "src",
     "types",
     "site",
+    "!site/_/og.png",
     "docs/cli.md",
     "docs/spec-alignment.md",
     "AGENTS.md",
@@ -46,10 +61,13 @@
     "markdown-it": "^14.2.0"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.5.1",
     "@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",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.4.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/loops.wd

@@ -84,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/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";
 
@@ -59,7 +60,9 @@ export function buildSite(cwd = process.cwd()) {
       file: path.relative(cwd, route.file).replaceAll(path.sep, "/"),
       assets: {
         skins: [...page.assets.skins],
-        scripts: page.assets.runtime ? ["/__wd/runtime.js", ...page.assets.scripts] : [...page.assets.scripts],
+        scripts: page.assets.runtime
+          ? ["/__wd/runtime.js", ...page.assets.scripts]
+          : [...page.assets.scripts],
         runtime: page.assets.runtime
       }
     });
@@ -72,6 +75,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);
@@ -94,13 +103,58 @@ export function buildSite(cwd = process.cwd()) {
  * @returns {string}
  */
 export function stripRuntimeComments(source) {
-  return source
-    // JSDoc blocks — type annotations the browser never needs.
-    .replace(/\/\*\*[\s\S]*?\*\//g, "")
-    // Whole-line `//` comments — developer notes that don't belong in the download.
-    .replace(/^[ \t]*\/\/.*$/gm, "")
-    // Drop the now blank/whitespace-only lines the removals leave behind.
-    .replace(/^[ \t]*\n/gm, "");
+  return (
+    source
+      // JSDoc blocks — type annotations the browser never needs.
+      .replace(/\/\*\*[\s\S]*?\*\//g, "")
+      // Whole-line `//` comments — developer notes that don't belong in the download.
+      .replace(/^[ \t]*\/\/.*$/gm, "")
+      // Drop the now blank/whitespace-only lines the removals leave behind.
+      .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}/*`];
 }
 
 /**
@@ -119,7 +173,7 @@ function defaultNotFoundHtml() {
     "<body>",
     "<main>",
     "<h1>Page not found</h1>",
-    "<p>That route does not exist. <a href=\"/\">Back to home</a>.</p>",
+    '<p>That route does not exist. <a href="/">Back to home</a>.</p>',
     "</main>",
     "</body>",
     "</html>",
@@ -193,7 +247,9 @@ function emitPageAssets(paths) {
     if (hasHiddenPathSegment(rel) || fs.lstatSync(file).isSymbolicLink()) continue;
     const out = path.join(paths.distRoot, rel);
     if (fs.existsSync(out)) {
-      console.warn(`hint: page asset "${rel}" skipped — a built route already emits /${rel.replaceAll(path.sep, "/")}`);
+      console.warn(
+        `hint: page asset "${rel}" skipped — a built route already emits /${rel.replaceAll(path.sep, "/")}`
+      );
       continue;
     }
     fs.mkdirSync(path.dirname(out), { recursive: true });