@jxsuite/compiler 1.4.0 → 2.0.0

package/src/site/image-transform.ts

@@ -4,6 +4,11 @@
  * Walks a Jx document tree, finds <img> nodes with static src paths, and injects srcset, sizes,
  * width, height, loading, and decoding attributes. Collects image references so the build
  * orchestrator knows which files to process.
+ *
+ * Two passes, deliberately separable. The **loading** pass (`images.lazyLoad`) runs on every image
+ * in every project, because deciding not to optimize an image says nothing about when to fetch it.
+ * The **variant** pass (`images.optimize`) is the expensive half and is the one the master switch
+ * turns off.
  */
 
 import { existsSync } from "node:fs";
@@ -16,6 +21,7 @@ import {
   processImage,
 } from "./image-optimizer.ts";
 import { getCached, getImageCacheDir, setCached } from "./image-cache.ts";
+import { imgLoadingAttrs } from "./img-loading.ts";
 import { resolveAssetUrl } from "@jxsuite/schema/asset-paths";
 
 import type { AssetMount } from "@jxsuite/schema/asset-paths";
@@ -239,14 +245,8 @@ export async function transformImageNodes(
   mounts: readonly AssetMount[] = [],
 ) {
   const imageRefs = new Map<string, ImageManifest>();
-
-  if (!config.optimize) {
-    return { imageRefs };
-  }
-
   const meta = metaCache ?? new Map();
   await walkAndTransform(doc, config, projectRoot, cache, meta, imageRefs, mounts);
-
   return { imageRefs };
 }
 
