@oxyhq/services 22.8.6 → 22.9.0

package/src/ui/navigation/surfaceNavStack.ts

@@ -0,0 +1,110 @@
+import { createStore, type StoreApi } from 'zustand/vanilla';
+import type { RouteName } from './routes';
+
+/**
+ * Per-surface route history — the NAV-WITHIN axis.
+ *
+ * Bloom's surface stack owns DEPTH (a surface presented on top of another). This
+ * store owns the ORTHOGONAL axis: the route history INSIDE one SDK surface. Each
+ * SDK surface holds its own {@link SurfaceNavStack}; `navigate`/`replace`/`goBack`
+ * mutate it and the SAME Bloom surface re-renders its content from the new top
+ * frame. It is the per-surface reincarnation of the old global
+ * `bottomSheetStore`'s `history` + `currentStep`.
+ *
+ * `closing`/`closeResult` model a pending dismissal: the surface's `SurfaceScreen`
+ * watches them and calls the Bloom surface's `dismiss(result)` from an effect —
+ * so a dismiss requested BEFORE the surface has mounted still resolves once it
+ * does, with no controls-capture race and no render-phase side effect.
+ */
+
+/** One frame in a surface's route history. */
+export interface NavFrame {
+  route: RouteName;
+  props: Record<string, unknown>;
+  /** Current wizard step for step-based screens (seeded from `props.initialStep`). */
+  step: number;
+}
+
+export interface NavStackState {
+  /** Bottom → top; the last frame is the visible screen. */
+  frames: NavFrame[];
+  /** Flipped once a dismiss is requested; the host resolves the Bloom surface. */
+  closing: boolean;
+  /** The value the surface's `present()` promise resolves with on dismissal. */
+  closeResult: unknown;
+}
+
+export interface SurfaceNavStack {
+  store: StoreApi<NavStackState>;
+  /** Drill in: push a new frame. */
+  navigate(route: RouteName, props?: Record<string, unknown>): void;
+  /** Swap the top frame in place (no history entry). */
+  replace(route: RouteName, props?: Record<string, unknown>): void;
+  /** Pop one frame. Returns `false` when already at the root frame. */
+  goBack(): boolean;
+  /** Whether a back is possible (a deeper frame OR a prior wizard step). */
+  canGoBack(): boolean;
+  /** Set the current frame's wizard step. */
+  setStep(step: number): void;
+  /** Request dismissal of the whole surface, resolving its promise with `result`. */
+  requestDismiss(result?: unknown): void;
+  /** The current (top) frame. */
+  getTop(): NavFrame;
+}
+
+function makeFrame(route: RouteName, props?: Record<string, unknown>): NavFrame {
+  const resolved = props ?? {};
+  const step = typeof resolved.initialStep === 'number' ? resolved.initialStep : 0;
+  return { route, props: resolved, step };
+}
+
+export function createSurfaceNavStack(
+  route: RouteName,
+  props?: Record<string, unknown>,
+): SurfaceNavStack {
+  const store = createStore<NavStackState>(() => ({
+    frames: [makeFrame(route, props)],
+    closing: false,
+    closeResult: undefined,
+  }));
+
+  const getTop = (): NavFrame => {
+    const { frames } = store.getState();
+    return frames[frames.length - 1];
+  };
+
+  return {
+    store,
+    getTop,
+    navigate(nextRoute, nextProps) {
+      store.setState((state) => ({ frames: [...state.frames, makeFrame(nextRoute, nextProps)] }));
+    },
+    replace(nextRoute, nextProps) {
+      store.setState((state) => ({
+        frames: [...state.frames.slice(0, -1), makeFrame(nextRoute, nextProps)],
+      }));
+    },
+    goBack() {
+      const { frames } = store.getState();
+      if (frames.length <= 1) return false;
+      store.setState({ frames: frames.slice(0, -1) });
+      return true;
+    },
+    canGoBack() {
+      const { frames } = store.getState();
+      return frames.length > 1 || (frames[frames.length - 1]?.step ?? 0) > 0;
+    },
+    setStep(step) {
+      store.setState((state) => {
+        const frames = state.frames.slice();
+        const index = frames.length - 1;
+        frames[index] = { ...frames[index], step };
+        return { frames };
+      });
+    },
+    requestDismiss(result) {
+      if (store.getState().closing) return;
+      store.setState({ closing: true, closeResult: result });
+    },
+  };
+}

