@zvndev/darkmown 0.12.1 → 0.14.0

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
@@ -39,30 +49,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 … :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:
 
-`: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:
+<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 +97,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
@@ -1039,48 +1159,71 @@ function handleButton(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.
@@ -1375,6 +1518,82 @@ 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
+ * @param {string} what Directive label for error messages.
+ * @returns {{ code: string, state: boolean, item: boolean }}
+ */
+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 ${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 ${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(`${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 };
+}
+
+/**
+ * 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
+ * @param {string} [what] Directive label for error messages.
+ * @returns {{ static: true, value: boolean } | { static: false, body: string, item: boolean }}
+ */
+function compileWhen(raw, ctx, what = '"::: … when"') {
+  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; }
+    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, 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();
+      expr = op === "contains" ? `C(${left.code}, ${right.code})` : `${left.code} ${op} ${right.code}`;
+    } else {
+      const only = compileWhenOperand(seg, ctx, what);
+      usesState = usesState || only.state;
+      usesItem = usesItem || only.item;
+      expr = only.code;
+    }
+    pieces.push(negate ? `(!(${expr}))` : `(${expr})`);
+  }
+  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