@graineai/inapp-react-native 0.25.0 → 0.26.1

package/INTEGRATION.md

@@ -824,6 +824,17 @@ fourth. The guarantees, so you do not have to think about them:
   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.
+- **Self-healing.** The newest screen is re-asserted every few seconds during
+  a call and when the app returns to the foreground, with its original
+  sequence number — so a frame lost in flight is repaired within seconds, not
+  at the next screen change; one that arrived is simply ignored.
+- **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
@@ -896,6 +907,7 @@ 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 |
@@ -908,7 +920,7 @@ told to ignore).
 
 | Prop | Type | Notes |
 |---|---|---|
-| `publishableKey` | `string` | Required unless you pass `client`. |
+| `publishableKey` | `string` | Required unless you pass `client`. Selects the agent — one key per agent; there is no `agentId` prop. |
 | `baseUrl` | `string` | Defaults to Graine's host. |
 | `client` | `GraineInAppClient` | Use **your** instance instead of building one. Pass this if your app has a module-level client. |
 | `navigationRef` | `ref` | The same ref you give `NavigationContainer`. Makes the agent screen-aware with no per-screen code. |
@@ -926,6 +938,7 @@ told to ignore).
 | 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. |

package/README.md

@@ -217,6 +217,7 @@ 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`. |
@@ -234,8 +235,11 @@ 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: `setScreen`, `clearScreen`, `identify`, `track`, `reportEvent`,
+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,8 @@ 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;

package/dist/client.js

@@ -363,6 +363,25 @@ 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;

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.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/dist/react-native/voice-launcher.js

@@ -192,6 +192,7 @@ export function GraineVoiceLauncher({ webView: WebView, autoStart = false, trans
                     clearTimeout(pending);
                     pending = null;
                 }
+                pushContext();
                 return;
             }
             if (next === "background" && wasActive && !pending) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graineai/inapp-react-native",
-  "version": "0.25.0",
+  "version": "0.26.1",
   "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",