@lunora/angular 1.0.0-alpha.8 → 1.0.0-alpha.9

package/README.md

@@ -1,5 +1,7 @@
 # @lunora/angular
 
+> **Experimental** — this package is outside the Lunora 1.0 stability promise: its API may change in any release, without a major version bump.
+
 Angular reactive adapter for Lunora — signal-based live queries and mutations.
 
 Thin, idiomatic glue over the framework-neutral `@lunora/client`. Angular signals

package/dist/index.d.mts

@@ -10,6 +10,7 @@ export { SKIP } from '@lunora/client/query';
 * 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";
 /**
@@ -17,6 +18,7 @@ type AgentThreadStatus = "awaiting_input" | "cancelled" | "error" | "idle" | "ru
 * 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;
@@ -37,6 +39,7 @@ interface AgentThreadRecord {
 * 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;
@@ -63,6 +66,7 @@ interface AgentChatMessage {
 * `@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). */
@@ -78,6 +82,7 @@ interface AgentTokenDelta {
 * 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. */
@@ -94,6 +99,7 @@ interface AgentProgressEvent {
 * 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;
 /**
@@ -101,6 +107,7 @@ type AgentLiveEvent = AgentProgressEvent | AgentTokenDelta;
 * 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: {
@@ -109,6 +116,10 @@ interface AgentApi {
     }, 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;
@@ -136,6 +147,10 @@ interface AgentOptions {
   /** 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
@@ -164,6 +179,7 @@ interface AgentResult {
 *
 * 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. */
@@ -189,6 +205,7 @@ type AgentThreadReference = FunctionReference<"query", {
 * 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;
@@ -197,6 +214,7 @@ type AgentTokenStreamReference = FunctionReference<"stream", {
 * 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: {
@@ -205,6 +223,10 @@ interface AgentChatApi {
     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;
@@ -241,6 +263,10 @@ interface AgentChatOptions {
   /** 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>;
@@ -282,6 +308,7 @@ interface AgentChatResult {
 *
 * 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;
 /**
@@ -291,6 +318,7 @@ declare const agentChat: (options: AgentChatOptions) => AgentChatResult;
 * 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: {
@@ -299,6 +327,10 @@ interface AgentStateApi {
     }, 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;
@@ -312,6 +344,10 @@ interface AgentStateOptions {
   /** 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>;
@@ -335,6 +371,7 @@ interface AgentStateResult<T> {
 *
 * 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. */
@@ -354,12 +391,17 @@ type AgentLiveStreamReference = FunctionReference<"stream", {
 * 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;
@@ -387,6 +429,7 @@ interface AgentToolEventsOptions {
 * (`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;
@@ -411,6 +454,10 @@ type AgentToolEvent = {
   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`)
@@ -435,14 +482,23 @@ interface AgentToolEventsResult {
 *
 * 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;
@@ -465,6 +521,7 @@ interface AuthResult {
 * ```ts
 * const { token, user, setToken } = auth();
 * ```
+* @experimental
 */
 declare const auth: (options?: AuthOptions) => AuthResult;
 /**
@@ -477,6 +534,7 @@ declare const auth: (options?: AuthOptions) => AuthResult;
 * {@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>;
 /**
@@ -484,6 +542,7 @@ declare const LUNORA_CLIENT: InjectionToken<LunoraClient>;
 * 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;
@@ -502,6 +561,7 @@ type ProvideLunoraOptions = Omit<LunoraClientOptions, "url"> & {
 * 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;
 /**
@@ -515,8 +575,13 @@ declare const provideLunora: (optionsOrClient?: LunoraClient | ProvideLunoraOpti
 * 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;
@@ -531,12 +596,23 @@ interface ConnectionStatusOptions {
 *
 * 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. */
+/**
+* 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. */
+/**
+* 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;
@@ -564,8 +640,13 @@ interface FlagOptions {
 * ```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;
@@ -588,14 +669,23 @@ interface FlagsOptions {
 * ```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>;
@@ -619,8 +709,13 @@ interface HydratePreloadedResult<T> {
 * ```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
@@ -666,8 +761,13 @@ interface LiveQueryOptions {
 * 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`.
@@ -694,8 +794,13 @@ interface MutateOptions<F extends FunctionReference> extends MutationCallOptions
 *
 * 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>>;
+/**
+* `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>;
@@ -724,6 +829,7 @@ interface MutatorResult<TArgs> {
 * 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. */
@@ -734,6 +840,10 @@ type PageItemOf<F extends FunctionReference> = ReturnTypeOf<F> extends {
 } ? 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;
@@ -744,6 +854,10 @@ interface PaginatedQueryOptions {
   /** 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>;
@@ -754,6 +868,10 @@ interface PaginatedQueryResult<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;
@@ -783,6 +901,7 @@ interface InfiniteQueryResult<T> {
 * ```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>>;
 /**
@@ -796,16 +915,29 @@ declare const paginatedQuery: <F extends FunctionReference>(reference: F, args:
 * ```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;
@@ -827,6 +959,10 @@ interface PresenceOptions<H extends HeartbeatReference, L extends ListPresentRef
   /** 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>;
@@ -849,8 +985,13 @@ interface PresenceResult<L extends ListPresentReference> {
 *     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
@@ -865,6 +1006,10 @@ interface RateLimitOptions {
   */
   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;
@@ -891,10 +1036,18 @@ interface RateLimitResult {
 * ```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. */
+/**
+* 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;
@@ -908,6 +1061,10 @@ interface StreamOptions {
   /** 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;
@@ -933,8 +1090,13 @@ interface StreamResult<T> {
 * ```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;
@@ -951,6 +1113,10 @@ interface SubscriptionOptions {
   /** 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>;
@@ -972,6 +1138,7 @@ interface SubscriptionResult<T> {
 * ```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>>;
 /**
@@ -987,6 +1154,7 @@ declare const subscription: <F extends FunctionReference>(reference: F, args: Ar
 * `@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. */
@@ -1039,11 +1207,15 @@ type CreateSpeaker = (config: {
 * 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. */
+/**
+* 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 {
@@ -1059,6 +1231,10 @@ interface VoiceSocket {
   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;
@@ -1090,6 +1266,10 @@ interface VoiceAgentOptions {
   /** 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>;
@@ -1132,6 +1312,7 @@ interface VoiceAgentResult {
 *
 * 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 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, connectionStatus, flag, flags, hydratePreloaded, infiniteQuery, injectLunoraClient, liveQuery, mutate, mutator, paginatedQuery, presence, provideLunora, rateLimit, stream, subscription, voiceAgent };

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export { SKIP } from '@lunora/client/query';
 * 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";
 /**
@@ -17,6 +18,7 @@ type AgentThreadStatus = "awaiting_input" | "cancelled" | "error" | "idle" | "ru
 * 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;
@@ -37,6 +39,7 @@ interface AgentThreadRecord {
 * 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;
@@ -63,6 +66,7 @@ interface AgentChatMessage {
 * `@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). */
@@ -78,6 +82,7 @@ interface AgentTokenDelta {
 * 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. */
@@ -94,6 +99,7 @@ interface AgentProgressEvent {
 * 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;
 /**
@@ -101,6 +107,7 @@ type AgentLiveEvent = AgentProgressEvent | AgentTokenDelta;
 * 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: {
@@ -109,6 +116,10 @@ interface AgentApi {
     }, 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;
@@ -136,6 +147,10 @@ interface AgentOptions {
   /** 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
@@ -164,6 +179,7 @@ interface AgentResult {
 *
 * 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. */
@@ -189,6 +205,7 @@ type AgentThreadReference = FunctionReference<"query", {
 * 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;
@@ -197,6 +214,7 @@ type AgentTokenStreamReference = FunctionReference<"stream", {
 * 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: {
@@ -205,6 +223,10 @@ interface AgentChatApi {
     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;
@@ -241,6 +263,10 @@ interface AgentChatOptions {
   /** 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>;
@@ -282,6 +308,7 @@ interface AgentChatResult {
 *
 * 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;
 /**
@@ -291,6 +318,7 @@ declare const agentChat: (options: AgentChatOptions) => AgentChatResult;
 * 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: {
@@ -299,6 +327,10 @@ interface AgentStateApi {
     }, 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;
@@ -312,6 +344,10 @@ interface AgentStateOptions {
   /** 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>;
@@ -335,6 +371,7 @@ interface AgentStateResult<T> {
 *
 * 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. */
@@ -354,12 +391,17 @@ type AgentLiveStreamReference = FunctionReference<"stream", {
 * 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;
@@ -387,6 +429,7 @@ interface AgentToolEventsOptions {
 * (`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;
@@ -411,6 +454,10 @@ type AgentToolEvent = {
   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`)
@@ -435,14 +482,23 @@ interface AgentToolEventsResult {
 *
 * 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;
@@ -465,6 +521,7 @@ interface AuthResult {
 * ```ts
 * const { token, user, setToken } = auth();
 * ```
+* @experimental
 */
 declare const auth: (options?: AuthOptions) => AuthResult;
 /**
@@ -477,6 +534,7 @@ declare const auth: (options?: AuthOptions) => AuthResult;
 * {@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>;
 /**
@@ -484,6 +542,7 @@ declare const LUNORA_CLIENT: InjectionToken<LunoraClient>;
 * 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;
@@ -502,6 +561,7 @@ type ProvideLunoraOptions = Omit<LunoraClientOptions, "url"> & {
 * 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;
 /**
@@ -515,8 +575,13 @@ declare const provideLunora: (optionsOrClient?: LunoraClient | ProvideLunoraOpti
 * 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;
@@ -531,12 +596,23 @@ interface ConnectionStatusOptions {
 *
 * 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. */
+/**
+* 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. */
+/**
+* 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;
@@ -564,8 +640,13 @@ interface FlagOptions {
 * ```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;
@@ -588,14 +669,23 @@ interface FlagsOptions {
 * ```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>;
@@ -619,8 +709,13 @@ interface HydratePreloadedResult<T> {
 * ```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
@@ -666,8 +761,13 @@ interface LiveQueryOptions {
 * 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`.
@@ -694,8 +794,13 @@ interface MutateOptions<F extends FunctionReference> extends MutationCallOptions
 *
 * 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>>;
+/**
+* `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>;
@@ -724,6 +829,7 @@ interface MutatorResult<TArgs> {
 * 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. */
@@ -734,6 +840,10 @@ type PageItemOf<F extends FunctionReference> = ReturnTypeOf<F> extends {
 } ? 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;
@@ -744,6 +854,10 @@ interface PaginatedQueryOptions {
   /** 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>;
@@ -754,6 +868,10 @@ interface PaginatedQueryResult<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;
@@ -783,6 +901,7 @@ interface InfiniteQueryResult<T> {
 * ```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>>;
 /**
@@ -796,16 +915,29 @@ declare const paginatedQuery: <F extends FunctionReference>(reference: F, args:
 * ```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;
@@ -827,6 +959,10 @@ interface PresenceOptions<H extends HeartbeatReference, L extends ListPresentRef
   /** 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>;
@@ -849,8 +985,13 @@ interface PresenceResult<L extends ListPresentReference> {
 *     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
@@ -865,6 +1006,10 @@ interface RateLimitOptions {
   */
   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;
@@ -891,10 +1036,18 @@ interface RateLimitResult {
 * ```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. */
+/**
+* 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;
@@ -908,6 +1061,10 @@ interface StreamOptions {
   /** 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;
@@ -933,8 +1090,13 @@ interface StreamResult<T> {
 * ```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;
@@ -951,6 +1113,10 @@ interface SubscriptionOptions {
   /** 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>;
@@ -972,6 +1138,7 @@ interface SubscriptionResult<T> {
 * ```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>>;
 /**
@@ -987,6 +1154,7 @@ declare const subscription: <F extends FunctionReference>(reference: F, args: Ar
 * `@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. */
@@ -1039,11 +1207,15 @@ type CreateSpeaker = (config: {
 * 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. */
+/**
+* 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 {
@@ -1059,6 +1231,10 @@ interface VoiceSocket {
   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;
@@ -1090,6 +1266,10 @@ interface VoiceAgentOptions {
   /** 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>;
@@ -1132,6 +1312,7 @@ interface VoiceAgentResult {
 *
 * 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 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, connectionStatus, flag, flags, hydratePreloaded, infiniteQuery, injectLunoraClient, liveQuery, mutate, mutator, paginatedQuery, presence, provideLunora, rateLimit, stream, subscription, voiceAgent };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/angular",
-  "version": "1.0.0-alpha.8",
+  "version": "1.0.0-alpha.9",
   "description": "Angular reactive adapter for Lunora — signal-based live queries and mutations",
   "keywords": [
     "angular",
@@ -45,8 +45,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/client": "1.0.0-alpha.21",
-    "@lunora/ratelimit": "1.0.0-alpha.7"
+    "@lunora/client": "1.0.0-alpha.23",
+    "@lunora/ratelimit": "1.0.0-alpha.8"
   },
   "peerDependencies": {
     "@angular/core": "^19.2.0 || ^20.0.0 || ^21.0.0 || ^22.0.0"