@zvndev/darkmown 0.12.1 → 0.13.0

package/AGENTS.md

@@ -7,7 +7,7 @@ Darkmown is a Markdown-native web framework. You build sites by writing `.md` an
 - `.md` files are plain CommonMark. Directives stay inert text.
 - `.wd` files are the same Markdown **plus directives** (state, loops, conditionals, includes, forms).
 - To make a `.md` page interactive, **rename it to `.wd`**. ⚠️ Renaming means the old `.md` is **gone** — never leave both `index.md` and `index.wd`, that is a fatal `Duplicate route` build error. Upgrade = delete the `.md`, create the `.wd`.
-- Static pages ship **zero** JavaScript; a page loads the ~4.7 KB gzipped runtime (CI-enforced under 5 KB) only if it declares reactive behavior.
+- Static pages ship **zero** JavaScript; a page loads the ~5.7 KB gzipped runtime (CI-enforced under 6 KB) only if it declares reactive behavior.
 
 ## Project layout & routing
 
@@ -57,13 +57,15 @@ Button actions are a **fixed whitelist**: `x++`, `x--`, `x += <number>`, `list +
 
 ### Conditionals
 ```wd
-:if count
-Shown when truthy.
+:if isPro
+Pro plan.
+:else if isTrial
+Trial.
 :else
-Shown when falsy.
+Free plan.
 :endif
 ```
-`:if name.path` tests a dotted path. Conditionals nest, including per-row inside a loop.
+`:if name.path` tests a dotted path for truthiness (a bare path — no operators). Chain with `:else if` (any number; a bare `:else` must be last). Conditionals nest, including per-row inside a loop.
 
 ### Loops — the only loop
 ```wd
@@ -120,8 +122,13 @@ Thanks, **{ profile.name }**!
 :endif
 
 :computed total = items.length * 4         ← derived state; arithmetic & comparisons only
+
+:store session = { "Authorization": "Bearer …" }      ← persisted token
+:fetch feed from "/api/feed" headers=session refresh="/auth/refresh"   ← auth header; 401 → renew token, retry once
+
+:effect q -> searches++                     ← run actions when watched state changes
 ```
-Shelf `.json` files (in `site/_/`) publish to `/__wd/data/`. `:form action="/api/x" into reply` posts urlencoded and lands the JSON reply in state (without JS it degrades to a native POST). Darkmown owns no backend — point forms at your own API.
+Shelf `.json` files (in `site/_/`) publish to `/__wd/data/`. `:form action="/api/x" into reply` posts urlencoded and lands the JSON reply in state (without JS it degrades to a native POST). Darkmown owns no backend — point forms at your own API. `:fetch`/`refresh=` URLs must be relative, `http(s)://`, or a leading `{ state }` interpolation. `:effect` actions are the `:button` vocabulary (`;`-chained); effects run on change, not on load, capped at 10 settle passes.
 
 **Form-state rules (these cause most form failures):**
 - `:form into x` declares `x` only at `:endform`. A `:if x` (or `{ x.field }`) that reads it must come **after `:endform`**, never inside the form body.
@@ -144,7 +151,7 @@ Your `.skin` selectors must match the **real** output. The emitted HTML is:
 | reactive `@loop` of a list | `<ul>`/`<ol>` (or `<div>`) of items |
 | `{ name }` | a text node |
 
-So style with real selectors: `section`, `.card`, `button`, `input`, `form`, `h1`. **To add a class to a container, use `::: name .class`. For any other custom element, write raw HTML `<div class="…">`. There is NO `{.class}` attribute syntax.**
+So style with real selectors: `section`, `.card`, `button`, `input`, `form`, `h1`. **To add a class to a container, use `::: name .class`. For any other custom element, write raw HTML `<div class="…">`. There is NO `{.class}` attribute syntax.** A container class can also be reactive: `::: card .on-sale when p.price < 50` toggles the class from a predicate (same whitelist as `@loop … where`).
 
 ## Styling with `.skin` — ship this on every page
 

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to Darkmown are documented here. Versions follow [semver](https://semver.org); pre-1.0 minor versions may contain breaking changes.
 
+## 0.13.0 — 2026-06-18
+
+Layered capabilities — four reactive features shaped as progressive disclosure: a simple default, with more power one layer down. The reactive runtime grew to ~5.7 KB gzipped; the CI budget moves from 5 KB to **6 KB** (still shipped un-minified, source fully commented).
+
+- **Conditionals — `:else if` chains.** `:if A` / `:else if B` / … / `:else` / `:endif`. Any number of `:else if`; an optional trailing bare `:else` must come last (a later `:else if` is a compile error). Desugars to nested `:if` regions the runtime already drives — identical behavior for static, reactive, and loop-row conditionals, and no runtime change.
+- **Styling — reactive classes (`::: … .class when <predicate>`).** A container class can be toggled by a predicate using the same whitelisted grammar as `@loop … where` / `:if` (`item.field`, `:state`, `==`/`!=`/`>`/`<`/`>=`/`<=`/`contains`, `and`/`or`). A fully-static predicate folds at build time; a state predicate becomes a global `data-wd-class` binding; a loop-item predicate reacts per row. Static `.class` tokens are unchanged.
+- **Fetch — authenticated requests + token refresh (`:fetch … headers= refresh=`).** `headers=<stateKey>` (already shipped) spreads a state object into request headers; pair with `:store` to persist a bearer token. New `refresh="<url>"`: on an HTTP 401 the runtime POSTs the current headers to the refresh URL, writes the renewed token back to state (persisting if it is a `:store`), and retries the original request once. Concurrent 401s sharing a refresh URL are de-duplicated into a single in-flight refresh.
+- **Effects — `:effect <state> -> <actions>`.** Run actions (the full `:button` vocabulary, `;`-chained) whenever a watched state path changes — for side effects beyond `:computed` (derive state) and fetch deps (auto-refetch). Effects run after a render against settled state, with a 10-pass settle cap guarding against effect→effect loops.
+- **Assets — page-colocated static files.** Any non-page file under `site/pages/` (images, SVG, fonts — anything but `.md`/`.wd`/`.skin`/`.js`) is copied to `dist/` at its path: `site/pages/logo.svg` → `dist/logo.svg`, `site/pages/blog/cover.png` → `dist/blog/cover.png`. The shelf (`site/_/` → `/__wd/media`, `/__wd/data`) is unchanged; `.avif` joins the served content-types.
+- **Security — `:fetch` URL scheme hardening.** `:fetch` (and `refresh=`) URLs are validated at compile time: relative paths, `http(s)://`, and a leading `{ state }` interpolation are allowed; a protocol-relative `//host` or any non-http(s) scheme (`file:`, `data:`, `javascript:`, …) is now a compile error with a corrective hint.
+
 ## 0.12.1 — 2026-06-18
 
 Release-hygiene and DX polish (post-0.12.0 smoke audit).

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 ~4.7 KB gzipped, CI-enforced under 5 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.7 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 ~4.7 KB gzipped, CI-enforced under 5 KB).
+- Static pages ship zero Darkmown runtime. Reactive pages share `/__wd/runtime.js` (currently ~5.7 KB gzipped, CI-enforced under 6 KB).
 - Shelf `.json` files are published at `/__wd/data/` so `:fetch` works on any static host.
 
 ## Interpolation
