@live-assistant/react-native 0.2.0 → 0.3.1

package/README.md

@@ -1,10 +1,26 @@
 # @live-assistant/react-native
 
-One install for a voice assistant in a React Native or Expo app: the controller,
-a Gemini Live connection, microphone and playback, React bindings and a
-ready-made widget, re-exported from one place.
+One install for a voice assistant in a React Native, Expo or web app — and one
+component to use it:
 
-This page is the whole integration. You should not need another one.
+```tsx
+import { LiveAssistant } from '@live-assistant/react-native';
+
+<LiveAssistant tokenEndpoint="https://api.example.com/assistant/token" />
+```
+
+That is the integration. The Gemini session, the microphone, the player, the tool
+registry, the controller, the provider and the widget are built inside it, the
+same way in every app — so they are not yours to write. The one value it cannot
+invent is the route on **your** server that mints a short-lived token, because
+your API key must never ship in an app bundle.
+
+This page is the whole of it: five steps, then a table for every value you can
+pass. **Building for the web only?** Steps 1 and 2 are the native setup — there,
+the install is the whole of it and nothing needs rebuilding; skip to
+[step 3](#3-mint-tokens-on-your-server). If you would rather read code than prose,
+[`examples/expo-app`](https://github.com/Recipely-Team/live-assistant/tree/main/examples/expo-app)
+is a working app in one file, and CI builds it on every change.
 
 ---
 
@@ -25,6 +41,8 @@ On the web nothing native is needed, but `getUserMedia` only exists in a
 
 ## 2. Configure the microphone — one line
 
+*Native only. A web build needs nothing from this step.*
+
 ```json
 {
   "expo": {
@@ -89,39 +107,215 @@ the tools and the voice when the token is minted, and discards a setup sent by
 the client — so a tool the token did not declare simply does not exist, with no
 error. Declare every tool here.
 
-## 4. Wire up the app
+## 4. Add the assistant
+
+```tsx
+import { LiveAssistant } from '@live-assistant/react-native';
+
+export function App() {
+  return (
+    <>
+      <Navigation />
+      <LiveAssistant
+        tokenEndpoint="https://api.example.com/assistant/token"
+        headers={{ authorization: `Bearer ${userToken}` }}
+      />
+    </>
+  );
+}
+```
+
+Render it once, near the root and beside your navigation, so a session survives
+moving between screens. It builds the controller on its first render and stops
+the session when it unmounts; `headers` and `language` are read again on every
+connection, so a login refreshed mid-conversation is the one used when a long
+session hands over to a new socket.
+
+### What it can already do, with nothing registered
+
+On the web the assistant reads the page it is on and acts on it:
+
+| It can | Meaning |
+| --- | --- |
+| `read` | what the page says, as text |
+| `list` | what can be followed, pressed or filled, by name |
+| `navigate` | follow a link, by its name or a path |
+| `back` | go back |
+| `press` | click a button or link |
+| `type` | put text in a field |
+| `scroll` | up, down, to the top or the bottom |
+
+Nothing declares any of that. It reads the live DOM at the moment of the call, so
+there is no route table to keep in step with your router and nothing to register
+on a new screen. Targets are named the way someone reading the screen aloud would
+name them — the accessible name — which is also why a React Native Web app works
+unchanged: `accessibilityLabel` renders as `aria-label`.
+
+Following a link **clicks** it rather than assigning the url, so your
+single-page router stays in charge and the live session is not thrown away by a
+reload. A target that is not on the page is answered with the names that are, so
+the model picks one instead of guessing again.
+
+On a phone there is no DOM, so the pack is inert unless you hand it a router:
+
+```tsx
+<LiveAssistant
+  tokenEndpoint={endpoint}
+  page={{ router: { go: (path) => router.push(path), back: () => router.back(), current: () => pathname } }}
+/>
+```
+
+### Your own tools
+
+Everything the page cannot do for itself is a tool:
 
 ```tsx
-import {
-  AssistantController,
-  AssistantProvider,
-  AssistantWidget,
-  GeminiLiveSession,
-  Microphone,
-  PcmPlayer,
-  ToolRegistry,
-} from '@live-assistant/react-native';
-
-const tools = new ToolRegistry([
-  {
-    definition: {
-      name: 'createNote',
-      description: 'Creates a note with the given text',
-      parameters: {
-        type: 'object',
-        properties: { text: { type: 'string' } },
-        required: ['text'],
+<LiveAssistant
+  tokenEndpoint={endpoint}
+  tools={[
+    {
+      definition: {
+        name: 'createNote',
+        description: 'Creates a note with the given text',
+        parameters: { type: 'object', properties: { text: { type: 'string' } }, required: ['text'] },
       },
+      run: async ({ text }) => ({ ok: true, id: await notes.create(String(text)) }),
     },
-    run: async ({ text }) => ({ ok: true, id: await notes.create(String(text)) }),
-  },
-]);
+  ]}
+/>
+```
+
+Declare the same definitions when you mint the token (step 3): Gemini fixes the
+tool list there, and a tool the token did not declare does not exist — with no
+error saying so.
+
+## 5. Run it
+
+```sh
+npx expo run:ios      # or run:android — a development build, not Expo Go
+npx expo start --web  # the web half needs no rebuild
+```
+
+Tap the orb. It asks for the microphone before spending a token, so the first run
+shows the permission prompt.
 
+---
+
+## Configuration
+
+Everything is optional except `tokenEndpoint` (or `getConnection` in its place).
+
+### `<LiveAssistant>`
+
+| Prop | Default | What it does |
+| --- | --- | --- |
+| **`tokenEndpoint`** | — | **Required.** Your server's route that mints a token. Called as `POST` with `{ resumptionHandle, languageCode }`; answer `{ token, model, wsUrl? }` |
+| `getConnection` | — | Instead of `tokenEndpoint`, when your app already has its own client. Throw to refuse — the thrown value comes back as `failure.cause` |
+| `headers` | — | Added to the token request; where your `Authorization` goes. Read fresh on every connection |
+| `language` | `'en-US'` | Sent to your endpoint as `languageCode` |
+| `tools` | — | Your app's own tools, on top of the page pack. An array or a `ToolRegistry` |
+| `page` | on where a document exists | Reading and driving the page. `false` removes it; an object narrows it — table below |
+| `timing` | measured | `utteranceGapMs` 1200 · `answerTimeoutMs` 12000 · `silenceTimeoutMs` 90000, `null` never ends a session · `echoTailMs` 250 · `maxHandovers` 3 |
+| `theme` | below | Colours, sizes and your logo |
+| `strings` | English | Every word the widget says |
+| `placement` | `'bottom-right'` | `'bottom-left'`, or `'inline'` to lay it out where you rendered it |
+| `style` | — | Merged last onto the floating stack — safe-area insets go here (`{ bottom: insets.bottom + 16 }`) |
+| `showTranscript` | `true` | Show the conversation in the panel |
+| `showComposer` | `true` | Show the typing box |
+| `renderMessage` | — | Replace a said line; the default bubble arrives as `fallback` |
+| `renderTool` | — | Replace a tool run; return `null` to hide it. The default shows **nothing** for a run that succeeded, on the grounds that the assistant already said what it did |
+| `onReady` | — | Called once with the controller, to start or stop a session from elsewhere (a push notification, a deep link) |
+| `onFailure` | — | Called with each failure, for logging. The widget already tells the user |
+
+### `page`
+
+| Field | Default | What it does |
+| --- | --- | --- |
+| `actions` | all seven | Which actions the model may use. A word left out never reaches the model, so it cannot ask for it and be refused |
+| `name` | `'page'` | The tool's name, if `page` collides with one of yours |
+| `root` | the whole document | A CSS selector the tools are confined to |
+| `maxCharacters` | `4000` | Cap on what `read` returns, so a long page cannot crowd out the conversation |
+| `maxTargets` | `40` | Cap on what `list` returns per kind |
+| `router` | — | `{ go, back, current }` — navigation where there is no DOM |
+| `document` / `window` | the globals | For tests, an iframe, or a server render |
+
+### `theme`
+
+Pass any part of it; the rest keeps the default.
+
+| Colour | Default | Where it shows |
+| --- | --- | --- |
+| `primary` | `#5B5BD6` | The orb at rest, and the controls' accent |
+| `userGlow` | `#3E9BFF` | The ring that follows the user's voice |
+| `assistantGlow` | `#B45BFF` | The glow that follows the assistant's voice |
+| `surface` | `#FFFFFF` | The panel |
+| `text` | `#1C1C28` | Panel text |
+| `mutedText` | `#6B6B80` | The status line and secondary text |
+| `userBubble` | `#5B5BD6` | The user's transcript bubble |
+| `userText` | `#FFFFFF` | Text in it |
+| `assistantBubble` | `#F0F0F7` | The assistant's bubble |
+| `assistantText` | `#1C1C28` | Text in it |
+| `toolChip` | `#E8F5EC` | A tool-run chip |
+| `toolText` | `#1F6B3A` | Text on it |
+| `danger` | `#D93F3F` | Errors, and the end-session control |
+| `onPrimary` | `#FFFFFF` | Anything drawn on `primary` |
+
+| Value | Default | What it does |
+| --- | --- | --- |
+| `logo` | — | **Your mark, drawn inside the orb.** Any `<Image source>`: a `require(...)`, a `{ uri }`, an imported asset |
+| `logoSize` | `0.55` | The logo's share of the orb's diameter; `1` would touch the edges |
+| `orbSize` | `64` | The orb's diameter |
+| `radius` | `16` | Corner radius of the panel and its controls |
+| `spacing` | `12` | Padding and the gaps between rows |
+| `fontSize` | `15` | Transcript text size |
+| `panelMaxHeight` | `420` | How tall the panel may grow before the transcript scrolls |
+
+```tsx
+<LiveAssistant
+  tokenEndpoint={endpoint}
+  theme={{ logo: require('./assets/mark.png'), colors: { primary: '#E4572E', assistantGlow: '#FFB400' }, radius: 8 }}
+/>
+```
+
+### `strings`
+
+Every word, in one object — the defaults are English and the library ships no
+other language, because a library that guesses at your voice is one you have to
+argue with.
+
+| Key | Default |
+| --- | --- |
+| `start` / `stop` | `Start voice assistant` / `End` |
+| `mute` / `unmute` | `Mute` / `Unmute` |
+| `send` / `composerPlaceholder` | `Send` / `Type a message` |
+| `status.idle` … `status.working` | `Tap to talk`, `Connecting…`, `Listening`, `Thinking…`, `Speaking`, `Working on it…` |
+| `ended.silence` | `Ended after a quiet spell` |
+| `errors.*` | one sentence per failure code — `microphone_denied`, `microphone_unavailable`, `connection_refused`, `connection_lost`, `no_answer` |
+| `genericError` | `Something went wrong` |
+| `toolRunning(name)` / `toolFailed(name)` | `Running {name}…` / `{name} did not work` |
+
+```tsx
+<LiveAssistant
+  tokenEndpoint={endpoint}
+  strings={{ start: 'Asistanı başlat', stop: 'Bitir', status: { listening: 'Dinliyorum' } }}
+/>
+```
+
+---
+
+## Building it yourself
+
+`<LiveAssistant>` is not a wall. It is these three things, and nothing you cannot
+write out when you need to hold them apart — a controller that outlives the tree,
+a widget somewhere other than where the provider is, a session you start from a
+push notification:
+
+```tsx
 const assistant = new AssistantController({
   session: new GeminiLiveSession(),
   microphone: new Microphone(),
   player: new PcmPlayer(),
-  tools,
+  tools: new ToolRegistry([...]),
   getConnection: async ({ resumptionHandle }) => {
     const response = await fetch('https://api.example.com/assistant/token', {
       method: 'POST',
@@ -143,43 +337,10 @@ export function App() {
 }
 ```
 
-Build the controller **once**, outside the component (or in `useState(() => …)`),
-and render the widget near the root so it survives navigation.
-
-## 5. Run it
-
-```sh
-npx expo run:ios      # or run:android — a development build, not Expo Go
-npx expo start --web  # the web half needs no rebuild
-```
-
-Tap the orb. It asks for the microphone before spending a token, so the first run
-shows the permission prompt.
-
----
-
-## Making it yours
-
-```tsx
-<AssistantWidget
-  placement="bottom-left"
-  theme={{ colors: { primary: '#E4572E', assistantGlow: '#FFB400' }, radius: 8 }}
-  strings={{ status: { listening: 'Dinliyorum' }, stop: 'Bitir' }}
-  renderTool={(entry, fallback) =>
-    entry.status === 'succeeded' ? <ActionChip name={entry.call.name} /> : fallback
-  }
-/>
-```
-
-- **`theme`** — colours, orb size, radius, spacing, font size, panel height.
-- **`strings`** — every word, including statuses, errors and end reasons. The
-  defaults are English.
-- **`renderMessage` / `renderTool`** — each transcript row, with the default
-  rendering handed to you as `fallback`. Note that the default chip shows
-  **nothing** for a tool run that succeeded, on the grounds that the assistant
-  already said what it did; override `renderTool` to show every run.
+Build the controller **once**, outside the component or in `useState(() => …)`:
+it owns a socket and two devices.
 
-Drawing your own UI instead? Use the hooks — `useAssistant()`,
+Drawing your own UI instead of the widget? Use the hooks — `useAssistant()`,
 `useTranscript()`, `useLevelFrames()` — and install `core`, `gemini`, `audio` and
 `react` directly rather than this package. **It matters for size**: this package
 re-exports with `export *` from a CommonJS build and Metro does not tree-shake,

package/dist/index.d.ts

@@ -9,10 +9,13 @@
  *   should be able to leave out. None of those reasons apply to the ordinary
  *   case — an app that wants the assistant — and making that case install five
  *   packages and keep five versions in step is friction with nothing behind it.
- * - **It adds nothing of its own.** Every name here is re-exported unchanged,
- *   so reading the source of `@live-assistant/core` still explains what you
- *   are holding, and an app that outgrows this package can depend on the
- *   pieces directly without changing a single import.
+ * - **It adds exactly one thing of its own: `<LiveAssistant>`.** Everything
+ *   else is re-exported unchanged, so reading the source of
+ *   `@live-assistant/core` still explains what you are holding, and an app that
+ *   outgrows this package can depend on the pieces directly without changing an
+ *   import. The one addition exists because this is the only package that can
+ *   see the session, the audio and the widget at once — and because the forty
+ *   lines it replaces were identical in every app that would ever write them.
  * - **The token server is deliberately absent.** It mints credentials with an
  *   API key, which belongs on a server and never in an app bundle. It is
  *   installed on its own, where it runs.
@@ -22,4 +25,6 @@ export * from '@live-assistant/gemini';
 export * from '@live-assistant/audio';
 export * from '@live-assistant/react';
 export * from '@live-assistant/widget';
+export { LiveAssistant } from './live-assistant';
+export type { LiveAssistantProps } from './live-assistant';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -14,6 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.LiveAssistant = void 0;
 /**
  * Everything an app on a phone needs, from one install.
  *
@@ -25,10 +26,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
  *   should be able to leave out. None of those reasons apply to the ordinary
  *   case — an app that wants the assistant — and making that case install five
  *   packages and keep five versions in step is friction with nothing behind it.
- * - **It adds nothing of its own.** Every name here is re-exported unchanged,
- *   so reading the source of `@live-assistant/core` still explains what you
- *   are holding, and an app that outgrows this package can depend on the
- *   pieces directly without changing a single import.
+ * - **It adds exactly one thing of its own: `<LiveAssistant>`.** Everything
+ *   else is re-exported unchanged, so reading the source of
+ *   `@live-assistant/core` still explains what you are holding, and an app that
+ *   outgrows this package can depend on the pieces directly without changing an
+ *   import. The one addition exists because this is the only package that can
+ *   see the session, the audio and the widget at once — and because the forty
+ *   lines it replaces were identical in every app that would ever write them.
  * - **The token server is deliberately absent.** It mints credentials with an
  *   API key, which belongs on a server and never in an app bundle. It is
  *   installed on its own, where it runs.
@@ -38,4 +42,6 @@ __exportStar(require("@live-assistant/gemini"), exports);
 __exportStar(require("@live-assistant/audio"), exports);
 __exportStar(require("@live-assistant/react"), exports);
 __exportStar(require("@live-assistant/widget"), exports);
+var live_assistant_1 = require("./live-assistant");
+Object.defineProperty(exports, "LiveAssistant", { enumerable: true, get: function () { return live_assistant_1.LiveAssistant; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,uDAAqC;AACrC,yDAAuC;AACvC,wDAAsC;AACtC,wDAAsC;AACtC,yDAAuC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,uDAAqC;AACrC,yDAAuC;AACvC,wDAAsC;AACtC,wDAAsC;AACtC,yDAAuC;AACvC,mDAAiD;AAAxC,+GAAA,aAAa,OAAA"}

package/dist/live-assistant.d.ts

@@ -0,0 +1,71 @@
+import { AssistantController, ToolRegistry } from '@live-assistant/core';
+import type { AssistantControllerOptions, AssistantFailure, AssistantTool, PageToolsOptions } from '@live-assistant/core';
+import type { GeminiLiveCredentials } from '@live-assistant/gemini';
+import type { AssistantWidgetProps } from '@live-assistant/widget';
+/** Shared by both ways of connecting; see `LiveAssistantProps`. */
+interface LiveAssistantCommonProps extends AssistantWidgetProps {
+    /** Sent to your token endpoint as `languageCode`. Default `'en-US'`. */
+    readonly language?: string;
+    /** Added to the token request — this is where an app's own `Authorization` goes. Read fresh on every connection. */
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Your app's own tools, on top of the page pack. */
+    readonly tools?: readonly AssistantTool[] | ToolRegistry;
+    /** Reading and driving the page. On by default in a browser; `false` removes it. */
+    readonly page?: boolean | PageToolsOptions;
+    readonly timing?: AssistantControllerOptions<GeminiLiveCredentials>['timing'];
+    /** Called with the controller once, for an app that wants to start or stop a session from elsewhere. */
+    readonly onReady?: (controller: AssistantController<GeminiLiveCredentials>) => void;
+    /** Called whenever a session fails. The widget already tells the user; this is for logging. */
+    readonly onFailure?: (failure: AssistantFailure) => void;
+}
+/** The endpoint form: the usual one. */
+interface LiveAssistantEndpointProps extends LiveAssistantCommonProps {
+    /** Your server's route that mints a short-lived token. The one value this component cannot invent. */
+    readonly tokenEndpoint: string;
+    readonly getConnection?: never;
+}
+/** The escape hatch: an app that already has its own client for the same thing. */
+interface LiveAssistantConnectionProps extends LiveAssistantCommonProps {
+    readonly getConnection: (request: {
+        readonly resumptionHandle?: string;
+    }) => Promise<GeminiLiveCredentials>;
+    readonly tokenEndpoint?: never;
+}
+export type LiveAssistantProps = LiveAssistantEndpointProps | LiveAssistantConnectionProps;
+/**
+ * The whole integration: import it, put it in your tree, and there is a voice
+ * assistant on the screen.
+ *
+ * ```tsx
+ * <LiveAssistant tokenEndpoint="https://api.example.com/assistant/token" />
+ * ```
+ *
+ * @remarks
+ * - **One required value, because it is the only one we cannot know**: the
+ *   route on your server that mints a short-lived token. Everything else — the
+ *   Gemini session, the microphone, the player, the tool registry, the
+ *   controller, the provider and the widget — is built here, the same way in
+ *   every app, which is what makes it ours to write rather than yours.
+ * - **The controller is built once**, in a `useState` initialiser. It owns a
+ *   socket and two devices; rebuilding it on a render would start a session per
+ *   render. The session is stopped when this unmounts.
+ * - **Handlers are held, not depended on.** `onReady` and `onFailure` are read
+ *   through a ref, so passing them inline — which is how anyone passes them —
+ *   cannot re-run the lifecycle effect. It once could, and its cleanup hung up
+ *   on a live session whenever a parent re-rendered.
+ * - **`headers` and `language` are read at connection time, not at mount.** An
+ *   app whose `Authorization` header is refreshed mid-session would otherwise
+ *   reconnect with the token it had when the component first rendered — which
+ *   is exactly when a long conversation hands over to a new socket.
+ * - **A non-2xx from your endpoint is thrown on purpose.** It reaches the app
+ *   as `connection_refused` with the response in `failure.cause`, rather than
+ *   as a session that fails later for no stated reason.
+ * - **It does not own your navigation or your screens.** The page pack reads
+ *   the live DOM, so on the web it already works; a native app passes its own
+ *   tools, or `page: { router }`.
+ * - **Outgrowing it costs nothing**: build `AssistantController` yourself and
+ *   render `AssistantProvider` + `AssistantWidget`, which is all this does.
+ */
+export declare function LiveAssistant({ tokenEndpoint, getConnection, language, headers, tools, page, timing, onReady, onFailure, ...widget }: LiveAssistantProps): import("react").JSX.Element;
+export {};
+//# sourceMappingURL=live-assistant.d.ts.map

package/dist/live-assistant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-assistant.d.ts","sourceRoot":"","sources":["../src/live-assistant.tsx"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzE,OAAO,KAAK,EAAE,0BAA0B,EAAE,gBAAgB,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAG1H,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAGpE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAEnE,mEAAmE;AACnE,UAAU,wBAAyB,SAAQ,oBAAoB;IAC7D,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,oHAAoH;IACpH,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,qDAAqD;IACrD,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,aAAa,EAAE,GAAG,YAAY,CAAC;IACzD,oFAAoF;IACpF,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAC;IAC3C,QAAQ,CAAC,MAAM,CAAC,EAAE,0BAA0B,CAAC,qBAAqB,CAAC,CAAC,QAAQ,CAAC,CAAC;IAC9E,wGAAwG;IACxG,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,EAAE,mBAAmB,CAAC,qBAAqB,CAAC,KAAK,IAAI,CAAC;IACpF,+FAA+F;IAC/F,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAC;CAC1D;AAED,wCAAwC;AACxC,UAAU,0BAA2B,SAAQ,wBAAwB;IACnE,sGAAsG;IACtG,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,CAAC,EAAE,KAAK,CAAC;CAChC;AAED,mFAAmF;AACnF,UAAU,4BAA6B,SAAQ,wBAAwB;IACrE,QAAQ,CAAC,aAAa,EAAE,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC5G,QAAQ,CAAC,aAAa,CAAC,EAAE,KAAK,CAAC;CAChC;AAED,MAAM,MAAM,kBAAkB,GAAG,0BAA0B,GAAG,4BAA4B,CAAC;AAK3F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,aAAa,CAAC,EAC5B,aAAa,EACb,aAAa,EACb,QAA2B,EAC3B,OAAO,EACP,KAAK,EACL,IAAI,EACJ,MAAM,EACN,OAAO,EACP,SAAS,EACT,GAAG,MAAM,EACV,EAAE,kBAAkB,+BA2CpB"}

package/dist/live-assistant.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LiveAssistant = LiveAssistant;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const core_1 = require("@live-assistant/core");
+const audio_1 = require("@live-assistant/audio");
+const gemini_1 = require("@live-assistant/gemini");
+const react_2 = require("@live-assistant/react");
+const widget_1 = require("@live-assistant/widget");
+const DEFAULT_LANGUAGE = 'en-US';
+const JSON_TYPE = 'application/json';
+/**
+ * The whole integration: import it, put it in your tree, and there is a voice
+ * assistant on the screen.
+ *
+ * ```tsx
+ * <LiveAssistant tokenEndpoint="https://api.example.com/assistant/token" />
+ * ```
+ *
+ * @remarks
+ * - **One required value, because it is the only one we cannot know**: the
+ *   route on your server that mints a short-lived token. Everything else — the
+ *   Gemini session, the microphone, the player, the tool registry, the
+ *   controller, the provider and the widget — is built here, the same way in
+ *   every app, which is what makes it ours to write rather than yours.
+ * - **The controller is built once**, in a `useState` initialiser. It owns a
+ *   socket and two devices; rebuilding it on a render would start a session per
+ *   render. The session is stopped when this unmounts.
+ * - **Handlers are held, not depended on.** `onReady` and `onFailure` are read
+ *   through a ref, so passing them inline — which is how anyone passes them —
+ *   cannot re-run the lifecycle effect. It once could, and its cleanup hung up
+ *   on a live session whenever a parent re-rendered.
+ * - **`headers` and `language` are read at connection time, not at mount.** An
+ *   app whose `Authorization` header is refreshed mid-session would otherwise
+ *   reconnect with the token it had when the component first rendered — which
+ *   is exactly when a long conversation hands over to a new socket.
+ * - **A non-2xx from your endpoint is thrown on purpose.** It reaches the app
+ *   as `connection_refused` with the response in `failure.cause`, rather than
+ *   as a session that fails later for no stated reason.
+ * - **It does not own your navigation or your screens.** The page pack reads
+ *   the live DOM, so on the web it already works; a native app passes its own
+ *   tools, or `page: { router }`.
+ * - **Outgrowing it costs nothing**: build `AssistantController` yourself and
+ *   render `AssistantProvider` + `AssistantWidget`, which is all this does.
+ */
+function LiveAssistant({ tokenEndpoint, getConnection, language = DEFAULT_LANGUAGE, headers, tools, page, timing, onReady, onFailure, ...widget }) {
+    // Read at connection time rather than captured at mount: see the doc block.
+    const latest = (0, react_1.useRef)({ tokenEndpoint, getConnection, language, headers, onReady, onFailure });
+    latest.current = { tokenEndpoint, getConnection, language, headers, onReady, onFailure };
+    const [controller] = (0, react_1.useState)(() => new core_1.AssistantController({
+        session: new gemini_1.GeminiLiveSession(),
+        microphone: new audio_1.Microphone(),
+        player: new audio_1.PcmPlayer(),
+        tools: tools instanceof core_1.ToolRegistry ? tools : new core_1.ToolRegistry(tools ?? []),
+        ...(page === undefined ? {} : { page }),
+        ...(timing === undefined ? {} : { timing }),
+        getConnection: async ({ resumptionHandle }) => {
+            const current = latest.current;
+            if (current.getConnection !== undefined)
+                return current.getConnection({ resumptionHandle });
+            const response = await fetch(current.tokenEndpoint, {
+                method: 'POST',
+                headers: { 'content-type': JSON_TYPE, ...current.headers },
+                body: JSON.stringify({ resumptionHandle, languageCode: current.language }),
+            });
+            if (!response.ok)
+                throw new Error(`the token endpoint answered ${response.status}`);
+            return (await response.json());
+        },
+    }));
+    // Only the controller is a dependency. `onReady` used to be one too, and an
+    // inline arrow — the ordinary way to pass it — is a new function on every
+    // render, so the effect re-ran and its cleanup hung up on a live session
+    // whenever anything above this re-rendered.
+    (0, react_1.useEffect)(() => {
+        latest.current.onReady?.(controller);
+        return () => void controller.stop();
+    }, [controller]);
+    return ((0, jsx_runtime_1.jsxs)(react_2.AssistantProvider, { controller: controller, children: [(0, jsx_runtime_1.jsx)(FailureReporter, { onFailure: latest.current.onFailure }), (0, jsx_runtime_1.jsx)(widget_1.AssistantWidget, { ...widget })] }));
+}
+const selectError = (state) => state.error;
+/**
+ * Reports failures to the app without re-rendering the widget for them.
+ *
+ * The handler is held in a ref for the same reason the lifecycle effect takes
+ * only the controller: an inline arrow changes identity every render, and a
+ * handler in the dependencies would report the same failure again each time.
+ */
+function FailureReporter({ onFailure }) {
+    const error = (0, react_2.useAssistantState)(selectError);
+    const report = (0, react_1.useRef)(onFailure);
+    report.current = onFailure;
+    (0, react_1.useEffect)(() => {
+        if (error !== null)
+            report.current?.(error);
+    }, [error]);
+    return null;
+}
+//# sourceMappingURL=live-assistant.js.map

package/dist/live-assistant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-assistant.js","sourceRoot":"","sources":["../src/live-assistant.tsx"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@live-assistant/react-native",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "One install for a voice assistant in a React Native or Expo app: the session, a Gemini Live connection, microphone and playback, React bindings and a ready-made widget, all re-exported from one place.",
   "license": "MIT",
   "author": "Recep Tayyip Ekşi",
@@ -41,11 +41,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@live-assistant/audio": "0.2.0",
-    "@live-assistant/core": "0.2.0",
-    "@live-assistant/gemini": "0.2.0",
-    "@live-assistant/react": "0.2.0",
-    "@live-assistant/widget": "0.2.0"
+    "@live-assistant/audio": "0.3.1",
+    "@live-assistant/core": "0.3.1",
+    "@live-assistant/gemini": "0.3.1",
+    "@live-assistant/react": "0.3.1",
+    "@live-assistant/widget": "0.3.1"
   },
   "peerDependencies": {
     "react": ">=18",

package/src/index.ts

@@ -9,10 +9,13 @@
  *   should be able to leave out. None of those reasons apply to the ordinary
  *   case — an app that wants the assistant — and making that case install five
  *   packages and keep five versions in step is friction with nothing behind it.
- * - **It adds nothing of its own.** Every name here is re-exported unchanged,
- *   so reading the source of `@live-assistant/core` still explains what you
- *   are holding, and an app that outgrows this package can depend on the
- *   pieces directly without changing a single import.
+ * - **It adds exactly one thing of its own: `<LiveAssistant>`.** Everything
+ *   else is re-exported unchanged, so reading the source of
+ *   `@live-assistant/core` still explains what you are holding, and an app that
+ *   outgrows this package can depend on the pieces directly without changing an
+ *   import. The one addition exists because this is the only package that can
+ *   see the session, the audio and the widget at once — and because the forty
+ *   lines it replaces were identical in every app that would ever write them.
  * - **The token server is deliberately absent.** It mints credentials with an
  *   API key, which belongs on a server and never in an app bundle. It is
  *   installed on its own, where it runs.
@@ -22,3 +25,5 @@ export * from '@live-assistant/gemini';
 export * from '@live-assistant/audio';
 export * from '@live-assistant/react';
 export * from '@live-assistant/widget';
+export { LiveAssistant } from './live-assistant';
+export type { LiveAssistantProps } from './live-assistant';

package/src/live-assistant.tsx

@@ -0,0 +1,153 @@
+import { useEffect, useRef, useState } from 'react';
+import { AssistantController, ToolRegistry } from '@live-assistant/core';
+import type { AssistantControllerOptions, AssistantFailure, AssistantTool, PageToolsOptions } from '@live-assistant/core';
+import { Microphone, PcmPlayer } from '@live-assistant/audio';
+import { GeminiLiveSession } from '@live-assistant/gemini';
+import type { GeminiLiveCredentials } from '@live-assistant/gemini';
+import { AssistantProvider, useAssistantState } from '@live-assistant/react';
+import { AssistantWidget } from '@live-assistant/widget';
+import type { AssistantWidgetProps } from '@live-assistant/widget';
+
+/** Shared by both ways of connecting; see `LiveAssistantProps`. */
+interface LiveAssistantCommonProps extends AssistantWidgetProps {
+  /** Sent to your token endpoint as `languageCode`. Default `'en-US'`. */
+  readonly language?: string;
+  /** Added to the token request — this is where an app's own `Authorization` goes. Read fresh on every connection. */
+  readonly headers?: Readonly<Record<string, string>>;
+  /** Your app's own tools, on top of the page pack. */
+  readonly tools?: readonly AssistantTool[] | ToolRegistry;
+  /** Reading and driving the page. On by default in a browser; `false` removes it. */
+  readonly page?: boolean | PageToolsOptions;
+  readonly timing?: AssistantControllerOptions<GeminiLiveCredentials>['timing'];
+  /** Called with the controller once, for an app that wants to start or stop a session from elsewhere. */
+  readonly onReady?: (controller: AssistantController<GeminiLiveCredentials>) => void;
+  /** Called whenever a session fails. The widget already tells the user; this is for logging. */
+  readonly onFailure?: (failure: AssistantFailure) => void;
+}
+
+/** The endpoint form: the usual one. */
+interface LiveAssistantEndpointProps extends LiveAssistantCommonProps {
+  /** Your server's route that mints a short-lived token. The one value this component cannot invent. */
+  readonly tokenEndpoint: string;
+  readonly getConnection?: never;
+}
+
+/** The escape hatch: an app that already has its own client for the same thing. */
+interface LiveAssistantConnectionProps extends LiveAssistantCommonProps {
+  readonly getConnection: (request: { readonly resumptionHandle?: string }) => Promise<GeminiLiveCredentials>;
+  readonly tokenEndpoint?: never;
+}
+
+export type LiveAssistantProps = LiveAssistantEndpointProps | LiveAssistantConnectionProps;
+
+const DEFAULT_LANGUAGE = 'en-US';
+const JSON_TYPE = 'application/json';
+
+/**
+ * The whole integration: import it, put it in your tree, and there is a voice
+ * assistant on the screen.
+ *
+ * ```tsx
+ * <LiveAssistant tokenEndpoint="https://api.example.com/assistant/token" />
+ * ```
+ *
+ * @remarks
+ * - **One required value, because it is the only one we cannot know**: the
+ *   route on your server that mints a short-lived token. Everything else — the
+ *   Gemini session, the microphone, the player, the tool registry, the
+ *   controller, the provider and the widget — is built here, the same way in
+ *   every app, which is what makes it ours to write rather than yours.
+ * - **The controller is built once**, in a `useState` initialiser. It owns a
+ *   socket and two devices; rebuilding it on a render would start a session per
+ *   render. The session is stopped when this unmounts.
+ * - **Handlers are held, not depended on.** `onReady` and `onFailure` are read
+ *   through a ref, so passing them inline — which is how anyone passes them —
+ *   cannot re-run the lifecycle effect. It once could, and its cleanup hung up
+ *   on a live session whenever a parent re-rendered.
+ * - **`headers` and `language` are read at connection time, not at mount.** An
+ *   app whose `Authorization` header is refreshed mid-session would otherwise
+ *   reconnect with the token it had when the component first rendered — which
+ *   is exactly when a long conversation hands over to a new socket.
+ * - **A non-2xx from your endpoint is thrown on purpose.** It reaches the app
+ *   as `connection_refused` with the response in `failure.cause`, rather than
+ *   as a session that fails later for no stated reason.
+ * - **It does not own your navigation or your screens.** The page pack reads
+ *   the live DOM, so on the web it already works; a native app passes its own
+ *   tools, or `page: { router }`.
+ * - **Outgrowing it costs nothing**: build `AssistantController` yourself and
+ *   render `AssistantProvider` + `AssistantWidget`, which is all this does.
+ */
+export function LiveAssistant({
+  tokenEndpoint,
+  getConnection,
+  language = DEFAULT_LANGUAGE,
+  headers,
+  tools,
+  page,
+  timing,
+  onReady,
+  onFailure,
+  ...widget
+}: LiveAssistantProps) {
+  // Read at connection time rather than captured at mount: see the doc block.
+  const latest = useRef({ tokenEndpoint, getConnection, language, headers, onReady, onFailure });
+  latest.current = { tokenEndpoint, getConnection, language, headers, onReady, onFailure };
+
+  const [controller] = useState(
+    () =>
+      new AssistantController<GeminiLiveCredentials>({
+        session: new GeminiLiveSession(),
+        microphone: new Microphone(),
+        player: new PcmPlayer(),
+        tools: tools instanceof ToolRegistry ? tools : new ToolRegistry(tools ?? []),
+        ...(page === undefined ? {} : { page }),
+        ...(timing === undefined ? {} : { timing }),
+        getConnection: async ({ resumptionHandle }) => {
+          const current = latest.current;
+          if (current.getConnection !== undefined) return current.getConnection({ resumptionHandle });
+          const response = await fetch(current.tokenEndpoint as string, {
+            method: 'POST',
+            headers: { 'content-type': JSON_TYPE, ...current.headers },
+            body: JSON.stringify({ resumptionHandle, languageCode: current.language }),
+          });
+          if (!response.ok) throw new Error(`the token endpoint answered ${response.status}`);
+          return (await response.json()) as GeminiLiveCredentials;
+        },
+      }),
+  );
+
+  // Only the controller is a dependency. `onReady` used to be one too, and an
+  // inline arrow — the ordinary way to pass it — is a new function on every
+  // render, so the effect re-ran and its cleanup hung up on a live session
+  // whenever anything above this re-rendered.
+  useEffect(() => {
+    latest.current.onReady?.(controller);
+    return () => void controller.stop();
+  }, [controller]);
+
+  return (
+    <AssistantProvider controller={controller}>
+      <FailureReporter onFailure={latest.current.onFailure} />
+      <AssistantWidget {...widget} />
+    </AssistantProvider>
+  );
+}
+
+const selectError = (state: { readonly error: AssistantFailure | null }): AssistantFailure | null => state.error;
+
+/**
+ * Reports failures to the app without re-rendering the widget for them.
+ *
+ * The handler is held in a ref for the same reason the lifecycle effect takes
+ * only the controller: an inline arrow changes identity every render, and a
+ * handler in the dependencies would report the same failure again each time.
+ */
+function FailureReporter({ onFailure }: { readonly onFailure?: (failure: AssistantFailure) => void }) {
+  const error = useAssistantState(selectError);
+  const report = useRef(onFailure);
+  report.current = onFailure;
+  useEffect(() => {
+    if (error !== null) report.current?.(error);
+  }, [error]);
+  return null;
+}