@entropy-softworks/ui 2026.8.41 → 2026.9.1

package/src/hooks/__tests__/useUploadBlobUrl.test.tsx

@@ -1,27 +1,44 @@
 /**
- * Behavioural tests for `useUploadBlobUrl`. The hook is exercised
- * through `renderHook` from `@testing-library/react-native`, with the
- * package's `apiFetch` mocked so we can drive successful and failing
- * upload fetches deterministically.
+ * Behavioural tests for `useUploadBlobUrl`.
+ *
+ * The platform branch is the point of most of these: `URL.createObjectURL` is
+ * a browser API that React Native does not implement usably, so web gets a
+ * blob URL and native gets a data URI. `react-native` is mocked down to a
+ * mutable `Platform` so one file can drive both.
  */
 import { act, renderHook, waitFor } from "@testing-library/react-native";
+import { Platform } from "react-native";
 
 import { apiFetch } from "../../utils/api-fetch";
 import { useUploadBlobUrl } from "../useUploadBlobUrl";
 
+// Only `Platform` is reached from the hook. A full react-native mock would be
+// a much bigger surface to keep true than this needs.
+jest.mock("react-native", () => ({ Platform: { OS: "ios" } }));
+
 jest.mock("../../utils/api-fetch", () => ({
   apiFetch: jest.fn(),
 }));
 
 const apiFetchMock = apiFetch as jest.MockedFunction<typeof apiFetch>;
+const mutablePlatform = Platform as { OS: string };
 
 const originalCreateObjectURL = globalThis.URL.createObjectURL;
 const originalRevokeObjectURL = globalThis.URL.revokeObjectURL;
 let urlCounter = 0;
 const revokedUrls: string[] = [];
 
