@zvndev/darkmown 2.0.0 → 2.1.0

package/src/compiler/fs-reader.js

@@ -0,0 +1,25 @@
+// ---------------------------------------------------------------------------
+// The default {@link import("./reader.js").Reader}: reads straight from the
+// real filesystem. This is the ONLY compiler module that imports `node:fs`, so
+// it is deliberately isolated — nothing reachable from `compileFromMemory`
+// imports it, keeping the browser/mobile compile path fs-free. The public
+// `compilePage`/`compileDocument`/`enhanceImages` (in `src/compiler.js`) inject
+// this reader by default, so every existing caller keeps working unchanged.
+// ---------------------------------------------------------------------------
+
+import fs from "node:fs";
+
+/**
+ * A {@link import("./reader.js").Reader} backed by `node:fs`. Each method is a
+ * thin pass-through to the synchronous fs call the compiler used before the
+ * reader abstraction, so an fs-backed compile stays byte-identical.
+ * @returns {import("./reader.js").Reader}
+ */
+export function fsReader() {
+  return {
+    readText: (absPath) => fs.readFileSync(absPath, "utf8"),
+    readBinary: (absPath) => fs.readFileSync(absPath),
+    exists: (absPath) => fs.existsSync(absPath),
+    realpath: (absPath) => fs.realpathSync(absPath)
+  };
+}

package/src/compiler/includes.js

@@ -5,7 +5,6 @@
 // and warn when a plain `.md` file uses `.wd`-only syntax.
 // ---------------------------------------------------------------------------
 
-import fs from "node:fs";
 import path from "node:path";
 import { scopeIdFor } from "../skin.js";
 import { pageIncludeExtensions } from "./context.js";
@@ -27,12 +26,13 @@ import { stripQuotes } from "./interpolation.js";
  * (page/include) always agree on both.
  * @param {string} skinPath Absolute path to the colocated `.skin` file.
  * @param {string} cwd Project root, for the path-based scope id.
+ * @param {import("./reader.js").Reader} reader Source reader for the skin file.
  * @returns {{ scoped: boolean, scopeId: string }}
  */
