@oxyhq/services 23.0.2 → 23.1.0

package/lib/typescript/module/ui/components/OxyProvider.d.ts

@@ -0,0 +1,40 @@
+import { type FC } from 'react';
+import type { OxyProviderProps } from '../types/navigation.js';
+/**
+ * OxyProvider - Universal provider for Expo apps (native + web)
+ *
+ * Provides authentication, session management, query client, and UI overlays.
+ * Wraps its own overlay stack in SafeAreaProvider and GestureHandlerRootView so
+ * the shared Bloom SURFACE STACK (`<SurfaceProvider>` / `<SurfaceHost>`) — which
+ * hosts every SDK surface (the ~35 bottom-sheet routes + the AccountDialog) — can
+ * safely render even when a consuming app has not mounted those providers yet.
+ *
+ * Usage:
+ * ```tsx
+ * import { OxyProvider, useAuth } from '@oxyhq/services';
+ *
+ * function App() {
+ *   return (
+ *     <SafeAreaProvider>
+ *       <GestureHandlerRootView style={{ flex: 1 }}>
+ *         <OxyProvider baseURL="https://api.oxy.so">
+ *           <YourApp />
+ *         </OxyProvider>
+ *       </GestureHandlerRootView>
+ *     </SafeAreaProvider>
+ *   );
+ * }
+ *
+ * function MyComponent() {
+ *   const { isAuthenticated, user, signIn, signOut } = useAuth();
+ *
+ *   if (!isAuthenticated) {
+ *     return <OxySignInButton />;
+ *   }
+ *   return <Text>Welcome, {user?.username}!</Text>;
+ * }
+ * ```
+ */
+declare const OxyProvider: FC<OxyProviderProps>;
+export default OxyProvider;
+//# sourceMappingURL=OxyProvider.d.ts.map

package/lib/typescript/module/ui/components/OxyProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OxyProvider.d.ts","sourceRoot":"","sources":["../../../../../src/ui/components/OxyProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAA+B,KAAK,EAAE,EAAkB,MAAM,OAAO,CAAC;AAI7E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAqB,CAAC;AA6C5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,QAAA,MAAM,WAAW,EAAE,EAAE,CAAC,gBAAgB,CA2OrC,CAAC;AAEF,eAAe,WAAW,CAAC"}

package/lib/typescript/module/ui/components/OxySignInButton.d.ts

@@ -0,0 +1,112 @@
+import type React from 'react';
+import { type ViewStyle, type TextStyle, type StyleProp } from 'react-native';
+/**
+ * The OAuth handshake surfaced to a NATIVE third-party RP via
+ * {@link OxySignInButtonProps.onOAuthResult} so it can finish the code exchange
+ * (`POST /auth/oauth/token`). Web sign-in is handled entirely by the SDK's web
+ * transport (`useOxy().startWebOAuthSignIn`) and never uses this callback.
+ */
+export interface OxyOAuthResult {
+    /** Deep-link URL the native auth session returned to (`?code=…&state=…`), or `null` if unobserved. */
+    redirectUrl: string | null;
+    /** The CSRF `state` sent on the authorize request; the RP must match it on return. */
+    state: string;
+    /** The PKCE `code_verifier` to replay on the token exchange. */
+    codeVerifier: string;
+}
+export interface OxySignInButtonProps {
+    /**
+     * Controls the appearance of the button
+     * @default 'default'
+     */
+    variant?: 'default' | 'outline' | 'contained';
+    /**
+     * Optional function to handle button press
+     * If not provided, the button will use the showBottomSheet method from OxyContext
+     */
+    onPress?: () => void;
+    /**
+     * Additional styles for the button container
+     */
+    style?: StyleProp<ViewStyle>;
+    /**
+     * Additional styles for the button text
+     */
+    textStyle?: StyleProp<TextStyle>;
+    /**
+     * Overrides the button label. When omitted the button renders the ONE
+     * primary relying-party action, localized: `accountSwitcher.continueWithOxy`
+     * ("Continue with Oxy" in English). "Sign in with Oxy" remains the name of
+     * the MECHANISM — only this surface's label is "Continue with Oxy".
+     *
+     * @default localized `accountSwitcher.continueWithOxy`
+     */
+    text?: string;
+    /**
+     * Whether to disable the button
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Whether to show the button even if user is already authenticated
+     * @default false
+     */
+    showWhenAuthenticated?: boolean;
+    /**
+     * Exact registered redirect URI the OAuth authorization code is returned to.
+     * REQUIRED only for third-party (`type: 'third_party'`) applications, which
+     * sign in via OAuth + PKCE against `auth.oxy.so`. First-party / official apps
+     * open the in-app dialog and ignore this prop. If a third-party app resolves
+     * without it, the button logs an error and does nothing (it will not invent a
+     * redirect URI).
+     */
+    oauthRedirectUri?: string;
+    /**
+     * Native only: receives the OAuth handshake after a third-party auth session
+     * so the RP can finish the token exchange. On web the SDK completes the flow
+     * itself — the popup transport keeps the handshake in memory, and the
+     * redirect transport reads it back from `sessionStorage` — so this is never
+     * called there. A native third-party sign-in with NO `onOAuthResult` handler
+     * cannot complete (the `state` + `code_verifier` are lost) and logs a warning.
+     *
+     * @example
+     * ```tsx
+     * <OxySignInButton
+     *   oauthRedirectUri="myapp://oauth/callback"
+     *   onOAuthResult={({ redirectUrl, state, codeVerifier }) => {
+     *     if (!redirectUrl) return;
+     *     const code = new URL(redirectUrl).searchParams.get('code');
+     *     // → POST /auth/oauth/token { code, code_verifier: codeVerifier, state }
+     *   }}
+     * />
+     * ```
+     */
+    onOAuthResult?: (result: OxyOAuthResult) => void;
+}
+/**
+ * A pre-styled button component for signing in with Oxy identity
+ *
+ * This component opens the Oxy Auth flow which allows users to authenticate
+ * using their Oxy Accounts identity (via QR code or deep link).
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <OxySignInButton />
+ *
+ * // Custom styling
+ * <OxySignInButton
+ *   variant="contained"
+ *   style={{ marginTop: 20 }}
+ *   text="Login with Oxy"
+ * />
+ *
+ * // Custom handler
+ * <OxySignInButton onPress={() => {
+ *   // Custom authentication flow
+ * }} />
+ * ```
+ */
+export declare const OxySignInButton: React.FC<OxySignInButtonProps>;
+export default OxySignInButton;
+//# sourceMappingURL=OxySignInButton.d.ts.map

