@zvndev/darkmown 2.1.0 → 2.3.0

package/src/compiler/loops.js

@@ -6,7 +6,7 @@
 // string fill used for the initial paint (text binds, per-row `:if`, meta).
 // ---------------------------------------------------------------------------
 
-import { at, createScope, nestedCtx } from "./context.js";
+import { at, createScope, lineOf, nestedCtx, wdError } from "./context.js";
 import { serializeExpr } from "./expr-ast.js";
 import { applyPipeline, stagesFromAttr } from "./format.js";
 import { resolveInclude } from "./includes.js";
@@ -28,9 +28,14 @@ import { compilePredicate, evalPredicate } from "./predicates.js";
  * @typedef {import("./context.js").LoopOpts} LoopOpts
  */
 
+// One concrete, compilable @loop line, appended to the schematic hint so a small
+// model copies a real line instead of echoing the `[…]` placeholders literally
+// (the on-device finding: bracket-placeholders get pasted into source verbatim).
+// Also the canonical @loop example the directive catalog + grammar draw from.
+export const LOOP_EXAMPLE = "@loop /products.json into p where p.price < 50 sort by p.price asc";
+
 // The fixed corrective suggestion shown for any malformed @loop header.
-const LOOP_USAGE =
-  "Use: @loop src into item [where …] [sort by …] [reverse] [offset N] [limit N] [paginate N] [sortable]";
+const LOOP_USAGE = `Use: @loop src into item [where …] [sort by …] [reverse] [offset N] [limit N] [paginate N] [sortable] — e.g. ${LOOP_EXAMPLE}`;
 
 /**
  * Parse the optional clause tail of a `@loop` header in FIXED order:
@@ -56,7 +61,10 @@ function parseLoopClauses(tail, itemName, ctx) {
   /** @type {number|null} */ let paginate = null;
   /** @returns {never} */
   const bad = () => {
-    throw new Error(`Malformed @loop clause in ${ctx.file}: "${tail.trim()}". ${LOOP_USAGE}`);
+    throw wdError(`Malformed @loop clause in ${ctx.file}: "${tail.trim()}". ${LOOP_USAGE}`, {
+      code: "WD102",
+      file: ctx.file
+    });
   };
 
   // `sortable` is a position-independent flag (drag-reorder); peel it wherever it
