@oxyhq/services 30.0.0 → 30.0.1

package/lib/typescript/module/ui/stores/followStore.d.ts

@@ -0,0 +1,30 @@
+import type { OxyServices, BulkFollowResult, BulkUnfollowResult } from '@oxyhq/core';
+interface FollowState {
+    followingUsers: Record<string, boolean>;
+    loadingUsers: Record<string, boolean>;
+    fetchingUsers: Record<string, boolean>;
+    errors: Record<string, string | null>;
+    followerCounts: Record<string, number>;
+    followingCounts: Record<string, number>;
+    loadingCounts: Record<string, boolean>;
+    setFollowingStatus: (userId: string, isFollowing: boolean) => void;
+    setFollowStatuses: (map: Record<string, boolean>) => void;
+    clearFollowError: (userId: string) => void;
+    resetFollowState: () => void;
+    resolveFollowStatuses: (userIds: string[], oxyServices: OxyServices) => void;
+    toggleFollowUser: (userId: string, oxyServices: OxyServices, isCurrentlyFollowing: boolean) => Promise<boolean>;
+    followManyUsers: (userIds: string[], oxyServices: OxyServices) => Promise<BulkFollowResult>;
+    unfollowManyUsers: (userIds: string[], oxyServices: OxyServices) => Promise<BulkUnfollowResult>;
+    setFollowerCount: (userId: string, count: number) => void;
+    setFollowingCount: (userId: string, count: number) => void;
+    updateCountsFromFollowAction: (targetUserId: string, action: 'follow' | 'unfollow', counts: {
+        followers: number;
+        following: number;
+    }, currentUserId?: string) => void;
+    fetchUserCounts: (userId: string, oxyServices: OxyServices) => Promise<void>;
+}
+/** Clears module-level micro-batch coordination state (test + sign-out hooks). */
+export declare const resetFollowBatchState: () => void;
+export declare const useFollowStore: import("zustand").UseBoundStore<import("zustand").StoreApi<FollowState>>;
+export {};
+//# sourceMappingURL=followStore.d.ts.map

package/lib/typescript/module/ui/stores/followStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"followStore.d.ts","sourceRoot":"","sources":["../../../../../src/ui/stores/followStore.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,kBAAkB,EAAwB,MAAM,aAAa,CAAC;AAE3G,UAAU,WAAW;IAKnB,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;IAEtC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAExC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,kBAAkB,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,KAAK,IAAI,CAAC;IAKnE,iBAAiB,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IAC1D,gBAAgB,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,gBAAgB,EAAE,MAAM,IAAI,CAAC;IAI7B,qBAAqB,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,WAAW,EAAE,WAAW,KAAK,IAAI,CAAC;IAC7E,gBAAgB,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,oBAAoB,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAEhH,eAAe,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,WAAW,EAAE,WAAW,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAE5F,iBAAiB,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,WAAW,EAAE,WAAW,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAEhG,gBAAgB,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1D,iBAAiB,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3D,4BAA4B,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,GAAG,UAAU,EAAE,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,EAAE,aAAa,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACtK,eAAe,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9E;AA8BD,kFAAkF;AAClF,eAAO,MAAM,qBAAqB,QAAO,IAMxC,CAAC;AAEF,eAAO,MAAM,cAAc,0EA+WxB,CAAC"}

