@freqhole/reliquary 0.0.0

package/dist/transfer/types.d.ts

@@ -0,0 +1,85 @@
+/** structural transport surface this subpath needs from a node. */
+export interface BlobCapableNode {
+    node_id(): string;
+    /** bulk verified download of a known blake3 hash, with progress. the
+     *  peer is asked to ensure the blob is staged before the transfer
+     *  starts. strategy 1 of `snatchBlob`/`snatchBlobToDisk`. */
+    download_verified_with_ensure_progress?(peerAddr: string, blake3Hash: string, totalSize: number, onProgress: (fraction: number) => void, downloadId?: string): Promise<Uint8Array>;
+    /** chunk-streamed verified download: each verified chunk arrives via
+     *  `onChunk` as it is read out of the peer's store, at its explicit
+     *  byte offset. strategy 2 of `snatchBlob` (chunks are accumulated into
+     *  one buffer) and the primary path of `snatchBlobToDisk` (chunks are
+     *  written straight to the caller's writable).
+     *
+     *  the chunk is always a fresh, plain-ArrayBuffer-backed view (never a
+     *  SharedArrayBuffer view) - the narrower type lets it be handed
+     *  straight to a `FileSystemWritableFileStream.write()` call without a
+     *  cast. */
+    download_verified_streaming_with_ensure?(peerAddr: string, blake3Hash: string, totalSize: number, onChunk: (chunk: Uint8Array<ArrayBuffer>, offset: number) => void, onProgress: (fraction: number) => void, downloadId?: string): Promise<number>;
+    /** unverified base64 json fallback for peers not reachable over the
+     *  verified-transfer transport at all (e.g. a desktop peer whose native
+     *  backend only accepts an app-level rpc alpn). strategy 3 - the
+     *  response has no transport-level integrity checking, so its bytes are
+     *  hash-checked explicitly against the requested blake3 before use. */
+    proxy_request?(peerAddr: string, method: string, path: string, body: string | null): Promise<{
+        status: number;
+        body: string;
+    }>;
+    /** pause/cancel an in-flight download by the id passed to it. returns
+     *  false when the download already settled. */
+    download_cancel?(downloadId: string): Promise<boolean>;
+    /** release a gc pin held by a paused/cancelled download, letting the
+     *  partial be reclaimed. */
+    unprotect_blob?(blake3Hash: string): Promise<void>;
+    /** import local bytes into the node's own store so a peer can download
+     *  them by hash. used by `BlobServer`/`serveBlobRequest`. */
+    import_blob?(data: Uint8Array): Promise<string>;
+    /** release a previously-imported blob from the node's store. used by
+     *  `BlobServer`'s release timer. */
+    release_blob?(blake3Hash: string): Promise<void> | void;
+}
+/** what a snatch needs to know about the blob being fetched. */
+export interface SnatchInfo {
+    /** app-addressable id used to build the strategy-3 proxy path (see
+     *  `SnatchOptions.proxyPath`). defaults to `blake3` when omitted - most
+     *  callers address blobs by blake3 directly. */
+    id?: string;
+    blake3: string;
+    size: number;
+    mime?: string;
+}
+export interface SnatchOptions {
+    onProgress?(fraction: number): void;
+    /** aborting rejects immediately with an AbortError - no next-peer retry,
+     *  no disk truncation (a resumed snatch rewrites the same offsets). */
+    signal?: AbortSignal;
+    /** opaque id registered with the node for this download; pass the same
+     *  id to `pauseSnatchDownload` to pause the in-flight transfer. */
+    downloadId?: string;
+    /** per-peer attempt timeout in ms. default 10 minutes - generous because
+     *  the responding peer may need to stage the blob into its own store
+     *  (bao tree computation) on first request. */
+    timeoutMs?: number;
+    /** build the http path used by the base64 `proxy_request` fallback
+     *  (strategy 3). omit to skip that strategy entirely. */
+    proxyPath?(id: string): string;
+    /** parse the strategy-3 proxy response body into its base64 payload +
+     *  mime. defaults to a flat `{ data, mime }` json shape; supply this
+     *  when the peer's rpc envelope nests differently. return null when the
+     *  response indicates no blob. */
+    parseProxyResponse?(body: string): {
+        data: string;
+        mime?: string;
+    } | null;
+}
+export interface SnatchResult {
+    bytes: Uint8Array;
+    blake3: string;
+    mime?: string;
+}
+export interface DiskSnatchResult {
+    size: number;
+    blake3: string;
+    mime?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/transfer/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/transfer/types.ts"],"names":[],"mappings":"AAeA,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,OAAO,IAAI,MAAM,CAAC;IAElB;;iEAE6D;IAC7D,sCAAsC,CAAC,CACrC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,EACtC,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,UAAU,CAAC,CAAC;IAEvB;;;;;;;;;gBASY;IACZ,uCAAuC,CAAC,CACtC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,EACjE,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,EACtC,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC,CAAC;IAEnB;;;;2EAIuE;IACvE,aAAa,CAAC,CACZ,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GAAG,IAAI,GAClB,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAE7C;mDAC+C;IAC/C,eAAe,CAAC,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEvD;gCAC4B;IAC5B,cAAc,CAAC,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnD;iEAC6D;IAC7D,WAAW,CAAC,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEhD;wCACoC;IACpC,YAAY,CAAC,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACzD;AAED,gEAAgE;AAChE,MAAM,WAAW,UAAU;IACzB;;oDAEgD;IAChD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,CAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC;2EACuE;IACvE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;uEACmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;mDAE+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;6DACyD;IACzD,SAAS,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B;;;sCAGkC;IAClC,kBAAkB,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC3E;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,UAAU,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf"}

package/dist/transfer/types.js

@@ -0,0 +1,15 @@
+// shared shapes for ./transfer: the structural transport surface this
+// subpath needs from a midden-shaped node, plus the request/result types
+// for snatch (peer -> local) and serve (local -> peer) flows.
+//
+// this subpath never imports midden at runtime - only structural types
+// matching its snake_case surface, so any BlobCapableNode-shaped object
+// (a real wasm node, a worker-backed facade, a test double) works the
+// same way. every method is optional: a caller's node may implement only
+// a subset (a lean transport, a peer reachable only via app-level rpc),
+// and each snatch strategy degrades to the next when its required method
+// is missing OR when it fails against a given peer (a peer whose backend
+// only accepts an app-level rpc alpn makes the verified strategies fail
+// even though the local node has the methods) - only a cancelled error
+// stops the fallthrough.
+export {};

package/dist/utils/hash.d.ts

@@ -0,0 +1,13 @@
+/**
+ * hash of an ArrayBuffer (or a view over one) as a lowercase hex string.
+ */
+export declare function sha256Hex(data: ArrayBuffer | ArrayBufferView): Promise<string>;
+/**
+ * hash of a File/Blob's contents as a lowercase hex string.
+ */
+export declare function sha256HexOfBlob(blob: Blob): Promise<string>;
+/**
+ * true if `data` hashes to `expectedHex` (case-insensitive).
+ */
+export declare function verifySha256Hex(data: ArrayBuffer | ArrayBufferView, expectedHex: string): Promise<boolean>;
+//# sourceMappingURL=hash.d.ts.map

package/dist/utils/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../src/utils/hash.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,WAAW,GAAG,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAMpF;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAEjE;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,WAAW,GAAG,eAAe,EACnC,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,OAAO,CAAC,CAGlB"}

package/dist/utils/hash.js

@@ -0,0 +1,31 @@
+// sha256 hashing helpers built on the web crypto subtle api. used wherever a
+// content hash is needed but the full blake3-canonical blob pipeline (./blobs,
+// ./worker) is overkill - legacy sha256 references, quick integrity checks, etc.
+/**
+ * hash of an ArrayBuffer (or a view over one) as a lowercase hex string.
+ */
+export async function sha256Hex(data) {
+    const buffer = ArrayBuffer.isView(data)
+        ? data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength)
+        : data;
+    const digest = await crypto.subtle.digest("SHA-256", buffer);
+    return bufferToHex(digest);
+}
+/**
+ * hash of a File/Blob's contents as a lowercase hex string.
+ */
+export async function sha256HexOfBlob(blob) {
+    return sha256Hex(await blob.arrayBuffer());
+}
+/**
+ * true if `data` hashes to `expectedHex` (case-insensitive).
+ */
+export async function verifySha256Hex(data, expectedHex) {
+    const actual = await sha256Hex(data);
+    return actual === expectedHex.toLowerCase();
+}
+function bufferToHex(buffer) {
+    return Array.from(new Uint8Array(buffer))
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}

