tempest-react-sdk 0.31.1 → 0.32.1

package/dist/imaging/use-image-processing.js

@@ -0,0 +1,45 @@
+import { resizeImage as e } from "./transform.js";
+import { compressToTarget as t } from "./compress.js";
+import { useCallback as n, useEffect as r, useRef as i, useState as a } from "react";
+//#region src/imaging/use-image-processing.ts
+function o(e) {
+	let [t, n] = a(null);
+	return r(() => {
+		if (e == null) {
+			n(null);
+			return;
+		}
+		let t = URL.createObjectURL(e);
+		return n(t), () => {
+			URL.revokeObjectURL(t);
+		};
+	}, [e]), { url: t };
+}
+function s() {
+	let [o, s] = a(null), [c, l] = a("idle"), [u, d] = a(null), f = i(!0);
+	r(() => (f.current = !0, () => {
+		f.current = !1;
+	}), []);
+	let p = n(async (e) => {
+		f.current && (l("working"), d(null));
+		try {
+			let t = await e();
+			return f.current && (s(t), l("done")), t;
+		} catch (e) {
+			let t = e instanceof Error ? e : Error(String(e));
+			throw f.current && (d(t), l("error")), t;
+		}
+	}, []);
+	return {
+		resize: n((t, n = {}) => p(() => e(t, n)), [p]),
+		compress: n((e, n) => p(() => t(e, n)), [p]),
+		result: o,
+		status: c,
+		error: u,
+		isWorking: c === "working"
+	};
+}
+//#endregion
+export { o as useImagePreview, s as useImageProcessing };
+
+//# sourceMappingURL=use-image-processing.js.map

package/dist/imaging/use-image-processing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-image-processing.js","names":[],"sources":["../../src/imaging/use-image-processing.ts"],"sourcesContent":["/**\n * React bindings for image work.\n *\n * Two things components get wrong every time: they leak object URLs (an\n * `URL.createObjectURL` without its `revokeObjectURL` holds the whole blob\n * in memory for the page's lifetime), and they set state after unmounting\n * when a slow resize finishes late. Both live here instead of in each\n * component.\n */\n\nimport { useCallback, useEffect, useRef, useState } from \"react\";\n\nimport { compressToTarget, type CompressedImage } from \"./compress\";\nimport type { CompressOptions, ImageSource, ProcessedImage, ResizeOptions } from \"./types\";\nimport { resizeImage } from \"./transform\";\n\n/** What {@link useImagePreview} returns. */\nexport interface UseImagePreviewResult {\n    /** Object URL for the current source, or `null`. */\n    readonly url: string | null;\n}\n\n/**\n * Hold an object URL for a blob, and revoke it when it is replaced.\n *\n * @example\n * ```tsx\n * function Preview({ file }: { file: File | null }) {\n *     const { url } = useImagePreview(file);\n *     return url === null ? null : <img src={url} alt=\"\" />;\n * }\n * ```\n *\n * @param source The blob to preview, or `null`.\n * @returns The object URL, valid until the source changes or the component\n *   unmounts.\n */\nexport function useImagePreview(source: Blob | null | undefined): UseImagePreviewResult {\n    const [url, setUrl] = useState<string | null>(null);\n\n    useEffect(() => {\n        if (source === null || source === undefined) {\n            setUrl(null);\n            return;\n        }\n        const created = URL.createObjectURL(source);\n        setUrl(created);\n        return () => {\n            URL.revokeObjectURL(created);\n        };\n    }, [source]);\n\n    return { url };\n}\n\n/** Lifecycle of a processing call. */\nexport type ImageProcessingStatus = \"idle\" | \"working\" | \"done\" | \"error\";\n\n/** What {@link useImageProcessing} returns. */\nexport interface UseImageProcessingResult {\n    /** Resize (and re-encode) an image. */\n    readonly resize: (source: ImageSource, options?: ResizeOptions) => Promise<ProcessedImage>;\n    /** Compress an image into a byte budget. */\n    readonly compress: (source: ImageSource, options: CompressOptions) => Promise<CompressedImage>;\n    /** The most recent result. */\n    readonly result: ProcessedImage | null;\n    /** Where the last call is. */\n    readonly status: ImageProcessingStatus;\n    /** Why the last call failed. */\n    readonly error: Error | null;\n    /** Whether a call is in flight. */\n    readonly isWorking: boolean;\n}\n\n/**\n * Run image operations with status tracking, safe against unmount.\n *\n * @example\n * ```tsx\n * function Upload() {\n *     const { compress, isWorking, result } = useImageProcessing();\n *\n *     async function onPick(file: File) {\n *         const ready = await compress(file, { maxBytes: 1_000_000, width: 1600 });\n *         await fetch(\"/api/photos\", { method: \"POST\", body: ready.blob });\n *     }\n *\n *     return <input type=\"file\" disabled={isWorking} onChange={(e) => onPick(e.target.files![0]!)} />;\n * }\n * ```\n *\n * The returned promises still reject on failure, so a caller can `try`\n * around them; `status` and `error` exist for rendering, not for swallowing\n * the failure.\n *\n * @returns The operations plus their state.\n */\nexport function useImageProcessing(): UseImageProcessingResult {\n    const [result, setResult] = useState<ProcessedImage | null>(null);\n    const [status, setStatus] = useState<ImageProcessingStatus>(\"idle\");\n    const [error, setError] = useState<Error | null>(null);\n    const mounted = useRef(true);\n\n    useEffect(() => {\n        mounted.current = true;\n        return () => {\n            mounted.current = false;\n        };\n    }, []);\n\n    const run = useCallback(\n        async <T extends ProcessedImage>(work: () => Promise<T>): Promise<T> => {\n            if (mounted.current) {\n                setStatus(\"working\");\n                setError(null);\n            }\n            try {\n                const produced = await work();\n                if (mounted.current) {\n                    setResult(produced);\n                    setStatus(\"done\");\n                }\n                return produced;\n            } catch (caught) {\n                const failure = caught instanceof Error ? caught : new Error(String(caught));\n                if (mounted.current) {\n                    setError(failure);\n                    setStatus(\"error\");\n                }\n                throw failure;\n            }\n        },\n        [],\n    );\n\n    const resize = useCallback(\n        (source: ImageSource, options: ResizeOptions = {}) =>\n            run(() => resizeImage(source, options)),\n        [run],\n    );\n\n    const compress = useCallback(\n        (source: ImageSource, options: CompressOptions) =>\n            run(() => compressToTarget(source, options)),\n        [run],\n    );\n\n    return {\n        resize,\n        compress,\n        result,\n        status,\n        error,\n        isWorking: status === \"working\",\n    };\n}\n"],"mappings":";;;;AAqCA,SAAgB,EAAgB,GAAwD;CACpF,IAAM,CAAC,GAAK,KAAU,EAAwB,IAAI;CAclD,OAZA,QAAgB;EACZ,IAAI,KAAW,MAA8B;GACzC,EAAO,IAAI;GACX;EACJ;EACA,IAAM,IAAU,IAAI,gBAAgB,CAAM;EAE1C,OADA,EAAO,CAAO,SACD;GACT,IAAI,gBAAgB,CAAO;EAC/B;CACJ,GAAG,CAAC,CAAM,CAAC,GAEJ,EAAE,OAAI;AACjB;AA4CA,SAAgB,IAA+C;CAC3D,IAAM,CAAC,GAAQ,KAAa,EAAgC,IAAI,GAC1D,CAAC,GAAQ,KAAa,EAAgC,MAAM,GAC5D,CAAC,GAAO,KAAY,EAAuB,IAAI,GAC/C,IAAU,EAAO,EAAI;CAE3B,SACI,EAAQ,UAAU,UACL;EACT,EAAQ,UAAU;CACtB,IACD,CAAC,CAAC;CAEL,IAAM,IAAM,EACR,OAAiC,MAAuC;EACpE,AAAI,EAAQ,YACR,EAAU,SAAS,GACnB,EAAS,IAAI;EAEjB,IAAI;GACA,IAAM,IAAW,MAAM,EAAK;GAK5B,OAJI,EAAQ,YACR,EAAU,CAAQ,GAClB,EAAU,MAAM,IAEb;EACX,SAAS,GAAQ;GACb,IAAM,IAAU,aAAkB,QAAQ,IAAa,MAAM,OAAO,CAAM,CAAC;GAK3E,MAJI,EAAQ,YACR,EAAS,CAAO,GAChB,EAAU,OAAO,IAEf;EACV;CACJ,GACA,CAAC,CACL;CAcA,OAAO;EACH,QAbW,GACV,GAAqB,IAAyB,CAAC,MAC5C,QAAU,EAAY,GAAQ,CAAO,CAAC,GAC1C,CAAC,CAAG,CAUJ;EACA,UARa,GACZ,GAAqB,MAClB,QAAU,EAAiB,GAAQ,CAAO,CAAC,GAC/C,CAAC,CAAG,CAKJ;EACA;EACA;EACA;EACA,WAAW,MAAW;CAC1B;AACJ"}

