@zvndev/darkmown 2.0.1 → 2.2.0

package/src/compiler/actions.js

@@ -9,7 +9,7 @@
 // while keeping the message text and `Use:` hints intact.
 // ---------------------------------------------------------------------------
 
-import { at } from "./context.js";
+import { at, lineOf, wdError } from "./context.js";
 import {
   escapeHtml,
   resolveStateKey,
@@ -23,6 +23,10 @@ import {
  * @typedef {import("./context.js").Action} Action
  */
 
+// 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}`;
+
 /**
  * @param {string} line
  * @param {Ctx} ctx
@@ -31,7 +35,13 @@ import {
  */
 export function handleButton(line, ctx, index) {
   const match = line.match(/^:button\s+"([^"]+)"\s*->\s*(.+)$/);
-  if (!match) throw new Error(`Malformed :button in ${at(ctx, index)}: ${line}`);
+  if (!match)
+    throw wdError(`Malformed :button in ${at(ctx, index)}: ${line}. ${BUTTON_USE}`, {
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint: BUTTON_USE.slice("Use: ".length),
+      example: BUTTON_EXAMPLE
+    });
   ctx.comp.assets.runtime = true;
   const action = parseAction(match[2], ctx);
   if (Array.isArray(action)) {
@@ -44,8 +54,11 @@ export function handleButton(line, ctx, index) {
   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).";
+// Concrete, compilable examples for the effect / every hint tails + catalog.
+// (Effects run the :button action vocabulary — mutations, not expressions; use
+// :computed for derived values. `searches++` is the canonical watch-and-act.)
+export const EFFECT_EXAMPLE = ":effect query -> searches++";
+const EFFECT_USE = `Use: :effect watchedState -> action[; action…] (actions use the :button vocabulary) — e.g. ${EFFECT_EXAMPLE}`;
 
 /**
  * Parse `:effect <watched> -> <actions>` into a zero-output marker the runtime
@@ -59,7 +72,13 @@ const EFFECT_USE =
  */
 export function handleEffect(line, ctx, index) {
   const match = line.match(/^:effect\s+([A-Za-z_$][\w$.]*)\s*->\s*(.+)$/);
-  if (!match) throw new Error(`Malformed :effect in ${at(ctx, index)}: ${line}. ${EFFECT_USE}`);
+  if (!match)
+    throw wdError(`Malformed :effect in ${at(ctx, index)}: ${line}. ${EFFECT_USE}`, {
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint: EFFECT_USE.slice("Use: ".length),
+      example: EFFECT_EXAMPLE
+    });
   const segs = validatePath(match[1], ctx, EFFECT_USE);
   const key = resolveStateKey(segs[0], ctx);
   if (!key)
@@ -73,8 +92,8 @@ export function handleEffect(line, ctx, index) {
   return `<script type="application/json" data-wd-effect>${safeScriptJson({ watch, actions })}</script>`;
 }
 
-const EVERY_USE =
-  "Use: :every <duration> -> action[; action…] — duration like 5s, 500ms, or 2m (actions use the :button vocabulary).";
+export const EVERY_EXAMPLE = ":every 5s -> seconds++";
+const EVERY_USE = `Use: :every <duration> -> action[; action…] — duration like 5s, 500ms, or 2m (actions use the :button vocabulary) — e.g. ${EVERY_EXAMPLE}`;
 
 /**
  * Parse a duration token into milliseconds: `<int>[ms|s|m]`, defaulting to ms.
@@ -101,7 +120,13 @@ function parseDuration(raw) {
  */
 export function handleEvery(line, ctx, index) {
   const match = line.match(/^:every\s+(\S+)\s*->\s*(.+)$/);
-  if (!match) throw new Error(`Malformed :every in ${at(ctx, index)}: ${line}. ${EVERY_USE}`);
+  if (!match)
+    throw wdError(`Malformed :every in ${at(ctx, index)}: ${line}. ${EVERY_USE}`, {
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint: EVERY_USE.slice("Use: ".length),
+      example: EVERY_EXAMPLE
+    });
   const ms = parseDuration(match[1]);
   if (ms == null || ms <= 0) {
     throw new Error(
@@ -114,8 +139,11 @@ export function handleEvery(line, ctx, index) {
   return `<script type="application/json" data-wd-every>${safeScriptJson({ ms, actions })}</script>`;
 }
 
-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 ";".';
+// One concrete action expression, appended so a model copies `count++` rather
+// 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}`;
 
 /**
  * Parse a `:button` action expression into a validated `{ op, target, value }`,
@@ -271,8 +299,13 @@ function parseMergeOperand(raw, ctx) {
   }
   const parsed = parseActionLiteral(value, ctx);
   if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
-  throw new Error(
-    `Unsupported merge operand "${raw}" in ${ctx.file}. Use: obj merge other (a state key or an inline {…} object).`
+  throw wdError(
+    `Unsupported merge operand "${raw}" in ${ctx.file}. Use: obj merge other (a state key or an inline {…} object) — e.g. settings merge patch`,
+    {
+      file: ctx.file,
+      hint: "obj merge other (a state key or an inline {…} object) — e.g. settings merge patch",
+      example: "settings merge patch"
+    }
   );
 }
 

package/src/compiler/collections.js

@@ -15,10 +15,10 @@
 // `scoped`/`draft`).
 // ---------------------------------------------------------------------------
 
-import fs from "node:fs";
 import path from "node:path";
 import { firstParagraph } from "../feeds.js";
 import { parseFrontmatter } from "./frontmatter.js";
+import { fsReader } from "./fs-reader.js";
 
 /**
  * @typedef {import("./context.js").Paths} Paths
@@ -47,20 +47,22 @@ const SCHEMA_TYPES = new Set(["string", "number", "boolean", "date", "string[]"]
  *
  * @param {Route[]} routes Post-draft-filter routes from `discoverRoutes`.
  * @param {Paths} paths Resolved project paths (`routesRoot` for `_schema.wd`).
+ * @param {import("./reader.js").Reader} [reader] Source reader (fs-backed by
+ *   default; pass an in-memory reader to build collections without a filesystem).
  * @returns {Map<string, CollectionRow[]>} Collection name → entry rows.
  */
-export function buildCollections(routes, paths) {
+export function buildCollections(routes, paths, reader = fsReader()) {
   /** @type {Map<string, CollectionRow[]>} */
   const collections = new Map();
   for (const route of routes) {
     const name = collectionNameOf(route.route);
     if (!name) continue;
     const rows = collections.get(name) || [];
-    rows.push(rowFor(route));
+    rows.push(rowFor(route, reader));
     collections.set(name, rows);
   }
   for (const [name, rows] of collections) {
-    const schema = readSchema(name, paths);
+    const schema = readSchema(name, paths, reader);
     if (schema) validateRows(rows, schema, name);
   }
   return collections;
@@ -87,9 +89,10 @@ function collectionNameOf(route) {
  * are added AFTER the spread so a stray frontmatter `url:`/`slug:` can't shadow
  * the real route data the loop relies on.
  * @param {Route} route
+ * @param {import("./reader.js").Reader} reader Source reader for the excerpt body.
  * @returns {CollectionRow}
  */
-function rowFor(route) {
+function rowFor(route, reader) {
   const slug = path.basename(route.file, path.extname(route.file));
   /** @type {Record<string, unknown>} */
   const fields = {};
@@ -98,7 +101,7 @@ function rowFor(route) {
     ...fields,
     url: route.route,
     slug: slug === "index" ? path.basename(path.dirname(route.file)) : slug,
-    excerpt: excerptFor(route)
+    excerpt: excerptFor(route, reader)
   };
 }
 
@@ -126,13 +129,14 @@ function coerceScalar(value) {
  * (plain `.md` only) the first paragraph of its body, else "". Mirrors the RSS
  * description fallback so a collection card and the feed read the same snippet.
  * @param {Route} route
+ * @param {import("./reader.js").Reader} reader Source reader for the `.md` body.
  * @returns {string}
  */
-function excerptFor(route) {
+function excerptFor(route, reader) {
   const fromMeta = route.meta.excerpt;
   if (typeof fromMeta === "string" && fromMeta.trim()) return fromMeta.trim();
   if (path.extname(route.file) !== ".md") return "";
-  const { body } = parseFrontmatter(fs.readFileSync(route.file, "utf8"), route.file);
+  const { body } = parseFrontmatter(reader.readText(route.file), route.file);
   return firstParagraph(body);
 }
 
@@ -153,12 +157,13 @@ function excerptFor(route) {
  * schema file itself, pointing at the offending line.
  * @param {string} name Collection name.
  * @param {Paths} paths
+ * @param {import("./reader.js").Reader} [reader] Source reader (fs-backed by default).
  * @returns {SchemaField[] | null}
  */
-export function readSchema(name, paths) {
+export function readSchema(name, paths, reader = fsReader()) {
   const file = path.join(paths.routesRoot, name, "_schema.wd");
-  if (!fs.existsSync(file)) return null;
-  const raw = fs.readFileSync(file, "utf8");
+  if (!reader.exists(file)) return null;
+  const raw = reader.readText(file);
   return parseSchema(raw, file);
 }
 

package/src/compiler/context.js

@@ -77,6 +77,10 @@
  *   dependency map that drives incremental rebuilds.
  * @property {Set<string>} collectionsUsed Names of the collections this compile
  *   looped, so a change to any entry of a collection rebuilds its consumers.
+ * @property {import("./reader.js").Reader} reader The file reader every source
+ *   read threads through — the real filesystem by default, or an in-memory map
+ *   for `compileFromMemory`. Set once by `createCompilation` and reached via
+ *   `ctx.comp.reader` in the directive handlers (includes, loop data).
  */
 
 /**
@@ -148,6 +152,20 @@
  * @property {Set<string>} collectionsUsed Collection names this compile looped.
  */
 
+/**
+ * Structured, machine-readable companion to a compile error's string message.
+ * The string `message` contract is unchanged; `wd` gives an AI edit-loop (or an
+ * editor) the same facts without re-parsing the prose: which file/line, the
+ * corrective `Use:` template, and one concrete compilable example line.
+ * @typedef {object} WdErrorInfo
+ * @property {string} file Absolute path of the source file the error is in.
+ * @property {number} [line] 1-based file line the error points at, when known
+ *   (some errors — e.g. a bad `where` operand — are file-scoped only, matching
+ *   the string message, which likewise omits the line there).
+ * @property {string} [hint] The corrective `Use:` template (without the `Use: ` prefix).
+ * @property {string} [example] One concrete, compilable directive line.
+ */
+
 /**
  * A compiled `@loop … where` predicate.
  * @typedef {object} Predicate
@@ -202,9 +220,14 @@ export const LOOP_META = {
   $count: "count"
 };
 
-/** @returns {Compilation} */
-export function createCompilation() {
+/**
+ * @param {import("./reader.js").Reader} reader The source reader for this
+ *   compile (fs-backed by default; in-memory for `compileFromMemory`).
+ * @returns {Compilation}
+ */
+export function createCompilation(reader) {
   return {
+    reader,
     assets: {
       skins: new Set(),
       scripts: new Set(),
@@ -248,7 +271,33 @@ export function createScope(parent, vars = {}) {
  * @returns {string}
  */
 export function at(ctx, index) {
-  return `${ctx.file}:${index + 1 + (ctx.bodyLine ?? 0) + (ctx.lineOffset ?? 0)}`;
+  return `${ctx.file}:${lineOf(ctx, index)}`;
+}
+
+/**
+ * The 1-based true file line for a body-slice `index` — the numeric half of
+ * {@link at}, exposed so {@link wdError} can populate the structured `wd.line`.
+ * @param {Pick<Ctx, "bodyLine" | "lineOffset">} ctx
+ * @param {number} index 0-based line index into the current body slice.
+ * @returns {number}
+ */
+export function lineOf(ctx, index) {
+  return index + 1 + (ctx.bodyLine ?? 0) + (ctx.lineOffset ?? 0);
+}
+
+/**
+ * Build a compile `Error` whose string `message` is unchanged but which also
+ * carries a structured {@link WdErrorInfo} on `err.wd` — so an AI edit-loop (or
+ * an editor) gets file/line/hint/example without re-parsing the prose. The
+ * string contract is the source of truth; `wd` is a strictly additive mirror.
+ * @param {string} message The full user-facing error string (unchanged contract).
+ * @param {WdErrorInfo} wd The structured mirror.
+ * @returns {Error & { wd: WdErrorInfo }}
+ */
+export function wdError(message, wd) {
+  const err = /** @type {Error & { wd: WdErrorInfo }} */ (new Error(message));
+  err.wd = wd;
+  return err;
 }
 
 /**

package/src/compiler/expr-ast.js

@@ -0,0 +1,296 @@
+// ---------------------------------------------------------------------------
+// Compiled-expression → compact AST.
+//
+// The predicate/computed compilers in `predicates.js` still do ALL the security
+// validation — they map every operand through a fixed grammar to safe JS over the
+// `I()`/`S()`/`C()`/`A()` readers, and reject anything outside the whitelist. This
+// module takes that ALREADY-VALIDATED JS fragment and re-parses it into a compact
+// serialized AST (nested arrays), so the runtime can WALK it with a tiny closed
+// evaluator instead of constructing a `new Function`. That is the whole point:
+// reactive pages no longer need `script-src 'unsafe-eval'`.
+//
+// The parsed sub-language is closed and small: the reader calls `S(k[,r])`,
+// `I(p)`, `C(a,b)`, `A(name,list[,field])`; number / JSON-string / boolean / null
+// / object / array literals; the operators `! - * / % + - < > <= >= == != && ||`;
+// and grouping parens. Precedence and associativity match JavaScript exactly, so
+// the walked AST evaluates identically to the prior `new Function` path. Anything
+// unexpected is a hard parse error — never a silent fallthrough.
+//
+// Node shapes (array with a tag at [0]):
+//   ["L", value]            literal (number | string | boolean | null | obj | arr)
+//   ["S", key]              state read           → getPath(state[key])
+//   ["S", key, rest]        dotted state read    → getPath(state[key], rest)
+//   ["I", path]             loop-item read       → getPath(item, path)
+//   ["C", a, b]             contains(a, b)
+//   ["A", name, list]       aggregate            → AGG(name, list)
+//   ["A", name, list, fld]  aggregate w/ field   → AGG(name, list, fld)
+//   ["!", a] | ["u-", a]    unary not / negate
+//   [op, a, b]              binary op (op ∈ the operator set above)
+// ---------------------------------------------------------------------------
+
+import { FORMATTERS } from "./format.js";
+import { getPath } from "./interpolation.js";
+
+// Binary-operator precedence (higher binds tighter), matching JS.
+/** @type {Record<string, number>} */
+const PREC = {
+  "||": 1,
+  "&&": 2,
+  "==": 3,
+  "!=": 3,
+  "<": 4,
+  ">": 4,
+  "<=": 4,
+  ">=": 4,
+  "+": 5,
+  "-": 5,
+  "*": 6,
+  "/": 6,
+  "%": 6
+};
+
+/**
+ * Re-parse a validated compiled expression (JS fragment over I()/S()/C()/A())
+ * into a compact AST. Throws on anything outside the closed grammar.
+ * @param {string} code
+ * @returns {any[]}
+ */
+export function astOf(code) {
+  let i = 0;
+  const n = code.length;
+  const ws = () => {
+    while (i < n && /\s/.test(code[i])) i++;
+  };
+  /** Peek a binary operator at the cursor without consuming; null if none. */
+  const peekOp = () => {
+    ws();
+    const two = code.slice(i, i + 2);
+    if (
+      two === "&&" ||
+      two === "||" ||
+      two === "==" ||
+      two === "!=" ||
+      two === "<=" ||
+      two === ">="
+    )
+      return two;
+    const one = code[i];
+    if (
+      one === "<" ||
+      one === ">" ||
+      one === "+" ||
+      one === "-" ||
+      one === "*" ||
+      one === "/" ||
+      one === "%"
+    )
+      return one;
+    return null;
+  };
+  /** @param {number} minPrec @returns {any[]} */
+  const parseExpr = (minPrec) => {
+    /** @type {any[]} */
+    let left = parseUnary();
+    for (;;) {
+      const op = peekOp();
+      if (op === null) break;
+      const prec = PREC[op];
+      if (prec < minPrec) break;
+      i += op.length;
+      const right = parseExpr(prec + 1);
+      left = [op, left, right];
+    }
+    return left;
+  };
+  /** @returns {any[]} */
+  const parseUnary = () => {
+    ws();
+    if (code[i] === "!" && code[i + 1] !== "=") {
+      i++;
+      return ["!", parseUnary()];
+    }
+    if (code[i] === "-") {
+      i++;
+      return ["u-", parseUnary()];
+    }
+    return parsePrimary();
+  };
+  /** @returns {any[]} */
+  const parsePrimary = () => {
+    ws();
+    const c = code[i];
+    if (c === "(") {
+      i++;
+      /** @type {any[]} */
+      const e = parseExpr(1);
+      ws();
+      if (code[i] !== ")") throw new Error(`expr-ast: expected ) at ${i} in ${code}`);
+      i++;
+      return e;
+    }
+    if (c === '"') return ["L", readString()];
+    if (c === "{" || c === "[") return ["L", readJson()];
+    if (c === "." || (c >= "0" && c <= "9")) return ["L", readNumber()];
+    if (/[A-Za-z_$]/.test(c)) return readIdent();
+    throw new Error(`expr-ast: unexpected "${c ?? "<end>"}" at ${i} in ${code}`);
+  };
+  const readString = () => {
+    let j = i + 1;
+    while (j < n) {
+      if (code[j] === "\\") j += 2;
+      else if (code[j] === '"') break;
+      else j++;
+    }
+    const lit = code.slice(i, j + 1);
+    i = j + 1;
+    return JSON.parse(lit);
+  };
+  const readJson = () => {
+    let depth = 0;
+    let j = i;
+    for (; j < n; j++) {
+      const ch = code[j];
+      if (ch === '"') {
+        j++;
+        while (j < n && code[j] !== '"') j += code[j] === "\\" ? 2 : 1;
+      } else if (ch === "{" || ch === "[") depth++;
+      else if (ch === "}" || ch === "]") {
+        depth--;
+        if (depth === 0) {
+          j++;
+          break;
+        }
+      }
+    }
+    const lit = code.slice(i, j);
+    i = j;
+    return JSON.parse(lit);
+  };
+  const readNumber = () => {
+    let j = i;
+    while (j < n && /[0-9.]/.test(code[j])) j++;
+    const num = Number(code.slice(i, j));
+    i = j;
+    return num;
+  };
+  /** @returns {any[]} */
+  const readIdent = () => {
+    let j = i;
+    while (j < n && /[\w$]/.test(code[j])) j++;
+    const word = code.slice(i, j);
+    i = j;
+    if (word === "true") return ["L", true];
+    if (word === "false") return ["L", false];
+    if (word === "null") return ["L", null];
+    if (code[i] !== "(") throw new Error(`expr-ast: unexpected identifier "${word}" in ${code}`);
+    const args = parseArgs();
+    if (word === "S") return args.length > 1 ? ["S", args[0][1], args[1][1]] : ["S", args[0][1]];
+    if (word === "I") return ["I", args[0][1]];
+    if (word === "C") return ["C", args[0], args[1]];
+    if (word === "A")
+      return args.length > 2 ? ["A", args[0][1], args[1], args[2][1]] : ["A", args[0][1], args[1]];
+    throw new Error(`expr-ast: unknown call "${word}" in ${code}`);
+  };
+  /** @returns {any[][]} */
+  const parseArgs = () => {
+    i++; // consume "("
+    /** @type {any[][]} */
+    const args = [];
+    ws();
+    if (code[i] !== ")") {
+      args.push(parseExpr(1));
+      ws();
+      while (code[i] === ",") {
+        i++;
+        args.push(parseExpr(1));
+        ws();
+      }
+    }
+    ws();
+    if (code[i] !== ")") throw new Error(`expr-ast: expected ) closing call in ${code}`);
+    i++;
+    return args;
+  };
+
+  const ast = parseExpr(1);
+  ws();
+  if (i !== n) throw new Error(`expr-ast: trailing input at ${i} in ${code}`);
+  return ast;
+}
+
+/**
+ * `JSON.stringify(astOf(code))` — the attribute payload the runtime reads.
+ * @param {string} code
+ * @returns {string}
+ */
+export const serializeExpr = (code) => JSON.stringify(astOf(code));
+
+/** @param {unknown} a @param {unknown} b @returns {boolean} */
+const contains = (a, b) =>
+  String(a ?? "")
+    .toLowerCase()
+    .includes(String(b ?? "").toLowerCase());
+
+/**
+ * Build-time mirror of the runtime AST walker — same operators, so a `:computed`
+ * or `where`/`when` predicate folds to the SAME value the runtime will recompute.
+ * `state` reads come from the compilation's declared-state map. No eval.
+ * @param {any[]} node
+ * @param {unknown} item Loop row for I(); undefined otherwise.
+ * @param {{ state: Map<string, unknown> }} comp
+ * @returns {any}
+ */
+export function evalAst(node, item, comp) {
+  /** @param {any[]} n @returns {any} */
+  const ev = (n) => {
+    const t = n[0];
+    switch (t) {
+      case "L":
+        return n[1];
+      case "S":
+        return getPath(comp.state.get(n[1]), n[2] ? n[2].split(".") : []);
+      case "I":
+        return getPath(item, n[1] ? n[1].split(".") : []);
+      case "C":
+        return contains(ev(n[1]), ev(n[2]));
+      case "A": {
+        const f = FORMATTERS[n[1]];
+        return f ? f(ev(n[2]), n[3] == null ? [] : [n[3]]) : undefined;
+      }
+      case "!":
+        return !ev(n[1]);
+      case "u-":
+        return -ev(n[1]);
+      case "&&":
+        return ev(n[1]) && ev(n[2]);
+      case "||":
+        return ev(n[1]) || ev(n[2]);
+      case "==":
+        // biome-ignore lint/suspicious/noDoubleEquals: loose equality preserves prior `new Function` semantics exactly.
+        return ev(n[1]) == ev(n[2]);
+      case "!=":
+        // biome-ignore lint/suspicious/noDoubleEquals: loose inequality preserves prior `new Function` semantics exactly.
+        return ev(n[1]) != ev(n[2]);
+      case "<":
+        return ev(n[1]) < ev(n[2]);
+      case ">":
+        return ev(n[1]) > ev(n[2]);
+      case "<=":
+        return ev(n[1]) <= ev(n[2]);
+      case ">=":
+        return ev(n[1]) >= ev(n[2]);
+      case "+":
+        return ev(n[1]) + ev(n[2]);
+      case "-":
+        return ev(n[1]) - ev(n[2]);
+      case "*":
+        return ev(n[1]) * ev(n[2]);
+      case "/":
+        return ev(n[1]) / ev(n[2]);
+      case "%":
+        return ev(n[1]) % ev(n[2]);
+    }
+    throw new Error(`expr-ast: unknown op "${t}"`);
+  };
+  return ev(node);
+}

package/src/compiler/fetch.js

@@ -7,7 +7,7 @@
 // while keeping the message text and `Use:` hints intact.
 // ---------------------------------------------------------------------------
 
-import { at } from "./context.js";
+import { at, lineOf, wdError } from "./context.js";
 import {
   escapeHtml,
   resolveStateKey,
@@ -21,8 +21,10 @@ import { declareState } from "./state.js";
  * @typedef {import("./context.js").Ctx} Ctx
  */
 
-const FETCH_USE =
-  'Use: :fetch name from "url" [method=…] [timeout=ms] [retry=N] [when=visible] [headers=key] [body=key] [refresh=url]';
+// A concrete, compilable :fetch line for the hint tail + the directive catalog.
+export const FETCH_EXAMPLE = ':fetch todos from "/api/todos.json" when=visible';
+
+const FETCH_USE = `Use: :fetch name from "url" [method=…] [timeout=ms] [retry=N] [when=visible] [headers=key] [body=key] [refresh=url] — e.g. ${FETCH_EXAMPLE}`;
 
 /**
  * Parse a keyword-arg `:fetch` directive into a lifecycle-aware marker.
@@ -36,7 +38,13 @@ const FETCH_USE =
  */
 export function handleFetch(line, ctx, index) {
   const head = line.match(/^:fetch\s+([A-Za-z_$][\w$]*)\s+from\s+("[^"]+"|\S+)\s*(.*)$/);
-  if (!head) throw new Error(`Malformed :fetch in ${at(ctx, index)}: ${line}. ${FETCH_USE}`);
+  if (!head)
+    throw wdError(`Malformed :fetch in ${at(ctx, index)}: ${line}. ${FETCH_USE}`, {
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint: FETCH_USE.slice("Use: ".length),
+      example: FETCH_EXAMPLE
+    });
   const name = head[1];
   const url = validateFetchUrl(stripQuotes(head[2]), ctx);
   /** @type {Record<string, string>} */