package/lib/typescript/module/ui/stores/followTargetStore.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The follow-graph store — the client's single cache authority for #809.
+ *
+ * The SDK caches none of these reads on purpose (a status cached across a write
+ * is the "follow reverts after navigating away and back" bug), which makes this
+ * store the one place a status lives between a write and the next read. If a
+ * second cache appears above it, the two will disagree the moment one is
+ * invalidated and the other is not.
+ *
+ * ## Keyed by target id, not by user id
+ *
+ * The legacy `followStore` is keyed by user id because the only followable
+ * thing was a user. Here a key is a target of any kind — a topic, a store, an
+ * artist, a channel — so nothing in this file may assume what it is looking at.
+ * That is the property that lets an application the SDK has never heard of use
+ * it without a release.
+ *
+ * ## Why the status is stored whole
+ *
+ * Not a boolean. `globalState`, `applicationMode` and `effectiveState` are
+ * three separate answers, and a UI that keeps only the last one cannot explain
+ * why a follow the user can see in their list does nothing in this app.
+ */
+import type { FollowApplicationMode, FollowRecord, FollowStatus } from '@oxyhq/contracts';
+/** The status of one target, or `undefined` when it has never been read. */
+type StatusMap = Record<string, FollowStatus | undefined>;
+interface FollowTargetState {
+    statuses: StatusMap;
+    /** In-flight writes, per target. Reads do not set this — only mutations do. */
+    pending: Record<string, boolean>;
+    errors: Record<string, string | undefined>;
+    setStatus: (targetId: string, status: FollowStatus) => void;
+    /**
+     * Seed many statuses at once — from a follow list, a feed payload, anything
+     * that already knows. Saves one request per rendered row, which is the
+     * difference between a list that paints and a list that flickers.
+     */
+    seed: (entries: Record<string, FollowStatus>) => void;
+    setPending: (targetId: string, pending: boolean) => void;
+    setError: (targetId: string, error: string | undefined) => void;
+    /** Drop everything. Called on identity change — see the note below. */
+    reset: () => void;
+}
+/**
+ * The state one target is in before the server has been asked. Distinct from
+ * "not following": a button that renders a follow action while the answer is
+ * unknown invites a follow the user did not intend, so callers check
+ * `isUnknown` rather than reading this as an answer.
+ */
+export declare const UNKNOWN_FOLLOW_STATUS: FollowStatus;
+export declare const useFollowTargetStore: import("zustand").UseBoundStore<import("zustand").StoreApi<FollowTargetState>>;
+/**
+ * Whether the user follows this at all, anywhere.
+ *
+ * Deliberately NOT `effectiveState !== 'not_following'`: a follow switched off
+ * in this application reports `not_following` — correctly, since the question
+ * that field answers is "does this act here" — and a button that read it as
+ * "not followed" would offer to follow something already followed.
+ */
+export declare function isFollowedGlobally(status: FollowStatus): boolean;
+/**
+ * Whether a cached status is safe to act on without a round trip.
+ *
+ * List payloads often carry `globalState` without `relationshipId`. Treating
+ * that as authoritative would leave disable/unfollow as no-ops forever.
+ */
+export declare function isCompleteFollowStatus(status: FollowStatus): boolean;
+/** Convert one list row into the status shape the follow-target store expects. */
+export declare function followRecordToStatus(record: FollowRecord): FollowStatus;
+/**
+ * Bulk-convert a follow list page into a status map keyed by target id — the
+ * input shape for `useFollowTargetStore.getState().seed(...)`.
+ */
+export declare function followRecordsToStatusMap(records: FollowRecord[]): Record<string, FollowStatus>;
+/**
+ * Apply a mode change to a cached status without a round trip.
+ *
+ * Exported because the optimistic path and the settled path must agree on what
+ * `effectiveState` becomes; deriving it in two places is how they drift. Mirrors
+ * the server's own derivation, which is the authority.
+ */
+export declare function withApplicationMode(status: FollowStatus, mode: FollowApplicationMode): FollowStatus;
+export {};
+//# sourceMappingURL=followTargetStore.d.ts.map

package/lib/typescript/module/ui/stores/followTargetStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"followTargetStore.d.ts","sourceRoot":"","sources":["../../../../../src/ui/stores/followTargetStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAAE,qBAAqB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAE1F,4EAA4E;AAC5E,KAAK,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,CAAC,CAAC;AAE1D,UAAU,iBAAiB;IACzB,QAAQ,EAAE,SAAS,CAAC;IACpB,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAE3C,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IAC5D;;;;OAIG;IACH,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,KAAK,IAAI,CAAC;IACtD,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IACzD,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAC;IAChE,uEAAuE;IACvE,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,YAInC,CAAC;AAEF,eAAO,MAAM,oBAAoB,gFAoB9B,CAAC;AAEJ;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAGpE;AAED,kFAAkF;AAClF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAQvE;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAM9F;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,qBAAqB,GAC1B,YAAY,CAad"}

package/lib/typescript/module/ui/stores/resetSessionScopedStores.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Drop session-scoped Zustand slices so the next user/account never inherits
+ * stale UI state.
+ *
+ * The file library is NOT reset here: it lives in React Query keyed by owner id
+ * (`queryKeys.files.list(ownerId)`), so switching accounts naturally shows the
+ * new owner's files and the old owner's cache is garbage-collected on its own.
+ */
+export declare function resetSessionScopedStores(): void;
+//# sourceMappingURL=resetSessionScopedStores.d.ts.map

package/lib/typescript/module/ui/stores/resetSessionScopedStores.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resetSessionScopedStores.d.ts","sourceRoot":"","sources":["../../../../../src/ui/stores/resetSessionScopedStores.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAG/C"}

package/lib/typescript/module/ui/types/fileManagement.d.ts

