@ultimat3/core 5.0.0 → 6.0.0

package/src/image/pipeline.ts

@@ -1,94 +1,117 @@
-// Single responsibility: THE image pipeline. Decode -> resize -> encode, one entry point,
-// one capability list. `storage`, `seo` and `pwa` all call this file and none of them owns a
-// second copy: responsive variants, blur placeholders and PWA icons are the same three steps
-// with different numbers, and a framework that generated them twice would drift twice.
-
-import { imageUnsupported } from './errors';
-import { decodeJpeg } from './jpeg-decode';
-import { encodeJpeg } from './jpeg-encode';
-import { DEFAULT_JPEG_QUALITY } from './jpeg-tables';
-import { decodePng, encodePng } from './png';
-import { IMAGE_MIME_TYPES, type ImageFormat, probeImage, sniffImageFormat } from './probe';
-import { hasAlpha, type Raster } from './raster';
-import { type ResizeSpec, resizeRaster } from './resize';
+// Single responsibility: THE image pipeline. Decode -> resize -> encode, one entry point, one
+// capability list. `storage`, `seo` and `pwa` all call this file and none of them owns a second
+// copy: responsive variants, blur placeholders and PWA icons are the same three steps with
+// different numbers, and a framework that generated them twice would drift twice.
+
+import { composeOnto, layOut, type ResizeSpec } from './canvas';
+import { imageFromBunError, imageUnsupported } from './errors';
+import { unshared } from './png-bytes';
+import { decodeImage, encodeImage } from './png-pixels';
+import { IMAGE_MIME_TYPES, type ImageFormat } from './probe';
+import { MAX_IMAGE_PIXELS } from './raster';
 
 /**
- * What the built-in, zero-dependency pipeline can actually produce. Bun ships no image API and
- * the contract forbids `sharp`, so WebP and AVIF are *probed and served*, never synthesised
- * here — a caller that needs them routes transforms through a driver (see `@ultimat3/seo`'s
- * `ImageTransformDriver`). Publishing the real list is what stops `<source type="image/avif">`
- * from promising a variant nothing can encode.
+ * What the pipeline can produce, on every platform, byte for byte. `Bun.Image` also reaches
+ * HEIC and AVIF **through an OS codec** — Apple's ImageIO, Windows' WIC — which is a variant
+ * that exists on the developer's laptop and not on the Linux node that serves it, under a key
+ * that says nothing about which machine minted it. `backend = 'bun'` below refuses that trade,
+ * so those two formats are refused HERE rather than silently on one deploy out of two: a caller
+ * that needs them routes transforms through a driver (`@ultimat3/seo`'s `ImageTransformDriver`).
  */
-export const DECODABLE_FORMATS = ['png', 'jpeg'] as const;
-export const ENCODABLE_FORMATS = ['png', 'jpeg'] as const;
+export const ENCODABLE_FORMATS = ['png', 'jpeg', 'webp'] as const;
+/** What the static codecs read. `svg` is markup, and `probeImage` measures it without decoding. */
+export const DECODABLE_FORMATS = ['png', 'jpeg', 'webp', 'gif'] as const;
 
 export type DecodableFormat = (typeof DECODABLE_FORMATS)[number];
 export type EncodableFormat = (typeof ENCODABLE_FORMATS)[number];
 
-export const canDecode = (format: ImageFormat): format is DecodableFormat =>
+export const canDecode = (format: string): format is DecodableFormat =>
   (DECODABLE_FORMATS as readonly string[]).includes(format);
 
-export const canEncode = (format: ImageFormat): format is EncodableFormat =>
+export const canEncode = (format: string): format is EncodableFormat =>
   (ENCODABLE_FORMATS as readonly string[]).includes(format);
 
-/** Small enough to inline in HTML, big enough to blur convincingly. */
-export const BLUR_PLACEHOLDER_WIDTH = 16;
-
-const decodeFix =
-  'convert the source to PNG or JPEG before it reaches the pipeline, or pass a custom ' +
-  'ImageTransformDriver that can read it';
+/** 1-100, lossy formats only. Bun's own default, pinned here so output cannot drift with it. */
+export const DEFAULT_IMAGE_QUALITY = 80;
 
 const encodeFix =
