@workglow/util 0.2.19 → 0.2.21

package/dist/json-schema/SchemaValidation.d.ts

@@ -14,6 +14,12 @@ export interface SchemaValidationResult {
     readonly valid: boolean;
     readonly errors: readonly SchemaValidationError[];
 }
+/**
+ * Pattern for format annotations used in dataflow compatibility checking.
+ * Format: /\w+(:\w+)?/ where first part is the "name" and optional second part narrows the type.
+ * Reused from SchemaUtils.ts areFormatStringsCompatible().
+ */
+export declare const FORMAT_PATTERN: RegExp;
 /**
  * Validates that a schema is a well-formed DataPortSchema.
  *

package/dist/json-schema/SchemaValidation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SchemaValidation.d.ts","sourceRoot":"","sources":["../../src/json-schema/SchemaValidation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,YAAY,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAEhE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAOvD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACnD;AA4BD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,cAAc,GAAG,sBAAsB,CAyCrF;AAgFD;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,cAAc,GAAG,sBAAsB,CAexF;AAqDD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,sBAAsB,CAU7E"}
+{"version":3,"file":"SchemaValidation.d.ts","sourceRoot":"","sources":["../../src/json-schema/SchemaValidation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,YAAY,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAEhE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAOvD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACnD;AAOD;;;;GAIG;AACH,eAAO,MAAM,cAAc,QAA4D,CAAC;AAgBxF;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,cAAc,GAAG,sBAAsB,CAyCrF;AAgFD;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,cAAc,GAAG,sBAAsB,CAexF;AAqDD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,sBAAsB,CAU7E"}

package/dist/media/cpuImage.d.ts

@@ -3,27 +3,26 @@
  * Copyright 2026 Steven Roussey
  * All Rights Reserved
  */
-import type { ImageBinary } from "./imageTypes";
-import { type GpuImage as IGpuImage, type GpuImageEncodeFormat } from "./gpuImage";
+import type { ImageChannels } from "./imageTypes";
+import type { GpuImage as IGpuImage, GpuImageEncodeFormat } from "./gpuImage";
+import type { ImageValue } from "./imageValue";
+import type { RawPixelBuffer } from "./rawPixelBuffer";
+export type { RawPixelBuffer } from "./rawPixelBuffer";
 export declare class CpuImage implements IGpuImage {
-    private readonly bin;
+    private bin;
     readonly backend: "cpu";
-    private _previewScale;
     private constructor();
     get width(): number;
     get height(): number;
-    get channels(): ImageBinary["channels"];
-    get previewScale(): number;
-    /** @internal — only previewSource and ImageTextTask.executePreview (without-
-     *  background source case) may call this. */
-    _setPreviewScale(scale: number): this;
-    materialize(): Promise<ImageBinary>;
-    /** @internal — synchronous accessor used by per-filter cpu ops to avoid awaiting materialize(). */
-    getBinary(): ImageBinary;
-    toCanvas(canvas: HTMLCanvasElement | OffscreenCanvas): Promise<void>;
+    get channels(): ImageChannels;
+    /** @internal — used by CPU filter ops to read the raw pixel buffer. */
+    getBinary(): RawPixelBuffer;
+    static from(value: ImageValue): Promise<CpuImage>;
+    /** @internal — synchronous factory for backends that already have a raw buffer
+     *  in hand (used by the WGSL CPU fallback). */
+    static fromRaw(bin: RawPixelBuffer): CpuImage;
+    toImageValue(previewScale: number): Promise<ImageValue>;
     encode(format: GpuImageEncodeFormat, _quality?: number): Promise<Uint8Array>;
-    retain(_n?: number): this;
-    release(): void;
-    static fromImageBinary(bin: ImageBinary, previewScale?: number): CpuImage;
+    dispose(): void;
 }
 //# sourceMappingURL=cpuImage.d.ts.map