package/dist/imaging.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./imaging/exceptions.cjs"),t=require("./imaging/canvas.cjs"),n=require("./imaging/decode.cjs"),r=require("./imaging/encode.cjs"),i=require("./imaging/transform.cjs"),a=require("./imaging/compress.cjs"),o=require("./imaging/thumbnails.cjs"),s=require("./imaging/use-image-processing.cjs");exports.DEFAULT_BACKGROUND=i.DEFAULT_BACKGROUND,exports.DEFAULT_COMPRESS_STEPS=a.DEFAULT_COMPRESS_STEPS,exports.DEFAULT_MAX_QUALITY=a.DEFAULT_MAX_QUALITY,exports.DEFAULT_MIN_QUALITY=a.DEFAULT_MIN_QUALITY,exports.DEFAULT_QUALITY=r.DEFAULT_QUALITY,exports.DEFAULT_TYPE=r.DEFAULT_TYPE,exports.ImageDecodeError=e.ImageDecodeError,exports.ImageEncodeError=e.ImageEncodeError,exports.ImagingError=e.ImagingError,exports.ImagingUnavailableError=e.ImagingUnavailableError,exports.UnsupportedImageTypeError=e.UnsupportedImageTypeError,exports.bestSupportedType=r.bestSupportedType,exports.compressToTarget=a.compressToTarget,exports.createSurface=t.createSurface,exports.createThumbnails=o.createThumbnails,exports.cropImage=i.cropImage,exports.decodeImage=n.decodeImage,exports.drawScaled=t.drawScaled,exports.encodeImage=r.encodeImage,exports.flipImage=i.flipImage,exports.getContext=t.getContext,exports.readImageInfo=n.readImageInfo,exports.resetImageTypeSupportCache=r.resetImageTypeSupportCache,exports.resizeImage=i.resizeImage,exports.rotateImage=i.rotateImage,exports.supportsImageType=r.supportsImageType,exports.useImagePreview=s.useImagePreview,exports.useImageProcessing=s.useImageProcessing;