package/dist/utils/hash.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=hash.test.d.ts.map

package/dist/utils/hash.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.test.d.ts","sourceRoot":"","sources":["../../src/utils/hash.test.ts"],"names":[],"mappings":""}

package/dist/utils/hash.test.js

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import { sha256Hex, sha256HexOfBlob, verifySha256Hex } from "./hash.js";
+// known-answer test vectors for sha-256
+const EMPTY_HASH = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+const ABC_HASH = "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad";
+function textToBuffer(text) {
+    return new TextEncoder().encode(text).buffer;
+}
+describe("sha256Hex", () => {
+    it("hashes an empty buffer to the well-known sha-256 empty digest", async () => {
+        const hash = await sha256Hex(new ArrayBuffer(0));
+        expect(hash).toBe(EMPTY_HASH);
+    });
+    it("hashes 'abc' to its well-known sha-256 digest", async () => {
+        const hash = await sha256Hex(textToBuffer("abc"));
+        expect(hash).toBe(ABC_HASH);
+    });
+    it("accepts an ArrayBufferView (Uint8Array) as well as a raw ArrayBuffer", async () => {
+        const bytes = new TextEncoder().encode("abc");
+        const hash = await sha256Hex(bytes);
+        expect(hash).toBe(ABC_HASH);
+    });
+    it("only hashes the view's byte range, not the whole underlying buffer", async () => {
+        const backing = new Uint8Array(10);
+        backing.set(new TextEncoder().encode("abc"), 2);
+        const view = new Uint8Array(backing.buffer, 2, 3);
+        const hash = await sha256Hex(view);
+        expect(hash).toBe(ABC_HASH);
+    });
+    it("produces different hashes for different inputs", async () => {
+        const a = await sha256Hex(textToBuffer("hello"));
+        const b = await sha256Hex(textToBuffer("world"));
+        expect(a).not.toBe(b);
+    });
+});
+describe("sha256HexOfBlob", () => {
+    it("hashes a Blob's contents the same as its raw bytes", async () => {
+        const blob = new Blob(["abc"]);
+        const hash = await sha256HexOfBlob(blob);
+        expect(hash).toBe(ABC_HASH);
+    });
+});
+describe("verifySha256Hex", () => {
+    it("returns true when the expected hash matches", async () => {
+        const ok = await verifySha256Hex(textToBuffer("abc"), ABC_HASH);
+        expect(ok).toBe(true);
+    });
+    it("returns false when the expected hash does not match", async () => {
+        const ok = await verifySha256Hex(textToBuffer("abc"), EMPTY_HASH);
+        expect(ok).toBe(false);
+    });
+    it("is case-insensitive when comparing the expected hash", async () => {
+        const ok = await verifySha256Hex(textToBuffer("abc"), ABC_HASH.toUpperCase());
+        expect(ok).toBe(true);
+    });
+});

