@workglow/util 0.2.14 → 0.2.15

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

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Browser-only augmentation of {@link Image}. Adds `getImageData`,
+ * `getImageBitmap`, `getVideoFrame`, `getOffscreenCanvas`, and a private
+ * helper `toFirstSupportedBrowser` consulted by the base `toFirstSupported`.
+ */
+declare module "./Image" {
+    interface Image {
+        getImageData(): Promise<ImageData>;
+        getImageBitmap(): Promise<ImageBitmap>;
+        getVideoFrame(): Promise<VideoFrame>;
+        getOffscreenCanvas(): Promise<OffscreenCanvas>;
+    }
+    namespace Image {
+        function fromBitmap(bitmap: ImageBitmap): Image;
+        function fromVideoFrame(frame: VideoFrame): Image;
+        function fromOffscreenCanvas(canvas: OffscreenCanvas): Image;
+    }
+}
+export {};
+//# sourceMappingURL=Image.browser.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Image.browser.d.ts","sourceRoot":"","sources":["../../src/media/Image.browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,QAAQ,SAAS,CAAC,CAAC;IACxB,UAAU,KAAK;QACb,YAAY,IAAI,OAAO,CAAC,SAAS,CAAC,CAAC;QACnC,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC;QACvC,aAAa,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;QACrC,kBAAkB,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC;KAChD;IACD,UAAU,KAAK,CAAC,CAAC;QACf,SAAS,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK,CAAC;QAChD,SAAS,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,KAAK,CAAC;QAClD,SAAS,mBAAmB,CAAC,MAAM,EAAE,eAAe,GAAG,KAAK,CAAC;KAC9D;CACF"}

package/dist/media/Image.d.ts

@@ -0,0 +1,100 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ImageBinary, ImageChannels, ImageDataSupport } from "./imageTypes";
+import { MediaRawImage, isMediaRawImageShape } from "./MediaRawImage";
+/**
+ * Legacy wire format: either a raw `data:image/...;base64,...` URI or a
+ * serialized {@link ImageBinary} with `data` as a plain number array
+ * (`Array.from(Uint8ClampedArray)`) to avoid the indexed-object pitfall
+ * when stringified through `JSON.stringify`.
+ */
+export type ImageJson = string | {
+    readonly data: readonly number[];
+    readonly width: number;
+    readonly height: number;
+    readonly channels: ImageChannels;
+} | {
+    readonly unsynced: true;
+    readonly kind: ImageSourceKind;
+};
+export type ImageSourceKind = "dataUri" | "pixels" | "blob" | "bitmap" | "videoFrame" | "offscreenCanvas";
+type ImageSource = {
+    readonly kind: "dataUri";
+    readonly dataUri: string;
+    readonly mimeType: string;
+} | {
+    readonly kind: "pixels";
+    readonly pixels: ImageBinary;
+} | {
+    readonly kind: "blob";
+    readonly blob: Blob;
+} | {
+    readonly kind: "bitmap";
+    readonly bitmap: ImageBitmap;
+} | {
+    readonly kind: "videoFrame";
+    readonly frame: VideoFrame;
+} | {
+    readonly kind: "offscreenCanvas";
+    readonly canvas: OffscreenCanvas;
+};
+declare const IMAGE_BRAND: unique symbol;
+export declare function dataUriToBlob(dataUri: string): Blob;
+/**
+ * Unified image representation: holds a single source (dataUri, pixels, blob,
+ * bitmap, video frame, or offscreen canvas) and converts on demand.
+ *
+ * - `toJSON()` normalizes to `{ kind, ... }`; no `Uint8ClampedArray` indexed-
+ *   object serialization pitfall.
+ * - `fromJSON()` accepts the new discriminated shape **and** legacy shapes
+ *   (raw data URI, raw `ImageBinary`, indexed-object `data`) for migration.
+ * - `toFirstSupported(supports[])` replaces `convertImageDataToUseableForm`.
+ */
+export declare class Image {
+    /** @internal brand so `Image.is` works across realms. */
+    readonly [IMAGE_BRAND]: true;
+    private source;
+    private pixelsCache;
+    private dataUriCache;
+    private blobCache;
+    private constructor();
+    static fromDataUri(dataUri: string): Image;
+    static fromPixels(pixels: ImageBinary): Image;
+    static fromBlob(blob: Blob): Image;
+    /** Accepts anything `convertImageDataToUseableForm` accepted today, plus `Image`. */
+    static from(value: unknown): Image;
+    static is(value: unknown): value is Image;
+    /**
+     * Reconstruct an {@link Image} from its serialized form. Accepts a raw
+     * `data:` URI string, a pixel-backed object `{data,width,height,channels}`
+     * (with `data` as typed array, plain array, or the indexed-object pitfall
+     * produced by `JSON.stringify(Uint8ClampedArray)`), or an `Image` instance.
+     */
+    static fromJSON(value: unknown): Image;
+    get kind(): ImageSourceKind;
+    get mimeType(): string | undefined;
+    get width(): number | undefined;
+    get height(): number | undefined;
+    get channels(): ImageChannels | undefined;
+    getPixels(): Promise<ImageBinary>;
+    getDataUri(mimeType?: string): Promise<string>;
+    getBlob(mimeType?: string): Promise<Blob>;
+    /**
+     * Return the first representation in `supports` that can be produced on
+     * this platform. Mirrors the list-order semantics of the former
+     * `convertImageDataToUseableForm`: earlier entries win.
+     */
+    toFirstSupported(supports: readonly ImageDataSupport[]): Promise<unknown>;
+    toJSON(): ImageJson;
+    private canonicalSupport;
+    /** @internal */
+    getSource(): ImageSource;
+    /** @internal */
+    setPixelsCache(pixels: ImageBinary): void;
+    private currentSourceValue;
+}
+export { MediaRawImage, isMediaRawImageShape };
+//# sourceMappingURL=Image.d.ts.map

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

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