-export function scopeInfoForSkin(skinPath, cwd) {
+export function scopeInfoForSkin(skinPath, cwd, reader) {
   const rel = path.relative(cwd, skinPath).replaceAll(path.sep, "/");
   const scopeId = scopeIdFor(rel);
-  const src = fs.readFileSync(skinPath, "utf8").replace(/\/\*[\s\S]*?\*\//g, "");
+  const src = reader.readText(skinPath).replace(/\/\*[\s\S]*?\*\//g, "");
   for (const raw of src.split("\n")) {
     const t = raw.trim();
     if (!t || t.startsWith("//") || !/[A-Za-z0-9]/.test(t)) continue;
@@ -49,13 +49,14 @@ export function scopeInfoForSkin(skinPath, cwd) {
  * `.skin` extension).
  * @param {string} file Absolute path to the page/include source file.
  * @param {Paths} context
+ * @param {import("./reader.js").Reader} reader Source reader for the skin file.
  * @returns {{ scoped: boolean, scopeId: string } | null}
  */
-export function scopedSkinFor(file, context) {
+export function scopedSkinFor(file, context, reader) {
   const ext = path.extname(file);
   const candidate = `${file.slice(0, -ext.length)}.skin`;
-  if (!fs.existsSync(candidate)) return null;
-  return scopeInfoForSkin(candidate, context.cwd);
+  if (!reader.exists(candidate)) return null;
+  return scopeInfoForSkin(candidate, context.cwd, reader);
 }
 
 /**
@@ -127,9 +128,10 @@ export function stampScope(html, scopeId) {
  * @param {string} file
  * @param {Paths} context
  * @param {Assets} assets
+ * @param {import("./reader.js").Reader} reader Source reader for sibling probing.
  * @returns {void}
  */
-export function collectColocatedAssets(file, context, assets) {
+export function collectColocatedAssets(file, context, assets, reader) {
   const ext = path.extname(file);
   const stem = file.slice(0, -ext.length);
   for (const [assetExt, folder] of [
@@ -137,7 +139,7 @@ export function collectColocatedAssets(file, context, assets) {
     [".js", "scripts"]
   ]) {
     const candidate = `${stem}${assetExt}`;
-    if (!fs.existsSync(candidate)) continue;
+    if (!reader.exists(candidate)) continue;
     const rel = path.relative(context.cwd, candidate).replaceAll(path.sep, "/");
     const outputExt = assetExt === ".skin" ? ".css" : ".js";
     const publicPath = `/__wd/${folder}/${rel.slice(0, -assetExt.length).replace(/[/.]/g, "_")}${outputExt}`;
@@ -146,7 +148,8 @@ export function collectColocatedAssets(file, context, assets) {
       assets.skins.add(publicPath);
       // Surface "this skin is scoped" so the warning pass (builder) and the HTML
       // stamp can find the scoped skins among all colocated ones by source path.
-      if (scopeInfoForSkin(candidate, context.cwd).scoped) assets.scopedSkins.add(candidate);
+      if (scopeInfoForSkin(candidate, context.cwd, reader).scoped)
+        assets.scopedSkins.add(candidate);
     }
     if (assetExt === ".js") assets.scripts.add(publicPath);
   }
@@ -157,10 +160,16 @@ export function collectColocatedAssets(file, context, assets) {
  * @param {string} spec Include target (may be quoted).
  * @param {string} fromFile File requesting the include.
  * @param {Paths} context
- * @param {boolean} [allowAny] Allow non-page extensions (e.g. JSON for `@loop`).
+ * @param {boolean} allowAny Allow non-page extensions (e.g. JSON for `@loop`).
+ * @param {string} loc Source location (`file:line`) for the error messages, so
+ *   an unresolved/out-of-sandbox include reports the directive's line. Callers
+ *   with a line index pass `at(ctx, index)`; pass `fromFile` for the file-only
+ *   message.
+ * @param {import("./reader.js").Reader} reader Source reader for existence
+ *   probing, threaded from `ctx.comp.reader`.
  * @returns {string}
  */
-export function resolveInclude(spec, fromFile, context, allowAny = false) {
+export function resolveInclude(spec, fromFile, context, allowAny, loc, reader) {
   const clean = stripQuotes(spec);
   const candidates = [];
   if (clean.startsWith("/")) {
@@ -172,13 +181,15 @@ export function resolveInclude(spec, fromFile, context, allowAny = false) {
   for (const candidate of candidates) {
     const resolved = path.resolve(candidate);
     if (!isAllowedInclude(resolved, context)) {
-      throw new Error(`Include "${spec}" from ${fromFile} resolves outside site/pages or site/_`);
+      throw new Error(`Include "${spec}" from ${loc} resolves outside site/pages or site/_`);
     }
-    if (!fs.existsSync(resolved)) continue;
+    if (!reader.exists(resolved)) continue;
     if (!allowAny && !pageIncludeExtensions.includes(path.extname(resolved))) continue;
     return resolved;
   }
-  throw new Error(`Could not resolve include "${spec}" from ${fromFile}`);
+  throw new Error(
+    `Could not resolve include "${spec}" from ${loc}. Looked in site/pages and site/_ — check the path and leading slash.`
+  );
 }
 
 /**

package/src/compiler/index.js

@@ -32,4 +32,4 @@ export { parseFrontmatter } from "./frontmatter.js";
 export { stampScope } from "./includes.js";
 export { escapeHtml } from "./interpolation.js";
 export { loopKeyOf } from "./loops.js";
-export { compileDocument, compilePage, enhanceImages } from "./page.js";
+export { compileDocument, compileFromMemory, compilePage, enhanceImages } from "./page.js";

package/src/compiler/loops.js

@@ -6,8 +6,8 @@
 // string fill used for the initial paint (text binds, per-row `:if`, meta).
 // ---------------------------------------------------------------------------
 
-import fs from "node:fs";
 import { at, createScope, nestedCtx } from "./context.js";
+import { serializeExpr } from "./expr-ast.js";
 import { applyPipeline, stagesFromAttr } from "./format.js";
 import { resolveInclude } from "./includes.js";
 import {
@@ -219,7 +219,7 @@ 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 ${ctx.file}: ${line}. ${LOOP_USAGE}`);
+  if (!match) throw new Error(`Malformed @loop in ${at(ctx, index)}: ${line}. ${LOOP_USAGE}`);
   const source = stripQuotes(match[1].trim());
   const itemName = match[2];
   const clauses = match[3]
@@ -273,8 +273,13 @@ export function handleLoop(line, bodyLines, emptyLines, ctx, index, emptyStart =
     paginate: clauses.paginate
   };
   // The loop body starts on the line after the opener; nested errors in it (and
-  // in the empty branch, via `opts.emptyStart`) report the true file line.
-  const bodyCtx = nestedCtx(ctx, index + 1);
+  // in the empty branch, via `opts.emptyStart`) report the true file line. The
+  // opener's location rides on the body ctx so a reactive loop nested inside this
+  // one can point the depth error back at its own opener line.
+  const bodyCtx = {
+    ...nestedCtx(ctx, index + 1),
+    loopOpener: { at: at(ctx, index), line: line.trim() }
+  };
 
   if (
     source.startsWith("/") ||
@@ -283,9 +288,16 @@ export function handleLoop(line, bodyLines, emptyLines, ctx, index, emptyStart =
     source.endsWith(".json")
   ) {
     if (opts.paginate) throw new Error(paginateOnlyCollections(ctx));
-    const dataFile = resolveInclude(source, ctx.file, ctx.context, true);
+    const dataFile = resolveInclude(
+      source,
+      ctx.file,
+      ctx.context,
+      true,
+      at(ctx, index),
+      ctx.comp.reader
+    );
     ctx.comp.deps.add(dataFile);
-    const rows = JSON.parse(fs.readFileSync(dataFile, "utf8"));
+    const rows = JSON.parse(ctx.comp.reader.readText(dataFile));
     if (!Array.isArray(rows)) throw new Error(`@loop data must be a JSON array: ${dataFile}`);
     return loopOverData(rows, itemName, bodyLines, bodyCtx, opts);
   }
@@ -372,6 +384,27 @@ function paginateOnlyCollections(ctx) {
   return `@loop paginate requires a collection source (a site/pages/<name>/ subdirectory) in ${ctx.file}. ${LOOP_USAGE}`;
 }
 
+/**
+ * Reject a reactive `@loop` that would open a THIRD reactive nesting level. The
+ * runtime reconciles at most two nested `data-wd-loop` levels (an outer loop and
+ * one inner loop); a third level's `data-wd-loop-out` paints empty. This guards
+ * every reactive-region entry point ({@link reactiveLoop}, {@link itemRelativeLoop}),
+ * so a state-key, item-relative, or state-filtered source is all covered. Static
+ * (build-unrolled) loops carry the depth through without incrementing it, so an
+ * interleaved static level neither triggers nor masks the limit.
+ * `ctx.reactiveDepth` is the number of reactive loops already enclosing this one.
+ * @param {Ctx} ctx
+ * @returns {void}
+ */
+function assertReactiveDepth(ctx) {
+  if ((ctx.reactiveDepth ?? 0) < 2) return;
+  const opener = ctx.loopOpener ?? { at: ctx.file, line: "" };
+  throw new Error(
+    `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.`
+  );
+}
+
 /**
  * Loop over a build-time collection's entry rows. With no `paginate`, this is a
  * plain static unroll (filter/sort/reverse/offset/limit at build time, zero JS).
@@ -540,6 +573,7 @@ function staticUnroll(rows, itemName, bodyLines, ctx, empty = null, emptyStart =
  * @returns {string}
  */
 function reactiveLoop(key, itemName, bodyLines, ctx, opts = null) {
+  assertReactiveDepth(ctx);
   ctx.comp.assets.runtime = true;
   /** @type {Ctx} */
   const templateCtx = {
@@ -547,6 +581,7 @@ function reactiveLoop(key, itemName, bodyLines, ctx, opts = null) {
     loopItem: itemName,
     loopKey: key ?? undefined,
     loopMeta: true,
+    reactiveDepth: (ctx.reactiveDepth ?? 0) + 1,
     scope: createScope(ctx.scope)
   };
   const templateHtml = ctx.compileBody(bodyLines, templateCtx).trim();
@@ -664,7 +699,7 @@ function loopEmptyTemplate(emptyLines, ctx, emptyStart = 0) {
  */
 function loopClauseAttrs(c) {
   return (
-    (c.where ? ` data-wd-loop-where="${escapeHtml(c.where.body)}"` : "") +
+    (c.where ? ` data-wd-loop-where="${escapeHtml(serializeExpr(c.where.body))}"` : "") +
     (c.sort
       ? ` data-wd-loop-sort="${escapeHtml(c.sort.keyKind === "key" ? `key:${c.sort.key}` : c.sort.key)}" data-wd-loop-sort-dir="${escapeHtml(c.sort.dirKind === "key" ? `key:${c.sort.dir}` : c.sort.dir)}"`
       : "") +
@@ -689,6 +724,7 @@ function loopClauseAttrs(c) {
  * @returns {string}
  */
 function itemRelativeLoop(path, itemName, bodyLines, ctx, opts) {
+  assertReactiveDepth(ctx);
   /** @type {Ctx} */
   // loopKey: undefined — an item-relative loop's source is a path off the outer
   // row, not a top-level state key, so a per-row `remove` inside it has no valid
@@ -698,6 +734,7 @@ function itemRelativeLoop(path, itemName, bodyLines, ctx, opts) {
     loopItem: itemName,
     loopKey: undefined,
     loopMeta: true,
+    reactiveDepth: (ctx.reactiveDepth ?? 0) + 1,
     scope: createScope(ctx.scope)
   };
   const templateHtml = ctx.compileBody(bodyLines, templateCtx).trim();

package/src/compiler/page.js

@@ -5,9 +5,9 @@
 // per-file compile (frontmatter + colocated assets + body / `.md` passthrough).
 // ---------------------------------------------------------------------------
 
-import fs from "node:fs";
 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";
@@ -20,6 +20,7 @@ import {
 } from "./includes.js";
 import { escapeHtml } from "./interpolation.js";
 import { selectMd } from "./markdown.js";
+import { memoryReader } from "./reader.js";
 
 /**
  * @typedef {import("./context.js").Paths} Paths
@@ -42,16 +43,20 @@ const SKIP_LINK_STYLE =
  * Compile a page source file into a full HTML document plus its assets.
  * @param {string} file Absolute path to the source `.md`/`.wd` file.
  * @param {Paths} context Resolved project paths.
- * @param {{ feed?: { href: string, title: string }, collections?: Map<string, import("./collections.js").CollectionRow[]>, vars?: Record<string, unknown> }} [options]
+ * @param {{ feed?: { href: string, title: string }, collections?: Map<string, import("./collections.js").CollectionRow[]>, vars?: Record<string, unknown>, reader?: import("./reader.js").Reader }} [options]
  *   When a site-wide RSS feed is emitted (the home page set `site_url` and the
  *   site has dated posts), `feed` carries its absolute href + title so every page
  *   links it. `collections` is the build-time collection index a bare-name
  *   `@loop` resolves against; `vars` seeds the document scope (the pager `page`
- *   object on a paginated route).
+ *   object on a paginated route). `reader` is the source reader (fs-backed by
+ *   default via `src/compiler.js`; in-memory for `compileFromMemory`).
  * @returns {CompiledPage}
  */
 export function compilePage(file, context, options = {}) {
-  const compiled = compileDocument(file, context, [], options.vars, options.collections);
+  // The raw entry point requires a reader — the Node barrel (`src/compiler.js`)
+  // injects `fsReader()`, and `compileFromMemory` injects a `memoryReader`.
+  const reader = /** @type {import("./reader.js").Reader} */ (options.reader);
+  const compiled = compileDocument(file, context, [], options.vars, options.collections, reader);
   const title = compiled.meta.title || "Darkmown";
   const description = compiled.meta.description || "";
   // Per-page document language for the `<html lang>` attribute (`lang: fr` in
@@ -155,10 +160,10 @@ export function compilePage(file, context, options = {}) {
   // body so its scoped selectors match. Pure compile-time string post-pass (like
   // enhanceImages) — no runtime, no `data-wd-*` marker, so a static page stays
   // static. Include-scoped skins are stamped earlier, in handleInclude.
-  const scopedSkin = scopedSkinFor(file, context);
+  const scopedSkin = scopedSkinFor(file, context, reader);
   const stamped =
     scopedSkin && scopedSkin.scoped ? stampScope(compiled.html, scopedSkin.scopeId) : compiled.html;
-  const body = enhanceImages(stamped, context);
+  const body = enhanceImages(stamped, context, reader);
   const { content, target } = ensureMainLandmark(body);
 
   return {
@@ -216,9 +221,10 @@ function ensureMainLandmark(html) {
  * lazy-load. Author-set attributes are never overwritten.
  * @param {string} html Assembled page body HTML.
  * @param {Paths} paths Resolved project paths.
+ * @param {import("./reader.js").Reader} reader Source reader for the image bytes.
  * @returns {string}
  */
-export function enhanceImages(html, paths) {
+export function enhanceImages(html, paths, reader) {
   let index = 0;
   return html.replace(/<img\b[^>]*?\/?>/g, (tag) => {
     const i = index++;
@@ -228,7 +234,7 @@ export function enhanceImages(html, paths) {
     // Dimensions only when the author hasn't sized it — adding one axis to a
     // manually-sized image would distort its aspect ratio.
     if (!has("width") && !has("height")) {
-      const dim = measureImage(srcOf(tag), paths);
+      const dim = measureImage(srcOf(tag), paths, reader);
       if (dim) add.push(`width="${dim.width}"`, `height="${dim.height}"`);
     }
     if (!has("decoding")) add.push(`decoding="async"`);
@@ -259,9 +265,10 @@ function srcOf(tag) {
  * comes from the shelf (`site/_`), other absolute paths from `site/pages`.
  * @param {string} src
  * @param {Paths} paths
+ * @param {import("./reader.js").Reader} reader
  * @returns {{ width: number, height: number } | null}
  */
-function measureImage(src, paths) {
+function measureImage(src, paths, reader) {
   if (!src || /^(https?:)?\/\//i.test(src) || src.startsWith("data:")) return null;
   let filePath;
   if (src.startsWith("/__wd/media/")) {
@@ -272,7 +279,7 @@ function measureImage(src, paths) {
     return null; // page-relative: the source directory is lost after assembly
   }
   try {
-    const { width, height } = imageSize(fs.readFileSync(filePath));
+    const { width, height } = imageSize(reader.readBinary(filePath));
     if (typeof width === "number" && typeof height === "number") return { width, height };
   } catch {
     /* missing or unreadable — degrade to no dimensions */
@@ -288,12 +295,34 @@ function measureImage(src, paths) {
  * @param {Record<string, unknown>} [vars] Initial static scope variables.
  * @param {Map<string, import("./collections.js").CollectionRow[]>} [collections]
  *   Build-time collection index a bare-name `@loop` resolves against.
+ * @param {import("./reader.js").Reader} [reader] Source reader (fs-backed when
+ *   omitted via `src/compiler.js`; in-memory for `compileFromMemory`).
  * @returns {CompiledDocument}
  */
-export function compileDocument(file, context, stack = [], vars = {}, collections = new Map()) {
-  const comp = createCompilation();
+export function compileDocument(
+  file,
+  context,
+  stack = [],
+  vars = {},
+  collections = new Map(),
+  reader
+) {
+  // reader is injected by every caller (the Node barrel's `fsReader()` or
+  // `compileFromMemory`'s `memoryReader`); it is only trailing-optional here so
+  // the defaulted `vars`/`collections` params can precede it.
+  const comp = createCompilation(/** @type {import("./reader.js").Reader} */ (reader));
   comp.collections = collections;
-  const result = compileFile(file, context, stack, createScope(null, vars), comp, [], null);
+  const result = compileFile(
+    file,
+    context,
+    stack,
+    createScope(null, vars),
+    comp,
+    [],
+    null,
+    0,
+    null
+  );
   return {
     meta: result.meta,
     html: result.html,
@@ -314,21 +343,36 @@ export function compileDocument(file, context, stack = [], vars = {}, collection
  * @param {Compilation} comp
  * @param {string[]} sections
  * @param {string | null} loopItem
+ * @param {number} [reactiveDepth] Enclosing REACTIVE `@loop` levels, threaded in
+ *   from the including page so an include's body can't bypass the two-level
+ *   reactive-nesting limit at the `@include` boundary.
+ * @param {{ at: string, line: string } | null} [loopOpener] The enclosing `@loop`
+ *   opener, threaded in so a depth error inside the include names the right opener.
  * @returns {{ meta: Meta, html: string }}
  */
-export function compileFile(file, context, stack, scope, comp, sections, loopItem) {
-  const real = fs.realpathSync(file);
+export function compileFile(
+  file,
+  context,
+  stack,
+  scope,
+  comp,
+  sections,
+  loopItem,
+  reactiveDepth = 0,
+  loopOpener = null
+) {
+  const real = comp.reader.realpath(file);
   if (stack.includes(real)) {
     throw new Error(
       `Include cycle detected: ${[...stack, real].map((p) => path.basename(p)).join(" -> ")}`
     );
   }
 
-  const raw = fs.readFileSync(file, "utf8");
+  const raw = comp.reader.readText(file);
   const { meta, body, bodyLine } = parseFrontmatter(raw, file);
   warnLikelyFrontmatter(raw, file, comp);
   comp.deps.add(file);
-  collectColocatedAssets(file, context, comp.assets);
+  collectColocatedAssets(file, context, comp.assets, comp.reader);
 
   if (path.extname(file) === ".md") {
     scanMarkdownHints(body, file, comp);
@@ -351,6 +395,8 @@ export function compileFile(file, context, stack, scope, comp, sections, loopIte
     comp,
     sections,
     loopItem,
+    reactiveDepth,
+    ...(loopOpener ? { loopOpener } : {}),
     md: selectMd(meta),
     compileBody,
     compileFile
@@ -359,3 +405,37 @@ export function compileFile(file, context, stack, scope, comp, sections, loopIte
   if (htmlHasHighlight(html)) comp.assets.hasCode = true;
   return { meta, html };
 }
+
+/**
+ * Compile a page entirely from an in-memory file map — no filesystem, no
+ * `node:fs`. `files` maps PROJECT-RELATIVE POSIX paths (`site/pages/index.wd`,
+ * `site/_/nav.wd`) to their source strings; `entryPath` is the project-relative
+ * path of the page to compile. Includes, colocated `.skin`/`.js` detection, and
+ * `@loop` JSON-data reads all resolve against the same map (anything not in it
+ * is simply "absent"), so `@include`s work as long as their targets are present.
+ *
+ * This is the strategic fs-free entry point the browser playground and a planned
+ * mobile host use: the entire module graph reachable from here is free of
+ * `node:fs`, so it bundles for the browser. It returns the same
+ * {@link CompiledPage} shape as {@link compilePage} and throws the same
+ * `file:line` compile errors, so the error DX is identical in-browser.
+ * @param {Record<string, string> | Map<string, string>} files Project-relative
+ *   path → source content.
+ * @param {string} entryPath Project-relative path of the page to compile.
+ * @param {{ feed?: { href: string, title: string }, collections?: Map<string, import("./collections.js").CollectionRow[]>, vars?: Record<string, unknown>, cwd?: string }} [options]
+ *   Same shell options as {@link compilePage}; `cwd` overrides the virtual
+ *   project root the relative keys resolve against (defaults to `/`).
+ * @returns {CompiledPage}
+ */
+export function compileFromMemory(files, entryPath, options = {}) {
+  const cwd = options.cwd ?? "/";
+  const reader = memoryReader(files, cwd);
+  const context = createPaths(cwd);
+  const abs = path.resolve(cwd, entryPath);
+  return compilePage(abs, context, {
+    feed: options.feed,
+    collections: options.collections,
+    vars: options.vars,
+    reader
+  });
+}

package/src/compiler/predicates.js

@@ -5,6 +5,7 @@
 // readers — no identifier survives un-mapped, so no raw user content is eval'd.
 // ---------------------------------------------------------------------------
 
+import { astOf, evalAst } from "./expr-ast.js";
 import { getPath, lookupVar, resolveStateKey } from "./interpolation.js";
 
 /**
@@ -93,14 +94,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 +104,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.`

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

@@ -9,8 +9,8 @@
 // ---------------------------------------------------------------------------
 
 import { at } from "./context.js";
-import { FORMATTERS } from "./format.js";
-import { escapeHtml, getPath, parseStateValue, safeScriptJson } from "./interpolation.js";
+import { astOf, evalAst } from "./expr-ast.js";
+import { escapeHtml, parseStateValue, safeScriptJson } from "./interpolation.js";
 import { compileComputedExpr } from "./predicates.js";
 
 /**
@@ -119,27 +119,25 @@ export function handleComputed(line, ctx, index) {
       `Malformed :computed in ${at(ctx, index)}: ${line}. Use: :computed total = items.length * 4`
     );
   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 new Error(
+      `Malformed :computed expression in ${at(ctx, index)}: ${line}. Use: :computed total = items.length * 4`
     );
-    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>`;
 }
 
 /**