@lunora/react 1.0.0-alpha.24 → 1.0.0-alpha.241

package/dist/index.d.mts

@@ -1,174 +1,100 @@
 import { ReactNode, ReactElement } from 'react';
-import { LunoraClient, OptimisticUpdate, User, ConnectionStatus, ReturnOf, ArgsOf, FunctionReference, MutatorHandle, Preloaded } from '@lunora/client';
-export { type ArgsOf, type FunctionReference, type LunoraClient, type LunoraErrorCode, type MutatorHandle, type MutatorTransaction, type OptimisticLocalStore, type OptimisticUpdate, type Preloaded, type ReturnOf, type User, getErrorCode, getRetryAfterMs, isConflictError, isForbiddenError, isRateLimitedError, isUnauthorizedError } from '@lunora/client';
+import { LunoraClient, OptimisticUpdate, User, SubscriptionErrorCallback, SubscriptionError, FunctionReference, ArgsOf, ActionCallOptions, ReturnOf, AuthImpersonation, AuthSession, AuthUser, ClientQueryRef, ConnectionStatus, HttpStreamRef, HttpStreamArgsOf, HttpStreamChunkOf, SubscribeLiveTopicOptions, LiveStreamSubscribeError, MutatorHandle, Preloaded } from '@lunora/client';
+export { type ArgsOf, type AuthImpersonation, type AuthPage, type AuthSession, type AuthUser, type ClientQueryRef, type FunctionReference, type HttpStreamArgsOf, type HttpStreamChunkOf, type HttpStreamRef, type LunoraClient, type LunoraErrorCode, type MutatorHandle, type MutatorTransaction, type OptimisticLocalStore, type OptimisticUpdate, type Preloaded, type ReturnOf, type SubscriptionError, type SubscriptionErrorCallback, type User, createClientQuery, getErrorCode, getRetryAfterMs, isConflictError, isForbiddenError, isRateLimitedError, isUnauthorizedError } from '@lunora/client';
 import { QueryClient } from '@tanstack/react-query';
-export { type L as LunoraQueryOptions, l as lunoraQueryOptions } from "./packem_shared/query-options.d-D4okOpO8.mjs";
+export { type L as LunoraQueryOptions, l as lunoraQueryOptions } from "./packem_shared/query-options.d-CdgGQ9s4.mjs";
+import { AuthStatus } from '@lunora/client/auth';
 import { PaginationStatus } from '@lunora/client/pagination';
 export type { PaginationResult, PaginationStatus } from '@lunora/client/pagination';
 import { RateLimitStatus, RateLimitConfig } from '@lunora/ratelimit';
+export { RestrictionError, UploadControl, UploadError, type UploadRestrictions } from '@visulima/storage-client';
+export { type UploadMethod, type UploadResult, type UseChunkedRestUploadOptions, type UseChunkedRestUploadReturn, type UseFileInputOptions, type UseFileInputReturn, type UseMultipartUploadOptions, type UseMultipartUploadReturn, type UsePasteUploadOptions, type UsePasteUploadReturn, type UseTusUploadOptions, type UseTusUploadReturn, type UseUploadOptions, type UseUploadReturn, useChunkedRestUpload, useFileInput, useMultipartUpload, usePasteUpload, useTusUpload, useUpload } from '@visulima/storage-client/react';
 interface AuthGateProps {
   children: ReactNode;
 }
-/** Renders `children` only once a token is set on the client (after hydration). */
-declare const Authenticated: ({
-  children
-}: AuthGateProps) => ReactNode;
-/** Renders `children` only when auth has settled and no token is set. */
-declare const Unauthenticated: ({
-  children
-}: AuthGateProps) => ReactNode;
-/** Renders `children` while auth is still settling (before hydration completes). */
-declare const AuthLoading: ({
-  children
-}: AuthGateProps) => ReactNode;
-/**
-* Resolved auth-gate state. `isLoading` covers the window before the client has
-* hydrated — the server render and the first hydration render both report
-* loading, so the markup agrees and no signed-out UI flashes in.
-*/
+/**
+ * Renders `children` once authentication has settled in the caller's favour — a
+ * credential is held and nothing has contradicted it. Follows the shared
+ * `AuthStatus` contract in `@lunora/client/auth`, so an unreachable identity
+ * endpoint keeps the gate open (with `useAuth().user` still `null`).
+ */
+declare const Authenticated: ({ children }: AuthGateProps) => ReactNode;
+/** Renders `children` only when auth has settled and there is no session. */
+declare const Unauthenticated: ({ children }: AuthGateProps) => ReactNode;
+/** Renders `children` while auth is still settling — before hydration, or while the first identity resolve is in flight. */
+declare const AuthLoading: ({ children }: AuthGateProps) => ReactNode;
+/**
+ * Resolved auth-gate state, derived from the shared `AuthStatus` contract in
+ * `@lunora/client/auth` — the same mapping Vue, Solid, Svelte and Angular use.
+ */
 interface AuthState {
   isAuthenticated: boolean;
   isLoading: boolean;
 }
 /**
-* Three-state auth status for gating UI. Reports `isLoading` until the client
-* has hydrated, then `isAuthenticated` tracks whether a token is set on the
-* shared client.
-*
-* Lunora auth is token-based and resolves synchronously once the token is
-* known, so the loading window is hydration rather than a server round-trip —
-* use it (via {@link AuthState}) to render a fallback while it settles.
-*/
+ * Three-state auth status for gating UI.
+ *
+ * `isLoading` covers the server render and the first hydration render (the
+ * identity store's server snapshot is `"loading"`, so the markup agrees and no
+ * signed-out UI flashes in) as well as the window where a credential is held and
+ * its first identity resolve is still in flight.
+ *
+ * `isAuthenticated` follows the credential, not the identity record: an
+ * unreachable identity endpoint keeps the gate open with `user === null`. A UI
+ * that needs to tell that apart reads `useAuth().status`.
+ */
 declare const useAuthState: () => AuthState;
 interface LunoraProviderProps {
   children: ReactNode;
   client: LunoraClient;
   /**
-  * Bring-your-own QueryClient. When omitted, the provider creates one with
-  * defaults tuned for Lunora's push-driven model: `staleTime: Infinity` (the
-  * WS subscription is the only invalidation signal), `retry: 0` (failures
-  * route through the offline queue on the client), and `gcTime: 5min` (keep
-  * results around for a short return-to-view window).
-  *
-  * If a parent `<QueryClientProvider>` is already mounted, the provider
-  * uses *that* client and does NOT install an inner one (so apps with their
-  * own setup don't double-wrap).
-  */
+   * Bring-your-own QueryClient. When omitted, the provider creates one with
+   * defaults tuned for Lunora's push-driven model: `staleTime: Infinity` (the
+   * WS subscription is the only invalidation signal), `retry: 0` (failures
+   * route through the offline queue on the client), and `gcTime: 5min` (keep
+   * results around for a short return-to-view window).
+   *
+   * If a parent `<QueryClientProvider>` is already mounted, the provider
+   * uses *that* client and does NOT install an inner one (so apps with their
+   * own setup don't double-wrap).
+   */
   queryClient?: QueryClient;
 }
 /**
-* Provides both the {@link LunoraClient} and a TanStack `QueryClient` to the
-* tree. The detection logic for a parent QueryClientProvider keeps this safe to
-* drop into an app that already runs TanStack Query for its own purposes.
-*/
-declare const LunoraProvider: ({
-  children,
-  client,
-  queryClient
-}: LunoraProviderProps) => ReactElement;
+ * Provides both the {@link LunoraClient} and a TanStack `QueryClient` to the
+ * tree. The detection logic for a parent QueryClientProvider keeps this safe to
+ * drop into an app that already runs TanStack Query for its own purposes.
+ */
+declare const LunoraProvider: ({ children, client, queryClient }: LunoraProviderProps) => ReactElement;
 /**
-* Read the {@link LunoraClient} from the nearest `&lt;LunoraProvider>`. Kept
-* colocated with the provider for back-compat.
-*/
+ * Read the {@link LunoraClient} from the nearest `<LunoraProvider>`. Kept
+ * colocated with the provider for back-compat.
+ */
 declare const useLunora: () => LunoraClient;
-/**
-* Client-safe mirror of `@lunora/payment`'s `Subscription`. Re-declared here
-* (rather than imported) so this React entry never pulls in the server-only
-* `@lunora/payment` module graph — the kit stays React + DOM only. Keep this in
-* sync with `packages/payment/src/types.ts`.
-*/
-interface Subscription {
-  readonly cancelAtPeriodEnd: boolean;
-  readonly createdAt: number;
-  readonly currentPeriodEnd?: number;
-  readonly id: string;
-  readonly priceId: string;
-  readonly provider: "polar" | "stripe";
-  readonly quantity: number;
-  readonly referenceId: string;
-  readonly state: "active" | "canceled" | "past_due" | "paused" | "trialing";
-  readonly updatedAt: number;
-}
-/** The `{ url }` shape every checkout/portal trigger resolves to. */
-interface RedirectTarget {
-  readonly url: string;
-}
-/** A thunk the app supplies that calls its own Lunora action and resolves a redirect URL. */
-type RedirectTrigger = () => Promise<RedirectTarget>;
-interface UseCheckoutResult {
-  /** Run the trigger and redirect the browser to the resolved URL. Resolves once the redirect is issued; rejects on failure. */
-  checkout: () => Promise<void>;
-  /** The most recent failure, or `undefined`. */
-  error: Error | undefined;
-  /** `true` while the trigger is in flight (before the redirect is issued). */
-  pending: boolean;
-}
-/**
-* Decoupled redirect-on-resolve primitive shared by `CheckoutButton` and
-* `CustomerPortalButton`. The app passes a `trigger` thunk that calls its own
-* Lunora action (the one wrapping `LunoraPayment.createCheckout` /
-* `createPortalSession`) and resolves `{ url }`; this hook awaits it, flips
-* `pending`, surfaces any `error`, and on success navigates via
-* `location.assign(url)`.
-*
-* Mirrors Convex's `CheckoutLink` / `CustomerPortalLink` flow (trigger an action
-* that returns a URL, then redirect) while staying agnostic of the app's
-* function names.
-*/
-declare const useCheckout: (trigger: RedirectTrigger) => UseCheckoutResult;
-/**
-* Presentational props shared by the redirect buttons. Kept to a curated set
-* (rather than spreading arbitrary button attributes) so the component stays
-* within the repo's `react/jsx-props-no-spreading` rule while covering the
-* common styling / accessibility hooks.
-*/
-interface RedirectButtonOwnProps {
-  /** Accessible label when the visible `children` are icon-only. */
-  "aria-label"?: string;
-  children?: ReactNode;
-  className?: string;
-  /** Force-disable the control regardless of pending state. */
-  disabled?: boolean;
-  /** Called with the failure when the trigger rejects. The error is also surfaced via `useCheckout`. */
-  onError?: (error: Error) => void;
-  title?: string;
-}
-interface CheckoutButtonProps extends RedirectButtonOwnProps {
-  /** Calls the app's checkout action and resolves the hosted-checkout `{ url }`. */
-  onCheckout: RedirectTrigger;
-}
-interface CustomerPortalButtonProps extends RedirectButtonOwnProps {
-  /** Calls the app's portal action and resolves the customer-portal `{ url }`. */
-  onPortal: RedirectTrigger;
-}
-/**
-* Button that starts a hosted checkout. On click it awaits `onCheckout` (a thunk
-* that calls the app's checkout action) and redirects to the returned URL,
-* disabling itself while the request is in flight.
-*/
-declare const CheckoutButton: ({
-  onCheckout,
-  ...rest
-}: CheckoutButtonProps) => ReactNode;
-/**
-* Button that opens the provider's customer portal. On click it awaits
-* `onPortal` (a thunk that calls the app's portal action) and redirects to the
-* returned URL, disabling itself while the request is in flight.
-*/
-declare const CustomerPortalButton: ({
-  onPortal,
-  ...rest
-}: CustomerPortalButtonProps) => ReactNode;
 interface UseQueryOptions {
+  /**
+   * Called when the server pushes a subscription-scoped error (an RLS denial, a
+   * query that starts failing server-side). Without a handler such an error has
+   * nowhere to go and the hook's value simply freezes at its last good result.
+   */
+  onError?: SubscriptionErrorCallback;
   shardKey?: string;
 }
 interface UseMutationCallOptions<TCurrent = unknown, TValue = unknown, TArgs = unknown> {
+  /**
+   * Single-query shortcut forwarded to `client.mutation`: the transform is
+   * layered onto the subscription registered under **this write's own**
+   * `(reference, args, shardKey)` and nothing else. A `messages:send` mutation
+   * and a `messages:list` query share neither, so for that shape — nearly every
+   * shape — reach for {@link UseMutationCallOptions.optimisticUpdate}, whose
+   * store names the query it patches.
+   */
   optimistic?: (current: TCurrent | undefined) => TValue;
   /**
-  * Convex-parity multi-query optimistic update forwarded to
-  * `client.mutation`. Patches many subscribed queries at once via an
-  * `OptimisticLocalStore`, rolled back atomically on failure.
-  */
+   * Convex-parity multi-query optimistic update forwarded to
+   * `client.mutation`. Patches many subscribed queries at once via an
+   * `OptimisticLocalStore`, rolled back atomically on failure.
+   */
   optimisticUpdate?: OptimisticUpdate<TArgs>;
   shardKey?: string;
 }
