@lunora/solid 1.0.0-alpha.11 → 1.0.0-alpha.110

package/dist/index.d.mts

@@ -1,104 +1,614 @@
-import { LunoraClient, User, ConnectionStatus, FunctionReference, ArgsOf, MutationCallOptions, ReturnOf, MutatorHandle, Preloaded } from '@lunora/client';
-export type { ArgsOf, FunctionReference, MutatorHandle, MutatorTransaction, OptimisticUpdate, Preloaded, ReturnOf, Unsubscribe } from '@lunora/client';
-import { Context, JSX, Accessor } from 'solid-js';
+import { LunoraClient, FunctionReference, ArgsOf, ActionCallOptions, ReturnOf, SubscriptionErrorCallback, User, ConnectionStatus, MutationCallOptions, MutatorHandle, SubscriptionError, Preloaded } from '@lunora/client';
+export type { ArgsOf, FunctionReference, MutatorHandle, MutatorTransaction, OptimisticUpdate, Preloaded, ReturnOf, SubscriptionError, SubscriptionErrorCallback, Unsubscribe } from '@lunora/client';
+import { Context, Accessor } from 'solid-js';
+import { AuthStatus } from '@lunora/client/auth';
 import { PaginationStatus } from '@lunora/client/pagination';
 import { RateLimitStatus, RateLimitConfig } from '@lunora/ratelimit';
 /**
-* Solid context carrying the framework-neutral {@link LunoraClient}. Every
-* reactive primitive in this adapter (`createQuery`, `createMutation`,
-* `hydratePreloaded`) reads the client from here, so a single
-* `<LunoraProvider client={…}>` at the root of the tree wires the whole app.
-*
-* Defaults to `undefined` so {@link useLunora} can throw a helpful error when a
-* primitive is used outside a provider rather than dereferencing it.
-*/
+ * Solid context carrying the framework-neutral {@link LunoraClient}. Every
+ * reactive primitive in this adapter (`createQuery`, `createMutation`,
+ * `hydratePreloaded`) reads the client from here, so a single
+ * `<LunoraProvider client={…}>` at the root of the tree wires the whole app.
+ *
+ * Defaults to `undefined` so {@link useLunora} can throw a helpful error when a
+ * primitive is used outside a provider rather than dereferencing it. Solid 2
+ * refuses to hand back an `undefined` default at all — see {@link useLunora}.
+ */
 declare const LunoraContext: Context<LunoraClient | undefined>;
 /**
-* Read the {@link LunoraClient} from the nearest `&lt;LunoraProvider>`.
-*
-* Throws when called outside a provider — the client is required to open the
-* HTTP/WS transport, so there is no sensible fallback. The React adapter's
-* `useLunora` has the same contract.
-*/
+ * Read the {@link LunoraClient} from the nearest `<LunoraProvider>`.
+ *
+ * Throws when called outside a provider — the client is required to open the
+ * HTTP/WS transport, so there is no sensible fallback. The React adapter's
+ * `useLunora` has the same contract.
+ */
 declare const useLunora: () => LunoraClient;
