@jxsuite/compiler 0.26.2 → 0.28.0

package/src/site/image-optimizer.ts

@@ -30,6 +30,14 @@ export interface ImageConfig {
   quality: { webp?: number; avif?: number; jpeg?: number; png?: number };
   sizes: string;
   lazyLoad: boolean;
+  service?: "build" | "cloudflare";
+  binding?: string;
+  /**
+   * Hostnames whose remote (https) images are routed through the optimization pipeline. Cloudflare
+   * service only — the generated /_jx/image endpoint fetches and transforms allowlisted remote
+   * sources; everything else is rejected to prevent open-proxy use.
+   */
+  remoteDomains?: string[];
 }
 
 let _sharp: typeof import("sharp") | null = null;

package/src/site/image-transform.ts

@@ -7,8 +7,15 @@
  */
 
 import { existsSync } from "node:fs";
+import { createHash } from "node:crypto";
 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 +27,45 @@ 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 `/_jx/image` endpoint URLs for the configured widths that fit within the
+ * original image width. The `v` param carries the content hash for cache busting.
+ *
+ * @param {string} src - Original site-relative src (e.g. "/images/hero.png")
+ * @param {number[]} widths
+ * @param {number} originalWidth
+ * @param {string} hash - 8-char content hash
+ * @returns {string}
+ */
+function buildCloudflareSrcset(src: string, widths: number[], originalWidth: number, hash: string) {
+  return widths
+    .filter((w) => w <= originalWidth)
+    .sort((a, b) => a - b)
+    .map((w) => `/_jx/image?src=${encodeURIComponent(src)}&w=${w}&v=${hash} ${w}w`)
+    .join(", ");
+}
+
 /**
  * @param {string} absoluteSrc
  * @param {string} src
@@ -64,6 +110,35 @@ 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 /_jx/image
+ * endpoint like local assets; everything else passes through untouched.
+ *
+ * @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;
+  }
+}
+
+/** 8-char cache-busting hash for a remote URL (original bytes aren't available at build time). */
+function urlHash(src: string) {
+  return createHash("sha256").update(src).digest("hex").slice(0, 8);
+}
+
 /**
  * Resolve a src path to an absolute filesystem path.
  *
@@ -90,20 +165,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 +190,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 +214,7 @@ async function walkAndTransform(
       config,
       projectRoot,
       cache,
+      metaCache,
       imageRefs,
     );
   }
@@ -141,7 +222,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 +231,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
+    // the endpoint's scale-down fit avoid upscaling past the source size.
+    srcset = buildCloudflareSrcset(src, config.widths, Infinity, urlHash(src));
+  } else if (config.service === "cloudflare") {
+    const meta = await resolveCfMeta(absoluteSrc as string, metaCache);
+    srcset = buildCloudflareSrcset(src, config.widths, 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];
-  const srcset = buildSrcset(manifest.variants, preferredFormat);
+    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 +306,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 +315,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 +332,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.widths, Infinity, urlHash(src));
+    } else if (config.service === "cloudflare") {
+      const meta = await resolveCfMeta(absoluteSrc as string, metaCache);
+      srcset = buildCloudflareSrcset(src, config.widths, 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;
@@ -246,9 +281,11 @@ function resolvePathEntries($paths: any, projectRoot: string, contentTypes: Map<
     }
     const param = $paths.param ?? "slug";
     const field = $paths.field ?? "id";
-    return entries.map((entry: ContentLoaderEntry) => ({
-      [param]: field === "id" ? entry.id : (entry.data[field] ?? entry.id),
-    }));
+    return entries
+      .map((entry: ContentLoaderEntry) => ({
+        [param]: field === "id" ? entry.id : (entry.data[field] ?? entry.id),
+      }))
+      .filter((p: Record<string, unknown>) => p[param]);
   }
 
   // Explicit values: { values: ["en", "fr"], param: "lang" }

package/src/site/prototype-resolver.ts

@@ -16,8 +16,8 @@
 
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
-import { pathToFileURL } from "node:url";
 import { createRequire } from "node:module";
+import { importImplementation } from "./format-host.ts";
 import type { JxDocument, JxMutableNode } from "@jxsuite/schema/types";
 
 /**
@@ -59,7 +59,10 @@ export async function resolvePrototypes(
   doc: JxMutableNode | JxDocument,
   route: { sourcePath?: string; _pathParams?: Record<string, string> },
   projectRoot: string,
-  projectContext: { config?: Record<string, unknown>; contentTypes?: Map<string, unknown[]> } = {},
+  projectContext: {
+    config?: Record<string, unknown>;
+    contentTypes?: Map<string, unknown[]>;
+  } = {},
 ) {
   const imports = doc.imports ?? {};
   const state = doc.state;
@@ -83,7 +86,7 @@ export async function resolvePrototypes(
       const resolved = await resolveClassPrototype(def, route, projectRoot, state, projectContext);
       // Preserve timing metadata on the resolved value so compilePage() can strip it
       if (def.timing && resolved && typeof resolved === "object" && !Array.isArray(resolved)) {
-        resolved.timing = def.timing;
+        (resolved as Record<string, unknown>).timing = def.timing;
       }
       state[key] = resolved;
     } catch (err) {
@@ -110,7 +113,10 @@ async function resolveClassPrototype(
   route: { sourcePath?: string; _pathParams?: Record<string, string> },
   projectRoot: string,
   state: Record<string, unknown>,
-  projectContext: { config?: Record<string, unknown>; contentTypes?: Map<string, unknown[]> },
+  projectContext: {
+    config?: Record<string, unknown>;
+    contentTypes?: Map<string, unknown[]>;
+  },
 ) {
   const src = def.$src;
 
@@ -136,15 +142,17 @@ async function resolveClassPrototype(
   }
 
   // 3. Resolve $implementation relative to .class.json location
-  const classJsonURL = pathToFileURL(classJsonPath).href;
-  const implURL = new URL(classDef.$implementation, classJsonURL).href;
+  const implPath = resolve(dirname(classJsonPath), classDef.$implementation);
 
-  // 4. Import the module
-  const mod = await import(implURL);
+  // 4. Import the module (tolerates src-vs-dist layouts and .js → .ts under Bun)
+  const mod = await importImplementation(implPath);
 
   // 5. Find the exported class
   const exportName = def.$export ?? classDef.title ?? def.$prototype;
-  const ExportedClass = mod[exportName] ?? mod.default?.[exportName];
+  const ExportedClass = (mod[exportName] ??
+    (mod.default as Record<string, unknown> | undefined)?.[exportName]) as
+    | (new (config: Record<string, unknown>) => { resolve?: () => unknown })
+    | undefined;
   if (!ExportedClass) {
     throw new Error(`Module ${classDef.$implementation} does not export "${exportName}"`);
   }