@zvndev/darkmown 2.0.1 → 2.2.0

package/src/compiler/forms.js

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

package/src/compiler/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,14 +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 {string} [loc] Source location (`file:line`) for the error messages, so
+ * @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)`; it defaults to `fromFile` (the bare
- *   path) for any caller without one, preserving the file-only message.
+ *   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, loc = fromFile) {
+export function resolveInclude(spec, fromFile, context, allowAny, loc, reader) {
   const clean = stripQuotes(spec);
   const candidates = [];
   if (clean.startsWith("/")) {
@@ -178,7 +183,7 @@ export function resolveInclude(spec, fromFile, context, allowAny = false, loc =
     if (!isAllowedInclude(resolved, context)) {
       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;
   }

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 { at, createScope, lineOf, nestedCtx, wdError } from "./context.js";
+import { serializeExpr } from "./expr-ast.js";
 import { applyPipeline, stagesFromAttr } from "./format.js";
 import { resolveInclude } from "./includes.js";
 import {
@@ -28,9 +28,14 @@ import { compilePredicate, evalPredicate } from "./predicates.js";
  * @typedef {import("./context.js").LoopOpts} LoopOpts
  */
 
+// One concrete, compilable @loop line, appended to the schematic hint so a small
+// model copies a real line instead of echoing the `[…]` placeholders literally
+// (the on-device finding: bracket-placeholders get pasted into source verbatim).
+// Also the canonical @loop example the directive catalog + grammar draw from.
+export const LOOP_EXAMPLE = "@loop /products.json into p where p.price < 50 sort by p.price asc";
+
 // The fixed corrective suggestion shown for any malformed @loop header.
-const LOOP_USAGE =
-  "Use: @loop src into item [where …] [sort by …] [reverse] [offset N] [limit N] [paginate N] [sortable]";
+const LOOP_USAGE = `Use: @loop src into item [where …] [sort by …] [reverse] [offset N] [limit N] [paginate N] [sortable] — e.g. ${LOOP_EXAMPLE}`;
 
 /**
  * Parse the optional clause tail of a `@loop` header in FIXED order:
@@ -219,7 +224,13 @@ function numArgAttr(arg) {
  */
 export function handleLoop(line, bodyLines, emptyLines, ctx, index, emptyStart = 0) {
   const match = line.match(/^@loop\s+(.+?)\s+into\s+([A-Za-z_$][\w$]*)(\s+.+?)?\s*$/);
-  if (!match) throw new Error(`Malformed @loop in ${at(ctx, index)}: ${line}. ${LOOP_USAGE}`);
+  if (!match)
+    throw wdError(`Malformed @loop in ${at(ctx, index)}: ${line}. ${LOOP_USAGE}`, {
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint: LOOP_USAGE.slice("Use: ".length),
+      example: LOOP_EXAMPLE
+    });
   const source = stripQuotes(match[1].trim());
   const itemName = match[2];
   const clauses = match[3]
@@ -288,9 +299,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, at(ctx, index));
+    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);
   }
@@ -692,7 +710,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)}"`
       : "") +

package/src/compiler/media.js

@@ -8,7 +8,7 @@
 // while keeping the message text and `Use:` hints intact.
 // ---------------------------------------------------------------------------
 
-import { at } from "./context.js";
+import { at, lineOf, wdError } from "./context.js";
 import { validateFetchUrl } from "./fetch.js";
 import { escapeHtml, stripQuotes } from "./interpolation.js";
 
@@ -16,6 +16,11 @@ import { escapeHtml, stripQuotes } from "./interpolation.js";
  * @typedef {import("./context.js").Ctx} Ctx
  */
 
+// Concrete, compilable media examples for the hint tails + the directive catalog.
+export const VIDEO_EXAMPLE = ":video /demo.mp4 controls";
+export const AUDIO_EXAMPLE = ":audio /theme.mp3 controls";
+export const EMBED_EXAMPLE = ':embed https://youtu.be/dQw4w9WgXcQ title="Demo"';
+
 /** @type {Record<"video" | "audio", { flags: string[], attrs: string[] }>} */
 const MEDIA_SPEC = {
   video: {
@@ -41,9 +46,14 @@ const MEDIA_SPEC = {
 export function handleMedia(line, kind, ctx, index) {
   const match = line.match(new RegExp(`^:${kind}\\s+(\\S+)\\s*(.*)$`));
   if (!match) {
-    throw new Error(
-      `Malformed :${kind} in ${at(ctx, index)}: ${line}. Use: :${kind} /clip [controls] [autoplay] [loop] [muted]`
-    );
+    const example = kind === "video" ? VIDEO_EXAMPLE : AUDIO_EXAMPLE;
+    const hint = `:${kind} /clip [controls] [autoplay] [loop] [muted] — e.g. ${example}`;
+    throw wdError(`Malformed :${kind} in ${at(ctx, index)}: ${line}. Use: ${hint}`, {
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint,
+      example
+    });
   }
   const src = validateFetchUrl(stripQuotes(match[1]), ctx, `:${kind}`);
   const spec = MEDIA_SPEC[kind];
@@ -93,9 +103,13 @@ export function handleMedia(line, kind, ctx, index) {
 export function handleEmbed(line, ctx, index) {
   const match = line.match(/^:embed\s+(\S+)\s*(.*)$/);
   if (!match) {
-    throw new Error(
-      `Malformed :embed in ${at(ctx, index)}: ${line}. Use: :embed https://youtu.be/ID [title="…"]`
-    );
+    const hint = `:embed https://youtu.be/ID [title="…"] — e.g. ${EMBED_EXAMPLE}`;
+    throw wdError(`Malformed :embed in ${at(ctx, index)}: ${line}. Use: ${hint}`, {
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint,
+      example: EMBED_EXAMPLE
+    });
   }
   const raw = stripQuotes(match[1]);
   let title = "";

package/src/compiler/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,10 +295,22 @@ 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,
@@ -342,18 +361,18 @@ export function compileFile(
   reactiveDepth = 0,
   loopOpener = null
 ) {
-  const real = fs.realpathSync(file);
+  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);
@@ -386,3 +405,37 @@ export function compileFile(
   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
+  });
+}