package/src/ui/navigation/surfaceRegistry.ts

@@ -0,0 +1,174 @@
+import type { ReactNode } from 'react';
+import type { AccountDialogView } from '@oxyhq/core';
+import type { RouteName } from './routes';
+
+/**
+ * The SDK's typed surface registry — the contract layer the SDK stacks on top of
+ * Bloom's content-agnostic surface stack (`@oxyhq/bloom/surfaces`). One entry per
+ * route describing its `props` (what the presenter must pass) and its `result`
+ * (what awaiting `present()` resolves with). Hand-maintained, contract-first:
+ * adding a route here is the single edit that types it end to end.
+ *
+ * For P1 most routes keep permissive `Record<string, unknown>` props + a `void`
+ * result — the historical grab-bag `showBottomSheet`/`navigate` props are
+ * unchanged. Later phases tighten individual routes without changing this shape.
+ */
+
+/** One registry entry: the props a route is presented with + its dismissal result. */
+type SurfaceRoute<Props = Record<string, unknown>, Result = void> = {
+  props: Props;
+  result: Result;
+};
+
+export interface SurfaceRegistry {
+  ManageAccount: SurfaceRoute;
+  AccountVerification: SurfaceRoute;
+  PaymentGateway: SurfaceRoute;
+  Profile: SurfaceRoute;
+  LanguageSelector: SurfaceRoute;
+  PrivacySettings: SurfaceRoute;
+  SearchSettings: SurfaceRoute;
+  FileManagement: SurfaceRoute;
+  HelpSupport: SurfaceRoute;
+  FAQ: SurfaceRoute;
+  Feedback: SurfaceRoute;
+  LegalDocuments: SurfaceRoute;
+  AppInfo: SurfaceRoute;
+  PremiumSubscription: SurfaceRoute;
+  WelcomeNewUser: SurfaceRoute;
+  UserLinks: SurfaceRoute;
+  HistoryView: SurfaceRoute;
+  SavesCollections: SurfaceRoute;
+  EditProfile: SurfaceRoute;
+  EditProfileField: SurfaceRoute;
+  LearnMoreUsernames: SurfaceRoute;
+  TrustCenter: SurfaceRoute;
+  TrustLeaderboard: SurfaceRoute;
+  TrustRewards: SurfaceRoute;
+  TrustRules: SurfaceRoute;
+  AboutTrust: SurfaceRoute;
+  TrustFAQ: SurfaceRoute;
+  FollowersList: SurfaceRoute;
+  FollowingList: SurfaceRoute;
+  CreateAccount: SurfaceRoute;
+  AccountMembers: SurfaceRoute;
+  AccountSettings: SurfaceRoute;
+  AvatarCrop: SurfaceRoute;
+  Notifications: SurfaceRoute;
+  ConnectedApps: SurfaceRoute;
+  Preferences: SurfaceRoute;
+  /** Unified account switcher + sign-in surface (folded `OxyAccountDialog` body). */
+  AccountDialog: SurfaceRoute<{ initialView?: AccountDialogView }>;
+}
+
+/**
+ * Compile-time guard: the registry keys must be EXACTLY the route names. If a new
+ * `RouteName` is added without a registry entry (or vice-versa) this alias
+ * resolves to `never` and the `satisfies` assertion below fails to type-check.
+ */
+type RegistryCoversRoutes = [RouteName] extends [keyof SurfaceRegistry]
+  ? [keyof SurfaceRegistry] extends [RouteName]
+    ? true
+    : never
+  : never;
+const _registryCoversRoutes: RegistryCoversRoutes = true;
+void _registryCoversRoutes;
+
+/** Typed props a route is presented with. */
+export type SurfaceProps<K extends RouteName> = SurfaceRegistry[K]['props'];
+/** What awaiting a route's `present()` resolves with when it is dismissed. */
+export type SurfaceResult<K extends RouteName> = SurfaceRegistry[K]['result'];
+
+/**
+ * How a surface renders — the SDK's presentation taxonomy. Each value maps to a
+ * concrete Bloom `Dialog` placement/chrome in `surfaces.ts`:
+ *
+ *   - `'sheet'`      → responsive `{ base: 'bottom', md: 'center' }` (the default:
+ *                      a bottom sheet on narrow viewports, a centered card on wide).
+ *   - `'center'`     → a plain centered modal at every width.
+ *   - `'drawer'`     → responsive `{ base: 'bottom', md: 'left' }` side drawer.
+ *   - `'fullScreen'` → approximated with the shared `Dialog`: a full-height sheet /
+ *                      large centered card, flush (`contentPadding: 0`) content, a
+ *                      black canvas and programmatic-only dismiss (the flagship
+ *                      image picker). A real Bloom `'fullScreen'` placement is a
+ *                      follow-up if the approximation reads wrong on device.
+ */
+export type SurfacePresentation = 'sheet' | 'center' | 'drawer' | 'fullScreen';
+
+/**
+ * Per-route surface configuration. Merges the historical `SheetRouteConfig`
+ * knobs with the new {@link SurfacePresentation}.
+ *
+ * NOTE: `scrollable` / `manualActivation` / `dynamicBackdrop` / `handleComponent`
+ * describe the in-tree bottom-sheet's pan + scroll behaviour. On Bloom's `Dialog`
+ * surface those concerns are now owned by the shared `DialogBottomSheet` (it opts
+ * pure custom children OUT of its internal ScrollView and manages the pan itself),
+ * so for P1 these fields are informational — reserved for a future Bloom
+ * bottom-placement passthrough. `presentation` (+ `scrollable` for the picker's
+ * flush layout) is what actually drives the surface today.
+ */
+export interface SurfaceRouteConfig {
+  /** Which surface hosts the route. */
+  presentation: SurfacePresentation;
+  /**
+   * When `false`, the route owns its own scroll container (a FlatList /
+   * SectionList / VirtualizedList) and the host must not wrap it in a ScrollView.
+   */
+  scrollable: boolean;
+  /** Body-pan activation strategy — reserved (owned by Bloom's Dialog surface). */
+  manualActivation: boolean;
+  /** Drag-proportional backdrop dim — reserved (owned by Bloom's Dialog surface). */
+  dynamicBackdrop: boolean;
+  /** Optional custom drag-handle slot — reserved (owned by Bloom's Dialog surface). */
+  handleComponent?: () => ReactNode;
+}
+
+/** Defaults shared across all routes — the canonical responsive "sheet". */
+const DEFAULT_SURFACE_CONFIG: SurfaceRouteConfig = {
+  presentation: 'sheet',
+  scrollable: true,
+  manualActivation: true,
+  dynamicBackdrop: true,
+};
+
+/**
+ * Predicate matching `FileManagementScreen`'s internal `isImageOnlyPicker`
+ * derivation. When the consumer restricts to image MIME types (no videos, no
+ * audio, no documents), FileManagement renders the flagship `PhotoPickerView`,
+ * which owns its own FlatList and reads best as a full-bleed picker. Kept in sync
+ * with `FileManagementScreen` — both check the same disabled MIME type families.
+ */
+const isFileManagementImageOnlyPicker = (props: Record<string, unknown>): boolean => {
+  if (!props.selectMode) return false;
+  const disabled = props.disabledMimeTypes;
+  if (!Array.isArray(disabled) || disabled.length === 0) return false;
+  const has = (predicate: (mt: string) => boolean): boolean =>
+    disabled.some((mt) => typeof mt === 'string' && predicate(mt));
+  const blocksVideos = has((mt) => mt === 'video/' || mt.startsWith('video/'));
+  const blocksAudio = has((mt) => mt === 'audio/' || mt.startsWith('audio/'));
+  const blocksDocs = has(
+    (mt) => mt === 'application/pdf' || mt === 'application/' || mt.startsWith('application/'),
+  );
+  return blocksVideos && blocksAudio && blocksDocs;
+};
+
+/**
+ * Resolve the surface configuration for a route + props. Defaults to the
+ * responsive sheet; the image-only FileManagement picker upgrades to a full-bleed
+ * `'fullScreen'` surface that owns its own scrolling.
+ */
+export const getSurfaceConfig = (
+  route: RouteName,
+  props: Record<string, unknown>,
+): SurfaceRouteConfig => {
+  if (route === 'FileManagement' && isFileManagementImageOnlyPicker(props)) {
+    return { ...DEFAULT_SURFACE_CONFIG, presentation: 'fullScreen', scrollable: false };
+  }
+  return DEFAULT_SURFACE_CONFIG;
+};
+
+/** Convenience: just the presentation taxonomy for a route + props. */
+export const getSurfacePresentation = (
+  route: RouteName,
+  props: Record<string, unknown>,
+): SurfacePresentation => getSurfaceConfig(route, props).presentation;

