@entropy-softworks/ui 2026.8.41 → 2026.8.42

package/CHANGELOG.md

@@ -7,151 +7,161 @@ are CalVer — `YYYY.M.D` of the publish date, with leading zeros dropped (npm's
 them), matching the `entropy-auth` crate. The `0.1.0` entry below predates the switch and was never
 published to npm.
 
+## 2026.8.42
+
+### Fixed
+
+- Custom uploaded icons never rendered on a phone. `useUploadBlobUrl` built its URI with
+  `URL.createObjectURL`, which is a browser API — React Native's `URL` does not implement it in any
+  way that can be relied on, so the call either threw or produced something no image loader would
+  open, and every upload fell through to the fallback glyph on every native consumer. Web still gets
+  a blob URL (no copy, and revocable); native now reads the bytes and builds
+  `data:<type>;base64,...`, which every RN image loader accepts. Base64 inflates by a third and the
+  string lives as long as the row is mounted, which is affordable for icons — vault caps an upload
+  at 256KB — and is why the two platforms differ rather than both taking the data URI.
+- The base64 encoder is hand-rolled rather than `btoa`. React Native ships no `btoa`, so whether one
+  exists depends on which polyfill the consuming app installed, which is not something a library can
+  assume.
+
+### Added
+
+- `useUploadBlobUrl` takes an options object — `{ uploadsPath, resolve }` — in place of the bare
+  path, which still works. `resolve` produces the URI for an upload id without going through
+  `apiFetch` at all, for a consumer whose uploads are not behind a server: vault's device-only
+  vaults keep theirs in on-device SQLite. Returning `null` reports `errored`, so an id that does not
+  resolve draws the same fallback a failed fetch does. The resolver is held in a ref and only
+  `uploadId` / `uploadsPath` re-run the effect, so an arrow defined inline at the call site cannot
+  turn every render into a refetch.
+- `ItemIcon` takes `resolveUpload`, passed straight through. Without it such a consumer had to
+  pre-resolve the reference into a `data:` URI and hand it over as `iconUrl` — which works only
+  because anything that is not `custom:` is treated as a plain URL, and hides the intent completely.
+
 ## 2026.8.41
 
 ### Fixed
 
