@appilots/sdk 0.11.1 → 0.13.0

package/dist/navigation/index.d.mts

@@ -83,6 +83,33 @@ interface ScreenActionMetadata {
      * between sdk and mcp-generator packages.
      */
     appilotsInferred?: AppilotsInferredAction;
+    /**
+     * How long this action's work takes, in milliseconds, as DECLARED by
+     * the app. The SDK waits this long for the UI to settle after pressing
+     * it, instead of the agnostic default.
+     *
+     * There is no constant that fits: an app operation runs from ~100ms to
+     * minutes, and when the wait is too short the agent photographs a
+     * loading screen with no controls on it and plans against nothing. The
+     * app is the only party that knows, so it says so:
+     *
+     * ```tsx
+     * registerScreen({
+     *   name: 'Wizard',
+     *   actions: [{ id: 'gerar', label: 'Gerar', type: 'submit', asyncBudgetMs: 90_000 }],
+     * });
+     * ```
+     *
+     * Omitting it is supported and common: the SDK then falls back on its
+     * defaults (6s, or 10s when the generator inferred the handler is
+     * async) AND on what it can see — while the screen keeps a loading
+     * indicator up, the wait runs on to a safety ceiling. So declaring is
+     * how an app says "this one is QUICK, do not wait on my spinner", or
+     * gives a number for work that shows no indicator at all. The value is
+     * clamped to `MAX_DECLARED_ASYNC_BUDGET_MS`: a declaration is a
+     * request, not a licence to hang the session.
+     */
+    asyncBudgetMs?: number;
 }
 /**
  * Inferred metadata about an action's expected async behavior.
@@ -149,19 +176,34 @@ interface NavigationConfig {
  * ```
  */
 declare function registerScreen(metadata: ScreenMetadata): void;
-/** Get metadata for a specific screen */
+/**
+ * Get metadata for a specific screen.
+ *
+ * Exact name first, then the SAME fold the server applies.
+ *
+ * The asymmetry this closes: the backend routes by
+ * `normalizeRouteIdentity`, so `HomeTab`, `HomeScreen` and `Home` are
+ * one screen to it, while this lookup was a bare `Map.get` and they were
+ * three. An app whose navigator names a tab `HomeTab` and whose
+ * `registerScreen` says `Home` — the ordinary React Navigation shape,
+ * since the tab and the screen inside it cannot share a name — served
+ * the agent a described screen from the map and `undefined` here, so the
+ * title, the description and the declared risk of the screen it was
+ * standing on all went missing. Nothing reported an error; the metadata
+ * was simply absent.
+ *
+ * Folded matching only resolves an UNAMBIGUOUS hit. Two screens that
+ * fold together (`Orders` and `OrdersTab` both registered) are a real
+ * ambiguity, and guessing between them would be worse than the miss:
+ * the caller gets `undefined` and the app keeps the exact-name contract
+ * it already had.
+ */
 declare function getScreenMetadata(name: string): ScreenMetadata | undefined;
 /** Get all registered screens */
 declare function getAllScreens(): ScreenMetadata[];
 /** Clear the screen registry (useful for testing) */
 declare function clearScreenRegistry(): void;
 
-/**
- * Global navigation state — lightweight singleton so any part of the SDK
- * can read the current screen without needing a React context or hook.
- *
- * Updated by AppilotsNavigationContainer and read by useAppilotsChat().
- */
 /**
  * Tell the SDK which screen the user is on.
  *
@@ -199,6 +241,21 @@ interface RuntimeNavigationStateSnapshot {
     routeNames: string[];
     /** Whether React Navigation reports that goBack() can currently run. */
     canGoBack?: boolean;
+    /**
+     * The stack a back press pops through, oldest first, ending on the
+     * current screen. Empty when no navigator is reachable.
+     *
+     * `canGoBack` says a back exists; this says where it goes.
+     */
+    backStack?: string[];
+    /**
+     * Screens the user has been on this session, oldest first, capped and
+     * with consecutive repeats collapsed.
+     *
+     * Different from `backStack`: a popped screen leaves the stack and
+     * stays here, and a tab switch never touches the stack at all.
+     */
+    visited?: string[];
 }
 /**
  * Snapshot the runtime navigation tree in a small, serializable shape.

package/dist/navigation/index.d.ts

@@ -83,6 +83,33 @@ interface ScreenActionMetadata {
      * between sdk and mcp-generator packages.
      */
     appilotsInferred?: AppilotsInferredAction;