package/src/ui/navigation/surfaces.ts

@@ -0,0 +1,244 @@
+import { createElement } from 'react';
+import type { ViewStyle } from 'react-native';
+import {
+  surfaces as bloomSurfaces,
+  type PresentOptions,
+  type SurfaceControls,
+} from '@oxyhq/bloom/surfaces';
+import SurfaceScreen from '../components/SurfaceScreen';
+import type { RouteName } from './routes';
+import {
+  getSurfaceConfig,
+  getSurfacePresentation,
+  type SurfacePresentation,
+  type SurfaceProps,
+  type SurfaceResult,
+  type SurfaceRouteConfig,
+} from './surfaceRegistry';
+import { createSurfaceNavStack, type SurfaceNavStack } from './surfaceNavStack';
+
+/**
+ * The SDK's typed surface API — a route registry layered on top of Bloom's
+ * content-agnostic surface stack (`@oxyhq/bloom/surfaces`).
+ *
+ * `present(route)` opens a NEW Bloom surface (the DEPTH axis) whose content is a
+ * {@link SurfaceScreen} driven by the route's own {@link SurfaceNavStack} (the
+ * NAV-WITHIN axis). Navigating within that surface mutates its nav stack and
+ * re-renders the SAME Bloom surface; presenting stacks another surface on top.
+ *
+ * Bloom coordinates z-order / backdrop / dismiss across every surface (SDK's and
+ * apps'), so nothing clashes.
+ */
+
+/** Responsive "sheet": bottom sheet on narrow, centered card on wide. */
+const SHEET_PLACEMENT = { base: 'bottom', md: 'center' } as const;
+
+/** Full-bleed black canvas for the `'fullScreen'` approximation (image picker). */
+const FULLSCREEN_SURFACE_STYLE: ViewStyle = { backgroundColor: '#000000', overflow: 'hidden' };
+
+/** Map a route's presentation taxonomy onto concrete Bloom `Dialog` options. */
+function bloomOptionsFor(config: SurfaceRouteConfig): PresentOptions {
+  switch (config.presentation) {
+    case 'center':
+      return { placement: 'center' };
+    case 'drawer':
+      return { placement: { base: 'bottom', md: 'left' } };
+    case 'fullScreen':
+      // Approximate a full-screen surface with the shared `Dialog`: a tall
+      // sheet / large centered card, flush content, a black canvas and
+      // programmatic-only dismiss — matching the shipped image-picker Dialog.
+      return {
+        placement: SHEET_PLACEMENT,
+        contentPadding: 0,
+        maxWidth: 640,
+        maxHeightRatio: 0.9,
+        dismissOnBackdrop: false,
+        style: FULLSCREEN_SURFACE_STYLE,
+        panelStyle: FULLSCREEN_SURFACE_STYLE,
+      };
+    default:
+      return { placement: SHEET_PLACEMENT };
+  }
+}
+
+/**
+ * A live handle to a presented SDK surface. Exposes DEPTH controls (`dismiss`,
+ * `result`) and NAV-WITHIN controls (`navigate`/`replace`/`goBack`/`setStep`) that
+ * drive this surface's own nav stack. Held by the `showBottomSheet` adapter (base
+ * surface) and by `OxyContext` (the AccountDialog surface).
+ */
+export interface SurfaceInstance<K extends RouteName = RouteName> {
+  readonly route: RouteName;
+  readonly presentation: SurfacePresentation;
+  navigate: (route: RouteName, props?: Record<string, unknown>) => void;
+  replace: (route: RouteName, props?: Record<string, unknown>) => void;
+  goBack: () => boolean;
+  canGoBack: () => boolean;
+  setStep: (step: number) => void;
+  dismiss: (result?: SurfaceResult<K>) => void;
+  readonly result: Promise<SurfaceResult<K> | undefined>;
+}
+
+/**
+ * The type-erased handle the `showBottomSheet` adapter needs from a tracked
+ * surface: what it hosts, and how to drive/dismiss it. Kept result-type-free so
+ * the (generic) `SurfaceInstance<K>` never has to be widened into a shared array.
+ */
+interface TrackedSurface {
+  readonly route: RouteName;
+  readonly presentation: SurfacePresentation;
+  navigate: (route: RouteName, props?: Record<string, unknown>) => void;
+  goBack: () => boolean;
+  dismiss: () => void;
+}
+
+/**
+ * Active SDK "route" surfaces (the `showBottomSheet` lineage), bottom → top.
+ * `present`/`presentRoute` register here; `presentDetached` (AccountDialog) does
+ * NOT, so the base-sheet navigation logic never treats the account modal as a
+ * navigable base. Entries self-remove when their surface is dismissed.
+ */
+const activeRouteSurfaces: TrackedSurface[] = [];
+
+function presentInternal<K extends RouteName>(
+  route: K,
+  props: Record<string, unknown>,
+  opts: PresentOptions | undefined,
+  track: boolean,
+): SurfaceInstance<K> {
+  const navStack = createSurfaceNavStack(route, props);
+  const config = getSurfaceConfig(route, props);
+  const bloomOpts: PresentOptions = { label: route, ...bloomOptionsFor(config), ...opts };
+
+  const result = bloomSurfaces.present<SurfaceResult<K>>((surface: SurfaceControls) =>
+    createElement(SurfaceScreen, { navStack, surface, presentation: config.presentation }),
+    bloomOpts,
+  );
+
+  const instance: SurfaceInstance<K> = {
+    route,
+    presentation: config.presentation,
+    navigate: (nextRoute, nextProps) => navStack.navigate(nextRoute, nextProps),
+    replace: (nextRoute, nextProps) => navStack.replace(nextRoute, nextProps),
+    goBack: () => navStack.goBack(),
+    canGoBack: () => navStack.canGoBack(),
+    setStep: (step) => navStack.setStep(step),
+    dismiss: (dismissResult) => navStack.requestDismiss(dismissResult),
+    result,
+  };
+
+  if (track) {
+    const tracked: TrackedSurface = {
+      route: instance.route,
+      presentation: instance.presentation,
+      navigate: instance.navigate,
+      goBack: instance.goBack,
+      dismiss: () => instance.dismiss(),
+    };
+    activeRouteSurfaces.push(tracked);
+    result.finally(() => {
+      const index = activeRouteSurfaces.indexOf(tracked);
+      if (index >= 0) activeRouteSurfaces.splice(index, 1);
+    });
+  }
+
+  return instance;
+}
+
+/**
+ * Present a NEW route surface on top of the stack (the DEPTH axis). Resolves with
+ * the value the surface is dismissed with. Registered in the route-surface stack.
+ */
+export function present<K extends RouteName>(
+  route: K,
+  props?: SurfaceProps<K>,
+  opts?: PresentOptions,
+): SurfaceInstance<K> {
+  return presentInternal(route, (props ?? {}) as Record<string, unknown>, opts, true);
+}
+
+/**
+ * Present a surface that is NOT part of the `showBottomSheet` base-navigation
+ * lineage (the AccountDialog modal). Otherwise identical to {@link present}.
+ */
+export function presentDetached<K extends RouteName>(
+  route: K,
+  props?: SurfaceProps<K>,
+  opts?: PresentOptions,
+): SurfaceInstance<K> {
+  return presentInternal(route, (props ?? {}) as Record<string, unknown>, opts, false);
+}
+
+/**
+ * Untyped present for the adapter, the nav helpers, and the `SurfaceScreen`
+ * binding (where the route is a runtime value and its props are already erased).
+ */
+export function presentRoute(route: RouteName, props?: Record<string, unknown>): SurfaceInstance {
+  return presentInternal(route, props ?? {}, undefined, true);
+}
+
+/** The top-most active route surface, or `undefined` when none are open. */
+export function topRouteSurface(): TrackedSurface | undefined {
+  return activeRouteSurfaces[activeRouteSurfaces.length - 1];
+}
+
+/**
+ * Dismiss every active route surface (the whole `showBottomSheet` session). The
+ * AccountDialog is untracked, so it is untouched. Iterates a snapshot because
+ * `dismiss` mutates `activeRouteSurfaces` asynchronously as surfaces settle.
+ */
+export function closeAllRouteSurfaces(): void {
+  for (const instance of [...activeRouteSurfaces].reverse()) instance.dismiss();
+}
+
+/**
+ * Drill in from a screen: navigate WITHIN the current surface when the target's
+ * presentation matches, else present the target as a NEW surface on top (so a
+ * sheet screen opening the full-bleed picker gets the right chrome).
+ */
+export function navigateWithinOrPresent(
+  currentPresentation: SurfacePresentation,
+  navStack: SurfaceNavStack,
+  route: RouteName,
+  props?: Record<string, unknown>,
+): void {
+  const nextProps = props ?? {};
+  if (getSurfacePresentation(route, nextProps) === currentPresentation) {
+    navStack.navigate(route, nextProps);
+  } else {
+    presentRoute(route, nextProps);
+  }
+}
+
+/** Replace variant of {@link navigateWithinOrPresent}. */
+export function replaceWithinOrPresent(
+  currentPresentation: SurfacePresentation,
+  navStack: SurfaceNavStack,
+  route: RouteName,
+  props?: Record<string, unknown>,
+): void {
+  const nextProps = props ?? {};
+  if (getSurfacePresentation(route, nextProps) === currentPresentation) {
+    navStack.replace(route, nextProps);
+  } else {
+    presentRoute(route, nextProps);
+  }
+}
+
+/**
+ * The SDK's imperative surface API (a module singleton). `present` is the typed
+ * route presenter; `dismissAll` unwinds the whole session. Not yet exported from
+ * the package root — the public `surfaces`/`useSurfaces` API lands in a later
+ * phase; for P1 the internal adapters (`showBottomSheet`, `openAccountDialog`)
+ * are the only public entry points.
+ */
+export const surfaces = {
+  present: <K extends RouteName>(route: K, props?: SurfaceProps<K>, opts?: PresentOptions) =>
+    present(route, props, opts).result,
+  dismissAll: closeAllRouteSurfaces,
+} as const;
+
+/** Hook form of {@link surfaces} (stable singleton). */
+export function useSurfaces(): typeof surfaces {
+  return surfaces;
+}

