@ultimat3/core 5.0.1 → 7.0.0

package/CLAUDE.md

@@ -14,6 +14,7 @@ is a change to every package.
 | New code | add to `CORE_CODE_TITLES` in `error-codes.ts`, else the title is auto-humanised |
 | Time | take a `Clock`; `Date.now()` / `new Date()` only inside `clock.ts` |
 | Context | never thread `ctx` as a parameter — `useContext()` |
+| A value ambient across an `await` | `asyncContext<T>(subject)` from `async-context.ts`, in **every** package — never `new AsyncLocalStorage` |
 | Exports | add to `src/index.ts` explicitly; no `export *`. Three subjects that each span a dozen modules arrive through `src/exports/` — every name is still written out in `index.ts`, so the public surface is one file to read |
 | Files | < 200 LOC, 500 hard ceiling, one responsibility, `kebab-case.ts`, test beside source |
 | Type claims | `type-pins.ts`, never a `.test.ts` — `tsconfig.json` excludes tests, so `tsc` never reads one |
@@ -22,6 +23,24 @@ Deliberate cycles (safe — nothing is referenced at module-evaluation time):
 `errors.ts ⇄ error-codes.ts`. Keep it that way: no top-level `UltimateError` use in
 `error-codes.ts`.
 
+**`async-context.ts` is the framework's ONE `AsyncLocalStorage`, and that is a framework rule
+rather than a core one, `As of 2026-08-20`.** `asyncContext` is exported from `src/index.ts` and
+six modules outside this package opened their own before they adopted it — `@ultimat3/db`'s
+transaction, statement attribution and expected-loop scopes, `@ultimat3/entity`'s `crossTenant`,
+`@ultimat3/ai`'s budget ledger and LLM stream sink. Each was a module-scope `new` a browser bundler
+turns into `TypeError: undefined is not a constructor` at module EVALUATION, so importing any of
+those packages from a client bundle failed before a line of app code ran. Reads degrade to
+`undefined`, writes throw `X_ASYNC_CONTEXT_UNAVAILABLE`; deferring the construction changes nothing
+a server can observe — the storage is built on the first `get()` or `run()` rather than at module
+evaluation, and `getStore()` outside a scope answers `undefined` either way.
+
+The mechanical half is `scripts/async-context-guard.ts`, collected by `x verify`'s `unit` step
+through `scripts/async-context-guard.test.ts` — it refuses a `new AsyncLocalStorage` **and** the
+import that binds the class, aliased or namespaced, anywhere but this one file. The browser-barrel
+test in `async-context.test.ts` covers the same defect for core alone and cannot see another
+package; the guard cannot see a runtime `await import('node:async_hooks')`. Neither is the other's
+duplicate.
+
 `error-render.ts` imports nothing, including from this package — an error factory that dies
 formatting its own message is the failure it exists to prevent, so it cannot depend on anything
 that could itself throw. The same defect shipped three times (`entity`, `flags`, `cli`) before
@@ -85,6 +104,7 @@ shape against a locally declared sample interface for exactly that reason.
 |---|---|---|
 | which deploy this is | `environment.ts` (`ULTIMATE_ENV`) | the twin of `ROLE`; never declare a second env var for it |
 | what this process does | `roles.ts` (`ROLE`) | |
+| how a route renders, caches offline and hydrates | `route-vocabulary.ts` (`RENDER_MODES`, `OFFLINE_STRATEGIES`, `HYDRATE_STRATEGIES`) | tier 0 because SIX packages name them and imports only go down — `render`, `http`, `seo`, `manifest` and `pwa` each kept a hand-copy until 2026-08, and `'spa'` was deleted from one while five went on admitting it under a green typecheck. Every union is `(typeof ARRAY)[number]`, pinned in `type-pins.ts`; `scripts/render-modes.test.ts` refuses a second declaration anywhere in `packages/*/src`. Re-export it, never restate it |
 | which build of the APP this is | `app-version.ts` (`APP_VERSION`) | one reader, `dev` by default: `db` writes it into `x_migrations` and `jobs` into `x_backfills`, and `jobs` cannot reach `db` for the answer |
 | the values | `env.ts` | `checkEnv().values` holds REAL secrets — anything that prints goes through `maskedEnvValues()` |
 | `.env.example` | `env-example.ts` | a projection of the schema, never hand-maintained |

package/README.md