package/lib/typescript/module/ui/components/OxySignInButton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OxySignInButton.d.ts","sourceRoot":"","sources":["../../../../../src/ui/components/OxySignInButton.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,KAAK,SAAS,EAAY,MAAM,cAAc,CAAC;AAoBxF;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC3B,sGAAsG;IACtG,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,sFAAsF;IACtF,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,YAAY,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACjC;;;OAGG;IACH,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;IAE9C;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IAErB;;OAEG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAE7B;;OAEG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAEjC;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;OAGG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAEhC;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,CAAC;CACpD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,EAAE,CAAC,oBAAoB,CA6O1D,CAAC;AAEF,eAAe,eAAe,CAAC"}

package/lib/typescript/module/ui/components/OxySignInRequestSurface.d.ts

@@ -0,0 +1,108 @@
+/**
+ * `OxySignInRequestSurface` — the in-flight "Sign in with Oxy" request, rendered
+ * from plain facts (issue #691, Phase 5).
+ *
+ * The user already performed their one action. From here the surface only
+ * REPORTS: the route-appropriate primary visual, the status line for the
+ * progress it was told about, and nothing else at the same weight. Alternatives
+ * stay behind "Having trouble?" until the chosen route could not be carried out,
+ * at which point they ARE the content and render plainly.
+ *
+ * PRESENTATIONAL AND HEADLESS-FRIENDLY. It owns no request, no controller, no
+ * polling, and no state of its own: everything it draws is a prop. That is what
+ * lets the two hosts of this surface share ONE implementation —
+ *
+ *  - `OxyAuthChooser`'s `SignInRequestView`, driven by `AccountDialogController`'s
+ *    device flow;
+ *  - the auth.oxy.so IdP's OAuth-bound lane, whose request carries an OAuth
+ *    binding the account dialog's session has no concept of.
+ *
+ * It resolves only what every `@oxyhq/services` consumer already has in context:
+ * the Bloom theme (`useTheme`) and the SDK's own locale dictionary (`useI18n`,
+ * the `accountSwitcher.*` copy in all 11 locales). Host-specific copy — the
+ * labels on {@link OxySignInRequestSurfaceProps.subordinate} and
+ * {@link OxySignInRequestSurfaceProps.alternatives} — arrives already localized.
+ *
+ * TWO THINGS IT DELIBERATELY DOES NOT DO:
+ *  - it renders no failure REASON. A host surfaces that the way its own shell
+ *    demands (the account dialog toasts it — errors never render inline there;
+ *    a full page may show a banner around this surface). The surface only takes
+ *    the fact that the request failed, and offers the way forward.
+ *  - it derives nothing from {@link OxySignInRequestSurfaceProps.qrPayload}.
+ *    Application identity, origin, and scopes are resolved server-side by the
+ *    approver (Commons), never read out of a payload here — the plate encodes it
+ *    and shows nothing about it.
+ *
+ * SECRETS: every prop is safe to render. There is no `sessionToken` (the secret
+ * claim/finalize credential), no bearer, and no authorization code — a host
+ * keeps those in its own controller, and no prop on this component invites one.
+ */
+import type React from 'react';
+import type { CommonsDeliveryRoute, SignInProgress } from '@oxyhq/core';
+import type { OxySignInSurfaceAction } from './authChooser/types.js';
+export interface OxySignInRequestSurfaceProps {
+    /**
+     * The ONE primary delivery route chosen for this request, or `null` while it
+     * is still being resolved. There is no chain: the surface renders exactly one
+     * route's visual, and never guesses one that has not been chosen yet.
+     */
+    route: CommonsDeliveryRoute | null;
+    /**
+     * The request's DERIVED progress — the only thing the status line is built
+     * from. It must come from a real observed signal (a server-reported delivery,
+     * an approver opening the request, an approval); the surface owns no clock and
+     * will never advance it on its own. `'idle'` means there is nothing honest to
+     * report, and renders no status line.
+     */
+    progress: SignInProgress;
+    /**
+     * The PUBLIC `oxycommons://approve?…` payload to encode as the QR, or `null`.
+     * It carries the single-use approval handle — never a secret credential — and
+     * the surface renders NOTHING derived from it.
+     */
+    qrPayload?: string | null;
+    /**
+     * `true` when the chosen primary route could not be carried out on this device.
+     * The one signal that reveals {@link alternatives} without the user asking;
+     * a host never silently cascades to another route on its own.
+     */
+    routeFailed?: boolean;
+    /**
+     * `true` when the request itself is terminally failed — there is no working
+     * primary route left to report on, so {@link onRetry} becomes the surface's one
+     * primary action and the alternatives render plainly.
+     */
+    failed?: boolean;
+    /**
+     * Start a BRAND-NEW request. Rendered as the primary action while
+     * {@link failed}; omit it when a fresh attempt cannot help (a request that
+     * would fail identically every time), leaving the alternatives as the only
+     * way forward.
+     */
+    onRetry?: () => void;
+    /**
+     * The acquisition action for a device where Commons is known to be ABSENT.
+     *
+     * Pass it ONLY on a positive "not installed" verdict. There, acquiring Commons
+     * is the GENUINE primary route — a same-device QR the user would have to scan
+     * with the very screen showing it is a dead end — so the surface leads with it
+     * and reports no route progress. Omit it wherever absence cannot be known (a
+     * browser cannot ask whether a URL scheme is registered).
+     */
+    onAcquireCommons?: () => void;
+    /**
+     * Subordinate links rendered directly beneath the primary, always visible:
+     * the ways OUT of the surface that are not troubleshooting (creating an
+     * account, cancelling the request).
+     */
+    subordinate?: readonly OxySignInSurfaceAction[];
+    /**
+     * The alternative ways to authenticate, kept behind "Having trouble?" until
+     * the user asks — or shown plainly once {@link failed} / {@link routeFailed}
+     * says the chosen route cannot deliver.
+     */
+    alternatives?: readonly OxySignInSurfaceAction[];
+}
+export declare const OxySignInRequestSurface: React.FC<OxySignInRequestSurfaceProps>;
+export default OxySignInRequestSurface;
+//# sourceMappingURL=OxySignInRequestSurface.d.ts.map

