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

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @basictech/react
 
+## 0.12.0-beta.4
+
+### Minor Changes
+
+- 0cd2283: Add useShareInvites for app-authorized invitation listing, inspection, acceptance, decline, and deletion with account-switch isolation and decision refresh. Add a drop-in ShareInvites inbox and ShareInvitesModal, integrate the inbox into account settings and SharesModal, and expose display-only ShareRecipientAvatar/ShareRecipientAvatars using the existing attributed local Marble renderer. Re-export the new APIs through the Next.js client entry point.
+
+  Use compact invite rows with right-aligned decisions and expandable details. Resolve public sender handles with DID/handle round-trip verification through client.shares.resolveContactHandle; omit routine pending labels, app IDs, and redundant subtitles.
+
+  Add useShareRecipients(dids) and its bound factory hook for verified public handles, deduplicated lookups, partial-error recovery, refresh, and stale-result isolation. Add ShareRecipientLabel for a compact avatar plus handle, and handle titles on avatar-only recipients. Reuse the existing local Marble renderer and upstream MIT attribution; no new dependencies or public photo lookup.
+
+  Reject saved or in-flight invite decisions when the hook switches SDK clients, even if both clients use the same local account ID. Do not refresh the replacement client's inbox for a stale decision.
+
+### Patch Changes
+
+- b5969b8: Label unnamed anonymous profiles as `Local User` and render locally adapted Marble avatars for
+  missing or failed profile images, seeded by DID or stable local account ID. Include upstream
+  attribution in the published package without adding a runtime dependency.
+- Updated dependencies [bbfb849]
+- Updated dependencies [0cd2283]
+- Updated dependencies [b5969b8]
+  - @basictech/core@0.12.0-beta.4
+
+## 0.12.0-beta.3
+
+### Minor Changes
+
+- fc5772a: Add app-owned menu actions and links with optional icons to UserAvatar, UserButton, and UserMenu.
+  Add a base background color to BasicUIProvider, derive borders and hover backgrounds from it,
+  and choose black or white text for hex accent colors. Preserve appearance in menu and modal
+  portals. Document component selection, simple theming, menu extensions, and Base UI dependencies.
+
+### Patch Changes
+
+- @basictech/core@0.12.0-beta.3
+
 ## 0.12.0-beta.2
 
 ### Minor Changes

package/README.md

@@ -18,14 +18,19 @@ its package metadata.
 
 ## Install
 
-This README describes the `0.12.0-beta.1` release candidate. After publication, install
+This README describes `0.12.0-beta.3`. After publication, install
 matching versions of the React SDK and the schema package you import directly:
 
 ```bash
-npm install @basictech/react@0.12.0-beta.1 @basictech/schema@0.12.0-beta.1
+npm install @basictech/react@0.12.0-beta.3 @basictech/schema@0.12.0-beta.3
 ```
 
-React is a peer dependency and must already be installed by your application.
+React and React DOM (18+) are peer dependencies and must already be installed by your application.
+Use Node.js 24+ for development, CI, and builds to match the supported engine range.
+`@base-ui/react` (`^1.8.0`) is installed automatically as a dependency, not a peer.
+We import its `avatar`, `dialog`, `menu`, and `tabs` subpaths and leave them external in the SDK
+build. Your app's bundler resolves those imports; we do not bundle the entire Base UI library
+inside the SDK. Installing the dependency does install the Base UI package on disk.
 
 ## Auth update guide
 
@@ -33,9 +38,9 @@ Upgrade the packages you use together. npm's `latest` channel remains on `0.11.0
 does not contain all of the API changes described here:
 
 ```bash
-npm install @basictech/react@0.12.0-beta.1 @basictech/schema@0.12.0-beta.1
+npm install @basictech/react@0.12.0-beta.3 @basictech/schema@0.12.0-beta.3
 # If you import core directly, update that dependency too:
-npm install @basictech/core@0.12.0-beta.1
+npm install @basictech/core@0.12.0-beta.3
 ```
 
 Keep the public packages on matching versions. No browser storage reset or persisted-profile
@@ -334,6 +339,10 @@ Drop-in account and sharing UI uses Base UI's accessible menu, avatar, and dialo
 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.
 
