@zvndev/darkmown 0.12.0 → 0.13.0

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/cli.js

@@ -10,7 +10,9 @@ import { initProject } from "./scaffold.js";
 import { contentType, resolvePublicFile, serve } from "./statics.js";
 
 const cliPath = fileURLToPath(import.meta.url);
-const command = process.argv[2] || "build";
+// Bare `darkmown` prints help (discovery) rather than silently building — a new
+// user typing the command alone expects to see what it can do, not a no-op build.
+const command = process.argv[2] || "help";
 
 if (command === "help" || command === "--help" || command === "-h") {
   printHelp();
@@ -18,14 +20,24 @@ if (command === "help" || command === "--help" || command === "-h") {
   const pkg = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
   console.log(pkg.version);
 } else if (command === "init") {
-  const target = process.argv[3] || ".";
-  const result = initProject(path.resolve(process.cwd(), target));
-  const relativeRoot = path.relative(process.cwd(), result.root) || ".";
-  console.log(`Created Darkmown project at ${relativeRoot}`);
-  console.log(`Next: ${nextStep(relativeRoot)}`);
+  try {
+    const target = process.argv[3] || ".";
+    const result = initProject(path.resolve(process.cwd(), target));
+    const relativeRoot = path.relative(process.cwd(), result.root) || ".";
+    console.log(`Created Darkmown project at ${relativeRoot}`);
+    console.log(`Next: ${nextStep(relativeRoot)}`);
+  } catch (error) {
+    failClean(error);
+  }
 } else if (command === "build") {
-  const result = buildSite();
-  console.log(`Built ${result.routes.length} routes into ${path.relative(process.cwd(), result.distRoot)}`);
+  try {
+    const result = buildSite();
+    console.log(`Built ${result.routes.length} routes into ${path.relative(process.cwd(), result.distRoot)}`);
+  } catch (error) {
+    // A compile error has a clear, file-pathed message — print just that, not a
+    // Node stack trace, so a typo reads as "fix your page", not "the tool crashed".
+    failClean(error);
+  }
 } else if (command === "dev") {
   const port = Number(process.env.PORT || 5173);
   const host = process.env.HOST || "127.0.0.1";
@@ -170,6 +182,17 @@ function broadcast(clients, message) {
   for (const client of clients) client.write(message);
 }
 
+/**
+ * Print a compile/CLI error as a single clean line and exit non-zero — no Node
+ * stack trace. The thrown Error already carries the file path + corrective hint.
+ * @param {unknown} error
+ * @returns {never}
+ */
+function failClean(error) {
+  console.error(`✗ ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+}
+
 function printHelp() {
   console.log(`Darkmown
 

package/src/compiler.js

@@ -110,13 +110,24 @@ export function compilePage(file, context) {
   const compiled = compileDocument(file, context);
   const title = compiled.meta.title || "Darkmown";
   const description = compiled.meta.description || "";
-  const descriptionTag = description
-    ? `\n  <meta name="description" content="${escapeHtml(description)}">
-  <meta property="og:title" content="${escapeHtml(title)}">
-  <meta property="og:description" content="${escapeHtml(description)}">
-  <meta property="og:type" content="website">
-  <meta name="twitter:card" content="summary">`
-    : "";
+  // Optional `image:` frontmatter sets the social-share preview (absolute URL).
+  const image = typeof compiled.meta.image === "string" ? compiled.meta.image : "";
+  /** @type {string[]} */
+  const social = [];
+  if (description) social.push(`<meta name="description" content="${escapeHtml(description)}">`);
+  if (description || image) {
+    social.push(`<meta property="og:title" content="${escapeHtml(title)}">`);
+    if (description) social.push(`<meta property="og:description" content="${escapeHtml(description)}">`);
+    social.push(`<meta property="og:type" content="website">`);
+  }
+  if (image) {
+    social.push(`<meta property="og:image" content="${escapeHtml(image)}">`);
+    social.push(`<meta name="twitter:image" content="${escapeHtml(image)}">`);
+  }
+  if (description || image) {
+    social.push(`<meta name="twitter:card" content="${image ? "summary_large_image" : "summary"}">`);
+  }
+  const descriptionTag = social.length ? `\n  ${social.join("\n  ")}` : "";
   const favicon = "data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%2032%2032'%3E%3Crect%20width='32'%20height='32'%20rx='6'%20fill='%2318221d'/%3E%3Ctext%20x='16'%20y='23'%20text-anchor='middle'%20font-family='Georgia,serif'%20font-size='19'%20font-weight='bold'%20fill='%23f7f3ea'%3ED%3C/text%3E%3C/svg%3E";
   const cssLinks = [...compiled.assets.skins].map((href) => `<link rel="stylesheet" href="${href}">`).join("\n");
   const scriptSrcs = compiled.assets.runtime ? ["/__wd/runtime.js", ...compiled.assets.scripts] : [...compiled.assets.scripts];
@@ -366,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);
@@ -531,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.
@@ -543,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++) {
@@ -560,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);
   }
@@ -623,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}`;
@@ -650,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}>`;
 }
 
 /**
@@ -729,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.
@@ -744,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]);
@@ -768,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.
@@ -800,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
@@ -1020,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
@@ -1364,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",