@graineai/inapp-react-native 0.27.1 → 0.27.4

package/INTEGRATION.md

@@ -518,6 +518,42 @@ your funnel.
 
 ---
 
+## Tap capture when your screens sit above the provider
+
+`GraineProvider` wraps its children in `GraineTouchCapture`, so an app whose
+whole tree hangs below the provider gets best-effort tap tracking for free
+(`captureTaps`, on by default with `fab`).
+
+That covers fewer apps than it sounds. An app that builds its client at startup
+and registers it with `setDefaultClient` can mount the provider anywhere — often
+deep, around a call bar or a single screen — while the screens the customer
+actually taps sit *above* it. Capture inside the provider then wraps the bar's
+own chrome and sees none of the taps that matter.
+
+For that layout, mount capture at your own root. Both components are exported
+and work without a provider above them: the client resolves through
+`setDefaultClient`, and the launcher-visibility gate simply does not apply when
+there is no provider context to read it from.
+
+```tsx
+import { GraineTouchCapture } from "@graineai/inapp-react-native";
+
+export default function App() {
+  return (
+    <SafeAreaProvider>
+      <GraineTouchCapture>
+        <YourNavigator />
+      </GraineTouchCapture>
+    </SafeAreaProvider>
+  );
+}
+```
+
+Taps land in the screen frame as `tap:screen` events with the tap's position;
+the runtime reads them as "tapped the screen" and Call History shows them on the
+call's timeline. Named taps from `useGraineTap` are unaffected and still carry
+their names. (0.27.4 — earlier versions did not export `GraineTouchCapture`.)
+
 ## Controlling where the launcher appears
 
 `includeScreens` for a simple allowlist:
@@ -682,6 +718,42 @@ for you on unmount and on backgrounding.
 
 ---
 
+## How long "Connecting…" takes, and why
+
+From the tap to the agent's first word there are four waits. Three of them
+are paid before the tap on a current SDK; the fourth is bounded. If the
+launcher sits on "Connecting…" for more than about two seconds, one of these
+is not happening, and the table says which.
+
+| Wait | What it is | When it is paid | Typical |
+|---|---|---|---|
+| Page load | The voice engine is a page in a WebView | **Before the tap** — `GraineFab` and the provider mount the engine on open and keep it warm (0.27.2+) | ~4s, hidden |
+| Mint + REGISTER | A 120-second SIP credential, then registration on the SBC | **Before the tap**, re-warmed as it nears expiry | ~1.6s, hidden |
+| Microphone | The OS permission prompt, first time only | At the tap | 0 once granted |
+| INVITE → answer | The call itself | At the tap | ~0.3s |
+
+**The INVITE is bounded, not left to the browser.** WebRTC gathers network
+candidates before dialling, and Chrome does not report gathering complete
+until STUN has been tried on *every* interface a device has — a VPN tunnel,
+a link-local IPv6 address, a cellular path the app may not use. Those never
+answer, and Chrome retries each for about forty seconds before giving up.
+Measured on the embed page with the SIP frames timestamped: registered at
+8.2s, the usable candidate in hand at 8.3s, the INVITE not sent until 48.3s,
+then answered in 300ms. On a phone with Wi-Fi and cellular that is the
+ten-second "Connecting…" that was reported. The engine now dials the moment a
+server-reflexive candidate exists, or 1.5 seconds after gathering starts if
+none arrives — a network with no STUN at all still gets a call,
+with host candidates, rather than the pause and then the same call.
+
+**On an app that is still on 0.26.x** the first two rows are paid *after* the
+tap: the page loads and registers only once the customer has pressed the
+microphone, so "Connecting…" is honest and about six seconds long. Moving to
+0.27.4 is what hides them. The dial bound needs no app change — it lives in
+the engine page, so every install gets it when the page is deployed.
+
+What "Connecting…" should look like on a current app, then: a tap, the
+microphone prompt once, and the greeting inside a second.
+
 ## Troubleshooting
 
 **Nothing renders at all, and the console says `no_origin`.**

package/dist/client.d.ts

