@graineai/inapp-react-native 0.26.1 → 0.27.0

package/INTEGRATION.md

@@ -819,9 +819,12 @@ fourth. The guarantees, so you do not have to think about them:
   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.
+- **Cleanup-safe.** The description is re-sent whenever its state changes and
+  withdrawn only on unmount — never on a change (0.26.2; earlier versions sent
+  a screen-less frame before every navigation). The withdrawal 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.
 - **Self-healing.** The newest screen is re-asserted every few seconds during
@@ -882,7 +885,9 @@ whole translation:
 | `continuous` / `perScreen` | same |
 | `perScreen` / `oncePerGroupEntry` / `oncePerAppSession` | same |
 | `EmbedButtonInset` | `LauncherInset` — same shape |
-| `EmbedButton` (mount it yourself) | `GraineLauncher` |
+| `EmbedButton` / the provider mounts the FAB | `fab={{ webView }}` on `GraineProvider`, or `GraineFab` yourself |
+| Best-effort click tracking on touchables | `captureTaps` (on by default with `fab`) — `tap:screen` events |
+| `useInitialize` → `{ isInitialized, error }` | `useGraineInit()` |
 | `Embed.Event(USER_DATA, { app_user_id, data })` | `useGraineIdentify()` / `client.identify({ id, name, … })` |
 | `Embed.Event(SCREEN_STATE, { screen, data })` | `useGraineScreen({ screen, fields })` |
 | `Embed.Event(CUSTOM_EVENT, data)` / `ANALYTICS_DATA` | `useGraineTrack()` / `client.track(name, data)` |

package/README.md

@@ -225,6 +225,9 @@ requests a permission on your behalf.
 | `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. |
+| `fab={{ webView }}` on the provider / `GraineFab` | The floating button, mounted for you; opens the conversation, folds back on end. |
+| `captureTaps` / `GraineTouchCapture` | Every tap tracked automatically — no per-button wrapping. |
+| `useGraineInit()` | `{ isInitialized, error }`. |
 | `GraineAgentBar` | Optional default UI. Mount at the root. Replace it with your own. |
 | `addMaskRule(pattern, token)` | Mask an app-specific identifier format. |
 

package/dist/client.d.ts

@@ -97,7 +97,10 @@ export declare class GraineInAppClient {
     setScreen(context: ScreenContext | null): void;
     private dispatchFriction;
     reportEvent(event: AppEvent): void;
-    track(name: string, data?: Record<string, unknown>): void;
+    track(name: string, data?: Record<string, unknown>, opts?: {
+        coalesce?: boolean;
+    }): void;
+    private scheduleScreenTrailing;
     private scheduleScreen;
     setAppVersion(version: string | null | undefined): void;
     buildContextFrame(): {

package/dist/client.js

@@ -415,16 +415,34 @@ export class GraineInAppClient {
         this.emit("app_event", event);
         this.send({ type: "app_event", event });
     }
-    track(name, data) {
+    track(name, data, opts) {
         if (!name)
             return;
         this.recentEvents.push({ name, at: Date.now(), ...(data ? { data } : {}) });
         if (this.recentEvents.length > 10)
             this.recentEvents.shift();
+        if (opts?.coalesce) {
+            this.dispatchFriction(this.detector.onTrack(name, Date.now()));
+            if (this.screen)
+                this.scheduleScreenTrailing();
+            return;
+        }
         this.dispatchFriction(this.detector.onTrack(name, Date.now()));
         if (this.screen)
             this.scheduleScreen();
     }
+    scheduleScreenTrailing() {
+        this.pendingScreen = true;
+        if (this.contextTimer)
+            return;
+        this.contextTimer = setTimeout(() => {
+            this.contextTimer = null;
+            if (this.pendingScreen) {
+                this.pendingScreen = false;
+                this.scheduleScreen();
+            }
+        }, CONTEXT_THROTTLE_MS);
+    }
     scheduleScreen() {
         this.emit("screen", { screen: this.screen, actions: this.getAvailableActions() });
         if (this.contextTimer) {

package/dist/friction.js

@@ -225,7 +225,10 @@ export class FrictionDetector {
         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);
+        const label = name.slice(4);
+        const s = this.signal("rage_taps", { tap: label, count: times.length, seconds: (windowMs / 1000).toFixed(1) }, label === "screen"
+            ? `The customer tapped the "{title}" screen {count} times in {seconds}s — something on it may not be responding or not doing what they expect.`
+            : `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) {

package/dist/index.d.ts

@@ -4,8 +4,10 @@ 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, useGraineField, useGraineClient, setDefaultClient, 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, useGraineInit, type GraineEvent, type GraineProviderProps, type Turn, type Caption, } from "./react-native/index.js";
 export { requestMicrophonePermission } from "./react-native/permissions.js";
