@jxsuite/compiler 0.27.0 → 0.28.2

package/src/site/format-host.ts

@@ -0,0 +1,84 @@
+/**
+ * Format-host — node-side FormatHostIO and project registry construction
+ *
+ * Provides the filesystem/module I/O the shared format registry needs to run inside the compiler
+ * (and dev server). Format classes are auto-discovered from the project-level imports map; see
+ * specs/extensions.md.
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname, resolve, isAbsolute, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { createRequire } from "node:module";
+import {
+  buildFormatRegistry,
+  type FormatRegistry,
+  type FormatHostIO,
+} from "@jxsuite/schema/format-registry";
+import type { ProjectConfig } from "@jxsuite/schema/types";
+
+export type { FormatRegistry, FormatEntry } from "@jxsuite/schema/format-registry";
+
+/**
+ * Import a class $implementation module by absolute path, tolerating source-vs-built layouts. A
+ * `.class.json` typically declares `"$implementation": "./markdown.js"` next to its TypeScript
+ * source: under Bun the sibling `.ts` resolves directly, while under node the built module lives in
+ * the package's `dist/` directory. Tries, in order: the literal path, src/ → dist/, .js → .ts.
+ *
+ * @param {string} path - Absolute path to the implementation module
+ * @returns {Promise<Record<string, unknown>>}
+ */
+export async function importImplementation(path: string): Promise<Record<string, unknown>> {
+  const candidates = [path];
+  const srcSeg = `${sep}src${sep}`;
+  const distSeg = `${sep}dist${sep}`;
+  if (path.includes(srcSeg)) candidates.push(path.replace(srcSeg, distSeg));
+  if (path.endsWith(".js")) candidates.push(path.slice(0, -3) + ".ts");
+
+  let lastError: unknown;
+  for (const candidate of candidates) {
+    try {
+      return await import(pathToFileURL(candidate).href);
+    } catch (e) {
+      lastError = e;
+    }
+  }
+  throw lastError;
+}
+
+/** Create a node FormatHostIO rooted at a project (bare specifiers resolve via node_modules). */
+export function createNodeFormatIO(projectRoot: string): FormatHostIO {
+  return {
+    loadJson: async (path) => JSON.parse(readFileSync(path, "utf-8")),
+    importModule: (path) => importImplementation(path),
+    resolvePath: (base, ref) => {
+      if (ref.startsWith("./") || ref.startsWith("../")) {
+        return resolve(dirname(base), ref);
+      }
+      if (isAbsolute(ref)) return ref;
+      const require = createRequire(resolve(projectRoot, "package.json"));
+      return require.resolve(ref);
+    },
+  };
+}
+
+/** Build the format registry for a project from its project.json imports map. */
+export async function buildProjectFormatRegistry(
+  projectRoot: string,
+  projectConfig?: ProjectConfig,
+): Promise<FormatRegistry> {
+  return buildFormatRegistry(
+    projectConfig?.imports as Record<string, string> | undefined,
+    createNodeFormatIO(projectRoot),
+    resolve(projectRoot, "project.json"),
+  );
+}
+
+/** Error message for an unregistered non-JSON extension, naming the fix. */
+export function unknownFormatError(path: string, ext: string): Error {
+  return new Error(
+    `No format class imported for "${ext}" (${path}). ` +
+      `Add a format class to project.json imports, e.g. ` +
+      `"Markdown": "@jxsuite/parser/Markdown.class.json".`,
+  );
+}

package/src/site/head-merger.ts

@@ -37,7 +37,10 @@ export function mergeHead(
     { tagName: "meta", attributes: { charset: context.charset ?? "utf-8" } },
     {
       tagName: "meta",
-      attributes: { name: "viewport", content: "width=device-width, initial-scale=1" },
+      attributes: {
+        name: "viewport",
+        content: "width=device-width, initial-scale=1",
+      },
     },
   ];
 