@@ -79,6 +79,7 @@ export declare class GraineInAppClient {
     private performAction;
     get isConnected(): boolean;
     getScreen(): ScreenContext | null;
+    private availableActionsFrameField;
     getIdentity(): Record<string, string>;
     getRecentEvents(): Array<{
         name: string;
@@ -106,7 +107,7 @@ export declare class GraineInAppClient {
     buildContextFrame(): {
         type: "app_context";
         context: Record<string, unknown>;
-        available_actions: string[];
+        available_actions?: string[];
         seq: number;
     } | null;
     private flushScreen;

package/dist/client.js

@@ -327,6 +327,18 @@ export class GraineInAppClient {
     getScreen() {
         return this.screen;
     }
+    availableActionsFrameField(declared) {
+        const usable = (declared ?? this.availableActions).filter((a) => this.actions.has(a));
+        if (usable.length)
+            return { available_actions: usable };
+        if (Array.isArray(declared))
+            return { available_actions: [] };
+        if (this.actions.size === 0) {
+            console.warn("[Graine] No in-app action handlers are registered. Falling back to the dashboard's " +
+                "catalogue so the agent is not silently disarmed — register handlers with useGraineAction.");
+        }
+        return {};
+    }
     getIdentity() {
         return { ...this.identity };
     }
@@ -478,7 +490,7 @@ export class GraineInAppClient {
                 ...(this.recentEvents.length ? { recent_events: this.recentEvents } : {}),
                 ...(this.highlightables.size ? { highlightable: [...this.highlightables] } : {}),
             }),
-            available_actions: (availableActions ?? this.availableActions).filter((a) => this.actions.has(a)),
+            ...this.availableActionsFrameField(availableActions),
             seq: ++this.screenSeq,
         };
     }

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

@@ -19,5 +19,6 @@ export interface GraineFabProps {
     }>;
     onOpen?: () => void;
     onClose?: () => void;
+    prewarm?: boolean;
 }
-export declare function GraineFab({ webView, position, size, accent: accentProp, label, overlay, onOpen, onClose }: GraineFabProps): React.JSX.Element | null;
+export declare function GraineFab({ webView, position, size, accent: accentProp, label, overlay, prewarm, onOpen, onClose }: GraineFabProps): React.JSX.Element;

package/dist/react-native/fab.js

@@ -53,23 +53,26 @@ export function GraineTouchCapture({ children, enabled = true, style }) {
     }, [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, overlay, onOpen, onClose }) {
+export function GraineFab({ webView, position = "bottom-right", size = 56, accent: accentProp, label, overlay, prewarm = true, 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, { overlay: overlay, 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, { overlay: overlay, children: _jsx(Pressable, { accessibilityRole: "button", accessibilityLabel: label ?? `Talk to ${name}`, onPress: () => { setOpen(true); onOpen?.(); }, style: ({ pressed }) => ({
+    const dashboardAccent = accentProp ?? dashboard.accent;
+    const button = (api) => {
+        if (error || !launcherVisible)
+            return null;
+        const side = position === "bottom-left" ? { left: launcherInset.right } : { right: launcherInset.right };
+        return (_jsx(Pressable, { accessibilityRole: "button", accessibilityLabel: label ?? `Talk to ${name}`, onPress: () => { setOpen(true); api.start(); onOpen?.(); }, style: ({ pressed }) => ({
                 position: "absolute", bottom: launcherInset.bottom, ...side,
-                width: size, height: size, borderRadius: size / 2, backgroundColor: accent,
+                width: size, height: size, borderRadius: size / 2, backgroundColor: dashboardAccent,
                 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() || "•" })) }) }));
+            }), 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() || "•" })) }));
+    };
+    if (!prewarm && !open)
+        return _jsx(AboveNativeScreens, { overlay: overlay, children: button({ start: () => { } }) });
+    return (_jsx(GraineVoiceLauncher, { webView: webView, onEnded: () => { setOpen(false); onClose?.(); }, children: (api) => (_jsx(AboveNativeScreens, { overlay: overlay, children: open ? _jsx(GraineAgentBar, { accent: dashboardAccent, name: name }) : button(api) })) }));
 }

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

@@ -2,6 +2,8 @@ import React from "react";
 import { GraineInAppClient, type GraineInAppOptions } from "../client.js";
 import { type AudioAdapter, type VoiceSessionOptions } from "../voice.js";
 import type { ActionHandler, ScreenContext, ScreenField } from "../protocol.js";
+export { GraineFab, GraineTouchCapture } from "./fab.js";
+export type { GraineFabProps, GraineTouchCaptureProps } from "./fab.js";
 import type { FrictionConfig } from "../friction.js";
 import { type LauncherInset, type LauncherVisibility } from "./navigation.js";
 interface GraineContextValue {
@@ -133,4 +135,3 @@ export declare function useGraineReady(): {
     ready: boolean;
     error: string | null;
 };
-export {};

package/dist/react-native/index.js

@@ -4,6 +4,7 @@ import { AppState } from "react-native";
 import { GraineInAppClient } from "../client.js";
 import { VoiceSession } from "../voice.js";
 import { GraineFab, GraineTouchCapture } from "./fab.js";
+export { GraineFab, GraineTouchCapture } from "./fab.js";
 import { LauncherVisibilityTracker, activeRouteName, } from "./navigation.js";
 export const Ctx = createContext(null);
 let defaultClient = null;

package/package.json

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