package/dist/utils/image-utils.d.ts

@@ -0,0 +1,28 @@
+/**
+ * options for picking and resizing an image file.
+ */
+export interface PickImageOptions {
+    /** maximum output width in pixels (default: 200) */
+    maxWidth?: number;
+    /** maximum output height in pixels (default: 200) */
+    maxHeight?: number;
+    /** output quality 0-1, for lossy formats like webp/jpeg (default: 0.8) */
+    quality?: number;
+    /** if true, center-crop to a square before resizing (default: false) */
+    cropSquare?: boolean;
+    /** output mime type (default: "image/webp") */
+    mime?: string;
+}
+/**
+ * open a native file picker for images, resize and encode as a data url.
+ * returns null if the user cancels, the input never resolves, or an error
+ * occurs.
+ */
+export declare function pickImageAsDataUrl(options?: PickImageOptions): Promise<string | null>;
+/**
+ * resize an image File/Blob to a data url. useful when a file is already in
+ * hand (e.g. from drag-and-drop). returns null on error, or if the current
+ * environment has no OffscreenCanvas/createImageBitmap support.
+ */
+export declare function resizeImageToDataUrl(blob: Blob, options?: PickImageOptions): Promise<string | null>;
+//# sourceMappingURL=image-utils.d.ts.map

