@lunora/angular 1.0.0-alpha.2 → 1.0.0-alpha.21

package/dist/index.d.mts

@@ -1,57 +1,613 @@
-import { InjectionToken, EnvironmentProviders, DestroyRef, Signal } from '@angular/core';
-import { LunoraClient, LunoraClientOptions, ConnectionStatus, SubscriptionError, FunctionReference, ArgsOf, ReturnOf, MutationCallOptions } from '@lunora/client';
-export type { ArgsOf, ConnectionStatus, FunctionReference, LunoraClient, LunoraClientOptions, MutationCallOptions, ReturnOf, SubscriptionError, Unsubscribe } from '@lunora/client';
+import { DestroyRef, Signal, InjectionToken, EnvironmentProviders } from '@angular/core';
+import { FunctionReference, LunoraClient, SubscriptionError, User, LunoraClientOptions, ConnectionStatus, Preloaded, ArgsOf, ReturnOf, MutationCallOptions, MutatorHandle } from '@lunora/client';
+export type { ArgsOf, ConnectionStatus, FunctionReference, LunoraClient, LunoraClientOptions, MutationCallOptions, Preloaded, ReturnOf, SubscriptionError, Unsubscribe } from '@lunora/client';
+import { PaginationStatus } from '@lunora/client/pagination';
+import { RateLimitStatus, RateLimitConfig } from '@lunora/ratelimit';
 export { SKIP } from '@lunora/client/query';
 /**
-* DI token carrying the framework-neutral {@link LunoraClient}. Every reactive
-* primitive in this adapter (`liveQuery`, `mutate`, `connectionStatus`) reads the
-* client from here, so a single {@link provideLunora} in the application config
-* wires the whole app.
-*
-* The token has a root-scoped default factory, so it resolves even without
-* {@link provideLunora}: it builds one same-origin browser client (which opens
-* its WebSocket lazily on the first subscription). Call {@link provideLunora} to
-* point it at a remote URL or hand it a pre-built client.
-*/
+ * The lifecycle status stored on an agent thread. Client-safe mirror of
+ * `@lunora/agent`'s `AgentThreadStatus` — re-declared here (rather than imported)
+ * so this Angular entry never pulls in the server-only `@lunora/agent` module graph
+ * (the adapter stays Angular + `@lunora/client` only). Keep in sync with
+ * `packages/agent/src/types.ts`.
+ * @experimental
+ */
+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`.
+ * @experimental
+ */
+interface AgentThreadRecord {
+  createdAt?: number;
+  /** The failure message when `status === "error"`. */
+  error?: 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;
+}
+/**
+ * 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 Angular 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`.
+ * @experimental
+ */
+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;
+}
+/**
+ * A live token delta streamed while a turn is generating. Client-safe mirror of
+ * `@lunora/agent`'s `AgentTokenDelta`. Ephemeral — deltas feed the chat surface's
+ * streaming text live and are never replayed; the persisted assistant message
+ * stays the single source of truth.
+ * @experimental
+ */
+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 `agentToolEvents`, ignored by the chat surface's streaming text.
+ * @experimental
+ */
+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).
+ * @experimental
+ */
+type AgentLiveEvent = AgentProgressEvent | AgentTokenDelta;
+/**
+ * The `agents.agentThread` reference the primitive 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.
+ * @experimental
+ */
+interface AgentApi {
+  agents: {
+    agentThread: FunctionReference<"query", {
+      key: string;
+    }, Record<string, unknown> | undefined>;
+  };
+}
+/**
+ * `AgentOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
+interface AgentOptions {
+  /** The generated `api` — its `agents.agentThread` query drives live thread state. */
+  api: AgentApi;
+  /**
+   * Optional app mutation over the agent's cancel path
+   * (`ctx.agents.&lt;name>.cancel(id)`). Called with `{ instanceId, threadKey }`.
+   * When omitted (or no run is in flight) {@link AgentResult.cancel} is a no-op.
+   */
+  cancel?: FunctionReference<"mutation">;
+  /** Client to bind to. Defaults to the injected `LUNORA_CLIENT`. */
+  client?: LunoraClient;
+  /**
+   * `DestroyRef` whose `onDestroy` tears the live subscription down. Defaults to
+   * `inject(DestroyRef)` — the calling component/service.
+   */
+  destroyRef?: DestroyRef;
+  /**
+   * The app mutation that starts (or continues) a run — a thin wrapper over
+   * `ctx.agents.&lt;name>.run(...)`. Called with `{ threadKey, input }` merged with
+   * {@link AgentOptions.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;
+}
+/**
+ * `AgentResult` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
+interface AgentResult {
+  /**
+   * 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>;
+  /** `true` while a `run` invocation is in flight. */
+  pending: Signal<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: Signal<AgentThreadStatus | undefined>;
+  /** The live thread record (status, `instanceId`, …), or `undefined` before it exists. */
+  thread: Signal<AgentThreadRecord | undefined>;
+}
+/**
+ * A thin agent handle: live thread `status` plus `run` / `cancel`, without the
+ * chat message surface. Composes `subscription(api.agents.agentThread)` for live
+ * state and drives the run/cancel writes straight on the client — the Angular
+ * counterpart to React's `useAgent`, re-expressed with signals. For the full
+ * conversation surface (durable history + streaming + approvals) use `agentChat`.
+ *
+ * `run` and `cancel` stay generic over the app-defined mutations that wrap
+ * `ctx.agents.&lt;name>.run` / `.cancel`, so the primitive hard-codes no function
+ * names beyond the `agents:*` surface.
+ *
+ * Call from an injection context (component/service field or constructor); pass an
+ * explicit `client` / `destroyRef` to drive it outside one (e.g. in a test).
+ * @experimental
+ */
+declare const agent: (options: AgentOptions) => AgentResult;
+/** 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 primitive consumes only the token arm.
+ * @experimental
+ */
+type AgentTokenStreamReference = FunctionReference<"stream", {
+  key: string;
+}, AgentLiveEvent>;
+/**
+ * The `agents.*` reference surface the chat primitive reads. A structural subset
+ * of the generated `api.agents`, so the whole generated `api` object is
+ * assignable.
+ * @experimental
+ */
+interface AgentChatApi {
+  agents: {
+    agentMessages: AgentMessagesReference$1;
+    agentResolveApproval: AgentApprovalReference;
+    agentThread: AgentThreadReference;
+  };
+}
+/**
+ * `AgentChatOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
+interface AgentChatOptions {
+  /** The generated `api` — its `agents.*` surface provides history, thread state, and approval resolution. */
+  api: AgentChatApi;
+  /**
+   * Optional app mutation over the agent's cancel path
+   * (`ctx.agents.&lt;name>.cancel(id)`). Called with `{ instanceId, threadKey }`.
+   * When omitted (or no run is in flight) {@link AgentChatResult.cancel} is a
+   * no-op.
+   */
+  cancel?: FunctionReference<"mutation">;
+  /** Client to bind to. Defaults to the injected `LUNORA_CLIENT`. */
+  client?: LunoraClient;
+  /**
+   * `DestroyRef` whose `onDestroy` tears the subscriptions + stream down. Defaults
+   * to `inject(DestroyRef)` — the calling component/service.
+   */
+  destroyRef?: DestroyRef;
+  /** History depth forwarded to `agents:agentMessages`. */
+  limit?: number;
+  /**
+   * The app mutation that starts (or continues) a run — a thin wrapper over
+   * `ctx.agents.&lt;name>.run(...)`. Called with `{ threadKey, input }` merged with
+   * {@link AgentChatOptions.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 AgentChatResult.streamingText}
+   * stays empty and the UI updates message-by-message from durable history.
+   */
+  stream?: AgentTokenStreamReference;
+  /** The thread to observe and continue. */
+  threadKey: string;
+}
+/**
+ * `AgentChatResult` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
+interface AgentChatResult {
+  /** 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>;
+  /** Durable thread history (oldest first) plus any un-acknowledged optimistic user turns. */
+  messages: Signal<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: Signal<AgentThreadStatus | undefined>;
+  /** The in-flight turn's streamed text — live-only, empty once the turn persists to `messages`. */
+  streamingText: Signal<string>;
+}
+/**
+ * A first-class agent chat surface: live durable history + in-flight token
+ * streaming + the send / approve / reject / cancel writes, keyed by `threadKey` —
+ * the Angular counterpart to React's `useAgentChat`, re-expressed with signals.
+ *
+ * It composes the existing primitives rather than adding transport:
+ * `subscription(api.agents.agentMessages)` for durable history,
+ * `subscription(api.agents.agentThread)` for live status + the in-flight
+ * `instanceId`, {@link stream} over an app token stream for in-flight deltas, and
+ * the client's own `mutation` 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.
+ *
+ * Call from an injection context (component/service field or constructor); pass an
+ * explicit `client` / `destroyRef` to drive it outside one (e.g. in a test).
+ * @experimental
+ */
+declare const agentChat: (options: AgentChatOptions) => AgentChatResult;
+/**
+ * The `agents.agentState` reference the primitive subscribes to for the thread's
+ * live synced state. A structural subset of the generated `api.agents` surface
+ * (like `AgentApi` 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 primitive's generic `T`, since codegen pins the reference return
+ * as an optional record (it never evaluates agent config).
+ * @experimental
+ */
+interface AgentStateApi {
+  agents: {
+    agentState: FunctionReference<"query", {
+      key: string;
+    }, Record<string, unknown> | undefined>;
+  };
+}
+/**
+ * `AgentStateOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
+interface AgentStateOptions {
+  /** The generated `api` — its `agents.agentState` query drives live thread state. */
+  api: AgentStateApi;
+  /** Client to bind to. Defaults to the injected `LUNORA_CLIENT`. */
+  client?: LunoraClient;
+  /**
+   * `DestroyRef` whose `onDestroy` tears the subscription down. Defaults to
+   * `inject(DestroyRef)` — the calling component/service.
+   */
+  destroyRef?: DestroyRef;
+  /** The thread whose synced state to observe. */
+  threadKey: string;
+}
+/**
+ * `AgentStateResult` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
+interface AgentStateResult<T> {
+  /** The subscription error, if the live channel reported one. */
+  error: Signal<SubscriptionError | undefined>;
+  /** The live synced state, or `undefined` before it is seeded/first pushed. */
+  state: Signal<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 `subscription(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`. The Angular counterpart to React's `useAgentState`,
+ * re-expressed with signals.
+ *
+ * Generic over the app's state shape (`agentState&lt;SupportState>(...)`, 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.
+ *
+ * Call from an injection context (component/service field or constructor); pass an
+ * explicit `client` / `destroyRef` to drive it outside one (e.g. in a test).
+ * @experimental
+ */
+declare const agentState: <T extends Record<string, unknown> = Record<string, unknown>>(options: AgentStateOptions) => AgentStateResult<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 primitive consumes
+ * only the progress arm (`kind === "progress"`).
+ */
+type AgentLiveStreamReference = FunctionReference<"stream", {
+  key: string;
+}, AgentLiveEvent>;
+/**
+ * The `agents.*` reference surface the tool-events primitive reads. A structural
+ * subset of the generated `api.agents`, so the whole generated `api` object is
+ * assignable.
+ * @experimental
+ */
+interface AgentToolEventsApi {
+  agents: {
+    agentMessages: AgentMessagesReference;
+  };
+}
+/**
+ * `AgentToolEventsOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
+interface AgentToolEventsOptions {
+  /** The generated `api` — its `agents.agentMessages` query provides the durable tool lifecycle. */
+  api: AgentToolEventsApi;
+  /** Client to bind to. Defaults to the injected `LUNORA_CLIENT`. */
+  client?: LunoraClient;
+  /**
+   * `DestroyRef` whose `onDestroy` tears the subscription + stream down. Defaults
+   * to `inject(DestroyRef)` — the calling component/service.
+   */
+  destroyRef?: DestroyRef;
+  /** History depth forwarded to `agents:agentMessages`. */
+  limit?: number;
+  /**
+   * Optional live event stream — the same app stream function `agentChat` 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`.
+ * @experimental
+ */
+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";
+};
+/**
+ * `AgentToolEventsResult` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
+interface AgentToolEventsResult {
+  /**
+   * The thread's tool events: the durable lifecycle (oldest first, by `seq`)
+   * followed by any in-flight ephemeral progress events, recomputed from the live
+   * subscription + stream. Treat as derived, not identity-stable.
+   */
+  events: Signal<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. The Angular counterpart to React's
+ * `useAgentToolEvents`, re-expressed as a `computed` signal.
+ *
+ * It composes the existing primitives rather than adding transport:
+ * `subscription(api.agents.agentMessages)` for the durable lifecycle and
+ * {@link stream} 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 `agentChat`; this primitive is the tool-observability slice.
+ *
+ * Call from an injection context (component/service field or constructor); pass an
+ * explicit `client` / `destroyRef` to drive it outside one (e.g. in a test).
+ * @experimental
+ */
+declare const agentToolEvents: (options: AgentToolEventsOptions) => AgentToolEventsResult;
+/**
+ * `AuthOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
+interface AuthOptions {
+  /** Client to bind to. Defaults to the injected `LUNORA_CLIENT`. */
+  client?: LunoraClient;
+  /** `DestroyRef` whose `onDestroy` removes the listeners. Defaults to `inject(DestroyRef)`. */
+  destroyRef?: DestroyRef;
+}
+/**
+ * `AuthResult` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
+interface AuthResult {
+  /** Set the auth token (sign-in / sign-out). */
+  setToken: (token: string | null) => void;
+  /** The current auth token, or `null`. */
+  token: Signal<string | null>;
+  /** The resolved user from `store.getUser()`, or `null`. */
+  user: Signal<User | null>;
+}
+/**
+ * Token + identity plumbing for Angular. `token` is a signal tracking the
+ * client's auth token; `user` is a signal resolved from `getCurrentUser()`
+ * whenever the token changes. `setToken(jwt)` after sign-in makes subsequent
+ * RPC calls carry the `Authorization` header.
+ *
+ * Multiple `auth` instances on the same client share a single per-client
+ * identity store (from `@lunora/client/auth`) — a `setToken` from one component
+ * re-renders every watcher with the freshly-resolved user.
+ *
+ * Call from an injection context (component/service field or constructor):
+ * ```ts
+ * const { token, user, setToken } = auth();
+ * ```
+ * @experimental
+ */
+declare const auth: (options?: AuthOptions) => AuthResult;
+/**
+ * `AuthGateResult` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
+interface AuthGateResult {
+  /** `true` once a token is set and the user has resolved. */
+  isAuthenticated: Signal<boolean>;
+  /** `true` while a token is set but the user hasn't resolved yet. */
+  isLoading: Signal<boolean>;
+}
+/**
+ * Derived auth-gate signals for template gating (Angular's `\@if` control
+ * flow), built on {@link auth}. Angular has no JSX-style `Authenticated` slot
+ * component the way React/Vue/Solid do, so this exposes the same three-state
+ * logic as two booleans instead: a token with no resolved user yet is
+ * `isLoading`; a token with a resolved user is `isAuthenticated`; no token is
+ * neither (the signed-out state a template checks for with a plain `\@else`).
+ *
+ * Call from an injection context (component/service field or constructor):
+ * ```ts
+ * protected readonly authState = authGate();
+ * // template: \@if (authState.isAuthenticated()) { ... } \@else if (authState.isLoading()) { ... }
+ * ```
+ * @experimental
+ */
+declare const authGate: (options?: AuthOptions) => AuthGateResult;
+/**
+ * DI token carrying the framework-neutral {@link LunoraClient}. Every reactive
+ * primitive in this adapter (`liveQuery`, `mutate`, `connectionStatus`) reads the
+ * client from here, so a single {@link provideLunora} in the application config
+ * wires the whole app.
+ *
+ * The token has a root-scoped default factory, so it resolves even without
+ * {@link provideLunora}: it builds one same-origin browser client (which opens
+ * its WebSocket lazily on the first subscription). Call {@link provideLunora} to
+ * point it at a remote URL or hand it a pre-built client.
+ * @experimental
+ */
 declare const LUNORA_CLIENT: InjectionToken<LunoraClient>;
 /**
-* Options accepted by {@link provideLunora}. Identical to {@link LunoraClientOptions}
-* except `url` is optional — it defaults to the page origin in the browser (and to
-* `""` on the server; pass an explicit `url` for SSR data-loading — see
-* {@link sameOriginUrl}).
-*/
+ * Options accepted by {@link provideLunora}. Identical to {@link LunoraClientOptions}
+ * except `url` is optional — it defaults to the page origin in the browser (and to
+ * `""` on the server; pass an explicit `url` for SSR data-loading — see
+ * {@link sameOriginUrl}).
+ * @experimental
+ */
 type ProvideLunoraOptions = Omit<LunoraClientOptions, "url"> & {
   url?: string;
 };
 /**
-* Wire a {@link LunoraClient} into the application injector. Add the result to the
-* `providers` array of an Angular application config (or any `EnvironmentProviders`
-* consumer):
-*
-* ```ts
-* export const appConfig: ApplicationConfig = {
-*     providers: [provideLunora({ url: "https://api.example.com" })],
-* };
-* ```
-*
-* Pass {@link LunoraClientOptions} to configure a fresh client (URL defaults to
-* the page origin), or hand in an already-constructed {@link LunoraClient} to
-* share one instance (e.g. a client you also preload against during SSR).
-*/
+ * Wire a {@link LunoraClient} into the application injector. Add the result to the
+ * `providers` array of an Angular application config (or any `EnvironmentProviders`
+ * consumer):
+ *
+ * ```ts
+ * export const appConfig: ApplicationConfig = {
+ *     providers: [provideLunora({ url: "https://api.example.com" })],
+ * };
+ * ```
+ *
+ * Pass {@link LunoraClientOptions} to configure a fresh client (URL defaults to
+ * the page origin), or hand in an already-constructed {@link LunoraClient} to
+ * share one instance (e.g. a client you also preload against during SSR).
+ * @experimental
+ */
 declare const provideLunora: (optionsOrClient?: LunoraClient | ProvideLunoraOptions) => EnvironmentProviders;
 /**
-* Read the {@link LunoraClient} from the current injector. Call inside an
-* injection context (a component/service field initializer or constructor, or a
-* `runInInjectionContext` callback). Use it to hold the client for imperative
-* calls — e.g. `mutation`/`action` from event handlers, which run outside an
-* injection context:
-*
-* ```ts
-* private readonly client = injectLunoraClient();
-* send = (text: string) => this.client.mutation(api.messages.send, { text });
-* ```
-*/
+ * Read the {@link LunoraClient} from the current injector. Call inside an
+ * injection context (a component/service field initializer or constructor, or a
+ * `runInInjectionContext` callback). Use it to hold the client for imperative
+ * calls — e.g. `mutation`/`action` from event handlers, which run outside an
+ * injection context:
+ *
+ * ```ts
+ * private readonly client = injectLunoraClient();
+ * send = (text: string) => this.client.mutation(api.messages.send, { text });
+ * ```
+ * @experimental
+ */
 declare const injectLunoraClient: () => LunoraClient;