+interface ActionHandle<F extends FunctionReference> {
+  /** Invoke the action. Resolves with the server result; rejects on failure. */
+  call: (args: ArgsOf<F>, options?: ActionCallOptions) => Promise<ReturnOf<F>>;
+  /** The latest invocation's resolved value, or `undefined` before the first success. */
+  data: Accessor<ReturnOf<F> | undefined>;
+  /** The latest invocation's error, or `undefined`. */
+  error: Accessor<Error | undefined>;
+  /** `true` while any invocation from this handle is in flight (ref-counted, so overlapping calls compose). */
+  pending: Accessor<boolean>;
+  /** Clear `data`/`error` back to idle. */
+  reset: () => void;
+}
+/**
+ * The transport surface {@link createAction} actually needs — just
+ * `client.action`. Narrowed so the primitive can be exercised against a stub in
+ * tests without constructing a full `LunoraClient`.
+ */
+interface ActionClient<F extends FunctionReference> {
+  action: (function_: F, args: ArgsOf<F>, options?: ActionCallOptions) => Promise<ReturnOf<F>>;
+}
+/**
+ * Build an action handle bound to an explicit client. Internal seam used by the
+ * provider-bound {@link createAction}; exported for tests that inject a stub.
+ * The ref-counted pending + error-normalize orchestration is the shared
+ * `createCallRunner` from `@lunora/client`; only the reactive sinks (Solid
+ * signals) are adapter-specific.
+ *
+ * `data`/`error` follow the adapter-wide contract: both track the LATEST
+ * invocation (an earlier call settling later cannot clobber a newer one), a
+ * success clears `error`, and a failure leaves the previous `data` in place.
+ * `reset()` clears both; it does not cancel an in-flight call.
+ */
+declare const createActionForClient: <F extends FunctionReference>(client: ActionClient<F>, function_: F) => ActionHandle<F>;
+/**
+ * Returns a reactive handle `{ call, pending, data, error, reset }` for the
+ * given action reference, bound to the `LunoraClient` from the nearest
+ * `<LunoraProvider>`.
+ *
+ * **Narrower than `createMutation` on purpose:** no `optimistic` /
+ * `optimisticUpdate` call options. An optimistic update patches the subscription
+ * cache on the assumption a 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.
+ */
+declare const createAction: <F extends FunctionReference>(function_: F) => ActionHandle<F>;
+/**
+ * The lifecycle status stored on an agent thread. Client-safe mirror of
+ * `@lunora/agent`'s `AgentThreadStatus` — re-declared here (rather than imported)
+ * so this Solid entry never pulls in the server-only `@lunora/agent` module graph
+ * (the adapter stays Solid + `@lunora/client` 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"`. */
+  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;
+}
+/** A plain value or a Solid accessor of it — matching `createQuery`'s reactive-args contract. */
+type MaybeAccessor<T> = Accessor<T> | T;
+/**
+ * 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.
+ */
+interface CreateAgentApi {
+  agents: {
+    agentThread: FunctionReference<"query", {
+      key: string;
+    }, Record<string, unknown> | undefined>;
+  };
+}
+interface CreateAgentOptions {
+  /** The generated `api` — its `agents.agentThread` query drives live thread state. */
+  api: CreateAgentApi;
+  /**
+   * 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 CreateAgentResult.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` are cleared until a later frame arrives.
+   */
+  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 CreateAgentOptions.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 — a plain value or accessor (an accessor re-subscribes on change). */
+  threadKey: MaybeAccessor<string>;
+}
+interface CreateAgentResult {
+  /**
+   * 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: Accessor<Error | undefined>;
+  /** `true` while a `run` invocation is in flight. */
+  pending: Accessor<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: Accessor<AgentThreadStatus | undefined>;
+  /** The live thread record (status, `instanceId`, …), or `undefined` before it exists. */
+  thread: Accessor<AgentThreadRecord | undefined>;
+}
+/**
+ * A thin agent handle: live thread `status` plus `run` / `cancel`, without the
+ * chat message surface. Composes `createSubscription(api.agents.agentThread)` for
+ * live state and `createMutation` for the run/cancel writes — the Solid
+ * counterpart to React's `useAgent`, re-expressed with signals. For the full
+ * conversation surface (durable history + streaming + approvals) use
+ * `createAgentChat`.
+ *
+ * `run` and `cancel` stay generic over the app-defined mutations that wrap
+ * `ctx.agents.<name>.run` / `.cancel`, so the primitive hard-codes no function
+ * names beyond the `agents:*` surface. `threadKey` may be an accessor — a changing
+ * key re-subscribes to the new thread.
+ */
+declare const createAgent: (options: CreateAgentOptions) => CreateAgentResult;
+/**
+ * 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 Solid 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;
+}
+/**
+ * A live token delta streamed while a turn is generating. Client-safe mirror of
+ * `@lunora/agent`'s `AgentTokenDelta`. Ephemeral — deltas feed
+ * {@link CreateAgentChatResult.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 `createAgentToolEvents`, ignored by {@link CreateAgentChatResult.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 primitive consumes only the token arm.
+ */
+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.
+ */
+interface CreateAgentChatApi {
+  agents: {
+    agentMessages: AgentMessagesReference$1;
+    agentResolveApproval: AgentApprovalReference;
+    agentThread: AgentThreadReference;
+  };
+}
+interface CreateAgentChatOptions {
+  /** The generated `api` — its `agents.*` surface provides history, thread state, and approval resolution. */
+  api: CreateAgentChatApi;
+  /**
+   * 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 CreateAgentChatResult.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` are cleared until a later frame arrives.
+   */
+  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 CreateAgentChatOptions.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 CreateAgentChatResult.streamingText}
+   * stays empty and the UI updates message-by-message from durable history.
+   */
+  stream?: AgentTokenStreamReference;
+  /** The thread to observe and continue — a plain value or accessor (an accessor re-subscribes on change). */
+  threadKey: MaybeAccessor<string>;
+}
+interface CreateAgentChatResult {
+  /** 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: Accessor<Error | undefined>;
+  /** Durable thread history (oldest first) plus any un-acknowledged optimistic user turns. */
+  messages: Accessor<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: Accessor<AgentThreadStatus | undefined>;
+  /** The in-flight turn's streamed text — live-only, empty once the turn persists to `messages`. */
+  streamingText: Accessor<string>;
+}
+/**
+ * A first-class agent chat surface: live durable history + in-flight token
+ * streaming + the send / approve / reject / cancel writes, keyed by `threadKey` —
+ * the Solid counterpart to React's `useAgentChat`, re-expressed with signals.
+ *
+ * It composes the existing primitives rather than adding transport:
+ * `createSubscription(api.agents.agentMessages)` for durable history,
+ * `createSubscription(api.agents.agentThread)` for live status + the in-flight
+ * `instanceId`, {@link createStream} over an app token stream for in-flight deltas,
+ * and `createMutation` 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 createAgentChat: (options: CreateAgentChatOptions) => CreateAgentChatResult;
+/**
+ * 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 `CreateAgentApi` 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).
+ */
+interface CreateAgentStateApi {
+  agents: {
+    agentState: FunctionReference<"query", {
+      key: string;
+    }, Record<string, unknown> | undefined>;
+  };
+}
+interface CreateAgentStateOptions {
+  /** The generated `api` — its `agents.agentState` query drives live thread state. */
+  api: CreateAgentStateApi;
+  /** The thread whose synced state to observe — a plain value or accessor (an accessor re-subscribes on change). */
+  threadKey: MaybeAccessor<string>;
+}
+interface CreateAgentStateResult<T> {
+  /** The subscription error, if the live channel reported one. */
+  error: Accessor<Error | undefined>;
+  /** The live synced state, or `undefined` before it is seeded/first pushed. */
+  state: Accessor<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 `createSubscription(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 Solid counterpart to React's
+ * `useAgentState`, re-expressed with signals.
+ *
+ * Generic over the app's state shape (`createAgentState` 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 so the
+ * reference's optional-record return casts cleanly to `T`.
+ */
+declare const createAgentState: <T extends Record<string, unknown> = Record<string, unknown>>(options: CreateAgentStateOptions) => CreateAgentStateResult<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.
+ */
+interface CreateAgentToolEventsApi {
+  agents: {
+    agentMessages: AgentMessagesReference;
+  };
+}
+interface CreateAgentToolEventsOptions {
+  /** The generated `api` — its `agents.agentMessages` query provides the durable tool lifecycle. */
+  api: CreateAgentToolEventsApi;
+  /** History depth forwarded to `agents:agentMessages`. */
+  limit?: number;
+  /**
+   * Optional live event stream — the same app stream function `createAgentChat`
+   * 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 — a plain value or accessor (an accessor re-subscribes on change). */
+  threadKey: MaybeAccessor<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 CreateAgentToolEventsResult {
+  /**
+   * 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: Accessor<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 Solid counterpart to React's
+ * `useAgentToolEvents`, re-expressed as a memo.
+ *
+ * It composes the existing primitives rather than adding transport:
+ * `createSubscription(api.agents.agentMessages)` for the durable lifecycle and
+ * {@link createStream} 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 `createAgentChat`; this primitive is the tool-observability slice.
+ */
+declare const createAgentToolEvents: (options: CreateAgentToolEventsOptions) => CreateAgentToolEventsResult;
+/**
+ * Children accepted by this adapter's components.
+ *
+ * Structurally identical to Solid 2.0's `Element`, which is in turn a widening
+ * of 1.x's `JSX.Element` (a DOM `Node` satisfies `object` with no
+ * `call`/`apply`/`bind`). Children are contravariant, so one union that accepts
+ * both majors' element types is enough — no `any` required here.
+ */
+type SolidChildren = SolidChildrenArray | boolean | null | number | (object & {
+  readonly apply?: never;
+  readonly bind?: never;
+  readonly call?: never;
+}) | (string & {}) | undefined;
+interface SolidChildrenArray extends Array<SolidChildren> {}
+/**
+ * The return type of this adapter's components.
+ *
+ * Deliberately `any`, and the one place in the package where that is the right
+ * answer. TypeScript checks a component's return type against the *renderer's*
+ * `JSX.Element`, and the two majors define that incompatibly — 1.x's is rooted
+ * in the DOM `Node` interface, 2.0's in an opaque `RenderedElement`. Neither is
+ * assignable to the other, so no concrete type satisfies both, and a structural
+ * union (as used for {@link SolidChildren}) fails in the return position. `any`
+ * is what lets one set of `.d.ts` files type-check inside a 1.x app and a 2.x
+ * app alike.
+ */
+type SolidElement = any;
 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: Accessor<AuthStatus>;
   token: Accessor<string | null>;
   user: Accessor<User | null>;
 }
 /**
-* Token + identity plumbing for Solid. Returns `{ token, user, setToken }`
-* where `token` and `user` are fine-grained signals. `setToken(jwt)` after
-* sign-in updates the shared client token; `user` resolves asynchronously via
-* `client.getCurrentUser()` and updates on every token change.
-*/
+ * Token + identity plumbing for Solid. Returns `{ token, user, setToken }`
+ * where `token` and `user` are fine-grained signals. `setToken(jwt)` after
+ * sign-in updates the shared client token; `user` resolves asynchronously via
+ * `client.getCurrentUser()` and updates on every token change.
+ */
 declare const createAuth: () => UseAuthResult;
 interface AuthGateProps {
-  children: JSX.Element;
-}
-/**
-* Render `children` only after authentication has settled and a token + user
-* are both present.
-*/
-declare const Authenticated: (props: AuthGateProps) => JSX.Element;
-/**
-* Render `children` while authentication is still in progress — token is set
-* but the user has not yet resolved.
-*/
-declare const AuthLoading: (props: AuthGateProps) => JSX.Element;
-/**
-* Render `children` only when auth has settled and no token is present (the
-* signed-out state).
-*/
-declare const Unauthenticated: (props: AuthGateProps) => JSX.Element;
-/**
-* Reactive accessor 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`) — Solid's
-* fine-grained signals mean only the components that read the accessor
-* re-render. The Solid equivalent of `@lunora/react`'s `useConnectionStatus`.
-*
-* The status listener is torn down via `onCleanup` when the owning reactive
-* scope disposes (component unmount). Call inside a component / reactive root.
-*/
+  children: SolidChildren;
+}
+/** An auth-gate component: renders its children only while the gate's condition holds. */
+type AuthGate = (props: AuthGateProps) => SolidElement;
+/**
+ * Render `children` once authentication has settled in the caller's favour — a
+ * credential is held and nothing has contradicted it.
+ *
+ * Gated on the shared `AuthStatus` contract in `@lunora/client/auth`, not on
+ * `user() !== null`: an unreachable identity endpoint leaves `user` at `null`
+ * while the credential is still perfectly valid.
+ */
+declare const Authenticated: AuthGate;
+/**
+ * Render `children` while authentication is still in progress — a credential is
+ * held and the first identity resolve has not come back yet.
+ */
+declare const AuthLoading: AuthGate;
+/**
+ * Render `children` only when auth has settled and there is no session — no
+ * credential, or the server answered that the credential has none.
+ */
+declare const Unauthenticated: AuthGate;
+/**
+ * Reactive accessor 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`) — Solid's
+ * fine-grained signals mean only the components that read the accessor
+ * re-render. The Solid equivalent of `@lunora/react`'s `useConnectionStatus`.
+ *
+ * The listener is registered at **mount**, not in the component body, because
+ * `onConnectionStatus` invokes it synchronously on subscribe: Solid 2 rejects a
+ * signal write inside an owned scope (`REACTIVE_WRITE_IN_OWNED_SCOPE`) and — since
+ * the throw escapes render — halts the reactive system for the whole page, not
+ * just this component. Nothing is missed by waiting: the initial value comes
+ * from `client.connectionStatus()`, and the immediate callback re-syncs at
+ * mount. Torn down when the owning scope disposes. Call inside a component /
+ * reactive root.
+ */
 declare const createConnectionStatus: () => Accessor<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;