package/src/ui/screens/FileManagementScreen.tsx

@@ -1123,7 +1123,13 @@ const FileManagementScreen: React.FC<FileManagementScreenProps> = ({
     // this is pure layout: the top chrome (header / controls / search) plus a
     // photo grid of shimmering tiles sized with the same 3-per-row geometry the
     // real photo grid uses. No hand-rolled `Animated` shimmer.
-    if (loading) {
+    //
+    // The image-only picker owns its OWN loading skeleton (rendered by
+    // `PhotoPickerView` when its photo list is still loading), so it inherits the
+    // picker's placement-aware container width / columns / tile size and the
+    // Dialog-vs-bottom-sheet sizing. Skipping the browse chrome here is what keeps
+    // the picker from flashing the wrong (file-manager) skeleton inside the Dialog.
+    if (loading && !isImageOnlyPicker) {
         const GRID_PADDING = 10;
         const TILE_GAP = 4;
         const GRID_COLUMNS = 3;
@@ -1197,6 +1203,7 @@ const FileManagementScreen: React.FC<FileManagementScreenProps> = ({
                     uploadProgress={uploadProgress}
                     hasMore={paging.hasMore}
                     loadingMore={paging.loadingMore}
+                    loading={loading}
                     reduceMotion={reduceMotion}
                     getThumbUrl={thumbSourceFor}
                     primaryColor={colors.primary}

package/src/ui/screens/fileManagement/PhotoPickerSection.tsx

@@ -14,6 +14,7 @@ import {
 import { Image as ExpoImage } from 'expo-image';
 import { Ionicons, MaterialCommunityIcons } from '@expo/vector-icons';
 import { BREAKPOINTS } from '@oxyhq/bloom/styles';
+import * as Skeleton from '@oxyhq/bloom/skeleton';
 import type { FileMetadata } from '@oxyhq/core';
 import { computePhotoGridLayout } from './photoGridLayout';
 
@@ -122,6 +123,13 @@ export interface PhotoPickerViewProps {
     uploadProgress: { current: number; total: number } | null;
     hasMore: boolean;
     loadingMore: boolean;
+    /**
+     * Initial-load flag. While `true` AND no photos have arrived yet, the picker
+     * renders its OWN loading skeleton (placement-aware grid of shimmer tiles)
+     * instead of the empty state — so the loading UI matches the picker's shape
+     * and container width, not the browse file-manager chrome.
+     */
+    loading: boolean;
     reduceMotion: boolean;
     getThumbUrl: (file: FileMetadata) => string | undefined;
     primaryColor: string;
@@ -161,6 +169,18 @@ const RING_SPRING_TENSION = 120;
 const CELL_CORNER_RADIUS = 8; // `rounded-radius-8`
 const SELECTION_RING_WIDTH = 3; // `border-[3px]`
 
+/**
+ * Loading-skeleton tile fill. The picker's backdrop is ALWAYS black regardless
+ * of theme, so we cannot use Bloom `Skeleton.Box`'s theme default (`contrast50`,
+ * which is a near-black gray on a dark theme → invisible on this backdrop). A
+ * neutral dark gray reads as a photo placeholder on black; Bloom's shimmer still
+ * pulses the tile opacity on top of it. `Skeleton.Box` applies `style` after its
+ * own base, so this override wins while the animated opacity is preserved.
+ */
+const SKELETON_TILE_COLOR = '#26262A';
+/** Minimum skeleton rows so the grid never looks empty on a very short panel. */
+const SKELETON_MIN_ROWS = 4;
+
 type PhotoPickerCellProps = {
     photo: FileMetadata;
     size: number;
@@ -325,6 +345,7 @@ const PhotoPickerView: React.FC<PhotoPickerViewProps> = ({
     uploadProgress,
     hasMore,
     loadingMore,
+    loading,
     reduceMotion,
     getThumbUrl,
     primaryColor,
@@ -366,14 +387,13 @@ const PhotoPickerView: React.FC<PhotoPickerViewProps> = ({
     // better below full height); the bottom sheet may run taller. Keep this
     // breakpoint in sync with `DIALOG_PLACEMENT` in BottomSheetRouter.
     const isCenteredPanel = windowWidth >= BREAKPOINTS.md;
-    const rootStyle = useMemo(
-        () => ({
-            maxHeight: isCenteredPanel
-                ? Math.min(Math.round(windowHeight * 0.85), 720)
-                : Math.round(windowHeight * 0.9),
-        }),
+    const maxPanelHeight = useMemo(
+        () => (isCenteredPanel
+            ? Math.min(Math.round(windowHeight * 0.85), 720)
+            : Math.round(windowHeight * 0.9)),
         [isCenteredPanel, windowHeight],
     );
+    const rootStyle = useMemo(() => ({ maxHeight: maxPanelHeight }), [maxPanelHeight]);
 
     const effectiveWidth = gridWidth > 0 ? gridWidth : windowWidth;
     const { columns, cellSize, gutter } = useMemo(
@@ -381,6 +401,18 @@ const PhotoPickerView: React.FC<PhotoPickerViewProps> = ({
         [effectiveWidth],
     );
 
+    // How many shimmer tiles the loading skeleton renders: enough FULL rows to
+    // fill the panel down to (but never past) its `maxHeight` cap, so the panel
+    // hugs the skeleton content instead of overflowing or scrolling. `floor`
+    // keeps the last row whole; `SKELETON_MIN_ROWS` guards a very short panel.
+    const skeletonTileCount = useMemo(() => {
+        const rowHeight = cellSize + gutter;
+        if (rowHeight <= 0) return columns * SKELETON_MIN_ROWS;
+        const available = Math.max(0, maxPanelHeight - GRID_CONTENT_PADDING_TOP);
+        const rows = Math.max(SKELETON_MIN_ROWS, Math.floor(available / rowHeight));
+        return rows * columns;
+    }, [cellSize, gutter, columns, maxPanelHeight]);
+
     // Map selectedIds → 1-based selection order for the badge. We freeze a
     // stable order at the time of selection: the order is the insertion
     // order of the Set (which JS preserves natively).
@@ -515,7 +547,37 @@ const PhotoPickerView: React.FC<PhotoPickerViewProps> = ({
                 where Yoga already defaults min-height to 0). */}
             <View className="flex-1 min-h-0 bg-black">
                 {/* Photo grid (renders behind the translucent header). */}
-                {isEmpty ? (
+                {isEmpty && loading ? (
+                    /* Loading skeleton — the picker's OWN shape: shimmer tiles laid
+                       out with the SAME placement-aware geometry the real grid uses
+                       (`computePhotoGridLayout(effectiveWidth)`), pushed below the
+                       translucent header by the grid content padding. `flexWrap`
+                       breaks rows exactly at `columns` because the last tile in each
+                       row carries no right margin (a full row + gutters fits the
+                       measured width by construction). The real translucent header
+                       still floats on top, so Cancel stays reachable while loading. */
+                    <View
+                        className="pt-[60px]"
+                        style={{ flexDirection: 'row', flexWrap: 'wrap' }}
+                        pointerEvents="none"
+                        accessibilityElementsHidden
+                        importantForAccessibility="no-hide-descendants"
+                    >
+                        {Array.from({ length: skeletonTileCount }, (_, index) => (
+                            <Skeleton.Box
+                                key={index}
+                                width={cellSize}
+                                height={cellSize}
+                                borderRadius={CELL_CORNER_RADIUS}
+                                style={{
+                                    marginRight: (index + 1) % columns === 0 ? 0 : gutter,
+                                    marginBottom: gutter,
+                                    backgroundColor: SKELETON_TILE_COLOR,
+                                }}
+                            />
+                        ))}
+                    </View>
+                ) : isEmpty ? (
                     <View className="flex-1 items-center justify-center px-space-32 pt-[60px]">
                         <View className="opacity-30 mb-space-16">
                             <MaterialCommunityIcons name="image-outline" size={64} color="#FFFFFF" />