@@ -88,7 +88,14 @@ Images, fonts, icons, and other non-page files live on the include shelf at `sit
 - Any non-`.md`/`.wd` file in `site/_/` → served at `/__wd/media/<path>` (e.g. `site/_/logo.svg` → `/__wd/media/logo.svg`).
 - `.json` files → served at `/__wd/data/<name>` (this is what `:fetch` reads).
 
-Reference them with a normal URL: `![logo](/__wd/media/logo.svg)`. The preview/`serve` layer returns the correct `Content-Type` per extension. (Files dropped in `site/pages/` are treated as routes, not assets — put shareable assets on the shelf.)
+Reference them with a normal URL: `![logo](/__wd/media/logo.svg)`. The preview/`serve` layer returns the correct `Content-Type` per extension.
+
+**Or colocate an asset next to the page that uses it.** Any non-page file under `site/pages/` (anything but `.md`/`.wd` routes and the colocated `.skin`/`.js`) is copied to `dist/` at its own path, so a clean relative URL just works:
+
+- `site/pages/logo.svg` → `dist/logo.svg` → `![logo](/logo.svg)`
+- `site/pages/blog/cover.png` → `dist/blog/cover.png` → `![cover](/blog/cover.png)`
+
+Use the shelf for assets shared across many pages; colocate the ones that belong to a single page or section. Both ship untouched with the correct content-type.
 
 ## Loops
 
@@ -240,6 +247,20 @@ Cart has { count } items.
 
 State declared inside a section is scoped to it — two sections can both own a `count`. Bindings and actions resolve to the nearest scope.
 
+### Reactive classes — `.class when <predicate>`
+
+A container class can be toggled by a predicate. Static `.class` tokens are unchanged; add `when <predicate>` to make one reactive:
+
+```wd
+@loop products into p
+::: card .product .on-sale when p.price < 50 .featured when p.featured
+**{ p.name }** — ${ p.price }
+:::
+@endloop
+```
+
+The predicate uses the same whitelist as `@loop … where` / `:if` — item fields, declared `:state`/`:store`, numbers, strings, the `==`/`!=`/`>`/`<`/`>=`/`<=`/`contains` operators, and `and`/`or`. A bare path (`.featured when p.featured`) reads as truthy. A predicate over only static values folds at build time into a plain class; one that reads state or the loop item stays reactive and ships with the runtime.
+
 ## Reactive directives
 
 ```wd
@@ -256,6 +277,20 @@ Count is still zero.
 :endif
 ```
 
+Conditionals chain with `:else if`. Each condition is a bare truthy path (the same form `:if` takes — no operators). Use any number of them; an optional bare `:else` must be the last branch:
+
+```wd
+:if isPro
+Pro plan
+:else if isTrial
+Trial — { daysLeft } days left
+:else
+Free plan
+:endif
+```
+
+A whole chain compiles to nested conditional regions, so it stays reactive (or folds at build time when the values are static) exactly like a single `:if`.
+
 Directive actions are intentionally narrow and compile-time checked. Arbitrary JavaScript belongs in colocated `.js` files.
 
 ### Button actions
@@ -297,6 +332,19 @@ Values are literals: a `"string"`, number, `true`/`false`/`null`, or inline JSON
 
 > **Pitfall:** `list toggle v` and `list remove v` match members by value (`===`). That is exact for strings, numbers, and booleans, but not reliable for object members — two equal-looking objects are different values. To remove a row object, loop the list and use the per-row `remove` action below.
 
+### Effects — `:effect`
+
+`:effect <watched> -> <actions>` runs actions whenever a watched state path changes. The actions are the same `:button` vocabulary (`;`-chained) — this is the escape hatch for side effects beyond `:computed` (which derives state) and `:fetch` deps (which auto-refetch):
+
+```wd
+:state q = ""
+:state searches = 0
+
+:effect q -> searches++
+```
+
+Effects run after a render, against settled state, and an effect that mutates state triggers another pass — bounded by a 10-pass settle cap that warns (and stops) if an effect never settles. They do not fire on the initial load, only on a real change.
+
 ## Fetching data
 
 `:fetch name from "url"` declares state and fills it from JSON over the network:
@@ -323,8 +371,7 @@ Cover loading, errors, empty, and data — `@empty` (from the loops above) absor
 
 :if roster_loading
 Loading…
-:else
-:if roster_error
+:else if roster_error
 Couldn't load the team: { roster_error }
 :else
 @loop roster into member
@@ -333,7 +380,6 @@ Couldn't load the team: { roster_error }
 No team members yet.
 @endloop
 :endif
-:endif
 ```
 
 ### Options
@@ -344,6 +390,28 @@ No team members yet.
 - `retry=<N>` — retry on network failure or a 5xx response before surfacing the error.
 - `headers=<key>` — a `:state`/`:store` key holding an object, sent as request headers.
 - `body=<key>` — a `:state`/`:store` key, JSON-serialized as the request body (for non-`GET`).
+- `refresh=<url>` — a token-refresh endpoint; on a `401`, renew the `headers=` token and retry once (see below).
+
+> **URL safety.** A `:fetch`/`refresh` URL must be a relative path, an `http(s)://` URL, or a leading `{ state }` interpolation. A protocol-relative `//host` or a non-http(s) scheme (`file:`, `data:`, `javascript:`, …) is a compile error.
+
+### Authenticated requests and token refresh
+
+`headers=<key>` sends a state object as request headers — pair it with `:store` to persist a bearer token across reloads:
+
+```wd
+:store session = { "Authorization": "Bearer …" }
+:fetch feed from "/api/feed" headers=session
+```
+
+Add `refresh="<url>"` and Darkmown manages the token lifecycle: when a request comes back `401`, it POSTs the current `headers` object to the refresh URL, writes the returned headers (the new token) back into the `session` state — persisting it, since `session` is a `:store` — and retries the original request once. Concurrent `401`s sharing a refresh URL are de-duplicated into a single in-flight refresh.
+
+```wd
+:store session = { "Authorization": "Bearer …" }
+
+:fetch feed from "/api/feed" headers=session refresh="/auth/refresh"
+```
+
+`refresh=` requires `headers=` (it needs a state key to renew). The refresh endpoint should accept the current headers as a JSON body and reply with the new headers object.
 
 ### Dynamic URLs and refetching
 
@@ -447,7 +515,7 @@ Darkmown is a **trusted-author** site generator: you compile content you wrote,
 
 - **Compile only trusted, author-written content.** Do not compile `.md`/`.wd` files you did not write — user-generated content, third-party docs, form input — without sanitizing it first.
 - **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` has no URL allowlist, and reactive pages need `unsafe-eval`.** A `:fetch` URL is taken straight from the page source, so the request goes wherever the author wrote. Reactive pages also require `script-src 'unsafe-eval'` in your Content-Security-Policy, because the runtime compiles validated `:computed` / `@loop … where` expressions via `new Function` — a strict CSP without `unsafe-eval` will break reactive pages (static pages are unaffected).
+- **`:fetch` has no host allowlist, and reactive pages need `unsafe-eval`.** A `:fetch` (or `refresh=`) 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 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.
 

package/SECURITY.md

@@ -16,7 +16,7 @@ Darkmown is a **trusted-author** static site generator. The threat model assumes
 
 1. **Compile only trusted, author-written content.** Do not compile `.md`/`.wd` files you did not write — user-generated content, third-party docs, or form input — without applying your own sanitization first.
 2. **Raw HTML passes through by default.** `markdown-it` runs with `html: true`, so raw HTML in content is emitted verbatim. There is no built-in sanitizer, so 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 strips raw HTML.
-3. **`:fetch` has no URL allowlist, and reactive pages require `unsafe-eval`.** A `:fetch` URL is read directly from the page source, so requests go wherever the author wrote them. Reactive pages also need `script-src 'unsafe-eval'` in your Content-Security-Policy, because the runtime compiles validated `:computed` / `@loop … where` expressions through `new Function`; a strict CSP without `unsafe-eval` breaks reactive pages (static pages are unaffected).
+3. **`:fetch` has no host allowlist, and reactive pages require `unsafe-eval`.** A `:fetch` (or `refresh=`) URL is read directly from the page source; the compiler rejects non-http(s) schemes (`file:`, `data:`, `javascript:`, protocol-relative `//host`) but does not restrict which hosts you call, so SSRF protection is the author's responsibility. Reactive pages also need `script-src 'unsafe-eval'` in your Content-Security-Policy, because the runtime compiles validated `:computed` / `@loop … where` / `.class when` expressions through `new Function`; a strict CSP without `unsafe-eval` breaks reactive pages (static pages are unaffected).
 
 This is the same trust posture as every Markdown SSG: the framework is safe for the trusted-author use case it targets, and unsafe content is the author's responsibility to sanitize before it reaches the compiler.
 

package/docs/spec-alignment.md