+**Which one should I use?** `UserButton` gives you the avatar, name, handle, and menu.
+Choose `UserAvatar` for the same menu with an avatar-only trigger. `UserMenu` is the shared
+component underneath both; you normally do not need to render it separately.
+
 ```tsx
 import {
   BasicUIProvider, SignInButton, UserButton, AuthStatus, SyncStatus, SharesModal,
@@ -360,22 +369,83 @@ export function AccountTools() {
 | --- | --- |
 | `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. |
+| `UserAvatar` | Borderless avatar trigger for the shared user menu. Current account or explicit `profile` (`null` means guest); `size`, `className`, `style`; a missing or failed image falls back to a locally adapted, deterministic Marble avatar seeded by DID, then account ID. The package ships its upstream attribution in `THIRD_PARTY_NOTICES.md`. 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
+| `AccountSettingsModal` | Profile tab edits the project display name with Cancel/Save changes; drafts survive tab switches. Invitations loads the in-app inbox when selected (`showInvites={false}` hides it). 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 shows the in-app invitation inbox with accept/decline. |
+| `ShareInvites` | Compact “Share Invites” list with sender handle/avatar, permissions, and right-aligned accept/decline actions. Details expands scope, expiry, and sender DID. Routine pending status, app IDs, and extra subtitles are omitted; expiry, compatibility, and completed decisions remain visible. Optional `invites` supplies a complete hook result. |
+| `ShareInvitesModal` | Standalone dialog wrapping `ShareInvites`; no outgoing scope required. Supports the same `invites` override. |
+| `ShareRecipientAvatar` | Display-only avatar with required `recipient: { did, name?, handle?, picture? }` and optional `size` (32 by default), native span attributes, and styles. Stable DID-seeded Marble fallback; no provider, menu, sync badge, or profile lookup. |
+| `ShareRecipientAvatars` | DID-deduplicated avatar stack with `recipients`, `size`, and `max` (4 by default); accessible overflow count. Names/photos are app-supplied, never inferred from share titles. |
+| `ShareRecipientLabel` | Avatar with visible `@handle`, falling back to a supplied name or “Unknown user”. Same `recipient` and native span props as the avatar; `size` defaults to 24. Long handles wrap. Canonical DID is available as the title, not the visible label. No provider or lookup required. |
+
+All 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.
+```tsx
+import { ShareInvitesModal, ShareInvites, ShareRecipientAvatars } from '@basictech/react'
+
+// Inside basic.Provider; choose a standalone dialog or an inline inbox:
+<ShareInvitesModal trigger="View invitations" />
+<ShareInvites />
+
+// Display-only recipient avatars also work outside the provider:
+<ShareRecipientAvatars recipients={[
+  { did: 'did:web:alice.example', name: 'Alice' },
+  { did: 'did:web:bob.example' },
+]} max={4} />
+```
+
+The user menu's account settings also includes Invitations by default; pass `showInvites={false}`
+to `UserButton`, `UserAvatar`, or `UserMenu` to hide it. These APIs are also exported from
+`@basictech/nextjs/client`. Keep the upstream attribution shipped with the Marble renderer.
+
+### Simple colors and custom menu items
+
+`appearance.base`, automatic accent contrast, and `menuItems` require `0.12.0-beta.3` or newer;
+they are not available in beta.2.
+
+Start with `theme: 'light'` or `'dark'`. Optionally set a `base` background and an `accent`.
+Light mode uses black text; dark mode uses white text, with muted shades for secondary text.
+Borders and hover backgrounds follow the base color. Choose a light base for light mode and a
+dark base for dark mode. Omit the accent for neutral black/white buttons. For an accent, use
+`#RGB` or `#RRGGBB`: solid buttons automatically choose black or white text for contrast.
+Other CSS accent values retain white foreground text; check their contrast yourself.
+
+```tsx
+import { BasicUIProvider, UserButton } from '@basictech/react'
+import '@basictech/react/styles.css'
+
+// Inside your existing BasicProvider. openPreferences is your app's callback.
+<BasicUIProvider appearance={{ theme: 'dark', base: '#201d17', accent: '#d4af37' }}>
+  <UserButton menuItems={[
+    { id: 'preferences', label: 'Preferences', onClick: openPreferences },
+    { id: 'about', label: 'About', href: '/about' },
+  ]} />
+</BasicUIProvider>
+```
+
+`UserAvatar`, `UserButton`, and `UserMenu` all accept `menuItems`. Each item has a unique `id`,
+`label`, either `href` or `onClick`, and optional `icon` (a React node) and `disabled`.
+Icons are decorative, sized to 16px, and can come from your app's existing icon library:
+`{ id: 'preferences', label: 'Preferences', icon: <SettingsIcon />, onClick: openPreferences }`.
+Items appear after Manage account and before Sign out/Clear account. Selecting an item closes
+the menu; async action failures use the SDK's dismissible error dialog. Use `onClick` to call
+your router when you need client-side navigation rather than a normal link.
+
+Nested appearance providers inherit settings, including in portaled menus and modals.
+Pass your app's current light/dark mode to `theme`; there is no separate theme listener.
+Existing `radius` and `density: 'comfortable' | 'compact'` options remain available.
+Fonts inherit from the host. No icon pack or additional provider is needed.
+
+To replace custom auth UI, keep your existing BasicProvider, import the stylesheet once,
+and replace the old avatar/dropdown with `UserButton` or `UserAvatar`. Move app-owned actions
+into `menuItems`; account switching and sign-out remain SDK-managed. `accountSettingsUrl`
+only adds a link inside the built-in settings modal—it does not replace Manage account.
 
 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