+/**
+ * `ConnectionStatusOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
 interface ConnectionStatusOptions {
   /** Client to observe. Defaults to the injected `LUNORA_CLIENT`. */
   client?: LunoraClient;
@@ -59,88 +615,725 @@ interface ConnectionStatusOptions {
   destroyRef?: DestroyRef;
 }
 /**
-* A `signal` of the client's aggregate live-socket status across all shard
-* connections. Reads the current status synchronously and updates on every
-* transition (`idle` → `connecting` → `connected` → `offline`). The Angular
-* equivalent of `@lunora/react`'s `useConnectionStatus`.
-*
-* The listener is removed when the owning `DestroyRef` fires. Call from an
-* injection context (component/service field or constructor).
-*/
+ * A `signal` of the client's aggregate live-socket status across all shard
+ * connections. Reads the current status synchronously and updates on every
+ * transition (`idle` → `connecting` → `connected` → `offline`). The Angular
+ * equivalent of `@lunora/react`'s `useConnectionStatus`.
+ *
+ * The listener is removed when the owning `DestroyRef` fires. Call from an
+ * injection context (component/service field or constructor).
+ * @experimental
+ */
 declare const connectionStatus: (options?: ConnectionStatusOptions) => Signal<ConnectionStatus>;
+/**
+ * The value kinds a flag resolves to — OpenFeature's boolean / number / string / structured (JSON) flags.
+ * @experimental
+ */
+type FlagValue = boolean | number | string | Record<string, unknown> | unknown[] | null;
+/**
+ * Targeting context bag forwarded to the OpenFeature provider.
+ * @experimental
+ */
+type FlagContext = Record<string, unknown>;
+/**
+ * `FlagOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
+interface FlagOptions {
+  /** Client to bind to. Defaults to the injected `LUNORA_CLIENT`. */
+  client?: LunoraClient;
+  /**
+   * Per-call targeting context merged on top of the app's default `identify`
+   * targeting key.
+   */
+  context?: FlagContext;
+  /** `DestroyRef` whose `onDestroy` tears down the subscription. Defaults to `inject(DestroyRef)`. */
+  destroyRef?: DestroyRef;
+}
+/**
+ * Subscribe to a single feature flag, live over Lunora's WebSocket.
+ *
+ * The returned signal holds `defaultValue` until the first evaluation lands, then
+ * the server's resolved value — re-pushed whenever the provider re-evaluates.
+ * The flag's kind is inferred from `defaultValue`'s runtime type, so
+ * `flag("dark", false)` reads a boolean and `flag("hero", "control")` a string.
+ *
+ * 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`).
+ *
+ * Call from an injection context:
+ * ```ts
+ * readonly darkMode = flag("dark-mode", false);
+ * ```
+ * @experimental
+ */
+declare const flag: <T extends FlagValue>(key: string, defaultValue: T, options?: FlagOptions) => Signal<T>;
+/**
+ * `FlagsOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
+interface FlagsOptions {
+  /** Client to bind to. Defaults to the injected `LUNORA_CLIENT`. */
+  client?: LunoraClient;
+  /**
+   * Targeting context shared by every flag in the set, merged on top of the
+   * app's default `identify` targeting key.
+   */
+  context?: FlagContext;
+  /** `DestroyRef` whose `onDestroy` tears down the subscriptions. Defaults to `inject(DestroyRef)`. */
+  destroyRef?: DestroyRef;
+}
+/**
+ * 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 returned signal holds the same-shaped record with resolved
+ * values (the defaults until each evaluation lands).
+ *
+ * Call from an injection context:
+ * ```ts
+ * readonly features = flags({ "dark-mode": false, "new-editor": false });
+ * ```
+ * @experimental
+ */
+declare const flags: <T extends Record<string, FlagValue>>(flagDefaults: T, options?: FlagsOptions) => Signal<T>;
+/**
+ * `HydratePreloadedOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
+interface HydratePreloadedOptions {
+  /** Client to bind to. Defaults to the injected `LUNORA_CLIENT`. */
+  client?: LunoraClient;
+  /** `DestroyRef` whose `onDestroy` tears the subscription down. Defaults to `inject(DestroyRef)`. */
+  destroyRef?: DestroyRef;
+}
+/**
+ * `HydratePreloadedResult` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
+interface HydratePreloadedResult<T> {
+  /** The latest value pushed by the server. Seeded synchronously from the preloaded value. */
+  data: Signal<T | undefined>;
+  /** The latest subscription error, or `undefined`. */
+  error: Signal<SubscriptionError | undefined>;
+}
+/**
+ * Hydrate a query from a {@link Preloaded} token produced by `preloadQuery`
+ * during SSR, then keep it live — the Angular half of the reactive-loader
+ * handoff.
+ *
+ * The returned signal is seeded **synchronously** from `preloaded.value`, so the
+ * very first read (during hydration) shows the server value: no loading flash,
+ * no hydration mismatch. After seeding it opens a WebSocket subscription on the
+ * same `(functionPath, args, shardKey)` the SSR loader used, so every later
+ * server delta updates the signal exactly like `liveQuery`.
+ *
+ * The subscription tears down when the owning `DestroyRef` fires.
+ *
+ * Call from an injection context:
+ * ```ts
+ * readonly { data, error } = hydratePreloaded(preloadedMessages);
+ * ```
+ * @experimental
+ */
+declare const hydratePreloaded: <T>(preloaded: Preloaded<T>, options?: HydratePreloadedOptions) => HydratePreloadedResult<T>;
+/**
+ * `LiveQueryOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
 interface LiveQueryOptions {
   /**
-  * Client to bind to. Defaults to the injected `LUNORA_CLIENT`; pass one
-  * explicitly to use `liveQuery` outside an injection context (or in a test).
-  */
+   * Client to bind to. Defaults to the injected `LUNORA_CLIENT`; pass one
+   * explicitly to use `liveQuery` outside an injection context (or in a test).
+   */
   client?: LunoraClient;
   /**
-  * `DestroyRef` whose `onDestroy` tears the subscription down. Defaults to
-  * `inject(DestroyRef)` — the calling component/service — so it closes when that
-  * component is destroyed. Pass one explicitly to control the lifetime yourself.
-  */
+   * `DestroyRef` whose `onDestroy` tears the subscription down. Defaults to
+   * `inject(DestroyRef)` — the calling component/service — so it closes when that
+   * component is destroyed. Pass one explicitly to control the lifetime yourself.
+   */
   destroyRef?: DestroyRef;
   /**
-  * Called when the subscription errors after the initial attach — the async
-  * error channel `createQuerySubscription` only wires when a sink is present.
-  * Without it, a post-attach failure is dropped silently: the signal simply
-  * stops updating with no error state exposed. Pass a handler to surface it
-  * (log, toast, set an error signal of your own).
-  */
+   * Called when the subscription errors after the initial attach — the async
+   * error channel `createQuerySubscription` only wires when a sink is present.
+   * Without it, a post-attach failure is dropped silently: the signal simply
+   * stops updating with no error state exposed. Pass a handler to surface it
+   * (log, toast, set an error signal of your own).
+   */
   onError?: (error: SubscriptionError) => void;
   /** Route to a specific shard when the target function is `.shardBy(...)`-partitioned. */
   shardKey?: string;
 }
 /**
-* Subscribe to a server query and mirror its value into an Angular `signal`.
-*
-* Reads `undefined` until the first server frame lands, then updates on every
-* delta the WebSocket pushes. The underlying subscription is torn down
-* automatically when the owning `DestroyRef` fires (the component/service is
-* destroyed), so there is no leaked socket subscription.
-*
-* Call it from an injection context (a component/service field initializer or
-* constructor) so the default `inject(DestroyRef)` resolves the caller's
-* lifetime:
-*
-* ```ts
-* export class MessagesComponent {
-*     readonly messages = liveQuery(api.messages.list, { channelId: "general" });
-* }
-* ```
-*
-* Pass `"skip"` (the `SKIP` sentinel from `@lunora/client/query`) as `args` to
-* short-circuit — no network call, no socket; the signal stays `undefined`. To
-* call outside an injection context (e.g. lazily in `ngOnInit`), supply `client`
-* and `destroyRef` via {@link LiveQueryOptions}.
-*/
+ * Subscribe to a server query and mirror its value into an Angular `signal`.
+ *
+ * Reads `undefined` until the first server frame lands, then updates on every
+ * delta the WebSocket pushes. The underlying subscription is torn down
+ * automatically when the owning `DestroyRef` fires (the component/service is
+ * destroyed), so there is no leaked socket subscription.
+ *
+ * Call it from an injection context (a component/service field initializer or
+ * constructor) so the default `inject(DestroyRef)` resolves the caller's
+ * lifetime:
+ *
+ * ```ts
+ * export class MessagesComponent {
+ *     readonly messages = liveQuery(api.messages.list, { channelId: "general" });
+ * }
+ * ```
+ *
+ * Pass `"skip"` (the `SKIP` sentinel from `@lunora/client/query`) as `args` to
+ * short-circuit — no network call, no socket; the signal stays `undefined`. To
+ * call outside an injection context (e.g. lazily in `ngOnInit`), supply `client`
+ * and `destroyRef` via {@link LiveQueryOptions}.
+ * @experimental
+ */
 declare const liveQuery: <F extends FunctionReference>(reference: F, args: ArgsOf<F> | "skip", options?: LiveQueryOptions) => Signal<ReturnOf<F> | undefined>;