@@ -9,7 +9,8 @@ Zero dependencies, zero `@ultimat3/*` imports.
 | rendering an app's value into a `cause` / `fix` without throwing | `error-render.ts` |
 | code → `{ title, docs }` registry, `registerErrorCodes()` | `error-codes.ts` |
 | `Result<T, E>` for boundaries where throwing is wrong | `result.ts` |
-| request context on `AsyncLocalStorage` | `context.ts` |
+| the one lazy `AsyncLocalStorage`, every ambient scope in the framework | `async-context.ts` |
+| request context on that seam | `context.ts` |
 | `Actor` (`user \| service \| agent \| anonymous`) | `actor.ts` |
 | acting as another actor, with an origin and a reason | `impersonate.ts` |
 | is an error worth retrying? one classification per code | `error-retry.ts` |
@@ -20,6 +21,7 @@ Zero dependencies, zero `@ultimat3/*` imports.
 | the committed encrypted secrets envelope, AES-256-GCM | `secrets.ts` |
 | the two secrets files, and decrypted values → `defineEnv` | `secrets-store.ts` |
 | `defineConfig()` for `app.config.ts` | `config.ts` |
+| the closed route vocabulary every renderer names | `route-vocabulary.ts` |
 | runtime roles + `ROLE` resolution | `roles.ts` |
 | `Clock` — the only source of "now" | `clock.ts` |
 | UUIDv7, nanoid, branded ids | `ids.ts` |
@@ -38,7 +40,7 @@ Zero dependencies, zero `@ultimat3/*` imports.
 | the sockets this process opened, so a self-request is not egress | `listeners.ts` |
 | `defineService('orgs', …)` → `ctx.orgs`, rebuilt per actor | `service.ts` |
 | the registrar table one same-tier package reaches another through | `registrar.ts` |
-| decode → resize → encode, the one image pipeline | `image/` |
+| decode → resize → encode, the one image pipeline (over `Bun.Image`) | `image/` |
 | `assertNever`, `invariant` | `assert.ts` |
 
 ## Errors are instructions
@@ -466,31 +468,55 @@ than in `@ultimat3/time` because `@ultimat3/money` needs it too and tier 1 may n
 
 ```ts
 probeImage(bytes);                                     // { format, width, height, mimeType }
-transformImageBytes(bytes, { width: 640, format: 'jpeg', quality: 80 });
-blurDataUrl(bytes);                                    // 16px PNG data: URI, the LQIP
+await transformImageBytes(bytes, { width: 640, format: 'webp', quality: 80 });
+await blurDataUrl(bytes);                              // ThumbHash PNG data: URI, the LQIP
 ```
 
 `storage` variants, `seo` `<picture>` sources and `pwa` icons are the same three steps —
 decode, resize, encode — with different numbers, so there is one implementation and no second
-scaler for an icon to grow a halo in. Zero dependencies: no `sharp`, no native module.
+scaler for an icon to grow a halo in. The codecs are **`Bun.Image`** — statically-linked
+libjpeg-turbo / libspng / libwebp with SIMD resize kernels, in the runtime. Still zero
+dependencies: no `sharp`, no native module.
+
+Every terminal is `async`, because the pipeline runs on a worker thread. `probeImage` stays
+synchronous: it reads a header and never decodes, which is also why it measures SVG and AVIF that
+no codec here reads.
 
 | | |
 |---|---|
-| Decode / encode | PNG and JPEG. `canDecode()` / `canEncode()` publish the real list |
-| Probe only | WebP, AVIF, GIF, SVG — measured from the header so `width`/`height` still inline and CLS stays 0 |
+| Decode | PNG, JPEG, WebP, GIF. `canDecode()` publishes the real list |
+| Encode | PNG, JPEG, WebP. `canEncode()` publishes the real list |
+| Probe only | AVIF and SVG — measured from the header so `width`/`height` still inline and CLS stays 0 |
 | Anything else | `X_IMAGE_UNSUPPORTED`, naming the format and pointing at an `ImageTransformDriver` |
