@zvndev/darkmown 0.13.0 → 0.14.0

package/AGENTS.md

@@ -20,6 +20,7 @@ package.json
 - **Folders are routes.** `site/pages/blog/post.wd` serves at `/blog/post/`.
 - Files/folders starting with `.`, `-`, or `_` are **hidden** from routing (drafts, partials).
 - A `page.skin` next to `page.wd` attaches styling; a `page.js` attaches behavior. Matched by basename.
+- **Colocated assets:** any other file under `site/pages/` (not a `.md`/`.wd` route, not a basename-matched `.skin`/`.js`) copies to `dist/` at its own path with the right content-type — so `site/pages/logo.svg` is served at `/logo.svg`. Use the `site/_/` shelf for assets shared across pages; colocate the ones a single page owns.
 
 Commands: `darkmown dev`, `darkmown build`, `darkmown serve`.
 
@@ -57,15 +58,25 @@ Button actions are a **fixed whitelist**: `x++`, `x--`, `x += <number>`, `list +
 
 ### Conditionals
 ```wd
-:if isPro
+:if plan == "pro" or seats >= 5
 Pro plan.
-:else if isTrial
+:else if trialDays > 0 and not expired
 Trial.
 :else
 Free plan.
 :endif
 ```
-`: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.
+`:if <predicate>` branches on a compile-time-validated predicate — a bare path (truthy), comparisons (`==` `!=` `<` `<=` `>` `>=` `contains`), joined with `and`/`or`/`not`. Operands are item paths, declared `:state`/`:store`, numbers, or `"strings"` — no expressions. (Same grammar as `.class when`; `@loop … where` is the comparison-only subset — operators with `and`/`or`.) Chain with `:else if` (any number; a bare `:else` must be last). Conditionals nest, including per-row inside a loop.
+
+### Reactive classes — `.class when <predicate>`
+```wd
+@loop tasks into task
+::: card .task .done when task.done .urgent when task.priority > 3   ← toggles each class by predicate
+**{ task.title }**
+:::
+@endloop
+```
+`.class when <predicate>` on a `:::` container toggles that class from the same predicate grammar as `:if`. A predicate over only static values folds to a plain class at build time; one reading `:state` or the loop item stays reactive.
 
 ### Loops — the only loop
 ```wd
@@ -151,7 +162,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.** 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`).
+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 grammar as `:if`).
 
 ## Styling with `.skin` — ship this on every page
 

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to Darkmown are documented here. Versions follow [semver](https://semver.org); pre-1.0 minor versions may contain breaking changes.
 
+## 0.14.0 — 2026-06-18
+
+Richer conditionals — `:if` / `:else if` now read the full predicate grammar instead of a bare truthy path only. The reactive runtime is ~5.7 KB gzipped (5762 B), still under the 6 KB CI budget and shipped un-minified.
+
+- **Conditionals — comparison & logical expressions.** A `:if` / `:else if` condition now accepts the same compile-time-validated grammar as `.class when`: a bare path (truthy) **or** the comparisons `==` `!=` `<` `<=` `>` `>=` `contains`, joined with `and`, `or`, and negated with `not`. Operands are loop-item paths, declared `:state`/`:store`, numbers, `"strings"`, or `true`/`false`/`null`. `:if plan == "pro" or seats >= 5` and `:else if trialDays > 0 and not expired` are now valid where only `:if plan` worked before. A bare path keeps the original zero-overhead fast path.
+- **Same reactivity rules, same security.** A condition over only static values still folds the branch at build time (`runtime: false` preserved); one over `:state` emits a reactive region (`data-wd-if` + `data-wd-if-expr`); one over a loop item evaluates per row (`data-wd-each-if`). The expression compiles to the same whitelisted form over `I()`/`S()`/`C()` and runs via the shared `evalPredicate` runtime helper — no new eval surface, and `constructor`/`prototype`/`__proto__` path segments stay rejected in compiler and runtime. `:else if` chains inherit this automatically.
+- **No grouping (caveat).** There is no parenthesis grouping; `and`/`or` associate left-to-right with no precedence between them. Split into `:else if` branches or a `:computed` boolean when grouping matters. `@loop … where` stays the comparison-only subset of this grammar (no `not`, no bare-truthy form).
+- **Fix — nested global conditionals re-evaluate after an outer flip.** When a page-level (non-loop) `:if` flips to its falsy branch, the runtime now recurses into the freshly injected branch and evaluates any nested conditional (the desugared `:else if` tail) in the same pass. Previously the injected nested region kept its build-time branch until the next unrelated render. This also corrects bare-path nested `:else if` chains over page state, not just the new comparison form.
+
 ## 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).

package/README.md

@@ -259,7 +259,7 @@ A container class can be toggled by a predicate. Static `.class` tokens are unch
 @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.
+The predicate uses the same whitelist as `:if` — item fields, declared `:state`/`:store`, numbers, strings, the `==`/`!=`/`>`/`<`/`>=`/`<=`/`contains` operators, and `and`/`or`/`not`. A bare path (`.featured when p.featured`) reads as truthy. (`@loop … where` is the comparison-only subset of this grammar.) 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
 
@@ -270,26 +270,28 @@ Count: { count }
 
 :button "Increment" -> count++
 
-:if count
+:if count >= 10
+Count is high.
+:else if count > 0
 Count has changed.
 :else
 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:
+A condition reads the same predicate grammar as `.class when`: a bare path (truthy), or the comparisons `==` `!=` `<` `<=` `>` `>=` `contains`, joined with `and`, `or`, and `not`. (`@loop … where` is the comparison-only subset — operators with `and`/`or`.) Chain with `:else if` (any number; an optional bare `:else` must be the last branch):
 
 ```wd
-:if isPro
+:if plan == "pro" or seats >= 5
 Pro plan
-:else if isTrial
-Trial — { daysLeft } days left
+:else if trialDays > 0 and not expired
+Trial — { trialDays } 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`.
+A whole chain compiles to nested conditional regions, so it stays reactive (or folds at build time when every value is static) exactly like a single `:if`.
 
 Directive actions are intentionally narrow and compile-time checked. Arbitrary JavaScript belongs in colocated `.js` files.
 
@@ -350,7 +352,7 @@ Effects run after a render, against settled state, and an effect that mutates st
 `:fetch name from "url"` declares state and fills it from JSON over the network:
 
 ```
-:fetch <name> from "<url>" [method=GET] [when=load|visible] [timeout=<ms>] [retry=<N>] [headers=<key>] [body=<key>]
+:fetch <name> from "<url>" [method=GET] [when=load|visible] [timeout=<ms>] [retry=<N>] [headers=<key>] [body=<key>] [refresh=<url>]
 ```
 
 Each fetch automatically declares four state keys you can branch on:

package/docs/spec-alignment.md

@@ -51,7 +51,7 @@ This audit compares the current Darkmown implementation with the original MARROW
 - **Nested `:if` over loop items (v0.5.0):** conditionals nest inside reactive `@loop`, per row. Both fill paths fixed — build-time balanced `matchElement` recursion and runtime `fillItem` recursion.
 - **State-driven list filtering — `@loop … where <predicate>`:** the #1 need surfaced by the agent-eval benchmark. Conditions (`field <op> value`, plus `contains`) join with `and` / `or` over a compile-time-validated whitelist — item paths, declared `:state`, numbers, strings; `constructor`/`prototype`/`__proto__` rejected. Raw user content is never evaluated; the validated predicate compiles to the whitelisted grammar and runs via `new Function` at runtime. The source decides reactivity, matching the loop itself: an item-only predicate filters at build time and stays zero-JS; a predicate that reads `:state` compiles to a reactive filtered loop (rows baked in for static sources). This replaces the fragile DOM-toggle escape hatch with the keyed reconciler.
 - **`:bind <state>`:** two-way `<input>` bound to a `:state` value — the input primitive that powers live search. Accepts `type=`, `placeholder=`, `autocomplete=`, `required`, `autofocus`.
-- **Per-row actions in reactive loops:** a `:button` inside `@loop … into item` can act on its own row — `cart += item` appends a copy of the row to another `:state` list (the only way to carry a loop item into another list), and `list remove item` removes the row from the looped `:state` source (both names compile-checked against the enclosing loop). The runtime resolves the clicked row by stamping each reconciled node with its item, so removal is exact even under a `where` filter. This closes the last "store demo" gap noted in the design memory (per-row `:button` couldn't carry row data); `:if` string-equality remains the only listed gap, now partly covered by `@loop … where`.
+- **Per-row actions in reactive loops:** a `:button` inside `@loop … into item` can act on its own row — `cart += item` appends a copy of the row to another `:state` list (the only way to carry a loop item into another list), and `list remove item` removes the row from the looped `:state` source (both names compile-checked against the enclosing loop). The runtime resolves the clicked row by stamping each reconciled node with its item, so removal is exact even under a `where` filter. This closes the last "store demo" gap noted in the design memory (per-row `:button` couldn't carry row data). (The `:if` string-equality gap noted here was fully closed in v0.14.0 — see Stage 10 — when `:if` gained the comparison grammar.)
 - **`.skin` robustness:** `@media`/`@supports` at-rules wrap nested rules; the `font` shorthand passes through (size-led or containing `/`) while `font <stack>` still aliases to `font-family`; `/* … */` block comments and decorative divider lines are skipped.
 - **Editor tooling:** VS Code extension (`editors/vscode`) ships `.wd` + `.skin` TextMate grammars, snippets, and folding, grammar-tested in CI.
 - **`AGENTS.md`:** a model-facing build guide (shipped in the npm files array), tuned over a 5-round agent-eval benchmark that lifted build quality from 2.78→4.51/5.
@@ -62,18 +62,22 @@ Three capability gaps from the 2026-06-16 audit, closed together over a shared `
 
 - **Global state — `:store`:** `:store name = value [ephemeral]` declares page-global, durable-by-default state. Non-ephemeral stores persist to `localStorage["wd:store:<name>"]`, hydrate the declared value as a seed only when absent (first write wins thereafter), and sync across tabs via a single `storage` listener that re-renders on change. `ephemeral` opts out of persistence and cross-tab sync (in-memory for the session). Stores are never section-scoped; they share the runtime `state` object with `:state`, and a compile-time collision check keeps the two namespaces disjoint (declaring a `:store` and `:state` with one name, or a store twice, is a path-and-suggestion compile error). Reads (`{ cart }`, `:if`, `@loop`, `:computed`) and all actions resolve stores identically to state.
 - **Full action vocabulary:** `:button … ->` now covers `inc`/`dec` (`n++`, `n--`), `add`/`sub` (`n += k`, `n -= k`), `set` (`name = v`), `toggle` (`flag toggle`), `append` (`list append v` / `list += v`), `prepend`, `member-toggle` (`list toggle v`), `remove-value` (`list remove v`), `clear`, `merge` (`obj merge <key|{…}>`), `delete` (`obj delete "key"`), and `reset` (restore the declared seed) — alongside the existing `append-row` (`cart += item`) and per-row `remove`. Targets are dotted-path aware (`cart.count++`) via a safe `setPath` mirroring `getPath` (proto-pollution guards in compiler and runtime). Buttons may carry a `;`-separated action sequence, applied in order with a single render. Operands are the compile-validated literal grammar (string / number / boolean / null / inline JSON; merge also accepts a bare state/store key). **Honest caveat:** `member-toggle` and `remove-value` compare by value with `===`/`includes`, so they are reliable for primitive members but not for object members (two equal-looking objects are distinct values) — remove row objects with the per-row `remove` action instead.
-- **Fetch lifecycle:** `:fetch name from "url" [method=] [when=load|visible] [timeout=ms] [retry=N] [headers=key] [body=key]`. Each fetch auto-declares four states — `name` (null), `name_loading` (false), `name_error` (null), `name_empty` (false, true for `null`/`[]`/`{}`) — enabling the recommended loading → error → empty → data pattern (with `@empty` absorbing the empty case for list fetches). URLs may interpolate `{ state }` and auto-refetch (≈150 ms debounce) when a dependency key changes, skipping while a required value is empty. A `refetch` action (`name refetch`) re-triggers a load on demand. Full HTTP via `method`/`headers`/`body`; `timeout` arms an AbortController; `retry` backs off on network error or 5xx before surfacing the error.
+- **Fetch lifecycle:** `:fetch name from "url" [method=] [when=load|visible] [timeout=ms] [retry=N] [headers=key] [body=key] [refresh=url]` (`headers=`/`refresh=` detailed under Stage 9). Each fetch auto-declares four states — `name` (null), `name_loading` (false), `name_error` (null), `name_empty` (false, true for `null`/`[]`/`{}`) — enabling the recommended loading → error → empty → data pattern (with `@empty` absorbing the empty case for list fetches). URLs may interpolate `{ state }` and auto-refetch (≈150 ms debounce) when a dependency key changes, skipping while a required value is empty. A `refetch` action (`name refetch`) re-triggers a load on demand. Full HTTP via `method`/`headers`/`body`; `timeout` arms an AbortController; `retry` backs off on network error or 5xx before surfacing the error.
 - **Loop ergonomics:** `@loop src into item [where …] [sort by key [asc|desc]] [reverse] [offset N] [limit N]`, clauses in that fixed order. `sort by` keys must start with the loop item (`item.path`); the comparator is numeric when both values are numbers, else `String(...).localeCompare`. `offset`/`limit` accept an integer **or** a `:state`/`:store` key for reactive pagination. Per-row meta vars — `$index` (0-based), `$number` (1-based), `$first`, `$last`, `$count` — are usable in interpolation and `:if`. An `@empty` branch renders when the post-pipeline row count is 0. **Honest caveat:** `sort by` over null/missing keys is best-effort — those values stringify (`"null"`/`"undefined"`) and fall into the lexicographic `localeCompare` path rather than getting special handling. Every clause stays build-time when the source and all arguments are static, preserving `runtime: false`.
 
 ## Stage 7 additions (2026-06-14)
 
 - **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 10 additions (2026-06-18, v0.14.0)
+
+- **Richer `:if` / `:else if` conditions:** a conditional now accepts the same compile-time-validated predicate grammar as `.class when` (its sibling through the shared `compileWhen`) — instead of a bare truthy path only. Operands are item paths, declared `:state`/`:store`, numbers, `"strings"`, `true`/`false`/`null`; comparisons `==` `!=` `<` `<=` `>` `>=` and `contains`; joined with `and` / `or` and negated with `not`. A bare path still reads as truthy (the fast path is unchanged). (`@loop … where` stays a comparison-only subset — each condition needs an operator; it has no `not` or bare-truthy form. Unifying it is deferred, not done here.) Reactivity is decided exactly as before: a predicate over only static values folds the branch at build time (`runtime: false` preserved); one over `:state` emits a global `data-wd-if` region carrying `data-wd-if-expr`; one over a loop item emits a per-row `data-wd-each-if` with `data-wd-if-expr`. The expression compiles to the **same** whitelisted grammar over `I()`/`S()`/`C()` and runs via `new Function` through the shared `evalPredicate` runtime helper — no new eval surface, and `constructor`/`prototype`/`__proto__` segments stay rejected in compiler and runtime. `:else if` chains inherit this automatically (each desugared condition re-enters the same path). **Honest caveat:** there is no parenthesis grouping — `and`/`or` associate left-to-right with no precedence between them, so model intent explicitly (split into `:else if` branches or a `:computed` boolean when grouping matters).
+
 ## 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).
+- **`: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. (v0.13.0 accepted only a bare truthy path per condition; Stage 10 / v0.14.0 lifted that to the full predicate grammar.)
 - **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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/darkmown",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "private": false,
   "publishConfig": {
     "access": "public"

package/site/pages/docs/index.wd

@@ -198,19 +198,19 @@ Directive actions are intentionally narrow and compile-time checked. Arbitrary J
 
 ### 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:
+A condition reads the same predicate grammar as `.class when` — a bare path (truthy), or the comparisons `==` `!=` `<` `<=` `>` `>=` `contains`, joined with `and`, `or`, and `not`. (`@loop … where` is the comparison-only subset.) Chain with `:else if` (any number; a bare `:else` must come last):
 
 ```wd
-:if isPro
+:if plan == "pro" or seats >= 5
 Pro plan
-:else if isTrial
-Trial — { daysLeft } days left
+:else if trialDays > 0 and not expired
+Trial — { trialDays } 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`.
+A whole chain compiles to nested conditional regions, so it folds at build time when every value is static and stays reactive otherwise — exactly like a single `:if`.
 
 ### Reactive classes — `.class when …`
 
@@ -224,7 +224,7 @@ A container class can react to state or the loop item. Static `.class` tokens st
 @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.
+The predicate uses the `:if` whitelist (item fields, `:state`, numbers, strings, comparisons, `and`/`or`/`not`, `contains`). A static predicate folds to a plain class at build; a state or loop-item predicate stays reactive.
 
 ### Effects — `:effect`
 
@@ -330,6 +330,7 @@ See [SECURITY.md](https://github.com/ZVN-DEV/darkmown/blob/main/SECURITY.md) in
 - A matching `.skin` file attaches CSS to the page (indentation-based, compiles to real CSS).
 - A matching `.js` file attaches page behavior.
 - Both work for included fragments too, by basename.
+- Any other file under `site/pages/` (an image, font, PDF — anything that isn't a `.md`/`.wd` route or a basename-matched `.skin`/`.js`) copies to `dist/` at its own path with the right content-type. So `site/pages/logo.svg` is served at `/logo.svg`. Use the `site/_/` shelf for assets shared across pages; colocate the ones a single page owns.
 
 ## Spec status
 

package/site/pages/reactive.wd

@@ -16,6 +16,16 @@ The count is { count }.
 
 :button "Increment" -> count++
 
+`:if` reads JavaScript-style comparisons — `==` `!=` `<` `<=` `>` `>=` `contains` — joined with `and`, `or`, and `not`. This chain reacts to the counter above, no handler wired by hand:
+
+:if count >= 3 and count <= 5
+Counter is in the sweet spot (3–5).
+:else if count > 5
+Counter is over the top.
+:else
+Counter is warming up.
+:endif
+
 :state open = false
 
 :button "Show details" -> open = true

package/src/compiler.js

@@ -1159,48 +1159,71 @@ function handleEffect(line, ctx) {
  * @returns {string}
  */
 function handleIf(line, truthyLines, falsyLines, ctx) {
-  const match = line.match(/^:if\s+([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)\s*$/);
-  if (!match) throw new Error(`Malformed :if in ${ctx.file}: ${line}. Use ":if name" with a :state or in-scope value.`);
-  const segs = match[1].split(".");
-  const head = segs[0];
+  const condition = line.replace(/^:if\s+/, "").trim();
+  // Fast path: a bare truthy dotted path (`:if open`, `:if item.done`). Keeps the
+  // existing markup/behavior identical. Anything with operators (`>`, `==`, `and`,
+  // `not`, …) falls through to the predicate path below.
+  const match = condition.match(/^([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)$/);
+  if (match) {
+    const segs = match[1].split(".");
+    const head = segs[0];
+
+    // Per-row meta vars in :if — only valid inside a loop.
+    if (LOOP_META[head]) {
+      if (!ctx.loopMeta) throw new Error(`":if ${match[1]}" uses the loop meta variable "${head}" outside a @loop in ${ctx.file}. Use it inside a loop body.`);
+      if (ctx.loopItem) {
+        const truthy = compileBody(truthyLines, ctx).trim();
+        const falsy = compileBody(falsyLines, ctx).trim();
+        return `<span data-wd-each-if data-wd-meta="${LOOP_META[head]}"><template data-wd-if-true>${truthy}</template><template data-wd-if-false>${falsy}</template><span data-wd-each-if-out></span></span>`;
+      }
+      // static: the meta boolean is in scope — fall through to the static branch below.
+    }
 
-  // Per-row meta vars in :if — only valid inside a loop.
-  if (LOOP_META[head]) {
-    if (!ctx.loopMeta) throw new Error(`":if ${match[1]}" uses the loop meta variable "${head}" outside a @loop in ${ctx.file}. Use it inside a loop body.`);
-    if (ctx.loopItem) {
+    const staticValue = lookupVar(ctx.scope, head);
+    if (staticValue.found) {
+      const active = Boolean(getPath(staticValue.value, segs.slice(1)));
+      return compileBody(active ? truthyLines : falsyLines, ctx);
+    }
+
+    if (ctx.loopItem && head === ctx.loopItem) {
       const truthy = compileBody(truthyLines, ctx).trim();
       const falsy = compileBody(falsyLines, ctx).trim();
-      return `<span data-wd-each-if data-wd-meta="${LOOP_META[head]}"><template data-wd-if-true>${truthy}</template><template data-wd-if-false>${falsy}</template><span data-wd-each-if-out></span></span>`;
+      const rest = segs.slice(1).join(".");
+      const pathAttr = ` data-wd-path="${escapeHtml(rest)}"`;
+      return `<span data-wd-each-if${pathAttr}><template data-wd-if-true>${truthy}</template><template data-wd-if-false>${falsy}</template><span data-wd-each-if-out></span></span>`;
     }
-    // static: the meta boolean is in scope — fall through to the static branch below.
-  }
-
-  const staticValue = lookupVar(ctx.scope, head);
-  if (staticValue.found) {
-    const active = Boolean(getPath(staticValue.value, segs.slice(1)));
-    return compileBody(active ? truthyLines : falsyLines, ctx);
-  }
 
-  if (ctx.loopItem && head === ctx.loopItem) {
+    const key = resolveStateKey(head, ctx);
+    if (!key) {
+      throw new Error(`:if ${match[1]} in ${ctx.file} does not match a :state or in-scope value. Declare it first.`);
+    }
+    ctx.comp.assets.runtime = true;
     const truthy = compileBody(truthyLines, ctx).trim();
     const falsy = compileBody(falsyLines, ctx).trim();
-    const rest = segs.slice(1).join(".");
-    const pathAttr = ` data-wd-path="${escapeHtml(rest)}"`;
-    return `<span data-wd-each-if${pathAttr}><template data-wd-if-true>${truthy}</template><template data-wd-if-false>${falsy}</template><span data-wd-each-if-out></span></span>`;
-  }
-
-  const key = resolveStateKey(head, ctx);
-  if (!key) {
-    throw new Error(`:if ${match[1]} in ${ctx.file} does not match a :state or in-scope value. Declare it first.`);
-  }
+    const restPath = segs.slice(1).join(".");
+    const pathAttr = restPath ? ` data-wd-path="${escapeHtml(restPath)}"` : "";
+    const initialTruthy = Boolean(getPath(ctx.comp.state.get(key), segs.slice(1)));
+    const active = initialTruthy ? truthy : falsy;
+    return `<div data-wd-if="${key}"${pathAttr} data-wd-if-active="${initialTruthy}"><template data-wd-true>${truthy}</template><template data-wd-false>${falsy}</template><div data-wd-if-out>${active}</div></div>`;
+  }
+
+  // Predicate path: a comparison / logical condition. Compiles through the same
+  // whitelist as `@loop … where` / `.class when` (with `not`), so it folds at
+  // build when static, drives a per-row each-if when it reads the loop item, and
+  // a global if-region (evaluated each render) when it reads state. No raw eval.
+  if (!condition) throw new Error(`Malformed :if in ${ctx.file}: ${line}. Use ":if name" or ":if a <op> b [and|or|not …]".`);
+  const compiled = compileWhen(condition, ctx, '":if"');
+  if (compiled.static) return compileBody(compiled.value ? truthyLines : falsyLines, ctx);
   ctx.comp.assets.runtime = true;
   const truthy = compileBody(truthyLines, ctx).trim();
   const falsy = compileBody(falsyLines, ctx).trim();
-  const restPath = segs.slice(1).join(".");
-  const pathAttr = restPath ? ` data-wd-path="${escapeHtml(restPath)}"` : "";
-  const initialTruthy = Boolean(getPath(ctx.comp.state.get(key), segs.slice(1)));
+  const exprAttr = ` data-wd-if-expr="${escapeHtml(compiled.body)}"`;
+  if (compiled.item) {
+    return `<span data-wd-each-if${exprAttr}><template data-wd-if-true>${truthy}</template><template data-wd-if-false>${falsy}</template><span data-wd-each-if-out></span></span>`;
+  }
+  const initialTruthy = evalPredicate(compiled.body, undefined, ctx);
   const active = initialTruthy ? truthy : falsy;
-  return `<div data-wd-if="${key}"${pathAttr} data-wd-if-active="${initialTruthy}"><template data-wd-true>${truthy}</template><template data-wd-false>${falsy}</template><div data-wd-if-out>${active}</div></div>`;
+  return `<div data-wd-if=""${exprAttr} data-wd-if-active="${initialTruthy}"><template data-wd-true>${truthy}</template><template data-wd-false>${falsy}</template><div data-wd-if-out>${active}</div></div>`;
 }
 
 // The fixed corrective suggestion shown for any malformed @loop header.
@@ -1503,24 +1526,25 @@ function evalPredicate(body, item, ctx) {
  * resolution order.
  * @param {string} tok
  * @param {Ctx} ctx
+ * @param {string} what Directive label for error messages.
  * @returns {{ code: string, state: boolean, item: boolean }}
  */
-function compileWhenOperand(tok, ctx) {
+function compileWhenOperand(tok, ctx, what) {
   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".`);
+    throw new Error(`Unsupported operand "${tok}" in ${what} (${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})`);
+    throw new Error(`Path "${tok}" is not allowed in ${what} (${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".`);
+  if (!key) throw new Error(`${what} 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 };
 }
@@ -1533,9 +1557,10 @@ function compileWhenOperand(tok, ctx) {
  * (which decides data-wd-each-class vs the global data-wd-class).
  * @param {string} raw
  * @param {Ctx} ctx
+ * @param {string} [what] Directive label for error messages.
  * @returns {{ static: true, value: boolean } | { static: false, body: string, item: boolean }}
  */
-function compileWhen(raw, ctx) {
+function compileWhen(raw, ctx, what = '"::: … when"') {
   const parts = raw.split(/\s+(and|or)\s+/i);
   /** @type {string[]} */
   const pieces = [];
@@ -1543,21 +1568,26 @@ function compileWhen(raw, ctx) {
   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();
+    let seg = parts[i].trim();
+    // Optional leading `not` negates the whole sub-condition.
+    let negate = false;
+    if (/^not\s+/i.test(seg)) { negate = true; seg = seg.replace(/^not\s+/i, "").trim(); }
     const opMatch = seg.match(/^(.+?)\s+(contains|==|!=|>=|<=|>|<)\s+(.+)$/i);
+    let expr;
     if (opMatch) {
-      const left = compileWhenOperand(opMatch[1].trim(), ctx);
-      const right = compileWhenOperand(opMatch[3].trim(), ctx);
+      const left = compileWhenOperand(opMatch[1].trim(), ctx, what);
+      const right = compileWhenOperand(opMatch[3].trim(), ctx, what);
       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})`);
+      expr = op === "contains" ? `C(${left.code}, ${right.code})` : `${left.code} ${op} ${right.code}`;
     } else {
-      const only = compileWhenOperand(seg, ctx);
+      const only = compileWhenOperand(seg, ctx, what);
       usesState = usesState || only.state;
       usesItem = usesItem || only.item;
-      pieces.push(`(${only.code})`);
+      expr = only.code;
     }
+    pieces.push(negate ? `(!(${expr}))` : `(${expr})`);
   }
   const body = pieces.join(" ");
   if (!usesState && !usesItem) return { static: true, value: evalPredicate(body, undefined, ctx) };

package/src/runtime.js

@@ -205,12 +205,20 @@ function classToggle(el, raw, item) {
   /** @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);
-  }
+  for (const [name, body] of pairs) el.classList.toggle(name, evalPredicate(body, item));
+}
+
+/**
+ * Evaluate a compiled whitelist predicate body (over I()/S()/C()) to a boolean.
+ * Shared by reactive classes (`.class when`) and expression conditionals
+ * (`:if a > b`). `item` is the loop row for per-row predicates, else undefined.
+ * @param {string} body
+ * @param {any} item
+ * @returns {boolean}
+ */
+function evalPredicate(body, item) {
+  try { return 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); return false; }
 }
 
 /**
@@ -241,8 +249,9 @@ function fillItem(node, item, meta = {}) {
   // 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]")) {
+    const expr = region.getAttribute("data-wd-if-expr");
     const m = region.getAttribute("data-wd-meta");
-    const value = m ? meta[m] : getPath(item, region.getAttribute("data-wd-path"));
+    const value = expr ? evalPredicate(expr, item) : (m ? meta[m] : getPath(item, region.getAttribute("data-wd-path")));
     const output = region.querySelector("[data-wd-each-if-out]");
     if (!output) continue;
     const template = /** @type {HTMLTemplateElement | null} */ (region.querySelector(value ? "template[data-wd-if-true]" : "template[data-wd-if-false]"));
@@ -301,6 +310,31 @@ function pipeline(list, region) {
   return list;
 }
 
+/**
+ * Evaluate one global `data-wd-if` region against current state and swap its
+ * branch when the truthiness flips. `data-wd-if-expr` carries a compiled
+ * predicate (richer `:if`); otherwise it is a bare-path truthiness test. On a
+ * swap, the freshly injected branch can carry nested if-regions (a desugared
+ * `:else if`) that were never in the live tree this pass — querySelectorAll
+ * skips <template> content — so recurse to fill them. Unchanged regions are
+ * left alone; their already-live nested regions are reached by renderNow's
+ * document-wide query.
+ * @param {Element} node
+ * @returns {void}
+ */
+function renderIf(node) {
+  const expr = node.getAttribute("data-wd-if-expr");
+  const value = expr ? evalPredicate(expr, undefined) : getPath(state[node.getAttribute("data-wd-if") || ""], node.getAttribute("data-wd-path"));
+  const active = String(Boolean(value));
+  if (node.getAttribute("data-wd-if-active") === active) return;
+  node.setAttribute("data-wd-if-active", active);
+  const output = node.querySelector("[data-wd-if-out]");
+  if (!output) return;
+  const template = /** @type {HTMLTemplateElement | null} */ (node.querySelector(value ? "template[data-wd-true]" : "template[data-wd-false]"));
+  output.innerHTML = template?.innerHTML || "";
+  for (const nested of output.querySelectorAll("[data-wd-if]")) renderIf(nested);
+}
+
 /**
  * Synchronously render the whole document from current `state`:
  * computed → if-regions → keyed loop reconcile → text/input binds.
@@ -308,16 +342,7 @@ function pipeline(list, region) {
  */
 function renderNow() {
   recompute();
-  for (const node of document.querySelectorAll("[data-wd-if]")) {
-    const value = getPath(state[node.getAttribute("data-wd-if") || ""], node.getAttribute("data-wd-path"));
-    const active = String(Boolean(value));
-    if (node.getAttribute("data-wd-if-active") === active) continue;
-    node.setAttribute("data-wd-if-active", active);
-    const output = node.querySelector("[data-wd-if-out]");
-    if (!output) continue;
-    const template = /** @type {HTMLTemplateElement | null} */ (node.querySelector(value ? "template[data-wd-true]" : "template[data-wd-false]"));
-    output.innerHTML = template?.innerHTML || "";
-  }
+  for (const node of document.querySelectorAll("[data-wd-if]")) renderIf(node);
 
   // Reactive styling: toggle state-driven `.class when …` bindings. Loop-row
   // bindings (data-wd-each-class) are handled per item inside fillItem.

package/src/scaffold.js

@@ -128,10 +128,19 @@ export function initProject(root) {
     "",
     "Run `npm install` and `npm run dev` to start the live compiler.",
     "",
+    "## Commands",
+    "",
+    "- `npm run dev` — live compiler on http://localhost:5173 with hot reload.",
+    "- `npm run build` — compile the site to `dist/`.",
+    "- `npm run preview` — serve the built `dist/` locally.",
+    "",
+    "## Layout",
+    "",
     "- Pages live in `site/pages`.",
     "- Shared includes live in `site/_`.",
     "- Hidden route files start with `.` or `-`.",
-    "- Colocated `index.skin` and `index.js` attach automatically."
+    "- Colocated `index.skin` and `index.js` attach automatically.",
+    "- Any other file under `site/pages` (images, fonts, …) copies to `dist/` at its own path."
   ].join("\n"));
   return { root };
 }