package/dist/imaging.d.ts

@@ -0,0 +1,541 @@
+/**
+ * Pick the smallest format this browser can actually produce.
+ *
+ * @example
+ * ```ts
+ * const type = await bestSupportedType(["image/avif", "image/webp", "image/jpeg"]);
+ * ```
+ *
+ * @param preferences Formats in preference order.
+ * @returns The first supported one, falling back to `image/jpeg`, which
+ *   every canvas implementation encodes.
+ */
+export declare function bestSupportedType(preferences?: readonly ImageType[]): Promise<ImageType>;
+
+/** What {@link compressToTarget} produced. */
+export declare interface CompressedImage extends ProcessedImage {
+    /** The quality it settled on. */
+    readonly quality: number;
+    /** How many encodes it took. */
+    readonly attempts: number;
+    /**
+     * Whether the result actually fits the budget.
+     *
+     * `false` means the image could not reach it even at `minQuality` —
+     * reported rather than thrown, because a 2.1 MB result against a 2 MB
+     * budget is usually still worth uploading, and that call is the
+     * caller's.
+     */
+    readonly withinBudget: boolean;
+}
+
+/** Options for {@link compressToTarget}. */
+export declare interface CompressOptions extends ResizeOptions {
+    /** Byte budget the result must fit in. */
+    readonly maxBytes: number;
+    /** Lowest quality worth producing. Defaults to `0.4`. */
+    readonly minQuality?: number;
+    /** Highest quality to start from. Defaults to `0.92`. */
+    readonly maxQuality?: number;
+    /** Search steps. Defaults to `6`, which resolves quality to ~1%. */
+    readonly steps?: number;
+}
+
+/**
+ * Compress an image until it fits a byte budget.
+ *
+ * @example
+ * ```ts
+ * const upload = await compressToTarget(file, {
+ *     maxBytes: 2 * 1024 * 1024,
+ *     width: 2000,
+ *     type: "image/webp",
+ * });
+ *
+ * if (!upload.withinBudget) {
+ *     console.warn(`still ${upload.bytes} bytes at quality ${upload.quality}`);
+ * }
+ * ```
+ *
+ * Resizing first is what usually does the work: halving the long edge
+ * removes three quarters of the pixels, which no quality setting matches.
+ * Pass `width`/`height` when the source is a full-resolution photo.
+ *
+ * @param source Anything decodable.
+ * @param options Byte budget plus the usual resize and format options.
+ * @returns The best result found, and whether it fits.
+ * @throws {@link ImageDecodeError} when the source cannot be decoded.
+     */
+ export declare function compressToTarget(source: ImageSource, options: CompressOptions): Promise<CompressedImage>;
+
+ /**
+  * Create a drawing surface, preferring `OffscreenCanvas`.
+  *
+  * `OffscreenCanvas` works inside a worker, which is where a PWA wants this
+  * running: resizing a 12-megapixel photo on the main thread blocks the UI
+  * for tens of milliseconds per image.
+  *
+  * @param width Surface width in pixels.
+  * @param height Surface height in pixels.
+  * @returns The surface.
+  * @throws {@link ImagingUnavailableError} when neither kind exists — a
+      *   server render, or a test environment without a canvas.
+      */
+  export declare function createSurface(width: number, height: number): Surface;
+
+  /**
+   * Produce several sizes from a single decode.
+   *
+   * @example
+   * ```ts
+   * const [thumb, card] = await createThumbnails(file, [
+   *     { name: "thumb", size: 96 },
+   *     { name: "card", size: 480 },
+   * ]);
+   * ```
+   *
+   * Sizes are the **longest edge**, and the aspect ratio is kept, so a
+   * portrait and a landscape photo both fit the same grid cell without a
+   * separate calculation per orientation.
+   *
+   * @param source Anything decodable.
+   * @param specs The sizes to produce.
+   * @param options Shared format and quality.
+   * @returns One result per spec, in the order requested.
+   * @throws {@link ImageDecodeError} when the source cannot be decoded.
+       */
+   export declare function createThumbnails(source: ImageSource, specs: readonly ThumbnailSpec[], options?: EncodeOptions): Promise<Thumbnail[]>;
+
+   /**
+    * Crop a rectangle out of an image, in source pixels.
+    *
+    * The rectangle is clamped to the image, so a crop dragged past the edge
+    * produces a smaller result instead of transparent padding.
+    *
+    * @example
+    * ```ts
+    * const badge = await cropImage(file, { x: 120, y: 80, width: 400, height: 400 });
+    * ```
+    *
+    * @param source Anything decodable.
+    * @param rect The region to keep.
+    * @param options Format and quality.
+    * @returns The encoded crop.
+    * @throws {@link ImageDecodeError} when the source cannot be decoded.
+        */
+    export declare function cropImage(source: ImageSource, rect: CropRect, options?: EncodeOptions): Promise<ProcessedImage>;
+
+    /** A rectangle in source pixels. */
+    export declare interface CropRect {
+        readonly x: number;
+        readonly y: number;
+        readonly width: number;
+        readonly height: number;
+    }
+
+    /** A decoded image, ready to draw. */
+    export declare interface DecodedImage {
+        /** The pixels. */
+        readonly bitmap: ImageBitmap;
+        /** Width in pixels, after orientation was applied. */
+        readonly width: number;
+        /** Height in pixels, after orientation was applied. */
+        readonly height: number;
+    }
+
+    /**
+     * Decode any supported source into a bitmap, oriented as the photographer
+     * held the camera.
+     *
+     * @example
+     * ```ts
+     * const { bitmap, width, height } = await decodeImage(file);
+     * ```
+     *
+     * @param source A `Blob`/`File`, URL string, `ImageBitmap`, `ImageData`,
+     *   `HTMLImageElement`, or a canvas.
+     * @returns The decoded pixels and their dimensions.
+     * @throws {@link ImageDecodeError} when the bytes are not a decodable image,
+         *   or the URL cannot be fetched.
+         */
+     export declare function decodeImage(source: ImageSource): Promise<DecodedImage>;
+
+     /** Background used when a format cannot carry transparency. */
+     export declare const DEFAULT_BACKGROUND = "#ffffff";
+
+     /** Search steps when the caller does not choose. */
+     export declare const DEFAULT_COMPRESS_STEPS = 6;
+
+     /** Highest quality to start from by default. */
+     export declare const DEFAULT_MAX_QUALITY = 0.92;
+
+     /** Lowest quality worth producing by default. */
+     export declare const DEFAULT_MIN_QUALITY = 0.4;
+
+     /** Quality used when the caller does not choose. */
+     export declare const DEFAULT_QUALITY = 0.85;
+
+     /** Format used when the caller does not choose. */
+     export declare const DEFAULT_TYPE: ImageType;
+
+     /**
+      * Draw a bitmap into a surface with high-quality filtering.
+      *
+      * @param bitmap The source pixels.
+      * @param target Destination surface.
+      * @param box Where to draw inside the destination.
+      * @param background Fill painted before drawing.
+      */
+     export declare function drawScaled(bitmap: ImageBitmap, target: Surface, box: {
+         x: number;
+         y: number;
+         width: number;
+         height: number;
+     }, background?: string): void;
+
+     /**
+      * Encode a surface into image bytes.
+      *
+      * @param surface The canvas to encode.
+      * @param options Format and quality.
+      * @returns The blob plus the dimensions and the type actually produced.
+      * @throws {@link ImageEncodeError} when the canvas produces nothing.
+          */
+      export declare function encodeImage(surface: Surface, options?: EncodeOptions): Promise<ProcessedImage>;
+
+      /** Options for {@link encodeImage}. */
+      export declare interface EncodeOptions {
+          /** Output format. Defaults to `image/jpeg`. */
+          readonly type?: ImageType;
+          /** Quality for lossy formats, `0`-`1`. Defaults to `0.85`. */
+          readonly quality?: number;
+      }
+
+      /**
+       * Mirror an image horizontally, vertically, or both.
+       *
+       * @example
+       * ```ts
+       * const selfie = await flipImage(capture, { horizontal: true });
+       * ```
+       *
+       * @param source Anything decodable.
+       * @param axes Which axes to mirror.
+       * @param options Format and quality.
+       * @returns The flipped image.
+       * @throws {@link ImageDecodeError} when the source cannot be decoded.
+           */
+       export declare function flipImage(source: ImageSource, axes: {
+           horizontal?: boolean;
+           vertical?: boolean;
+       }, options?: EncodeOptions): Promise<ProcessedImage>;
+
+       /**
+        * Get a 2-D context configured for image work.
+        *
+        * `imageSmoothingQuality = "high"` is the setting that makes a steep
+        * downscale average its source pixels instead of sampling them sparsely.
+        *
+        * @param surface The surface to draw on.
+        * @param background Optional fill painted before anything else.
+        * @returns The context.
+        * @throws {@link ImagingUnavailableError} when the context cannot be created.
+            */
+        export declare function getContext(surface: Surface, background?: string): SurfaceContext;
+
+        /** The source could not be decoded into pixels. */
+        export declare class ImageDecodeError extends ImagingError {
+            constructor(message: string, options?: ErrorOptions);
+        }
+
+        /** The canvas could not produce encoded bytes. */
+        export declare class ImageEncodeError extends ImagingError {
+            constructor(message: string, options?: ErrorOptions);
+        }
+
+        /** What a file holds, without decoding all of it. */
+        export declare interface ImageInfo {
+            readonly width: number;
+            readonly height: number;
+            /** MIME type as reported by the blob. */
+            readonly type: string;
+            /** Size in bytes. */
+            readonly bytes: number;
+            /** `width / height`. */
+            readonly aspectRatio: number;
+        }
+
+        /** Lifecycle of a processing call. */
+        export declare type ImageProcessingStatus = "idle" | "working" | "done" | "error";
+
+        /**
+         * Types for browser-side image processing.
+         */
+        /** Anything the module can decode. */
+        export declare type ImageSource = Blob | File | ImageBitmap | ImageData | HTMLImageElement | HTMLCanvasElement | OffscreenCanvas | string;
+
+        /** Encodable image formats. */
+        export declare type ImageType = "image/jpeg" | "image/png" | "image/webp" | "image/avif";
+
+        /**
+         * Errors thrown by the imaging module.
+         *
+         * `name` is a literal string on every subclass: minifiers rename classes,
+         * and a derived `new.target.name` ships as `error.name === "t"`.
+         */
+        /** Base class for every error this module throws. */
+        export declare class ImagingError extends Error {
+            constructor(message: string, options?: ErrorOptions);
+        }
+
+        /** The environment has no canvas to draw on. */
+        export declare class ImagingUnavailableError extends ImagingError {
+            constructor(message: string, options?: ErrorOptions);
+        }
+
+        /** The result of an operation that produced an encoded image. */
+        export declare interface ProcessedImage {
+            /** The encoded bytes. */
+            readonly blob: Blob;
+            /** Output width. */
+            readonly width: number;
+            /** Output height. */
+            readonly height: number;
+            /** Output format actually produced — not necessarily the one asked for. */
+            readonly type: string;
+            /** Size in bytes. */
+            readonly bytes: number;
+        }
+
+        /**
+         * Read an image's dimensions, type and size.
+         *
+         * Decodes to measure, which is the only reliable way in a browser — there
+         * is no header parser here, and guessing dimensions from a MIME type is not
+         * a thing. Cheap enough for a preview, not for a thousand files in a loop.
+         *
+         * @example
+         * ```ts
+         * const info = await readImageInfo(file);
+         * if (info.bytes > 5_000_000) {
+         *     // ask before uploading
+         * }
+         * ```
+         *
+         * @param blob The image file.
+         * @returns Its dimensions, MIME type, byte size and aspect ratio.
+         * @throws {@link ImageDecodeError} when the blob is not a decodable image.
+             */
+         export declare function readImageInfo(blob: Blob): Promise<ImageInfo>;
+
+         /**
+          * Clear the format-support cache.
+          *
+          * Only useful in tests: browser support does not change at runtime.
+          */
+         export declare function resetImageTypeSupportCache(): void;
+
+         /**
+          * How a resize fits the requested box.
+          *
+          * - `contain`: the whole image fits inside the box; the result may be
+          *   smaller than the box in one dimension.
+          * - `cover`: the box is filled; the overflow is cropped, centred.
+          * - `fill`: the image is stretched to the box, changing its aspect ratio.
+          * - `pad`: like `contain`, but the result is exactly the box, with the
+          *   remainder painted in `background`.
+          */
+         export declare type ResizeFit = "contain" | "cover" | "fill" | "pad";
+
+         /**
+          * Resize an image, re-encoding it.
+          *
+          * @example
+          * ```ts
+          * const resized = await resizeImage(file, { width: 1600, type: "image/webp" });
+          * console.log(resized.width, resized.bytes, resized.type);
+          * ```
+          *
+          * @param source Anything decodable.
+          * @param options Target box, fit, format and quality.
+          * @returns The encoded result.
+          * @throws {@link ImageDecodeError} when the source cannot be decoded.
+              * @throws {@link ImageEncodeError} when the canvas produces no bytes.
+                  */
+              export declare function resizeImage(source: ImageSource, options?: ResizeOptions): Promise<ProcessedImage>;
+
+              /** Options for {@link resizeImage}. */
+              export declare interface ResizeOptions extends EncodeOptions {
+                  /** Target width in pixels. */
+                  readonly width?: number;
+                  /** Target height in pixels. */
+                  readonly height?: number;
+                  /** How the image fits the box. Defaults to `contain`. */
+                  readonly fit?: ResizeFit;
+                  /** Fill colour for `pad`, and behind transparency when encoding JPEG. */
+                  readonly background?: string;
+                  /**
+                   * Never scale an image up.
+                   *
+                   * On by default: enlarging a photo adds no detail and multiplies the
+                   * bytes, which is the opposite of what a resize is usually for.
+                   */
+                  readonly withoutEnlargement?: boolean;
+              }
+
+              /**
+               * Rotate an image by a multiple of 90 degrees.
+               *
+               * Restricted to right angles on purpose: an arbitrary angle needs a
+               * decision about the corners (crop, pad, or grow the canvas) that belongs
+               * to the caller's design, not to a utility default.
+               *
+               * @example
+               * ```ts
+               * const upright = await rotateImage(file, 90);
+               * ```
+               *
+               * @param source Anything decodable.
+               * @param degrees `90`, `180`, `270` — or any multiple, normalised.
+               * @param options Format and quality.
+               * @returns The rotated image.
+               * @throws {@link ImageDecodeError} when the source cannot be decoded.
+                   * @throws {@link RangeError} when the angle is not a multiple of 90.
+                       */
+                   export declare function rotateImage(source: ImageSource, degrees: number, options?: EncodeOptions): Promise<ProcessedImage>;
+
+                   /**
+                    * Whether this browser can actually encode a format.
+                    *
+                    * Asks for a 1x1 image in that type and checks what came back, because
+                    * that is the only answer that counts: a browser that "supports" WebP for
+                    * display may still not encode it.
+                    *
+                    * @example
+                    * ```ts
+                    * const type = (await supportsImageType("image/webp")) ? "image/webp" : "image/jpeg";
+                    * const resized = await resizeImage(file, { width: 1200, type });
+                    * ```
+                    *
+                    * @param type The format to test.
+                    * @returns Whether encoding produces that type. Cached per type.
+                    */
+                   export declare function supportsImageType(type: ImageType): Promise<boolean>;
+
+                   /**
+                    * The drawing surface, and the one thing everyone gets wrong on it.
+                    *
+                    * **JPEG has no alpha.** Encoding a transparent PNG as JPEG paints the
+                    * transparent pixels black. Filling the surface first is the difference
+                    * between a photo on a white background and one with a black hole in it.
+                    *
+                    * What is *not* here is worth recording. The received wisdom for downscaling
+                    * on a canvas is to halve repeatedly, because a single `drawImage` into a
+                    * much smaller box was said to alias. That was implemented here, and then
+                    * measured: on a 512 px checkerboard reduced to 32 px, the stepwise result
+                    * and the single high-quality draw were **pixel-identical** (standard
+                    * deviation 0.0 on both) in Chromium and Firefox — while stepwise cost
+                    * **39.19 ms against 0.13 ms** on a 4000x3000 photo, 300 times more, and
+                    * allocated three intermediate canvases on a device that may not have the
+                    * memory. Modern engines honour `imageSmoothingQuality = "high"`, which is
+                    * what this module sets. The halving was deleted rather than kept "just in
+                    * case": unmeasurable benefit at 300x the cost is not insurance, it is
+                    * ballast.
+                    */
+                   /** A canvas this module can draw on, on the main thread or in a worker. */
+                   export declare type Surface = OffscreenCanvas | HTMLCanvasElement;
+
+                   /** A 2-D context from either surface kind. */
+                   export declare type SurfaceContext = OffscreenCanvasRenderingContext2D | CanvasRenderingContext2D;
+
+                   /** A produced thumbnail. */
+                   export declare interface Thumbnail extends ProcessedImage {
+                       readonly name: string;
+                   }
+
+                   /** One requested size. */
+                   export declare interface ThumbnailSpec {
+                       /** Name to find it by in the result. */
+                       readonly name: string;
+                       /** Longest edge in pixels. */
+                       readonly size: number;
+                       /** Format and quality, overriding the shared options. */
+                       readonly encode?: EncodeOptions;
+                   }
+
+                   /**
+                    * The browser cannot encode the requested format.
+                    *
+                    * Worth its own class because the failure is otherwise silent: asking a
+                    * canvas for an unsupported type does not throw — it hands back a PNG,
+                    * and an app that trusted the request ships 4 MB where it expected 300 KB.
+                    */
+                   export declare class UnsupportedImageTypeError extends ImagingError {
+                       constructor(message: string, options?: ErrorOptions);
+                   }
+
+                   /**
+                    * Hold an object URL for a blob, and revoke it when it is replaced.
+                    *
+                    * @example
+                    * ```tsx
+                    * function Preview({ file }: { file: File | null }) {
+                    *     const { url } = useImagePreview(file);
+                    *     return url === null ? null : <img src={url} alt="" />;
+                    * }
+                    * ```
+                    *
+                    * @param source The blob to preview, or `null`.
+                    * @returns The object URL, valid until the source changes or the component
+                    *   unmounts.
+                    */
+                   export declare function useImagePreview(source: Blob | null | undefined): UseImagePreviewResult;
+
+                   /** What {@link useImagePreview} returns. */
+                   export declare interface UseImagePreviewResult {
+                       /** Object URL for the current source, or `null`. */
+                       readonly url: string | null;
+                   }
+
+                   /**
+                    * Run image operations with status tracking, safe against unmount.
+                    *
+                    * @example
+                    * ```tsx
+                    * function Upload() {
+                    *     const { compress, isWorking, result } = useImageProcessing();
+                    *
+                    *     async function onPick(file: File) {
+                    *         const ready = await compress(file, { maxBytes: 1_000_000, width: 1600 });
+                    *         await fetch("/api/photos", { method: "POST", body: ready.blob });
+                    *     }
+                    *
+                    *     return <input type="file" disabled={isWorking} onChange={(e) => onPick(e.target.files![0]!)} />;
+                    * }
+                    * ```
+                    *
+                    * The returned promises still reject on failure, so a caller can `try`
+                    * around them; `status` and `error` exist for rendering, not for swallowing
+                    * the failure.
+                    *
+                    * @returns The operations plus their state.
+                    */
+                   export declare function useImageProcessing(): UseImageProcessingResult;
+
+                   /** What {@link useImageProcessing} returns. */
+                   export declare interface UseImageProcessingResult {
+                       /** Resize (and re-encode) an image. */
+                       readonly resize: (source: ImageSource, options?: ResizeOptions) => Promise<ProcessedImage>;
+                       /** Compress an image into a byte budget. */
+                       readonly compress: (source: ImageSource, options: CompressOptions) => Promise<CompressedImage>;
+                       /** The most recent result. */
+                       readonly result: ProcessedImage | null;
+                       /** Where the last call is. */
+                       readonly status: ImageProcessingStatus;
+                       /** Why the last call failed. */
+                       readonly error: Error | null;
+                       /** Whether a call is in flight. */
+                       readonly isWorking: boolean;
+                   }
+
+                   export { }