+export { GraineFab, GraineTouchCapture, TAP_MAX_MOVE_PX, TAP_MAX_MS, type GraineFabProps, type GraineTouchCaptureProps, } from "./react-native/fab.js";
+export { UNNAMED_TAP } from "./protocol.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";
 export { GraineAgentBar, GraineLauncher, type GraineAgentBarProps, type GraineLauncherProps, type GraineBarTheme, } from "./react-native/ui.js";

package/dist/index.js

@@ -3,8 +3,10 @@ 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, useGraineField, useGraineClient, setDefaultClient, 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, useGraineInit, } from "./react-native/index.js";
 export { requestMicrophonePermission } from "./react-native/permissions.js";
+export { GraineFab, GraineTouchCapture, TAP_MAX_MOVE_PX, TAP_MAX_MS, } from "./react-native/fab.js";
+export { UNNAMED_TAP } from "./protocol.js";
 export { resolveNativeAppearance, } from "./react-native/appearance.js";
 export { RtcVoiceSessionController, RtcVoiceError, } from "./react-native/voice-rtc.js";
 export { GraineAgentBar, GraineLauncher, } from "./react-native/ui.js";

package/dist/protocol.d.ts

@@ -58,3 +58,4 @@ export interface AppActionResultFrame extends AppActionResult {
 export type ActionHandler = (args: Record<string, any>) => AppActionResult | void | Promise<AppActionResult | void>;
 export declare const ACTION_DEADLINE_MS = 6000;
 export declare const CONTEXT_THROTTLE_MS = 400;
+export declare const UNNAMED_TAP = "tap:screen";

package/dist/protocol.js

@@ -1,2 +1,3 @@
 export const ACTION_DEADLINE_MS = 6000;
 export const CONTEXT_THROTTLE_MS = 400;
+export const UNNAMED_TAP = "tap:screen";

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

@@ -0,0 +1,20 @@
+import React, { type ComponentType } from "react";
+import { type StyleProp, type ViewStyle } from "react-native";
+export declare const TAP_MAX_MOVE_PX = 12;
+export declare const TAP_MAX_MS = 400;
+export interface GraineTouchCaptureProps {
+    children: React.ReactNode;
+    enabled?: boolean;
+    style?: StyleProp<ViewStyle>;
+}
+export declare function GraineTouchCapture({ children, enabled, style }: GraineTouchCaptureProps): React.JSX.Element;
+export interface GraineFabProps {
+    webView: ComponentType<any>;
+    position?: "bottom-right" | "bottom-left";
+    size?: number;
+    accent?: string;
+    label?: string;
+    onOpen?: () => void;
+    onClose?: () => void;
+}
+export declare function GraineFab({ webView, position, size, accent: accentProp, label, onOpen, onClose }: GraineFabProps): React.JSX.Element | null;

package/dist/react-native/fab.js

@@ -0,0 +1,85 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useContext, useRef, useState } from "react";
+import { Image, Platform, Pressable, Text, View } from "react-native";
+let FullWindowOverlay = null;
+try {
+    if (Platform.OS === "ios" && typeof require === "function") {
+        FullWindowOverlay = require("react-native-screens")?.FullWindowOverlay ?? null;
+    }
+}
+catch {
+    FullWindowOverlay = null;
+}
+function AboveNativeScreens({ children }) {
+    if (!FullWindowOverlay)
+        return _jsx(_Fragment, { children: children });
+    const Overlay = FullWindowOverlay;
+    return _jsx(Overlay, { children: _jsx(View, { style: { flex: 1 }, pointerEvents: "box-none", children: children }) });
+}
+import { Ctx, useGraineAgent, useGraineClient } from "./index.js";
+import { GraineVoiceLauncher } from "./voice-launcher.js";
+import { GraineAgentBar } from "./ui.js";
+import { resolveNativeAppearance } from "./appearance.js";
+import { UNNAMED_TAP } from "../protocol.js";
+export const TAP_MAX_MOVE_PX = 12;
+export const TAP_MAX_MS = 400;
+export function GraineTouchCapture({ children, enabled = true, style }) {
+    const client = useGraineClient();
+    const ctx = useContext(Ctx);
+    const start = useRef(null);
+    const onTouchStart = useCallback((e) => {
+        try {
+            const t = e?.nativeEvent;
+            if (!t || (t.touches?.length ?? 1) > 1) {
+                start.current = null;
+                return;
+            }
+            start.current = { x: t.pageX, y: t.pageY, at: Date.now() };
+        }
+        catch {
+            start.current = null;
+        }
+    }, []);
+    const onTouchEnd = useCallback((e) => {
+        try {
+            const s = start.current;
+            start.current = null;
+            if (!enabled || !s)
+                return;
+            const t = e?.nativeEvent;
+            if (!t)
+                return;
+            if (Math.hypot(t.pageX - s.x, t.pageY - s.y) > TAP_MAX_MOVE_PX)
+                return;
+            if (Date.now() - s.at > TAP_MAX_MS)
+                return;
+            if (!client.getScreen())
+                return;
+            if (ctx && !ctx.launcherVisible)
+                return;
+            client.track(UNNAMED_TAP, { x: Math.round(t.pageX), y: Math.round(t.pageY) }, { coalesce: true });
+        }
+        catch { }
+    }, [client, ctx, enabled]);
+    return (_jsx(View, { style: [{ flex: 1 }, style], onTouchStart: onTouchStart, onTouchEnd: onTouchEnd, children: children }));
+}
+export function GraineFab({ webView, position = "bottom-right", size = 56, accent: accentProp, label, onOpen, onClose }) {
+    const { launcherVisible, launcherInset, appearance, error } = useGraineAgent();
+    const [open, setOpen] = useState(false);
+    const dashboard = resolveNativeAppearance(appearance, { accent: "#318CE7", heading: "Assistant", radius: 18 });
+    const accent = accentProp ?? dashboard.accent;
+    const name = dashboard.heading;
+    if (error || !launcherVisible)
+        return null;
+    if (open) {
+        return (_jsx(AboveNativeScreens, { children: _jsx(GraineVoiceLauncher, { webView: webView, autoStart: true, onEnded: () => { setOpen(false); onClose?.(); }, children: () => _jsx(GraineAgentBar, { accent: accent, name: name }) }) }));
+    }
+    const side = position === "bottom-left" ? { left: launcherInset.right } : { right: launcherInset.right };
+    return (_jsx(AboveNativeScreens, { children: _jsx(Pressable, { accessibilityRole: "button", accessibilityLabel: label ?? `Talk to ${name}`, onPress: () => { setOpen(true); onOpen?.(); }, style: ({ pressed }) => ({
+                position: "absolute", bottom: launcherInset.bottom, ...side,
+                width: size, height: size, borderRadius: size / 2, backgroundColor: accent,
+                alignItems: "center", justifyContent: "center",
+                opacity: pressed ? 0.85 : 1,
+                elevation: 6, shadowColor: "#000", shadowOpacity: 0.25, shadowRadius: 8, shadowOffset: { width: 0, height: 4 },
+            }), children: dashboard.logoUrl ? (_jsx(Image, { source: { uri: dashboard.logoUrl }, style: { width: size * 0.6, height: size * 0.6, borderRadius: size * 0.3 } })) : (_jsx(Text, { style: { color: "#fff", fontSize: size * 0.4, fontWeight: "700" }, children: name.trim().charAt(0).toUpperCase() || "•" })) }) }));
+}

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