package/dist/media/cpuImage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cpuImage.d.ts","sourceRoot":"","sources":["../../src/media/cpuImage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAEL,KAAK,QAAQ,IAAI,SAAS,EAC1B,KAAK,oBAAoB,EAC1B,MAAM,YAAY,CAAC;AAyCpB,qBAAa,QAAS,YAAW,SAAS;IAKpB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAJxC,QAAQ,CAAC,OAAO,EAAG,KAAK,CAAU;IAElC,OAAO,CAAC,aAAa,CAAS;IAE9B,OAAO,eAEN;IAED,IAAI,KAAK,IAAI,MAAM,CAElB;IACD,IAAI,MAAM,IAAI,MAAM,CAEnB;IACD,IAAI,QAAQ,IAAI,WAAW,CAAC,UAAU,CAAC,CAEtC;IAED,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED;iDAC6C;IAC7C,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAGpC;IAEK,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,CAExC;IAED,mGAAmG;IACnG,SAAS,IAAI,WAAW,CAEvB;IAEK,QAAQ,CAAC,MAAM,EAAE,iBAAiB,GAAG,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAczE;IAEK,MAAM,CAAC,MAAM,EAAE,oBAAoB,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAIjF;IAED,MAAM,CAAC,EAAE,GAAE,MAAU,GAAG,IAAI,CAG3B;IAED,OAAO,IAAI,IAAI,CAEd;IAED,MAAM,CAAC,eAAe,CAAC,GAAG,EAAE,WAAW,EAAE,YAAY,GAAE,MAAY,GAAG,QAAQ,CAE7E;CACF"}
+{"version":3,"file":"cpuImage.d.ts","sourceRoot":"","sources":["../../src/media/cpuImage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EACV,QAAQ,IAAI,SAAS,EACrB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,UAAU,EAAkB,MAAM,cAAc,CAAC;AAG/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAQvD,qBAAa,QAAS,YAAW,SAAS;IAGpB,OAAO,CAAC,GAAG;IAF/B,QAAQ,CAAC,OAAO,EAAG,KAAK,CAAU;IAElC,OAAO,eAAmD;IAE1D,IAAI,KAAK,IAAI,MAAM,CAGlB;IACD,IAAI,MAAM,IAAI,MAAM,CAGnB;IACD,IAAI,QAAQ,IAAI,aAAa,CAG5B;IAED,uEAAuE;IACvE,SAAS,IAAI,cAAc,CAG1B;IAED,OAAa,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC,CAiBtD;IAED;mDAC+C;IAC/C,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,cAAc,GAAG,QAAQ,CAE5C;IAEK,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAkC5D;IAEK,MAAM,CAAC,MAAM,EAAE,oBAAoB,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAKjF;IAED,OAAO,IAAI,IAAI,CAEd;CACF"}

package/dist/media/encode.d.ts

@@ -3,9 +3,7 @@
  * Copyright 2026 Steven Roussey
  * All Rights Reserved
  */
-import type { ImageBinary } from "./imageTypes";
-export declare function encodeImageBinaryToPng(bin: ImageBinary): Promise<Uint8Array>;
-export declare function imageBinaryToBase64Png(bin: ImageBinary): Promise<string>;
-export declare function imageBinaryToDataUri(bin: ImageBinary, mimeType?: string): Promise<string>;
-export declare function imageBinaryToBlob(bin: ImageBinary, mimeType?: string): Promise<Blob>;
+import type { RawPixelBuffer } from "./rawPixelBuffer";
+export declare function rawPixelBufferToDataUri(bin: RawPixelBuffer, mimeType?: string): Promise<string>;
+export declare function rawPixelBufferToBlob(bin: RawPixelBuffer, mimeType?: string): Promise<Blob>;
 //# sourceMappingURL=encode.d.ts.map

package/dist/media/encode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"encode.d.ts","sourceRoot":"","sources":["../../src/media/encode.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAYhD,wBAAsB,sBAAsB,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAElF;AAED,wBAAsB,sBAAsB,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAG9E;AAED,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,WAAW,EAAE,QAAQ,SAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAEpG;AAED,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,WAAW,EAAE,QAAQ,SAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAG/F"}
+{"version":3,"file":"encode.d.ts","sourceRoot":"","sources":["../../src/media/encode.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAYvD,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,cAAc,EACnB,QAAQ,SAAc,GACrB,OAAO,CAAC,MAAM,CAAC,CAEjB;AAED,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,cAAc,EACnB,QAAQ,SAAc,GACrB,OAAO,CAAC,IAAI,CAAC,CAGf"}

package/dist/media/gpuImage.d.ts

@@ -3,48 +3,39 @@
  * Copyright 2026 Steven Roussey
  * All Rights Reserved
  */
-import type { ImageBinary, ImageChannels } from "./imageTypes";
+import type { ImageChannels } from "./imageTypes";
+import type { ImageValue } from "./imageValue";
 export type GpuImageBackend = "webgpu" | "sharp" | "cpu";
 export type GpuImageEncodeFormat = "png" | "jpeg" | "webp";
+/**
+ * `GpuImage` is a private implementation detail of image tasks: it never
+ * crosses a task/engine/worker boundary. Lives only inside an
+ * `ImageFilterTask.execute` method body. Cross-boundary currency is
+ * `ImageValue`. Use `GpuImage.from(value)` at task entry and
+ * `imageValueFromGpu(out, scale)` (or `transferToImageBitmap()` /
+ * `toBuffer()` directly) at task exit.
+ */
 export interface GpuImage {
     readonly width: number;
     readonly height: number;
     readonly channels: ImageChannels;
     readonly backend: GpuImageBackend;
-    /** Ratio of current dims to user's intended (pre-preview-downscale) dims.
-     *  1.0 in run mode and any image not derived from a previewSource downscale.
-     *  < 1.0 after previewSource has fired. Pixel-space task params are
-     *  multiplied by this before dispatch in preview mode (no-op at 1.0). */
-    readonly previewScale: number;
-    materialize(): Promise<ImageBinary>;
-    toCanvas(canvas: HTMLCanvasElement | OffscreenCanvas): Promise<void>;
+    /** Materialize back into a wire-form `ImageValue`. Always returns a fresh
+     *  ImageValue; the caller is the new owner. */
+    toImageValue(previewScale: number): Promise<ImageValue>;
+    /** Encode to a compressed image format (png/jpeg/webp). Implementations MAY
+     *  consume the underlying resource — treat as single-use. */
     encode(format: GpuImageEncodeFormat, quality?: number): Promise<Uint8Array>;
-    /**
-     * Increment the refcount by `n` (default 1). Returns `this` for chaining.
-     * No-op for backends without external resource lifetime (CpuImage, SharpImage).
-     * Throws if the resource has already been reclaimed (count was already 0).
-     */
-    retain(n?: number): this;
-    /**
-     * Decrement the refcount by 1. When it hits 0, reclaim the underlying resource
-     * (e.g., return the GPU texture to the pool). Throws on release-after-reclaim.
-     * No-op for backends without external resource lifetime.
-     */
-    release(): void;
+    /** Early cleanup on error paths only. Required because GPU/native resources
+     *  are not held by GC. The happy path uses `toImageValue()` which transfers
+     *  ownership; this is the abort/error case. */
+    dispose(): void;
 }
 export interface GpuImageStatic {
-    fromImageBinary(bin: ImageBinary): GpuImage;
-    fromImageBinaryAsync?(bin: ImageBinary): Promise<GpuImage>;
-    fromDataUri(dataUri: string): Promise<GpuImage>;
-    fromBlob(blob: Blob): Promise<GpuImage>;
-    fromImageBitmap?(bitmap: ImageBitmap): Promise<GpuImage>;
+    /** Bridge from the cross-boundary `ImageValue` to a backend-private GpuImage. */
+    from(value: ImageValue): Promise<GpuImage>;
 }
 export declare function registerGpuImageFactory<K extends keyof GpuImageStatic>(key: K, fn: GpuImageStatic[K]): void;
-/**
- * Returns the registered factory function for `key`, or `undefined` if it
- * has not been registered. Prefer this over accessing `GpuImage[key]` directly
- * when the factory is optional — the Proxy throws on missing registrations.
- */
 export declare function getGpuImageFactory<K extends keyof GpuImageStatic>(key: K): GpuImageStatic[K] | undefined;
 export declare const GpuImage: GpuImageStatic;
 //# sourceMappingURL=gpuImage.d.ts.map

package/dist/media/gpuImage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gpuImage.d.ts","sourceRoot":"","sources":["../../src/media/gpuImage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE/D,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,OAAO,GAAG,KAAK,CAAC;AACzD,MAAM,MAAM,oBAAoB,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;AAE3D,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC;;;6EAGyE;IACzE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,GAAG,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE,MAAM,CAAC,MAAM,EAAE,oBAAoB,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC5E;;;;OAIG;IACH,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;;;OAIG;IACH,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,eAAe,CAAC,GAAG,EAAE,WAAW,GAAG,QAAQ,CAAC;IAC5C,oBAAoB,CAAC,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC3D,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAChD,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACxC,eAAe,CAAC,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC1D;AAaD,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,MAAM,cAAc,EACpE,GAAG,EAAE,CAAC,EACN,EAAE,EAAE,cAAc,CAAC,CAAC,CAAC,GACpB,IAAI,CAEN;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,cAAc,EAC/D,GAAG,EAAE,CAAC,GACL,cAAc,CAAC,CAAC,CAAC,GAAG,SAAS,CAG/B;AAED,eAAO,MAAM,QAAQ,EAAE,cASrB,CAAC"}
+{"version":3,"file":"gpuImage.d.ts","sourceRoot":"","sources":["../../src/media/gpuImage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,OAAO,GAAG,KAAK,CAAC;AACzD,MAAM,MAAM,oBAAoB,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;AAE3D;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC;mDAC+C;IAC/C,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACxD;iEAC6D;IAC7D,MAAM,CAAC,MAAM,EAAE,oBAAoB,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC5E;;mDAE+C;IAC/C,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,iFAAiF;IACjF,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC5C;AASD,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,MAAM,cAAc,EACpE,GAAG,EAAE,CAAC,EACN,EAAE,EAAE,cAAc,CAAC,CAAC,CAAC,GACpB,IAAI,CAEN;AAED,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,cAAc,EAC/D,GAAG,EAAE,CAAC,GACL,cAAc,CAAC,CAAC,CAAC,GAAG,SAAS,CAG/B;AAED,eAAO,MAAM,QAAQ,EAAE,cASrB,CAAC"}

package/dist/media/imageCacheCodec.d.ts

@@ -1,9 +1,21 @@
-import type { ImageChannels } from "./imageTypes";
-export interface CachedImage {
-    kind: "image-binary";
-    width: number;
-    height: number;
-    channels: ImageChannels;
-    data: Uint8ClampedArray;
+import type { NodeImageFormat } from "./imageValue";
+/**
+ * Cache codec for `format: "image"` ports.
+ *
+ * Produces a JSON-safe wire form so persistent caches (e.g. `TaskOutputTabularRepository`,
+ * which stringifies before writing to disk) can round-trip image outputs. The wire form
+ * carries encoded bytes plus dimensions and `previewScale`; the decoded shape is the
+ * platform-native `ImageValue` (browser → `BrowserImageValue`, node/bun → `NodeImageValue`).
+ *
+ * Cross-platform read is supported: a node-written cache entry decodes to a
+ * `BrowserImageValue` when read in the browser (via `createImageBitmap`), and vice versa.
+ */
+export interface ImageValueWire {
+    readonly __imageValueWire: 1;
+    readonly format: NodeImageFormat;
+    readonly base64: string;
+    readonly width: number;
+    readonly height: number;
+    readonly previewScale: number;
 }
 //# sourceMappingURL=imageCacheCodec.d.ts.map

package/dist/media/imageCacheCodec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"imageCacheCodec.d.ts","sourceRoot":"","sources":["../../src/media/imageCacheCodec.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAe,aAAa,EAAE,MAAM,cAAc,CAAC;AAE/D,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,cAAc,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,aAAa,CAAC;IACxB,IAAI,EAAE,iBAAiB,CAAC;CACzB"}
+{"version":3,"file":"imageCacheCodec.d.ts","sourceRoot":"","sources":["../../src/media/imageCacheCodec.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAiC,eAAe,EAAE,MAAM,cAAc,CAAC;AAGnF;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B"}

package/dist/media/imageRasterCodecRegistry.d.ts

@@ -3,10 +3,10 @@
  * Copyright 2026 Steven Roussey <sroussey@gmail.com>
  * SPDX-License-Identifier: Apache-2.0
  */
-import type { ImageBinary } from "./imageTypes";
+import type { RawPixelBuffer } from "./rawPixelBuffer";
 export interface ImageRasterCodec {
-    decodeDataUri(dataUri: string): Promise<ImageBinary>;
-    encodeDataUri(image: ImageBinary, mimeType: string): Promise<string>;
+    decodeDataUri(dataUri: string): Promise<RawPixelBuffer>;
+    encodeDataUri(image: RawPixelBuffer, mimeType: string): Promise<string>;
 }
 export declare function registerImageRasterCodec(next: ImageRasterCodec): void;
 export declare function getImageRasterCodec(): ImageRasterCodec;

package/dist/media/imageRasterCodecRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"imageRasterCodecRegistry.d.ts","sourceRoot":"","sources":["../../src/media/imageRasterCodecRegistry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,MAAM,WAAW,gBAAgB;IAC/B,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACrD,aAAa,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACtE;AAeD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAErE;AAED,wBAAgB,mBAAmB,IAAI,gBAAgB,CAOtD"}
+{"version":3,"file":"imageRasterCodecRegistry.d.ts","sourceRoot":"","sources":["../../src/media/imageRasterCodecRegistry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,MAAM,WAAW,gBAAgB;IAC/B,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACxD,aAAa,CAAC,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACzE;AAeD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAErE;AAED,wBAAgB,mBAAmB,IAAI,gBAAgB,CAOtD"}

package/dist/media/imageTypes.d.ts

@@ -4,20 +4,4 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 export type ImageChannels = 1 | 3 | 4;
-export type ImageDataSupport = "Blob" | "ImageBinary" | "ImageBitmap" | "OffscreenCanvas" | "VideoFrame" | "RawImage" | "DataUri" | "Sharp";
-export interface ImageBinary {
-    data: Uint8ClampedArray;
-    width: number;
-    height: number;
-    channels: ImageChannels;
-    rawChannels?: number | undefined;
-}
-/** RGBA pixel buffer (`channels` is always 4). */
-export type RgbaImageBinary = Readonly<Omit<ImageBinary, "channels" | "rawChannels"> & {
-    readonly channels: 4;
-}>;
-export declare function parseDataUri(dataUri: string): {
-    mimeType: string;
-    base64: string;
-};
 //# sourceMappingURL=imageTypes.d.ts.map

package/dist/media/imageTypes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"imageTypes.d.ts","sourceRoot":"","sources":["../../src/media/imageTypes.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAEtC,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN,aAAa,GACb,aAAa,GACb,iBAAiB,GACjB,YAAY,GACZ,UAAU,GACV,SAAS,GACT,OAAO,CAAC;AAEZ,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,iBAAiB,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,aAAa,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAED,kDAAkD;AAClD,MAAM,MAAM,eAAe,GAAG,QAAQ,CACpC,IAAI,CAAC,WAAW,EAAE,UAAU,GAAG,aAAa,CAAC,GAAG;IAAE,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAA;CAAE,CACzE,CAAC;AAEF,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB,CAUA"}
+{"version":3,"file":"imageTypes.d.ts","sourceRoot":"","sources":["../../src/media/imageTypes.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC"}

package/dist/media/imageValue.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export type NodeImageFormat = "png" | "jpeg" | "raw-rgba";
+export interface ImageValueBase {
+    readonly width: number;
+    readonly height: number;
+    readonly previewScale: number;
+}
+export interface BrowserImageValue extends ImageValueBase {
+    readonly bitmap: ImageBitmap;
+}
+export interface NodeImageValue extends ImageValueBase {
+    readonly buffer: Buffer;
+    readonly format: NodeImageFormat;
+}
+export type ImageValue = BrowserImageValue | NodeImageValue;
+export declare function imageValueFromBitmap(bitmap: ImageBitmap, width: number, height: number, previewScale?: number): BrowserImageValue;
+export declare function imageValueFromBuffer(buffer: Buffer, format: NodeImageFormat, width: number, height: number, previewScale?: number): NodeImageValue;
+export declare function isImageValue(v: unknown): v is ImageValue;
+export declare function isBrowserImageValue(v: unknown): v is BrowserImageValue;
+export declare function isNodeImageValue(v: unknown): v is NodeImageValue;
+/**
+ * Best-effort normalization at boundaries (input resolver, builder hook).
+ * Accepts the wire forms an `ImageValue` port may receive:
+ *   - an existing `ImageValue` (passthrough)
+ *   - a `data:` URI (browser: decoded via `createImageBitmap`; node: encoded
+ *     bytes wrapped in a `NodeImageValue`, with dimensions probed via the
+ *     registered raster codec)
+ *   - a `Blob` (browser only)
+ *   - an `ImageBitmap` (browser only)
+ * Returns `undefined` for unrecognized shapes.
+ *
+ * Note: a raw `Buffer` is intentionally not handled here — callers with
+ * encoded bytes plus a format hint should construct one via
+ * `imageValueFromBuffer(...)` directly.
+ *
+ * String dispatch is platform-agnostic; non-string platform-specific shapes
+ * are tested via `typeof` guards so the same module loads on browser and node.
+ */
+export declare function normalizeToImageValue(value: unknown): Promise<ImageValue | undefined>;
+//# sourceMappingURL=imageValue.d.ts.map

package/dist/media/imageValue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"imageValue.d.ts","sourceRoot":"","sources":["../../src/media/imageValue.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,MAAM,GAAG,UAAU,CAAC;AAE1D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAkB,SAAQ,cAAc;IACvD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED,MAAM,WAAW,cAAe,SAAQ,cAAc;IACpD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;CAClC;AAED,MAAM,MAAM,UAAU,GAAG,iBAAiB,GAAG,cAAc,CAAC;AAE5D,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,YAAY,GAAE,MAAY,GACzB,iBAAiB,CAEnB;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,eAAe,EACvB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,YAAY,GAAE,MAAY,GACzB,cAAc,CAEhB;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,UAAU,CAExD;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,iBAAiB,CAUtE;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,cAAc,CAWhE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CA6B3F"}

package/dist/media/imageValue.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};
+//# sourceMappingURL=imageValue.test.d.ts.map

package/dist/media/imageValue.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"imageValue.test.d.ts","sourceRoot":"","sources":["../../src/media/imageValue.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/media/imageValueSchema.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @copyright
+ * Copyright 2026 Steven Roussey
+ * All Rights Reserved
+ */
+import type { DataPortSchema } from "../json-schema/DataPortSchema";
+/**
+ * Schema annotation for `ImageValue` ports. Multi-type form so the
+ * validator accepts the wire forms an `ImageValue` port may receive
+ * before hydration: `string` (data: URI), `object` (Blob, ImageBitmap, an
+ * ImageValue, or a `Buffer`-like). The `format: "image"` annotation drives
+ * the input resolver.
+ */
+export declare function ImageValueSchema(annotations?: Record<string, unknown>): DataPortSchema;
+//# sourceMappingURL=imageValueSchema.d.ts.map

package/dist/media/imageValueSchema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"imageValueSchema.d.ts","sourceRoot":"","sources":["../../src/media/imageValueSchema.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAEpE;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,cAAc,CAS1F"}

package/dist/media/previewBudget.d.ts

@@ -3,21 +3,18 @@
  * Copyright 2026 Steven Roussey
  * All Rights Reserved
  */
-import type { GpuImage } from "./gpuImage";
-export type PreviewResizeFn = (image: GpuImage, w: number, h: number) => GpuImage;
-export declare function registerPreviewResizeFn(fn: PreviewResizeFn): void;
+import type { ImageValue } from "./imageValue";
+export type PreviewResizeFn = (image: ImageValue, width: number, height: number) => Promise<ImageValue>;
+export declare function registerPreviewResizeFn(fn: PreviewResizeFn | undefined): void;
 export declare function getPreviewBudget(): number;
 export declare function setPreviewBudget(px: number): void;
 /**
- * Scale-then-effect entry for `executePreview`. Returns a downscaled image
- * when the input's longer edge exceeds the budget AND the backend benefits
- * (webgpu only). Otherwise returns the input unchanged — referential
- * equality is the signal to callers that no transient was created.
- *
- * Calling code that wants downscale must call `registerPreviewResizeFn` at
- * startup with a callback that performs the resize (typically routed through
- * @workglow/tasks's applyFilter). Without registration, previewSource is
- * a no-op even on webgpu inputs.
+ * Engine-applied chain-head downscale for `runPreview`. Idempotent: when
+ * the input is already within budget, returns the input unchanged
+ * (referential equality is the no-op signal). When over budget, calls the
+ * registered resize fn (typically routed through Sharp on node and an
+ * OffscreenCanvas/WebGPU resize on browser) and composes `previewScale`:
+ * `out.previewScale = in.previewScale × downscaleRatio`.
  */
-export declare function previewSource(image: GpuImage): GpuImage;
+export declare function previewSource(image: ImageValue): Promise<ImageValue>;
 //# sourceMappingURL=previewBudget.d.ts.map

package/dist/media/previewBudget.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"previewBudget.d.ts","sourceRoot":"","sources":["../../src/media/previewBudget.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAiB3C,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,QAAQ,CAAC;AAQlF,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,eAAe,GAAG,IAAI,CAEjE;AAMD,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAKjD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,QAAQ,GAAG,QAAQ,CAcvD"}
+{"version":3,"file":"previewBudget.d.ts","sourceRoot":"","sources":["../../src/media/previewBudget.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAc/C,MAAM,MAAM,eAAe,GAAG,CAC5B,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,KACX,OAAO,CAAC,UAAU,CAAC,CAAC;AAQzB,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,eAAe,GAAG,SAAS,GAAG,IAAI,CAE7E;AAMD,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAKjD;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAe1E"}

package/dist/media/rawPixelBuffer.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ImageChannels } from "./imageTypes";
+/** Internal pixel-buffer shape used by CPU filter ops and codec helpers.
+ *  Replaces the old `ImageBinary` export — the boundary type is now `ImageValue`. */
+export interface RawPixelBuffer {
+    data: Uint8ClampedArray;
+    width: number;
+    height: number;
+    channels: ImageChannels;
+    rawChannels?: number | undefined;
+}
+/** RGBA-only variant. */
+export type RgbaPixelBuffer = Readonly<Omit<RawPixelBuffer, "channels" | "rawChannels"> & {
+    readonly channels: 4;
+}>;
+//# sourceMappingURL=rawPixelBuffer.d.ts.map

package/dist/media/rawPixelBuffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rawPixelBuffer.d.ts","sourceRoot":"","sources":["../../src/media/rawPixelBuffer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD;qFACqF;AACrF,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,iBAAiB,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,aAAa,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAED,yBAAyB;AACzB,MAAM,MAAM,eAAe,GAAG,QAAQ,CACpC,IAAI,CAAC,cAAc,EAAE,UAAU,GAAG,aAAa,CAAC,GAAG;IAAE,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAA;CAAE,CAC5E,CAAC"}

package/dist/media/{sharpImage.node.d.ts → sharpImage.server.d.ts}

@@ -3,8 +3,9 @@
  * Copyright 2026 Steven Roussey
  * All Rights Reserved
  */
-import type { ImageBinary, ImageChannels } from "./imageTypes";
+import type { ImageChannels } from "./imageTypes";
 import type { GpuImage as IGpuImage, GpuImageEncodeFormat } from "./gpuImage";
+import type { ImageValue } from "./imageValue";
 type Sharp = {
     clone(): Sharp;
     flip(): Sharp;
@@ -15,7 +16,7 @@ type Sharp = {
         alpha?: boolean;
     }): Sharp;
     recomb(matrix: number[][]): Sharp;
-    linear(a: number, b: number): Sharp;
+    linear(a: number | number[], b: number | number[]): Sharp;
     threshold(threshold: number, options?: {
         grayscale?: boolean;
     }): Sharp;
@@ -70,24 +71,51 @@ export declare class SharpImage implements IGpuImage {
     readonly height: number;
     readonly channels: ImageChannels;
     readonly backend: "sharp";
-    private _previewScale;
     private constructor();
-    get previewScale(): number;
-    /** @internal — only previewSource and ImageTextTask.executePreview (without-
-     *  background source case) may call this. */
-    _setPreviewScale(scale: number): this;
-    static fromImageBinary(bin: ImageBinary, previewScale?: number): Promise<SharpImage>;
-    static fromBuffer(buf: Buffer): Promise<SharpImage>;
+    static from(value: ImageValue): Promise<SharpImage>;
     apply(op: (p: Sharp) => Sharp, outSize?: {
         width: number;
         height: number;
         channels?: ImageChannels;
     }): SharpImage;
-    materialize(): Promise<ImageBinary>;
-    toCanvas(_canvas: HTMLCanvasElement | OffscreenCanvas): Promise<void>;
+    toBuffer(format: "png" | "jpeg" | "raw-rgba"): Promise<Buffer>;
+    toImageValue(previewScale: number): Promise<ImageValue>;
     encode(format: GpuImageEncodeFormat, quality?: number): Promise<Uint8Array>;
-    retain(_n?: number): this;
-    release(): void;
+    dispose(): void;
 }
+export interface DecodeBufferToRawOptions {
+    readonly limitInputPixels?: number;
+    readonly sequentialRead?: boolean;
+    readonly ensureAlpha?: boolean;
+}
+export interface RawPixelInput {
+    readonly data: Buffer | Uint8ClampedArray;
+    readonly width: number;
+    readonly height: number;
+    readonly channels: 1 | 2 | 3 | 4;
+}
+export type EncodeRawPixelsOptions = {
+    readonly format: "png";
+    readonly compressionLevel?: number;
+} | {
+    readonly format: "jpeg";
+    readonly quality?: number;
+    readonly mozjpeg?: boolean;
+} | {
+    readonly format: "webp";
+    readonly quality?: number;
+};
+export declare function probeImageDimensions(buffer: Buffer): Promise<{
+    width: number;
+    height: number;
+    channels: number | undefined;
+}>;
+export declare function decodeBufferToRaw(buffer: Buffer, options?: DecodeBufferToRawOptions): Promise<{
+    data: Buffer;
+    width: number;
+    height: number;
+    channels: number;
+}>;
+export declare function encodeRawPixels(raw: RawPixelInput, options: EncodeRawPixelsOptions): Promise<Buffer>;
 export {};
-//# sourceMappingURL=sharpImage.node.d.ts.map
+//# sourceMappingURL=sharpImage.server.d.ts.map

package/dist/media/sharpImage.server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharpImage.server.d.ts","sourceRoot":"","sources":["../../src/media/sharpImage.server.ts"],"names":[],"mappings":"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"}

package/dist/media/webGpuImage.browser.d.ts

@@ -3,8 +3,9 @@
  * Copyright 2026 Steven Roussey
  * All Rights Reserved
  */
-import type { ImageBinary, ImageChannels } from "./imageTypes";
+import type { ImageChannels } from "./imageTypes";
 import type { GpuImage as IGpuImage, GpuImageEncodeFormat } from "./gpuImage";
+import type { ImageValue } from "./imageValue";
 export interface ApplyParams {
     shader: string;
     uniforms: ArrayBuffer | undefined;
@@ -20,21 +21,17 @@ export declare class WebGpuImage implements IGpuImage {
     readonly height: number;
     readonly backend: "webgpu";
     readonly channels: ImageChannels;
-    /** Internal refcount. Initialized to 1 in fromImageBinary/apply. Reclaim at 0. */
-    private refcount;
-    private _previewScale;
     private constructor();
-    get previewScale(): number;
-    /** @internal — only previewSource and ImageTextTask.executePreview (without-
-     *  background source case) may call this. Mutates previewScale on this
-     *  instance and returns this for chaining. */
-    _setPreviewScale(scale: number): this;
-    static fromImageBinary(bin: ImageBinary): Promise<WebGpuImage>;
+    static from(value: ImageValue): Promise<WebGpuImage>;
     apply(params: ApplyParams): WebGpuImage;
-    materialize(): Promise<ImageBinary>;
-    toCanvas(canvas: HTMLCanvasElement | OffscreenCanvas): Promise<void>;
+    /** Synchronous transfer to ImageBitmap via OffscreenCanvas. The transfer
+     *  drains the texture; this image is disposed afterward. */
+    transferToImageBitmap(): Promise<ImageBitmap>;
+    toImageValue(previewScale: number): Promise<ImageValue>;
+    /** Encode the image to a compressed format. Single-use: the underlying
+     *  texture is disposed during encoding (via `transferToImageBitmap`); a
+     *  second call on the same instance throws. */
     encode(format: GpuImageEncodeFormat, quality?: number): Promise<Uint8Array>;
-    retain(n?: number): this;
-    release(): void;
+    dispose(): void;
 }
 //# sourceMappingURL=webGpuImage.browser.d.ts.map

package/dist/media/webGpuImage.browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webGpuImage.browser.d.ts","sourceRoot":"","sources":["../../src/media/webGpuImage.browser.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,KAAK,EAAE,QAAQ,IAAI,SAAS,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAa9E,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,WAAW,GAAG,SAAS,CAAC;IAClC,OAAO,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C;AA6BD,qBAAa,WAAY,YAAW,SAAS;IAUzC,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,OAAO;IACf,QAAQ,CAAC,KAAK,EAAE,MAAM;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM;IAZzB,QAAQ,CAAC,OAAO,EAAG,QAAQ,CAAU;IACrC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAK;IAErC,kFAAkF;IAClF,OAAO,CAAC,QAAQ,CAAK;IAErB,OAAO,CAAC,aAAa,CAAS;IAE9B,OAAO,eAeN;IAED,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED;;kDAE8C;IAC9C,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAGpC;IAED,OAAa,eAAe,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAYnE;IAED,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,CAkDtC;IAEK,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,CA4BxC;IAEK,QAAQ,CAAC,MAAM,EAAE,iBAAiB,GAAG,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAkCzE;IAEK,MAAM,CAAC,MAAM,EAAE,oBAAoB,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAWhF;IAED,MAAM,CAAC,CAAC,GAAE,MAAU,GAAG,IAAI,CAM1B;IAED,OAAO,IAAI,IAAI,CAYd;CACF"}
+{"version":3,"file":"webGpuImage.browser.d.ts","sourceRoot":"","sources":["../../src/media/webGpuImage.browser.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,QAAQ,IAAI,SAAS,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAE9E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAQ/C,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,WAAW,GAAG,SAAS,CAAC;IAClC,OAAO,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C;AAED,qBAAa,WAAY,YAAW,SAAS;IAKzC,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,OAAO;IACf,QAAQ,CAAC,KAAK,EAAE,MAAM;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM;IAPzB,QAAQ,CAAC,OAAO,EAAG,QAAQ,CAAU;IACrC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAK;IAErC,OAAO,eAKH;IAEJ,OAAa,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAiBzD;IAED,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,CA4CtC;IAED;gEAC4D;IACtD,qBAAqB,IAAI,OAAO,CAAC,WAAW,CAAC,CA0ClD;IAEK,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAG5D;IAED;;mDAE+C;IACzC,MAAM,CAAC,MAAM,EAAE,oBAAoB,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAShF;IAED,OAAO,IAAI,IAAI,CASd;CACF"}

package/dist/media-browser.d.ts

@@ -7,15 +7,18 @@ import "./media/imageCacheCodec";
 import "./media/imageHydrationResolver";
 export * from "./media/color";
 export { CpuImage } from "./media/cpuImage";
-export { encodeImageBinaryToPng, imageBinaryToBase64Png, imageBinaryToBlob, imageBinaryToDataUri, } from "./media/encode";
+export { rawPixelBufferToBlob, rawPixelBufferToDataUri } from "./media/encode";
 export { _resetFilterRegistryForTests, applyFilter, hasFilterOp, registerFilterOp, } from "./media/filterRegistry";
 export type { FilterOpFn } from "./media/filterRegistry";
 export { getGpuDevice, resetGpuDeviceForTests } from "./media/gpuDevice.browser";
 export { getGpuImageFactory, GpuImage as GpuImageFactory, registerGpuImageFactory, } from "./media/gpuImage";
 export type { GpuImage, GpuImageBackend, GpuImageEncodeFormat, GpuImageStatic, } from "./media/gpuImage";
-export { GpuImageSchema } from "./media/gpuImageSchema";
+export { ImageValueSchema } from "./media/imageValueSchema";
 export * from "./media/imageRasterCodecRegistry";
-export * from "./media/imageTypes";
+export type { ImageChannels } from "./media/imageTypes";
+export type { RawPixelBuffer, RgbaPixelBuffer } from "./media/rawPixelBuffer";
+export { imageValueFromBitmap, imageValueFromBuffer, isBrowserImageValue, isImageValue, isNodeImageValue, normalizeToImageValue, } from "./media/imageValue";
+export type { BrowserImageValue, ImageValue, ImageValueBase, NodeImageFormat, NodeImageValue, } from "./media/imageValue";
 export * from "./media/MediaRawImage";
 export { getPreviewBudget, previewSource, registerPreviewResizeFn, setPreviewBudget, } from "./media/previewBudget";
 export { createShaderCache, getShaderCache, PASSTHROUGH_SHADER_SRC, VERTEX_PRELUDE, } from "./media/shaderRegistry.browser";
@@ -24,4 +27,7 @@ export { createTexturePool, getTexturePool, resetTexturePoolForTests, } from "./
 export type { TexturePool, TexturePoolOptions } from "./media/texturePool.browser";
 export { WebGpuImage } from "./media/webGpuImage.browser";
 export type { ApplyParams } from "./media/webGpuImage.browser";
+export declare function probeImageDimensions(): Promise<never>;
+export declare function decodeBufferToRaw(): Promise<never>;
+export declare function encodeRawPixels(): Promise<never>;
 //# sourceMappingURL=media-browser.d.ts.map

package/dist/media-browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"media-browser.d.ts","sourceRoot":"","sources":["../src/media-browser.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,yBAAyB,CAAC;AACjC,OAAO,gCAAgC,CAAC;AAExC,cAAc,eAAe,CAAC;AAC9B,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,4BAA4B,EAC5B,WAAW,EACX,WAAW,EACX,gBAAgB,GACjB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACjF,OAAO,EACL,kBAAkB,EAClB,QAAQ,IAAI,eAAe,EAC3B,uBAAuB,GACxB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,QAAQ,EACR,eAAe,EACf,oBAAoB,EACpB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,cAAc,kCAAkC,CAAC;AACjD,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,sBAAsB,EACtB,cAAc,GACf,MAAM,gCAAgC,CAAC;AACxC,YAAY,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,wBAAwB,GACzB,MAAM,6BAA6B,CAAC;AACrC,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACnF,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,YAAY,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC"}
+{"version":3,"file":"media-browser.d.ts","sourceRoot":"","sources":["../src/media-browser.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,yBAAyB,CAAC;AACjC,OAAO,gCAAgC,CAAC;AAExC,cAAc,eAAe,CAAC;AAC9B,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAC/E,OAAO,EACL,4BAA4B,EAC5B,WAAW,EACX,WAAW,EACX,gBAAgB,GACjB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACjF,OAAO,EACL,kBAAkB,EAClB,QAAQ,IAAI,eAAe,EAC3B,uBAAuB,GACxB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,QAAQ,EACR,eAAe,EACf,oBAAoB,EACpB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,cAAc,kCAAkC,CAAC;AACjD,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9E,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,iBAAiB,EACjB,UAAU,EACV,cAAc,EACd,eAAe,EACf,cAAc,GACf,MAAM,oBAAoB,CAAC;AAC5B,cAAc,uBAAuB,CAAC;AACtC,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,sBAAsB,EACtB,cAAc,GACf,MAAM,gCAAgC,CAAC;AACxC,YAAY,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,wBAAwB,GACzB,MAAM,6BAA6B,CAAC;AACrC,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACnF,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,YAAY,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAO/D,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,KAAK,CAAC,CAE3D;AACD,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,KAAK,CAAC,CAExD;AACD,wBAAsB,eAAe,IAAI,OAAO,CAAC,KAAK,CAAC,CAEtD"}