-  "request 'png' or 'jpeg', or route the transform through an ImageTransformDriver (a CDN " +
-  'or an external encoder) that can produce it';
-
-/** Bytes in, RGBA out. The only place a format is turned into pixels. */
-export function decodeImage(bytes: Uint8Array): Raster {
-  const format = sniffImageFormat(bytes);
-  if (format === null) {
-    throw imageUnsupported('the bytes match no image format this pipeline knows', decodeFix);
-  }
-  if (format === 'png') return decodePng(bytes);
-  if (format === 'jpeg') return decodeJpeg(bytes);
-  throw imageUnsupported(`decoding ${format} is not built in`, decodeFix, { format });
-}
-
-/** RGBA in, bytes out. `quality` is ignored by lossless formats. */
-export function encodeImage(
-  raster: Raster,
-  format: ImageFormat,
-  quality: number = DEFAULT_JPEG_QUALITY,
-): Uint8Array {
-  if (format === 'png') return encodePng(raster);
-  if (format === 'jpeg') return encodeJpeg(raster, quality);
-  throw imageUnsupported(`encoding ${format} is not built in`, encodeFix, { format });
-}
+  "request 'png', 'jpeg' or 'webp', or route the transform through an ImageTransformDriver (a " +
+  'CDN or an external encoder) that can produce it';
 
 export interface ImageTransformSpec extends ResizeSpec {
-  /** Defaults to whichever encodable format preserves the source: PNG if it has alpha. */
+  /** Defaults to the source's format when the pipeline can write it, PNG otherwise. */
   readonly format?: ImageFormat | undefined;
-  /** 1-100, JPEG only. */
+  /** 1-100, lossy formats only. */
   readonly quality?: number | undefined;
 }
 
 /**
- * PNG keeps transparency, JPEG does not; picking by the pixels means a logo never silently
- * grows a black background because nobody passed `format`.
+ * `backend = 'bun'` is set on every call, not once at import. It forces the statically-linked
+ * codecs and the Highway geometry kernels on every OS, which is what makes the same source and
+ * the same spec the same BYTES on a laptop and on the node — and `variantKey` is content-
+ * addressed, so a variant that re-encoded differently per platform would be a cache that never
+ * hits and a hash that never agrees. Per call rather than at import because the property is
+ * process-global and writable: an app that flips it back would otherwise silently win.
  */
-export const defaultFormatFor = (raster: Raster): EncodableFormat =>
-  hasAlpha(raster) ? 'png' : 'jpeg';
+function bunImage(bytes: Uint8Array): Bun.Image {
+  Bun.Image.backend = 'bun';
+  // The decompression-bomb ceiling, enforced by the decoder from the header before it allocates
+  // — the same number `probeImage` refuses at, so the two answers cannot disagree.
+  return new Bun.Image(unshared(bytes), { maxPixels: MAX_IMAGE_PIXELS });
+}
 
