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

package/src/compiler/includes.js

@@ -7,7 +7,7 @@
 
 import path from "node:path";
 import { scopeIdFor } from "../skin.js";
-import { pageIncludeExtensions } from "./context.js";
+import { pageIncludeExtensions, wdError } from "./context.js";
 import { stripQuotes } from "./interpolation.js";
 
 /**
@@ -181,14 +181,18 @@ export function resolveInclude(spec, fromFile, context, allowAny, loc, reader) {
   for (const candidate of candidates) {
     const resolved = path.resolve(candidate);
     if (!isAllowedInclude(resolved, context)) {
-      throw new Error(`Include "${spec}" from ${loc} resolves outside site/pages or site/_`);
+      throw wdError(`Include "${spec}" from ${loc} resolves outside site/pages or site/_`, {
+        code: "WD601",
+        file: fromFile
+      });
     }
     if (!reader.exists(resolved)) continue;
     if (!allowAny && !pageIncludeExtensions.includes(path.extname(resolved))) continue;
     return resolved;
   }
-  throw new Error(
-    `Could not resolve include "${spec}" from ${loc}. Looked in site/pages and site/_ — check the path and leading slash.`
+  throw wdError(
+    `Could not resolve include "${spec}" from ${loc}. Looked in site/pages and site/_ — check the path and leading slash.`,
+    { code: "WD602", file: fromFile }
   );
 }
 

package/src/compiler/interpolation.js

@@ -1,10 +1,12 @@
 // ---------------------------------------------------------------------------
 // Interpolation primitives: path/value resolution, state-key lookup, scalar
 // parsing, and HTML escaping. These are the leaf utilities the directive
-// handlers, loops, predicates, and markdown layer all build on — this module
-// imports only the shared typedefs, so it sits near the root of the DAG.
+// handlers, loops, predicates, and markdown layer all build on — it imports
+// only `context.js` (which imports nothing), so it sits at the root of the DAG.
 // ---------------------------------------------------------------------------
 
+import { wdError } from "./context.js";
+
 /**
  * @typedef {import("./context.js").Scope} Scope
  * @typedef {import("./context.js").Ctx} Ctx
@@ -66,7 +68,11 @@ export function getPath(value, segments) {
 export function validatePath(path, ctx, use) {
   const segs = path.split(".");
   if (segs.some((seg) => ["constructor", "prototype", "__proto__"].includes(seg))) {
-    throw new Error(`Path segment in "${path}" is not allowed in ${ctx.file}. Use: ${use}`);
+    throw wdError(`Path segment in "${path}" is not allowed in ${ctx.file}. Use: ${use}`, {
+      code: "WD002",
+      file: ctx.file,
+      hint: use
+    });
   }
   return segs;
 }
@@ -98,8 +104,9 @@ export function interpolateLeaf(value, expr, ctx) {
   if (value === null || value === undefined) return "";
   if (Array.isArray(value)) return value.join(", ");
   if (typeof value === "object") {
-    throw new Error(
-      `Cannot interpolate the object value "{ ${expr} }" in ${ctx.file}. Interpolate a field instead — e.g. { ${expr}.title } — or iterate it with @loop ${expr} into item.`
+    throw wdError(
+      `Cannot interpolate the object value "{ ${expr} }" in ${ctx.file}. Interpolate a field instead — e.g. { ${expr}.title } — or iterate it with @loop ${expr} into item.`,
+      { code: "WD003", file: ctx.file }
     );
   }
   return String(value);
@@ -143,11 +150,12 @@ export function parseStateValue(raw, where) {
       const open = value[0];
       const close = open === "[" ? "]" : "}";
       const shown = value.length > 60 ? `${value.slice(0, 57)}…` : value;
-      throw new Error(
+      throw wdError(
         `Unbalanced JSON value "${shown}"${where ? ` in ${where}` : ""}: this opens "${open}" but ` +
           `never closes it. :state/:store/:theme accept a multi-line array/object, but the literal ` +
           `must balance (a "${close}" is missing) with no blank lines inside it. ` +
-          `Quote it for literal bracket text (e.g. = "[draft]").`
+          `Quote it for literal bracket text (e.g. = "[draft]").`,
+        { code: "WD004" }
       );
     }
     return value;

package/src/compiler/loops.js

@@ -61,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
@@ -152,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";
   }
@@ -177,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";
@@ -201,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 };
 }
@@ -226,6 +236,7 @@ export function handleLoop(line, bodyLines, emptyLines, ctx, index, emptyStart =
   const match = line.match(/^@loop\s+(.+?)\s+into\s+([A-Za-z_$][\w$]*)(\s+.+?)?\s*$/);
   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),
@@ -258,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} */
@@ -298,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,
@@ -309,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);
@@ -335,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);
     }
