@jxsuite/compiler 2.0.8 → 3.1.0

package/src/site/context-injection.ts

@@ -1,40 +1,39 @@
 /**
- * Context-injection.js — $page and $site context injection
+ * The build's filesystem half of context injection.
  *
- * Injects project-level and page-level context variables into a page's state before compilation.
- * These are available as $site.* and $page.* in template expressions.
- *
- * Per site-architecture spec §10: $site.name — from project.json name $site.url — from project.json
- * url $site.state.* — site-wide reactive state $page.url — current page URL path $page.title — page
- * title $page.params — dynamic route parameters (if any) $page.locale/$page.dir — the route's
- * language and writing direction (§13.4) $page.alternates — this page in every language it exists
- * in (§13.5)
+ * `injectContext` itself is `@jxsuite/site/context` — a live renderer binds `${$site.name}` and
+ * `${$page.url}` exactly as a built page does, so the two must not be separate implementations.
+ * What is left here is the one thing that needs real directories: rebasing a project-level relative
+ * `imports` entry onto the page's own directory.
  *
  * @docs framework/site/i18n
  */
 
 import { dirname, relative, resolve } from "node:path";
-import type {
-  JxDocument,
-  JxElement,
-  JxStateDefinition,
-  ProjectConfig,
-} from "@jxsuite/schema/types";
-import { localeDirection, localeLabel } from "@jxsuite/schema/locale";
-import { localeOfRoute } from "./i18n.ts";
-import type { ResolvedI18n, TranslationMember } from "./i18n.ts";
-import type { SiteRoute } from "../types.ts";
+import { injectContext as injectContextWith } from "@jxsuite/site/context";
+import type { ImportRebaser, SiteRoute, TranslationMember } from "@jxsuite/site/context";
+import type { ResolvedI18n } from "@jxsuite/schema/locale";
+import type { JxDocument, ProjectConfig } from "@jxsuite/schema/types";
+
+/** An {@link ImportRebaser} over a project on disk. */
+export function nodeImportRebaser(projectRoot: string): ImportRebaser {
+  return (src, route) => {
+    if (!route.sourcePath) {
+      return src;
+    }
+    return `./${relative(dirname(route.sourcePath), resolve(projectRoot, src))}`;
+  };
+}
 
 /**
- * Inject $site and $page context into a page document's state.
+ * Inject $site and $page context for a page compiled from a project on disk.
  *
  * @param {JxDocument} doc - The page document (mutated)
  * @param {ProjectConfig} projectConfig - Loaded project configuration
  * @param {SiteRoute} route - The resolved route for this page
  * @param {string | null} [projectRoot] - Absolute path to the project root (for import rebasing)
  * @param {ResolvedI18n | null} [i18n] - Validated locale config, when the project declares one
- * @param {readonly TranslationMember[]} [translations] - This route's translation set, itself
- *   included
+ * @param {readonly TranslationMember[]} [translations] - This route's translation set
  * @returns {JxDocument} The mutated document
  */
 export function injectContext(
@@ -44,110 +43,13 @@ export function injectContext(
   projectRoot: string | null = null,
   i18n: ResolvedI18n | null = null,
   translations: readonly TranslationMember[] = [],
-) {
-  if (!doc.state) {
-    doc.state = {};
-  }
-
-  // $site context — read-only project-level data
-  doc.state.$site = {
-    name: projectConfig.name ?? "Jx Site",
-    url: projectConfig.url ?? "",
-    ...(i18n === null ? {} : { defaultLocale: i18n.defaultLocale, locales: i18n.locales }),
-    ...projectConfig.state,
-  };
-
-  /*
-   * $page context — read-only page-level data.
-   *
-   * The locale lives here rather than as a top-level `$locale` because that is what it is: a
-   * property of the route, not a third ambient namespace beside $site and $page. A document's own
-   * `$lang` still wins over the route's locale, so this is the resolved answer, not the prefix.
-   */
-  const pageLang =
-    (typeof doc.$lang === "string" ? doc.$lang : undefined) ??
-    localeOfRoute(route.urlPattern, i18n) ??
-    projectConfig.defaults?.lang;
-  /*
-   * The same translation set `<head>` advertises, in the shape a template can render: a language
-   * switcher is the one part of a multilingual site the framework cannot write for the author, and
-   * without this it could only be hand-maintained — a hardcoded list of URLs that goes stale the
-   * moment a page gains or loses a translation, silently, in the one place a reader would use it.
-   *
-   * Site-absolute URLs, not the absolute hrefs `<head>` needs: a switcher is an internal link, and
-   * it has to work before `url` is configured. `current` marks the member this route *is*, taken
-   * from the route rather than from `$page.locale`, because a document whose `$lang` disagrees with
-   * its directory is still served from that directory.
-   */
-  const alternates = translations.map((member) => ({
-    code: member.locale,
-    current: member.urlPattern === route.urlPattern,
-    dir: localeDirection(member.locale),
-    label: localeLabel(member.locale),
-    url: member.urlPattern,
-  }));
-  doc.state.$page = {
-    params: route._pathParams ?? {},
-    title: doc.title ?? doc._pageTitle ?? projectConfig.name ?? "",
-    url: route.urlPattern,
-    ...(alternates.length > 0 && { alternates }),
-    ...(pageLang === undefined ? {} : { dir: localeDirection(pageLang), locale: pageLang }),
-  };
-
-  // Merge project-level state into page state (page wins on conflicts)
-  if (projectConfig.state) {
-    for (const [key, value] of Object.entries(projectConfig.state)) {
-      if (key !== "$site" && key !== "$page" && !(key in doc.state)) {
-        doc.state[key] = value as JxStateDefinition;
-      }
-    }
-  }
-
-  // Merge project-level $media into page $media
-  if (projectConfig.$media) {
-    doc.$media = { ...projectConfig.$media, ...doc.$media };
-  }
-
-  // Merge project-level imports into page imports (page wins on collision)
-  if (projectConfig.imports && Object.keys(projectConfig.imports).length > 0) {
-    if (!doc.imports) {
-      doc.imports = {};
-    }
-    for (const [name, srcPath] of Object.entries(projectConfig.imports)) {
-      if (!(name in doc.imports)) {
-        const src = srcPath as string;
-        // Only rebase relative paths — bare/npm specifiers pass through unmodified
-        if (projectRoot && route.sourcePath && (src.startsWith("./") || src.startsWith("../"))) {
-          const abs = resolve(projectRoot, src);
-          doc.imports[name] = `./${relative(dirname(route.sourcePath), abs)}`;
-        } else {
-          doc.imports[name] = src;
-        }
-      }
-    }
-  }
-
-  // Merge project-level $elements into page $elements (union, dedup)
-  if (projectConfig.$elements?.length) {
-    if (!doc.$elements?.length) {
-      doc.$elements = [...projectConfig.$elements];
-    } else {
-      const seen = new Set<string>();
-      const merged: (string | JxElement)[] = [];
-      for (const entry of [
-        ...projectConfig.$elements,
-        ...(doc.$elements as (string | JxElement)[]),
-      ]) {
-        const key =
-          typeof entry === "string" ? entry : /** @type {{ $ref?: string }} */ entry?.$ref;
-        if (key && !seen.has(key)) {
-          seen.add(key);
-          merged.push(entry);
-        }
-      }
-      doc.$elements = merged;
-    }
-  }
-
-  return doc;
+): JxDocument {
+  return injectContextWith(
+    doc,
+    projectConfig,
+    route,
+    projectRoot === null ? null : nodeImportRebaser(projectRoot),
+    i18n,
+    translations,
+  );
 }

package/src/site/headers-emitter.ts

@@ -11,6 +11,7 @@
  * @docs framework/site/deployment
  */
 
+import { withBase } from "@jxsuite/schema/asset-paths";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { buildCspHeaders, normalizeCspConfig } from "./csp.ts";
@@ -181,6 +182,25 @@ export function contentTypeRules(outDir: string): HeaderRule[] {
   return rules;
 }
 
+/**
+ * Re-root every rule's pattern onto the deployment base.
+ *
+ * A `_headers` pattern is matched against the REQUEST path, so on a site served from `/m/my-site/`
+ * a rule for `/assets/*` matches nothing at all — which is silent, because a missing cache header
+ * is a slow site rather than a broken one. The generated patterns and the author's `build.headers`
+ * rules go through together: both describe the same URL space.
+ *
+ * @param {readonly HeaderRule[]} rules
+ * @param {string} base - From `siteBasePath`; `""` returns the rules untouched
+ * @returns {HeaderRule[]}
+ */
+export function rebaseHeaderRules(rules: readonly HeaderRule[], base: string): HeaderRule[] {
+  if (base === "") {
+    return [...rules];
+  }
+  return rules.map((rule) => ({ headers: rule.headers, pattern: withBase(base, rule.pattern) }));
+}
+
 /** Render rules in the Netlify / Cloudflare Pages `_headers` format. */
 export function renderHeaders(rules: readonly HeaderRule[]): string {
   const blocks = rules.map((rule) => {

package/src/site/i18n.ts

@@ -12,7 +12,12 @@
  * @docs framework/site/i18n
  */
 
-import { canonicalizeLocale, localeDirection } from "@jxsuite/schema/locale";
+import { siteAbsoluteUrl } from "@jxsuite/schema/asset-paths";
+import {
+  canonicalizeLocale,
+  localeDirection,
+  localeOfRoute as localeForRoute,
+} from "@jxsuite/schema/locale";
 import type { ResolvedI18n, TextDirection } from "@jxsuite/schema/locale";
 
 /*
@@ -26,30 +31,10 @@ import type { ResolvedI18n, TextDirection } from "@jxsuite/schema/locale";
  */
 export { resolveI18n } from "@jxsuite/schema/locale";
 export type { LocaleRouting, ResolvedI18n } from "@jxsuite/schema/locale";
-
-/**
- * The locale a URL belongs to.
- *
- * Matching is on the **first path segment**, compared canonically, so `/fr-CA/about/` resolves for
- * a project that declared `fr-ca`. A path under no declared locale is the default locale — under
- * `prefix-except-default` that is the point, and under `prefix-always` it is a page the author put
- * outside the locale tree, which is theirs to place.
- *
- * @param {string} urlPattern - Site-absolute route pattern, e.g. `/fr/about/`
- * @param {ResolvedI18n | null} i18n
- * @returns {string | null} A canonical tag, or null when the project has no i18n
- */
-export function localeOfRoute(urlPattern: string, i18n: ResolvedI18n | null): string | null {
-  if (i18n === null) {
-    return null;
-  }
-  const first = urlPattern.split("/").find(Boolean);
-  if (first === undefined) {
-    return i18n.defaultLocale;
-  }
-  const canonical = canonicalizeLocale(first);
-  return canonical !== null && i18n.locales.includes(canonical) ? canonical : i18n.defaultLocale;
-}
+/* `localeOfRoute` lives beside `resolveI18n` in `@jxsuite/schema/locale` for the reason that one
+   does: the studio and the cloud preview both have to answer "what language is this URL" and
+   neither can import this package. Re-exported so nothing in the build had to change its import. */
+export { localeOfRoute } from "@jxsuite/schema/locale";
 
 /**
  * Routes sitting outside the locale tree under `prefix-always`.
@@ -239,7 +224,7 @@ export function translationSets(
     if (route.translationKey !== undefined) {
       declared.add(route.urlPattern);
     }
-    const locale = localeOfRoute(route.urlPattern, i18n);
+    const locale = localeForRoute(route.urlPattern, i18n);
     if (locale === null) {
       continue;
     }
@@ -314,13 +299,13 @@ export function localeAlternates(
     let alternates = built.get(members);
     if (alternates === undefined) {
       alternates = members.map((m) => ({
-        href: new URL(m.urlPattern, siteUrl).href,
+        href: siteAbsoluteUrl(m.urlPattern, siteUrl),
         hreflang: m.locale,
       }));
       const fallback = members.find((m) => m.locale === i18n.defaultLocale);
       if (fallback !== undefined) {
         alternates.push({
-          href: new URL(fallback.urlPattern, siteUrl).href,
+          href: siteAbsoluteUrl(fallback.urlPattern, siteUrl),
           hreflang: "x-default",
         });
       }

package/src/site/image-optimizer.ts

@@ -124,10 +124,24 @@ export function contentHash(srcPath: string) {
  * @param {ImageConfig} config
  * @returns {string}
  */
+/**
+ * Bumped whenever the pipeline decides variants differently for the same settings.
+ *
+ * The cache key is settings plus source bytes, which answers "would this produce the same output?"
+ * only while the code between them is fixed. It is not: capping variants at the largest configured
+ * width changed the answer for every image already cached, and without a version here those images
+ * keep their stale manifests — including the oversized variants the change exists to stop
+ * emitting.
+ *
+ * 1 → 2: variants stop at the largest configured width (compiler.md §7.2).
+ */
+const PIPELINE_VERSION = 2;
+
 export function configHash(config: ImageConfig) {
   const key = JSON.stringify({
     formats: config.formats,
     quality: config.quality,
+    v: PIPELINE_VERSION,
     widths: config.widths,
   });
   return createHash("md5").update(key).digest("hex").slice(0, 8);
@@ -166,8 +180,24 @@ export async function processImage(srcPath: string, cacheImgDir: string, config:
 
   const variants: ImageVariant[] = [];
 
+  /*
+   * The configured ladder, capped at the source's own width — upscaling only wastes bytes.
+   *
+   * A source SMALLER than every rung would otherwise produce no variants at all, and one that falls
+   * between rungs would never be offered at its native resolution, so both get their own width
+   * added. A source LARGER than the top rung does not: the largest configured width is the ceiling
+   * the project chose, and honouring it is the point of configuring it.
+   *
+   * This used to add the native width unconditionally, so a 3840 px screenshot shipped a 3840 px
+   * AVIF *and* WebP — encoded on every cold build, copied into dist, and offered as a `3840w`
+   * candidate that no `sizes` on any real viewport would pick.
+   */
+  const ceiling = config.widths.length > 0 ? Math.max(...config.widths) : meta.width;
   const widths = config.widths.filter((w) => w <= meta.width);
-  if (widths.length === 0 || !widths.includes(meta.width)) {
+  if (meta.width < ceiling && !widths.includes(meta.width)) {
+    widths.push(meta.width);
+  }
+  if (widths.length === 0) {
     widths.push(meta.width);
   }
   widths.sort((a, b) => a - b);

package/src/site/image-transform.ts

@@ -25,7 +25,7 @@ import { imgLoadingAttrs } from "./img-loading.ts";
 import { resolveAssetUrl } from "@jxsuite/schema/asset-paths";
 
 import type { AssetMount } from "@jxsuite/schema/asset-paths";
-import type { ImageConfig, ImageManifest } from "./image-optimizer.ts";
+import type { ImageConfig, ImageManifest, ImageVariant } from "./image-optimizer.ts";
 import type { JxDocument, JxMutableNode } from "@jxsuite/schema/types";
 import type { CacheManifest } from "./image-cache.ts";
 
@@ -267,13 +267,23 @@ async function walkAndTransform(
   metaCache: ImageMetaCache,
   imageRefs: Map<string, ImageManifest>,
   mounts: readonly AssetMount[],
+  containerWidth: number | null = null,
 ) {
   if (!node || typeof node !== "object") {
     return;
   }
 
   if (node.tagName === "img") {
-    await transformImgNode(node, config, projectRoot, cache, metaCache, imageRefs, mounts);
+    await transformImgNode(
+      node,
+      config,
+      projectRoot,
+      cache,
+      metaCache,
+      imageRefs,
+      mounts,
+      containerWidth,
+    );
     // 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") {
@@ -294,11 +304,22 @@ async function walkAndTransform(
   }
 
   if (Array.isArray(node.children)) {
+    // Every descendant is bounded by the narrowest literal max-width above it.
+    const inner = containerWidthOf(node, containerWidth);
     for (const child of node.children) {
       if (typeof child === "string") {
         continue;
       }
-      await walkAndTransform(child, config, projectRoot, cache, metaCache, imageRefs, mounts);
+      await walkAndTransform(
+        child,
+        config,
+        projectRoot,
+        cache,
+        metaCache,
+        imageRefs,
+        mounts,
+        inner,
+      );
     }
   }
 }
@@ -327,6 +348,8 @@ interface ResolvedVariants {
   dims: { width: number; height: number } | null;
   /** One entry per additional format, when the image is to be wrapped in a `<picture>`. */
   sources: PictureSource[];
+  /** Resized last-resort `src`, when a universally decodable format was emitted. */
+  fallbackSrc?: string | undefined;
 }
 
 /**
@@ -417,7 +440,43 @@ async function resolveVariants(
    * 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 ?? "" };
+  return {
+    dims,
+    fallbackSrc: fallbackVariant(manifest.variants, config.formats),
+    sources: wrap ? available : [],
+    srcset: available[0]?.srcset ?? "",
+  };
+}
+
+/**
+ * Formats an `<img src>` may point at without narrowing who can see the image.
+ *
+ * `src` is the last resort — reached only by a client that understood neither `srcset` nor any
+ * `<source type>`, which in practice means it understands JPEG and PNG and little else.
+ */
+const UNIVERSAL_FORMATS: readonly string[] = ["jpeg", "png"];
+
+/**
+ * The largest emitted variant a `src` can safely fall back to, or `undefined` to keep the original.
+ *
+ * The original is a correct fallback and a terrible one: it is the unresized source, so a 3840 px
+ * screenshot leaves a 1.7 MB PNG on the end of the chain. A resized variant of the same universally
+ * decodable format is strictly better. When the project emits no such format — `["webp", "avif"]`
+ * is a common and reasonable choice — there is nothing safe to point at, and the original stays: a
+ * smaller image nobody can decode is not an improvement.
+ */
+function fallbackVariant(variants: ImageVariant[], formats: readonly string[]): string | undefined {
+  const format = UNIVERSAL_FORMATS.find((candidate) => formats.includes(candidate));
+  if (format === undefined) {
+    return undefined;
+  }
+  let best: ImageVariant | undefined;
+  for (const variant of variants) {
+    if (variant.format === format && (best === undefined || variant.width > best.width)) {
+      best = variant;
+    }
+  }
+  return best?.outputPath;
 }
 
 /**
@@ -429,6 +488,61 @@ async function resolveVariants(
  * @param {Map<string, ImageManifest>} imageRefs
  * @param {readonly AssetMount[]} mounts
  */
+const CSS_LENGTH = /^(\d+(?:\.\d+)?)(px|rem)$/;
+
+/** A CSS length in px, but only when it is a plain `px`/`rem` literal. `null` for anything else. */
+function pxLength(value: unknown): number | null {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const match = CSS_LENGTH.exec(value.trim());
+  if (!match) {
+    return null;
+  }
+  const n = Number(match[1]);
+  return match[2] === "rem" ? n * 16 : n;
+}
+
+/**
+ * The narrowest px `max-width`/`width` an element at this point in the tree sits inside.
+ *
+ * Only literal lengths count. A `clamp()`, a percentage or a custom property is a real constraint
+ * too, but not one the build can resolve — and a wrong `sizes` is worse than none, because the
+ * browser trusts it completely and picks its candidate before layout exists to contradict it.
+ */
+function containerWidthOf(
+  node: JxMutableNode | JxDocument,
+  inherited: number | null,
+): number | null {
+  const style = node.style as Record<string, unknown> | undefined;
+  if (!style || typeof style !== "object") {
+    return inherited;
+  }
+  const declared = pxLength(style.maxWidth) ?? pxLength(style.width);
+  if (declared === null) {
+    return inherited;
+  }
+  return inherited === null ? declared : Math.min(inherited, declared);
+}
+
+/**
+ * The `sizes` an image in a `max-width` container needs.
+ *
+ * `sizes` is a promise about layout, and the browser keeps the browser's side of it absolutely: it
+ * picks a candidate from this string before any layout has happened, and never revisits the choice.
+ * A single project-wide string therefore cannot be right — jxsuite.com's `(max-width: 768px) 100vw,
+ * 50vw` describes a half-width image, while its hero renders full-width inside a 960 px column, so
+ * the same string is too small on a wide screen and too large on a narrow one. The container width
+ * is layout the compiler already holds, so it is the better answer wherever it exists.
+ */
+function sizesForContainer(containerWidth: number | null): string | undefined {
+  if (containerWidth === null) {
+    return undefined;
+  }
+  const width = Math.round(containerWidth);
+  return `(max-width: ${width}px) 100vw, ${width}px`;
+}
+
 async function transformImgNode(
   node: JxMutableNode | JxDocument,
   config: ImageConfig,
@@ -437,6 +551,7 @@ async function transformImgNode(
   metaCache: ImageMetaCache,
   imageRefs: Map<string, ImageManifest>,
   mounts: readonly AssetMount[],
+  containerWidth: number | null = null,
 ) {
   if (!node.attributes) {
     node.attributes = {};
@@ -465,10 +580,24 @@ async function transformImgNode(
       )
     : null;
 
+  /*
+   * Precedence: what the author wrote, then what the layout says, then the project-wide default.
+   * The project default is a guess that cannot see the container; the container width is not a
+   * guess, so it outranks it — and an image with neither keeps whatever the project chose.
+   */
+  const ownWidth = containerWidthOf(node, containerWidth);
+  const resolvedSizes =
+    (attrs.sizes as string | undefined) ?? sizesForContainer(ownWidth) ?? config.sizes;
+
   if (variants) {
     if (variants.srcset !== "") {
       attrs.srcset = variants.srcset;
-      attrs.sizes ??= config.sizes;
+      if (resolvedSizes !== undefined) {
+        attrs.sizes = resolvedSizes;
+      }
+      if (variants.fallbackSrc !== undefined) {
+        attrs.src = variants.fallbackSrc;
+      }
     }
     // Intrinsic dimensions prevent layout shift; author-supplied values win.
     if (variants.dims && attrs.width === undefined && attrs.height === undefined) {
@@ -480,7 +609,7 @@ async function transformImgNode(
   Object.assign(attrs, imgLoadingAttrs(attrs, config.lazyLoad));
 
   if (variants && variants.sources.length > 0) {
-    wrapInPicture(node, variants.sources, config.sizes);
+    wrapInPicture(node, variants.sources, resolvedSizes ?? "");
   }
 }
 
@@ -515,7 +644,12 @@ function wrapInPicture(
   node.attributes = {};
   node.children = [
     ...sources.map((source) => ({
-      attributes: { sizes: inheritedSizes, srcset: source.srcset, type: source.type },
+      attributes: {
+        // An empty `sizes` is not a neutral default — omit it and let the browser assume 100vw.
+        ...(inheritedSizes === "" ? {} : { sizes: inheritedSizes }),
+        srcset: source.srcset,
+        type: source.type,
+      },
       tagName: "source",
     })),
     img,