package/src/site/image-optimizer.ts

@@ -30,6 +30,13 @@ export interface ImageConfig {
   quality: { webp?: number; avif?: number; jpeg?: number; png?: number };
   sizes: string;
   lazyLoad: boolean;
+  service?: "build" | "cloudflare";
+  /**
+   * Hostnames whose remote (https) images are routed through the optimization pipeline. Cloudflare
+   * service only — allowlisted remote sources get /cdn-cgi/image transform srcsets (the zone must
+   * permit resizing from the remote origin); everything else is left untouched.
+   */
+  remoteDomains?: string[];
 }
 
 let _sharp: typeof import("sharp") | null = null;

package/src/site/image-transform.ts

@@ -8,7 +8,13 @@
 
 import { existsSync } from "node:fs";
 import { resolve, extname, basename } from "node:path";
-import { processImage, buildSrcset, contentHash, configHash } from "./image-optimizer.ts";
+import {
+  processImage,
+  buildSrcset,
+  contentHash,
+  configHash,
+  getImageMetadata,
+} from "./image-optimizer.ts";
 import { getCached, setCached, getImageCacheDir } from "./image-cache.ts";
 
 import type { ImageConfig } from "./image-optimizer.ts";
@@ -20,6 +26,60 @@ import type { JxDocument } from "@jxsuite/schema/types";
 const SKIP_EXTENSIONS = new Set([".svg", ".gif"]);
 const EXTERNAL_PREFIXES = ["http://", "https://", "data:", "//"];
 