-| Ceiling | `MAX_IMAGE_PIXELS` (64MP), checked from the header **before** a byte is allocated |
-| Determinism | same bytes + same spec → same output bytes. No clock, no randomness |
-
-Adding a format is a decoder plus an entry in `DECODABLE_FORMATS` / `ENCODABLE_FORMATS` — never a
-second dispatch. An unencodable `format` is refused from the spec alone, before the source is
-decoded, so a request nothing can write never expands 64 megapixels first.
-
-`image/` is the one place in core allowed past the 200-line target, and only there: a JPEG or PNG
-codec is a single algorithm that does not split into smaller responsibilities without inventing
-seams. Nothing else in it qualifies, which is why the segment headers (`jpeg-headers.ts`), the SVG
-text parse (`probe-svg.ts`) and the colour grammar (`color.ts`) are their own files. The 500-line
-hard ceiling applies to all of them.
+| Ceiling | `MAX_IMAGE_PIXELS` (64MP), passed to the decoder as `maxPixels` and refused from the header **before** a byte is allocated |
+| Determinism | same bytes + same spec → same output bytes, **on every platform** |
+
+**AVIF and HEIC are refused everywhere, deliberately.** `Bun.Image` can reach them through an OS
+codec (ImageIO on macOS, WIC on Windows), and this pipeline sets `Bun.Image.backend = 'bun'` on
+every call to forbid exactly that: the static codecs and the Highway geometry kernels are what make
+a laptop and a Linux node produce the same bytes, and `variantKey` is content-addressed. A variant
+that re-encoded differently per platform is a cache that never hits. Producing AVIF means a CDN or
+a custom `ImageTransformDriver`.
+
+`transformImageBytes` has two paths and picks by geometry. When the resampled artwork IS the output
+box it is one `Bun.Image` call, source bytes to encoded bytes. When it is not — a letterbox, a
+`padding`, a `cover` crop — the artwork comes back as PNG and `canvas.ts` composites it, because
+`Bun.Image` resamples but has no compositor and the PWA maskable safe zone is a composite.
+`png-pixels.ts` is the raw-pixel seam that hop needs, 8-bit RGBA only; anything else is
+`X_IMAGE_UNSUPPORTED` naming `transformImageBytes`.
+
+Adding a format is an entry in `DECODABLE_FORMATS` / `ENCODABLE_FORMATS` and a branch in
+`withFormat` — never a second dispatch. An unencodable `format` is refused from the spec alone,
+before the source is decoded, so a request nothing can write never expands 64 megapixels first.
+
+`Bun.Image` rejects with `ERR_IMAGE_*` on `error.code`. `imageFromBunError` is the ONE place that
+is read, mapping it onto `X_IMAGE_UNSUPPORTED` / `X_IMAGE_TOO_LARGE` / `X_IMAGE_DECODE_FAILED`; no
+caller branches on a Bun code.
+
+Two files in `image/` are past the 200-line target and neither splits without inventing a seam:
+`probe.ts` is one algorithm per format over header bytes, and `fixtures.ts` is data. The 500-line
+hard ceiling applies to both. Everything else in `image/` is under the target — deleting the
+hand-rolled JPEG and PNG codecs is what put it there.
 
 `image/fixtures.ts` is byte-exact output from Pillow and ffmpeg on purpose: a codec that only round
 trips against itself proves nothing. Never regenerate a fixture with our own encoder.

package/package.json