package/lib/typescript/module/ui/components/OxySignInRequestSurface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OxySignInRequestSurface.d.ts","sourceRoot":"","sources":["../../../../../src/ui/components/OxySignInRequestSurface.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAK/B,OAAO,KAAK,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAOxE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,wBAAqB,CAAC;AAKlE,MAAM,WAAW,4BAA4B;IAC3C;;;;OAIG;IACH,KAAK,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACnC;;;;;;OAMG;IACH,QAAQ,EAAE,cAAc,CAAC;IACzB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,MAAM,IAAI,CAAC;IAC9B;;;;OAIG;IACH,WAAW,CAAC,EAAE,SAAS,sBAAsB,EAAE,CAAC;IAChD;;;;OAIG;IACH,YAAY,CAAC,EAAE,SAAS,sBAAsB,EAAE,CAAC;CAClD;AAED,eAAO,MAAM,uBAAuB,EAAE,KAAK,CAAC,EAAE,CAAC,4BAA4B,CA8E1E,CAAC;AAEF,eAAe,uBAAuB,CAAC"}

package/lib/typescript/module/ui/components/ProfileButton.d.ts

@@ -0,0 +1,56 @@
+import type React from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+export interface ProfileButtonProps {
+    /**
+     * Expanded row (avatar + name + handle + chevron) when `true` (default), or a
+     * bare avatar-only trigger when `false` (collapsed sidebar).
+     */
+    expanded?: boolean;
+    /**
+     * Avatar diameter in px. Defaults to 40 when expanded, 32 when collapsed.
+     */
+    avatarSize?: number;
+    /** Navigate to the "Manage account" surface (settings). */
+    onNavigateManage?: () => void;
+    /** Start the add-account / sign-in flow for an additional account. */
+    onAddAccount?: () => void;
+    /** Optional: navigate to the signed-in user's own profile. */
+    onNavigateProfile?: () => void;
+    /**
+     * Retained for source compatibility. The trigger now opens the unified
+     * `OxyAccountDialogScreen` (a centered / bottom-sheet modal) rather than an
+     * anchored popover, so popover placement no longer applies.
+     */
+    placement?: 'up' | 'down' | 'auto';
+    /**
+     * Extra className applied to the outer trigger. Kept for NativeWind consumers
+     * that layer utility classes on top; the component's own layout is driven by
+     * `StyleSheet` so it renders correctly with or without NativeWind.
+     */
+    className?: string;
+    /** Extra style applied to the outer trigger. */
+    style?: StyleProp<ViewStyle>;
+}
+/**
+ * Self-contained sidebar account trigger, modeled on Bluesky's ProfileCard and
+ * the Oxy inbox's `MailboxDrawer` footer. Pressing it opens the unified
+ * {@link OxyAccountDialogScreen} — the single account switcher + sign-in surface — via
+ * `useOxy().openAccountDialog`.
+ *
+ * Three auth states from {@link useAuth}:
+ *  - **Undetermined** (`!isAuthResolved || isPrivateApiPending`): a neutral
+ *    avatar-sized skeleton circle, no press.
+ *  - **Signed in**: a pressable row — Bloom `Avatar` + display name + `@handle`
+ *    + a chevron. Press opens the dialog on its `accounts` view.
+ *  - **Signed out**: a "Sign in" row that calls `useAuth().signIn()` (which opens
+ *    the dialog on its `signin` view).
+ *
+ * Styling uses react-native `StyleSheet` + the Bloom theme (via `useTheme`) so
+ * the layout renders identically in EVERY consumer — including apps that do not
+ * use NativeWind (e.g. the accounts app). Only the web hover animation keeps
+ * dynamic inline `style` (the CSS transition/transform values), which is what
+ * the `react-native-web-style.d.ts` augmentation exists for.
+ */
+declare const ProfileButton: React.FC<ProfileButtonProps>;
+export default ProfileButton;
+//# sourceMappingURL=ProfileButton.d.ts.map

