pixel-data-js 0.3.0 → 0.5.0

package/dist/index.prod.d.ts

@@ -19,7 +19,7 @@ type BlendColor32 = (src: Color32, dst: Color32) => Color32;
 type ImageDataLike = {
     width: number;
     height: number;
-    data: Uint8ClampedArray<ArrayBuffer>;
+    data: Uint8ClampedArray<ArrayBufferLike>;
 };
 type SerializedImageData = {
     width: number;
@@ -67,23 +67,23 @@ type AnyMask = BinaryMask | AlphaMask;
 interface PixelOptions {
     /**
      * The starting X coordinate in the destination buffer.
-     * @Defaults 0.
-     * */
+     * @default 0
+     */
     x?: number;
     /**
      * The starting Y coordinate in the destination buffer.
-     * @Default 0.
-     * */
+     * @default 0
+     */
     y?: number;
     /**
      * The width of the region to process.
-     * @Default Source width.
-     * */
+     * @default Source width.
+     */
     w?: number;
     /**
      * The height of the region to process.
-     * @Default Source height.
-     * */
+     * @default Source height.
+     */
     h?: number;
     /**
      * Overall layer opacity 0-255.
@@ -92,24 +92,29 @@ interface PixelOptions {
     alpha?: number;
     /**
      * Mask width.
-     * @default w
-     * */
+     * @default value of `w`
+     */
     mw?: number;
     /**
      * X offset into the mask buffer.
      * @default 0
-     * */
+     */
     mx?: number;
     /**
      * Y offset into the mask buffer.
      * @default 0
-     * */
+     */
     my?: number;
     /** An optional mask to restrict where pixels are written. */
     mask?: AnyMask | null;
-    /** The interpretation logic for the provided mask. Defaults to MaskType.Binary. */
+    /** The interpretation logic for the provided mask.
+     * @default {@link MaskType.BINARY}
+     */
     maskType?: MaskType;
-    /** If true the inverse of the mask will be applied */
+    /**
+     * If true the inverse of the mask will be applied
+     * @default false
+     */
     invertMask?: boolean;
 }
 /**
@@ -126,63 +131,114 @@ interface PixelBlendOptions extends PixelOptions {
      * @default 0
      */
     sy?: number;
-    /** The specific blending function/algorithm to use for pixel math. */
+    /**
+     * The blending algorithm to use for blending pixels.
+     * @default {@link sourceOverColor32}
+     */
     blendFn?: BlendColor32;
 }
 /**
  * Configuration for operations that require color blending.
  */
 interface ColorBlendOptions extends PixelOptions {
-    /** The blending logic used to combine source and destination pixels. */
+    /**
+     * The blending algorithm to use for blending pixels.
+     * @default {@link sourceOverColor32}
+     */
     blendFn?: BlendColor32;
 }
 type ApplyMaskOptions = Omit<PixelOptions, 'mask'>;
+type SelectionRect = Rect & ({
+    mask: Uint8Array;
+    maskType: MaskType;
+} | {
+    mask?: null;
+    maskType?: null;
+});
 
+declare const overwriteColor32: BlendColor32;
 declare const sourceOverColor32: BlendColor32;
+/** Math.min(src, dst) */
+declare const darkenColor32: BlendColor32;
+/** (src * dst) / 255 */
+declare const multiplyColor32: BlendColor32;
+/** 255 - (255-src)/dst */
+declare const colorBurnColor32: BlendColor32;
+/** src + dst - 255 */
+declare const linearBurnColor32: BlendColor32;
+declare const darkerColor32: BlendColor32;
+/** Math.max(src, dst) */
+declare const lightenColor32: BlendColor32;
 /**
- * Screen: Lightens the destination (inverse of Multiply).
- * Result = 1 - ((1 - Src) * (1 - Dst))
+ * 255 - ((255 - src) * (255 - dst))
  */
 declare const screenColor32: BlendColor32;
-/**
- * Linear Dodge (Additive): Simply adds the source to the destination.
- * Clamps at 255.
- */
+/** src === 255 ? 255 : Math.min(255, (dst << 8) / (255 - src)) */
+declare const colorDodgeColor32: BlendColor32;
+/** src + dst */
 declare const linearDodgeColor32: BlendColor32;
