@jxsuite/compiler 2.0.8 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/compiler",
-  "version": "2.0.8",
+  "version": "3.0.0",
   "description": "Jx static HTML compiler, island detector, and site builder",
   "license": "MIT",
   "repository": {
@@ -42,22 +42,23 @@
     "build:site": "bun src/cli.ts build",
     "test": "bun test --isolate",
     "test:coverage": "bun test --isolate --coverage",
-    "upgrade": "bunx npm-check-updates -u && bun install"
+    "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@apidevtools/json-schema-ref-parser": "^16.0.0",
-    "@jxsuite/create": "^1.3.7",
-    "@jxsuite/runtime": "^2.1.0",
-    "@jxsuite/schema": "^1.9.0",
+    "@apidevtools/json-schema-ref-parser": "^16.0.1",
+    "@jxsuite/create": "^1.3.8",
+    "@jxsuite/runtime": "^3.0.0",
+    "@jxsuite/schema": "^2.0.0",
+    "@jxsuite/site": "^1.0.0",
     "@vue/reactivity": "3.5.41",
     "esbuild": "^0.28.2",
     "lit-html": "^3.3.3",
-    "sharp": "^0.35.3"
+    "sharp": "^0.35.4"
   },
   "devDependencies": {
-    "@happy-dom/global-registrator": "^20.11.6",
-    "@jxsuite/connector": "^0.5.5",
-    "@jxsuite/parser": "^1.5.6",
+    "@happy-dom/global-registrator": "^20.11.8",
+    "@jxsuite/connector": "^0.5.6",
+    "@jxsuite/parser": "^1.6.0",
     "@types/mdast": "^4.0.4"
   }
 }

package/src/shared.ts