package/lib/typescript/module/ui/components/ProfileButton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProfileButton.d.ts","sourceRoot":"","sources":["../../../../../src/ui/components/ProfileButton.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,EAKH,KAAK,SAAS,EACd,KAAK,SAAS,EACjB,MAAM,cAAc,CAAC;AAyCtB,MAAM,WAAW,kBAAkB;IAC/B;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,gBAAgB,CAAC,EAAE,MAAM,IAAI,CAAC;IAC9B,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,8DAA8D;IAC9D,iBAAiB,CAAC,EAAE,MAAM,IAAI,CAAC;IAC/B;;;;OAIG;IACH,SAAS,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;IACnC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,QAAA,MAAM,aAAa,EAAE,KAAK,CAAC,EAAE,CAAC,kBAAkB,CA6P/C,CAAC;AAiDF,eAAe,aAAa,CAAC"}

package/lib/typescript/module/ui/components/ProfileSummaryCard.d.ts

@@ -0,0 +1,33 @@
+import type React from 'react';
+/**
+ * ProfileSummaryCard — the shared "who am I" summary block rendered at the top
+ * of {@link ManageAccountScreen} and {@link EditProfileScreen}.
+ *
+ * A Bloom filled {@link Card} containing a centered {@link Avatar}, the display
+ * name and any number of secondary lines (handle, email, …). When
+ * `onAvatarPress` is supplied the avatar becomes a {@link PressableScale} entry
+ * point (used to open the avatar picker) and can render an optional camera
+ * badge overlay.
+ */
+export interface ProfileSummaryCardProps {
+    /** Primary display name shown under the avatar. */
+    displayName: string;
+    /** Resolved avatar thumbnail URL (undefined → initials fallback). */
+    avatarUri?: string;
+    /** Avatar diameter in px. Defaults to 72. */
+    avatarSize?: number;
+    /**
+     * Secondary lines rendered beneath the name (e.g. `@handle`, email).
+     * Falsy entries are skipped so callers can pass conditional values inline.
+     */
+    lines?: Array<string | null | undefined | false>;
+    /** When provided, the avatar is pressable (e.g. opens the avatar picker). */
+    onAvatarPress?: () => void;
+    /** Render the camera badge overlay. Only meaningful with `onAvatarPress`. */
+    showCameraBadge?: boolean;
+    /** Accessibility label for the pressable avatar. */
+    avatarAccessibilityLabel?: string;
+}
+declare const ProfileSummaryCard: React.FC<ProfileSummaryCardProps>;
+export default ProfileSummaryCard;
+//# sourceMappingURL=ProfileSummaryCard.d.ts.map

