@jxsuite/compiler 0.28.0 → 0.28.3

package/src/site/image-transform.ts

@@ -7,62 +7,93 @@
  */
 
 import { existsSync } from "node:fs";
-import { createHash } from "node:crypto";
-import { resolve, extname, basename } from "node:path";
+import { basename, extname, resolve } from "node:path";
 import {
-  processImage,
   buildSrcset,
-  contentHash,
   configHash,
+  contentHash,
   getImageMetadata,
+  processImage,
 } from "./image-optimizer.ts";
-import { getCached, setCached, getImageCacheDir } from "./image-cache.ts";
+import { getCached, getImageCacheDir, setCached } from "./image-cache.ts";
 
-import type { ImageConfig } from "./image-optimizer.ts";
-import type { ImageManifest } from "./image-optimizer.ts";
-import type { JxMutableNode } from "@jxsuite/schema/types";
+import type { ImageConfig, ImageManifest } from "./image-optimizer.ts";
+import type { JxDocument, JxMutableNode } from "@jxsuite/schema/types";
 import type { CacheManifest } from "./image-cache.ts";
-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 }>;
+export type ImageMetaCache = Map<
+  string,
+  { width: number | null; height: number | null; hash: string }
+>;
+
+let sharpWarned = false;
 
 /**
  * Resolve original image dimensions and content hash for cloudflare mode. Reads only the image
- * header via Sharp — no variants are generated.
+ * header via Sharp — no variants are generated. Dimensions degrade to null when Sharp is
+ * unavailable (e.g. native binary won't load): srcsets are still emitted (fit=scale-down guards
+ * against upscaling), only the width/height attributes are skipped.
  *
  * @param {string} absoluteSrc
  * @param {ImageMetaCache} metaCache
- * @returns {Promise<{ width: number; height: number; hash: string }>}
+ * @returns {Promise<{ width: number | null; height: number | null; 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) };
+    const hash = contentHash(absoluteSrc);
+    try {
+      const m = await getImageMetadata(absoluteSrc);
+      meta = { width: m.width, height: m.height, hash };
+    } catch (error) {
+      if (!sharpWarned) {
+        sharpWarned = true;
+        console.warn(
+          `Could not read image dimensions (${(error as Error).message}) — ` +
+            `emitting srcsets without width/height attributes.`,
+        );
+      }
+      meta = { width: null, height: null, hash };
+    }
     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.
+ * 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 - Original site-relative src (e.g. "/images/hero.png")
- * @param {number[]} widths
+ * @param {string} src - Site-relative src (e.g. "/images/hero.png") or allowlisted https URL
+ * @param {ImageConfig} config
  * @param {number} originalWidth
- * @param {string} hash - 8-char content hash
+ * @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, widths: number[], originalWidth: number, hash: string) {
-  return widths
+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) => `/_jx/image?src=${encodeURIComponent(src)}&w=${w}&v=${hash} ${w}w`)
+    .toSorted((a, b) => a - b)
+    .map(
+      (w) =>
+        `/cdn-cgi/image/width=${w},quality=${quality},fit=scale-down,format=auto` +
+        `${separator}${src}${suffix} ${w}w`,
+    )
     .join(", ");
 }
 
@@ -86,10 +117,14 @@ async function resolveManifest(
 
   if (cached) {
     const allExist = cached.variants.every((v) => existsSync(v.absolutePath));
-    if (allExist) return cached;
+    if (allExist) {
+      return cached;
+    }
   }
 
-  if (!cached) console.log(`    Optimizing ${basename(absoluteSrc)}...`);
+  if (!cached) {
+    console.log(`    Optimizing ${basename(absoluteSrc)}...`);
+  }
   const manifest = await processImage(absoluteSrc, getImageCacheDir(projectRoot), config);
   setCached(cache, key, src, manifest);
   return manifest;
@@ -102,43 +137,59 @@ async function resolveManifest(
  * @returns {boolean}
  */
 function shouldSkip(src: string) {
-  if (typeof src !== "string") return true;
-  if (!src) return true;
-  if (src.includes("${")) return true;
-  if (EXTERNAL_PREFIXES.some((p) => src.startsWith(p))) return true;
-  if (SKIP_EXTENSIONS.has(extname(src).toLowerCase())) return true;
+  if (typeof src !== "string") {
+    return true;
+  }
+  if (!src) {
+    return true;
+  }
+  if (src.includes("${")) {
+    return true;
+  }
+  if (EXTERNAL_PREFIXES.some((p) => src.startsWith(p))) {
+    return true;
+  }
+  if (SKIP_EXTENSIONS.has(extname(src).toLowerCase())) {
+    return true;
+  }
   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.
+ * 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;
+  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;
+    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.
  *
@@ -176,9 +227,11 @@ export async function transformImageNodes(
   cache: CacheManifest | null,
   metaCache?: ImageMetaCache,
 ) {
-  const imageRefs: Map<string, ImageManifest> = new Map();
+  const imageRefs = new Map<string, ImageManifest>();
 
-  if (!config.optimize) return { imageRefs };
+  if (!config.optimize) {
+    return { imageRefs };
+  }
 
   const meta = metaCache ?? new Map();
   await walkAndTransform(doc, config, projectRoot, cache, meta, imageRefs);
@@ -202,7 +255,9 @@ async function walkAndTransform(
   metaCache: ImageMetaCache,
   imageRefs: Map<string, ImageManifest>,
 ) {
-  if (!node || typeof node !== "object") return;
+  if (!node || typeof node !== "object") {
+    return;
+  }
 
   if (node.tagName === "img") {
     await transformImgNode(node, config, projectRoot, cache, metaCache, imageRefs);
@@ -221,7 +276,9 @@ async function walkAndTransform(
 
   if (Array.isArray(node.children)) {
     for (const child of node.children) {
-      if (typeof child === "string") continue;
+      if (typeof child === "string") {
+        continue;
+      }
       await walkAndTransform(child, config, projectRoot, cache, metaCache, imageRefs);
     }
   }
@@ -243,43 +300,59 @@ async function transformImgNode(
   metaCache: ImageMetaCache,
   imageRefs: Map<string, ImageManifest>,
 ) {
-  if (!node.attributes) node.attributes = {};
+  if (!node.attributes) {
+    node.attributes = {};
+  }
 
   const src = node.attributes.src ?? node.src;
+  // Bound ($ref) or missing srcs cannot be optimized at build time.
+  if (typeof src !== "string") {
+    return;
+  }
   const remote = isAllowedRemote(src, config);
-  if (!remote && shouldSkip(src)) return;
-  if (node.attributes["data-no-optimize"] !== undefined) return;
-
-  const absoluteSrc = remote ? null : resolveImagePath(src, projectRoot);
-  if (absoluteSrc && !existsSync(absoluteSrc)) return;
+  if (!remote && shouldSkip(src)) {
+    return;
+  }
+  if (node.attributes["data-no-optimize"] !== undefined) {
+    return;
+  }
 
   let srcset;
   let original: { width: number; height: number } | undefined;
 
   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;
+    // Fit=scale-down avoid upscaling past the source size.
+    srcset = buildCloudflareSrcset(src, config, Infinity, null);
   } 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 absoluteSrc = resolveImagePath(src, projectRoot);
+    if (!existsSync(absoluteSrc)) {
+      return;
     }
 
-    const preferredFormat = config.formats.includes("avif") ? "avif" : config.formats[0];
-    srcset = buildSrcset(manifest.variants, preferredFormat);
-    original = manifest.original;
+    if (config.service === "cloudflare") {
+      const meta = await resolveCfMeta(absoluteSrc, metaCache);
+      srcset = buildCloudflareSrcset(src, config, meta.width ?? Infinity, meta.hash);
+      if (meta.width != null && meta.height != null) {
+        original = { width: meta.width, height: meta.height };
+      }
+    } else {
+      let manifest = imageRefs.get(absoluteSrc);
+
+      if (!manifest) {
+        manifest = await resolveManifest(absoluteSrc, src, config, projectRoot, cache!);
+        imageRefs.set(absoluteSrc, manifest);
+      }
+
+      const preferredFormat = config.formats.includes("avif") ? "avif" : config.formats[0];
+      srcset = buildSrcset(manifest.variants, preferredFormat);
+      ({ original } = manifest);
+    }
   }
 
   if (srcset) {
     node.attributes.srcset = srcset;
-    node.attributes.sizes = node.attributes.sizes ?? config.sizes;
+    node.attributes.sizes ??= config.sizes;
   }
 
   if (!node.attributes.width && original?.width) {
@@ -323,32 +396,44 @@ async function transformInnerHtmlImages(
   const replacements = [];
 
   for (const m of html.matchAll(IMG_TAG_RE)) {
-    const tag = m[0];
-    const attrs = m[1];
+    const [tag] = m;
+    const [, attrs] = m;
 
-    if (SRCSET_ATTR_RE.test(attrs)) continue;
-    if (DATA_NO_OPT_RE.test(attrs)) continue;
+    if (SRCSET_ATTR_RE.test(attrs)) {
+      continue;
+    }
+    if (DATA_NO_OPT_RE.test(attrs)) {
+      continue;
+    }
 
     const srcMatch = attrs.match(SRC_ATTR_RE);
-    if (!srcMatch) continue;
+    if (!srcMatch) {
+      continue;
+    }
 
     // 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;
+    if (!remote && shouldSkip(src)) {
+      continue;
+    }
 
     const absoluteSrc = remote ? null : resolveImagePath(src, projectRoot);
-    if (absoluteSrc && !existsSync(absoluteSrc)) continue;
+    if (absoluteSrc && !existsSync(absoluteSrc)) {
+      continue;
+    }
 
     let srcset;
     let original: { width: number; height: number } | undefined;
 
     if (remote) {
-      srcset = buildCloudflareSrcset(src, config.widths, Infinity, urlHash(src));
+      srcset = buildCloudflareSrcset(src, config, Infinity, null);
     } else if (config.service === "cloudflare") {
       const meta = await resolveCfMeta(absoluteSrc as string, metaCache);
-      srcset = buildCloudflareSrcset(src, config.widths, meta.width, meta.hash);
-      original = meta;
+      srcset = buildCloudflareSrcset(src, config, meta.width ?? Infinity, meta.hash);
+      if (meta.width != null && meta.height != null) {
+        original = { width: meta.width, height: meta.height };
+      }
     } else {
       let manifest = imageRefs.get(absoluteSrc as string);
       if (!manifest) {
@@ -358,9 +443,11 @@ async function transformInnerHtmlImages(
 
       const preferredFormat = config.formats.includes("avif") ? "avif" : config.formats[0];
       srcset = buildSrcset(manifest.variants, preferredFormat);
-      original = manifest.original;
+      ({ original } = manifest);
+    }
+    if (!srcset) {
+      continue;
     }
-    if (!srcset) continue;
 
     let extra = ` srcset="${srcset}" sizes="${config.sizes}"`;
     if (!/\bwidth=/.test(attrs) && original?.width) {
@@ -370,8 +457,12 @@ async function transformInnerHtmlImages(
       extra += ` height="${original.height}"`;
     }
     if (config.lazyLoad && !/\bloading="eager"/.test(attrs)) {
-      if (!/\bloading=/.test(attrs)) extra += ` loading="lazy"`;
-      if (!/\bdecoding=/.test(attrs)) extra += ` decoding="async"`;
+      if (!/\bloading=/.test(attrs)) {
+        extra += ` loading="lazy"`;
+      }
+      if (!/\bdecoding=/.test(attrs)) {
+        extra += ` decoding="async"`;
+      }
     }
 
     replacements.push({ match: tag, replacement: `<img${attrs}${extra}>` });

package/src/site/layout-resolver.ts

@@ -13,9 +13,10 @@
  * - Named slots use attributes.slot on page children
  */
 
-import { readFileSync, existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
+import { parseJxDocument } from "@jxsuite/schema/parse";
 import { resolve } from "node:path";
-import type { JxElement, JxDocument } from "@jxsuite/schema/types";
+import type { JxDocument, JxElement } from "@jxsuite/schema/types";
 
 /**
  * Resolve a page's layout, wrapping the page content in the layout structure.
@@ -48,10 +49,10 @@ export function resolveLayout(
   /** @type {JxDocument} */
   let layoutDoc;
   try {
-    layoutDoc = JSON.parse(readFileSync(layoutPath, "utf8"));
-  } catch (e) {
-    const err = e as Error;
-    throw new Error(`Invalid layout JSON at ${layoutPath}: ${err.message}`);
+    layoutDoc = parseJxDocument(readFileSync(layoutPath, "utf8"), layoutPath);
+  } catch (error) {
+    const err = error as Error;
+    throw new Error(`Invalid layout JSON at ${layoutPath}: ${err.message}`, { cause: error });
   }
 
   // Check for nested layouts (layout inheriting from another layout)
@@ -93,8 +94,12 @@ export function resolveLayout(
   }
 
   // Preserve page-level metadata
-  if (pageDoc.$head) merged._pageHead = pageDoc.$head;
-  if (pageDoc.title) merged._pageTitle = pageDoc.title;
+  if (pageDoc.$head) {
+    merged._pageHead = pageDoc.$head;
+  }
+  if (pageDoc.title) {
+    merged._pageTitle = pageDoc.title;
+  }
 
   // Remove $layout from merged doc (already resolved)
   delete merged.$layout;
@@ -117,17 +122,23 @@ export function resolveLayout(
  * @param {(JxElement | string)[]} children - Page children to distribute
  */
 function distributeSlots(node: JxElement, children: (JxElement | string)[]) {
-  if (!node || typeof node !== "object") return;
-  if (!Array.isArray(node.children)) return;
+  if (!node || typeof node !== "object") {
+    return;
+  }
+  if (!Array.isArray(node.children)) {
+    return;
+  }
 
   // Collect named and default children
-  const named: Map<string, (JxElement | string)[]> = new Map(); // slot name → children[]
-  const defaults: (JxElement | string)[] = []; // children without a slot target
+  const named = new Map<string, (JxElement | string)[]>(); // Slot name → children[]
+  const defaults: (JxElement | string)[] = []; // Children without a slot target
 
   for (const child of children) {
     if (child && typeof child === "object" && child.attributes?.slot) {
       const slotName = child.attributes.slot as string;
-      if (!named.has(slotName)) named.set(slotName, []);
+      if (!named.has(slotName)) {
+        named.set(slotName, []);
+      }
       (named.get(slotName) as (JxElement | string)[]).push(child);
     } else {
       defaults.push(child);
@@ -150,8 +161,12 @@ function fillSlots(
   named: Map<string, (JxElement | string)[]>,
   defaults: (JxElement | string)[],
 ) {
-  if (!node || typeof node !== "object") return;
-  if (!Array.isArray(node.children)) return;
+  if (!node || typeof node !== "object") {
+    return;
+  }
+  if (!Array.isArray(node.children)) {
+    return;
+  }
 
   const newChildren: (JxElement | string)[] = [];
 
@@ -162,12 +177,12 @@ function fillSlots(
       if (slotName && named.has(slotName as string)) {
         // Named slot — replace with matching children
         newChildren.push(...(named.get(slotName as string) as (JxElement | string)[]));
-        named.delete(slotName as string); // consumed
+        named.delete(slotName as string); // Consumed
       } else if (!slotName && defaults.length > 0) {
         // Default slot — replace with unassigned children
         newChildren.push(...defaults);
         // Don't clear defaults — only one default slot should exist,
-        // but if there are multiple, the first one wins
+        // But if there are multiple, the first one wins
       } else {
         // No matching content — keep slot's fallback children
         if (Array.isArray(child.children)) {
@@ -191,5 +206,5 @@ function fillSlots(
  * @returns {JxDocument}
  */
 function deepClone(obj: JxDocument) {
-  return JSON.parse(JSON.stringify(obj));
+  return structuredClone(obj);
 }