@lumavox/react-native 0.0.0-stage → 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lumavox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,62 @@
-# Temporary Holding Version
+# @lumavox/react-native
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Voice conversations with Lumavox agents in a React Native app, on iOS,
+Android and the web — **one install**: the client (`@lumavox/client`), the
+hooks (`@lumavox/react`), and the audio they lack, a player and a recorder
+for **push-to-talk**, on
+[`react-native-audio-api`](https://github.com/software-mansion/react-native-audio-api)
+on a phone and Web Audio in a browser.
+
+```sh
+npm install @lumavox/react-native react-native-audio-api
+```
+
+React Native 0.76 or later on the New Architecture, iOS 17 and Android 12
+or later; with Expo, a development build — never Expo Go. In `app.json`:
+
+```json
+{ "expo": { "plugins": [["@lumavox/react-native", { "microphonePermission": "Hold to talk to your coach." }]] } }
+```
+
+**Never list `react-native-audio-api`'s plugin as well**: this one runs it
+with background audio off and every permission listed, and it runs once.
+
+```tsx
+import { AgentProvider, createAudio, createClient, useAgent } from "@lumavox/react-native";
+
+const lumavox = createClient({
+  // Your server mints the key with your API key (POST /v1/ephemeral-keys).
+  getToken: async () => (await fetch(keyServer, { method: "POST" })).text(),
+});
+
+function Talk({ agentId }: { agentId: string }) {
+  const audio = useMemo(() => createAudio(), []);
+  useEffect(() => () => audio.dispose(), [audio]);
+  const agent = useAgent({ agentId }, { audio });
+  return (
+    <Pressable
+      onPressIn={() => {
+        void audio.prime(); // in the press: the web needs it
+        void agent.startRecording();
+      }}
+      onPressOut={() => void agent.stopRecording()}
+    >
+      <Text>{agent.recording ? "Listening…" : "Hold to talk"}</Text>
+    </Pressable>
+  );
+}
+// <AgentProvider client={lumavox}><Talk agentId="agt_..." /></AgentProvider>
+```
+
+- Phones record at 16 kHz, browsers at 24 kHz; the agent plays from the
+  loudspeaker (`createAudio({ output: "earpiece" })` on iPhones), and
+  Bluetooth earbuds' microphone is used on iPhones.
+- A call, Siri or another app pauses the reply and throws away a recording
+  in progress — `interrupted`, `onAudioInterrupted`, `onAudioResumed`; so
+  does leaving the screen: no background audio in this release.
+- Hands-free and background audio come with `react-native-audio-api` 1.0.
+
+The guide, with the bare React Native setup: the docs' **SDKs** tab,
+*React Native*.
+
+MIT, copyright Lumavox.

package/app.plugin.js

@@ -0,0 +1,98 @@
+/**
+ * The Expo config plugin: `"plugins": [["@lumavox/react-native", { … }]]`
+ * in `app.json`. It runs `react-native-audio-api`'s own plugin with every
+ * option set here, because that plugin's defaults are wrong for a
+ * conversation and it cannot be set twice:
+ *
+ * - **Background is on by default there** — iOS's `audio` background mode
+ *   and an Android `mediaPlayback` foreground service. A conversation
+ *   pauses with the screen in this release (background is the app's choice
+ *   from hands-free on), so both are turned off.
+ * - **`androidPermissions` replaces its list**, which lacks
+ *   `RECORD_AUDIO`; nothing removes a permission. Ours is listed in full:
+ *   `RECORD_AUDIO`, and `MODIFY_AUDIO_SETTINGS` for the communication mode
+ *   the library's 1.0 sets. An app's own are added to it.
+ * - **It runs once** (`createRunOncePlugin`): listed in `app.json` as well,
+ *   the second listing's options are dropped without a word — so, listed
+ *   before this one, it is refused here, and the docs say never to list it.
+ *
+ * CommonJS, as Expo loads it with `require`: the package has no
+ * `"type": "module"` for that reason.
+ */
+
+/** The library's plugin's name in Expo's record of the plugins run. */
+const LIBRARY = "react-native-audio-api";
+
+const PERMISSIONS = [
+  "android.permission.RECORD_AUDIO",
+  "android.permission.MODIFY_AUDIO_SETTINGS",
+];
+
+/** iOS shows it when the app first asks for the microphone; the app's own words are better. */
+const MICROPHONE = "Hold to talk to the assistant.";
+
+/** What this plugin takes; anything else is a mistake, refused. */
+const OPTIONS = [
+  "microphonePermission",
+  "androidPermissions",
+  "disableFFmpeg",
+  "disableStaticExternalLibs",
+];
+
+/**
+ * The library's plugin's options for ours.
+ *
+ * @param {{
+ *   microphonePermission?: string,
+ *   androidPermissions?: string[],
+ *   disableFFmpeg?: boolean,
+ *   disableStaticExternalLibs?: boolean,
+ * }} [options]
+ */
+function audioApiOptions(options = {}) {
+  for (const name of Object.keys(options)) {
+    if (!OPTIONS.includes(name)) {
+      throw new Error(
+        `@lumavox/react-native's plugin takes ${OPTIONS.join(", ")}, not "${name}".`,
+      );
+    }
+  }
+  return {
+    iosMicrophonePermission: options.microphonePermission ?? MICROPHONE,
+    iosBackgroundMode: false,
+    androidPermissions: [
+      ...new Set([...PERMISSIONS, ...(options.androidPermissions ?? [])]),
+    ],
+    androidForegroundService: false,
+    androidFSTypes: [],
+    androidFSStopWithTask: true,
+    // The library's own defaults: FFmpeg decodes compressed files, which a
+    // conversation's raw PCM never needs — `true` makes the app smaller.
+    disableFFmpeg: options.disableFFmpeg ?? false,
+    disableStaticExternalLibs: options.disableStaticExternalLibs ?? false,
+  };
+}
+
+/**
+ * @param {any} config Expo's app config.
+ * @param {Parameters<typeof audioApiOptions>[0]} [options]
+ * @param {(config: any, options: object) => any} [library] the library's
+ *   plugin; Expo passes none, the tests a stand-in.
+ */
+function withLumavox(config, options, library) {
+  if (config?._internal?.pluginHistory?.[LIBRARY]) {
+    throw new Error(
+      `${LIBRARY}'s plugin is listed in app.json beside @lumavox/react-native's: remove it — @lumavox/react-native passes it every option, and it runs only once.`,
+    );
+  }
+  const run = library ?? loadLibrary();
+  return run(config, audioApiOptions(options));
+}
+
+function loadLibrary() {
+  const plugin = require(`${LIBRARY}/app.plugin`);
+  return plugin.default ?? plugin;
+}
+
+module.exports = withLumavox;
+module.exports.audioApiOptions = audioApiOptions;

package/dist/audio.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `createAudio` and `requestMicrophone` for whatever picks no platform
+ * file — TypeScript, a test runner, a bundler that is not React Native's:
+ * the browser's. Metro, React Native's bundler, takes `audio.native.ts` on
+ * iOS and Android and `audio.web.ts` on the web, since `index.ts` imports
+ * `./audio` with no extension; both answer `CreateAudio`.
+ */
+export { createAudio, requestMicrophone } from "./audio.web.js";

package/dist/audio.js

@@ -0,0 +1,8 @@
+/**
+ * `createAudio` and `requestMicrophone` for whatever picks no platform
+ * file — TypeScript, a test runner, a bundler that is not React Native's:
+ * the browser's. Metro, React Native's bundler, takes `audio.native.ts` on
+ * iOS and Android and `audio.web.ts` on the web, since `index.ts` imports
+ * `./audio` with no extension; both answer `CreateAudio`.
+ */
+export { createAudio, requestMicrophone } from "./audio.web.js";

package/dist/audio.native.d.ts

@@ -0,0 +1,50 @@
+import type { AudioOptions, CreateAudio, DeviceAudio, Output } from "./device-audio.js";
+/** Hz the microphone records at unless a rate the socket takes is asked. */
+export declare const RECORD_RATE = 16000;
+export declare class PhoneAudio implements DeviceAudio {
+    interrupted: boolean;
+    private context;
+    private queue;
+    /** The ids of the buffers enqueued and not yet played. */
+    private readonly playing;
+    /** A byte of a sample split across two frames. */
+    private carry;
+    private capture;
+    private readonly drained;
+    private readonly interruptions;
+    private readonly unwatch;
+    constructor(options?: AudioOptions);
+    prime(): Promise<void>;
+    play(pcm: ArrayBuffer, frame: {
+        sample_rate: number;
+    }): void;
+    stop(): void;
+    onDrained(fn: () => void): () => void;
+    /** At 16 kHz, or at the rate asked when the socket takes it. */
+    startCapture(onPcm: (pcm: ArrayBuffer) => void, options?: {
+        rate?: number;
+    }): Promise<{
+        rate: number;
+    }>;
+    stopCapture(): Promise<void>;
+    resume(): Promise<void>;
+    setOutput(output: Output): void;
+    onInterruption(fn: (interrupted: boolean) => void): () => void;
+    dispose(): void;
+    /** The queue for a reply at `rate`: this one, or a new context's. */
+    private player;
+    /**
+     * The wire's PCM as floats. **A split sample is carried, never dropped**:
+     * the edge sends whole samples (`apps/edge/src/voice/tts.ts`), but an odd
+     * byte dropped shifts every byte after it and turns the rest into noise —
+     * the bug that once made the console's playback white noise.
+     */
+    private samples;
+    /** The audio was taken: the reply waits, the recording is thrown away. */
+    private interrupt;
+    private quiet;
+    private tell;
+}
+export declare const createAudio: CreateAudio;
+/** Ask for the microphone, if it was not granted: whether it is now. */
+export declare const requestMicrophone: () => Promise<boolean>;

package/dist/audio.native.js

@@ -0,0 +1,250 @@
+/**
+ * A phone's player and recorder, on `react-native-audio-api` 0.13.6: what
+ * Metro picks for `./audio` on iOS and Android (`index.ts`). With
+ * `session.ts`, the only file that touches the library.
+ *
+ * - **The reply plays through one `AudioBufferQueueSourceNode`**, started
+ *   once: each frame's PCM is a buffer enqueued behind the last, gapless,
+ *   and a queue that runs dry plays silence until the next. `clearBuffers`
+ *   stops it at once.
+ * - **The context runs at the reply's rate**, rebuilt — what is queued
+ *   dropped — when an `audio.start` brings another: 0.13.6's queue plays
+ *   every buffer at its context's rate whatever the buffer says (its
+ *   `AudioBufferBaseSourceNode`), so a 24 kHz reply in a 48 kHz context
+ *   would play an octave up. The device's own resampling does the rest.
+ * - **The agent stopped speaking when the last buffer enqueued has ended**,
+ *   counted by the ids `enqueueBuffer` answers: the queue's own
+ *   `isLastBufferInQueue` can say so just as the next frame is enqueued, and
+ *   a buffer `clearBuffers` dropped never ends.
+ * - **The microphone records at 16 kHz**, mono, 100 ms a buffer — less to
+ *   send than 24 kHz, and a rate the socket takes. `onAudioReady` hands the
+ *   samples over JSI as floats, at the rate the device chose, which need
+ *   not be the one asked: read from the buffer and resampled (`resample`).
+ * - **An interruption** — a call, Siri, another app, the app leaving the
+ *   screen — suspends the context, so the reply's frames keep queueing and
+ *   play from where they stopped; and closes the recorder, whose audio is
+ *   thrown away (the hook discards the recording on the socket). The audio
+ *   comes back on its own when the system says it may, else on `resume()`
+ *   or the next press.
+ */
+import { DEFAULT_SAMPLE_RATE, floatToPcm16, pcm16ToFloat, RECORDING_RATES, resample, } from "@lumavox/client";
+import { AudioContext, AudioRecorder, } from "react-native-audio-api";
+import * as session from "./session.js";
+/** Hz the microphone records at unless a rate the socket takes is asked. */
+export const RECORD_RATE = 16000;
+/** Seconds of microphone per buffer delivered: the recorder's own latency. */
+const RECORD_SECONDS = 0.1;
+export class PhoneAudio {
+    constructor(options = {}) {
+        this.interrupted = false;
+        this.context = null;
+        this.queue = null;
+        /** The ids of the buffers enqueued and not yet played. */
+        this.playing = new Set();
+        /** A byte of a sample split across two frames. */
+        this.carry = null;
+        this.capture = null;
+        this.drained = new Set();
+        this.interruptions = new Set();
+        session.configure(options.output ?? "speaker");
+        this.unwatch = session.watch(({ began, shouldResume }) => {
+            if (began)
+                this.interrupt();
+            else if (shouldResume && this.interrupted) {
+                this.resume().catch(() => {
+                    // swallowed: still taken — `interrupted` stays, and `resume()` or the next press tries again.
+                });
+            }
+        });
+    }
+    async prime() {
+        await session.activate();
+        this.player(this.context?.sampleRate ?? DEFAULT_SAMPLE_RATE);
+    }
+    play(pcm, frame) {
+        const queue = this.player(frame.sample_rate);
+        const samples = this.samples(pcm);
+        if (samples.length === 0)
+            return;
+        const buffer = this.context.createBuffer(1, samples.length, frame.sample_rate);
+        buffer.copyToChannel(samples, 0);
+        this.playing.add(queue.enqueueBuffer(buffer));
+    }
+    stop() {
+        const was = this.playing.size > 0;
+        this.queue?.clearBuffers();
+        this.playing.clear();
+        // Half a sample of audio that will never play now.
+        this.carry = null;
+        if (was)
+            this.tell(this.drained);
+    }
+    onDrained(fn) {
+        this.drained.add(fn);
+        return () => {
+            this.drained.delete(fn);
+        };
+    }
+    /** At 16 kHz, or at the rate asked when the socket takes it. */
+    async startCapture(onPcm, options) {
+        // A press is the person going on: the audio is taken back first.
+        if (this.interrupted)
+            await this.resume();
+        if (!(await session.microphone())) {
+            throw new Error("Microphone permission was refused.");
+        }
+        // Taken again while the permission was asked: no recording through a call.
+        if (this.interrupted)
+            throw new Error("The audio was interrupted.");
+        const asked = options?.rate;
+        const rate = asked && RECORDING_RATES.includes(asked)
+            ? asked
+            : RECORD_RATE;
+        const recorder = new AudioRecorder();
+        const mine = { recorder, open: true };
+        const ready = recorder.onAudioReady({
+            sampleRate: rate,
+            bufferLength: Math.round(rate * RECORD_SECONDS),
+            channelCount: 1,
+        }, ({ buffer }) => {
+            if (!mine.open)
+                return;
+            const samples = buffer.getChannelData(0);
+            const at = buffer.sampleRate === rate
+                ? samples
+                : resample(samples, buffer.sampleRate, rate);
+            onPcm(floatToPcm16(at).buffer);
+        });
+        if (ready.status === "error")
+            throw new Error(ready.message);
+        this.capture = mine;
+        const started = await recorder.start();
+        if (started.status === "error" || !mine.open) {
+            if (this.capture === mine)
+                this.capture = null;
+            mine.open = false;
+            recorder.clearOnAudioReady();
+            throw new Error(started.status === "error"
+                ? started.message
+                : "The audio was interrupted.");
+        }
+        return { rate };
+    }
+    async stopCapture() {
+        const mine = this.capture;
+        this.capture = null;
+        if (!mine)
+            return;
+        try {
+            // What the recorder hands over until it has stopped is the end of
+            // the last word: delivered before this settles.
+            await mine.recorder.stop();
+        }
+        finally {
+            mine.open = false;
+            mine.recorder.clearOnAudioReady();
+        }
+    }
+    async resume() {
+        await session.activate();
+        await this.context?.resume();
+        if (!this.interrupted)
+            return;
+        this.interrupted = false;
+        this.tell(this.interruptions, false);
+    }
+    setOutput(output) {
+        session.configure(output);
+    }
+    onInterruption(fn) {
+        this.interruptions.add(fn);
+        return () => {
+            this.interruptions.delete(fn);
+        };
+    }
+    dispose() {
+        this.stop();
+        void this.stopCapture();
+        this.unwatch();
+        void this.context?.close();
+        this.context = null;
+        this.queue = null;
+    }
+    /** The queue for a reply at `rate`: this one, or a new context's. */
+    player(rate) {
+        if (this.queue && this.context?.sampleRate === rate)
+            return this.queue;
+        this.stop();
+        void this.context?.close();
+        const context = new AudioContext({ sampleRate: rate });
+        const queue = context.createBufferQueueSource();
+        queue.connect(context.destination);
+        queue.onBufferEnded = ({ bufferId }) => {
+            if (this.queue !== queue)
+                return;
+            if (this.playing.delete(bufferId) && this.playing.size === 0) {
+                this.tell(this.drained);
+            }
+        };
+        queue.start();
+        // Made while the audio is taken: it waits, as the one it replaced did.
+        if (this.interrupted)
+            this.quiet(context);
+        this.context = context;
+        this.queue = queue;
+        return queue;
+    }
+    /**
+     * The wire's PCM as floats. **A split sample is carried, never dropped**:
+     * the edge sends whole samples (`apps/edge/src/voice/tts.ts`), but an odd
+     * byte dropped shifts every byte after it and turns the rest into noise —
+     * the bug that once made the console's playback white noise.
+     */
+    samples(pcm) {
+        let bytes = new Uint8Array(pcm);
+        if (this.carry !== null) {
+            const joined = new Uint8Array(bytes.length + 1);
+            joined[0] = this.carry;
+            joined.set(bytes, 1);
+            bytes = joined;
+            this.carry = null;
+        }
+        if (bytes.length % 2) {
+            this.carry = bytes[bytes.length - 1];
+            bytes = bytes.slice(0, -1);
+        }
+        return pcm16ToFloat(bytes.buffer);
+    }
+    /** The audio was taken: the reply waits, the recording is thrown away. */
+    interrupt() {
+        if (this.interrupted)
+            return;
+        this.interrupted = true;
+        if (this.context)
+            this.quiet(this.context);
+        const mine = this.capture;
+        this.capture = null;
+        if (mine) {
+            mine.open = false;
+            mine.recorder
+                .stop()
+                .catch(() => {
+                // swallowed: the system has the microphone; it is closed either way.
+            })
+                .finally(() => mine.recorder.clearOnAudioReady());
+        }
+        this.tell(this.interruptions, true);
+    }
+    quiet(context) {
+        context.suspend().catch(() => {
+            // swallowed: an interruption may have stopped the engine already.
+        });
+    }
+    tell(listeners, ...args) {
+        for (const fn of listeners)
+            fn(...args);
+    }
+}
+export const createAudio = (options) => new PhoneAudio(options);
+/** Ask for the microphone, if it was not granted: whether it is now. */
+export const requestMicrophone = () => session.microphone();

package/dist/audio.web.d.ts

@@ -0,0 +1,4 @@
+import type { CreateAudio } from "./device-audio.js";
+export declare const createAudio: CreateAudio;
+/** Ask for the microphone, if it was not granted: whether it is now. */
+export declare function requestMicrophone(): Promise<boolean>;

package/dist/audio.web.js

@@ -0,0 +1,49 @@
+import { createWebAudio } from "@lumavox/client/web-audio";
+class BrowserAudio {
+    constructor() {
+        this.interrupted = false;
+        this.web = createWebAudio();
+    }
+    prime() {
+        return this.web.prime();
+    }
+    play(pcm, frame) {
+        this.web.play(pcm, frame);
+    }
+    stop() {
+        this.web.stop();
+    }
+    onDrained(fn) {
+        return this.web.onDrained(fn);
+    }
+    startCapture(onPcm, options) {
+        return this.web.startCapture(onPcm, options);
+    }
+    stopCapture() {
+        return this.web.stopCapture();
+    }
+    dispose() {
+        this.web.dispose();
+    }
+    resume() {
+        return this.web.prime();
+    }
+    setOutput(_output) { }
+    onInterruption(_fn) {
+        return () => { };
+    }
+}
+export const createAudio = () => new BrowserAudio();
+/** Ask for the microphone, if it was not granted: whether it is now. */
+export async function requestMicrophone() {
+    try {
+        const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+        for (const track of stream.getTracks())
+            track.stop();
+        return true;
+    }
+    catch {
+        // swallowed: a refusal, or no microphone, is the answer — `false`.
+        return false;
+    }
+}

package/dist/device-audio.d.ts

@@ -0,0 +1,39 @@
+/**
+ * What `createAudio()` answers on every platform — a phone's
+ * (`audio.native.ts`) and a browser's (`audio.web.ts`) — so an app written
+ * once runs on both: the `AgentAudio` that `useAgent` drives, and what an
+ * app does with the device itself.
+ */
+import type { AgentAudio } from "@lumavox/client";
+/** Where the agent is heard with no headphones on. */
+export type Output = "speaker" | "earpiece";
+export interface AudioOptions {
+    /**
+     * The loudspeaker (the default) or the earpiece, held to the ear like a
+     * call. Headphones and Bluetooth take over when connected, whichever.
+     * iPhones only: on Android the loudspeaker until `react-native-audio-api`
+     * 1.0 lets the earpiece be chosen.
+     */
+    output?: Output;
+}
+export interface DeviceAudio extends AgentAudio {
+    /**
+     * Get ready to play. **On the web, call it from the press that starts
+     * the conversation**: browsers start sound only from a gesture. On a
+     * phone it activates the audio session ahead of the first reply.
+     */
+    prime(): Promise<void>;
+    /** A call, Siri or another app has the audio: playback is paused. */
+    readonly interrupted: boolean;
+    /**
+     * Take the audio back after an interruption that did not give it back
+     * itself — the system said not to resume, or another app kept it.
+     * Rejects while it is still taken. Pressing to talk does it too.
+     */
+    resume(): Promise<void>;
+    /** The loudspeaker or the earpiece, from now on (`AudioOptions.output`). */
+    setOutput(output: Output): void;
+    onInterruption(fn: (interrupted: boolean) => void): () => void;
+}
+/** `createAudio`'s signature, which each platform's file implements. */
+export type CreateAudio = (options?: AudioOptions) => DeviceAudio;

package/dist/device-audio.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `@lumavox/react-native`: one install for a React Native app, on iOS,
+ * Android and the web — the client (`createClient`), the hooks
+ * (`useAgent` and the reads, `@lumavox/react`), and the audio they lack:
+ * `createAudio()`, a player and a recorder for push-to-talk, on
+ * `react-native-audio-api` on a phone and Web Audio in a browser.
+ *
+ * ```ts
+ * const audio = useMemo(() => createAudio(), []);
+ * const agent = useAgent({ agentId }, { audio });
+ * // press: agent.startRecording(); release: agent.stopRecording()
+ * ```
+ */
+export * from "@lumavox/client";
+export * from "@lumavox/react";
+export { createAudio, requestMicrophone } from "./audio";
+export type { AudioOptions, CreateAudio, DeviceAudio, Output, } from "./device-audio.js";

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * `@lumavox/react-native`: one install for a React Native app, on iOS,
+ * Android and the web — the client (`createClient`), the hooks
+ * (`useAgent` and the reads, `@lumavox/react`), and the audio they lack:
+ * `createAudio()`, a player and a recorder for push-to-talk, on
+ * `react-native-audio-api` on a phone and Web Audio in a browser.
+ *
+ * ```ts
+ * const audio = useMemo(() => createAudio(), []);
+ * const agent = useAgent({ agentId }, { audio });
+ * // press: agent.startRecording(); release: agent.stopRecording()
+ * ```
+ */
+export * from "@lumavox/client";
+export * from "@lumavox/react";
+// **No extension, on purpose**: Metro picks `audio.native.js` or
+// `audio.web.js` for `./audio` by platform, and only when the import names
+// none — `./audio.js` would be that file alone (`audio.ts`).
+export { createAudio, requestMicrophone } from "./audio";

package/dist/session.d.ts

@@ -0,0 +1,15 @@
+import type { Output } from "./device-audio.js";
+/** The audio session's category, mode and options for `output`. */
+export declare function configure(output: Output): void;
+/** Make the session active: before the first sound, and after an interruption. */
+export declare function activate(): Promise<void>;
+/** Whether the app may record: asked only when not granted yet. */
+export declare function microphone(): Promise<boolean>;
+export interface Interruption {
+    /** `true` when the audio is taken, `false` when it is given back. */
+    began: boolean;
+    /** Given back with the system's word that it may play again. */
+    shouldResume: boolean;
+}
+/** Every interruption, the system's and the screen's, until the answer is called. */
+export declare function watch(fn: (event: Interruption) => void): () => void;

package/dist/session.js

@@ -0,0 +1,80 @@
+/**
+ * The phone's audio session: how the app's audio sits beside the system's
+ * — the speaker, the earbuds, calls and other apps. With `audio.native.ts`
+ * the only file that touches `react-native-audio-api`, so its 1.0, which
+ * renames the session's API (`setSystemOptions`), changes these two and the
+ * peer range, and nothing an app sees.
+ *
+ * - **Play and record at once, from the loudspeaker** (`playAndRecord`,
+ *   `defaultToSpeaker`): without it iOS plays a recording app's audio from
+ *   the earpiece. Headphones and Bluetooth take over when connected; the
+ *   earpiece is the app's choice (`Output`). Android keeps the loudspeaker
+ *   until 1.0: 0.13.6 sets no communication mode, and so chooses no
+ *   earpiece.
+ * - **The earbuds' microphone on iPhones** (`allowBluetoothHFP`): their
+ *   hands-free profile, at call quality, for the whole conversation — not
+ *   switched per press, since every switch moves the route and 0.13.6's
+ *   engine can die on a Bluetooth route change (its #1209, for R3). Android
+ *   records from the phone until 1.0, whose `setInputDevice` works.
+ * - **`default` mode, not `voiceChat`**: on 0.13.6 `voiceChat` cancels no
+ *   echo — push-to-talk needs none, as the reply stops while the person
+ *   speaks — and plays at the call volume, quieter on the loudspeaker.
+ * - **Interruptions are watched** (`observeAudioInterruptions`): a call,
+ *   Siri or another app on iOS, a loss of audio focus on Android — which
+ *   watching *asks for*, so other apps' audio stops while a conversation is
+ *   on screen. And **the app leaving the screen** is one: no background
+ *   audio in this release (the plugin turns the library's off), so the
+ *   conversation pauses with the screen and goes on when it is back.
+ */
+import { AppState } from "react-native";
+import { AudioManager } from "react-native-audio-api";
+/** The audio session's category, mode and options for `output`. */
+export function configure(output) {
+    AudioManager.setAudioSessionOptions({
+        iosCategory: "playAndRecord",
+        iosMode: "default",
+        iosOptions: output === "speaker"
+            ? ["defaultToSpeaker", "allowBluetoothHFP"]
+            : ["allowBluetoothHFP"],
+    });
+}
+/** Make the session active: before the first sound, and after an interruption. */
+export function activate() {
+    return AudioManager.setAudioSessionActivity(true);
+}
+/** Whether the app may record: asked only when not granted yet. */
+export async function microphone() {
+    if ((await AudioManager.checkRecordingPermissions()) === "Granted") {
+        return true;
+    }
+    return (await AudioManager.requestRecordingPermissions()) === "Granted";
+}
+/** Adapters watching: interruptions are observed while any is. */
+let watching = 0;
+/** Every interruption, the system's and the screen's, until the answer is called. */
+export function watch(fn) {
+    if (watching++ === 0)
+        AudioManager.observeAudioInterruptions(true);
+    const system = AudioManager.addSystemEventListener("interruption", (event) => fn({ began: event.type === "began", shouldResume: event.shouldResume }));
+    let away = false;
+    const screen = AppState.addEventListener("change", (state) => {
+        if (state === "background") {
+            away = true;
+            fn({ began: true, shouldResume: true });
+        }
+        else if (state === "active" && away) {
+            away = false;
+            fn({ began: false, shouldResume: true });
+        }
+    });
+    let done = false;
+    return () => {
+        if (done)
+            return;
+        done = true;
+        system.remove();
+        screen.remove();
+        if (--watching === 0)
+            AudioManager.observeAudioInterruptions(false);
+    };
+}

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@lumavox/react-native",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.9.0",
+  "description": "Voice conversations with Lumavox agents in a React Native app, on iOS, Android and the web: the client, the React hooks, and push-to-talk audio on react-native-audio-api.",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "app.plugin.js"
+  ],
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "@ino/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./app.plugin.js": "./app.plugin.js",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepack": "node scripts/build.mjs",
+    "check": "biome check --write",
+    "format": "biome format --write",
+    "lint": "biome lint",
+    "test": "vitest run",
+    "test:unit": "vitest run",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p test"
+  },
+  "dependencies": {
+    "@lumavox/client": "0.9.0",
+    "@lumavox/react": "0.9.0"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-native": ">=0.76",
+    "react-native-audio-api": ">=0.13.6 <0.14"
+  },
+  "peerDependenciesMeta": {
+    "react-native": {
+      "optional": true
+    },
+    "react-native-audio-api": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.6.2",
+    "@types/node": "^24",
+    "@types/react": "^19",
+    "esbuild": "^0.28.1",
+    "react": "19.3.1",
+    "typescript": "^6",
+    "vitest": "^4.1.12"
+  }
+}