package/dist/imaging.js

@@ -0,0 +1,9 @@
+import { ImageDecodeError as e, ImageEncodeError as t, ImagingError as n, ImagingUnavailableError as r, UnsupportedImageTypeError as i } from "./imaging/exceptions.js";
+import { createSurface as a, drawScaled as o, getContext as s } from "./imaging/canvas.js";
+import { decodeImage as c, readImageInfo as l } from "./imaging/decode.js";
+import { DEFAULT_QUALITY as u, DEFAULT_TYPE as d, bestSupportedType as f, encodeImage as p, resetImageTypeSupportCache as m, supportsImageType as h } from "./imaging/encode.js";
+import { DEFAULT_BACKGROUND as g, cropImage as _, flipImage as v, resizeImage as y, rotateImage as b } from "./imaging/transform.js";
+import { DEFAULT_COMPRESS_STEPS as x, DEFAULT_MAX_QUALITY as S, DEFAULT_MIN_QUALITY as C, compressToTarget as w } from "./imaging/compress.js";
+import { createThumbnails as T } from "./imaging/thumbnails.js";
+import { useImagePreview as E, useImageProcessing as D } from "./imaging/use-image-processing.js";
+export { g as DEFAULT_BACKGROUND, x as DEFAULT_COMPRESS_STEPS, S as DEFAULT_MAX_QUALITY, C as DEFAULT_MIN_QUALITY, u as DEFAULT_QUALITY, d as DEFAULT_TYPE, e as ImageDecodeError, t as ImageEncodeError, n as ImagingError, r as ImagingUnavailableError, i as UnsupportedImageTypeError, f as bestSupportedType, w as compressToTarget, a as createSurface, T as createThumbnails, _ as cropImage, c as decodeImage, o as drawScaled, p as encodeImage, v as flipImage, s as getContext, l as readImageInfo, m as resetImageTypeSupportCache, y as resizeImage, b as rotateImage, h as supportsImageType, E as useImagePreview, D as useImageProcessing };