package/lib/typescript/module/ui/components/ProfileSummaryCard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProfileSummaryCard.d.ts","sourceRoot":"","sources":["../../../../../src/ui/components/ProfileSummaryCard.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAQ/B;;;;;;;;;GASG;AACH,MAAM,WAAW,uBAAuB;IACpC,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,KAAK,CAAC,CAAC;IACjD,6EAA6E;IAC7E,aAAa,CAAC,EAAE,MAAM,IAAI,CAAC;IAC3B,6EAA6E;IAC7E,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,oDAAoD;IACpD,wBAAwB,CAAC,EAAE,MAAM,CAAC;CACrC;AAWD,QAAA,MAAM,kBAAkB,EAAE,KAAK,CAAC,EAAE,CAAC,uBAAuB,CAkDzD,CAAC;AAEF,eAAe,kBAAkB,CAAC"}

package/lib/typescript/module/ui/components/RequireOxyAuth.d.ts

@@ -0,0 +1,55 @@
+/**
+ * RequireOxyAuth — the optional signed-out gate primitive (React Native).
+ *
+ * ONE shared way for any Oxy app to opt into a signed-out gate. It is entirely
+ * OPTIONAL: a public app renders its children untouched (`prompt="off"`); an
+ * auth-required app blocks them behind a signed-out state (`prompt="hard"`); an
+ * app that mostly works signed-out but wants a nudge shows a dismissible banner
+ * (`prompt="soft"`). Every mode reuses the ONE account dialog the provider
+ * already mounts — opening the sign-in surface is always
+ * `useOxy().openAccountDialog('signin')`; there is NO second dialog.
+ *
+ * Readiness gating (CRITICAL): the gate keys on the SDK's own readiness state
+ * (`useOxy().canUsePrivateApi` / `isPrivateApiPending`), NEVER on app-local
+ * hooks. While auth is still resolving (`isPrivateApiPending`) it renders a
+ * neutral loading state so the signed-out wall never flashes before the
+ * device-first cold boot concludes (the documented cold-boot race).
+ *
+ * Styling follows the sibling `OxyAccountDialogScreen`/`OxySignInButton` pattern —
+ * `useTheme()` + `StyleSheet` (NOT NativeWind), so the gate renders correctly in
+ * EVERY consumer, including apps that do not run NativeWind (e.g. the accounts
+ * app).
+ */
+import type React from 'react';
+import { type ReactNode } from 'react';
+/**
+ * How `RequireOxyAuth` treats a signed-out (or still-resolving) session.
+ *  - `off`  — always render children (public app; a no-op provided for symmetry).
+ *  - `soft` — render children, plus a dismissible sign-in banner when signed out.
+ *  - `hard` — block children behind a centered signed-out state until signed in.
+ */
+export type RequireOxyAuthPrompt = 'off' | 'soft' | 'hard';
+export interface RequireOxyAuthProps {
+    children: ReactNode;
+    /** Gate behavior. @default 'hard' */
+    prompt?: RequireOxyAuthPrompt;
+    /** Replaces the neutral loading UI shown while auth is still resolving. */
+    loadingFallback?: ReactNode;
+    /** Replaces the entire default signed-out wall (`prompt="hard"`). */
+    signedOutFallback?: ReactNode;
+    /** Title for the default `prompt="hard"` wall. */
+    title?: string;
+    /** Subtitle for the default `prompt="hard"` wall. */
+    subtitle?: string;
+    /** Message for the `prompt="soft"` banner. */
+    bannerMessage?: string;
+    /** CTA label for the `prompt="soft"` banner. */
+    bannerActionLabel?: string;
+}
+/**
+ * Optional signed-out gate. Wrap any subtree (or the whole app via the
+ * provider's `requireAuth` prop) to opt into a shared, readiness-safe wall.
+ */
+export declare const RequireOxyAuth: React.FC<RequireOxyAuthProps>;
+export default RequireOxyAuth;
+//# sourceMappingURL=RequireOxyAuth.d.ts.map

