@zvndev/darkmown 2.2.0 → 2.3.0

package/src/catalog.js

@@ -13,6 +13,10 @@
 // hints use, and the operator/formatter lists are read from the compiler's own
 // tables (FORMATTER_NAMES, PREDICATE_OPS, LOOP_META) — so the catalog cannot
 // drift from what actually compiles (drift-guarded in tests/catalog.test.js).
+//
+// The catalog also carries the stable compile-error codes (`errors`, from
+// src/errors.js): an AI edit-loop that hits `[WD201] …` can look the code up in
+// the same artifact it learned the syntax from, without parsing the prose.
 // ---------------------------------------------------------------------------
 
 import fs from "node:fs";
@@ -41,6 +45,7 @@ import {
   IF_EXAMPLE,
   INCLUDE_EXAMPLE
 } from "./compiler/structure.js";
+import { ERROR_AREAS, errorCatalog } from "./errors.js";
 
 /**
  * @typedef {"static" | "reactive" | "either"} Reactivity Whether the directive
@@ -77,6 +82,10 @@ import {
  * @property {CatalogEntry[]} formatPipes The `{ value | pipe }` formatter whitelist.
  * @property {CatalogEntry[]} predicateOps Comparison operators for `where`/`:if`/`when`.
  * @property {string[]} predicateJoiners Logical joiners (`and`/`or`/`not`).
+ * @property {import("./errors.js").ErrorArea[]} errorAreas The `WDxxx` code blocks.
+ * @property {import("./errors.js").ErrorEntry[]} errors Every stable compile-error
+ *   code, with its cause and fix. A thrown error's message starts with its code
+ *   (`[WD201] …`) and mirrors it on `err.wd.code`.
  */
 
 /** The directive surface. `example` is drawn from the compiler's own constants. */
@@ -512,7 +521,9 @@ export function directiveCatalog() {
       description: OP_DESC[op],
       example: op === "contains" ? 'p.tags contains "sale"' : `p.price ${op} 50`
     })),
-    predicateJoiners: [...PREDICATE_JOINERS]
+    predicateJoiners: [...PREDICATE_JOINERS],
+    errorAreas: ERROR_AREAS.map((area) => ({ ...area })),
+    errors: errorCatalog()
   };
 }
 
@@ -581,6 +592,10 @@ export function llmsText() {
   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(
+    "- 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."
+  );
   out.push("");
   return out.join("\n");
 }

package/src/compiler/actions.js

@@ -37,6 +37,7 @@ export function handleButton(line, ctx, index) {
   const match = line.match(/^:button\s+"([^"]+)"\s*->\s*(.+)$/);
   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),
@@ -74,6 +75,7 @@ export function handleEffect(line, 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}`, {
+      code: "WD302",
       file: ctx.file,
       line: lineOf(ctx, index),
       hint: EFFECT_USE.slice("Use: ".length),
@@ -82,8 +84,9 @@ export function handleEffect(line, ctx, index) {
   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(".");
@@ -122,6 +125,7 @@ export function handleEvery(line, ctx, index) {
   const match = line.match(/^:every\s+(\S+)\s*->\s*(.+)$/);
   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),
@@ -129,9 +133,11 @@ export function handleEvery(line, ctx, index) {
     });
   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);
@@ -176,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(".");
@@ -198,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 };
@@ -208,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.
@@ -235,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 };
@@ -277,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
+  });
 }
 
 /**
@@ -292,8 +308,9 @@ 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;
   }
@@ -302,6 +319,7 @@ function parseMergeOperand(raw, ctx) {
   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"
@@ -325,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

@@ -155,10 +155,17 @@
 /**
  * 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.
+ * 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} file Absolute path of the source file the error is in.
+ * @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).
@@ -207,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
@@ -286,16 +310,21 @@ export function lineOf(ctx, index) {
 }
 
 /**
- * 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.
+ * 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(message));
+  const err = /** @type {Error & { wd: WdErrorInfo }} */ (new Error(`[${wd.code}] ${message}`));
   err.wd = wd;
   return err;
 }

package/src/compiler/fetch.js

@@ -40,6 +40,7 @@ export function handleFetch(line, ctx, index) {
   const head = line.match(/^:fetch\s+([A-Za-z_$][\w$]*)\s+from\s+("[^"]+"|\S+)\s*(.*)$/);
   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),
@@ -51,10 +52,19 @@ export function handleFetch(line, ctx, index) {
   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]);
   }
@@ -63,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) }
       );
     }
   }
@@ -81,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");
@@ -147,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 }
       );
     }
   }