+    /**
+     * How long this action's work takes, in milliseconds, as DECLARED by
+     * the app. The SDK waits this long for the UI to settle after pressing
+     * it, instead of the agnostic default.
+     *
+     * There is no constant that fits: an app operation runs from ~100ms to
+     * minutes, and when the wait is too short the agent photographs a
+     * loading screen with no controls on it and plans against nothing. The
+     * app is the only party that knows, so it says so:
+     *
+     * ```tsx
+     * registerScreen({
+     *   name: 'Wizard',
+     *   actions: [{ id: 'gerar', label: 'Gerar', type: 'submit', asyncBudgetMs: 90_000 }],
+     * });
+     * ```
+     *
+     * Omitting it is supported and common: the SDK then falls back on its
+     * defaults (6s, or 10s when the generator inferred the handler is
+     * async) AND on what it can see — while the screen keeps a loading
+     * indicator up, the wait runs on to a safety ceiling. So declaring is
+     * how an app says "this one is QUICK, do not wait on my spinner", or
+     * gives a number for work that shows no indicator at all. The value is
+     * clamped to `MAX_DECLARED_ASYNC_BUDGET_MS`: a declaration is a
+     * request, not a licence to hang the session.
+     */
+    asyncBudgetMs?: number;
 }
 /**
  * Inferred metadata about an action's expected async behavior.
@@ -149,19 +176,34 @@ interface NavigationConfig {
  * ```
  */
 declare function registerScreen(metadata: ScreenMetadata): void;
-/** Get metadata for a specific screen */
+/**
+ * Get metadata for a specific screen.
+ *
+ * Exact name first, then the SAME fold the server applies.
+ *
+ * The asymmetry this closes: the backend routes by
+ * `normalizeRouteIdentity`, so `HomeTab`, `HomeScreen` and `Home` are
+ * one screen to it, while this lookup was a bare `Map.get` and they were
+ * three. An app whose navigator names a tab `HomeTab` and whose
+ * `registerScreen` says `Home` — the ordinary React Navigation shape,
+ * since the tab and the screen inside it cannot share a name — served
+ * the agent a described screen from the map and `undefined` here, so the
+ * title, the description and the declared risk of the screen it was
+ * standing on all went missing. Nothing reported an error; the metadata
+ * was simply absent.
+ *
+ * Folded matching only resolves an UNAMBIGUOUS hit. Two screens that
+ * fold together (`Orders` and `OrdersTab` both registered) are a real
+ * ambiguity, and guessing between them would be worse than the miss:
+ * the caller gets `undefined` and the app keeps the exact-name contract
+ * it already had.
+ */
 declare function getScreenMetadata(name: string): ScreenMetadata | undefined;
 /** Get all registered screens */
 declare function getAllScreens(): ScreenMetadata[];
 /** Clear the screen registry (useful for testing) */
 declare function clearScreenRegistry(): void;
 
-/**
- * Global navigation state — lightweight singleton so any part of the SDK
- * can read the current screen without needing a React context or hook.
- *
- * Updated by AppilotsNavigationContainer and read by useAppilotsChat().
- */
 /**
  * Tell the SDK which screen the user is on.
  *
@@ -199,6 +241,21 @@ interface RuntimeNavigationStateSnapshot {
     routeNames: string[];
     /** Whether React Navigation reports that goBack() can currently run. */
     canGoBack?: boolean;