package/dist/utils/image-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-utils.d.ts","sourceRoot":"","sources":["../../src/utils/image-utils.ts"],"names":[],"mappings":"AAMA;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAOD;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAmC3F;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,IAAI,EACV,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAsDxB"}

package/dist/utils/image-utils.js

@@ -0,0 +1,113 @@
+// helpers for picking an image file from the user's device and converting it
+// to a small webp data url. resizing runs on the main thread via
+// OffscreenCanvas/createImageBitmap; a worker-backed variant that keeps the
+// decode/encode work off the main thread can build on top of this once the
+// ./worker subpath exists.
+const DEFAULT_MAX_WIDTH = 200;
+const DEFAULT_MAX_HEIGHT = 200;
+const DEFAULT_QUALITY = 0.8;
+const DEFAULT_MIME = "image/webp";
+/**
+ * open a native file picker for images, resize and encode as a data url.
+ * returns null if the user cancels, the input never resolves, or an error
+ * occurs.
+ */
+export async function pickImageAsDataUrl(options) {
+    const input = document.createElement("input");
+    input.type = "file";
+    input.accept = "image/*";
+    input.style.display = "none";
+    document.body.appendChild(input);
+    try {
+        input.click();
+        const file = await new Promise((resolve) => {
+            input.addEventListener("change", () => {
+                resolve(input.files?.[0] ?? null);
+            });
+            // the `cancel` event is the standard way to detect picker dismissal.
+            // it is supported in chrome 113+ and firefox 113+. older browsers that
+            // don't fire `cancel` will leave this promise pending until the page
+            // navigates - acceptable because pickImageAsDataUrl is always called in
+            // a fire-and-forget context and callers re-enable the trigger on each
+            // interaction.
+            input.addEventListener("cancel", () => resolve(null));
+        });
+        if (!file) {
+            return null;
+        }
+        return await resizeImageToDataUrl(file, options);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        input.remove();
+    }
+}
+/**
+ * resize an image File/Blob to a data url. useful when a file is already in
+ * hand (e.g. from drag-and-drop). returns null on error, or if the current
+ * environment has no OffscreenCanvas/createImageBitmap support.
+ */
+export async function resizeImageToDataUrl(blob, options) {
+    if (typeof OffscreenCanvas === "undefined" || typeof createImageBitmap !== "function") {
+        return null;
+    }
+    const maxWidth = options?.maxWidth ?? DEFAULT_MAX_WIDTH;
+    const maxHeight = options?.maxHeight ?? DEFAULT_MAX_HEIGHT;
+    const quality = options?.quality ?? DEFAULT_QUALITY;
+    const cropSquare = options?.cropSquare ?? false;
+    const mime = options?.mime ?? DEFAULT_MIME;
+    let bitmap = null;
+    try {
+        bitmap = await createImageBitmap(blob);
+        let sx = 0;
+        let sy = 0;
+        let sw = bitmap.width;
+        let sh = bitmap.height;
+        if (cropSquare) {
+            const minDim = Math.min(bitmap.width, bitmap.height);
+            sx = (bitmap.width - minDim) / 2;
+            sy = (bitmap.height - minDim) / 2;
+            sw = minDim;
+            sh = minDim;
+        }
+        const aspect = sw / sh;
+        let outW = sw;
+        let outH = sh;
+        if (outW > maxWidth) {
+            outW = maxWidth;
+            outH = Math.round(outW / aspect);
+        }
+        if (outH > maxHeight) {
+            outH = maxHeight;
+            outW = Math.round(outH * aspect);
+        }
+        outW = Math.max(1, outW);
+        outH = Math.max(1, outH);
+        const canvas = new OffscreenCanvas(outW, outH);
+        const ctx = canvas.getContext("2d");
+        if (!ctx)
+            return null;
+        ctx.drawImage(bitmap, sx, sy, sw, sh, 0, 0, outW, outH);
+        const out = await canvas.convertToBlob({ type: mime, quality });
+        const buffer = await out.arrayBuffer();
+        return `data:${mime};base64,${arrayBufferToBase64(buffer)}`;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        bitmap?.close();
+    }
+}
+function arrayBufferToBase64(buffer) {
+    const bytes = new Uint8Array(buffer);
+    const chunkSize = 0x8000;
+    let binary = "";
+    for (let i = 0; i < bytes.length; i += chunkSize) {
+        const chunk = bytes.subarray(i, i + chunkSize);
+        binary += String.fromCharCode(...chunk);
+    }
+    return btoa(binary);
+}

