@graineai/inapp-react-native 0.23.0 → 0.25.0

package/INTEGRATION.md

@@ -507,6 +507,7 @@ useGraineEvents((e) => {
     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;
+    case "action_completed":     analytics.track("agent_action_result", { name: e.name, status: e.status }); break;
   }
 });
 ```
@@ -765,6 +766,95 @@ and resamples in its output stage, which is where the artefacts came from.
 
 ---
 
+## Friction detection
+
+The agent speaks up when the customer looks stuck — before they say so. The
+SDK reads what your screens already report and turns it into five signals:
+
+| Signal | Fires when |
+|---|---|
+| `stalled_on_step` | untouched for `idle.afterMs` (a stuck field is named) |
+| `repeated_field_error` | the same field shows an error `count` times in `windowMs` |
+| `looping_between_screens` | back on the same screen `visits` times in `windowMs` |
+| `rage_taps` | a `useGraineTap`-tracked tap `taps` times in `windowMs` |
+| `screen_error` | the screen reports an `error` banner |
+
+Each is sent to the agent as an `app_event` (it still decides whether to
+speak, within `nudge.cooldownSeconds` / `nudge.maxPerSession`) and to your app
+as `friction_detected` on `useGraineEvents`.
+
+**Configure it in the dashboard** — Agent → Embed & Widgets → Friction — and
+every install picks it up with the session. Or pass rules from the app for the
+screens only it knows about; the app's layer wins:
+
+```tsx
+<GraineProvider client={client} friction={{
+  screens: {
+    terms: { ignore: true },                       // reading is not stuck
+    otp:   { idle: { afterMs: 20000 },
+             message: "The customer has been on the OTP screen {seconds}s without entering a code." },
+    home:  { idle: false },
+  },
+  nudge: { openLauncher: true },                   // your app decides what "open" means
+}}>
+```
+
+Every rule accepts `false` to switch it off; `message` templates take
+`{title} {screen} {field} {error} {count} {seconds} {tap}`. The full document
+with defaults is `DEFAULT_FRICTION`.
+
+```tsx
+useGraineEvents((e) => {
+  if (e.type === "friction_detected" && client.friction.nudge.openLauncher) openAssistant();
+});
+```
+
+## 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
+transcript:
+
+- **What the agent did in the app** — every action it called, the arguments,
+  whether the app accepted or refused it, and the app's own answer
+  ("Opened the privacy screen.", "I can reach: settings, favourites, …").
+- **What happened in the app** — the screens the customer moved through, the
+  taps you track with `useGraineTap`, and every friction signal, with whether
+  the agent spoke to it and, if not, why (it was mid-sentence, it had just
+  spoken, it had reached its limit).
+- **Who it was** — from `identify()`.
+
+All of it exports to CSV. Nothing needs to be instrumented beyond what the
+screens already report.
+
+## Captions on WebRTC
+
+Captions — the agent's line and what the customer is saying — reach the host
+on both transports. On WebRTC the audio carries no text, so the runtime
+mirrors the same caption frames over the control channel; a native bar using
+`onCaption` sees `role: "customer"` and `role: "agent"` lines either way.
+
+---
+
 ## Coming from RevRag
 
 Same shape, different names. If you have a RevRag integration, this is the
@@ -791,6 +881,7 @@ whole translation:
 | `checkPermissions()` | `requestMicrophonePermission()` |
 | server `widget_config` | `appearance` from the session, via `resolveNativeAppearance` |
 | LiveKit native setup | none — see *Why there is no LiveKit step* |
+| Friction detection (dashboard switch) | Per-screen JSON rules — `friction` on the provider, or Embed & Widgets → Friction; five named signals, `friction_detected` event |
 
 Two things RevRag has that are deliberately absent: a LiveKit install step
 (audio rides a WebView on a hosted page, so audio fixes ship without an app
@@ -809,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`
@@ -826,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

@@ -1,10 +1,12 @@
 import { type ActionHandler, type AppActionResult, type AppEvent, type ScreenContext } from "./protocol.js";