@@ -274,6 +274,11 @@ async function walkAndTransform(
 
   if (node.tagName === "img") {
     await transformImgNode(node, config, projectRoot, cache, metaCache, imageRefs, mounts);
+    // Wrapping rewrote this node into a `<picture>` whose children this pass just authored.
+    // Descending into them would find the `<img>` and wrap it again, forever.
+    if (node.tagName !== "img") {
+      return;
+    }
   }
 
   if (typeof node.innerHTML === "string" && node.innerHTML.includes("<img")) {
@@ -298,94 +303,226 @@ async function walkAndTransform(
   }
 }
 
+/** A `<source>` in a generated `<picture>`: one image format, one candidate list. */
+interface PictureSource {
+  type: string;
+  srcset: string;
+}
+
 /**
- * @param {JxMutableNode | JxDocument} node
+ * Formats in the order a browser should be offered them — best compression first. A `<picture>`
+ * takes the FIRST source it can decode, so this order is the whole negotiation.
+ */
+const PICTURE_FORMAT_ORDER: readonly string[] = ["avif", "webp", "jpeg", "png"];
+const MEDIA_TYPES: Record<string, string> = {
+  avif: "image/avif",
+  jpeg: "image/jpeg",
+  png: "image/png",
+  webp: "image/webp",
+};
+
+interface ResolvedVariants {
+  /** Candidate list for the `<img>` itself, in the preferred format. */
+  srcset: string;
+  dims: { width: number; height: number } | null;
+  /** One entry per additional format, when the image is to be wrapped in a `<picture>`. */
+  sources: PictureSource[];
+}
+
+/**
+ * Generate (or look up) this image's variants and describe what the markup should say.
+ *
+ * Returns null whenever the image is not ours to touch — a bound `src`, an SVG, a remote URL off
+ * the allowlist, a missing file, an explicit `data-no-optimize`. Both callers treat null the same
+ * way: leave the markup alone apart from the loading attributes.
+ *
+ * @param {string} src
+ * @param {boolean} optedOut - `data-no-optimize` is present
  * @param {ImageConfig} config
  * @param {string} projectRoot
  * @param {CacheManifest | null} cache
  * @param {ImageMetaCache} metaCache
  * @param {Map<string, ImageManifest>} imageRefs
  * @param {readonly AssetMount[]} mounts
+ * @returns {Promise<ResolvedVariants | null>}
  */
-async function transformImgNode(
-  node: JxMutableNode | JxDocument,
+async function resolveVariants(
+  src: string,
+  optedOut: boolean,
   config: ImageConfig,
   projectRoot: string,
   cache: CacheManifest | null,
   metaCache: ImageMetaCache,
   imageRefs: Map<string, ImageManifest>,
   mounts: readonly AssetMount[],
-) {
-  if (!node.attributes) {
-    node.attributes = {};
-  }
-
-  const src = node.attributes.src ?? node.src;
+): Promise<ResolvedVariants | null> {
   // Bound ($ref) or missing srcs cannot be optimized at build time.
-  if (typeof src !== "string") {
-    return;
+  if (typeof src !== "string" || optedOut) {
+    return null;
   }
   const remote = isAllowedRemote(src, config);
   if (!remote && shouldSkip(src)) {
-    return;
-  }
-  if (node.attributes["data-no-optimize"] !== undefined) {
-    return;
+    return null;
   }
 
-  let srcset;
-  let dims: { width: number; height: number } | null = null;
-
   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 {
-    const absoluteSrc = resolveImagePath(src, projectRoot, mounts);
-    if (!existsSync(absoluteSrc)) {
-      return;
-    }
+    return { dims: null, sources: [], srcset: buildCloudflareSrcset(src, config, Infinity, null) };
+  }
 
-    if (config.service === "cloudflare") {
-      const meta = await resolveCfMeta(absoluteSrc, metaCache);
-      srcset = buildCloudflareSrcset(src, config, meta.width ?? Infinity, meta.hash);
-      dims = meta.width && meta.height ? { height: meta.height, width: meta.width } : null;
-    } else {
-      let manifest = imageRefs.get(absoluteSrc);
+  const absoluteSrc = resolveImagePath(src, projectRoot, mounts);
+  if (!existsSync(absoluteSrc)) {
+    return null;
+  }
 
-      if (!manifest) {
-        manifest = await resolveManifest(absoluteSrc, src, config, projectRoot, cache!);
-        imageRefs.set(absoluteSrc, manifest);
-      }
+  if (config.service === "cloudflare") {
+    // Cloudflare negotiates the format itself (`format=auto`), so there is nothing for a
+    // `<picture>` to choose between.
+    const meta = await resolveCfMeta(absoluteSrc, metaCache);
+    const srcset = buildCloudflareSrcset(src, config, meta.width ?? Infinity, meta.hash);
+    const dims = meta.width && meta.height ? { height: meta.height, width: meta.width } : null;
+    return { dims, sources: [], srcset };
+  }
 
-      const preferredFormat = config.formats.includes("avif") ? "avif" : config.formats[0]!;
-      srcset = buildSrcset(manifest.variants, preferredFormat);
-      dims =
-        manifest.original?.width && manifest.original.height
-          ? { height: manifest.original.height, width: manifest.original.width }
-          : null;
-    }
+  let manifest = imageRefs.get(absoluteSrc);
+  if (!manifest) {
+    manifest = await resolveManifest(absoluteSrc, src, config, projectRoot, cache!);
+    imageRefs.set(absoluteSrc, manifest);
   }
 
-  if (srcset) {
-    node.attributes.srcset = srcset;
-    node.attributes.sizes ??= config.sizes;
+  /*
+   * The project's own formats, best-compression first. A format the project did not ask for is not
+   * offered even if a stale manifest happens to hold variants of it, and one this order does not
+   * know keeps the position the project gave it.
+   */
+  const ordered = [
+    ...PICTURE_FORMAT_ORDER.filter((format) => config.formats.includes(format)),
+    ...config.formats.filter((format) => !PICTURE_FORMAT_ORDER.includes(format)),
+  ];
+  const available = ordered
+    .map((format) => ({
+      srcset: buildSrcset(manifest.variants, format),
+      type: MEDIA_TYPES[format] ?? `image/${format}`,
+    }))
+    .filter((source) => source.srcset !== "");
+
+  const dims =
+    manifest.original?.width && manifest.original.height
+      ? { height: manifest.original.height, width: manifest.original.width }
+      : null;
+  /*
+   * One format needs no negotiation, and a srcset in the single format the project asked for is
+   * both smaller markup and the historical behaviour. Two or more do: `srcset` alone carries no
+   * format information, so a browser that cannot decode AVIF would still pick an AVIF candidate.
+   */
+  const wrap = config.picture !== false && available.length > 1;
+  return { dims, sources: wrap ? available : [], srcset: available[0]?.srcset ?? "" };
+}
+
+/**
+ * @param {JxMutableNode | JxDocument} node
+ * @param {ImageConfig} config
+ * @param {string} projectRoot
+ * @param {CacheManifest | null} cache
+ * @param {ImageMetaCache} metaCache
+ * @param {Map<string, ImageManifest>} imageRefs
+ * @param {readonly AssetMount[]} mounts
+ */
+async function transformImgNode(
+  node: JxMutableNode | JxDocument,
+  config: ImageConfig,
+  projectRoot: string,
+  cache: CacheManifest | null,
+  metaCache: ImageMetaCache,
+  imageRefs: Map<string, ImageManifest>,
+  mounts: readonly AssetMount[],
+) {
+  if (!node.attributes) {
+    node.attributes = {};
+  }
+  const attrs = node.attributes;
+  /*
+   * A node-level `src` is normalized into `attributes` first. The static emitter only renders a
+   * fixed set of node-level DOM properties and `src` is not among them, so an image written that
+   * way used to acquire a `srcset` and lose its `src` — the fallback the srcset exists to have.
+   */
+  if (attrs.src === undefined && typeof node.src === "string") {
+    attrs.src = node.src;
+    delete node.src;
   }
 
-  // Intrinsic dimensions prevent layout shift; author-supplied values win.
-  if (dims && node.attributes.width === undefined && node.attributes.height === undefined) {
-    node.attributes.width = String(dims.width);
-    node.attributes.height = String(dims.height);
+  const variants = config.optimize
+    ? await resolveVariants(
+        attrs.src as string,
+        attrs["data-no-optimize"] !== undefined,
+        config,
+        projectRoot,
+        cache,
+        metaCache,
+        imageRefs,
+        mounts,
+      )
+    : null;
+
+  if (variants) {
+    if (variants.srcset !== "") {
+      attrs.srcset = variants.srcset;
+      attrs.sizes ??= config.sizes;
+    }
+    // Intrinsic dimensions prevent layout shift; author-supplied values win.
+    if (variants.dims && attrs.width === undefined && attrs.height === undefined) {
+      attrs.width = String(variants.dims.width);
+      attrs.height = String(variants.dims.height);
+    }
   }
 
-  if (config.lazyLoad && node.attributes.loading !== "eager") {
-    node.attributes.loading = "lazy";
-    node.attributes.decoding = "async";
+  Object.assign(attrs, imgLoadingAttrs(attrs, config.lazyLoad));
+
+  if (variants && variants.sources.length > 0) {
+    wrapInPicture(node, variants.sources, config.sizes);
   }
 }
 
+/**
+ * Turn an `<img>` node into a `<picture>` wrapping it, one `<source>` per format.
+ *
+ * The `<img>` keeps everything that describes the image — `src`, `alt`, dimensions, styles, the
+ * loading attributes — and loses `srcset`/`sizes`, which now live on the sources. That is what
+ * makes it a real fallback: a browser that matches no `<source>` gets the original file, not a
+ * candidate list in a format it just declined.
+ *
+ * @param {JxMutableNode | JxDocument} node - The `<img>` node, mutated into a `<picture>`
+ * @param {PictureSource[]} sources
+ * @param {string} sizes
+ */
+function wrapInPicture(
+  node: JxMutableNode | JxDocument,
+  sources: readonly PictureSource[],
+  sizes: string,
+) {
+  const imgAttrs: Record<string, unknown> = { ...node.attributes };
+  const inheritedSizes = (imgAttrs.sizes as string | undefined) ?? sizes;
+  delete imgAttrs.srcset;
+  delete imgAttrs.sizes;
+  const img: Record<string, unknown> = { attributes: imgAttrs, tagName: "img" };
+  if (node.style !== undefined) {
+    img.style = node.style;
+    delete node.style;
+  }
+
+  node.tagName = "picture";
+  node.attributes = {};
+  node.children = [
+    ...sources.map((source) => ({
+      attributes: { sizes: inheritedSizes, srcset: source.srcset, type: source.type },
+      tagName: "source",
+    })),
+    img,
+  ] as (string | JxMutableNode)[];
+}
+
 const IMG_TAG_RE = /<img\b([^>]*)>/gi;
-const SRC_ATTR_RE = /\bsrc="([^"]*)"/;
 const SRCSET_ATTR_RE = /\bsrcset="/;
 const DATA_NO_OPT_RE = /\bdata-no-optimize\b/;
 
@@ -410,78 +547,57 @@ async function transformInnerHtmlImages(
   imageRefs: Map<string, ImageManifest>,
   mounts: readonly AssetMount[],
 ) {
-  /** @type {{ match: string; replacement: string }[]} */
-  const replacements = [];
+  const replacements: { match: string; replacement: string }[] = [];
 
   for (const m of html.matchAll(IMG_TAG_RE)) {
     const tag = m[0]!;
     const attrs = m[1]!;
 
-    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;
-    }
-
     // 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 src = (attrValue(attrs, "src") ?? "").replaceAll("&amp;", "&");
+    const alreadyResponsive = SRCSET_ATTR_RE.test(attrs);
+    const variants =
+      config.optimize && src !== "" && !alreadyResponsive
+        ? await resolveVariants(
+            src,
+            DATA_NO_OPT_RE.test(attrs),
+            config,
+            projectRoot,
+            cache,
+            metaCache,
+            imageRefs,
+            mounts,
+          )
+        : null;
+
+    let extra = "";
+    if (variants && variants.srcset !== "") {
+      extra += ` srcset="${variants.srcset}" sizes="${config.sizes}"`;
     }
-
-    const absoluteSrc = remote ? null : resolveImagePath(src, projectRoot, mounts);
-    if (absoluteSrc && !existsSync(absoluteSrc)) {
-      continue;
+    if (variants?.dims && !/\bwidth=/.test(attrs) && !/\bheight=/.test(attrs)) {
+      extra += ` width="${variants.dims.width}" height="${variants.dims.height}"`;
     }
-
-    let srcset;
-    let dims: { width: number; height: number } | null = null;
-
-    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 ?? Infinity, meta.hash);
-      dims = meta.width && meta.height ? { height: meta.height, width: meta.width } : 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 preferredFormat = config.formats.includes("avif") ? "avif" : config.formats[0]!;
-      srcset = buildSrcset(manifest.variants, preferredFormat);
-      dims =
-        manifest.original?.width && manifest.original.height
-          ? { height: manifest.original.height, width: manifest.original.width }
-          : null;
-    }
-    if (!srcset) {
-      continue;
+    const loading = imgLoadingAttrs(
+      {
+        decoding: attrValue(attrs, "decoding"),
+        fetchpriority: attrValue(attrs, "fetchpriority"),
+        loading: attrValue(attrs, "loading"),
+      },
+      config.lazyLoad,
+    );
+    for (const [key, value] of Object.entries(loading)) {
+      extra += ` ${key}="${value}"`;
     }
 
-    let extra = ` srcset="${srcset}" sizes="${config.sizes}"`;
-    if (dims && !/\bwidth=/.test(attrs) && !/\bheight=/.test(attrs)) {
-      extra += ` width="${dims.width}" height="${dims.height}"`;
-    }
-    if (config.lazyLoad && !/\bloading="eager"/.test(attrs)) {
-      if (!/\bloading=/.test(attrs)) {
-        extra += ` loading="lazy"`;
-      }
-      if (!/\bdecoding=/.test(attrs)) {
-        extra += ` decoding="async"`;
-      }
+    if (extra === "") {
+      continue;
     }
 
-    replacements.push({ match: tag, replacement: `<img${attrs}${extra}>` });
+    const img =
+      variants && variants.sources.length > 0
+        ? renderPictureTag(attrs, variants.sources, config.sizes, extra)
+        : `<img${attrs}${extra}>`;
+    replacements.push({ match: tag, replacement: img });
   }
 
   let result = html;
@@ -490,3 +606,38 @@ async function transformInnerHtmlImages(
   }
   return result;
 }
+
+/**
+ * The string-surgery twin of {@link wrapInPicture}: the same markup, built from a raw attribute
+ * string rather than a node. `srcset`/`sizes` stay off the `<img>` so it remains a real fallback.
+ *
+ * @param {string} attrs - The original tag's attribute string
+ * @param {readonly PictureSource[]} sources
+ * @param {string} sizes
+ * @param {string} extra - Attributes this pass decided to add
+ * @returns {string}
+ */
+function renderPictureTag(
+  attrs: string,
+  sources: readonly PictureSource[],
+  sizes: string,
+  extra: string,
+) {
+  const inheritedSizes = attrValue(attrs, "sizes") ?? sizes;
+  const imgExtra = extra.replace(/ srcset="[^"]*"/, "").replace(/ sizes="[^"]*"/, "");
+  const sourceTags = sources
+    .map((s) => `<source type="${s.type}" srcset="${s.srcset}" sizes="${inheritedSizes}">`)
+    .join("");
+  return `<picture>${sourceTags}<img${attrs}${imgExtra}></picture>`;
+}
+
+/**
+ * Read one double-quoted attribute out of a raw tag attribute string.
+ *
+ * @param {string} attrs
+ * @param {string} name
+ * @returns {string | undefined}
+ */
+function attrValue(attrs: string, name: string): string | undefined {
+  return new RegExp(`\\b${name}="([^"]*)"`, "i").exec(attrs)?.[1];
+}

package/src/site/img-loading.ts

@@ -0,0 +1,55 @@
+/**
+ * One decision, three callers: which loading attributes an `<img>` ends up with.
+ *
+ * It used to be three decisions. The static emitter added `loading="lazy"` to every `<img>` that
+ * did not already carry one — unconditionally, outside `images.optimize` and outside the image
+ * pipeline, so it reached the LCP image too, which is the one image on a page that must never be
+ * lazy. The pipeline then made the same decision again for the nodes it rewrote, and a third time
+ * for `<img>` tags sitting inside pre-rendered `innerHTML`. Only two of the three consulted
+ * `images.lazyLoad`, and none of them knew what `fetchpriority` meant.
+ *
+ * The compiler cannot know which image is the largest contentful paint — that depends on the
+ * viewport, not the document — so it does not guess. It honours the author's answer instead.
+ *
+ * @docs framework/site/images
+ */
+
+/** WHATWG HTML: `fetchpriority` values. `high` is the one that means "this is the LCP image". */
+export const HIGH_PRIORITY = "high";
+
+/** Attributes an `<img>` already carries, as far as this decision is concerned. */
+export interface ImgLoadingState {
+  loading?: unknown;
+  decoding?: unknown;
+  fetchpriority?: unknown;
+}
+
+/** Attributes to add. Empty when the author has already decided, or when lazy loading is off. */
+export interface ImgLoadingAttrs {
+  loading?: "lazy";
+  decoding?: "async";
+}
+
+const present = (value: unknown) => value !== undefined && value !== null && value !== "";
+
+/**
+ * Decide the loading attributes for one `<img>`.
+ *
+ * Three ways to end up with nothing added: `lazyLoad` is off, the author set `loading` themselves,
+ * or the author marked the image `fetchpriority="high"`. That last one is not a stylistic
+ * preference — a high-priority lazy image is a contradiction the browser resolves by ignoring the
+ * priority, so honouring both would silently discard the author's only lever over LCP.
+ *
+ * @param {ImgLoadingState} attrs - Attributes the image already carries
+ * @param {boolean} lazyLoad - `images.lazyLoad`
+ * @returns {ImgLoadingAttrs}
+ */
+export function imgLoadingAttrs(attrs: ImgLoadingState, lazyLoad: boolean): ImgLoadingAttrs {
+  if (!lazyLoad || present(attrs.loading)) {
+    return {};
+  }
+  if (String(attrs.fetchpriority ?? "").toLowerCase() === HIGH_PRIORITY) {
+    return {};
+  }
+  return present(attrs.decoding) ? { loading: "lazy" } : { decoding: "async", loading: "lazy" };
+}