+    /**
+     * The stack a back press pops through, oldest first, ending on the
+     * current screen. Empty when no navigator is reachable.
+     *
+     * `canGoBack` says a back exists; this says where it goes.
+     */
+    backStack?: string[];
+    /**
+     * Screens the user has been on this session, oldest first, capped and
+     * with consecutive repeats collapsed.
+     *
+     * Different from `backStack`: a popped screen leaves the stack and
+     * stays here, and a tab switch never touches the stack at all.
+     */
+    visited?: string[];
 }
 /**
  * Snapshot the runtime navigation tree in a small, serializable shape.

package/dist/navigation/index.js

@@ -1,51 +1,51 @@
 'use strict';
 
-var chunkDRXUBLGY_js = require('../chunk-DRXUBLGY.js');
-var chunkKZ2BLMS4_js = require('../chunk-KZ2BLMS4.js');
+var chunkALJGKORS_js = require('../chunk-ALJGKORS.js');
+var chunkUZ2D4BVX_js = require('../chunk-UZ2D4BVX.js');
 
 
 
 Object.defineProperty(exports, "AppilotsNavigationContainer", {
   enumerable: true,
-  get: function () { return chunkDRXUBLGY_js.AppilotsNavigationContainer; }
+  get: function () { return chunkALJGKORS_js.AppilotsNavigationContainer; }
 });
 Object.defineProperty(exports, "clearScreenRegistry", {
   enumerable: true,
-  get: function () { return chunkKZ2BLMS4_js.clearScreenRegistry; }
+  get: function () { return chunkUZ2D4BVX_js.clearScreenRegistry; }
 });
 Object.defineProperty(exports, "getActiveRouteNames", {
   enumerable: true,
-  get: function () { return chunkKZ2BLMS4_js.getActiveRouteNames; }
+  get: function () { return chunkUZ2D4BVX_js.getActiveRouteNames; }
 });
 Object.defineProperty(exports, "getAllScreens", {
   enumerable: true,
-  get: function () { return chunkKZ2BLMS4_js.getAllScreens; }
+  get: function () { return chunkUZ2D4BVX_js.getAllScreens; }
 });
 Object.defineProperty(exports, "getCurrentScreen", {
   enumerable: true,
-  get: function () { return chunkKZ2BLMS4_js.getCurrentScreen; }
+  get: function () { return chunkUZ2D4BVX_js.getCurrentScreen; }
 });
 Object.defineProperty(exports, "getNavigationRef", {
   enumerable: true,
-  get: function () { return chunkKZ2BLMS4_js.getNavigationRef; }
+  get: function () { return chunkUZ2D4BVX_js.getNavigationRef; }
 });
 Object.defineProperty(exports, "getNavigationStateSnapshot", {
   enumerable: true,
-  get: function () { return chunkKZ2BLMS4_js.getNavigationStateSnapshot; }
+  get: function () { return chunkUZ2D4BVX_js.getNavigationStateSnapshot; }
 });
 Object.defineProperty(exports, "getScreenMetadata", {
   enumerable: true,
-  get: function () { return chunkKZ2BLMS4_js.getScreenMetadata; }
+  get: function () { return chunkUZ2D4BVX_js.getScreenMetadata; }
 });
 Object.defineProperty(exports, "registerScreen", {
   enumerable: true,
-  get: function () { return chunkKZ2BLMS4_js.registerScreen; }
+  get: function () { return chunkUZ2D4BVX_js.registerScreen; }
 });
 Object.defineProperty(exports, "setCurrentScreen", {
   enumerable: true,
-  get: function () { return chunkKZ2BLMS4_js.setCurrentScreen; }
+  get: function () { return chunkUZ2D4BVX_js.setCurrentScreen; }
 });
 Object.defineProperty(exports, "setNavigationRef", {
   enumerable: true,
-  get: function () { return chunkKZ2BLMS4_js.setNavigationRef; }
+  get: function () { return chunkUZ2D4BVX_js.setNavigationRef; }
 });

package/dist/navigation/index.mjs

@@ -1,2 +1,2 @@
-export { AppilotsNavigationContainer } from '../chunk-LLH7QCSX.mjs';
-export { clearScreenRegistry, getActiveRouteNames, getAllScreens, getCurrentScreen, getNavigationRef, getNavigationStateSnapshot, getScreenMetadata, registerScreen, setCurrentScreen, setNavigationRef } from '../chunk-PQZ64CCE.mjs';
+export { AppilotsNavigationContainer } from '../chunk-L3SY3Q4K.mjs';
+export { clearScreenRegistry, getActiveRouteNames, getAllScreens, getCurrentScreen, getNavigationRef, getNavigationStateSnapshot, getScreenMetadata, registerScreen, setCurrentScreen, setNavigationRef } from '../chunk-HRWBK35Y.mjs';

package/metro.d.ts

@@ -13,17 +13,15 @@
 export interface MetroConfigLike {
   projectRoot?: string;
   resolver?: {
-    resolveRequest?: (
-      context: unknown,
-      moduleName: string,
-      platform: string | null,
-    ) => unknown;
+    resolveRequest?: (context: unknown, moduleName: string, platform: string | null) => unknown;
     [option: string]: unknown;
   };
   [option: string]: unknown;
 }
 
 export interface WithAppilotsOptions {
+  /** CLI output directory containing control-evidence.json. Defaults to .appilots. */
+  outputDir?: string;
   /**
    * Path to the `.appilotsrc` file.
    *

package/metro.js

@@ -65,13 +65,16 @@ function missingConfigError(configPath) {
   );
 }
 
-function createShimSource(configJSON) {
+function createShimSource(configJSON, sessionStorageAvailable) {
   return (
     '// Auto-generated by @appilots/sdk/metro — do not edit\n' +
     'var _g = typeof globalThis !== "undefined" ? globalThis : global;\n' +
     'var _config = ' +
     configJSON +
     ';\n' +
+    (sessionStorageAvailable
+      ? 'try { var _storage = require("@react-native-async-storage/async-storage");\n_config.sessionStorage = _storage.default || _storage; } catch (_storageError) {}\n'
+      : '') +
     '_g.__APPILOTS_RC__ = _config;\n' +
     '\n' +
     '// Call initAppilots immediately so auto-tracking patches React.createElement\n' +
@@ -99,9 +102,9 @@ function createShimSource(configJSON) {
   );
 }
 
-function writeShim(configJSON, shimPath) {
+function writeShim(configJSON, shimPath, sessionStorageAvailable) {
   fs.mkdirSync(path.dirname(shimPath), { recursive: true });
-  fs.writeFileSync(shimPath, createShimSource(configJSON));
+  fs.writeFileSync(shimPath, createShimSource(configJSON, sessionStorageAvailable));
 }
 
 function withAppilots(metroConfig, options = {}) {
@@ -136,12 +139,47 @@ function withAppilots(metroConfig, options = {}) {
     // A malformed .appilotsrc throws from JSON.parse and is NOT downgraded to
     // a warning either: the shim would be stale or absent, and the failure
     // would resurface later as an unresolvable module.
-    writeShim(parseConfigJSON(source), shimPath);
+    // Reuse an existing host dependency; never add a native dependency to the app.
+    let sessionStorageAvailable = false;
+    if (JSON.parse(source).sessionPersistence !== false) {
+      try {
+        require.resolve('@react-native-async-storage/async-storage', { paths: [projectRoot] });
+        sessionStorageAvailable = true;
+      } catch {
+        /* Hosts without storage keep in-memory sessions. */
+      }
+    }
+    writeShim(parseConfigJSON(source), shimPath, sessionStorageAvailable);
     lastConfigSource = source;
   };
 
   ensureShimFresh();
 