package/lib/typescript/module/ui/components/RequireOxyAuth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RequireOxyAuth.d.ts","sourceRoot":"","sources":["../../../../../src/ui/components/RequireOxyAuth.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAY,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAQjD;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;AAE3D,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,SAAS,CAAC;IACpB,qCAAqC;IACrC,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,2EAA2E;IAC3E,eAAe,CAAC,EAAE,SAAS,CAAC;IAC5B,qEAAqE;IACrE,iBAAiB,CAAC,EAAE,SAAS,CAAC;IAC9B,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gDAAgD;IAChD,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAOD;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,KAAK,CAAC,EAAE,CAAC,mBAAmB,CA4CxD,CAAC;AA0JF,eAAe,cAAc,CAAC"}

package/lib/typescript/module/ui/components/SettingsIcon.d.ts

@@ -0,0 +1,15 @@
+import type React from 'react';
+import MaterialCommunityIcons from '@expo/vector-icons/MaterialCommunityIcons';
+interface SettingsIconProps {
+    /** MaterialCommunityIcons icon name */
+    name: React.ComponentProps<typeof MaterialCommunityIcons>['name'];
+    /** Background color for the circle */
+    color: string;
+    /** Icon size (default 14, fits bloom's 20x20 container) */
+    iconSize?: number;
+    /** Container size (default 20, matches bloom SettingsListItem icon slot) */
+    size?: number;
+}
+export declare const SettingsIcon: React.NamedExoticComponent<SettingsIconProps>;
+export default SettingsIcon;
+//# sourceMappingURL=SettingsIcon.d.ts.map

package/lib/typescript/module/ui/components/SettingsIcon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SettingsIcon.d.ts","sourceRoot":"","sources":["../../../../../src/ui/components/SettingsIcon.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,OAAO,sBAAsB,MAAM,2CAA2C,CAAC;AAG/E,UAAU,iBAAiB;IACvB,uCAAuC;IACvC,IAAI,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;IAClE,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAoBD,eAAO,MAAM,YAAY,+CAA8B,CAAC;AACxD,eAAe,YAAY,CAAC"}

package/lib/typescript/module/ui/components/SurfaceHeaderAction.d.ts

@@ -0,0 +1,16 @@
+import type React from 'react';
+export interface SurfaceHeaderActionProps {
+    /** Button label (e.g. a translated "Save"). */
+    label: string;
+    onPress: () => void;
+    /** Show a spinner instead of the label (also disables the button). */
+    loading?: boolean;
+    disabled?: boolean;
+}
+/**
+ * A filled pill action for a surface's nav-header right slot — the canonical
+ * "Save" affordance. Pass a memoized instance to `useSurfaceHeader({ right })`
+ * so the header does not thrash between renders.
+ */
+export declare const SurfaceHeaderAction: React.FC<SurfaceHeaderActionProps>;
+//# sourceMappingURL=SurfaceHeaderAction.d.ts.map

package/lib/typescript/module/ui/components/SurfaceHeaderAction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SurfaceHeaderAction.d.ts","sourceRoot":"","sources":["../../../../../src/ui/components/SurfaceHeaderAction.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAM/B,MAAM,WAAW,wBAAwB;IACvC,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,sEAAsE;IACtE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,KAAK,CAAC,EAAE,CAAC,wBAAwB,CAuBlE,CAAC"}

package/lib/typescript/module/ui/components/SurfaceScreen.d.ts

@@ -0,0 +1,23 @@
+import React from 'react';
+import type { SurfaceControls } from '@oxyhq/bloom/surfaces';
+import type { SurfaceNavStack } from '../navigation/surfaceNavStack.js';
+export interface SurfaceScreenProps {
+    /** This surface's route history (the NAV-WITHIN axis). */
+    navStack: SurfaceNavStack;
+    /** Bloom's per-surface controls (dismiss / present a child) — the DEPTH axis. */
+    surface: SurfaceControls;
+    /** Whether backdrop / Escape / back may dismiss at the root frame. Defaults to true. */
+    dismissOnBackdrop?: boolean;
+}
+/**
+ * Binds one SDK surface to its content: resolves the lazy screen for the current
+ * nav-stack frame and renders it inside the error boundary with the per-surface
+ * navigation props. Mounted by `surfaces.present` as the Bloom surface's content.
+ *
+ * Dismissal is driven through the nav stack's `closing` flag (watched in an
+ * effect) rather than a captured-controls call, so a dismiss requested before
+ * this surface mounted still resolves the Bloom surface exactly once.
+ */
+declare function SurfaceScreen({ navStack, surface, dismissOnBackdrop, }: SurfaceScreenProps): React.JSX.Element | null;
+export default SurfaceScreen;
+//# sourceMappingURL=SurfaceScreen.d.ts.map