package/dist/utils/image-utils.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=image-utils.test.d.ts.map

package/dist/utils/image-utils.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-utils.test.d.ts","sourceRoot":"","sources":["../../src/utils/image-utils.test.ts"],"names":[],"mappings":""}

package/dist/utils/image-utils.test.js

@@ -0,0 +1,181 @@
+// @vitest-environment happy-dom
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { pickImageAsDataUrl, resizeImageToDataUrl } from "./image-utils.js";
+// happy-dom provides `document` and the File/Blob constructors, but not canvas
+// rasterization (OffscreenCanvas, createImageBitmap) - no environment does that
+// without native bindings. these fakes stand in for the browser's actual image
+// decode/encode pipeline so the surrounding sizing/cropping/error-handling logic
+// gets real coverage without a native canvas dependency.
+class FakeImageBitmap {
+    width;
+    height;
+    constructor(width, height) {
+        this.width = width;
+        this.height = height;
+    }
+    close = vi.fn();
+}
+class FakeOffscreenCanvasContext {
+    drawImage = vi.fn();
+}
+class FakeOffscreenCanvas {
+    width;
+    height;
+    static instances = [];
+    context = new FakeOffscreenCanvasContext();
+    convertToBlobResult = new Blob(["fake-encoded-bytes"], { type: "image/webp" });
+    constructor(width, height) {
+        this.width = width;
+        this.height = height;
+        FakeOffscreenCanvas.instances.push(this);
+    }
+    getContext() {
+        return this.context;
+    }
+    async convertToBlob(options) {
+        if (!this.convertToBlobResult)
+            throw new Error("encode failed");
+        return new Blob(["fake-encoded-bytes"], { type: options?.type ?? "image/webp" });
+    }
+}
+function installCanvasFakes(bitmapSize) {
+    vi.stubGlobal("createImageBitmap", vi.fn(async () => new FakeImageBitmap(bitmapSize.width, bitmapSize.height)));
+    vi.stubGlobal("OffscreenCanvas", FakeOffscreenCanvas);
+}
+afterEach(() => {
+    vi.unstubAllGlobals();
+    FakeOffscreenCanvas.instances = [];
+});
+describe("resizeImageToDataUrl", () => {
+    it("returns null when OffscreenCanvas/createImageBitmap are unavailable", async () => {
+        const result = await resizeImageToDataUrl(new Blob(["x"], { type: "image/png" }));
+        expect(result).toBeNull();
+    });
+    it("returns a data url with the requested (default) mime type", async () => {
+        installCanvasFakes({ width: 400, height: 300 });
+        const result = await resizeImageToDataUrl(new Blob(["x"], { type: "image/png" }));
+        expect(result).toMatch(/^data:image\/webp;base64,/);
+    });
+    it("downscales to fit within maxWidth/maxHeight while preserving aspect ratio", async () => {
+        installCanvasFakes({ width: 400, height: 200 });
+        await resizeImageToDataUrl(new Blob(["x"]), { maxWidth: 100, maxHeight: 100 });
+        const canvas = FakeOffscreenCanvas.instances[0];
+        expect(canvas.width).toBe(100);
+        expect(canvas.height).toBe(50);
+    });
+    it("does not upscale images smaller than the max bounds", async () => {
+        installCanvasFakes({ width: 50, height: 40 });
+        await resizeImageToDataUrl(new Blob(["x"]), { maxWidth: 200, maxHeight: 200 });
+        const canvas = FakeOffscreenCanvas.instances[0];
+        expect(canvas.width).toBe(50);
+        expect(canvas.height).toBe(40);
+    });
+    it("center-crops to a square when cropSquare is set", async () => {
+        installCanvasFakes({ width: 400, height: 200 });
+        await resizeImageToDataUrl(new Blob(["x"]), { cropSquare: true, maxWidth: 200, maxHeight: 200 });
+        const canvas = FakeOffscreenCanvas.instances[0];
+        expect(canvas.width).toBe(200);
+        expect(canvas.height).toBe(200);
+        expect(canvas.context.drawImage).toHaveBeenCalledWith(expect.anything(), 100, // sx: (400 - 200) / 2
+        0, // sy: (200 - 200) / 2
+        200, // sw
+        200, // sh
+        0, 0, 200, 200);
+    });
+    it("passes the requested mime type and quality through to the encoder", async () => {
+        installCanvasFakes({ width: 100, height: 100 });
+        const result = await resizeImageToDataUrl(new Blob(["x"]), {
+            mime: "image/jpeg",
+            quality: 0.5,
+        });
+        expect(result).toMatch(/^data:image\/jpeg;base64,/);
+    });
+    it("closes the decoded bitmap even when encoding succeeds", async () => {
+        installCanvasFakes({ width: 100, height: 100 });
+        const bitmaps = [];
+        vi.stubGlobal("createImageBitmap", vi.fn(async () => {
+            const bmp = new FakeImageBitmap(100, 100);
+            bitmaps.push(bmp);
+            return bmp;
+        }));
+        await resizeImageToDataUrl(new Blob(["x"]));
+        expect(bitmaps[0].close).toHaveBeenCalledTimes(1);
+    });
+    it("returns null and still closes the bitmap when getContext returns null", async () => {
+        installCanvasFakes({ width: 100, height: 100 });
+        const bitmaps = [];
+        vi.stubGlobal("createImageBitmap", vi.fn(async () => {
+            const bmp = new FakeImageBitmap(100, 100);
+            bitmaps.push(bmp);
+            return bmp;
+        }));
+        vi.spyOn(FakeOffscreenCanvas.prototype, "getContext").mockReturnValueOnce(null);
+        const result = await resizeImageToDataUrl(new Blob(["x"]));
+        expect(result).toBeNull();
+        expect(bitmaps[0].close).toHaveBeenCalledTimes(1);
+    });
+    it("returns null when createImageBitmap rejects (e.g. non-image input)", async () => {
+        vi.stubGlobal("createImageBitmap", vi.fn(async () => {
+            throw new Error("not an image");
+        }));
+        vi.stubGlobal("OffscreenCanvas", FakeOffscreenCanvas);
+        const result = await resizeImageToDataUrl(new Blob(["not an image"]));
+        expect(result).toBeNull();
+    });
+});
+describe("pickImageAsDataUrl", () => {
+    function captureInput() {
+        let captured = null;
+        const realCreateElement = document.createElement.bind(document);
+        vi.spyOn(document, "createElement").mockImplementation((tag) => {
+            const el = realCreateElement(tag);
+            if (tag === "input")
+                captured = el;
+            return el;
+        });
+        return {
+            getInput: () => {
+                if (!captured)
+                    throw new Error("input was never created");
+                return captured;
+            },
+        };
+    }
+    it("resolves with the resized data url when a file is chosen", async () => {
+        installCanvasFakes({ width: 100, height: 100 });
+        const { getInput } = captureInput();
+        const promise = pickImageAsDataUrl();
+        const input = getInput();
+        const file = new File(["x"], "photo.png", { type: "image/png" });
+        Object.defineProperty(input, "files", { value: [file], configurable: true });
+        input.dispatchEvent(new Event("change"));
+        const result = await promise;
+        expect(result).toMatch(/^data:image\/webp;base64,/);
+    });
+    it("resolves with null when the picker is cancelled", async () => {
+        const { getInput } = captureInput();
+        const promise = pickImageAsDataUrl();
+        const input = getInput();
+        input.dispatchEvent(new Event("cancel"));
+        const result = await promise;
+        expect(result).toBeNull();
+    });
+    it("resolves with null when the change event fires with no file selected", async () => {
+        const { getInput } = captureInput();
+        const promise = pickImageAsDataUrl();
+        const input = getInput();
+        Object.defineProperty(input, "files", { value: [], configurable: true });
+        input.dispatchEvent(new Event("change"));
+        const result = await promise;
+        expect(result).toBeNull();
+    });
+    it("removes the temporary input element after resolving", async () => {
+        const { getInput } = captureInput();
+        const promise = pickImageAsDataUrl();
+        const input = getInput();
+        expect(document.body.contains(input)).toBe(true);
+        input.dispatchEvent(new Event("cancel"));
+        await promise;
+        expect(document.body.contains(input)).toBe(false);
+    });
+});