package/dist/tabular/assets.cjs

@@ -0,0 +1,2 @@
+const e=require("../_virtual/_rolldown/runtime.cjs");let t=require("onnxruntime-web");t=e.__toESM(t,1);var n=[`ort-wasm-simd-threaded.wasm`,`ort-wasm-simd-threaded.mjs`,`ort-wasm-simd-threaded.jsep.wasm`,`ort-wasm-simd-threaded.jsep.mjs`];function r(e){t.env.wasm.wasmPaths=e.endsWith(`/`)?e:`${e}/`}function i(e){let t=e.endsWith(`/`)?e:`${e}/`;return n.map(e=>`${t}${e}`)}exports.ORT_WASM_ASSETS=n,exports.configureOrtAssets=r,exports.ortAssetUrls=i;
+//# sourceMappingURL=assets.cjs.map

package/dist/tabular/assets.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.cjs","names":[],"sources":["../../src/tabular/assets.ts"],"sourcesContent":["/**\n * The runtime's own assets, which are the other half of working offline.\n *\n * ONNX Runtime Web does **not** embed its WebAssembly binary, not even in\n * the `.bundle` builds. Measured in Chromium: the default entry fetches\n * `ort-wasm-simd-threaded.jsep.wasm` at session creation, and serving the\n * app without that file fails with `Aborted(both async and sync fetching of\n * the wasm failed)` — an error that says nothing about the missing file.\n *\n * So an offline app has to ship those binaries and precache them. This\n * module names them and points the runtime at a local directory.\n */\n\nimport * as ort from \"onnxruntime-web\";\n\n/**\n * The WebAssembly binaries ONNX Runtime Web may request.\n *\n * Which one is fetched depends on the browser's threading and SIMD support,\n * so an app that must work everywhere ships all of them. Chromium with the\n * default entry point fetched the `jsep` build.\n */\nexport const ORT_WASM_ASSETS: readonly string[] = [\n    \"ort-wasm-simd-threaded.wasm\",\n    \"ort-wasm-simd-threaded.mjs\",\n    \"ort-wasm-simd-threaded.jsep.wasm\",\n    \"ort-wasm-simd-threaded.jsep.mjs\",\n];\n\n/**\n * Point ONNX Runtime Web at locally served WebAssembly binaries.\n *\n * Call once, before creating any predictor.\n *\n * @example\n * ```ts\n * configureOrtAssets(\"/ort/\");\n * const predictor = await TabularPredictor.create(\"/models/classifier.onnx\");\n * ```\n *\n * @param basePath Directory the binaries are served from, with a trailing\n *   slash. Copy them there at build time — for Vite, from\n *   `node_modules/onnxruntime-web/dist/`.\n */\nexport function configureOrtAssets(basePath: string): void {\n    ort.env.wasm.wasmPaths = basePath.endsWith(\"/\") ? basePath : `${basePath}/`;\n}\n\n/**\n * The URLs a service worker should precache for offline inference.\n *\n * The model file is not included: it is cached by\n * {@link fetchModelBytes} on first use, under its own bucket.\n *\n * @example\n * ```ts\n * installPrecache([...ortAssetUrls(\"/ort/\"), \"/index.html\"]);\n * ```\n *\n * @param basePath Directory the binaries are served from.\n * @returns Absolute-from-root URLs for every runtime asset.\n */\nexport function ortAssetUrls(basePath: string): string[] {\n    const prefix = basePath.endsWith(\"/\") ? basePath : `${basePath}/`;\n    return ORT_WASM_ASSETS.map((asset) => `${prefix}${asset}`);\n}\n"],"mappings":"uGAsBA,IAAa,EAAqC,CAC9C,8BACA,6BACA,mCACA,iCACJ,EAiBA,SAAgB,EAAmB,EAAwB,CACvD,EAAI,IAAI,KAAK,UAAY,EAAS,SAAS,GAAG,EAAI,EAAW,GAAG,EAAS,EAC7E,CAgBA,SAAgB,EAAa,EAA4B,CACrD,IAAM,EAAS,EAAS,SAAS,GAAG,EAAI,EAAW,GAAG,EAAS,GAC/D,OAAO,EAAgB,IAAK,GAAU,GAAG,IAAS,GAAO,CAC7D"}