@@ -0,0 +1,51 @@
+import type { BaseScreenProps } from './navigation.js';
+import type { FileMetadata } from '@oxyhq/core';
+export type OnConfirmFileSelection = (files: FileMetadata[]) => void;
+export interface FileManagementScreenProps extends BaseScreenProps {
+    userId?: string;
+    containerWidth?: number;
+    selectMode?: boolean;
+    multiSelect?: boolean;
+    onSelect?: (file: FileMetadata) => void;
+    /**
+     * Forward-navigation picker: called with the picked file in single-select
+     * mode when the picker is one FRAME of a larger in-surface flow. Unlike
+     * {@link onSelect}, the caller is expected to NAVIGATE the surface onward
+     * (e.g. the avatar flow pushes the cropper on top of this picker) — so on
+     * select the picker neither dismisses nor closes the session, and its
+     * Cancel/back pops THIS frame (returning to the frame that opened the picker)
+     * rather than closing. Takes precedence over `onSelect`/`dismiss` when set.
+     */
+    onPicked?: (file: FileMetadata) => void;
+    onConfirmSelection?: OnConfirmFileSelection;
+    initialSelectedIds?: string[];
+    maxSelection?: number;
+    disabledMimeTypes?: string[];
+    /**
+     * What to do after a single selection (non-multiSelect) is made.
+     * 'close' (default) will dismiss the bottom sheet via onClose.
+     * 'back' will navigate back to the previous screen (e.g., return to AccountSettings without closing sheet).
+     * 'none' will keep the picker open (caller can manually close or navigate).
+     */
+    afterSelect?: 'close' | 'back' | 'none';
+    allowUploadInSelectMode?: boolean;
+    /**
+     * Default visibility for uploaded files in this screen
+     * Useful for third-party apps that want files to be public (e.g., GIF selector)
+     */
+    defaultVisibility?: 'private' | 'public' | 'unlisted';
+    /**
+     * Link context for tracking file usage by third-party apps
+     * When provided, selected files will be linked to this entity
+     */
+    linkContext?: {
+        app: string;
+        entityType: string;
+        entityId: string;
+        webhookUrl?: string;
+    };
+}
+export type ViewMode = 'all' | 'photos' | 'videos' | 'documents' | 'audio';
+export type SortBy = 'date' | 'size' | 'name' | 'type';
+export type SortOrder = 'asc' | 'desc';
+//# sourceMappingURL=fileManagement.d.ts.map

package/lib/typescript/module/ui/types/fileManagement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileManagement.d.ts","sourceRoot":"","sources":["../../../../../src/ui/types/fileManagement.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAc,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,MAAM,MAAM,sBAAsB,GAAG,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,IAAI,CAAC;AAErE,MAAM,WAAW,yBAA0B,SAAQ,eAAe;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,CAAC;IACxC;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,CAAC;IAExC,kBAAkB,CAAC,EAAE,sBAAsB,CAAC;IAE5C,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IACxC,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC;;;OAGG;IACH,iBAAiB,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,UAAU,CAAC;IACtD;;;OAGG;IACH,WAAW,CAAC,EAAE;QACV,GAAG,EAAE,MAAM,CAAC;QACZ,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;CACL;AAED,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,OAAO,CAAC;AAC3E,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AACvD,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,MAAM,CAAC"}

package/lib/typescript/module/ui/types/navigation.d.ts