package/lib/typescript/module/ui/components/SurfaceScreen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SurfaceScreen.d.ts","sourceRoot":"","sources":["../../../../../src/ui/components/SurfaceScreen.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAoE,MAAM,OAAO,CAAC;AASzF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAI7D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAA+B,CAAC;AAgErE,MAAM,WAAW,kBAAkB;IACjC,0DAA0D;IAC1D,QAAQ,EAAE,eAAe,CAAC;IAC1B,iFAAiF;IACjF,OAAO,EAAE,eAAe,CAAC;IACzB,wFAAwF;IACxF,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,iBAAS,aAAa,CAAC,EACrB,QAAQ,EACR,OAAO,EACP,iBAAwB,GACzB,EAAE,kBAAkB,4BA8JpB;AAED,eAAe,aAAa,CAAC"}

package/lib/typescript/module/ui/components/authChooser/AccountsMenuView.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The signed-in Oxy account MENU (`accounts` view) — a Google-account-menu-style
+ * full menu built entirely with NativeWind `className` (the dynamic per-account
+ * accent hex is the one inline style NativeWind cannot express). Structure:
+ *
+ *  - HERO on its own chrome-free block: the current account's large pressable
+ *    avatar (with a camera badge to change the photo), the greeting, the account
+ *    address, and a "Manage your Oxy account" pill.
+ *  - SWITCH ACCOUNT: a disclosure row whose corner animates from pill to card as
+ *    the other switchable accounts + "Add another account" + "Manage accounts on
+ *    this device" reveal beneath it.
+ *  - OXY STORAGE: cloud + used/total + a composition meter + Upgrade / Manage chips.
+ *  - MENU rows: Your data in Oxy · Oxy settings · Help & feedback · Sign out —
+ *    Bloom's grouped section, the same component every other SDK settings surface
+ *    uses, not a local row copy.
+ *  - FOOTER: Privacy Policy · Terms of Service.
+ *
+ * All three blocks share ONE rhythm taken from that grouped section: a 12px
+ * content inset, a 12px gap after the leading element, 16px between blocks, and
+ * a 16px trailing chevron column.
+ *
+ * Collapse state is a plain `useState` toggled in the row's press handler — no
+ * effect hook, no derived-from-props sync.
+ */
+import type React from 'react';
+import type { AccountDialogSnapshot } from '@oxyhq/core';
+import { type AccountStorageModel, type AccountsMenuActions, type OxyAuthChooserHandlers, type Theme, type Translate } from './types.js';
+interface AccountsMenuViewProps {
+    snapshot: AccountDialogSnapshot;
+    theme: Theme;
+    t: Translate;
+    handlers: OxyAuthChooserHandlers;
+    storage: AccountStorageModel | null;
+    menu: AccountsMenuActions;
+}
+declare const AccountsMenuView: React.FC<AccountsMenuViewProps>;
+export default AccountsMenuView;
+//# sourceMappingURL=AccountsMenuView.d.ts.map

package/lib/typescript/module/ui/components/authChooser/AccountsMenuView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AccountsMenuView.d.ts","sourceRoot":"","sources":["../../../../../../src/ui/components/authChooser/AccountsMenuView.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAkB/B,OAAO,KAAK,EAAE,qBAAqB,EAAqB,MAAM,aAAa,CAAC;AAK5E,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,KAAK,EACV,KAAK,SAAS,EACf,MAAM,YAAS,CAAC;AAsEjB,UAAU,qBAAqB;IAC7B,QAAQ,EAAE,qBAAqB,CAAC;IAChC,KAAK,EAAE,KAAK,CAAC;IACb,CAAC,EAAE,SAAS,CAAC;IACb,QAAQ,EAAE,sBAAsB,CAAC;IACjC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACpC,IAAI,EAAE,mBAAmB,CAAC;CAC3B;AAED,QAAA,MAAM,gBAAgB,EAAE,KAAK,CAAC,EAAE,CAAC,qBAAqB,CAoXrD,CAAC;AA8DF,eAAe,gBAAgB,CAAC"}

