@jxsuite/compiler 0.27.0 → 0.28.0

package/src/site/site-build.ts

@@ -9,7 +9,6 @@
  */
 
 import {
-  readFileSync,
   writeFileSync,
   copyFileSync,
   mkdirSync,
@@ -20,7 +19,9 @@ import {
 } from "node:fs";
 import { resolve, dirname, join } from "node:path";
 import { loadProjectConfig } from "./site-loader.ts";
-import { discoverPages, expandDynamicRoutes } from "./pages-discovery.ts";
+import { discoverPages, expandDynamicRoutes, readPageDocument } from "./pages-discovery.ts";
+import { buildProjectFormatRegistry } from "./format-host.ts";
+import type { FormatRegistry } from "@jxsuite/schema/format-registry";
 import { resolveLayout } from "./layout-resolver.ts";
 import { mergeHead, renderHead } from "./head-merger.ts";
 import { injectContext } from "./context-injection.ts";
@@ -42,9 +43,11 @@ import {
 } from "../shared.ts";
 import { loadContentTypes, loadContentConfig, resolveContentTypeRefs } from "./content-loader.ts";
 import { resolvePrototypes } from "./prototype-resolver.ts";
-import { compileMarkdown } from "../targets/compile-markdown.ts";
 import { transformImageNodes } from "./image-transform.ts";
 import { loadCache, saveCache, getImageCacheDir } from "./image-cache.ts";
+import { compilePagesImageFunction } from "../targets/compile-image-endpoint.ts";
+import type { ImageConfig } from "./image-optimizer.ts";
+import type { ImageMetaCache } from "./image-transform.ts";
 import type {
   JxElement,
   JxMutableNode,
@@ -85,6 +88,16 @@ export async function buildSite(
   const publicDir = resolve(projectRoot, "public");
   const trailingSlash = projectConfig.build.trailingSlash ?? "always";
 
+  // ── 1b. Build the format registry from project imports ─────────────────
+  const formatRegistry = await buildProjectFormatRegistry(projectRoot, projectConfig);
+  if (formatRegistry.entries.length > 0) {
+    log(
+      `  Registered ${formatRegistry.entries.length} format(s): ${formatRegistry.entries
+        .map((e) => e.name)
+        .join(", ")}`,
+    );
+  }
+
   // ── 2. Clean output directory ───────────────────────────────────────────
   if (clean && existsSync(outDir)) {
     rmSync(outDir, { recursive: true, force: true });
@@ -97,12 +110,12 @@ export async function buildSite(
   }
 
   log("Discovering pages...");
-  const staticRoutes = discoverPages(pagesDir);
+  const staticRoutes = await discoverPages(pagesDir, formatRegistry);
   log(`  Found ${staticRoutes.length} page(s)`);
 
   // ── 3b. Load content types ─────────────────────────────────────────────
   log("Loading content types...");
-  const contentTypes = await loadContentTypes(projectRoot, projectConfig);
+  const contentTypes = await loadContentTypes(projectRoot, projectConfig, formatRegistry);
   if (contentTypes.size > 0) {
     log(`  Loaded ${contentTypes.size} content type(s): ${[...contentTypes.keys()].join(", ")}`);
     // Resolve cross-content-type $ref references
@@ -113,7 +126,7 @@ export async function buildSite(
   }
 
   // ── 4. Expand dynamic routes ────────────────────────────────────────────
-  const routes = await expandDynamicRoutes(staticRoutes, projectRoot, contentTypes);
+  const routes = await expandDynamicRoutes(staticRoutes, projectRoot, contentTypes, formatRegistry);
   log(`  ${routes.length} route(s) after expansion`);
 
   let fileCount = 0;
@@ -125,8 +138,9 @@ export async function buildSite(
   const componentDefs: Map<string, JxElement> = new Map(); // tagName → parsed component definition
   if (existsSync(componentsDir)) {
     log("Compiling components...");
-    const componentFiles = readdirSync(componentsDir).filter(
-      (f: string) => f.endsWith(".json") || f.endsWith(".md"),
+    const componentExtensions = [".json", ...formatRegistry.documentExtensions("component")];
+    const componentFiles = readdirSync(componentsDir).filter((f: string) =>
+      componentExtensions.some((ext) => f.endsWith(ext)),
     );
     const componentOutDir = resolve(outDir, "components");
     mkdirSync(componentOutDir, { recursive: true });
@@ -134,7 +148,10 @@ export async function buildSite(
     for (const file of componentFiles) {
       try {
         const componentPath = resolve(componentsDir, file);
-        const result = await compileElement(componentPath, { $media: projectConfig.$media });
+        const result = await compileElement(componentPath, {
+          $media: projectConfig.$media,
+          formats: formatRegistry,
+        });
         for (const f of result.files) {
           const outName = f.path.includes("/") ? (f.path.split("/").pop() as string) : f.path;
           writeFileSync(resolve(componentOutDir, outName), f.content, "utf8");
@@ -143,11 +160,7 @@ export async function buildSite(
         }
 
         // Pre-render component HTML scaffold and CSS sidecar
-        const doc = componentPath.endsWith(".md")
-          ? (await import("@jxsuite/parser/transpile")).transpileJxMarkdown(
-              readFileSync(componentPath, "utf8"),
-            )
-          : JSON.parse(readFileSync(componentPath, "utf8"));
+        const doc = await readPageDocument(componentPath, formatRegistry);
         if (doc.tagName) {
           componentDefs.set(doc.tagName, doc);
           const css = buildComponentCSS(doc.tagName, doc.style, doc, projectConfig.$media ?? {});
@@ -176,14 +189,29 @@ export async function buildSite(
       const entries = collectServerEntries(doc);
       for (const entry of entries) {
         const resolvedSrc = "./components/" + entry.src.replace(/^\.\//, "");
-        siteServerEntries.push({ exportName: entry.exportName, src: resolvedSrc });
+        siteServerEntries.push({
+          exportName: entry.exportName,
+          src: resolvedSrc,
+        });
       }
     }
   }
 
   // ── 6. Compile each route ───────────────────────────────────────────────
 
-  const imageCache = projectConfig.images.optimize ? loadCache(projectRoot) : null;
+  const cfImages = projectConfig.images.optimize && projectConfig.images.service === "cloudflare";
+  const imageCache = projectConfig.images.optimize && !cfImages ? loadCache(projectRoot) : null;
+  /** @type {import("./image-transform.ts").ImageMetaCache | null} */
+  const imageMetaCache = cfImages ? new Map() : null;
+  if (cfImages) {
+    console.log(
+      `images.service is "cloudflare" — ensure your wrangler config declares the Images binding ` +
+        `("images": { "binding": "${projectConfig.images.binding ?? "IMAGES"}" })` +
+        (projectConfig.build.adapter === "cloudflare-workers"
+          ? ` and an assets binding ("assets": { "binding": "ASSETS" }).`
+          : `.`),
+    );
+  }
 
   for (const route of routes) {
     try {
@@ -195,6 +223,8 @@ export async function buildSite(
         contentTypes,
         imageCache,
         componentDefs,
+        imageMetaCache,
+        formatRegistry,
       );
 
       // Determine which component tags are fully static (for script omission)
@@ -219,17 +249,29 @@ export async function buildSite(
       writeFileSync(outPath, result.html, "utf8");
       fileCount++;
 
-      // Write markdown export alongside HTML
-      try {
-        const md = compileMarkdown(result.doc, componentDefs);
-        if (md.content) {
-          const mdPath = outPath.replace(/\.html$/, ".md");
-          writeFileSync(mdPath, md.content, "utf8");
-          fileCount++;
+      // Write serialized export sidecars alongside HTML (formats with exportTarget: true)
+      for (const fmt of formatRegistry.withCapability("serialize")) {
+        if (!fmt.exportTarget) continue;
+        try {
+          const content = (await fmt.call("serialize", result.doc, {
+            mode: "export",
+            componentDefs,
+            evaluateTemplate: (value: string, scope: Record<string, unknown>) => {
+              if (!isTemplateString(value)) return undefined;
+              return evaluateStaticTemplate(value, scope) ?? value;
+            },
+            buildScope: (state: Record<string, JxStateDefinition>) =>
+              buildInitialScope(state, null),
+          })) as string;
+          if (content) {
+            const sidecarPath = outPath.replace(/\.html$/, fmt.extensions[0]);
+            writeFileSync(sidecarPath, content, "utf8");
+            fileCount++;
+          }
+        } catch (e) {
+          const err = e as Error;
+          errors.push(`Error exporting ${fmt.name} for ${route.urlPattern}: ${err.message}`);
         }
-      } catch (e) {
-        const err = e as Error;
-        errors.push(`Error exporting markdown for ${route.urlPattern}: ${err.message}`);
       }
 
       // Write any additional files (island modules, etc.)
@@ -282,6 +324,13 @@ export async function buildSite(
     if (adapter === "cloudflare-pages") {
       const functions = compilePagesFunctions([...deduped.values()]);
 
+      if (cfImages) {
+        functions.set(
+          "functions/_jx/image.js",
+          compilePagesImageFunction(projectConfig.images as ImageConfig),
+        );
+      }
+
       for (const [filePath, source] of functions) {
         const fullPath = resolve(outDir, filePath);
         mkdirSync(resolve(fullPath, ".."), { recursive: true });
@@ -304,7 +353,13 @@ export async function buildSite(
         log(`  Generated ${functions.size} Pages function(s) in dist/functions/`);
       }
     } else {
-      const workerSource = compileSiteServer([...deduped.values()], { adapter });
+      const workerSource = compileSiteServer([...deduped.values()], {
+        adapter,
+        images:
+          cfImages && adapter === "cloudflare-workers"
+            ? (projectConfig.images as ImageConfig)
+            : null,
+      });
 
       if (workerSource) {
         const workerPath = resolve(outDir, "worker.js");
@@ -369,6 +424,7 @@ export async function buildSite(
  * @param {Map<string, ContentLoaderEntry[]>} [contentTypes]
  * @param {import("./image-cache.js").CacheManifest | null} [imageCache]
  * @param {Map<string, JxElement>} [componentDefs]
+ * @param {ImageMetaCache | null} [imageMetaCache] - Set when images.service is "cloudflare"
  * @returns {Promise<{
  *   html: string;
  *   files: { path: string; content: string; tagName?: string }[];
@@ -383,15 +439,11 @@ async function compilePage(
   contentTypes: Map<string, ContentLoaderEntry[]> = new Map(),
   imageCache: import("./image-cache.js").CacheManifest | null = null,
   componentDefs: Map<string, JxElement> = new Map(),
+  imageMetaCache: ImageMetaCache | null = null,
+  formatRegistry?: FormatRegistry,
 ) {
-  // Load the raw page document
-  let pageDoc;
-  if ((route.sourcePath as string).endsWith(".md")) {
-    const { transpileJxMarkdown } = await import("@jxsuite/parser/transpile");
-    pageDoc = transpileJxMarkdown(readFileSync(route.sourcePath as string, "utf8"));
-  } else {
-    pageDoc = JSON.parse(readFileSync(route.sourcePath as string, "utf8"));
-  }
+  // Load the raw page document (.json natively, other formats via the registry)
+  const pageDoc = await readPageDocument(route.sourcePath as string, formatRegistry);
 
   // Resolve layout (wraps page in layout with slot distribution)
   const layoutDoc = resolveLayout(pageDoc, projectConfig, projectRoot);
@@ -472,12 +524,13 @@ async function compilePage(
   }
 
   // Transform <img> nodes for responsive image optimization
-  if (imageCache && projectConfig.images?.optimize) {
+  if (projectConfig.images?.optimize && (imageCache || imageMetaCache)) {
     await transformImageNodes(
       layoutDoc,
-      projectConfig.images as import("./image-optimizer").ImageConfig,
+      projectConfig.images as ImageConfig,
       projectRoot,
       imageCache,
+      imageMetaCache ?? undefined,
     );
   }
 
@@ -496,7 +549,7 @@ async function compilePage(
     (e: JxElement | string) => typeof e === "string" && !e.startsWith("./") && !e.startsWith("../"),
   );
   if (npmElements.length > 0) {
-    result.html = injectNpmElementScripts(result.html, /** @type {string[]} */ (npmElements));
+    result.html = injectNpmElementScripts(result.html, /** @type {string[]} */ npmElements);
   }
 
   // Compile server handler if applicable (skip when provider bundles site-wide)
@@ -512,7 +565,12 @@ async function compilePage(
     }
   }
 
-  return { html: result.html, files: result.files, serverHandler, doc: layoutDoc };
+  return {
+    html: result.html,
+    files: result.files,
+    serverHandler,
+    doc: layoutDoc,
+  };
 }
 
 /**
@@ -595,7 +653,7 @@ function expandMapTemplate(template: JxMutableNode, scope: Record<string, unknow
     if (k === "children" && Array.isArray(v)) {
       node.children = v.map((child) => {
         if (typeof child === "string") return child;
-        return expandMapTemplate(/** @type {JxMutableNode} */ (child), scope);
+        return expandMapTemplate(/** @type {JxMutableNode} */ child, scope);
       });
     } else if (k === "style" && v && typeof v === "object") {
       const style = { ...v } as Record<string, unknown>;

package/src/site/site-loader.ts

@@ -34,6 +34,8 @@ const DEFAULTS = {
     quality: { webp: 80, avif: 65, jpeg: 80, png: 80 },
     sizes: "(max-width: 768px) 100vw, 50vw",
     lazyLoad: true,
+    service: "build",
+    binding: "IMAGES",
   },
   build: {
     outDir: "./dist",
@@ -96,6 +98,23 @@ export function loadProjectConfig(projectRoot: string) {
     );
   }
 
+  // Validate image service
+  const VALID_IMAGE_SERVICES = ["build", "cloudflare"];
+  if (!VALID_IMAGE_SERVICES.includes(config.images.service)) {
+    throw new Error(
+      `Unknown images.service "${config.images.service}" in project.json. ` +
+        `Valid services: ${VALID_IMAGE_SERVICES.join(", ")}`,
+    );
+  }
+  const CF_ADAPTERS = ["cloudflare-workers", "cloudflare-pages"];
+  if (config.images.service === "cloudflare" && !CF_ADAPTERS.includes(config.build.adapter)) {
+    console.warn(
+      `images.service "cloudflare" requires a Cloudflare adapter ` +
+        `(${CF_ADAPTERS.join(", ")}) — falling back to "build"`,
+    );
+    config.images.service = "build";
+  }
+
   return {
     config,
     configPath,

package/src/targets/compile-client.ts

@@ -88,10 +88,16 @@ export function compileClient(
     if ("$expression" in d) {
       const node = (d as Record<string, unknown>).$expression as ExpressionNode;
       if (isMutating(node.operator)) {
-        const compiled = compileExpression(node, { statePrefix: "state", eventParam: "e" });
+        const compiled = compileExpression(node, {
+          statePrefix: "state",
+          eventParam: "e",
+        });
         onEntries.push([key, { args: ["state", "e"], body: compiled }]);
       } else {
-        const compiled = compileExpression(node, { statePrefix: "state", eventParam: "e" });
+        const compiled = compileExpression(node, {
+          statePrefix: "state",
+          eventParam: "e",
+        });
         computedEntries.push([key, `() => ${compiled}`]);
       }
       continue;
@@ -235,7 +241,15 @@ function buildClientNode(
   context: any,
   bindings: Map<string, string>,
   handlers: Map<string, any>,
-  counter: { t: number; s: number; h: number; m: number; sw: number; l: number; needsLit: boolean },
+  counter: {
+    t: number;
+    s: number;
+    h: number;
+    m: number;
+    sw: number;
+    l: number;
+    needsLit: boolean;
+  },
 ) {
   // String children are text nodes
   if (typeof def === "string") {
@@ -285,9 +299,12 @@ function buildClientNode(
       const v = val as JxMutableNode;
       const key = `_h${counter.h++}`;
       bindAttrs.push(`@${eventName}="${key}"`);
-      handlers.set(key, { args: v.parameters ?? v.arguments ?? ["state", "event"], body: v.body });
+      handlers.set(key, {
+        args: v.parameters ?? v.arguments ?? ["state", "event"],
+        body: v.body,
+      });
       needsBind = true;
-    } else if (val && typeof val === "object" && "$expression" in /** @type {any} */ (val)) {
+    } else if (val && typeof val === "object" && "$expression" in /** @type {any} */ val) {
       const key = `_h${counter.h++}`;
       bindAttrs.push(`@${eventName}="${key}"`);
       const compiled = compileExpression(
@@ -513,7 +530,7 @@ function emitLitMapTemplate(def: JxMutableNode) {
     } else if (val && typeof val === "object" && (val as JxMutableNode).$prototype === "Function") {
       const body = mapRefsToLit((val as JxMutableNode).body as string);
       attrs += " @" + eventName + "=${(e) => { " + body + " }}";
-    } else if (val && typeof val === "object" && "$expression" in /** @type {any} */ (val)) {
+    } else if (val && typeof val === "object" && "$expression" in /** @type {any} */ val) {
       const compiled = compileExpression(
         (val as Record<string, unknown>).$expression as ExpressionNode,
         {
@@ -594,7 +611,15 @@ function emitClientModule(
   onEntries: [string, any][],
   initBlocks: string[],
   srcImportMap: Map<string, Set<string>>,
-  counter: { t: number; s: number; h: number; m: number; sw: number; l: number; needsLit: boolean },
+  counter: {
+    t: number;
+    s: number;
+    h: number;
+    m: number;
+    sw: number;
+    l: number;
+    needsLit: boolean;
+  },
   _reactivitySrc: string,
 ) {
   const lines: string[] = [];

package/src/targets/compile-element.ts

@@ -25,7 +25,7 @@ import type { JxStyle, JxMutableNode } from "@jxsuite/schema/types";
  * @returns {Promise<{ files: { path: string; content: string; tagName: string }[] }>}
  */
 export async function compileElement(sourcePath: string | any, opts: Record<string, unknown> = {}) {
-  const { resolveElementPath, $media: optsMedia } = opts as JxMutableNode;
+  const { resolveElementPath, $media: optsMedia, formats } = opts as JxMutableNode;
   /** @type {{ path: string; content: string; tagName: string }[]} */
   const files: { path: string; content: string; tagName: string }[] = [];
   const visited: Set<string> = new Set();
@@ -45,11 +45,18 @@ export async function compileElement(sourcePath: string | any, opts: Record<stri
       filePath = parentDir ? resolve(parentDir, srcPath) : resolve(srcPath);
       if (visited.has(filePath)) return;
       visited.add(filePath);
-      if (filePath.endsWith(".md")) {
-        const { transpileJxMarkdown } = await import("@jxsuite/parser/transpile");
-        doc = transpileJxMarkdown(readFileSync(filePath, "utf8"));
-      } else {
+      if (filePath.endsWith(".json")) {
         doc = JSON.parse(readFileSync(filePath, "utf8"));
+      } else {
+        const { extname } = await import("node:path");
+        const ext = extname(filePath).toLowerCase();
+        const registry = formats as import("@jxsuite/schema/format-registry").FormatRegistry;
+        const entry = registry?.byExtension?.(ext, "parse");
+        if (!entry) {
+          const { unknownFormatError } = await import("../site/format-host.ts");
+          throw unknownFormatError(filePath, ext);
+        }
+        doc = (await entry.call("parse", readFileSync(filePath, "utf8"))) as JxMutableNode;
       }
     } else {
       doc = srcPath;
@@ -272,7 +279,10 @@ export function emitElementModule(
   for (const [key, def] of functionEntries) {
     lines.push("");
     if ("$expression" in def) {
-      const compiled = compileExpression(def.$expression, { statePrefix: "s", eventParam: "e" });
+      const compiled = compileExpression(def.$expression, {
+        statePrefix: "s",
+        eventParam: "e",
+      });
       lines.push(`    this.state.${key} = (s, e) => { ${compiled}; };`);
     } else if (def.$src) {
       // $src function — wrap imported function so it receives state
@@ -429,7 +439,7 @@ function emitLitChildren(
   if (!children) return "";
 
   if ((children as JxMutableNode).$prototype === "Array") {
-    return emitMappedArray(/** @type {JxMutableNode} */ (children), indent);
+    return emitMappedArray(/** @type {JxMutableNode} */ children, indent);
   }
 
   if (!Array.isArray(children)) return "";
@@ -510,7 +520,7 @@ function emitLitNode(def: JxMutableNode | string, indent: string) {
       parts.push(
         `@${eventName}="\${(e) => ${refToExpr((val as JxMutableNode).$ref as string)}(s, e)}"`,
       );
-    } else if (val && typeof val === "object" && "$expression" in /** @type {any} */ (val)) {
+    } else if (val && typeof val === "object" && "$expression" in /** @type {any} */ val) {
       const compiled = compileExpression(
         (val as Record<string, unknown>).$expression as ExpressionNode,
         {
@@ -521,7 +531,7 @@ function emitLitNode(def: JxMutableNode | string, indent: string) {
       parts.push(`@${eventName}="\${(e) => { ${compiled}; }}"`);
     } else if (val && typeof val === "object" && (val as JxMutableNode).$prototype === "Function") {
       parts.push(
-        `@${eventName}="\${(e) => { ${inlineHandlerBody(/** @type {JxMutableNode} */ (val))} }}"`,
+        `@${eventName}="\${(e) => { ${inlineHandlerBody(/** @type {JxMutableNode} */ val)} }}"`,
       );
     }
   }
@@ -582,7 +592,7 @@ function emitMappedArray(arrayDef: JxMutableNode, indent: string) {
       parts.push(
         `@${eventName}="\${(e) => ${refToExpr((val as JxMutableNode).$ref as string)}(s, e)}"`,
       );
-    } else if (val && typeof val === "object" && "$expression" in /** @type {any} */ (val)) {
+    } else if (val && typeof val === "object" && "$expression" in /** @type {any} */ val) {
       const compiled = compileExpression(
         (val as Record<string, unknown>).$expression as ExpressionNode,
         {

package/src/targets/compile-image-endpoint.ts

@@ -0,0 +1,138 @@
+/**
+ * Compile-image-endpoint.js — Cloudflare Images binding endpoint codegen
+ *
+ * Generates the `/_jx/image` runtime image-transformation handler used when `images.service:
+ * "cloudflare"` is set in project.json. The handler fetches the original static asset via the
+ * ASSETS binding and pipes it through the Cloudflare Images binding, negotiating the output format
+ * from the request's Accept header.
+ */
+
+import type { ImageConfig } from "../site/image-optimizer.ts";
+
+const MIME: Record<string, string> = {
+  avif: "image/avif",
+  webp: "image/webp",
+  jpeg: "image/jpeg",
+  png: "image/png",
+};
+
+/**
+ * Generate the shared `jxHandleImage(request, env, waitUntil)` handler source. Widths, format
+ * preference order (avif first, mirroring the build-time pipeline), per-format quality, and the
+ * Images binding name are baked in at codegen time.
+ *
+ * @param {ImageConfig} images - The project's images config
+ * @returns {string} JavaScript source defining `jxHandleImage`
+ */
+export function buildImageHandlerSource(images: ImageConfig) {
+  const binding = images.binding ?? "IMAGES";
+  const formats = [...(images.formats ?? [])]
+    .filter((f) => f in MIME)
+    .sort((a, b) => Number(b === "avif") - Number(a === "avif"));
+  const tuples = formats.map((f) => [
+    MIME[f],
+    images.quality?.[f as keyof ImageConfig["quality"]] ?? 80,
+  ]);
+
+  return `const JX_IMG_WIDTHS = new Set(${JSON.stringify(images.widths ?? [])})
+const JX_IMG_FORMATS = ${JSON.stringify(tuples)} // [mime, quality] in preference order
+const JX_IMG_BINDING = ${JSON.stringify(binding)}
+const JX_IMG_REMOTE_DOMAINS = new Set(${JSON.stringify(images.remoteDomains ?? [])})
+
+async function jxHandleImage(request, env, waitUntil) {
+  const url = new URL(request.url)
+  const src = url.searchParams.get('src') ?? ''
+  const w = Number(url.searchParams.get('w') ?? '')
+
+  // Same-origin asset paths, or https sources from allowlisted remote domains —
+  // never act as an open proxy.
+  let remoteSrc = null
+  if (src.startsWith('https://')) {
+    try {
+      const remote = new URL(src)
+      if (JX_IMG_REMOTE_DOMAINS.has(remote.hostname)) remoteSrc = remote
+    } catch {}
+    if (!remoteSrc) return new Response('Invalid src', { status: 400 })
+  } else if (!src.startsWith('/') || src.startsWith('//') || src.includes('..') ||
+      src.includes(':') || src.includes('\\\\') || src.includes('?') || src.includes('#')) {
+    return new Response('Invalid src', { status: 400 })
+  }
+  if (!JX_IMG_WIDTHS.has(w)) return new Response('Invalid width', { status: 400 })
+
+  const accept = request.headers.get('accept') ?? ''
+  let target = null
+  for (const [mime, quality] of JX_IMG_FORMATS) {
+    if (accept.includes(mime)) { target = { mime, quality }; break }
+  }
+
+  const v = url.searchParams.get('v') ?? ''
+  const cacheKey = new Request(url.origin + '/_jx/image?src=' + encodeURIComponent(src) +
+    '&w=' + w + '&f=' + (target ? target.mime : 'orig') + '&v=' + encodeURIComponent(v))
+  const cache = caches.default
+  const hit = await cache.match(cacheKey)
+  if (hit) {
+    const out = new Response(hit.body, hit)
+    out.headers.set('Vary', 'Accept')
+    return out
+  }
+
+  const fetchSource = () =>
+    remoteSrc
+      ? fetch(remoteSrc.href, { redirect: 'follow' })
+      : env.ASSETS.fetch(new Request(new URL(src, url.origin)))
+
+  const asset = await fetchSource()
+  if (!asset.ok || !asset.body) return new Response('Not found', { status: 404 })
+
+  let response
+  if (target && env[JX_IMG_BINDING]) {
+    try {
+      const result = await env[JX_IMG_BINDING]
+        .input(asset.body)
+        .transform({ width: w, fit: 'scale-down' })
+        .output({ format: target.mime, quality: target.quality })
+      response = result.response()
+    } catch (e) {
+      // Transform failed — serve the original source untouched.
+      const retry = await fetchSource()
+      response = new Response(retry.body, retry)
+    }
+  } else {
+    response = new Response(asset.body, asset)
+  }
+
+  response = new Response(response.body, response)
+  response.headers.set('Cache-Control', 'public, max-age=31536000, immutable')
+  if (waitUntil) waitUntil(cache.put(cacheKey, response.clone()))
+  response.headers.set('Vary', 'Accept')
+  return response
+}`;
+}
+
+/**
+ * Generate the Hono route registering `jxHandleImage` at `/_jx/image`. Must be injected before the
+ * cloudflare-workers `app.all('*')` ASSETS catch-all.
+ *
+ * @returns {string}
+ */
+export function buildImageWorkerRoute() {
+  return `
+app.get('/_jx/image', (c) => jxHandleImage(c.req.raw, c.env, (p) => c.executionCtx?.waitUntil?.(p)))`;
+}
+
+/**
+ * Generate a complete Cloudflare Pages Function (`functions/_jx/image.js`) wrapping `jxHandleImage`
+ * in an `onRequestGet` handler.
+ *
+ * @param {ImageConfig} images - The project's images config
+ * @returns {string}
+ */
+export function compilePagesImageFunction(images: ImageConfig) {
+  return `// Generated by @jxsuite/compiler — do not edit manually
+${buildImageHandlerSource(images)}
+
+export async function onRequestGet(context) {
+  return jxHandleImage(context.request, context.env, (p) => context.waitUntil(p))
+}
+`;
+}

package/src/targets/compile-server.ts

@@ -7,7 +7,9 @@
 
 import $RefParser from "@apidevtools/json-schema-ref-parser";
 import { collectServerEntries } from "../shared.ts";
+import { buildImageHandlerSource, buildImageWorkerRoute } from "./compile-image-endpoint.ts";
 import type { JxElement } from "@jxsuite/schema/types";
+import type { ImageConfig } from "../site/image-optimizer.ts";
 
 /**
  * Compile a Jx document to a Hono server handler file. The handler exposes each `timing: "server"`
@@ -62,6 +64,8 @@ export default app
  * @param {object} [opts]
  * @param {string} [opts.baseUrl] - Base path for server endpoints. Default is `'/_jx/server'`
  * @param {string | null} [opts.adapter] - Deployment adapter: `"cloudflare"`, `"node"`, `"bun"`
+ * @param {ImageConfig | null} [opts.images] - When set, embed the Cloudflare Images binding
+ *   endpoint at `/_jx/image` (images.service: "cloudflare")
  * @returns {string | null} Complete worker/server source string, or null
  */
 export function compileSiteServer(
@@ -69,9 +73,10 @@ export function compileSiteServer(
   opts: {
     baseUrl?: string;
     adapter?: string | null;
+    images?: ImageConfig | null;
   } = {},
 ) {
-  const { baseUrl = "/_jx/server", adapter = null } = opts;
+  const { baseUrl = "/_jx/server", adapter = null, images = null } = opts;
   if (entries.length === 0 && !adapter) return null;
 
   const imports = entries
@@ -80,6 +85,10 @@ export function compileSiteServer(
 
   const routes = entries.map(({ exportName }) => buildRoute(exportName, baseUrl)).join("\n");
 
+  const imageHandler = images ? `\n${buildImageHandlerSource(images)}\n` : "";
+  // The image route must register before the cloudflare-workers ASSETS catch-all below.
+  const imageRoute = images ? buildImageWorkerRoute() : "";
+
   const adapterBlock =
     adapter === "cloudflare-workers"
       ? "\napp.all('*', (c) => c.env.ASSETS.fetch(c.req.raw))\n"
@@ -88,9 +97,9 @@ export function compileSiteServer(
   return `// Generated by @jxsuite/compiler — do not edit manually
 import { Hono } from 'hono'
 ${imports}
-
+${imageHandler}
 const app = new Hono()
-${routes}
+${routes}${imageRoute}
 ${adapterBlock}
 export default app
 `;