@vinaverse/react-native 0.0.0-stage → 0.1.0-alpha.11

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,327 @@
-# Temporary Holding Version
+# @vinaverse/react-native
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A ready, themeable conversation with your Vinaverse agent for React Native and Expo apps. Drop it into a screen,
+give it a conversation whose session comes from your backend, and it draws everything the realtime protocol defines:
+streaming replies, cards (photo cards for people and places, services, bookings, questions, proposals, next steps,
+your own help pages), held and unsent messages, a
+person from your business taking over, and every way a session ends. No native module; New Architecture; FlashList 2.3.2 or later.
+
+```tsx
+import { createConversation } from '@vinaverse/client/conversation';
+import { CardCarousel, VinaverseChat } from '@vinaverse/react-native';
+
+// Outside the screen: it connects early and survives navigation.
+const conversation = createConversation({
+  getSession: (request) => api.vinaverseSession(request), // your backend creates it with its service key
+  locale: 'es-US',
+  deepLinkPrefixes: ['yourapp://bookings/'],
+});
+// Opt-in: a turn's listing cards in one swipeable row (without it they stack). Module level: a stable object.
+const components = { CardGroup: CardCarousel };
+
+export function AgentScreen() {
+  return (
+    <VinaverseChat
+      conversation={conversation}
+      locale="es-US"
+      theme={{ light: { primary: '#7A2E8E', personBubble: '#7A2E8E' } }}
+      components={components}
+      onProposal={(card, decision) => api.decideProposal(card, decision)} // your backend, the person's token
+      onOpenLink={(link) => router.push(link)}
+    />
+  );
+}
+```
+
+## 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, CardCarousel } from '@vinaverse/react-native/chat';
+import { AgentLauncher, AgentRuntimeProvider } from '@vinaverse/react-native/launcher';
+import { AskAboutRow } from '@vinaverse/react-native/ask';
+import { AgentHistoryList, AgentTranscript } from '@vinaverse/react-native/history'; // the history screens
+
+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, entryPoint }) => openChat(route, mode, entryPoint)}
+    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 } }}
+  entryPoint={entryPoint}                   // 'launcher', 'ask', 'deep_link': session_opened says it
+  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={({ entryPoint }) => openChat('professional', side, entryPoint)} />
+```
+
+- **Parts:** `AgentChat` draws the conversation, a conversation that ended (`components.Ended`: `onStartNew`,
+  `reason`, `code`, `onContact`), the backend out of reach (`components.Unreachable`: `onRetry`, `reason`,
+  `onContact`), no agent at all (`components.UnavailableScreen`, the whole screen: off, or the session refused;
+  `reason`, `code`, `onRetry`, `onContact`), and under the composer thumbs on the newest whole reply seen live and the
+  privacy link (`components.Footer`, `null` to hide). Each slot replaces its screen entirely, layout and words, and gets
+  the kit's part as `Default` to wrap instead; to change only the words, pass `copy`. A person to contact
+  (`onContact`) reaches every full-screen slot. `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. So a setup flow starts when the person taps it, never on its own:
+  starting it automatically would put words in their mouth, which the kit declines by design. The opener chip's test id
+  is `vinaverse-opener` (`openerTestID` for your own); the chip asking about where the person moved is
+  `vinaverse-suggestion` (`VinaverseChat`'s `suggestionTestID`). `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`; on iOS it goes as the keyboard starts to rise, on Android once it is up), 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). Its `onOpen` and the ask row's `onPress` give `entryPoint` (`launcher`, `ask`): pass it to
+  `AgentChat`'s `entryPoint` (or `deep_link`, or your own words) and `session_opened` says where the chat was opened
+  from. Every agent part asks the runtime to `sweep()` when the app comes back to the foreground. `AskAboutRow` is "ask the agent about this" on
+  your own pages, decided once as the page draws, from the status already read: it is never added under a drawn page
+  (an agent whose status arrives later shows from the next visit), and `appearance` gives it a tint (`background`) and the
+  `chevron` or none, and `testID` its test id.
+- **Policies and adapters:** `imagePolicy` (photo hosts, frame, the stand-in for a missing photo, given the card's `title` and `kind`) 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`). A listing with no rating draws `copy.ratingNone` in the rating's place (empty by default; "New", say).
+- **History** (`@vinaverse/react-native/history` only, never `.`, so an app without a history screen ships none
+  of it): `AgentHistoryList` lists the person's past conversations, newest activity first, a page at a time as
+  they scroll (title, when, how many messages, whether it ended); a row opens (`onOpen`: show `AgentTranscript`), an
+  open one continues (`onContinue(conversation, live)`: pinned under its own key, `useAgentHistory().keyOf`, show
+  `AgentChat` with it), and deletes after the person confirms (`confirmDelete`, default the platform's alert with the
+  copy's words; a refused delete is said on the row and through `onWarning`). `AgentTranscript` reads one back, the
+  newest page first and earlier pages above (a button, and the top of the list), drawn with the chat's own bubbles and
+  cards over a read-only store, so a restored card takes nothing (no proposal confirmed, no link opened, no answer),
+  a guardrail's refusal reads as it did live ("Not answered" under the person's message) and a proposal shows the
+  outcome it had; `agentKey` + `onContinue` add "Continue", except for a conversation that `ended` (pass the row's
+  `state === 'ended'`, as the list offers Continue only for an open one). Slots: `Row`, `Empty`, `Failure`, `ListComponent` on the
+  list; `Header`, `Failure`, `ListComponent`, `MessageBubble`, `Image`, `CardGroup` and `cards` on the transcript.
+  Both show when the status offers history (`useAgentFeatures().history`); your backend serves the two routes
+  (`backendRoutes`' `list` and `read`), else they say history is not available.
+
+  ```tsx
+  import { AgentHistoryList, AgentTranscript } from '@vinaverse/react-native/history';
+
+  <AgentHistoryList subject={user?.id ?? null} mode={side} timeZone={tz}
+    onOpen={(c) => router.push({ pathname: `/history/${c.id}`, params: { ended: String(c.state === 'ended') } })}
+    onContinue={(c) => router.push({ pathname: '/chat', params: { mode: c.experience_mode, scope: c.business_scope_id } })} />
+  <AgentTranscript conversationId={id} ended={ended === 'true'} agentKey={{ subject: user?.id ?? null, mode: side }} onContinue={() => router.push('/chat')} />
+  ```
+- **Hooks** for your own parts: `useAgentConversation`, `useAgentStatus`, `useAgentStatusState` (`{ status, reading,
+  failed }`: "still reading" apart from "could not read"), `useAgentFeatures`, `useAgentProfile`, `useAgentName`,
+  `useAgentLauncher`, `useAgentRuntime`; `useAgentHistory`, `useAgentTranscript` (`@vinaverse/react-native/history`).
+- **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
+npm install @vinaverse/react-native@alpha @vinaverse/client@alpha @shopify/flash-list@^2.3.2
+```
+
+Alphas are published under the `alpha` tag. Keep every `@vinaverse/*` package on the same version, so your app and the
+kit share one copy of `@vinaverse/client`.
+
+**Import by part.** The package has an entry per part: `@vinaverse/react-native/chat` (the conversation, `AgentChat`,
+`VinaverseChat`, cards, theme), `/launcher` (`AgentLauncher` and its parts) and `/ask` (`AskAboutRow`). The launcher and
+the ask row each re-export the runtime bindings (`AgentRuntimeProvider`, the hooks) and the theme. The entries share
+their modules, so two of them still mean one theme and one chat context. `@vinaverse/react-native` itself still exports
+everything.
+
+What it buys, honestly. Metro without tree shaking (its default) puts every module an app imports statically, anywhere,
+into the one bundle it writes for iOS or Android. Measured on the kit alone (minified, brotli, peers excluded):
+
+| The app imports | Ships |
+|---|---|
+| `@vinaverse/react-native` | 14.9 kB |
+| `/launcher` and `/ask`, no chat screen | 2.9 kB |
+| `/launcher`, `/ask` and `/chat` (a chat screen anywhere) | 15.1 kB |
+
+- **The bundle** shrinks only for an app that never imports `/chat`. An app with a chat screen ships the whole kit
+  whichever way it imports it; the separate entries add about 0.1 kB.
+- **Start-up** is where an app with a chat screen gains: a screen that imports only `/launcher` runs the kit's 2.5 kB
+  of launcher code when it loads, not all 15 kB (with `@vinaverse/react-native`, using the launcher loads every part).
+  Inline requires (`inlineRequires`) defer a module until its first use, but they do not split the kit's own entry:
+  only the per-part imports do.
+- **Both** need the chat screen loaded lazily (`React.lazy`, or Expo Router's async routes). On iOS and Android a
+  production Metro bundle is still one file, so lazy loading defers when the chat's code runs, never whether it ships;
+  on the web, async routes put it in a bundle of its own.
+
+Loading the chat screen lazily. On the web, Expo Router's async routes (`"asyncRoutes"` in the `expo-router` plugin's
+options in `app.json`, e.g. `{ "web": true, "default": "development" }`) put each route's code in a bundle of its own,
+loaded the first time it is visited. That setting makes routes async on iOS and Android in development only, so a
+production iOS or Android build gets no deferral from it: there, `React.lazy` is what defers the chat:
+
+```tsx
+import { lazy, Suspense } from 'react';
+import { AgentLauncher, AgentRuntimeProvider } from '@vinaverse/react-native/launcher'; // the tabs: 2.5 kB of the kit
+
+// Only this file imports /chat, and only when the screen is first drawn.
+const ChatScreen = lazy(() => import('./ChatScreen')); // ChatScreen.tsx: import { AgentChat } from '@vinaverse/react-native/chat'
+
+export function Chat() {
+  return (
+    <Suspense fallback={null}>
+      <ChatScreen />
+    </Suspense>
+  );
+}
+```
+
+What is lost without it: a screen that imports `/chat` statically, or anything that does, loads and runs the whole chat
+(about 13 kB of the kit, its cards and list) when that screen's module first runs; with inline requires, when it is
+first used. Nothing breaks either way, and the bundle is the same on iOS and Android.
+
+**One build under Metro.** Every `@vinaverse/*` entry lists the `react-native` condition first, which React Native's
+and Expo's Metro configs set for iOS and Android: Metro takes the CommonJS build for an `import`, a `require`, and a
+`require` Babel writes for you (an `export const X = ImportedBinding` becomes a getter that requires), so an app holds
+one copy of the kit and one of each React context. Before 0.1.0-alpha.8 an ES import and a require resolved to
+different builds, and a card drawn from the second found no chat around it; a `metro.config.js` that forces the `import`
+condition for `@vinaverse/*` is no longer needed (harmless if kept). Jest with jest-expo resolves the same CommonJS
+build, untransformed. Web bundlers (no `react-native` condition) take the ES module build for an import: import the kit
+with `import` statements there.
+
+**Size on iOS and Android comes from the per-part entries, not tree shaking.** Metro takes the CommonJS build there,
+which no tree shaking (Expo's production tree shaking included) can trim: a screen ships and runs every module of the
+entry it imports. So import by part (`/launcher`, `/ask`, `/chat`) to keep the kit's start-up work to the parts a
+screen draws. Tree shaking (webpack, Rollup, esbuild, Expo on the web) applies on the web only, where an import takes
+the ES module build.
+
+## Peer dependencies
+
+| Package | Range | Why |
+|---|---|---|
+| `react` | `>=19.1` | hooks over `useSyncExternalStore` |
+| `react-native` | `>=0.81` | the New Architecture (FlashList v2 needs it) |
+| `@shopify/flash-list` | `>=2.3.2 <3` | the chat list: `maintainVisibleContentPosition` with `startRenderingFromBottom` and `autoscrollToBottomThreshold`; the kit is tested on 2.3.2 |
+
+## What you can change, and what you cannot
+
+- **Change:** colors (light and dark), font family, radii and spacing (`theme`); every string (`copy`, in en, es and
+  pt-BR built in); the header, bubbles, composer, empty state, images, the list (LegendList works) and any card kind
+  (`components`, each slot gets the default as `Default` to wrap it); or compose your own layout from the exported
+  parts inside `VinaverseChatProvider`, or your own UI on `@vinaverse/react`'s hooks.
+- **Cannot:** remove, cover or reword the AI disclosure (the server's text, always shown under the header); remove
+  "Powered by Vinaverse" (v1); show a person from your business as the agent or the agent as a person; call the agent
+  an assistant; draw a proposal as done before your backend's outcome, or confirm one without `onProposal`. The kit
+  draws these outside every slot.
+
+## Sessions and the app's lifecycle
+
+- **The session comes from your backend**, never a fixed secret: `getSession(request)` when the conversation opens and
+  on the person's next action after a session ended, and `refreshSecret(sessionId)` for a fresh client secret (on a
+  refused secret, 4401, and before reopening after the background). The app never holds a service key.
+- **Background**: the kit tells the conversation when the app goes to the background and comes back (`AppState`).
+  By default the connection stays, without pings; `createConversation({ closeInBackground: true, refreshSecret })`
+  closes it in the background and opens it again, with a fresh secret, in the foreground. Nothing typed is lost.
+- **A session's end**: pass `expires_at` on from the session your backend created. Past it (the tenant's tool token
+  with it), the person's next message gets a new session for the same conversation from `getSession`; the old one is
+  never reopened with a fresh secret. A reconnect keeps everything drawn: the session's transcript merges by id.
+- **Modes**: a customer and a professional each get their own conversation, `createConversationsByMode`, and the
+  screen draws `conversations.select(mode)`. Each mode keeps its own history on the device, and `getSession` gets the
+  `mode` so your backend creates the session for that mode's agent.
+- **Language**: the agent answers in `subject.locale`, which your backend sets when it creates the session; the kit's
+  `locale` prop is only for its own words, dates and money (and is passed to `getSession` as a hint you may ignore).
+
+## Handlers
+
+| Prop | When |
+|---|---|
+| `onProposal(card, 'confirm' \| 'decline')` | the person decided a proposal: apply it with your backend and the person's token, return the outcome |
+| `onOpenLink(link, card)` | a card's link (it already passed the deep-link rule): route by the page it names |
+| `onCardAction(card, action)` | a card action without a link (also sent to the session) |
+| `onPickPhoto(question, card)` | a photo question: pick, upload to your backend, return `{ upload_ref }` |
+| `failureAction` | `{ label?, onPress(state) }`: a way out on a failed turn and on "couldn't connect" ([When the agent fails](#when-the-agent-fails)) |
+| `onWarning(message, { code })` | warnings for your logger, `code` one of `theme` (hard to read), `copy` (says "assistant"), `send_failed`, `answer_failed`, `proposal_failed`, `photo_failed`, so you count them without the text |
+
+## When the agent fails
+
+Two failures need a way out for the person: a turn that failed before any reply ("Something went wrong.") and no
+session to talk to ("Couldn't connect.", with "Try again"). Give one action for both, drawn as a button by the kit's
+own parts, so a person is always the way out:
+
+```tsx
+<VinaverseChat
+  conversation={conversation}
+  failureAction={{ onPress: (state) => openSupport(state.conversationId) }} // "Talk to a person", in the person's language
+/>
+```
+
+`label` replaces "Talk to a person" (the copy's `talkToPerson`, which `copy` can also change). Or replace either part:
+`components.Error` (the failed turn) and `components.Unavailable` (the banner) each get the `state` and the kit's own
+part as `Default`. With neither, the kit draws both as before.
+
+| `state` | |
+|---|---|
+| `kind` | `turn_failed` or `unavailable` |
+| `reason` | the turn's error code (`internal`, `timeout`, …), or `unavailable` / `unauthorized` |
+| `retry` | try again, when it can be: the person's text once more, for a turn the server allows to retry (once); a new session for `unavailable`. Undefined otherwise |
+| `conversationId` | the conversation, once a session named it: for your support records |
+
+## Listings, carousels, links and the welcome
+
+- **Professionals and spaces** draw as photo cards: the hero photo (through your `Image` slot, so `expo-image`'s cache
+  applies), the name's monogram when there is none or it fails, rating with its count, "From $45" and the next open
+  time, said as people say it ("Next: tomorrow, 10:00 AM"; `copy.today` and `copy.tomorrow`, else the date). The
+  photo frame is `imagePolicy.aspectRatio` (default 1.6); `'natural'` draws a card on its own in its photo's own
+  shape, held within `naturalAspect` (square to 2:1 by default), while a card in a carousel keeps the fixed frame.
+- **Bookings, services and every other card** show their `status` (a booking's "Confirmed") first among the badges,
+  and a tap opens what the card is about (its `ref`) through `onOpenTarget`, as a listing does.
+- **A carousel** for the cards a turn draws together: add the kit's `CardCarousel`. A turn's cards of one carousel
+  group join one row where the first of them is, even with another card between them. Without it they draw one under
+  another; it is opt-in so an app that does not use it does not ship it.
+
+  ```tsx
+  import { CardCarousel, VinaverseChat } from '@vinaverse/react-native';
+  const components = { Image: ExpoImage, CardGroup: CardCarousel }; // module level: a stable object
+  <VinaverseChat conversation={conversation} components={components} onOpenLink={openLink} />;
+  ```
+
+- **Links**: when your scope keeps the agent from answering, it shows your own help, support, policy, contact or
+  feedback pages. Each opens through `onOpenLink` (an https page too: your in-app browser), a deep link only when it
+  passes your deep-link prefixes.
+- **The welcome**: pass `welcome` on from the session your backend created; the kit greets an empty conversation with
+  it and its chips (no model call). A chip sends its message as the person's own. An `EmptyState` slot gets both.
+
+## The keyboard
+
+`keyboardBehavior` keeps the composer above the keyboard: `padding` on iOS by default, nothing on Android (the window
+resizes). An edge-to-edge Android app whose window does not resize passes `padding`; an app that manages the keyboard
+itself passes `none`. This is checked on devices in the release's stabilization phase, not by the unit tests.
+
+## Performance and accessibility
+
+A streamed reply re-renders only its own bubble, at most once per frame; a new message renders one row; typing renders
+only the composer (held by render-count tests). The list is anchored at the bottom without being inverted, so screen
+readers read it oldest first; finished replies are announced once; every control has a 44 pt target and a role;
+right-to-left languages, large text and reduced motion are respected.
+
+More: [docs/architecture/ui-kits.md](../../docs/architecture/ui-kits.md). An Expo example:
+[examples/expo-chat](../../examples/expo-chat).
+
+## License
+
+Apache-2.0

package/dist/ask.cjs

@@ -0,0 +1,62 @@
+'use strict';
+
+var chunkNMKJ7LIJ_cjs = require('./chunk-NMKJ7LIJ.cjs');
+var chunk6QYDPGRS_cjs = require('./chunk-6QYDPGRS.cjs');
+var agent = require('@vinaverse/react/agent');
+
+
+
+Object.defineProperty(exports, "AskAboutRow", {
+  enumerable: true,
+  get: function () { return chunkNMKJ7LIJ_cjs.AskAboutRow; }
+});
+Object.defineProperty(exports, "ThemeProvider", {
+  enumerable: true,
+  get: function () { return chunk6QYDPGRS_cjs.ThemeProvider; }
+});
+Object.defineProperty(exports, "useTheme", {
+  enumerable: true,
+  get: function () { return chunk6QYDPGRS_cjs.useTheme; }
+});
+Object.defineProperty(exports, "AgentRuntimeProvider", {
+  enumerable: true,
+  get: function () { return agent.AgentRuntimeProvider; }
+});
+Object.defineProperty(exports, "forgetGreeting", {
+  enumerable: true,
+  get: function () { return agent.forgetGreeting; }
+});
+Object.defineProperty(exports, "greetedKey", {
+  enumerable: true,
+  get: function () { return agent.greetedKey; }
+});
+Object.defineProperty(exports, "useAgentConversation", {
+  enumerable: true,
+  get: function () { return agent.useAgentConversation; }
+});
+Object.defineProperty(exports, "useAgentFeatures", {
+  enumerable: true,
+  get: function () { return agent.useAgentFeatures; }
+});
+Object.defineProperty(exports, "useAgentLauncher", {
+  enumerable: true,
+  get: function () { return agent.useAgentLauncher; }
+});
+Object.defineProperty(exports, "useAgentName", {
+  enumerable: true,
+  get: function () { return agent.useAgentName; }
+});
+Object.defineProperty(exports, "useAgentProfile", {
+  enumerable: true,
+  get: function () { return agent.useAgentProfile; }
+});
+Object.defineProperty(exports, "useAgentRuntime", {
+  enumerable: true,
+  get: function () { return agent.useAgentRuntime; }
+});
+Object.defineProperty(exports, "useAgentStatus", {
+  enumerable: true,
+  get: function () { return agent.useAgentStatus; }
+});
+//# sourceMappingURL=ask.cjs.map
+//# sourceMappingURL=ask.cjs.map

package/dist/ask.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"ask.cjs","sourcesContent":[]}

package/dist/ask.d.cts

@@ -0,0 +1,38 @@
+export { AgentRuntimeProvider, GreetingStorage, UseAgentConversation, UseAgentLauncher, forgetGreeting, greetedKey, useAgentConversation, useAgentFeatures, useAgentLauncher, useAgentName, useAgentProfile, useAgentRuntime, useAgentStatus } from '@vinaverse/react/agent';
+import { CopyOverrides } from '@vinaverse/react';
+import { ComponentType, ReactNode } from 'react';
+import { a as ThemeOverrides, C as ColorSchemeSetting } from './theme-BhiEGv64.cjs';
+export { T as Theme, b as ThemeProvider, u as useTheme } from './theme-BhiEGv64.cjs';
+import '@vinaverse/tokens';
+
+/** The row's look beyond the theme. */
+interface AskAboutRowAppearance {
+    /** A tint behind the row; default the theme's `surface`. */
+    readonly background?: string;
+    /** The chevron at the row's end. Default true. */
+    readonly chevron?: boolean;
+}
+interface AskAboutRowProps {
+    /** "Ask Example Agent about Riley Sample". */
+    readonly title: string;
+    readonly body?: string;
+    /** The person asks: open the chat with `entryPoint` (`ask`), so the session says where it was opened from. */
+    readonly onPress: (from: {
+        readonly entryPoint: 'ask';
+    }) => void;
+    /** The app's brand mark at the row's start; default the agent name's first letter. */
+    readonly Mark?: ComponentType<{
+        readonly size: number;
+        readonly color: string;
+    }>;
+    readonly appearance?: AskAboutRowAppearance;
+    readonly locale?: string;
+    readonly copy?: CopyOverrides;
+    readonly theme?: ThemeOverrides;
+    readonly colorScheme?: ColorSchemeSetting;
+    /** The row's test id. Default `vinaverse-ask-about`. */
+    readonly testID?: string;
+}
+declare function AskAboutRow(props: AskAboutRowProps): ReactNode;
+
+export { AskAboutRow, type AskAboutRowAppearance, type AskAboutRowProps, ColorSchemeSetting, ThemeOverrides };