@basictech/react 0.12.0-beta.0 → 0.12.0-beta.2

package/README.md

@@ -18,22 +18,24 @@ its package metadata.
 
 ## Install
 
-Install the React SDK and declare the schema package you import directly:
+This README describes the `0.12.0-beta.1` release candidate. After publication, install
+matching versions of the React SDK and the schema package you import directly:
 
 ```bash
-npm install @basictech/react @basictech/schema
+npm install @basictech/react@0.12.0-beta.1 @basictech/schema@0.12.0-beta.1
 ```
 
 React is a peer dependency and must already be installed by your application.
 
 ## Auth update guide
 
-Upgrade the packages you use together from npm's default `latest` channel:
+Upgrade the packages you use together. npm's `latest` channel remains on `0.11.0` and
+does not contain all of the API changes described here:
 
 ```bash
-npm install @basictech/react@latest @basictech/schema@latest
+npm install @basictech/react@0.12.0-beta.1 @basictech/schema@0.12.0-beta.1
 # If you import core directly, update that dependency too:
-npm install @basictech/core@latest
+npm install @basictech/core@0.12.0-beta.1
 ```
 
 Keep the public packages on matching versions. No browser storage reset or persisted-profile
@@ -42,9 +44,8 @@ that an older installed beta contains the update.
 
 ### Update auth checks and editing controls
 
-- Replace `useAuth().status === 'reauth_required'` with `status === 'expired'`.
-  Core client snapshots likewise use `authStatus: 'expired'`; only low-level `AuthSession`
-  retains the legacy compatibility state.
+- Replace `useAuth().status === 'reauth_required'` with `status === 'expired'`. The
+  `reauth_required` state no longer exists anywhere, including low-level `AuthSession`.
 - Use `auth.canWrite` to disable mutation controls and `auth.readOnlyReason` for explanation.
   It is account eligibility, not a guarantee of connectivity or permission to a particular source.
   Catch imperative mutation errors too: auth can expire after the UI renders. Newly attempted
