@ultimat3/core 24.0.0 → 25.0.0

package/src/env-example.ts

@@ -2,16 +2,12 @@
 // second hand-maintained list. Render it from the declarations, and report drift when the file on
 // disk has fallen behind. Loading `.env` itself is Bun's job — see `envFileCandidates()`.
 
-import type { EnvSchema, EnvVarDecl } from './env';
-import { type CodedErrorInit, UltimateError } from './errors';
+//
+// It REPORTS and never throws. `assertEnvExample` and its `EnvExampleDriftError` were deleted in
+// 25.0.0: a second, weaker gate nothing called. `X_ENV_EXAMPLE_DRIFT` is `x verify`'s `manifest`
+// step's finding (`@ultimat3/cli`'s `app-env.ts`), byte-for-byte against `renderEnvExample`.
 
-export class EnvExampleDriftError extends UltimateError {
-  static readonly code = 'X_ENV_EXAMPLE_DRIFT';
-  override readonly name = 'EnvExampleDriftError';
-  constructor(init: CodedErrorInit) {
-    super({ ...init, code: EnvExampleDriftError.code });
-  }
-}
+import type { EnvSchema, EnvVarDecl } from './env';
 
 const ENV_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
@@ -99,11 +95,10 @@ export interface EnvExampleReport {
   /**
    * In the file, not in the schema — never fatal, because apps set keys nothing declares.
    *
-   * NOT reported on its own, and the comment here said it was. `ok` is `missing.length === 0`, so
-   * an example carrying only extra keys returns `ok: true` and `assertEnvExample` never builds an
-   * error: the list reaches a surface only as `meta` on a drift some MISSING key already raised.
-   * A caller that wants it reads `checkEnvExample(...).extra` itself, which is why this stays
-   * public. `env-example.test.ts` pins both halves.
+   * NOT reported on its own. `ok` is `missing.length === 0`, so an example carrying only extra
+   * keys returns `ok: true`; the framework's reporter (`@ultimat3/cli`'s `app-env.ts`) builds its
+   * finding from `missing` only. A caller that wants it reads `checkEnvExample(...).extra` itself,
+   * which is why this stays public. `env-example.test.ts` pins it.
    */
   readonly extra: readonly string[];
 }
@@ -115,18 +110,3 @@ export function checkEnvExample(schema: EnvSchema, text: string): EnvExampleRepo
   const extra = [...present].filter((key) => !declared.includes(key));
   return { ok: missing.length === 0, missing, extra };
 }
-
-/**
- * Throws `X_ENV_EXAMPLE_DRIFT` when the committed example has fallen behind the schema — the
- * failure an agent hits *before* a teammate hits `X_ENV_MISSING` on a variable nobody told them
- * about.
- */
-export function assertEnvExample(schema: EnvSchema, text: string, path = ENV_EXAMPLE_PATH): void {
-  const report = checkEnvExample(schema, text);
-  if (report.ok) return;
-  throw new EnvExampleDriftError({
-    cause: `${path} does not declare ${report.missing.join(', ')}, declared by defineEnv()`,
-    fix: `Bun.write('${path}', renderEnvExample(schema)) — regenerate it from the declarations`,
-    meta: { path, missing: report.missing, extra: report.extra },
-  });
-}

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

@@ -35,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. */
@@ -46,23 +51,20 @@ 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(
-    `createFlightGate (${subject})`,
+    `flightGate (${subject})`,
     'maxConcurrent',
     limits.maxConcurrent,
   );
-  const maxQueued = finiteCount(`createFlightGate (${subject})`, 'maxQueued', limits.maxQueued);
+  const maxQueued = finiteCount(`flightGate (${subject})`, 'maxQueued', limits.maxQueued);
   const waiters: Array<() => void> = [];
   let active = 0;
 
@@ -74,7 +76,8 @@ export function createFlightGate(
     subject,
   });
 
-  const acquire = async (): Promise<void> => {
+  const acquire = async (signal: AbortSignal | undefined): Promise<void> => {
+    if (signal?.aborted === true) throw signal.reason;
     if (active < maxConcurrent) {
       active += 1;
       return;
@@ -85,8 +88,20 @@ export function createFlightGate(
       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 });
     });
   };
 
@@ -103,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 {
@@ -124,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/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/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/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());

package/src/image/raster.ts

@@ -43,7 +43,7 @@ export function assertPixelBudget(width: number, height: number, source: string)
 }
 
 /** A transparent canvas of the given size, budget already checked. */
-export function createRaster(width: number, height: number, source = 'raster'): Raster {
+export function blankRaster(width: number, height: number, source = 'raster'): Raster {
   assertPixelBudget(width, height, source);
   return { width, height, pixels: new Uint8ClampedArray(width * height * 4) };
 }
@@ -63,6 +63,29 @@ export function rasterFrom(width: number, height: number, pixels: Uint8ClampedAr
   return { width, height, pixels };
 }
 
+/** A rectangle of a raster, in its pixels. */
+export interface ImageRegion extends ImageSize {
+  readonly x: number;
+  readonly y: number;
+}
+
+/** The pixels of `region`, copied row by row. The region must lie inside the raster. */
+export function cropRaster(raster: Raster, region: ImageRegion): Raster {
+  const { x, y, width, height } = region;
+  if (x < 0 || y < 0 || x + width > raster.width || y + height > raster.height) {
+    throw imageDecodeFailed(
+      `crop ${width}x${height}+${x}+${y} lies outside the ${raster.width}x${raster.height} raster`,
+      { x, y, width, height, rasterWidth: raster.width, rasterHeight: raster.height },
+    );
+  }
+  const out = blankRaster(width, height, 'crop');
+  for (let row = 0; row < height; row += 1) {
+    const from = ((y + row) * raster.width + x) * 4;
+    out.pixels.set(raster.pixels.subarray(from, from + width * 4), row * width * 4);
+  }
+  return out;
+}
+
 /** Whether any pixel is not fully opaque — decides PNG vs JPEG when nobody asked. */
 export function hasAlpha(raster: Raster): boolean {
   const { pixels } = raster;