-- `AuthScreen`'s form-height lock skipped its measuring pass for any consumer
-  that resolves `signUpEnabled` asynchronously. `probed` was initialised from
-  `signUpEnabled`, which is right when the consumer knows its registration
-  policy at mount — but one that has to ASK for it (Access's portal fetches the
-  tenant's policy and starts at the conservative "closed") mounted with sign-up
-  off, skipped the pre-measure, and turned sign-up on a moment later with
-  nothing measured. The first real toggle was then the one that grew the card:
-  it resized once, then held still forever, which is exactly the symptom the
-  lock exists to remove. The probe now re-arms on the false -> true edge.
+- `AuthScreen`'s form-height lock skipped its measuring pass for any consumer that resolves
+  `signUpEnabled` asynchronously. `probed` was initialised from `signUpEnabled`, which is right when
+  the consumer knows its registration policy at mount — but one that has to ASK for it (Access's
+  portal fetches the tenant's policy and starts at the conservative "closed") mounted with sign-up
+  off, skipped the pre-measure, and turned sign-up on a moment later with nothing measured. The
+  first real toggle was then the one that grew the card: it resized once, then held still forever,
+  which is exactly the symptom the lock exists to remove. The probe now re-arms on the false -> true
+  edge.
 
 ## 2026.8.40
 
 ### Added
 
-- `AuthScreen` takes `lockFormHeight` (default `true`). The card reserves the
-  height of the taller of Sign In / Sign Up so the two toggle without the
-  layout moving; the cost is slack, left as empty space above the shorter
-  mode's submit button. Where Sign Up carries several more fields that gap is
-  the more visible flaw of the two — most people only ever sign in, and they
-  all see it — so a consumer can now let the card resize instead. The body is
-  already wrapped in a layout animation, so the change eases rather than jumps.
+- `AuthScreen` takes `lockFormHeight` (default `true`). The card reserves the height of the taller
+  of Sign In / Sign Up so the two toggle without the layout moving; the cost is slack, left as empty
+  space above the shorter mode's submit button. Where Sign Up carries several more fields that gap
+  is the more visible flaw of the two — most people only ever sign in, and they all see it — so a
+  consumer can now let the card resize instead. The body is already wrapped in a layout animation,
+  so the change eases rather than jumps.
 
 ## 2026.8.39
 
 ### Added
 
-- `SocialConnections` takes `showEntropy` (default `true`), which drops the
-  first-party "Continue with Entropy" button from the row. Unlike the other
-  three, that one is not a staged-rollout placeholder waiting for its
-  connector: on Entropy Access's own sign-in surfaces it offers to sign in to
-  the identity provider with the identity provider, which is a button that can
-  never mean anything. A flag rather than inferring intent from a missing
-  `onEntropy`, because rendering an unhandled provider is deliberate here —
-  simple-finance renders the whole row with no handlers at all, and inference
-  would silently take that button away from it.
+- `SocialConnections` takes `showEntropy` (default `true`), which drops the first-party "Continue
+  with Entropy" button from the row. Unlike the other three, that one is not a staged-rollout
+  placeholder waiting for its connector: on Entropy Access's own sign-in surfaces it offers to sign
+  in to the identity provider with the identity provider, which is a button that can never mean
+  anything. A flag rather than inferring intent from a missing `onEntropy`, because rendering an
+  unhandled provider is deliberate here — simple-finance renders the whole row with no handlers at
+  all, and inference would silently take that button away from it.
 
 ## 2026.8.35
 
 ### Fixed
 
-- `AuthService.getCurrentUser()` destroyed the session it was asked about. It
-  returned `loadPersistedUser()` and nothing else, and on web that reads a
-  module-level variable which is null in every freshly loaded document — so it
-  answered "nobody" on each page load and refresh while the session cookie was
-  perfectly valid. `useAuth.checkAuth` treats that as a session it cannot
-  resolve and calls `logout()`, which POSTs `/auth/logout` and ends the session
-  server-side: the user was signed out by the act of loading the page.
-
-  Observed on Access, whose portal and admin console are separate SPAs on one
-  origin — so every navigation between them is a fresh document and therefore a
-  guaranteed logout, presenting as an infinite sign-in loop. Its audit log
-  recorded the logouts nobody had asked for.
-
-  Native was affected too, if less visibly: `isAuthenticated()` there is
-  satisfied by a token in SecureStore, so a token that outlived its cached user
-  record produced the same spurious logout.
-
-  `getCurrentUser()` now falls back to `GET /auth/me` when nothing is persisted.
-  It deliberately does not route through `isAuthenticated()`, whose web branch
-  falls back to calling `getCurrentUser()` — going the other way would recurse
-  until the stack gave out, on exactly the signed-out path this makes cheap.
-  The request is shared with `refreshUserData()` through a private `fetchMe`,
-  parameterised on whether a 401 should log out: a refresh of a session
-  believed live that 401s means the session died, while a lookup that 401s is
-  just an anonymous visitor and must not tear anything down.
+- `AuthService.getCurrentUser()` destroyed the session it was asked about. It returned
+  `loadPersistedUser()` and nothing else, and on web that reads a module-level variable which is
+  null in every freshly loaded document — so it answered "nobody" on each page load and refresh
+  while the session cookie was perfectly valid. `useAuth.checkAuth` treats that as a session it
+  cannot resolve and calls `logout()`, which POSTs `/auth/logout` and ends the session server-side:
+  the user was signed out by the act of loading the page.
+
+  Observed on Access, whose portal and admin console are separate SPAs on one origin — so every
+  navigation between them is a fresh document and therefore a guaranteed logout, presenting as an
+  infinite sign-in loop. Its audit log recorded the logouts nobody had asked for.
+
+  Native was affected too, if less visibly: `isAuthenticated()` there is satisfied by a token in
+  SecureStore, so a token that outlived its cached user record produced the same spurious logout.
+
+  `getCurrentUser()` now falls back to `GET /auth/me` when nothing is persisted. It deliberately
+  does not route through `isAuthenticated()`, whose web branch falls back to calling
+  `getCurrentUser()` — going the other way would recurse until the stack gave out, on exactly the
+  signed-out path this makes cheap. The request is shared with `refreshUserData()` through a private
+  `fetchMe`, parameterised on whether a 401 should log out: a refresh of a session believed live
+  that 401s means the session died, while a lookup that 401s is just an anonymous visitor and must
+  not tear anything down.
 
 ## 2026.8.17
 
 ### Fixed
 
-- The systemic bare-CSS-var-no-`dark:`-fallback pattern flagged as a known
-  follow-up in 2026.8.15 — completed across the rest of the package: `Card`,
-  `ContextMenu`, `DataTable`, `DropdownMenu`, `Popover`, `SettingsRow`,
-  `PinPad`, `PasswordGenerator`, `EntropyByline`, `ErrorBoundary` (severe:
-  its retry button's label was invisible white-on-white in dark mode),
-  `Pagination`, `LockOverlay`, `ProtectedRoute`, and every screen under
-  `src/screens/auth/*` (root backgrounds, plus scattered destructive-text and
-  `ServerConfigScreen`'s from-scratch raw-`Text` markup).
-- `CardFooter`'s base `items-center` was never overridden by the `flex-col`
-  className every consuming screen passes it (`AuthScreen`, `LoginScreen`,
-  `RegisterScreen`, and ~10 others) — `flex-row`→`flex-col` and `border-t`→
-  `border-t-0` correctly override via tailwind-merge's same-property
-  matching, but `items-center` has no `items-*` counterpart in that
-  className to conflict with, so it silently survived. Left the submit
-  button's wrapping view with ambiguous (content-fit) width instead of
-  stretching to match its own `w-full` Pressable child — surfaced as the
-  "Sign In" button rendering with a runaway width specifically once its
-  content swapped from label text to the loading spinner (the one thing
-  that actually changes Yoga's layout resolution for that ambiguous case).
-  Added `items-stretch` alongside `flex-col` at every call site.
+- The systemic bare-CSS-var-no-`dark:`-fallback pattern flagged as a known follow-up in 2026.8.15 —
+  completed across the rest of the package: `Card`, `ContextMenu`, `DataTable`, `DropdownMenu`,
+  `Popover`, `SettingsRow`, `PinPad`, `PasswordGenerator`, `EntropyByline`, `ErrorBoundary` (severe:
+  its retry button's label was invisible white-on-white in dark mode), `Pagination`, `LockOverlay`,
+  `ProtectedRoute`, and every screen under `src/screens/auth/*` (root backgrounds, plus scattered
+  destructive-text and `ServerConfigScreen`'s from-scratch raw-`Text` markup).
+- `CardFooter`'s base `items-center` was never overridden by the `flex-col` className every
+  consuming screen passes it (`AuthScreen`, `LoginScreen`, `RegisterScreen`, and ~10 others) —
+  `flex-row`→`flex-col` and `border-t`→ `border-t-0` correctly override via tailwind-merge's
+  same-property matching, but `items-center` has no `items-*` counterpart in that className to
+  conflict with, so it silently survived. Left the submit button's wrapping view with ambiguous
+  (content-fit) width instead of stretching to match its own `w-full` Pressable child — surfaced as
+  the "Sign In" button rendering with a runaway width specifically once its content swapped from
+  label text to the loading spinner (the one thing that actually changes Yoga's layout resolution
+  for that ambiguous case). Added `items-stretch` alongside `flex-col` at every call site.
 
 ## 2026.8.15
 
 ### Fixed
 
-- Several components colored themselves with a bare CSS-variable utility
-  (`bg-primary`, `bg-background`, `border-border`, `bg-destructive`, …) and no
-  `dark:` fallback — on native Android that value stays stuck on its light
-  setting regardless of actual system theme; only components carrying an
-  explicit `dark:`-prefixed class (the existing pattern in `Heading`/`Text`/
-  `MutedText`) reacted correctly. Added matching `dark:` variants — one per
-  CSS variable's own `.dark` value in `styles/globals.css` — to `Button`,
-  `Input`, `Dialog`'s destructive variant, `legal-dialog`'s body text, and
-  `AuthScreen`'s root background. Surfaced as vault's "Get Started" screen
-  going render-broken in dark mode: invisible button, invisible heading/legal
-  text, and a background that stayed white.
-- `AuthScreen`'s tagline and "← Back" link used the plain `Text` component
-  with a `text-muted-foreground` override that fought `Text`'s own base
-  `dark:text-white` — the override lost to the base class's `dark:` variant,
-  so both rendered bright white instead of muted in dark mode. Switched both
-  to `MutedText`, which carries the correct `dark:text-neutral-400`.
-- Known follow-up, not fixed here: the same bare-CSS-var-no-dark:-fallback
-  pattern is present in roughly 15 more files in this package
-  (`password-generator.tsx`, `pin-pad.tsx`, `tag-chip.tsx`, several other
-  still-active auth screens, …) — scoped out of this release to unblock the
-  reported bug; needs its own pass.
+- Several components colored themselves with a bare CSS-variable utility (`bg-primary`,
+  `bg-background`, `border-border`, `bg-destructive`, …) and no `dark:` fallback — on native Android
+  that value stays stuck on its light setting regardless of actual system theme; only components
+  carrying an explicit `dark:`-prefixed class (the existing pattern in `Heading`/`Text`/
+  `MutedText`) reacted correctly. Added matching `dark:` variants — one per CSS variable's own
+  `.dark` value in `styles/globals.css` — to `Button`, `Input`, `Dialog`'s destructive variant,
+  `legal-dialog`'s body text, and `AuthScreen`'s root background. Surfaced as vault's "Get Started"
+  screen going render-broken in dark mode: invisible button, invisible heading/legal text, and a
+  background that stayed white.
+- `AuthScreen`'s tagline and "← Back" link used the plain `Text` component with a
+  `text-muted-foreground` override that fought `Text`'s own base `dark:text-white` — the override
+  lost to the base class's `dark:` variant, so both rendered bright white instead of muted in dark
+  mode. Switched both to `MutedText`, which carries the correct `dark:text-neutral-400`.
+- Known follow-up, not fixed here: the same bare-CSS-var-no-dark:-fallback pattern is present in
+  roughly 15 more files in this package (`password-generator.tsx`, `pin-pad.tsx`, `tag-chip.tsx`,
+  several other still-active auth screens, …) — scoped out of this release to unblock the reported
+  bug; needs its own pass.
 
 ## 2026.8.2
 
 ### Fixed
 
-- `registerTelemetry` and the rest of the telemetry registry were exported from
-  the root barrel twice — once through `export * from "./services"` and once by
-  name. Metro's CommonJS interop resolved the duplicate ambiguously and
-  consumers got `undefined` at runtime despite the types checking. The root
-  barrel now re-exports them only through `./services`.
+- `registerTelemetry` and the rest of the telemetry registry were exported from the root barrel
+  twice — once through `export * from "./services"` and once by name. Metro's CommonJS interop
+  resolved the duplicate ambiguously and consumers got `undefined` at runtime despite the types
+  checking. The root barrel now re-exports them only through `./services`.
 
 ## 2026.8.1
 
 ### Added
 
-- Telemetry registry (`registerTelemetry`, `trackClick`, `withClickTracking`). The
-  package reports interactions to a sink the host app supplies; it knows nothing
-  about batching, authentication or transport. No sink registered means every
-  entry point is a no-op, so consumers that do not opt in are unaffected.
-- `telemetryId` prop on `Button` and `IconButton`. Reports a stable,
-  author-assigned id when the control is activated. Wired through `onPress`, so
-  a disabled or loading button records nothing.
-- All 69 interactive controls across the 18 auth screens carry a `telemetryId`,
-  making sign-in, sign-up, MFA and consent measurable by consuming apps without
-  each of them re-tagging the packaged screens.
+- Telemetry registry (`registerTelemetry`, `trackClick`, `withClickTracking`). The package reports
+  interactions to a sink the host app supplies; it knows nothing about batching, authentication or
+  transport. No sink registered means every entry point is a no-op, so consumers that do not opt in
+  are unaffected.
+- `telemetryId` prop on `Button` and `IconButton`. Reports a stable, author-assigned id when the
+  control is activated. Wired through `onPress`, so a disabled or loading button records nothing.
+- All 69 interactive controls across the 18 auth screens carry a `telemetryId`, making sign-in,
+  sign-up, MFA and consent measurable by consuming apps without each of them re-tagging the packaged
+  screens.
 
 ## [Unreleased]
 

package/lib/components/item-icon.d.ts

@@ -1,4 +1,5 @@
 import React from "react";
+import { type UploadResolver } from "../hooks/useUploadBlobUrl";
 export interface ItemIconProps {
     /**
      * Stored icon reference. Either a literal URL, a `custom:<uploadId>`
@@ -22,6 +23,21 @@ export interface ItemIconProps {
     faviconPath?: string;
     /** Upload-fetch path prefix. Defaults to `/uploads`. */
     uploadsPath?: string;
+    /**
+     * Resolve a `custom:<uploadId>` reference yourself instead of letting this
+     * component fetch it.
+     *
+     * For a consumer whose uploads are not behind `apiFetch` at all — vault's
+     * device-only vaults keep them in on-device SQLite, with no server to ask.
+     * Without this, such a consumer has to either fork the component or
+     * pre-resolve the reference into a `data:` URI and pass it as `iconUrl`,
+     * which works by accident (anything that is not `custom:` is treated as a
+     * plain URL) and hides the intent.
+     *
+     * Return `null` for an id that does not resolve; the fallback glyph is drawn,
+     * exactly as for a fetch that fails.
+     */
+    resolveUpload?: UploadResolver;
 }
 /**
  * Per-item icon: shows the custom upload, falls back to the favicon

package/lib/components/item-icon.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"item-icon.d.ts","sourceRoot":"","sources":["../../src/components/item-icon.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA8B,MAAM,OAAO,CAAC;AAOnD,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAQD;;;;GAIG;AACH,eAAO,MAAM,QAAQ,2CAmEnB,CAAC"}
+{"version":3,"file":"item-icon.d.ts","sourceRoot":"","sources":["../../src/components/item-icon.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA8B,MAAM,OAAO,CAAC;AAKnD,OAAO,EAAE,KAAK,cAAc,EAAoB,MAAM,2BAA2B,CAAC;AAElF,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;;;OAaG;IACH,aAAa,CAAC,EAAE,cAAc,CAAC;CAChC;AAQD;;;;GAIG;AACH,eAAO,MAAM,QAAQ,2CAoEnB,CAAC"}

package/lib/components/item-icon.jsx

@@ -13,12 +13,12 @@ const WEB_LAZY_PROPS = Platform.OS === "web" ? { loading: "lazy", decoding: "asy
  * proxy, then to a generic globe glyph on a tile-toned square. Shared
  * between RN clients (mobile) and RN-Web (extension popup).
  */
-export const ItemIcon = React.memo(function ItemIcon({ iconUrl, siteUrl, size = 40, imageSize, borderRadius, background, fallbackColor, faviconPath = "/favicon", uploadsPath = "/uploads", }) {
+export const ItemIcon = React.memo(function ItemIcon({ iconUrl, siteUrl, size = 40, imageSize, borderRadius, background, fallbackColor, faviconPath = "/favicon", uploadsPath = "/uploads", resolveUpload, }) {
     const { colorScheme } = useColorScheme();
     const isDark = colorScheme === "dark";
     const resolved = resolveIcon({ iconUrl, siteUrl, faviconPath });
     const uploadId = resolved.kind === "upload" ? resolved.uploadId : null;
-    const upload = useUploadBlobUrl(uploadId, uploadsPath);
+    const upload = useUploadBlobUrl(uploadId, { uploadsPath, resolve: resolveUpload });
     const directUri = resolved.kind === "url" ? resolved.uri : null;
     const [urlErrored, setUrlErrored] = useState(false);
     useEffect(() => {

package/lib/components/item-icon.jsx.map

@@ -1 +1 @@
-{"version":3,"file":"item-icon.jsx","sourceRoot":"","sources":["../../src/components/item-icon.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"item-icon.jsx","sourceRoot":"","sources":["../../src/components/item-icon.tsx"],"names":[],"mappings":"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"}

package/lib/hooks/index.d.ts

@@ -2,6 +2,6 @@ export { AuthProvider, useAuth, useRole, useRequireAuth, useSession, type AuthPr
 export { useShakeAnimation } from "./useShakeAnimation";
 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, getPasswordStrength, type UsePasswordGeneratorResult, type PasswordStrength, type BreachState, } from "./usePasswordGenerator";
 //# sourceMappingURL=index.d.ts.map

package/lib/hooks/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,OAAO,EACP,OAAO,EACP,cAAc,EACd,UAAU,EACV,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,GAC7B,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAErE,OAAO,EAAE,gBAAgB,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAEhF,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,KAAK,0BAA0B,EAC/B,KAAK,gBAAgB,EACrB,KAAK,WAAW,GACjB,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,OAAO,EACP,OAAO,EACP,cAAc,EACd,UAAU,EACV,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,GAC7B,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAErE,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,KAAK,0BAA0B,EAC/B,KAAK,gBAAgB,EACrB,KAAK,WAAW,GACjB,MAAM,wBAAwB,CAAC"}

package/lib/hooks/index.js

@@ -2,6 +2,6 @@ export { AuthProvider, useAuth, useRole, useRequireAuth, useSession, } from "./u
 export { useShakeAnimation } from "./useShakeAnimation";
 export { useDebouncedValue } from "./useDebouncedValue";
 export { useAutoLock } from "./useAutoLock";
-export { useUploadBlobUrl } from "./useUploadBlobUrl";
+export { useUploadBlobUrl, } from "./useUploadBlobUrl";
 export { usePasswordGenerator, getPasswordStrength, } from "./usePasswordGenerator";
 //# sourceMappingURL=index.js.map

package/lib/hooks/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,OAAO,EACP,OAAO,EACP,cAAc,EACd,UAAU,GAKX,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,EAAE,WAAW,EAA2B,MAAM,eAAe,CAAC;AAErE,OAAO,EAAE,gBAAgB,EAA4B,MAAM,oBAAoB,CAAC;AAEhF,OAAO,EACL,oBAAoB,EACpB,mBAAmB,GAIpB,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,OAAO,EACP,OAAO,EACP,cAAc,EACd,UAAU,GAKX,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,EAAE,WAAW,EAA2B,MAAM,eAAe,CAAC;AAErE,OAAO,EAIL,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,oBAAoB,EACpB,mBAAmB,GAIpB,MAAM,wBAAwB,CAAC"}

package/lib/hooks/useUploadBlobUrl.d.ts

@@ -4,10 +4,54 @@ export interface UploadBlobUrlResult {
     setErrored: (v: boolean) => void;
 }
 /**
- * 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 declare function useUploadBlobUrl(uploadId: string | null | undefined, uploadsPath?: string): UploadBlobUrlResult;
+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 declare function useUploadBlobUrl(uploadId: string | null | undefined, options?: string | UploadBlobUrlOptions): UploadBlobUrlResult;
 //# sourceMappingURL=useUploadBlobUrl.d.ts.map

package/lib/hooks/useUploadBlobUrl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useUploadBlobUrl.d.ts","sourceRoot":"","sources":["../../src/hooks/useUploadBlobUrl.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CAClC;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACnC,WAAW,SAAa,GACvB,mBAAmB,CAsDrB"}
+{"version":3,"file":"useUploadBlobUrl.d.ts","sourceRoot":"","sources":["../../src/hooks/useUploadBlobUrl.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CAClC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AAE/F,MAAM,WAAW,oBAAoB;IACnC,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACnC,OAAO,GAAE,MAAM,GAAG,oBAAyB,GAC1C,mBAAmB,CAgGrB"}

package/lib/hooks/useUploadBlobUrl.js

@@ -1,15 +1,39 @@
-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;
 /**
- * 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.
+ * 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, uploadsPath = "/uploads") {
+export function useUploadBlobUrl(uploadId, options = {}) {
+    const { uploadsPath = "/uploads", resolve } = typeof options === "string" ? { uploadsPath: options, resolve: undefined } : options;
     const [uri, setUri] = useState(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(resolve);
+    resolveRef.current = resolve;
     useEffect(() => {
         setErrored(false);
         if (!uploadId) {
@@ -19,21 +43,51 @@ export function useUploadBlobUrl(uploadId, uploadsPath = "/uploads") {
         const controller = new AbortController();
         const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
         let createdUrl = null;
-        apiFetch(`${uploadsPath}/${encodeURIComponent(uploadId)}`, { signal: controller.signal })
-            .then(async (response) => {
+        const load = async () => {
+            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;
+                return null;
             }
             if (!response.ok) {
                 throw new Error(`Failed to load upload (${response.status})`);
             }
-            const blob = await response.blob();
+            if (Platform.OS === "web") {
+                const blob = await response.blob();
+                if (controller.signal.aborted) {
+                    return null;
+                }
+                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) => {
             if (controller.signal.aborted) {
@@ -57,4 +111,29 @@ export function useUploadBlobUrl(uploadId, uploadsPath = "/uploads") {
     }, [uploadId, uploadsPath]);
     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) {
+    const chars = [];
+    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("");
+}
 //# sourceMappingURL=useUploadBlobUrl.js.map

package/lib/hooks/useUploadBlobUrl.js.map

@@ -1 +1 @@
-{"version":3,"file":"useUploadBlobUrl.js","sourceRoot":"","sources":["../../src/hooks/useUploadBlobUrl.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAQhC;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,QAAmC,EACnC,WAAW,GAAG,UAAU;IAExB,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,QAAQ,CAAgB,IAAI,CAAC,CAAC;IACpD,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAE9C,SAAS,CAAC,GAAG,EAAE;QACb,UAAU,CAAC,KAAK,CAAC,CAAC;QAClB,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,CAAC,IAAI,CAAC,CAAC;YACb,OAAO;QACT,CAAC;QAED,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,gBAAgB,CAAC,CAAC;QACvE,IAAI,UAAU,GAAkB,IAAI,CAAC;QAErC,QAAQ,CAAC,GAAG,WAAW,IAAI,kBAAkB,CAAC,QAAQ,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC;aACtF,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE;YACvB,IAAI,UAAU,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBAC9B,OAAO;YACT,CAAC;YACD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,IAAI,KAAK,CAAC,0BAA0B,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;YAChE,CAAC;YACD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YACnC,IAAI,UAAU,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBAC9B,OAAO;YACT,CAAC;YACD,MAAM,GAAG,GAAG,GAAG,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;YACtC,UAAU,GAAG,GAAG,CAAC;YACjB,MAAM,CAAC,GAAG,CAAC,CAAC;QACd,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,CAAU,EAAE,EAAE;YACpB,IAAI,UAAU,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBAC9B,OAAO;YACT,CAAC;YACD,IAAI,CAAC,YAAY,YAAY,IAAI,CAAC,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;gBACzD,OAAO;YACT,CAAC;YACD,UAAU,CAAC,IAAI,CAAC,CAAC;QACnB,CAAC,CAAC;aACD,OAAO,CAAC,GAAG,EAAE;YACZ,YAAY,CAAC,OAAO,CAAC,CAAC;QACxB,CAAC,CAAC,CAAC;QAEL,OAAO,GAAG,EAAE;YACV,UAAU,CAAC,KAAK,EAAE,CAAC;YACnB,YAAY,CAAC,OAAO,CAAC,CAAC;YACtB,IAAI,UAAU,EAAE,CAAC;gBACf,GAAG,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC;YAClC,CAAC;QACH,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC;IAE5B,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;AACtC,CAAC"}
+{"version":3,"file":"useUploadBlobUrl.js","sourceRoot":"","sources":["../../src/hooks/useUploadBlobUrl.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@entropy-softworks/ui",
-  "version": "2026.8.41",
+  "version": "2026.8.42",
   "private": false,
   "description": "Shared React Native UI primitives, auth screens, hooks, and services for Entropy Softworks Expo apps",
   "license": "MIT",

package/src/components/item-icon.tsx

@@ -3,7 +3,7 @@ import { Image, Platform, View } from "react-native";
 import { Ionicons } from "@expo/vector-icons";
 import { useColorScheme } from "nativewind";
 import { resolveIcon } from "../services/favicon";
-import { useUploadBlobUrl } from "../hooks/useUploadBlobUrl";
+import { type UploadResolver, useUploadBlobUrl } from "../hooks/useUploadBlobUrl";
 
 export interface ItemIconProps {
   /**
@@ -28,6 +28,21 @@ export interface ItemIconProps {
   faviconPath?: string;
   /** Upload-fetch path prefix. Defaults to `/uploads`. */
   uploadsPath?: string;
+  /**
+   * Resolve a `custom:<uploadId>` reference yourself instead of letting this
+   * component fetch it.
+   *
+   * For a consumer whose uploads are not behind `apiFetch` at all — vault's
+   * device-only vaults keep them in on-device SQLite, with no server to ask.
+   * Without this, such a consumer has to either fork the component or
+   * pre-resolve the reference into a `data:` URI and pass it as `iconUrl`,
+   * which works by accident (anything that is not `custom:` is treated as a
+   * plain URL) and hides the intent.
+   *
+   * Return `null` for an id that does not resolve; the fallback glyph is drawn,
+   * exactly as for a fetch that fails.
+   */
+  resolveUpload?: UploadResolver;
 }
 
 // react-native-web forwards `loading` and `decoding` to the underlying
@@ -51,13 +66,14 @@ export const ItemIcon = React.memo(function ItemIcon({
   fallbackColor,
   faviconPath = "/favicon",
   uploadsPath = "/uploads",
+  resolveUpload,
 }: ItemIconProps) {
   const { colorScheme } = useColorScheme();
   const isDark = colorScheme === "dark";
 
   const resolved = resolveIcon({ iconUrl, siteUrl, faviconPath });
   const uploadId = resolved.kind === "upload" ? resolved.uploadId : null;
-  const upload = useUploadBlobUrl(uploadId, uploadsPath);
+  const upload = useUploadBlobUrl(uploadId, { uploadsPath, resolve: resolveUpload });
 
   const directUri = resolved.kind === "url" ? resolved.uri : null;
   const [urlErrored, setUrlErrored] = useState(false);

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("");
+}