package/dist/media/MediaRawImage.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Structural match for `RawImage` from `@huggingface/transformers`. The HF
+ * class carries helpers (`save`, `toCanvas`, `rgb`, ...) that the provider
+ * runtime does not invoke on inputs, so a minimal shim over the four data
+ * fields is sufficient. If a consumer later needs HF-specific methods we can
+ * widen this shim lazily — no need to pull the transformers dep into
+ * `@workglow/util/media` today.
+ */
+export declare class MediaRawImage {
+    readonly data: Uint8ClampedArray;
+    readonly width: number;
+    readonly height: number;
+    readonly channels: number;
+    constructor(data: Uint8ClampedArray, width: number, height: number, channels: number);
+}
+export declare function isMediaRawImageShape(value: unknown): value is {
+    data: Uint8ClampedArray;
+    width: number;
+    height: number;
+    channels: number;
+};
+//# sourceMappingURL=MediaRawImage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MediaRawImage.d.ts","sourceRoot":"","sources":["../../src/media/MediaRawImage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;GAOG;AACH,qBAAa,aAAa;IACxB,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,YAAY,IAAI,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAKnF;CACF;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CASvF"}

package/dist/media/color.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export interface ColorObject {
+    readonly r: number;
+    readonly g: number;
+    readonly b: number;
+    readonly a: number;
+}
+/**
+ * Parse a `#RGB` / `#RGBA` / `#RRGGBB` / `#RRGGBBAA` hex color into a {@link ColorObject}.
+ * Case-insensitive on input. No whitespace tolerance. Shorthand nibbles are doubled.
+ * Throws on any malformed input.
+ */
+export declare function parseHexColor(hex: string): ColorObject;
+/**
+ * Emit a {@link ColorObject} as `#RRGGBB` when `a === 255`, otherwise `#RRGGBBAA`.
+ * Always lowercase, never shorthand. Throws on non-integer or out-of-range channels.
+ */
+export declare function toHexColor(c: ColorObject): string;
+/**
+ * Type guard for a {@link ColorObject}-shaped value (alpha optional).
+ * Does not reject extra properties — JSON Schema validation handles that separately.
+ */
+export declare function isColorObject(value: unknown): value is ColorObject;
+/** Type guard for a hex color string (same regex as `parseHexColor`). */
+export declare function isHexColor(value: unknown): value is string;
+/**
+ * Normalize either wire form to a full {@link ColorObject}. Object inputs default
+ * `a` to 255. Throws on anything that's neither a valid hex string nor a valid
+ * color object.
+ */
+export declare function resolveColor(value: string | {
+    r: number;
+    g: number;
+    b: number;
+    a?: number;
+}): ColorObject;
+//# sourceMappingURL=color.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"color.d.ts","sourceRoot":"","sources":["../../src/media/color.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAID;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CA+BtD;AAeD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,WAAW,GAAG,MAAM,CAOjD;AAMD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAQlE;AAED,yEAAyE;AACzE,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE1D;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9D,WAAW,CAWb"}

package/dist/media/imageRasterCodecRegistry.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ImageBinary } from "./imageTypes";
+export interface ImageRasterCodec {
+    decodeDataUri(dataUri: string): Promise<ImageBinary>;
+    encodeDataUri(image: ImageBinary, mimeType: string): Promise<string>;
+}
+export declare function registerImageRasterCodec(next: ImageRasterCodec): void;
+export declare function getImageRasterCodec(): ImageRasterCodec;
+//# sourceMappingURL=imageRasterCodecRegistry.d.ts.map

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

@@ -0,0 +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;AAID,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAErE;AAED,wBAAgB,mBAAmB,IAAI,gBAAgB,CAOtD"}

package/dist/media/{image.d.ts → imageTypes.d.ts}

@@ -12,8 +12,12 @@ export interface ImageBinary {
     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=image.d.ts.map
+//# sourceMappingURL=imageTypes.d.ts.map

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

@@ -0,0 +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"}

package/dist/media-browser.d.ts

@@ -3,6 +3,10 @@
  * Copyright 2025 Steven Roussey <sroussey@gmail.com>
  * SPDX-License-Identifier: Apache-2.0
  */
-export * from "./media/image";
-export * from "./media/image.browser";
+export * from "./media/imageTypes";
+export * from "./media/color";
+export * from "./media/imageRasterCodecRegistry";
+export * from "./media/MediaRawImage";
+export * from "./media/Image";
+export * from "./media/Image.browser";
 //# 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,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"media-browser.d.ts","sourceRoot":"","sources":["../src/media-browser.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,kCAAkC,CAAC;AACjD,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC"}