@@ -1,9 +1,15 @@
 {
   "name": "@ultimat3/core",
-  "version": "5.0.1",
+  "version": "7.0.0",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
   "license": "MIT",
   "type": "module",
+  "sideEffects": [
+    "./src/context.ts",
+    "./src/lifecycle-errors.ts",
+    "./src/schema-error-codes.ts",
+    "./src/secrets-errors.ts"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/developerz-ai/ultimate.git",

package/src/async-context.ts

@@ -0,0 +1,79 @@
+// Single responsibility: the one lazily-constructed `AsyncLocalStorage` in the framework. Every
+// ambient value core carries — the request context, the active span, the impersonation reason —
+// opens its scope through this seam, so "what happens where there is no async context" has one
+// answer instead of one per module.
+
+// `node:async_hooks` is unavoidable and deliberate: nothing else in Bun makes a value ambient
+// across an `await` without threading it through every signature in the framework.
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { UltimateError } from './errors';
+
+export interface AsyncContext<T> {
+  /** The value in flight, or `undefined` — outside a scope, and in a runtime that has none. */
+  get(): T | undefined;
+  /** Run `fn` with `value` in flight. `X_ASYNC_CONTEXT_UNAVAILABLE` where that is impossible. */
+  run<R>(value: T, fn: () => R): R;
+}
+
+/**
+ * The storage is constructed on the first `get()` or `run()`, never at module scope. That is the
+ * whole point of this file: a browser bundler stubs `node:async_hooks` to `{}` — Bun's
+ * `target: 'browser'` emits `var { AsyncLocalStorage } = (() => ({}))` — so a module-scope `new` threw
+ * `TypeError: undefined is not a constructor` at module EVALUATION, and every package that
+ * transitively imports core was dead on arrival in a client bundle. `@ultimat3/ui` calls itself a
+ * SolidJS design system and could not be put on a client by the only client bundler the framework
+ * has, for this reason and no other.
+ *
+ * The laziness buys the browser bundle, not a server allocation. `open()` runs on a READ as well as
+ * a write, so a server whose first call is `get()` constructs the storage there — it is deferred,
+ * never skipped. What deferring changes is nothing observable: `getStore()` outside a scope answers
+ * `undefined` whether the storage was ever constructed or not, which is what makes it safe.
+ *
+ * **Reads degrade, writes throw**, and that split is the doctrine rather than a convenience.
+ * `get()` answers `undefined` in a browser because that is TRUE — nothing is in flight there, so
+ * "am I inside a scope" has a definite no for an answer and does not deserve an exception. It is
+ * the same call `@ultimat3/ui`'s `solid()` makes: inert where the capability is genuinely absent,
+ * throwing only where a caller asked for something the runtime cannot deliver. `run()` is that
+ * second case, so it names itself with a code and a fix rather than leaving a bare `TypeError`
+ * from a stack that mentions no file the caller wrote.
+ *
+ * **A synchronous save/restore fallback is not the answer here**, and this note exists so that it
+ * is not re-proposed: a module-level `current` swapped in a `try`/`finally` serves sync code and
+ * is silently WRONG across an `await` — two overlapping scopes interleave and the second one's
+ * `finally` restores a value the first is still inside. That is the `jobs: { driver: 'redis' }`
+ * failure mode this repo already paid for once: accepted, unwarned, and wrong in the dangerous
+ * direction. An error a caller can read beats an ambient value that is occasionally somebody
+ * else's.
+ *
+ * `subject` names what could not be opened, and is a `string` by construction — never an
+ * `unknown` reaching a `cause:`, which `bun run error-render` refuses.
+ */
+export function asyncContext<T>(subject: string): AsyncContext<T> {
+  let storage: AsyncLocalStorage<T> | undefined;
+
+  function open(): AsyncLocalStorage<T> | undefined {
+    if (storage !== undefined) return storage;
+    // The stub is an object with no `AsyncLocalStorage` key, so the binding reads `undefined`.
+    if (typeof AsyncLocalStorage !== 'function') return undefined;
+    storage = new AsyncLocalStorage<T>();
+    return storage;
+  }
+
+  return {
+    get(): T | undefined {
+      return open()?.getStore();
+    },
+    run<R>(value: T, fn: () => R): R {
+      const store = open();
+      if (store === undefined) {
+        throw new UltimateError({
+          code: 'X_ASYNC_CONTEXT_UNAVAILABLE',
+          cause: `${subject} needs AsyncLocalStorage, and node:async_hooks is stubbed to {} in this runtime`,
+          fix: `${subject} is server-only — open it in apps/web/server.ts or a route handler, and keep every module that opens one out of the import graph of a client island entry`,
+          meta: { subject },
+        });
+      }
+      return store.run(value, fn);
+    },
+  };
+}

package/src/config.ts

@@ -4,9 +4,13 @@
 
 import { ConfigInvalidError } from './errors';
 import { ROLES, type Role } from './roles';
+// `app.config.ts` CONSUMES the route vocabulary; it does not own it. Declaring `OfflineStrategy`
+// here is what made it copyable — `render`, `manifest` and `pwa` each wrote their own rather than
+// import a name that reads like a config key.
+import type { OfflineStrategy } from './route-vocabulary';
+import { isIanaZoneName } from './time-zone-name';
 
 export type ThemeMode = 'light' | 'dark' | 'system';
-export type OfflineStrategy = 'precache' | 'runtime' | 'network-only';
 export type CacheTier = 'memo' | 'lru' | 'shared' | 'isr' | 'cdn';
 export type RealtimeTier = 'channels' | 'live-queries' | 'local-first';
 export type RealtimeTransport = 'memory' | 'nats' | 'redis';
@@ -205,15 +209,6 @@ const NAME_RE = /^[a-z][a-z0-9-]{1,63}$/;
  */
 const CURRENCY_RE = /^[A-Z]{3}$/;
 
-function isTimeZone(value: string): boolean {
-  try {
-    new Intl.DateTimeFormat('en', { timeZone: value });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 function isLocale(value: string): boolean {
   try {
     return Intl.getCanonicalLocales(value).length === 1;
@@ -252,8 +247,22 @@ function defaults(name: string): Omit<AppConfig, 'name'> {
   };
 }
 
+const BASE_FIX = 'edit app.config.ts to fix the fields named in cause, then run: x verify';
+
+/**
+ * Appended only when the zone is what failed. Axiom 4: an operator holding `'CET'` needs the
+ * spelling to write, and the two refused classes have different remedies — a single-label legacy
+ * name swaps mechanically, an abbreviation or an offset has no replacement at all because it names
+ * no jurisdiction. Deliberately parallel to `@ultimat3/time`'s `X_TIMEZONE_INVALID` fix, since the
+ * two refuse the same strings and an operator may meet either first.
+ */
+const TIMEZONE_FIX =
+  "set defaultTimeZone to an Area/Location name, or UTC — list every accepted one with bun -e \"console.log(Intl.supportedValuesOf('timeZone').join('\\n'))\" — where a legacy single-label name swaps mechanically (Japan → Asia/Tokyo, GB → Europe/London, Universal → UTC), while an abbreviation or numeric offset (CET, EST5EDT, +01:00) carries no DST rule and has no replacement, so name the city whose clock you mean (Europe/Paris, America/New_York)";
+
 function validate(config: AppConfig): void {
   const issues: string[] = [];
+  // Zero or one entry: the zone's own remedy, carried only when the zone is what failed.
+  const zoneFix: string[] = [];
 
   if (!NAME_RE.test(config.name)) {
     issues.push(`name "${config.name}" must match ${String(NAME_RE)}`);
@@ -265,8 +274,14 @@ function validate(config: AppConfig): void {
   if (!config.locales.includes(config.defaultLocale)) {
     issues.push(`defaultLocale "${config.defaultLocale}" is not in locales`);
   }
-  if (!isTimeZone(config.defaultTimeZone)) {
-    issues.push(`defaultTimeZone "${config.defaultTimeZone}" is not an IANA time zone`);
+  // `@ultimat3/time`'s rule, restated because tier 0 cannot import tier 1 — see
+  // `time-zone-name.ts`. One validator means a zone `app.config.ts` accepts is a zone every
+  // `format` call, `task()` and `toZoned` below it can then do arithmetic in.
+  if (!isIanaZoneName(config.defaultTimeZone)) {
+    issues.push(
+      `defaultTimeZone "${config.defaultTimeZone}" is not an IANA Area/Location zone name`,
+    );
+    zoneFix.push(TIMEZONE_FIX);
   }
   if (!CURRENCY_RE.test(config.defaultCurrency)) {
     issues.push(`defaultCurrency "${config.defaultCurrency}" is not a 3-letter ISO 4217 code`);
@@ -284,7 +299,9 @@ function validate(config: AppConfig): void {
   if (issues.length > 0) {
     throw new ConfigInvalidError({
       cause: issues.join('; '),
-      fix: 'edit app.config.ts to fix the fields named in cause, then run: x verify',
+      // The generic instruction goes LAST so the fix line still ends in a command that can be
+      // pasted — a trailing `.` after `x verify` is a command nobody can run.
+      fix: [...zoneFix, BASE_FIX].join('. '),
       meta: { issues },
     });
   }

package/src/context.ts

@@ -2,8 +2,8 @@
 // service bag reach every layer through AsyncLocalStorage instead of being threaded as
 // parameters — otherwise every signature in the framework grows a `ctx` argument twice.
 
-import { AsyncLocalStorage } from 'node:async_hooks';
 import { type Actor, anonymousActor } from './actor';
+import { asyncContext } from './async-context';
 import { type Clock, systemClock } from './clock';
 import { UltimateError } from './errors';
 import { traceId as newTraceId, uuid } from './ids';
@@ -72,7 +72,12 @@ export interface CtxInit {
 
 export type CtxPatch = Omit<CtxInit, 'requestId'>;
 
-const storage = new AsyncLocalStorage<Ctx>();
+/**
+ * `async-context.ts` owns why this is a lazily-opened seam rather than a module-scope
+ * `new AsyncLocalStorage()`, and why a browser gets `undefined` from a read and an error from a
+ * write. It is the same seam `telemetry.ts` and `impersonate.ts` open, on purpose: one answer.
+ */
+const requestContext = asyncContext<Ctx>('the request context');
 
 const neverAborted = new AbortController().signal;
 
@@ -133,16 +138,16 @@ export function createContext(init: CtxInit = {}): Ctx {
 }
 
 export function runWithContext<T>(ctx: Ctx, fn: () => T): T {
-  return storage.run(ctx, fn);
+  return requestContext.run(ctx, fn);
 }
 
 /** The context, or `undefined` outside a request. Prefer `useContext()` in app code. */
 export function tryUseContext(): Ctx | undefined {
-  return storage.getStore();
+  return requestContext.get();
 }
 
 export function useContext(): Ctx {
-  const ctx = storage.getStore();
+  const ctx = tryUseContext();
   if (ctx === undefined) {
     throw new UltimateError({
       code: 'X_NO_CONTEXT',
@@ -154,7 +159,7 @@ export function useContext(): Ctx {
 }
 
 export function hasContext(): boolean {
-  return storage.getStore() !== undefined;
+  return tryUseContext() !== undefined;
 }
 
 /**
@@ -183,7 +188,7 @@ export function withChildContext<T>(patch: CtxPatch, fn: () => T): T {
     signal: patch.signal ?? parent.signal,
     services: { ...carried, ...(patch.services ?? {}) },
   });
-  return storage.run(child, fn);
+  return requestContext.run(child, fn);
 }
 
 /** Resolve a late-bound service. Throws `X_SERVICE_MISSING` rather than returning undefined. */
@@ -222,7 +227,7 @@ export function throwIfAborted(ctx: Ctx = useContext()): void {
  * never mistaken for the customer's own.
  */
 setLoggerContextFields(() => {
-  const ctx = storage.getStore();
+  const ctx = tryUseContext();
   if (ctx === undefined) return undefined;
   const { actor } = ctx;
   return {

package/src/error-codes.ts

@@ -28,6 +28,7 @@ export function errorDocsUrl(code: string): string {
 /** Codes owned by `@ultimat3/core`. Every other package calls `registerErrorCodes()`. */
 const CORE_CODE_TITLES = {
   X_ABORTED: 'operation aborted',
+  X_ASYNC_CONTEXT_UNAVAILABLE: 'async context unavailable',
   X_CONFIG_INVALID: 'app.config.ts is invalid',
   X_CURSOR_INVALID: 'pagination cursor is malformed, tampered with or from another query',
   X_CURSOR_SECRET_DEV: 'cursors are signed with the shipped development key',

package/src/error-reporter-sentry.ts

@@ -64,7 +64,7 @@ export function parseSentryDsn(dsn: string): SentryDsn {
 }
 
 /** The protocol's own level names. `warning`/`error`/`fatal` happen to be the same three words. */
-const LEVELS: Readonly<Record<ErrorSeverity, string>> = Object.freeze({
+const LEVELS = Object.freeze<Record<ErrorSeverity, string>>({
   warning: 'warning',
   error: 'error',
   fatal: 'fatal',

package/src/image/canvas.ts

@@ -0,0 +1,170 @@
+// Single responsibility: the GEOMETRY of a resize — output box, padded inner area, drawn size —
+// and the source-over composite that places the drawn artwork on it. `Bun.Image` resamples but
+// cannot letterbox, pad or crop, so this is the half of a transform it does not do; keeping the
+// arithmetic here is also what lets a caller ask for the box before any pixel exists.
+
+import { parseColor } from './color';
+import { imageUnsupported } from './errors';
+import { assertPixelBudget, createRaster, type ImageSize, type Raster } from './raster';
+
+export type ImageFit = 'cover' | 'contain';
+
+export interface ResizeSpec {
+  readonly width?: number | undefined;
+  readonly height?: number | undefined;
+  /** Default 'contain'. */
+  readonly fit?: ImageFit | undefined;
+  /** Fraction of the shorter OUTPUT edge left empty on every side. `0 <= padding < 0.5`. */
+  readonly padding?: number | undefined;
+  /** '#rgb' | '#rgba' | '#rrggbb' | '#rrggbbaa' | 'transparent'. Default transparent. */
+  readonly background?: string | undefined;
+}
+
+function assertDimension(value: number, field: string): void {
+  if (!Number.isInteger(value) || value < 1) {
+    throw imageUnsupported(
+      `resize ${field} is ${value}, which is not a whole number of pixels above zero`,
+      `pass an integer ${field} of 1 or more, or omit it to derive it from the source`,
+      { field, value },
+    );
+  }
+}
+
+/**
+ * The output CANVAS size. A single-axis request clamps to the source: asking for `width: 2000`
+ * of a 400px original must not invent 1600 pixels of blur, it must hand back the 400.
+ */
+export function fitBox(source: ImageSize, spec: ResizeSpec): ImageSize {
+  const { width, height } = spec;
+  if (width !== undefined) assertDimension(width, 'width');
+  if (height !== undefined) assertDimension(height, 'height');
+  if (width !== undefined && height !== undefined) return { width, height };
+  if (width !== undefined) {
+    const w = Math.min(width, source.width);
+    return { width: w, height: Math.max(1, Math.round((w * source.height) / source.width)) };
+  }
+  if (height !== undefined) {
+    const h = Math.min(height, source.height);
+    return { width: Math.max(1, Math.round((h * source.width) / source.height)), height: h };
+  }
+  return { width: source.width, height: source.height };
+}
+
+/** The size the source is DRAWN at inside `box` — no letterbox, no crop maths. May upscale. */
+export function scaledToFit(source: ImageSize, box: ImageSize, fit: ImageFit): ImageSize {
+  const x = box.width / source.width;
+  const y = box.height / source.height;
+  const scale = fit === 'cover' ? Math.max(x, y) : Math.min(x, y);
+  return {
+    width: Math.max(1, Math.round(source.width * scale)),
+    height: Math.max(1, Math.round(source.height * scale)),
+  };
+}
+
+/** The whole plan for one transform, decided before a pixel is touched. */
+export interface Layout {
+  /** The output canvas. */
+  readonly box: ImageSize;
+  /** Pixels of padding on each edge. */
+  readonly pad: number;
+  /** The area inside the padding the artwork may occupy. */
+  readonly inner: ImageSize;
+  /** What the source is resampled to before it is placed. */
+  readonly drawn: ImageSize;
+  /** Parsed once, here, so an unspellable colour is refused before any pixel is produced. */
+  readonly background: readonly [number, number, number, number];
+  /** False when `drawn` IS the box and nothing shows through — the resampler's output is the answer. */
+  readonly needsCanvas: boolean;
+}
+
+export function layOut(source: ImageSize, spec: ResizeSpec): Layout {
+  const box = fitBox(source, spec);
+  assertPixelBudget(box.width, box.height, 'resize');
+  const padding = spec.padding ?? 0;
+  if (!Number.isFinite(padding) || padding < 0 || padding >= 0.5) {
+    throw imageUnsupported(
+      `resize padding is ${padding}, outside the 0 <= padding < 0.5 range`,
+      'pass a fraction of the shorter output edge, e.g. 0.1 for a 10% border on every side',
+      { padding },
+    );
+  }
+  const pad = Math.round(Math.min(box.width, box.height) * padding);
+  const inner = { width: box.width - 2 * pad, height: box.height - 2 * pad };
+  if (inner.width < 1 || inner.height < 1) {
+    throw imageUnsupported(
+      `padding ${padding} leaves no room inside a ${box.width}x${box.height} output`,
+      'lower the padding or raise the requested width and height',
+      { padding, pad, width: box.width, height: box.height },
+    );
+  }
+  const drawn = scaledToFit(source, inner, spec.fit ?? 'contain');
+  // Parsed even when the fast path will not use it: 'chartreuse' must be refused whether or not
+  // the geometry happens to hide the colour, or the rejection depends on the source's dimensions.
+  const background = parseColor(spec.background ?? 'transparent');
+  // An opaque background still shows THROUGH a source with alpha, so it needs the canvas even at
+  // full bleed. A transparent one does not, and skipping it keeps a plain `srcset` variant out of
+  // the RGBA round trip entirely.
+  const needsCanvas =
+    drawn.width !== box.width || drawn.height !== box.height || background[3] !== 0;
+  return { box, pad, inner, drawn, background, needsCanvas };
+}
+
+function fill(canvas: Raster, color: readonly [number, number, number, number]): void {
+  const [r, g, b, a] = color;
+  // A zero-alpha background is canonicalised to all-zero, matching the composite's own
+  // `outA === 0 -> outC = 0`: '#ff000000' and 'transparent' must not produce different bytes.
+  if (a === 0) return;
+  const { pixels } = canvas;
+  for (let i = 0; i < pixels.length; i += 4) {
+    pixels[i] = r;
+    pixels[i + 1] = g;
+    pixels[i + 2] = b;
+    pixels[i + 3] = a;
+  }
+}
+
+/** Source-over. `outA === 0` means every contributor was transparent — the colour is nothing. */
+function blend(dst: Uint8ClampedArray, d: number, s: Uint8ClampedArray, p: number): void {
+  const sa = s[p + 3] ?? 0;
+  if (sa === 0) return;
+  const da = dst[d + 3] ?? 0;
+  if (sa === 255 || da === 0) {
+    dst[d] = s[p] ?? 0;
+    dst[d + 1] = s[p + 1] ?? 0;
+    dst[d + 2] = s[p + 2] ?? 0;
+    dst[d + 3] = sa;
+    return;
+  }
+  const sf = sa / 255;
+  const df = (da / 255) * (1 - sf);
+  const outA = sf + df;
+  dst[d] = ((s[p] ?? 0) * sf + (dst[d] ?? 0) * df) / outA;
+  dst[d + 1] = ((s[p + 1] ?? 0) * sf + (dst[d + 1] ?? 0) * df) / outA;
+  dst[d + 2] = ((s[p + 2] ?? 0) * sf + (dst[d + 2] ?? 0) * df) / outA;
+  dst[d + 3] = outA * 255;
+}
+
+/**
+ * The artwork, centred in the inner area and clipped to it — that clip is exactly the `cover`
+ * crop, so one blit serves both fits.
+ */
+export function composeOnto(art: Raster, layout: Layout): Raster {
+  const { box, pad, inner } = layout;
+  const canvas = createRaster(box.width, box.height, 'resize');
+  fill(canvas, layout.background);
+  const ox = pad + Math.round((inner.width - art.width) / 2);
+  const oy = pad + Math.round((inner.height - art.height) / 2);
+  const x1 = Math.min(pad + inner.width, ox + art.width);
+  const y1 = Math.min(pad + inner.height, oy + art.height);
+  for (let y = Math.max(pad, oy); y < y1; y += 1) {
+    for (let x = Math.max(pad, ox); x < x1; x += 1) {
+      blend(
+        canvas.pixels,
+        (y * canvas.width + x) * 4,
+        art.pixels,
+        ((y - oy) * art.width + (x - ox)) * 4,
+      );
+    }
+  }
+  return canvas;
+}

package/src/image/errors.ts

@@ -1,7 +1,9 @@
-// Single responsibility: the three failure modes of the image pipeline, as coded errors.
-// Every one names the format AND a runnable way forward, because an agent that hits
-// "unsupported" needs to know which format to ask for instead, not that it lost.
+// Single responsibility: the three failure modes of the image pipeline, as coded errors, and the
+// one translation of `Bun.Image`'s `ERR_IMAGE_*` rejections into them. Every one names the format
+// AND a runnable way forward, because an agent that hits "unsupported" needs to know which format
+// to ask for instead, not that it lost.
 
+import { renderThrowable, stringField } from '../error-render';
 import { UltimateError } from '../errors';
 
 export class ImageUnsupportedError extends UltimateError {
@@ -56,3 +58,33 @@ export const imageTooLarge = (
     'downscale the source before it reaches the pipeline, or raise MAX_IMAGE_PIXELS deliberately',
     meta,
   );
+
+/**
+ * `Bun.Image` rejects with a plain `Error` carrying a stable `error.code`. This is the ONE place
+ * that code is read: a caller branching on `ERR_IMAGE_*` would be a second vocabulary for the same
+ * three failures, and `X_IMAGE_*` is the one the rest of the framework, the wiki and `x errors
+ * explain` already know. Unknown codes land on decode-failed rather than on a bare `Error`.
+ */
+const UNSUPPORTED_FIX =
+  "request 'png', 'jpeg' or 'webp' — AVIF and HEIC need an OS codec the portable backend never " +
+  'uses, so route those through an ImageTransformDriver (a CDN or an external encoder)';
+
+const UNKNOWN_FORMAT_FIX =
+  're-export the source as PNG, JPEG or WebP: `file <path>` reports what these bytes actually are';
+
+export function imageFromBunError(value: unknown, doing: string): UltimateError {
+  // `renderThrowable`, never `${value}` — the rejection is Bun's value, not ours, and a cause that
+  // throws while formatting itself replaces the refusal with a TypeError nothing catches by code.
+  const cause = `${doing}: ${renderThrowable(value)}`;
+  const code = stringField(value, 'code');
+  if (code === 'ERR_IMAGE_FORMAT_UNSUPPORTED') {
+    return new ImageUnsupportedError(cause, UNSUPPORTED_FIX, { bunCode: code });
+  }
+  if (code === 'ERR_IMAGE_UNKNOWN_FORMAT') {
+    return new ImageUnsupportedError(cause, UNKNOWN_FORMAT_FIX, { bunCode: code });
+  }
+  if (code === 'ERR_IMAGE_TOO_MANY_PIXELS') {
+    return imageTooLarge(cause, { bunCode: code });
+  }
+  return imageDecodeFailed(cause, code === undefined ? {} : { bunCode: code });
+}