@zvndev/darkmown 2.1.0 → 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/context.js

@@ -152,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
@@ -257,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/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>} */

package/src/compiler/forms.js

@@ -9,7 +9,7 @@
 // while keeping the message text and `Use:` hints intact.
 // ---------------------------------------------------------------------------
 
-import { at, nestedCtx } from "./context.js";
+import { at, lineOf, nestedCtx, wdError } from "./context.js";
 import { validateFetchUrl } from "./fetch.js";
 import {
   escapeHtml,
@@ -25,6 +25,20 @@ import { declareErrorState, declareState } from "./state.js";
  * @typedef {import("./context.js").Ctx} Ctx
  */
 
+// Concrete, compilable one-liners for the form-family hint tails + the catalog.
+// (Field openers like :select/:checkbox expect following `- Label` lines; the
+// example is the opener, which the catalog/grammar pair with option lines.)
+export const FORM_EXAMPLE = ":form into contact";
+export const INPUT_EXAMPLE = ":input email type=email required";
+export const TEXTAREA_EXAMPLE = ':textarea message placeholder="Your message" rows=4';
+export const SELECT_EXAMPLE = ":select topic";
+export const CHECKBOX_EXAMPLE = ":checkbox toppings";
+export const RADIO_EXAMPLE = ":radio size";
+export const SUBMIT_EXAMPLE = ':submit "Send"';
+export const BIND_EXAMPLE = ':bind query placeholder="Search"';
+export const SLIDER_EXAMPLE = ":slider volume = 50 min=0 max=100 step=1";
+const INPUT_USE = `Use: :input name [type=…] [placeholder="…"] [required] — e.g. ${INPUT_EXAMPLE}`;
+
 /**
  * @param {string} line
  * @param {string[]} bodyLines
@@ -43,9 +57,13 @@ export function handleForm(line, bodyLines, ctx, index) {
     .replace(/(?:^|\s)into\s+[A-Za-z_$][\w$]*/, "")
     .trim();
   if ((!rawAction && !into) || leftover) {
-    throw new Error(
-      `Malformed :form in ${at(ctx, index)}: ${line}. Use ':form into name' (client state), ':form action="/url"' (native post), or both (fetch round-trip into state).`
-    );
+    const hint = `':form into name' (client state), ':form action="/url"' (native post), or both (fetch round-trip into state) — e.g. ${FORM_EXAMPLE}`;
+    throw wdError(`Malformed :form in ${at(ctx, index)}: ${line}. Use ${hint}`, {
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint,
+      example: FORM_EXAMPLE
+    });
   }
   const action = rawAction ? validateFetchUrl(rawAction, ctx, ":form action") : undefined;
   const inner = ctx.compileBody(bodyLines, nestedCtx(ctx, index + 1)).trim();