+/** A PNG-flavoured response, headers included — the data URI carries its type. */
+function imageResponse(bytes: number[], contentType = "image/png"): Response {
+  return new Response(Uint8Array.from(bytes), {
+    status: 200,
+    headers: { "Content-Type": contentType },
+  });
+}
+
 beforeEach(() => {
   apiFetchMock.mockReset();
+  mutablePlatform.OS = "ios";
   urlCounter = 0;
   revokedUrls.length = 0;
   globalThis.URL.createObjectURL = jest.fn(() => `blob:test/${++urlCounter}`);
@@ -41,29 +58,46 @@ describe("useUploadBlobUrl", () => {
     expect(result.current.errored).toBe(false);
   });
 
-  it("resolves a blob URL on a successful fetch", async () => {
-    apiFetchMock.mockResolvedValueOnce(new Response(new Blob(["ok"]), { status: 200 }));
+  it("builds a data URI on native, carrying the response's content type", async () => {
+    // "ok" — short enough to check the base64 by eye.
+    apiFetchMock.mockResolvedValueOnce(imageResponse([0x6f, 0x6b], "image/webp"));
     const { result } = renderHook(() => useUploadBlobUrl("abc"));
     await waitFor(() => {
-      expect(result.current.uri).toMatch(/^blob:test\//);
+      expect(result.current.uri).toBe("data:image/webp;base64,b2s=");
     });
     expect(result.current.errored).toBe(false);
+    // Never `createObjectURL` on native: that is the whole bug this replaced.
+    expect(globalThis.URL.createObjectURL).not.toHaveBeenCalled();
   });
 
-  it("marks errored when the fetch fails", async () => {
-    apiFetchMock.mockResolvedValueOnce(new Response("nope", { status: 500 }));
-    const { result } = renderHook(() => useUploadBlobUrl("abc"));
-    await waitFor(() => {
-      expect(result.current.errored).toBe(true);
-    });
-    expect(result.current.uri).toBeNull();
+  it("encodes every remainder length correctly", async () => {
+    // Base64 pads by input length mod 3, and the two padded cases take
+    // different branches. Byte values chosen so a bit-shift slip shows up as a
+    // wrong character rather than a coincidentally-right one.
+    const cases: [number[], string][] = [
+      [[0xff], "/w=="],
+      [[0xff, 0xee], "/+4="],
+      [[0xff, 0xee, 0xdd], "/+7d"],
+      [[0x00, 0x00, 0x00, 0x01], "AAAAAQ=="],
+    ];
+    for (const [bytes, expected] of cases) {
+      apiFetchMock.mockResolvedValueOnce(imageResponse(bytes));
+      const { result, unmount } = renderHook(() => useUploadBlobUrl(`id-${expected}`));
+      await waitFor(() => {
+        expect(result.current.uri).toBe(`data:image/png;base64,${expected}`);
+      });
+      act(() => {
+        unmount();
+      });
+    }
   });
 
-  it("revokes the blob URL on unmount", async () => {
+  it("keeps the blob URL on web, and revokes it on unmount", async () => {
+    mutablePlatform.OS = "web";
     apiFetchMock.mockResolvedValueOnce(new Response(new Blob(["ok"]), { status: 200 }));
     const { result, unmount } = renderHook(() => useUploadBlobUrl("abc"));
     await waitFor(() => {
-      expect(result.current.uri).not.toBeNull();
+      expect(result.current.uri).toMatch(/^blob:test\//);
     });
     const uri = result.current.uri;
     if (uri === null) {
@@ -72,6 +106,84 @@ describe("useUploadBlobUrl", () => {
     act(() => {
       unmount();
     });
+    // The revoke matters on web and only on web — a data URI is a string with
+    // nothing to release.
     expect(revokedUrls).toContain(uri);
   });
+
+  it("marks errored when the fetch fails", async () => {
+    apiFetchMock.mockResolvedValueOnce(new Response("nope", { status: 500 }));
+    const { result } = renderHook(() => useUploadBlobUrl("abc"));
+    await waitFor(() => {
+      expect(result.current.errored).toBe(true);
+    });
+    expect(result.current.uri).toBeNull();
+  });
+
+  describe("with a consumer-supplied resolver", () => {
+    it("uses it instead of the transport", async () => {
+      const resolve = jest.fn().mockResolvedValue("data:image/png;base64,AAAA");
+      const { result } = renderHook(() => useUploadBlobUrl("abc", { resolve }));
+
+      await waitFor(() => {
+        expect(result.current.uri).toBe("data:image/png;base64,AAAA");
+      });
+      expect(resolve).toHaveBeenCalledWith("abc", expect.any(AbortSignal));
+      // The reason the seam exists: a consumer whose uploads are not behind a
+      // server must not have one asked.
+      expect(apiFetchMock).not.toHaveBeenCalled();
+    });
+
+    it("reports an unresolvable id as errored so the fallback is drawn", async () => {
+      const resolve = jest.fn().mockResolvedValue(null);
+      const { result } = renderHook(() => useUploadBlobUrl("gone", { resolve }));
+      await waitFor(() => {
+        expect(result.current.errored).toBe(true);
+      });
+      expect(result.current.uri).toBeNull();
+    });
+
+    it("reports a throwing resolver as errored rather than crashing the tree", async () => {
+      const resolve = jest.fn().mockRejectedValue(new Error("database is closed"));
+      const { result } = renderHook(() => useUploadBlobUrl("abc", { resolve }));
+      await waitFor(() => {
+        expect(result.current.errored).toBe(true);
+      });
+    });
+
+    it("does not re-resolve when only the resolver's identity changes", async () => {
+      // The hazard this guards: an inline arrow at the call site is a new
+      // function every render, and a resolver in the effect's deps would turn
+      // that into an unbounded refetch loop. What identifies the resource is
+      // the id.
+      const first = jest.fn().mockResolvedValue("data:image/png;base64,AAAA");
+      const { result, rerender } = renderHook(
+        ({ resolve }: { resolve: jest.Mock }) => useUploadBlobUrl("abc", { resolve }),
+        { initialProps: { resolve: first } }
+      );
+      await waitFor(() => {
+        expect(result.current.uri).not.toBeNull();
+      });
+
+      const second = jest.fn().mockResolvedValue("data:image/png;base64,BBBB");
+      act(() => {
+        rerender({ resolve: second });
+        rerender({ resolve: jest.fn() });
+      });
+
+      expect(first).toHaveBeenCalledTimes(1);
+      expect(second).not.toHaveBeenCalled();
+    });
+
+    it("still accepts a bare path as the second argument", async () => {
+      // The published signature was `(uploadId, uploadsPath?)`; other
+      // consumers are on it.
+      apiFetchMock.mockResolvedValueOnce(imageResponse([0x6f, 0x6b]));
+      const { result } = renderHook(() => useUploadBlobUrl("abc", "/attachments"));
+      await waitFor(() => {
+        expect(result.current.uri).not.toBeNull();
+      });
+      expect(apiFetchMock).toHaveBeenCalledWith("/attachments/abc", expect.anything());
+    });
+  });
 });

package/src/hooks/index.ts

@@ -16,7 +16,12 @@ export { useDebouncedValue } from "./useDebouncedValue";
 
 export { useAutoLock, type UseAutoLockOptions } from "./useAutoLock";
 
-export { useUploadBlobUrl, type UploadBlobUrlResult } from "./useUploadBlobUrl";
+export {
+  type UploadBlobUrlOptions,
+  type UploadBlobUrlResult,
+  type UploadResolver,
+  useUploadBlobUrl,
+} from "./useUploadBlobUrl";
 
 export {
   usePasswordGenerator,

package/src/hooks/useUploadBlobUrl.ts

@@ -1,4 +1,5 @@
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
+import { Platform } from "react-native";
 import { apiFetch } from "../utils/api-fetch";
 
 const FETCH_TIMEOUT_MS = 15_000;
@@ -10,18 +11,72 @@ export interface UploadBlobUrlResult {
 }
 
 /**
- * Fetch an authenticated upload via `apiFetch`, expose a blob URL the
- * caller can hand to an `<Image>` / `<img>`. Cancels in-flight on input
- * change and revokes the URL on unmount so list scrolling doesn't leak
- * memory.
+ * Produce a renderable URI for an upload id without going through
+ * `apiFetch`.
+ *
+ * For a consumer that keeps uploads somewhere this package cannot reach — an
+ * on-device database, a cache it populated itself — the resolver is the whole
+ * seam. Return `null` for an id that does not resolve; the hook reports that
+ * as `errored`, which is what a renderer draws its fallback on.
+ *
+ * The `signal` aborts with the effect, so a resolver doing real work can stop
+ * when the row scrolls away.
+ */
+export type UploadResolver = (uploadId: string, signal: AbortSignal) => Promise<string | null>;
+
+export interface UploadBlobUrlOptions {
+  /** Upload-fetch path prefix. Defaults to `/uploads`. */
+  uploadsPath?: string;
+  /**
+   * Resolve the URI yourself instead of fetching it.
+   *
+   * Identity does not have to be stable: the resolver is held in a ref and
+   * only `uploadId` / `uploadsPath` re-run the effect. An inline arrow would
+   * otherwise refetch on every render, and what identifies the resource is the
+   * id, not the function that happens to fetch it.
+   */
+  resolve?: UploadResolver;
+}
+
+/**
+ * A URI for an upload, fetched through `apiFetch` unless the consumer resolves
+ * it itself.
+ *
+ * # Web gets a blob URL; native gets a data URI
+ *
+ * `URL.createObjectURL` is a browser API. React Native's `URL` does not
+ * implement it in any way that can be relied on across both platforms — so on
+ * native this hook used to hand `<Image>` a URI built by a function that
+ * either threw or produced something the image loader could not open, and the
+ * fetch fell into the `catch` below. The visible symptom was that custom
+ * uploaded icons never appeared on a phone: they resolved to the fallback
+ * glyph every time, on every consumer, and looked like a missing-image problem
+ * rather than a URL one.
+ *
+ * Native therefore reads the bytes and builds `data:<type>;base64,…`, which
+ * every RN image loader accepts. The cost is that base64 inflates by a third
+ * and the string sits in the JS heap for as long as the row is mounted, which
+ * is affordable for the icons this exists to draw (the vault caps an upload at
+ * 256KB) and is why web keeps the blob URL — no copy, and revocable.
+ *
+ * The second argument accepts a bare path for backwards compatibility with
+ * `useUploadBlobUrl(id, "/uploads")`; new call sites should pass options.
  */
 export function useUploadBlobUrl(
   uploadId: string | null | undefined,
-  uploadsPath = "/uploads"
+  options: string | UploadBlobUrlOptions = {}
 ): UploadBlobUrlResult {
+  const { uploadsPath = "/uploads", resolve } =
+    typeof options === "string" ? { uploadsPath: options, resolve: undefined } : options;
+
   const [uri, setUri] = useState<string | null>(null);
   const [errored, setErrored] = useState(false);
 
+  // See `UploadBlobUrlOptions.resolve`: kept in a ref so a resolver defined
+  // inline at the call site cannot turn every render into a refetch.
+  const resolveRef = useRef<UploadResolver | undefined>(resolve);
+  resolveRef.current = resolve;
+
   useEffect(() => {
     setErrored(false);
     if (!uploadId) {
@@ -33,21 +88,55 @@ export function useUploadBlobUrl(
     const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
     let createdUrl: string | null = null;
 
-    apiFetch(`${uploadsPath}/${encodeURIComponent(uploadId)}`, { signal: controller.signal })
-      .then(async (response) => {
+    const load = async (): Promise<string | null> => {
+      const resolver = resolveRef.current;
+      if (resolver) {
+        return resolver(uploadId, controller.signal);
+      }
+
+      const response = await apiFetch(`${uploadsPath}/${encodeURIComponent(uploadId)}`, {
+        signal: controller.signal,
+      });
+      if (controller.signal.aborted) {
+        return null;
+      }
+      if (!response.ok) {
+        throw new Error(`Failed to load upload (${response.status})`);
+      }
+
+      if (Platform.OS === "web") {
+        const blob = await response.blob();
         if (controller.signal.aborted) {
-          return;
-        }
-        if (!response.ok) {
-          throw new Error(`Failed to load upload (${response.status})`);
+          return null;
         }
-        const blob = await response.blob();
+        createdUrl = URL.createObjectURL(blob);
+        return createdUrl;
+      }
+
+      const bytes = new Uint8Array(await response.arrayBuffer());
+      if (controller.signal.aborted) {
+        return null;
+      }
+      // The server sends the stored content type; anything else is a server
+      // that has lost track of what it is holding, and `<Image>` will refuse
+      // the URI rather than guess — which surfaces as the fallback glyph, the
+      // same outcome a failed fetch gives.
+      const contentType = response.headers.get("content-type") ?? "application/octet-stream";
+      return `data:${contentType};base64,${toBase64(bytes)}`;
+    };
+
+    load()
+      .then((next) => {
         if (controller.signal.aborted) {
           return;
         }
-        const url = URL.createObjectURL(blob);
-        createdUrl = url;
-        setUri(url);
+        if (next === null) {
+          // A resolver that has nothing for this id, or an aborted read. Either
+          // way there is no image, which is what `errored` means to a renderer.
+          setErrored(true);
+          return;
+        }
+        setUri(next);
       })
       .catch((e: unknown) => {
         if (controller.signal.aborted) {
@@ -73,3 +162,38 @@ export function useUploadBlobUrl(
 
   return { uri, errored, setErrored };
 }
+
+const BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+/**
+ * Base64, without depending on the host having `btoa`.
+ *
+ * React Native ships no `btoa`, and whether one exists depends entirely on
+ * which polyfill the consuming app happened to install — a library cannot
+ * assume it. Encoding by hand is a dozen lines and removes the question.
+ *
+ * The `?? 0` on the tail bytes is the padding rule rather than a guard: base64
+ * completes a short final group with zero bits and then marks the missing
+ * bytes with `=`. Reading past the end is therefore correct here, and doing it
+ * this way keeps the loop free of the non-null assertions
+ * `noUncheckedIndexedAccess` would otherwise demand at every lookup.
+ */
+function toBase64(bytes: Uint8Array): string {
+  const chars: string[] = [];
+
+  for (let index = 0; index < bytes.length; index += 3) {
+    const b0 = bytes[index] ?? 0;
+    const b1 = bytes[index + 1] ?? 0;
+    const b2 = bytes[index + 2] ?? 0;
+    const remaining = bytes.length - index;
+
+    chars.push(
+      BASE64_ALPHABET.charAt(b0 >> 2),
+      BASE64_ALPHABET.charAt(((b0 & 3) << 4) | (b1 >> 4)),
+      remaining > 1 ? BASE64_ALPHABET.charAt(((b1 & 15) << 2) | (b2 >> 6)) : "=",
+      remaining > 2 ? BASE64_ALPHABET.charAt(b2 & 63) : "="
+    );
+  }
+
+  return chars.join("");
+}