package/dist/tabular/assets.js

@@ -0,0 +1,19 @@
+import * as e from "onnxruntime-web";
+//#region src/tabular/assets.ts
+var t = [
+	"ort-wasm-simd-threaded.wasm",
+	"ort-wasm-simd-threaded.mjs",
+	"ort-wasm-simd-threaded.jsep.wasm",
+	"ort-wasm-simd-threaded.jsep.mjs"
+];
+function n(t) {
+	e.env.wasm.wasmPaths = t.endsWith("/") ? t : `${t}/`;
+}
+function r(e) {
+	let n = e.endsWith("/") ? e : `${e}/`;
+	return t.map((e) => `${n}${e}`);
+}
+//#endregion
+export { t as ORT_WASM_ASSETS, n as configureOrtAssets, r as ortAssetUrls };
+
+//# sourceMappingURL=assets.js.map

package/dist/tabular/assets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.js","names":[],"sources":["../../src/tabular/assets.ts"],"sourcesContent":["/**\n * The runtime's own assets, which are the other half of working offline.\n *\n * ONNX Runtime Web does **not** embed its WebAssembly binary, not even in\n * the `.bundle` builds. Measured in Chromium: the default entry fetches\n * `ort-wasm-simd-threaded.jsep.wasm` at session creation, and serving the\n * app without that file fails with `Aborted(both async and sync fetching of\n * the wasm failed)` — an error that says nothing about the missing file.\n *\n * So an offline app has to ship those binaries and precache them. This\n * module names them and points the runtime at a local directory.\n */\n\nimport * as ort from \"onnxruntime-web\";\n\n/**\n * The WebAssembly binaries ONNX Runtime Web may request.\n *\n * Which one is fetched depends on the browser's threading and SIMD support,\n * so an app that must work everywhere ships all of them. Chromium with the\n * default entry point fetched the `jsep` build.\n */\nexport const ORT_WASM_ASSETS: readonly string[] = [\n    \"ort-wasm-simd-threaded.wasm\",\n    \"ort-wasm-simd-threaded.mjs\",\n    \"ort-wasm-simd-threaded.jsep.wasm\",\n    \"ort-wasm-simd-threaded.jsep.mjs\",\n];\n\n/**\n * Point ONNX Runtime Web at locally served WebAssembly binaries.\n *\n * Call once, before creating any predictor.\n *\n * @example\n * ```ts\n * configureOrtAssets(\"/ort/\");\n * const predictor = await TabularPredictor.create(\"/models/classifier.onnx\");\n * ```\n *\n * @param basePath Directory the binaries are served from, with a trailing\n *   slash. Copy them there at build time — for Vite, from\n *   `node_modules/onnxruntime-web/dist/`.\n */\nexport function configureOrtAssets(basePath: string): void {\n    ort.env.wasm.wasmPaths = basePath.endsWith(\"/\") ? basePath : `${basePath}/`;\n}\n\n/**\n * The URLs a service worker should precache for offline inference.\n *\n * The model file is not included: it is cached by\n * {@link fetchModelBytes} on first use, under its own bucket.\n *\n * @example\n * ```ts\n * installPrecache([...ortAssetUrls(\"/ort/\"), \"/index.html\"]);\n * ```\n *\n * @param basePath Directory the binaries are served from.\n * @returns Absolute-from-root URLs for every runtime asset.\n */\nexport function ortAssetUrls(basePath: string): string[] {\n    const prefix = basePath.endsWith(\"/\") ? basePath : `${basePath}/`;\n    return ORT_WASM_ASSETS.map((asset) => `${prefix}${asset}`);\n}\n"],"mappings":";;AAsBA,IAAa,IAAqC;CAC9C;CACA;CACA;CACA;AACJ;AAiBA,SAAgB,EAAmB,GAAwB;CACvD,EAAI,IAAI,KAAK,YAAY,EAAS,SAAS,GAAG,IAAI,IAAW,GAAG,EAAS;AAC7E;AAgBA,SAAgB,EAAa,GAA4B;CACrD,IAAM,IAAS,EAAS,SAAS,GAAG,IAAI,IAAW,GAAG,EAAS;CAC/D,OAAO,EAAgB,KAAK,MAAU,GAAG,IAAS,GAAO;AAC7D"}