-/**
- * Multiply: Darkens the destination based on the source color.
- * Result = (Src * Dst) / 255
- */
-declare const multiplyColor32: BlendColor32;
-/**
- * Difference: Subtracts the darker color from the lighter color.
- * Result = |Src - Dst|
- */
-declare const differenceColor32: BlendColor32;
-/**
- * Hard Light: Decides Multiply vs Screen based on SOURCE brightness.
- * Acts like a harsh spotlight.
- */
+declare const lighterColor32: BlendColor32;
+/** src < 128 ? (2 * src * dst) : (255 - 2 * (255 - src) * (255 - dst)) */
+declare const overlayColor32: BlendColor32;
+/**  ((255 - dst) * ((src * dst) >> 8) + dst * (255 - (((255 - src) * (255 - dst)) >> 8))) >> 8 */
+declare const softLightColor32: BlendColor32;
+/** If src < 128 (50% gray), Multiply; otherwise, Screen */
 declare const hardLightColor32: BlendColor32;
 /**
- * Color Burn: Darkens the destination to reflect the source color.
- * Intense saturation in the darks.
- */
-declare const colorBurnColor32: BlendColor32;
-/**
- * Overlay: The classic "Contrast" mode.
- * Decides Multiply vs Screen based on DESTINATION brightness.
+ * If src < 128: Burn(dst, 2 * src)
+ * If src >= 128: Dodge(dst, 2 * (src - 128))
  */