@@ -434,6 +504,8 @@ unknown table names and infer fields in reads, writes, and queries.
 | `useStorageInfo` | `useStorageInfo(): UseStorageInfoResult` | Default repo storage use and quota |
 | `useMounts` | `useMounts(query?): UseMountsResult` | Incoming mounts and mount opening |
 | `useOutgoingShares` | `useOutgoingShares(): UseOutgoingSharesResult` | Outgoing share lifecycle |
+| `useShareInvites` | `useShareInvites(enabled?): UseShareInvitesResult` | Incoming invitation list, inspection, and decisions |
+| `useShareRecipients` | `useShareRecipients(dids: readonly string[]): UseShareRecipientsResult` | Public, verified handles for share recipients or senders |
 | `useBasic` | `useBasic(): UseBasicResult` | Auth plus common client, db, account, sync, and repo state |
 
 ### `basic.useAuth()`
@@ -992,9 +1064,113 @@ After a handle-based share is created successfully, the SDK stores a profile-loc
 containing `{ did, handle }` in browser local storage. Use `getContactHandle(recipientDid)` to show
 the remembered handle; it returns `null` for DIDs that were shared directly or are not cached.
 
-`manageUrl()` returns the Basic ID `/shares` handoff. Invite acceptance and ordinary mount
-management belong there. `client.shares.leave()` is intentionally owner-only and throws
-`OWNER_CREDENTIAL_REQUIRED` without an explicit owner adapter.
+`manageUrl()` remains an optional Basic ID `/shares` handoff. Invitations can now be managed
+inside apps with `useShareInvites()` or the prebuilt components. `client.shares.leave(mountId)`
+also supports matching app Shares write permission (or root Shares write permission).
+
+### `basic.useShareInvites()`
+
+```text
+{
+  data: ShareInviteInfo[]
+  isLoading: boolean
+  error: BasicError | null
+  refresh(): void
+  get(id: string): Promise<ShareInviteInfo>
+  accept(id: string): Promise<MountInfo>
+  decline(id: string): Promise<ShareInviteInfo>
+  delete(id: string): Promise<ShareInviteInfo>
+  resolveContactHandle(did: string): Promise<string | null>
+}
+```
+
+Uses the signed-in account's existing core `client.shares` invitation methods with app credentials;
+no owner adapter or Basic ID navigation is needed. Reads require Shares read (or matching app)
+permission, and decisions require write permission. Results are app-scoped unless explicitly
+granted root Shares access. Permission/compatibility errors are not treated as an empty inbox.
+Pass `false` to defer loading until your inbox is visible; imperative methods still work.
+
+`resolveContactHandle(did)` uses public DID-document and handle-resolution requests without
+credentials. It only returns an advertised `basic://` handle if resolving that handle points
+back to the same DID. Missing/unverified handles return `null`; network failures reject.
+The inbox loads handles independently of invitations, shows “Unknown sender” on failure, and
+keeps the canonical DID under Details. It never invents a handle from the DID or share title.
+Custom `invites` results must supply this resolver too; standalone recipient avatars still
+make no network requests.
+
+`ShareInviteInfo` includes sender `originOwnerDid`, `appId`, `role`, `scope`, display titles,
+`acceptBy`, `state`, compatibility, and received/decision timestamps. Review these fields before
+acceptance: display titles describe data, not the sender's identity. Accepting creates a mount
+for data shared **with** the recipient; it does not grant access to the recipient's own data.
+
+Pending invitations can be accepted, declined, or deleted. An `accepting` invitation can retry
+acceptance, but cannot be declined/deleted. Expired or incompatible invitations cannot be accepted;
+expired pending invitations can still be declined. The server enforces all permissions and states.
+Decisions refresh this hook's list even on failure, because acceptance may have partially advanced.
+Other hook instances are independent: refresh an existing mount list after acceptance and call
+`mounts.open(mount.id)` to access its data. For custom behavior, the inline/modal `invites` prop
+accepts a hook result with wrapped methods:
+
+```tsx
+function Inbox() {
+  const invites = basic.useShareInvites()
+  const mounts = basic.useMounts()
+  return <ShareInvites invites={{
+    ...invites,
+    async accept(id) {
+      const mount = await invites.accept(id)
+      mounts.refresh()
+      return mount
+    },
+  }} />
+}
+```
+
+An account switch immediately hides the previous account's data/errors. Stale decision callbacks
+and late results reject with `ACCOUNT_CHANGED`; this does not undo a request already sent to the
+server. Loading and action state in the components resets by local profile ID, including two
+profiles with the same DID. Custom UI must catch rejected imperative calls.
+
+### `basic.useShareRecipients()` and shared-user display
+
+`useShareRecipients(dids)` returns `{ data: ShareRecipient[], isLoading, error, refresh }`.
+Pass outgoing `recipientDid` values, incoming `originOwnerDid` values, or any list of DIDs.
+For one person, pass `[did]`. The hook requires the provider but not sign-in: it uses public
+`client.shares.resolveContactHandle()` lookups with DID → handle → DID verification.
+
+- DIDs are deduplicated in first-occurrence order. Recreating an equivalent array does not refetch.
+- `data` immediately contains `{ did, handle: null }` entries, so avatars can render while loading.
+- Once lookups settle, verified handles are filled in. Missing/unverified handles remain `null`.
+  A failed request leaves that recipient's handle `null`, preserves the other results, and exposes
+  the first failure (in input order) as `error`. `refresh()` retries the current list.
+- Input/client changes hide obsolete identities immediately and ignore late results. Each hook
+  instance owns its requests; resolve once in a parent and reuse `data` across labels/stacks.
+- The Shares API has no public photo/name endpoint. The hook does not fetch those fields.
+  You may supply `name` or `picture` from your app. Missing/loading/failed images use the existing
+  DID-seeded local Marble avatar, with its MIT attribution retained.
+
+```tsx
+import { ShareRecipientAvatars, ShareRecipientLabel } from '@basictech/react'
+import '@basictech/react/styles.css'
+import { basic } from './basic'
+
+function SharedWith({ dids }: { dids: readonly string[] }) {
+  const { data, error, refresh } = basic.useShareRecipients(dids)
+  return (
+    <div>
+      <ShareRecipientAvatars recipients={data} max={4} />
+      <ul>{data.map((recipient) => (
+        <li key={recipient.did}><ShareRecipientLabel recipient={recipient} /></li>
+      ))}</ul>
+      {error && <button onClick={refresh}>Retry handle lookup</button>}
+    </div>
+  )
+}
+```
+
+All three recipient components are display-only and accept the same `ShareRecipient` shape.
+They do not open the account menu or fetch identities themselves. In Next.js Client Components,
+import these components and `useShareRecipients` from `@basictech/nextjs/client`.
 
 ### `basic.useMounts()` and mounted data
 