@@ -147,20 +155,25 @@ function parseSortClause(fieldTok, dirTok, itemName, ctx) {
   if (fieldState) {
     const resolved = resolveStateKey(fieldState[1], ctx);
     if (!resolved)
-      throw new Error(
-        `@loop sort by { ${fieldState[1]} } references unknown :state/:store in ${ctx.file}. ${LOOP_USAGE}`
+      throw wdError(
+        `@loop sort by { ${fieldState[1]} } references unknown :state/:store in ${ctx.file}. ${LOOP_USAGE}`,
+        { code: "WD103", file: ctx.file }
       );
     key = resolved;
     keyKind = "key";
   } else {
     const segs = fieldTok.split(".");
     if (segs[0] !== itemName)
-      throw new Error(
-        `@loop sort key "${fieldTok}" must start with the loop item "${itemName}" in ${ctx.file}. ${LOOP_USAGE}`
+      throw wdError(
+        `@loop sort key "${fieldTok}" must start with the loop item "${itemName}" in ${ctx.file}. ${LOOP_USAGE}`,
+        { code: "WD104", file: ctx.file }
       );
     const rest = segs.slice(1);
     if (rest.some((seg) => ["constructor", "prototype", "__proto__"].includes(seg)))
-      throw new Error(`Sort key "${fieldTok}" is not allowed in @loop (${ctx.file})`);
+      throw wdError(`Sort key "${fieldTok}" is not allowed in @loop (${ctx.file})`, {
+        code: "WD105",
+        file: ctx.file
+      });
     key = rest.join(".");
     keyKind = "literal";
   }
@@ -172,8 +185,9 @@ function parseSortClause(fieldTok, dirTok, itemName, ctx) {
     if (dirState) {
       const resolved = resolveStateKey(dirState[1], ctx);
       if (!resolved)
-        throw new Error(
-          `@loop sort direction { ${dirState[1]} } references unknown :state/:store in ${ctx.file}. ${LOOP_USAGE}`
+        throw wdError(
+          `@loop sort direction { ${dirState[1]} } references unknown :state/:store in ${ctx.file}. ${LOOP_USAGE}`,
+          { code: "WD106", file: ctx.file }
         );
       dir = resolved;
       dirKind = "key";
@@ -196,8 +210,9 @@ function parseNumArg(tok, ctx) {
   if (/^\d+$/.test(tok)) return { kind: "literal", value: Number(tok) };
   const key = resolveStateKey(tok, ctx);
   if (!key)
-    throw new Error(
-      `@loop offset/limit "${tok}" in ${ctx.file} is neither a non-negative integer nor a declared :state. ${LOOP_USAGE}`
+    throw wdError(
+      `@loop offset/limit "${tok}" in ${ctx.file} is neither a non-negative integer nor a declared :state. ${LOOP_USAGE}`,
+      { code: "WD107", file: ctx.file }
     );
   return { kind: "key", value: key };
 }
@@ -219,7 +234,14 @@ function numArgAttr(arg) {
  */
 export function handleLoop(line, bodyLines, emptyLines, ctx, index, emptyStart = 0) {
   const match = line.match(/^@loop\s+(.+?)\s+into\s+([A-Za-z_$][\w$]*)(\s+.+?)?\s*$/);
-  if (!match) throw new Error(`Malformed @loop in ${at(ctx, index)}: ${line}. ${LOOP_USAGE}`);
+  if (!match)
+    throw wdError(`Malformed @loop in ${at(ctx, index)}: ${line}. ${LOOP_USAGE}`, {
+      code: "WD101",
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint: LOOP_USAGE.slice("Use: ".length),
+      example: LOOP_EXAMPLE
+    });
   const source = stripQuotes(match[1].trim());
   const itemName = match[2];
   const clauses = match[3]
@@ -247,16 +269,18 @@ export function handleLoop(line, bodyLines, emptyLines, ctx, index, emptyStart =
       clauses.limit ||
       clauses.paginate)
   ) {
-    throw new Error(
-      `@loop sortable cannot combine with where/sort/reverse/offset/limit/paginate in ${ctx.file}. ${LOOP_USAGE}`
+    throw wdError(
+      `@loop sortable cannot combine with where/sort/reverse/offset/limit/paginate in ${ctx.file}. ${LOOP_USAGE}`,
+      { code: "WD108", file: ctx.file }
     );
   }
   // `paginate N` OWNS the page slice, so an explicit offset/limit alongside it is
   // a conflict (which one wins?). Reject it with a clear hint rather than silently
   // letting one override the other.
   if (clauses.paginate && (clauses.offset || clauses.limit)) {
-    throw new Error(
-      `@loop paginate cannot combine with offset/limit in ${ctx.file} — paginate already slices each page. ${LOOP_USAGE}`
+    throw wdError(
+      `@loop paginate cannot combine with offset/limit in ${ctx.file} — paginate already slices each page. ${LOOP_USAGE}`,
+      { code: "WD109", file: ctx.file }
     );
   }
   /** @type {LoopOpts} */
@@ -287,7 +311,7 @@ export function handleLoop(line, bodyLines, emptyLines, ctx, index, emptyStart =
     source.startsWith("../") ||
     source.endsWith(".json")
   ) {
-    if (opts.paginate) throw new Error(paginateOnlyCollections(ctx));
+    if (opts.paginate) throw paginateOnlyCollections(ctx);
     const dataFile = resolveInclude(
       source,
       ctx.file,
@@ -298,23 +322,28 @@ export function handleLoop(line, bodyLines, emptyLines, ctx, index, emptyStart =
     );
     ctx.comp.deps.add(dataFile);
     const rows = JSON.parse(ctx.comp.reader.readText(dataFile));
-    if (!Array.isArray(rows)) throw new Error(`@loop data must be a JSON array: ${dataFile}`);
+    if (!Array.isArray(rows))
+      throw wdError(`@loop data must be a JSON array: ${dataFile}`, {
+        code: "WD111",
+        file: ctx.file
+      });
     return loopOverData(rows, itemName, bodyLines, bodyCtx, opts);
   }
 
   const resolved = lookupPath(source, ctx);
   if (resolved.found) {
-    if (opts.paginate) throw new Error(paginateOnlyCollections(ctx));
+    if (opts.paginate) throw paginateOnlyCollections(ctx);
     // A missing/unset field (e.g. an optional frontmatter key) is an EMPTY
     // list, not an error — the `@empty` branch renders, matching the runtime.
     if (resolved.value === null || resolved.value === undefined) {
       return loopOverData([], itemName, bodyLines, bodyCtx, opts);
     }
     if (!Array.isArray(resolved.value)) {
-      throw new Error(
+      throw wdError(
         `@loop ${source} in ${at(ctx, index)} found an in-scope value, but it is not a list ` +
           `(got ${typeof resolved.value}). Use: a list value (e.g. \`tags: [a, b]\` in frontmatter) — ` +
-          `or leave the field out entirely, which loops zero rows and renders the @empty branch.`
+          `or leave the field out entirely, which loops zero rows and renders the @empty branch.`,
+        { code: "WD112", file: ctx.file, line: lineOf(ctx, index) }
       );
     }
     return loopOverData(resolved.value, itemName, bodyLines, bodyCtx, opts);
@@ -324,11 +353,14 @@ export function handleLoop(line, bodyLines, emptyLines, ctx, index, emptyStart =
   const segs = source.split(".");
   if (/^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/.test(source)) {
     if (segs.some((seg) => ["constructor", "prototype", "__proto__"].includes(seg))) {
-      throw new Error(`@loop source "${source}" is not allowed in ${ctx.file}`);
+      throw wdError(`@loop source "${source}" is not allowed in ${ctx.file}`, {
+        code: "WD113",
+        file: ctx.file
+      });
     }
     const key = resolveStateKey(segs[0], ctx);
     if (key) {
-      if (opts.paginate) throw new Error(paginateOnlyCollections(ctx));
+      if (opts.paginate) throw paginateOnlyCollections(ctx);
       const fullKey = segs.length > 1 ? `${key}.${segs.slice(1).join(".")}` : key;
       return reactiveLoop(fullKey, itemName, bodyLines, bodyCtx, opts);
     }
@@ -344,16 +376,17 @@ export function handleLoop(line, bodyLines, emptyLines, ctx, index, emptyStart =
     // the enclosing row item — an ITEM-RELATIVE loop the runtime fills per row.
     if (ctx.loopItem && segs[0] === ctx.loopItem && segs.length > 1) {
       if (opts.sortable) {
-        throw new Error(
-          `@loop sortable is not supported on a nested (item-relative) loop in ${ctx.file}. ${LOOP_USAGE}`
+        throw wdError(
+          `@loop sortable is not supported on a nested (item-relative) loop in ${ctx.file}. ${LOOP_USAGE}`,
+          { code: "WD114", file: ctx.file }
         );
       }
-      if (opts.paginate) throw new Error(paginateOnlyCollections(ctx));
+      if (opts.paginate) throw paginateOnlyCollections(ctx);
       return itemRelativeLoop(segs.slice(1).join("."), itemName, bodyLines, bodyCtx, opts);
     }
   }
 
-  throw new Error(unresolvedSourceError(source, ctx));
+  throw unresolvedSourceError(source, ctx);
 }
 
 /**
@@ -362,15 +395,16 @@ export function handleLoop(line, bodyLines, emptyLines, ctx, index, emptyStart =
  * collection reference is immediately actionable.
  * @param {string} source
  * @param {Ctx} ctx
- * @returns {string}
+ * @returns {Error}
  */
 function unresolvedSourceError(source, ctx) {
   const names = [...ctx.comp.collections.keys()].sort();
   const collectionsHint = names.length ? ` Available collections: ${names.join(", ")}.` : "";
-  return (
+  return wdError(
     `@loop source "${source}" in ${ctx.file} was not found. Loop over a collection ` +
-    `(a site/pages/<name>/ subdirectory, by its bare name), a JSON file ` +
-    `(@loop /data.json into row), an in-scope value, or a :state list.${collectionsHint}`
+      `(a site/pages/<name>/ subdirectory, by its bare name), a JSON file ` +
+      `(@loop /data.json into row), an in-scope value, or a :state list.${collectionsHint}`,
+    { code: "WD115", file: ctx.file }
   );
 }
 
@@ -378,10 +412,13 @@ function unresolvedSourceError(source, ctx) {
  * The error for `paginate` on a non-collection source: pagination multiplies
  * static routes, which only makes sense for a build-time collection listing.
  * @param {Ctx} ctx
- * @returns {string}
+ * @returns {Error}
  */
 function paginateOnlyCollections(ctx) {
-  return `@loop paginate requires a collection source (a site/pages/<name>/ subdirectory) in ${ctx.file}. ${LOOP_USAGE}`;
+  return wdError(
+    `@loop paginate requires a collection source (a site/pages/<name>/ subdirectory) in ${ctx.file}. ${LOOP_USAGE}`,
+    { code: "WD110", file: ctx.file }
+  );
 }
 
 /**
@@ -399,9 +436,10 @@ function paginateOnlyCollections(ctx) {
 function assertReactiveDepth(ctx) {
   if ((ctx.reactiveDepth ?? 0) < 2) return;
   const opener = ctx.loopOpener ?? { at: ctx.file, line: "" };
-  throw new Error(
+  throw wdError(
     `Reactive @loop nesting is limited to one inner level in ${opener.at}: "${opener.line}". ` +
-      `Unroll the outer data at build time (JSON/frontmatter source) or move the innermost list into build-time data.`
+      `Unroll the outer data at build time (JSON/frontmatter source) or move the innermost list into build-time data.`,
+    { code: "WD116", file: ctx.file }
   );
 }
 
@@ -511,8 +549,9 @@ function pipelineRows(rows, where, opts, ctx) {
  */
 function loopOverData(rows, itemName, bodyLines, ctx, opts) {
   if (opts.sortable) {
-    throw new Error(
-      `@loop sortable requires a :state or :store list to reorder, not a JSON file or in-scope value, in ${ctx.file}. ${LOOP_USAGE}`
+    throw wdError(
+      `@loop sortable requires a :state or :store list to reorder, not a JSON file or in-scope value, in ${ctx.file}. ${LOOP_USAGE}`,
+      { code: "WD117", file: ctx.file }
     );
   }
   // Reactive when the where reads state OR an offset/limit references a state key.

package/src/compiler/markdown.js

@@ -7,7 +7,7 @@
 
 import MarkdownIt from "markdown-it";
 import { highlightCode } from "../highlight.js";
-import { LOOP_META } from "./context.js";
+import { LOOP_META, wdError } from "./context.js";
 import { applyPipeline, fmtAttr, validatePipes } from "./format.js";
 import {
   escapeHtml,
@@ -266,8 +266,9 @@ function resolveBindingHtml(expr, ctx) {
   // Per-row meta vars ($index/$number/$first/$last/$count) — only inside a loop.
   if (LOOP_META[head]) {
     if (!ctx.loopMeta)
-      throw new Error(
-        `"{ ${expr} }" uses the loop meta variable "${head}" outside a @loop in ${ctx.file}. Move it into a loop body, or rename your value.`
+      throw wdError(
+        `"{ ${expr} }" uses the loop meta variable "${head}" outside a @loop in ${ctx.file}. Move it into a loop body, or rename your value.`,
+        { code: "WD005", file: ctx.file }
       );
     if (ctx.loopItem) return `<span data-wd-each-meta="${LOOP_META[head]}"${fmt}></span>`; // reactive: filled per row
     // static: the value is in scope (injected by staticUnroll); fall through.

package/src/compiler/media.js

@@ -8,7 +8,7 @@
 // while keeping the message text and `Use:` hints intact.
 // ---------------------------------------------------------------------------
 
-import { at } from "./context.js";
+import { at, lineOf, wdError } from "./context.js";
 import { validateFetchUrl } from "./fetch.js";
 import { escapeHtml, stripQuotes } from "./interpolation.js";
 
@@ -16,6 +16,11 @@ import { escapeHtml, stripQuotes } from "./interpolation.js";
  * @typedef {import("./context.js").Ctx} Ctx
  */
 
+// Concrete, compilable media examples for the hint tails + the directive catalog.
+export const VIDEO_EXAMPLE = ":video /demo.mp4 controls";
+export const AUDIO_EXAMPLE = ":audio /theme.mp3 controls";
+export const EMBED_EXAMPLE = ':embed https://youtu.be/dQw4w9WgXcQ title="Demo"';
+
 /** @type {Record<"video" | "audio", { flags: string[], attrs: string[] }>} */
 const MEDIA_SPEC = {
   video: {
@@ -41,9 +46,15 @@ const MEDIA_SPEC = {
 export function handleMedia(line, kind, ctx, index) {
   const match = line.match(new RegExp(`^:${kind}\\s+(\\S+)\\s*(.*)$`));
   if (!match) {
-    throw new Error(
-      `Malformed :${kind} in ${at(ctx, index)}: ${line}. Use: :${kind} /clip [controls] [autoplay] [loop] [muted]`
-    );
+    const example = kind === "video" ? VIDEO_EXAMPLE : AUDIO_EXAMPLE;
+    const hint = `:${kind} /clip [controls] [autoplay] [loop] [muted] — e.g. ${example}`;
+    throw wdError(`Malformed :${kind} in ${at(ctx, index)}: ${line}. Use: ${hint}`, {
+      code: "WD701",
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint,
+      example
+    });
   }
   const src = validateFetchUrl(stripQuotes(match[1]), ctx, `:${kind}`);
   const spec = MEDIA_SPEC[kind];
@@ -55,11 +66,19 @@ export function handleMedia(line, kind, ctx, index) {
   for (const token of (match[2] || "").matchAll(re)) {
     if (token[3]) {
       if (!spec.flags.includes(token[3]))
-        throw new Error(`Unknown :${kind} flag "${token[3]}" in ${at(ctx, index)}`);
+        throw wdError(`Unknown :${kind} flag "${token[3]}" in ${at(ctx, index)}`, {
+          code: "WD702",
+          file: ctx.file,
+          line: lineOf(ctx, index)
+        });
       flags.add(token[3]);
     } else {
       if (!spec.attrs.includes(token[1]))
-        throw new Error(`Unknown :${kind} attribute "${token[1]}" in ${at(ctx, index)}`);
+        throw wdError(`Unknown :${kind} attribute "${token[1]}" in ${at(ctx, index)}`, {
+          code: "WD703",
+          file: ctx.file,
+          line: lineOf(ctx, index)
+        });
       attrs.set(token[1], stripQuotes(token[2]));
     }
   }
@@ -93,16 +112,25 @@ export function handleMedia(line, kind, ctx, index) {
 export function handleEmbed(line, ctx, index) {
   const match = line.match(/^:embed\s+(\S+)\s*(.*)$/);
   if (!match) {
-    throw new Error(
-      `Malformed :embed in ${at(ctx, index)}: ${line}. Use: :embed https://youtu.be/ID [title="…"]`
-    );
+    const hint = `:embed https://youtu.be/ID [title="…"] — e.g. ${EMBED_EXAMPLE}`;
+    throw wdError(`Malformed :embed in ${at(ctx, index)}: ${line}. Use: ${hint}`, {
+      code: "WD704",
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint,
+      example: EMBED_EXAMPLE
+    });
   }
   const raw = stripQuotes(match[1]);
   let title = "";
   const re = /([A-Za-z-]+)=("[^"]*"|\S+)/g;
   for (const token of (match[2] || "").matchAll(re)) {
     if (token[1] !== "title")
-      throw new Error(`Unknown :embed attribute "${token[1]}" in ${at(ctx, index)}`);
+      throw wdError(`Unknown :embed attribute "${token[1]}" in ${at(ctx, index)}`, {
+        code: "WD705",
+        file: ctx.file,
+        line: lineOf(ctx, index)
+      });
     title = stripQuotes(token[2]);
   }
   const { url, label } = resolveEmbed(raw, ctx);

package/src/compiler/page.js

@@ -6,12 +6,12 @@
 // ---------------------------------------------------------------------------
 
 import path from "node:path";
-import { imageSize } from "image-size";
 import { createPaths } from "../config.js";
 import { htmlHasHighlight } from "../highlight.js";
 import { compileBody } from "./body.js";
-import { createCompilation, createScope } from "./context.js";
+import { createCompilation, createScope, wdError } from "./context.js";
 import { parseFrontmatter, warnLikelyFrontmatter } from "./frontmatter.js";
+import { imageSize } from "./image-size.js";
 import {
   collectColocatedAssets,
   scanMarkdownHints,
@@ -279,8 +279,9 @@ function measureImage(src, paths, reader) {
     return null; // page-relative: the source directory is lost after assembly
   }
   try {
-    const { width, height } = imageSize(reader.readBinary(filePath));
-    if (typeof width === "number" && typeof height === "number") return { width, height };
+    // `imageSize` itself never throws (an unsupported or malformed image is just
+    // null); the try/catch is for the read, which does throw on a missing file.
+    return imageSize(reader.readBinary(filePath));
   } catch {
     /* missing or unreadable — degrade to no dimensions */
   }
@@ -363,8 +364,9 @@ export function compileFile(
 ) {
   const real = comp.reader.realpath(file);
   if (stack.includes(real)) {
-    throw new Error(
-      `Include cycle detected: ${[...stack, real].map((p) => path.basename(p)).join(" -> ")}`
+    throw wdError(
+      `[WD612] Include cycle detected: ${[...stack, real].map((p) => path.basename(p)).join(" -> ")}`,
+      { code: "WD612", file }
     );
   }
 

package/src/compiler/predicates.js

@@ -5,6 +5,7 @@
 // readers — no identifier survives un-mapped, so no raw user content is eval'd.
 // ---------------------------------------------------------------------------
 
+import { wdError } from "./context.js";
 import { astOf, evalAst } from "./expr-ast.js";
 import { getPath, lookupVar, resolveStateKey } from "./interpolation.js";
 
@@ -13,6 +14,20 @@ import { getPath, lookupVar, resolveStateKey } from "./interpolation.js";
  * @typedef {import("./context.js").Predicate} Predicate
  */
 
+// The comparison operators a `where` / `.class when` / `:if` / `:computed`
+// condition may use, longest-match first so `>=` wins over `>`. The single
+// source of truth: the operator regex is built from this list, and the directive
+// catalog + GBNF grammar enumerate the same array (drift-guarded in tests).
+export const PREDICATE_OPS = ["contains", "==", "!=", ">=", "<=", ">", "<"];
+
+// The logical joiners between conditions (`and`/`or`), plus a leading `not` the
+// `.class when` / `:if` paths accept. Catalogued alongside the operators.
+export const PREDICATE_JOINERS = ["and", "or", "not"];
+
+// `left <op> right` where <op> is one of PREDICATE_OPS. Built from the array so
+// adding an operator in one place updates the parser and the catalog together.
+const CONDITION_RE = new RegExp(`^(.+?)\\s+(${PREDICATE_OPS.join("|")})\\s+(.+)$`, "i");
+
 // Compile a `where` predicate to a safe JS boolean expression over I()/S()/C().
 // Conditions (operand <op> operand) join with `and`/`or`; operands are loop-item
 // paths, declared :state, numbers, or strings. No identifiers survive un-mapped.
@@ -46,11 +61,16 @@ export function compilePredicate(raw, itemName, ctx) {
  * @returns {{ expr: string, usesState: boolean }}
  */
 function compileCondition(cond, itemName, ctx) {
-  const m = cond.match(/^(.+?)\s+(contains|==|!=|>=|<=|>|<)\s+(.+)$/i);
-  if (!m)
-    throw new Error(
-      `Malformed where-condition "${cond}" in ${ctx.file}. Use: ${itemName}.field contains state, or ${itemName}.field <op> value.`
-    );
+  const m = cond.match(CONDITION_RE);
+  if (!m) {
+    const hint = `${itemName}.field contains state, or ${itemName}.field <op> value — e.g. ${itemName}.price < 50`;
+    throw wdError(`Malformed where-condition "${cond}" in ${ctx.file}. Use: ${hint}`, {
+      code: "WD220",
+      file: ctx.file,
+      hint,
+      example: `${itemName}.price < 50`
+    });
+  }
   const left = compileOperand(m[1].trim(), itemName, ctx);
   const right = compileOperand(m[3].trim(), itemName, ctx);
   const usesState = left.usesState || right.usesState;
@@ -71,20 +91,25 @@ function compileOperand(tok, itemName, ctx) {
   if (/^-?\d+(?:\.\d+)?$/.test(tok)) return { code: tok, usesState: false };
   if (["true", "false", "null"].includes(tok)) return { code: tok, usesState: false };
   if (!/^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/.test(tok)) {
-    throw new Error(
-      `Unsupported operand "${tok}" in @loop where (${ctx.file}). Use ${itemName}.field, a :state name, a number, or a "string".`
+    throw wdError(
+      `Unsupported operand "${tok}" in @loop where (${ctx.file}). Use ${itemName}.field, a :state name, a number, or a "string".`,
+      { code: "WD221", file: ctx.file }
     );
   }
   const segs = tok.split(".");
   if (segs.some((seg) => ["constructor", "prototype", "__proto__"].includes(seg))) {
-    throw new Error(`Path "${tok}" is not allowed in @loop where (${ctx.file})`);
+    throw wdError(`Path "${tok}" is not allowed in @loop where (${ctx.file})`, {
+      code: "WD222",
+      file: ctx.file
+    });
   }
   if (segs[0] === itemName)
     return { code: `I(${JSON.stringify(segs.slice(1).join("."))})`, usesState: false };
   const key = resolveStateKey(segs[0], ctx);
   if (!key) {
-    throw new Error(
-      `@loop where references unknown name "${segs[0]}" in ${ctx.file}. Use the loop item (${itemName}.field) or a declared :state.`
+    throw wdError(
+      `@loop where references unknown name "${segs[0]}" in ${ctx.file}. Use the loop item (${itemName}.field) or a declared :state.`,
+      { code: "WD223", file: ctx.file }
     );
   }
   const rest = segs.slice(1).join(".");
@@ -130,13 +155,17 @@ function compileWhenOperand(tok, ctx, what) {
   if (/^-?\d+(?:\.\d+)?$/.test(tok)) return { code: tok, state: false, item: false };
   if (["true", "false", "null"].includes(tok)) return { code: tok, state: false, item: false };
   if (!/^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/.test(tok)) {
-    throw new Error(
-      `Unsupported operand "${tok}" in ${what} (${ctx.file}). Use item.field, a :state name, a number, or a "string".`
+    throw wdError(
+      `Unsupported operand "${tok}" in ${what} (${ctx.file}). Use item.field, a :state name, a number, or a "string".`,
+      { code: "WD224", file: ctx.file }
     );
   }
   const segs = tok.split(".");
   if (segs.some((seg) => ["constructor", "prototype", "__proto__"].includes(seg))) {
-    throw new Error(`Path "${tok}" is not allowed in ${what} (${ctx.file})`);
+    throw wdError(`Path "${tok}" is not allowed in ${what} (${ctx.file})`, {
+      code: "WD225",
+      file: ctx.file
+    });
   }
   const scoped = lookupVar(ctx.scope, segs[0]);
   if (scoped.found)
@@ -149,8 +178,9 @@ function compileWhenOperand(tok, ctx, what) {
     return { code: `I(${JSON.stringify(segs.slice(1).join("."))})`, state: false, item: true };
   const key = resolveStateKey(segs[0], ctx);
   if (!key)
-    throw new Error(
-      `${what} references unknown name "${segs[0]}" in ${ctx.file}. Use a loop item field, a declared :state, a number, or a "string".`
+    throw wdError(
+      `${what} references unknown name "${segs[0]}" in ${ctx.file}. Use a loop item field, a declared :state, a number, or a "string".`,
+      { code: "WD226", file: ctx.file }
     );
   const rest = segs.slice(1).join(".");
   return {
@@ -189,7 +219,7 @@ export function compileWhen(raw, ctx, what = '"::: … when"') {
       negate = true;
       seg = seg.replace(/^not\s+/i, "").trim();
     }
-    const opMatch = seg.match(/^(.+?)\s+(contains|==|!=|>=|<=|>|<)\s+(.+)$/i);
+    const opMatch = seg.match(CONDITION_RE);
     let expr;
     if (opMatch) {
       const left = compileWhenOperand(opMatch[1].trim(), ctx, what);
@@ -243,12 +273,16 @@ export function compileComputedExpr(raw, ctx) {
           ["constructor", "prototype", "__proto__"].includes(s)
         )
       ) {
-        throw new Error(`Path "${listPath}" is not allowed in :computed ${name}() (${ctx.file})`);
+        throw wdError(`Path "${listPath}" is not allowed in :computed ${name}() (${ctx.file})`, {
+          code: "WD227",
+          file: ctx.file
+        });
       }
       const key = resolveStateKey(segs[0], ctx);
       if (!key) {
-        throw new Error(
-          `:computed ${name}() references unknown state "${segs[0]}" in ${ctx.file}. Declare it with :state or :fetch first.`
+        throw wdError(
+          `:computed ${name}() references unknown state "${segs[0]}" in ${ctx.file}. Declare it with :state or :fetch first.`,
+          { code: "WD228", file: ctx.file }
         );
       }
       const rest = segs.slice(1).join(".");
@@ -260,15 +294,22 @@ export function compileComputedExpr(raw, ctx) {
     }
   );
   if (/["'\\`]/.test(expr)) {
-    throw new Error(`Unsupported string syntax in :computed expression "${raw}" (${ctx.file})`);
+    throw wdError(`Unsupported string syntax in :computed expression "${raw}" (${ctx.file})`, {
+      code: "WD229",
+      file: ctx.file
+    });
   }
   if (!/^[\w$.\s+\-*/%()<>=!&|]*$/.test(expr)) {
-    throw new Error(
-      `Unsupported syntax in :computed expression "${raw}" (${ctx.file}). Allowed: state names, numbers, strings, + - * / % ( ), comparisons, && || !.`
+    throw wdError(
+      `Unsupported syntax in :computed expression "${raw}" (${ctx.file}). Allowed: state names, numbers, strings, + - * / % ( ), comparisons, && || !.`,
+      { code: "WD230", file: ctx.file }
     );
   }
   if (/(^|[^=!<>])=(?!=)/.test(expr)) {
-    throw new Error(`Assignment is not allowed in :computed expressions ("${raw}" in ${ctx.file})`);
+    throw wdError(`Assignment is not allowed in :computed expressions ("${raw}" in ${ctx.file})`, {
+      code: "WD231",
+      file: ctx.file
+    });
   }
   // Reject function-call syntax: a `(` that directly follows an identifier, a
   // string literal, or a closing `)` (e.g. `x()`, `x.valueOf()`, `(a)(b)`). Only
@@ -278,8 +319,9 @@ export function compileComputedExpr(raw, ctx) {
   // SECURITY.md guarantee that function calls are compile errors. Runs BEFORE the
   // identifier→S() mapping so it never trips on the emitted helper calls.
   if (/[\w$)]\s*\(/.test(expr)) {
-    throw new Error(
-      `Function calls are not allowed in :computed expressions ("${raw}" in ${ctx.file})`
+    throw wdError(
+      `Function calls are not allowed in :computed expressions ("${raw}" in ${ctx.file})`,
+      { code: "WD232", file: ctx.file }
     );
   }
   expr = expr.replace(/[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*/g, (ref) => {
@@ -287,14 +329,16 @@ export function compileComputedExpr(raw, ctx) {
     if (["true", "false", "null"].includes(ref)) return ref;
     const segs = ref.split(".");
     if (segs.some((seg) => ["constructor", "prototype", "__proto__"].includes(seg))) {
-      throw new Error(
-        `Path segment "${ref}" is not allowed in :computed expressions (${ctx.file})`
-      );
+      throw wdError(`Path segment "${ref}" is not allowed in :computed expressions (${ctx.file})`, {
+        code: "WD233",
+        file: ctx.file
+      });
     }
     const key = resolveStateKey(segs[0], ctx);
     if (!key) {
-      throw new Error(
-        `:computed references unknown state "${segs[0]}" in ${ctx.file}. Declare it with :state or :fetch first.`
+      throw wdError(
+        `:computed references unknown state "${segs[0]}" in ${ctx.file}. Declare it with :state or :fetch first.`,
+        { code: "WD234", file: ctx.file }
       );
     }
     const rest = segs.slice(1).join(".");