@graineai/inapp-react-native 0.24.0 → 0.26.0

package/INTEGRATION.md

@@ -809,6 +809,33 @@ useGraineEvents((e) => {
 });
 ```
 
+## Fast navigation: the agent always has the latest screen
+
+A customer who taps through four screens and then asks "where am I?" gets the
+fourth. The guarantees, so you do not have to think about them:
+
+- **Immediate.** `useGraineScreen` reports a screen the moment it mounts, and
+  the voice launcher relays it to the runtime at once — the 400ms coalescing
+  applies only to the SDK's own text socket, never to a host's channel.
+- **Ordered.** Every context frame carries a monotonic `seq`; the runtime keeps
+  the newest and drops anything that arrives late. The last screen always wins.
+- **Cleanup-safe.** A screen's unmount clears the screen only if it is still
+  the one being described (`client.clearScreen(id)`), so a navigation library
+  unmounting the old screen after the new one mounted cannot erase it.
+- **Reconnect-safe.** The newest context is replayed whenever the media or the
+  screen channel (re)connects.
+- **Applied every turn.** The runtime puts the last-reported screen on the
+  prompt at every generation, so nothing that rewrites the prompt mid-call — a
+  language switch, a summary — can make the agent forget where the customer is.
+
+Every reporting hook works **outside a provider** too — against the client the
+provider registered, or one you pass to `setDefaultClient(client)` once — so an
+app whose provider wraps only its bar has no reason to re-implement them.
+
+If you drive the client yourself instead of using `useGraineScreen`, call
+`client.setScreen(ctx)` on mount and `client.clearScreen(ctx.screen)` on
+unmount — never `setScreen(null)` from a cleanup.
+
 ## What Call History shows for an in-app conversation
 
 Every conversation lands in the dashboard's Call History with, beside the
@@ -876,11 +903,13 @@ told to ignore).
 | `useGraineAgent()` | connection state, transcript, mute, send a turn |
 | `useGraineIdentify()` | who the customer is |
 | `useGraineScreen()` | what is on the screen |
+| `useGraineField()` | one input as it changes — value, error, status; friction reads it |
 | `useGraineAction()` | one handler per declared action |
 | `useGraineHighlight()` | let the agent point at an element on this screen |
 | `useGraineWidget()` | the component the agent drew, and how to answer it |
 | `useGraineTrack()` | product events that inform but do not interrupt |
-| `useGraineEvents()` | conversation lifecycle |
+| `useGraineEvents()` | conversation lifecycle, action outcomes, friction signals |
+| `useGraineTap()` | wrap an `onPress` so the tap is tracked (and rage taps detected) |
 | `useGraineVoice()` | only if you bring your own native audio instead of the WebView |
 
 ### `GraineProvider`
@@ -897,6 +926,21 @@ told to ignore).
 | `autoConnect` | `boolean` | Default `true`. Set `false` when `GraineVoiceLauncher` owns the connection — see below. |
 | `onProactive` | `(text) => void` | The agent spoke first; draw your own nudge. |
 | `endOnBackground` | `boolean` | Default `true`. You want it on. |
+| `appVersion` | `string` | Which build the conversation happened in. Lands on the call record. |
+| `friction` | `FrictionConfig` | This app's friction rules, layered over the dashboard's. See *Friction detection*. |
+
+### `GraineInAppClient`
+
+| Method | For |
+|---|---|
+| `setScreen(ctx)` / `clearScreen(id)` | Report a screen; withdraw it only if it is still the current one. |
+| `updateField(field)` / `removeField(name)` | One input changed; merged into the current screen by name. |
+| `identify(user)` | Who the customer is. Masked on the way out. |
+| `track(name, data)` / `reportEvent(event)` | Inform the agent / ask it to speak up. |
+| `registerAction(name, handler)` / `executeAction(name, args)` | Implement and run in-app actions. |
+| `configureFriction(rules)` / `friction` | Replace the app's friction layer / read the resolved rules. |
+| `session()` | The dashboard config for this key: appearance, actions, friction. |
+| `on(event, fn)` | `screen`, `action`, `action_result`, `friction`, `app_event`, `mic_denied`, … |
 
 ### `GraineVoiceLauncher`
 

package/README.md

@@ -217,13 +217,30 @@ requests a permission on your behalf.
 | `GraineProvider` | Connects the agent. Set `voice` for spoken conversations. |
 | `useGraineAgent()` | Connection state, transcript, and `send()`. |
 | `useGraineScreen(context)` | Report what this screen shows. |
+| `useGraineField(name, field)` | One input as it changes — value, error, status. |
 | `useGraineAction(name, handler)` | Implement one action the agent may call. |
 | `useGraineVoice(adapter, opts)` | Microphone, playback and barge-in. |
+| `useGraineEvents(fn)` | Conversation lifecycle, `action_completed`, `friction_detected`, `mic_denied`. |
+| `useGraineTrack()` / `useGraineTap()` | Product events and taps the agent knows about but does not interrupt for. |
+| `useGraineIdentify()` | Who the customer is — it reaches the greeting and the call record. |
+| `useGraineHighlight()` / `useGraineWidget()` | Let the agent point at things and draw components. |
+| `GraineVoiceLauncher` | The voice engine: WebView, microphone, WebRTC or WebSocket. |
 | `GraineAgentBar` | Optional default UI. Mount at the root. Replace it with your own. |
 | `addMaskRule(pattern, token)` | Mask an app-specific identifier format. |
 
+**Friction detection** — the agent notices a stuck customer (idle, repeated
+field errors, back-and-forth, rage taps, error banners) and speaks first. Rules
+are JSON, per screen, configured in the dashboard; pass `friction` on the
+provider only for the screens your app knows better. `DEFAULT_FRICTION`,
+`resolveFriction` and `FrictionDetector` are exported for hosts that want the
+engine on their own timers.
+
+Every reporting hook works outside a provider too — call `setDefaultClient(client)`
+once if your provider wraps only your bar.
+
 `GraineInAppClient` is exported for apps that want the transport without the
-React layer.
+React layer: `setScreen`, `clearScreen`, `updateField`, `removeField`, `identify`, `track`, `reportEvent`,
+`registerAction`, `executeAction`, `configureFriction`, `friction`, `session`.
 
 ## Support
 

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { type ActionHandler, type AppActionResult, type AppEvent, type ScreenContext } from "./protocol.js";
+import { type ActionHandler, type AppActionResult, type AppEvent, type ScreenContext, type ScreenField } from "./protocol.js";
 import { type FrictionConfig } from "./friction.js";
 export declare const SUBPROTOCOL = "graine.embed.v1";
 export interface GraineInAppOptions {
@@ -91,6 +91,9 @@ export declare class GraineInAppClient {
     highlight(name: string | null, ttlMs?: number): void;
     registerAction(name: string, handler: ActionHandler): () => void;
     get availableActions(): string[];
+    updateField(field: ScreenField): void;
+    removeField(name: string): void;
+    clearScreen(screenId: string | null | undefined): void;
     setScreen(context: ScreenContext | null): void;
     private dispatchFriction;
     reportEvent(event: AppEvent): void;

package/dist/client.js

@@ -363,6 +363,32 @@ export class GraineInAppClient {
     get availableActions() {
         return [...this.actions.keys()];
     }
+    updateField(field) {
+        if (!this.screen || !field || !field.name)
+            return;
+        const fields = [...(this.screen.fields ?? [])];
+        const i = fields.findIndex((f) => f.name === field.name);
+        if (i >= 0)
+            fields[i] = { ...fields[i], ...field };
+        else
+            fields.push(field);
+        this.setScreen({ ...this.screen, fields });
+    }
+    removeField(name) {
+        if (!this.screen || !name)
+            return;
+        const fields = this.screen.fields ?? [];
+        if (!fields.some((f) => f.name === name))
+            return;
+        this.setScreen({ ...this.screen, fields: fields.filter((f) => f.name !== name) });
+    }
+    clearScreen(screenId) {
+        if (!this.screen)
+            return;
+        if (screenId && this.screen.screen !== screenId)
+            return;
+        this.setScreen(null);
+    }
     setScreen(context) {
         const changedScreen = context?.screen !== this.screen?.screen;
         this.screen = context;

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { FrictionDetector, resolveFriction, rulesFor, DEFAULT_FRICTION, type Fri
 export { VoiceSession, liveAudioStreamAdapter, base64ToPcm16, CAPTURE_SAMPLE_RATE, type AudioAdapter, type VoiceSessionOptions, } from "./voice.js";
 export { EchoGuard, decodeAgentAudio, decodeMuLaw, decodePcm16, base64ToBytes, type AudioFormat, type DecodedAudio, } from "./audio.js";
 export { addMaskRule, maskDeep, maskString } from "./mask.js";
-export { GraineProvider, useGraineAgent, useGraineScreen, useGraineAction, useGraineVoice, useGraineIdentify, useGraineEvents, useGraineTrack, useGraineTap, useGraineHighlight, useGraineWidget, useGraineReady, type GraineEvent, type GraineProviderProps, type Turn, type Caption, } from "./react-native/index.js";
+export { GraineProvider, useGraineAgent, useGraineScreen, useGraineAction, useGraineVoice, useGraineIdentify, useGraineEvents, useGraineField, useGraineClient, setDefaultClient, useGraineTrack, useGraineTap, useGraineHighlight, useGraineWidget, useGraineReady, type GraineEvent, type GraineProviderProps, type Turn, type Caption, } from "./react-native/index.js";
 export { requestMicrophonePermission } from "./react-native/permissions.js";
 export { resolveNativeAppearance, type NativeAppearance, type NativeAppearanceFallback, } from "./react-native/appearance.js";
 export { RtcVoiceSessionController, RtcVoiceError, type RtcVoiceState, type RtcVoiceErrorCode, type RtcVoiceSession, type RtcVoiceOptions, } from "./react-native/voice-rtc.js";

package/dist/index.js

@@ -3,7 +3,7 @@ export { FrictionDetector, resolveFriction, rulesFor, DEFAULT_FRICTION, } from "
 export { VoiceSession, liveAudioStreamAdapter, base64ToPcm16, CAPTURE_SAMPLE_RATE, } from "./voice.js";
 export { EchoGuard, decodeAgentAudio, decodeMuLaw, decodePcm16, base64ToBytes, } from "./audio.js";
 export { addMaskRule, maskDeep, maskString } from "./mask.js";
-export { GraineProvider, useGraineAgent, useGraineScreen, useGraineAction, useGraineVoice, useGraineIdentify, useGraineEvents, useGraineTrack, useGraineTap, useGraineHighlight, useGraineWidget, useGraineReady, } from "./react-native/index.js";
+export { GraineProvider, useGraineAgent, useGraineScreen, useGraineAction, useGraineVoice, useGraineIdentify, useGraineEvents, useGraineField, useGraineClient, setDefaultClient, useGraineTrack, useGraineTap, useGraineHighlight, useGraineWidget, useGraineReady, } from "./react-native/index.js";
 export { requestMicrophonePermission } from "./react-native/permissions.js";
 export { resolveNativeAppearance, } from "./react-native/appearance.js";
 export { RtcVoiceSessionController, RtcVoiceError, } from "./react-native/voice-rtc.js";

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

@@ -1,7 +1,7 @@
 import React from "react";
 import { GraineInAppClient, type GraineInAppOptions } from "../client.js";
 import { type AudioAdapter, type VoiceSessionOptions } from "../voice.js";
-import type { ActionHandler, ScreenContext } from "../protocol.js";
+import type { ActionHandler, ScreenContext, ScreenField } from "../protocol.js";
 import type { FrictionConfig } from "../friction.js";
 import { type LauncherInset, type LauncherVisibility } from "./navigation.js";
 interface GraineContextValue {
@@ -80,6 +80,8 @@ export interface Turn {
     text: string;
     live?: boolean;
 }
+export declare function setDefaultClient(client: GraineInAppClient | null): void;
+export declare function useGraineClient(): GraineInAppClient;
 export interface GraineProviderProps extends Partial<GraineInAppOptions> {
     children: React.ReactNode;
     client?: GraineInAppClient;
@@ -108,6 +110,7 @@ export declare function useGraineVoice(adapter: AudioAdapter | null, options?: V
     stop: () => Promise<void>;
 };
 export declare function useGraineScreen(context: ScreenContext | null): void;
+export declare function useGraineField(name: string, field: Omit<ScreenField, "name">): void;
 export declare function useGraineHighlight(name: string): {
     highlighted: boolean;
 };

package/dist/react-native/index.js

@@ -5,6 +5,18 @@ import { GraineInAppClient } from "../client.js";
 import { VoiceSession } from "../voice.js";
 import { LauncherVisibilityTracker, activeRouteName, } from "./navigation.js";
 const Ctx = createContext(null);
+let defaultClient = null;
+export function setDefaultClient(client) {
+    defaultClient = client;
+}
+export function useGraineClient() {
+    const ctx = useContext(Ctx);
+    const client = ctx?.client ?? defaultClient;
+    if (!client) {
+        throw new Error("[Graine] No client. Either render inside <GraineProvider>, or call setDefaultClient(client) once at startup.");
+    }
+    return client;
+}
 export function GraineProvider({ children, autoConnect = true, onProactive, endOnBackground = true, navigationRef, appVersion, friction, includeScreens, launcherDelayMs = 0, visibility, client: providedClient, ...options }) {
     const clientRef = useRef(null);
     if (!clientRef.current) {
@@ -99,6 +111,7 @@ export function GraineProvider({ children, autoConnect = true, onProactive, endO
         };
     }, [navigationRef, client]);
     useEffect(() => { client.setAppVersion(appVersion); }, [client, appVersion]);
+    useEffect(() => { setDefaultClient(client); }, [client]);
     useEffect(() => { if (friction !== undefined)
         client.configureFriction(friction); }, [client, friction]);
     useEffect(() => {
@@ -273,11 +286,12 @@ export function useGraineEvents(handler) {
     useEffect(() => onEvent((e) => ref.current(e)), [onEvent]);
 }
 export function useGraineTrack() {
-    const { track } = useGraine();
-    return track;
+    const ctx = useContext(Ctx);
+    const client = useGraineClient();
+    return useCallback((name, data) => (ctx ? ctx.track(name, data) : client.track(name, data)), [ctx, client]);
 }
 export function useGraineTap(name, handler, data) {
-    const { track } = useGraine();
+    const track = useGraineTrack();
     const handlerRef = useRef(handler);
     handlerRef.current = handler;
     const dataRef = useRef(data);
@@ -292,7 +306,7 @@ export function useGraineTap(name, handler, data) {
     }, [name, track]);
 }
 export function useGraineIdentify() {
-    const { client } = useGraine();
+    const client = useGraineClient();
     return useCallback((user) => client.identify(user), [client]);
 }
 export function useGraineVoice(adapter, options = {}) {
@@ -328,15 +342,23 @@ export function useGraineVoice(adapter, options = {}) {
     };
 }
 export function useGraineScreen(context) {
-    const { client } = useGraine();
+    const client = useGraineClient();
     const serialised = JSON.stringify(context ?? null);
     useEffect(() => {
         client.setScreen(context);
-        return () => client.setScreen(null);
+        return () => client.clearScreen(context?.screen);
     }, [client, serialised]);
 }
+export function useGraineField(name, field) {
+    const client = useGraineClient();
+    const serialised = JSON.stringify(field ?? null);
+    useEffect(() => {
+        client.updateField({ name, ...(field ?? {}) });
+    }, [client, name, serialised]);
+    useEffect(() => () => client.removeField(name), [client, name]);
+}
 export function useGraineHighlight(name) {
-    const { client } = useGraine();
+    const client = useGraineClient();
     const [highlighted, setHighlighted] = useState(false);
     useEffect(() => client.registerHighlightable(name), [client, name]);
     useEffect(() => {
@@ -357,7 +379,7 @@ export function useGraineHighlight(name) {
     return { highlighted };
 }
 export function useGraineWidget() {
-    const { client } = useGraine();
+    const client = useGraineClient();
     const [widget, setWidget] = useState(null);
     useEffect(() => client.on("widget", (w) => {
         if (!w?.widget_id)
@@ -379,7 +401,7 @@ export function useGraineWidget() {
     return { widget, submit, dismiss };
 }
 export function useGraineAction(name, handler) {
-    const { client } = useGraine();
+    const client = useGraineClient();
     const handlerRef = useRef(handler);
     handlerRef.current = handler;
     useEffect(() => client.registerAction(name, (args) => handlerRef.current(args)), [client, name]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graineai/inapp-react-native",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "type": "module",
   "description": "Graine in-app agent for React Native — an agent that sees the screen your customer is on and can act on it.",
   "license": "MIT",