+import { type FrictionConfig } from "./friction.js";
 export declare const SUBPROTOCOL = "graine.embed.v1";
 export interface GraineInAppOptions {
     baseUrl: string;
     publishableKey: string;
     variables?: Record<string, string>;
     stallAfterMs?: number;
+    friction?: FrictionConfig;
     voice?: boolean;
     WebSocketImpl?: any;
     fetchImpl?: typeof fetch;
@@ -22,6 +24,7 @@ export interface SessionConfig {
         toolName?: string;
         name?: string;
     }>;
+    friction?: FrictionConfig;
 }
 export interface ActionDiagnosis {
     usable: string[];
@@ -43,7 +46,10 @@ export declare class GraineInAppClient {
     private contextTimer;
     private pendingScreen;
     private stallTimer;
-    private stallReportedFor;
+    private detector;
+    private serverFriction;
+    private appFriction;
+    private legacyStall;
     private pingTimer;
     private agentSpeaking;
     private bargedIn;
@@ -53,6 +59,9 @@ export declare class GraineInAppClient {
     private appVersion;
     private recentEvents;
     constructor(opts: GraineInAppOptions);
+    private effectiveFriction;
+    configureFriction(override: FrictionConfig | null | undefined): void;
+    get friction(): Required<FrictionConfig>;
     on(event: string, fn: Listener): () => void;
     emit(event: string, payload?: any): void;
     private get fetch();
@@ -67,6 +76,7 @@ export declare class GraineInAppClient {
     executeAction(name: string, args?: Record<string, unknown>): Promise<AppActionResult>;
     private runAction;
     private invokeAction;
+    private performAction;
     get isConnected(): boolean;
     getScreen(): ScreenContext | null;
     getIdentity(): Record<string, string>;
@@ -81,7 +91,9 @@ 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;
     track(name: string, data?: Record<string, unknown>): void;
     private scheduleScreen;

package/dist/client.js

@@ -1,5 +1,6 @@
 import { ACTION_DEADLINE_MS, CONTEXT_THROTTLE_MS, } from "./protocol.js";
 import { maskDeep } from "./mask.js";
+import { FrictionDetector, resolveFriction } from "./friction.js";
 export const SUBPROTOCOL = "graine.embed.v1";
 const PING_MS = 25000;
 export class GraineInAppClient {
@@ -17,7 +18,8 @@ export class GraineInAppClient {
         this.contextTimer = null;
         this.pendingScreen = false;
         this.stallTimer = null;
-        this.stallReportedFor = null;
+        this.serverFriction = null;
+        this.legacyStall = false;
         this.pingTimer = null;
         this.agentSpeaking = false;
         this.bargedIn = false;
@@ -31,6 +33,23 @@ export class GraineInAppClient {
         if (!opts?.baseUrl)
             throw new Error("[Graine] baseUrl is required.");
         this.opts = { stallAfterMs: 45000, ...opts };
+        this.appFriction = opts.friction;
+        this.legacyStall = "stallAfterMs" in opts;
+        this.detector = new FrictionDetector(this.effectiveFriction());
+    }
+    effectiveFriction() {
+        const legacy = this.legacyStall
+            ? { idle: this.opts.stallAfterMs && this.opts.stallAfterMs > 0 ? { afterMs: this.opts.stallAfterMs } : false }
+            : null;
+        return resolveFriction(this.serverFriction, legacy, this.appFriction);
+    }
+    configureFriction(override) {
+        this.appFriction = override ?? undefined;
+        this.detector.configure(this.effectiveFriction());
+        this.armStall();
+    }
+    get friction() {
+        return this.detector.settings;
     }
     on(event, fn) {
         if (!this.listeners.has(event))
@@ -69,6 +88,9 @@ export class GraineInAppClient {
             throw new Error(data?.error || `Embed rejected (${res.status})`);
         }
         this.config = data;
+        this.serverFriction = data && typeof data.friction === "object" ? data.friction : null;
+        this.detector.configure(this.effectiveFriction());
+        this.armStall();
         this.reportActionMismatch();
         return this.config;
     }
@@ -263,6 +285,15 @@ export class GraineInAppClient {
         this.send({ type: "app_action_result", action_id: request.action_id, ...result });
     }
     async invokeAction(request) {
+        const result = await this.performAction(request);
+        this.emit("action_result", {
+            name: request.name,
+            status: result.status,
+            ...(result.message ? { message: result.message } : {}),
+        });
+        return result;
+    }
+    async performAction(request) {
         const handler = this.actions.get(request.name);
         if (!handler) {
             return {
@@ -332,16 +363,35 @@ 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;
+        const now = Date.now();
         if (changedScreen) {
-            this.screenSince = Date.now();
-            this.stallReportedFor = null;
-            this.armStall();
+            this.screenSince = now;
         }
+        this.dispatchFriction(this.detector.onScreen(context, now));
+        this.armStall();
         this.scheduleScreen();
     }
+    dispatchFriction(signals) {
+        for (const s of signals) {
+            this.emit("friction", s);
+            this.reportEvent({
+                name: s.name,
+                detail: s.detail,
+                cooldown_seconds: s.cooldown_seconds,
+                max_per_session: s.max_per_session,
+            });
+        }
+    }
     reportEvent(event) {
         this.emit("app_event", event);
         this.send({ type: "app_event", event });
@@ -352,6 +402,7 @@ export class GraineInAppClient {
         this.recentEvents.push({ name, at: Date.now(), ...(data ? { data } : {}) });
         if (this.recentEvents.length > 10)
             this.recentEvents.shift();
+        this.dispatchFriction(this.detector.onTrack(name, Date.now()));
         if (this.screen)
             this.scheduleScreen();
     }
@@ -402,24 +453,14 @@ export class GraineInAppClient {
     }
     armStall() {
         clearTimeout(this.stallTimer);
-        const after = this.opts.stallAfterMs ?? 0;
-        if (!after || !this.screen)
+        const due = this.detector.idleDueIn(Date.now());
+        if (due === null)
             return;
-        const screenId = this.screen.screen;
         this.stallTimer = setTimeout(() => {
-            if (this.stallReportedFor === screenId)
-                return;
-            this.stallReportedFor = screenId;
-            const title = this.screen?.title ?? screenId;
-            const stuck = (this.screen?.fields ?? []).find((f) => f.status === "invalid" || f.error || f.status === "empty");
-            this.reportEvent({
-                name: "stalled_on_step",
-                detail: stuck
-                    ? `The customer has not touched the "${title}" screen for ${Math.round(after / 1000)}s. ` +
-                        `The "${stuck.label ?? stuck.name}" field is ${stuck.error ? `showing: ${stuck.error}` : stuck.status}.`
-                    : `The customer has not touched the "${title}" screen for ${Math.round(after / 1000)}s.`,
-            });
-        }, after);
+            const signal = this.detector.onIdle(Date.now());
+            if (signal)
+                this.dispatchFriction([signal]);
+        }, due);
     }
     identify(user) {
         if (!user) {
@@ -436,7 +477,9 @@ export class GraineInAppClient {
         this.scheduleScreen();
     }
     noteInteraction() {
-        this.screenSince = Date.now();
+        const now = Date.now();
+        this.screenSince = now;
+        this.detector.onInteraction(now);
         this.armStall();
     }
     say(text) {

package/dist/friction.d.ts

@@ -0,0 +1,70 @@
+import type { ScreenContext } from "./protocol.js";
+export interface IdleRule {
+    afterMs: number;
+}
+export interface RepeatedErrorsRule {
+    count: number;
+    windowMs: number;
+}
+export interface BackAndForthRule {
+    visits: number;
+    windowMs: number;
+}
+export interface RageTapsRule {
+    taps: number;
+    windowMs: number;
+}
+export interface FrictionScreenRules {
+    ignore?: boolean;
+    idle?: IdleRule | false;
+    repeatedErrors?: RepeatedErrorsRule | false;
+    backAndForth?: BackAndForthRule | false;
+    rageTaps?: RageTapsRule | false;
+    screenError?: boolean;
+    message?: string;
+}
+export interface FrictionNudge {
+    cooldownSeconds?: number;
+    maxPerSession?: number;
+    openLauncher?: boolean;
+}
+export interface FrictionConfig extends FrictionScreenRules {
+    enabled?: boolean;
+    cooldownMs?: number;
+    nudge?: FrictionNudge;
+    screens?: Record<string, FrictionScreenRules>;
+}
+export declare const DEFAULT_FRICTION: Readonly<Required<Omit<FrictionConfig, "message" | "ignore">>>;
+export declare function resolveFriction(...layers: Array<FrictionConfig | null | undefined>): Required<FrictionConfig>;
+export declare function rulesFor(config: Required<FrictionConfig>, screenId: string | null | undefined): Required<FrictionScreenRules>;
+export type FrictionKind = "stalled_on_step" | "repeated_field_error" | "looping_between_screens" | "rage_taps" | "screen_error";
+export interface FrictionSignal {
+    name: FrictionKind;
+    screen: string;
+    detail: string;
+    data: Record<string, unknown>;
+    cooldown_seconds: number;
+    max_per_session: number;
+}
+export declare class FrictionDetector {
+    private config;
+    private screen;
+    private screenSince;
+    private lastSignalAt;
+    private idleFiredFor;
+    private visits;
+    private errorHits;
+    private errorFiredFor;
+    private taps;
+    private screenErrorFiredFor;
+    constructor(config?: FrictionConfig | Required<FrictionConfig>);
+    configure(config: Required<FrictionConfig>): void;
+    get settings(): Required<FrictionConfig>;
+    private signal;
+    private active;
+    onScreen(ctx: ScreenContext | null, now: number): FrictionSignal[];
+    onInteraction(now: number): void;
+    onTrack(name: string, now: number): FrictionSignal[];
+    idleDueIn(now: number): number | null;
+    onIdle(now: number): FrictionSignal | null;
+}

package/dist/friction.js

@@ -0,0 +1,258 @@
+const DEFAULT_RULES = {
+    idle: { afterMs: 45000 },
+    repeatedErrors: { count: 2, windowMs: 60000 },
+    backAndForth: { visits: 3, windowMs: 45000 },
+    rageTaps: { taps: 4, windowMs: 1500 },
+};
+export const DEFAULT_FRICTION = Object.freeze({
+    enabled: true,
+    cooldownMs: 60000,
+    ...DEFAULT_RULES,
+    screenError: true,
+    nudge: { cooldownSeconds: 20, maxPerSession: 3, openLauncher: false },
+    screens: {},
+});
+function num(v) {
+    const n = typeof v === "string" ? Number(v) : v;
+    return typeof n === "number" && Number.isFinite(n) && n > 0 ? n : null;
+}
+function rule(raw, shape) {
+    if (raw === false)
+        return false;
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== "object")
+        return undefined;
+    const out = {};
+    for (const [k, fallback] of Object.entries(shape)) {
+        const v = num(raw[k]);
+        out[k] = v ?? fallback;
+    }
+    return out;
+}
+function screenRules(raw, base) {
+    if (!raw || typeof raw !== "object")
+        return {};
+    const r = raw;
+    const out = {};
+    if (r.ignore === true)
+        out.ignore = true;
+    const idle = rule(r.idle, base.idle || DEFAULT_RULES.idle);
+    if (idle !== undefined)
+        out.idle = idle;
+    const rep = rule(r.repeatedErrors, base.repeatedErrors || DEFAULT_RULES.repeatedErrors);
+    if (rep !== undefined)
+        out.repeatedErrors = rep;
+    const bf = rule(r.backAndForth, base.backAndForth || DEFAULT_RULES.backAndForth);
+    if (bf !== undefined)
+        out.backAndForth = bf;
+    const rage = rule(r.rageTaps, base.rageTaps || DEFAULT_RULES.rageTaps);
+    if (rage !== undefined)
+        out.rageTaps = rage;
+    if (typeof r.screenError === "boolean")
+        out.screenError = r.screenError;
+    if (typeof r.message === "string" && r.message.trim())
+        out.message = r.message.trim();
+    return out;
+}
+export function resolveFriction(...layers) {
+    let out = {
+        ...DEFAULT_FRICTION,
+        nudge: { ...DEFAULT_FRICTION.nudge },
+        screens: {},
+        ignore: false,
+        message: "",
+    };
+    for (const layer of layers) {
+        if (!layer || typeof layer !== "object")
+            continue;
+        const top = screenRules(layer, out);
+        out = { ...out, ...top };
+        if (typeof layer.enabled === "boolean")
+            out.enabled = layer.enabled;
+        const cd = num(layer.cooldownMs);
+        if (cd !== null)
+            out.cooldownMs = cd;
+        if (layer.nudge && typeof layer.nudge === "object") {
+            const n = layer.nudge;
+            out.nudge = {
+                ...out.nudge,
+                ...(num(n.cooldownSeconds) !== null ? { cooldownSeconds: num(n.cooldownSeconds) } : {}),
+                ...(num(n.maxPerSession) !== null ? { maxPerSession: num(n.maxPerSession) } : {}),
+                ...(typeof n.openLauncher === "boolean" ? { openLauncher: n.openLauncher } : {}),
+            };
+        }
+        if (layer.screens && typeof layer.screens === "object") {
+            const screens = { ...out.screens };
+            for (const [id, raw] of Object.entries(layer.screens)) {
+                if (!id)
+                    continue;
+                screens[id] = { ...(screens[id] || {}), ...screenRules(raw, out) };
+            }
+            out.screens = screens;
+        }
+    }
+    return out;
+}
+export function rulesFor(config, screenId) {
+    const over = (screenId && config.screens[screenId]) || {};
+    return {
+        ignore: over.ignore ?? false,
+        idle: over.idle ?? config.idle,
+        repeatedErrors: over.repeatedErrors ?? config.repeatedErrors,
+        backAndForth: over.backAndForth ?? config.backAndForth,
+        rageTaps: over.rageTaps ?? config.rageTaps,
+        screenError: over.screenError ?? config.screenError,
+        message: over.message ?? config.message ?? "",
+    };
+}
+function fill(template, vars) {
+    return template.replace(/\{(\w+)\}/g, (_, k) => (vars[k] === undefined || vars[k] === null ? "" : String(vars[k])));
+}
+const stuckField = (fields) => (fields ?? []).find((f) => f.status === "invalid" || f.error) ?? (fields ?? []).find((f) => f.status === "empty");
+export class FrictionDetector {
+    constructor(config) {
+        this.screen = null;
+        this.screenSince = 0;
+        this.lastSignalAt = new Map();
+        this.idleFiredFor = null;
+        this.visits = [];
+        this.errorHits = new Map();
+        this.errorFiredFor = new Set();
+        this.taps = new Map();
+        this.screenErrorFiredFor = null;
+        this.config = resolveFriction(config);
+    }
+    configure(config) {
+        this.config = config;
+    }
+    get settings() {
+        return this.config;
+    }
+    signal(name, vars, fallback, now) {
+        const screen = this.screen?.screen ?? "";
+        const last = this.lastSignalAt.get(screen) ?? -Infinity;
+        if (now - last < this.config.cooldownMs)
+            return null;
+        this.lastSignalAt.set(screen, now);
+        const rules = rulesFor(this.config, screen);
+        const all = { title: this.screen?.title ?? screen, screen, ...vars };
+        return {
+            name,
+            screen,
+            detail: rules.message ? fill(rules.message, all) : fill(fallback, all),
+            data: vars,
+            cooldown_seconds: this.config.nudge.cooldownSeconds ?? 20,
+            max_per_session: this.config.nudge.maxPerSession ?? 3,
+        };
+    }
+    active() {
+        if (!this.config.enabled || !this.screen)
+            return null;
+        const r = rulesFor(this.config, this.screen.screen);
+        return r.ignore ? null : r;
+    }
+    onScreen(ctx, now) {
+        const prev = this.screen;
+        this.screen = ctx;
+        if (!ctx)
+            return [];
+        const changed = !prev || prev.screen !== ctx.screen;
+        if (changed) {
+            this.screenSince = now;
+            this.idleFiredFor = null;
+            this.screenErrorFiredFor = null;
+            this.errorFiredFor.clear();
+            this.visits.push({ screen: ctx.screen, at: now });
+            if (this.visits.length > 50)
+                this.visits.shift();
+        }
+        const rules = this.active();
+        if (!rules)
+            return [];
+        const out = [];
+        if (changed && rules.backAndForth) {
+            const { visits, windowMs } = rules.backAndForth;
+            const recent = this.visits.filter((v) => v.screen === ctx.screen && now - v.at <= windowMs).length;
+            if (recent >= visits) {
+                const s = this.signal("looping_between_screens", { count: recent, seconds: Math.round(windowMs / 1000) }, `The customer has come back to the "{title}" screen {count} times in the last {seconds}s without getting past it.`, now);
+                if (s)
+                    out.push(s);
+            }
+        }
+        if (rules.repeatedErrors) {
+            const { count, windowMs } = rules.repeatedErrors;
+            for (const f of ctx.fields ?? []) {
+                if (!(f.status === "invalid" || f.error))
+                    continue;
+                const key = `${ctx.screen}:${f.name}`;
+                const hits = (this.errorHits.get(key) ?? []).filter((t) => now - t <= windowMs);
+                const prevField = (prev?.fields ?? []).find((p) => p.name === f.name);
+                const same = prevField && !changed && (prevField.error ?? "") === (f.error ?? "") && prevField.status === f.status;
+                if (!same)
+                    hits.push(now);
+                this.errorHits.set(key, hits);
+                if (hits.length >= count && !this.errorFiredFor.has(key)) {
+                    this.errorFiredFor.add(key);
+                    const s = this.signal("repeated_field_error", { field: f.label ?? f.name, error: f.error ?? f.status, count: hits.length }, `The "{field}" field on the "{title}" screen has rejected the customer {count} times — it is showing: {error}.`, now);
+                    if (s)
+                        out.push(s);
+                }
+            }
+        }
+        if (rules.screenError && ctx.error && this.screenErrorFiredFor !== ctx.screen) {
+            this.screenErrorFiredFor = ctx.screen;
+            const s = this.signal("screen_error", { error: ctx.error }, `The "{title}" screen is showing an error: {error}.`, now);
+            if (s)
+                out.push(s);
+        }
+        return out;
+    }
+    onInteraction(now) {
+        this.screenSince = now;
+    }
+    onTrack(name, now) {
+        const rules = this.active();
+        if (!rules || !rules.rageTaps || !this.screen)
+            return [];
+        if (!name.startsWith("tap:"))
+            return [];
+        const { taps, windowMs } = rules.rageTaps;
+        const key = `${this.screen.screen}:${name}`;
+        const times = (this.taps.get(key) ?? []).filter((t) => now - t <= windowMs);
+        times.push(now);
+        this.taps.set(key, times);
+        if (times.length < taps)
+            return [];
+        this.taps.set(key, []);
+        const s = this.signal("rage_taps", { tap: name.slice(4), count: times.length, seconds: (windowMs / 1000).toFixed(1) }, `The customer tapped "{tap}" {count} times in {seconds}s on the "{title}" screen — it may not be responding or not doing what they expect.`, now);
+        return s ? [s] : [];
+    }
+    idleDueIn(now) {
+        const rules = this.active();
+        if (!rules || !rules.idle || !this.screen)
+            return null;
+        if (this.idleFiredFor === this.screen.screen)
+            return null;
+        return Math.max(0, rules.idle.afterMs - (now - this.screenSince));
+    }
+    onIdle(now) {
+        const rules = this.active();
+        if (!rules || !rules.idle || !this.screen)
+            return null;
+        if (this.idleFiredFor === this.screen.screen)
+            return null;
+        if (now - this.screenSince < rules.idle.afterMs)
+            return null;
+        this.idleFiredFor = this.screen.screen;
+        const stuck = stuckField(this.screen.fields);
+        const seconds = Math.round(rules.idle.afterMs / 1000);
+        return this.signal("stalled_on_step", {
+            seconds,
+            field: stuck ? stuck.label ?? stuck.name : "",
+            error: stuck?.error ?? stuck?.status ?? "",
+        }, stuck
+            ? `The customer has not touched the "{title}" screen for {seconds}s. The "{field}" field is ${stuck.error ? "showing: {error}" : "{error}"}.`
+            : `The customer has not touched the "{title}" screen for {seconds}s.`, now);
+    }
+}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export type { ActionHandler, AppActionRequest, AppActionResult, AppEvent, ScreenContext, ScreenField, } from "./protocol.js";
 export { GraineInAppClient, type GraineInAppOptions, type SessionConfig, type ActionDiagnosis, } from "./client.js";
+export { FrictionDetector, resolveFriction, rulesFor, DEFAULT_FRICTION, type FrictionConfig, type FrictionScreenRules, type FrictionNudge, type FrictionSignal, type FrictionKind, } from "./friction.js";
 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";

package/dist/index.js

@@ -1,4 +1,5 @@
 export { GraineInAppClient, } from "./client.js";
+export { FrictionDetector, resolveFriction, rulesFor, DEFAULT_FRICTION, } from "./friction.js";
 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";

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

@@ -2,6 +2,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 { FrictionConfig } from "../friction.js";
 import { type LauncherInset, type LauncherVisibility } from "./navigation.js";
 interface GraineContextValue {
     client: GraineInAppClient;
@@ -44,6 +45,7 @@ export type GraineEvent = {
     type: "action_completed";
     name: string;
     status: string;
+    message?: string;
 } | {
     type: "muted";
     muted: boolean;
@@ -56,6 +58,11 @@ export type GraineEvent = {
 } | {
     type: "launcher_shown";
     screen: string | null;
+} | {
+    type: "friction_detected";
+    name: string;
+    screen: string;
+    detail: string;
 };
 export interface GraineWidget {
     id: string;
@@ -83,11 +90,12 @@ export interface GraineProviderProps extends Partial<GraineInAppOptions> {
         current: any;
     } | null;
     appVersion?: string;
+    friction?: FrictionConfig;
     includeScreens?: string[];
     launcherDelayMs?: number;
     visibility?: LauncherVisibility;
 }
-export declare function GraineProvider({ children, autoConnect, onProactive, endOnBackground, navigationRef, appVersion, includeScreens, launcherDelayMs, visibility, client: providedClient, ...options }: GraineProviderProps): React.JSX.Element;
+export declare function GraineProvider({ children, autoConnect, onProactive, endOnBackground, navigationRef, appVersion, friction, includeScreens, launcherDelayMs, visibility, client: providedClient, ...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;

package/dist/react-native/index.js

@@ -5,7 +5,7 @@ import { GraineInAppClient } from "../client.js";
 import { VoiceSession } from "../voice.js";
 import { LauncherVisibilityTracker, activeRouteName, } from "./navigation.js";
 const Ctx = createContext(null);
-export function GraineProvider({ children, autoConnect = true, onProactive, endOnBackground = true, navigationRef, appVersion, includeScreens, launcherDelayMs = 0, visibility, client: providedClient, ...options }) {
+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) {
         clientRef.current =
@@ -99,6 +99,8 @@ export function GraineProvider({ children, autoConnect = true, onProactive, endO
         };
     }, [navigationRef, client]);
     useEffect(() => { client.setAppVersion(appVersion); }, [client, appVersion]);
+    useEffect(() => { if (friction !== undefined)
+        client.configureFriction(friction); }, [client, friction]);
     useEffect(() => {
         if (!navigationRef?.current)
             setLauncherVisible(true);
@@ -134,6 +136,7 @@ export function GraineProvider({ children, autoConnect = true, onProactive, endO
             })),
             client.on("widget", (widget) => setWidgets((prev) => [...prev, widget])),
             client.on("mic_denied", (p) => emitEvent({ type: "mic_denied", reason: String(p?.reason || "NotAllowedError") })),
+            client.on("friction", (s) => emitEvent({ type: "friction_detected", name: String(s?.name ?? ""), screen: String(s?.screen ?? ""), detail: String(s?.detail ?? "") })),
             client.on("muted", (m) => {
                 setMutedState(m);
                 emitEvent({ type: "muted", muted: m });
@@ -145,6 +148,12 @@ export function GraineProvider({ children, autoConnect = true, onProactive, endO
                 emitEvent({ type: "agent_speaking", speaking });
             }),
             client.on("action", (req) => emitEvent({ type: "action_requested", name: req?.name ?? "" })),
+            client.on("action_result", (r) => emitEvent({
+                type: "action_completed",
+                name: r?.name ?? "",
+                status: r?.status ?? "unknown",
+                ...(r?.message ? { message: String(r.message) } : {}),
+            })),
             client.on("transcript", ({ text, final }) => {
                 if (text)
                     setCaption({ role: "customer", text, live: !final });
@@ -323,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.23.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",