@zvndev/darkmown 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 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.

package/README.md

@@ -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.19.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -48,8 +48,8 @@
   "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/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";
 
@@ -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}

package/src/compiler.js

@@ -327,6 +327,7 @@ function compileFile(file, context, stack, scope, comp, sections, loopItem) {
 
   const raw = fs.readFileSync(file, "utf8");
   const { meta, body } = parseFrontmatter(raw, file);
+  warnLikelyFrontmatter(raw, file, comp);
   collectColocatedAssets(file, context, comp.assets);
 
   if (path.extname(file) === ".md") {
@@ -365,6 +366,37 @@ export function parseFrontmatter(raw, file) {
   return { meta, body };
 }
 
+/**
+ * Warn (non-fatal) when a file looks like it MEANT to open frontmatter but forgot
+ * the leading `---`: the first content line is a `key: value` pair and a bare
+ * `---` fence appears within the opening lines. Conservative — a normal markdown
+ * body whose first line happens to contain a colon (with no early `---`) is left
+ * alone, since `---` is also a valid horizontal rule.
+ * @param {string} raw
+ * @param {string} file
+ * @param {Compilation} comp
+ * @returns {void}
+ */
+function warnLikelyFrontmatter(raw, file, comp) {
+  if (raw.startsWith("---\n")) return; // a real opener: parseFrontmatter handled it
+  const lines = raw.replace(/\r\n?/g, "\n").split("\n");
+  let i = 0;
+  while (i < lines.length && !lines[i].trim()) i++; // skip leading blanks
+  if (i >= lines.length || !/^[A-Za-z][\w-]*:\s*\S/.test(lines[i])) return;
+  // Only warn when the run of lines up to a bare `---` is ALL `key: value` pairs:
+  // a forgotten opener, not prose that merely contains a colon and a later rule.
+  for (let j = i; j < lines.length && j < i + 12; j++) {
+    const t = lines[j].trim();
+    if (t === "---") {
+      comp.warnings.push(
+        `${file}: this looks like frontmatter missing its opening "---". Use: a "---" line before the fields (and another "---" to close) — otherwise the block renders as page text.`
+      );
+      return;
+    }
+    if (t && !/^[A-Za-z][\w-]*:\s*\S/.test(t)) return; // hit prose → not frontmatter
+  }
+}
+
 // Frontmatter values are scalars, except an inline flow array `[a, b, c]`.
 // Block sequences (`- item` on following lines) are intentionally out of scope —
 // the parser stays single-pass and line-based.
@@ -571,6 +603,7 @@ function compileBody(lines, ctx) {
     if (/^(@endloop|:endif|:endfor|:endform|:else)\s*$/.test(line)) {
       throw new Error(`Stray "${line.trim()}" with no matching opener in ${ctx.file}`);
     }
+    warnUnknownDirective(line, ctx);
     prose.push(line);
   }
 
@@ -578,6 +611,44 @@ function compileBody(lines, ctx) {
   return out.join("\n");
 }
 
+// Lines that reached prose but LOOK like a directive (a `@word`/`:word` token at
+// the very start, followed by a space or end of line) and match no handler are
+// almost always a typo — every real directive was intercepted above. Warn, never
+// throw: prose legitimately contains `@` and `:`, so the match is deliberately
+// narrow (lowercase token + boundary; emoji shortcodes, times, and `@user`
+// followed by punctuation do not match).
+const KNOWN_DIRECTIVE =
+  /^(?:@(?:include|loop|empty|endloop)|:(?:state|store|fetch|computed|effect|form|endform|input|textarea|select|checkbox|radio|bind|submit|button|if|endif|else|try|note|sprint))(?:\s|$)/;
+/**
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @returns {void}
+ */
+function warnUnknownDirective(line, ctx) {
+  // Catch capitalized (`:State`) and hyphenated (`:end-loop`) typos too — the
+  // known-directive whitelist stays case-sensitive, so a mis-cased real
+  // directive correctly trips the warning. Still unindented-only, to keep prose
+  // that legitimately starts lines with `@`/`:` from false-positiving.
+  const m = line.match(/^([@:][A-Za-z][A-Za-z-]*)(?:\s|$)/);
+  if (m && !KNOWN_DIRECTIVE.test(line)) {
+    ctx.comp.warnings.push(
+      `${ctx.file}: "${m[1]}" looks like a directive but matches none — it will render as literal text. Check the spelling (e.g. @loop, @include, :state, :if).`
+    );
+  }
+}
+
+/**
+ * Format a source location as `file:line` (1-based) for compile errors. Keeps the
+ * file path intact so existing message matchers still pass, while pointing at the
+ * unclosed opener's line.
+ * @param {string} file
+ * @param {number} index 0-based line index of the opener.
+ * @returns {string}
+ */
+function at(file, index) {
+  return `${file}:${index + 1}`;
+}
+
 /**
  * Capture lines from an opener until a matching close token, honoring nesting and fences.
  * @param {string[]} lines
@@ -612,7 +683,7 @@ function scanBlock(lines, start, openRe, endToken, file) {
     }
     body.push(line);
   }
-  throw new Error(`Missing ${endToken} for "${lines[start]}" in ${file}`);
+  throw new Error(`Missing ${endToken} for "${lines[start]}" in ${at(file, start)}`);
 }
 
 /**
@@ -683,7 +754,7 @@ function scanContainer(lines, start, file) {
     }
     body.push(line);
   }
-  throw new Error(`Missing closing ::: for "${lines[start]}" in ${file}`);
+  throw new Error(`Missing closing ::: for "${lines[start]}" in ${at(file, start)}`);
 }
 
 /**
@@ -752,7 +823,7 @@ function scanConditional(lines, start, file) {
     }
     current.push(line);
   }
-  throw new Error(`Missing :endif for "${lines[start]}" in ${file}`);
+  throw new Error(`Missing :endif for "${lines[start]}" in ${at(file, start)}`);
 }
 
 // ---------------------------------------------------------------------------
@@ -1637,6 +1708,11 @@ function handleLoop(line, bodyLines, emptyLines, ctx) {
       const fullKey = segs.length > 1 ? `${key}.${segs.slice(1).join(".")}` : key;
       return reactiveLoop(fullKey, itemName, bodyLines, ctx, opts);
     }
+    // Inside a reactive loop, `@loop <outerItem>.<path> into x` loops a field of
+    // the enclosing row item — an ITEM-RELATIVE loop the runtime fills per row.
+    if (ctx.loopItem && segs[0] === ctx.loopItem && segs.length > 1) {
+      return itemRelativeLoop(segs.slice(1).join("."), itemName, bodyLines, ctx, opts);
+    }
   }
 
   throw new Error(
@@ -1911,15 +1987,7 @@ function reactiveLoop(key, itemName, bodyLines, ctx, opts = null) {
   const templateCtx = { ...ctx, loopItem: itemName, loopKey: key ?? undefined, loopMeta: true, scope: createScope(ctx.scope) };
   const templateHtml = compileBody(bodyLines, templateCtx).trim();
 
-  let wrapperTag = "div";
-  let itemTemplate = templateHtml;
-  const listMatch = templateHtml.match(/^<(ul|ol)>\s*([\s\S]*?)\s*<\/\1>$/);
-  if (listMatch && (listMatch[2].match(/<li>/g) || []).length === 1) {
-    wrapperTag = listMatch[1];
-    itemTemplate = listMatch[2].trim();
-  } else {
-    itemTemplate = `<div data-wd-loop-piece>${templateHtml}</div>`;
-  }
+  const { wrapperTag, itemTemplate } = wrapRowTemplate(templateHtml);
 
   const where = opts?.where || null;
   const sort = opts?.sort || null;
@@ -1941,27 +2009,132 @@ function reactiveLoop(key, itemName, bodyLines, ctx, opts = null) {
   /** @type {Map<string, number>} */
   const counts = new Map();
   const count = rows.length;
+  // Inner ITEM-RELATIVE loop regions are filled per row by the runtime, not at
+  // build time; mask them so the outer initial-paint string fill leaves their
+  // pristine <template>/empty-out markup untouched, then restore.
+  const { masked, regions } = maskItemLoops(itemTemplate);
   const initial = rows
     .map((/** @type {unknown} */ item, i) => {
       const itemKey = loopKeyOf(item, counts);
       const meta = { index: i, number: i + 1, first: i === 0, last: i === count - 1, count };
-      return fillTemplateString(withLoopKey(itemTemplate, itemKey), item, meta);
+      return unmaskItemLoops(fillTemplateString(withLoopKey(masked, itemKey), item, meta), regions);
     })
     .join("");
 
-  const emptyTemplate = emptyLines ? `<template data-wd-loop-empty>${compileBody(emptyLines, { ...ctx, loopMeta: true }).trim()}</template>` : "";
+  const emptyTemplate = loopEmptyTemplate(emptyLines, ctx);
   const initialOut = count === 0 && emptyLines ? compileBody(emptyLines, { ...ctx, loopMeta: true }).trim() : initial;
 
-  const attrs =
-    (where ? ` data-wd-loop-where="${escapeHtml(where.body)}"` : "") +
-    (sort ? ` data-wd-loop-sort="${escapeHtml(sort.key)}" data-wd-loop-sort-dir="${sort.dir}"` : "") +
-    (reverse ? ` data-wd-loop-reverse` : "") +
-    (offset ? ` data-wd-loop-offset="${numArgAttr(offset)}"` : "") +
-    (limit ? ` data-wd-loop-limit="${numArgAttr(limit)}"` : "") +
+  const attrs = loopClauseAttrs({ where, sort, reverse, offset, limit }) +
     (baked ? ` data-wd-loop-data="${escapeHtml(JSON.stringify(baked))}"` : "");
   return `<div data-wd-loop="${escapeHtml(key || "")}"${attrs}><template data-wd-loop-template>${itemTemplate}</template>${emptyTemplate}<${wrapperTag} data-wd-loop-out>${initialOut}</${wrapperTag}></div>`;
 }
 
+/**
+ * Unwrap a compiled row body into a wrapper tag + row template. A body that is a
+ * single-`<li>` `<ul>`/`<ol>` becomes an `<li>` row under that list wrapper;
+ * anything else is wrapped in a `<div data-wd-loop-piece>` under a `<div>`. Shared
+ * by top-level reactive loops and item-relative (nested) loops.
+ * @param {string} templateHtml
+ * @returns {{ wrapperTag: string, itemTemplate: string }}
+ */
+function wrapRowTemplate(templateHtml) {
+  const listMatch = templateHtml.match(/^<(ul|ol)>\s*([\s\S]*?)\s*<\/\1>$/);
+  if (listMatch && (listMatch[2].match(/<li>/g) || []).length === 1) {
+    return { wrapperTag: listMatch[1], itemTemplate: listMatch[2].trim() };
+  }
+  return { wrapperTag: "div", itemTemplate: `<div data-wd-loop-piece>${templateHtml}</div>` };
+}
+
+/**
+ * Compile an `@empty` branch body into a `<template data-wd-loop-empty>` (or "" when
+ * there is no empty branch). Shared by top-level and item-relative loops.
+ * @param {string[] | null} emptyLines
+ * @param {Ctx} ctx
+ * @returns {string}
+ */
+function loopEmptyTemplate(emptyLines, ctx) {
+  return emptyLines ? `<template data-wd-loop-empty>${compileBody(emptyLines, { ...ctx, loopMeta: true }).trim()}</template>` : "";
+}
+
+/**
+ * Serialize the shared `where`/`sort`/`reverse`/`offset`/`limit` clause config to
+ * the `data-wd-loop-*` attribute string consumed by the runtime pipeline. Shared
+ * by top-level reactive loops and item-relative (nested) loops.
+ * @param {Pick<LoopOpts, "where" | "sort" | "reverse" | "offset" | "limit">} c
+ * @returns {string}
+ */
+function loopClauseAttrs(c) {
+  return (
+    (c.where ? ` data-wd-loop-where="${escapeHtml(c.where.body)}"` : "") +
+    (c.sort ? ` data-wd-loop-sort="${escapeHtml(c.sort.key)}" data-wd-loop-sort-dir="${c.sort.dir}"` : "") +
+    (c.reverse ? ` data-wd-loop-reverse` : "") +
+    (c.offset ? ` data-wd-loop-offset="${numArgAttr(c.offset)}"` : "") +
+    (c.limit ? ` data-wd-loop-limit="${numArgAttr(c.limit)}"` : "")
+  );
+}
+
+/**
+ * Emit ONE level of nested reactive loop: a `@loop <outerItem>.<path> into x`
+ * whose rows are read off the enclosing loop row at runtime. The region carries
+ * its own row <template> + clause config but, unlike a top-level loop, its source
+ * is the relative `path` (not a global state key) — `fillItem` resolves the rows
+ * off the current outer item and reconciles per row. The output starts empty; the
+ * runtime fills it on first render (the page already ships the runtime).
+ * @param {string} path Dotted sub-path off the outer item (e.g. `items`).
+ * @param {string} itemName Inner loop item name.
+ * @param {string[]} bodyLines Inner loop body.
+ * @param {Ctx} ctx
+ * @param {Partial<LoopOpts>} opts
+ * @returns {string}
+ */
+function itemRelativeLoop(path, itemName, bodyLines, ctx, opts) {
+  /** @type {Ctx} */
+  // loopKey: undefined — an item-relative loop's source is a path off the outer
+  // row, not a top-level state key, so a per-row `remove` inside it has no valid
+  // target and must be rejected (rather than inheriting the outer loop's key).
+  const templateCtx = { ...ctx, loopItem: itemName, loopKey: undefined, loopMeta: true, scope: createScope(ctx.scope) };
+  const templateHtml = compileBody(bodyLines, templateCtx).trim();
+
+  const { wrapperTag, itemTemplate } = wrapRowTemplate(templateHtml);
+
+  const emptyTemplate = loopEmptyTemplate(opts.empty || null, ctx);
+  const attrs = loopClauseAttrs({ where: opts.where || null, sort: opts.sort || null, reverse: opts.reverse || false, offset: opts.offset || null, limit: opts.limit || null });
+  return `<div data-wd-loop-item="${escapeHtml(path)}"${attrs}><template data-wd-loop-template>${itemTemplate}</template>${emptyTemplate}<${wrapperTag} data-wd-loop-out></${wrapperTag}></div>`;
+}
+
+/**
+ * Replace each top-level `data-wd-loop-item` region in a row template with an
+ * opaque placeholder so the outer initial-paint string fill cannot reach inside
+ * its pristine markup. Returns the masked string and the excised regions in order.
+ * @param {string} template
+ * @returns {{ masked: string, regions: string[] }}
+ */
+function maskItemLoops(template) {
+  const marker = "<div data-wd-loop-item=";
+  /** @type {string[]} */
+  const regions = [];
+  let masked = "";
+  let i = 0;
+  for (;;) {
+    const start = template.indexOf(marker, i);
+    if (start === -1) return { masked: masked + template.slice(i), regions };
+    const end = matchElement(template, start, "div");
+    masked += template.slice(i, start) + `\x00WDLI${regions.length}\x00`;
+    regions.push(template.slice(start, end));
+    i = end;
+  }
+}
+
+/**
+ * Restore the masked `data-wd-loop-item` regions into a filled row string.
+ * @param {string} str
+ * @param {string[]} regions
+ * @returns {string}
+ */
+function unmaskItemLoops(str, regions) {
+  return regions.length ? str.replace(/\x00WDLI(\d+)\x00/g, (_, n) => regions[Number(n)]) : str;
+}
+
 /**
  * @param {string} template
  * @param {string} itemKey
@@ -2507,7 +2680,13 @@ function parseSingleAction(expression, raw, ctx) {
   if (remove) {
     const operand = remove[2].trim();
     if (ctx.loopItem && operand === ctx.loopItem) {
-      if (!ctx.loopKey || resolveStateKey(remove[1], ctx) !== ctx.loopKey) {
+      // A nested (item-relative) loop has a loop item but no top-level state key —
+      // its source is a path off the outer row, which the runtime's row-remove
+      // can't target. Fail loud with the honest workaround.
+      if (!ctx.loopKey) {
+        throw new Error(`Button action "${raw}" can't delete a row of a nested (item-relative) loop in ${ctx.file}. Per-row "remove" needs a top-level :state/:store list; carry the row into one (cart += ${ctx.loopItem}) and remove it there.`);
+      }
+      if (resolveStateKey(remove[1], ctx) !== ctx.loopKey) {
         throw new Error(`Button action "${raw}" must target the :state list being looped (@loop ${remove[1]} into ${ctx.loopItem}) in ${ctx.file}.`);
       }
       return { op: "remove", target: ctx.loopKey };

package/src/headers.js

@@ -0,0 +1,94 @@
+/**
+ * Security headers Darkmown emits on every delivery surface — the local
+ * `darkmown serve`/preview server (`src/statics.js`), Cloudflare Pages
+ * (`dist/_headers`, written by `src/builder.js`), and Vercel (`vercel.json`).
+ *
+ * `statics.js` and the generated `_headers` derive from the values here, so they
+ * never drift. `vercel.json` is the exception: Vercel reads it BEFORE the build
+ * runs, so its CSP strings and static-route list are hand-maintained copies, not
+ * build output. The `vercel-csp-routes` test cross-checks vercel.json against the
+ * built route manifest so a new static route can't silently miss the strict CSP.
+ *
+ * The CSP is derived from what the framework's own output actually emits
+ * (verify against built `dist/` HTML):
+ *   - External script `/__wd/runtime.js` (same-origin) on reactive pages.
+ *   - Inline `<script type="application/json" data-wd-state>` (state seed) and
+ *     inline `<script type="speculationrules">` (prerender) — JSON/speculation
+ *     blocks can't be nonce'd cleanly, so `script-src 'unsafe-inline'`.
+ *   - The reactive runtime compiles validated expressions via `new Function`,
+ *     so reactive pages additionally need `script-src 'unsafe-eval'`.
+ *   - Inline `<style>` for view transitions — `style-src 'unsafe-inline'`.
+ *   - `data:` favicon and remote images — `img-src 'self' data: https:`.
+ *
+ * Static pages (zero framework JS) still emit inline `<style>` and an inline
+ * `<script type="speculationrules">`, so they keep `'unsafe-inline'`, but they
+ * never call `new Function`, so their CSP drops `'unsafe-eval'`.
+ */
+
+/**
+ * `connect-src` for the demo is `'self'`: the framework's own pages only
+ * `:fetch` same-origin endpoints. Apps whose `:fetch` targets a remote host
+ * must widen this (e.g. to `connect-src 'self' https://api.example.com` or
+ * `connect-src *`) by editing their `vercel.json` / `_headers` / serve config.
+ * @type {string}
+ */
+const CONNECT_SRC = "connect-src 'self'";
+
+/**
+ * Directives shared by both the static and reactive CSP. Order is cosmetic.
+ * @type {string[]}
+ */
+const COMMON_CSP_DIRECTIVES = [
+  "default-src 'self'",
+  "style-src 'self' 'unsafe-inline'",
+  "img-src 'self' data: https:",
+  "font-src 'self'",
+  CONNECT_SRC,
+  "object-src 'none'",
+  "base-uri 'self'",
+  "frame-ancestors 'self'"
+];
+
+/**
+ * Relaxed CSP for reactive pages: `new Function` needs `'unsafe-eval'`, the
+ * inline state/speculationrules JSON needs `'unsafe-inline'`.
+ * @type {string}
+ */
+export const REACTIVE_CSP = [
+  "script-src 'self' 'unsafe-inline' 'unsafe-eval'",
+  ...COMMON_CSP_DIRECTIVES
+].join("; ");
+
+/**
+ * Stricter CSP for static pages: no runtime means no `new Function`, so
+ * `'unsafe-eval'` is dropped. Inline `<style>`/`<script type=speculationrules>`
+ * keep `'unsafe-inline'` on script/style.
+ * @type {string}
+ */
+export const STATIC_CSP = [
+  "script-src 'self' 'unsafe-inline'",
+  ...COMMON_CSP_DIRECTIVES
+].join("; ");
+
+/**
+ * Baseline security headers applied to every HTML response, independent of the
+ * CSP. CSP is added per-route (static vs reactive) by the helpers below.
+ * @type {Record<string, string>}
+ */
+export const BASE_SECURITY_HEADERS = {
+  "X-Content-Type-Options": "nosniff",
+  "Referrer-Policy": "strict-origin-when-cross-origin",
+  "X-Frame-Options": "SAMEORIGIN"
+};
+
+/**
+ * The full security-header set for one response, including the CSP variant.
+ * @param {boolean} reactive Whether the route ships the reactive runtime.
+ * @returns {Record<string, string>}
+ */
+export function securityHeaders(reactive) {
+  return {
+    ...BASE_SECURITY_HEADERS,
+    "Content-Security-Policy": reactive ? REACTIVE_CSP : STATIC_CSP
+  };
+}

package/src/runtime.js

@@ -246,9 +246,15 @@ function loopKeyOf(item, counts) {
  * @returns {void}
  */
 function fillItem(node, item, meta = {}) {
+  // Nested item-relative loops (data-wd-loop-item) own their descendants' binds;
+  // when present, `skip` excludes a node living inside one so the outer row's
+  // text/meta/each-if/class passes never overwrite an inner row's values.
+  const inners = node.querySelectorAll("[data-wd-loop-item]");
+  const skip = inners.length ? (/** @type {Element} */ el) => el.closest("[data-wd-loop-item]") : () => false;
   // querySelectorAll skips <template> content, so this sees only the outermost
   // regions; recursing into each injected branch fills the rest.
   for (const region of node.querySelectorAll("[data-wd-each-if]")) {
+    if (skip(region)) continue;
     const expr = region.getAttribute("data-wd-if-expr");
     const m = region.getAttribute("data-wd-meta");
     const value = expr ? evalPredicate(expr, item) : (m ? meta[m] : getPath(item, region.getAttribute("data-wd-path")));
@@ -262,13 +268,17 @@ function fillItem(node, item, meta = {}) {
     ? [node, ...node.querySelectorAll("[data-wd-each]")]
     : [...node.querySelectorAll("[data-wd-each]")];
   for (const target of targets) {
+    if (skip(target)) continue;
     target.textContent = getPath(item, target.getAttribute("data-wd-path")) ?? "";
   }
   for (const marker of node.querySelectorAll("[data-wd-each-meta]")) {
+    if (skip(marker)) continue;
     marker.textContent = meta[marker.getAttribute("data-wd-each-meta") || ""] ?? "";
   }
   const classNodes = node.matches("[data-wd-each-class]") ? [node, ...node.querySelectorAll("[data-wd-each-class]")] : [...node.querySelectorAll("[data-wd-each-class]")];
-  for (const el of classNodes) classToggle(el, el.getAttribute("data-wd-each-class"), item);
+  for (const el of classNodes) { if (!skip(el)) classToggle(el, el.getAttribute("data-wd-each-class"), item); }
+  // Reconcile nested loops last, against the now-settled outer row.
+  for (const region of inners) reconcile(region, getPath(item, region.getAttribute("data-wd-loop-item")));
 }
 
 /**
@@ -335,6 +345,75 @@ function renderIf(node) {
   for (const nested of output.querySelectorAll("[data-wd-if]")) renderIf(nested);
 }
 
+/**
+ * Reconcile one loop region (top-level or nested) from a resolved row source:
+ * filter (`where`) → pipeline (sort/reverse/offset/limit) → @empty → keyed
+ * reconcile. Each surviving row is `fillItem`-ed, which itself recurses into any
+ * nested item-relative loops. Shared by the global pass and `fillItem`.
+ * @param {Element} region
+ * @param {any} rows Source list (state-resolved globally; item-relative inside fillItem).
+ * @returns {void}
+ */
+function reconcile(region, rows) {
+  const template = /** @type {HTMLTemplateElement | null} */ (region.querySelector("template[data-wd-loop-template]"));
+  const out = region.querySelector("[data-wd-loop-out]");
+  if (!template || !out) return;
+  let list = Array.isArray(rows) ? rows.slice() : [];
+  const where = region.getAttribute("data-wd-loop-where");
+  if (where) {
+    const predicate = loopPredicate(where);
+    list = list.filter((/** @type {any} */ item) => {
+      try {
+        return predicate((/** @type {string | null} */ path) => getPath(item, path), (/** @type {string} */ k, /** @type {string} */ r) => getPath(state[k], r || ""), containsFn);
+      } catch (error) {
+        warn(where, error);
+        return false;
+      }
+    });
+  }
+  list = pipeline(list, region);
+
+  // Empty branch: clone the [data-wd-loop-empty] template into the output.
+  const emptyTpl = /** @type {HTMLTemplateElement | null} */ (region.querySelector("template[data-wd-loop-empty]"));
+  if (!list.length && emptyTpl) {
+    if (out.getAttribute("data-wd-empty") !== "1") {
+      out.textContent = "";
+      for (const child of [...emptyTpl.content.children]) out.appendChild(child.cloneNode(true));
+      out.setAttribute("data-wd-empty", "1");
+    }
+    return;
+  }
+  if (out.getAttribute("data-wd-empty") === "1") { out.textContent = ""; out.removeAttribute("data-wd-empty"); }
+
+  /** @type {Map<string, WdRow>} */
+  const existing = new Map();
+  for (const child of [...out.children]) {
+    existing.set(child.getAttribute("data-wd-loop-key") || "", /** @type {WdRow} */ (child));
+  }
+  /** @type {Map<string, number>} */
+  const counts = new Map();
+  /** @type {Set<string>} */
+  const used = new Set();
+  const count = list.length;
+  for (let i = 0; i < count; i++) {
+    const item = list[i];
+    const key = loopKeyOf(item, counts);
+    let node = existing.get(key);
+    if (!node || used.has(key)) {
+      node = /** @type {WdRow} */ (template.content.firstElementChild?.cloneNode(true));
+      if (!node) continue;
+      node.setAttribute("data-wd-loop-key", key);
+    }
+    used.add(key);
+    fillItem(node, item, { index: i, number: i + 1, first: i === 0, last: i === count - 1, count });
+    node.__wdItem = item; /** let per-row actions resolve which row was clicked */
+    out.appendChild(node);
+  }
+  for (const [key, node] of existing) {
+    if (!used.has(key)) node.remove();
+  }
+}
+
 /**
  * Synchronously render the whole document from current `state`:
  * computed → if-regions → keyed loop reconcile → text/input binds.
@@ -348,69 +427,14 @@ function renderNow() {
   // bindings (data-wd-each-class) are handled per item inside fillItem.
   for (const el of document.querySelectorAll("[data-wd-class]")) classToggle(el, el.getAttribute("data-wd-class"), undefined);
 
+  // Nested item-relative loops use data-wd-loop-item, so this top-level query
+  // skips them; fillItem reconciles those against their enclosing row.
   for (const region of document.querySelectorAll("[data-wd-loop]")) {
     const key = region.getAttribute("data-wd-loop");
     const data = region.getAttribute("data-wd-loop-data");
     /** Source may be a dotted path (e.g. team.members) read off state via getPath. */
     const dot = key ? key.indexOf(".") : -1;
-    const rows = key ? (dot < 0 ? state[key] : getPath(state[key.slice(0, dot)], key.slice(dot + 1))) : (data ? JSON.parse(data) : []);
-    const template = /** @type {HTMLTemplateElement | null} */ (region.querySelector("template[data-wd-loop-template]"));
-    const out = region.querySelector("[data-wd-loop-out]");
-    if (!template || !out) continue;
-    let list = Array.isArray(rows) ? rows.slice() : [];
-    const where = region.getAttribute("data-wd-loop-where");
-    if (where) {
-      const predicate = loopPredicate(where);
-      list = list.filter((/** @type {any} */ item) => {
-        try {
-          return predicate((/** @type {string | null} */ path) => getPath(item, path), (/** @type {string} */ k, /** @type {string} */ r) => getPath(state[k], r || ""), containsFn);
-        } catch (error) {
-          warn(where, error);
-          return false;
-        }
-      });
-    }
-    list = pipeline(list, region);
-
-    // Empty branch: clone the [data-wd-loop-empty] template into the output.
-    const emptyTpl = /** @type {HTMLTemplateElement | null} */ (region.querySelector("template[data-wd-loop-empty]"));
-    if (!list.length && emptyTpl) {
-      if (out.getAttribute("data-wd-empty") !== "1") {
-        out.textContent = "";
-        for (const child of [...emptyTpl.content.children]) out.appendChild(child.cloneNode(true));
-        out.setAttribute("data-wd-empty", "1");
-      }
-      continue;
-    }
-    if (out.getAttribute("data-wd-empty") === "1") { out.textContent = ""; out.removeAttribute("data-wd-empty"); }
-
-    /** @type {Map<string, WdRow>} */
-    const existing = new Map();
-    for (const child of [...out.children]) {
-      existing.set(child.getAttribute("data-wd-loop-key") || "", /** @type {WdRow} */ (child));
-    }
-    /** @type {Map<string, number>} */
-    const counts = new Map();
-    /** @type {Set<string>} */
-    const used = new Set();
-    const count = list.length;
-    for (let i = 0; i < count; i++) {
-      const item = list[i];
-      const key = loopKeyOf(item, counts);
-      let node = existing.get(key);
-      if (!node || used.has(key)) {
-        node = /** @type {WdRow} */ (template.content.firstElementChild?.cloneNode(true));
-        if (!node) continue;
-        node.setAttribute("data-wd-loop-key", key);
-      }
-      used.add(key);
-      fillItem(node, item, { index: i, number: i + 1, first: i === 0, last: i === count - 1, count });
-      node.__wdItem = item; /** let per-row actions resolve which row was clicked */
-      out.appendChild(node);
-    }
-    for (const [key, node] of existing) {
-      if (!used.has(key)) node.remove();
-    }
+    reconcile(region, key ? (dot < 0 ? state[key] : getPath(state[key.slice(0, dot)], key.slice(dot + 1))) : (data ? JSON.parse(data) : []));
   }
 
   for (const node of document.querySelectorAll("[data-wd-bind]")) {

package/src/skin.js

@@ -53,7 +53,16 @@ export function compileSkin(source) {
   /** @type {number | null} */
   let tokenIndent = null;
   /** @type {string[]} */
+  let tokenVars = [];
+  /** @type {string[]} */
   const rootVars = [];
+  /** @type {string[]} */
+  const darkVars = [];
+  // Manual-toggle variants: `tokens [data-theme=dark]` collects custom
+  // properties under an attribute-scoped `:root` so a `:store theme` toggle can
+  // flip them with no JS beyond writing the attribute.
+  /** @type {Map<string, string[]>} */
+  const attrVars = new Map();
 
   for (let i = 0; i < lines.length; i++) {
     const { indent, text } = lines[i];
@@ -61,14 +70,41 @@ export function compileSkin(source) {
     // the next line is indented deeper. Everything else is a declaration.
     const opensBlock = i + 1 < lines.length && lines[i + 1].indent > indent;
 
-    if (text === "tokens" && opensBlock) {
+    // `tokens` opens a design-token block emitting `:root { --name: value }`.
+    // An optional modifier picks a variant: `tokens dark` collects into a
+    // `prefers-color-scheme: dark` override (OS-driven), while a bracketed
+    // `tokens [data-theme=dark]` scopes the override to a `:root` attribute for
+    // manual toggling. Both reuse the same `--name` properties.
+    // Capture the whole modifier (`.+`, not `\S+`) so a malformed bracketed
+    // modifier with internal spaces (`[data-theme=dark extra]`) is still routed
+    // to normalizeAttr's null fail-safe rather than slipping through as a bogus
+    // `tokens …` selector.
+    const tokenMatch = /^tokens(?:\s+(.+))?$/.exec(text);
+    if (tokenMatch && opensBlock) {
       tokenIndent = indent;
+      const modifier = tokenMatch[1];
+      if (!modifier) {
+        tokenVars = rootVars;
+      } else if (modifier === "dark") {
+        tokenVars = darkVars;
+      } else if (modifier.startsWith("[") && modifier.endsWith("]")) {
+        const attr = normalizeAttr(modifier);
+        if (attr) {
+          const selector = `:root${attr}`;
+          tokenVars = attrVars.get(selector) ?? [];
+          attrVars.set(selector, tokenVars);
+        } else {
+          tokenVars = rootVars; // malformed `[…]` modifier → fall back to default :root tokens
+        }
+      } else {
+        tokenVars = rootVars;
+      }
       continue;
     }
 
     if (tokenIndent !== null && indent > tokenIndent) {
       const [name, ...rest] = text.split(/\s+/);
-      rootVars.push(`  --${name}: ${rest.join(" ")};`);
+      tokenVars.push(`  --${name}: ${rest.join(" ")};`);
       continue;
     }
 
@@ -96,10 +132,32 @@ export function compileSkin(source) {
     css.push(media ? `${media} { ${rule} }` : rule);
   }
 
+  // Prepend tokens ahead of selector rules. `unshift` reverses insertion order,
+  // so push the overrides first to land them after the `:root` defaults.
+  for (const [selector, vars] of attrVars) {
+    if (vars.length) css.unshift(`${selector} {\n${vars.join("\n")}\n}`);
+  }
+  if (darkVars.length) {
+    css.unshift(`@media (prefers-color-scheme: dark) {\n:root {\n${darkVars.join("\n")}\n}\n}`);
+  }
   if (rootVars.length) css.unshift(`:root {\n${rootVars.join("\n")}\n}`);
   return css.join("\n");
 }
 
+/**
+ * Normalize a bracketed token modifier into a valid attribute selector,
+ * quoting the value so `[data-theme=dark]` becomes `[data-theme="dark"]`.
+ * Returns null for a malformed modifier (`[]`, `[a=b c]`, injection-shaped
+ * input) so the caller can fall back to default `:root` tokens instead of
+ * emitting a junk selector.
+ * @param {string} bracketed
+ * @returns {string | null}
+ */
+function normalizeAttr(bracketed) {
+  const m = bracketed.match(/^\[\s*([^\]=\s]+)\s*=\s*"?([^\]"]*)"?\s*\]$/);
+  return m ? `[${m[1]}="${m[2]}"]` : null;
+}
+
 /**
  * Combine a selector with its parent (handles `&` nesting and comma lists).
  * @param {string} text

package/src/statics.js

@@ -1,6 +1,19 @@
 import fs from "node:fs";
 import http from "node:http";
 import path from "node:path";
+import { BASE_SECURITY_HEADERS, REACTIVE_CSP } from "./headers.js";
+
+/**
+ * Security headers for an HTML response from the local server. The relaxed
+ * (reactive) CSP is a superset that satisfies both static and reactive pages,
+ * so the runtime server uses it for every HTML response; the build-time
+ * outputs (`vercel.json`, `dist/_headers`) tighten static routes per-path.
+ * @type {Record<string, string>}
+ */
+const HTML_SECURITY_HEADERS = {
+  ...BASE_SECURITY_HEADERS,
+  "Content-Security-Policy": REACTIVE_CSP
+};
 
 /**
  * Serve a built file for a request URL out of `distRoot`, or a 404 page.
@@ -12,7 +25,7 @@ import path from "node:path";
 export function serve(distRoot, url, res) {
   const file = resolvePublicFile(distRoot, url || "/");
   if (!file || !fs.existsSync(file)) {
-    res.writeHead(404, { "content-type": "text/html; charset=utf-8" });
+    res.writeHead(404, { "content-type": "text/html; charset=utf-8", ...HTML_SECURITY_HEADERS });
     const notFound = path.join(distRoot, "404.html");
     if (fs.existsSync(notFound)) {
       res.end(fs.readFileSync(notFound));
@@ -21,7 +34,11 @@ export function serve(distRoot, url, res) {
     res.end("<h1>Not found</h1><p>This route is hidden or has not been created.</p>");
     return;
   }
-  res.writeHead(200, { "content-type": contentType(file) });
+  const type = contentType(file);
+  const headers = type.startsWith("text/html")
+    ? { "content-type": type, ...HTML_SECURITY_HEADERS }
+    : { "content-type": type };
+  res.writeHead(200, headers);
   fs.createReadStream(file).pipe(res);
 }