@@ -1182,7 +1358,8 @@ The unbound exports mirror the bound hooks:
 | `useQuery<V>(name, query?, { source? }?)` | Caller supplies a JSON object value type; name is a string |
 | `useSyncStatus(source?)`, `useSchemaStatus(source?)` | Same status results |
 | `useRepos()`, `useFiles()`, `useStorageInfo()` | Same repo/file results |
-| `useMounts()`, `useOutgoingShares()` | Same share results |
+| `useMounts()`, `useOutgoingShares()`, `useShareInvites(enabled?)` | Same share results |
+| `useShareRecipients(dids)` | Same public identity result |
 
 Every unbound hook must run below `BasicProvider`; otherwise it throws `Basic hooks must be used
 within a <BasicProvider>`. Bound hooks likewise throw outside their own `basic.Provider`, because
@@ -1236,13 +1413,16 @@ Common application-facing codes include:
 | `STALE_WRITE`, `SCHEMA_VALIDATION_FAILED` | Server rejected a write; REST errors arrive as `ProblemError`, while sync terminal failures appear in `rejected` |
 | `ACCESS_TOKEN_ADOPTION_TIMEOUT`, `invalid_grant` | Cross-tab token adoption failed or reauthentication is required |
 
-Data hooks (`useQuery`, `useFiles`, `useStorageInfo`, `useMounts`, and `useOutgoingShares`) use the
-same `{ data, isLoading, error }` lifecycle. Files/mounts/outgoing also expose `refresh()`. Disabled
-signed-out storage, mount, and outgoing-share hooks settle after client readiness with empty/null
+Data hooks (`useQuery`, `useFiles`, `useStorageInfo`, `useMounts`, `useOutgoingShares`, and
+`useShareInvites`) use the same `{ data, isLoading, error }` lifecycle. Files/mounts/outgoing/invites
+also expose `refresh()`. Disabled signed-out storage, mount, and share hooks settle after client readiness with empty/null
 data rather than remaining loading. Non-Basic data-hook failures are wrapped as `UNKNOWN_ERROR`;
 query failures use `QUERY_FAILED` as the fallback code. `useAuth().error` reflects auth lifecycle
 errors; imperative methods reject and should be caught at the call site.
 
