@lunora/vue 1.0.0-alpha.28 → 1.0.0-alpha.281

package/LICENSE.md

@@ -103,3 +103,9 @@ Unless required by applicable law or agreed to in writing, software distributed
 under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
 CONDITIONS OF ANY KIND, either express or implied. See the License for the
 specific language governing permissions and limitations under the License.
+
+<!-- DEPENDENCIES -->
+<!-- /DEPENDENCIES -->
+
+<!-- TYPE_DEPENDENCIES -->
+<!-- /TYPE_DEPENDENCIES -->

package/README.md

@@ -74,22 +74,29 @@ const { mutate, pending } = useMutation(api.messages.send);
 
 ## API
 
-| Composable            | React equivalent      | Description                                                                     |
-| --------------------- | --------------------- | ------------------------------------------------------------------------------- |
-| `createLunora`        | `LunoraProvider`      | Vue plugin — call `app.use(createLunora(client))` at the app root.              |
-| `useLunora`           | `useLunora`           | Inject the ambient `LunoraClient` from the nearest provider.                    |
-| `useQuery`            | `useQuery`            | Live query `ShallowRef` — re-subscribes when reactive args change.              |
-| `useMutation`         | `useMutation`         | Optimistic mutation handle (`data`, `error`, `pending`, `mutate`, `reset`).     |
-| `useSubscription`     | `useSubscription`     | Raw subscription `ShallowRef` — unbounded live stream.                          |
-| `usePaginatedQuery`   | `usePaginatedQuery`   | Cursor-paginated query with `loadMore`, `status`, and `results`.                |
-| `useInfiniteQuery`    | `useInfiniteQuery`    | Infinite-scroll variant of `usePaginatedQuery`.                                 |
-| `useAuth`             | `useAuth`             | Reactive auth: readonly `token`/`user` refs plus `setToken`.                    |
-| `usePresence`         | `usePresence`         | Collaborative-awareness — heartbeat + live present-members `ShallowRef`.        |
-| `useFlag`             | `useFlag`             | Live OpenFeature flag as a readonly `Ref` — holds `default` until resolved.     |
-| `useFlags`            | `useFlags`            | Batch variant — a readonly `Ref` of one value per key in the defaults map.      |
-| `useRateLimit`        | `useRateLimit`        | Client-side rate-limit mirror — `ok`, `disabled`, `retryAfter` as ComputedRefs. |
-| `useConnectionStatus` | `useConnectionStatus` | Reactive connection state (`idle`, `connecting`, `connected`, `offline`).       |
-| `hydratePreloaded`    | `usePreloadedQuery`   | Seed a query synchronously from an SSR `Preloaded` token, then go live.         |
+| Composable            | React equivalent      | Description                                                                       |
+| --------------------- | --------------------- | --------------------------------------------------------------------------------- |
+| `createLunora`        | `LunoraProvider`      | Vue plugin — call `app.use(createLunora(client))` at the app root.                |
+| `useLunora`           | `useLunora`           | Inject the ambient `LunoraClient` from the nearest provider.                      |
+| `useQuery`            | `useQuery`            | Live query `ShallowRef` — re-subscribes when reactive args change.                |
+| `useMutation`         | `useMutation`         | Optimistic mutation handle (`data`, `error`, `pending`, `mutate`, `reset`).       |
+| `useSubscription`     | `useSubscription`     | Raw subscription `ShallowRef` — unbounded live stream.                            |
+| `usePaginatedQuery`   | `usePaginatedQuery`   | Cursor-paginated query with `loadMore`, `status`, `results`, and `error`.         |
+| `useInfiniteQuery`    | `useInfiniteQuery`    | Infinite-scroll variant of `usePaginatedQuery`.                                   |
+| `useAuth`             | `useAuth`             | Reactive auth: readonly `token`/`user`/`status` refs plus `setToken`.             |
+| `usePresence`         | `usePresence`         | Collaborative-awareness — heartbeat + live present-members `ShallowRef`.          |
+| `useLiveTopic`        | `useLiveTopic`        | Follow one declared live topic as `lastEvent` / `error` refs.                     |
+| `useFlag`             | `useFlag`             | Live OpenFeature flag as a readonly `Ref` — holds `default` until resolved.       |
+| `useFlags`            | `useFlags`            | Batch variant — a readonly `Ref` of one value per key in the defaults map.        |
+| `useRateLimit`        | `useRateLimit`        | Client-side rate-limit mirror — `ok`, `disabled`, `retryAfter` as ComputedRefs.   |
+| `useConnectionStatus` | `useConnectionStatus` | Reactive connection state (`idle`, `connecting`, `connected`, `offline`).         |
+| `hydratePreloaded`    | `usePreloadedQuery`   | Seed a query synchronously from an SSR `Preloaded` token, then go live.           |
+| `useAgentToolEvents`  | `useAgentToolEvents`  | One agent thread's tool lifecycle as a `ComputedRef` of discriminated events.     |
+| `useVoiceAgent`       | `useVoiceAgent`       | Full-duplex voice call — refs for status/transcript/level, `startCall`/`endCall`. |
+
+`useLiveTopic(topic, options?)` takes the reference `_generated/live.ts` hands out, e.g. `useLiveTopic(live.posts.post({ postId }), { onEvent })`, as a value, a ref or a getter, so a reactive `postId` resubscribes. The stream's route is resolved against the injected `LunoraClient`, and `lastEvent` and `onEvent` are typed by the payload the topic declares. Each connection option (`shardKey`, `sessionKey`, `headers`, `withCredentials`, `retryDelay`, `maxDelayMs`) may be a plain value, a ref, or a getter. `onEvent` and `onError` are plain functions and never trigger a resubscribe. The SSE connection is shared by stream route, and it opens nothing during SSR.
+
+`useVoiceAgent` opens nothing until `startCall()` — that call is what requests the microphone, so it must run from a user gesture. `endCall()` releases the socket, the mic tracks and the Web Audio graph, and `onScopeDispose` runs it for you on unmount.
 
 ## Related