package/lib/typescript/module/ui/components/authChooser/SignInEntryView.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The sign-in ENTRY (`signin` / `add` views) — ONE primary action.
+ *
+ * Issue #691, Phase 5: the normal experience presents no menu of authentication
+ * methods. The user sees "Continue with Oxy"; Oxy — not the user — then picks
+ * how the request reaches their Commons identity, and the request surface shows
+ * honest progress. Everything else (a QR from another device, a passkey on this
+ * device, getting Commons, creating an account) lives behind "Having trouble?".
+ *
+ * Existing accounts still render ABOVE the CTA: "continue as one of these" is a
+ * choice of WHO, not of HOW, so it is not one of the competing method buttons
+ * the issue removes.
+ *
+ * On web this view is transient — the container auto-starts the flow the instant
+ * the view is reached, because the request surface (QR, or "Check Commons on
+ * your phone") IS the primary route there, never something behind a tap.
+ */
+import type React from 'react';
+import type { AccountDialogSnapshot } from '@oxyhq/core';
+import type { OxyAuthChooserHandlers, SignInAlternatives, Theme, Translate } from './types.js';
+interface SignInEntryViewProps {
+    snapshot: AccountDialogSnapshot;
+    theme: Theme;
+    t: Translate;
+    handlers: OxyAuthChooserHandlers;
+    /** The ONE primary action. Starts the flow; Oxy chooses the route from there. */
+    onContinueWithOxy: () => void;
+    alternatives: SignInAlternatives;
+}
+declare const SignInEntryView: React.FC<SignInEntryViewProps>;
+export default SignInEntryView;
+//# sourceMappingURL=SignInEntryView.d.ts.map

package/lib/typescript/module/ui/components/authChooser/SignInEntryView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SignInEntryView.d.ts","sourceRoot":"","sources":["../../../../../../src/ui/components/authChooser/SignInEntryView.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAIzD,OAAO,KAAK,EACV,sBAAsB,EAEtB,kBAAkB,EAClB,KAAK,EACL,SAAS,EACV,MAAM,YAAS,CAAC;AAEjB,UAAU,oBAAoB;IAC5B,QAAQ,EAAE,qBAAqB,CAAC;IAChC,KAAK,EAAE,KAAK,CAAC;IACb,CAAC,EAAE,SAAS,CAAC;IACb,QAAQ,EAAE,sBAAsB,CAAC;IACjC,iFAAiF;IACjF,iBAAiB,EAAE,MAAM,IAAI,CAAC;IAC9B,YAAY,EAAE,kBAAkB,CAAC;CAClC;AAED,QAAA,MAAM,eAAe,EAAE,KAAK,CAAC,EAAE,CAAC,oBAAoB,CA2EnD,CAAC;AAEF,eAAe,eAAe,CAAC"}

package/lib/typescript/module/ui/components/authChooser/SignInRequestView.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The ACTIVE REQUEST surface (`qr` view) as the account dialog drives it —
+ * `AccountDialogController`'s device flow bound to the shared, presentational
+ * {@link OxySignInRequestSurface} (issue #691, Phase 5).
+ *
+ * This module owns WIRING only. Every pixel comes from the shared surface, which
+ * the auth.oxy.so IdP mounts from its own OAuth-bound request; there is one
+ * implementation of the request presentation, not two. What lives here is what
+ * only the account dialog knows:
+ *
+ *  - which of the controller's facts map onto the surface's props;
+ *  - which alternatives are genuine ones for the CURRENT presentation (the
+ *    passkey ceremony is pointless once the request is already being confirmed,
+ *    and a QR link is redundant while the QR itself is the primary visual);
+ *  - the one piece of local intent the controller has no opinion on: leaving the
+ *    acquisition surface via "I have Commons on another device".
+ *
+ * Failures are NOT rendered here. The container toasts them at the point they
+ * arrive (owner mandate: no error renders inline inside the dialog); this view
+ * only reports that the request failed, so the surface can offer "Try again".
+ */
+import type React from 'react';
+import type { AccountDialogSnapshot } from '@oxyhq/core';
+import type { SignInAlternatives, Translate } from './types.js';
+interface SignInRequestViewProps {
+    snapshot: AccountDialogSnapshot;
+    t: Translate;
+    /** Restart the request after a failure. */
+    onRetry: () => void;
+    alternatives: SignInAlternatives;
+}
+declare const SignInRequestView: React.FC<SignInRequestViewProps>;
+export default SignInRequestView;
+//# sourceMappingURL=SignInRequestView.d.ts.map

package/lib/typescript/module/ui/components/authChooser/SignInRequestView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SignInRequestView.d.ts","sourceRoot":"","sources":["../../../../../../src/ui/components/authChooser/SignInRequestView.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEzD,OAAO,KAAK,EAA0B,kBAAkB,EAAE,SAAS,EAAE,MAAM,YAAS,CAAC;AAErF,UAAU,sBAAsB;IAC9B,QAAQ,EAAE,qBAAqB,CAAC;IAChC,CAAC,EAAE,SAAS,CAAC;IACb,2CAA2C;IAC3C,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,YAAY,EAAE,kBAAkB,CAAC;CAClC;AAED,QAAA,MAAM,iBAAiB,EAAE,KAAK,CAAC,EAAE,CAAC,sBAAsB,CA2FvD,CAAC;AAEF,eAAe,iBAAiB,CAAC"}