@@ -0,0 +1,153 @@
+import type { ReactNode, RefObject } from 'react';
+import type { QueryClient } from '@tanstack/react-query';
+import type { RouteName } from '../navigation/routes.js';
+import type { SessionMode } from '@oxyhq/core';
+import type { WebAuthMode } from '../oauth/types.js';
+export interface StepController {
+    canGoBack: () => boolean;
+    goBack: () => void;
+}
+export interface BaseScreenProps {
+    navigate?: (screen: RouteName, props?: Record<string, unknown>) => void;
+    goBack?: () => void;
+    /** Whether the host surface can navigate back — a deeper frame OR a prior step. */
+    canGoBack?: () => boolean;
+    onClose?: () => void;
+    onAuthenticated?: (payload?: unknown) => void;
+    /**
+     * Dismiss THIS surface, resolving the `present()` promise that opened it
+     * with `result`. Injected by the surface host (the P1 surface stack). Picker
+     * and crop screens use it to hand a typed result back to the awaiting
+     * `surfaces.present(...)` call instead of an untyped `onSelect`/`onConfirm`
+     * callback prop.
+     */
+    dismiss?: (result?: unknown) => void;
+    theme?: 'light' | 'dark' | string;
+    initialStep?: number;
+    stepControllerRef?: RefObject<StepController | null>;
+    onStepChange?: (currentStep: number, totalSteps: number) => void;
+    currentScreen?: RouteName;
+    scrollTo?: (y: number, animated?: boolean) => void;
+    username?: string;
+    email?: string;
+    password?: string;
+    confirmPassword?: string;
+    userProfile?: unknown;
+    [key: string]: unknown;
+}
+export interface OxyProviderProps {
+    oxyServices?: unknown;
+    children?: ReactNode;
+    onAuthStateChange?: (user: unknown) => void;
+    storageKeyPrefix?: string;
+    /**
+     * The app's Oxy OAuth client id / ApplicationCredential publicKey.
+     * Required for the cross-app device sign-in flow: the QR / approval-window
+     * sign-in registers a device-flow session via `POST /auth/session/create`,
+     * which now identifies the requesting app by this real registered
+     * client id. The central Oxy auth experience resolves and renders the
+     * consent identity from it server-side. Without it the device sign-in
+     * flow cannot start.
+     */
+    clientId?: string;
+    baseURL?: string;
+    authWebUrl?: string;
+    authRedirectUri?: string;
+    /**
+     * Authorize endpoint override for web "Sign in with Oxy". Defaults to the
+     * production Oxy IdP (`https://auth.oxy.so/authorize`) when unset. Set this
+     * from an env var (e.g. Vite `VITE_OXY_AUTHORIZE_URL`, Expo
+     * `EXPO_PUBLIC_OXY_AUTHORIZE_URL`) so a local/staging deployment targets its
+     * own IdP instead of production.
+     */
+    authorizeBaseUrl?: string;
+    /**
+     * Who owns this app's session.
+     *
+     * - `'account'` (default) — the device's ACTIVE account. Every ordinary Oxy
+     *   app: any app sharing the device's `DeviceSession` can switch the active
+     *   account and this one follows, sign-in surfaces and the account switcher
+     *   are available, and `accounts` lists the account graph.
+     * - `'identity'` — the owner of this device's PRIMARY identity key, for as
+     *   long as that key exists. The provider pins its authenticated user AND
+     *   its bearer to the account that key authenticates as, so an account
+     *   switch made by any sibling app changes the shared device state but never
+     *   this app's user or token. Built for the identity vault (Commons).
+     *
+     * In `'identity'` mode the account-graph surfaces are disabled at the source
+     * rather than hidden in the UI: `accounts` stays empty and is never fetched,
+     * `switchToAccount` / `switchSession` reject with `IdentityBoundSessionError`,
+     * `accountDialogController` is `null` and `openAccountDialog()` does nothing,
+     * and the web OAuth cold-boot lane (the authorization-code return leg) is
+     * skipped — it commits whichever account the IdP resolves, which is not
+     * necessarily the local key's owner.
+     *
+     * Read once at mount, like `baseURL` / `oxyServices`: changing it on a
+     * mounted provider does not re-bind the session.
+     * @default 'account'
+     */
+    sessionMode?: SessionMode;
+    /**
+     * How a WEB third-party "Sign in with Oxy" hands the user to the IdP.
+     *
+     * - `'popup'` (default) — a small `auth.oxy.so` window opened from the
+     *   user's click. The app stays MOUNTED and becomes authenticated without a
+     *   reload; the IdP delivers only the authorization code + `state` back to
+     *   the opener via `postMessage` (never a token, device secret, or PKCE
+     *   verifier). A blocked popup falls back to the redirect automatically.
+     * - `'redirect'` — a full-page navigation to `auth.oxy.so`, which returns to
+     *   the registered `redirect_uri` with `?code=`. The tab unmounts and
+     *   remounts, so route and unsaved state are lost.
+     *
+     * Either way the navigation only ever happens from a real user gesture: the
+     * SDK never bounces the top-level window on its own (#691 phase 7b).
+     *
+     * Native is unaffected — it always uses an in-app auth session.
+     * @default 'popup'
+     */
+    webAuthMode?: WebAuthMode;
+    queryClient?: QueryClient;
+    /**
+     * Convenience: wrap the whole app subtree in `<RequireOxyAuth prompt=...>`.
+     * `off` (default) renders children unconditionally; `soft` adds a dismissible
+     * sign-in banner while signed out; `hard` blocks the app behind the signed-out
+     * wall until the user signs in. For finer control, mount `RequireOxyAuth`
+     * yourself around a specific subtree instead.
+     * @default 'off'
+     */
+    requireAuth?: 'off' | 'soft' | 'hard';
+    /**
+     * When true, provisions a non-rotating background credential for native code
+     * (Android widgets) that runs without a JS runtime. Android-only today; inert
+     * on web and iOS.
+     * @default false
+     */
+    backgroundSession?: boolean;
+    /**
+     * Whether this origin/app may persist the durable device credential
+     * (`deviceId` + `deviceSecret`) at all.
+     *
+     * `'persistent'` (the default, and every app's behaviour) stores it — web
+     * localStorage per origin, SecureStore per app on native — so the SDK can
+     * re-mint an access token on the next cold boot.
+     *
+     * `'ephemeral'` stores NOTHING durable: the session lives in memory for the
+     * lifetime of the page and is gone on reload. It exists for ONE caller,
+     * `auth.oxy.so` with the browser hub enabled (issue #937 Phase 5, ADR 0003),
+     * where the durable credential for the browser profile is the server-side
+     * DeviceSession behind the `__Host-oxy-device` handle. Two durable
+     * credentials for one origin is the dual authority that phase exists to
+     * remove — revoking the hub while a localStorage secret still mints would
+     * make a sign-out look like it worked — so the way to let the hub be
+     * authoritative is to stop persisting the other one, not to consult it
+     * second.
+     *
+     * Do NOT reach for this to make an app "more private". A relying-party
+     * origin set to `'ephemeral'` simply signs the user out on every reload,
+     * because nothing else on that origin remembers the device.
+     *
+     * @default 'persistent'
+     */
+    deviceCredentialStorage?: 'persistent' | 'ephemeral';
+}
+//# sourceMappingURL=navigation.d.ts.map