@@ -80,6 +80,7 @@ export interface Turn {
     text: string;
     live?: boolean;
 }
+export declare const Ctx: React.Context<GraineContextValue | null>;
 export declare function setDefaultClient(client: GraineInAppClient | null): void;
 export declare function useGraineClient(): GraineInAppClient;
 export interface GraineProviderProps extends Partial<GraineInAppOptions> {
@@ -93,11 +94,15 @@ export interface GraineProviderProps extends Partial<GraineInAppOptions> {
     } | null;
     appVersion?: string;
     friction?: FrictionConfig;
+    fab?: Omit<import("./fab.js").GraineFabProps, "webView"> & {
+        webView: React.ComponentType<any>;
+    };
+    captureTaps?: boolean;
     includeScreens?: string[];
     launcherDelayMs?: number;
     visibility?: LauncherVisibility;
 }
-export declare function GraineProvider({ children, autoConnect, onProactive, endOnBackground, navigationRef, appVersion, friction, includeScreens, launcherDelayMs, visibility, client: providedClient, ...options }: GraineProviderProps): React.JSX.Element;
+export declare function GraineProvider({ children, autoConnect, onProactive, endOnBackground, navigationRef, fab, captureTaps, 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;
@@ -120,6 +125,10 @@ export declare function useGraineWidget(): {
     dismiss: () => void;
 };
 export declare function useGraineAction(name: string, handler: ActionHandler): void;
+export declare function useGraineInit(): {
+    isInitialized: boolean;
+    error: string | null;
+};
 export declare function useGraineReady(): {
     ready: boolean;
     error: string | null;

package/dist/react-native/index.js

@@ -1,10 +1,11 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, } from "react";
 import { AppState } from "react-native";
 import { GraineInAppClient } from "../client.js";
 import { VoiceSession } from "../voice.js";
+import { GraineFab, GraineTouchCapture } from "./fab.js";
 import { LauncherVisibilityTracker, activeRouteName, } from "./navigation.js";
-const Ctx = createContext(null);
+export const Ctx = createContext(null);
 let defaultClient = null;
 export function setDefaultClient(client) {
     defaultClient = client;
@@ -17,7 +18,7 @@ export function useGraineClient() {
     }
     return client;
 }
-export function GraineProvider({ children, autoConnect = true, onProactive, endOnBackground = true, navigationRef, appVersion, friction, includeScreens, launcherDelayMs = 0, visibility, client: providedClient, ...options }) {
+export function GraineProvider({ children, autoConnect = true, onProactive, endOnBackground = true, navigationRef, fab, captureTaps, appVersion, friction, includeScreens, launcherDelayMs = 0, visibility, client: providedClient, ...options }) {
     const clientRef = useRef(null);
     if (!clientRef.current) {
         clientRef.current =
@@ -268,7 +269,9 @@ export function GraineProvider({ children, autoConnect = true, onProactive, endO
         identify: (user) => client.identify(user),
     }), [client, connected, connecting, error, open, messages, widgets, muted, agentSpeaking, caption,
         launcherVisible, launcherInset, currentScreen, onEvent, appearance, sessionReady]);
-    return _jsx(Ctx.Provider, { value: value, children: children });
+    const wantsCapture = captureTaps ?? !!fab;
+    const body = fab || wantsCapture ? (_jsxs(GraineTouchCapture, { enabled: wantsCapture, children: [children, fab ? _jsx(GraineFab, { ...fab }) : null] })) : children;
+    return _jsx(Ctx.Provider, { value: value, children: body });
 }
 function useGraine() {
     const ctx = useContext(Ctx);
@@ -346,8 +349,12 @@ export function useGraineScreen(context) {
     const serialised = JSON.stringify(context ?? null);
     useEffect(() => {
         client.setScreen(context);
-        return () => client.clearScreen(context?.screen);
     }, [client, serialised]);
+    const reported = useRef(context?.screen);
+    reported.current = context?.screen;
+    useEffect(() => () => {
+        client.clearScreen(reported.current);
+    }, [client]);
 }
 export function useGraineField(name, field) {
     const client = useGraineClient();
@@ -406,6 +413,10 @@ export function useGraineAction(name, handler) {
     handlerRef.current = handler;
     useEffect(() => client.registerAction(name, (args) => handlerRef.current(args)), [client, name]);
 }
+export function useGraineInit() {
+    const { sessionReady, error } = useGraineAgent();
+    return { isInitialized: sessionReady, error };
+}
 export function useGraineReady() {
     const { sessionReady, error } = useGraineAgent();
     return { ready: sessionReady, error };

package/package.json

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