@@ -6,7 +6,7 @@ This audit compares the current Darkmown implementation with the original MARROW
 
 - **Markdown-first authoring:** `.md` is strict CommonMark rendered by a real parser (markdown-it); `.wd` is the same Markdown plus first-party directives. Renaming the file is the upgrade path — extensions genuinely gate functionality.
 - **Content tree over components:** routing, includes, and repeated fragments are file/document based instead of React-style components.
-- **Tiered output:** static routes emit HTML/CSS and no Darkmown runtime; reactive routes opt into `/__wd/runtime.js` (~4.7 KB gzipped, CI-enforced below the 5 KB target).
+- **Tiered output:** static routes emit HTML/CSS and no Darkmown runtime; reactive routes opt into `/__wd/runtime.js` (~5.7 KB gzipped, CI-enforced below the 6 KB target).
 - **No virtual DOM:** state changes patch direct DOM bindings, conditional regions, and keyed loop regions.
 - **Keyed list patching:** reactive loops reconcile by item key (`id`/`key`/value) instead of re-rendering the region.
 - **Sections with scoped state:** `::: section #id .class` containers scope `:state`; bindings and actions resolve through the nearest scope chain.
@@ -69,9 +69,20 @@ Three capability gaps from the 2026-06-16 audit, closed together over a shared `
 
 - **Array frontmatter + readable `meta`:** `parseFrontmatter` now parses inline flow arrays (`tags: [a, b, "x, y"]` → real array; quoted items keep internal commas; a value without a leading `[` stays a scalar — block sequences are intentionally out of scope to keep the parser single-pass). A page's frontmatter is exposed to its body under `meta`, so `{ meta.title }` prints a field, `{ meta.tags }` renders an array joined with `, `, and `@loop meta.tags into tag` iterates a frontmatter array at build time (stays `runtime: false`). Genuine correctness fix on its own, and the groundwork for reading/emitting OKF-style bundles (Google Cloud's Open Knowledge Format — markdown + `type`-bearing frontmatter + cross-links; tracked but deliberately not coupled to its v0.1 Draft).
 
+## Stage 9 additions (2026-06-18, v0.13.0)
+
+Four progressive-disclosure capabilities plus an assets and a security change. The reactive runtime grew to ~5.7 KB gzipped; the CI budget moved 5 KB → 6 KB (still un-minified).
+
+- **`:else if` chains:** `:if … :else if … :else … :endif`, any number of `:else if`, optional trailing bare `:else` (a `:else if` after the bare `:else` is a compile error). Implemented by **desugaring** the chain tail into a nested `:if` inside the falsy branch, which re-enters the existing compile path — so static, reactive, and per-row (loop) conditionals all behave identically with no runtime change. **Honest caveat:** each condition is a bare truthy path, the same grammar `:if` accepts — comparisons (`==`, `<`, …) are not supported in a conditional (use `@loop … where` for those, or a `:computed` boolean).
+- **Reactive classes — `::: … .class when <predicate>`:** a container class toggled by a predicate using the `@loop … where` / `:if` whitelist (item fields, `:state`/`:store`, numbers, strings, `==`/`!=`/`>`/`<`/`>=`/`<=`/`contains`, `and`/`or`, plus a bare truthy path). A fully-static predicate folds to a plain class at build time (`runtime: false` preserved); a predicate over `:state` emits a global `data-wd-class`; a loop-item predicate emits `data-wd-each-class` evaluated per row. The predicate compiles to the same whitelisted grammar over `I()`/`S()`/`C()` and runs via `new Function`.
+- **Authenticated fetch + token refresh — `:fetch … headers= refresh=`:** `headers=<stateKey>` (existing) spreads a state object into request headers. New `refresh="<url>"`: on HTTP 401 the runtime POSTs the current headers to the refresh URL, writes the returned headers object back into the `headers` state (persisting if it is a `:store`), and retries the original request once; concurrent 401s sharing a refresh URL collapse to a single in-flight refresh. **Honest caveat:** this is bearer-token-style renewal only — no OAuth authorization-code flow, no refresh-token rotation beyond what the endpoint returns; `refresh=` requires `headers=`.
+- **Effects — `:effect <watched> -> <actions>`:** run the `:button` action vocabulary (`;`-chained) whenever a watched state path changes. Emits a zero-output `data-wd-effect` marker; the runtime snapshots each watched value and, after a render against settled state, runs the actions on change, re-rendering and re-checking up to a 10-pass settle cap (a non-settling effect warns and stops). **Honest caveat:** effects do not fire on initial load (only on change), and row-scoped actions (`append-row`/`remove`) have no clicked row in an effect, so they no-op.
+- **Page-colocated static assets:** any non-page file under `site/pages/` (anything but `.md`/`.wd` routes and colocated `.skin`/`.js`) is copied to `dist/` at its path (`site/pages/logo.svg` → `dist/logo.svg`). The shelf (`site/_/` → `/__wd/media`, `/__wd/data`) is unchanged; a name clash with an emitted route is skipped with a warning. `.avif` was added to the served content-types.
+- **`:fetch` URL scheme hardening (security):** `:fetch`/`refresh=` URLs are validated at compile time — relative, `http(s)://`, or a leading `{ state }` interpolation are allowed; protocol-relative `//host` and non-http(s) schemes (`file:`, `data:`, `javascript:`, …) are rejected with a corrective hint. **This is scheme validation, not a host allowlist** — SSRF to arbitrary http(s) hosts remains the author's responsibility (see the trust boundary).
+
 ## Demo-only directives (not part of the public surface)
 
-The compiler recognizes three directives — `:note`, `:try`, and `:sprint` — that exist **only to power the demo site** (darkmown.com). They are **not** part of the supported public directive set, are not documented for authors, and may change or be removed without notice. Do not build pages that depend on them. The supported public directives are the ones catalogued above: `:state`, `:store`, `:computed`, `:button`, `:bind`, `:if`/`:else`/`:endif`, `:fetch`, `:form`/`:input`/`:submit`, `@loop`/`@empty`/`@endloop` (with `where`, `sort by`, `reverse`, `offset`, `limit`), `@include`, and `::: section`.
+The compiler recognizes three directives — `:note`, `:try`, and `:sprint` — that exist **only to power the demo site** (darkmown.com). They are **not** part of the supported public directive set, are not documented for authors, and may change or be removed without notice. Do not build pages that depend on them. The supported public directives are the ones catalogued above: `:state`, `:store`, `:computed`, `:effect`, `:button`, `:bind`, `:if`/`:else if`/`:else`/`:endif`, `:fetch` (with `headers`/`refresh`), `:form`/`:input`/`:submit`, `@loop`/`@empty`/`@endloop` (with `where`, `sort by`, `reverse`, `offset`, `limit`), `@include`, and `::: section` (with reactive `.class when`).
 
 ## Still missing from the full vision
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/darkmown",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -13,7 +13,7 @@
   "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: 5120)'); if (size >= 5120) process.exit(1)\"",
+    "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",

package/site/_/empty.json

@@ -0,0 +1 @@
+[]

package/site/pages/app.wd

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

package/site/pages/data.wd

@@ -33,6 +33,47 @@ Loading the team…
 
 That loop also proves `:if` over loop items: the lead badge is decided per row.
 
+## The four states of a fetch
+
+Every `:fetch` tracks the whole lifecycle — `loading`, `error`, `empty`, and data — so a page can answer each one. Here the same primitive shows an **error** (a missing URL 404s) and an **empty** result (a file that is just `[]`):
+
+:fetch broken from "/__wd/data/intentionally-missing.json"
+
+:if broken_error
+The request failed on purpose — `broken_error` holds: { broken_error }
+:else if broken_loading
+Trying the missing endpoint…
+:else
+Waiting…
+:endif
+
+:fetch roster from "/__wd/data/empty.json"
+
+@loop roster into person
+- { person.name }
+@empty
+The roster came back empty — `@empty` renders instead of the rows.
+@endloop
+
+The error branch uses an `:else if` chain; the empty branch uses the loop's `@empty`. No state machine to wire by hand.
+
+## Authenticated requests
+
+A real API usually wants a token. `:fetch … headers=<key>` spreads a state object into the request headers, so pair it with `:store` to persist that token across reloads:
+
+:store session = { "Authorization": "Bearer demo-token" }
+:fetch feed from "/__wd/data/team.json" headers=session
+
+:if feed_error
+The API rejected the token: { feed_error }
+:else if feed
+Authenticated fetch returned { feed.length } row(s). Open the network tab — the `Authorization` header rides along on the request.
+:else
+Loading the authenticated feed…
+:endif
+
+This demo points `from=` at a static file (which ignores the header), so it stays self-contained — point it at your real API and the bearer token travels with every request. When that token expires, add `refresh="/auth/refresh"` and Darkmown renews it on a `401` and retries once, automatically.
+
 ## Forms write state, no backend required
 
 `:form into profile` captures the submit straight into state. With `action="/url"` instead, Darkmown emits a plain native form and stays out of the way entirely:

package/site/pages/docs/index.wd

@@ -170,7 +170,7 @@ tags: [sales, revenue, "q1, q2"]
 
 ## Reactive directives
 
-Reactive pages opt into `/__wd/runtime.js` (~4.7 KB gzipped, under a CI-enforced 5 KB budget). Static pages do not.
+Reactive pages opt into `/__wd/runtime.js` (~5.7 KB gzipped, under a CI-enforced 6 KB budget). Static pages do not.
 
 ```wd
 :state count = 0
@@ -196,6 +196,49 @@ Count is still zero.
 
 Directive actions are intentionally narrow and compile-time checked. Arbitrary JavaScript belongs in a colocated `.js` file.
 
+### Multi-branch conditionals
+
+Chain conditionals with `:else if`. Each condition is a bare truthy path (the same form `:if` takes). Use any number of branches; a bare `:else` must come last:
+
+```wd
+:if isPro
+Pro plan
+:else if isTrial
+Trial — { daysLeft } days left
+:else
+Free plan
+:endif
+```
+
+A whole chain compiles to nested conditional regions, so it folds at build time when the values are static and stays reactive otherwise — exactly like a single `:if`.
+
+### Reactive classes — `.class when …`
+
+A container class can react to state or the loop item. Static `.class` tokens stay as-is; add `when <predicate>` for a reactive one:
+
+```wd
+@loop products into p
+::: card .product .on-sale when p.price < 50
+**{ p.name }** — ${ p.price }
+:::
+@endloop
+```
+
+The predicate uses the `@loop … where` / `:if` whitelist (item fields, `:state`, numbers, strings, comparisons, `and`/`or`, `contains`). A static predicate folds to a plain class at build; a state or loop-item predicate stays reactive.
+
+### Effects — `:effect`
+
+`:effect <watched> -> <actions>` runs actions (the `:button` vocabulary, `;`-chained) whenever the watched state changes — for side effects beyond `:computed` and fetch deps:
+
+```wd
+:state q = ""
+:state searches = 0
+
+:effect q -> searches++
+```
+
+Effects run after a render against settled state, never on the initial load, with a 10-pass settle cap guarding against loops.
+
 ### Button actions
 
 A `:button "Label" -> action` mutates one `:state` or `:store` value. The vocabulary is the same for both:
@@ -223,8 +266,7 @@ Values are literals — a `"string"`, number, `true`/`false`/`null`, or inline J
 
 :if team_loading
 Loading…
-:else
-:if team_error
+:else if team_error
 Couldn't load the team: { team_error }
 :else
 @loop team into member
@@ -233,10 +275,18 @@ Couldn't load the team: { team_error }
 No team members yet.
 @endloop
 :endif
-:endif
 ```
 
-Options after the URL: `method=` (default `GET`), `when=load|visible`, `timeout=<ms>`, `retry=<N>`, `headers=<key>`, and `body=<key>` (the last two name a `:state`/`:store` key). A URL can interpolate state (`"/api/users/{ userId }"`) and re-fetches automatically when that state changes; trigger a reload by hand with `:button "Reload" -> team refetch`. Loop a sub-path of fetched data with a dotted source — `@loop team.members into member`.
+Options after the URL: `method=` (default `GET`), `when=load|visible`, `timeout=<ms>`, `retry=<N>`, `headers=<key>`, and `body=<key>` (the last two name a `:state`/`:store` key). A URL can interpolate state (`"/api/users/{ userId }"`) and re-fetches automatically when that state changes; trigger a reload by hand with `:button "Reload" -> team refetch`. Loop a sub-path of fetched data with a dotted source — `@loop team.members into member`. URLs must be relative, `http(s)://`, or a leading `{ state }` interpolation — other schemes are rejected at compile time.
+
+### Authenticated requests
+
+`headers=<key>` sends a state object as request headers; pair it with `:store` to persist a bearer token. Add `refresh="<url>"` and a `401` triggers a token refresh: Darkmown POSTs the current headers to the refresh URL, writes the renewed token back into the `headers` state, and retries the request once (concurrent `401`s share one refresh).
+
+```wd
+:store session = { "Authorization": "Bearer …" }
+:fetch feed from "/api/feed" headers=session refresh="/auth/refresh"
+```
 
 ## Global state — `:store`
 
@@ -271,7 +321,7 @@ Darkmown is a trusted-author site generator: you compile content you wrote, the
 
 - **Compile only content you authored.** Don't run `.md`/`.wd` you didn't write — user-generated content, third-party docs — through the compiler without sanitizing it first.
 - **Raw HTML passes through by default.** Markdown renders with `html: true`, so raw HTML is emitted verbatim and there is no built-in sanitizer. Set `html: false` in a page's frontmatter to drop raw HTML for untrusted content.
-- **`:fetch` has no URL allowlist, and reactive pages need `unsafe-eval`.** Fetch URLs come straight from the page source, and the runtime compiles `:computed` / `@loop … where` expressions via `new Function` — so a reactive page needs `script-src 'unsafe-eval'` in your CSP. Static pages need neither.
+- **`:fetch` has no host allowlist, and reactive pages need `unsafe-eval`.** Fetch URLs come straight from the page source — the compiler rejects non-http(s) schemes but does not restrict which hosts you call, so SSRF is the author's responsibility. The runtime compiles `:computed` / `@loop … where` / `.class when` expressions via `new Function`, so a reactive page needs `script-src 'unsafe-eval'` in your CSP. Static pages need neither.
 
 See [SECURITY.md](https://github.com/ZVN-DEV/darkmown/blob/main/SECURITY.md) in the package for the full security model.
 
@@ -283,6 +333,6 @@ See [SECURITY.md](https://github.com/ZVN-DEV/darkmown/blob/main/SECURITY.md) in
 
 ## Spec status
 
-The implementation is faithful to the original core thesis: Markdown-first authoring, no component ceremony, zero runtime on static pages, and tiny direct-DOM reactivity only when declared. `:store`, the full `:fetch` lifecycle (loading/error/empty states, dynamic URLs, `refetch`, and dotted loop sources), `:form` (including server round-trips), loop ergonomics (`sort by`/`limit`/`offset`/`reverse`/`@empty` and `$index`/`$number`/`$first`/`$last`/`$count`), `:computed`, and `persist` are all shipped and live — try them on the [Data & Forms page](/data/). Still on the roadmap: a first-party server runtime (`site/api/`) and HTML-fragment swaps. See `docs/spec-alignment.md` in the package for the full audit.
+The implementation is faithful to the original core thesis: Markdown-first authoring, no component ceremony, zero runtime on static pages, and tiny direct-DOM reactivity only when declared. `:store`, the full `:fetch` lifecycle (loading/error/empty states, dynamic URLs, `refetch`, dotted loop sources, authenticated `headers=` + `refresh=` token renewal), `:form` (including server round-trips), loop ergonomics (`sort by`/`limit`/`offset`/`reverse`/`@empty` and `$index`/`$number`/`$first`/`$last`/`$count`), `:if … :else if … :else`, reactive `.class when …`, `:effect`, `:computed`, and `persist` are all shipped and live — try them on the [Data & Forms page](/data/) and the [Reactive page](/reactive/). Still on the roadmap: a first-party server runtime (`site/api/`) and HTML-fragment swaps. See `docs/spec-alignment.md` in the package for the full audit.
 
 </main>

package/site/pages/index.wd

@@ -97,14 +97,14 @@ Markdoc.renderers.react(content, React, {
 
 </section>
 
-:note "Static pages ship zero JavaScript. The moment a page asks for reactivity — like this very homepage — one ~4.7 KB gzipped runtime loads (CI-enforced under 5 KB), never before. JS optional, CSS optional, always."
+:note "Static pages ship zero JavaScript. The moment a page asks for reactivity — like this very homepage — one ~5.7 KB gzipped runtime loads (CI-enforced under 6 KB), never before. JS optional, CSS optional, always."
 
 <section class="props">
 
 ## Three rules, no escape hatch
 
 - **Zero-JS static.** A page with no state ships no framework JavaScript. `/markdown/` and `/docs/` prove it — open them and check the network tab.
-- **One runtime.** Every reactive page shares the same ~4.7 KB gzipped runtime, CI-enforced under 5 KB. No per-component bundles, no hydration tax that scales with your UI.
+- **One runtime.** Every reactive page shares the same ~5.7 KB gzipped runtime, CI-enforced under 6 KB. No per-component bundles, no hydration tax that scales with your UI.
 - **One loop, one binding.** `@loop … into …` is the only loop; `{ name }` is the only interpolation. Nothing else to learn, nothing else to misuse.
 
 </section>

package/site/pages/reactive.wd

@@ -39,30 +39,34 @@ The same `@loop` that unrolls static data also drives reactive lists. Items are
 
 :button "Add todo" -> todos += {"id": 3, "title": "Live compile", "owner": "Testing"}
 
-## Conditionals inside a loop, nested
+## Multi-branch conditionals + reactive classes
 
-`:if` works per row, and conditionals nest — the inner branch is decided after the outer one, for every item, and stays reactive. Add a "done" task and watch which badge each row shows:
+`:if … :else if … :else … :endif` picks one of several branches per row, and a container class can react to the row too: `.class when <predicate>` toggles a class from the same whitelist `@loop … where` uses. Each card below picks one of three badges *and* tags itself `.is-done` / `.is-blocked`, all reactive:
+
+<style>
+.task-row { border-left: 4px solid #9991; padding-left: .6rem; }
+.task-row.is-done { border-left-color: #2e9e5b; }
+.task-row.is-blocked { border-left-color: #d2453f; }
+</style>
 
 :state tasks = [{"id": 1, "title": "Draft the spec", "done": true, "blocked": false}, {"id": 2, "title": "Wire the runtime", "done": false, "blocked": true}, {"id": 3, "title": "Write the demo", "done": false, "blocked": false}]
 
 @loop tasks into task
-::: card .task-row
+::: card .task-row .is-done when task.done .is-blocked when task.blocked
 **{ task.title }** —
 :if task.done
 done ✓
-:else
-:if task.blocked
+:else if task.blocked
 blocked ✗
 :else
 in progress …
 :endif
-:endif
 :::
 @endloop
 
 :button "Add a finished task" -> tasks += {"id": 4, "title": "Ship it", "done": true, "blocked": false}
 
-Each row picks one of three states from two nested conditionals, all in plain Markdown — no component, no ternary, no JavaScript.
+Each row picks one of three states from a single `:else if` chain, and its left border color comes from a reactive `.class when …` — plain Markdown, no component, no ternary, no JavaScript.
 
 ## Live filtering — search in pure Markdown
 
@@ -83,6 +87,15 @@ Each row picks one of three states from two nested conditionals, all in plain Ma
 
 The predicate whitelist is compile-time validated — item fields, declared state, numbers, and strings only. An item-only predicate (say `where p.price < 50`) would instead filter at build time and ship zero JavaScript.
 
+### …and an effect that watches the search
+
+`:effect <state> -> <actions>` runs actions whenever the watched state changes — for side effects past deriving state. This one counts how many times the search box above has changed:
+
+:state searches = 0
+:effect q -> searches++
+
+The search has changed **{ searches }** time(s). Type in the box above and this updates on its own — no handler wired by hand.
+
 ### …and an editable cart
 
 A `:button` inside a loop can act on its own row. **Add to cart** carries the row into another list; **Remove** drops a line — a whole add/remove flow with no JavaScript:

package/src/builder.js

@@ -71,6 +71,11 @@ export function buildSite(cwd = process.cwd()) {
   fs.writeFileSync(path.join(paths.distRoot, "404.html"), notFoundHtml ?? defaultNotFoundHtml());
 
   fs.writeFileSync(path.join(paths.distRoot, "routes.json"), JSON.stringify(manifest, null, 2));
+
+  // Page-colocated static assets (images, SVG, fonts, …) copy last, so the guard
+  // sees every emitted route/framework file already on disk.
+  emitPageAssets(paths);
+
   return { routes: manifest, distRoot: paths.distRoot };
 }
 
@@ -168,6 +173,33 @@ function emitShelfAssets(paths) {
   }
 }
 
+/**
+ * Copy page-colocated static assets (images, SVG, fonts, …) from `site/pages`
+ * into `dist`, preserving their relative path: `site/pages/logo.svg` →
+ * `dist/logo.svg`; `site/pages/blog/cover.png` → `dist/blog/cover.png`. Routes
+ * (`.md`/`.wd`) and the compiler's colocated `.skin`/`.js` files are skipped —
+ * those have their own emit paths. A backstop guard skips any asset whose output
+ * would clobber an already-emitted route/framework file (in practice their
+ * extensions differ, so this only fires on a genuine name clash).
+ * @param {Paths} paths
+ * @returns {void}
+ */
+function emitPageAssets(paths) {
+  if (!fs.existsSync(paths.routesRoot)) return;
+  for (const file of walk(paths.routesRoot)) {
+    const ext = path.extname(file).toLowerCase();
+    if ([".md", ".wd", ".skin", ".js"].includes(ext)) continue;
+    const rel = path.relative(paths.routesRoot, file);
+    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, "/")}`);
+      continue;
+    }
+    fs.mkdirSync(path.dirname(out), { recursive: true });
+    fs.copyFileSync(file, out);
+  }
+}
+
 /**
  * @param {string} dir
  * @returns {string[]}

package/src/compiler.js

@@ -377,6 +377,11 @@ function compileBody(lines, ctx) {
       out.push(handleComputed(line, ctx));
       continue;
     }
+    if (/^:effect\s/.test(line)) {
+      flush();
+      out.push(handleEffect(line, ctx));
+      continue;
+    }
     if (/^:form\s/.test(line)) {
       flush();
       const block = scanBlock(lines, i, /^:form\s/, ":endform", ctx.file);
@@ -542,7 +547,13 @@ function scanContainer(lines, start, file) {
 }
 
 /**
- * Split an `:if … :else … :endif` block into its two branches.
+ * Split an `:if … :else if … :else … :endif` chain into the first condition's
+ * truthy body and a falsy body. A bare `:else` works as before. The first
+ * `:else if B` is **desugared** into a nested `:if` that lives in the falsy
+ * branch: the falsy body becomes `[":if B", …rest…, ":endif"]`, which re-enters
+ * `compileBody`/`handleIf` recursively. A whole `:if/:else if/:else` chain
+ * therefore compiles to nested `data-wd-if` regions the runtime already drives —
+ * identical behavior for static, reactive, and loop-row conditionals.
  * @param {string[]} lines
  * @param {number} start Index of the `:if` line.
  * @param {string} file Source path for errors.
@@ -554,6 +565,11 @@ function scanConditional(lines, start, file) {
   /** @type {string[]} */
   const falsy = [];
   let current = truthy;
+  // "truthy": collecting the :if body. "else": a bare :else closed the chain —
+  // no further branches allowed. "elseif": the first :else if was desugared into
+  // a nested :if inside `falsy`; subsequent depth-0 :else if/:else lines belong to
+  // that nested chain and are emitted verbatim for the recursive compile to split.
+  let mode = "truthy";
   let depth = 0;
   let fence = null;
   for (let i = start + 1; i < lines.length; i++) {
@@ -571,12 +587,28 @@ function scanConditional(lines, start, file) {
     }
     if (/^:if\s/.test(line)) depth++;
     if (line.trim() === ":endif") {
-      if (depth === 0) return { truthy, falsy, end: i };
+      if (depth === 0) {
+        if (mode === "elseif") falsy.push(":endif"); // close the synthesized nested :if
+        return { truthy, falsy, end: i };
+      }
       depth--;
     }
-    if (line.trim() === ":else" && depth === 0) {
-      current = falsy;
-      continue;
+    if (depth === 0 && mode !== "elseif") {
+      const t = line.trim();
+      const elseIf = t.match(/^:else if\s+(.+?)\s*$/);
+      if (elseIf) {
+        if (mode === "else") throw new Error(`":else if" after ":else" in ${file}. ":else" must be the last branch — order the "else if" conditions before the bare ":else".`);
+        falsy.push(`:if ${elseIf[1]}`); // desugar the chain tail into a nested :if
+        current = falsy;
+        mode = "elseif";
+        continue;
+      }
+      if (t === ":else") {
+        if (mode === "else") throw new Error(`Duplicate ":else" in ${file}. A conditional may have only one bare ":else".`);
+        current = falsy;
+        mode = "else";
+        continue;
+      }
     }
     current.push(line);
   }
@@ -634,20 +666,44 @@ function parseIncludeArgs(raw, ctx) {
  * @returns {string}
  */
 function handleContainer(header, bodyLines, ctx) {
-  const tokens = header.split(/\s+/);
+  let rest = header.trim();
   let tag = "section";
-  /** @type {string[]} */
-  let extraClass = [];
+  /** @type {string[]} Static classes baked into class="". */
+  const extraClass = [];
+  /** @type {[string, string][]} Reactive loop-item class bindings (data-wd-each-class). */
+  const eachClasses = [];
+  /** @type {[string, string][]} Global state-driven class bindings (data-wd-class). */
+  const stateClasses = [];
   let id = "";
-  let nameToken = tokens[0] && !tokens[0].startsWith("#") && !tokens[0].startsWith(".") ? tokens.shift() ?? "section" : "section";
-  if (nameToken !== "section") {
-    tag = "div";
-    extraClass.push(nameToken);
-  }
-  for (const token of tokens) {
-    if (token.startsWith("#")) id = token.slice(1);
-    else if (token.startsWith(".")) extraClass.push(token.slice(1));
-    else throw new Error(`Unexpected token "${token}" in container "::: ${header}" in ${ctx.file}`);
+  // Leading tag/name token (anything not starting with . or #). "section" keeps
+  // the <section> tag; any other name becomes a <div> and also a class.
+  const lead = rest.match(/^([^\s.#]\S*)/);
+  let nameToken = "section";
+  if (lead) { nameToken = lead[1]; rest = rest.slice(lead[0].length).trim(); }
+  if (nameToken !== "section") { tag = "div"; extraClass.push(nameToken); }
+  while (rest.length) {
+    if (rest.startsWith("#")) {
+      const m = rest.match(/^#(\S+)/);
+      id = (m ? m[1] : "");
+      rest = rest.slice((m ? m[0] : rest).length).trim();
+      continue;
+    }
+    const cm = rest.match(/^\.([A-Za-z_][\w-]*)/);
+    if (!cm) throw new Error(`Unexpected token "${rest.split(/\s+/)[0]}" in container "::: ${header}" in ${ctx.file}`);
+    const cls = cm[1];
+    rest = rest.slice(cm[0].length).trim();
+    // Optional `when <predicate>` makes the class reactive. The predicate runs to
+    // the next ` .`/` #` token or the end of the header.
+    const whenMatch = rest.match(/^when\s+(.+?)(?=\s+[.#]|$)/);
+    if (whenMatch) {
+      rest = rest.slice(whenMatch[0].length).trim();
+      const compiled = compileWhen(whenMatch[1].trim(), ctx);
+      if (compiled.static) { if (compiled.value) extraClass.push(cls); }
+      else if (compiled.item) eachClasses.push([cls, compiled.body]);
+      else stateClasses.push([cls, compiled.body]);
+    } else {
+      extraClass.push(cls);
+    }
   }
   const explicitId = Boolean(id);
   if (!id) id = `wd-s${++ctx.comp.sectionCounter}`;
@@ -661,7 +717,10 @@ function handleContainer(header, bodyLines, ctx) {
   }
   const idAttr = explicitId ? ` id="${escapeHtml(id)}"` : "";
   const classAttr = extraClass.length ? ` class="${escapeHtml(extraClass.join(" "))}"` : "";
-  return `<${tag}${idAttr}${classAttr}>\n${inner}\n</${tag}>`;
+  let classBind = "";
+  if (eachClasses.length) { ctx.comp.assets.runtime = true; classBind += ` data-wd-each-class="${escapeHtml(JSON.stringify(eachClasses))}"`; }
+  if (stateClasses.length) { ctx.comp.assets.runtime = true; classBind += ` data-wd-class="${escapeHtml(JSON.stringify(stateClasses))}"`; }
+  return `<${tag}${idAttr}${classAttr}${classBind}>\n${inner}\n</${tag}>`;
 }
 
 /**
@@ -740,7 +799,7 @@ function declareErrorState(key, ctx) {
 }
 
 const FETCH_USE =
-  'Use: :fetch name from "url" [method=…] [timeout=ms] [retry=N] [when=visible] [headers=key] [body=key]';
+  'Use: :fetch name from "url" [method=…] [timeout=ms] [retry=N] [when=visible] [headers=key] [body=key] [refresh=url]';
 
 /**
  * Parse a keyword-arg `:fetch` directive into a lifecycle-aware marker.
@@ -755,14 +814,14 @@ function handleFetch(line, ctx) {
   const head = line.match(/^:fetch\s+([A-Za-z_$][\w$]*)\s+from\s+("[^"]+"|\S+)\s*(.*)$/);
   if (!head) throw new Error(`Malformed :fetch in ${ctx.file}: ${line}. ${FETCH_USE}`);
   const name = head[1];
-  const url = stripQuotes(head[2]);
+  const url = validateFetchUrl(stripQuotes(head[2]), ctx);
   /** @type {Record<string, string>} */
   const opts = {};
   for (const part of head[3].trim().split(/\s+/).filter(Boolean)) {
     const kv = part.match(/^([A-Za-z]+)=(.+)$/);
     if (!kv) throw new Error(`Unknown :fetch option "${part}" in ${ctx.file}. ${FETCH_USE}`);
     const optName = kv[1];
-    if (!["method", "when", "timeout", "retry", "headers", "body"].includes(optName)) {
+    if (!["method", "when", "timeout", "retry", "headers", "body", "refresh"].includes(optName)) {
       throw new Error(`Unknown :fetch option "${optName}" in ${ctx.file}. ${FETCH_USE}`);
     }
     opts[optName] = stripQuotes(kv[2]);
@@ -779,6 +838,14 @@ function handleFetch(line, ctx) {
       throw new Error(`:fetch ${n} must be a non-negative integer in ${ctx.file}. ${FETCH_USE}`);
     }
   }
+  if (opts.refresh !== undefined) {
+    // Layer 2: a 401 triggers a token-refresh POST to this URL, then one retry.
+    // The new token is written back into the `headers=` state, so it is required.
+    if (!opts.headers) {
+      throw new Error(`:fetch refresh= needs headers= (the state key holding the token to renew) in ${ctx.file}. ${FETCH_USE}`);
+    }
+    opts.refresh = validateFetchUrl(opts.refresh, ctx, ":fetch refresh");
+  }
 
   // Extract `{ path }` dependency keys from the URL (validated against poison
   // segments). The runtime fills them from state on each (re)fetch.
@@ -811,11 +878,40 @@ function handleFetch(line, ctx) {
     attr("retry", opts.retry) +
     attr("headers", opts.headers && resolveStateKey(opts.headers, ctx)) +
     attr("body", opts.body && resolveStateKey(opts.body, ctx)) +
+    attr("refresh", opts.refresh) +
     attr("deps", deps.join(",")) +
     `></span>`;
   return `<script type="application/json" data-wd-state>${safeScriptJson(seeds)}</script>${marker}`;
 }
 
+/**
+ * Validate a `:fetch` (or `refresh=`) URL's scheme at compile time. Mirrors the
+ * `:try` href guard: relative paths (`/`, `./`, `../`, bare), an `http(s)://`
+ * URL, or a leading `{ state }` interpolation are allowed; a protocol-relative
+ * `//host` or any non-http(s) scheme (`file:`, `data:`, `javascript:`, …) is
+ * rejected. Interpolated values are percent-encoded by the runtime, so a scheme
+ * cannot be injected through state at request time.
+ * @param {string} url
+ * @param {Ctx} ctx
+ * @param {string} [what] Option name for the error message.
+ * @returns {string}
+ */
+function validateFetchUrl(url, ctx, what = ":fetch") {
+  const value = url.trim();
+  if (value !== url || value === "" || /[\u0000-\u001F\u007F]/.test(value)) {
+    throw new Error(`Unsafe ${what} URL "${escapeHtml(url)}" in ${ctx.file}. Use a relative path (/, ./, ../), an http(s):// URL, or a { state } interpolation.`);
+  }
+  if (value.startsWith("//")) {
+    throw new Error(`Unsafe ${what} URL "${escapeHtml(url)}" in ${ctx.file}. Protocol-relative URLs are not allowed; use http:// or https:// explicitly.`);
+  }
+  if (value.startsWith("{")) return value; // interpolation-first; the runtime percent-encodes state values
+  const scheme = value.match(/^([A-Za-z][A-Za-z0-9+.-]*):/);
+  if (scheme && !["http", "https"].includes(scheme[1].toLowerCase())) {
+    throw new Error(`Unsafe ${what} URL "${escapeHtml(url)}" in ${ctx.file}. The "${scheme[1]}:" scheme is not allowed; use http://, https://, or a relative path.`);
+  }
+  return value;
+}
+
 /**
  * @param {string} line
  * @param {Ctx} ctx
@@ -1031,6 +1127,30 @@ function handleButton(line, ctx) {
   return `<button type="button" data-wd-action="${action.op}" data-wd-target="${action.target}"${valueAttr}>${escapeHtml(match[1])}</button>`;
 }
 
+const EFFECT_USE = "Use: :effect watchedState -> action[; action…] (actions use the :button vocabulary).";
+
+/**
+ * Parse `:effect <watched> -> <actions>` into a zero-output marker the runtime
+ * watches: when `<watched>` state changes, it runs `<actions>` (the same `:button`
+ * action vocabulary, `;`-chained). For arbitrary side effects beyond `:computed`
+ * (derive state) and fetch deps (auto-refetch).
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @returns {string}
+ */
+function handleEffect(line, ctx) {
+  const match = line.match(/^:effect\s+([A-Za-z_$][\w$.]*)\s*->\s*(.+)$/);
+  if (!match) throw new Error(`Malformed :effect in ${ctx.file}: ${line}. ${EFFECT_USE}`);
+  const segs = validatePath(match[1], ctx, EFFECT_USE);
+  const key = resolveStateKey(segs[0], ctx);
+  if (!key) throw new Error(`:effect watches unknown state "${segs[0]}" in ${ctx.file}. Declare it first with :state ${segs[0]} = ...`);
+  ctx.comp.assets.runtime = true;
+  const watch = [key, ...segs.slice(1)].join(".");
+  const action = parseAction(match[2], ctx);
+  const actions = Array.isArray(action) ? action : [action];
+  return `<script type="application/json" data-wd-effect>${safeScriptJson({ watch, actions })}</script>`;
+}
+
 /**
  * @param {string} line
  * @param {string[]} truthyLines
@@ -1375,6 +1495,75 @@ function evalPredicate(body, item, ctx) {
   }
 }
 
+/**
+ * Compile one operand of a `::: … .class when <predicate>` expression. Like the
+ * `@loop where` operand, but also folds a static-scope value (a loop-unrolled
+ * item field or include arg) to its build-time literal, so a fully-static
+ * predicate can be evaluated at compile time. Mirrors `:if`'s scope→item→state
+ * resolution order.
+ * @param {string} tok
+ * @param {Ctx} ctx
+ * @returns {{ code: string, state: boolean, item: boolean }}
+ */
+function compileWhenOperand(tok, ctx) {
+  if (/^"[^"]*"$/.test(tok) || /^'[^']*'$/.test(tok)) return { code: JSON.stringify(tok.slice(1, -1)), state: false, item: false };
+  if (/^-?\d+(?:\.\d+)?$/.test(tok)) return { code: tok, state: false, item: false };
+  if (["true", "false", "null"].includes(tok)) return { code: tok, state: false, item: false };
+  if (!/^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/.test(tok)) {
+    throw new Error(`Unsupported operand "${tok}" in "::: … when" (${ctx.file}). Use item.field, a :state name, a number, or a "string".`);
+  }
+  const segs = tok.split(".");
+  if (segs.some((seg) => ["constructor", "prototype", "__proto__"].includes(seg))) {
+    throw new Error(`Path "${tok}" is not allowed in "::: … when" (${ctx.file})`);
+  }
+  const scoped = lookupVar(ctx.scope, segs[0]);
+  if (scoped.found) return { code: JSON.stringify(getPath(scoped.value, segs.slice(1)) ?? null), state: false, item: false };
+  if (ctx.loopItem && segs[0] === ctx.loopItem) return { code: `I(${JSON.stringify(segs.slice(1).join("."))})`, state: false, item: true };
+  const key = resolveStateKey(segs[0], ctx);
+  if (!key) throw new Error(`"::: … when" references unknown name "${segs[0]}" in ${ctx.file}. Use a loop item field, a declared :state, a number, or a "string".`);
+  const rest = segs.slice(1).join(".");
+  return { code: `S(${JSON.stringify(key)}${rest ? `, ${JSON.stringify(rest)}` : ""})`, state: true, item: false };
+}
+
+/**
+ * Compile a `::: … .class when <predicate>`. Allows `:if`-style bare truthy
+ * paths and `where`-style `left <op> right` conditions joined by `and`/`or`.
+ * Folds to a static verdict when every operand is build-known, else returns a
+ * runtime body over I()/S()/C() plus whether it reads the reactive loop item
+ * (which decides data-wd-each-class vs the global data-wd-class).
+ * @param {string} raw
+ * @param {Ctx} ctx
+ * @returns {{ static: true, value: boolean } | { static: false, body: string, item: boolean }}
+ */
+function compileWhen(raw, ctx) {
+  const parts = raw.split(/\s+(and|or)\s+/i);
+  /** @type {string[]} */
+  const pieces = [];
+  let usesState = false;
+  let usesItem = false;
+  for (let i = 0; i < parts.length; i++) {
+    if (i % 2 === 1) { pieces.push(parts[i].toLowerCase() === "and" ? "&&" : "||"); continue; }
+    const seg = parts[i].trim();
+    const opMatch = seg.match(/^(.+?)\s+(contains|==|!=|>=|<=|>|<)\s+(.+)$/i);
+    if (opMatch) {
+      const left = compileWhenOperand(opMatch[1].trim(), ctx);
+      const right = compileWhenOperand(opMatch[3].trim(), ctx);
+      usesState = usesState || left.state || right.state;
+      usesItem = usesItem || left.item || right.item;
+      const op = opMatch[2].toLowerCase();
+      pieces.push(op === "contains" ? `(C(${left.code}, ${right.code}))` : `(${left.code} ${op} ${right.code})`);
+    } else {
+      const only = compileWhenOperand(seg, ctx);
+      usesState = usesState || only.state;
+      usesItem = usesItem || only.item;
+      pieces.push(`(${only.code})`);
+    }
+  }
+  const body = pieces.join(" ");
+  if (!usesState && !usesItem) return { static: true, value: evalPredicate(body, undefined, ctx) };
+  return { static: false, body, item: usesItem };
+}
+
 /**
  * @param {unknown[]} rows
  * @param {string} itemName

package/src/runtime.js

@@ -131,7 +131,11 @@ function isEmpty(v) {
 async function httpJson(url, init) {
   const response = await fetch(url, init);
   const text = await response.text();
-  if (!response.ok) throw new Error(`HTTP ${response.status}`);
+  if (!response.ok) {
+    const err = /** @type {Error & { status?: number }} */ (new Error(`HTTP ${response.status}`));
+    err.status = response.status; // lets the :fetch lifecycle single out a 401 for token refresh
+    throw err;
+  }
   try { return JSON.parse(text); } catch { return { status: response.status, body: text }; }
 }
 
@@ -186,6 +190,29 @@ function loopPredicate(body) {
   return fn;
 }
 
+/**
+ * Toggle reactive `.class when <predicate>` bindings on an element. `raw` is the
+ * JSON `[[name, body], …]` from data-wd-class (global, item undefined) or
+ * data-wd-each-class (per loop row); each body is the same I()/S()/C()
+ * expression the loop `where` uses.
+ * @param {Element} el
+ * @param {string | null} raw
+ * @param {any} item Loop item for each-class; undefined for a global class.
+ * @returns {void}
+ */
+function classToggle(el, raw, item) {
+  if (!raw) return;
+  /** @type {[string, string][]} */
+  let pairs;
+  try { pairs = JSON.parse(raw); } catch { return; }
+  for (const [name, body] of pairs) {
+    let on = false;
+    try { on = Boolean(loopPredicate(body)((/** @type {string} */ p) => getPath(item, p), (/** @type {string} */ k, /** @type {string} */ r) => getPath(state[k], r || ""), containsFn)); }
+    catch (error) { warn(body, error); }
+    el.classList.toggle(name, on);
+  }
+}
+
 /**
  * Stable per-render key for a loop row, disambiguating duplicates with `#n`.
  * @param {any} item
@@ -231,6 +258,8 @@ function fillItem(node, item, meta = {}) {
   for (const marker of node.querySelectorAll("[data-wd-each-meta]")) {
     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);
 }
 
 /**
@@ -290,6 +319,10 @@ function renderNow() {
     output.innerHTML = template?.innerHTML || "";
   }
 
+  // Reactive styling: toggle state-driven `.class when …` bindings. Loop-row
+  // 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);
+
   for (const region of document.querySelectorAll("[data-wd-loop]")) {
     const key = region.getAttribute("data-wd-loop");
     const data = region.getAttribute("data-wd-loop-data");
@@ -362,6 +395,36 @@ function renderNow() {
   for (const input of document.querySelectorAll("[data-wd-bind-input]")) {
     if (document.activeElement !== input) /** @type {HTMLInputElement} */ (input).value = state[input.getAttribute("data-wd-bind-input") || ""] ?? "";
   }
+
+  runEffects(); // side effects run last, against fully settled state
+}
+
+/** @typedef {{ watch: string, actions: { op: string, target?: string, value?: any }[], last: string }} Effect */
+/** @type {Effect[]} */
+const effects = [...document.querySelectorAll("script[data-wd-effect]")].map((node) => {
+  const def = JSON.parse(node.textContent || "{}");
+  return { watch: def.watch, actions: def.actions || [], last: JSON.stringify(getPath(state, def.watch) ?? null) };
+});
+let effectDepth = 0;
+/**
+ * After a render, fire any `:effect` whose watched state changed, running its
+ * actions through the shared action runner. If that mutates state, re-render and
+ * re-check; a settle cap of 10 passes guards against effect→effect loops.
+ * @returns {void}
+ */
+function runEffects() {
+  if (!effects.length) return;
+  let changed = false;
+  for (const fx of effects) {
+    const now = JSON.stringify(getPath(state, fx.watch) ?? null);
+    if (now === fx.last) continue;
+    fx.last = now;
+    for (const a of fx.actions) applyAction(null, a.op, a.target || "", a.value);
+    changed = true;
+  }
+  if (!changed) { effectDepth = 0; return; }
+  if (++effectDepth >= 10) { effectDepth = 0; console.warn("effect did not settle"); return; }
+  renderNow(); // reflect the effect's state changes, then re-check
 }
 
 /**
@@ -391,10 +454,11 @@ document.addEventListener("input", (event) => {
 /**
  * Resolve the loop source and row item for a clicked element, if inside a loop.
  * The clicked button's row is the nearest reconciled loop node; it carries its item.
- * @param {Element} el
+ * @param {Element | null} el Null for effect-driven actions (no clicked row).
  * @returns {{ srcKey: string | null, item: any } | null}
  */
 function clickedRow(el) {
+  if (!el) return null; // effect-driven actions have no clicked row → row ops no-op
   const row = /** @type {WdRow | null} */ (el.closest("[data-wd-loop-key]"));
   const region = el.closest("[data-wd-loop]");
   if (!row || !region) return null;
@@ -404,7 +468,7 @@ function clickedRow(el) {
 /**
  * Apply one parsed action `{op,target,value}` against state. Targets are dotted
  * paths read via getPath / written via setPath; a bare name is a 1-segment path.
- * @param {Element} action The clicked element (for loop-row resolution).
+ * @param {Element | null} action The clicked element (for loop-row resolution); null for effects.
  * @param {string} op
  * @param {string} target
  * @param {any} value
@@ -518,12 +582,17 @@ function startFetch(node) {
 
   const headers = g("headers");
   const body = g("body");
+  const refresh = g("refresh");
   const method = g("method") || "GET";
   const timeout = Number(g("timeout"));
   let tries = Number(g("retry"));
+  let refreshed = false; // a token refresh + retry happens at most once per request
   state[key + "_error"] = null;
   set("_loading", true);
 
+  /** @param {any} error */
+  const fail = (error) => { state[key + "_error"] = String(error); set("_loading", false); };
+
   const attempt = () => {
     /** @type {RequestInit} */
     const init = { method };
@@ -542,14 +611,53 @@ function startFetch(node) {
     }).catch((error) => {
       clearTimeout(timer);
       if (dead()) return;
+      const is401 = error && error.status === 401;
+      // Layer 2: a 401 with a refresh URL renews the token once, then retries.
+      if (is401 && refresh && headers && !refreshed) {
+        refreshed = true;
+        return void refreshToken(refresh, headers).then((ok) => {
+          if (dead()) return;
+          ok ? attempt() : fail(error);
+        });
+      }
+      if (is401 && refreshed) return void fail(error); // a second 401 after refresh → give up
       if (tries-- > 0) return void setTimeout(attempt, 200);
-      state[key + "_error"] = String(error);
-      set("_loading", false);
+      fail(error);
     });
   };
   attempt();
 }
 
+/** @type {Map<string, Promise<boolean>>} In-flight token refreshes, keyed by URL. */
+const refreshFlights = new Map();
+/**
+ * Single-flight token refresh: POST the current header state to `refreshUrl`,
+ * and on a 2xx JSON reply write the returned headers object back into the
+ * `headersKey` state (persisting if it is a `:store`). Concurrent 401s sharing a
+ * refresh URL await the same request, then each retries its own fetch.
+ * @param {string} refreshUrl
+ * @param {string} headersKey
+ * @returns {Promise<boolean>} whether the token was renewed
+ */
+function refreshToken(refreshUrl, headersKey) {
+  const inflight = refreshFlights.get(refreshUrl);
+  if (inflight) return inflight;
+  const flight = httpJson(refreshUrl, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(state[headersKey] ?? {})
+  }).then((value) => {
+    if (value && typeof value === "object") {
+      state[headersKey] = value; // the new headers shape, e.g. { Authorization: "Bearer …" }
+      savePersisted();
+      return true;
+    }
+    return false;
+  }).catch(() => false).finally(() => refreshFlights.delete(refreshUrl));
+  refreshFlights.set(refreshUrl, flight);
+  return flight;
+}
+
 /** A fetch marker carrying its last dependency snapshot for refetch diffing and
  * a generation token so a superseded in-flight response/retry bails on write. */
 /** @typedef {Element & { __wdSnap?: string, __wdGen?: number }} FetchNode */

package/src/statics.js

@@ -65,6 +65,7 @@ const contentTypes = {
   ".jpeg": "image/jpeg",
   ".gif": "image/gif",
   ".webp": "image/webp",
+  ".avif": "image/avif",
   ".ico": "image/x-icon",
   ".woff": "font/woff",
   ".woff2": "font/woff2",