-/** A plain value or a Solid accessor of it — matching `createQuery`'s reactive-args contract. */
-type MaybeAccessor<T> = Accessor<T> | T;
 /**
-* Subscribe to a single feature flag and return a reactive accessor of its value.
-*
-* The accessor reads `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 `createFlag("dark", false)` reads a boolean
-* and `createFlag("hero", "control")` a string.
-*
-* `key` and `context` may be plain values or accessors; passing an accessor makes
-* the subscription reactive — when it changes the old subscription is torn down
-* (via `onCleanup`) and a fresh one opens. `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 createFlag: <T extends FlagValue>(key: MaybeAccessor<string>, defaultValue: T, context?: MaybeAccessor<FlagContext | undefined>) => Accessor<T>;
-/**
-* Subscribe to several feature flags at once and return a reactive accessor of
-* the resolved record.
-*
-* Pass a record of `key → defaultValue`; each flag's kind is inferred from its
-* default, and the accessor reads the same-shaped record with resolved values
-* (the defaults until each evaluation lands). A single `context` applies to every
-* flag and may be an accessor. This is the batched form of {@link createFlag}.
-*/
-declare const createFlags: <T extends Record<string, FlagValue>>(flags: T, context?: MaybeAccessor<FlagContext | undefined>) => Accessor<T>;
+ * Subscribe to a single feature flag and return a reactive accessor of its value.
+ *
+ * The accessor reads `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 `createFlag("dark", false)` reads a boolean
+ * and `createFlag("hero", "control")` a string.
+ *
+ * `key` may be a plain value or an accessor; passing an accessor makes the
+ * subscription reactive — when it changes the old subscription is torn down (via
+ * `onCleanup`) and a fresh one opens.
+ *
+ * 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 createFlag: <T extends FlagValue>(key: MaybeAccessor<string>, defaultValue: T) => Accessor<T>;
+/**
+ * Subscribe to several feature flags at once and return a reactive accessor of
+ * the resolved record.
+ *
+ * Pass a record of `key → defaultValue`; each flag's kind is inferred from its
+ * default, and the accessor reads the same-shaped record with resolved values
+ * (the defaults until each evaluation lands). This is the batched form of
+ * {@link createFlag}, and evaluates under the socket's server-verified identity
+ * only. The flag set is fixed for the primitive's lifetime, so nothing here is
+ * reactive — the subscriptions open on mount and tear down on cleanup.
+ */
+declare const createFlags: <T extends Record<string, FlagValue>>(flags: T) => Accessor<T>;
 interface MutationHandle<F extends FunctionReference> {
   /** The latest invocation's resolved value, or `undefined` before the first success. */
   data: Accessor<ReturnOf<F> | undefined>;
@@ -112,44 +622,49 @@ interface MutationHandle<F extends FunctionReference> {
   reset: () => void;
 }
 /**
-* The transport surface {@link createMutation} actually needs — just
-* `client.mutation`. Narrowed so the primitive can be exercised against a stub
-* in tests without constructing a full `LunoraClient`.
-*/
+ * The transport surface {@link createMutation} actually needs — just
+ * `client.mutation`. Narrowed so the primitive can be exercised against a stub
+ * in tests without constructing a full `LunoraClient`.
+ */
 interface MutationClient<F extends FunctionReference> {
   mutation: (function_: F, args: ArgsOf<F>, options?: MutationCallOptions<unknown, unknown, ArgsOf<F>>) => Promise<ReturnOf<F>>;
 }
 /**
-* Build a mutation handle bound to an explicit client. Internal seam used by the
-* provider-bound {@link createMutation}; exported for tests that inject a stub.
-* The ref-counted pending + error-normalize orchestration is the shared
-* `createMutationRunner` from `@lunora/client`; only the reactive sinks (Solid
-* signals) are adapter-specific.
-*/
+ * Build a mutation handle bound to an explicit client. Internal seam used by the
+ * provider-bound {@link createMutation}; exported for tests that inject a stub.
+ * The ref-counted pending + error-normalize orchestration is the shared
+ * `createCallRunner` from `@lunora/client`; only the reactive sinks (Solid
+ * signals) are adapter-specific.
+ *
+ * `data`/`error` follow the adapter-wide contract: both track the LATEST
+ * invocation (an earlier call settling later cannot clobber a newer one), a
+ * success clears `error`, and a failure leaves the previous `data` in place.
+ * `reset()` clears both; it does not cancel an in-flight call.
+ */
 declare const createMutationForClient: <F extends FunctionReference>(client: MutationClient<F>, function_: F) => MutationHandle<F>;
 /**
-* Returns a reactive handle `{ mutate, pending, data, error, reset }` for the
-* given mutation reference, bound to the `LunoraClient` from the nearest
-* `&lt;LunoraProvider>`.
-*
-* 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 Lunora subscription cache — the same
-* machinery `createQuery`/`hydratePreloaded` subscribe to, so an optimistic
-* write reflects in those accessors immediately and reverts on failure.
-*
-* `pending` is ref-counted across overlapping invocations of *this* handle, so
-* it only flips back to `false` once every concurrent call has settled. The
-* mutation also engages `@lunora/client`'s offline queue when the socket is
-* down, so `mutate` stays durable across reconnects.
-*/
+ * Returns a reactive handle `{ mutate, pending, data, error, reset }` for the
+ * given mutation reference, bound to the `LunoraClient` from the nearest
+ * `<LunoraProvider>`.
+ *
+ * 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 Lunora subscription cache — the same
+ * machinery `createQuery`/`hydratePreloaded` subscribe to, so an optimistic
+ * write reflects in those accessors immediately and reverts on failure.
+ *
+ * `pending` is ref-counted across overlapping invocations of *this* handle, so
+ * it only flips back to `false` once every concurrent call has settled. The
+ * mutation also engages `@lunora/client`'s offline queue when the socket is
+ * down, so `mutate` stays durable across reconnects.
+ */
 declare const createMutation: <F extends FunctionReference>(function_: F) => MutationHandle<F>;
 /**
-* The reactive handle returned by {@link createMutator} — the Solid counterpart
-* to `@lunora/react`'s `useMutator`, re-expressed with signals.
-* `error`/`isError`/`pending` are accessors and `mutate` is an awaitable that
-* resolves once the write is persisted (or rejects).
-*/
+ * The reactive handle returned by {@link createMutator} — the Solid counterpart
+ * to `@lunora/react`'s `useMutator`, re-expressed with signals.
+ * `error`/`isError`/`pending` are accessors and `mutate` is an awaitable that
+ * resolves once the write is persisted (or rejects).
+ */
 interface MutatorHook<TArgs> {
   /** The latest invocation's error, or `undefined`. */
   error: Accessor<Error | undefined>;
@@ -163,18 +678,18 @@ interface MutatorHook<TArgs> {
   reset: () => void;
 }
 /**
-* Ergonomic `{ mutate, pending, error, isError, reset }` wrapper over a bound
-* custom-mutator handle from `@lunora/db`'s `bindMutators` — the Solid
-* equivalent of `@lunora/react`'s `useMutator`. 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 primitive only surfaces signal state for the in-flight/error lifecycle.
-* Reads stay on the existing TanStack `useLiveQuery`; no new query primitive is
-* needed.
-*
-* `pending` is ref-counted across overlapping invocations of THIS handle, 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 Solid
+ * equivalent of `@lunora/react`'s `useMutator`. 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 primitive only surfaces signal state for the in-flight/error lifecycle.
+ * Reads stay on the existing TanStack `useLiveQuery`; no new query primitive is
+ * needed.
+ *
+ * `pending` is ref-counted across overlapping invocations of THIS handle, so it
+ * clears only once every concurrent call has settled.
+ */
 declare const createMutator: <TArgs = Record<string, unknown>>(handle: MutatorHandle<TArgs>) => MutatorHook<TArgs>;
 /** The args a paginated query exposes minus the framework-supplied page cursor. */
 type PaginatedArgs<F extends FunctionReference> = Omit<ArgsOf<F>, "paginationOpts">;
@@ -185,9 +700,18 @@ type PageItemOf<F extends FunctionReference> = ReturnOf<F> extends {
 interface CreatePaginatedQueryOptions {
   /** Page size for the first page (and the default for `loadMore`). */
   initialNumItems: number;
+  /** Called when a page subscription reports an error (also surfaced on the `error` accessor). */
+  onError?: SubscriptionErrorCallback;
   shardKey?: string;
 }
 interface CreatePaginatedQueryResult<T> {
+  /**
+   * The last page subscription error, or `undefined`. A tail page that fails
+   * before its first frame is dropped so `status` returns to `"CanLoadMore"`
+   * and `loadMore` can retry it; cleared by the next successful frame,
+   * `loadMore`, or an args change.
+   */
+  error: Accessor<SubscriptionError | undefined>;
   /** `true` while the first page or a `loadMore` page is in flight. */
   isLoading: Accessor<boolean>;
   /** Request the next page. A no-op unless `status === "CanLoadMore"`. */
@@ -199,9 +723,13 @@ interface CreatePaginatedQueryResult<T> {
 interface CreateInfiniteQueryOptions {
   /** Page size for the first page (and the default for `fetchNextPage`). */
   initialNumItems: number;
+  /** Called when a page subscription reports an error (also surfaced on the `error` accessor). */
+  onError?: SubscriptionErrorCallback;
   shardKey?: string;
 }
 interface CreateInfiniteQueryResult<T> {
+  /** The last page subscription error, or `undefined` — see `CreatePaginatedQueryResult.error`. */
+  error: Accessor<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. */
@@ -215,46 +743,46 @@ interface CreateInfiniteQueryResult<T> {
   status: Accessor<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`. `loadMore` appends the next
