@ultimat3/core 23.0.0 → 25.0.0

package/src/error-reporter-sentry.ts

@@ -7,7 +7,7 @@ import { renderThrowable } from './error-render';
 import type { ErrorReport, ErrorReporter, ErrorSeverity } from './error-reporter';
 import { type CodedErrorInit, UltimateError } from './errors';
 import { traceId } from './ids';
-import { logger } from './logger';
+import { logger, redactFields } from './logger';
 
 export class ErrorReporterDsnInvalidError extends UltimateError {
   static readonly code = 'X_ERROR_REPORTER_DSN_INVALID';
@@ -108,6 +108,10 @@ function payloadOf(report: ErrorReport, eventId: string): Record<string, unknown
           },
         }),
     extra: {
+      // The caller's two records go through `redactFields`, and FIRST. Spread raw and last, a
+      // `bigint` or a cycle in `meta` made `JSON.stringify` throw — that error was never reported
+      // — `meta: { fix, stack }` replaced the framework's own, and `meta.password` left the box.
+      ...redactFields(report.scope.extra ?? {}),
       // The whole point of reporting the framework's contract instead of a message: whoever is
       // paged reads the runnable fix next to the failure.
       fix: report.fix,
@@ -115,8 +119,8 @@ function payloadOf(report: ErrorReport, eventId: string): Record<string, unknown
       ...(report.scope.requestId === undefined ? {} : { requestId: report.scope.requestId }),
       ...(report.scope.actorId === undefined ? {} : { actorId: report.scope.actorId }),
       ...(report.stack === undefined ? {} : { stack: report.stack }),
-      ...(report.meta ?? {}),
-      ...(report.scope.extra ?? {}),
+      // Under its own key, so no name an error author picks can collide with one above.
+      ...(report.meta === undefined ? {} : { meta: redactFields(report.meta) }),
     },
     exception: { values: [{ type: report.code, value: `${report.title} — ${report.cause}` }] },
   };

package/src/errors.ts

@@ -2,7 +2,14 @@
 // Stable code + cause + exact fix command, rendered identically in the terminal, the browser
 // overlay and `--json`. Never throw a bare Error anywhere in the framework.
 