@@ -10,7 +10,9 @@ import {
   COLOR_SCHEME_ATTR,
   COLOR_SCHEME_STORAGE_KEY,
   RESERVED_KEYS,
+  booleanAttrValue,
   camelToKebab,
+  isSingleExpression,
   pureSchemeOf,
   resolveAtQuery,
   schemeSelectors,
@@ -55,7 +57,9 @@ export {
   COLOR_SCHEME_ATTR,
   COLOR_SCHEME_STORAGE_KEY,
   RESERVED_KEYS,
+  booleanAttrValue,
   camelToKebab,
+  isSingleExpression,
   pureSchemeOf,
   schemeSelectors,
   toCSSText,
@@ -107,11 +111,26 @@ export function emitFormulaFn(def: { parameters?: unknown[] }, compiledBody: str
  * @returns {string}
  */
 export function srcImportBinding(key: string, def: unknown) {
-  const declared = (def as { $export?: unknown } | null | undefined)?.$export;
-  const exportName = typeof declared === "string" && declared !== "" ? declared : key;
+  const exportName = srcExportName(key, def);
   return exportName === key ? key : `${exportName} as ${key}`;
 }
 
+/**
+ * The export a Function-def `$src` entry names inside its module: `$export`, or the state key.
+ *
+ * Separate from {@link srcImportBinding} because a lazily loaded `$src` has no import clause to
+ * alias in — it reaches the export off the module namespace object a dynamic `import()` resolves
+ * to, where the local name is chosen by the generated code and only the export name is fixed.
+ *
+ * @param {string} key - State key
+ * @param {unknown} def - The Function definition
+ * @returns {string}
+ */
+export function srcExportName(key: string, def: unknown): string {
+  const declared = (def as { $export?: unknown } | null | undefined)?.$export;
+  return typeof declared === "string" && declared !== "" ? declared : key;
+}
+
 /**
  * Emit the auto-fetch `effect()` for a `$prototype: "Request"` state entry.
  *
@@ -780,37 +799,6 @@ function readsRuntimeOnlyState(str: string, scope: Record<string, unknown>) {
   return false;
 }
 
-/**
- * Whether the whole string is exactly ONE `${…}` — the interpolation that opens at index 0 also
- * closes at the final character.
- *
- * A greedy `/^\$\{(.+)\}$/` also matched `"${a} / ${b}"`, spliced the interior into `return (a} /
- * ${b)`, and the SyntaxError became a silent null: the node rendered empty, and a `$head` entry
- * shipped its own template text. A brace-depth scan is exact where a tightened regex is not —
- * `"${`${a}-x`}"` is still one expression, and must keep returning a raw value.
- *
- * @param {string} str
- * @returns {boolean}
- */
-export function isSingleExpression(str: string): boolean {
-  if (!str.startsWith("${") || !str.endsWith("}")) {
-    return false;
-  }
-  let depth = 0;
-  for (let i = 1; i < str.length; i += 1) {
-    const c = str[i];
-    if (c === "{") {
-      depth += 1;
-    } else if (c === "}") {
-      depth -= 1;
-      if (depth === 0) {
-        return i === str.length - 1;
-      }
-    }
-  }
-  return false;
-}
-
 /**
  * @param {string} str
  * @param {Record<string, unknown>} scope
@@ -927,10 +915,34 @@ export function buildAttrs(def: JxElement | JxMutableNode, scope: Record<string,
   if (def.attributes) {
     for (const [k, v] of Object.entries(def.attributes)) {
       const value = resolveStaticValue(v, scope);
+      /*
+       * A boolean is the attribute's PRESENCE or its text, depending on which family HTML puts the
+       * attribute in — `booleanAttrValue` owns that judgement, and the runtime asks it the same
+       * question so a prerendered page cannot change meaning as it hydrates.
+       *
+       * @docs framework/concepts/elements
+       *
+       * Stringifying a boolean emitted `open="false"`, and HTML reads a boolean attribute by
+       * Presence alone — so the author wrote "closed" and the page rendered open. Nor could the
+       * Template return nothing instead: `resolveDocTemplates` and `expandMapTemplate` both `?? v`,
+       * Which restores the raw `${…}` source on a null. Absence therefore has to be expressible
+       * HERE, and `false` is the only value that can mean it.
+       *
+       * A *string* is never reinterpreted, in either family. `"aria-current": "false"` is the docs
+       * Sidebar's own not-the-current-page marker, and second-guessing it would be this same defect
+       * Pointed the other way.
+       */
+      if (typeof value === "boolean") {
+        const text = booleanAttrValue(k, value);
+        if (text !== null) {
+          out += text === "" ? ` ${k}` : ` ${k}="${escapeHtml(text)}"`;
+        }
+        continue;
+      }
       if (
         value !== null &&
         value !== undefined &&
-        (typeof value === "string" || typeof value === "number" || typeof value === "boolean")
+        (typeof value === "string" || typeof value === "number")
       ) {
         out += ` ${k}="${escapeHtml(String(value))}"`;
       }
@@ -1233,7 +1245,20 @@ export function compileStyles(
   if (rules.length === 0) {
     return "";
   }
-  return `<style>\n${rules.join("\n")}\n</style>`;
+  return `<style>\n${escapeStyleText(rules.join("\n"))}\n</style>`;
+}
+
+/**
+ * Make CSS safe to sit inside a `<style>` element.
+ *
+ * An HTML parser ends a `<style>` at the first `</style` in the text, wherever it appears — inside
+ * a CSS string, inside a comment, anywhere. Since a project's style values are author data
+ * (`content: "</style>"` is a legal declaration), inlining them unescaped would let content close
+ * the element and the rest of the stylesheet would render as markup. `\/` is a valid CSS escape for
+ * `/`, so the declaration keeps its meaning.
+ */
+export function escapeStyleText(css: string): string {
+  return css.replaceAll(/<\/(?=style)/gi, String.raw`<\/`);
 }
 
 /**

package/src/site/bundler.ts

@@ -92,6 +92,14 @@ export interface BundleOptions {
   conditions?: string[];
   /** Resolution hooks, applied before the bundler's own resolution. */
   resolver?: BundleResolver;
+  /**
+   * Whether to minify the bundle.
+   *
+   * Defaults to true for `target: "browser"` and false everywhere else: browser output is parsed on
+   * someone else's phone, server output is read off a stack trace. Callers override it — the site
+   * build from `build.minify`, and `jx dev` to keep a breakpoint on a line somebody wrote.
+   */
+  minify?: boolean;
   /**
    * Called with the absolute path of every file the bundler loads.
    *
@@ -161,6 +169,21 @@ export function workerBundleOptions(adapter: string): BundleOptions {
  */
 const BROWSER_DEFINE = { "process.env.NODE_ENV": '"production"' } as const;
 
+/**
+ * Whether this bundle is minified.
+ *
+ * Browser output defaults to minified and everything else to readable. Measured on jxsuite.com's
+ * own deployed bytes, the six scripts a page loads go from 155,254 B to 64,994 B — and it is the 90
+ * kB of source a phone no longer has to parse, not the 16 kB it no longer downloads, that moves
+ * Total Blocking Time.
+ *
+ * This widens the backend divergence {@link BROWSER_DEFINE} warns about: the two minifiers agree on
+ * semantics, not on bytes. A build that diffs `dist/` must pin one backend (`JX_BUNDLER=esbuild`).
+ */
+function shouldMinify(opts: BundleOptions): boolean {
+  return opts.minify ?? opts.target === "browser";
+}
+
 /** Map a bundle target to esbuild's platform (conditions carry the workerd specifics). */
 function esbuildPlatform(target: BundleTargetName): "browser" | "node" {
   return target === "node" || target === "bun" ? "node" : "browser";
@@ -193,7 +216,7 @@ export async function bundleEntry(request: BundleRequest, opts: BundleOptions):
       external,
       format: "esm",
       logLevel: "silent",
-      minify: false,
+      minify: shouldMinify(opts),
       outfile: request.outfile,
       platform: esbuildPlatform(opts.target),
       plugins: plugins as unknown as NonNullable<Parameters<typeof esbuild.build>[0]["plugins"]>,
@@ -207,7 +230,7 @@ export async function bundleEntry(request: BundleRequest, opts: BundleOptions):
     entrypoints: [request.entryPath],
     external,
     format: "esm",
-    minify: false,
+    minify: shouldMinify(opts),
     plugins,
     target: bunTarget(opts.target),
     throw: false,
@@ -254,7 +277,8 @@ export async function resolveThroughBundler(
     await bundleSource(
       `export * from ${JSON.stringify(specifier)};\n`,
       { outfile, resolveDir },
-      { ...opts, onFileLoaded: (path) => loaded.push(path) },
+      // The output is deleted in `finally` — this only wants the resolution, so never pay to minify.
+      { ...opts, minify: false, onFileLoaded: (path) => loaded.push(path) },
     );
   } catch {
     return undefined;
@@ -286,7 +310,7 @@ export async function bundleSource(
       external: opts.external ?? [],
       format: "esm",
       logLevel: "silent",
-      minify: false,
+      minify: shouldMinify(opts),
       outfile,
       platform: esbuildPlatform(opts.target),
       stdin: { contents: source, loader: "js", resolveDir, sourcefile: "jx-entry.js" },

package/src/site/client-runtime.ts

@@ -131,6 +131,7 @@ export async function writeClientRuntime(
   runtime: ClientRuntime,
   outDir: string,
   resolveDir: string = PACKAGE_DIR,
+  minify = true,
 ): Promise<{ written: number; errors: string[] }> {
   const errors: string[] = [];
   let written = 0;
@@ -150,7 +151,7 @@ export async function writeClientRuntime(
       await bundleSource(
         `export * from ${JSON.stringify(mod.specifier)};\n`,
         { outfile, resolveDir },
-        { target: "browser" },
+        { minify, target: "browser" },
       );
       written += 1;
     } catch (error) {
@@ -160,6 +161,52 @@ export async function writeClientRuntime(
   return { errors, written };
 }
 
+/**
+ * The asset paths an import map's `imports` object asks THIS build to write.
+ *
+ * Two kinds of entry are named by a map and produced by nobody: a prefix key's value is the
+ * DIRECTORY its subpaths are served from — `/assets/lit-html/` — rather than a file, and a CDN
+ * fallback belongs to a third party. What is left is the exact set `writeClientRuntime` matches
+ * against, so the promise the HTML makes and the bundles the build writes are read off one rule.
+ */
+export function importMapAssets(imports: Record<string, string>): string[] {
+  return Object.entries(imports)
+    .filter(([specifier, url]) => !isPrefixSpecifier(specifier) && url.startsWith("/"))
+    .map(([, url]) => url);
+}
+
+/**
+ * The same set, read back out of a finished page.
+ *
+ * A page reaches an import map by more than one route: `injectComponentScripts` adds one, and the
+ * page-template tiers in `compile-static`/`compile-client`/`compile-element` emit their own. Only
+ * the first of those was recording what it named, so a project with interactivity but no components
+ * shipped a map pointing at `/assets/vue-reactivity.js` while the set that gates bundling stayed
+ * empty — nothing was written, the page 404'd on both modules and rendered blank, and the build
+ * reported success (issue #227). Scanning the emitted HTML is what makes the two agree no matter
+ * which path produced the map.
+ */
+export function importMapAssetsInHtml(html: string): string[] {
+  const found: string[] = [];
+  for (const match of html.matchAll(/<script type="importmap">([\s\S]*?)<\/script>/g)) {
+    let imports: unknown;
+    try {
+      ({ imports } = JSON.parse(match[1] as string) as { imports?: unknown });
+    } catch {
+      // A map the build did not write and cannot parse names nothing this build must produce.
+      continue;
+    }
+    if (typeof imports !== "object" || imports === null) {
+      continue;
+    }
+    const entries = Object.entries(imports as Record<string, unknown>).filter(
+      (entry): entry is [string, string] => typeof entry[1] === "string",
+    );
+    found.push(...importMapAssets(Object.fromEntries(entries)));
+  }
+  return found;
+}
+
 /** Render the `<script type="importmap">` block for a resolved runtime. */
 export function renderImportMap(imports: Record<string, string>): string {
   const entries = Object.entries(imports)
@@ -216,11 +263,13 @@ const MAX_SUBPATH_PASSES = 10;
  *
  * @param {string} outDir - Build output root
  * @param {string} [resolveDir] - Directory bare specifiers resolve from
+ * @param {boolean} [minify] - Minify the emitted bundles (defaults to the browser-target default)
  * @returns {Promise<{ written: number; errors: string[] }>}
  */
 export async function writeRuntimeSubpaths(
   outDir: string,
   resolveDir: string = PACKAGE_DIR,
+  minify = true,
 ): Promise<{ written: number; errors: string[] }> {
   const errors: string[] = [];
   const done = new Set<string>();
@@ -280,6 +329,7 @@ export async function writeRuntimeSubpaths(
             `export * from ${JSON.stringify(specifier)};\n`,
             { outfile, resolveDir },
             {
+              minify,
               resolver: shareRuntimeCore(mod, outfile, await coreOf(mod), mirrors),
               target: "browser",
             },

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/i18n.ts

@@ -12,7 +12,11 @@
  * @docs framework/site/i18n
  */
 
-import { canonicalizeLocale, localeDirection } from "@jxsuite/schema/locale";
+import {
+  canonicalizeLocale,
+  localeDirection,
+  localeOfRoute as localeForRoute,
+} from "@jxsuite/schema/locale";
 import type { ResolvedI18n, TextDirection } from "@jxsuite/schema/locale";
 
 /*
@@ -26,30 +30,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 +223,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;
     }

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);