package/lib/typescript/module/ui/types/navigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../../../../src/ui/types/navigation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAsB,CAAC;AAEtD,OAAO,KAAK,EAAiB,WAAW,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAgB,CAAC;AAElD,MAAM,WAAW,cAAc;IAC3B,SAAS,EAAE,MAAM,OAAO,CAAC;IACzB,MAAM,EAAE,MAAM,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAE5B,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACxE,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,eAAe,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC9C;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAGrC,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IAGlC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACrD,YAAY,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;IAGjE,aAAa,CAAC,EAAE,SAAS,CAAC;IAG1B,QAAQ,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAGnD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,OAAO,CAAC;IAMtB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC7B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IAC5C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;;;;;;;;;;;;;;OAiBG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;IACtC;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,uBAAuB,CAAC,EAAE,YAAY,GAAG,WAAW,CAAC;CACxD"}

package/lib/typescript/module/ui/types/surfaceScreen.d.ts

@@ -0,0 +1,38 @@
+import type { RouteName } from '../navigation/routes.js';
+import type { SurfaceProps, SurfaceResult } from '../navigation/surfaceRegistry.js';
+/**
+ * The typed prop contract a screen receives when it is bound into an SDK surface.
+ *
+ * This is the successor to the grab-bag `BaseScreenProps`: `props` carries the
+ * route's own {@link SurfaceProps typed props}, and the navigation methods are
+ * split along the two axes the surface system models — NAV-WITHIN
+ * (`navigate`/`replace`/`goBack`/`step`) inside this surface, and DEPTH
+ * (`present`/`dismiss`) across the stack.
+ *
+ * In P1 the ~35 screens still consume the legacy `BaseScreenProps` shape (the
+ * `SurfaceScreen` binding passes a superset that satisfies both), so this type is
+ * the target contract for the per-screen migration in a later phase — it is not
+ * yet the render-time prop shape for existing screens.
+ */
+export interface SurfaceScreenProps<K extends RouteName> {
+    /** The route's typed props (from the {@link SurfaceProps registry}). */
+    props: SurfaceProps<K>;
+    /** Drill in to another route — WITHIN this surface, or a new surface if the
+     * target's presentation differs. */
+    navigate: <T extends RouteName>(route: T, props?: SurfaceProps<T>) => void;
+    /** Replace the current route in place (no history entry). */
+    replace: <T extends RouteName>(route: T, props?: SurfaceProps<T>) => void;
+    /** Pop one level; if at the root, dismiss the surface. */
+    goBack: () => void;
+    /** Whether a back is possible (a deeper route OR a prior wizard step). */
+    canGoBack: () => boolean;
+    /** Dismiss THIS surface, resolving its `present()` promise with `result`. */
+    dismiss: (result?: SurfaceResult<K>) => void;
+    /** Present a NEW surface on top of the stack (DEPTH); resolves with its result. */
+    present: <T extends RouteName>(route: T, props?: SurfaceProps<T>) => Promise<SurfaceResult<T> | undefined>;
+    /** The current wizard step of this frame. */
+    step: number;
+    /** Set the current wizard step. */
+    setStep: (step: number) => void;
+}
+//# sourceMappingURL=surfaceScreen.d.ts.map