-/** The whole pipeline in one call: decode, resize, encode. */
-export function transformImageBytes(bytes: Uint8Array, spec: ImageTransformSpec = {}): Uint8Array {
+function withFormat(image: Bun.Image, format: EncodableFormat, quality: number): Bun.Image {
+  if (format === 'png') return image.png();
+  if (format === 'jpeg') return image.jpeg({ quality });
+  return image.webp({ quality });
+}
+
+/** Every rejection from `Bun.Image` becomes one of the three `X_IMAGE_*` codes, never a bare one. */
+async function run<T>(doing: string, work: () => Promise<T>): Promise<T> {
+  try {
+    return await work();
+  } catch (error) {
+    throw imageFromBunError(error, doing);
+  }
+}
+
+/** The whole pipeline in one call: decode, resize, compose, encode. */
+export async function transformImageBytes(
+  bytes: Uint8Array,
+  spec: ImageTransformSpec = {},
+): Promise<Uint8Array> {
   const { format } = spec;
   // The spec alone answers "can this be written?", so answer it here — decoding and resampling
   // 64 megapixels first, only to refuse at the encoder, is work nobody can use.
   if (format !== undefined && !canEncode(format)) {
     throw imageUnsupported(`encoding ${format} is not built in`, encodeFix, { format });
   }
-  const source = decodeImage(bytes);
-  const resized = resizeRaster(source, spec);
-  return encodeImage(resized, format ?? defaultFormatFor(resized), spec.quality);
+  const quality = spec.quality ?? DEFAULT_IMAGE_QUALITY;
+  const source = await run('reading the image header', () => bunImage(bytes).metadata());
+  const output: EncodableFormat = format ?? (canEncode(source.format) ? source.format : 'png');
+  const layout = layOut(source, spec);
+  const { box, drawn } = layout;
+
+  if (!layout.needsCanvas) {
+    return run('transforming the image', () => {
+      const image = bunImage(bytes);
+      if (box.width !== source.width || box.height !== source.height) {
+        image.resize(box.width, box.height, { fit: 'fill' });
+      }
+      return withFormat(image, output, quality).bytes();
+    });
+  }
+
+  // The letterbox / padding / crop path. `Bun.Image` resamples but has no compositor, so the
+  // artwork comes back as PNG, is placed on the canvas here, and goes back through Bun to be
+  // written. Back through Bun even when the output IS png: `png-pixels.ts` writes filter 0, which
+  // is 1.2-1.8x libspng's bytes on a real icon (measured), and one writer for everything this
+  // function returns is also what makes "same input, same bytes" rest on the static codecs alone.
+  const art = await run('resampling the image', () =>
+    bunImage(bytes).resize(drawn.width, drawn.height, { fit: 'fill' }).png().bytes(),
+  );
+  const composed = encodeImage(composeOnto(decodeImage(art), layout));
+  return run('encoding the image', () => withFormat(bunImage(composed), output, quality).bytes());
 }
 
 /** Chunked because spreading a whole image into `String.fromCharCode` overflows the stack. */
@@ -104,14 +127,12 @@ export const dataUrl = (bytes: Uint8Array, format: ImageFormat): string =>
   `data:${IMAGE_MIME_TYPES[format]};base64,${base64Of(bytes)}`;
 
 /**
- * The LQIP: the source at 16px wide, as a `data:` URI. Always PNG — at this size a JPEG's
- * own headers cost more than the pixels, and alpha survives.
+ * The LQIP: a ThumbHash of the source as a `data:image/png;base64,` URI — at most 32px on its
+ * long edge, with the source's average colour, aspect ratio and rough structure. PNG, so alpha
+ * survives and no client-side decoder is needed to show it.
  */
-export function blurDataUrl(bytes: Uint8Array, width: number = BLUR_PLACEHOLDER_WIDTH): string {
-  const tiny = resizeRaster(decodeImage(bytes), { width });
-  return dataUrl(encodePng(tiny), 'png');
+export async function blurDataUrl(bytes: Uint8Array): Promise<string> {
+  return run('building the blur placeholder', () => bunImage(bytes).placeholder());
 }
 
 export type { ImageFormat };
-/** Intrinsic dimensions without decoding — this is what keeps CLS at 0 for every format. */
-export { IMAGE_MIME_TYPES, probeImage, sniffImageFormat };

package/src/image/png-pixels.ts

@@ -0,0 +1,183 @@
+// Single responsibility: the raw-pixel seam — 8-bit RGBA in and out of a PNG container. `Bun.Image`
+// owns every real codec now, but it has no compositor and no raw-pixel terminal, and the maskable
+// safe zone `@ultimat3/pwa` promises is a composite. So this file exists for exactly that one hop:
+// Bun re-encodes to PNG, this reads the pixels back, `canvas.ts` blits, this writes them again.
+
+import { imageDecodeFailed, imageUnsupported } from './errors';
+import {
+  adler32,
+  chunk,
+  joinBytes,
+  PNG_SIGNATURE,
+  paeth,
+  readU32,
+  unshared,
+  writeU32,
+} from './png-bytes';
+import { type Raster, rasterFrom } from './raster';
+
+/** Truecolour with alpha, 8 bits per channel — the ONE shape `Raster` is. */
+const RGBA_COLOR_TYPE = 8 << 4;
+const BYTES_PER_PIXEL = 4;
+
+const RAW_FIX =
+  'run the bytes through `transformImageBytes()` instead — it is backed by Bun.Image, which ' +
+  'reads every real format; the raw-pixel seam is 8-bit RGBA PNG only';
+
+// --------------------------------------------------------------------------------- encode
+
+/**
+ * Always filter 0. An adaptive filter buys a few percent on a placeholder or an icon and costs a
+ * second thing to be wrong in; every consumer of these bytes re-encodes through Bun anyway.
+ */
+function filterRows(raster: Raster): Uint8Array<ArrayBuffer> {
+  const stride = raster.width * BYTES_PER_PIXEL;
+  const out = new Uint8Array((stride + 1) * raster.height);
+  for (let y = 0; y < raster.height; y += 1) {
+    out[y * (stride + 1)] = 0;
+    out.set(raster.pixels.subarray(y * stride, (y + 1) * stride), y * (stride + 1) + 1);
+  }
+  return out;
+}
+
+/** RGBA pixels to PNG bytes. Deterministic: the same raster is the same bytes, every run. */
+export function encodeImage(raster: Raster, format: 'png' = 'png'): Uint8Array {
+  if (format !== 'png') {
+    throw imageUnsupported(`the raw-pixel seam writes PNG, not ${String(format)}`, RAW_FIX, {
+      format,
+    });
+  }
+  const header = new Uint8Array(13);
+  writeU32(header, 0, raster.width);
+  writeU32(header, 4, raster.height);
+  header[8] = 8;
+  header[9] = 6;
+  const filtered = filterRows(raster);
+  // `windowBits: -15` asks for RAW deflate: PNG supplies the zlib envelope itself, and Bun's
+  // documented default (15, zlib-wrapped) would nest a second one inside it.
+  const deflated = Bun.deflateSync(filtered, { windowBits: -15 });
+  const idat = new Uint8Array(deflated.length + 6);
+  idat[0] = 0x78;
+  idat[1] = 0x01;
+  idat.set(deflated, 2);
+  writeU32(idat, deflated.length + 2, adler32(filtered));
+  return joinBytes([
+    PNG_SIGNATURE,
+    chunk('IHDR', header),
+    chunk('IDAT', idat),
+    chunk('IEND', new Uint8Array(0)),
+  ]);
+}
+
+// --------------------------------------------------------------------------------- decode
+
+interface PngHeader {
+  readonly width: number;
+  readonly height: number;
+}
+
+function readHeader(bytes: Uint8Array): PngHeader {
+  if (bytes.length < 33) {
+    throw imageDecodeFailed(`a PNG is at least 33 bytes; these are ${bytes.length}`, {
+      length: bytes.length,
+    });
+  }
+  for (let i = 0; i < PNG_SIGNATURE.length; i += 1) {
+    if (bytes[i] !== PNG_SIGNATURE[i]) {
+      throw imageUnsupported('the raw-pixel seam reads PNG, and these bytes are not one', RAW_FIX, {
+        length: bytes.length,
+      });
+    }
+  }
+  const depth = bytes[24];
+  const colorType = bytes[25];
+  const interlace = bytes[28];
+  // Bun's encoder emits 8-bit RGBA, non-interlaced, for every source — verified, and the only
+  // shape this seam ever has to read. Anything else came from outside and says so.
+  if (((depth ?? 0) << 4) + (colorType ?? 0) !== RGBA_COLOR_TYPE + 6 || interlace !== 0) {
+    throw imageUnsupported(
+      `the PNG is ${String(depth)}-bit colour type ${String(colorType)}` +
+        `${interlace === 0 ? '' : ', interlaced'}, not 8-bit RGBA`,
+      RAW_FIX,
+      { depth, colorType, interlace },
+    );
+  }
+  return { width: readU32(bytes, 16), height: readU32(bytes, 20) };
+}
+
+/** Every IDAT concatenated: a PNG may split its stream across any number of them. */
+function idatStream(bytes: Uint8Array): Uint8Array {
+  const parts: Uint8Array[] = [];
+  let at = 8;
+  while (at + 12 <= bytes.length) {
+    const length = readU32(bytes, at);
+    const type = String.fromCharCode(...bytes.subarray(at + 4, at + 8));
+    if (type === 'IDAT') parts.push(bytes.subarray(at + 8, at + 8 + length));
+    if (type === 'IEND') break;
+    at += 12 + length;
+  }
+  if (parts.length === 0) {
+    throw imageDecodeFailed('the PNG carries no IDAT chunk, so it declares no pixels', {});
+  }
+  const stream = joinBytes(parts);
+  try {
+    // The 2-byte zlib header and the 4-byte Adler-32 trailer are PNG's envelope, stripped here
+    // so the payload inflates as RAW deflate — see the encoder above for the mirror image.
+    return Bun.inflateSync(unshared(stream.subarray(2, stream.length - 4)), { windowBits: -15 });
+  } catch {
+    throw imageDecodeFailed(`the PNG IDAT stream (${stream.length} bytes) could not be inflated`, {
+      length: stream.length,
+    });
+  }
+}
+
+/**
+ * The five PNG predictors, undone row by row. `raw` is `[filter, ...pixels]` per row.
+ *
+ * Reconstructed into a `Uint8Array`, never straight into the `Uint8ClampedArray` a `Raster` holds:
+ * every filter is arithmetic MOD 256 and a clamped array saturates instead, so `255 + 1` lands on
+ * 255 rather than 0. That is invisible on a filter-0 stream (ours) and wrong on every adaptive one
+ * (libspng's) — the alpha channel of a transparent pixel first, which is exactly the case a PWA
+ * icon is made of.
+ */
+function unfilter(raw: Uint8Array, width: number, height: number): Uint8ClampedArray {
+  const stride = width * BYTES_PER_PIXEL;
+  const out = new Uint8Array(stride * height);
+  for (let y = 0; y < height; y += 1) {
+    const type = raw[y * (stride + 1)] ?? 0;
+    if (type > 4) {
+      throw imageDecodeFailed(`PNG row ${y} declares filter ${type}, and there are only 0-4`, {
+        row: y,
+        filter: type,
+      });
+    }
+    const from = y * (stride + 1) + 1;
+    const to = y * stride;
+    for (let i = 0; i < stride; i += 1) {
+      const x = raw[from + i] ?? 0;
+      const a = i >= BYTES_PER_PIXEL ? (out[to + i - BYTES_PER_PIXEL] ?? 0) : 0;
+      const b = y > 0 ? (out[to - stride + i] ?? 0) : 0;
+      const c = y > 0 && i >= BYTES_PER_PIXEL ? (out[to - stride + i - BYTES_PER_PIXEL] ?? 0) : 0;
+      if (type === 0) out[to + i] = x;
+      else if (type === 1) out[to + i] = x + a;
+      else if (type === 2) out[to + i] = x + b;
+      else if (type === 3) out[to + i] = x + ((a + b) >> 1);
+      else out[to + i] = x + paeth(a, b, c);
+    }
+  }
+  return new Uint8ClampedArray(out.buffer, out.byteOffset, out.length);
+}
+
+/** PNG bytes to RGBA pixels. Refuses anything but 8-bit RGBA, naming the pipeline that reads it. */
+export function decodeImage(bytes: Uint8Array): Raster {
+  const { width, height } = readHeader(bytes);
+  const raw = idatStream(bytes);
+  const expected = (width * BYTES_PER_PIXEL + 1) * height;
+  if (raw.length !== expected) {
+    throw imageDecodeFailed(
+      `the PNG inflates to ${raw.length} bytes but ${width}x${height} RGBA needs ${expected}`,
+      { inflated: raw.length, expected, width, height },
+    );
+  }
+  return rasterFrom(width, height, unfilter(raw, width, height));
+}

package/src/impersonate.ts

@@ -2,13 +2,16 @@
 // the mechanism; this is the ONE door through it, because a swap with no reason and no origin is
 // indistinguishable in an audit trail from the customer doing it themselves.
 
-import { AsyncLocalStorage } from 'node:async_hooks';
 import { type Actor, actorLabel, actorOrigin } from './actor';
 import { assert } from './assert';
+import { asyncContext } from './async-context';
 import { useContext, withChildContext } from './context';
 import { currentSpan } from './telemetry';
 
-const storage = new AsyncLocalStorage<string>();
+// The same lazily-opened seam `context.ts` uses. Its `run()` cannot be reached in a runtime with
+// no async context: `impersonate()` calls `useContext()` first, and that throws `X_NO_CONTEXT`
+// there — so no second refusal is written here for symmetry's sake.
+const impersonation = asyncContext<string>('the impersonation reason');
 
 /**
  * Run `fn` as `actor`, recording who asked and why.
@@ -45,7 +48,7 @@ export function impersonate<T>(actor: Actor, reason: string, fn: () => T): T {
     'actor.label': label,
     'impersonation.reason': reason,
   });
-  return withChildContext({ actor: impersonated }, () => storage.run(reason, fn));
+  return withChildContext({ actor: impersonated }, () => impersonation.run(reason, fn));
 }
 
 /**
@@ -53,10 +56,10 @@ export function impersonate<T>(actor: Actor, reason: string, fn: () => T): T {
  * an app where nobody is impersonating. Read by an audit sink, and by nothing else.
  */
 export function impersonationReason(): string | undefined {
-  return storage.getStore();
+  return impersonation.get();
 }
 
 /** Is the caller acting as somebody else right now? */
 export function isImpersonating(): boolean {
-  return storage.getStore() !== undefined;
+  return impersonation.get() !== undefined;
 }

package/src/index.ts

@@ -384,37 +384,33 @@ export {
   uuid,
   uuidTimestamp,
 } from './ids';
+export { fitBox, type ImageFit, type ResizeSpec, scaledToFit } from './image/canvas';
 export { parseColor } from './image/color';
 export {
   ImageDecodeFailedError,
   ImageTooLargeError,
   ImageUnsupportedError,
   imageDecodeFailed,
+  imageFromBunError,
   imageTooLarge,
   imageUnsupported,
 } from './image/errors';
-export { decodeJpeg } from './image/jpeg-decode';
-export { encodeJpeg } from './image/jpeg-encode';
-export { DEFAULT_JPEG_QUALITY } from './image/jpeg-tables';
 export type {
   DecodableFormat,
   EncodableFormat,
   ImageTransformSpec,
 } from './image/pipeline';
 export {
-  BLUR_PLACEHOLDER_WIDTH,
   blurDataUrl,
   canDecode,
   canEncode,
   DECODABLE_FORMATS,
+  DEFAULT_IMAGE_QUALITY,
   dataUrl,
-  decodeImage,
-  defaultFormatFor,
   ENCODABLE_FORMATS,
-  encodeImage,
   transformImageBytes,
 } from './image/pipeline';
-export { decodePng, encodePng } from './image/png';
+export { decodeImage, encodeImage } from './image/png-pixels';
 export type { ImageFormat, ImageInfo } from './image/probe';
 export { IMAGE_FORMATS, IMAGE_MIME_TYPES, probeImage, sniffImageFormat } from './image/probe';
 export type { ImageSize, Raster } from './image/raster';
@@ -425,7 +421,6 @@ export {
   MAX_IMAGE_PIXELS,
   rasterFrom,
 } from './image/raster';
-export { fitBox, type ImageFit, type ResizeSpec, resizeRaster, scaledToFit } from './image/resize';
 export { impersonate, impersonationReason, isImpersonating } from './impersonate';
 export { cachedFormatter, canonicalLocale, MAX_CACHED_FORMATTERS } from './intl-cache';
 export type {

package/src/telemetry.ts

@@ -2,7 +2,7 @@
 // is a no-op so unconfigured apps pay nothing, and trace context is serialised explicitly
 // (`traceparent`) so a trace survives HTTP -> job -> live query.
 
-import { AsyncLocalStorage } from 'node:async_hooks';
+import { asyncContext } from './async-context';
 import { type Clock, systemClock } from './clock';
 import { tryUseContext } from './context';
 import { renderThrowable } from './error-render';
@@ -118,7 +118,10 @@ export function memoryExporter(): MemoryExporter {
   };
 }
 
-const activeSpan = new AsyncLocalStorage<Span>();
+// The same lazily-opened seam `context.ts` uses, and for the same reason: a module-scope
+// `new AsyncLocalStorage()` throws at EVALUATION in a browser bundle, taking every importer of
+// `@ultimat3/core` down with it. `async-context.ts` owns the argument.
+const activeSpan = asyncContext<Span>('the active span');
 
 let exporter: SpanExporter = noopExporter;
 let clock: Clock = systemClock;
@@ -161,12 +164,12 @@ export function serviceResource(): SpanResource {
 }
 
 export function currentSpan(): Span | undefined {
-  return activeSpan.getStore();
+  return activeSpan.get();
 }
 
 /** The trace the caller is inside: active span, else the request context, else a fresh trace. */
 export function currentSpanContext(): SpanContext | undefined {
-  const span = activeSpan.getStore();
+  const span = activeSpan.get();
   if (span !== undefined) return span.context;
   const ctx = tryUseContext();
   if (ctx === undefined) return undefined;

package/src/time-zone-name.ts

@@ -0,0 +1,43 @@
+// Single responsibility: is a string an IANA zone NAME? Tier 0's statement of the one rule
+// `@ultimat3/time` enforces everywhere above it — a zone is `Area/Location`, and `UTC` is the one
+// exception. It is stated twice because `core` is tier 0 and may not import `@ultimat3/time`;
+// `packages/time/src/zone-canonical.ts` is where the rule and its reasoning are written down.
+
+/**
+ * A LEADING sign is a fixed offset, which carries no DST rules. `Etc/GMT+2` keeps its `+`.
+ *
+ * Unobservable on ICU 78 — `+01:00` resolves to itself, so the slash rule below already refuses it,
+ * and deleting this line changes no answer this package can currently produce. It stays because it
+ * guards the runtime that folds an offset into `Etc/GMT-1`, which WOULD carry a slash, and because
+ * `packages/time/src/zone-canonical.ts` carries the same line: two statements of one rule may not
+ * differ, least of all in the half that is hard to test.
+ */
+const NUMERIC_OFFSET = /^[+-]/;
+
+/**
+ * Structural, and never delegated to `Intl` — the reasoning, and why a denylist is not the
+ * alternative, is `packages/time/src/zone-canonical.ts`'s and is not re-derived here. What this
+ * file enforces is that same rule for `app.config.ts`: an identifier is `Area/Location`, `UTC` is
+ * the one legal exception, and a leading sign is an offset rather than a name.
+ *
+ * It exists because a bare `new Intl.DateTimeFormat(…)` probe was the second answer to that
+ * question, and the two stopped agreeing: ICU 78 (Bun 1.4) resolves `CET`, `EST`, `Japan`, `GMT`,
+ * `Zulu` and the whole `backward`/abbreviation family, so `defaultTimeZone: 'CET'` passed validation
+ * at boot and threw `X_TIMEZONE_INVALID` on the first `format` call — a config file accepting a
+ * value nothing downstream can use (issue #257).
+ *
+ * The judgement is made on the RESOLVED name, not the input, so a casing (`utc`) and a runtime that
+ * folds an alias into its target (`Etc/UTC` → `UTC`) both answer correctly. No cache: this is read
+ * once per process at config validation, never off a request header — a zone that arrives from a
+ * caller goes through `@ultimat3/time`'s `canonicalTimeZone`, which is bounded and canonicalizing.
+ */
+export function isIanaZoneName(value: string): boolean {
+  if (value === '' || NUMERIC_OFFSET.test(value)) return false;
+  try {
+    const resolved = new Intl.DateTimeFormat('en-US', { timeZone: value }).resolvedOptions()
+      .timeZone;
+    return resolved === 'UTC' || resolved.includes('/');
+  } catch {
+    return false;
+  }
+}