+  // The existing Metro integration consumes the CLI's revision-bound evidence.
+  // Client JSX files remain unchanged; chain the original transformer.
+  const upstream = metroConfig.transformer?.babelTransformerPath;
+  let transformerPath;
+  if (upstream) {
+    transformerPath = path.join(shimDir, 'control-transformer.js');
+    const evidencePath = path.resolve(
+      projectRoot,
+      options.outputDir || '.appilots',
+      'control-evidence.json',
+    );
+    fs.writeFileSync(
+      transformerPath,
+      'module.exports = require(' +
+        JSON.stringify(path.join(__dirname, 'control-transformer.js')) +
+        ').createControlTransformer(' +
+        JSON.stringify(upstream) +
+        ',' +
+        JSON.stringify(evidencePath) +
+        ',' +
+        JSON.stringify(projectRoot) +
+        ');\n',
+    );
+  }
+
   // Resolve `@appilots/auto-init` to the shim
   const existingResolveRequest = metroConfig.resolver?.resolveRequest;
 
@@ -160,7 +198,10 @@ function withAppilots(metroConfig, options = {}) {
         return context.resolveRequest(context, moduleName, platform);
       },
     },
-    transformer: withPreservedNames(metroConfig.transformer),
+    transformer: {
+      ...withPreservedNames(metroConfig.transformer),
+      ...(transformerPath ? { babelTransformerPath: transformerPath } : {}),
+    },
   };
 }
 

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@appilots/sdk",
-  "version": "0.11.1",
+  "version": "0.13.0",
   "description": "AI-powered chat component and navigation SDK for React Native apps",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
+      "react-native": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
       "import": {
         "types": "./dist/index.d.mts",
         "default": "./dist/index.mjs"
@@ -17,6 +21,10 @@
       }
     },
     "./navigation": {
+      "react-native": {
+        "types": "./dist/navigation/index.d.ts",
+        "default": "./dist/navigation/index.js"
+      },
       "import": {
         "types": "./dist/navigation/index.d.mts",
         "default": "./dist/navigation/index.mjs"
@@ -27,6 +35,10 @@
       }
     },
     "./hooks": {
+      "react-native": {
+        "types": "./dist/hooks/index.d.ts",
+        "default": "./dist/hooks/index.js"
+      },
       "import": {
         "types": "./dist/hooks/index.d.mts",
         "default": "./dist/hooks/index.mjs"
@@ -44,6 +56,7 @@
   "files": [
     "dist",
     "metro.js",
+    "control-transformer.js",
     "metro.d.ts",
     "navigation",
     "hooks",
@@ -105,16 +118,17 @@
     "@types/react": "^18.3.0",
     "@types/react-native": "^0.73.0",
     "@types/react-test-renderer": "^18.3.0",
+    "@vitest/coverage-v8": "^2.1.0",
     "react": "^18.3.0",
     "react-19": "npm:react@^19.0.0",
     "react-native": "^0.76.0",
+    "react-native-paper": "5.14.5",
     "react-native-safe-area-context": "^5.0.0",
     "react-native-svg": "15.8.0",
     "react-test-renderer": "^18.3.1",
     "react-test-renderer-19": "npm:react-test-renderer@^19.0.0",
     "tsup": "^8.3.0",
     "typescript": "^5.6.0",
-    "@vitest/coverage-v8": "^2.1.0",
     "vitest": "^2.1.0"
   }
 }