-* page off the open-ended tail's `continueCursor`; it is a no-op unless
-* `status === "CanLoadMore"`.
-*
-* Call inside a reactive context (component / `createRoot`).
-*/
+ * 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`. `loadMore` appends the next
+ * page off the open-ended tail's `continueCursor`; it is a no-op unless
+ * `status === "CanLoadMore"`.
+ *
+ * Call inside a reactive context (component / `createRoot`).
+ */
 declare const createPaginatedQuery: <F extends FunctionReference>(function_: F, args: "skip" | Accessor<"skip" | PaginatedArgs<F>> | PaginatedArgs<F>, options: CreatePaginatedQueryOptions) => CreatePaginatedQueryResult<PageItemOf<F>>;
 /**
-* Subscribe to a reactively-paginated query and expose its pages discretely.
-*
-* Shares `createPaginatedQuery`'s pagination engine but keeps each page as its
-* own inner array (TanStack-Query-style `fetchNextPage` / `hasNextPage` shape).
-*
-* Call inside a reactive context (component / `createRoot`).
-*/
+ * Subscribe to a reactively-paginated query and expose its pages discretely.
+ *
+ * Shares `createPaginatedQuery`'s pagination engine but keeps each page as its
+ * own inner array (TanStack-Query-style `fetchNextPage` / `hasNextPage` shape).
+ *
+ * Call inside a reactive context (component / `createRoot`).
+ */
 declare const createInfiniteQuery: <F extends FunctionReference>(function_: F, args: "skip" | Accessor<"skip" | PaginatedArgs<F>> | PaginatedArgs<F>, options: CreateInfiniteQueryOptions) => CreateInfiniteQueryResult<PageItemOf<F>>;
 /**
-* `createPresence` — 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 inside a reactive context (component / `createRoot`).
-*/
-/**
-* A heartbeat mutation reference: takes `{ roomId, sessionId, data? }`.
-*/
+ * `createPresence` — 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 inside a reactive context (component / `createRoot`).
+ */
+/**
+ * A heartbeat mutation reference: takes `{ roomId, sessionId, data? }`.
+ */
 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;
 }>;
@@ -268,14 +796,22 @@ interface CreatePresenceOptions<H extends HeartbeatReference, L extends ListPres
   /** The `api.*` reference for the presence listPresent query. */
   listPresent: L;
   /**
-  * Stable id for this presence row. Defaults to a fresh per-mount id.
-  * Pass a user/connection id to control deduping across tabs.
-  */
+   * 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` is cleared until a later frame arrives.
+   */
+  onError?: SubscriptionErrorCallback;
+  /**
+   * Stable id for this presence row. Defaults to a fresh per-mount 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;
 }
 interface CreatePresenceResult<L extends ListPresentReference> {
+  /** The `listPresent` subscription's last error, or `undefined`. */
+  error: () => SubscriptionError | undefined;
   /** The present members for the room. `undefined` until the first push. */
   present: () => ReturnOf<L> | undefined;
   /** This mount's session id (generated when not supplied). */