package/lib/typescript/module/ui/types/surfaceScreen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surfaceScreen.d.ts","sourceRoot":"","sources":["../../../../../src/ui/types/surfaceScreen.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,kCAA+B,CAAC;AAEjF;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,SAAS;IACrD,wEAAwE;IACxE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IACvB;wCACoC;IACpC,QAAQ,EAAE,CAAC,CAAC,SAAS,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAC3E,6DAA6D;IAC7D,OAAO,EAAE,CAAC,CAAC,SAAS,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAC1E,0DAA0D;IAC1D,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,0EAA0E;IAC1E,SAAS,EAAE,MAAM,OAAO,CAAC;IACzB,6EAA6E;IAC7E,OAAO,EAAE,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAC7C,mFAAmF;IACnF,OAAO,EAAE,CAAC,CAAC,SAAS,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAC3G,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC"}

package/lib/typescript/module/ui/utils/avatarUtils.d.ts

@@ -0,0 +1,16 @@
+import type { OxyServices, User } from '@oxyhq/core';
+import type { UserProfileUpdate } from '@oxyhq/contracts';
+import type { QueryClient } from '@tanstack/react-query';
+/**
+ * Updates user profile with avatar and handles all side effects (cache writes,
+ * query invalidation). Usable from inside the provider without `useOxy`.
+ *
+ * @param updates - Profile updates including avatar
+ * @param oxyServices - OxyServices instance
+ * @param activeSessionId - Active session ID
+ * @param queryClient - TanStack Query client
+ * @param syncSession - Optional function to sync session/refresh token when auth errors occur
+ * @returns Promise that resolves with updated user data
+ */
+export declare function updateProfileWithAvatar(updates: UserProfileUpdate, oxyServices: OxyServices, activeSessionId: string | null, queryClient: QueryClient, syncSession?: () => Promise<User>): Promise<User>;
+//# sourceMappingURL=avatarUtils.d.ts.map

package/lib/typescript/module/ui/utils/avatarUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"avatarUtils.d.ts","sourceRoot":"","sources":["../../../../../src/ui/utils/avatarUtils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAOzD;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,iBAAiB,EAC1B,WAAW,EAAE,WAAW,EACxB,eAAe,EAAE,MAAM,GAAG,IAAI,EAC9B,WAAW,EAAE,WAAW,EACxB,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAChC,OAAO,CAAC,IAAI,CAAC,CA2Bf"}

package/lib/typescript/module/ui/utils/colorUtils.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Color Utility Functions
+ *
+ * Re-exports from shared module for cleaner internal imports.
+ * External consumers should use '@oxyhq/services/shared' directly.
+ *
+ * @module ui/utils/colorUtils
+ */
+export { darkenColor, lightenColor, hexToRgb, rgbToHex, withOpacity, isLightColor, getContrastTextColor, } from '@oxyhq/core';
+//# sourceMappingURL=colorUtils.d.ts.map

package/lib/typescript/module/ui/utils/colorUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"colorUtils.d.ts","sourceRoot":"","sources":["../../../../../src/ui/utils/colorUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,WAAW,EACX,YAAY,EACZ,QAAQ,EACR,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,oBAAoB,GACrB,MAAM,aAAa,CAAC"}

package/lib/typescript/module/ui/utils/commonsStoreLinks.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Where to send a user who doesn't have Commons installed yet.
+ *
+ * Commons is not published to either app store as of this writing (no submit
+ * profile in its `eas.json`, no store listing) — so these are ALWAYS
+ * env-overridable and NEVER hardcoded, and the landing-page fallback exists
+ * precisely so a "Get Commons" affordance is never a dead link in the
+ * meantime. Once Commons ships to TestFlight/Play, set the two store env vars
+ * and every consumer picks them up with no code change.
+ */
+/** Real per-platform store URLs, or `undefined` where not yet configured. */
+export interface CommonsStoreLinks {
+    ios: string | undefined;
+    android: string | undefined;
+}
+/** Per-platform Commons store URLs, from env — `undefined` when unset. */
+export declare function getCommonsStoreLinks(): CommonsStoreLinks;
+/**
+ * Resolve the "Get Commons" href for the current platform. Never `undefined`
+ * — falls back to a landing page so the affordance is always a working link,
+ * store listing or not.
+ */
+export declare function getCommonsAcquisitionUrl(platformOS: 'ios' | 'android' | string): string;
+//# sourceMappingURL=commonsStoreLinks.d.ts.map