+/**
+ * `MutateOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
 interface MutateOptions<F extends FunctionReference> extends MutationCallOptions<unknown, unknown, ArgsOf<F>> {
   /**
-  * Client to run the mutation on. Defaults to the injected `LUNORA_CLIENT`.
-  * Because mutations usually fire from event handlers — which run *outside* an
-  * injection context — capture the client once (`injectLunoraClient()` in a
-  * field) and pass it here, or call `client.mutation(...)` directly.
-  */
-  client?: LunoraClient;
-}
-/**
-* Run a Lunora mutation and resolve with the server result (rejects on failure).
-*
-* Optimistic updates stay client-owned: the `optimistic` / `optimisticUpdate`
-* call options pass straight through to `client.mutation`, which applies and
-* rolls them back against the live subscription cache — the same cache
-* `liveQuery` reads, so an optimistic write reflects immediately and
-* reverts on failure. The client's offline queue also engages when the socket is
-* down, so the write stays durable across reconnects.
-*
-* ```ts
-* private readonly client = injectLunoraClient();
-* send = (text: string) => mutate(api.messages.send, { text }, { client: this.client });
-* ```
-*
-* When called from within an injection context you may omit `client` and let it
-* resolve from the injector.
-*/
+   * Client to run the mutation on. Defaults to the injected `LUNORA_CLIENT`.
+   * Because mutations usually fire from event handlers — which run *outside* an
+   * injection context — capture the client once (`injectLunoraClient()` in a
+   * field) and pass it here, or call `client.mutation(...)` directly.
+   */
+  client?: LunoraClient;
+}
+/**
+ * Run a Lunora mutation and resolve with the server result (rejects on failure).
+ *
+ * Optimistic updates stay client-owned: the `optimistic` / `optimisticUpdate`
+ * call options pass straight through to `client.mutation`, which applies and
+ * rolls them back against the live subscription cache — the same cache
+ * `liveQuery` reads, so an optimistic write reflects immediately and
+ * reverts on failure. The client's offline queue also engages when the socket is
+ * down, so the write stays durable across reconnects.
+ *
+ * ```ts
+ * private readonly client = injectLunoraClient();
+ * send = (text: string) => mutate(api.messages.send, { text }, { client: this.client });
+ * ```
+ *
+ * When called from within an injection context you may omit `client` and let it
+ * resolve from the injector.
+ * @experimental
+ */
 declare const mutate: <F extends FunctionReference>(reference: F, args: ArgsOf<F>, options?: MutateOptions<F>) => Promise<ReturnOf<F>>;
