@lunora/angular 1.0.0-alpha.25 → 1.0.0-alpha.250

package/README.md

@@ -57,6 +57,60 @@ export class MessagesComponent {
 
 Pass `"skip"` as the args to short-circuit (no network call, no socket).
 
+Pass a function/`Signal` instead of a plain object to make the args reactive —
+each change tears the old subscription down, resets the signal to `undefined`,
+and opens a fresh one for the new args:
+
+```ts
+export class MessagesComponent {
+    private readonly channelId = input.required<string>();
+
+    readonly messages = liveQuery(api.messages.list, () => ({ channelId: this.channelId() }));
+}
+```
+
+`subscription` and `paginatedQuery`/`infiniteQuery` accept the same reactive
+args form. Calling from outside an injection context (e.g. `ngOnInit`) needs an
+explicit `injector` alongside `client`/`destroyRef` for the reactive form —
+`effect()` can't resolve one on its own there:
+
+```ts
+liveQuery(api.messages.list, () => ({ channelId: this.channelId() }), {
+    client: this.client,
+    destroyRef: this.destroyRef,
+    injector: this.injector,
+});
+```
+
+## Live topics
+
+`liveTopic` follows one topic a `defineLiveStream` declares, and mirrors the last
+payload and any refusal into two signals: `lastEvent` and `error`. Pass the
+reference `_generated/live.ts` hands out; the stream's route is resolved against
+the injected `LunoraClient`, and `lastEvent` and `onEvent` are typed by the payload
+the topic declares. It subscribes when the component is created and unsubscribes
+on `DestroyRef`.
+
+```ts
+import { input } from "@angular/core";
+import { liveTopic } from "@lunora/angular";
+
+import { live } from "../lunora/_generated/live";
+
+export class PostComponent {
+    readonly postId = input.required<string>();
+
+    readonly comments = liveTopic(() => live.posts.comments({ postId: this.postId() }));
+}
+```
+
+A function makes the topic reactive: a new topic resubscribes, while a new
+`onEvent` or `onError` callback is read at call time and does not. A plain
+reference resolves once. Pass `{ client, destroyRef, injector }` as the second
+argument when calling outside an injection context, as with `liveQuery`; the
+options also take `shardKey` and `sessionKey` (each a string or a signal, which resubscribes on change) and the transport tuning `headers`,
+`withCredentials`, `retryDelay` and `maxDelayMs`.
+
 ## Mutations
 
 ```ts
@@ -85,4 +139,21 @@ import { connectionStatus } from "@lunora/angular";
 readonly status = connectionStatus(); // Signal<"idle" | "connecting" | "connected" | "offline">
 ```
 
+## Agents
+
+```ts
+import { agentToolEvents, voiceAgent } from "@lunora/angular";
+
+// One thread's tool lifecycle: call / result / awaiting-approval / progress.
+readonly events = agentToolEvents({ api, threadKey: "t1", stream: api.chat.liveEvents }).events;
+
+// A full-duplex voice call against api.agents.<name>Voice.
+readonly call = voiceAgent({ threadKey: "t1", voice: api.agents.supportVoice });
+```
+
+`voiceAgent` opens nothing until `call.startCall()` — that call is what requests
+the microphone, so it must run from a user gesture. `call.endCall()` releases the
+socket, the mic tracks and the Web Audio graph, and the owning `DestroyRef` runs
+it on destroy.
+
 Part of the [Lunora](https://github.com/anolilab/lunora) framework.