@ultimat3/core 5.0.1 → 6.0.0

package/README.md

@@ -38,7 +38,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 +466,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,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "5.0.1",
+  "version": "6.0.0",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
   "license": "MIT",
   "type": "module",

package/src/async-context.ts

@@ -0,0 +1,77 @@
+// 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 first `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 server pays nothing: `getStore()` before any `run()` answers `undefined` whether the storage
+ * was ever constructed or not, so deferring the construction changes no observable behaviour.
+ *
+ * **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,6 +4,7 @@
 
 import { ConfigInvalidError } from './errors';
 import { ROLES, type Role } from './roles';
+import { isIanaZoneName } from './time-zone-name';
 
 export type ThemeMode = 'light' | 'dark' | 'system';
 export type OfflineStrategy = 'precache' | 'runtime' | 'network-only';
@@ -205,15 +206,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 +244,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 +271,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 +296,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/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 });
+}