@zvndev/darkmown 2.1.0 → 2.3.1-next.1.g3a4a8dc

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,14 @@ 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}`, {
+      code: "WD301",
+      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 +55,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,12 +73,20 @@ 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}`, {
+      code: "WD302",
+      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)
-    throw new Error(
-      `:effect watches unknown state "${segs[0]}" in ${ctx.file}. Declare it first with :state ${segs[0]} = ...`
+    throw wdError(
+      `:effect watches unknown state "${segs[0]}" in ${ctx.file}. Declare it first with :state ${segs[0]} = ...`,
+      { code: "WD303", file: ctx.file }
     );
   ctx.comp.assets.runtime = true;
   const watch = [key, ...segs.slice(1)].join(".");
@@ -73,8 +95,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,12 +123,21 @@ 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}`, {
+      code: "WD304",
+      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(
-      `:every duration "${match[1]}" is not valid in ${at(ctx, index)}. ${EVERY_USE}`
-    );
+    throw wdError(`:every duration "${match[1]}" is not valid in ${at(ctx, index)}. ${EVERY_USE}`, {
+      code: "WD305",
+      file: ctx.file,
+      line: lineOf(ctx, index)
+    });
   }
   ctx.comp.assets.runtime = true;
   const action = parseAction(match[2], ctx);
@@ -114,8 +145,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 }`,
@@ -148,8 +182,9 @@ function parseSingleAction(expression, raw, ctx) {
     const segs = validatePath(name, ctx, ACTION_USE);
     const key = resolveStateKey(segs[0], ctx);
     if (!key) {
-      throw new Error(
-        `Button action targets unknown state "${segs[0]}" in ${ctx.file}. Declare it first with :state ${segs[0]} = ...`
+      throw wdError(
+        `Button action targets unknown state "${segs[0]}" in ${ctx.file}. Declare it first with :state ${segs[0]} = ...`,
+        { code: "WD306", file: ctx.file }
       );
     }
     return [key, ...segs.slice(1)].join(".");
@@ -170,8 +205,9 @@ function parseSingleAction(expression, raw, ctx) {
     if (ctx.loopItem && rhs === ctx.loopItem) {
       const target = resolveTarget(add[1]);
       if (!Array.isArray(ctx.comp.state.get(target))) {
-        throw new Error(
-          `Button action "${raw}" needs ${add[1]} to be a :state list (declare it "${add[1]} = []") in ${ctx.file}.`
+        throw wdError(
+          `Button action "${raw}" needs ${add[1]} to be a :state list (declare it "${add[1]} = []") in ${ctx.file}.`,
+          { code: "WD307", file: ctx.file }
         );
       }
       return { op: "append-row", target };
@@ -180,8 +216,9 @@ function parseSingleAction(expression, raw, ctx) {
     const value = parseActionLiteral(rhs, ctx);
     if (Array.isArray(ctx.comp.state.get(target))) return { op: "append", target, value };
     if (typeof value === "number") return { op: "add", target, value };
-    throw new Error(
-      `Unsupported button action "${raw}" in ${ctx.file}. += with non-number values requires a list state target — declare it "${add[1]} = []".`
+    throw wdError(
+      `Unsupported button action "${raw}" in ${ctx.file}. += with non-number values requires a list state target — declare it "${add[1]} = []".`,
+      { code: "WD308", file: ctx.file }
     );
   }
   // `flag toggle` (no operand) → boolean flip; `list toggle v` → member-toggle.
@@ -207,13 +244,15 @@ function parseSingleAction(expression, raw, ctx) {
       // its source is a path off the outer row, which the runtime's row-remove
       // can't target. Fail loud with the honest workaround.
       if (!ctx.loopKey) {
-        throw new Error(
-          `Button action "${raw}" can't delete a row of a nested (item-relative) loop in ${ctx.file}. Per-row "remove" needs a top-level :state/:store list; carry the row into one (cart += ${ctx.loopItem}) and remove it there.`
+        throw wdError(
+          `Button action "${raw}" can't delete a row of a nested (item-relative) loop in ${ctx.file}. Per-row "remove" needs a top-level :state/:store list; carry the row into one (cart += ${ctx.loopItem}) and remove it there.`,
+          { code: "WD309", file: ctx.file }
         );
       }
       if (resolveStateKey(remove[1], ctx) !== ctx.loopKey) {
-        throw new Error(
-          `Button action "${raw}" must target the :state list being looped (@loop ${remove[1]} into ${ctx.loopItem}) in ${ctx.file}.`
+        throw wdError(
+          `Button action "${raw}" must target the :state list being looped (@loop ${remove[1]} into ${ctx.loopItem}) in ${ctx.file}.`,
+          { code: "WD310", file: ctx.file }
         );
       }
       return { op: "remove", target: ctx.loopKey };
@@ -249,7 +288,12 @@ function parseSingleAction(expression, raw, ctx) {
       target: resolveTarget(assign[1]),
       value: parseActionLiteral(assign[2], ctx)
     };
-  throw new Error(`Unsupported button action "${raw}" in ${ctx.file}. ${ACTION_USE}`);
+  throw wdError(`Unsupported button action "${raw}" in ${ctx.file}. ${ACTION_USE}`, {
+    code: "WD311",
+    file: ctx.file,
+    hint: ACTION_USE.slice("Use: ".length),
+    example: ACTION_EXAMPLE
+  });
 }
 
 /**
@@ -264,15 +308,22 @@ function parseMergeOperand(raw, ctx) {
   if (/^[A-Za-z_$][\w$]*$/.test(value)) {
     const key = resolveStateKey(value, ctx);
     if (!key)
-      throw new Error(
-        `Button action merge targets unknown state "${value}" in ${ctx.file}. Declare it first with :state ${value} = ...`
+      throw wdError(
+        `Button action merge targets unknown state "${value}" in ${ctx.file}. Declare it first with :state ${value} = ...`,
+        { code: "WD312", file: ctx.file }
       );
     return key;
   }
   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`,
+    {
+      code: "WD313",
+      file: ctx.file,
+      hint: "obj merge other (a state key or an inline {…} object) — e.g. settings merge patch",
+      example: "settings merge patch"
+    }
   );
 }
 
@@ -292,12 +343,14 @@ function parseActionLiteral(raw, ctx) {
     try {
       return JSON.parse(value);
     } catch {
-      throw new Error(
-        `Unsupported action literal "${raw}" in ${ctx.file}. Use: a quoted string, number, boolean, null, or valid JSON.`
+      throw wdError(
+        `Unsupported action literal "${raw}" in ${ctx.file}. Use: a quoted string, number, boolean, null, or valid JSON.`,
+        { code: "WD314", file: ctx.file }
       );
     }
   }
-  throw new Error(
-    `Unsupported action literal "${raw}" in ${ctx.file}. Use: a quoted string, number, boolean, null, or valid JSON.`
+  throw wdError(
+    `Unsupported action literal "${raw}" in ${ctx.file}. Use: a quoted string, number, boolean, null, or valid JSON.`,
+    { code: "WD314", file: ctx.file }
   );
 }

package/src/compiler/body.js

@@ -7,7 +7,7 @@
 // multi-line directive bodies with nesting + fence awareness.
 // ---------------------------------------------------------------------------
 
-import { at } from "./context.js";
+import { at, lineOf, wdError } from "./context.js";
 import {
   handleBind,
   handleButton,
@@ -92,7 +92,10 @@ export function compileBody(lines, ctx) {
     if (container) {
       flush();
       if (!container[1].trim())
-        throw new Error(`Stray ::: close with no open container in ${ctx.file}`);
+        throw wdError(`Stray ::: close with no open container in ${ctx.file}`, {
+          code: "WD007",
+          file: ctx.file
+        });
       const block = scanContainer(lines, i, ctx);
       out.push(handleContainer(container[1].trim(), block.body, ctx, i));
       i = block.end;
@@ -235,17 +238,22 @@ export function compileBody(lines, ctx) {
       continue;
     }
     if (/^@repeat\b/.test(line)) {
-      throw new Error(
-        `@repeat was replaced by @loop in ${ctx.file}. Use: @loop /data.json into item ... @endloop`
+      throw wdError(
+        `@repeat was replaced by @loop in ${ctx.file}. Use: @loop /data.json into item ... @endloop`,
+        { code: "WD008", file: ctx.file, hint: "@loop /data.json into item ... @endloop" }
       );
     }
     if (/^:for\b/.test(line)) {
-      throw new Error(
-        `:for was replaced by @loop in ${ctx.file}. Use: @loop items into item ... @endloop`
+      throw wdError(
+        `:for was replaced by @loop in ${ctx.file}. Use: @loop items into item ... @endloop`,
+        { code: "WD009", file: ctx.file, hint: "@loop items into item ... @endloop" }
       );
     }
     if (/^(@endloop|:endif|:endfor|:endform|:else)\s*$/.test(line)) {
-      throw new Error(`Stray "${line.trim()}" with no matching opener in ${ctx.file}`);
+      throw wdError(`Stray "${line.trim()}" with no matching opener in ${ctx.file}`, {
+        code: "WD010",
+        file: ctx.file
+      });
     }
     warnUnknownDirective(line, ctx);
     prose.push(line);
@@ -371,7 +379,11 @@ function scanBlock(lines, start, openRe, endToken, ctx) {
     }
     body.push(line);
   }
-  throw new Error(`Missing ${endToken} for "${lines[start]}" in ${at(ctx, start)}`);
+  throw wdError(`Missing ${endToken} for "${lines[start]}" in ${at(ctx, start)}`, {
+    code: "WD011",
+    file: ctx.file,
+    line: lineOf(ctx, start)
+  });
 }
 
 /**
@@ -457,7 +469,11 @@ function scanContainer(lines, start, ctx) {
     }
     body.push(line);
   }
-  throw new Error(`Missing closing ::: for "${lines[start]}" in ${at(ctx, start)}`);
+  throw wdError(`Missing closing ::: for "${lines[start]}" in ${at(ctx, start)}`, {
+    code: "WD012",
+    file: ctx.file,
+    line: lineOf(ctx, start)
+  });
 }
 
 /**
@@ -518,8 +534,9 @@ function scanConditional(lines, start, ctx) {
       const elseIf = t.match(/^:else if\s+(.+?)\s*$/);
       if (elseIf) {
         if (mode === "else")
-          throw new Error(
-            `":else if" after ":else" in ${ctx.file}. ":else" must be the last branch — order the "else if" conditions before the bare ":else".`
+          throw wdError(
+            `":else if" after ":else" in ${ctx.file}. ":else" must be the last branch — order the "else if" conditions before the bare ":else".`,
+            { code: "WD013", file: ctx.file }
           );
         falsy.push(`:if ${elseIf[1]}`); // desugar the chain tail into a nested :if
         falsyStart = i;
@@ -529,8 +546,9 @@ function scanConditional(lines, start, ctx) {
       }
       if (t === ":else") {
         if (mode === "else")
-          throw new Error(
-            `Duplicate ":else" in ${ctx.file}. A conditional may have only one bare ":else".`
+          throw wdError(
+            `Duplicate ":else" in ${ctx.file}. A conditional may have only one bare ":else".`,
+            { code: "WD014", file: ctx.file }
           );
         falsyStart = i + 1;
         current = falsy;
@@ -540,5 +558,9 @@ function scanConditional(lines, start, ctx) {
     }
     current.push(line);
   }
-  throw new Error(`Missing :endif for "${lines[start]}" in ${at(ctx, start)}`);
+  throw wdError(`Missing :endif for "${lines[start]}" in ${at(ctx, start)}`, {
+    code: "WD015",
+    file: ctx.file,
+    line: lineOf(ctx, start)
+  });
 }

package/src/compiler/collections.js

@@ -17,6 +17,7 @@
 
 import path from "node:path";
 import { firstParagraph } from "../feeds.js";
+import { wdError } from "./context.js";
 import { parseFrontmatter } from "./frontmatter.js";
 import { fsReader } from "./fs-reader.js";
 
@@ -197,8 +198,9 @@ export function parseSchema(raw, file) {
     if (!trimmed || trimmed.startsWith("#")) continue; // blank line or comment
     const match = trimmed.match(/^([A-Za-z0-9_-]+):\s*(.+)$/);
     if (!match) {
-      throw new Error(
-        `Malformed schema line in ${file}:${i + 1}: "${trimmed}". Use: field: type (e.g. \`title: string\`, \`tags: string[]\`, \`featured: boolean?\`).`
+      throw wdError(
+        `Malformed schema line in ${file}:${i + 1}: "${trimmed}". Use: field: type (e.g. \`title: string\`, \`tags: string[]\`, \`featured: boolean?\`).`,
+        { code: "WD120", file, line: i + 1 }
       );
     }
     fields.push(parseSchemaField(match[1], match[2].trim(), file, i + 1));
@@ -219,8 +221,9 @@ function parseSchemaField(name, rawType, file, lineNo) {
   const optional = rawType.endsWith("?");
   const type = optional ? rawType.slice(0, -1).trim() : rawType;
   if (!SCHEMA_TYPES.has(type)) {
-    throw new Error(
-      `Unknown schema type "${rawType}" for field "${name}" in ${file}:${lineNo}. Use one of: ${[...SCHEMA_TYPES].join(", ")} (append "?" to make a field optional).`
+    throw wdError(
+      `Unknown schema type "${rawType}" for field "${name}" in ${file}:${lineNo}. Use one of: ${[...SCHEMA_TYPES].join(", ")} (append "?" to make a field optional).`,
+      { code: "WD121", file, line: lineNo }
     );
   }
   return { name, type, optional };
@@ -249,8 +252,9 @@ function validateRows(rows, schema, name) {
     for (const field of schema) validateField(row, field, where);
     for (const key of Object.keys(row)) {
       if (allowed.has(key)) continue;
-      throw new Error(
-        `Unknown frontmatter field "${key}" in ${where}: it is not declared in _schema.wd. Add \`${key}: <type>\` to the schema, or remove the field.`
+      throw wdError(
+        `Unknown frontmatter field "${key}" in ${where}: it is not declared in _schema.wd. Add \`${key}: <type>\` to the schema, or remove the field.`,
+        { code: "WD122" }
       );
     }
   }
@@ -267,14 +271,16 @@ function validateField(row, field, where) {
   const present = field.name in row && row[field.name] !== null && row[field.name] !== "";
   if (!present) {
     if (field.optional) return;
-    throw new Error(
-      `Missing required field "${field.name}" (${field.type}) in ${where}. Add \`${field.name}: …\` to the entry's frontmatter, or mark it optional with "${field.name}: ${field.type}?" in _schema.wd.`
+    throw wdError(
+      `Missing required field "${field.name}" (${field.type}) in ${where}. Add \`${field.name}: …\` to the entry's frontmatter, or mark it optional with "${field.name}: ${field.type}?" in _schema.wd.`,
+      { code: "WD123" }
     );
   }
   const value = row[field.name];
   if (!matchesType(value, field.type)) {
-    throw new Error(
-      `Field "${field.name}" in ${where} should be ${field.type} but is "${describe(value)}". Fix the entry's frontmatter or the schema.`
+    throw wdError(
+      `Field "${field.name}" in ${where} should be ${field.type} but is "${describe(value)}". Fix the entry's frontmatter or the schema.`,
+      { code: "WD124" }
     );
   }
 }

package/src/compiler/context.js

@@ -152,6 +152,27 @@
  * @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 code, which
+ * file/line, the corrective `Use:` template, and one concrete compilable
+ * example line.
+ * @typedef {object} WdErrorInfo
+ * @property {string} code Stable error code (`WD` + three digits, e.g. `WD201`).
+ *   Every code is registered in `src/errors.js` with a title, cause, and fix,
+ *   and documented in `docs/errors.md`. {@link wdError} prefixes the string
+ *   message with `[<code>] `, so the code is greppable from the message too.
+ * @property {string} [file] Absolute path of the source file the error is in,
+ *   when the throwing layer knows one (`compileSkin` is a pure string→string
+ *   pass and a collection-row check names the entry route instead).
+ * @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
@@ -193,6 +214,23 @@
  */
 
 // Page-include extensions are the only two file types `@include` will pull in.
+/**
+ * Normalize CRLF/CR line endings to LF.
+ *
+ * Every line-structured parser in the project (frontmatter delimiters, the `.wd`
+ * directive dispatcher, `.skin` indentation) tests LF-shaped text. Source files
+ * authored on Windows — or checked out anywhere with git's `core.autocrlf`, the
+ * default on Windows — arrive CRLF-terminated, and an un-normalized `\r` turns
+ * `---` into `---\r` and silently defeats those tests. Applied at the reader
+ * boundary and again at the two entry points that accept raw strings from
+ * callers that bypass the reader; it is idempotent, so doubling up is free.
+ * @param {string} text
+ * @returns {string}
+ */
+export function normalizeNewlines(text) {
+  return text.includes("\r") ? text.replace(/\r\n?/g, "\n") : text;
+}
+
 export const pageIncludeExtensions = [".md", ".wd"];
 
 // Reserved per-row meta variables, mapped to their runtime marker token. Shared
@@ -257,7 +295,38 @@ 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` carrying a structured {@link WdErrorInfo} on `err.wd`
+ * — so an AI edit-loop (or an editor) gets code/file/line/hint/example without
+ * re-parsing the prose. The string message is the caller's text prefixed with
+ * the stable `[WDxxx]` code, so a user can search the code straight out of the
+ * terminal; everything after the prefix (the `file:line`, the corrective `Use:`
+ * template, the concrete `e.g.` example) is unchanged.
+ *
+ * Every author-facing compile error is built here, so no error can ship without
+ * a code. See `src/errors.js` for the registry and the numbering scheme.
+ * @param {string} message The user-facing error text, without the code prefix.
+ * @param {WdErrorInfo} wd The structured mirror (its `code` becomes the prefix).
+ * @returns {Error & { wd: WdErrorInfo }}
+ */
+export function wdError(message, wd) {
+  const err = /** @type {Error & { wd: WdErrorInfo }} */ (new Error(`[${wd.code}] ${message}`));
+  err.wd = wd;
+  return err;
 }
 
 /**

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,17 +38,33 @@ 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}`, {
+      code: "WD501",
+      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>} */
   const opts = {};
   for (const part of head[3].trim().split(/\s+/).filter(Boolean)) {
     const kv = part.match(/^([A-Za-z]+)=(.+)$/);
-    if (!kv) throw new Error(`Unknown :fetch option "${part}" in ${at(ctx, index)}. ${FETCH_USE}`);
+    if (!kv)
+      throw wdError(`Unknown :fetch option "${part}" in ${at(ctx, index)}. ${FETCH_USE}`, {
+        code: "WD502",
+        file: ctx.file,
+        line: lineOf(ctx, index)
+      });
     const optName = kv[1];
     if (!["method", "when", "timeout", "retry", "headers", "body", "refresh"].includes(optName)) {
-      throw new Error(`Unknown :fetch option "${optName}" in ${at(ctx, index)}. ${FETCH_USE}`);
+      throw wdError(`Unknown :fetch option "${optName}" in ${at(ctx, index)}. ${FETCH_USE}`, {
+        code: "WD502",
+        file: ctx.file,
+        line: lineOf(ctx, index)
+      });
     }
     opts[optName] = stripQuotes(kv[2]);
   }
@@ -55,17 +73,27 @@ export function handleFetch(line, ctx, index) {
     opts.method &&
     !["GET", "POST", "PUT", "PATCH", "DELETE"].includes(opts.method.toUpperCase())
   ) {
-    throw new Error(
-      `:fetch method "${opts.method}" is not allowed in ${at(ctx, index)}. ${FETCH_USE}`
+    throw wdError(
+      `:fetch method "${opts.method}" is not allowed in ${at(ctx, index)}. ${FETCH_USE}`,
+      {
+        code: "WD503",
+        file: ctx.file,
+        line: lineOf(ctx, index)
+      }
     );
   }
   if (opts.when && !["load", "visible"].includes(opts.when)) {
-    throw new Error(`:fetch when "${opts.when}" is not allowed in ${at(ctx, index)}. ${FETCH_USE}`);
+    throw wdError(`:fetch when "${opts.when}" is not allowed in ${at(ctx, index)}. ${FETCH_USE}`, {
+      code: "WD504",
+      file: ctx.file,
+      line: lineOf(ctx, index)
+    });
   }
   for (const n of ["timeout", "retry"]) {
     if (opts[n] !== undefined && !/^\d+$/.test(opts[n])) {
-      throw new Error(
-        `:fetch ${n} must be a non-negative integer in ${at(ctx, index)}. ${FETCH_USE}`
+      throw wdError(
+        `:fetch ${n} must be a non-negative integer in ${at(ctx, index)}. ${FETCH_USE}`,
+        { code: "WD505", file: ctx.file, line: lineOf(ctx, index) }
       );
     }
   }
@@ -73,8 +101,9 @@ export function handleFetch(line, ctx, index) {
     // Layer 2: a 401 triggers a token-refresh POST to this URL, then one retry.
     // The new token is written back into the `headers=` state, so it is required.
     if (!opts.headers) {
-      throw new Error(
-        `:fetch refresh= needs headers= (the state key holding the token to renew) in ${at(ctx, index)}. ${FETCH_USE}`
+      throw wdError(
+        `:fetch refresh= needs headers= (the state key holding the token to renew) in ${at(ctx, index)}. ${FETCH_USE}`,
+        { code: "WD506", file: ctx.file, line: lineOf(ctx, index) }
       );
     }
     opts.refresh = validateFetchUrl(opts.refresh, ctx, ":fetch refresh");
@@ -139,20 +168,23 @@ export function validateFetchUrl(url, ctx, what = ":fetch") {
   const value = url.trim();
   // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional — rejects control characters in URLs/hrefs.
   if (value !== url || value === "" || /[\u0000-\u001F\u007F]/.test(value)) {
-    throw new Error(
-      `Unsafe ${what} URL "${escapeHtml(url)}" in ${ctx.file}. Use a relative path (/, ./, ../), an http(s):// URL, or a { state } interpolation.`
+    throw wdError(
+      `Unsafe ${what} URL "${escapeHtml(url)}" in ${ctx.file}. Use a relative path (/, ./, ../), an http(s):// URL, or a { state } interpolation.`,
+      { code: "WD507", file: ctx.file }
     );
   }
   if (value.startsWith("//")) {
-    throw new Error(
-      `Unsafe ${what} URL "${escapeHtml(url)}" in ${ctx.file}. Protocol-relative URLs are not allowed; use http:// or https:// explicitly.`
+    throw wdError(
+      `Unsafe ${what} URL "${escapeHtml(url)}" in ${ctx.file}. Protocol-relative URLs are not allowed; use http:// or https:// explicitly.`,
+      { code: "WD508", file: ctx.file }
     );
   }
   if (value.startsWith("{")) return value; // interpolation-first; the runtime percent-encodes state values
   const scheme = value.match(/^([A-Za-z][A-Za-z0-9+.-]*):/);
   if (scheme && !["http", "https"].includes(scheme[1].toLowerCase())) {
-    throw new Error(
-      `Unsafe ${what} URL "${escapeHtml(url)}" in ${ctx.file}. The "${scheme[1]}:" scheme is not allowed; use http://, https://, or a relative path.`
+    throw wdError(
+      `Unsafe ${what} URL "${escapeHtml(url)}" in ${ctx.file}. The "${scheme[1]}:" scheme is not allowed; use http://, https://, or a relative path.`,
+      { code: "WD509", file: ctx.file }
     );
   }
   return value;

package/src/compiler/format.js

@@ -11,6 +11,8 @@
 // reads :state/:store emits `data-wd-fmt` and re-formats in the runtime.
 // ---------------------------------------------------------------------------
 
+import { wdError } from "./context.js";
+
 /**
  * @typedef {import("./context.js").Ctx} Ctx
  * @typedef {{ name: string, args: Array<string | number | boolean | null> }} Stage
@@ -221,8 +223,9 @@ export function validatePipes(inner, ctx) {
   const parsed = parsePipes(inner);
   for (const stage of parsed.stages) {
     if (!Object.hasOwn(FORMATTERS, stage.name)) {
-      throw new Error(
-        `Unknown formatter "${stage.name}" in { ${inner} } (${ctx.file}). Available: ${FORMATTER_NAMES.join(", ")}.`
+      throw wdError(
+        `Unknown formatter "${stage.name}" in { ${inner} } (${ctx.file}). Available: ${FORMATTER_NAMES.join(", ")}.`,
+        { code: "WD006", file: ctx.file }
       );
     }
   }