@m6d/cortex-react-native 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,78 @@
1
- # Temporary Holding Version
1
+ # @m6d/cortex-react-native
2
2
 
3
- 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.
3
+ React Native chat widget for Cortex agents, on Expo SDK 58 or later. It runs the same core as `@m6d/cortex-react` and draws it with native views, in the web widget's tokens, light or dark, left to right or Arabic right to left.
4
+
5
+ Replies draw as the web widget draws them, with native views and no web view but for reports:
6
+
7
+ - Markdown from the same parser the web uses: headings, emphasis, links, lists, quotes, code blocks highlighted with a copy control, and tables with a workbook export. Each paragraph reads in the direction of its own words.
8
+ - Charts (`vega-lite`) run Vega headless on the device, its expressions interpreted rather than compiled, and draw as SVG.
9
+ - Diagrams (`mermaid`): flowcharts, sequence, state, class and ER diagrams lay out with beautiful-mermaid, which loads with the first diagram; a pie and a gantt draw as charts.
10
+ - Maps draw with MapLibre on OpenStreetMap's tiles.
11
+ - Reports show in a web view of the report page the package ships as an asset, sized to their content.
12
+
13
+ A block that cannot draw says so in its place, with a chart's own rows when it has them.
14
+
15
+ ## Install
16
+
17
+ ```sh
18
+ npx expo install @m6d/cortex-react-native @google-cloud/recaptcha-enterprise-react-native @maplibre/maplibre-react-native expo-asset expo-clipboard expo-document-picker expo-file-system expo-image-picker expo-location expo-secure-store expo-sharing expo-web-browser react-native-safe-area-context react-native-svg react-native-webview
19
+ ```
20
+
21
+ `expo install` picks the native modules' versions that match your Expo SDK. Your package manager adds the other peers, Vega and beautiful-mermaid among them. Add MapLibre's config plugin to `app.json` (`"plugins": ["@maplibre/maplibre-react-native"]`).
22
+
23
+ ## Usage
24
+
25
+ ```tsx
26
+ import { CortexChatWidget, type CortexReactNativeConfig } from '@m6d/cortex-react-native';
27
+
28
+ const config = {
29
+ transport: {
30
+ baseUrl: 'https://engine.example.com/orgs/acme/projects/app/envs/production/agents/support',
31
+ // The end user's bearer. Leave it out for an anonymous agent.
32
+ getHeaders: () => ({ Authorization: `Bearer ${token}` }),
33
+ },
34
+ locale: 'en',
35
+ theme: 'system',
36
+ returnScheme: 'dev.m6d.cortex.sample.reactnative',
37
+ } satisfies CortexReactNativeConfig;
38
+
39
+ export function Support() {
40
+ return <CortexChatWidget config={config} />;
41
+ }
42
+ ```
43
+
44
+ The widget fills its parent; `style` sizes it otherwise. Under a `SafeAreaProvider` its composer runs on under the home indicator and pads itself clear, so leave the bottom edge to it: a `SafeAreaView` around it takes `edges={['top', 'left', 'right']}`. `baseUrl` is the agent's URL: the engine's public origin plus `/orgs/<org>/projects/<project>/envs/<environment>/agents/<agent>`. Cortex checks the bearer the way the agent's auth says. Without one, the widget signs in as a visitor.
45
+
46
+ The config is the web SDKs' config: `locale` (`en` or `ar`), `theme` (`light`, `dark` or `system`), `viewMode` (`helper` beside your app, or `full` with the history beside the chat), and `hooks`, whose `onToolCall` answers a client tool without drawing anything.
47
+
48
+ ## Slots and tool components
49
+
50
+ - The `slots` prop swaps the `header`, the `landing` or the `threadList` for components of your own. Each receives the context the widget's own is drawn from. Define them outside render: a new component each render remounts the part.
51
+ - `useCortexTokens()` returns the widget's colors and sizes (`surface`, `textStrong`, `border`, `radius`...) as it draws them, so a slot matches it. Outside the widget, `useCortexTokens({ theme, colors })` resolves them for the `theme` and `colors` you give the widget.
52
+ - `config.toolComponents` answers client tools with your own views, by tool name. Each gets the call (`toolCallPart`), its `message`, and `setOutput`, which rejects when the answer did not reach Cortex.
53
+ - `config.mediaRenderers` draws a fence language as native views, by fence tag, replacing the built-in of that name or adding one. Each gets the fence's `source` and `context` (`scheme`, `locale`), and calls `onDrawn` once drawn, until when the block says it is drawing, or `onFailed` with its reason.
54
+
55
+ ## Theming
56
+
57
+ `theme` picks the scheme: `light`, `dark`, or `system` to follow the device. `colors` draws the widget in your colors instead of its own, by token, each in both schemes, as a web page overrides the `--cx-*` tokens (`CortexColors`):
58
+
59
+ ```tsx
60
+ const config = {
61
+ ...shared,
62
+ colors: { accent: { light: '#0d9488', dark: '#2dd4bf' } },
63
+ } satisfies CortexReactNativeConfig;
64
+ ```
65
+
66
+ Give hex: `#rrggbb` or `#rgb`, and `#rrggbbaa` or `#rgba` for a color with an alpha. The widget mixes and fades them, so its hovers, borders and tints follow.
67
+
68
+ ## Connecting accounts
69
+
70
+ A tool can ask the end user to connect an account. The sign-in runs in the system browser's auth session and comes back to your app on `returnScheme`. Use a domain you control, reversed and lowercase, as the sample's `dev.m6d.cortex.sample.reactnative`: Cortex refuses a scheme without a dot. Register it as your app's scheme (`scheme` in `app.json`), and list it under the environment's **Settings** in the Cortex console, among its app return schemes. Without it, the connect card says the app cannot connect accounts and offers only Not now. The widget closes the session when the card goes away or the sign-in runs out.
71
+
72
+ ## Requirements
73
+
74
+ - Expo SDK 58 or later. `expo/fetch` streams the chat's server-sent events, and Expo installs the full `URL` the widget needs.
75
+ - The native modules installed above, in the app's own dependencies. Expo Go ships all but reCAPTCHA Enterprise's and MapLibre's.
76
+ - A development build for maps and reCAPTCHA Enterprise, whose native modules Expo Go lacks; in Expo Go a map says it could not be drawn. Give the app's Podfile static frameworks, as Google's SDK requires: `expo-build-properties` with `{ "ios": { "useFrameworks": "static" } }` in `app.json`, as the sample does. Create an iOS key and an Android key in Google Cloud, and enter each in the agent's end-user authentication, with the app's bundle ID and package name.
77
+
78
+ The visitor an anonymous agent signs in is kept in the device's keychain (iOS) or keystore (Android) through `expo-secure-store`, so it stays the same visitor across launches. Files a reader picks upload from the device as they are; a file the chat holds saves through the share sheet. The widget keeps its temporary files in a `cortex` folder of the app's cache and deletes each once done with it.