+`useShareRecipients` has the same result/refresh shape but performs public identity lookup without
+an auth gate. Partial lookup failures preserve successful recipients instead of clearing the list.
+
 ## Sync and REST modes
 
 The database and query shapes are shared, but the guarantees differ:

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,29 @@
+# Third-party notices
+
+## boring-avatars Marble renderer
+
+The built-in Marble avatar fallback adapts the Marble renderer and required utility behavior from
+boring-avatars 2.0.4, commit `89270f1d423a60a2fa2c241127e1744cba38aa38`:
+https://github.com/boringdesigners/boring-avatars/tree/89270f1d423a60a2fa2c241127e1744cba38aa38
+
+MIT License
+
+Copyright (c) 2021 boringdesigners
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 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';
+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, ShareInviteInfo, 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. */
@@ -133,6 +133,29 @@ interface UseProjectProfileResult extends AsyncResult<ProjectProfile | null> {
 }
 declare function useProjectProfile(enabled?: boolean): UseProjectProfileResult;
 
+interface UseShareInvitesResult {
+    data: ShareInviteInfo[];
+    isLoading: boolean;
+    error: BasicError | null;
+    refresh(): void;
+    get(id: string): Promise<ShareInviteInfo>;
+    accept(id: string): Promise<MountInfo>;
+    decline(id: string): Promise<ShareInviteInfo>;
+    delete(id: string): Promise<ShareInviteInfo>;
+    resolveContactHandle(did: string): Promise<string | null>;
+}
+declare function useShareInvites(enabled?: boolean): UseShareInvitesResult;
+
+/** Names/photos are optional app-supplied data, never inferred from a share title. */
+interface ShareRecipient {
+    did: string;
+    name?: string | null;
+    handle?: string | null;
+    picture?: string | null;
+}
+type UseShareRecipientsResult = AsyncResult<ShareRecipient[]>;
+declare function useShareRecipients(dids: readonly string[]): UseShareRecipientsResult;
+
 type CreateBasicConfig<S extends BasicSchema> = BrowserBasicConfig<S> & {
     schema: S;
 };