@@ -285,35 +821,46 @@ interface CreatePresenceResult<L extends ListPresentReference> {
 }
 declare const createPresence: <H extends HeartbeatReference, L extends ListPresentReference>(roomId: string, options: CreatePresenceOptions<H, L>) => CreatePresenceResult<L>;
 interface CreateQueryOptions {
+  /**
+   * 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 accessor simply freezes at its last good value.
+   */
+  onError?: SubscriptionErrorCallback;
   /** Route to a specific shard when the target function is `.shardBy(...)`-partitioned. */
   shardKey?: string;
 }
 /**
-* Subscribe to a server query and return a reactive accessor of its value.
-*
-* The accessor reads `undefined` until the first server frame lands, then
-* updates on every delta the WebSocket pushes — Solid's fine-grained signals
-* mean only the components that read the accessor re-render, which maps cleanly
-* onto Lunora's per-subscription delta model.
-*
-* `args` may be a plain value or an accessor; passing an accessor makes the
-* subscription reactive — when the args change the old subscription is torn down
-* (via `onCleanup`) and a fresh one opens for the new args. Pass `"skip"` (or an
-* accessor returning `"skip"`) to short-circuit: no network call, no socket.
-*
-* ```tsx
-* const messages = createQuery(api.messages.list, () => ({ channelId: channelId() }));
-* return &lt;For each={messages()?.messages}>{(m) => &lt;li>{m.text}&lt;/li>}&lt;/For>;
-* ```
-*/
+ * Subscribe to a server query and return a reactive accessor of its value.
+ *
+ * The accessor reads `undefined` until the first server frame lands, then
+ * updates on every delta the WebSocket pushes — Solid's fine-grained signals
+ * mean only the components that read the accessor re-render, which maps cleanly
+ * onto Lunora's per-subscription delta model.
+ *
+ * `args` may be a plain value or an accessor; passing an accessor makes the
+ * subscription reactive — when the args change the old subscription is torn down
+ * (via `onCleanup`), the accessor resets to `undefined`, and a fresh one opens for
+ * the new args. Pass `"skip"` (or an
+ * accessor returning `"skip"`) to short-circuit: no network call, no socket.
+ *
+ * ```tsx
+ * const messages = createQuery(api.messages.list, () => ({ channelId: channelId() }));
+ * return <For each={messages()?.messages}>{(m) => <li>{m.text}</li>}</For>;
+ * ```
+ *
+ * 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 accessor just freezes at its last good value.
+ */
 declare const createQuery: <F extends FunctionReference>(function_: F, args: (ArgsOf<F> | "skip") | Accessor<ArgsOf<F> | "skip">, options?: CreateQueryOptions) => Accessor<ReturnOf<F> | undefined>;
 interface CreateRateLimitOptions {
   /** Clock injection for tests. Defaults to `Date.now`. */
   now?: () => number;
   /**
-  * Re-evaluation cadence in milliseconds while throttled, so `retryAfter`
-  * ticks down and `disabled` flips back automatically. Defaults to `1000`.
-  */
+   * Re-evaluation cadence in milliseconds while throttled, so `retryAfter`
+   * ticks down and `disabled` flips back automatically. Defaults to `1000`.
+   */
   tickMs?: number;
 }
 interface CreateRateLimitResult {
@@ -331,78 +878,314 @@ interface CreateRateLimitResult {
   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 call; pass a stable reference (module constant) so
-* the derived memos stay settled.
-*/
+ * 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 call; pass a stable reference (module constant) so
+ * the derived memos stay settled.
+ */
 declare const createRateLimit: (config: RateLimitConfig, options?: CreateRateLimitOptions) => CreateRateLimitResult;
+/** The lifecycle of a stream the primitive is observing. */
+type CreateStreamStatus = "complete" | "error" | "idle" | "streaming";
+interface CreateStreamResult<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: Accessor<ReadonlyArray<T>>;
+  error: Accessor<Error | undefined>;
+  status: Accessor<CreateStreamStatus>;
+}
+interface CreateStreamOptions {
+  /**
+   * Opt into resume-on-reconnect for a stream the server declared `durable`.
+   * The chunks already received are kept 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, all as accessors. Changing the
+ * resolved `args` resets the stream — the previous iterator is cancelled and a
+ * fresh one opens with empty `chunks`.
+ *
+ * `args` may be a plain value or an accessor; resolving it to `"skip"` keeps the
+ * primitive mounted without opening a stream (mirrors `createSubscription`). The
+ * Solid counterpart to React's `useStream`, re-expressed with signals.
+ */
+declare const createStream: <F extends FunctionReference<"stream">>(function_: F, args: ArgsOf<F> | "skip" | Accessor<ArgsOf<F> | "skip">, options?: CreateStreamOptions) => CreateStreamResult<ReturnOf<F>>;
 interface CreateSubscriptionResult<T> {
   data: Accessor<T | undefined>;
   error: Accessor<Error | undefined>;
 }
 /**
-* Subscribe to a reactive server push stream. Returns `{ data, error }`
-* accessors that update whenever the server emits. Passing `"skip"` as `args`
-* (or an accessor that resolves to `"skip"`) tears down the subscription.
-*/
+ * Subscribe to a reactive server push stream. Returns `{ data, error }`
+ * accessors that update whenever the server emits. Passing `"skip"` as `args`
+ * (or an accessor that resolves to `"skip"`) tears down the subscription.
+ *
+ * `onError` mirrors the other adapters' subscription primitives: it receives the
+ * raw wire-level subscription error (code included) alongside the normalised
+ * `error` accessor.
+ */
 declare const createSubscription: <F extends FunctionReference>(function_: F, args: ArgsOf<F> | "skip" | Accessor<ArgsOf<F> | "skip">, options?: {
+  onError?: SubscriptionErrorCallback;
   shardKey?: string;
 }) => CreateSubscriptionResult<ReturnOf<F>>;
 /**
-* Hydrate a query from a {@link Preloaded} token produced by `preloadQuery`
-* during SSR, then keep it live.
-*
-* This is the client half of PLAN4's "your loaders are live" handoff. The
-* returned accessor is seeded **synchronously** from `preloaded.value`, so the
-* very first read — during hydration — returns the server-rendered value with
-* no loading flash and no `Suspense` fallback (unlike `createResource`, which
-* always starts pending). After the component mounts, a WebSocket subscription
-* attaches in an effect and every subsequent server delta flows into the same
-* signal, so the UI goes live with zero refetch.
-*
-* ```tsx
-* // route loader (server): const preloaded = await preloadQuery(client, api.messages.list, args);
-* const messages = hydratePreloaded(preloaded); // seeded from SSR, then live
-* return &lt;pre>{JSON.stringify(messages())}&lt;/pre>;
-* ```
-*
-* Effects do not run on the server during SSR (Solid only runs them after
-* hydration), so the subscription is strictly client-side — the seed is the
-* only value the server render ever sees.
-*/
-declare const hydratePreloaded: <T>(preloaded: Preloaded<T>) => Accessor<T>;
+ * Browser Web Audio subsystems for `createVoiceAgent` — 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 + reactive-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 Solid 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 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` 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 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;
+interface CreateVoiceAgentOptions {
+  /**
+   * 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. May be a plain value or accessor (resolved when the call opens). */
+  threadKey: MaybeAccessor<string>;
+  /** The generated `api.agents.<name>Voice` reference — identifies the voice DO endpoint. */
+  voice: VoiceReference;
+}
+interface CreateVoiceAgentResult {
+  /** The current input RMS (0–1) — drive a mic level meter. */
+  audioLevel: Accessor<number>;
+  /** `true` once the WS `ready` handshake completed. */
+  connected: Accessor<boolean>;
+  /** Tear down the call: close the socket, stop the mic, release audio. Idempotent. */
+  endCall: () => void;
+  /** The last transport/pipeline error, or `undefined`. */
+  error: Accessor<Error | undefined>;
+  /** The live assistant text for the in-flight turn (grows via deltas; finalized on done). */
+  interimTranscript: Accessor<string>;
+  /** `true` while the mic is muted. */
+  isMuted: Accessor<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: Accessor<VoiceStatus>;
+  /** Mute/unmute the microphone. Returns the new muted state. */
+  toggleMute: () => boolean;
+  /** The last finalized user utterance (STT result). */
+  transcript: Accessor<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 Solid signals. Pass the generated `api.agents.<name>Voice`
+ * reference (never a string), matching `createAgentChat`'s reference-passing style.
+ * The Solid counterpart to React's `useVoiceAgent`, re-expressed with signals; the
+ * per-call connection lives in a closure variable (a primitive runs once per
+ * component, so no signal-of-signal 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.
+ */
+declare const createVoiceAgent: (options: CreateVoiceAgentOptions) => CreateVoiceAgentResult;
+/**
+ * Hydrate a query from a {@link Preloaded} token produced by `preloadQuery`
+ * during SSR, then keep it live.
+ *
+ * This is the client half of PLAN4's "your loaders are live" handoff. The
+ * returned accessor is seeded **synchronously** from `preloaded.value`, so the
+ * very first read — during hydration — returns the server-rendered value with
+ * no loading flash and no `Suspense` fallback (unlike `createResource`, which
+ * always starts pending). Once the component mounts, a WebSocket subscription
+ * attaches and every subsequent server delta flows into the same signal, so the
+ * UI goes live with zero refetch.
+ *
+ * ```tsx
+ * // route loader (server): const preloaded = await preloadQuery(client, api.messages.list, args);
+ * const messages = hydratePreloaded(preloaded); // seeded from SSR, then live
+ * return <pre>{JSON.stringify(messages())}</pre>;
+ * ```
+ *
+ * Mount callbacks do not run on the server during SSR (both Solid majors defer
+ * them until after hydration), so the subscription is strictly client-side —
+ * the seed is the only value the server render ever sees.
+ *
+ * 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
+ * accessor keeps rendering the SSR snapshot as if it were live.
+ */
+declare const hydratePreloaded: <T>(preloaded: Preloaded<T>, options?: {
+  onError?: SubscriptionErrorCallback;
+}) => Accessor<T>;
 interface LunoraProviderProps {
-  children: JSX.Element;
+  children: SolidChildren;
   /**
-  * The framework-neutral transport. Build it once at the app root with
-  * `new LunoraClient({ url })` (or `createServerClient` during SSR) and pass
-  * it here — the provider does not own its lifecycle, so the same instance
-  * survives across route navigations.
-  */
+   * The framework-neutral transport. Build it once at the app root with
+   * `new LunoraClient({ url })` (or `createServerClient` during SSR) and pass
+   * it here — the provider does not own its lifecycle, so the same instance
+   * survives across route navigations.
+   */
   client: LunoraClient;
 }
 /**
-* Provides a {@link LunoraClient} to the Solid tree via {@link LunoraContext}.
-*
-* Solid's context is reactive-graph scoped rather than render scoped, so unlike
-* the React provider there is no QueryClient to detect or lazily create — the
-* adapter's reactive primitives (`createQuery`, `createMutation`,
-* `hydratePreloaded`) own their own signals and read the client straight from
-* context. Drop one of these at the root of your app:
-*
-* ```tsx
-* const client = new LunoraClient({ url: window.location.origin });
-*
-* render(() => (
-*     &lt;LunoraProvider client={client}>
-*         &lt;App />
-*     &lt;/LunoraProvider>
-* ), root);
-* ```
-*/
-declare const LunoraProvider: (props: LunoraProviderProps) => JSX.Element;
-export { AuthLoading, Authenticated, type CreateInfiniteQueryOptions, type CreateInfiniteQueryResult, type CreatePaginatedQueryOptions, type CreatePaginatedQueryResult, type CreatePresenceOptions, type CreatePresenceResult, type CreateQueryOptions, type CreateRateLimitOptions, type CreateRateLimitResult, type CreateSubscriptionResult, type FlagContext, type FlagValue, type HeartbeatReference, type ListPresentReference, LunoraContext, LunoraProvider, type LunoraProviderProps, type MutationClient, type MutationHandle, type MutatorHook, type PageItemOf, type PaginatedArgs, Unauthenticated, type UseAuthResult, createAuth, createConnectionStatus, createFlag, createFlags, createInfiniteQuery, createMutation, createMutationForClient, createMutator, createPaginatedQuery, createPresence, createQuery, createRateLimit, createSubscription, hydratePreloaded, useLunora };
+ * Provides a {@link LunoraClient} to the Solid tree via {@link LunoraContext}.
+ *
+ * Solid's context is reactive-graph scoped rather than render scoped, so unlike
+ * the React provider there is no QueryClient to detect or lazily create — the
+ * adapter's reactive primitives (`createQuery`, `createMutation`,
+ * `hydratePreloaded`) own their own signals and read the client straight from
+ * context. Drop one of these at the root of your app:
+ *
+ * ```tsx
+ * const client = new LunoraClient({ url: window.location.origin });
+ *
+ * render(() => (
+ *     <LunoraProvider client={client}>
+ *         <App />
+ *     </LunoraProvider>
+ * ), root);
+ * ```
+ *
+ * Written with `createComponent` rather than JSX on purpose. Solid 1.x and 2.0
+ * compile JSX against different runtimes (`solid-js/web` vs `@solidjs/web`), so
+ * a JSX source file would force this package to ship two builds; `createComponent`
+ * is exported from the `solid-js` root in both majors, and the provider component
+ * itself is resolved per-major by {@link providerOf}. The `get` accessors keep
+ * both props lazy, so swapping the `client` prop re-provides the new value to
+ * descendants exactly as the JSX form did.
+ */
+declare const LunoraProvider: (props: LunoraProviderProps) => SolidElement;
+export { type ActionClient, type ActionHandle, type AgentChatMessage, type AgentLiveEvent, type AgentProgressEvent, type AgentThreadRecord, type AgentThreadStatus, type AgentTokenDelta, type AgentToolEvent, AuthLoading, Authenticated, type CreateAgentApi, type CreateAgentChatApi, type CreateAgentChatOptions, type CreateAgentChatResult, type CreateAgentOptions, type CreateAgentResult, type CreateAgentStateApi, type CreateAgentStateOptions, type CreateAgentStateResult, type CreateAgentToolEventsApi, type CreateAgentToolEventsOptions, type CreateAgentToolEventsResult, type CreateInfiniteQueryOptions, type CreateInfiniteQueryResult, type CreatePaginatedQueryOptions, type CreatePaginatedQueryResult, type CreatePresenceOptions, type CreatePresenceResult, type CreateQueryOptions, type CreateRateLimitOptions, type CreateRateLimitResult, type CreateStreamOptions, type CreateStreamResult, type CreateStreamStatus, type CreateSubscriptionResult, type CreateVoiceAgentOptions, type CreateVoiceAgentResult, type FlagValue, type HeartbeatReference, type ListPresentReference, LunoraContext, LunoraProvider,
+/**
+ * SolidJS adapter for Lunora.
+ *
+ * Thin, idiomatic glue over the framework-neutral `@lunora/client`. Solid's
+ * fine-grained signals map directly onto Lunora's per-subscription deltas, so a
+ * live query is just a signal the WebSocket writes to. The adapter exposes
+ * `LunoraProvider` / `useLunora` (context carrying the `LunoraClient`),
+ * `createQuery` (a live query accessor that opens a subscription and updates on
+ * every delta), `createMutation` (an optimistic mutation handle), and
+ * `hydratePreloaded` (seed a query from an SSR `Preloaded` token synchronously —
+ * no loading flash — then attach the live subscription; the client half of
+ * PLAN4's "your loaders are live" reactive-loader handoff).
+ *
+ * Server-side preloading (`createServerClient`, `preloadQuery`) lives in the
+ * socket-free `@lunora/solid/server` entry (a re-export of `@lunora/client/ssr`, the
+ * framework-neutral server contract) — call it from your SolidStart route loader
+ * and hand the resulting `Preloaded` token to `hydratePreloaded`.
+ */
+type LunoraProviderProps, type MutationClient, type MutationHandle, type MutatorHook, type PageItemOf, type PaginatedArgs, type SolidChildren, Unauthenticated, type UseAuthResult, type VoiceAudioFormat, type VoiceReference, type VoiceStatus, createAction, createActionForClient, createAgent, createAgentChat, createAgentState, createAgentToolEvents, createAuth, createConnectionStatus, createFlag, createFlags, createInfiniteQuery, createMutation, createMutationForClient, createMutator, createPaginatedQuery, createPresence, createQuery, createRateLimit, createStream, createSubscription, createVoiceAgent, hydratePreloaded, useLunora };