-declare const overlayColor32: BlendColor32;
-declare const COLOR_32_BLEND_MODES: {
-    sourceOver: BlendColor32;
-    screen: BlendColor32;
-    linearDodge: BlendColor32;
-    multiply: BlendColor32;
-    difference: BlendColor32;
-    overlay: BlendColor32;
-    hardLight: BlendColor32;
-    colorBurn: BlendColor32;
+declare const vividLightColor32: BlendColor32;
+/** dst + 2 * src - 255 (Clamped to 0-255) */
+declare const linearLightColor32: BlendColor32;
+/** src < 128 ? min(dst, 2 * src) : max(dst, 2 * (src - 128)) */
+declare const pinLightColor32: BlendColor32;
+/** (Vivid Light logic forced to 0 or 255) */
+declare const hardMixColor32: BlendColor32;
+/** Math.abs(src - dst) */
+declare const differenceColor32: BlendColor32;
+/** dst + src - ((dst * src) >> 7) */
+declare const exclusionColor32: BlendColor32;
+/** Math.max(0, dst - src) */
+declare const subtractColor32: BlendColor32;
+/** sr === 0 ? 255 : Math.min(255, (dr << 8) / sr) */
+declare const divideColor32: BlendColor32;
+declare enum BlendMode {
+    overwrite = 0,
+    sourceOver = 1,
+    darken = 2,
+    multiply = 3,
+    colorBurn = 4,
+    linearBurn = 5,
+    darkerColor = 6,
+    lighten = 7,
+    screen = 8,
+    colorDodge = 9,
+    linearDodge = 10,
+    lighterColor = 11,
+    overlay = 12,
+    softLight = 13,
+    hardLight = 14,
+    vividLight = 15,
+    linearLight = 16,
+    pinLight = 17,
+    hardMix = 18,
+    difference = 19,
+    exclusion = 20,
+    subtract = 21,
+    divide = 22
+}
+declare const BLENDER_REGISTRY: readonly [readonly [BlendMode.overwrite, BlendColor32], readonly [BlendMode.sourceOver, BlendColor32], readonly [BlendMode.darken, BlendColor32], readonly [BlendMode.multiply, BlendColor32], readonly [BlendMode.colorBurn, BlendColor32], readonly [BlendMode.linearBurn, BlendColor32], readonly [BlendMode.darkerColor, BlendColor32], readonly [BlendMode.lighten, BlendColor32], readonly [BlendMode.screen, BlendColor32], readonly [BlendMode.colorDodge, BlendColor32], readonly [BlendMode.linearDodge, BlendColor32], readonly [BlendMode.lighterColor, BlendColor32], readonly [BlendMode.overlay, BlendColor32], readonly [BlendMode.softLight, BlendColor32], readonly [BlendMode.hardLight, BlendColor32], readonly [BlendMode.vividLight, BlendColor32], readonly [BlendMode.linearLight, BlendColor32], readonly [BlendMode.pinLight, BlendColor32], readonly [BlendMode.hardMix, BlendColor32], readonly [BlendMode.difference, BlendColor32], readonly [BlendMode.exclusion, BlendColor32], readonly [BlendMode.subtract, BlendColor32], readonly [BlendMode.divide, BlendColor32]];
+type RegisteredBlender = typeof BLENDER_REGISTRY[number][1];
+type BlendModeIndex = number & {
+    readonly __brandBlendModeIndex: unique symbol;
+};
+declare const COLOR_32_BLEND_MODES: BlendColor32[];
+declare const COLOR_32_BLEND_TO_INDEX: {
+    get: (blend: RegisteredBlender) => BlendModeIndex;
+};
+declare const INDEX_TO_COLOR_32_BLEND: {
+    get: (index: BlendModeIndex) => RegisteredBlender;
 };
 
 /**
@@ -213,7 +269,7 @@ declare function lerpColor32(a: Color32, b: Color32, t: number): Color32;
  * Linearly interpolates between two 32-bit colors using integer fixed-point math.
  * Highly optimized for image processing and real-time blitting. It processes
  * channels in parallel using bitmasks (RB and GA pairs).
- * @note Subject to a 1-bit drift (rounding down) due to fast bit-shift division.
+ * **Note:** Subject to a 1-bit drift (rounding down) due to fast bit-shift division.
  * @param src - The source (foreground) color as a 32-bit integer.
  * @param dst - The destination (background) color as a 32-bit integer.
  * @param w - The blend weight as a byte value from 0 to 255. Where 0 is 100% dst and 255 is 100% src
@@ -226,11 +282,268 @@ declare function color32ToHex(color: Color32): string;
  */
 declare function color32ToCssRGBA(color: Color32): string;
 
+declare class PixelData {
+    readonly imageData: ImageDataLike;
+    readonly data32: Uint32Array;
+    readonly width: number;
+    readonly height: number;
+    constructor(imageData: ImageDataLike);
+}
+
+type FloodFillImageDataOptions = {
+    contiguous?: boolean;
+    tolerance?: number;
+    bounds?: Rect;
+};
+type FloodFillResult = {
+    startX: number;
+    startY: number;
+    selectionRect: SelectionRect;
+    pixels: Uint8ClampedArray;
+};
+/**
+ * Performs a color-based flood fill selection on {@link ImageData} or {@link PixelData}.
+ * This utility identifies pixels starting from a specific coordinate that fall within a
+ * color tolerance. It can operate in "contiguous" mode (classic bucket fill) or
+ * "non-contiguous" mode (selects all matching pixels in the buffer).
+ *
+ * @param img - The source image data to process.
+ * @param startX - The starting horizontal coordinate.
+ * @param startY - The starting vertical coordinate.
+ * @param options - Configuration for the fill operation.
+ * @param options.contiguous - @default true. If true, only connected pixels are
+ * selected. If false, all pixels within tolerance are selected regardless of position.
+ * @param options.tolerance - @default 0. The maximum allowed difference in color
+ * distance (0-255) for a pixel to be included.
+ * @param options.bounds - Optional bounding box to restrict the search area.
+ *
+ * @returns A {@link FloodFillResult} containing the mask and bounds of the selection,
+ * or `null` if the starting coordinates are out of bounds.
+ *
+ * @example
+ * ```typescript
+ * const result = floodFillImageDataSelection(
+ * ctx.getImageData(0, 0, 100, 100),
+ * 50,
+ * 50,
+ * {
+ * tolerance: 20,
+ * contiguous: true
+ * }
+ * );
+ * ```
+ */
+declare function floodFillSelection(img: ImageDataLike | PixelData, startX: number, startY: number, { contiguous, tolerance, bounds, }?: FloodFillImageDataOptions): FloodFillResult | null;
+
+type PixelCanvas = {
+    readonly canvas: HTMLCanvasElement;
+    readonly ctx: CanvasRenderingContext2D;
+    readonly resize: (w: number, h: number) => void;
+};
+/**
+ * Ensures the canvas ctx is always set to imageSmoothingEnabled = false.
+ * Intended for canvas elements that are already part of the DOM.
+ * @see makeReusableCanvas
+ * @throws {Error} If the {@link HTMLCanvasElement} context cannot be initialized.
+ */
+declare function makePixelCanvas(canvas: HTMLCanvasElement): PixelCanvas;
+
+type ReusableCanvas = {
+    readonly canvas: HTMLCanvasElement;
+    readonly ctx: CanvasRenderingContext2D;
+};
+/**
+ * Creates a reusable canvas and context that are not part of the DOM.
+ * Ensures it is always set to `context.imageSmoothingEnabled = false`
+ * @see makePixelCanvas
+ * @throws {Error} If the {@link HTMLCanvasElement} context cannot be initialized.
+ */
+declare function makeReusableCanvas(): {
+    (width: number, height: number): ReusableCanvas;
+    reset(): void;
+};
+
+/**
+ * Extracts {@link ImageData} from a clipboard event if an image is present.
+ *
+ * This function iterates through the {@link DataTransferItemList} to find
+ * the first item with an image MIME type and decodes it.
+ *
+ * @param clipboardEvent - The event object from a `paste` listener.
+ *
+ * @returns A promise resolving to {@link ImageData}, or `null` if no
+ * image was found in the clipboard.
+ *
+ * @example
+ * ```typescript
+ * window.addEventListener('paste', async (event) => {
+ *   const data = await getImageDataFromClipboard(event)
+ *   if (data) {
+ *     console.log('Pasted image dimensions:', data.width, data.height)
+ *   }
+ * });
+ * ```
+ */
+declare function getImageDataFromClipboard(clipboardEvent: ClipboardEvent): Promise<ImageData | null>;
+
+/**
+ * Converts {@link ImageData} to a PNG {@link Blob} and writes it to the system clipboard.
+ * This is a high-level utility that combines {@link imageDataToImgBlob} and
+ * {@link writeImgBlobToClipboard}.
+ * @param imageData - The image data to copy to the clipboard.
+ * @returns A promise that resolves when the image has been successfully copied.
+ * @throws {Error}
+ * If the conversion to blob fails or clipboard permissions are denied.
+ *
+ * @example
+ * ```typescript
+ * const canvas = document.querySelector('canvas')
+ * const ctx = canvas.getContext('2d')
+ * const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height)
+ * await writeImageDataToClipboard(imageData)
+ * ```
+ */
+declare function writeImageDataToClipboard(imageData: ImageData): Promise<void>;
+
+/**
+ * Writes a {@link Blob} image to the system clipboard.
+ *
+ * @param blob - The image {@link Blob} (typically `image/png`) to copy.
+ * @returns A promise that resolves when the clipboard has been updated.
+ */
+declare function writeImgBlobToClipboard(blob: Blob): Promise<void>;
+
 declare function copyImageData({ data, width, height }: ImageDataLike): ImageData;
 declare function copyImageDataLike({ data, width, height }: ImageDataLike): ImageDataLike;
 
-declare function extractImageData(imageData: ImageDataLike, rect: Rect): Uint8ClampedArray;
-declare function extractImageData(imageData: ImageDataLike, x: number, y: number, w: number, h: number): Uint8ClampedArray;
+/**
+ * Extracts a specific rectangular region of pixels from a larger {@link ImageDataLike}
+ * source into a new {@link Uint8ClampedArray}.
+ *
+ * This is a "read-only" operation that returns a copy of the pixel data.
+ *
+ * @param imageData - The source image data to read from.
+ * @param rect - A {@link Rect} object defining the region to extract.
+ * @returns A {@link Uint8ClampedArray} containing the RGBA pixel data of the region.
+ */
+declare function extractImageDataPixels(imageData: ImageDataLike, rect: Rect): Uint8ClampedArray;
+/**
+ * @param imageData - The source image data to read from.
+ * @param x - The starting horizontal coordinate.
+ * @param y - The starting vertical coordinate.
+ * @param w - The width of the region to extract.
+ * @param h - The height of the region to extract.
+ * @returns A {@link Uint8ClampedArray} containing the RGBA pixel data of the region.
+ */
+declare function extractImageDataPixels(imageData: ImageDataLike, x: number, y: number, w: number, h: number): Uint8ClampedArray;
+
+/**
+ * Extracts the alpha channel from raw ImageData into an AlphaMask.
+ * When possible use {@link pixelDataToAlphaMask} instead.
+ * Repeat calls to the same data will use less memory.
+ */
+declare function imageDataToAlphaMask(imageData: ImageData): AlphaMask;
+
+/**
+ * Converts an {@link ImageData} object into a base64-encoded Data URL string.
+ *
+ * @param imageData - The pixel data to be converted.
+ *
+ * @returns A string representing the image in `image/png` format as a
+ * [Data URL](https://developer.mozilla.org/en-US/docs/Web/URI/Reference/Schemes/data).
+ * @throws {Error} If the {@link HTMLCanvasElement} context cannot be initialized.
+ * @example
+ * ```typescript
+ * const dataUrl = imageDataToDataUrl(imageData);
+ * const img = new Image();
+ * img.src = dataUrl;
+ * ```
+ */
+declare function imageDataToDataUrl(imageData: ImageData): string;
+declare namespace imageDataToDataUrl {
+    var reset: () => void;
+}
+
+/**
+ * Converts an {@link ImageData} object into a {@link Blob} in PNG format.
+ *
+ * This operation is asynchronous and uses {@link OffscreenCanvas}
+ * to perform the encoding, making it suitable for usage in both the main
+ * thread and Web Workers.
+ *
+ * @param imageData - The pixel data to be encoded.
+ *
+ * @returns A promise that resolves to a {@link Blob} with the MIME type `image/png`.
+ *
+ * @throws {Error}
+ * Thrown if the {@link OffscreenCanvas} context cannot be initialized or the blob
+ * encoding fails.
+ *
+ * @example
+ * ```typescript
+ * const blob = await imageDataToImgBlob(imageData);
+ * const url = URL.createObjectURL(blob);
+ * ```
+ */
+declare function imageDataToImgBlob(imageData: ImageData): Promise<Blob>;
+
+/**
+ * Decodes a {@link Blob} (typically PNG) back into an {@link ImageData} object.
+ *
+ * This function uses hardware-accelerated decoding via {@link createImageBitmap}
+ * and processes the data using an {@link OffscreenCanvas} to ensure
+ * compatibility with Web Workers.
+ *
+ * @param blob - The binary image data to decode.
+ *
+ * @returns A promise resolving to the decoded {@link ImageData}.
+ *
+ * @throws {Error}
+ * Thrown if the blob is corrupted or the browser cannot decode the format.
+ *
+ * @example
+ * ```typescript
+ * const blob = await getBlobFromStorage();
+ *
+ * const imageData = await pngBlobToImageData(blob);
+ * ```
+ */
+declare function imgBlobToImageData(blob: Blob): Promise<ImageData>;
+
+declare function invertImageData(imageData: ImageData): ImageData;
+
+/**
+ * Non destructively resizes the {@link ImageData} buffer to new dimensions, optionally
+ * offsetting the original content.
+ * This operation creates a new buffer. It does not scale or stretch pixels;
+ * instead, it crops or pads the image based on the new dimensions and
+ * provides an offset for repositioning.
+ *
+ * @param current The source {@link ImageData} to resize.
+ * @param newWidth The target width in pixels.
+ * @param newHeight The target height in pixels.
+ * @param offsetX The horizontal offset for placing the
+ * original image within the new buffer.
+ * @default 0
+ * @param offsetY The vertical offset for placing the
+ * original image within the new buffer.
+ * @default 0
+ *
+ * @returns A new {@link ImageData} instance with the specified dimensions.
+ *
+ * @example
+ * ```typescript
+ * // Centers an 80x80 image in a new 100x100 buffer
+ * const resized = resizeImageData(
+ *   originalData,
+ *   100,
+ *   100,
+ *   10,
+ *   10
+ * );
+ * ```
+ */
+declare function resizeImageData(current: ImageData, newWidth: number, newHeight: number, offsetX?: number, offsetY?: number): ImageData;
 
 declare function base64EncodeArrayBuffer(buffer: ArrayBufferLike): Base64EncodedUInt8Array;
 declare function base64DecodeArrayBuffer(encoded: Base64EncodedUInt8Array): Uint8ClampedArray<ArrayBuffer>;
@@ -243,13 +556,168 @@ declare function deserializeRawImageData<T extends SerializedImageData>(serializ
 declare function deserializeImageData<T extends SerializedImageData>(serialized: T): ImageData;
 declare function deserializeNullableImageData<T extends SerializedImageData | null>(serialized: T): T extends null ? null : ImageData;
 
-declare class PixelData {
-    readonly imageData: ImageDataLike;
-    readonly data32: Uint32Array;
-    readonly width: number;
-    readonly height: number;
-    constructor(imageData: ImageDataLike);
+/**
+ * Copies a pixel buffer into a specific region of an {@link ImageData} object.
+ *
+ * This function performs a direct memory copy from a {@link Uint8ClampedArray}
+ * into the target {@link ImageData} buffer. It supports both {@link Rect}
+ * objects and discrete coordinates.
+ *
+ * @param imageData - The target {@link ImageData} to write into. Must match the rect width/height.
+ * @param data - The source pixel data (RGBA).
+ * @param rect - A {@link Rect} object defining the destination region.
+ */
+declare function writeImageDataPixels(imageData: ImageData, data: Uint8ClampedArray, rect: Rect): void;
+/**
+ * @param imageData - The target {@link ImageData} to write into.
+ * @param data - The source pixel data (RGBA). Must match the width/height.
+ * @param x - The starting horizontal coordinate in the target.
+ * @param y - The starting vertical coordinate in the target.
+ * @param w - The width of the region to write.
+ * @param h - The height of the region to write.
+ */
+declare function writeImageDataPixels(imageData: ImageData, data: Uint8ClampedArray, x: number, y: number, w: number, h: number): void;
+
+/**
+ * A convenience wrapper that extracts the first {@link File} from an
+ * {@link HTMLInputElement} change event and converts it into {@link ImageData}.
+ *
+ * This function handles the boilerplate of accessing the file list and checking
+ * for existence. It is ideal for use directly in an `onchange` event listener.
+ *
+ * @param event - The change {@link Event} from an `<input type="file">` element.
+ *
+ * @returns A promise that resolves to {@link ImageData} if a file was successfully
+ * processed, or `null` if no file was selected or the input was cleared.
+ *
+ * @example
+ * ```typescript
+ * const input = document.querySelector('input[type="file"]');
+ *
+ * input.addEventListener('change', async (event) => {
+ *   const imageData = await fileInputChangeToImageData(event);
+ *
+ *   if (imageData) {
+ *     console.log('Image loaded:', imageData.width, imageData.height);
+ *   }
+ * });
+ * ```
+ */
+declare function fileInputChangeToImageData(event: Event): Promise<ImageData | null>;
+
+/**
+ * Thrown when the user provides a file that isn't an image.
+ */
+declare class UnsupportedFormatError extends Error {
+    constructor(mimeType: string);
 }
+/**
+ * Converts a browser {@link File} object into {@link ImageData}.
+ * This utility handles the full pipeline of image decoding using hardware-accelerated
+ * APIs {@link createImageBitmap} and {@link OffscreenCanvas}. It ensures that underlying
+ * resources like `ImageBitmap` are properly closed even if the conversion fails.
+ *
+ * @param file - The image file to convert. Can be null or undefined.
+ * @returns A `Promise` resolving to the pixel data as {@link ImageData},
+ * or `null` if no file was provided.
+ * @throws {@link UnsupportedFormatError}
+ * Thrown if the provided file's MIME type does not start with `image/`.
+ * @example
+ * ```typescript
+ * try {
+ *   const imageData = await fileToImageData(file);
+ *   if (imageData) {
+ *     console.log('Pixels:', imageData.data);
+ *   }
+ * } catch (err) {
+ *   if (err instanceof UnsupportedFormatError) {
+ *     // Handle bad file type
+ *   }
+ * }
+ * ```
+ */
+declare function fileToImageData(file: File | null | undefined): Promise<ImageData | null>;
+
+/**
+ * Probes the browser environment to determine which image MIME types are
+ * supported for pixel-level operations.
+ * This function performs a one-time check by attempting to convert a
+ * {@link OffscreenCanvas} to MIME types. The result is
+ * cached to prevent redundant hardware-accelerated operations on
+ * subsequent calls.
+ * @param rasterMimes List of MIME types to check
+ * @default ['image/png',
+ *   'image/jpeg',
+ *   'image/webp',
+ *   'image/avif',
+ *   'image/gif',
+ *   'image/bmp']
+ * @returns A `Promise` resolving to an array of supported MIME
+ * types from the `rasterMimes` list.
+ * @throws {Error} If the {@link OffscreenCanvas} context cannot be initialized.
+ * @example
+ * ```typescript
+ * const supported = await getSupportedPixelFormats();
+ * if (supported.includes('image/avif')) {
+ *   console.log('High-efficiency formats available');
+ * }
+ * ```
+ */
+declare function getSupportedPixelFormats(rasterMimes?: string[]): Promise<string[]>;
+
+/**
+ * Creates a new copy of a mask.
+ * Uses the underlying buffer's slice method for high-performance memory copying.
+ */
+declare function copyMask<T extends AnyMask>(src: T): T;
+
+/**
+ * Extracts a rectangular region from a 1D {@link Uint8Array} mask.
+ * This utility calculates the necessary offsets based on the `maskWidth` to
+ * slice out a specific area.
+ *
+ * @param mask - The source 1D array representing the full 2D mask.
+ * @param maskWidth - The width of the original source mask (stride).
+ * @param rect - A {@link Rect} object defining the region to extract.
+ * @returns A new {@link Uint8Array} containing the extracted region.
+ */
+declare function extractMask(mask: Uint8Array, maskWidth: number, rect: Rect): Uint8Array;
+/**
+ * @param mask - The source 1D array representing the full 2D mask.
+ * @param maskWidth - The width of the original source mask (stride).
+ * @param x - The starting horizontal coordinate.
+ * @param y - The starting vertical coordinate.
+ * @param w - The width of the region to extract.
+ * @param h - The height of the region to extract.
+ * @returns A new {@link Uint8Array} containing the extracted region.
+ */
+declare function extractMask(mask: Uint8Array, maskWidth: number, x: number, y: number, w: number, h: number): Uint8Array;
+
+/**
+ * Inverts a BinaryMask in-place.
+ */
+declare function invertBinaryMask(dst: BinaryMask): void;
+/**
+ * Inverts an AlphaMask in-place.
+ */
+declare function invertAlphaMask(dst: AlphaMask): void;
+
+/**
+ * Merges a source mask into a destination AlphaMask.
+ */
+declare function mergeMasks(dst: AlphaMask, dstWidth: number, src: AnyMask, opts: ApplyMaskOptions): void;
+
+/**
+ * Directly applies a mask to a region of PixelData,
+ * modifying the destination's alpha channel in-place.
+ */
+declare function applyMaskToPixelData(dst: PixelData, mask: AnyMask, opts: ApplyMaskOptions): void;
+
+/**
+ * Fills a rectangle in the destination PixelData with a single color,
+ * supporting blend modes, global alpha, and masking.
+ */
+declare function blendColorPixelData(dst: PixelData, color: Color32, opts: ColorBlendOptions): void;
 
 /**
  * Blits source PixelData into a destination PixelData using 32-bit integer bitwise blending.
@@ -267,4 +735,53 @@ declare class PixelData {
  */
 declare function blendPixelData(dst: PixelData, src: PixelData, opts: PixelBlendOptions): void;
 
-export { type AlphaMask, type AnyMask, type ApplyMaskOptions, type Base64EncodedUInt8Array, type BinaryMask, type BlendColor32, COLOR_32_BLEND_MODES, type Color32, type ColorBlendOptions, type ImageDataLike, MaskType, type PixelBlendOptions, type PixelOptions, type RGBA, type Rect, type SerializedImageData, base64DecodeArrayBuffer, base64EncodeArrayBuffer, blendPixelData, color32ToCssRGBA, color32ToHex, colorBurnColor32, colorDistance, copyImageData, copyImageDataLike, deserializeImageData, deserializeNullableImageData, deserializeRawImageData, differenceColor32, extractImageData, hardLightColor32, lerpColor32, lerpColor32Fast, linearDodgeColor32, multiplyColor32, overlayColor32, packColor, packRGBA, screenColor32, serializeImageData, serializeNullableImageData, sourceOverColor32, unpackAlpha, unpackBlue, unpackColor, unpackColorTo, unpackGreen, unpackRed };
+/**
+ * Clears a region of the PixelData to transparent (0x00000000).
+ * Internally uses the optimized fillPixelData.
+ */
+declare function clearPixelData(dst: PixelData, rect?: Partial<Rect>): void;
+
+/**
+ * Fills a region or the {@link PixelData} buffer with a solid color.
+ *
+ * @param dst - The target {@link PixelData} to modify.
+ * @param color - The {@link Color32} value to apply.
+ * @param rect - A {@link Rect} defining the area to fill. If omitted, the entire
+ * buffer is filled.
+ */
+declare function fillPixelData(dst: PixelData, color: Color32, rect?: Partial<Rect>): void;
+/**
+ * @param dst - The target {@link PixelData} to modify.
+ * @param color - The {@link Color32} value to apply.
+ * @param x - Starting horizontal coordinate.
+ * @param y - Starting vertical coordinate.
+ * @param w - Width of the fill area.
+ * @param h - Height of the fill area.
+ */
+declare function fillPixelData(dst: PixelData, color: Color32, x: number, y: number, w: number, h: number): void;
+
+declare function invertPixelData(pixelData: PixelData): PixelData;
+
+/**
+ * Extracts the alpha channel from PixelData into a single-channel mask.
+ * Returns a Uint8Array branded as AlphaMask.
+ */
+declare function pixelDataToAlphaMask(pixelData: PixelData): AlphaMask;
+
+/**
+ * Intersects a target rectangle with a boundary, trimming dimensions and masks in-place.
+ * This utility calculates the axis-aligned intersection between the `target` and `bounds`.
+ * If the `target` includes a `mask` (as in a {@link SelectionRect}), the mask is physically
+ * cropped and re-aligned using `extractMask` to match the new dimensions.
+ * @param target - The rectangle or selection object to be trimmed. **Note:** This object is mutated in-place.
+ * @param bounds - The boundary rectangle defining the maximum allowable area (e.g., canvas dimensions).
+ * @example
+ * const selection = { x: -10, y: -10, w: 50, h: 50, mask: new Uint8Array(2500) };
+ * const canvas = { x: 0, y: 0, w: 100, h: 100 };
+ * // Selection will be moved to (0,0) and resized to 40x40.
+ * // The mask is cropped by 10 px on the top and left.
+ * trimRectBounds(selection, canvas);
+ */
+declare function trimRectBounds<T extends Rect | SelectionRect>(target: T, bounds: Rect): void;
+
+export { type AlphaMask, type AnyMask, type ApplyMaskOptions, type Base64EncodedUInt8Array, type BinaryMask, type BlendColor32, BlendMode, type BlendModeIndex, COLOR_32_BLEND_MODES, COLOR_32_BLEND_TO_INDEX, type Color32, type ColorBlendOptions, type FloodFillImageDataOptions, type FloodFillResult, INDEX_TO_COLOR_32_BLEND, type ImageDataLike, MaskType, type PixelBlendOptions, type PixelCanvas, PixelData, type PixelOptions, type RGBA, type Rect, type RegisteredBlender, type ReusableCanvas, type SelectionRect, type SerializedImageData, UnsupportedFormatError, applyMaskToPixelData, base64DecodeArrayBuffer, base64EncodeArrayBuffer, blendColorPixelData, blendPixelData, clearPixelData, color32ToCssRGBA, color32ToHex, colorBurnColor32, colorDistance, colorDodgeColor32, copyImageData, copyImageDataLike, copyMask, darkenColor32, darkerColor32, deserializeImageData, deserializeNullableImageData, deserializeRawImageData, differenceColor32, divideColor32, exclusionColor32, extractImageDataPixels, extractMask, fileInputChangeToImageData, fileToImageData, fillPixelData, floodFillSelection, getImageDataFromClipboard, getSupportedPixelFormats, hardLightColor32, hardMixColor32, imageDataToAlphaMask, imageDataToDataUrl, imageDataToImgBlob, imgBlobToImageData, invertAlphaMask, invertBinaryMask, invertImageData, invertPixelData, lerpColor32, lerpColor32Fast, lightenColor32, lighterColor32, linearBurnColor32, linearDodgeColor32, linearLightColor32, makePixelCanvas, makeReusableCanvas, mergeMasks, multiplyColor32, overlayColor32, overwriteColor32, packColor, packRGBA, pinLightColor32, pixelDataToAlphaMask, resizeImageData, screenColor32, serializeImageData, serializeNullableImageData, softLightColor32, sourceOverColor32, subtractColor32, trimRectBounds, unpackAlpha, unpackBlue, unpackColor, unpackColorTo, unpackGreen, unpackRed, vividLightColor32, writeImageDataPixels, writeImageDataToClipboard, writeImgBlobToClipboard };