@zvndev/darkmown 2.6.1-next.11.g82bb8d7 → 2.7.0

package/src/runtime.js

@@ -17,42 +17,144 @@ const persistKeys = new Set();
 /** @type {Set<string>} Non-ephemeral :store names, persisted under wd:store:<name>. */
 const storeKeys = new Set();
 
-for (const script of document.querySelectorAll("script[data-wd-state]")) {
-  Object.assign(state, JSON.parse(script.textContent || "{}"));
-  const persist = script.getAttribute("data-wd-persist");
-  if (persist) persistKeys.add(persist);
-}
-for (const script of document.querySelectorAll("script[data-wd-store]")) {
-  const name = script.getAttribute("data-wd-store") || "";
-  state[name] = JSON.parse(script.textContent || "null");
-  if (!script.hasAttribute("data-wd-store-ephemeral")) storeKeys.add(name);
-}
+/** @type {Set<string>} Keys a `:state … from-url` mirrors into the query string. */
+const urlKeys = new Set();
 
-// Frozen seed snapshot, taken BEFORE localStorage overrides below, so `reset`
-// deep-clones the declared value — not the last persisted one.
+// Seed snapshot, recorded per key BEFORE its localStorage/URL override, so
+// `reset` deep-clones the DECLARED value — not the last persisted one.
 /** @type {Record<string, any>} */
-const initials = Object.freeze(JSON.parse(JSON.stringify(state)));
+const initials = {};
 