package/lib/typescript/module/ui/utils/commonsStoreLinks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commonsStoreLinks.d.ts","sourceRoot":"","sources":["../../../../../src/ui/utils/commonsStoreLinks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,6EAA6E;AAC7E,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACxB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAED,0EAA0E;AAC1E,wBAAgB,oBAAoB,IAAI,iBAAiB,CAKxD;AAKD;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,KAAK,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,CAIvF"}

package/lib/typescript/module/ui/utils/deliveryPlatform.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Classify the surface a "Sign in with Oxy" request is initiated from, for
+ * `AccountDialogController`'s `platform` option (issue #691, Phase 4/5).
+ *
+ * `@oxyhq/core` deliberately refuses to do this itself — it never touches a
+ * platform global — so the consumer that OWNS the environment classifies it and
+ * hands the verdict in. The verdict feeds `selectCommonsDelivery`, where it
+ * decides one thing only: whether this device may take the `'open-commons'`
+ * deep-link route. Getting it wrong in the "mobile" direction is the costly
+ * error (a custom-scheme navigation that does not resolve is a dead end with no
+ * automatic way back), so every ambiguous signal resolves AWAY from `'mobile'`.
+ *
+ * No user-agent string is parsed. The two signals used are declarative and
+ * standardized:
+ *   1. `navigator.userAgentData.mobile` — the User-Agent Client Hints boolean.
+ *      Authoritative where implemented (Chromium), in both directions.
+ *   2. The PRIMARY pointer (`(pointer: coarse)`) plus a touch digitizer.
+ *      A phone/tablet reports a coarse primary pointer; a touchscreen laptop
+ *      still reports its mouse as primary, so it is not misclassified.
+ */
+import type { CommonsDeliveryPlatform } from '@oxyhq/core';
+/**
+ * Which surface this app is running on, as `selectCommonsDelivery` models it.
+ *
+ *  - Native (Expo/RN) is always `'mobile'`: it is an Oxy app installed on a
+ *    phone/tablet, exactly the case where a verified Commons link can resolve
+ *    on this very device.
+ *  - A web browser is classified from the signals above.
+ *  - Anything else — a browser-like environment with neither signal — is
+ *    `'unknown'`, a first-class value that never opts into the deep link.
+ */
+export declare function resolveDeliveryPlatform(): CommonsDeliveryPlatform;
+//# sourceMappingURL=deliveryPlatform.d.ts.map

package/lib/typescript/module/ui/utils/deliveryPlatform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deliveryPlatform.d.ts","sourceRoot":"","sources":["../../../../../src/ui/utils/deliveryPlatform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAiB3D;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,IAAI,uBAAuB,CAgBjE"}

package/lib/typescript/module/ui/utils/deviceCredential.d.ts

@@ -0,0 +1,8 @@
+import type { AuthStateStore } from '@oxyhq/core';
+/** True when the persisted store holds a device credential. */
+export declare function hasPersistedDeviceCredential(store: AuthStateStore): Promise<boolean>;
+export declare function loadPersistedDeviceCredential(store: AuthStateStore): Promise<{
+    deviceId: string;
+    deviceSecret: string;
+} | null>;
+//# sourceMappingURL=deviceCredential.d.ts.map

package/lib/typescript/module/ui/utils/deviceCredential.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deviceCredential.d.ts","sourceRoot":"","sources":["../../../../../src/ui/utils/deviceCredential.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,+DAA+D;AAC/D,wBAAsB,4BAA4B,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAG1F;AAED,wBAAsB,6BAA6B,CACjD,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAM5D"}

package/lib/typescript/module/ui/utils/errorHandlers.d.ts

@@ -0,0 +1,35 @@
+import type { ApiError } from '@oxyhq/core';
+export interface HandleAuthErrorOptions {
+    defaultMessage: string;
+    code: string;
+    status?: number;
+    onError?: (error: ApiError) => void;
+    setAuthError?: (message: string) => void;
+    logger?: (message: string, error?: unknown) => void;
+}
+/**
+ * Determine whether the error represents an invalid session condition.
+ * This centralizes 401 detection across different fetch clients.
+ */
+export declare const isInvalidSessionError: (error: unknown) => boolean;
+/**
+ * Determine whether the error represents a timeout or network error.
+ * These are expected when the device is offline or has poor connectivity.
+ */
+export declare const isTimeoutOrNetworkError: (error: unknown) => boolean;
+/**
+ * Extract a consistent error message from unknown error shapes.
+ *
+ * @param error - The unknown error payload
+ * @param fallbackMessage - Message to return when no concrete message is available
+ */
+export declare const extractErrorMessage: (error: unknown, fallbackMessage?: string) => string;
+/**
+ * Centralized error handler for auth-related operations.
+ *
+ * @param error - Unknown error object
+ * @param options - Error handling configuration
+ * @returns Resolved error message
+ */
+export declare const handleAuthError: (error: unknown, { defaultMessage, code, status, onError, setAuthError, logger, }: HandleAuthErrorOptions) => string;
+//# sourceMappingURL=errorHandlers.d.ts.map