@@ -179,9 +105,19 @@ interface UseSubscriptionResult<T> {
 interface UsePaginatedQueryOptions {
   /** Page size for the first page (and the default for `loadMore`). */
   initialNumItems: number;
+  /** Called when a page subscription (or its initial fetch) fails; also surfaced on `error`. */
+  onError?: SubscriptionErrorCallback;
   shardKey?: string;
 }
 interface UsePaginatedQueryResult<T> {
+  /**
+   * The last page failure, or `undefined`. A tail page that fails before its
+   * first frame is dropped so `status` returns to `"CanLoadMore"` and
+   * `loadMore` can retry it; the first page has nothing to fall back to and
+   * stays `"LoadingFirstPage"` with this set. Cleared by the next successful
+   * frame, by `loadMore`, or by an args change.
+   */
+  error: SubscriptionError | undefined;
   /** `true` while the first page or a `loadMore` page is in flight. */
   isLoading: boolean;
   /** Request the next page. A no-op unless `status === "CanLoadMore"`. */
@@ -193,9 +129,13 @@ interface UsePaginatedQueryResult<T> {
 interface UseInfiniteQueryOptions {
   /** Page size for the first page (and the default for `fetchNextPage`). */
   initialNumItems: number;
+  /** Called when a page subscription (or its initial fetch) fails; also surfaced on `error`. */
+  onError?: SubscriptionErrorCallback;
   shardKey?: string;
 }
 interface UseInfiniteQueryResult<T> {
+  /** The last page failure, or `undefined` — see `UsePaginatedQueryResult.error`. */
+  error: SubscriptionError | undefined;
   /** Request the next page. A no-op unless `status === "CanLoadMore"`. */
   fetchNextPage: (numberItems?: number) => void;
   /** `true` when the loaded tail reports it can load another page. */
@@ -210,61 +150,753 @@ interface UseInfiniteQueryResult<T> {
 }
 interface UseAuthResult {
   setToken: (token: string | null) => void;
+  /**
+   * The resolved auth state. Branch on this, not on `user === null` — see the
+   * contract in `@lunora/client/auth`; `user` is `null` both when signed out
+   * and when a held credential's identity could not be resolved.
+   */
+  status: AuthStatus;
   token: string | null;
   user: User | null;
 }
+interface ActionHook<F extends FunctionReference> {
+  /**
+   * Invoke the action. Awaitable, and rejects on failure — the same contract
+   * as `useMutation`'s `mutate`.
+   */
+  call: (args: ArgsOf<F>, options?: ActionCallOptions) => Promise<ReturnOf<F>>;
+  /** The latest invocation's resolved value, or `undefined` before the first success. */
+  data: ReturnOf<F> | undefined;
+  /** The latest invocation's error, or `undefined`. */
+  error: Error | undefined;
+  /** `true` while ANY invocation from this hook is in flight (ref-counted, so overlapping calls compose). */
+  pending: boolean;
+  /** Clear the latest `data`/`error` back to idle. */
+  reset: () => void;
+}
+/**
+ * Returns `{ call, pending, data, error, reset }` for the given action reference.
+ * Prefer destructuring at the call site so the React linter can track
+ * dependencies on each field independently.
+ *
+ * Actions were the one procedure kind with no hook: `useQuery` and `useMutation`
+ * shipped, so every app that called an action reached for `useLunora()` and
+ * re-derived the same pending/error wrapper by hand. This is that wrapper, once.
+ *
+ * The request state machine is the shared `createCallRunner` from
+ * `@lunora/client` — the same one Vue, Solid and Svelte bind to their own
+ * primitives — so `pending`, error normalization and latest-invocation ordering
+ * behave identically in every adapter. Only the `useState` cells are React's.
+ * TanStack's mutation cache still carries the call so it shows up in Query
+ * Devtools alongside `useQuery`/`useMutation`.
+ *
+ * **Lifecycle contract** (identical across the adapters): `data` and `error`
+ * both track the LATEST invocation, not the last to settle — a double-click
+ * whose first call resolves after the second cannot overwrite the second's
+ * outcome. A success clears `error`; a failure leaves the previous `data` in
+ * place, so a transient error does not blank the view. `reset()` clears both,
+ * but does NOT cancel an in-flight call, whose result still lands.
+ *
+ * **Why the two TanStack defaults are overridden.** `networkMode` is `"always"`
+ * because the default `"online"` pauses the retryer *after* the call is already
+ * marked pending: offline, the promise would never settle, the spinner would
+ * stick, and the action would silently fire minutes later on reconnect. `retry`
+ * is pinned to `0` — not inherited from an app-supplied QueryClient — because
+ * `client.action` sends no idempotency key, so a retry after a 502 on an action
+ * that already ran server-side would run it a second time. `useMutation` pins
+ * both the same way, for a different reason: `client.mutation` queues an
+ * offline write itself, and a paused call would never reach that queue (it
+ * waits for the network itself only when the client cannot queue). An action
+ * has no queue at all, so offline it fails fast.
+ *
+ * **What it deliberately does not carry.** There is no `optimistic` /
+ * `optimisticUpdate` and no `withOptimisticUpdate`, which `useMutation` has. An
+ * optimistic update patches the subscription cache on the assumption the write
+ * will land; an action is not a write — it runs in the Worker, may call a third
+ * party, and has no declared effect on any query. Offering the option would
+ * imply a rollback guarantee nothing can honour.
+ *
+ * ```tsx
+ * const { call: runCommand, pending } = useAction(api.commands.run);
+ *
+ * await runCommand({ command: "lunora", args: ["verify"] });
+ * ```
+ *
+ * Not callable: `const run = useAction(api.x.y); run({ … })` is a `TS2349`.
+ * Destructure the invoker — `const { call: run } = useAction(api.x.y)`.
+ */
+declare const useAction: <F extends FunctionReference>(function_: F) => ActionHook<F>;
+/** The shape every list hook in this file returns. */
+interface AdminAuthListResult<T> {
+  /** Rows loaded so far (the full current window, not just the latest page). `undefined` before the first response. */
+  readonly data: ReadonlyArray<T> | undefined;
+  /** The read error, or `undefined`. */
+  readonly error: Error | undefined;
+  /**
+   * `true` when the server reports more rows exist beyond the current window
+   * (`total > data.length`). `false` before the first response resolves.
+   */
+  readonly hasMore: boolean;
+  /** `true` only before the first response has resolved (matches TanStack's `isLoading`, not `isFetching`). */
+  readonly loading: boolean;
+  /**
+   * Grow the requested window by one page and re-fetch. A no-op while
+   * `hasMore` is `false`. This is a growing-window re-fetch (re-request
+   * `{ limit }` from the top), not a page-accumulator — `AuthPage` is
+   * offset/limit-based, not cursor-based, and there is no live delta stream
+   * to keep page boundaries stable against (unlike
+   * `@lunora/react`'s `usePaginatedQuery`). See the design doc for the
+   * trade-off.
+   */
+  readonly loadMore: () => void;
+  /** Re-run the read — e.g. after a caller performs a mutation via a plain `client.*` call (mirrors Studio's `onDone={refetchOrgs}` pattern). */
+  readonly refetch: () => void;
+  /** `AuthPage.total` — the server-reported row count across the whole collection, not just the current window. `undefined` before the first response. */
+  readonly total: number | undefined;
+}
+/** Options shared by every `useAuthUsers`-style hook. */
+interface AdminAuthQueryOptions {
+  /** Gate the read (rules-of-hooks safe). Defaults to `true`. */
+  enabled?: boolean;
+  /** Page size for the first read; `loadMore` grows the window by this amount. Defaults to 50. */
+  pageSize?: number;
+}
+/** Options for {@link useAuthUsers}. */
+interface UseAuthUsersOptions extends AdminAuthQueryOptions {
+  filterField?: string;
+  filterValue?: string;
+  search?: string;
+  searchField?: string;
+  sortBy?: string;
+  sortDirection?: "asc" | "desc";
+}
+/**
+ * List authenticated users, paged and optionally searched/filtered/sorted.
+ * Hits the admin-gated `GET /_lunora/admin/auth/users` HTTP endpoint via
+ * `client.listAuthUsers` (never the WS/live transport) — the worker must be
+ * built with an `authAdmin` and `adminToken`.
+ *
+ * Mirrors `packages/studio/src/features/auth/users-panel.tsx`'s
+ * `useClientQuery(["lunora-auth-users", …], () => client.listAuthUsers(…))`
+ * read, minus the studio-specific polling (`useAutoRefresh`) — an app using
+ * this hook decides its own refresh cadence by calling `refetch()`.
+ */
+declare const useAuthUsers: (options?: UseAuthUsersOptions) => AdminAuthListResult<AuthUser>;
+/** Options for {@link useOrganizations}. */
+type UseOrganizationsOptions = AdminAuthQueryOptions;
+/**
+ * List organizations (requires the better-auth `organization` plugin).
+ * Hits `client.listAuthOrganizations` — an HTTP-only admin-gated read, same
+ * transport note as {@link useAuthUsers}.
+ *
+ * Mirrors `organizations-panel.tsx`'s
+ * `useClientQuery(["lunora-auth-orgs"], () => client.listAuthOrganizations({ limit: 100 }))`.
+ * Mutations (`client.createAuthOrganization`, `client.deleteAuthOrganization`,
+ * …) stay plain `client.*` calls; call this hook's `refetch()` afterward —
+ * see the design doc's "mutation ergonomics" section for why no hidden
+ * invalidation-on-mutate is wired in.
+ */
+declare const useOrganizations: (options?: UseOrganizationsOptions) => AdminAuthListResult<Record<string, unknown>>;
+/** Options for {@link useSignUpInvitations}. */
+type UseSignUpInvitationsOptions = AdminAuthQueryOptions;
+/**
+ * List sign-up invitations (requires the `inviteOnly` plugin). Hits
+ * `client.listAuthSignUpInvitations` — an HTTP-only admin-gated read, same
+ * transport note as {@link useAuthUsers}.
+ *
+ * Rows come back unfiltered and newest-first; a row is pending when `acceptedAt`
+ * is null and `expiresAt` is in the future. Mutations
+ * (`client.createAuthSignUpInvitation`, `client.revokeAuthSignUpInvitation`)
+ * stay plain `client.*` calls — call `refetch()` afterward, as the other admin
+ * hooks do.
+ */
+declare const useSignUpInvitations: (options?: UseSignUpInvitationsOptions) => AdminAuthListResult<Record<string, unknown>>;
+/** Options for {@link useAuthSessions}. */
+interface UseAuthSessionsOptions extends AdminAuthQueryOptions {
+  /** Scope the list to one user's sessions; omit for the global cross-user browser. */
+  userId?: string;
+}
+/**
+ * List auth sessions, paged and optionally scoped to one user. Hits
+ * `client.listAuthSessions` — HTTP-only, same transport note as
+ * {@link useAuthUsers}.
+ *
+ * Mirrors `auth-sessions-panel.tsx`'s
+ * `useClientQuery(["lunora-auth-sessions", …], () => client.listAuthSessions({ limit }))`.
+ * Revoking a session (`client.revokeAuthSession`/`revokeAuthUserSessions`)
+ * stays a plain `client.*` call followed by this hook's `refetch()`.
+ */
+declare const useAuthSessions: (options?: UseAuthSessionsOptions) => AdminAuthListResult<AuthSession>;
+/** Everything {@link useImpersonate} returns. */
+interface UseImpersonateResult {
+  /** The latest successful impersonation's token + user + expiry, or `undefined`. */
+  readonly data: AuthImpersonation | undefined;
+  /** The latest attempt's error, or `undefined`. */
+  readonly error: Error | undefined;
+  /**
+   * Mint an impersonation session for `userId`, resolving its bearer
+   * `AuthImpersonation`. Deliberately does **not** call
+   * `client.setAuthToken(...)` on the current client — see the security
+   * note below.
+   */
+  readonly impersonate: (userId: string) => Promise<AuthImpersonation>;
+  /** `true` while an impersonation request is in flight. */
+  readonly pending: boolean;
+  /** Clear `data`/`error` back to idle. */
+  readonly reset: () => void;
+}
+/**
+ * Mint an impersonation session via `client.impersonateAuthUser` — the one
+ * genuinely mutation-shaped hook of the four prototyped here (TanStack
+ * `useMutation` underneath, matching `@lunora/react`'s own `useMutation`
+ * ergonomics: `data`/`error`/`pending`/`reset`).
+ *
+ * **Security note (open question — see the design doc):** Studio's
+ * `user-detail-drawer.tsx` (`onImpersonate`) mints the token and displays it
+ * in a read-only text field; it never calls `client.setAuthToken(token)` on
+ * the admin's own client instance. This hook preserves that discipline
+ * deliberately — silently swapping the *current* session would sign the
+ * admin out of their own admin session with no visible transition and no
+ * "return to admin" path. The caller decides what to do with the resolved
+ * `AuthImpersonation` (open a second tab/incognito window authenticated as
+ * the target user, surface it for manual copy, etc.). What the ideal UX is
+ * (a dedicated "Acting as X — Return to admin" banner + explicit swap-back)
+ * is an open product question this spike does not resolve.
+ *
+ * Unlike the three list hooks, impersonating a user has no single paired
+ * list to invalidate (it may affect a sessions list, but not the user/org
+ * list currently being viewed) — mirroring Studio's own `refresh: false` on
+ * this action, this hook does not auto-invalidate anything. A caller that
+ * also renders `useAuthSessions` can call its `refetch()` explicitly.
+ */
+declare const useImpersonate: () => UseImpersonateResult;
+/**
+ * The lifecycle status stored on an agent thread. Client-safe mirror of
+ * `@lunora/agent`'s `AgentThreadStatus` — re-declared here (rather than imported)
+ * so this React entry never pulls in the server-only `@lunora/agent` module
+ * graph (the kit stays React + DOM only). Keep in sync with
+ * `packages/agent/src/types.ts`.
+ */
+type AgentThreadStatus = "awaiting_input" | "cancelled" | "error" | "idle" | "running";
+/**
+ * The live thread record surfaced by the `agents:agentThread` query. A structural
+ * subset of the persisted thread row — every field beyond `status` is optional so
+ * the shape stays forgiving as the server schema grows. Keep in sync with the
+ * `agent_threads` table in `packages/agent/src/component.ts`.
+ */
+interface AgentThreadRecord {
+  createdAt?: number;
+  /**
+   * The failure message when `status === "error"`, `null` once a later run
+   * cleared it, absent on a thread that has never failed. Read it for
+   * truthiness — `null` and absent both mean "no error".
+   */
+  error?: null | string;
+  /** The workflow instance id of the in-flight run — the handle `cancel` targets. */
+  instanceId?: string;
+  messageCount?: number;
+  /** The verified thread owner, when the run was started with one. */
+  owner?: string;
+  status: AgentThreadStatus;
+  title?: string;
+  updatedAt?: number;
+}
+/**
+ * The `agents.agentThread` reference the hook subscribes to for live thread state
+ * (status + the in-flight `instanceId`). A structural subset of the generated
+ * `api.agents` surface, so the whole generated `api` object is assignable.
+ */
+interface UseAgentApi {
+  agents: {
+    agentThread: FunctionReference<"query", {
+      key: string;
+    }, Record<string, unknown> | undefined>;
+  };
+}
+interface UseAgentOptions {
+  /** The generated `api` — its `agents.agentThread` query drives live thread state. */
+  api: UseAgentApi;
+  /**
+   * Optional app mutation over the agent's cancel path
+   * (`ctx.agents.<name>.cancel(id)`). Called with `{ instanceId, threadKey }`.
+   * When omitted (or no run is in flight) {@link UseAgentResult.cancel} is a
+   * no-op.
+   */
+  cancel?: FunctionReference<"mutation">;
+  /**
+   * Called when the live thread subscription reports an error (a session
+   * expiry, an RLS denial). Without it — and without reading `error` — such a
+   * failure is invisible and `thread` / `status` freeze at their last value.
+   */
+  onError?: SubscriptionErrorCallback;
+  /**
+   * The app mutation that starts (or continues) a run — a thin wrapper over
+   * `ctx.agents.<name>.run(...)`. Called with `{ threadKey, input }` merged with
+   * {@link UseAgentOptions.runArgs} and the per-call args.
+   */
+  run: FunctionReference<"mutation">;
+  /** Extra args merged into every `run` call (e.g. an `owner` or `title`). */
+  runArgs?: Record<string, unknown>;
+  /** The thread to observe and drive. */
+  threadKey: string;
+}
+interface UseAgentResult {
+  /**
+   * Terminate the in-flight run and mark its thread `"cancelled"`. Resolves as a
+   * no-op when no `cancel` mutation was supplied or no run is in flight.
+   */
+  cancel: () => Promise<void>;
+  /** The live thread subscription's last error, or `undefined`. */
+  error: Error | undefined;
+  /** `true` while a `run` invocation is in flight. */
+  pending: boolean;
+  /** Start (or continue) a run with a user message; extra args merge over `runArgs`. */
+  run: (input: string, args?: Record<string, unknown>) => Promise<void>;
+  /** The live thread status, or `undefined` before the thread exists. */
+  status: AgentThreadStatus | undefined;
+  /** The live thread record (status, `instanceId`, …), or `undefined` before it exists. */
+  thread: AgentThreadRecord | undefined;
+}
+/**
+ * A thin agent handle: live thread `status` plus `run` / `cancel`, without the
+ * chat message surface. Composes `useSubscription(api.agents.agentThread)` for
+ * live state and `useMutation` for the run/cancel writes. For the full
+ * conversation surface (durable history + streaming + approvals) use
+ * `useAgentChat`.
+ *
+ * `run` and `cancel` stay generic over the app-defined mutations that wrap
+ * `ctx.agents.<name>.run` / `.cancel`, so the hook hard-codes no function names
+ * beyond the `agents:*` surface.
+ */
+declare const useAgent: (options: UseAgentOptions) => UseAgentResult;
+/**
+ * One persisted (or optimistic) thread message, as `agents:agentMessages`
+ * surfaces it. Client-safe mirror of `@lunora/agent`'s `AgentMessageRow` —
+ * re-declared here (rather than imported) so this React entry never pulls in the
+ * server-only `@lunora/agent` module graph. Keep in sync with the `agent_messages`
+ * table in `packages/agent/src/component.ts`.
+ */
+interface AgentChatMessage {
+  content: string;
+  createdAt?: number;
+  /**
+   * `true` for a client-side optimistic user message not yet acknowledged by
+   * the server. Cleared once the durable history carries the matching user turn.
+   */
+  optimistic?: boolean;
+  role: "assistant" | "system" | "tool" | "user";
+  seq: number;
+  /** Approval lifecycle marker on a human-in-the-loop tool message. */
+  status?: "approved" | "awaiting_approval" | "rejected";
+  toolCallId?: string;
+  toolCalls?: ReadonlyArray<{
+    id: string;
+    input: unknown;
+    name: string;
+  }>;
+  toolName?: string;
+}
 /**
-* Token + identity plumbing. The token lives on the shared `LunoraClient`;
-* `setToken(jwt)` after a sign-in makes subsequent RPC calls carry the
-* `Authorization` header. `user` is resolved from better-auth's `get-session`
-* endpoint via `client.getCurrentUser()` — fetched on mount and refetched
-* whenever the token changes (`onAuthTokenChange`), and `null` when signed out.
-*
-* Multiple `useAuth` instances stay in sync: both `token` and `user` are read
-* through `useSyncExternalStore` over the shared client (and a per-client
-* identity store), so a `setToken` from one component re-renders every mounted
-* hook with the freshly-resolved user.
-*/
+ * A live token delta streamed while a turn is generating. Client-safe mirror of
+ * `@lunora/agent`'s `AgentTokenDelta`. Ephemeral — deltas feed
+ * {@link UseAgentChatResult.streamingText} live and are never replayed; the
+ * persisted assistant message stays the single source of truth.
+ */
+interface AgentTokenDelta {
+  /** Discriminates the token arm of {@link AgentLiveEvent}; unset on the wire (token is the default). */
+  kind?: "token";
+  /** The incremental text chunk the model just produced. */
+  text: string;
+  /** The thread this delta belongs to. */
+  threadKey: string;
+  /** The zero-based index of the turn producing the delta. */
+  turn: number;
+}
+/**
+ * A live tool-progress event streamed via `ctx.reportProgress(...)`. Client-safe
+ * mirror of `@lunora/agent`'s `AgentProgressEvent`. Ephemeral and `toolCallId`-keyed;
+ * surfaced by `useAgentToolEvents`, ignored by {@link UseAgentChatResult.streamingText}.
+ */
+interface AgentProgressEvent {
+  /** The arbitrary, JSON-serializable payload the tool reported. */
+  data: unknown;
+  /** Discriminates the progress arm of {@link AgentLiveEvent}. */
+  kind: "progress";
+  /** The thread this event belongs to. */
+  threadKey: string;
+  /** The tool call this progress belongs to. */
+  toolCallId: string;
+}
+/**
+ * A single event on the agent's live-only channel — a streamed token delta or a
+ * tool progress event. Client-safe mirror of `@lunora/agent`'s `AgentLiveEvent`.
+ * Discriminate on `kind` (`"progress"` for the progress arm; token deltas leave
+ * it unset).
+ */
+type AgentLiveEvent = AgentProgressEvent | AgentTokenDelta;
+/** The `agents:agentMessages` reference — live durable thread history. */
+type AgentMessagesReference$1 = FunctionReference<"query", {
+  key: string;
+  limit?: number;
+}, ReadonlyArray<Record<string, unknown>>>;
+/** The `agents:agentResolveApproval` reference — resolves a human-in-the-loop tool approval. */
+type AgentApprovalReference = FunctionReference<"mutation", {
+  decision: "approve" | "reject";
+  instanceId: string;
+  note?: string;
+  threadKey: string;
+  toolCallId: string;
+}, {
+  resolved: boolean;
+}>;
+/** The `agents:agentThread` reference — live thread status + in-flight `instanceId`. */
+type AgentThreadReference = FunctionReference<"query", {
+  key: string;
+}, Record<string, unknown> | undefined>;
+/**
+ * An app stream reference that tees the agent's in-flight live events, keyed by
+ * thread. Carries token deltas and — since `ctx.reportProgress` rides the same
+ * sink — tool progress events; this hook consumes only the token arm.
+ */
+type AgentTokenStreamReference = FunctionReference<"stream", {
+  key: string;
+}, AgentLiveEvent>;
+/**
+ * The `agents.*` reference surface the chat hook reads. A structural subset of
+ * the generated `api.agents`, so the whole generated `api` object is assignable.
+ */
+interface UseAgentChatApi {
+  agents: {
+    agentMessages: AgentMessagesReference$1;
+    agentResolveApproval: AgentApprovalReference;
+    agentThread: AgentThreadReference;
+  };
+}
+interface UseAgentChatOptions {
+  /** The generated `api` — its `agents.*` surface provides history, thread state, and approval resolution. */
+  api: UseAgentChatApi;
+  /**
+   * Optional app mutation over the agent's cancel path
+   * (`ctx.agents.<name>.cancel(id)`). Called with `{ instanceId, threadKey }`.
+   * When omitted (or no run is in flight) {@link UseAgentChatResult.cancel} is a
+   * no-op.
+   */
+  cancel?: FunctionReference<"mutation">;
+  /** History depth forwarded to `agents:agentMessages`. */
+  limit?: number;
+  /**
+   * Called when the live history or thread subscription reports an error (a
+   * session expiry, an RLS denial). Without it — and without reading `error` —
+   * such a failure is invisible and `messages` / `status` freeze at their last
+   * value.
+   */
+  onError?: SubscriptionErrorCallback;
+  /**
+   * The app mutation that starts (or continues) a run — a thin wrapper over
+   * `ctx.agents.<name>.run(...)`. Called with `{ threadKey, input }` merged with
+   * {@link UseAgentChatOptions.sendArgs} and the per-call args.
+   */
+  send: FunctionReference<"mutation">;
+  /** Extra args merged into every `send` call (e.g. an `owner` or `title`). */
+  sendArgs?: Record<string, unknown>;
+  /**
+   * Optional live token-delta stream — an app stream function that tees the
+   * agent's in-flight deltas. When omitted {@link UseAgentChatResult.streamingText}
+   * stays empty and the UI updates message-by-message from durable history.
+   */
+  stream?: AgentTokenStreamReference;
+  /** The thread to observe and continue. */
+  threadKey: string;
+}
+interface UseAgentChatResult {
+  /** Approve a paused human-in-the-loop tool call (optionally with a note). */
+  approve: (toolCallId: string, note?: string) => Promise<void>;
+  /**
+   * Terminate the in-flight run and mark its thread `"cancelled"`. Resolves as a
+   * no-op when no `cancel` mutation was supplied or no run is in flight.
+   */
+  cancel: () => Promise<void>;
+  /** The history or thread subscription's last error, or `undefined`. */
+  error: Error | undefined;
+  /** Durable thread history (oldest first) plus any un-acknowledged optimistic user turns. */
+  messages: ReadonlyArray<AgentChatMessage>;
+  /** Reject a paused human-in-the-loop tool call (optionally with a reason). */
+  reject: (toolCallId: string, note?: string) => Promise<void>;
+  /** Start (or continue) a run with a user message; extra args merge over `sendArgs`. Appends an optimistic user turn. */
+  send: (input: string, args?: Record<string, unknown>) => Promise<void>;
+  /** The live thread status, or `undefined` before the thread exists. */
+  status: AgentThreadStatus | undefined;
+  /** The in-flight turn's streamed text — live-only, empty once the turn persists to `messages`. */
+  streamingText: string;
+}
+/**
+ * A first-class agent chat surface: live durable history + in-flight token
+ * streaming + the send / approve / reject / cancel writes, keyed by `threadKey`.
+ *
+ * It composes the existing primitives rather than adding transport:
+ * `useSubscription(api.agents.agentMessages)` for durable history,
+ * `useSubscription(api.agents.agentThread)` for live status + the in-flight
+ * `instanceId`, {@link useStream} over an app token stream for in-flight deltas,
+ * and `useMutation` for the writes (`api.agents.agentResolveApproval` for
+ * approvals; app-defined wrappers for `send`/`cancel`). Only the `agents:*`
+ * surface is hard-coded — `send`/`cancel`/`stream` stay generic references.
+ *
+ * A `send` optimistically appends the user turn so it renders immediately; the
+ * optimistic row clears once the durable history carries the acknowledged turn.
+ * `streamingText` is live-only: it holds the current turn's streamed text and
+ * empties as soon as that turn's assistant message lands in `messages` (the
+ * persisted message is the source of truth), consistent with the loop's
+ * replay-safe, live-only delta design.
+ */
+declare const useAgentChat: (options: UseAgentChatOptions) => UseAgentChatResult;
+/**
+ * The `agents.agentState` reference the hook subscribes to for the thread's live
+ * synced state. A structural subset of the generated `api.agents` surface (like
+ * `UseAgentApi` for `agentThread`), so the whole generated `api` object is
+ * assignable. Client-safe: no `@lunora/agent` import — the per-agent state type
+ * is mirrored by the hook's generic `T`, since codegen pins the reference return
+ * as an optional record (it never evaluates agent config).
+ */
+interface UseAgentStateApi {
+  agents: {
+    agentState: FunctionReference<"query", {
+      key: string;
+    }, Record<string, unknown> | undefined>;
+  };
+}
+interface UseAgentStateOptions {
+  /** The generated `api` — its `agents.agentState` query drives live thread state. */
+  api: UseAgentStateApi;
+  /** The thread whose synced state to observe. */
+  threadKey: string;
+}
+interface UseAgentStateResult<T> {
+  /** The subscription error, if the live channel reported one. */
+  error: Error | undefined;
+  /** The live synced state, or `undefined` before it is seeded/first pushed. */
+  state: T | undefined;
+}
+/**
+ * Subscribe to an agent thread's synced state — the `setState`-style value a
+ * tool writes with `ctx.setState(...)`, seeded by `defineAgent({ initialState })`.
+ * A thin wrapper over `useSubscription(api.agents.agentState, { key })`: the
+ * server pushes a fresh frame whenever the state changes (the dedicated query's
+ * per-socket JSON memo suppresses no-op pushes on unrelated thread writes), so
+ * `state` updates only on a real `setState`.
+ *
+ * Generic over the app's state shape (`useAgentState` with a `SupportState` type
+ * argument, itself a record) — the reference is typed as an optional record
+ * because codegen cannot see the per-agent state type; the generic casts to `T`.
+ * The `extends` bound (not a bare unbounded type parameter) is required: this
+ * `.ts` file is parsed JSX-aware by the bundler, where an unbounded type-param
+ * arrow is ambiguous with a JSX element.
+ */
+declare const useAgentState: <T extends Record<string, unknown> = Record<string, unknown>>(options: UseAgentStateOptions) => UseAgentStateResult<T>;
+/** The `agents:agentMessages` reference — live durable thread history. */
+type AgentMessagesReference = FunctionReference<"query", {
+  key: string;
+  limit?: number;
+}, ReadonlyArray<Record<string, unknown>>>;
+/**
+ * An app stream reference that tees the agent's in-flight live events, keyed by
+ * thread. Carries token deltas and tool progress events; this hook consumes only
+ * the progress arm (`kind === "progress"`).
+ */
+type AgentLiveStreamReference = FunctionReference<"stream", {
+  key: string;
+}, AgentLiveEvent>;
+/**
+ * The `agents.*` reference surface the tool-events hook reads. A structural
+ * subset of the generated `api.agents`, so the whole generated `api` object is
+ * assignable.
+ */
+interface UseAgentToolEventsApi {
+  agents: {
+    agentMessages: AgentMessagesReference;
+  };
+}
+interface UseAgentToolEventsOptions {
+  /** The generated `api` — its `agents.agentMessages` query provides the durable tool lifecycle. */
+  api: UseAgentToolEventsApi;
+  /** History depth forwarded to `agents:agentMessages`. */
+  limit?: number;
+  /**
+   * Optional live event stream — the same app stream function `useAgentChat`
+   * uses. When supplied, ephemeral `ctx.reportProgress(...)` events for the
+   * thread are surfaced as `{ type: "progress" }` entries; when omitted only the
+   * durable lifecycle (call / result / awaiting-approval) is returned.
+   */
+  stream?: AgentLiveStreamReference;
+  /** The thread whose tool activity to observe. */
+  threadKey: string;
+}
+/**
+ * A single tool-lifecycle event for a thread. The durable arms
+ * (`call`/`result`/`awaiting-approval`) are derived from `agents:agentMessages`
+ * and carry the persisted `seq`; the ephemeral `progress` arm comes live off the
+ * stream and has no `seq`. Discriminate on `type`.
+ */
+type AgentToolEvent = {
+  data: unknown;
+  toolCallId: string;
+  type: "progress";
+} | {
+  input: unknown;
+  seq: number;
+  toolCallId: string;
+  toolName: string;
+  type: "call";
+} | {
+  output: string;
+  seq: number;
+  status?: "approved" | "rejected";
+  toolCallId?: string;
+  toolName?: string;
+  type: "result";
+} | {
+  seq: number;
+  toolCallId?: string;
+  toolName?: string;
+  type: "awaiting-approval";
+};
+interface UseAgentToolEventsResult {
+  /**
+   * The thread's tool events: the durable lifecycle (oldest first, by `seq`)
+   * followed by any in-flight ephemeral progress events. Rebuilt each render
+   * from the live subscription + stream — treat as derived, not identity-stable.
+   */
+  events: ReadonlyArray<AgentToolEvent>;
+}
+/**
+ * A focused view of a thread's tool activity: tool calls, their results,
+ * human-in-the-loop approval pauses, and live `ctx.reportProgress(...)` events —
+ * without the full chat message surface. Composes the existing primitives:
+ * `useSubscription(api.agents.agentMessages)` for the durable lifecycle and
+ * {@link useStream} over the optional app event stream for ephemeral progress.
+ *
+ * Progress events are live-only (the durable path never emits them): they ride
+ * the same sink as token deltas and are surfaced here, correlated to their tool
+ * call by `toolCallId`. For the conversational surface (messages + streaming
+ * text + approvals) use `useAgentChat`; this hook is the tool-observability slice.
+ */
+declare const useAgentToolEvents: (options: UseAgentToolEventsOptions) => UseAgentToolEventsResult;
+/**
+ * Token + identity plumbing. The token lives on the shared `LunoraClient`;
+ * `setToken(jwt)` after a sign-in makes subsequent RPC calls carry the
+ * `Authorization` header. `user` and `status` come from the framework-agnostic
+ * per-client identity store in `@lunora/client/auth` — the same store Vue,
+ * Solid, Svelte and Angular read, so all five agree on what "authenticated"
+ * means rather than each keeping a private copy of the resolve logic.
+ *
+ * `status` is the value to branch on: `user` is `null` both when signed out and
+ * when a held credential's identity endpoint could not be reached. See the
+ * contract documented on `AuthStatus`.
+ *
+ * Multiple `useAuth` instances stay in sync: token, user and status are all read
+ * through `useSyncExternalStore` over the shared client and its identity store,
+ * so a `setToken` from one component re-renders every mounted hook.
+ */
 declare const useAuth: () => UseAuthResult;
+type Setter<T> = (value: T) => void;
+/**
+ * Subscribe to a local-only {@link ClientQueryRef} and re-render when its
+ * value changes. Unlike `useQuery`, this never touches the network — the
+ * value lives in a reactive store on the `LunoraClient` instance and is shared
+ * across every consumer of the same ref.
+ *
+ * The initial render reads the store synchronously (via
+ * `useSyncExternalStore`), so there is never an "undefined flash" — the value
+ * is either the one most recently set or `ref.defaultValue`.
+ *
+ * Returns a `[value, setter]` tuple, matching the `useState` convention.
+ * @example
+ * ```tsx
+ * import { useClientQuery, createClientQuery } from "@lunora/react";
+ *
+ * const sidebarOpen = createClientQuery("sidebarOpen", true);
+ *
+ * function Sidebar() {
+ *   const [open, setOpen] = useClientQuery(sidebarOpen);
+ *   return <aside data-open={open}>…</aside>;
+ * }
+ * ```
+ */
+declare const useClientQuery: <T extends unknown>(ref: ClientQueryRef<T>) => [T, Setter<T>];
 /**
-* Reactive view of the client's aggregate live-socket status across all shard
-* connections. Re-renders on every transition (`idle` → `connecting` →
-* `connected` → `offline`). Use it to drive a connection indicator so an
-* operator can tell a healthy live channel from a silently-dropped socket.
-*/
+ * Reactive view of the client's aggregate live-socket status across all shard
+ * connections. Re-renders on every transition (`idle` → `connecting` →
+ * `connected` → `offline`). Use it to drive a connection indicator so an
+ * operator can tell a healthy live channel from a silently-dropped socket.
+ */
 declare const useConnectionStatus: () => ConnectionStatus;
-/** A targeting context merged on top of the app's default (`defineFlags({ identify })`). */
-type FlagContext = Record<string, unknown>;
 /** The value kinds a flag resolves to — OpenFeature's boolean / number / string / structured (JSON) flags. */
 type FlagValue = boolean | number | string | {
   [key: string]: unknown;
 } | unknown[] | null;
 /**
-* Subscribe to a single feature flag, live over Lunora's WebSocket.
-*
-* Returns `defaultValue` until the first evaluation lands, then the server's
-* resolved value — re-pushed whenever the provider re-evaluates (e.g. a flag is
-* toggled in Cloudflare Flagship). The flag's kind is inferred from
-* `defaultValue`'s runtime type, so `useFlag("dark", false)` reads a boolean and
-* `useFlag("hero", "control")` a string. `context` supplies a per-call targeting
-* context merged on top of the app's default `identify` targeting key.
-*
-* Evaluation runs through whatever OpenFeature provider the app wired in
-* `lunora/flags.ts`; the read never throws — a provider error resolves the
-* default (the same fail-open contract as server-side `ctx.flags`).
-*/
-declare const useFlag: <T extends FlagValue>(key: string, defaultValue: T, context?: FlagContext) => T;
-/**
-* Subscribe to several feature flags at once, live over Lunora's WebSocket.
-*
-* Pass a record of `key → defaultValue`; each flag's kind is inferred from its
-* default, and the result is the same-shaped record with resolved values (the
-* defaults until each evaluation lands). A single `context` applies to every
-* flag. This is the batched form of {@link useFlag} — one effect manages one
-* subscription per key, so it stays rules-of-hooks-safe even as the flag set
-* changes between renders.
-*/
-declare const useFlags: <T extends Record<string, FlagValue>>(flags: T, context?: FlagContext) => T;
+ * Subscribe to a single feature flag, live over Lunora's WebSocket.
+ *
+ * Returns `defaultValue` until the first evaluation lands, then the server's
+ * resolved value — re-pushed whenever the provider re-evaluates (e.g. a flag is
+ * toggled in Cloudflare Flagship). The flag's kind is inferred from
+ * `defaultValue`'s runtime type, so `useFlag("dark", false)` reads a boolean and
+ * `useFlag("hero", "control")` a string.
+ *
+ * The reactive channel is public, so the server evaluates every flag under the
+ * socket's own verified identity — the targeting key your `defineFlags({
+ * identify })` derives — and accepts no client-supplied targeting context. For
+ * evaluation under a context you compute, call `ctx.flags.*` inside a query,
+ * mutation, or action and return the resolved value.
+ *
+ * Evaluation runs through whatever OpenFeature provider the app wired in
+ * `lunora/flags.ts`; the read never throws — a provider error resolves the
+ * default (the same fail-open contract as server-side `ctx.flags`).
+ */
+declare const useFlag: <T extends FlagValue>(key: string, defaultValue: T) => T;
+/**
+ * Subscribe to several feature flags at once, live over Lunora's WebSocket.
+ *
+ * Pass a record of `key → defaultValue`; each flag's kind is inferred from its
+ * default, and the result is the same-shaped record with resolved values (the
+ * defaults until each evaluation lands). This is the batched form of
+ * {@link useFlag} — one effect manages one subscription per key, so it stays
+ * rules-of-hooks-safe even as the flag set changes between renders. Like
+ * {@link useFlag} it evaluates under the socket's server-verified identity only.
+ */
+declare const useFlags: <T extends Record<string, FlagValue>>(flags: T) => T;
+/** The lifecycle of a stream the hook is observing. */
+type UseStreamStatus = "complete" | "error" | "idle" | "streaming";
+/**
+ * Result shape returned by {@link useHttpStream}.
+ */
+interface UseHttpStreamResult<T> {
+  /** Force-cancel the stream (aborts the fetch) and resolve the iterator. Safe to call multiple times. */
+  cancel: () => void;
+  /** Chunks the server has pushed so far, in arrival order. */
+  chunks: ReadonlyArray<T>;
+  error: Error | undefined;
+  status: UseStreamStatus;
+}
+/**
+ * Options accepted by {@link useHttpStream}.
+ */
+interface UseHttpStreamOptions {
+  /** Forwarded to `client.httpStream()` — caps the in-flight chunk buffer. */
+  maxBuffer?: number;
+}
+/**
+ * Consume an **HTTP-SSE route stream** (`httpRoute.<verb>(path).stream()`) via
+ * `client.httpStream`. Distinct from `useStream`, which consumes the WS
+ * procedure stream (`kind: "stream"`). Returns the chunks received so far plus
+ * a lifecycle status and a cancel function. Changing the route or the
+ * serialized `args` resets the stream — the previous fetch is aborted (the
+ * server sees `request.signal`) and a fresh one opens with empty `chunks`.
+ * Unmount also aborts.
+ *
+ * Pass `"skip"` for `args` to keep the hook mounted without opening a stream
+ * (mirrors `useQuery` / `useStream`).
+ */
+declare const useHttpStream: <Ref extends HttpStreamRef>(route: Ref, args: "skip" | HttpStreamArgsOf<Ref>, options?: UseHttpStreamOptions) => UseHttpStreamResult<HttpStreamChunkOf<Ref>>;
 /** The args a paginated query exposes minus the framework-supplied page cursor. */
 type PaginatedArgs<F> = Omit<ArgsOf<F>, "paginationOpts">;
 /** The element type of the `page` array a paginated query returns. */
@@ -272,45 +904,78 @@ type PageItemOf<F> = ReturnOf<F> extends {
   page: (infer T)[];
 } ? T : unknown;
 /**
-* Subscribe to a reactively-paginated query and grow the feed page by page.
-*
-* The query function must accept a `paginationOpts: { numItems, cursor,
-* endCursor }` arg and return a `PaginationResult` (the shape
-* `ctx.db.query(...).paginate` yields). Pages are tracked as an ordered list of
-* stable boundary cursors: each loaded page is a live subscription over a
-* FIXED `(lower, upper]` range whose upper bound is the next page's lower bound.
-* Because boundaries are shared stable cursors, inserting or deleting a row in
-* the middle of the list grows/shrinks the affected page in place without
-* duplicating or skipping rows across page boundaries — the bug the legacy
-* "first N after the previous page's last row" model suffered under live edits.
-*
-* `loadMore` appends the next page off the open-ended tail's `continueCursor`;
-* it is a no-op unless `status === "CanLoadMore"`. Background split/join
-* maintenance keeps page sizes near `initialNumItems` as edits accumulate (see
-* `use-paginated-core.ts`).
-*
-* Changing `fn`, the base `args`, `initialNumItems`, or `shardKey` resets the
-* feed to its first page. The public return shape (`results` / `status` /
-* `loadMore`) is unchanged from the legacy keyset implementation.
-*/
+ * Subscribe to a reactively-paginated query and grow the feed page by page.
+ *
+ * Pass `onError` (and read `error`) to see a page failure: without it the hook
+ * only reports `status`, and a first page that fails reads as an eternal
+ * `isLoading`.
+ *
+ * The query function must accept a `paginationOpts: { numItems, cursor,
+ * endCursor }` arg and return a `PaginationResult` (the shape
+ * `ctx.db.query(...).paginate` yields). Pages are tracked as an ordered list of
+ * stable boundary cursors: each loaded page is a live subscription over a
+ * FIXED `(lower, upper]` range whose upper bound is the next page's lower bound.
+ * Because boundaries are shared stable cursors, inserting or deleting a row in
+ * the middle of the list grows/shrinks the affected page in place without
+ * duplicating or skipping rows across page boundaries — the bug the legacy
+ * "first N after the previous page's last row" model suffered under live edits.
+ *
+ * `loadMore` appends the next page off the open-ended tail's `continueCursor`;
+ * it is a no-op unless `status === "CanLoadMore"`. Background split/join
+ * maintenance keeps page sizes near `initialNumItems` as edits accumulate (see
+ * `use-paginated-core.ts`).
+ *
+ * Changing `fn`, the base `args`, `initialNumItems`, or `shardKey` resets the
+ * feed to its first page. The public return shape (`results` / `status` /
+ * `loadMore`) is unchanged from the legacy keyset implementation.
+ *
+ * There is no total-row count here, and deliberately not: `paginate()` never
+ * counts the tail, which is what keeps a page O(page) rather than O(table). For
+ * a "42 of 1,203" label, subscribe to a `ctx.db.<table>.count(where)` query with
+ * the same filter args via `useQuery` — it is live, so it moves with the
+ * list. See the pagination concept page.
+ */
 declare const usePaginatedQuery: <F extends FunctionReference>(function_: F, args: "skip" | PaginatedArgs<F>, options: UsePaginatedQueryOptions) => UsePaginatedQueryResult<PageItemOf<F>>;
 /**
-* Subscribe to a reactively-paginated query and expose its pages discretely.
-*
-* Shares `usePaginatedQuery`'s reactive-pagination engine — pages are fixed
-* `(lower, upper]` cursor ranges with shared stable boundaries, so a row
-* inserted or deleted mid-list grows/shrinks the affected page without
-* duplicating or skipping rows across boundaries — but keeps each page as its
-* own inner array rather than flattening them, and adds the
-* TanStack-Query-style `fetchNextPage` / `hasNextPage` / `isFetchingNextPage`
-* shape. `fetchNextPage` appends the next page off the open-ended tail's
-* `continueCursor`; it is a no-op unless `status === "CanLoadMore"`.
-*
-* Changing `fn`, the base `args`, `initialNumItems`, or `shardKey` resets the
-* feed to its first page. The public return shape is unchanged from the legacy
-* keyset implementation.
-*/
+ * Subscribe to a reactively-paginated query and expose its pages discretely.
+ *
+ * Shares `usePaginatedQuery`'s reactive-pagination engine — pages are fixed
+ * `(lower, upper]` cursor ranges with shared stable boundaries, so a row
+ * inserted or deleted mid-list grows/shrinks the affected page without
+ * duplicating or skipping rows across boundaries — but keeps each page as its
+ * own inner array rather than flattening them, and adds the
+ * TanStack-Query-style `fetchNextPage` / `hasNextPage` / `isFetchingNextPage`
+ * shape. `fetchNextPage` appends the next page off the open-ended tail's
+ * `continueCursor`; it is a no-op unless `status === "CanLoadMore"`.
+ *
+ * Changing `fn`, the base `args`, `initialNumItems`, or `shardKey` resets the
+ * feed to its first page. The public return shape is unchanged from the legacy
+ * keyset implementation.
+ */
 declare const useInfiniteQuery: <F extends FunctionReference>(function_: F, args: "skip" | PaginatedArgs<F>, options: UseInfiniteQueryOptions) => UseInfiniteQueryResult<PageItemOf<F>>;
+/** Options for {@link useLiveTopic}: the `subscribeLiveTopic` options, with the callbacks read through a ref. */
+type UseLiveTopicOptions = SubscribeLiveTopicOptions;
+interface UseLiveTopicResult {
+  /** Set when the shard refuses the subscription (403, 409, 429 and similar). */
+  error: LiveStreamSubscribeError | undefined;
+  /** The last payload delivered on the topic, or `undefined` until the first event. */
+  lastEvent: unknown;
+}
+/**
+ * `useLiveTopic` — follow one live topic of a `defineLiveStream` for the life of
+ * the component.
+ *
+ * It is a lifecycle wrapper over `subscribeLiveTopic`: the connection itself is
+ * shared by URL, so mounting this hook ten times still opens one stream. It
+ * subscribes on mount, unsubscribes on unmount, and resubscribes only when the
+ * connection inputs (`url`, `topic`, credentials, headers, retry tuning) change.
+ * Changing `onEvent` or `onError` identity does not resubscribe — the latest
+ * callback is read through a ref.
+ *
+ * It is a no-op during SSR: effects do not run on the server, so the hook returns
+ * its initial values there.
+ */
+declare const useLiveTopic: (options: UseLiveTopicOptions) => UseLiveTopicResult;
 type CallOptions<F extends FunctionReference> = UseMutationCallOptions<unknown, unknown, ArgsOf<F>>;
 interface MutationHook<F extends FunctionReference> {
   /** The latest invocation's resolved value, or `undefined` before the first success. */
@@ -325,34 +990,43 @@ interface MutationHook<F extends FunctionReference> {
   /** Clear the latest `data`/`error` back to idle. */
   reset: () => void;
   /**
-  * Bind a Convex-parity multi-query optimistic update to this mutation.
-  * Returns a `{ mutate, pending, … }` whose `mutate` forwards `update` as the
-  * `optimisticUpdate` for every call — unless a per-call `optimisticUpdate`
-  * is supplied in the call options, which overrides the bound one.
-  */
+   * Bind a Convex-parity multi-query optimistic update to this mutation.
+   * Returns a `{ mutate, pending, … }` whose `mutate` forwards `update` as the
+   * `optimisticUpdate` for every call — unless a per-call `optimisticUpdate`
+   * is supplied in the call options, which overrides the bound one.
+   */
   withOptimisticUpdate: (update: OptimisticUpdate<ArgsOf<F>>) => MutationHook<F>;
 }
 /**
-* Returns `{ mutate, pending, data, error, reset, withOptimisticUpdate }` for the
-* given mutation reference. Prefer destructuring at the call site so the React
-* linter can track dependencies on each field independently.
-*
-* Built on TanStack Query's mutation cache (the same cache the query hooks use),
-* so it composes with Query Devtools and exposes the latest call's `data`/`error`
-* plus `reset()`. `mutate` maps to `mutateAsync`, so it stays an awaitable that
-* rejects on failure (rather than TanStack's fire-and-forget `mutate`).
-*
-* `pending` is ref-counted across overlapping invocations of THIS hook instance
-* (driven by the mutation's `onMutate`/`onSettled` lifecycle), so it flips back to
-* `false` only once every concurrent call has settled — and a sibling component
-* mutating the same function never affects it (TanStack's own `isPending` tracks
-* just the latest invocation).
-*
-* Optimistic updates stay client-owned: the `optimistic` / `optimisticUpdate`
-* call options pass straight through to `client.mutation`, which applies and
-* rolls them back against the Lunora subscription cache (Convex parity) — not
-* through TanStack's `onMutate`.
-*/
+ * Returns `{ mutate, pending, data, error, reset, withOptimisticUpdate }` for the
+ * given mutation reference. Prefer destructuring at the call site so the React
+ * linter can track dependencies on each field independently.
+ *
+ * Not callable: `const send = useMutation(api.x.y); send({ … })` is a `TS2349`.
+ * Destructure the invoker — `const { mutate: send } = useMutation(api.x.y)`.
+ *
+ * Built on TanStack Query's mutation cache (the same cache the query hooks use),
+ * so it composes with Query Devtools and exposes the latest call's `data`/`error`
+ * plus `reset()`. `mutate` maps to `mutateAsync`, so it stays an awaitable that
+ * rejects on failure (rather than TanStack's fire-and-forget `mutate`).
+ *
+ * `pending` is ref-counted across overlapping invocations of THIS hook instance
+ * (driven by the mutation's `onMutate`/`onSettled` lifecycle), so it flips back to
+ * `false` only once every concurrent call has settled — and a sibling component
+ * mutating the same function never affects it (TanStack's own `isPending` tracks
+ * just the latest invocation).
+ *
+ * Optimistic updates stay client-owned: the `optimistic` / `optimisticUpdate`
+ * call options pass straight through to `client.mutation`, which applies and
+ * rolls them back against the Lunora subscription cache (Convex parity) — not
+ * through TanStack's `onMutate`.
+ *
+ * Offline, a write the client can queue reaches `client.mutation` at once,
+ * which queues it (the offline queue or a durable outbox) and paints the
+ * optimistic update. A write it cannot queue (before the shard's first connect,
+ * or with no WebSocket) waits until the browser is online again, then sends.
+ * TanStack never retries; the queue owns replays.
+ */
 declare const useMutation: <F extends FunctionReference>(function_: F) => MutationHook<F>;
 interface MutatorHook<TArgs> {
   /** The latest invocation's error, or `undefined`. */
@@ -367,86 +1041,104 @@ interface MutatorHook<TArgs> {
   reset: () => void;
 }
 /**
-* Ergonomic `{ mutate, pending, error, isError, reset }` wrapper over a bound
-* custom-mutator handle from `@lunora/db`'s `bindMutators`. The optimistic
-* overlay and server-authoritative push are owned by the bound handle (and
-* TanStack DB's optimistic-transaction layer rebases pending overlays on every
-* sync tick) — this hook only surfaces React state for the in-flight/error
-* lifecycle. Reads stay on the existing `useLiveQuery`; no new query hook is
-* needed.
-*
-* `pending` is ref-counted across overlapping invocations of THIS hook instance,
-* so it clears only once every concurrent call has settled.
-*/
+ * Ergonomic `{ mutate, pending, error, isError, reset }` wrapper over a bound
+ * custom-mutator handle from `@lunora/db`'s `bindMutators`. The optimistic
+ * overlay and server-authoritative push are owned by the bound handle (and
+ * TanStack DB's optimistic-transaction layer rebases pending overlays on every
+ * sync tick) — this hook only surfaces React state for the in-flight/error
+ * lifecycle. Reads stay on the existing `useLiveQuery`; no new query hook is
+ * needed.
+ *
+ * `pending` is ref-counted across overlapping invocations of THIS hook instance,
+ * so it clears only once every concurrent call has settled.
+ */
 declare const useMutator: <TArgs = Record<string, unknown>>(handle: MutatorHandle<TArgs>) => MutatorHook<TArgs>;
 /**
-* Hydrate a query from a {@link Preloaded} token produced by `preloadQuery`
-* during SSR, then keep it live.
-*
-* The first render returns the preloaded value (TanStack's `initialData`),
-* so the server markup and the initial client markup match — no hydration
-* mismatch, no loading flash. After mount, a WS subscription attaches so
-* later server pushes update the value just like `useQuery`.
-*
-* The {@link Preloaded} token's `value` seeds `initialData`; we don't need a
-* full dehydrate/hydrate dance because the consumer hands us the resolved
-* value directly. Apps that want to share a pre-populated QueryClient across
-* many preloaded queries can pass their own `queryClient` to `LunoraProvider`
-* and hydrate it themselves via TanStack's `hydrate(qc, dehydratedState)`.
-*/
-declare const usePreloadedQuery: <T>(preloaded: Preloaded<T>) => T;
-/**
-* The PLAN4 §1 framework-neutral name for the preloaded-hydration handoff:
-* `hydratePreloaded(preloaded)` seeds the SSR value on the first paint, then
-* attaches a live WS subscription on mount. It is a thin alias of
-* {@link usePreloadedQuery} so the React adapter exposes the same
-* `hydratePreloaded` primitive every other adapter (Solid, Svelte, Vue) will,
-* while existing callers of `usePreloadedQuery` keep working unchanged.
-*
-* It carries React's Rules-of-Hooks contract (it calls hooks internally), so
-* call it like a hook — at the top level of a component, unconditionally.
-*/
-declare const hydratePreloaded: <T>(preloaded: Preloaded<T>) => T;
-/**
-* `usePresence` — collaborative-awareness hook, the client half of the
-* `@lunora/server` `definePresence` preset (Convex `@convex-dev/presence`
-* parity).
-*
-* It drives the two presence functions the server component ships:
-*
-* - **heartbeat** (a mutation): called on mount, on a fixed interval, and again
-* whenever the tab becomes visible, to upsert the caller's presence row and
-* refresh its `lastSeen`. On unmount the interval is cleared. Each heartbeat
-* carries the latest `data` from a ref, so `setData` takes effect on the next
-* tick without re-subscribing or resetting the timer.
-* - **listPresent** (a query): subscribed to over the live-query WS, so the
-* present-list updates reactively. Because the server patches a single row per
-* heartbeat, the client's **per-row subscription delta merge** applies just that
-* row to the cached list instead of re-sending every member — the list stays
-* cheap even with many participants heart-beating.
-*
-* `sessionId` defaults to a stable per-mount id (one row per tab); pass your own
-* to dedupe across tabs by user. TTL/expiry is server-side: a member that stops
-* heart-beating drops out of `listPresent` once `lastSeen` ages past the TTL, so
-* the hook needs no client-side reaping.
-*
-* The two `FunctionReference`s come from your generated `api` (e.g.
-* `api.presence.heartbeat` / `api.presence.listPresent`) — passed in so the hook
-* stays decoupled from any specific app schema.
-*/
-/**
-* A heartbeat mutation reference: takes `{ roomId, sessionId, data? }` (the shape
-* `definePresence().functions.heartbeat` registers).
-*/
+ * Hydrate a query from a {@link Preloaded} token produced by `preloadQuery`
+ * during SSR, then keep it live.
+ *
+ * The first render returns the preloaded value (TanStack's `initialData`),
+ * so the server markup and the initial client markup match — no hydration
+ * mismatch, no loading flash. After mount, a WS subscription attaches so
+ * later server pushes update the value just like `useQuery`.
+ *
+ * The {@link Preloaded} token's `value` seeds `initialData`; we don't need a
+ * full dehydrate/hydrate dance because the consumer hands us the resolved
+ * value directly. Apps that want to share a pre-populated QueryClient across
+ * many preloaded queries can pass their own `queryClient` to `LunoraProvider`
+ * and hydrate it themselves via TanStack's `hydrate(qc, dehydratedState)`.
+ *
+ * Pass `onError` to surface a subscription-scoped error the server pushes (a
+ * session expiry, an RLS denial). Without it such an error is dropped and the
+ * hook keeps rendering the SSR snapshot as if it were live.
+ *
+ * The preloaded value was read for whoever was signed in when the page loaded.
+ * After a sign-out or user switch retires an identity (`client.identityEpoch()`
+ * above `0`), every `usePreloadedQuery` on the client (mounted then or later)
+ * stops using it and returns `undefined` until the live value arrives. So does
+ * every one under a `LunoraProvider` whose `client` was swapped, mounted before
+ * or after the swap — hence the `T | undefined` return type. A token
+ * preloaded after the switch (a client-side navigation that preloads again) is
+ * ignored too and costs a loading flash: the hook cannot tell which identity a
+ * token was read under.
+ */
+declare const usePreloadedQuery: <T>(preloaded: Preloaded<T>, options?: {
+  onError?: SubscriptionErrorCallback;
+}) => T | undefined;
+/**
+ * The PLAN4 §1 framework-neutral name for the preloaded-hydration handoff:
+ * `hydratePreloaded(preloaded)` seeds the SSR value on the first paint, then
+ * attaches a live WS subscription on mount. It is a thin alias of
+ * {@link usePreloadedQuery} so the React adapter exposes the same
+ * `hydratePreloaded` primitive every other adapter (Solid, Svelte, Vue) will,
+ * while existing callers of `usePreloadedQuery` keep working unchanged.
+ *
+ * It carries React's Rules-of-Hooks contract (it calls hooks internally), so
+ * call it like a hook — at the top level of a component, unconditionally.
+ */
+declare const hydratePreloaded: <T>(preloaded: Preloaded<T>, options?: {
+  onError?: SubscriptionErrorCallback;
+}) => T | undefined;
+/**
+ * `usePresence` — collaborative-awareness hook, the client half of the
+ * `@lunora/server` `definePresence` preset (Convex `@convex-dev/presence`
+ * parity).
+ *
+ * It drives the two presence functions the server component ships:
+ *
+ * - **heartbeat** (a mutation): called on mount, on a fixed interval, and again
+ * whenever the tab becomes visible, to upsert the caller's presence row and
+ * refresh its `lastSeen`. On unmount the interval is cleared. Each heartbeat
+ * carries the latest `data` from a ref, so `setData` takes effect on the next
+ * tick without re-subscribing or resetting the timer.
+ * - **listPresent** (a query): subscribed to over the live-query WS, so the
+ * present-list updates reactively. Because the server patches a single row per
+ * heartbeat, the client's **per-row subscription delta merge** applies just that
+ * row to the cached list instead of re-sending every member — the list stays
+ * cheap even with many participants heart-beating.
+ *
+ * `sessionId` defaults to a stable per-mount id (one row per tab); pass your own
+ * to dedupe across tabs by user. TTL/expiry is server-side: a member that stops
+ * heart-beating drops out of `listPresent` once `lastSeen` ages past the TTL, so
+ * the hook needs no client-side reaping.
+ *
+ * The two `FunctionReference`s come from your generated `api` (e.g.
+ * `api.presence.heartbeat` / `api.presence.listPresent`) — passed in so the hook
+ * stays decoupled from any specific app schema.
+ */
+/**
+ * A heartbeat mutation reference: takes `{ roomId, sessionId, data? }` (the shape
+ * `definePresence().functions.heartbeat` registers).
+ */
 type HeartbeatReference = FunctionReference<"mutation", {
   data?: Record<string, unknown>;
   roomId: string;
   sessionId: string;
 }>;
 /**
-* A listPresent query reference: takes `{ roomId }` and returns the array of
-* present members.
-*/
+ * A listPresent query reference: takes `{ roomId }` and returns the array of
+ * present members.
+ */
 type ListPresentReference = FunctionReference<"query", {
   roomId: string;
 }>;
@@ -460,14 +1152,22 @@ interface UsePresenceOptions<H extends HeartbeatReference, L extends ListPresent
   /** The `api.*` reference for the presence listPresent query. */
   listPresent: L;
   /**
-  * Stable id for this presence row. Defaults to a fresh per-mount id (one row
-  * per tab). Pass a user/connection id to control deduping.
-  */
+   * Called when the `listPresent` subscription reports an error (a session
+   * expiry, an RLS denial). Without it — and without reading `error` — such a
+   * failure is invisible and `present` freezes at its last value.
+   */
+  onError?: SubscriptionErrorCallback;
+  /**
+   * Stable id for this presence row. Defaults to a fresh per-mount id (one row
+   * per tab). Pass a user/connection id to control deduping.
+   */
   sessionId?: string;
   /** Forwarded to the heartbeat mutation / listPresent subscription when sharding by room. */
   shardKey?: string;
 }
 interface UsePresenceResult<L extends ListPresentReference> {
+  /** The `listPresent` subscription's last error, or `undefined`. */
+  error: SubscriptionError | undefined;
   /** The present members for the room, as `listPresent` returns them. `undefined` until the first push. */
   present: ReturnOf<L> | undefined;
   /** This mount's session id (generated when not supplied). */
@@ -477,25 +1177,36 @@ interface UsePresenceResult<L extends ListPresentReference> {
 }
 declare const usePresence: <H extends HeartbeatReference, L extends ListPresentReference>(roomId: string, options: UsePresenceOptions<H, L>) => UsePresenceResult<L>;
 /**
-* Subscribe to a server query.
-*
-* Returns `undefined` until the first response lands. Pass `"skip"` for
-* `args` to short-circuit the query (no network call, no subscription).
-*
-* Internally this routes through TanStack Query: the queryKey is
-* `["lunora", fn.__lunoraRef, args, shardKey]` (TanStack hashes structurally
-* so an args object built in a different key order still dedupes). The
-* subscription registry shares a single WS subscription across every consumer
-* of the same queryKey; pushes call `queryClient.setQueryData(...)`.
-*/
+ * Subscribe to a server query.
+ *
+ * Returns `undefined` until the first response lands. Pass `"skip"` for
+ * `args` to short-circuit the query (no network call, no subscription).
+ *
+ * When the `LunoraClient` was created with `hydrateOnStart: true` and a
+ * `queryCache` adapter, the first **enabled** render waits for the durable
+ * read cache to finish loading. If a cached value exists for this query it
+ * is fed as `initialData` so the user sees it immediately — no undefined
+ * flash before the socket round-trip.
+ *
+ * Internally this routes through TanStack Query: the queryKey is
+ * `["lunora", fn.__lunoraRef, stableWireKey(args), shardKey]` (the args are
+ * encoded key-order-independently, so an args object built in a different key
+ * order still dedupes, and wire-typed args get distinct entries). The
+ * subscription registry shares a single WS subscription across every consumer
+ * of the same queryKey; pushes call `queryClient.setQueryData(...)`.
+ *
+ * Pass `onError` to surface a subscription-scoped error the server pushes (an RLS
+ * denial, a query that starts failing server-side). Without it such an error is
+ * dropped and the returned value just freezes at its last good result.
+ */
 declare const useQuery: <F extends FunctionReference>(function_: F, args: ArgsOf<F> | "skip", options?: UseQueryOptions) => ReturnOf<F> | undefined;
 interface UseRateLimitOptions {
   /** Clock injection for tests. Defaults to `Date.now`. */
   now?: () => number;
   /**
-  * Re-render cadence in milliseconds while throttled, so `retryAfter` ticks
-  * down and `disabled` flips back automatically. Defaults to `1000`.
-  */
+   * Re-render cadence in milliseconds while throttled, so `retryAfter` ticks
+   * down and `disabled` flips back automatically. Defaults to `1000`.
+   */
   tickMs?: number;
 }
 interface UseRateLimitResult {
@@ -513,17 +1224,15 @@ interface UseRateLimitResult {
   retryAfter: number;
 }
 /**
-* Client-side mirror of a rate limit for instant UX — disable a button or show
-* a countdown without a round-trip. It runs the same token-bucket / fixed-window
-* math as `@lunora/ratelimit` on the server, so the prediction agrees with the
-* authoritative check; the server remains the source of truth.
-*
-* `config` is read on every render; pass a stable reference (module constant or
-* `useMemo`) so the `consume`/`check` callbacks keep a steady identity.
-*/
+ * Client-side mirror of a rate limit for instant UX — disable a button or show
+ * a countdown without a round-trip. It runs the same token-bucket / fixed-window
+ * math as `@lunora/ratelimit` on the server, so the prediction agrees with the
+ * authoritative check; the server remains the source of truth.
+ *
+ * `config` is read on every render; pass a stable reference (module constant or
+ * `useMemo`) so the `consume`/`check` callbacks keep a steady identity.
+ */
 declare const useRateLimit: (config: RateLimitConfig, options?: UseRateLimitOptions) => UseRateLimitResult;
-/** The lifecycle of a stream the hook is observing. */
-type UseStreamStatus = "complete" | "error" | "idle" | "streaming";
 interface UseStreamResult<T> {
   /** Force-cancel the stream and resolve the iterator. Safe to call multiple times. */
   cancel: () => void;
@@ -533,24 +1242,198 @@ interface UseStreamResult<T> {
   status: UseStreamStatus;
 }
 interface UseStreamOptions {
+  /**
+   * Opt into resume-on-reconnect for a stream the server declared `durable`.
+   * The hook keeps the chunks it already has and the socket re-attaches to the
+   * same run, so a dropped connection mid-generation continues instead of
+   * surfacing `STREAM_DISCONNECTED`. Has no effect on an ephemeral stream.
+   */
+  durable?: boolean;
   /** Forwarded to `client.stream()` — caps the in-flight chunk buffer. */
   maxBuffer?: number;
   shardKey?: string;
 }
 /**
-* Subscribe to a streaming query. Returns the chunks pushed so far plus a
-* lifecycle status and a cancel function. Changing `fn` or the serialized
-* `args` resets the stream — the previous iterator is cancelled and a fresh
-* one opens with empty `chunks`.
-*
-* Pass `"skip"` for `args` to keep the hook mounted without opening a stream
-* (mirrors `useQuery` / `useSubscription`).
-*/
+ * Subscribe to a streaming query. Returns the chunks pushed so far plus a
+ * lifecycle status and a cancel function. Changing `fn` or the serialized
+ * `args` resets the stream — the previous iterator is cancelled and a fresh
+ * one opens with empty `chunks`.
+ *
+ * Pass `"skip"` for `args` to keep the hook mounted without opening a stream
+ * (mirrors `useQuery` / `useSubscription`).
+ */
 declare const useStream: <F extends FunctionReference<"stream">>(function_: F, args: "skip" | ArgsOf<F>, options?: UseStreamOptions) => UseStreamResult<ReturnOf<F>>;
 /**
-* Subscribe to a real-time stream from the server. Unlike `useQuery`, this
-* hook does not issue an initial HTTP fetch — it only delivers values that
-* the server pushes over the WS.
-*/
+ * Subscribe to a real-time stream from the server. Unlike `useQuery`, this
+ * hook does not issue an initial HTTP fetch — it only delivers values that
+ * the server pushes over the WS.
+ *
+ * A server-pushed error lands on `error` as a `LunoraError` carrying the
+ * server's `code` (a bare `Error` only when the server sent no code), so
+ * consumers can branch on the error kind; `onError` receives the raw
+ * `SubscriptionError` in addition.
+ */
 declare const useSubscription: <F extends FunctionReference>(function_: F, args: ArgsOf<F> | "skip", options?: UseQueryOptions) => UseSubscriptionResult<ReturnOf<F>>;
-export { AuthLoading, type AuthState, Authenticated, CheckoutButton, type CheckoutButtonProps, CustomerPortalButton, type CustomerPortalButtonProps, type FlagContext, type FlagValue, type HeartbeatReference, type ListPresentReference, LunoraProvider, type LunoraProviderProps, type MutationHook, type MutatorHook, type PageItemOf, type PaginatedArgs, type RedirectTarget, type RedirectTrigger, type Subscription, Unauthenticated, type UseAuthResult, type UseCheckoutResult, type UseInfiniteQueryOptions, type UseInfiniteQueryResult, type UseMutationCallOptions, type UsePaginatedQueryOptions, type UsePaginatedQueryResult, type UsePresenceOptions, type UsePresenceResult, type UseQueryOptions, type UseRateLimitOptions, type UseRateLimitResult, type UseStreamOptions, type UseStreamResult, type UseStreamStatus, type UseSubscriptionResult, hydratePreloaded, useAuth, useAuthState, useCheckout, useConnectionStatus, useFlag, useFlags, useInfiniteQuery, useLunora, useMutation, useMutator, usePaginatedQuery, usePreloadedQuery, usePresence, useQuery, useRateLimit, useStream, useSubscription };
+/**
+ * Browser Web Audio subsystems for `useVoiceAgent` — the default microphone
+ * capture and speaker playback implementations injected into the hook via its
+ * `createMicrophone` / `createSpeaker` seams. Kept in a sibling module so the
+ * heavy Web Audio graph (and its structural DOM typings) stays isolated from the
+ * hook's transport + React-state logic and remains mockable in a non-browser
+ * test env.
+ */
+/**
+ * The negotiated audio format the voice DO streams back. Mirrors
+ * `@lunora/agent`'s `VoiceServerFrame` `ready.audioFormat` — re-declared (not
+ * imported) so this React package never pulls in the server-only `@lunora/agent`
+ * module graph.
+ */
+type VoiceAudioFormat = "mp3" | "wav";
+/** Captures microphone audio and reports level / turn boundaries back to the hook. */
+interface VoiceMicrophone {
+  /** Mute/unmute the mic without tearing down the capture graph. */
+  setMuted: (muted: boolean) => void;
+  /** Stop capture and release the media stream + audio graph. */
+  stop: () => void;
+}
+/** Plays the server's streamed audio chunks and supports a mid-utterance barge-in. */
+interface VoiceSpeaker {
+  /** Queue a decoded audio chunk for gap-minimized playback. */
+  enqueue: (audio: Uint8Array) => void;
+  /** Drop everything queued and stop the current chunk (barge-in). */
+  interrupt: () => void;
+  /** Release the playback audio context. */
+  stop: () => void;
+}
+/** Config passed to a {@link CreateMicrophone} factory. */
+interface MicrophoneConfig {
+  /** The consecutive above-threshold chunk count that counts as a barge-in. */
+  interruptChunks: number;
+  /** RMS above which the user is considered to be barging in while the agent speaks. */
+  interruptThreshold: number;
+  /**
+   * `true` from the moment a turn is committed until it completes — the whole
+   * `thinking` + `speaking` window, not just the audible half.
+   *
+   * It gates BOTH branches below, and the wider span is the point. Gated only
+   * on "audibly speaking", turn detection kept running through the entire
+   * STT+LLM window after a `commit`: room noise at the (deliberately low)
+   * `silenceThreshold` re-armed `sawSpeech`, another quiet gap fired a SECOND
+   * `commit`, and the DO refused it with "a turn is already in progress" —
+   * a refusal that returns before draining the audio buffer, so the PCM
+   * captured since the first commit leaked into the next utterance.
+   *
+   * A genuine barge-in still works in that window: it routes through the
+   * `onInterrupt` branch, which needs `interruptChunks` consecutive chunks at
+   * `interruptThreshold` — an order of magnitude above `silenceThreshold` —
+   * and `interrupt` is exactly what the DO tells the client to send.
+   */
+  isTurnActive: () => boolean;
+  /** One 16 kHz mono 16-bit little-endian PCM frame captured from the mic. */
+  onAudio: (pcm: Uint8Array) => void;
+  /** A barge-in was detected (RMS spike while the agent is speaking). */
+  onInterrupt: () => void;
+  /** The current input RMS (0–1), for a level meter. */
+  onLevel: (rms: number) => void;
+  /** A spoken utterance ended (speech followed by `silenceDurationMs` of silence). */
+  onSilence: () => void;
+  /** Milliseconds of sub-threshold audio (after speech) that closes an utterance. */
+  silenceDurationMs: number;
+  /** RMS below which audio counts as silence. */
+  silenceThreshold: number;
+}
+type CreateMicrophone = (config: MicrophoneConfig) => Promise<VoiceMicrophone>;
+type CreateSpeaker = (config: {
+  audioFormat: VoiceAudioFormat;
+}) => VoiceSpeaker;
+/**
+ * The `agents.<name>Voice` reference codegen emits for a voice-enabled agent — a
+ * live, WS-backed session keyed by `threadKey`. A structural subset of the
+ * generated member, so passing `api.agents.<name>Voice` type-checks.
+ */
+type VoiceReference = FunctionReference<"stream", {
+  threadKey: string;
+}, Record<string, unknown>>;
+/** The lifecycle of a voice call, mirrored to the UI. */
+type VoiceStatus = "idle" | "listening" | "speaking" | "thinking";
+/** A minimal structural subset of the DOM `WebSocket` the hook drives. */
+interface VoiceSocket {
+  binaryType: string;
+  close: () => void;
+  onclose: ((event: unknown) => void) | null;
+  onerror: ((event: unknown) => void) | null;
+  onmessage: ((event: {
+    data: unknown;
+  }) => void) | null;
+  onopen: ((event: unknown) => void) | null;
+  readonly readyState: number;
+  send: (data: ArrayBufferView | ArrayBufferLike | string) => void;
+}
+type CreateSocket = (url: string) => VoiceSocket;
+interface UseVoiceAgentOptions {
+  /**
+   * Advanced/test seam: build the microphone capture subsystem. Defaults to a
+   * `getUserMedia` + Web Audio implementation. Injected wholesale so the Web
+   * Audio graph stays isolated (and mockable in a non-browser test env).
+   */
+  createMicrophone?: CreateMicrophone;
+  /**
+   * Advanced/test seam: open the transport. Defaults to the WebSocket
+   * implementation the client was built with (`client.getWebSocketImpl()`),
+   * NOT a raw `globalThis.WebSocket`.
+   */
+  createSocket?: CreateSocket;
+  /** Advanced/test seam: build the audio playback subsystem. Defaults to a Web Audio implementation. */
+  createSpeaker?: CreateSpeaker;
+  /** Consecutive above-`interruptThreshold` chunks that trigger a barge-in. Default `3`. */
+  interruptChunks?: number;
+  /** Input RMS above which the user is treated as barging in while the agent speaks. Default `0.15`. */
+  interruptThreshold?: number;
+  /** Milliseconds of silence (after speech) that auto-commits an utterance. Default `1200`. */
+  silenceDurationMs?: number;
+  /** Input RMS below which audio counts as silence. Default `0.01`. */
+  silenceThreshold?: number;
+  /** The thread to converse on — shared with the agent's text turns. */
+  threadKey: string;
+  /** The generated `api.agents.<name>Voice` reference — identifies the voice DO endpoint. */
+  voice: VoiceReference;
+}
+interface UseVoiceAgentResult {
+  /** The current input RMS (0–1) — drive a mic level meter. */
+  audioLevel: number;
+  /** `true` once the WS `ready` handshake completed. */
+  connected: boolean;
+  /** Tear down the call: close the socket, stop the mic, release audio. Idempotent. */
+  endCall: () => void;
+  /** The last transport/pipeline error, or `undefined`. */
+  error: Error | undefined;
+  /** The live assistant text for the in-flight turn (grows via deltas; finalized on done). */
+  interimTranscript: string;
+  /** `true` while the mic is muted. */
+  isMuted: boolean;
+  /** Send a typed turn (no audio) — a text message spoken back by the agent. */
+  sendText: (text: string) => void;
+  /** Open the mic, connect the socket, and start the conversation. Idempotent while active. */
+  startCall: () => Promise<void>;
+  /** The current call lifecycle. */
+  status: VoiceStatus;
+  /** Mute/unmute the microphone. Returns the new muted state. */
+  toggleMute: () => boolean;
+  /** The last finalized user utterance (STT result). */
+  transcript: string;
+}
+/**
+ * A first-class voice-call surface for a voice-enabled agent: it opens a
+ * WebSocket to the agent's `VoiceSessionDO`, captures mic audio as 16 kHz PCM,
+ * streams the agent's synthesized speech back through the browser's audio output,
+ * and mirrors the call lifecycle (`status`, `transcript`, `interimTranscript`,
+ * `audioLevel`) to React state. Pass the generated `api.agents.<name>Voice`
+ * reference (never a string), matching `useAgentChat`'s reference-passing style.
+ *
+ * v1 transport is plain binary WebSocket frames with push-to-talk / silence-timer
+ * turn detection and client-side RMS barge-in. The heavy Web Audio capture and
+ * playback subsystems are injectable (`createMicrophone` / `createSpeaker` /
+ * `createSocket`) so the hook is drivable outside a browser.
+ */
+declare const useVoiceAgent: (options: UseVoiceAgentOptions) => UseVoiceAgentResult;
+export { type ActionHook, type AdminAuthListResult, type AgentChatMessage, type AgentLiveEvent, type AgentProgressEvent, type AgentThreadRecord, type AgentThreadStatus, type AgentTokenDelta, type AgentToolEvent, AuthLoading, type AuthState, Authenticated, type FlagValue, type HeartbeatReference, type ListPresentReference, LunoraProvider, type LunoraProviderProps, type MutationHook, type MutatorHook, type PageItemOf, type PaginatedArgs, Unauthenticated, type UseAgentApi, type UseAgentChatApi, type UseAgentChatOptions, type UseAgentChatResult, type UseAgentOptions, type UseAgentResult, type UseAgentStateApi, type UseAgentStateOptions, type UseAgentStateResult, type UseAgentToolEventsApi, type UseAgentToolEventsOptions, type UseAgentToolEventsResult, type UseAuthResult, type UseAuthSessionsOptions, type UseAuthUsersOptions, type UseHttpStreamOptions, type UseHttpStreamResult, type UseImpersonateResult, type UseInfiniteQueryOptions, type UseInfiniteQueryResult, type UseLiveTopicOptions, type UseLiveTopicResult, type UseMutationCallOptions, type UseOrganizationsOptions, type UsePaginatedQueryOptions, type UsePaginatedQueryResult, type UsePresenceOptions, type UsePresenceResult, type UseQueryOptions, type UseRateLimitOptions, type UseRateLimitResult, type UseSignUpInvitationsOptions, type UseStreamOptions, type UseStreamResult, type UseStreamStatus, type UseSubscriptionResult, type UseVoiceAgentOptions, type UseVoiceAgentResult, type VoiceAudioFormat, type VoiceReference, type VoiceStatus, hydratePreloaded, useAction, useAgent, useAgentChat, useAgentState, useAgentToolEvents, useAuth, useAuthSessions, useAuthState, useAuthUsers, useClientQuery, useConnectionStatus, useFlag, useFlags, useHttpStream, useImpersonate, useInfiniteQuery, useLiveTopic, useLunora, useMutation, useMutator, useOrganizations, usePaginatedQuery, usePreloadedQuery, usePresence, useQuery, useRateLimit, useSignUpInvitations, useStream, useSubscription, useVoiceAgent };