@graineai/inapp-react-native 0.4.0 → 0.9.0

package/INTEGRATION.md

@@ -0,0 +1,339 @@
+# Graine in-app agent — React Native
+
+A voice agent inside your app that can see the screen the customer is on and act
+on it. Target integration time: **under an hour**, because there is no native
+setup step.
+
+Package: `@graineai/inapp-react-native`
+
+---
+
+## What you need
+
+| | |
+|---|---|
+| React Native | 0.68+ |
+| React | 17+ |
+| Navigation | `@react-navigation/native` — optional, but it is what makes the agent screen-aware without per-screen code |
+| Peer install | `react-native-webview` — autolinks, no setup code |
+| From Graine | your **publishable key**, from Agent → Embed & Widgets |
+
+**There is no native setup.** No `MainApplication.kt` edit, no `AppDelegate.swift`
+edit, no ProGuard rules, no babel plugin ordering. The microphone and speaker run
+inside a WebView pointed at your hosted agent page, so every fix to the audio
+path ships over the air instead of through the app stores.
+
+You still declare microphone permission, because it is your app asking:
+
+**Android** — `android/app/src/main/AndroidManifest.xml`
+
+```xml
+<uses-permission android:name="android.permission.INTERNET" />
+<uses-permission android:name="android.permission.RECORD_AUDIO" />
+<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
+```
+
+**iOS** — `Info.plist`
+
+```xml
+<key>NSMicrophoneUsageDescription</key>
+<string>Used to talk to the in-app assistant.</string>
+```
+
+---
+
+## Install
+
+```bash
+npm install @graineai/inapp-react-native react-native-webview
+cd ios && pod install && cd ..     # for react-native-webview only
+```
+
+---
+
+## Step 1 — Wrap your app
+
+```tsx
+import { useRef } from "react";
+import { NavigationContainer } from "@react-navigation/native";
+import { WebView } from "react-native-webview";
+import {
+  GraineProvider,
+  GraineVoiceLauncher,
+  GraineAgentBar,
+} from "@graineai/inapp-react-native";
+
+export default function App() {
+  const navigationRef = useRef(null);
+
+  return (
+    <GraineProvider
+      baseUrl="https://www.graine.ai"
+      publishableKey="pk_live_..."
+      navigationRef={navigationRef}
+    >
+      <NavigationContainer ref={navigationRef}>
+        <RootNavigator />
+      </NavigationContainer>
+
+      <GraineVoiceLauncher webView={WebView} autoStart>
+        {() => <GraineAgentBar />}
+      </GraineVoiceLauncher>
+    </GraineProvider>
+  );
+}
+```
+
+`navigationRef` is the line that matters. With it the SDK reads the current route
+itself, so the agent knows which screen the customer is on without you calling
+anything per screen — including the screen you add next year when nobody
+remembers this page. Without it the agent still talks; it just has no idea where
+anyone is.
+
+Appearance — colour, title, logo — comes from the dashboard, not from props, so a
+brand change reaches every app without a release.
+
+At this point you have a working voice agent. Everything below makes it useful.
+
+---
+
+## Step 2 — Tell it who it is talking to
+
+```tsx
+const identify = useGraineIdentify();
+
+useEffect(() => {
+  if (user) identify({ name: user.name, plan: user.plan });
+  else identify(null);          // on sign-out
+}, [user, identify]);
+```
+
+Traits become prompt variables, so a prompt can say `greet {name}` or "the
+customer is on the {plan} plan". Everything is masked before it leaves the
+device, so passing a PAN or a card number by accident does not leak it.
+
+Nothing else is gated on this. Skip it and every other feature still works — the
+agent just does not know their name.
+
+---
+
+## Step 3 — Report what is ON the screen
+
+The route gives the agent a screen *name*. This gives it the contents.
+
+```tsx
+useGraineScreen(useMemo(() => ({
+  screen: "kyc_documents",
+  title: "Upload your documents",
+  journey: "onboarding",
+  fields: [
+    { name: "pan", label: "PAN", value: pan,
+      status: panError ? "invalid" : pan ? "filled" : "empty", error: panError },
+    { name: "address", label: "Address proof", value: addressFile?.name,
+      status: addressFile ? "filled" : "empty" },
+  ],
+}), [pan, panError, addressFile]));
+```
+
+**`status` is what makes proactive help work.** The SDK runs a 45-second timer per
+screen; when it fires it names the field that is `invalid` or `empty`, so the
+agent opens with "the PAN isn't being accepted" rather than "need a hand?".
+Without `status` it can only manage the second one.
+
+Report the real value. Masking happens on the way out and again on arrival — a
+screen that pre-redacts just blinds the agent.
+
+---
+
+## Step 4 — Let it act
+
+Two halves, and both are required.
+
+**In your app**, a handler:
+
+```tsx
+useGraineAction("set_tenure", ({ months }) => {
+  const n = Number(months);
+  if (!TENURES.includes(n))
+    return { status: "refused", message: `I can set ${TENURES.join(", ")} months.` };
+  setTenure(n);
+  return { status: "ok", message: `Tenure set to ${n} months.` };
+});
+```
+
+**In the dashboard**, the declaration: Agent → Embed & Widgets → "What this agent
+may do in your app". The name must match exactly. Saving pushes it to the agent
+immediately.
+
+Neither half works alone. A handler with no declaration is dead code; a
+declaration with no handler is worse, because the agent will promise it and the
+runtime answers "this app build does not implement it".
+
+Return a message saying what actually happened — the agent repeats it, so a vague
+result becomes a vague promise. **The runtime blocks on your handler**, so return
+promptly; anything slow should return immediately and report completion by
+updating the screen.
+
+---
+
+## Step 5 — Product events, without interrupting
+
+```tsx
+const track = useGraineTrack();
+track("payment_declined", { reason: "insufficient_funds", amount: 4999 });
+```
+
+This does **not** make the agent speak. It lands in the context, so when the
+customer asks "why was my card refused" the agent already knows. Use it for what
+explains a conversation: a declined payment, a rejected document, an OTP retried
+three times.
+
+The last 10 are kept. To make the agent speak first, report an event instead —
+and the runtime decides whether it is worth interrupting for.
+
+---
+
+## Step 6 — React to the conversation
+
+```tsx
+useGraineEvents((e) => {
+  switch (e.type) {
+    case "conversation_started": analytics.track("agent_call_started"); break;
+    case "conversation_ended":   analytics.track("agent_call_ended", { reason: e.reason }); break;
+    case "agent_volunteered":    analytics.track("agent_spoke_first"); break;
+    case "action_requested":     analytics.track("agent_action", { name: e.name }); break;
+  }
+});
+```
+
+Fires once, in order, at the moment it happens. `conversation_ended` carries a
+reason so a customer hanging up and a socket dying are not the same number in
+your funnel.
+
+---
+
+## Controlling where the launcher appears
+
+`includeScreens` for a simple allowlist:
+
+```tsx
+<GraineProvider includeScreens={["Home", "Settings"]} ... >
+```
+
+Groups when a flow needs its own rules:
+
+```tsx
+<GraineProvider
+  navigationRef={navigationRef}
+  visibility={{
+    defaultDelayMs: 1200,
+    defaultInset: { right: 16, bottom: 20 },
+    groups: [
+      { id: "kyc", screens: ["Step1", "Step2", "Step3"],
+        continuity: "continuous", delayMs: 1500,
+        delayPolicy: "oncePerGroupEntry", inset: { right: 16, bottom: 54 } },
+      { id: "done", screens: ["Confirmation"],
+        continuity: "perScreen", delayMs: 1500, delayPolicy: "oncePerAppSession" },
+    ],
+  }}
+>
+```
+
+| Setting | Effect |
+|---|---|
+| `continuity: "continuous"` | the launcher stays put across screens in the flow — no flicker between steps |
+| `delayPolicy: "oncePerGroupEntry"` | wait once on entering the flow, not on every step |
+| `delayPolicy: "oncePerAppSession"` | wait once per app run |
+| `inset` | clears tab bars and sheets, per flow |
+
+Screens named in any group count as included, so groups alone are enough. With
+**no** rules configured everything is eligible — the SDK does not hide its own
+button until you configure it.
+
+Walked through `Login -> Home -> Step1 -> Step2 -> Step3 -> Done -> Home ->
+Step1 -> Done` with the config above:
+
+```
+Login  not eligible
+Home   1200ms   default, no group
+Step1  1500ms   group entry
+Step2  0ms      continuous
+Step3  0ms      continuous
+Done   1500ms   first visit
+Step1  1500ms   re-entry after leaving
+Done   0ms      session policy already spent
+```
+
+Route names are **case-sensitive** and must match your navigator exactly.
+
+---
+
+## Without React Navigation
+
+Omit `navigationRef` and call `useGraineScreen` yourself on each screen — it
+carries `screen` as well as the fields, so nothing is lost except the automatic
+part. Everything else is unchanged.
+
+---
+
+## Troubleshooting
+
+**The agent talks but does not know what screen I am on.**
+`navigationRef` must be the same ref you pass to `NavigationContainer`, and
+`GraineProvider` must wrap it.
+
+**"Sorry, I can't help with that here."**
+The action is not declared in the dashboard, or the name does not match your
+`useGraineAction` exactly, or the screen did not list it in `availableActions`.
+The client may only narrow the declared list, never extend it.
+
+**No sound on iPhone.**
+The ringer switch. Your audio session needs `playsInSilentModeIOS: true` and
+`allowsRecordingIOS: true` while a call is live.
+
+**The launcher never appears.**
+The current route is not in `includeScreens` or any group, or a delay is still
+running. Omit `includeScreens` to test.
+
+**The agent interrupts itself after a word or two.**
+Echo. The SDK suppresses the agent's own voice from the microphone, but a very
+loud speaker defeats a level-based guard. Lower the volume, or use earphones to
+confirm that is what it is.
+
+---
+
+## Reference
+
+| Hook | For |
+|---|---|
+| `useGraineAgent()` | connection state, transcript, mute, send a turn |
+| `useGraineIdentify()` | who the customer is |
+| `useGraineScreen()` | what is on the screen |
+| `useGraineAction()` | one handler per declared action |
+| `useGraineTrack()` | product events that inform but do not interrupt |
+| `useGraineEvents()` | conversation lifecycle |
+| `useGraineVoice()` | only if you bring your own native audio instead of the WebView |
+
+`GraineProvider`: `baseUrl`, `publishableKey`, `navigationRef`, `includeScreens`,
+`launcherDelayMs`, `visibility`, `autoConnect`, `onProactive`.
+
+`GraineVoiceLauncher`: `webView` (required), `autoStart`, `onCaption`,
+`onCallState`, and a child function receiving `{ connected, connecting, muted,
+start, end, setMuted }`.
+
+---
+
+## Why there is no LiveKit step
+
+Other in-app agent SDKs run voice over LiveKit, which means native
+initialisation in `MainApplication.kt` and `AppDelegate.swift`, a pod install, a
+Lottie dependency, ProGuard rules, and a clean rebuild of both platforms. Their
+own documentation leads its troubleshooting with the error you get when one of
+those is missed.
+
+We put the audio in a WebView instead. The trade is real and worth stating: WebRTC
+gets acoustic echo cancellation from the platform's audio stack, and our
+level-based echo guard is an approximation of it that gives up when the speaker
+is very loud. What you get in exchange is that the audio path — where nearly
+every fix lands — ships over the air, and integration is an npm install rather
+than an afternoon in Xcode.

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { type ActionHandler, type AppEvent, type ScreenContext } from "./protocol";
+import { type ActionHandler, type AppActionResult, type AppEvent, type ScreenContext } from "./protocol";
 export declare const SUBPROTOCOL = "graine.embed.v1";
 export interface GraineInAppOptions {
     baseUrl: string;
@@ -37,6 +37,8 @@ export declare class GraineInAppClient {
     private bargedIn;
     private muted;
     private playoutClock;
+    private identity;
+    private recentEvents;
     constructor(opts: GraineInAppOptions);
     on(event: string, fn: Listener): () => void;
     private emit;
@@ -46,14 +48,20 @@ export declare class GraineInAppClient {
     connect(): Promise<void>;
     private send;
     private onFrame;
+    executeAction(name: string, args?: Record<string, unknown>): Promise<AppActionResult>;
     private runAction;
+    private invokeAction;
+    getScreen(): ScreenContext | null;
+    getAvailableActions(): string[];
     registerAction(name: string, handler: ActionHandler): () => void;
     get availableActions(): string[];
     setScreen(context: ScreenContext | null): void;
     reportEvent(event: AppEvent): void;
+    track(name: string, data?: Record<string, unknown>): void;
     private scheduleScreen;
     private flushScreen;
     private armStall;
+    identify(user: Record<string, unknown> | null): void;
     noteInteraction(): void;
     say(text: string): boolean;
     sendAudio(base64: string, sampleRate?: number): boolean;

package/dist/client.js

@@ -21,6 +21,8 @@ export class GraineInAppClient {
         this.bargedIn = false;
         this.muted = false;
         this.playoutClock = null;
+        this.identity = {};
+        this.recentEvents = [];
         if (!opts?.publishableKey)
             throw new Error("[Graine] publishableKey is required.");
         if (!opts?.baseUrl)
@@ -126,7 +128,11 @@ export class GraineInAppClient {
             event: "start",
             meta_data: {
                 client: "graine-inapp-sdk",
-                context_data: { ...(this.config.variables ?? {}), ...(this.opts.variables ?? {}) },
+                context_data: {
+                    ...(this.config.variables ?? {}),
+                    ...(this.opts.variables ?? {}),
+                    ...this.identity,
+                },
             },
         });
         this.pingTimer = setInterval(() => this.send({ type: "ping" }), PING_MS);
@@ -209,15 +215,20 @@ export class GraineInAppClient {
                 this.emit("frame", msg);
         }
     }
+    async executeAction(name, args = {}) {
+        return this.invokeAction({ action_id: "", name, arguments: args });
+    }
     async runAction(request) {
-        const reply = (result) => this.send({ type: "app_action_result", action_id: request.action_id, ...result });
+        const result = await this.invokeAction(request);
+        this.send({ type: "app_action_result", action_id: request.action_id, ...result });
+    }
+    async invokeAction(request) {
         const handler = this.actions.get(request.name);
         if (!handler) {
-            reply({
+            return {
                 status: "refused",
                 message: `This app build does not implement "${request.name}".`,
-            });
-            return;
+            };
         }
         this.emit("action", request);
         try {
@@ -225,20 +236,26 @@ export class GraineInAppClient {
                 Promise.resolve(handler(request.arguments ?? {})),
                 new Promise((_, rej) => setTimeout(() => rej(new Error("handler_timeout")), ACTION_DEADLINE_MS - 500)),
             ]);
-            reply(result && typeof result === "object" ? result : { status: "ok" });
+            return result && typeof result === "object" ? result : { status: "ok" };
         }
         catch (err) {
             const timedOut = err?.message === "handler_timeout";
             if (!timedOut)
                 console.error(`[Graine] action "${request.name}" threw`, err);
-            reply({
+            return {
                 status: "error",
                 message: timedOut
                     ? `"${request.name}" did not finish in time.`
                     : `"${request.name}" failed: ${err?.message ?? "unknown error"}`,
-            });
+            };
         }
     }
+    getScreen() {
+        return this.screen;
+    }
+    getAvailableActions() {
+        return [...this.actions.keys()];
+    }
     registerAction(name, handler) {
         this.actions.set(name, handler);
         this.scheduleScreen();
@@ -263,6 +280,15 @@ export class GraineInAppClient {
     reportEvent(event) {
         this.send({ type: "app_event", event });
     }
+    track(name, data) {
+        if (!name)
+            return;
+        this.recentEvents.push({ name, at: Date.now(), ...(data ? { data } : {}) });
+        if (this.recentEvents.length > 10)
+            this.recentEvents.shift();
+        if (this.screen)
+            this.scheduleScreen();
+    }
     scheduleScreen() {
         if (this.contextTimer) {
             this.pendingScreen = true;
@@ -284,7 +310,12 @@ export class GraineInAppClient {
         const { availableActions, ...rest } = this.screen;
         return this.send({
             type: "app_context",
-            context: maskDeep({ ...rest, idle_ms: Date.now() - this.screenSince }),
+            context: maskDeep({
+                ...rest,
+                idle_ms: Date.now() - this.screenSince,
+                ...(Object.keys(this.identity).length ? { user: this.identity } : {}),
+                ...(this.recentEvents.length ? { recent_events: this.recentEvents } : {}),
+            }),
             available_actions: (availableActions ?? this.availableActions).filter((a) => this.actions.has(a)),
             seq: ++this.screenSeq,
         });
@@ -310,6 +341,21 @@ export class GraineInAppClient {
             });
         }, after);
     }
+    identify(user) {
+        if (!user) {
+            this.identity = {};
+            return;
+        }
+        const flat = {};
+        for (const [k, v] of Object.entries(user)) {
+            if (v === undefined || v === null)
+                continue;
+            flat[k] = typeof v === "string" ? v : JSON.stringify(v);
+        }
+        this.identity = maskDeep(flat);
+        if (this.screen)
+            this.scheduleScreen();
+    }
     noteInteraction() {
         this.screenSince = Date.now();
         this.armStall();

package/dist/index.d.ts

@@ -3,5 +3,7 @@ export { GraineInAppClient, type GraineInAppOptions, type SessionConfig } from "
 export { VoiceSession, liveAudioStreamAdapter, base64ToPcm16, CAPTURE_SAMPLE_RATE, type AudioAdapter, type VoiceSessionOptions, } from "./voice";
 export { EchoGuard, decodeAgentAudio, decodeMuLaw, decodePcm16, base64ToBytes, type AudioFormat, type DecodedAudio, } from "./audio";
 export { addMaskRule, maskDeep, maskString } from "./mask";
-export { GraineProvider, useGraineAgent, useGraineScreen, useGraineAction, useGraineVoice, type GraineProviderProps, type Turn, type Caption, } from "./react-native/index";
+export { GraineProvider, useGraineAgent, useGraineScreen, useGraineAction, useGraineVoice, useGraineIdentify, useGraineEvents, useGraineTrack, type GraineEvent, type GraineProviderProps, type Turn, type Caption, } from "./react-native/index";
 export { GraineAgentBar, GraineLauncher, type GraineAgentBarProps, type GraineLauncherProps } from "./react-native/ui";
+export { GraineVoiceLauncher, type GraineVoiceLauncherProps, type GraineVoiceApi, } from "./react-native/voice-launcher";
+export { LauncherVisibilityTracker, activeRouteName, type LauncherInset, type LauncherContinuity, type LauncherDelayPolicy, type LauncherGroup, type LauncherVisibility, type VisibilityDecision, } from "./react-native/navigation";

package/dist/index.js

@@ -2,5 +2,7 @@ export { GraineInAppClient } from "./client";
 export { VoiceSession, liveAudioStreamAdapter, base64ToPcm16, CAPTURE_SAMPLE_RATE, } from "./voice";
 export { EchoGuard, decodeAgentAudio, decodeMuLaw, decodePcm16, base64ToBytes, } from "./audio";
 export { addMaskRule, maskDeep, maskString } from "./mask";
-export { GraineProvider, useGraineAgent, useGraineScreen, useGraineAction, useGraineVoice, } from "./react-native/index";
+export { GraineProvider, useGraineAgent, useGraineScreen, useGraineAction, useGraineVoice, useGraineIdentify, useGraineEvents, useGraineTrack, } from "./react-native/index";
 export { GraineAgentBar, GraineLauncher } from "./react-native/ui";
+export { GraineVoiceLauncher, } from "./react-native/voice-launcher";
+export { LauncherVisibilityTracker, activeRouteName, } from "./react-native/navigation";

package/dist/react-native/index.d.ts

@@ -2,6 +2,7 @@ import React from "react";
 import { GraineInAppClient, type GraineInAppOptions } from "../client";
 import { type AudioAdapter, type VoiceSessionOptions } from "../voice";
 import type { ActionHandler, ScreenContext } from "../protocol";
+import { type LauncherInset, type LauncherVisibility } from "./navigation";
 interface GraineContextValue {
     client: GraineInAppClient;
     connected: boolean;
@@ -16,7 +17,39 @@ interface GraineContextValue {
     setMuted: (muted: boolean) => void;
     agentSpeaking: boolean;
     caption: Caption | null;
+    launcherVisible: boolean;
+    launcherInset: LauncherInset;
+    currentScreen: string | null;
+    appearance: Record<string, any> | null;
+    onEvent: (fn: (e: GraineEvent) => void) => () => void;
+    track: (name: string, data?: Record<string, unknown>) => void;
+    identify: (user: Record<string, unknown> | null) => void;
 }
+export type GraineEvent = {
+    type: "conversation_started";
+} | {
+    type: "conversation_ended";
+    reason: string;
+} | {
+    type: "agent_speaking";
+    speaking: boolean;
+} | {
+    type: "agent_volunteered";
+    text: string;
+} | {
+    type: "action_requested";
+    name: string;
+} | {
+    type: "action_completed";
+    name: string;
+    status: string;
+} | {
+    type: "muted";
+    muted: boolean;
+} | {
+    type: "error";
+    message: string;
+};
 export interface Caption {
     role: "agent" | "customer";
     text: string;
@@ -31,9 +64,18 @@ export interface GraineProviderProps extends GraineInAppOptions {
     children: React.ReactNode;
     autoConnect?: boolean;
     onProactive?: (text: string) => void;
+    navigationRef?: {
+        current: any;
+    } | null;
+    includeScreens?: string[];
+    launcherDelayMs?: number;
+    visibility?: LauncherVisibility;
 }
-export declare function GraineProvider({ children, autoConnect, onProactive, ...options }: GraineProviderProps): React.JSX.Element;
+export declare function GraineProvider({ children, autoConnect, onProactive, navigationRef, includeScreens, launcherDelayMs, visibility, ...options }: GraineProviderProps): React.JSX.Element;
 export declare function useGraineAgent(): GraineContextValue;
+export declare function useGraineEvents(handler: (e: GraineEvent) => void): void;
+export declare function useGraineTrack(): (name: string, data?: Record<string, unknown>) => void;
+export declare function useGraineIdentify(): (user: Record<string, unknown> | null) => void;
 export declare function useGraineVoice(adapter: AudioAdapter | null, options?: VoiceSessionOptions): {
     listening: boolean;
     agentSpeaking: boolean;

package/dist/react-native/index.js

@@ -1,9 +1,10 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { createContext, useContext, useEffect, useMemo, useRef, useState, } from "react";
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, } from "react";
 import { GraineInAppClient } from "../client";
 import { VoiceSession } from "../voice";
+import { LauncherVisibilityTracker, activeRouteName, } from "./navigation";
 const Ctx = createContext(null);
-export function GraineProvider({ children, autoConnect = true, onProactive, ...options }) {
+export function GraineProvider({ children, autoConnect = true, onProactive, navigationRef, includeScreens, launcherDelayMs = 0, visibility, ...options }) {
     const clientRef = useRef(null);
     if (!clientRef.current)
         clientRef.current = new GraineInAppClient(options);
@@ -19,6 +20,82 @@ export function GraineProvider({ children, autoConnect = true, onProactive, ...o
     const [caption, setCaption] = useState(null);
     const proactiveRef = useRef(onProactive);
     proactiveRef.current = onProactive;
+    const listenersRef = useRef(new Set());
+    const emitEvent = useCallback((e) => {
+        listenersRef.current.forEach((fn) => {
+            try {
+                fn(e);
+            }
+            catch { }
+        });
+    }, []);
+    const onEvent = useCallback((fn) => {
+        listenersRef.current.add(fn);
+        return () => { listenersRef.current.delete(fn); };
+    }, []);
+    const [appearance, setAppearance] = useState(null);
+    const [currentScreen, setCurrentScreen] = useState(null);
+    const [launcherVisible, setLauncherVisible] = useState(false);
+    const [launcherInset, setLauncherInset] = useState({ right: 16, bottom: 20 });
+    const trackerRef = useRef(null);
+    if (!trackerRef.current) {
+        trackerRef.current = new LauncherVisibilityTracker(includeScreens, visibility, launcherDelayMs);
+    }
+    const showTimerRef = useRef(null);
+    useEffect(() => {
+        const nav = navigationRef?.current;
+        if (!nav || typeof nav.addListener !== "function")
+            return;
+        const apply = () => {
+            let route = null;
+            try {
+                route = activeRouteName(nav.getRootState?.());
+            }
+            catch {
+                route = null;
+            }
+            if (!route)
+                return;
+            setCurrentScreen(route);
+            try {
+                client.setScreen({ screen: route, title: route });
+            }
+            catch { }
+            const decision = trackerRef.current.onRoute(route);
+            setLauncherInset(decision.inset);
+            if (showTimerRef.current) {
+                clearTimeout(showTimerRef.current);
+                showTimerRef.current = null;
+            }
+            if (!decision.eligible) {
+                setLauncherVisible(false);
+                return;
+            }
+            if (decision.delayMs <= 0) {
+                setLauncherVisible(true);
+                return;
+            }
+            setLauncherVisible(false);
+            showTimerRef.current = setTimeout(() => {
+                showTimerRef.current = null;
+                setLauncherVisible(true);
+            }, decision.delayMs);
+        };
+        apply();
+        const off = nav.addListener("state", apply);
+        return () => {
+            if (showTimerRef.current)
+                clearTimeout(showTimerRef.current);
+            if (typeof off === "function")
+                off();
+            else if (typeof nav.removeListener === "function")
+                nav.removeListener("state", apply);
+        };
+    }, [navigationRef, client]);
+    useEffect(() => {
+        if (!navigationRef?.current)
+            setLauncherVisible(true);
+    }, [navigationRef]);
     const openRef = useRef(open);
     openRef.current = open;
     useEffect(() => {
@@ -27,8 +104,14 @@ export function GraineProvider({ children, autoConnect = true, onProactive, ...o
                 setConnected(true);
                 setConnecting(false);
                 setError(null);
+                if (client.config?.appearance)
+                    setAppearance(client.config.appearance);
+                emitEvent({ type: "conversation_started" });
+            }),
+            client.on("close", (info) => {
+                setConnected(false);
+                emitEvent({ type: "conversation_ended", reason: info?.reason || String(info?.code ?? "closed") });
             }),
-            client.on("close", () => setConnected(false)),
             client.on("chunk", (text) => setMessages((prev) => {
                 const last = prev[prev.length - 1];
                 if (last?.role === "agent" && last.live) {
@@ -36,18 +119,24 @@ export function GraineProvider({ children, autoConnect = true, onProactive, ...o
                 }
                 if (prev[prev.length - 1]?.role !== "customer") {
                     proactiveRef.current?.(text);
+                    emitEvent({ type: "agent_volunteered", text });
                     if (!openRef.current)
                         setOpen(true);
                 }
                 return [...prev, { role: "agent", text, live: true }];
             })),
             client.on("widget", (widget) => setWidgets((prev) => [...prev, widget])),
-            client.on("muted", (m) => setMutedState(m)),
+            client.on("muted", (m) => {
+                setMutedState(m);
+                emitEvent({ type: "muted", muted: m });
+            }),
             client.on("agent_speaking", (speaking) => {
                 setAgentSpeaking(speaking);
                 if (speaking)
                     setCaption(null);
+                emitEvent({ type: "agent_speaking", speaking });
             }),
+            client.on("action", (req) => emitEvent({ type: "action_requested", name: req?.name ?? "" })),
             client.on("transcript", ({ text, final }) => {
                 if (text)
                     setCaption({ role: "customer", text, live: !final });
@@ -92,7 +181,15 @@ export function GraineProvider({ children, autoConnect = true, onProactive, ...o
             client.noteInteraction();
             client.say(text);
         },
-    }), [client, connected, connecting, error, open, messages, widgets, muted, agentSpeaking, caption]);
+        launcherVisible,
+        launcherInset,
+        currentScreen,
+        appearance,
+        onEvent,
+        track: (name, data) => client.track(name, data),
+        identify: (user) => client.identify(user),
+    }), [client, connected, connecting, error, open, messages, widgets, muted, agentSpeaking, caption,
+        launcherVisible, launcherInset, currentScreen, onEvent, appearance]);
     return _jsx(Ctx.Provider, { value: value, children: children });
 }
 function useGraine() {
@@ -104,6 +201,20 @@ function useGraine() {
 export function useGraineAgent() {
     return useGraine();
 }
+export function useGraineEvents(handler) {
+    const { onEvent } = useGraine();
+    const ref = useRef(handler);
+    ref.current = handler;
+    useEffect(() => onEvent((e) => ref.current(e)), [onEvent]);
+}
+export function useGraineTrack() {
+    const { track } = useGraine();
+    return track;
+}
+export function useGraineIdentify() {
+    const { client } = useGraine();
+    return useCallback((user) => client.identify(user), [client]);
+}
 export function useGraineVoice(adapter, options = {}) {
     const { client } = useGraine();
     const [listening, setListening] = useState(false);

package/dist/react-native/navigation.d.ts

@@ -0,0 +1,44 @@
+export interface LauncherInset {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+}
+export type LauncherContinuity = "continuous" | "perScreen";
+export type LauncherDelayPolicy = "perScreen" | "oncePerGroupEntry" | "oncePerAppSession";
+export interface LauncherGroup {
+    id: string;
+    screens: string[];
+    continuity: LauncherContinuity;
+    inset?: LauncherInset;
+    delayMs?: number;
+    delayPolicy?: LauncherDelayPolicy;
+}
+export interface LauncherVisibility {
+    defaultDelayMs?: number;
+    defaultInset?: LauncherInset;
+    groups?: LauncherGroup[];
+}
+export interface VisibilityDecision {
+    eligible: boolean;
+    delayMs: number;
+    inset: LauncherInset;
+    groupId: string | null;
+    continuous: boolean;
+}
+export declare class LauncherVisibilityTracker {
+    private includeScreens;
+    private visibility;
+    private defaultDelayMs;
+    private enteredGroups;
+    private sessionDelayedGroups;
+    private lastGroupId;
+    private lastRoute;
+    constructor(includeScreens: string[] | undefined, visibility: LauncherVisibility | undefined, defaultDelayMs?: number);
+    reset(): void;
+    private groupFor;
+    private isEligible;
+    onRoute(route: string): VisibilityDecision;
+}
+export declare function activeRouteName(state: any): string | null;
+export declare function routeParams(state: any): Record<string, unknown> | undefined;

package/dist/react-native/navigation.js

@@ -0,0 +1,98 @@
+const DEFAULT_INSET = { right: 16, bottom: 20 };
+export class LauncherVisibilityTracker {
+    constructor(includeScreens, visibility, defaultDelayMs = 0) {
+        this.includeScreens = includeScreens;
+        this.visibility = visibility;
+        this.defaultDelayMs = defaultDelayMs;
+        this.enteredGroups = new Set();
+        this.sessionDelayedGroups = new Set();
+        this.lastGroupId = null;
+        this.lastRoute = null;
+    }
+    reset() {
+        this.enteredGroups.clear();
+        this.sessionDelayedGroups.clear();
+        this.lastGroupId = null;
+        this.lastRoute = null;
+    }
+    groupFor(route) {
+        for (const g of this.visibility?.groups || []) {
+            if (g.screens.includes(route))
+                return g;
+        }
+        return null;
+    }
+    isEligible(route) {
+        const groups = this.visibility?.groups || [];
+        const hasAllowlist = Array.isArray(this.includeScreens) && this.includeScreens.length > 0;
+        if (!hasAllowlist && groups.length === 0)
+            return true;
+        if (hasAllowlist && this.includeScreens.includes(route))
+            return true;
+        return groups.some((g) => g.screens.includes(route));
+    }
+    onRoute(route) {
+        const eligible = this.isEligible(route);
+        const group = this.groupFor(route);
+        const inset = group?.inset || this.visibility?.defaultInset || DEFAULT_INSET;
+        if (!eligible) {
+            this.lastGroupId = null;
+            this.lastRoute = route;
+            return { eligible: false, delayMs: 0, inset, groupId: group?.id ?? null, continuous: false };
+        }
+        const configuredDelay = group?.delayMs ?? this.visibility?.defaultDelayMs ?? this.defaultDelayMs;
+        const policy = group?.delayPolicy ?? "perScreen";
+        const continuity = group?.continuity ?? "perScreen";
+        const stayingInGroup = group != null && this.lastGroupId === group.id;
+        const movedScreen = this.lastRoute !== route;
+        const continuous = continuity === "continuous" && stayingInGroup && movedScreen;
+        let delayMs = configuredDelay;
+        if (continuous) {
+            delayMs = 0;
+        }
+        else if (group) {
+            if (policy === "oncePerGroupEntry" && stayingInGroup) {
+                delayMs = 0;
+            }
+            else if (policy === "oncePerAppSession") {
+                delayMs = this.sessionDelayedGroups.has(group.id) ? 0 : configuredDelay;
+                this.sessionDelayedGroups.add(group.id);
+            }
+            if (!stayingInGroup)
+                this.enteredGroups.add(group.id);
+        }
+        this.lastGroupId = group?.id ?? null;
+        this.lastRoute = route;
+        return { eligible: true, delayMs, inset, groupId: group?.id ?? null, continuous };
+    }
+}
+export function activeRouteName(state) {
+    if (!state || !Array.isArray(state.routes) || typeof state.index !== "number")
+        return null;
+    let route = state.routes[state.index];
+    while (route?.state) {
+        const child = route.state;
+        if (!Array.isArray(child.routes))
+            break;
+        const idx = typeof child.index === "number" ? child.index : child.routes.length - 1;
+        const next = child.routes[idx];
+        if (!next)
+            break;
+        route = next;
+    }
+    return route?.name ?? null;
+}
+export function routeParams(state) {
+    if (!state || !Array.isArray(state.routes) || typeof state.index !== "number")
+        return undefined;
+    let route = state.routes[state.index];
+    while (route?.state?.routes) {
+        const child = route.state;
+        const idx = typeof child.index === "number" ? child.index : child.routes.length - 1;
+        const next = child.routes[idx];
+        if (!next)
+            break;
+        route = next;
+    }
+    return route?.params && typeof route.params === "object" ? route.params : undefined;
+}

package/dist/react-native/ui.d.ts

@@ -7,6 +7,6 @@ export interface GraineAgentBarProps {
     hidden?: boolean;
     captionsOn?: boolean;
 }
-export declare function GraineAgentBar({ accent, name, avatarUrl, bottomInset, hidden, captionsOn, }: GraineAgentBarProps): React.JSX.Element | null;
+export declare function GraineAgentBar({ accent: accentProp, name: nameProp, avatarUrl: avatarProp, bottomInset, hidden, captionsOn, }: GraineAgentBarProps): React.JSX.Element | null;
 export declare const GraineLauncher: typeof GraineAgentBar;
 export type GraineLauncherProps = GraineAgentBarProps;

package/dist/react-native/ui.js

@@ -2,8 +2,11 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { ActivityIndicator, Image, KeyboardAvoidingView, Platform, Pressable, ScrollView, StyleSheet, Text, TextInput, View, } from "react-native";
 import { useGraineAgent } from "./index";
-export function GraineAgentBar({ accent = "#318CE7", name = "Assistant", avatarUrl, bottomInset = 96, hidden = false, captionsOn = false, }) {
-    const { connected, connecting, error, messages, send, muted, setMuted, caption, agentSpeaking } = useGraineAgent();
+export function GraineAgentBar({ accent: accentProp, name: nameProp, avatarUrl: avatarProp, bottomInset = 96, hidden = false, captionsOn = false, }) {
+    const { connected, connecting, error, messages, send, muted, setMuted, caption, agentSpeaking, launcherVisible, launcherInset, appearance, } = useGraineAgent();
+    const accent = accentProp ?? appearance?.accent ?? "#318CE7";
+    const name = nameProp ?? appearance?.title ?? "Assistant";
+    const avatarUrl = avatarProp ?? appearance?.logo ?? undefined;
     const [expanded, setExpanded] = useState(false);
     const [captions, setCaptions] = useState(captionsOn);
     const [draft, setDraft] = useState("");
@@ -31,9 +34,16 @@ export function GraineAgentBar({ accent = "#318CE7", name = "Assistant", avatarU
         setDraft("");
         send(text);
     }, [draft, send]);
-    if (hidden || error)
+    if (hidden || error || !launcherVisible)
         return null;
-    return (_jsxs(View, { pointerEvents: "box-none", style: [styles.root, { bottom: bottomInset }], children: [expanded && (_jsxs(View, { style: styles.panel, children: [_jsxs(ScrollView, { ref: scrollRef, style: styles.transcript, contentContainerStyle: styles.transcriptInner, showsVerticalScrollIndicator: false, children: [messages.length === 0 && (_jsx(Text, { style: styles.empty, children: "I can see what you're working on \u2014 ask me anything, or I'll step in if you get stuck." })), messages.map((m, i) => (_jsx(View, { style: [
+    return (_jsxs(View, { pointerEvents: "box-none", style: [
+            styles.root,
+            {
+                bottom: launcherInset.bottom ?? bottomInset,
+                right: launcherInset.right ?? 12,
+                left: launcherInset.left ?? 12,
+            },
+        ], children: [expanded && (_jsxs(View, { style: styles.panel, children: [_jsxs(ScrollView, { ref: scrollRef, style: styles.transcript, contentContainerStyle: styles.transcriptInner, showsVerticalScrollIndicator: false, children: [messages.length === 0 && (_jsx(Text, { style: styles.empty, children: "I can see what you're working on \u2014 ask me anything, or I'll step in if you get stuck." })), messages.map((m, i) => (_jsx(View, { style: [
                                     styles.bubble,
                                     m.role === "agent" ? styles.agentBubble : [styles.customerBubble, { backgroundColor: accent }],
                                 ], children: _jsx(Text, { style: m.role === "agent" ? styles.agentText : styles.customerText, children: m.text }) }, i)))] }), _jsx(KeyboardAvoidingView, { behavior: Platform.OS === "ios" ? "padding" : undefined, children: _jsxs(View, { style: styles.composer, children: [_jsx(TextInput, { style: styles.input, value: draft, onChangeText: setDraft, placeholder: "Type a message", placeholderTextColor: "#8a8f98", onSubmitEditing: submit, returnKeyType: "send", blurOnSubmit: false }), _jsx(Pressable, { onPress: submit, disabled: !draft.trim(), accessibilityLabel: "Send", style: [styles.send, { backgroundColor: accent, opacity: draft.trim() ? 1 : 0.4 }], children: _jsx(Text, { style: styles.sendLabel, children: "\u2191" }) })] }) })] })), captions && caption?.text ? (_jsx(View, { style: styles.captionWrap, children: _jsx(Text, { numberOfLines: 3, style: [styles.caption, caption.live && styles.captionLive], children: caption.text }) })) : null, _jsxs(View, { style: styles.bar, children: [avatarUrl ? (_jsx(Image, { source: { uri: avatarUrl }, style: styles.avatarImage, accessibilityIgnoresInvertColors: true })) : (_jsx(View, { style: [styles.avatar, { backgroundColor: accent }], children: _jsx(Text, { style: styles.avatarGlyph, children: "\u2726" }) })), _jsxs(Pressable, { onPress: () => setExpanded((v) => !v), style: { flex: 1 }, accessibilityLabel: expanded ? "Collapse" : "Expand", children: [_jsx(Text, { style: styles.name, children: name }), _jsx(Text, { style: styles.status, children: status })] }), connecting ? _jsx(ActivityIndicator, { size: "small", color: accent }) : null, _jsx(Pressable, { onPress: () => setCaptions((v) => !v), hitSlop: 8, accessibilityLabel: captions ? "Hide captions" : "Show captions", style: [styles.round, captions && { backgroundColor: accent }], children: _jsx(Text, { style: [styles.glyph, captions && { color: "#fff" }], children: "CC" }) }), _jsx(Pressable, { onPress: () => setMuted(!muted), disabled: !connected, hitSlop: 8, accessibilityLabel: muted ? "Unmute" : "Mute", style: [styles.round, muted && styles.muted, !connected && { opacity: 0.4 }], children: _jsx(Text, { style: [styles.glyph, muted && { color: "#fff" }], children: muted ? "🔇" : "🎙" }) }), _jsx(Pressable, { onPress: () => setExpanded((v) => !v), hitSlop: 8, accessibilityLabel: expanded ? "Collapse" : "Expand", style: styles.round, children: _jsx(Text, { style: styles.chevron, children: expanded ? "⌄" : "⌃" }) })] })] }));

package/dist/react-native/voice-launcher.d.ts

@@ -0,0 +1,24 @@
+import React from "react";
+export interface GraineVoiceLauncherProps {
+    webView: React.ComponentType<any>;
+    autoStart?: boolean;
+    onCaption?: (c: {
+        role: string;
+        text: string;
+        live: boolean;
+    }) => void;
+    onCallState?: (s: {
+        connected: boolean;
+        connecting: boolean;
+    }) => void;
+    children?: (api: GraineVoiceApi) => React.ReactNode;
+}
+export interface GraineVoiceApi {
+    connected: boolean;
+    connecting: boolean;
+    muted: boolean;
+    start: () => void;
+    end: () => void;
+    setMuted: (m: boolean) => void;
+}
+export declare function GraineVoiceLauncher({ webView: WebView, autoStart, onCaption, onCallState, children, }: GraineVoiceLauncherProps): React.JSX.Element;

package/dist/react-native/voice-launcher.js

@@ -0,0 +1,93 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { View } from "react-native";
+import { useGraineAgent } from "./index";
+export function GraineVoiceLauncher({ webView: WebView, autoStart = false, onCaption, onCallState, children, }) {
+    const { client, appearance } = useGraineAgent();
+    const ref = useRef(null);
+    const [connected, setConnected] = useState(false);
+    const [connecting, setConnecting] = useState(false);
+    const [muted, setMutedState] = useState(false);
+    const [ready, setReady] = useState(false);
+    const post = useCallback((msg) => {
+        ref.current?.injectJavaScript(`window.postMessage(${JSON.stringify(msg)}, "*"); true;`);
+    }, []);
+    const pushContext = useCallback(() => {
+        const screen = client.getScreen();
+        if (!screen)
+            return;
+        const { availableActions, ...rest } = screen;
+        post({
+            type: "graine:app-context",
+            context: rest,
+            availableActions: (availableActions ?? client.getAvailableActions()).filter((a) => client.getAvailableActions().includes(a)),
+            seq: Date.now(),
+        });
+    }, [client, post]);
+    useEffect(() => {
+        if (ready)
+            pushContext();
+    }, [ready, pushContext]);
+    const onMessage = useCallback(async (e) => {
+        let msg;
+        try {
+            msg = JSON.parse(e?.nativeEvent?.data ?? "{}");
+        }
+        catch {
+            return;
+        }
+        switch (msg.type) {
+            case "graine:ready":
+                setReady(true);
+                pushContext();
+                if (autoStart)
+                    post({ type: "graine:start-call" });
+                return;
+            case "graine:call":
+                setConnected(!!msg.connected);
+                setConnecting(!!msg.connecting);
+                onCallState?.({ connected: !!msg.connected, connecting: !!msg.connecting });
+                return;
+            case "graine:muted":
+                setMutedState(!!msg.muted);
+                return;
+            case "graine:caption":
+                onCaption?.({ role: msg.role, text: msg.text, live: !!msg.live });
+                return;
+            case "graine:app-action": {
+                const action = msg.action || {};
+                const result = await client.executeAction(action.name, action.arguments || {});
+                post({
+                    type: "graine:app-action-result",
+                    actionId: action.action_id,
+                    status: result.status,
+                    message: result.message ?? "",
+                    data: result.data ?? {},
+                });
+                return;
+            }
+        }
+    }, [autoStart, client, onCaption, onCallState, post, pushContext]);
+    const api = {
+        connected,
+        connecting,
+        muted,
+        start: useCallback(() => {
+            setConnecting(true);
+            post({ type: "graine:start-call" });
+        }, [post]),
+        end: useCallback(() => post({ type: "graine:end-call" }), [post]),
+        setMuted: useCallback((m) => {
+            setMutedState(m);
+            post({ type: "graine:set-muted", muted: m });
+        }, [post]),
+    };
+    useEffect(() => () => { post({ type: "graine:end-call" }); }, [post]);
+    const agentId = client.config?.agentId;
+    if (!agentId)
+        return _jsx(_Fragment, { children: children?.(api) });
+    const src = `${client.opts.baseUrl.replace(/\/$/, "")}/embed/${agentId}` +
+        `?mode=voice&branding=0&embed=1` +
+        (appearance?.accent ? `&accent=${encodeURIComponent(String(appearance.accent).replace("#", ""))}` : "");
+    return (_jsxs(_Fragment, { children: [_jsx(View, { style: { position: "absolute", width: 1, height: 1, opacity: 0, bottom: 0, left: 0 }, pointerEvents: "none", children: _jsx(WebView, { ref: ref, source: { uri: src }, originWhitelist: ["*"], javaScriptEnabled: true, domStorageEnabled: true, allowsInlineMediaPlayback: true, mediaPlaybackRequiresUserAction: false, mediaCapturePermissionGrantType: "grant", onMessage: onMessage, style: { width: 1, height: 1, backgroundColor: "transparent" } }) }), children?.(api)] }));
+}

package/dist/voice.d.ts

@@ -22,9 +22,11 @@ export declare class VoiceSession {
     private format;
     private echo;
     private agentAudible;
+    private lastAudioAt;
     constructor(client: GraineInAppClient, adapter: AudioAdapter, options?: VoiceSessionOptions);
     get active(): boolean;
     start(): Promise<void>;
+    private agentIsAudible;
     stop(): Promise<void>;
 }
 export declare function liveAudioStreamAdapter(LiveAudioStream: any, sink: Pick<AudioAdapter, "play" | "clear">): AudioAdapter;

package/dist/voice.js

@@ -14,6 +14,7 @@ export class VoiceSession {
         this.format = null;
         this.echo = new EchoGuard();
         this.agentAudible = false;
+        this.lastAudioAt = 0;
     }
     get active() {
         return this.capturing;
@@ -29,6 +30,7 @@ export class VoiceSession {
                     return;
                 if (decoded.latch)
                     this.format = decoded.latch;
+                this.lastAudioAt = Date.now();
                 this.adapter.play(decoded.pcm16, decoded.sampleRate);
             }),
             this.client.on("clear", () => {
@@ -51,19 +53,24 @@ export class VoiceSession {
         await this.adapter.startCapture((base64) => {
             const pcm = base64ToPcm16(base64);
             const frameMs = (pcm.length / CAPTURE_SAMPLE_RATE) * 1000;
-            const buffered = this.adapter.bufferedSeconds?.();
-            const audible = buffered !== undefined ? buffered > 0.02 || this.agentAudible : this.agentAudible;
-            for (const frame of this.echo.filter(base64, pcm, audible, frameMs)) {
+            for (const frame of this.echo.filter(base64, pcm, this.agentIsAudible(), frameMs)) {
                 this.client.sendAudio(frame, CAPTURE_SAMPLE_RATE);
             }
         });
     }
+    agentIsAudible() {
+        if (Date.now() - this.lastAudioAt > 1500)
+            return false;
+        const buffered = this.adapter.bufferedSeconds?.();
+        return buffered !== undefined ? buffered > 0.02 || this.agentAudible : this.agentAudible;
+    }
     async stop() {
         if (!this.capturing)
             return;
         this.capturing = false;
         this.format = null;
         this.agentAudible = false;
+        this.lastAudioAt = 0;
         this.echo.reset();
         this.offs.forEach((off) => off());
         this.offs = [];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@graineai/inapp-react-native",
-  "version": "0.4.0",
-  "description": "Graine in-app agent for React Native — an agent that sees the screen your customer is on and can act on it.",
+  "version": "0.9.0",
+  "description": "Graine in-app agent for React Native \u2014 an agent that sees the screen your customer is on and can act on it.",
   "license": "MIT",
   "private": false,
   "main": "dist/index.js",
@@ -25,7 +25,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "INTEGRATION.md"
   ],
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json",