-import { describeErrorCode } from './error-codes';
+/**
+ * Structural brand. `instanceof` is unreliable across duplicated module instances, so the guard is
+ * duck-typed on a well-known symbol instead. It is `@ultimat3/schema`'s — declared once, at the
+ * tier both error classes can reach (`core -> schema` is the declared edge) — and imported from
+ * there by anything that needs the symbol itself: core does not publish it a second time.
+ */
+import { ULTIMATE_ERROR_BRAND } from '@ultimat3/schema';
+import { describeErrorCode, hasErrorCode } from './error-codes';
 import {
   isThrownError,
   renderCauseValue,
@@ -12,13 +19,6 @@ import {
 } from './error-render';
 import { DEFAULT_ERROR_RETRY, type ErrorRetry, isErrorRetry, retryFor } from './error-retry';
 
-/**
- * Structural brand. `instanceof` is unreliable across duplicated module instances and across
- * tier-0 packages that may not import each other (`@ultimat3/schema` cannot import
- * `@ultimat3/core`), so the guard is duck-typed on a well-known symbol instead.
- */
-export const ULTIMATE_ERROR_BRAND: unique symbol = Symbol.for('ultimate.error');
-
 export interface UltimateErrorInit {
   /** `SCREAMING_SNAKE`, prefixed `X_`. Must exist in the code registry to get a title. */
   readonly code: string;
@@ -48,6 +48,14 @@ export interface UltimateErrorInit {
   readonly retry?: ErrorRetry | undefined;
   /** The underlying thrown value, when this error wraps one. */
   readonly sourceError?: unknown;
+  /**
+   * A title off the WIRE — a problem document's `title` — used only when this realm registered
+   * none for `code`. A browser rebuilds a server's refusal by code and may never have loaded the
+   * package that titles it; the registry still wins wherever it has an answer, so a server can
+   * never retitle a code this realm owns. Untrusted display text: the decoder caps it, and the
+   * constructor makes it one line like every other field.
+   */
+  readonly remoteTitle?: string | undefined;
 }
 
 export interface UltimateErrorJSON {
@@ -111,7 +119,8 @@ export class UltimateError extends Error {
     // Escaping at construction is the one place that covers all of them, and it is what #97 called
     // the real answer. `singleLine` is idempotent, so a call site that already escaped is unharmed.
     const code = singleLine(init.code);
-    const title = singleLine(described.title);
+    const remote = init.remoteTitle !== undefined && !hasErrorCode(init.code);
+    const title = singleLine(remote ? (init.remoteTitle ?? described.title) : described.title);
     const cause = singleLine(init.cause);
     // `message` carries the cause because it is the ONLY field a runtime prints when an
     // error escapes uncaught — a worker log, a CI transcript, a stack trace. A message of

package/src/exports/error-contract.ts

@@ -63,7 +63,6 @@ export {
   NotImplementedError,
   notImplemented,
   toUltimateError,
-  ULTIMATE_ERROR_BRAND,
   UltimateError,
 } from '../errors';
 export { SCHEMA_ERROR_CODE_TITLES } from '../schema-error-codes';

package/src/exports/observability.ts

@@ -35,7 +35,6 @@ export {
 } from '../error-reporter-sentry';
 export type { LogFields, Logger, LoggerOptions, LogLevel } from '../logger';
 export {
-  createLogger,
   isRedactedKey,
   LOG_LEVELS,
   logger,
@@ -43,6 +42,7 @@ export {
   redactKeys,
   setLoggerContextFields,
   setLogStream,
+  structuredLogger,
 } from '../logger';
 export type {
   Counter,

package/src/exports/secrets.ts

@@ -47,6 +47,7 @@ export {
   SecretsPlaintextInvalidError,
   SecretsTamperedError,
 } from '../secrets-errors';
+export { SecretsKeyAclError } from '../secrets-key-file';
 export type {
   MasterKeyRef,
   MasterKeySource,
@@ -58,6 +59,7 @@ export {
   installSecrets,
   masterKeyIdOf,
   masterKeyPath,
+  promoteStagedMasterKey,
   readSecretsFile,
   requireMasterKey,
   SECRETS_FILE,
@@ -67,6 +69,7 @@ export {
   secretsFileExists,
   secretsPath,
   stagedMasterKeyPath,
+  stageMasterKeyFile,
   writeMasterKeyFile,
   writeSecretsFile,
 } from '../secrets-store';

package/src/finite-option.ts

@@ -48,7 +48,7 @@ export function finiteCount(
   assert(
     Number.isSafeInteger(value) && value >= min,
     `${subject} ${option} is ${String(value)}, and it counts things: it must be a whole number of ${min === 1 ? 'at least 1' : '0 or more'}, or the bound it sets is not one`,
-    `pass a whole ${option} to ${subject} — and parse an environment value before you pass it, because Number(process.env.…) is NaN when the variable is unset and Math.floor does not repair that`,
+    `${option}: Number.parseInt(raw, 10)   # a whole number ${min === 1 ? '≥ 1' : '≥ 0'} for ${subject}; parse an env value and check it, since Number(process.env.…) is NaN when unset and Math.floor does not repair that`,
   );
   return value;
 }

package/src/flight-gate.ts

@@ -8,6 +8,7 @@
 // memory fault and answers it minutes late.
 
 import { UltimateError } from './errors';
+import { finiteCount } from './finite-option';
 
 export interface FlightGateLimits {
   /** Work running at once. */
@@ -34,7 +35,12 @@ export interface FlightGateOptions {
 }
 
 export interface FlightGate {
-  run<T>(work: () => Promise<T>): Promise<T>;
+  /**
+   * `signal` makes a QUEUED wait cancellable: on abort the waiter leaves the queue and the call
+   * rejects with the abort's reason. Once a slot is handed over the work runs; the signal is then
+   * the work's own business.
+   */
+  run<T>(work: () => Promise<T>, signal?: AbortSignal): Promise<T>;
   /** Running right now. */
   readonly active: number;
   /** Waiting for a slot right now. A count that does not fall back to 0 is a leak. */
@@ -45,36 +51,57 @@ export interface FlightGate {
  * A slot is HANDED OVER on release rather than released and re-acquired: decrementing first would
  * let a caller arriving in the same tick past the ceiling while a waiter's continuation is still a
  * queued microtask, which is how a "bounded" pool goes over its bound under exactly the load it
- * exists for. `@ultimat3/auth`'s `createKdfGate` states the same rule; this is that function with
+ * exists for. `@ultimat3/auth`'s `boundedKdfGate` states the same rule; this is that function with
  * the refusal made injectable.
  */
-export function createFlightGate(
-  limits: FlightGateLimits,
-  options?: FlightGateOptions,
-): FlightGate {
+export function flightGate(limits: FlightGateLimits, options?: FlightGateOptions): FlightGate {
   const subject = options?.subject ?? 'in-flight work';
+  // Refused at CONSTRUCTION, because this pair wedges rather than fails: `active < NaN` and
+  // `waiters.length >= NaN` are both false, so every caller parks in a queue with no bound. Zero
+  // is a real value at both — "never wait" and, at the width, "refuse everything".
+  const maxConcurrent = finiteCount(
+    `flightGate (${subject})`,
+    'maxConcurrent',
+    limits.maxConcurrent,
+  );
+  const maxQueued = finiteCount(`flightGate (${subject})`, 'maxQueued', limits.maxQueued);
   const waiters: Array<() => void> = [];
   let active = 0;
 
   const state = (): FlightGateState => ({
-    maxConcurrent: limits.maxConcurrent,
-    maxQueued: limits.maxQueued,
+    maxConcurrent,
+    maxQueued,
     active,
     queued: waiters.length,
     subject,
   });
 
-  const acquire = async (): Promise<void> => {
-    if (active < limits.maxConcurrent) {
+  const acquire = async (signal: AbortSignal | undefined): Promise<void> => {
+    if (signal?.aborted === true) throw signal.reason;
+    if (active < maxConcurrent) {
       active += 1;
       return;
     }
-    if (waiters.length >= limits.maxQueued) {
+    // A width of zero has no slot to hand over, so a waiter would never be resumed: the queue is
+    // for work that WILL run, and here none will.
+    if (maxConcurrent === 0 || waiters.length >= maxQueued) {
       const current = state();
       throw options?.overflow?.(current) ?? gateOverloaded(current);
     }
-    await new Promise<void>((resume) => {
-      waiters.push(resume);
+    // A waiter that only stored its resolver could not be taken back: a superseded or abandoned
+    // call stayed pending and kept its queue place until a slot reached it. The abort removes it.
+    await new Promise<void>((resume, refuse) => {
+      const onAbort = (): void => {
+        const at = waiters.indexOf(waiter);
+        if (at !== -1) waiters.splice(at, 1);
+        refuse(signal?.reason);
+      };
+      const waiter = (): void => {
+        signal?.removeEventListener('abort', onAbort);
+        resume();
+      };
+      waiters.push(waiter);
+      signal?.addEventListener('abort', onAbort, { once: true });
     });
   };
 
@@ -91,8 +118,8 @@ export function createFlightGate(
     get queued(): number {
       return waiters.length;
     },
-    async run<T>(work: () => Promise<T>): Promise<T> {
-      await acquire();
+    async run<T>(work: () => Promise<T>, signal?: AbortSignal): Promise<T> {
+      await acquire(signal);
       try {
         return await work();
       } finally {
@@ -112,7 +139,7 @@ export function gateOverloaded(state: FlightGateState): UltimateError {
   return new UltimateError({
     code: 'X_FLIGHT_GATE_OVERLOADED',
     cause: `${state.active} of ${state.subject} are running at the ceiling of ${state.maxConcurrent} and ${state.queued} more are queued at the limit of ${state.maxQueued}`,
-    fix: 'retry after the Retry-After header, or widen the ceiling at the createFlightGate({ maxConcurrent, maxQueued }) call site — only if the box has the capacity the extra slots buy',
+    fix: 'retry after the Retry-After header, or widen the ceiling at the flightGate({ maxConcurrent, maxQueued }) call site — only if the box has the capacity the extra slots buy',
     meta: {
       active: state.active,
       queued: state.queued,

package/src/fnv1a.ts

@@ -0,0 +1,19 @@
+// 32-bit FNV-1a: a BUCKET, never a key. Rollout buckets and factory seeds need a hash every process
+// computes identically and synchronously; anything that decides who shares what is `fingerprint`
+// (`canonical-json.ts`), because 2^32 values collide offline in seconds.
+
+const FNV_OFFSET_BASIS = 0x811c_9dc5;
+const FNV_PRIME = 0x0100_0193;
+
+/**
+ * The published 32-bit FNV-1a over UTF-16 code units, unsigned. Pure and dependency-free, which is
+ * the property its two callers need: two nodes place one subject in one bucket without talking.
+ */
+export function fnv1a(text: string): number {
+  let hash = FNV_OFFSET_BASIS;
+  for (let index = 0; index < text.length; index += 1) {
+    hash ^= text.charCodeAt(index);
+    hash = Math.imul(hash, FNV_PRIME);
+  }
+  return hash >>> 0;
+}

package/src/generation-fence.ts

@@ -18,7 +18,7 @@ export interface GenerationFence {
  * `subject` names what the generation counts, and it reaches the `cause:` — "the live window was
  * superseded" is actionable where "generation 3 != 4" is a puzzle.
  */
-export function createFence(subject: string): GenerationFence {
+export function generationFence(subject: string): GenerationFence {
   let current = 0;
   return {
     generation: (): number => current,

package/src/health-disclosure.ts

@@ -0,0 +1,43 @@
+// What `/healthz` and `/readyz` say, and to whom — ONE rule for every role's listener. Both answer
+// outside every pipeline, so the body is a stranger's to read: everyone gets the verdict, and the
+// build id, the in-flight count and the readiness check names go only to a listed peer.
+
+import { classifyAddress } from './address-class';
+import type { HealthReport } from './lifecycle';
+import type { Role } from './roles';
+
+/** The box itself: `kubectl exec`, a port-forward, a compose healthcheck, a sidecar scraper. */
+export const DEFAULT_HEALTH_DETAIL_PEERS: readonly string[] = ['loopback'];
+
+/** The verdict a stranger gets. An allow-list, so a field `HealthReport` gains is withheld by default. */
+export interface PublicHealthBody {
+  readonly state: HealthReport['state'];
+  readonly ready: boolean;
+  readonly role: Role;
+}
+
+/** The body for one caller: the whole report for a listed peer, the verdict for anyone else. */
+export function healthBody(
+  report: HealthReport,
+  role: Role,
+  detailed: boolean,
+): PublicHealthBody | (HealthReport & { readonly role: Role }) {
+  return detailed ? { ...report, role } : { state: report.state, ready: report.ready, role };
+}
+
+/**
+ * Whether `address` is one the list names: an entry is an address CLASS (`loopback`, `private`, …)
+ * or one exact IP literal. Pure, and total — it runs on an unauthenticated probe path, so a list
+ * that is not a list, an entry that is not a string and an address that is not a literal all
+ * answer `false` rather than throw: nothing can vouch for them, whatever the list says.
+ */
+export function healthPeerListed(peers: readonly string[], address: string | null): boolean {
+  if (address === null || !Array.isArray(peers)) return false;
+  const kind = classifyAddress(address);
+  if (kind === undefined) return false;
+  const literal = address.trim().toLowerCase();
+  return peers.some(
+    (entry: unknown) =>
+      typeof entry === 'string' && (entry === kind || entry.trim().toLowerCase() === literal),
+  );
+}

package/src/host-rules.ts

@@ -4,6 +4,8 @@
 // read. In core because two tier-5 packages drive a browser (`scraping`, and `cli`'s `x shot`) and
 // neither may import the other; two copies of this rule would be two answers to "may it leave".
 
+import { classifyAddress } from './address-class';
+
 export type HostRule = string;
 
 /** The one spelling that means "every host", written out so it is visible in review. */
@@ -51,6 +53,31 @@ export function hostMatches(host: string, rule: HostRule): boolean {
   return normalised === cleaned;
 }
 
+/** A rule that names a CLASS of hosts rather than one — the two spellings `hostMatches` widens. */
+const isWildcard = (rule: HostRule): boolean => {
+  const cleaned = rule.trim();
+  return cleaned === ANY_HOST || cleaned.startsWith('*.');
+};
+
+/**
+ * The address-class FLOOR. A wildcard means "any site", and an address literal inside the network
+ * — loopback, RFC 1918, link-local, the metadata endpoint — is not a site: it is the request this
+ * module's header names. So a wildcard never admits one, and the opt-out is NAMING it: an exact
+ * rule (`'127.0.0.1'`, `'[::1]'`) is a line a reviewer can see, which `'*'` is not.
+ *
+ * What this cannot do is see through a NAME. `allowHosts: ['*']` still admits a hostname that
+ * resolves inward, because this function is synchronous and has no resolver — pinning the
+ * resolved address belongs to the driver that opens the connection, as `@ultimat3/jobs`'
+ * `webhook-target.ts` does for a webhook. The URL parser has already folded the numeric
+ * spellings (`2130706433`, `0x7f.1`) to dotted form, so they are classified as what they are.
+ */
+function admits(host: string, rule: HostRule): boolean {
+  if (!hostMatches(host, rule)) return false;
+  if (!isWildcard(rule)) return true;
+  const kind = classifyAddress(host);
+  return kind === undefined || kind === 'public';
+}
+
 /**
  * Fails CLOSED: a URL that cannot be parsed is refused. A driver handed a malformed request has
  * no way to know where it would have gone, and "we could not tell, so we let it through" is the
@@ -67,5 +94,5 @@ export function hostDecision(url: string, allowHosts: readonly HostRule[]): Host
     return { allowed: false, host: '' };
   }
   if (host === '') return { allowed: false, host };
-  return { allowed: allowHosts.some((rule) => hostMatches(host, rule)), host };
+  return { allowed: allowHosts.some((rule) => admits(host, rule)), host };
 }

package/src/html-escape.ts

@@ -0,0 +1,24 @@
+// The one HTML character table: how an untrusted value becomes inert text or attribute content.
+// At tier 0 because every package that writes markup — http, mail, render, seo, the dashboards —
+// can reach it, and a second table is one character away from a hole (`bun run flight-copies`).
+
+/** A `Map`, so a lookup never reaches `Object.prototype` (`bun run proto-index`). */
+const HTML_ESCAPES: ReadonlyMap<string, string> = new Map([
+  ['&', '&amp;'],
+  ['<', '&lt;'],
+  ['>', '&gt;'],
+  ['"', '&quot;'],
+  ["'", '&#39;'],
+]);
+
+const HTML_SPECIAL = /[&<>"']/g;
+
+/**
+ * Text content AND attribute values, in any quoting — one set for both, deliberately. A text-only
+ * subset is correct exactly until someone uses it for an attribute, and a no-`'` set until someone
+ * writes a single-quoted one. `&#39;` rather than `&apos;`: it is a numeric reference, so it means
+ * the same thing in HTML 4, HTML 5 and XML. One pass, so `&` is never escaped twice.
+ */
+export function escapeHtml(value: string): string {
+  return value.replace(HTML_SPECIAL, (char) => HTML_ESCAPES.get(char) ?? char);
+}

package/src/ids.ts

@@ -33,7 +33,7 @@ function randomBytes(length: number): Uint8Array {
 /**
  * A full 10 bits, from both bytes. Reading `bytes[0]` alone masked an 8-bit value with a 10-bit
  * mask, so the seed only ever reached 255 while `COUNTER_SEED_MASK` declared 1023 — the constant
- * and the code disagreed, and the second byte was allocated on every `uuid()` for nothing.
+ * and the code disagreed, and the second byte was allocated on every `uuidV7()` for nothing.
  */
 function seedCounter(): number {
   const bytes = randomBytes(2);
@@ -43,7 +43,7 @@ function seedCounter(): number {
 /**
  * `new Uint8Array(NaN)` is a zero-length array, not a throw, so an unscreened length made this
  * answer `''` — an id that is no id, minted silently. `min: 1`: zero bytes of randomness is the
- * same empty string, and every caller here (`uuid`, `traceId`, `spanId`) wants a width.
+ * same empty string, and every caller here (`uuidV7`, `traceId`, `spanId`) wants a width.
  */
 export function randomHex(byteLength: number): string {
   const bytes = randomBytes(finiteCount('randomHex', 'byteLength', byteLength, 1));
@@ -60,7 +60,7 @@ export function randomHex(byteLength: number): string {
  * Strictly increasing lexicographically even within the same millisecond, and never goes
  * backwards when the wall clock does.
  */
-export function uuid(clock: Clock = systemClock): string {
+export function uuidV7(clock: Clock = systemClock): string {
   let epochMs = clock.now().getTime();
   if (epochMs < lastEpochMs) epochMs = lastEpochMs;
 
@@ -108,7 +108,7 @@ export function uuidTimestamp(id: string): Date {
       // problem document, and the strings that arrive here wrong are session tokens and API keys
       // as often as they are typos. The expected shape is the half that helps the reader.
       cause: `expected a UUIDv7 (${UUID_SHAPE}), received ${describeValue(id)}`,
-      fix: 'generate ids with uuid() from @ultimat3/core',
+      fix: 'generate ids with uuidV7() from @ultimat3/core',
       meta: { received: describeValue(id) },
     });
   }
@@ -131,7 +131,7 @@ export function nanoid(length = 21): string {
 
 /** `typedId<'post'>()` — a UUIDv7 branded so it cannot be passed where a user id is wanted. */
 export function typedId<K extends string>(clock: Clock = systemClock): Id<K> {
-  return uuid(clock) as Id<K>;
+  return uuidV7(clock) as Id<K>;
 }
 
 /** Validate an untrusted string into a branded id. Throws `X_ID_INVALID`. */
@@ -166,9 +166,9 @@ const ALL_ZERO = /^0+$/;
  * The ONE definition of "is this a W3C trace id" — `traceparent` parsing, and any layer that
  * accepts an id from outside, ask here rather than carrying a second regex.
  *
- * A dashed UUID is the failure this predicate exists to name: `uuid()` produces 36 characters with
+ * A dashed UUID is the failure this predicate exists to name: `uuidV7()` produces 36 characters with
  * hyphens, every OTLP collector rejects it, and nothing downstream said so — the trace simply
- * never appeared. Mint trace ids with `traceId()`, never `uuid()`. All-zero is invalid per the
+ * never appeared. Mint trace ids with `traceId()`, never `uuidV7()`. All-zero is invalid per the
  * spec: it is the wire's spelling of "no trace", not a trace whose id happens to be zero.
  */
 export function isTraceId(value: unknown): boolean {

package/src/image/canvas.ts

@@ -5,7 +5,13 @@
 
 import { parseColor } from './color';
 import { imageUnsupported } from './errors';
-import { assertPixelBudget, createRaster, type ImageSize, type Raster } from './raster';
+import {
+  assertPixelBudget,
+  blankRaster,
+  type ImageRegion,
+  type ImageSize,
+  type Raster,
+} from './raster';
 
 export type ImageFit = 'cover' | 'contain';
 
@@ -69,7 +75,15 @@ export interface Layout {
   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. */
+  /**
+   * The part of the source that is resampled, when it is not all of it: an UPSCALING `cover`
+   * whose aspect disagrees with the box. Resampling first would draw the whole source past the
+   * box only to clip it away — a 1x200 strip at 1000x200000 for a 1000x1000 box — so the visible
+   * region is cut first and `drawn` is the inner area. A downscaling `cover` resamples first: its
+   * `drawn` is never larger than the source, and no crop then means no full-size decode.
+   */
+  readonly crop: ImageRegion | undefined;
+  /** What the source (or `crop`) is resampled to before it is placed: within `max(source, box)`. */
   readonly drawn: ImageSize;
   /** Parsed once, here, so an unspellable colour is refused before any pixel is produced. */
   readonly background: readonly [number, number, number, number];
@@ -97,7 +111,13 @@ export function layOut(source: ImageSize, spec: ResizeSpec): Layout {
       { padding, pad, width: box.width, height: box.height },
     );
   }
-  const drawn = scaledToFit(source, inner, spec.fit ?? 'contain');
+  const fit = spec.fit ?? 'contain';
+  const scaled = scaledToFit(source, inner, fit);
+  const crop = fit === 'cover' ? visibleRegion(source, inner, scaled) : undefined;
+  // The crop is whole source pixels covering the exact window, so its resample can overflow the
+  // inner area by under one scaled pixel a side; `composeOnto` centre-clips that, as it clips an
+  // uncropped cover, so both orders centre the same fractional window.
+  const drawn = crop === undefined ? scaled : drawnOf(crop, source, inner);
   // 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');
@@ -106,7 +126,58 @@ export function layOut(source: ImageSize, spec: ResizeSpec): Layout {
   // 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 };
+  return { box, pad, inner, crop, drawn, background, needsCanvas };
+}
+
+/**
+ * The source region a `cover` shows, or `undefined` when resampling the whole source first costs
+ * no more than the source itself (`scaled` within it) or nothing overflows the inner area.
+ * Centred as `composeOnto` centres an overflowing draw, so both orders crop the same window.
+ */
+function visibleRegion(
+  source: ImageSize,
+  inner: ImageSize,
+  scaled: ImageSize,
+): ImageRegion | undefined {
+  const overflows = scaled.width > inner.width || scaled.height > inner.height;
+  if (!overflows || scaled.width * scaled.height <= source.width * source.height) return undefined;
+  const scale = coverScale(source, inner);
+  // The exact window is fractional. The whole pixels that COVER it (floor to ceil) centre exactly
+  // once `composeOnto` clips the overflow; a ROUNDED window shifts a .5 offset half a source pixel
+  // off centre, which shows on a small source upscaled a lot. Covering costs up to one scaled pixel
+  // a side, so it is taken only while that stays under twice the inner area — a degenerate strip
+  // (1x200 into a square), where half a source pixel is invisible, keeps the rounded window.
+  const span = (total: number, wanted: number, cover: boolean): { start: number; size: number } => {
+    const exact = Math.min(total, wanted / scale);
+    const from = (total - exact) / 2;
+    if (!cover) {
+      const size = Math.min(total, Math.max(1, Math.round(exact)));
+      return { start: Math.round((total - size) / 2), size };
+    }
+    const start = Math.max(0, Math.floor(from));
+    return { start, size: Math.min(total, Math.ceil(from + exact)) - start };
+  };
+  const across = span(source.width, inner.width, true);
+  const down = span(source.height, inner.height, true);
+  const covered = { x: across.start, y: down.start, width: across.size, height: down.size };
+  const cost = drawnOf(covered, source, inner);
+  if (cost.width * cost.height < 2 * inner.width * inner.height) return covered;
+  const a = span(source.width, inner.width, false);
+  const d = span(source.height, inner.height, false);
+  return { x: a.start, y: d.start, width: a.size, height: d.size };
+}
+
+function coverScale(source: ImageSize, inner: ImageSize): number {
+  return Math.max(inner.width / source.width, inner.height / source.height);
+}
+
+/** The cropped region at the cover scale: the inner area plus under one scaled pixel a side. */
+function drawnOf(crop: ImageRegion, source: ImageSize, inner: ImageSize): ImageSize {
+  const scale = coverScale(source, inner);
+  return {
+    width: Math.max(inner.width, Math.round(crop.width * scale)),
+    height: Math.max(inner.height, Math.round(crop.height * scale)),
+  };
 }
 
 function fill(canvas: Raster, color: readonly [number, number, number, number]): void {
@@ -150,7 +221,7 @@ function blend(dst: Uint8ClampedArray, d: number, s: Uint8ClampedArray, p: numbe
  */
 export function composeOnto(art: Raster, layout: Layout): Raster {
   const { box, pad, inner } = layout;
-  const canvas = createRaster(box.width, box.height, 'resize');
+  const canvas = blankRaster(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);

package/src/image/errors.ts

@@ -55,7 +55,9 @@ export const imageTooLarge = (
 ): ImageTooLargeError =>
   new ImageTooLargeError(
     cause,
-    'downscale the source before it reaches the pipeline, or raise MAX_IMAGE_PIXELS deliberately',
+    // No "or lift the ceiling": `MAX_IMAGE_PIXELS` is a constant, so a fix naming it as a knob
+    // sent a reader looking for a setting that does not exist.
+    'downscale the source below the 64-megapixel ceiling before it reaches the pipeline, or route it through an ImageTransformDriver (a CDN or an external encoder) — MAX_IMAGE_PIXELS is fixed, not a setting',
     meta,
   );
 

package/src/image/pipeline.ts

@@ -9,7 +9,7 @@ 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';
+import { cropRaster, type ImageRegion, MAX_IMAGE_PIXELS } from './raster';
 
 /**
  * What the pipeline can produce, on every platform, byte for byte. `Bun.Image` also reaches
@@ -97,6 +97,15 @@ async function run<T>(doing: string, work: () => Promise<T>): Promise<T> {
   }
 }
 
+/**
+ * `region` of the source as PNG. `Bun.Image` has no crop, so the source is decoded to a raster
+ * (within the same `MAX_IMAGE_PIXELS` its header was held to) and the region copied out of it.
+ */
+async function croppedPng(bytes: Uint8Array, region: ImageRegion): Promise<Uint8Array> {
+  const whole = await run('decoding the image', () => bunImage(bytes).png().bytes());
+  return encodeImage(cropRaster(decodeImage(whole), region));
+}
+
 /** The whole pipeline in one call: decode, resize, compose, encode. */
 export async function transformImageBytes(
   bytes: Uint8Array,
@@ -112,12 +121,15 @@ export async function transformImageBytes(
   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;
+  const { box, drawn, crop } = layout;
+  // The cropped region stands in for the source from here on: what is resampled is what shows.
+  const input = crop === undefined ? bytes : await croppedPng(bytes, crop);
+  const inputSize = crop ?? source;
 
   if (!layout.needsCanvas) {
     return run('transforming the image', () => {
-      const image = bunImage(bytes);
-      if (box.width !== source.width || box.height !== source.height) {
+      const image = bunImage(input);
+      if (box.width !== inputSize.width || box.height !== inputSize.height) {
         image.resize(box.width, box.height, { fit: 'fill' });
       }
       return withFormat(image, output, quality).bytes();
@@ -130,7 +142,7 @@ export async function transformImageBytes(
   // 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(),
+    bunImage(input).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());