package/lib/typescript/module/ui/utils/errorHandlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorHandlers.d.ts","sourceRoot":"","sources":["../../../../../src/ui/utils/errorHandlers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAgB5C,MAAM,WAAW,sBAAsB;IACrC,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,CAAC;IACpC,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CACrD;AAkBD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,GAAI,OAAO,OAAO,KAAG,OA4BtD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,uBAAuB,GAAI,OAAO,OAAO,KAAG,OA0CxD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAC9B,OAAO,OAAO,EACd,wBAAoC,KACnC,MAuBF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAC1B,OAAO,OAAO,EACd,kEAOG,sBAAsB,KACxB,MAiBF,CAAC"}

package/lib/typescript/module/ui/utils/fileManagement.d.ts

@@ -0,0 +1,55 @@
+import type Ionicons from "@expo/vector-icons/Ionicons";
+import type { AssetUploadInput, RNFileDescriptor } from "@oxyhq/core";
+import type { ComponentProps } from "react";
+/**
+ * Extended File interface that includes a `uri` property for mobile preview support.
+ * React Native file pickers return URI-based references that need to be preserved
+ * on the File object for preview rendering.
+ */
+interface FileWithUri extends File {
+    uri?: string;
+}
+/**
+ * Picker descriptor as returned by expo-document-picker / expo-image-picker.
+ * Carries enough info to either build a web `File` from the URI or pass the
+ * descriptor straight to FormData on React Native.
+ */
+export interface PickerAsset {
+    file?: File | Blob;
+    uri?: string;
+    name?: string | null;
+    mimeType?: string | null;
+    size?: number | null;
+}
+/**
+ * Type guard — returns true if the input is a React Native file descriptor
+ * (carries a URI but is not a real DOM `File` / `Blob` instance).
+ */
+export declare function isRNFileDescriptor(input: unknown): input is RNFileDescriptor;
+/**
+ * Format file size in bytes to human-readable string
+ */
+export declare function formatFileSize(bytes: number): string;
+/**
+ * Get icon name for file based on content type
+ */
+export declare function getFileIcon(contentType: string): ComponentProps<typeof Ionicons>["name"];
+/**
+ * Convert a document/image picker asset into a value that
+ * `OxyServices.assetUpload` can accept.
+ *
+ * - On the web, builds a real `File` (with the `uri` field preserved for
+ *   preview rendering) by fetching the asset as a Blob.
+ * - On React Native (iOS/Android), returns the picker descriptor directly
+ *   ({ uri, type, name, size }). RN's `FormData` reads the file from disk
+ *   during the multipart upload — no in-JS Blob conversion needed. Attempting
+ *   to wrap an ArrayBuffer in a Blob fails on Hermes ("Creating blobs from
+ *   'ArrayBuffer' and 'ArrayBufferView' are not supported").
+ */
+export declare function convertDocumentPickerAssetToFile(doc: PickerAsset, index: number): Promise<FileWithUri | RNFileDescriptor | null>;
+/**
+ * Upload file raw - helper function for file uploads
+ */
+export declare function uploadFileRaw(file: AssetUploadInput, userId: string, oxyServices: any, visibility?: "private" | "public" | "unlisted"): Promise<any>;
+export {};
+//# sourceMappingURL=fileManagement.d.ts.map

package/lib/typescript/module/ui/utils/fileManagement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileManagement.d.ts","sourceRoot":"","sources":["../../../../../src/ui/utils/fileManagement.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,6BAA6B,CAAC;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AAG5C;;;;GAIG;AACH,UAAU,WAAY,SAAQ,IAAI;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC3B,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAO5E;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMpD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAC1B,WAAW,EAAE,MAAM,GACjB,cAAc,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,CAAC,CAYzC;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,gCAAgC,CACrD,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,MAAM,GACX,OAAO,CAAC,WAAW,GAAG,gBAAgB,GAAG,IAAI,CAAC,CAuEhD;AAED;;GAEG;AACH,wBAAsB,aAAa,CAClC,IAAI,EAAE,gBAAgB,EACtB,MAAM,EAAE,MAAM,EAEd,WAAW,EAAE,GAAG,EAChB,UAAU,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,UAAU,gBAG9C"}