@vinaverse/react-native 0.1.0-alpha.4 → 0.1.0-alpha.5

package/README.md

@@ -33,6 +33,72 @@ export function AgentScreen() {
 }
 ```
 
+## Hosting the agent (the runtime)
+
+An app that hosts the agent writes its backend once (`createAgentRuntime`, `@vinaverse/client/agent`) and draws the
+parts; which conversation, keeping it across screens, waiting the backend out, a conversation that ended, the backend
+out of reach, status, name, ratings and sign-out are the runtime's.
+
+```tsx
+import { createAgentRuntime } from '@vinaverse/client/agent';
+import { AgentChat, AgentLauncher, AgentRuntimeProvider, AskAboutRow, CardCarousel } from '@vinaverse/react-native';
+
+const agent = createAgentRuntime({ backend: { openSession, refreshSecret, status }, conversation: { locale } });
+const components = { CardGroup: CardCarousel, Image: ExpoImage }; // module level: stable
+const imagePolicy = { hosts: ['images.example.com'], aspectRatio: 1.6, Placeholder: BrandTile }; // stable too
+
+<AgentRuntimeProvider runtime={agent}>
+  <Tabs />
+  <AgentLauncher subject={user?.id ?? null} mode={side} Mark={YourMark}
+    route={currentTab} routes={['home', 'explore']} hidden={sheetOpen}  // never with the keyboard up
+    storage={preferences} onOpen={({ route, mode }) => openChat(route, mode)}
+    style={{ position: 'absolute', right: 16, bottom: tabBarHeight + 16 }} />
+</AgentRuntimeProvider>
+
+// The chat screen
+<AgentChat
+  agentKey={{ subject: user?.id ?? null, mode: side, scope: businessId }}
+  place={{ screen: 'professional', entity: { type: 'professional', id } }}
+  askAbout={`Tell me about ${name}`}        // offered when the session was told another place
+  starters={startersFor(screen)}            // when the session brings no welcome
+  components={components}
+  onOpenTarget={(t) => router.push(routeFor(t))}   // a card about a professional, a space, a booking
+  onOpenLink={openLink}
+  onContact={() => router.push('/contact')}       // a person, when the agent fails or is unavailable
+  onOpenPrivacy={() => router.push('/privacy')}
+  prefetchImage={(url) => Image.prefetch(url)}
+  imagePolicy={imagePolicy}
+/>
+
+// On the app's own page about a professional
+<AskAboutRow title={`Ask ${agentName} about ${name}`} onPress={() => openChat('professional', side)} />
+```
+
+- **Parts:** `AgentChat` draws the conversation, a conversation that ended (`components.Ended`, start over), the backend
+  out of reach (`components.Unreachable`, try again), no agent at all (`components.UnavailableScreen`, the whole
+  screen: off, or the session refused, with a person through `onContact`), and under the composer thumbs on the newest
+  whole reply and the privacy link (`components.Footer`, `null` to hide); each slot gets the kit's part as `Default`,
+  to wrap it. `opener` is a first question as a chip the person taps (a flow that asks for itself), until they say
+  anything; nothing is ever sent in their name. `AgentLauncher` is a round button with
+  a greeting bubble once per person and mode (`storage`: your preferences store; `greeting`: words or words by mode,
+  read through `announce`; `storageKey` maps the record to one your app already keeps, so nobody is greeted twice),
+  your `Mark` inside, floating where `placement` says (`edge`, `bottom` above your tab bar, `inset`; `style` after it),
+  with `appearance` (a `ring`, the `shadow`, the bubble's `tail`), shown on your `routes` only, never with the keyboard
+  up (`hideWithKeyboard`), stepping aside when you say (`hidden`), and only when the status offers it; its button,
+  bubble and entrance are slots (`LauncherButton`, `LauncherGreeting`, `LauncherEntrance`: a short fade and scale,
+  none with reduced motion). `AskAboutRow` is "ask the agent about this" on
+  your own pages, shown when the agent is available, decided once per visit.
+- **Policies and adapters:** `imagePolicy` (photo hosts, frame, the stand-in for a missing photo) applies to every card
+  and every fetch ahead; `announce` reads finished replies and the greeting your way; `onChip` hears a tapped chip.
+  Card renderers get the card read once (`read`).
+- **Hooks** for your own parts: `useAgentConversation`, `useAgentStatus`, `useAgentFeatures`, `useAgentProfile`,
+  `useAgentName`, `useAgentLauncher`, `useAgentRuntime`.
+- **Events** for analytics through `onEvent`: sessions, ratings, chips, targets and links opened, the launcher shown,
+  opened, greeted and its greeting closed.
+- **StrictMode, in development only:** React mounts, unmounts and mounts again, so a conversation still opening is let
+  go with the first unmount and the second mount asks your backend for another session: two `openSession` calls per
+  opening in development, one in a release build. The first request's answer is dropped, never shown.
+
 ## Install
 
 ```sh