package/dist/tabular/cache.cjs

@@ -0,0 +1,2 @@
+const e=require("./exceptions.cjs");var t=`tempest-tabular-models`;function n(){return globalThis.caches!==void 0}async function r(t,r={}){let a=r.cacheName??`tempest-tabular-models`;if(!n())return await i(t,r.requestInit);let o=await globalThis.caches.open(a);if(r.revalidate!==!0){let e=await o.match(t);if(e!==void 0)return new Uint8Array(await e.arrayBuffer())}try{let n=await fetch(t,r.requestInit);if(!n.ok)throw new e.ModelFetchError(`Failed to download the model: ${n.status} ${n.statusText}`);return await o.put(t,n.clone()),new Uint8Array(await n.arrayBuffer())}catch(n){let r=await o.match(t);if(r!==void 0)return new Uint8Array(await r.arrayBuffer());throw n instanceof e.ModelFetchError?n:new e.ModelFetchError(`The model is not cached and could not be downloaded: ${t}. Warm the cache while online — prefetch it at install time, or precache it in the service worker.`,{cause:n})}}async function i(t,n){try{let r=await fetch(t,n);if(!r.ok)throw new e.ModelFetchError(`Failed to download the model: ${r.status} ${r.statusText}`);return new Uint8Array(await r.arrayBuffer())}catch(n){throw n instanceof e.ModelFetchError?n:new e.ModelFetchError(`Failed to download the model: ${t}`,{cause:n})}}async function a(e,r=t){return n()?await(await globalThis.caches.open(r)).match(e)!==void 0:!1}async function o(e,r,i=t){if(!n())return!1;let a=await globalThis.caches.open(i),o=new Uint8Array(r).buffer;return await a.put(e,new Response(o,{headers:{"content-type":`application/octet-stream`}})),!0}async function s(e,r=t){return n()?e===void 0?await globalThis.caches.delete(r):await(await globalThis.caches.open(r)).delete(e):!1}exports.DEFAULT_MODEL_CACHE=t,exports.cacheModelBytes=o,exports.clearModelCache=s,exports.fetchModelBytes=r,exports.isModelCached=a;
+//# sourceMappingURL=cache.cjs.map