@@ -169,6 +192,8 @@ interface CreatedBasic<S extends BasicSchema> {
     useStorageInfo(): UseStorageInfoResult;
     useMounts(query?: MountsQuery): UseMountsResult<S>;
     useOutgoingShares(): UseOutgoingSharesResult;
+    useShareInvites(enabled?: boolean): UseShareInvitesResult;
+    useShareRecipients(dids: readonly string[]): UseShareRecipientsResult;
 }
 /** Create one browser client and a complete hook surface bound to its schema. */
 declare function createBasic<const S extends BasicSchema>(config: CreateBasicConfig<S>): CreatedBasic<S>;
@@ -198,6 +223,9 @@ declare function useCollection<V extends JsonObject = JsonObject>(name: string,
 
 interface BasicAppearance {
     theme?: 'light' | 'dark';
+    /** Background color. Choose a light or dark base to match the theme. */
+    base?: string;
+    /** Hex colors get automatic black/white foreground contrast. */
     accent?: string;
     radius?: string;
     density?: 'compact' | 'comfortable';
@@ -218,16 +246,34 @@ interface AuthButtonProps extends BasicButtonProps {
 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;
+    profile?: (Pick<BasicProfile, 'name' | 'handle' | 'email' | 'picture'> & Partial<Pick<BasicProfile, 'id' | 'did' | 'kind'>>) | null;
     size?: number;
     showSyncBadge?: boolean;
     sync?: UseSyncStatusResult;
     accounts?: UseAccountsResult;
     auth?: UseAuthResult;
     projectProfile?: UseProjectProfileResult;
+    invites?: UseShareInvitesResult;
+    showInvites?: boolean;
     allowAddAccount?: boolean;
+    menuItems?: UserMenuItem[];
+}
+declare function UserAvatar({ accounts, auth, projectProfile, invites, showInvites, allowAddAccount, menuItems, ...avatarProps }: UserAvatarProps): react.JSX.Element;
+interface ShareRecipientAvatarProps extends HTMLAttributes<HTMLSpanElement> {
+    recipient: ShareRecipient;
+    size?: number;
 }
-declare function UserAvatar({ accounts, auth, projectProfile, allowAddAccount, ...avatarProps }: UserAvatarProps): react.JSX.Element;
+/** Display-only identity: no account menu, sync badge, provider, or profile lookup. */
+declare function ShareRecipientAvatar({ recipient, ...props }: ShareRecipientAvatarProps): react.JSX.Element;
+type ShareRecipientLabelProps = ShareRecipientAvatarProps;
+/** Avatar and visible handle; accepts the same data as the avatar-only components. */
+declare function ShareRecipientLabel({ recipient, size, className, ...props }: ShareRecipientLabelProps): react.JSX.Element;
+interface ShareRecipientAvatarsProps extends HTMLAttributes<HTMLSpanElement> {
+    recipients: readonly ShareRecipient[];
+    size?: number;
+    max?: number;
+}
+declare function ShareRecipientAvatars({ recipients, size, max, className, ...props }: ShareRecipientAvatarsProps): react.JSX.Element;
 declare function AuthStatus({ auth: supplied, className, ...props }: HTMLAttributes<HTMLSpanElement> & {
     auth?: UseAuthResult;
 }): react.JSX.Element;
@@ -235,6 +281,19 @@ declare function SyncStatus({ sync: supplied, source, className, ...props }: HTM
     sync?: UseSyncStatusResult;
     source?: SourceRef;
 }): react.JSX.Element | null;
+/** App-owned items appear after Manage account and before Sign out. */
+type UserMenuItem = {
+    id: string;
+    label: string;
+    icon?: ReactNode;
+    disabled?: boolean;
+} & ({
+    href: string;
+    onClick?: never;
+} | {
+    onClick: () => void | Promise<void>;
+    href?: never;
+});
 interface UserButtonProps {
     accounts?: UseAccountsResult;
     auth?: UseAuthResult;
@@ -245,17 +304,20 @@ interface UserButtonProps {
     showSyncBadge?: boolean;
     shape?: 'rounded' | 'square';
     projectProfile?: UseProjectProfileResult;
+    invites?: UseShareInvitesResult;
+    showInvites?: boolean;
     /** Show the action to sign in to another account. Defaults to true. */
     allowAddAccount?: boolean;
     className?: string;
     accountSettingsUrl?: string;
+    menuItems?: UserMenuItem[];
 }
 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;
+declare function UserMenu({ accounts: supplied, auth: suppliedAuth, sync, showSyncStatus, showSyncBadge, shape, trigger, avatarProps, projectProfile, invites, showInvites, allowAddAccount, className, accountSettingsUrl, menuItems, }: UserMenuProps): react.JSX.Element;
 interface BasicModalProps {
     open?: boolean;
     onOpenChange?: (open: boolean) => void;
@@ -267,21 +329,39 @@ interface AccountSettingsModalProps extends BasicModalProps {
     auth?: UseAuthResult;
     accounts?: UseAccountsResult;
     projectProfile?: UseProjectProfileResult;
+    invites?: UseShareInvitesResult;
+    /** Show the in-app invitation inbox. Defaults to true; loads only when selected. */
+    showInvites?: boolean;
     sync?: UseSyncStatusResult;
     accountSettingsUrl?: string;
     children?: ReactNode;
 }
-declare function AccountSettingsModal({ auth: suppliedAuth, accounts: suppliedAccounts, accountSettingsUrl, projectProfile, sync, children, ...props }: AccountSettingsModalProps): react.JSX.Element;
+declare function AccountSettingsModal({ auth: suppliedAuth, accounts: suppliedAccounts, accountSettingsUrl, projectProfile, invites, showInvites, sync, children, ...props }: AccountSettingsModalProps): react.JSX.Element;
+interface ShareInvitesProps extends HTMLAttributes<HTMLElement> {
+    auth?: UseAuthResult;
+    accounts?: UseAccountsResult;
+    /** Optional complete hook result, useful for previews or app-owned state. */
+    invites?: UseShareInvitesResult;
+}
+/** Inline invitation inbox, shared by standalone and account-settings dialogs. */
+declare function ShareInvites({ auth: suppliedAuth, accounts: suppliedAccounts, invites, className, ...props }: ShareInvitesProps): react.JSX.Element;
+interface ShareInvitesModalProps extends BasicModalProps {
+    auth?: UseAuthResult;
+    accounts?: UseAccountsResult;
+    invites?: UseShareInvitesResult;
+}
+declare function ShareInvitesModal({ auth, accounts, invites, ...props }: ShareInvitesModalProps): react.JSX.Element;
 interface SharesModalProps extends BasicModalProps {
     auth?: UseAuthResult;
     accounts?: UseAccountsResult;
     sync?: UseSyncStatusResult;
     shares?: UseOutgoingSharesResult;
+    invites?: UseShareInvitesResult;
     /** 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;
+declare function SharesModal({ auth: supplied, accounts: suppliedAccounts, sync, shares, invites, scope, repo, ...props }: SharesModalProps): react.JSX.Element;
 
 /** Synchronous browser Storage adapted to core's key-value contract. */
 declare class BrowserKeyValueStorage implements KeyValueStorage {
@@ -378,4 +458,4 @@ declare class PersistenceStore implements ReplicaStoreFactory {
 /** Browser multipart transport with upload progress, adapted from the Drive UI. */
 declare const browserUploadTransport: UploadTransportAdapter;
 
-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 };
+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, ShareInvites, ShareInvitesModal, type ShareInvitesModalProps, type ShareInvitesProps, type ShareRecipient, ShareRecipientAvatar, type ShareRecipientAvatarProps, ShareRecipientAvatars, type ShareRecipientAvatarsProps, ShareRecipientLabel, type ShareRecipientLabelProps, 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 UseShareInvitesResult, type UseShareRecipientsResult, type UseStorageInfoResult, type UseSyncStatusResult, UserAvatar, type UserAvatarProps, UserButton, type UserButtonProps, UserMenu, type UserMenuItem, type UserMenuProps, browserCurrentUrl, browserNavigate, browserReplaceUrl, browserStorage, browserUploadTransport, createBasic, createBasicClient, createBrowserAuthChannelFactory, createBrowserMessageChannel, useAccounts, useAuth, useBasic, useCollection, useDb, useFiles, useMounts, useOutgoingShares, useProjectProfile, useQuery, useRepos, useSchemaStatus, useShareInvites, useShareRecipients, useStorageInfo, useSyncStatus };