@@ -72,8 +73,10 @@ function AuthNotice() {
 
 ### Render per-account status
 
-`useAccounts().accounts` now returns `BasicAccount[]`, including anonymous and expired accounts.
-Each account adds `auth: { status, reason, checkedAt }` to the existing profile fields:
+`useAccounts().accounts` returns `BasicAccount[]`, including anonymous and expired accounts, and
+`useAccounts().activeAccount` is this tab's selection. The former `profiles`/`users`/`activeUser`
+snapshot aliases and the `active` hook field are gone. Each account adds
+`auth: { status, reason, checkedAt }` to the existing profile fields:
 
 | Account status | Meaning |
 | --- | --- |
@@ -90,6 +93,11 @@ is expired; otherwise an unverified remembered account is checking. The active a
 has `auth.status: 'anon'`, while top-level `useAuth()` reports `status: 'signed_out'` and
 `isAnonymous: true`. REST exposes one remembered account, not a multi-account registry.
 
+`account.auth.reason` is exactly `'AUTH_EXPIRED' | null`. Raw active-account diagnostics such as
+`invalid_grant` remain available as `useAuth().error`. Sign-in prerequisite errors returned by
+server-backed hooks are stable within each hook but intentionally distinct objects from that raw
+diagnostic; an expired hook can report `AUTH_EXPIRED` while the auth diagnostic is `invalid_grant`.
+
 Ordinary network loss is not expiry, and anonymous editing still works. `goOnline()` cannot
 bypass expired read-only enforcement. Reauthorization resumes retained queued work; already
 accepted server requests cannot be undone by client cancellation. REST has no offline cache.
@@ -278,7 +286,7 @@ The package also exports the adapters for explicit composition: `BrowserKeyValue
 `browserStorage`, `BrowserTokenStore`, `PersistenceStore`, `browserUploadTransport`,
 `createBrowserMessageChannel`, `createBrowserAuthChannelFactory`, `browserNavigate`,
 `browserCurrentUrl`, and `browserReplaceUrl`. Most applications only need `createBasic`, which
-installs them.
+installs them. `supportsAccessTokenAdoption` is internal and is not a public React export.
 
 ### Token storage
 
@@ -320,6 +328,93 @@ With the default `renderWhileLoading={false}`, hooks under the Provider first re
 client is ready. Setting it to `true` is useful for an application shell that reads `isReady` and
 owns its loading UI.
 
+## Prebuilt components
+
+Drop-in account and sharing UI uses Base UI's accessible menu, avatar, and dialog primitives.
+Components use the nearest `BasicProvider` (including `basic.Provider`); they do not create a
+second auth client. Import the optional stylesheet once. Omit it to supply your own styles.
+
+```tsx
+import {
+  BasicUIProvider, SignInButton, UserButton, AuthStatus, SyncStatus, SharesModal,
+} from '@basictech/react'
+import '@basictech/react/styles.css'
+import { basic } from './basic'
+
+export function AccountTools() {
+  return (
+    <basic.Provider>
+      <BasicUIProvider appearance={{ theme: 'light', accent: '#354f45', radius: '8px' }}>
+        <SignInButton />
+        <UserButton allowAddAccount />
+        <AuthStatus />
+        <SyncStatus />
+        <SharesModal scope={[{ table: 'todos', recordIds: ['todo-1'] }]} />
+      </BasicUIProvider>
+    </basic.Provider>
+  )
+}
+```
+
+| Component | Options and behavior |
+| --- | --- |
+| `BasicButton` | Native button props/ref; `variant="solid\|outline\|ghost"`. Defaults to `type="button"`. |
+| `SignInButton`, `SignOutButton` | Native button props and variant, pending/error feedback. Sign-in accepts `input` (handle/DID); `onClick.preventDefault()` cancels the action. Expired sessions can reauthorize or sign out. |
+| `UserAvatar` | Borderless avatar trigger for the shared user menu. Current account or explicit `profile` (`null` means guest); `size`, `className`, `style`; image failure falls back to initials. Sync badge defaults on in sync mode; `showSyncBadge={false}` hides it. REST mode never shows a sync badge. |
+| `UserButton` | Avatar, name, handle, and dropdown icon with a bordered hoverable trigger. `shape="rounded\|square"` defaults to rounded. Opens the shared user menu. Local accounts never show a handle. |
+| `UserMenu` | Shared menu used by both triggers; `trigger="avatar\|button"` defaults to avatar. Current account at top, Manage account, other saved accounts, and auth actions. The switch section appears only when other accounts exist. Only expired auth gets an `Expired` warning; no signed-in badge. `showSyncStatus={false}` hides the header's sync label; REST mode always hides sync badges. `allowAddAccount` defaults to true, starting sign-in in a new profile in REST or sync mode. Local accounts offer Clear account with a destructive-action confirmation. Optional `accountSettingsUrl`. |
+| `AuthStatus` | Loading, signed-in, guest, signed-out, recovering, and expired session labels. UI visibility is not authorization. |
+| `SyncStatus` | Connectivity, pending counts, and conflict/rejection count; optional `source` for a repo or mount. An online queue is not labelled synced. |
+| `AccountSettingsModal` | Profile tab edits the project display name with Cancel/Save changes; drafts survive tab switches. Advanced shows read-only DID, PDS URL, local account/storage identifiers, auth/write state, and sync counts. No tokens or credentials are rendered. Local accounts show explicit DID/PDS fallbacks. `projectProfile` supplies a complete preview hook result. Optional `accountSettingsUrl` links to universal identity settings; `children` adds host-owned Profile content. |
+| `SharesModal` | Same identity-header layout with Outgoing/Incoming tabs. Required explicit `scope`, optional `repo` (default: `'default'`). Viewer/editor invitations by handle/DID, outgoing list, refresh, confirmed cancellation/revocation. Incoming acceptance and mount management remain in Basic ID. |
+
+Both modals accept `open`/`onOpenChange`, an optional button element or label as `trigger`, and
+`finalFocus` for externally controlled use. `trigger={null}` omits the trigger. Custom trigger
+components must forward their ref and DOM props. Dialogs trap focus and close with Escape.
+
+`BasicUIProvider` accepts `appearance: { theme, accent, radius, density }`; density is
+`'comfortable'` or `'compact'`. Nested providers inherit appearance; portaled menus/dialogs retain
+it. Choose an accent with sufficient contrast against white for solid buttons. Fonts inherit from
+the host. Override the prefixed `basic-*` classes and `--basic-*` CSS tokens for finer styling.
+
+For controlled previews, components accept complete hook results via `auth`, `accounts`, `sync`,
+or `shares` as appropriate. These replace rendered state **and action callbacks**; a BasicProvider
+is still required and hooks still subscribe/read. Do not use these props as an authorization
+boundary. Real mutations remain subject to SDK and server permissions.
+
+Share creation requires an explicit nonempty table/record scope and defaults to viewer access.
+The list is labelled **all permissions**, not filtered to the new-invitation scope. Revocation cannot
+retract downloaded data. Signing out removes the account's local cache and pending edits.
+The incoming-invitations section links to Basic ID: inbox/accept/decline APIs require owner
+credentials, not app tokens. Server project-profile GET/PATCH/DELETE APIs exist at
+`/account/:project_id/profile` with `app:profile:read/update/delete` grants respectively.
+Configure those requested OAuth scopes and reauthorize existing sessions when needed.
+The shared menu shows sync status and any expiry warning with the current account in its header.
+Inactive accounts show saved expiry state, not the active account's sync status.
+Both `UserButton` and `UserAvatar` accept `showSyncBadge` (default follows SDK sync mode); circles use
+green for synced, blue for connecting/pending, orange for errors, gray for offline/local/idle.
+The demo's `?page=components` gallery offers live behavior, isolated simulated actions, design
+controls, and a copyable usage recipe. Live OAuth/shares require a configured signed-in account.
+
+### Project profile API
+
+`basic.useProjectProfile()` (also exported as `useProjectProfile`) returns `data`, `isLoading`,
+`error`, `refresh()`, `update(patch)`, and `reset()`. Pass `false` to disable automatic reads.
+`data` is `{ profile: { name?, avatar_url?, status? }, meta? }` or null before loading/sign-in.
+The core client exposes the same operations directly:
+
+```ts
+await basic.client.getProjectProfile()
+await basic.client.updateProjectProfile({ name: 'Name in this app', status: null })
+await basic.client.resetProjectProfile()
+```
+
+Requests always target the configured client ID using the active app token. Omitted fields stay
+unchanged; null removes an override. Metadata objects merge on the server; `meta: null` clears
+metadata. Reset removes all project overrides and metadata. Universal profile data is untouched.
+Permission failures propagate as SDK errors. Profile responses are not written into the local
+account registry; consumers needing the updated project identity should use this hook's data.
+
 ## Hook reference
 
 The schema-bound factory returns every hook below. Bound hooks are preferred because they reject
@@ -352,8 +447,8 @@ unknown table names and infer fields in reads, writes, and queries.
 | `isAnonymous` | `boolean` | The active sync profile is anonymous and not signed in |
 | `status` | `'bootstrapping' \| 'signed_out' \| 'authenticated' \| 'recovering' \| 'expired'` | Current public auth lifecycle |
 | `canWrite` | `boolean` | Active-account write eligibility; source permissions still apply |
-| `readOnlyReason` | `string \| null` | For example `AUTH_EXPIRED` when reauthorization is needed |
-| `error` | `BasicError \| null` | Stable auth bootstrap/refresh error code when available |
+| `readOnlyReason` | `ReadOnlyReason \| null` | `'AUTH_EXPIRED' \| 'AUTH_CHECKING' \| 'AUTHORIZATION_REQUIRED' \| 'CLIENT_NOT_STARTED'`; switch exhaustively for banners |
+| `error` | `BasicError \| null` | Raw active auth diagnostic; same object while its code and expired state are unchanged |
 | `user` | `AuthUser \| null` | OIDC user info (`sub`, `pds_url`, and optional `email`, `name`, `picture`, `handle`) |
 | `did` | `string \| null` | Signed-in account DID |
 | `handle` | `string \| null` | Resolved account handle |
@@ -399,31 +494,33 @@ replicas and returns to another local profile or a fresh anonymous one when enab
 
 ### `basic.useAccounts()`
 
-`useAccounts()` returns `{ accounts, active, switchAccount, addAccount, removeAccount }`:
+`useAccounts()` returns `{ accounts, activeAccount, switchAccount, addAccount, removeAccount }`:
 
 - `accounts: BasicAccount[]` lists local profiles with per-account auth summaries.
-- `active: BasicAccount | null` is this tab's selected profile and auth summary.
+- `activeAccount: BasicAccount | null` is this tab's selected profile and auth summary.
 - `switchAccount(id): Promise<void>` changes the active profile in this tab.
-- `addAccount(): Promise<BasicProfile>` creates and activates a new anonymous profile from which to
-  start another sign-in.
+- `addAccount({ signIn?: boolean }): Promise<BasicProfile>` creates and activates a new profile.
+  Omit options to stay local; pass `{ signIn: true }` to validate redirect configuration first and
+  start sign-in in the new profile. The prebuilt menu uses this sign-in option.
 - `removeAccount(id): Promise<void>` removes that profile and its local credentials/replicas. If it
   is active, this follows the sign-out path. It does not delete the server account.
 
 `BasicProfile` contains `id`, `kind: 'anon' | 'account'`, `storagePrefix`, `createdAt`,
-`lastActiveAt`, and optional/null `did`, `handle`, `email`, `name`, and `picture`. Multi-account and
-`addAccount()` require sync mode with anonymous profiles enabled.
+`lastActiveAt`, and optional/null `did`, `handle`, `email`, `name`, and `picture`. Saved accounts and
+switching work in REST and sync modes. `addAccount({ signIn: true })` works in either mode;
+`addAccount()` without sign-in still requires sync mode with anonymous profiles enabled.
 
 ```tsx
 // file: AccountSwitcher.tsx
 import { basic } from './basic'
 
 export function AccountSwitcher() {
-  const { accounts, active, switchAccount, addAccount, removeAccount } = basic.useAccounts()
+  const { accounts, activeAccount, switchAccount, addAccount, removeAccount } = basic.useAccounts()
 
   return (
     <section>
       <select
-        value={active?.id ?? ''}
+        value={activeAccount?.id ?? ''}
         onChange={(event) => void switchAccount(event.currentTarget.value)}
       >
         {accounts.map((account) => (
@@ -433,7 +530,7 @@ export function AccountSwitcher() {
         ))}
       </select>
       <button onClick={() => void addAccount()}>Add account</button>
-      {active && <button onClick={() => void removeAccount(active.id)}>Remove local profile</button>}
+      {activeAccount && <button onClick={() => void removeAccount(activeAccount.id)}>Remove local profile</button>}
     </section>
   )
 }
@@ -821,9 +918,8 @@ Shares v2 is capability-gated and requires sign-in. `useOutgoingShares()` return
 ```text
 {
   data: OutgoingShareInfo[]
-  outgoingShares: OutgoingShareInfo[] // alias of data
   isLoading: boolean
-  error: BasicError | null
+  error: BasicError | null // load failure, or AUTHORIZATION_REQUIRED / AUTH_EXPIRED while not signed in
   refresh(): void
   create(input: CreateOutgoingShareInput): Promise<OutgoingShareInfo>
   get(id: string): Promise<OutgoingShareInfo>
@@ -869,7 +965,7 @@ export function OutgoingShares() {
       <button onClick={() => location.assign(shares.manageUrl())}>Manage in Basic ID</button>
       {shares.error && <p>{shares.error.code}</p>}
       <ul>
-        {shares.outgoingShares.map((share) => (
+        {shares.data.map((share) => (
           <li key={share.id}>
             {share.recipientDid}: {share.effectiveState}
             {share.state === 'pending' && (
@@ -907,9 +1003,8 @@ management belong there. `client.shares.leave()` is intentionally owner-only and
 ```text
 {
   data: MountInfo[]
-  mounts: MountInfo[] // alias of data
   isLoading: boolean
-  error: BasicError | null
+  error: BasicError | null // load failure, or AUTHORIZATION_REQUIRED / AUTH_EXPIRED while not signed in
   refresh(): void
   open(mountId: string): Promise<MountHandle<S>>
   manageUrl(): string
@@ -955,7 +1050,7 @@ export function IncomingMounts() {
     <section>
       <button onClick={() => location.assign(mounts.manageUrl())}>Manage mounts</button>
       <ul>
-        {mounts.mounts.map((mount) => (
+        {mounts.data.map((mount) => (
           <li key={mount.id}>
             {mount.role} from {mount.originOwnerDid}
             <button onClick={() => void open(mount.id)}>Open</button>
@@ -1090,7 +1185,8 @@ The unbound exports mirror the bound hooks:
 | `useMounts()`, `useOutgoingShares()` | Same share results |
 
 Every unbound hook must run below `BasicProvider`; otherwise it throws `Basic hooks must be used
-within a <BasicProvider>`.
+within a <BasicProvider>`. Bound hooks likewise throw outside their own `basic.Provider`, because
+the Provider is what starts and stops the client.
 
 ## Error handling
 

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import * as react from 'react';
-import { ReactNode, ReactElement } from 'react';
-import { BasicSchema, BasicConfig, BasicClient, BasicAccount, BasicProfile, AuthStatus, BasicError, AuthUser, BasicSyncStatus, BasicRejection, BasicConflict, SourceRef, SchemaStatus, BasicDb, Repo, FileRecord, MountFileInfo, StorageInfo, FileListQuery, MountInfo, MountHandle, OutgoingShareInfo, CreateOutgoingShareInput, MountsQuery, JsonObject, BasicRecord, Query, MountViewerFiles, OwnerFiles, TableNames, Collection, InferValue, KeyValueStorage, TokenStore, AuthMessageChannel, ReplicaStoreFactory, StoragePartition, ReplicaStore, UploadTransportAdapter } from '@basictech/core';
+import { ReactNode, ReactElement, RefObject, ButtonHTMLAttributes, HTMLAttributes } from 'react';
+import { BasicSchema, BasicConfig, BasicClient, BasicAccount, BasicProfile, ReadOnlyReason, AuthStatus as AuthStatus$1, BasicError, AuthUser, BasicSyncStatus, BasicRejection, BasicConflict, SourceRef, SchemaStatus, BasicDb, Repo, FileRecord, MountFileInfo, StorageInfo, FileListQuery, MountInfo, MountHandle, OutgoingShareInfo, CreateOutgoingShareInput, MountsQuery, JsonObject, BasicRecord, Query, ProjectProfile, ProjectProfilePatch, MountViewerFiles, OwnerFiles, TableNames, Collection, InferValue, KeyValueStorage, TokenStore, AuthChannelContext, AuthMessageChannel, ReplicaStoreFactory, StoragePartition, ReplicaStore, UploadTransportAdapter } from '@basictech/core';
 
 type BrowserBasicConfig<S extends BasicSchema = BasicSchema> = BasicConfig<S>;
 /** Create a core client with the complete browser adapter set installed. */
@@ -8,9 +8,11 @@ declare function createBasicClient<S extends BasicSchema>(config: BrowserBasicCo
 
 interface UseAccountsResult {
     accounts: BasicAccount[];
-    active: BasicAccount | null;
+    activeAccount: BasicAccount | null;
     switchAccount(id: string): Promise<void>;
-    addAccount(): Promise<BasicProfile>;
+    addAccount(options?: {
+        signIn?: boolean;
+    }): Promise<BasicProfile>;
     removeAccount(id: string): Promise<void>;
 }
 declare function useAccounts(): UseAccountsResult;
@@ -20,8 +22,9 @@ interface UseAuthResult {
     isSignedIn: boolean;
     isAnonymous: boolean;
     canWrite: boolean;
-    readOnlyReason: string | null;
-    status: AuthStatus;
+    readOnlyReason: ReadOnlyReason | null;
+    status: AuthStatus$1;
+    /** Raw auth diagnostic; stable identity while its code and expired state are unchanged. */
     error: BasicError | null;
     user: AuthUser | null;
     did: string | null;
@@ -64,6 +67,7 @@ declare function useFiles(query?: FileListQuery, options?: {
 interface UseStorageInfoResult {
     data: StorageInfo | null;
     isLoading: boolean;
+    /** Load failure, or the sign-in requirement while no account is signed in. */
     error: BasicError | null;
     refresh(): void;
 }
@@ -71,8 +75,8 @@ declare function useStorageInfo(): UseStorageInfoResult;
 
 interface UseMountsResult<S extends BasicSchema = BasicSchema> {
     data: MountInfo[];
-    mounts: MountInfo[];
     isLoading: boolean;
+    /** Load failure, or the sign-in requirement while no account is signed in. */
     error: BasicError | null;
     refresh(): void;
     open(mountId: string): Promise<MountHandle<S>>;
@@ -81,8 +85,8 @@ interface UseMountsResult<S extends BasicSchema = BasicSchema> {
 declare function useMounts(query?: MountsQuery): UseMountsResult;
 interface UseOutgoingSharesResult {
     data: OutgoingShareInfo[];
-    outgoingShares: OutgoingShareInfo[];
     isLoading: boolean;
+    /** Load failure, or the sign-in requirement while no account is signed in. */
     error: BasicError | null;
     refresh(): void;
     create(input: CreateOutgoingShareInput): Promise<OutgoingShareInfo>;
@@ -116,6 +120,19 @@ interface UseReposResult {
 }
 declare function useRepos(): UseReposResult;
 
+interface AsyncResult<T> {
+    data: T;
+    isLoading: boolean;
+    error: BasicError | null;
+    refresh(): void;
+}
+
+interface UseProjectProfileResult extends AsyncResult<ProjectProfile | null> {
+    update(patch: ProjectProfilePatch): Promise<ProjectProfile>;
+    reset(): Promise<ProjectProfile>;
+}
+declare function useProjectProfile(enabled?: boolean): UseProjectProfileResult;
+
 type CreateBasicConfig<S extends BasicSchema> = BrowserBasicConfig<S> & {
     schema: S;
 };
@@ -145,6 +162,7 @@ interface CreatedBasic<S extends BasicSchema> {
     useSyncStatus(source?: SourceRef): UseSyncStatusResult;
     useSchemaStatus(source?: SourceRef): SchemaStatus;
     useRepos(): UseReposResult;
+    useProjectProfile(enabled?: boolean): UseProjectProfileResult;
     useFiles(query?: FileListQuery, options?: {
         source?: SourceRef;
     }): UseFilesResult;
@@ -178,6 +196,93 @@ declare function useCollection<V extends JsonObject = JsonObject>(name: string,
     source?: SourceRef;
 }): Collection<V>;
 
+interface BasicAppearance {
+    theme?: 'light' | 'dark';
+    accent?: string;
+    radius?: string;
+    density?: 'compact' | 'comfortable';
+}
+/** Optional styling provider. CSS is opt-in via @basictech/react/styles.css. */
+declare function BasicUIProvider({ appearance, children, }: {
+    appearance?: BasicAppearance;
+    children: ReactNode;
+}): react.JSX.Element;
+interface BasicButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    variant?: 'solid' | 'outline' | 'ghost';
+}
+declare const BasicButton: react.ForwardRefExoticComponent<BasicButtonProps & react.RefAttributes<HTMLButtonElement>>;
+interface AuthButtonProps extends BasicButtonProps {
+    auth?: UseAuthResult;
+    input?: string;
+}
+declare function SignInButton(props: AuthButtonProps): react.JSX.Element;
+declare function SignOutButton(props: AuthButtonProps): react.JSX.Element;
+interface UserAvatarProps extends HTMLAttributes<HTMLSpanElement> {
+    profile?: (Pick<BasicProfile, 'name' | 'handle' | 'email' | 'picture'> & Partial<Pick<BasicProfile, 'kind'>>) | null;
+    size?: number;
+    showSyncBadge?: boolean;
+    sync?: UseSyncStatusResult;
+    accounts?: UseAccountsResult;
+    auth?: UseAuthResult;
+    projectProfile?: UseProjectProfileResult;
+    allowAddAccount?: boolean;
+}
+declare function UserAvatar({ accounts, auth, projectProfile, allowAddAccount, ...avatarProps }: UserAvatarProps): react.JSX.Element;
+declare function AuthStatus({ auth: supplied, className, ...props }: HTMLAttributes<HTMLSpanElement> & {
+    auth?: UseAuthResult;
+}): react.JSX.Element;
+declare function SyncStatus({ sync: supplied, source, className, ...props }: HTMLAttributes<HTMLSpanElement> & {
+    sync?: UseSyncStatusResult;
+    source?: SourceRef;
+}): react.JSX.Element | null;
+interface UserButtonProps {
+    accounts?: UseAccountsResult;
+    auth?: UseAuthResult;
+    sync?: UseSyncStatusResult;
+    /** Show synchronization status in the account menu. Defaults to true. */
+    showSyncStatus?: boolean;
+    /** Defaults to enabled in sync mode. */
+    showSyncBadge?: boolean;
+    shape?: 'rounded' | 'square';
+    projectProfile?: UseProjectProfileResult;
+    /** Show the action to sign in to another account. Defaults to true. */
+    allowAddAccount?: boolean;
+    className?: string;
+    accountSettingsUrl?: string;
+}
+declare function UserButton(props: UserButtonProps): react.JSX.Element;
+interface UserMenuProps extends UserButtonProps {
+    trigger?: 'avatar' | 'button';
+    avatarProps?: UserAvatarProps;
+}
+declare function UserMenu({ accounts: supplied, auth: suppliedAuth, sync, showSyncStatus, showSyncBadge, shape, trigger, avatarProps, projectProfile, allowAddAccount, className, accountSettingsUrl, }: UserMenuProps): react.JSX.Element;
+interface BasicModalProps {
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    finalFocus?: RefObject<HTMLElement>;
+    /** Supply a button element; null omits the trigger for controlled use. */
+    trigger?: ReactNode;
+}
+interface AccountSettingsModalProps extends BasicModalProps {
+    auth?: UseAuthResult;
+    accounts?: UseAccountsResult;
+    projectProfile?: UseProjectProfileResult;
+    sync?: UseSyncStatusResult;
+    accountSettingsUrl?: string;
+    children?: ReactNode;
+}
+declare function AccountSettingsModal({ auth: suppliedAuth, accounts: suppliedAccounts, accountSettingsUrl, projectProfile, sync, children, ...props }: AccountSettingsModalProps): react.JSX.Element;
+interface SharesModalProps extends BasicModalProps {
+    auth?: UseAuthResult;
+    accounts?: UseAccountsResult;
+    sync?: UseSyncStatusResult;
+    shares?: UseOutgoingSharesResult;
+    /** Explicit least-privilege scope; the component never infers all tables. */
+    scope: CreateOutgoingShareInput['scope'];
+    repo?: CreateOutgoingShareInput['repo'];
+}
+declare function SharesModal({ auth: supplied, accounts: suppliedAccounts, sync, shares, scope, repo, ...props }: SharesModalProps): react.JSX.Element;
+
 /** Synchronous browser Storage adapted to core's key-value contract. */
 declare class BrowserKeyValueStorage implements KeyValueStorage {
     private readonly storage;
@@ -211,6 +316,8 @@ declare class BrowserTokenStore implements TokenStore {
     private waitForAccessToken;
 }
 
+/** The subset of BrowserTokenStore the auth channel needs; any token store providing it works. */
+type AccessTokenAdopter = Pick<BrowserTokenStore, 'accessToken' | 'adoptAccessToken'>;
 interface BrowserMessageChannel {
     postMessage(message: unknown): void;
     close(): void;
@@ -223,9 +330,11 @@ declare function createBrowserMessageChannel(name: string): BrowserMessageChanne
 /**
  * Access tokens may cross tabs transiently but are never written to browser
  * storage. The receiving adapter adopts the token before core handles the
- * ordinary token-rotation notification.
+ * ordinary token-rotation notification. Core supplies the token key for the
+ * profile's auth channel; channels without a context (the accounts channel)
+ * are plain BroadcastChannels.
  */
-declare function createBrowserAuthChannelFactory(clientId: string, tokenStore: BrowserTokenStore): (name: string) => AuthMessageChannel;
+declare function createBrowserAuthChannelFactory(tokenStore: AccessTokenAdopter): (name: string, context?: AuthChannelContext) => AuthMessageChannel;
 
 declare function browserNavigate(url: string): void;
 declare function browserCurrentUrl(): string;
@@ -269,4 +378,4 @@ declare class PersistenceStore implements ReplicaStoreFactory {
 /** Browser multipart transport with upload progress, adapted from the Drive UI. */
 declare const browserUploadTransport: UploadTransportAdapter;
 
-export { BasicProvider, type BasicProviderProps, type BoundBasicProviderProps, type BrowserBasicConfig, BrowserKeyValueStorage, type BrowserLockManager, type BrowserMessageChannel, BrowserTokenStore, type CreateBasicConfig, type CreatedBasic, PersistenceStore, type PersistenceStoreOptions, type UseAccountsResult, type UseAuthResult, type UseBasicResult, type UseFilesResult, type UseMountsResult, type UseOutgoingSharesResult, type UseQueryResult, type UseReposResult, type UseStorageInfoResult, type UseSyncStatusResult, browserCurrentUrl, browserNavigate, browserReplaceUrl, browserStorage, browserUploadTransport, createBasic, createBasicClient, createBrowserAuthChannelFactory, createBrowserMessageChannel, useAccounts, useAuth, useBasic, useCollection, useDb, useFiles, useMounts, useOutgoingShares, useQuery, useRepos, useSchemaStatus, useStorageInfo, useSyncStatus };
+export { type AccessTokenAdopter, AccountSettingsModal, type AccountSettingsModalProps, type AuthButtonProps, AuthStatus, type BasicAppearance, BasicButton, type BasicButtonProps, type BasicModalProps, BasicProvider, type BasicProviderProps, BasicUIProvider, type BoundBasicProviderProps, type BrowserBasicConfig, BrowserKeyValueStorage, type BrowserLockManager, type BrowserMessageChannel, BrowserTokenStore, type CreateBasicConfig, type CreatedBasic, PersistenceStore, type PersistenceStoreOptions, SharesModal, type SharesModalProps, SignInButton, SignOutButton, SyncStatus, type UseAccountsResult, type UseAuthResult, type UseBasicResult, type UseFilesResult, type UseMountsResult, type UseOutgoingSharesResult, type UseProjectProfileResult, type UseQueryResult, type UseReposResult, type UseStorageInfoResult, type UseSyncStatusResult, UserAvatar, type UserAvatarProps, UserButton, type UserButtonProps, UserMenu, type UserMenuProps, browserCurrentUrl, browserNavigate, browserReplaceUrl, browserStorage, browserUploadTransport, createBasic, createBasicClient, createBrowserAuthChannelFactory, createBrowserMessageChannel, useAccounts, useAuth, useBasic, useCollection, useDb, useFiles, useMounts, useOutgoingShares, useProjectProfile, useQuery, useRepos, useSchemaStatus, useStorageInfo, useSyncStatus };