+/** Per-build memo of original image dimensions + content hash (cloudflare mode). */
+export type ImageMetaCache = Map<string, { width: number; height: number; hash: string }>;
+
+/**
+ * Resolve original image dimensions and content hash for cloudflare mode. Reads only the image
+ * header via Sharp — no variants are generated.
+ *
+ * @param {string} absoluteSrc
+ * @param {ImageMetaCache} metaCache
+ * @returns {Promise<{ width: number; height: number; hash: string }>}
+ */
+async function resolveCfMeta(absoluteSrc: string, metaCache: ImageMetaCache) {
+  let meta = metaCache.get(absoluteSrc);
+  if (!meta) {
+    const m = await getImageMetadata(absoluteSrc);
+    meta = { width: m.width, height: m.height, hash: contentHash(absoluteSrc) };
+    metaCache.set(absoluteSrc, meta);
+  }
+  return meta;
+}
+
+/**
+ * Build a srcset of Cloudflare `/cdn-cgi/image/` transform-via-URL entries for the configured
+ * widths that fit within the original image width. `format=auto` lets Cloudflare negotiate
+ * AVIF/WebP per browser; `fit=scale-down` guards against upscaling. Requires Image Transformations
+ * to be enabled on the serving zone (does not work on *.pages.dev).
+ *
+ * @param {string} src - Site-relative src (e.g. "/images/hero.png") or allowlisted https URL
+ * @param {ImageConfig} config
+ * @param {number} originalWidth
+ * @param {string | null} hash - 8-char content hash for cache busting (null for remote sources,
+ *   whose bytes aren't available at build time)
+ * @returns {string}
+ */
+function buildCloudflareSrcset(
+  src: string,
+  config: ImageConfig,
+  originalWidth: number,
+  hash: string | null,
+) {
+  const quality = config.quality?.webp ?? 80;
+  const separator = src.startsWith("/") ? "" : "/";
+  const suffix = hash ? `?v=${hash}` : "";
+  return config.widths
+    .filter((w) => w <= originalWidth)
+    .sort((a, b) => a - b)
+    .map(
+      (w) =>
+        `/cdn-cgi/image/width=${w},quality=${quality},fit=scale-down,format=auto` +
+        `${separator}${src}${suffix} ${w}w`,
+    )
+    .join(", ");
+}
+
 /**
  * @param {string} absoluteSrc
  * @param {string} src
@@ -64,6 +124,31 @@ function shouldSkip(src: string) {
   return false;
 }
 
+/**
+ * Check if a remote src is eligible for cloudflare-service optimization: an https URL whose
+ * hostname is in the project's `images.remoteDomains` allowlist. Content data (e.g. CSV columns)
+ * routinely references externally hosted images — allowlisted hosts flow through the /cdn-cgi/image
+ * transform URL like local assets; everything else passes through untouched. The zone must permit
+ * resizing from the remote origin (Images → Transformations → Sources).
+ *
+ * @param {string} src
+ * @param {ImageConfig} config
+ * @returns {boolean}
+ */
+function isAllowedRemote(src: string, config: ImageConfig) {
+  if (config.service !== "cloudflare") return false;
+  if (!config.remoteDomains?.length) return false;
+  if (typeof src !== "string" || !src.startsWith("https://")) return false;
+  if (src.includes("${")) return false;
+  try {
+    const url = new URL(src);
+    if (SKIP_EXTENSIONS.has(extname(url.pathname).toLowerCase())) return false;
+    return config.remoteDomains.includes(url.hostname);
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Resolve a src path to an absolute filesystem path.
  *
@@ -90,20 +175,23 @@ function resolveImagePath(src: string, projectRoot: string) {
  * @param {JxMutableNode | JxDocument} doc - The Jx document tree (mutated in place)
  * @param {ImageConfig} config
  * @param {string} projectRoot
- * @param {CacheManifest} cache
+ * @param {CacheManifest | null} cache - Variant cache (build mode); unused in cloudflare mode
+ * @param {ImageMetaCache} [metaCache] - Dimension/hash memo (cloudflare mode)
  * @returns {Promise<{ imageRefs: Map<string, ImageManifest> }>}
  */
 export async function transformImageNodes(
   doc: JxMutableNode | JxDocument,
   config: ImageConfig,
   projectRoot: string,
-  cache: CacheManifest,
+  cache: CacheManifest | null,
+  metaCache?: ImageMetaCache,
 ) {
   const imageRefs: Map<string, ImageManifest> = new Map();
 
   if (!config.optimize) return { imageRefs };
 
-  await walkAndTransform(doc, config, projectRoot, cache, imageRefs);
+  const meta = metaCache ?? new Map();
+  await walkAndTransform(doc, config, projectRoot, cache, meta, imageRefs);
 
   return { imageRefs };
 }
@@ -112,20 +200,22 @@ export async function transformImageNodes(
  * @param {JxMutableNode | JxDocument} node
  * @param {ImageConfig} config
  * @param {string} projectRoot
- * @param {CacheManifest} cache
+ * @param {CacheManifest | null} cache
+ * @param {ImageMetaCache} metaCache
  * @param {Map<string, ImageManifest>} imageRefs
  */
 async function walkAndTransform(
   node: JxMutableNode | JxDocument,
   config: ImageConfig,
   projectRoot: string,
-  cache: CacheManifest,
+  cache: CacheManifest | null,
+  metaCache: ImageMetaCache,
   imageRefs: Map<string, ImageManifest>,
 ) {
   if (!node || typeof node !== "object") return;
 
   if (node.tagName === "img") {
-    await transformImgNode(node, config, projectRoot, cache, imageRefs);
+    await transformImgNode(node, config, projectRoot, cache, metaCache, imageRefs);
   }
 
   if (typeof node.innerHTML === "string" && node.innerHTML.includes("<img")) {
@@ -134,6 +224,7 @@ async function walkAndTransform(
       config,
       projectRoot,
       cache,
+      metaCache,
       imageRefs,
     );
   }
@@ -141,7 +232,7 @@ async function walkAndTransform(
   if (Array.isArray(node.children)) {
     for (const child of node.children) {
       if (typeof child === "string") continue;
-      await walkAndTransform(child, config, projectRoot, cache, imageRefs);
+      await walkAndTransform(child, config, projectRoot, cache, metaCache, imageRefs);
     }
   }
 }
@@ -150,45 +241,62 @@ async function walkAndTransform(
  * @param {JxMutableNode | JxDocument} node
  * @param {ImageConfig} config
  * @param {string} projectRoot
- * @param {CacheManifest} cache
+ * @param {CacheManifest | null} cache
+ * @param {ImageMetaCache} metaCache
  * @param {Map<string, ImageManifest>} imageRefs
  */
 async function transformImgNode(
   node: JxMutableNode | JxDocument,
   config: ImageConfig,
   projectRoot: string,
-  cache: CacheManifest,
+  cache: CacheManifest | null,
+  metaCache: ImageMetaCache,
   imageRefs: Map<string, ImageManifest>,
 ) {
   if (!node.attributes) node.attributes = {};
 
   const src = node.attributes.src ?? node.src;
-  if (shouldSkip(src)) return;
+  const remote = isAllowedRemote(src, config);
+  if (!remote && shouldSkip(src)) return;
   if (node.attributes["data-no-optimize"] !== undefined) return;
 
-  const absoluteSrc = resolveImagePath(src, projectRoot);
-  if (!existsSync(absoluteSrc)) return;
+  const absoluteSrc = remote ? null : resolveImagePath(src, projectRoot);
+  if (absoluteSrc && !existsSync(absoluteSrc)) return;
 
-  let manifest = imageRefs.get(absoluteSrc);
+  let srcset;
+  let original: { width: number; height: number } | undefined;
 
-  if (!manifest) {
-    manifest = await resolveManifest(absoluteSrc, src, config, projectRoot, cache);
-    imageRefs.set(absoluteSrc, manifest);
-  }
+  if (remote) {
+    // Original dimensions are unknown without fetching — emit every configured width and let
+    // fit=scale-down avoid upscaling past the source size.
+    srcset = buildCloudflareSrcset(src, config, Infinity, null);
+  } else if (config.service === "cloudflare") {
+    const meta = await resolveCfMeta(absoluteSrc as string, metaCache);
+    srcset = buildCloudflareSrcset(src, config, meta.width, meta.hash);
+    original = meta;
+  } else {
+    let manifest = imageRefs.get(absoluteSrc as string);
 
-  const preferredFormat = config.formats.includes("avif") ? "avif" : config.formats[0];
-  const srcset = buildSrcset(manifest.variants, preferredFormat);
+    if (!manifest) {
+      manifest = await resolveManifest(absoluteSrc as string, src, config, projectRoot, cache!);
+      imageRefs.set(absoluteSrc as string, manifest);
+    }
+
+    const preferredFormat = config.formats.includes("avif") ? "avif" : config.formats[0];
+    srcset = buildSrcset(manifest.variants, preferredFormat);
+    original = manifest.original;
+  }
 
   if (srcset) {
     node.attributes.srcset = srcset;
     node.attributes.sizes = node.attributes.sizes ?? config.sizes;
   }
 
-  if (!node.attributes.width && manifest.original?.width) {
-    node.attributes.width = String(manifest.original.width);
+  if (!node.attributes.width && original?.width) {
+    node.attributes.width = String(original.width);
   }
-  if (!node.attributes.height && manifest.original?.height) {
-    node.attributes.height = String(manifest.original.height);
+  if (!node.attributes.height && original?.height) {
+    node.attributes.height = String(original.height);
   }
 
   if (config.lazyLoad && node.attributes.loading !== "eager") {
@@ -208,7 +316,8 @@ const DATA_NO_OPT_RE = /\bdata-no-optimize\b/;
  * @param {string} html
  * @param {ImageConfig} config
  * @param {string} projectRoot
- * @param {CacheManifest} cache
+ * @param {CacheManifest | null} cache
+ * @param {ImageMetaCache} metaCache
  * @param {Map<string, ImageManifest>} imageRefs
  * @returns {Promise<string>}
  */
@@ -216,7 +325,8 @@ async function transformInnerHtmlImages(
   html: string,
   config: ImageConfig,
   projectRoot: string,
-  cache: CacheManifest,
+  cache: CacheManifest | null,
+  metaCache: ImageMetaCache,
   imageRefs: Map<string, ImageManifest>,
 ) {
   /** @type {{ match: string; replacement: string }[]} */
@@ -232,28 +342,42 @@ async function transformInnerHtmlImages(
     const srcMatch = attrs.match(SRC_ATTR_RE);
     if (!srcMatch) continue;
 
-    const src = srcMatch[1];
-    if (shouldSkip(src)) continue;
-
-    const absoluteSrc = resolveImagePath(src, projectRoot);
-    if (!existsSync(absoluteSrc)) continue;
-
-    let manifest = imageRefs.get(absoluteSrc);
-    if (!manifest) {
-      manifest = await resolveManifest(absoluteSrc, src, config, projectRoot, cache);
-      imageRefs.set(absoluteSrc, manifest);
+    // Attribute values in pre-rendered innerHTML are entity-escaped — decode for processing
+    const src = srcMatch[1].replaceAll("&amp;", "&");
+    const remote = isAllowedRemote(src, config);
+    if (!remote && shouldSkip(src)) continue;
+
+    const absoluteSrc = remote ? null : resolveImagePath(src, projectRoot);
+    if (absoluteSrc && !existsSync(absoluteSrc)) continue;
+
+    let srcset;
+    let original: { width: number; height: number } | undefined;
+
+    if (remote) {
+      srcset = buildCloudflareSrcset(src, config, Infinity, null);
+    } else if (config.service === "cloudflare") {
+      const meta = await resolveCfMeta(absoluteSrc as string, metaCache);
+      srcset = buildCloudflareSrcset(src, config, meta.width, meta.hash);
+      original = meta;
+    } else {
+      let manifest = imageRefs.get(absoluteSrc as string);
+      if (!manifest) {
+        manifest = await resolveManifest(absoluteSrc as string, src, config, projectRoot, cache!);
+        imageRefs.set(absoluteSrc as string, manifest);
+      }
+
+      const preferredFormat = config.formats.includes("avif") ? "avif" : config.formats[0];
+      srcset = buildSrcset(manifest.variants, preferredFormat);
+      original = manifest.original;
     }
-
-    const preferredFormat = config.formats.includes("avif") ? "avif" : config.formats[0];
-    const srcset = buildSrcset(manifest.variants, preferredFormat);
     if (!srcset) continue;
 
     let extra = ` srcset="${srcset}" sizes="${config.sizes}"`;
-    if (!/\bwidth=/.test(attrs) && manifest.original?.width) {
-      extra += ` width="${manifest.original.width}"`;
+    if (!/\bwidth=/.test(attrs) && original?.width) {
+      extra += ` width="${original.width}"`;
     }
-    if (!/\bheight=/.test(attrs) && manifest.original?.height) {
-      extra += ` height="${manifest.original.height}"`;
+    if (!/\bheight=/.test(attrs) && original?.height) {
+      extra += ` height="${original.height}"`;
     }
     if (config.lazyLoad && !/\bloading="eager"/.test(attrs)) {
       if (!/\bloading=/.test(attrs)) extra += ` loading="lazy"`;

package/src/site/pages-discovery.ts

@@ -1,8 +1,10 @@
 /**
  * Pages-discovery.js — File-based route discovery
  *
- * Scans the pages/ directory and builds a route table mapping URL paths to their source JSON files,
- * layouts, and metadata.
+ * Scans the pages/ directory and builds a route table mapping URL paths to their source files,
+ * layouts, and metadata. `.json` pages are native; any other extension must be claimed by a format
+ * class (with the `parse` capability and a "page" document kind) registered from the project's
+ * imports map.
  *
  * Conventions (per site-architecture spec §4): pages/index.json → / pages/about.json → /about
  * pages/about/index.json → /about pages/blog/[slug].json → /blog/:slug (dynamic)
@@ -12,11 +14,13 @@
 
 import { readdirSync, readFileSync } from "node:fs";
 import { resolve, relative, extname, join } from "node:path";
+import type { FormatRegistry } from "@jxsuite/schema/format-registry";
+import type { JxDocument } from "@jxsuite/schema/types";
 import type { ContentLoaderEntry } from "@jxsuite/parser/types";
 
 interface Route {
   urlPattern: string; // URL pattern (e.g. "/blog/:slug")
-  sourcePath: string; // Absolute path to the .json source file
+  sourcePath: string; // Absolute path to the source file
   relativePath: string; // Path relative to pages/ dir
   isDynamic: boolean; // Whether route has parameters
   isCatchAll: boolean; // Whether route uses [...param] spread
@@ -25,15 +29,45 @@ interface Route {
   _pathParams?: Record<string, string>; // Resolved path parameters
 }
 
+/**
+ * Read a page document, dispatching by extension: .json natively, anything else via the format
+ * registry's parse capability.
+ *
+ * @param {string} filePath - Absolute path to the page source
+ * @param {FormatRegistry} [registry]
+ * @returns {Promise<JxDocument>}
+ */
+export async function readPageDocument(
+  filePath: string,
+  registry?: FormatRegistry,
+): Promise<JxDocument> {
+  const source = readFileSync(filePath, "utf8");
+  if (filePath.endsWith(".json")) {
+    return JSON.parse(source);
+  }
+  const ext = extname(filePath).toLowerCase();
+  const entry = registry?.byExtension(ext, "parse");
+  if (!entry) {
+    throw new Error(
+      `No format class imported for "${ext}" (${filePath}). ` +
+        `Add a format class to project.json imports, e.g. ` +
+        `"Markdown": "@jxsuite/parser/Markdown.class.json".`,
+    );
+  }
+  return (await entry.call("parse", source)) as JxDocument;
+}
+
 /**
  * Discover all routable pages in a pages/ directory.
  *
  * @param {string} pagesDir - Absolute path to the pages/ directory
- * @returns {Route[]} Sorted route table (static routes first, then dynamic)
+ * @param {FormatRegistry} [registry] - Format registry; its "page"-kind extensions are routable
+ * @returns {Promise<Route[]>} Sorted route table (static routes first, then dynamic)
  */
-export function discoverPages(pagesDir: string) {
+export async function discoverPages(pagesDir: string, registry?: FormatRegistry) {
   const routes: Route[] = [];
-  walkDir(pagesDir, pagesDir, routes);
+  const pageExtensions = new Set([".json", ...(registry?.documentExtensions("page") ?? [])]);
+  await walkDir(pagesDir, pagesDir, routes, pageExtensions, registry);
 
   // Sort: static routes first, then by specificity (more segments = more specific)
   routes.sort((a, b) => {
@@ -51,8 +85,16 @@ export function discoverPages(pagesDir: string) {
  * @param {string} dir
  * @param {string} pagesRoot
  * @param {Route[]} routes
+ * @param {Set<string>} pageExtensions
+ * @param {FormatRegistry} [registry]
  */
-function walkDir(dir: string, pagesRoot: string, routes: Route[]) {
+async function walkDir(
+  dir: string,
+  pagesRoot: string,
+  routes: Route[],
+  pageExtensions: Set<string>,
+  registry?: FormatRegistry,
+) {
   const entries = readdirSync(dir, { withFileTypes: true });
 
   for (const entry of entries) {
@@ -61,19 +103,19 @@ function walkDir(dir: string, pagesRoot: string, routes: Route[]) {
     if (entry.isDirectory()) {
       // Skip underscore-prefixed directories
       if (entry.name.startsWith("_")) continue;
-      walkDir(fullPath, pagesRoot, routes);
+      await walkDir(fullPath, pagesRoot, routes, pageExtensions, registry);
       continue;
     }
 
-    // Only process .json and .md files
-    const ext = extname(entry.name);
-    if (ext !== ".json" && ext !== ".md") continue;
+    // Only process .json and registered page-format files
+    const ext = extname(entry.name).toLowerCase();
+    if (!pageExtensions.has(ext)) continue;
 
     // Skip underscore-prefixed files (local components, not routes)
     if (entry.name.startsWith("_")) continue;
 
     const relativePath = relative(pagesRoot, fullPath);
-    const route = fileToRoute(relativePath, fullPath);
+    const route = await fileToRoute(relativePath, fullPath, registry);
     if (route) routes.push(route);
   }
 }
@@ -83,11 +125,13 @@ function walkDir(dir: string, pagesRoot: string, routes: Route[]) {
  *
  * @param {string} relativePath - E.g. "blog/[slug].json"
  * @param {string} absolutePath - Full filesystem path
- * @returns {Route}
+ * @param {FormatRegistry} [registry]
+ * @returns {Promise<Route>}
  */
-function fileToRoute(relativePath: string, absolutePath: string) {
-  // Remove .json or .md extension
-  let urlPath = relativePath.replace(/\.(json|md)$/, "");
+async function fileToRoute(relativePath: string, absolutePath: string, registry?: FormatRegistry) {
+  // Remove the source extension
+  const ext = extname(relativePath);
+  let urlPath = ext ? relativePath.slice(0, -ext.length) : relativePath;
 
   // Normalize path separators
   urlPath = urlPath.split("\\").join("/");
@@ -127,20 +171,9 @@ function fileToRoute(relativePath: string, absolutePath: string) {
   /** @type {string | null} */
   let $layout = null;
   try {
-    const source = readFileSync(absolutePath, "utf8");
-    if (absolutePath.endsWith(".md")) {
-      // Parse YAML frontmatter for $layout
-      const fmMatch = source.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-      if (fmMatch) {
-        // Quick regex extraction — avoids full YAML dependency
-        const layoutMatch = fmMatch[1].match(/^\$layout:\s*(.+)/m);
-        if (layoutMatch) $layout = layoutMatch[1].trim().replace(/^['"]|['"]$/g, "");
-      }
-    } else {
-      const raw = JSON.parse(source);
-      if (typeof raw.$layout === "string") {
-        $layout = raw.$layout;
-      }
+    const doc = await readPageDocument(absolutePath, registry);
+    if (typeof doc.$layout === "string") {
+      $layout = doc.$layout;
     }
   } catch {
     // Skip unreadable files — will error during compilation
@@ -168,12 +201,14 @@ function fileToRoute(relativePath: string, absolutePath: string) {
  * @param {Route[]} routes - Discovered route table
  * @param {string} projectRoot - Project root for resolving $ref paths
  * @param {Map<string, any[]>} [contentTypes] - Loaded content types (from content-loader)
+ * @param {FormatRegistry} [registry] - Format registry for reading non-JSON dynamic pages
  * @returns {Promise<Route[]>} Expanded routes with concrete paths
  */
 export async function expandDynamicRoutes(
   routes: Route[],
   projectRoot: string,
   contentTypes: Map<string, any[]> = new Map(),
+  registry?: FormatRegistry,
 ) {
   const expanded: Route[] = [];
 
@@ -187,7 +222,7 @@ export async function expandDynamicRoutes(
     /** @type {Record<string, unknown>} */
     let raw;
     try {
-      raw = JSON.parse(readFileSync(route.sourcePath, "utf8"));
+      raw = await readPageDocument(route.sourcePath, registry);
     } catch {
       expanded.push(route);
       continue;