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

package/src/catalog.js

@@ -20,6 +20,7 @@
 // ---------------------------------------------------------------------------
 
 import fs from "node:fs";
+import { gzipSync } from "node:zlib";
 import { BUTTON_EXAMPLE, EFFECT_EXAMPLE, EVERY_EXAMPLE } from "./compiler/actions.js";
 import { LOOP_META } from "./compiler/context.js";
 import { FETCH_EXAMPLE } from "./compiler/fetch.js";
@@ -115,8 +116,10 @@ const DIRECTIVES = [
   {
     name: ":::",
     kind: "block",
-    syntax: "::: [tag] [.class …] [#id] [.class when <pred>] … :::",
-    description: "Group content in a section/div/nav/main with classes, ids, and reactive classes.",
+    syntax:
+      '::: [tag] [.class …] [#id] [.class when <pred>] [role="…"] [aria-…="…"] [title="…"] … :::',
+    description:
+      "Group content in a section/div/nav/main with classes, ids, reactive classes, and role/aria-*/title.",
     example: CONTAINER_EXAMPLE,
     reactive: "either"
   },
@@ -131,9 +134,9 @@ const DIRECTIVES = [
   {
     name: ":state",
     kind: "line",
-    syntax: ":state name = value [persist|ephemeral]",
+    syntax: ":state name = value [persist|ephemeral] [from-url]",
     description:
-      "Declare page-scoped reactive state. Ephemeral by default; persist keeps it across reloads.",
+      "Declare page-scoped reactive state. Ephemeral by default; persist keeps it across reloads, from-url mirrors it into the query string.",
     example: STATE_EXAMPLE,
     reactive: "reactive"
   },
@@ -158,7 +161,8 @@ const DIRECTIVES = [
     kind: "line",
     syntax:
       ':fetch name from "url" [method=…] [when=visible] [timeout=ms] [retry=N] [headers=key] [body=key]',
-    description: "Load remote JSON with auto loading/error/empty lifecycle state.",
+    description:
+      "Load remote JSON, auto-declaring name/_loading/_error/_error_body/_empty lifecycle state.",
     example: FETCH_EXAMPLE,
     reactive: "reactive"
   },
@@ -166,7 +170,8 @@ const DIRECTIVES = [
     name: ":effect",
     kind: "line",
     syntax: ":effect watched -> action[; action…]",
-    description: "Run button-vocabulary actions whenever the watched state changes.",
+    description:
+      "Run button-vocabulary actions whenever the watched state changes. Page level only, never inside a reactive @loop body.",
     example: EFFECT_EXAMPLE,
     reactive: "reactive"
   },
@@ -174,7 +179,8 @@ const DIRECTIVES = [
     name: ":every",
     kind: "line",
     syntax: ":every <duration> -> action[; action…]",
-    description: "Run actions on a timer (5s/500ms/2m); auto-pauses while the tab is hidden.",
+    description:
+      "Run actions on a timer (5s/500ms/2m); auto-pauses while the tab is hidden. Page level only, never inside a reactive @loop body.",
     example: EVERY_EXAMPLE,
     reactive: "reactive"
   },
@@ -189,8 +195,9 @@ const DIRECTIVES = [
   {
     name: ":button",
     kind: "line",
-    syntax: ':button "Label" -> action[; action…]',
-    description: "A button that runs one or more state actions on click.",
+    syntax: ':button "Label" [role="…"] [aria-…="…"] [title="…"] -> action[; action…]',
+    description:
+      "A button that runs one or more state actions on click; takes role/aria-*/title before the arrow.",
     example: BUTTON_EXAMPLE,
     reactive: "reactive"
   },
@@ -198,7 +205,8 @@ const DIRECTIVES = [
     name: ":form",
     kind: "block",
     syntax: ':form [into name] [action="/url"] [method="post"] … :endform',
-    description: "A form: client state (into), native post (action), or fetch round-trip (both).",
+    description:
+      "A form: client state (into), native post (action), or fetch round-trip (both). Multipart when it holds a file field.",
     example: FORM_EXAMPLE,
     reactive: "either"
   },
@@ -206,7 +214,7 @@ const DIRECTIVES = [
     name: ":input",
     kind: "line",
     syntax: ':input name [type=…] [placeholder="…"] [required]',
-    description: "A single-line form input (auto aria-label).",
+    description: "A single-line form input (auto aria-label). type=file makes its form multipart.",
     example: INPUT_EXAMPLE,
     reactive: "static"
   },
@@ -222,25 +230,28 @@ const DIRECTIVES = [
     name: ":select",
     kind: "block",
     syntax: ':select name [required]  then "- Label" lines',
-    description: "A dropdown; one <option> per following - Label line.",
+    description:
+      "A dropdown; one <option> per following - Label line. Inside a :form it is a form field; outside one it binds a :state of that name.",
     example: SELECT_EXAMPLE,
-    reactive: "static"
+    reactive: "either"
   },
   {
     name: ":checkbox",
     kind: "block",
     syntax: ':checkbox name [required]  then "- Label" lines',
-    description: "A checkbox group that captures every checked value.",
+    description:
+      "In a :form, a checkbox group capturing every checked value; outside one, a single box bound to a boolean :state.",
     example: CHECKBOX_EXAMPLE,
-    reactive: "static"
+    reactive: "either"
   },
   {
     name: ":radio",
     kind: "block",
     syntax: ':radio name [required]  then "- Label" lines',
-    description: "A radio group that captures a single value.",
+    description:
+      "A radio group capturing a single value. Inside a :form it is a form field; outside one it binds a :state of that name.",
     example: RADIO_EXAMPLE,
-    reactive: "static"
+    reactive: "either"
   },
   {
     name: ":submit",
@@ -347,12 +358,32 @@ const LOOP_VAR_DESC = {
   $count: "Total row count."
 };
 
-/** The button-action vocabulary. `token` is the distinguishing keyword the drift
- * test checks against actions.js's ACTION_USE string. */
+/**
+ * The button-action vocabulary — the ONE list every downstream surface reads.
+ *
+ * `token` is the distinguishing keyword (`refetch` drifted out of this list for
+ * three releases: implemented in the compiler, documented in the README seven
+ * times, and missing from `llms.txt`, `llms-full.txt` and the `WD311` hint,
+ * because the guard compared this array against a hardcoded literal copy of
+ * itself. `tests/catalog-actions.test.js` now derives the compiler's real
+ * vocabulary by compiling probes, so that cannot recur.)
+ *
+ * `place` and `operand` describe the token's SHAPE, which is what
+ * `src/grammar.js` needs to emit the GBNF `action-op` rule:
+ *   place    "suffix" → `name++`   | "infix" → `name toggle`
+ *   operand  "none"   → nothing follows the token
+ *            "required" → exactly one value follows
+ *            "optional" → a value may follow (`flag toggle` / `list toggle v`)
+ * @type {{ name: string, token: string, place: "suffix" | "infix",
+ *   operand: "none" | "required" | "optional", syntax: string,
+ *   description: string, example: string }[]}
+ */
 const ACTION_OPS = [
   {
     name: "increment",
     token: "++",
+    place: "suffix",
+    operand: "none",
     syntax: "name++",
     description: "Increment a number.",
     example: "count++"
@@ -360,6 +391,8 @@ const ACTION_OPS = [
   {
     name: "decrement",
     token: "--",
+    place: "suffix",
+    operand: "none",
     syntax: "name--",
     description: "Decrement a number.",
     example: "count--"
@@ -367,6 +400,8 @@ const ACTION_OPS = [
   {
     name: "add",
     token: "+=",
+    place: "infix",
+    operand: "required",
     syntax: "n += k",
     description: "Add to a number.",
     example: "count += 5"
@@ -374,6 +409,8 @@ const ACTION_OPS = [
   {
     name: "subtract",
     token: "-=",
+    place: "infix",
+    operand: "required",
     syntax: "n -= k",
     description: "Subtract from a number.",
     example: "count -= 5"
@@ -381,6 +418,8 @@ const ACTION_OPS = [
   {
     name: "set",
     token: "=",
+    place: "infix",
+    operand: "required",
     syntax: "name = v",
     description: "Assign a value.",
     example: "open = true"
@@ -388,6 +427,8 @@ const ACTION_OPS = [
   {
     name: "toggle",
     token: "toggle",
+    place: "infix",
+    operand: "optional",
     syntax: "flag toggle",
     description: "Flip a boolean (or toggle a list member with `list toggle v`).",
     example: "open toggle"
@@ -395,6 +436,8 @@ const ACTION_OPS = [
   {
     name: "append",
     token: "append",
+    place: "infix",
+    operand: "required",
     syntax: "list append v",
     description: "Append a value to a list.",
     example: 'items append "x"'
@@ -402,6 +445,8 @@ const ACTION_OPS = [
   {
     name: "prepend",
     token: "prepend",
+    place: "infix",
+    operand: "required",
     syntax: "list prepend v",
     description: "Prepend a value to a list.",
     example: 'items prepend "x"'
@@ -409,6 +454,8 @@ const ACTION_OPS = [
   {
     name: "remove",
     token: "remove",
+    place: "infix",
+    operand: "required",
     syntax: "list remove v",
     description: "Remove a value from a list (or the current loop row).",
     example: 'items remove "x"'
@@ -416,6 +463,8 @@ const ACTION_OPS = [
   {
     name: "clear",
     token: "clear",
+    place: "infix",
+    operand: "none",
     syntax: "x clear",
     description: "Empty a list or reset a value to null.",
     example: "items clear"
@@ -423,6 +472,8 @@ const ACTION_OPS = [
   {
     name: "merge",
     token: "merge",
+    place: "infix",
+    operand: "required",
     syntax: "obj merge other",
     description: "Shallow-merge another object/state key.",
     example: "settings merge patch"
@@ -430,6 +481,8 @@ const ACTION_OPS = [
   {
     name: "delete",
     token: "delete",
+    place: "infix",
+    operand: "required",
     syntax: "obj delete key",
     description: "Delete a key from an object.",
     example: 'settings delete "beta"'
@@ -437,9 +490,20 @@ const ACTION_OPS = [
   {
     name: "reset",
     token: "reset",
+    place: "infix",
+    operand: "none",
     syntax: "name reset",
     description: "Reset a state key to its initial value.",
     example: "form reset"
+  },
+  {
+    name: "refetch",
+    token: "refetch",
+    place: "infix",
+    operand: "none",
+    syntax: "name refetch",
+    description: "Re-run the matching :fetch.",
+    example: "board refetch"
   }
 ];
 
@@ -509,6 +573,11 @@ const FRONTMATTER_KEYS = [
     description: "HOME PAGE ONLY: allow (default) or deny the AI crawlers named in robots.txt.",
     example: "ai_crawlers: deny"
   },
+  {
+    name: "rss_limit",
+    description: "HOME PAGE ONLY: how many newest posts rss.xml carries (default 20).",
+    example: "rss_limit: 50"
+  },
   {
     name: "date",
     description: "Marks the page a post: RSS item, sitemap lastmod, og:type=article.",
@@ -573,6 +642,102 @@ const OP_DESC = {
   "<": "Less than."
 };
 
+/**
+ * The shipped reactive runtime's human-readable gzip size, for the cheatsheet.
+ *
+ * MEASURED, not written down. `src/runtime.min.js` is the exact artifact
+ * `emitRuntime` copies to `/__wd/runtime.js`, and it ships inside the published
+ * tarball, so gzipping it answers the question the same way in this repo and in
+ * a consumer's `node_modules`. `.size-snapshot.json` records the same number for
+ * the size gate, but that file is a repo artifact and is NOT published, so
+ * reading it here would throw for every npm consumer whose `darkmown build`
+ * emits `dist/llms.txt`.
+ *
+ * Before 2.7 this was a hand-maintained literal kept honest by
+ * `tests/size-prose.test.js`. Deriving it removes the drift instead of policing
+ * it — and that test now cross-checks the measurement against the snapshot.
+ * The cheatsheet is the artifact an app pastes into a model's system prompt, so
+ * a wrong number here is the one that gets repeated back at users; it once said
+ * "~8 KB", which was the BUDGET, not the size.
+ */
+const RUNTIME_SIZE = `~${(gzipSync(fs.readFileSync(new URL("runtime.min.js", import.meta.url))).length / 1000).toFixed(1)} KB`;
+
+/**
+ * Block openers close explicitly; these are the closers and the mid-block
+ * markers. They are real vocabulary an author must write and were missing from
+ * the cheatsheet entirely, so a model could open a block it could not close.
+ * @returns {string[]}
+ */
+function blockStructureSection() {
+  return [
+    "## Block structure (every block closes explicitly)",
+    "- `@loop … @endloop`. `@empty` inside the loop body renders when the list is empty.",
+    "- `:if … :endif`, with optional `:else if <condition>` and `:else` branches before the close.",
+    "- `:form … :endform`, `:carousel … :endcarousel`, and `::: … :::` (a bare `:::` closes a container).",
+    ""
+  ];
+}
+
+/**
+ * The `{.class #id}` inline-attribute block. Real, undocumented in the
+ * cheatsheet, and with one sharp edge (inline code is not supported) that an
+ * author otherwise discovers by shipping a broken page.
+ * @returns {string[]}
+ */
+function inlineAttributesSection() {
+  return [
+    "## Inline attributes  `{.class #id}`",
+    "- Attach classes/an id to an inline element by following it with NO space:" +
+      " `[Get started](/start/){.btn}`, `![logo](/l.png){.brand}`, `*text*{.hl}`.",
+    "- Several at once: `[Go](/u/){.btn .lg #cta}`. A space before the block breaks it (stays literal).",
+    "- Works on links, images, and emphasis/strong. It does NOT work on inline `code`.",
+    ""
+  ];
+}
+
+/**
+ * Collections: any `site/pages/<name>/` folder is queryable by its bare name,
+ * with optional `_schema.wd` validation. The docs site covers this; the
+ * cheatsheet did not, so an AI author had no way to reach it.
+ * @returns {string[]}
+ */
+function collectionsSection() {
+  return [
+    "## Collections (a folder of pages, queried like data)",
+    "- Any `site/pages/<name>/` folder is a collection. Loop it by BARE NAME:" +
+      " `@loop posts into post sort by post.date desc`",
+    "- Each row is that entry's frontmatter plus derived `url`, `slug`, and `excerpt`.",
+    "- Optional `site/pages/<name>/_schema.wd` type-checks every entry at build time," +
+      " one `field: type` per line. Types: `string`, `number`, `boolean`, `date`, `string[]`;" +
+      " a trailing `?` makes a field optional. e.g. `title: string`, `featured: boolean?`",
+    ""
+  ];
+}
+
+/**
+ * The `.skin` language. AGENTS.md tells a model to always ship styling, and the
+ * cheatsheet carried not one line of the styling syntax.
+ * @returns {string[]}
+ */
+function skinSection() {
+  return [
+    "## Styling: the `.skin` language (zero runtime)",
+    "- A `.skin` beside a page or include (`index.wd` → `index.skin`) compiles to CSS and links itself.",
+    "- Indentation IS the structure: no braces, no semicolons, no colon between property and value.",
+    "- Selector, then indented `property value` lines: `.card` / `  bg white` / `  radius 8px`.",
+    "- `tokens` opens a design-token block (`accent #16645a`) emitting CSS variables;" +
+      " `tokens dark` supplies the dark-mode values for the same names. Read one with `$name`" +
+      " (`color $accent`).",
+    "- Shorthands: `bg`→background, `radius`→border-radius, `shadow`→box-shadow," +
+      " `font`→font-family, and `page` targets `<body>`.",
+    "- Nest by indenting (a nested selector is a descendant); `&:hover` / `&.active` attach to" +
+      " the parent; `@media (min-width: 40rem)` wraps its indented rules.",
+    "- A first line of `scoped` scopes every selector in that file to its own subtree at compile" +
+      " time. `tokens` stay global; `:global(.x)` opts one selector out.",
+    ""
+  ];
+}
+
 /** Read the installed version from package.json (always shipped beside src/). */
 function readVersion() {
   const pkg = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
@@ -622,6 +787,19 @@ export function directiveCatalog() {
 /** The action tokens the catalog exposes — used by the drift guard. */
 export const CATALOG_ACTION_TOKENS = ACTION_OPS.map((a) => a.token);
 
+/**
+ * The same vocabulary with each token's SHAPE, for `src/grammar.js`. The GBNF
+ * `action-op` rule used to be a hand-written string listing all fourteen
+ * alternatives; it is now generated from this, so the grammar and the catalog
+ * cannot list different ops.
+ * @type {{ token: string, place: "suffix" | "infix", operand: "none" | "required" | "optional" }[]}
+ */
+export const CATALOG_ACTION_GRAMMAR = ACTION_OPS.map((a) => ({
+  token: a.token,
+  place: a.place,
+  operand: a.operand
+}));
+
 /**
  * One page of a built site, as it appears in the generated `llms.txt` index and
  * `llms-full.txt` corpus.
@@ -662,7 +840,9 @@ export function llmsText(site) {
   out.push("");
   out.push("Darkmown compiles Markdown. A plain `.md` file stays plain; rename it to `.wd`");
   out.push("to unlock the directives below. Static pages ship ZERO JavaScript; only pages");
-  out.push("that use :state/:store/:fetch/:button (reactive) load the ~8 KB runtime. Copy an");
+  out.push(
+    `that use :state/:store/:fetch/:button (reactive) load the ${RUNTIME_SIZE} runtime. Copy an`
+  );
   out.push("example verbatim — every one compiles. Interpolate values with `{ path }`.");
   out.push("");
 
@@ -672,6 +852,8 @@ export function llmsText(site) {
   }
   out.push("");
 
+  out.push(...blockStructureSection());
+
   out.push("## @loop clauses (this fixed order, all optional)");
   for (const c of cat.loopClauses) {
     out.push(`- \`${c.syntax}\` — ${c.description} e.g. \`${c.example}\``);
@@ -706,17 +888,24 @@ export function llmsText(site) {
   );
   out.push("");
 
+  out.push(...inlineAttributesSection());
+
   out.push("## Page frontmatter");
   for (const key of cat.frontmatterKeys) {
     out.push(`- \`${key.name}\`: ${key.description} e.g. \`${key.example}\``);
   }
   out.push("");
 
+  out.push(...collectionsSection());
+  out.push(...skinSection());
+
   out.push("## Rules");
   out.push("- `.md` never gets directives — the `.wd` extension is the feature gate.");
   out.push("- One loop syntax (`@loop … into … @endloop`), one interpolation syntax (`{ name }`).");
   out.push("- Actions and predicates are a fixed whitelist — no JavaScript, no `x.filter(...)`.");
-  out.push("- Close every block: `@endloop`, `:endif`, `:endform`, `:endcarousel`, `:::`.");
+  out.push(
+    "- Close every block (see Block structure above) — an unclosed block is a compile error."
+  );
   out.push(
     "- Compile errors start with a stable code (`[WD201] …`) and always name the file," +
       " the line, and a fix. Read the message; it tells you exactly what to write."
@@ -776,6 +965,8 @@ export function llmsFullText(site) {
   }
   out.push("");
 
+  out.push(...blockStructureSection());
+
   out.push("## @loop clauses (this fixed order, all optional)");
   for (const c of cat.loopClauses) {
     out.push(`- \`${c.syntax}\`: ${c.description} e.g. \`${c.example}\``);
@@ -807,12 +998,17 @@ export function llmsFullText(site) {
   out.push(`Join conditions with ${cat.predicateJoiners.map((j) => `\`${j}\``).join(" / ")}.`);
   out.push("");
 
+  out.push(...inlineAttributesSection());
+
   out.push("## Page frontmatter");
   for (const key of cat.frontmatterKeys) {
     out.push(`- \`${key.name}\`: ${key.description} e.g. \`${key.example}\``);
   }
   out.push("");
 
+  out.push(...collectionsSection());
+  out.push(...skinSection());
+
   out.push("## Compile error codes");
   for (const area of cat.errorAreas) {
     out.push(`### ${area.range} ${area.title}`);

package/src/cli.js

@@ -19,7 +19,7 @@ import {
 } from "./dev.js";
 import { discoverRoutes, isDraft, outputPathForRoute } from "./router.js";
 import { availableTemplates, initProject } from "./scaffold.js";
-import { contentType, resolvePublicFile, serve } from "./statics.js";
+import { contentType, isServableFile, pipeFile, resolvePublicFile, serve } from "./statics.js";
 
 const cliPath = fileURLToPath(import.meta.url);
 
@@ -329,7 +329,10 @@ function startPreviewServer({ cwd, log, error }) {
  */
 function serveDev(distRoot, url, res, draftFiles, buildError) {
   const file = resolvePublicFile(distRoot, url);
-  if (!file || !fs.existsSync(file)) {
+  // `isServableFile`, not `existsSync`: a route whose last segment contains a
+  // dot (`/v1.2/`) resolves to a DIRECTORY, and streaming one is an unhandled
+  // EISDIR that kills the dev server. It is a miss here, like any other.
+  if (!file || !isServableFile(file)) {
     // An HTML route with no dist output while the last build FAILED is almost
     // certainly unbuilt because of that failure — serve the compile error (the
     // SSE overlay replays it too), not the misleading "hidden or not created"
@@ -353,7 +356,7 @@ function serveDev(distRoot, url, res, draftFiles, buildError) {
     return;
   }
   res.writeHead(200, { "content-type": contentType(file) });
-  fs.createReadStream(file).pipe(res);
+  pipeFile(file, res);
 }
 
 /**

package/src/compiler/actions.js

@@ -17,6 +17,7 @@ import {
   stripQuotes,
   validatePath
 } from "./interpolation.js";
+import { a11yAttrHtml, takeA11yAttrs } from "./structure.js";
 
 /**
  * @typedef {import("./context.js").Ctx} Ctx
@@ -25,7 +26,7 @@ import {
 
 // A concrete, compilable :button line for the malformed hint + directive catalog.
 export const BUTTON_EXAMPLE = ':button "Add one" -> count++';
-const BUTTON_USE = `Use: :button "Label" -> action — e.g. ${BUTTON_EXAMPLE}`;
+const BUTTON_USE = `Use: :button "Label" [role="…"] [aria-…="…"] [title="…"] -> action — e.g. ${BUTTON_EXAMPLE}`;
 
 /**
  * @param {string} line
@@ -34,8 +35,8 @@ const BUTTON_USE = `Use: :button "Label" -> action — e.g. ${BUTTON_EXAMPLE}`;
  * @returns {string}
  */
 export function handleButton(line, ctx, index) {
-  const match = line.match(/^:button\s+"([^"]+)"\s*->\s*(.+)$/);
-  if (!match)
+  /** @returns {never} */
+  const malformed = () => {
     throw wdError(`Malformed :button in ${at(ctx, index)}: ${line}. ${BUTTON_USE}`, {
       code: "WD301",
       file: ctx.file,
@@ -43,24 +44,42 @@ export function handleButton(line, ctx, index) {
       hint: BUTTON_USE.slice("Use: ".length),
       example: BUTTON_EXAMPLE
     });
+  };
+  // Label first, then any whitelisted accessibility attributes, then `->` and
+  // the action chain. The attributes are peeled BEFORE the arrow is looked for,
+  // so a value containing `->` (`aria-label="a -> b"`) cannot split the line in
+  // the wrong place, and a rejected attribute reports the whitelist rather than
+  // "malformed :button".
+  const head = line.match(/^:button\s+"([^"]+)"\s*([\s\S]*)$/);
+  if (!head) return malformed();
+  const taken = takeA11yAttrs(head[2], ctx, index, ":button");
+  const arrow = taken.rest.match(/^->\s*(.+)$/);
+  if (!arrow) return malformed();
+  /** @type {[string, string]} */
+  const match = [head[1], arrow[1]];
   ctx.comp.assets.runtime = true;
-  const action = parseAction(match[2], ctx);
+  const action = parseAction(match[1], ctx);
   for (const a of Array.isArray(action) ? action : [action])
     recordSymbol(ctx, index, {
       kind: "action",
       name: a.target,
       target: a.target,
       op: a.op,
-      detail: `:button "${match[1]}" -> ${match[2].trim()}`
+      detail: `:button "${match[0]}" -> ${match[1].trim()}`
     });
+  const a11y = a11yAttrHtml(taken.attrs);
   if (Array.isArray(action)) {
-    return `<button type="button" data-wd-actions="${escapeHtml(JSON.stringify(action))}">${escapeHtml(match[1])}</button>`;
+    return `<button type="button"${a11y} data-wd-actions="${escapeHtml(JSON.stringify(action))}">${escapeHtml(match[0])}</button>`;
   }
   const valueAttr =
     action.value === undefined
       ? ""
       : ` data-wd-value="${escapeHtml(JSON.stringify(action.value))}"`;
-  return `<button type="button" data-wd-action="${action.op}" data-wd-target="${action.target}"${valueAttr}>${escapeHtml(match[1])}</button>`;
+  // The target is a STATE KEY, and a section-scoped key carries the `::: name #id`
+  // id verbatim (`a"onmouseover=…:count`), so it needs the same escaping the
+  // neighbouring `id=` has always had — otherwise the id closes the attribute and
+  // whatever follows becomes a live one.
+  return `<button type="button"${a11y} data-wd-action="${action.op}" data-wd-target="${escapeHtml(action.target)}"${valueAttr}>${escapeHtml(match[0])}</button>`;
 }
 
 // Concrete, compilable examples for the effect / every hint tails + catalog.
@@ -69,6 +88,47 @@ export function handleButton(line, ctx, index) {
 export const EFFECT_EXAMPLE = ":effect query -> searches++";
 const EFFECT_USE = `Use: :effect watchedState -> action[; action…] (actions use the :button vocabulary) — e.g. ${EFFECT_EXAMPLE}`;
 
+// ---------------------------------------------------------------------------
+// `:every` and `:effect` are PAGE-LEVEL registrations, not per-row ones.
+//
+// A reactive `@loop` compiles its body once into a `<template>` and the runtime
+// clones that template per list item, so a timer or a watcher written inside the
+// body is registered once per row: three rows meant three intervals, and a row
+// removed from the list left its interval running, so a single tick advanced a
+// counter by the number of rows the page had EVER shown. There is no correct
+// per-row meaning to give either directive — an effect watches a top-level state
+// key and an action targets one, neither can name the row — so the placement is
+// refused at compile time rather than repaired at runtime.
+//
+// Mirrors `declareState`'s WD202 check: `ctx.loopItem` is set only inside a
+// REACTIVE loop body (a static unroll passes the row through `ctx.scope`), which
+// is exactly the case that clones. It is inherited by everything nested in that
+// body, so a nested loop and an `:if`/each-if branch are covered by the same test.
+// ---------------------------------------------------------------------------
+
+/**
+ * Refuse a `:every`/`:effect` written inside a reactive `@loop` body.
+ * @param {string} what The directive keyword, for the message.
+ * @param {string} onList The same directive rewritten to act on the whole list,
+ *   which is what the author almost always meant.
+ * @param {string} example The directive's compilable example, for the hint tail.
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {void}
+ */
+function rejectInReactiveLoop(what, onList, example, ctx, index) {
+  if (!ctx.loopItem) return;
+  const hint =
+    `declare ${what} once outside the loop — at page level, or inside the ::: section — and act on the ` +
+    `whole list (${onList}) — e.g. ${example}`;
+  throw wdError(
+    `${what} cannot be used inside a reactive @loop body in ${at(ctx, index)}. ` +
+      `Each row is cloned from the loop template, so every row would register its own ` +
+      `timer/watcher and a removed row's would keep firing. Use: ${hint}`,
+    { code: "WD315", file: ctx.file, line: lineOf(ctx, index), hint, example }
+  );
+}
+
 /**
  * Parse `:effect <watched> -> <actions>` into a zero-output marker the runtime
  * watches: when `<watched>` state changes, it runs `<actions>` (the same `:button`
@@ -80,6 +140,7 @@ const EFFECT_USE = `Use: :effect watchedState -> action[; action…] (actions us
  * @returns {string}
  */
 export function handleEffect(line, ctx, index) {
+  rejectInReactiveLoop(":effect", ":effect query -> rows refetch", EFFECT_EXAMPLE, ctx, index);
   const match = line.match(/^:effect\s+([A-Za-z_$][\w$.]*)\s*->\s*(.+)$/);
   if (!match)
     throw wdError(`Malformed :effect in ${at(ctx, index)}: ${line}. ${EFFECT_USE}`, {
@@ -138,6 +199,7 @@ function parseDuration(raw) {
  * @returns {string}
  */
 export function handleEvery(line, ctx, index) {
+  rejectInReactiveLoop(":every", ":every 5s -> rows refetch", EVERY_EXAMPLE, ctx, index);
   const match = line.match(/^:every\s+(\S+)\s*->\s*(.+)$/);
   if (!match)
     throw wdError(`Malformed :every in ${at(ctx, index)}: ${line}. ${EVERY_USE}`, {
@@ -173,7 +235,7 @@ export function handleEvery(line, ctx, index) {
 // than the schematic `name++`. The action vocabulary the directive catalog draws
 // from lives here (the parser branches below), mirrored compactly in ACTION_USE.
 export const ACTION_EXAMPLE = "count++";
-export const ACTION_USE = `Use: name++, name--, n += k, n -= k, name = v, flag toggle, list append/prepend v, list toggle v, list remove v, x clear, obj merge other, obj delete key, name reset — chain with ";" — e.g. ${ACTION_EXAMPLE}`;
+export const ACTION_USE = `Use: name++, name--, n += k, n -= k, name = v, flag toggle, list append/prepend v, list toggle v, list remove v, x clear, obj merge other, obj delete key, name reset, name refetch — chain with ";" — e.g. ${ACTION_EXAMPLE}`;
 
 /**
  * Parse a `:button` action expression into a validated `{ op, target, value }`,
@@ -252,10 +314,16 @@ function parseSingleAction(expression, raw, ctx) {
     if (toggle[2] === undefined) return { op: "toggle", target };
     return { op: "member-toggle", target, value: parseActionLiteral(toggle[2], ctx) };
   }
-  const prepend = expression.match(new RegExp(`^(${PATH})\\s+(?:append|prepend)\\s+(.+)$`));
-  if (prepend) {
-    const op = expression.includes(" prepend ") ? "prepend" : "append";
-    return { op, target: resolveTarget(prepend[1]), value: parseActionLiteral(prepend[2], ctx) };
+  // Capture the OPERATOR, never search the whole expression for it: scanning for
+  // " prepend " made `list append "we prepend things"` compile to
+  // data-wd-action="prepend", so the operand silently chose the operator.
+  const listAdd = expression.match(new RegExp(`^(${PATH})\\s+(append|prepend)\\s+(.+)$`));
+  if (listAdd) {
+    return {
+      op: listAdd[2],
+      target: resolveTarget(listAdd[1]),
+      value: parseActionLiteral(listAdd[3], ctx)
+    };
   }
   // Per-row: remove the current row from the list being looped — `todos remove todo`.
   // Disambiguation: operand IS the loop item name → `remove` (current row);