@graineai/inapp-react-native 0.24.0 → 0.25.0

package/INTEGRATION.md

@@ -809,6 +809,26 @@ 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.
+
+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
@@ -880,7 +900,8 @@ told to ignore).
 | `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 +918,20 @@ 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. |
+| `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

@@ -219,11 +219,24 @@ requests a permission on your behalf.
 | `useGraineScreen(context)` | Report what this screen shows. |
 | `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.
+
 `GraineInAppClient` is exported for apps that want the transport without the
-React layer.
+React layer: `setScreen`, `clearScreen`, `identify`, `track`, `reportEvent`,
+`registerAction`, `executeAction`, `configureFriction`, `friction`, `session`.
 
 ## Support
 

package/dist/client.d.ts

@@ -91,6 +91,7 @@ export declare class GraineInAppClient {
     highlight(name: string | null, ttlMs?: number): void;
     registerAction(name: string, handler: ActionHandler): () => void;
     get availableActions(): string[];
+    clearScreen(screenId: string | null | undefined): void;
     setScreen(context: ScreenContext | null): void;
     private dispatchFriction;
     reportEvent(event: AppEvent): void;

package/dist/client.js

@@ -363,6 +363,13 @@ export class GraineInAppClient {
     get availableActions() {
         return [...this.actions.keys()];
     }
+    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/react-native/index.js

@@ -332,7 +332,7 @@ export function useGraineScreen(context) {
     const serialised = JSON.stringify(context ?? null);
     useEffect(() => {
         client.setScreen(context);
-        return () => client.setScreen(null);
+        return () => client.clearScreen(context?.screen);
     }, [client, serialised]);
 }
 export function useGraineHighlight(name) {

package/package.json

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