@zvndev/darkmown 2.0.1 → 2.2.0

package/src/compiler/predicates.js

@@ -5,6 +5,8 @@
 // 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";
 
 /**
@@ -12,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.
@@ -45,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;
@@ -93,14 +113,9 @@ function compileOperand(tok, itemName, ctx) {
   };
 }
 
-/** @param {unknown} a @param {unknown} b @returns {boolean} */
-const containsHelper = (a, b) =>
-  String(a ?? "")
-    .toLowerCase()
-    .includes(String(b ?? "").toLowerCase());
-
 /**
- * Evaluate a compiled predicate against a row at build time.
+ * Evaluate a compiled predicate against a row at build time by walking its AST —
+ * the same closed evaluator the runtime uses, so the fold matches. No eval.
  * @param {string} body
  * @param {unknown} item
  * @param {Ctx} ctx
@@ -108,11 +123,7 @@ const containsHelper = (a, b) =>
  */
 export function evalPredicate(body, item, ctx) {
   try {
-    /** @param {string} [p] */
-    const I = (p) => getPath(item, p ? p.split(".") : []);
-    /** @param {string} k @param {string} [r] */
-    const S = (k, r) => getPath(ctx.comp.state.get(k), r ? r.split(".") : []);
-    return Boolean(new Function("I", "S", "C", `return (${body});`)(I, S, containsHelper));
+    return Boolean(evalAst(astOf(body), item, ctx.comp));
   } catch {
     console.warn(
       `@loop where predicate "${body}" in ${ctx.file} could not be evaluated at build time; treating the row as excluded. Check the condition.`
@@ -197,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);

package/src/compiler/reader.js

@@ -0,0 +1,60 @@
+// ---------------------------------------------------------------------------
+// The file-reader abstraction the compiler reads every source through. The
+// compiler never touches `node:fs` directly; instead a `Reader` is threaded
+// through the `Compilation` (and the page-shell helpers), so the exact same
+// compile can run against the real filesystem (`fsReader`, in `fs-reader.js`)
+// or against an in-memory map of project-relative path → content
+// (`memoryReader`, here). The memory path is what `compileFromMemory` — and a
+// planned mobile/browser host — needs: a fully fs-free compile.
+//
+// This module imports NOTHING from `node:fs`, so it (and everything reachable
+// from `compileFromMemory`) bundles cleanly for the browser. The Node reader
+// lives in its own `fs-reader.js` that no browser-reachable module imports.
+// ---------------------------------------------------------------------------
+
+import path from "node:path";
+
+/**
+ * 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) => Uint8Array} readBinary Read raw bytes (images).
+ * @property {(absPath: string) => boolean} exists Whether the path exists.
+ * @property {(absPath: string) => string} realpath Canonical path (symlinks
+ *   resolved on a real fs; a no-op normalize in memory) — used for cycle keys.
+ */
+
+/**
+ * A reader backed by an in-memory map of PROJECT-RELATIVE path → content. Keys
+ * are POSIX, project-relative (e.g. `site/pages/index.wd`, `site/_/nav.wd`);
+ * lookups translate an absolute compile path back to its key via `cwd`. There
+ * are no symlinks in memory, so `realpath` just normalizes. Binary reads are
+ * unsupported (the playground has no image files, and image measuring degrades
+ * to "no dimensions" on a throw), so `readBinary` throws — callers already
+ * try/catch it.
+ * @param {Record<string, string> | Map<string, string>} files
+ * @param {string} [cwd] Virtual project root the keys are relative to.
+ * @returns {Reader}
+ */
+export function memoryReader(files, cwd = "/") {
+  const map = files instanceof Map ? files : new Map(Object.entries(files));
+  const keyOf = (/** @type {string} */ absPath) =>
+    path.relative(cwd, path.resolve(absPath)).split(path.sep).join("/");
+  return {
+    readText: (absPath) => {
+      const key = keyOf(absPath);
+      const value = map.get(key);
+      if (value === undefined) {
+        throw new Error(`ENOENT: no in-memory file "${key}" (from ${absPath})`);
+      }
+      return value;
+    },
+    readBinary: () => {
+      throw new Error("memoryReader: binary reads are unsupported");
+    },
+    exists: (absPath) => map.has(keyOf(absPath)),
+    realpath: (absPath) => path.resolve(absPath)
+  };
+}

package/src/compiler/state.js

@@ -8,15 +8,22 @@
 // while keeping the message text and `Use:` hints intact.
 // ---------------------------------------------------------------------------
 
-import { at } from "./context.js";
-import { FORMATTERS } from "./format.js";
-import { escapeHtml, getPath, parseStateValue, safeScriptJson } from "./interpolation.js";
+import { at, lineOf, wdError } from "./context.js";
+import { astOf, evalAst } from "./expr-ast.js";
+import { escapeHtml, parseStateValue, safeScriptJson } from "./interpolation.js";
 import { compileComputedExpr } from "./predicates.js";
 
 /**
  * @typedef {import("./context.js").Ctx} Ctx
  */
 
+// Concrete, compilable one-liners for the state-family hint tails + the catalog.
+export const STATE_EXAMPLE = ":state count = 0";
+export const STORE_EXAMPLE = ":store cart = []";
+export const COMPUTED_EXAMPLE = ":computed total = items.length * 4";
+export const THEME_EXAMPLE = ":theme";
+const STATE_USE = `Use: :state name = value [persist] — e.g. ${STATE_EXAMPLE}`;
+
 /**
  * @param {string} line
  * @param {Ctx} ctx
@@ -25,7 +32,13 @@ import { compileComputedExpr } from "./predicates.js";
  */
 export function handleState(line, ctx, index) {
   const match = line.match(/^:state\s+([A-Za-z_$][\w$]*)\s*=\s*(.+?)(\s+persist)?$/);
-  if (!match) throw new Error(`Malformed :state in ${at(ctx, index)}: ${line}`);
+  if (!match)
+    throw wdError(`Malformed :state in ${at(ctx, index)}: ${line}. ${STATE_USE}`, {
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint: STATE_USE.slice("Use: ".length),
+      example: STATE_EXAMPLE
+    });
   const value = parseStateValue(match[2], at(ctx, index));
   const key = declareState(match[1], value, ctx);
   const persistAttr = match[3] ? ` data-wd-persist="${key}"` : "";
@@ -43,8 +56,13 @@ export function declareState(name, value, ctx) {
   if (ctx.loopItem)
     throw new Error(`State cannot be declared inside a reactive @loop body (${ctx.file})`);
   if (ctx.comp.stores.has(name))
-    throw new Error(
-      `State "${name}" collides with a :store of the same name in ${ctx.file}. Use: :store name = value for the global, or rename one.`
+    throw wdError(
+      `State "${name}" collides with a :store of the same name in ${ctx.file}. Use: :store name = value for the global, or rename one — e.g. ${STORE_EXAMPLE}`,
+      {
+        file: ctx.file,
+        hint: `:store name = value for the global, or rename one — e.g. ${STORE_EXAMPLE}`,
+        example: STORE_EXAMPLE
+      }
     );
   const key = ctx.sections.length ? `${ctx.sections.at(-1)}:${name}` : name;
   if (ctx.comp.state.has(key))
@@ -63,8 +81,14 @@ export function declareState(name, value, ctx) {
 export function handleStore(line, ctx, index) {
   const match = line.match(/^:store\s+([A-Za-z_$][\w$]*)\s*=\s*(.+?)(\s+ephemeral)?$/);
   if (!match)
-    throw new Error(
-      `Malformed :store in ${at(ctx, index)}: ${line}. Use: :store name = value [ephemeral]`
+    throw wdError(
+      `Malformed :store in ${at(ctx, index)}: ${line}. Use: :store name = value [ephemeral] — e.g. ${STORE_EXAMPLE}`,
+      {
+        file: ctx.file,
+        line: lineOf(ctx, index),
+        hint: `:store name = value [ephemeral] — e.g. ${STORE_EXAMPLE}`,
+        example: STORE_EXAMPLE
+      }
     );
   const value = parseStateValue(match[2], at(ctx, index));
   const name = declareStore(match[1], value, ctx);
@@ -83,10 +107,22 @@ export function handleStore(line, ctx, index) {
  */
 export function declareStore(name, value, ctx) {
   if (ctx.comp.stores.has(name))
-    throw new Error(`Store "${name}" is declared twice in ${ctx.file}. Use: :store name = value`);
+    throw wdError(
+      `Store "${name}" is declared twice in ${ctx.file}. Use: :store name = value — e.g. ${STORE_EXAMPLE}`,
+      {
+        file: ctx.file,
+        hint: `:store name = value — e.g. ${STORE_EXAMPLE}`,
+        example: STORE_EXAMPLE
+      }
+    );
   if (ctx.comp.state.has(name))
-    throw new Error(
-      `Store "${name}" collides with a :state of the same name in ${ctx.file}. Use: :store name = value for the global, or rename one.`
+    throw wdError(
+      `Store "${name}" collides with a :state of the same name in ${ctx.file}. Use: :store name = value for the global, or rename one — e.g. ${STORE_EXAMPLE}`,
+      {
+        file: ctx.file,
+        hint: `:store name = value for the global, or rename one — e.g. ${STORE_EXAMPLE}`,
+        example: STORE_EXAMPLE
+      }
     );
   ctx.comp.stores.add(name);
   ctx.comp.state.set(name, value);
@@ -115,31 +151,38 @@ export function declareErrorState(key, ctx) {
 export function handleComputed(line, ctx, index) {
   const match = line.match(/^:computed\s+([A-Za-z_$][\w$]*)\s*=\s*(.+)$/);
   if (!match)
-    throw new Error(
-      `Malformed :computed in ${at(ctx, index)}: ${line}. Use: :computed total = items.length * 4`
-    );
+    throw wdError(`Malformed :computed in ${at(ctx, index)}: ${line}. Use: ${COMPUTED_EXAMPLE}`, {
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint: COMPUTED_EXAMPLE,
+      example: COMPUTED_EXAMPLE
+    });
   const expr = compileComputedExpr(match[2].trim(), ctx);
-  /** @type {unknown} */
-  let initial;
+  // Parse the validated expression to the compact AST the runtime walks. A parse
+  // failure means the RHS is syntactically malformed (e.g. `|| <`) — a compile
+  // error, not a silently-broken binding.
+  /** @type {any[]} */
+  let ast;
   try {
-    /** @param {string} key @param {string} [path] */
-    const read = (key, path) => getPath(ctx.comp.state.get(key), path ? path.split(".") : []);
-    // Build-time mirror of the runtime's AGG helper, so a `:computed total = sum(...)`
-    // has the same initial value the runtime will recompute to.
-    const agg = (
-      /** @type {string} */ name,
-      /** @type {any} */ list,
-      /** @type {string} */ field
-    ) => (FORMATTERS[name] ? FORMATTERS[name](list, field == null ? [] : [field]) : undefined);
-    initial = new Function("S", "A", `return (${expr});`)(read, agg);
+    ast = astOf(expr);
   } catch {
-    console.warn(
-      `:computed "${match[2].trim()}" in ${ctx.file} could not be evaluated at build time; falling back to null. Check the expression.`
+    throw wdError(
+      `Malformed :computed expression in ${at(ctx, index)}: ${line}. Use: ${COMPUTED_EXAMPLE}`,
+      {
+        file: ctx.file,
+        line: lineOf(ctx, index),
+        hint: COMPUTED_EXAMPLE,
+        example: COMPUTED_EXAMPLE
+      }
     );
-    initial = null;
   }
+  // Build-time mirror of the runtime: walk the AST (no eval) so `:computed total =
+  // sum(...)` seeds the value the runtime recomputes. The walker is total over a
+  // validated AST — state that isn't known at build time resolves to undefined and
+  // folds to null, never throws — so parse-failure above is the only error path.
+  const initial = evalAst(ast, undefined, ctx.comp);
   const key = declareState(match[1], initial ?? null, ctx);
-  return `<span data-wd-computed data-wd-computed-key="${key}" data-wd-computed-expr="${escapeHtml(expr)}"></span><script type="application/json" data-wd-state>${safeScriptJson({ [key]: initial ?? null })}</script>`;
+  return `<span data-wd-computed data-wd-computed-key="${key}" data-wd-computed-expr="${escapeHtml(JSON.stringify(ast))}"></span><script type="application/json" data-wd-state>${safeScriptJson({ [key]: initial ?? null })}</script>`;
 }
 
 /**
@@ -157,8 +200,14 @@ export function handleComputed(line, ctx, index) {
 export function handleTheme(line, ctx, index) {
   const match = line.match(/^:theme(?:\s+([A-Za-z_$][\w$]*))?(?:\s*=\s*(.+))?$/);
   if (!match) {
-    throw new Error(
-      `Malformed :theme in ${at(ctx, index)}: ${line}. Use: :theme  (or  :theme name = "auto")`
+    throw wdError(
+      `Malformed :theme in ${at(ctx, index)}: ${line}. Use: :theme  (or  :theme name = "auto") — e.g. ${THEME_EXAMPLE}`,
+      {
+        file: ctx.file,
+        line: lineOf(ctx, index),
+        hint: `:theme  (or  :theme name = "auto") — e.g. ${THEME_EXAMPLE}`,
+        example: THEME_EXAMPLE
+      }
     );
   }
   const name = match[1] || "theme";

package/src/compiler/structure.js

@@ -11,7 +11,8 @@
 // while keeping the message text and `Use:` hints intact.
 // ---------------------------------------------------------------------------
 
-import { at, createScope, LOOP_META, nestedCtx } from "./context.js";
+import { at, createScope, LOOP_META, lineOf, nestedCtx, wdError } from "./context.js";
+import { astOf, serializeExpr } from "./expr-ast.js";
 import { resolveInclude, scopedSkinFor, stampScope } from "./includes.js";
 import {
   escapeHtml,
@@ -27,6 +28,13 @@ import { compileWhen, evalPredicate } from "./predicates.js";
  * @typedef {import("./context.js").Ctx} Ctx
  */
 
+// Concrete, compilable structure examples for the hint tails + the catalog.
+export const INCLUDE_EXAMPLE = "@include /header.wd";
+export const CONTAINER_EXAMPLE = "::: card .featured";
+export const IF_EXAMPLE = ":if count > 0";
+export const CAROUSEL_EXAMPLE = ":carousel autoplay=3000";
+const INCLUDE_USE = `Use: @include /partial.wd [with key="value"] — e.g. ${INCLUDE_EXAMPLE}`;
+
 // Container names that emit their own semantic landmark element instead of a
 // `<div>`, so scaffolds get real `<nav>`/`<main>` landmarks (accessibility: the
 // skip link targets a genuine main-content region and navigation chrome sits in
@@ -43,8 +51,21 @@ const SEMANTIC_CONTAINER_TAGS = new Set(["nav", "main"]);
  */
 export function handleInclude(line, ctx, index) {
   const match = line.match(/^@include\s+(\S+)(?:\s+with\s+(.+))?$/);
-  if (!match) throw new Error(`Malformed @include in ${at(ctx, index)}: ${line}`);
-  const target = resolveInclude(match[1], ctx.file, ctx.context, false, at(ctx, index));
+  if (!match)
+    throw wdError(`Malformed @include in ${at(ctx, index)}: ${line}. ${INCLUDE_USE}`, {
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint: INCLUDE_USE.slice("Use: ".length),
+      example: INCLUDE_EXAMPLE
+    });
+  const target = resolveInclude(
+    match[1],
+    ctx.file,
+    ctx.context,
+    false,
+    at(ctx, index),
+    ctx.comp.reader
+  );
   const args = parseIncludeArgs(match[2] || "", ctx);
   const childScope = createScope(ctx.scope, args);
   // Thread the reactive-nesting depth (and the enclosing loop opener, so a depth
@@ -67,7 +88,7 @@ export function handleInclude(line, ctx, index) {
   // anywhere else on the page, and the scope never leaks to the include's
   // siblings (only this child HTML is stamped). The CSS rewrite (builder) uses
   // the same path-derived id, so attribute and stylesheet line up.
-  const scopedSkin = scopedSkinFor(target, ctx.context);
+  const scopedSkin = scopedSkinFor(target, ctx.context, ctx.comp.reader);
   return scopedSkin && scopedSkin.scoped ? stampScope(child.html, scopedSkin.scopeId) : child.html;
 }
 
@@ -110,9 +131,9 @@ export function handleContainer(header, bodyLines, ctx, index) {
   let tag = "section";
   /** @type {string[]} Static classes baked into class="". */
   const extraClass = [];
-  /** @type {[string, string][]} Reactive loop-item class bindings (data-wd-each-class). */
+  /** @type {[string, any[]][]} Reactive loop-item class bindings (data-wd-each-class): [class, exprAST]. */
   const eachClasses = [];
-  /** @type {[string, string][]} Global state-driven class bindings (data-wd-class). */
+  /** @type {[string, any[]][]} Global state-driven class bindings (data-wd-class): [class, exprAST]. */
   const stateClasses = [];
   let id = "";
   // Leading tag/name token (anything not starting with . or #). "section" keeps
@@ -157,8 +178,8 @@ export function handleContainer(header, bodyLines, ctx, index) {
       const compiled = compileWhen(whenMatch[1].trim(), ctx);
       if (compiled.static) {
         if (compiled.value) extraClass.push(cls);
-      } else if (compiled.item) eachClasses.push([cls, compiled.body]);
-      else stateClasses.push([cls, compiled.body]);
+      } else if (compiled.item) eachClasses.push([cls, astOf(compiled.body)]);
+      else stateClasses.push([cls, astOf(compiled.body)]);
     } else {
       extraClass.push(cls);
     }
@@ -207,10 +228,15 @@ export function handleCarousel(line, bodyLines, ctx, index) {
   let autoplayAttr = "";
   if (rest) {
     const auto = rest.match(/^autoplay=(\d+)$/);
-    if (!auto)
-      throw new Error(
-        `Malformed :carousel in ${at(ctx, index)}: ${line}. Use: :carousel [autoplay=3000] … :endcarousel`
-      );
+    if (!auto) {
+      const hint = `:carousel [autoplay=3000] … :endcarousel — e.g. ${CAROUSEL_EXAMPLE}`;
+      throw wdError(`Malformed :carousel in ${at(ctx, index)}: ${line}. Use: ${hint}`, {
+        file: ctx.file,
+        line: lineOf(ctx, index),
+        hint,
+        example: CAROUSEL_EXAMPLE
+      });
+    }
     autoplayAttr = ` data-wd-carousel-autoplay="${auto[1]}"`;
   }
   ctx.comp.assets.behaviors.add("carousel");
@@ -315,10 +341,15 @@ export function handleIf(line, truthyLines, falsyLines, ctx, index, falsyStart =
   // whitelist as `@loop … where` / `.class when` (with `not`), so it folds at
   // build when static, drives a per-row each-if when it reads the loop item, and
   // a global if-region (evaluated each render) when it reads state. No raw eval.
-  if (!condition)
-    throw new Error(
-      `Malformed :if in ${at(ctx, index)}: ${line}. Use ":if name" or ":if a <op> b [and|or|not …]".`
-    );
+  if (!condition) {
+    const hint = `":if name" or ":if a <op> b [and|or|not …]" — e.g. ${IF_EXAMPLE}`;
+    throw wdError(`Malformed :if in ${at(ctx, index)}: ${line}. Use ${hint}`, {
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint,
+      example: IF_EXAMPLE
+    });
+  }
   const compiled = compileWhen(condition, ctx, '":if"');
   if (compiled.static)
     return ctx.compileBody(
@@ -328,7 +359,7 @@ export function handleIf(line, truthyLines, falsyLines, ctx, index, falsyStart =
   ctx.comp.assets.runtime = true;
   const truthy = ctx.compileBody(truthyLines, truthyCtx).trim();
   const falsy = ctx.compileBody(falsyLines, falsyCtx).trim();
-  const exprAttr = ` data-wd-if-expr="${escapeHtml(compiled.body)}"`;
+  const exprAttr = ` data-wd-if-expr="${escapeHtml(serializeExpr(compiled.body))}"`;
   if (compiled.item) {
     return `<span data-wd-each-if${exprAttr}><template data-wd-if-true>${truthy}</template><template data-wd-if-false>${falsy}</template><span data-wd-each-if-out></span></span>`;
   }

package/src/compiler.js

@@ -1,7 +1,13 @@
 // Darkmown's compiler, split into cohesive modules under `src/compiler/`. This
-// file is a thin barrel: it re-exports the public API from `src/compiler/index.js`
-// so every existing `import … from "./compiler.js"` (builder, tests) keeps
-// working unchanged. See `src/compiler/index.js` for the module map.
+// file is the Node-facing barrel: it re-exports the public API from
+// `src/compiler/index.js` so every existing `import … from "./compiler.js"`
+// (builder, tests) keeps working unchanged. It is ALSO the single place the
+// default filesystem reader is injected — `compilePage`/`compileDocument`/
+// `enhanceImages` default their reader to `fsReader()` here, so callers keep
+// their old signatures and the compile stays byte-identical. The fs-free entry
+// point (`compileFromMemory`) needs no default and passes through. Because this
+// module imports `fs-reader.js` (and thus `node:fs`), it is Node-only; the
+// browser bundles `compileFromMemory` from `src/compiler/page.js` directly.
 
 // Re-export the public typedefs so existing `import("./compiler.js").Type`
 // references (e.g. `Assets` in src/builder.js) keep resolving after the split.
@@ -16,12 +22,57 @@
  * @typedef {import("./compiler/context.js").CompiledPage} CompiledPage
  */
 
+import { fsReader } from "./compiler/fs-reader.js";
+import {
+  compileDocument as compileDocumentImpl,
+  compilePage as compilePageImpl,
+  enhanceImages as enhanceImagesImpl
+} from "./compiler/index.js";
+
 export {
-  compileDocument,
-  compilePage,
-  enhanceImages,
+  compileFromMemory,
   escapeHtml,
   loopKeyOf,
   parseFrontmatter,
   stampScope
 } from "./compiler/index.js";
+
+/**
+ * Compile a page source file into a full HTML document plus its assets, reading
+ * from the real filesystem by default. Pass `options.reader` to compile against
+ * a different source (see `compileFromMemory`).
+ * @param {string} file Absolute path to the source `.md`/`.wd` file.
+ * @param {import("./config.js").Paths} context Resolved project paths.
+ * @param {{ feed?: { href: string, title: string }, collections?: Map<string, import("./compiler/collections.js").CollectionRow[]>, vars?: Record<string, unknown>, reader?: import("./compiler/reader.js").Reader }} [options]
+ * @returns {CompiledPage}
+ */
+export function compilePage(file, context, options = {}) {
+  return compilePageImpl(file, context, { reader: fsReader(), ...options });
+}
+
+/**
+ * Compile a source file into its body HTML, frontmatter, and assets (no page
+ * shell), reading from the real filesystem by default.
+ * @param {string} file Absolute path to the source file.
+ * @param {import("./config.js").Paths} context Resolved project paths.
+ * @param {string[]} [stack] Include stack for cycle detection.
+ * @param {Record<string, unknown>} [vars] Initial static scope variables.
+ * @param {Map<string, import("./compiler/collections.js").CollectionRow[]>} [collections]
+ * @param {import("./compiler/reader.js").Reader} [reader] Source reader.
+ * @returns {CompiledDocument}
+ */
+export function compileDocument(file, context, stack, vars, collections, reader = fsReader()) {
+  return compileDocumentImpl(file, context, stack, vars, collections, reader);
+}
+
+/**
+ * Harden every `<img>` in an assembled page body, reading intrinsic dimensions
+ * from the real filesystem by default.
+ * @param {string} html Assembled page body HTML.
+ * @param {import("./config.js").Paths} paths Resolved project paths.
+ * @param {import("./compiler/reader.js").Reader} [reader] Source reader for image bytes.
+ * @returns {string}
+ */
+export function enhanceImages(html, paths, reader = fsReader()) {
+  return enhanceImagesImpl(html, paths, reader);
+}

package/src/grammar.js

@@ -0,0 +1,131 @@
+// ---------------------------------------------------------------------------
+// GBNF grammar generator for `.wd` DIRECTIVE LINES.
+//
+// `generateGrammar()` emits a llama.cpp-compatible GBNF grammar that constrains
+// a small model's decoding to well-formed Darkmown directive lines (plus the
+// `{ path | pipe }` interpolation token). It is generated from the SAME catalog
+// the cheatsheet uses, so the keyword set, `@loop` clauses, comparison operators,
+// and format-pipe names can never drift from what compiles.
+//
+// Scope (stated deliberately): this grammar constrains the SHAPE of a directive
+// line — the leading keyword must be a real directive, `@loop` must be
+// `@loop <src> into <item> …clauses`, a `where`/`:if` condition must be
+// `operand <op> operand`, a `:button` must be `"…" -> <action-chain>`, and an
+// interpolation must pipe through a known formatter. It does NOT try to grammar-
+// check free-form values (arbitrary JSON seeds, URLs, prose) — those are `text`.
+// That is enough to delete the on-device failure class (JS/HTML muscle-memory
+// openers like `::: card class=` or `cart.filter(...)` become unrepresentable)
+// while staying small and maintainable.
+// ---------------------------------------------------------------------------
+
+import { directiveCatalog } from "./catalog.js";
+
+/** Slugify a directive token into a GBNF rule name (`@loop` → `dir-loop`). */
+/** @type {Record<string, string>} */
+const SLUG = {
+  "@include": "dir-include",
+  "@loop": "dir-loop",
+  ":::": "dir-container",
+  ":if": "dir-if",
+  ":state": "dir-state",
+  ":store": "dir-store",
+  ":computed": "dir-computed",
+  ":fetch": "dir-fetch",
+  ":effect": "dir-effect",
+  ":every": "dir-every",
+  ":theme": "dir-theme",
+  ":button": "dir-button",
+  ":form": "dir-form",
+  ":input": "dir-input",
+  ":textarea": "dir-textarea",
+  ":select": "dir-select",
+  ":checkbox": "dir-checkbox",
+  ":radio": "dir-radio",
+  ":submit": "dir-submit",
+  ":bind": "dir-bind",
+  ":slider": "dir-slider",
+  ":video": "dir-video",
+  ":audio": "dir-audio",
+  ":embed": "dir-embed",
+  ":carousel": "dir-carousel"
+};
+
+// The directives given a structured RHS below; every other directive gets the
+// generic `"<keyword>" restofline` rule (keyword pinned, argument tail free).
+const STRUCTURED = new Set(["@loop", ":if", ":button", ":::"]);
+
+/** A GBNF alternation literal list, e.g. `"a" | "b"`. */
+const alt = (/** @type {string[]} */ items) => items.map((s) => `"${s}"`).join(" | ");
+
+/**
+ * Generate the GBNF grammar for `.wd` directive lines from the directive catalog.
+ * @returns {string}
+ */
+export function generateGrammar() {
+  const cat = directiveCatalog();
+  const dirRules = cat.directives.map((d) => SLUG[d.name]).filter(Boolean);
+
+  /** @type {string[]} */
+  const lines = [];
+  lines.push("# Darkmown .wd directive-line grammar — generated by src/grammar.js");
+  lines.push(
+    "# Constrains a directive line (or a { path | pipe } interpolation). Do not edit by hand."
+  );
+  lines.push("");
+  lines.push("root ::= directive | binding");
+  lines.push(`directive ::= ${dirRules.join(" | ")}`);
+  lines.push("");
+
+  // Structured directives.
+  lines.push('dir-loop ::= "@loop" sp operand sp "into" sp ident loop-clauses');
+  lines.push('dir-if ::= ":if" sp ( condition (sp joiner sp condition)* | path )');
+  lines.push('dir-button ::= ":button" sp dqstring sp "->" sp action-chain');
+  lines.push('dir-container ::= ":::" restofline');
+  lines.push("");
+
+  // Generic directives: keyword pinned, argument tail free to end of line.
+  for (const d of cat.directives) {
+    if (STRUCTURED.has(d.name)) continue;
+    lines.push(`${SLUG[d.name]} ::= "${d.name}" restofline`);
+  }
+  lines.push("");
+
+  // @loop clause vocabulary (mirrors the fixed clause order in the catalog).
+  lines.push("loop-clauses ::= ( sp loop-clause )*");
+  lines.push(
+    'loop-clause ::= where-clause | "sort by" sp path ( sp ( "asc" | "desc" ) )? | "reverse" | "offset" sp number | "limit" sp number | "paginate" sp number | "sortable"'
+  );
+  lines.push('where-clause ::= "where" sp condition ( sp joiner sp condition )*');
+  lines.push("condition ::= operand sp op sp operand");
+  lines.push(`op ::= ${alt(cat.predicateOps.map((o) => o.name))}`);
+  lines.push(`joiner ::= ${alt(cat.predicateJoiners.filter((j) => j !== "not"))}`);
+  lines.push("");
+
+  // Button-action vocabulary. Each operator token below is asserted present
+  // against the catalog's action tokens in tests/grammar.test.js.
+  lines.push('action-chain ::= action ( wsopt ";" wsopt action )*');
+  lines.push("action ::= ident action-op");
+  lines.push(
+    'action-op ::= "++" | "--" | sp "+=" sp value | sp "-=" sp value | sp "=" sp value | sp "toggle" ( sp value )? | sp "append" sp value | sp "prepend" sp value | sp "remove" sp value | sp "clear" | sp "merge" sp ident | sp "delete" sp value | sp "reset" | sp "refetch"'
+  );
+  lines.push("");
+
+  // Interpolation binding with format pipes.
+  lines.push('binding ::= "{" wsopt path pipe-chain wsopt "}"');
+  lines.push('pipe-chain ::= ( wsopt "|" wsopt pipe ( ":" value )* )*');
+  lines.push(`pipe ::= ${alt(cat.formatPipes.map((p) => p.name))}`);
+  lines.push("");
+
+  // Terminals.
+  lines.push("operand ::= path | dqstring | number");
+  lines.push("value ::= dqstring | number | path");
+  lines.push("ident ::= [a-zA-Z_$] [a-zA-Z0-9_$]*");
+  lines.push("path ::= [a-zA-Z0-9_$/.~-]+");
+  lines.push("number ::= [0-9]+");
+  lines.push('dqstring ::= "\\"" [^"]* "\\""');
+  lines.push("restofline ::= [^\\n]*");
+  lines.push('sp ::= " "+');
+  lines.push('wsopt ::= " "*');
+  lines.push("");
+  return lines.join("\n");
+}