@@ -355,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);
 }
 
 /**
@@ -373,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 }
   );
 }
 
@@ -389,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 }
+  );
 }
 
 /**
@@ -410,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 }
   );
 }
 
@@ -522,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

@@ -49,6 +49,7 @@ export function handleMedia(line, kind, ctx, index) {
     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,
@@ -65,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]));
     }
   }
@@ -105,6 +114,7 @@ export function handleEmbed(line, ctx, index) {
   if (!match) {
     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,
@@ -116,7 +126,11 @@ export function handleEmbed(line, ctx, index) {
   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

@@ -65,6 +65,7 @@ function compileCondition(cond, itemName, ctx) {
   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`
@@ -90,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(".");
@@ -149,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)
@@ -168,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 {
@@ -262,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(".");
@@ -279,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
@@ -297,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) => {
@@ -306,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(".");

package/src/compiler/reader.js

@@ -13,13 +13,18 @@
 // ---------------------------------------------------------------------------
 
 import path from "node:path";
+import { normalizeNewlines } from "./context.js";
 
 /**
  * The narrow filesystem surface the compiler needs. Every method takes an
  * ABSOLUTE path (the compiler resolves includes/assets to absolute paths before
  * reading), so a reader only has to map absolute paths to bytes/existence.
  * @typedef {object} Reader
- * @property {(absPath: string) => string} readText Read a UTF-8 text file.
+ * @property {(absPath: string) => string} readText Read a UTF-8 text file. The
+ *   result is ALWAYS LF-normalized: every parser downstream is line-structured
+ *   and LF-shaped, so a CRLF source (Windows, or any `core.autocrlf` checkout)
+ *   would otherwise fail to match delimiters like `---`. A custom reader must
+ *   uphold this.
  * @property {(absPath: string) => Uint8Array} readBinary Read raw bytes (images).
  * @property {(absPath: string) => boolean} exists Whether the path exists.
  * @property {(absPath: string) => string} realpath Canonical path (symlinks
@@ -40,6 +45,11 @@ import path from "node:path";
  */
 export function memoryReader(files, cwd = "/") {
   const map = files instanceof Map ? files : new Map(Object.entries(files));
+  // Resolution deliberately uses the HOST `path`, because `cwd` is frequently a
+  // real OS directory (the fs-parity test compiles the same project from disk
+  // and from memory against one temp root, and a Windows temp root is
+  // `C:\…` — which `path.posix` does not recognize as absolute). Only the
+  // resulting KEY is forced to POSIX, matching the map's documented key shape.
   const keyOf = (/** @type {string} */ absPath) =>
     path.relative(cwd, path.resolve(absPath)).split(path.sep).join("/");
   return {
@@ -49,7 +59,7 @@ export function memoryReader(files, cwd = "/") {
       if (value === undefined) {
         throw new Error(`ENOENT: no in-memory file "${key}" (from ${absPath})`);
       }
-      return value;
+      return normalizeNewlines(value);
     },
     readBinary: () => {
       throw new Error("memoryReader: binary reads are unsupported");