@guideai/react-native 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,122 @@
-# Temporary Holding Version
+# @guideai/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.
+Your GuideAI agent inside a React Native app, in assistant mode. You design the chat; we run the conversation, call your API as the signed-in user, and hand you everything a reply carries: text, pictures, follow-up suggestions, and changes waiting for the user's approval.
+
+```bash
+npm install @guideai/react-native
+```
+
+React ≥ 18 and React Native ≥ 0.73. No native module of its own, so it works in Expo Go and over OTA updates.
+
+## Set up once, at startup
+
+```ts
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { GuideAI } from '@guideai/react-native';
+
+GuideAI.configure({
+  apiKey: 'pk_live_…',                  // Settings → Install
+  origin: 'https://app.example.com',    // a domain registered on the site
+  agent: 'tutor',                       // an Agent Blueprint key; omit for the main agent
+  getAuthToken: () => AsyncStorage.getItem('accessToken'),
+  onAuthExpired: () => refreshSession(), // return the new token
+  userProfile: { age: 12, class: 'JSS1', country: 'Nigeria', language: 'en' },
+});
+```
+
+### What else your API needs
+
+Declare it once in the dashboard (**Copilot Tools → your API → Supplied by your app**), then supply the values:
+
+```ts
+GuideAI.configure({
+  …,
+  getRequestHeaders: async () => ({ 'device-id': await getDeviceId() }),   // declared headers
+  toolContext: { course: openCourseId },   // declared values; or GuideAI.setToolContext(…) later
+});
+```
+
+- **Headers:** sent on every call the assistant makes to your API, never to GuideAI. Only names declared in Copilot Tools are sent, and the app's value wins over anything the model sets. `Authorization` comes from `getAuthToken`, never from here.
+- **Values:** each one fills the API inputs it's declared to fill (app key `course` fills `content_id`), so the assistant never asks the user for them.
+
+The dashboard shows the exact snippet for your declarations.
+
+### Local or staging GuideAI
+
+Production is the default. Point a development build somewhere else with `baseUrl`:
+
+```ts
+GuideAI.configure({ …, baseUrl: __DEV__ ? 'http://localhost:8000' : undefined });
+```
+
+Use `http://10.0.2.2:8000` from an Android emulator.
+
+`userProfile` is a few facts the agent pitches answers to (level, curriculum, language). Update it after login with `GuideAI.setUserProfile(profile)`.
+
+`getAuthToken` is read before every turn and may be async. The assistant calls your endpoints (the site's Copilot toolset) from the device with that token, so your API enforces the user's access exactly as it does for your own screens. A `401` asks `onAuthExpired` once and repeats the call. The token is sent only to your API, never to GuideAI, unless the toolset has `forward_user_token` switched on.
+
+## Draw your own chat
+
+```tsx
+import { useGuideAI } from '@guideai/react-native';
+
+function Tutor() {
+  const chat = useGuideAI();
+  return (
+    <>
+      {chat.messages.map((m) => (
+        <View key={m.id}>
+          <YourMarkdown text={m.content} />           {/* pictures are Markdown images here */}
+          {m.suggestions?.map((s) => (
+            <Chip key={s} label={s} onPress={() => chat.send(s)} />
+          ))}
+          {m.pendingAction && (
+            <ApproveBar
+              label={m.pendingAction.label}            // "Create the course “Algebra”"
+              onApprove={() => chat.confirm(m.id)}
+              onCancel={() => chat.cancel(m.id)}
+            />
+          )}
+        </View>
+      ))}
+      <TextInput value={chat.input} onChangeText={chat.setInput} />
+      <Button title="Send" disabled={!chat.canSend} onPress={() => chat.send()} />
+      {chat.status && <Text>{chat.status}</Text>}
+    </>
+  );
+}
+```
+
+| On `useGuideAI()` | |
+|---|---|
+| `messages` | `{ id, role, content, streaming, error, suggestions, images, pendingAction }` |
+| `send(text?)`, `input`, `setInput`, `canSend`, `busy`, `status` | The conversation. |
+| `confirm(id)`, `cancel(id)` | Answer a `pendingAction`. Nothing is written until `confirm`. |
+| `sendVoice({ uri, mimeType?, languageCode? })` | Push-to-talk: you record (e.g. `expo-audio`), we transcribe and send. Returns `{ text, error? }`. |
+| `retry()`, `clear()`, `transcribing` | |
+
+`suggestions` appear when the agent's Blueprint has the **Suggest follow-ups** node, and `images` when it has **Draw images**.
+
+## Or use ours
+
+```tsx
+import { GuideAILauncher } from '@guideai/react-native/ui';
+
+<GuideAILauncher />
+```
+
+## Telling the agent what is on screen (optional)
+
+```tsx
+import { GuideAIScreen, useGuideAIElement } from '@guideai/react-native';
+
+<GuideAIScreen name="Courses" path="/courses" title="My courses">…</GuideAIScreen>
+```
+
+## Build
+
+```
+pnpm build       # dist/: index + ui, ESM and CommonJS, bundled types
+pnpm test
+pnpm typecheck
+```

package/dist/index.cjs

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const useOnboarding = require("./useOnboarding-DWkCW5v0.cjs");
+const jsxRuntime = require("react/jsx-runtime");
+const React = require("react");
+function GuideAIScreen({
+  name,
+  path,
+  title,
+  active = true,
+  children
+}) {
+  const runtime = useOnboarding.useGuideAIRuntime();
+  const registry = React.useMemo(() => new useOnboarding.ScreenRegistry(), [name, path]);
+  React.useEffect(() => {
+    if (!active) return;
+    runtime.setActiveScreen({ path, title: title != null ? title : name, registry });
+    return () => {
+      var _a;
+      if (((_a = runtime.getActiveScreen()) == null ? void 0 : _a.registry) === registry) {
+        runtime.setActiveScreen(void 0);
+      }
+    };
+  }, [runtime, registry, path, title, name, active]);
+  return /* @__PURE__ */ jsxRuntime.jsx(useOnboarding.RegistryContext.Provider, { value: registry, children });
+}
+function useGuideAIElement(id, options) {
+  const registry = useOnboarding.useScreenRegistry();
+  const handlers = React.useRef({});
+  handlers.current = {
+    press: options.press,
+    setValue: options.setValue,
+    scrollTo: options.scrollTo
+  };
+  const {
+    label,
+    kind,
+    value,
+    accessibilityLabel,
+    placeholder,
+    hidden,
+    sectionTitle
+  } = options;
+  const canPress = Boolean(options.press);
+  const canSetValue = Boolean(options.setValue);
+  const canScrollTo = Boolean(options.scrollTo);
+  React.useEffect(() => {
+    if (!registry) return;
+    const bound = {};
+    if (canPress) bound.press = () => {
+      var _a, _b;
+      return (_b = (_a = handlers.current).press) == null ? void 0 : _b.call(_a);
+    };
+    if (canSetValue) bound.setValue = (next) => {
+      var _a, _b;
+      return (_b = (_a = handlers.current).setValue) == null ? void 0 : _b.call(_a, next);
+    };
+    if (canScrollTo) bound.scrollTo = () => {
+      var _a, _b;
+      return (_b = (_a = handlers.current).scrollTo) == null ? void 0 : _b.call(_a);
+    };
+    return registry.register(
+      { id, label, kind, value, accessibilityLabel, placeholder, hidden, sectionTitle },
+      bound
+    );
+  }, [
+    registry,
+    id,
+    label,
+    kind,
+    value,
+    accessibilityLabel,
+    placeholder,
+    hidden,
+    sectionTitle,
+    canPress,
+    canSetValue,
+    canScrollTo
+  ]);
+}
+exports.GuideAI = useOnboarding.GuideAI;
+exports.useGuideAI = useOnboarding.useGuideAI;
+exports.useOnboarding = useOnboarding.useOnboarding;
+exports.GuideAIScreen = GuideAIScreen;
+exports.useGuideAIElement = useGuideAIElement;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":["../src/react/GuideAIScreen.tsx","../src/react/useGuideAIElement.ts"],"sourcesContent":["// ============================================================\n// @guideai/react-native — screen declaration\n// ============================================================\n//\n// Wraps a screen once. Everything inside can then register itself with\n// useGuideAIElement() from any depth.\n//\n// Two identities per screen, and they are not interchangeable:\n//\n//   path  — \"/share\"     what the mobile scanner emitted. Grounding on\n//                        the backend is EXACT STRING EQUALITY against\n//                        this, so a mismatch silently loses all\n//                        route-level knowledge for the screen.\n//   name  — \"ShareForm\"  the React Navigation screen name, which is what\n//                        navigate() takes.\n//\n// Mixing them up produces no error — just an assistant that stops\n// knowing anything about the screen. Hence both are required.\n// ============================================================\n\nimport React, { useEffect, useMemo } from 'react';\nimport { RegistryContext, useGuideAIRuntime } from './context';\nimport { ScreenRegistry } from '../screen/screen-registry';\n\nexport interface GuideAIScreenProps {\n  /** React Navigation screen name, e.g. \"ShareForm\". Used by navigate(). */\n  name: string;\n  /** Scanner route path, e.g. \"/share\". Used for grounding. */\n  path: string;\n  /** Human title shown to the model. Defaults to `name`. */\n  title?: string;\n  /**\n   * Whether this screen is the one currently on top.\n   *\n   * Defaults to true. React Navigation keeps previous screens MOUNTED in\n   * the stack, so without this a backgrounded screen would keep claiming\n   * to be active and the model would be told about controls the user\n   * cannot see. Hosts using React Navigation should pass\n   * `useIsFocused()`.\n   */\n  active?: boolean;\n  children: React.ReactNode;\n}\n\nexport function GuideAIScreen({\n  name, path, title, active = true, children,\n}: GuideAIScreenProps): React.ReactElement {\n  const runtime = useGuideAIRuntime();\n\n  // One registry per mounted screen. Recreated only if the identity\n  // changes, so elements registered by children survive re-renders.\n  const registry = useMemo(() => new ScreenRegistry(), [name, path]);\n\n  useEffect(() => {\n    if (!active) return;\n\n    runtime.setActiveScreen({ path, title: title ?? name, registry });\n\n    return () => {\n      // Only stand down if still the active screen. During a transition\n      // the next screen's effect may run before this one's cleanup, and\n      // clearing then would blank a screen that just became active.\n      if (runtime.getActiveScreen()?.registry === registry) {\n        runtime.setActiveScreen(undefined);\n      }\n    };\n  }, [runtime, registry, path, title, name, active]);\n\n  return (\n    <RegistryContext.Provider value={registry}>\n      {children}\n    </RegistryContext.Provider>\n  );\n}\n","// ============================================================\n// @guideai/react-native — element declaration hook\n// ============================================================\n//\n// The manual path: a component declares itself so the assistant can see\n// and act on it.\n//\n// KNOWN LIMIT, stated rather than hidden: this is per-element work. On a\n// screen with 200 controls that is 200 calls, and an element nobody\n// declares is INVISIBLE to the assistant — it does not degrade, it is\n// simply not there, with no warning and no failing test. Automatic\n// harvesting (instrumented components, accessibility props, static\n// extraction) is the intended answer and is being explored separately.\n// Until then this is the escape hatch, and it is honest about being one.\n// ============================================================\n\nimport { useEffect, useRef } from 'react';\nimport { useScreenRegistry } from './context';\nimport type { DeclaredElement, ElementHandlers } from '../screen/screen-registry';\n\nexport type UseGuideAIElementOptions =\n  Omit<DeclaredElement, 'id'> & ElementHandlers;\n\n/**\n * Declare one element to the assistant.\n *\n * Registration is an effect, so it runs after mount and unwinds on\n * unmount. Handlers are kept in a ref and read through a stable wrapper:\n * without that, an inline `press={() => …}` would be a new function on\n * every render and re-register the element on every render with it.\n */\nexport function useGuideAIElement(\n  id: string,\n  options: UseGuideAIElementOptions,\n): void {\n  const registry = useScreenRegistry();\n\n  // Latest handlers, without making them a dependency of registration.\n  const handlers = useRef<ElementHandlers>({});\n  handlers.current = {\n    press: options.press,\n    setValue: options.setValue,\n    scrollTo: options.scrollTo,\n  };\n\n  const {\n    label, kind, value, accessibilityLabel, placeholder, hidden, sectionTitle,\n  } = options;\n\n  // WHICH capabilities exist must be part of registration, not just their\n  // implementations. Always installing a wrapper would make every element\n  // report itself as pressable, so `element_not_pressable` could never\n  // fire and the model would be told a static label is a button.\n  const canPress = Boolean(options.press);\n  const canSetValue = Boolean(options.setValue);\n  const canScrollTo = Boolean(options.scrollTo);\n\n  useEffect(() => {\n    if (!registry) return;\n\n    // Stable indirection: the registry holds these for the element's\n    // lifetime, and they read whatever the latest render supplied — so an\n    // inline arrow function does not re-register on every render.\n    const bound: ElementHandlers = {};\n    if (canPress) bound.press = () => handlers.current.press?.();\n    if (canSetValue) bound.setValue = (next: string) => handlers.current.setValue?.(next);\n    if (canScrollTo) bound.scrollTo = () => handlers.current.scrollTo?.();\n\n    return registry.register(\n      { id, label, kind, value, accessibilityLabel, placeholder, hidden, sectionTitle },\n      bound,\n    );\n  }, [\n    registry, id, label, kind, value,\n    accessibilityLabel, placeholder, hidden, sectionTitle,\n    canPress, canSetValue, canScrollTo,\n  ]);\n}\n"],"names":["useGuideAIRuntime","useMemo","ScreenRegistry","useEffect","RegistryContext","useScreenRegistry","useRef"],"mappings":";;;;;AA4CO,SAAS,cAAc;AAAA,EAC5B;AAAA,EAAM;AAAA,EAAM;AAAA,EAAO,SAAS;AAAA,EAAM;AACpC,GAA2C;AACzC,QAAM,UAAUA,cAAAA,kBAAA;AAIhB,QAAM,WAAWC,MAAAA,QAAQ,MAAM,IAAIC,cAAAA,kBAAkB,CAAC,MAAM,IAAI,CAAC;AAEjEC,QAAAA,UAAU,MAAM;AACd,QAAI,CAAC,OAAQ;AAEb,YAAQ,gBAAgB,EAAE,MAAM,OAAO,wBAAS,MAAM,UAAU;AAEhE,WAAO,MAAM;;AAIX,YAAI,aAAQ,sBAAR,mBAA2B,cAAa,UAAU;AACpD,gBAAQ,gBAAgB,MAAS;AAAA,MACnC;AAAA,IACF;AAAA,EACF,GAAG,CAAC,SAAS,UAAU,MAAM,OAAO,MAAM,MAAM,CAAC;AAEjD,wCACGC,cAAAA,gBAAgB,UAAhB,EAAyB,OAAO,UAC9B,UACH;AAEJ;AC1CO,SAAS,kBACd,IACA,SACM;AACN,QAAM,WAAWC,cAAAA,kBAAA;AAGjB,QAAM,WAAWC,MAAAA,OAAwB,EAAE;AAC3C,WAAS,UAAU;AAAA,IACjB,OAAO,QAAQ;AAAA,IACf,UAAU,QAAQ;AAAA,IAClB,UAAU,QAAQ;AAAA,EAAA;AAGpB,QAAM;AAAA,IACJ;AAAA,IAAO;AAAA,IAAM;AAAA,IAAO;AAAA,IAAoB;AAAA,IAAa;AAAA,IAAQ;AAAA,EAAA,IAC3D;AAMJ,QAAM,WAAW,QAAQ,QAAQ,KAAK;AACtC,QAAM,cAAc,QAAQ,QAAQ,QAAQ;AAC5C,QAAM,cAAc,QAAQ,QAAQ,QAAQ;AAE5CH,QAAAA,UAAU,MAAM;AACd,QAAI,CAAC,SAAU;AAKf,UAAM,QAAyB,CAAA;AAC/B,QAAI,SAAU,OAAM,QAAQ,MAAA;;AAAM,kCAAS,SAAQ,UAAjB;AAAA;AAClC,QAAI,mBAAmB,WAAW,CAAC;;AAAiB,kCAAS,SAAQ,aAAjB,4BAA4B;AAAA;AAChF,QAAI,YAAa,OAAM,WAAW,MAAA;;AAAM,kCAAS,SAAQ,aAAjB;AAAA;AAExC,WAAO,SAAS;AAAA,MACd,EAAE,IAAI,OAAO,MAAM,OAAO,oBAAoB,aAAa,QAAQ,aAAA;AAAA,MACnE;AAAA,IAAA;AAAA,EAEJ,GAAG;AAAA,IACD;AAAA,IAAU;AAAA,IAAI;AAAA,IAAO;AAAA,IAAM;AAAA,IAC3B;AAAA,IAAoB;AAAA,IAAa;AAAA,IAAQ;AAAA,IACzC;AAAA,IAAU;AAAA,IAAa;AAAA,EAAA,CACxB;AACH;;;;;;"}