-for (const key of persistKeys) {
-  const stored = localStorage.getItem(`wd:${key}`);
-  if (stored === null) continue;
+/**
+ * Best-effort localStorage. Touching it THROWS outright in a sandboxed iframe or
+ * a browser set to block site data, and setItem throws on quota — persistence
+ * must never abort the boot or stop a render, so every access is swallowed here.
+ * `ls(k)` reads, `ls(k, v)` writes, `ls(k, null)` drops a corrupt entry.
+ * @param {string} k
+ * @param {string | null} [v]
+ * @returns {any}
+ */
+function ls(k, v) {
   try {
-    state[key] = JSON.parse(stored);
-  } catch {
-    localStorage.removeItem(`wd:${key}`);
+    return v === undefined ? localStorage.getItem(k) : v === null ? localStorage.removeItem(k) : localStorage.setItem(k, v);
+  } catch { return null; }
+}
+
+/** The query-string parameter a state key mirrors to (`cart:items` → `cart.items`). */
+const urlParam = (/** @type {string} */ key) => key.replace(":", ".");
+
+/**
+ * Claim every seed `<script>` in the LIVE tree: apply the declared value for any
+ * key state does not already hold, record it as that key's reset seed, then let
+ * localStorage and the query string override it in that order.
+ *
+ * Boot runs this over the document; `scan()` runs it again whenever a render
+ * changes structure. That second call is the point: `querySelectorAll` cannot
+ * see into `<template>` content, so a `:state`/`:store`/`:theme` declared inside
+ * an unopened `:if` branch was never hydrated at all — it started undefined and
+ * never persisted. Re-opening a branch injects FRESH script nodes (the branch is
+ * cloned from a template each time), so the guard here is "state does not have
+ * this key yet", not a per-node claim: re-opening a branch must not reset what
+ * the reader already changed.
+ * @returns {void}
+ */
+function hydrate() {
+  for (const script of document.querySelectorAll("script[data-wd-state],script[data-wd-store]")) {
+    const store = script.getAttribute("data-wd-store");
+    const seed = JSON.parse(script.textContent || "null");
+    for (const [key, value] of store ? [[store, seed]] : Object.entries(seed || {})) {
+      if (key in state) continue;
+      // The seed is the reset baseline, so state gets a COPY: mutating a list
+      // through an action must not rewrite what `reset` restores.
+      state[key] = structuredClone((initials[key] = value));
+      const durable = store ? !script.hasAttribute("data-wd-store-ephemeral") : script.getAttribute("data-wd-persist") === key;
+      if (durable) {
+        (store ? storeKeys : persistKeys).add(key);
+        const lsKey = (store ? "wd:store:" : "wd:") + key;
+        const stored = ls(lsKey);
+        // A corrupt entry self-heals: drop it and keep the declared seed, rather
+        // than re-reading the same garbage on every load. A :store with nothing
+        // stored yet writes its seed so other tabs see it.
+        if (stored === null) { if (store) ls(lsKey, JSON.stringify(value ?? null)); }
+        else if (jsonOr(stored) === undefined) ls(lsKey, null);
+        else state[key] = jsonOr(stored);
+      }
+      // `from-url` outranks both: a shared link must show what it says.
+      if (script.getAttribute("data-wd-url") === key) {
+        urlKeys.add(key);
+        readUrl(false, [key]);
+      }
+    }
   }
 }
-for (const name of storeKeys) {
-  const stored = localStorage.getItem(`wd:store:${name}`);
-  if (stored === null) localStorage.setItem(`wd:store:${name}`, JSON.stringify(state[name] ?? null));
-  else try { state[name] = JSON.parse(stored); } catch { /** keep seed */ }
+
+/**
+ * Mirror every `from-url` key into the address bar. A value equal to its
+ * declared seed DROPS its parameter, so the default page keeps a clean URL, and
+ * the write is `replaceState`, so filtering never fills the back button.
+ * @returns {void}
+ */
+function syncUrl() {
+  if (!urlKeys.size) return;
+  const params = new URLSearchParams(location.search);
+  for (const key of urlKeys) {
+    const value = state[key];
+    if (JSON.stringify(value ?? null) === JSON.stringify(initials[key] ?? null)) params.delete(urlParam(key));
+    else params.set(urlParam(key), typeof value === "string" ? value : JSON.stringify(value));
+  }
+  const query = params.toString();
+  const next = location.pathname + (query ? `?${query}` : "") + location.hash;
+  if (next === location.pathname + location.search + location.hash) return;
+  // about:srcdoc (the playground's preview iframe) answers replaceState with a
+  // SecurityError. This call sits between the state write and the render in
+  // every handler, so an unguarded throw froze the preview on the first
+  // keystroke. Like `ls`, URL sync is best-effort and never blocks a paint.
+  try { history.replaceState(history.state, "", next); } catch { /* history is not writable here */ }
+}
+
+/**
+ * Re-read every `from-url` key from the address bar. `restore` is true for a
+ * popstate, where a parameter that is GONE means "back to the declared value";
+ * it is false while hydrating, where an absent parameter must leave the
+ * persisted value the storage read just restored.
+ * `only` narrows the read to the keys just claimed by `hydrate`: re-reading the
+ * WHOLE set there would revert a write the page has already made but not yet
+ * mirrored, which is exactly what happens when an `:effect` writes a `from-url`
+ * key and the same action opens a branch declaring another one.
+ * @param {boolean} [restore]
+ * @param {string[]} [only]
+ * @returns {void}
+ */
+function readUrl(restore, only) {
+  const params = new URLSearchParams(location.search);
+  for (const key of only || urlKeys) {
+    const raw = params.get(urlParam(key));
+    const seed = initials[key];
+    if (raw == null) { if (restore) state[key] = structuredClone(seed); }
+    else state[key] = typeof seed === "string" ? raw : jsonOr(raw) ?? raw;
+  }
 }
 
 function savePersisted() {
-  for (const key of persistKeys) localStorage.setItem(`wd:${key}`, JSON.stringify(state[key] ?? null));
-  for (const name of storeKeys) localStorage.setItem(`wd:store:${name}`, JSON.stringify(state[name] ?? null));
+  for (const key of persistKeys) ls(`wd:${key}`, JSON.stringify(state[key] ?? null));
+  for (const name of storeKeys) ls(`wd:store:${name}`, JSON.stringify(state[name] ?? null));
+  syncUrl();
 }
 
+hydrate();
+
+// Back/forward across `replaceState` history entries, and any other navigation
+// that changes the query string without a reload.
+window.addEventListener("popstate", () => {
+  if (!urlKeys.size) return;
+  readUrl(true);
+  // Storage follows the URL. Boot reads URL > storage > seed, so leaving a
+  // persisted value behind after a back to a parameter-less URL would show the
+  // seed now and flip back to the stored value on the next reload.
+  savePersisted();
+  render();
+});
+
 window.addEventListener("storage", (event) => {
   const name = event.key && event.key.startsWith("wd:store:") ? event.key.slice(9) : "";
   if (!storeKeys.has(name) || event.newValue == null) return;
@@ -119,6 +221,75 @@ function isEmpty(v) {
   return v == null || (typeof v === "object" && (Array.isArray(v) ? v.length : Object.keys(v).length) === 0);
 }
 
+/**
+ * Parse JSON, or undefined when the text is not JSON. `undefined` is a safe
+ * sentinel: no JSON document parses to it, so a body of literal `null` is still
+ * distinguishable from "not JSON at all".
+ * @param {string} text
+ * @returns {any}
+ */
+function jsonOr(text) {
+  try { return JSON.parse(text); } catch { return undefined; }
+}
+
+// The characters a value must not carry into a URL, mirroring `DEST_UNSAFE`
+// in src/compiler/markdown.js: an unencoded space or paren makes the paint and
+// the re-render disagree, and `tests/attr-binding.test.js` pins the two together.
+// biome-ignore lint/suspicious/noControlCharactersInRegex: intentional — a control character in a URL has to be encoded, not passed through.
+const URL_UNSAFE = /[\u0000-\u0020()<>"'`\\\u007F]/g;
+
+/**
+ * Every node matching `sel` at or under `node` — the self-match matters because
+ * a loop row's own element can carry the marker, not just its descendants.
+ * @param {Element} node
+ * @param {string} sel
+ * @returns {Element[]}
+ */
+const selfAnd = (node, sel) => (node.matches(sel) ? [node, ...node.querySelectorAll(sel)] : [...node.querySelectorAll(sel)]);
+
+/**
+ * Repaint one bound attribute (a markdown link/image destination that read
+ * `:state`, `:computed`, or a loop row). The marker is `[attr, …parts]`, where a
+ * part is either a literal string or a reader: `["s", key, path]` for state,
+ * `["m", name]` for a row meta variable, `["i", path]` for the row itself.
+ *
+ * The scheme guard is the load-bearing half. The compiler vets URLs the AUTHOR
+ * wrote; the value arriving here came from state, a form field, or a fetched
+ * payload, and nothing upstream has seen it. Control characters are stripped
+ * before the test because a browser strips them out of a URL before resolving
+ * it, so `java<TAB>script:` is a live javascript: URL. An unsafe value is not
+ * applied — the attribute is emptied instead. Mirrored by `unsafeUrlValue` in
+ * src/compiler/interpolation.js for the build-time paint.
+ * @param {Element} el
+ * @param {string | null} raw
+ * @param {any} item Loop row, or undefined outside one.
+ * @param {Record<string, any>} meta Per-row meta values.
+ * @returns {void}
+ */
+function applyAttr(el, raw, item, meta) {
+  if (!raw) return;
+  let parts;
+  try { parts = JSON.parse(raw); } catch { return; }
+  let out = ""; // encoded: what lands on the attribute
+  let plain = ""; // raw: what the scheme guard tests
+  for (let i = 1; i < parts.length; i++) {
+    const p = parts[i];
+    // A literal chunk is the author's own URL text, already vetted by the
+    // compiler; only a READER value is encoded, and with exactly the character
+    // set `encodeDest` uses in src/compiler/markdown.js, or the build-time paint
+    // and the first re-render would disagree on every value holding a space.
+    if (typeof p === "string") { out += p; plain += p; continue; }
+    const v = String((p[0] === "s" ? getPath(state[p[1]], p[2]) : p[0] === "m" ? meta[p[1]] : getPath(item, p[1])) ?? "");
+    plain += v;
+    out += v.replace(URL_UNSAFE, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}`);
+  }
+  // Defense in depth: the compiler only ever emits href (a link) or src (an
+  // image), so anything else in a marker did not come from a compile.
+  if (parts[0] !== "href" && parts[0] !== "src") return;
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional — a browser strips these out of a URL, so the guard must too.
+  el.setAttribute(parts[0], /^(javascript|data|vbscript):/i.test(plain.replace(/[\u0000-\u0020\u007F]+/g, "")) ? "" : out);
+}
+
 // --- Format pipes -----------------------------------------------------------
 // A compact mirror of src/compiler/format.js: the same formatter math, so a
 // reactive `{ value | money }` re-formats in the browser exactly as the static
@@ -202,19 +373,53 @@ const AGG = (/** @type {string} */ name, /** @type {any} */ list, /** @type {str
 async function httpJson(url, init) {
   const response = await fetch(url, init);
   const text = await response.text();
+  const body = jsonOr(text);
   if (!response.ok) {
-    const err = /** @type {Error & { status?: number }} */ (new Error(`HTTP ${response.status}`));
+    // A real API says WHY it refused. Prefer the body's own `error`/`message`
+    // string over the bare status line, and carry the parsed body along so a
+    // page can render field-level errors from `<name>_error_body`.
+    // The first NON-EMPTY string of the two: `{ "error": "", "message": "…" }`
+    // is a real shape, and `??` would keep the empty string and render "Error".
+    const said = body && [body.error, body.message].find((v) => typeof v === "string" && v);
+    const err = /** @type {Error & { status?: number, body?: any }} */ (new Error(said || `HTTP ${response.status}`));
     err.status = response.status; // lets the :fetch lifecycle single out a 401 for token refresh
+    err.body = body ?? null;
     throw err;
   }
-  try { return JSON.parse(text); } catch { return { status: response.status, body: text }; }
+  return body === undefined ? { status: response.status, body: text } : body;
+}
+
+/**
+ * Write the `<name>_error` / `<name>_error_body` pair for a key: the server's
+ * own message and its parsed JSON body, or null/null when there is no failure.
+ * @param {string} key
+ * @param {any} [error]
+ * @returns {void}
+ */
+function setError(key, error) {
+  state[key + "_error"] = error ? error.message || String(error) : null;
+  state[key + "_error_body"] = (error && error.body) ?? null;
 }
 
-const computedDefs = [...document.querySelectorAll("[data-wd-computed]")].map((node) => ({
-  key: node.getAttribute("data-wd-computed-key") || "",
-  expr: node.getAttribute("data-wd-computed-expr") || "",
-  ast: JSON.parse(node.getAttribute("data-wd-computed-expr") || "null")
-}));
+/**
+ * Bump a node's generation token and hand back a staleness probe. An in-flight
+ * request that a newer one superseded must never write its result. Shared by the
+ * `:fetch` lifecycle and the round-trip `:form` submit.
+ * @param {{ __wdGen?: number }} node
+ * @returns {() => boolean}
+ */
+function genGuard(node) {
+  const gen = (node.__wdGen = (node.__wdGen || 0) + 1);
+  return () => gen !== node.__wdGen;
+}
+
+/**
+ * Set whenever a render pass changes STRUCTURE — an `:if` branch injected, a loop
+ * row cloned, an `@empty` branch filled. It buys one more pass (the document-wide
+ * queries must reach the new nodes) and one more `scan()` (the new nodes may be
+ * directives no query had ever seen). True at boot: nothing is registered yet.
+ */
+let dirty = true;
 
 /**
  * Log an expression failure when `window.wd.debug` is enabled.
@@ -228,16 +433,22 @@ function warn(expr, error) {
 }
 
 /**
- * Re-evaluate all `:computed` definitions into `state`.
+ * Re-evaluate every `:computed` marker in the live tree into `state`. Read from
+ * the DOM rather than a registry captured at load: `querySelectorAll` cannot see
+ * into `<template>` content, so a registry would permanently miss a `:computed`
+ * that only becomes live when an `:if` branch opens. `parseAst` caches by the raw
+ * attribute text, so re-reading costs an attribute read, not a re-parse.
  * @returns {void}
  */
 function recompute() {
-  for (const def of computedDefs) {
+  for (const node of document.querySelectorAll("[data-wd-computed]")) {
+    const key = node.getAttribute("data-wd-computed-key") || "";
+    const expr = node.getAttribute("data-wd-computed-expr") || "null";
     try {
-      state[def.key] = evalAst(def.ast, undefined);
+      state[key] = evalAst(parseAst(expr), undefined);
     } catch (error) {
-      state[def.key] = undefined;
-      warn(def.expr, error);
+      state[key] = undefined;
+      warn(expr, error);
     }
   }
 }
@@ -338,10 +549,13 @@ function classToggle(el, raw, item) {
  * @returns {string}
  */
 function loopKeyOf(item, counts) {
-  const base =
+  // Every literal `#` doubles, so the `#n` duplicate suffix lives in a namespace
+  // no real key can reach: a genuine "a#1" keys as "a##1", never as a's duplicate.
+  const base = (
     item && typeof item === "object"
       ? String(item.id ?? item.key ?? JSON.stringify(item))
-      : String(item);
+      : String(item)
+  ).replace(/#/g, "##");
   const seen = counts.get(base) || 0;
   counts.set(base, seen + 1);
   return seen ? `${base}#${seen}` : base;
@@ -359,8 +573,8 @@ function fillItem(node, item, meta = {}) {
   // Nested item-relative loops (data-wd-loop-item) own their descendants' binds;
   // when present, `skip` excludes a node living inside one so the outer row's
   // text/meta/each-if/class passes never overwrite an inner row's values.
-  const inners = node.querySelectorAll("[data-wd-loop-item]");
-  const skip = inners.length ? (/** @type {Element} */ el) => el.closest("[data-wd-loop-item]") : () => false;
+  let inners = node.querySelectorAll("[data-wd-loop-item]");
+  const skip = (/** @type {Element} */ el) => inners.length && el.closest("[data-wd-loop-item]");
   // 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]")) {
@@ -370,14 +584,17 @@ function fillItem(node, item, meta = {}) {
     const value = expr ? evalPredicate(parseAst(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]"));
-    output.innerHTML = template?.innerHTML || "";
+    // swapBranch carries the same skip-when-unchanged guard the global :if has:
+    // re-injecting an unchanged branch on every render would destroy whatever is
+    // live inside it — a nested loop's reconciled rows, focus, a playing <video>.
+    swapBranch(region, output, value, "wd-if");
     fillItem(output, item, meta);
   }
-  const targets = node.matches("[data-wd-each]")
-    ? [node, ...node.querySelectorAll("[data-wd-each]")]
-    : [...node.querySelectorAll("[data-wd-each]")];
-  for (const target of targets) {
+  // An each-if branch can REVEAL a nested loop, and the capture above predates
+  // the injection — re-read it, or the passes below overwrite the inner rows
+  // with the OUTER row's values.
+  inners = node.querySelectorAll("[data-wd-loop-item]");
+  for (const target of selfAnd(node, "[data-wd-each]")) {
     if (skip(target)) continue;
     target.textContent = applyFmt(target, getPath(item, target.getAttribute("data-wd-path"))) ?? "";
   }
@@ -385,8 +602,10 @@ function fillItem(node, item, meta = {}) {
     if (skip(marker)) continue;
     marker.textContent = applyFmt(marker, 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) { if (!skip(el)) classToggle(el, el.getAttribute("data-wd-each-class"), item); }
+  for (const el of selfAnd(node, "[data-wd-each-class]")) { if (!skip(el)) classToggle(el, el.getAttribute("data-wd-each-class"), item); }
+  // Per-row bound attributes (a link/image destination reading the row). State
+  // parts resolve here too, so a destination mixing the two stays correct.
+  for (const el of selfAnd(node, "[data-wd-each-attr]")) { if (!skip(el)) applyAttr(el, el.getAttribute("data-wd-each-attr"), item, meta); }
   // Reconcile nested loops last, against the now-settled outer row.
   for (const region of inners) reconcile(region, getPath(item, region.getAttribute("data-wd-loop-item")));
 }
@@ -427,7 +646,7 @@ function pipeline(list, region) {
         const av = getPath(a.value, sort || null);
         const bv = getPath(b.value, sort || null);
         const c = typeof av === "number" && typeof bv === "number" ? av - bv : String(av).localeCompare(String(bv));
-        return (c || a.index - b.index) * dir;
+        return c ? c * dir : a.index - b.index;
       }).map((w) => w.value);
     }
   }
@@ -439,6 +658,30 @@ function pipeline(list, region) {
   return list;
 }
 
+/**
+ * Swap a conditional region to the branch its truthiness selects, and report
+ * whether anything actually moved. The unchanged-guard is the load-bearing part:
+ * re-injecting the branch that is already showing would replace every live node
+ * inside it on every render. One implementation for both conditionals — the
+ * global `:if` (`prefix` "wd", templates `data-wd-true`/`-false`) and the per-row
+ * `:if` inside a loop row ("wd-if", `data-wd-if-true`/`-false`).
+ * @param {Element} region Carries data-wd-if-active, the last painted branch.
+ * @param {Element} output The node whose contents the branch replaces.
+ * @param {any} value
+ * @param {string} prefix
+ * @returns {boolean} true when the branch was swapped
+ */
+function swapBranch(region, output, value, prefix) {
+  const active = String(Boolean(value));
+  if (region.getAttribute("data-wd-if-active") === active) return false;
+  region.setAttribute("data-wd-if-active", active);
+  const template = /** @type {HTMLTemplateElement | null} */ (region.querySelector(`template[data-${prefix}-${active}]`));
+  unregister(output); // the branch being replaced takes its directives with it
+  output.innerHTML = template?.innerHTML || "";
+  // The branch may carry directives no query has ever seen.
+  return (dirty = true);
+}
+
 /**
  * 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
@@ -454,13 +697,8 @@ function pipeline(list, region) {
 function renderIf(node) {
   const expr = node.getAttribute("data-wd-if-expr");
   const value = expr ? evalPredicate(parseAst(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 || "";
+  if (!output || !swapBranch(node, output, value, "wd")) return;
   for (const nested of output.querySelectorAll("[data-wd-if]")) renderIf(nested);
 }
 
@@ -489,13 +727,18 @@ function reconcile(region, rows) {
   const emptyTpl = /** @type {HTMLTemplateElement | null} */ (region.querySelector("template[data-wd-loop-empty]"));
   if (!list.length && emptyTpl) {
     if (out.getAttribute("data-wd-empty") !== "1") {
+      unregister(out); // the rows being wiped take their directives with them
       out.textContent = "";
       for (const child of [...emptyTpl.content.children]) out.appendChild(child.cloneNode(true));
       out.setAttribute("data-wd-empty", "1");
+      dirty = true;
     }
     return;
   }
-  if (out.getAttribute("data-wd-empty") === "1") { out.textContent = ""; out.removeAttribute("data-wd-empty"); }
+  // The @empty branch is ONE branch, not a per-row clone, so it may legally hold
+  // an :every/:effect. Emptying and refilling the list re-clones it, so the copy
+  // leaving here must be dropped or the next empty state would tick twice.
+  if (out.getAttribute("data-wd-empty") === "1") { unregister(out); out.textContent = ""; out.removeAttribute("data-wd-empty"); }
 
   /** @type {Map<string, WdRow>} */
   const existing = new Map();
@@ -507,6 +750,7 @@ function reconcile(region, rows) {
   /** @type {Set<string>} */
   const used = new Set();
   const count = list.length;
+  let moved = false;
   for (let i = 0; i < count; i++) {
     const item = list[i];
     const key = loopKeyOf(item, counts);
@@ -515,59 +759,100 @@ function reconcile(region, rows) {
       node = /** @type {WdRow} */ (template.content.firstElementChild?.cloneNode(true));
       if (!node) continue;
       node.setAttribute("data-wd-loop-key", key);
+      // A fresh row missed this pass's document-wide if/class/scan work.
+      dirty = true;
     }
     used.add(key);
     fillItem(node, item, { index: i, number: i + 1, first: i === 0, last: i === count - 1, count });
     node.__wdItem = item; /** let per-row actions resolve which row was clicked */
-    out.appendChild(node);
+    // Leave a row that is already in place ALONE. appendChild is a
+    // remove-then-insert per spec, so appending unconditionally blurs the
+    // focused field, resets scroll, restarts CSS transitions and reloads an
+    // <iframe> in a row — on every render, even when the list did not change.
+    // Once one row has had to move, every later row must be re-appended too, or
+    // the ones left behind would sit in front of it.
+    if (moved || out.children[i] !== node) { moved = true; out.appendChild(node); }
   }
   for (const [key, node] of existing) {
-    if (!used.has(key)) node.remove();
+    if (!used.has(key)) { unregister(node); node.remove(); }
   }
 }
 
 /**
  * Synchronously render the whole document from current `state`:
- * computed → if-regions → keyed loop reconcile → text/input binds.
+ * (scan → computed → if-regions → reactive classes → keyed loop reconcile)
+ * repeated until the structure settles → text/input binds → theme → effects.
+ *
+ * The repeat is the point. The if/class passes are document-wide queries, so a
+ * row the loop reconcile CLONED during the same pass was not in the tree when
+ * they ran and would keep the compile-time branch and classes baked into its
+ * template — wrong until some unrelated state change. Symmetrically, a branch an
+ * `:if` just injected can carry `:fetch`/`:computed`/`:effect`/`:every`/`:theme`
+ * nodes that no query had ever seen. Either marks `dirty`, which buys one more
+ * pass; two passes always suffice in practice and three is the hard cap.
  * @returns {void}
  */
+let settleTries = 0;
 function renderNow() {
-  recompute();
-  for (const node of document.querySelectorAll("[data-wd-if]")) renderIf(node);
+  for (let pass = 0; pass < 3; pass++) {
+    if (dirty) scan();
+    dirty = false;
+    recompute();
+    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.
-  for (const el of document.querySelectorAll("[data-wd-class]")) classToggle(el, el.getAttribute("data-wd-class"), undefined);
+    // 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);
 
-  // Nested item-relative loops use data-wd-loop-item, so this top-level query
-  // skips them; fillItem reconciles those against their enclosing row.
-  for (const region of document.querySelectorAll("[data-wd-loop]")) {
-    const key = region.getAttribute("data-wd-loop");
-    const data = region.getAttribute("data-wd-loop-data");
-    /** Source may be a dotted path (e.g. team.members) read off state via getPath. */
-    const dot = key ? key.indexOf(".") : -1;
-    reconcile(region, key ? (dot < 0 ? state[key] : getPath(state[key.slice(0, dot)], key.slice(dot + 1))) : (data ? JSON.parse(data) : []));
+    // Nested item-relative loops use data-wd-loop-item, so this top-level query
+    // skips them; fillItem reconciles those against their enclosing row.
+    for (const region of document.querySelectorAll("[data-wd-loop]")) {
+      const key = region.getAttribute("data-wd-loop");
+      const data = region.getAttribute("data-wd-loop-data");
+      /** Source may be a dotted path (e.g. team.members) read off state via getPath. */
+      const dot = key ? key.indexOf(".") : -1;
+      reconcile(region, key ? (dot < 0 ? state[key] : getPath(state[key.slice(0, dot)], key.slice(dot + 1))) : (data ? JSON.parse(data) : []));
+    }
+    if (!dirty) break;
   }
+  // Deeper than the cap (an `:if` whose branch declares the `:computed` a nested
+  // `:if` reads, a few levels down) the loop used to exit still dirty and leave
+  // the innermost region showing its compile-time branch until some unrelated
+  // state change. Finish this paint, then schedule another pass; the counter
+  // bounds a genuine cycle instead of spinning forever.
+  if (dirty && ++settleTries < 10) {
+    if (/** @type {any} */ (window).wd?.debug) console.warn("[wd] render did not settle; scheduling another pass");
+    render();
+  } else settleTries = 0;
 
   for (const node of document.querySelectorAll("[data-wd-bind]")) {
     node.textContent = applyFmt(node, getPath(state[node.getAttribute("data-wd-bind") || ""], node.getAttribute("data-wd-path"))) ?? "";
   }
 
-  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") || ""] ?? "";
+  for (const node of document.querySelectorAll("[data-wd-attr]")) applyAttr(node, node.getAttribute("data-wd-attr"), undefined, {});
+
+  // Bound controls, reflected back from state. A checkbox carries a boolean and
+  // a radio carries whichever option equals the value, so neither can go through
+  // `.value`; a text field keeps the focus guard, because overwriting what
+  // someone is typing mid-keystroke moves their caret.
+  for (const input of /** @type {NodeListOf<HTMLInputElement>} */ (document.querySelectorAll("[data-wd-bind-input]"))) {
+    const value = state[input.getAttribute("data-wd-bind-input") || ""] ?? "";
+    if (input.type === "checkbox") input.checked = Boolean(value);
+    else if (input.type === "radio") input.checked = input.value === String(value);
+    else if (document.activeElement !== input) input.value = value;
   }
 
-  if (themeNodes.length) reflectThemes();
-  runEffects(); // side effects run last, against fully settled state
+  reflectThemes();
+  // side effects run last, against fully settled state
+  runEffects();
   if (subscribers.size) notifySubscribers();
 }
 
 /** :theme — reflect a store value onto <html data-theme> so a manual light/dark
  * switch layers over the OS preference: `auto`/empty clears the attribute (follow
  * the system via the skin's `tokens dark` media query), anything else forces it. */
-const themeNodes = [...document.querySelectorAll("[data-wd-theme]")];
 function reflectThemes() {
-  for (const node of themeNodes) {
+  for (const node of document.querySelectorAll("[data-wd-theme]")) {
     const value = state[node.getAttribute("data-wd-theme") || ""];
     const root = document.documentElement;
     if (value == null || value === "" || value === "auto") root.removeAttribute("data-theme");
@@ -575,12 +860,9 @@ function reflectThemes() {
   }
 }
 
-/** @typedef {{ watch: string, actions: { op: string, target?: string, value?: any }[], last: string }} Effect */
+/** @typedef {{ node: Element, 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) };
-});
+const effects = [];
 let effectDepth = 0;
 /**
  * After a render, fire any `:effect` whose watched state changed, running its
@@ -595,10 +877,14 @@ function runEffects() {
     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);
+    runActions(fx.actions);
     changed = true;
   }
   if (!changed) { effectDepth = 0; return; }
+  // An effect writes state exactly like a click does, so it persists and syncs
+  // to the URL exactly like a click does. Without this an `:effect` that writes
+  // a `from-url` key never reached the address bar at all.
+  savePersisted();
   if (++effectDepth >= 10) { effectDepth = 0; console.warn("effect did not settle"); return; }
   renderNow(); // reflect the effect's state changes, then re-check
 }
@@ -622,8 +908,9 @@ document.addEventListener("input", (event) => {
   const input = /** @type {HTMLInputElement | null} */ (/** @type {Element} */ (event.target)?.closest("[data-wd-bind-input]"));
   if (!input) return;
   // A `:slider` binds a range input: keep state numeric so `:computed`/math see a
-  // number, not the DOM's string `.value`. Other inputs stay strings as before.
-  state[input.getAttribute("data-wd-bind-input") || ""] = input.type === "range" ? input.valueAsNumber : input.value;
+  // number, not the DOM's string `.value`. A standalone `:checkbox` binds the
+  // boolean, not the label. Everything else stays a string, as before.
+  state[input.getAttribute("data-wd-bind-input") || ""] = input.type === "range" ? input.valueAsNumber : input.type === "checkbox" ? input.checked : input.value;
   savePersisted();
   render();
   checkRefetch();
@@ -687,6 +974,19 @@ function applyAction(action, op, target, value) {
   }
 }
 
+/**
+ * Run a parsed action sequence with no clicked row — the `:effect` and `:every`
+ * paths. Their defs are parsed ONCE and re-fired, so an `append`/`prepend` would
+ * push the SAME object reference every time and a later `remove` (which filters
+ * by identity) would delete every copy at once. Clone per fire; the click path
+ * re-parses its JSON attribute each time and needs no copy.
+ * @param {{ op: string, target?: string, value?: any }[]} actions
+ * @returns {void}
+ */
+const runActions = (actions) => {
+  for (const a of actions) applyAction(null, a.op, a.target || "", structuredClone(a.value));
+};
+
 document.addEventListener("click", (event) => {
   const action = /** @type {Element} */ (event.target)?.closest("[data-wd-action],[data-wd-actions]");
   if (!action) return;
@@ -723,19 +1023,41 @@ document.addEventListener("submit", (event) => {
     return;
   }
 
+  // A slow earlier submit must not land on top of a newer one's reply, and the
+  // previous attempt's error must not sit on screen through the retry.
+  const dead = genGuard(/** @type {any} */ (form));
+  setError(key);
+  render();
+  // ONE FormData feeds both bodies. Bound controls (`:bind`, a bound `:select`)
+  // carry no `name`, so FormData never saw them: they are appended by their
+  // state key here, before the split, so the urlencoded path carries exactly
+  // the same keys the multipart path does. A bound key that a real field
+  // already occupies is left alone — sending both would hand the server the
+  // same name twice with different values.
+  const fd = new FormData(form);
+  for (const el of form.querySelectorAll("[data-wd-bind-input]")) {
+    const bound = el.getAttribute("data-wd-bind-input");
+    if (bound && !el.getAttribute("name") && !fd.has(bound)) fd.append(bound, state[bound] ?? "");
+  }
+  // A file cannot be urlencoded, so a form carrying one posts the FormData
+  // itself and lets the browser set the multipart content-type WITH its
+  // boundary, which is exactly why no content-type is passed here.
+  const upload = form.querySelector("input[type=file]");
   httpJson(action, {
     method: form.getAttribute("method") || "post",
-    headers: { "content-type": "application/x-www-form-urlencoded" },
-    body: new URLSearchParams(/** @type {any} */ (new FormData(form))).toString()
+    headers: upload ? undefined : { "content-type": "application/x-www-form-urlencoded" },
+    body: upload ? fd : new URLSearchParams(/** @type {any} */ (fd)).toString()
   })
     .then((value) => {
+      if (dead()) return;
       state[key] = value;
-      state[`${key}_error`] = null;
+      setError(key);
       savePersisted();
       render();
     })
     .catch((error) => {
-      state[`${key}_error`] = String(error);
+      if (dead()) return;
+      setError(key, error);
       render();
     });
 });
@@ -749,9 +1071,7 @@ document.addEventListener("submit", (event) => {
  */
 function startFetch(node) {
   // Per-node generation token: a refetch bumps it; superseded writes bail.
-  const gen = node.__wdGen = (node.__wdGen || 0) + 1;
-  /** @returns {boolean} stale once a newer fetch superseded this one */
-  const dead = () => gen !== node.__wdGen;
+  const dead = genGuard(node);
   /** @param {string} n @returns {string} */
   const g = (n) => node.getAttribute("data-wd-fetch-" + n) || "";
   const key = g("key");
@@ -772,11 +1092,11 @@ function startFetch(node) {
   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;
+  setError(key);
   set("_loading", true);
 
   /** @param {any} error */
-  const fail = (error) => { state[key + "_error"] = String(error); set("_loading", false); };
+  const fail = (error) => { setError(key, error); set("_loading", false); };
 
   const attempt = () => {
     /** @type {RequestInit} */
@@ -791,7 +1111,7 @@ function startFetch(node) {
       if (dead()) return;
       state[key] = value;
       state[key + "_empty"] = isEmpty(value);
-      state[key + "_error"] = null;
+      setError(key);
       set("_loading", false);
     }).catch((error) => {
       clearTimeout(timer);
@@ -847,70 +1167,127 @@ function refreshToken(refreshUrl, headersKey) {
  * a generation token so a superseded in-flight response/retry bails on write. */
 /** @typedef {Element & { __wdSnap?: string, __wdGen?: number }} FetchNode */
 /** @type {FetchNode[]} */
-const fetchNodes = [...document.querySelectorAll("[data-wd-fetch]")];
+const fetchNodes = [];
 /** @param {FetchNode} node @returns {string} */
 const depSnapshot = (node) => (node.getAttribute("data-wd-fetch-deps") || "").split(",").filter(Boolean).map((d) => JSON.stringify(getPath(state, d))).join("|");
 
 /** @type {any} */
 let refetchTimer = 0;
+/** @type {Set<FetchNode>} Nodes owed a refetch, accumulated across the window. */
+const due = new Set();
 /**
  * After a mutation render, debounce-refetch any fetch node whose URL deps
- * changed. Snapshots live on the node, so no extra bookkeeping structure.
+ * changed. Snapshots live on the node, so no extra bookkeeping structure. The
+ * due set OUTLIVES each debounce restart: a second mutation resets the timer,
+ * and a node dropped there could never be re-detected — its snapshot has already
+ * been advanced — so its refetch would be lost rather than merely delayed.
  * @returns {void}
  */
 function checkRefetch() {
-  /** @type {FetchNode[]} */
-  const due = [];
   for (const node of fetchNodes) {
     const snap = depSnapshot(node);
-    if (snap && snap !== node.__wdSnap) { node.__wdSnap = snap; due.push(node); }
+    if (snap && snap !== node.__wdSnap) { node.__wdSnap = snap; due.add(node); }
   }
-  if (!due.length) return;
+  if (!due.size) return;
   clearTimeout(refetchTimer);
-  refetchTimer = setTimeout(() => { for (const node of due) startFetch(node); }, 150);
+  refetchTimer = setTimeout(() => { for (const node of due) startFetch(node); due.clear(); }, 150);
 }
 
-for (const node of fetchNodes) {
-  node.__wdSnap = depSnapshot(node);
-  if (node.getAttribute("data-wd-fetch-when") === "visible" && "IntersectionObserver" in window) {
-    const observer = new IntersectionObserver((entries) => {
-      if (!entries.some((entry) => entry.isIntersecting)) return;
-      observer.disconnect();
-      startFetch(node);
-    });
-    observer.observe(node);
-  } else {
-    startFetch(node);
+/**
+ * Drop every registration belonging to a subtree that is about to leave the
+ * document — a closed `:if` branch, a removed loop row.
+ *
+ * `scan()` claims a node once, and the claim marker lives ON the node while the
+ * registries (`effects`, `fetchNodes`, `everyDefs`) are module-level. A branch
+ * is re-cloned from its template every time it opens, so without this the NEXT
+ * open registers a FRESH node while the detached one stays: an `:every` ticked
+ * twice after one reopen, three times after two, and kept ticking with the
+ * branch closed. Same shape for `:effect` (fired once per stale copy) and
+ * `:fetch` (one request per stale copy, on a state change the reader cannot
+ * even see).
+ * @param {Element} root
+ * @returns {void}
+ */
+function unregister(root) {
+  for (const node of selfAnd(root, "[data-wd-fetch],[data-wd-effect],[data-wd-every]")) {
+    due.delete(/** @type {any} */ (node));
+    // A fetch entry IS the node; an effect/every entry carries it on `.node`.
+    for (const list of [/** @type {any[]} */ (fetchNodes), effects, everyDefs]) {
+      for (let i = list.length - 1; i >= 0; i--) {
+        if ((list[i].node || list[i]) !== node) continue;
+        if (list[i].t) clearInterval(list[i].t);
+        list.splice(i, 1);
+      }
+    }
+  }
+}
+
+/**
+ * Claim and wire up the directives that need ONE-TIME setup: `:fetch` (kick off
+ * the request, snapshot its deps), `:effect` (parse the def, snapshot its watch)
+ * and `:every` (start a timer). `querySelectorAll` cannot see into `<template>`
+ * content, so building these at load permanently missed any that lived in an
+ * unopened `:if` branch or a loop row template — they simply never ran. Called
+ * again whenever a render changes structure; each node is claimed once
+ * (`__wdReg`), so a re-scan costs the query and nothing else. (`:computed` and
+ * `:theme` need no claim at all: both read the live tree on every render.)
+ * @returns {void}
+ */
+function scan() {
+  // Seed scripts first: a branch that just opened may DECLARE the state the
+  // directives below read (see hydrate).
+  hydrate();
+  for (const node of /** @type {any} */ (document.querySelectorAll("[data-wd-fetch],[data-wd-effect],[data-wd-every]"))) {
+    if (node.__wdReg) continue;
+    node.__wdReg = 1;
+    if (node.hasAttribute("data-wd-effect")) {
+      const def = JSON.parse(node.textContent || "{}");
+      effects.push({ node, watch: def.watch, actions: def.actions || [], last: JSON.stringify(getPath(state, def.watch) ?? null) });
+    }
+    if (node.hasAttribute("data-wd-every")) {
+      if (!everyDefs.length) document.addEventListener("visibilitychange", () => (document.hidden ? stopEvery() : startEvery()));
+      everyDefs.push({ ...JSON.parse(node.textContent || "{}"), node });
+      startEvery();
+    }
+    if (node.hasAttribute("data-wd-fetch")) {
+      fetchNodes.push(node);
+      node.__wdSnap = depSnapshot(node);
+      if (node.getAttribute("data-wd-fetch-when") === "visible" && "IntersectionObserver" in window) {
+        const observer = new IntersectionObserver((entries) => {
+          if (!entries.some((entry) => entry.isIntersecting)) return;
+          observer.disconnect();
+          startFetch(node);
+        });
+        observer.observe(node);
+      } else {
+        startFetch(node);
+      }
+    }
   }
 }
 
 // :every — run actions on a timer, paused while the tab is hidden so background
 // tabs don't poll or animate. Each tick runs the action sequence (no clicked row,
 // like :effect), then saves + renders + checks refetch deps, exactly like a click.
-/** @typedef {{ ms: number, actions: { op: string, target?: string, value?: any }[] }} EveryDef */
+/** @typedef {{ node: Element, ms: number, actions: { op: string, target?: string, value?: any }[], t?: any }} EveryDef */
 /** @type {EveryDef[]} */
-const everyDefs = [...document.querySelectorAll("script[data-wd-every]")].map((node) => JSON.parse(node.textContent || "{}"));
-/** @type {any[]} */
-let everyTimers = [];
+const everyDefs = [];
+// The timer lives on the def, not in a shared list, so a def registered later
+// (one revealed by an :if flip) starts ticking without restarting the others.
 function startEvery() {
-  if (everyTimers.length || document.hidden) return;
+  if (document.hidden) return;
   for (const def of everyDefs) {
-    if (!def.ms || !def.actions) continue;
-    everyTimers.push(setInterval(() => {
-      for (const a of def.actions) applyAction(null, a.op, a.target || "", a.value);
+    if (def.t || !def.ms || !def.actions) continue;
+    def.t = setInterval(() => {
+      runActions(def.actions);
       savePersisted();
       render();
       checkRefetch();
-    }, def.ms));
+    }, def.ms);
   }
 }
 function stopEvery() {
-  for (const timer of everyTimers) clearInterval(timer);
-  everyTimers = [];
-}
-if (everyDefs.length) {
-  document.addEventListener("visibilitychange", () => (document.hidden ? stopEvery() : startEvery()));
-  startEvery();
+  for (const def of everyDefs) { clearInterval(def.t); def.t = 0; }
 }
 
 // Escape-hatch subscriptions: colocated `.js` "behaviors" (carousels, drag-and-
@@ -944,6 +1321,8 @@ function notifySubscribers() {
     state[key] = value;
     savePersisted();
     render();
+    // The input and click handlers both do; behaviors write only through here.
+    checkRefetch();
   },
   /**
    * Run `cb(value)` now and on every future change to `state[key]`. Returns an