package/dist/utils/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./hash.js";
+export * from "./image-utils.js";
+export * from "./log.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC"}

package/dist/utils/index.js

@@ -0,0 +1,3 @@
+export * from "./hash.js";
+export * from "./image-utils.js";
+export * from "./log.js";

package/dist/utils/log.d.ts

@@ -0,0 +1,22 @@
+export type LogLevel = "trace" | "debug" | "info" | "warn" | "error";
+export interface LoggingConfig {
+    level?: LogLevel;
+    /** tag prefixes to allow; an empty array (or omitting this) allows every tag. */
+    filter?: string[];
+}
+/**
+ * set the default log level and/or tag filter. intended to be called once at
+ * app startup; localStorage overrides (if present) still take priority so
+ * logging can be adjusted at runtime without a rebuild.
+ */
+export declare function configureLogging(config: LoggingConfig): void;
+/** clear any configureLogging() overrides, restoring the built-in default. */
+export declare function resetLoggingConfig(): void;
+export declare const log: {
+    trace: (tag: string, msg: string, ...args: unknown[]) => void;
+    debug: (tag: string, msg: string, ...args: unknown[]) => void;
+    info: (tag: string, msg: string, ...args: unknown[]) => void;
+    warn: (tag: string, msg: string, ...args: unknown[]) => void;
+    error: (tag: string, msg: string, ...args: unknown[]) => void;
+};
+//# sourceMappingURL=log.d.ts.map

package/dist/utils/log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../../src/utils/log.ts"],"names":[],"mappings":"AA4BA,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAErE,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAeD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAG5D;AAED,8EAA8E;AAC9E,wBAAgB,kBAAkB,IAAI,IAAI,CAGzC;AAyCD,eAAO,MAAM,GAAG;iBACD,MAAM,OAAO,MAAM,WAAW,OAAO,EAAE,KAAG,IAAI;iBAC9C,MAAM,OAAO,MAAM,WAAW,OAAO,EAAE,KAAG,IAAI;gBAC/C,MAAM,OAAO,MAAM,WAAW,OAAO,EAAE,KAAG,IAAI;gBAC9C,MAAM,OAAO,MAAM,WAAW,OAAO,EAAE,KAAG,IAAI;iBAC7C,MAAM,OAAO,MAAM,WAAW,OAAO,EAAE,KAAG,IAAI;CAC5D,CAAC"}