-export { type ConnectionStatusOptions, LUNORA_CLIENT, type LiveQueryOptions, type MutateOptions, type ProvideLunoraOptions, connectionStatus, injectLunoraClient, liveQuery, mutate, provideLunora };
+/**
+ * `MutatorResult` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
+interface MutatorResult<TArgs> {
+  /** The latest invocation's error, or `undefined`. */
+  error: Signal<Error | undefined>;
+  /** `true` when the latest invocation rejected. */
+  isError: Signal<boolean>;
+  /** Run the mutator; resolves once the write is persisted, rejects on failure. */
+  mutate: (args: TArgs) => Promise<void>;
+  /** `true` while ANY invocation from this handle is in flight. */
+  pending: Signal<boolean>;
+  /** Clear the latest `error` back to idle. */
+  reset: () => void;
+}
+/**
+ * Ergonomic `{ mutate, pending, error, isError, reset }` wrapper over a bound
+ * custom-mutator handle from `` `@lunora/db` ``'s `bindMutators` — the Angular
+ * equivalent of `` `@lunora/react` ``'s `useMutator`. The optimistic overlay and
+ * server-authoritative push are owned by the bound handle; this function only
+ * surfaces reactive state for the in-flight/error lifecycle.
+ *
+ * `pending` is ref-counted across overlapping invocations of THIS handle, so it
+ * clears only once every concurrent call has settled.
+ *
+ * Does NOT require an injection context — it works with plain signals.
+ *
+ * ```ts
+ * private readonly collection = bindMutators(collections);
+ * readonly mutator = mutator(this.collection.insert);
+ * ```
+ * @experimental
+ */
+declare const mutator: <TArgs = Record<string, unknown>>(handle: MutatorHandle<TArgs>) => MutatorResult<TArgs>;
+/** The args a paginated query exposes minus the framework-supplied page cursor. */
+type PaginatedArgs<F extends FunctionReference> = Omit<ArgsOfRaw<F>, "paginationOpts">;
+/** The element type of the `page` array a paginated query returns. */
+type PageItemOf<F extends FunctionReference> = ReturnTypeOf<F> extends {
+  page: (infer T)[];
+} ? T : unknown;
+type ArgsOfRaw<F extends FunctionReference> = F extends FunctionReference<"query", infer A> ? A : never;
+type ReturnTypeOf<F extends FunctionReference> = F extends FunctionReference<"query", unknown, infer R> ? R : never;
+/**
+ * Options for the paginated query — part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
+interface PaginatedQueryOptions {
+  /** Client to bind to. Defaults to the injected `LUNORA_CLIENT`. */
+  client?: LunoraClient;
+  /** `DestroyRef` whose `onDestroy` tears down the subscriptions. Defaults to `inject(DestroyRef)`. */
+  destroyRef?: DestroyRef;
+  /** Page size for the first page (and the default for `loadMore`). */
+  initialNumItems: number;
+  /** Route to a specific shard when the target function is `.shardBy(...)`-partitioned. */
+  shardKey?: string;
+}
+/**
+ * `PaginatedQueryResult` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
+interface PaginatedQueryResult<T> {
+  /** `true` while the first page or a `loadMore` page is in flight. */
+  isLoading: Signal<boolean>;
+  /** Request the next page. A no-op unless `status === "CanLoadMore"`. */
+  loadMore: (numberItems: number) => void;
+  /** Flattened items across every loaded page, in order. */
+  results: Signal<T[]>;
+  /** The pagination status. */
+  status: Signal<PaginationStatus>;
+}
+/**
+ * `InfiniteQueryResult` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
+interface InfiniteQueryResult<T> {
+  /** 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. */
+  hasNextPage: Signal<boolean>;
+  /** `true` while a `fetchNextPage` page (beyond the first) is in flight. */
+  isFetchingNextPage: Signal<boolean>;
+  /** `true` while the first page is in flight. */
+  isLoading: Signal<boolean>;
+  /** One inner array per loaded page, in order; unresolved pages are omitted. */
+  pages: Signal<T[][]>;
+  /** The pagination status. */
+  status: Signal<PaginationStatus>;
+}
+/**
+ * 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`. Pages are tracked as an
+ * ordered list of stable boundary cursors; each loaded page is a live
+ * subscription over a FIXED `(lower, upper]` range.
+ *
+ * `loadMore` appends the next page off the open-ended tail's `continueCursor`;
+ * it is a no-op unless `status === "CanLoadMore"`.
+ *
+ * Call from an injection context:
+ * ```ts
+ * readonly messages = paginatedQuery(api.messages.list, {}, { initialNumItems: 20 });
+ * ```
+ * @experimental
+ */
+declare const paginatedQuery: <F extends FunctionReference>(reference: F, args: PaginatedArgs<F> | "skip", options: PaginatedQueryOptions) => PaginatedQueryResult<PageItemOf<F>>;
+/**
+ * Subscribe to a reactively-paginated query and expose its pages discretely.
+ *
+ * Shares `paginatedQuery`'s reactive-pagination engine but keeps each page as
+ * its own inner array rather than flattening them, and adds the TanStack-Query-
+ * style `fetchNextPage` / `hasNextPage` / `isFetchingNextPage` shape.
+ *
+ * Call from an injection context:
+ * ```ts
+ * readonly feed = infiniteQuery(api.messages.list, {}, { initialNumItems: 20 });
+ * ```
+ * @experimental
+ */
+declare const infiniteQuery: <F extends FunctionReference>(reference: F, args: PaginatedArgs<F> | "skip", options: PaginatedQueryOptions) => InfiniteQueryResult<PageItemOf<F>>;
+/**
+ * `HeartbeatReference` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
+type HeartbeatReference = FunctionReference<"mutation", {
+  data?: Record<string, unknown>;
+  roomId: string;
+  sessionId: string;
+}>;
+/**
+ * `ListPresentReference` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
+type ListPresentReference = FunctionReference<"query", {
+  roomId: string;
+}>;
+/**
+ * `PresenceOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
+interface PresenceOptions<H extends HeartbeatReference, L extends ListPresentReference> {
+  /** Client to bind to. Defaults to the injected `LUNORA_CLIENT`. */
+  client?: LunoraClient;
+  /** Awareness blob for the first heartbeat (selection, cursor, name, color…). */
+  data?: Record<string, unknown>;
+  /** `DestroyRef` whose `onDestroy` cleans up. Defaults to `inject(DestroyRef)`. */
+  destroyRef?: DestroyRef;
+  /** The `api.*` reference for the presence heartbeat mutation. */
+  heartbeat: H;
+  /** Heartbeat cadence in ms. Defaults to 10s (10000). */
+  intervalMs?: number;
+  /** The `api.*` reference for the presence listPresent query. */
+  listPresent: L;
+  /**
+   * Stable id for this presence row. Defaults to a fresh per-call id.
+   * Pass a user/connection id to control deduping across tabs.
+   */
+  sessionId?: string;
+  /** Forwarded to the heartbeat mutation / listPresent subscription when sharding by room. */
+  shardKey?: string;
+}
+/**
+ * `PresenceResult` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
+interface PresenceResult<L extends ListPresentReference> {
+  /** The present members for the room. `undefined` until the first push. */
+  present: Signal<ReturnOf<L> | undefined>;
+  /** This mount's session id (generated when not supplied). */
+  sessionId: string;
+  /** Replace the awareness `data` sent with subsequent heartbeats, and heartbeat immediately. */
+  setData: (data: Record<string, unknown> | undefined) => void;
+}
+/**
+ * `presence` — collaborative-awareness primitive, the client half of the
+ * `@lunora/server` `definePresence` preset.
+ *
+ * Drives the heartbeat mutation (on mount, interval, and tab re-focus) and
+ * subscribes to the live `listPresent` query for the given room.
+ *
+ * Call from an injection context (component/service field or constructor):
+ * ```ts
+ * readonly roomPresence = presence("room:general", {
+ *     heartbeat: api.presence.heartbeat,
+ *     listPresent: api.presence.listPresent,
+ * });
+ * ```
+ * @experimental
+ */
+declare const presence: <H extends HeartbeatReference, L extends ListPresentReference>(roomId: string, options: PresenceOptions<H, L>) => PresenceResult<L>;
+/**
+ * `RateLimitOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
+interface RateLimitOptions {
+  /**
+   * `DestroyRef` whose `onDestroy` clears the interval. Defaults to
+   * `inject(DestroyRef)` — the calling component/service.
+   */
+  destroyRef?: DestroyRef;
+  /** 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`.
+   */
+  tickMs?: number;
+}
+/**
+ * `RateLimitResult` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
+interface RateLimitResult {
+  /** Would consuming `count` (default 1) succeed right now? Does not consume. */
+  check: (count?: number) => boolean;
+  /** Optimistically consume `count` (default 1) locally; mirrors the server algorithm. */
+  consume: (count?: number) => RateLimitStatus;
+  /** `true` while a single unit cannot be consumed — convenient for disabling a control. */
+  disabled: Signal<boolean>;
+  /** `true` while a single unit can be consumed. */
+  ok: Signal<boolean>;
+  /** Clear local accounting (e.g. after the server confirms a reset). */
+  reset: () => void;
+  /** Milliseconds until the next unit is available. `0` when `ok`. */
+  retryAfter: Signal<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.
+ *
+ * Requires an Angular injection context unless a `DestroyRef` is passed
+ * explicitly via `options.destroyRef`.
+ *
+ * ```ts
+ * readonly sendLimit = rateLimit({ kind: "token bucket", period: 1000, rate: 10 });
+ * ```
+ * @experimental
+ */
+declare const rateLimit: (config: RateLimitConfig, options?: RateLimitOptions) => RateLimitResult;
+/**
+ * The lifecycle of a stream the primitive is observing.
+ * @experimental
+ */
+type StreamStatus = "complete" | "error" | "idle" | "streaming";
+/**
+ * `StreamOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
+interface StreamOptions {
+  /** Client to bind to. Defaults to the injected `LUNORA_CLIENT`. */
+  client?: LunoraClient;
+  /**
+   * `DestroyRef` whose `onDestroy` cancels the stream. Defaults to
+   * `inject(DestroyRef)` — the calling component/service.
+   */
+  destroyRef?: DestroyRef;
+  /** Forwarded to `client.stream()` — caps the in-flight chunk buffer. */
+  maxBuffer?: number;
+  /** Route to a specific shard when the target function is `.shardBy(...)`-partitioned. */
+  shardKey?: string;
+}
+/**
+ * `StreamResult` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
+interface StreamResult<T> {
+  /** Force-cancel the stream and resolve the iterator. Safe to call multiple times. */
+  cancel: () => void;
+  /** Chunks the server has pushed so far, in arrival order. */
+  chunks: Signal<ReadonlyArray<T>>;
+  /** The stream error, or `undefined`. */
+  error: Signal<Error | undefined>;
+  /** The stream lifecycle. */
+  status: Signal<StreamStatus>;
+}
+/**
+ * Subscribe to a streaming query. Returns the chunks pushed so far plus a
+ * lifecycle status and a `cancel` function, all as signals.
+ *
+ * Unlike `subscription`, which tracks the latest value, `stream` accumulates every
+ * chunk the server pushes — use it for token-by-token deltas and other append-only
+ * feeds. Pass `"skip"` as `args` to keep the primitive mounted without opening a
+ * stream (mirrors `subscription`); the stream tears down when the owning
+ * `DestroyRef` fires. The Angular counterpart to React's `useStream`, re-expressed
+ * with signals.
+ *
+ * Call from an injection context (component/service field or constructor):
+ * ```ts
+ * readonly tokens = stream(api.chat.liveEvents, { key: "thread-1" });
+ * ```
+ * @experimental
+ */
+declare const stream: <F extends FunctionReference<"stream">>(reference: F, args: ArgsOf<F> | "skip", options?: StreamOptions) => StreamResult<ReturnOf<F>>;
+/**
+ * `SubscriptionOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
+interface SubscriptionOptions {
+  /** Client to bind to. Defaults to the injected `LUNORA_CLIENT`. */
+  client?: LunoraClient;
+  /**
+   * `DestroyRef` whose `onDestroy` tears the subscription down. Defaults to
+   * `inject(DestroyRef)` — the calling component/service.
+   */
+  destroyRef?: DestroyRef;
+  /**
+   * Called when the subscription errors after the initial attach. Without it,
+   * a post-attach failure is dropped silently.
+   */
+  onError?: (error: SubscriptionError) => void;
+  /** Route to a specific shard when the target function is `.shardBy(...)`-partitioned. */
+  shardKey?: string;
+}
+/**
+ * `SubscriptionResult` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
+interface SubscriptionResult<T> {
+  /** The latest value pushed by the server. `undefined` before the first frame. */
+  data: Signal<T | undefined>;
+  /** The latest error, or `undefined`. */
+  error: Signal<SubscriptionError | undefined>;
+}
+/**
+ * Subscribe to a reactive server push stream. Returns `{ data, error }` signals
+ * that update whenever the server emits a new value.
+ *
+ * Unlike `liveQuery`, which tracks a single value, `subscription` also
+ * exposes an `error` signal for the async error channel. Use it for ephemeral,
+ * high-frequency streams where you need error visibility.
+ *
+ * Pass `"skip"` as `args` to short-circuit — no network call, no socket.
+ * The subscription tears down when the owning `DestroyRef` fires.
+ *
+ * Call from an injection context (component/service field or constructor):
+ * ```ts
+ * readonly stream = subscription(api.events.stream, { roomId: "general" });
+ * ```
+ * @experimental
+ */
+declare const subscription: <F extends FunctionReference>(reference: F, args: ArgsOf<F> | "skip", options?: SubscriptionOptions) => SubscriptionResult<ReturnOf<F>>;
+/**
+ * Browser Web Audio subsystems for `voiceAgent` — the default microphone capture
+ * and speaker playback implementations injected into the primitive 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
+ * primitive's transport + signal-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 Angular package never pulls in the server-only `@lunora/agent`
+ * module graph.
+ * @experimental
+ */
+type VoiceAudioFormat = "mp3" | "wav";
+/** Captures microphone audio and reports level / turn boundaries back to the primitive. */
+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` while `status === "speaking"` — gates barge-in detection. */
+  isSpeaking: () => 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.&lt;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.&lt;name>Voice` type-checks.
+ * @experimental
+ */
+type VoiceReference = FunctionReference<"stream", {
+  threadKey: string;
+}, Record<string, unknown>>;
+/**
+ * The lifecycle of a voice call, mirrored to the UI.
+ * @experimental
+ */
+type VoiceStatus = "idle" | "listening" | "speaking" | "thinking";
+/** A minimal structural subset of the DOM `WebSocket` the primitive 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;
+/**
+ * `VoiceAgentOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
+interface VoiceAgentOptions {
+  /** Client to bind to. Defaults to the injected `LUNORA_CLIENT`. */
+  client?: LunoraClient;
+  /**
+   * 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 `new WebSocket(url)`. */
+  createSocket?: CreateSocket;
+  /** Advanced/test seam: build the audio playback subsystem. Defaults to a Web Audio implementation. */
+  createSpeaker?: CreateSpeaker;
+  /**
+   * `DestroyRef` whose `onDestroy` tears the call down. Defaults to
+   * `inject(DestroyRef)` — the calling component/service.
+   */
+  destroyRef?: DestroyRef;
+  /** 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. Resolved when the call opens. */
+  threadKey: string;
+  /** The generated `api.agents.&lt;name>Voice` reference — identifies the voice DO endpoint. */
+  voice: VoiceReference;
+}
+/**
+ * `VoiceAgentResult` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
+interface VoiceAgentResult {
+  /** The current input RMS (0–1) — drive a mic level meter. */
+  audioLevel: Signal<number>;
+  /** `true` once the WS `ready` handshake completed. */
+  connected: Signal<boolean>;
+  /** Tear down the call: close the socket, stop the mic, release audio. Idempotent. */
+  endCall: () => void;
+  /** The last transport/pipeline error, or `undefined`. */
+  error: Signal<Error | undefined>;
+  /** The live assistant text for the in-flight turn (grows via deltas; finalized on done). */
+  interimTranscript: Signal<string>;
+  /** `true` while the mic is muted. */
+  isMuted: Signal<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: Signal<VoiceStatus>;
+  /** Mute/unmute the microphone. Returns the new muted state. */
+  toggleMute: () => boolean;
+  /** The last finalized user utterance (STT result). */
+  transcript: Signal<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 Angular signals. Pass the generated `api.agents.&lt;name>Voice`
+ * reference (never a string), matching `agentChat`'s reference-passing style. The
+ * Angular counterpart to React's `useVoiceAgent`, re-expressed with signals; the
+ * per-call connection lives in a closure variable (the primitive runs once per
+ * component, so no signal-of-connection indirection is needed).
+ *
+ * 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 primitive is drivable outside a browser.
+ *
+ * Call from an injection context (component/service field or constructor); pass an
+ * explicit `client` / `destroyRef` to drive it outside one (e.g. in a test).
+ * @experimental
+ */
+declare const voiceAgent: (options: VoiceAgentOptions) => VoiceAgentResult;
+export { type AgentApi, type AgentChatApi, type AgentChatMessage, type AgentChatOptions, type AgentChatResult, type AgentLiveEvent, type AgentOptions, type AgentProgressEvent, type AgentResult, type AgentStateApi, type AgentStateOptions, type AgentStateResult, type AgentThreadRecord, type AgentThreadStatus, type AgentTokenDelta, type AgentTokenStreamReference, type AgentToolEvent, type AgentToolEventsApi, type AgentToolEventsOptions, type AgentToolEventsResult, type AuthGateResult, type AuthOptions, type AuthResult, type ConnectionStatusOptions, type FlagContext, type FlagOptions, type FlagValue, type FlagsOptions, type HeartbeatReference, type HydratePreloadedOptions, type HydratePreloadedResult, type InfiniteQueryResult, LUNORA_CLIENT, type ListPresentReference, type LiveQueryOptions, type MutateOptions, type MutatorResult, type PaginatedQueryOptions, type PaginatedQueryResult, type PresenceOptions, type PresenceResult, type ProvideLunoraOptions, type RateLimitOptions, type RateLimitResult, type StreamOptions, type StreamResult, type StreamStatus, type SubscriptionOptions, type SubscriptionResult, type VoiceAgentOptions, type VoiceAgentResult, type VoiceAudioFormat, type VoiceReference, type VoiceStatus, agent, agentChat, agentState, agentToolEvents, auth, authGate, connectionStatus, flag, flags, hydratePreloaded, infiniteQuery, injectLunoraClient, liveQuery, mutate, mutator, paginatedQuery, presence, provideLunora, rateLimit, stream, subscription, voiceAgent };