@@ -68,7 +86,13 @@ export function handleForm(line, bodyLines, ctx, index) {
  */
 export function handleInput(line, ctx, index) {
   const match = line.match(/^:input\s+([A-Za-z_][\w-]*)\s*(.*)$/);
-  if (!match) throw new Error(`Malformed :input in ${at(ctx, index)}: ${line}`);
+  if (!match)
+    throw wdError(`Malformed :input in ${at(ctx, index)}: ${line}. ${INPUT_USE}`, {
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint: INPUT_USE.slice("Use: ".length),
+      example: INPUT_EXAMPLE
+    });
   const attrs = [`name="${escapeHtml(match[1])}"`];
   let type = "text";
   let placeholder;
@@ -127,9 +151,12 @@ export function handleInput(line, ctx, index) {
 export function handleBind(line, ctx, index) {
   const match = line.match(/^:bind\s+([A-Za-z_$][\w$]*)\s*(.*)$/);
   if (!match)
-    throw new Error(
-      `Malformed :bind in ${at(ctx, index)}: ${line}. Use: :bind query placeholder="Search"`
-    );
+    throw wdError(`Malformed :bind in ${at(ctx, index)}: ${line}. Use: ${BIND_EXAMPLE}`, {
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint: BIND_EXAMPLE,
+      example: BIND_EXAMPLE
+    });
   const key = resolveStateKey(match[1], ctx);
   if (!key) {
     throw new Error(
@@ -187,9 +214,12 @@ export function handleBind(line, ctx, index) {
 export function handleSlider(line, ctx, index) {
   const head = line.match(/^:slider\s+([A-Za-z_$][\w$]*)\s*(.*)$/);
   if (!head)
-    throw new Error(
-      `Malformed :slider in ${at(ctx, index)}: ${line}. Use: :slider volume = 50 min=0 max=100 step=1`
-    );
+    throw wdError(`Malformed :slider in ${at(ctx, index)}: ${line}. Use: ${SLIDER_EXAMPLE}`, {
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint: SLIDER_EXAMPLE,
+      example: SLIDER_EXAMPLE
+    });
   const name = head[1];
   let rest = head[2].trim();
 
@@ -274,7 +304,15 @@ export function handleSlider(line, ctx, index) {
 export function handleSubmit(line, ctx, index) {
   const match = line.match(/^:submit\s+"([^"]+)"\s*$/);
   if (!match)
-    throw new Error(`Malformed :submit in ${at(ctx, index)}: ${line}. Use: :submit "Label"`);
+    throw wdError(
+      `Malformed :submit in ${at(ctx, index)}: ${line}. Use: :submit "Label" — e.g. ${SUBMIT_EXAMPLE}`,
+      {
+        file: ctx.file,
+        line: lineOf(ctx, index),
+        hint: `:submit "Label" — e.g. ${SUBMIT_EXAMPLE}`,
+        example: SUBMIT_EXAMPLE
+      }
+    );
   return `<button type="submit">${escapeHtml(match[1])}</button>`;
 }
 
@@ -290,10 +328,15 @@ export function handleSubmit(line, ctx, index) {
  */
 export function handleTextarea(line, ctx, index) {
   const match = line.match(/^:textarea\s+([A-Za-z_][\w-]*)\s*(.*)$/);
-  if (!match)
-    throw new Error(
-      `Malformed :textarea in ${at(ctx, index)}: ${line}. Use: :textarea name [placeholder="…"] [rows=N] [required]`
-    );
+  if (!match) {
+    const hint = `:textarea name [placeholder="…"] [rows=N] [required] — e.g. ${TEXTAREA_EXAMPLE}`;
+    throw wdError(`Malformed :textarea in ${at(ctx, index)}: ${line}. Use: ${hint}`, {
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint,
+      example: TEXTAREA_EXAMPLE
+    });
+  }
   const attrs = [`name="${escapeHtml(match[1])}"`];
   let placeholder;
   let hasAria = false;
@@ -343,10 +386,15 @@ export function handleTextarea(line, ctx, index) {
  */
 export function handleSelect(line, optionLines, ctx, index) {
   const match = line.match(/^:select\s+([A-Za-z_][\w-]*)\s*(.*)$/);
-  if (!match)
-    throw new Error(
-      `Malformed :select in ${at(ctx, index)}: ${line}. Use: :select name [required] then "- Label" lines`
-    );
+  if (!match) {
+    const hint = `:select name [required] then "- Label" lines — e.g. ${SELECT_EXAMPLE}`;
+    throw wdError(`Malformed :select in ${at(ctx, index)}: ${line}. Use: ${hint}`, {
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint,
+      example: SELECT_EXAMPLE
+    });
+  }
   const attrs = [`name="${escapeHtml(match[1])}"`];
   let hasAria = false;
   const re = /([A-Za-z-]+)=("[^"]*"|\S+)|([A-Za-z-]+)/g;
@@ -404,10 +452,16 @@ export function handleChoiceGroup(line, optionLines, ctx, kind, index) {
       ? /^:checkbox\s+([A-Za-z_][\w-]*)\s*(.*)$/
       : /^:radio\s+([A-Za-z_][\w-]*)\s*(.*)$/
   );
-  if (!match)
-    throw new Error(
-      `Malformed ${directive} in ${at(ctx, index)}: ${line}. Use: ${directive} name [required] then "- Label" lines`
-    );
+  if (!match) {
+    const example = kind === "checkbox" ? CHECKBOX_EXAMPLE : RADIO_EXAMPLE;
+    const hint = `${directive} name [required] then "- Label" lines — e.g. ${example}`;
+    throw wdError(`Malformed ${directive} in ${at(ctx, index)}: ${line}. Use: ${hint}`, {
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint,
+      example
+    });
+  }
   const name = match[1];
   const flags = [];
   let ariaLabel = null;

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:
@@ -219,7 +224,13 @@ 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}`, {
+      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]

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,14 @@ 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}`, {
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint,
+      example
+    });
   }
   const src = validateFetchUrl(stripQuotes(match[1]), ctx, `:${kind}`);
   const spec = MEDIA_SPEC[kind];
@@ -93,9 +103,13 @@ 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}`, {
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint,
+      example: EMBED_EXAMPLE
+    });
   }
   const raw = stripQuotes(match[1]);
   let title = "";

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,15 @@ 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}`, {
+      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;
@@ -189,7 +208,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);