@appilots/sdk 0.2.0

package/dist/navigation/index.d.mts

@@ -0,0 +1,43 @@
+export { A as AppilotsNavigationContainer, N as NavigationConfig, S as ScreenActionMetadata, a as ScreenFieldMetadata, b as ScreenMetadata, c as clearScreenRegistry, g as getAllScreens, d as getScreenMetadata, r as registerScreen } from '../registerScreen-D1oGm28T.mjs';
+import 'react';
+
+/**
+ * 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().
+ */
+declare function setCurrentScreen(screen: string): void;
+/**
+ * Get the current screen name. Prefers a LIVE reading from the navigation
+ * ref state (using recursive descent into nested navigators) to ensure
+ * accuracy even if onStateChange missed an update.
+ * Falls back to the cached value set by onStateChange.
+ */
+declare function getCurrentScreen(): string | null;
+declare function setNavigationRef(ref: any): void;
+declare function getNavigationRef(): any;
+declare function getActiveRouteNames(): string[];
+interface RuntimeNavigationStateSnapshot {
+    /** Deepest active route name, same semantic as getCurrentScreen(). */
+    currentRouteName?: string;
+    /** Active route chain from root to deepest route. */
+    activePath: string[];
+    /** Route names accepted by the root navigator, when React Navigation exposes them. */
+    rootRouteNames: string[];
+    /** Route names accepted by the currently active nested navigator. */
+    currentRouteNames: string[];
+    /** Union of route names exposed anywhere in the mounted navigation tree. */
+    routeNames: string[];
+    /** Whether React Navigation reports that goBack() can currently run. */
+    canGoBack?: boolean;
+}
+/**
+ * Snapshot the runtime navigation tree in a small, serializable shape.
+ * This gives the relay route-level facts that the visible UI snapshot
+ * cannot provide: mounted sibling tabs, root routes, current stack
+ * routes, and whether a back action is possible.
+ */
+declare function getNavigationStateSnapshot(): RuntimeNavigationStateSnapshot | null;
+
+export { type RuntimeNavigationStateSnapshot, getActiveRouteNames, getCurrentScreen, getNavigationRef, getNavigationStateSnapshot, setCurrentScreen, setNavigationRef };

package/dist/navigation/index.d.ts

@@ -0,0 +1,43 @@
+export { A as AppilotsNavigationContainer, N as NavigationConfig, S as ScreenActionMetadata, a as ScreenFieldMetadata, b as ScreenMetadata, c as clearScreenRegistry, g as getAllScreens, d as getScreenMetadata, r as registerScreen } from '../registerScreen-D1oGm28T.js';
+import 'react';
+
+/**
+ * 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().
+ */
+declare function setCurrentScreen(screen: string): void;
+/**
+ * Get the current screen name. Prefers a LIVE reading from the navigation
+ * ref state (using recursive descent into nested navigators) to ensure
+ * accuracy even if onStateChange missed an update.
+ * Falls back to the cached value set by onStateChange.
+ */
+declare function getCurrentScreen(): string | null;
+declare function setNavigationRef(ref: any): void;
+declare function getNavigationRef(): any;
+declare function getActiveRouteNames(): string[];
+interface RuntimeNavigationStateSnapshot {
+    /** Deepest active route name, same semantic as getCurrentScreen(). */
+    currentRouteName?: string;
+    /** Active route chain from root to deepest route. */
+    activePath: string[];
+    /** Route names accepted by the root navigator, when React Navigation exposes them. */
+    rootRouteNames: string[];
+    /** Route names accepted by the currently active nested navigator. */
+    currentRouteNames: string[];
+    /** Union of route names exposed anywhere in the mounted navigation tree. */
+    routeNames: string[];
+    /** Whether React Navigation reports that goBack() can currently run. */
+    canGoBack?: boolean;
+}
+/**
+ * Snapshot the runtime navigation tree in a small, serializable shape.
+ * This gives the relay route-level facts that the visible UI snapshot
+ * cannot provide: mounted sibling tabs, root routes, current stack
+ * routes, and whether a back action is possible.
+ */
+declare function getNavigationStateSnapshot(): RuntimeNavigationStateSnapshot | null;
+
+export { type RuntimeNavigationStateSnapshot, getActiveRouteNames, getCurrentScreen, getNavigationRef, getNavigationStateSnapshot, setCurrentScreen, setNavigationRef };

package/dist/navigation/index.js

@@ -0,0 +1,51 @@
+'use strict';
+
+var chunkKGN3DNGX_js = require('../chunk-KGN3DNGX.js');
+var chunkSIBKF7AA_js = require('../chunk-SIBKF7AA.js');
+
+
+
+Object.defineProperty(exports, "AppilotsNavigationContainer", {
+  enumerable: true,
+  get: function () { return chunkKGN3DNGX_js.AppilotsNavigationContainer; }
+});
+Object.defineProperty(exports, "clearScreenRegistry", {
+  enumerable: true,
+  get: function () { return chunkSIBKF7AA_js.clearScreenRegistry; }
+});
+Object.defineProperty(exports, "getActiveRouteNames", {
+  enumerable: true,
+  get: function () { return chunkSIBKF7AA_js.getActiveRouteNames; }
+});
+Object.defineProperty(exports, "getAllScreens", {
+  enumerable: true,
+  get: function () { return chunkSIBKF7AA_js.getAllScreens; }
+});
+Object.defineProperty(exports, "getCurrentScreen", {
+  enumerable: true,
+  get: function () { return chunkSIBKF7AA_js.getCurrentScreen; }
+});
+Object.defineProperty(exports, "getNavigationRef", {
+  enumerable: true,
+  get: function () { return chunkSIBKF7AA_js.getNavigationRef; }
+});
+Object.defineProperty(exports, "getNavigationStateSnapshot", {
+  enumerable: true,
+  get: function () { return chunkSIBKF7AA_js.getNavigationStateSnapshot; }
+});
+Object.defineProperty(exports, "getScreenMetadata", {
+  enumerable: true,
+  get: function () { return chunkSIBKF7AA_js.getScreenMetadata; }
+});
+Object.defineProperty(exports, "registerScreen", {
+  enumerable: true,
+  get: function () { return chunkSIBKF7AA_js.registerScreen; }
+});
+Object.defineProperty(exports, "setCurrentScreen", {
+  enumerable: true,
+  get: function () { return chunkSIBKF7AA_js.setCurrentScreen; }
+});
+Object.defineProperty(exports, "setNavigationRef", {
+  enumerable: true,
+  get: function () { return chunkSIBKF7AA_js.setNavigationRef; }
+});

package/dist/navigation/index.mjs

@@ -0,0 +1,2 @@
+export { AppilotsNavigationContainer } from '../chunk-KCDNL4HV.mjs';
+export { clearScreenRegistry, getActiveRouteNames, getAllScreens, getCurrentScreen, getNavigationRef, getNavigationStateSnapshot, getScreenMetadata, registerScreen, setCurrentScreen, setNavigationRef } from '../chunk-HDLZGXNF.mjs';

package/dist/registerScreen-D1oGm28T.d.mts

@@ -0,0 +1,159 @@
+import React__default from 'react';
+
+interface AppilotsNavigationContainerProps {
+    children: React__default.ReactElement;
+}
+/**
+ * Wraps your NavigationContainer from the outside and automatically
+ * injects `ref` and `onStateChange` to track the current screen.
+ *
+ * ```tsx
+ * import { NavigationContainer } from '@react-navigation/native';
+ * import { AppilotsNavigationContainer } from '@appilots/sdk';
+ *
+ * <AppilotsProvider>
+ *   <AppilotsNavigationContainer>
+ *     <NavigationContainer>
+ *       <Stack.Navigator>...</Stack.Navigator>
+ *     </NavigationContainer>
+ *   </AppilotsNavigationContainer>
+ *   <AppilotsChat />
+ * </AppilotsProvider>
+ * ```
+ */
+declare function AppilotsNavigationContainer({ children }: AppilotsNavigationContainerProps): React__default.ReactElement<any, string | React__default.JSXElementConstructor<any>>;
+
+/**
+ * Navigation-related types for the Appilots SDK.
+ */
+interface ScreenFieldMetadata {
+    /** Field identifier (used by AI model to reference this field) */
+    id: string;
+    /** Human-readable label (must match the UI component's label) */
+    label: string;
+    /** Field type */
+    type: 'text' | 'number' | 'select' | 'toggle' | 'date' | string;
+    /** Whether the field is required */
+    required?: boolean;
+    /** Options for select fields */
+    options?: {
+        label: string;
+        value: string;
+    }[];
+}
+interface ScreenActionMetadata {
+    /** Action identifier (used by AI model to reference this action) */
+    id: string;
+    /** Human-readable label (must match the UI component's label) */
+    label: string;
+    /** Action type */
+    type: 'submit' | 'button' | 'link' | string;
+    /** Target screen for navigation/link actions, when known. */
+    targetScreen?: string;
+    /**
+     * When true, the agent MUST present a confirmation card to the user
+     * before executing this action. Set at registerScreen time for
+     * high-risk or destructive operations.
+     *
+     * The server's permission policy honours this flag when present in
+     * the MCP doc, but a stale MCP can miss it. As defense-in-depth,
+     * the SDK also gates such actions locally: when a `ui_interaction`
+     * targets an action with `requiresConfirmation: true` and there is
+     * NO already-pending confirm action in the queue, the executor
+     * synthesises one and waits for user input before pressing.
+     */
+    requiresConfirmation?: boolean;
+    /**
+     * Structured risk/effect metadata. Prefer these fields over label
+     * heuristics for multilingual apps: the runtime can gate the action
+     * without trying to infer intent from Portuguese/English/etc. text.
+     */
+    effect?: 'read' | 'write' | 'destructive' | string;
+    riskLevel?: 'low' | 'medium' | 'high' | string;
+    destructive?: boolean;
+    /**
+     * Static-analysis hints produced by the MCP generator (Camada B).
+     * Present only when the generator could statically prove the
+     * handler's async shape — otherwise undefined and the SDK falls
+     * back to agnostic runtime signals (ActivityIndicator,
+     * pressed-button-still-disabled, fingerprint quiescence).
+     *
+     * Mirrors `AppilotsInferredAction` from `@appilots/mcp-generator`.
+     * Kept as a structural type here to avoid a runtime dependency
+     * between sdk and mcp-generator packages.
+     */
+    appilotsInferred?: AppilotsInferredAction;
+}
+/**
+ * Inferred metadata about an action's expected async behavior.
+ * See `packages/mcp-generator/docs/INFERRED_ACTION_FIELDS.md` for
+ * the full schema and detection rules.
+ */
+interface AppilotsInferredAction {
+    isAsyncTrigger?: boolean;
+    expectedOutcome?: 'navigation' | 'inline-feedback' | 'data-arrival' | 'mixed' | 'none';
+    loadingStateBindings?: string[];
+}
+interface ScreenMetadata {
+    /** Unique screen identifier */
+    name: string;
+    /** Human-readable title */
+    title?: string;
+    /** Description of what this screen does */
+    description?: string;
+    /** Available actions on this screen (legacy: string[], new: ScreenActionMetadata[]) */
+    actions?: (string | ScreenActionMetadata)[];
+    /** Form fields available on this screen (legacy: string[], new: ScreenFieldMetadata[]) */
+    fields?: ScreenFieldMetadata[];
+    /** Legacy: simple list of form field names */
+    formFields?: string[];
+    /** Tags for categorisation */
+    tags?: string[];
+    /**
+     * Dev-defined prompts to surface as chips when the chat opens on this
+     * screen. Highest priority — these win over screen-action and global
+     * popular prompts. Keep them short and specific to the screen ("Adicionar
+     * cliente" beats "Me ajude").
+     *
+     * @example
+     * registerScreen({
+     *   name: 'Customers',
+     *   suggestedPrompts: ['Adicionar cliente', 'Buscar por nome'],
+     * });
+     */
+    suggestedPrompts?: string[];
+}
+interface NavigationConfig {
+    /** Root navigator name */
+    rootNavigator?: string;
+    /** Map of screen names to metadata */
+    screens?: Record<string, ScreenMetadata>;
+    /** Navigation linking config */
+    linking?: {
+        prefixes?: string[];
+        config?: Record<string, unknown>;
+    };
+}
+
+/**
+ * Register a screen with metadata so the AI agent can understand it.
+ *
+ * @example
+ * ```tsx
+ * registerScreen({
+ *   name: 'ItemList',
+ *   title: 'Items',
+ *   description: 'Lists items available in this app',
+ *   actions: ['viewDetails', 'addItem'],
+ * });
+ * ```
+ */
+declare function registerScreen(metadata: ScreenMetadata): void;
+/** Get metadata for a specific screen */
+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;
+
+export { AppilotsNavigationContainer as A, type NavigationConfig as N, type ScreenActionMetadata as S, type ScreenFieldMetadata as a, type ScreenMetadata as b, clearScreenRegistry as c, getScreenMetadata as d, getAllScreens as g, registerScreen as r };

package/dist/registerScreen-D1oGm28T.d.ts

@@ -0,0 +1,159 @@
+import React__default from 'react';
+
+interface AppilotsNavigationContainerProps {
+    children: React__default.ReactElement;
+}
+/**
+ * Wraps your NavigationContainer from the outside and automatically
+ * injects `ref` and `onStateChange` to track the current screen.
+ *
+ * ```tsx
+ * import { NavigationContainer } from '@react-navigation/native';
+ * import { AppilotsNavigationContainer } from '@appilots/sdk';
+ *
+ * <AppilotsProvider>
+ *   <AppilotsNavigationContainer>
+ *     <NavigationContainer>
+ *       <Stack.Navigator>...</Stack.Navigator>
+ *     </NavigationContainer>
+ *   </AppilotsNavigationContainer>
+ *   <AppilotsChat />
+ * </AppilotsProvider>
+ * ```
+ */
+declare function AppilotsNavigationContainer({ children }: AppilotsNavigationContainerProps): React__default.ReactElement<any, string | React__default.JSXElementConstructor<any>>;
+
+/**
+ * Navigation-related types for the Appilots SDK.
+ */
+interface ScreenFieldMetadata {
+    /** Field identifier (used by AI model to reference this field) */
+    id: string;
+    /** Human-readable label (must match the UI component's label) */
+    label: string;
+    /** Field type */
+    type: 'text' | 'number' | 'select' | 'toggle' | 'date' | string;
+    /** Whether the field is required */
+    required?: boolean;
+    /** Options for select fields */
+    options?: {
+        label: string;
+        value: string;
+    }[];
+}
+interface ScreenActionMetadata {
+    /** Action identifier (used by AI model to reference this action) */
+    id: string;
+    /** Human-readable label (must match the UI component's label) */
+    label: string;
+    /** Action type */
+    type: 'submit' | 'button' | 'link' | string;
+    /** Target screen for navigation/link actions, when known. */
+    targetScreen?: string;
+    /**
+     * When true, the agent MUST present a confirmation card to the user
+     * before executing this action. Set at registerScreen time for
+     * high-risk or destructive operations.
+     *
+     * The server's permission policy honours this flag when present in
+     * the MCP doc, but a stale MCP can miss it. As defense-in-depth,
+     * the SDK also gates such actions locally: when a `ui_interaction`
+     * targets an action with `requiresConfirmation: true` and there is
+     * NO already-pending confirm action in the queue, the executor
+     * synthesises one and waits for user input before pressing.
+     */
+    requiresConfirmation?: boolean;
+    /**
+     * Structured risk/effect metadata. Prefer these fields over label
+     * heuristics for multilingual apps: the runtime can gate the action
+     * without trying to infer intent from Portuguese/English/etc. text.
+     */
+    effect?: 'read' | 'write' | 'destructive' | string;
+    riskLevel?: 'low' | 'medium' | 'high' | string;
+    destructive?: boolean;
+    /**
+     * Static-analysis hints produced by the MCP generator (Camada B).
+     * Present only when the generator could statically prove the
+     * handler's async shape — otherwise undefined and the SDK falls
+     * back to agnostic runtime signals (ActivityIndicator,
+     * pressed-button-still-disabled, fingerprint quiescence).
+     *
+     * Mirrors `AppilotsInferredAction` from `@appilots/mcp-generator`.
+     * Kept as a structural type here to avoid a runtime dependency
+     * between sdk and mcp-generator packages.
+     */
+    appilotsInferred?: AppilotsInferredAction;
+}
+/**
+ * Inferred metadata about an action's expected async behavior.
+ * See `packages/mcp-generator/docs/INFERRED_ACTION_FIELDS.md` for
+ * the full schema and detection rules.
+ */
+interface AppilotsInferredAction {
+    isAsyncTrigger?: boolean;
+    expectedOutcome?: 'navigation' | 'inline-feedback' | 'data-arrival' | 'mixed' | 'none';
+    loadingStateBindings?: string[];
+}
+interface ScreenMetadata {
+    /** Unique screen identifier */
+    name: string;
+    /** Human-readable title */
+    title?: string;
+    /** Description of what this screen does */
+    description?: string;
+    /** Available actions on this screen (legacy: string[], new: ScreenActionMetadata[]) */
+    actions?: (string | ScreenActionMetadata)[];
+    /** Form fields available on this screen (legacy: string[], new: ScreenFieldMetadata[]) */
+    fields?: ScreenFieldMetadata[];
+    /** Legacy: simple list of form field names */
+    formFields?: string[];
+    /** Tags for categorisation */
+    tags?: string[];
+    /**
+     * Dev-defined prompts to surface as chips when the chat opens on this
+     * screen. Highest priority — these win over screen-action and global
+     * popular prompts. Keep them short and specific to the screen ("Adicionar
+     * cliente" beats "Me ajude").
+     *
+     * @example
+     * registerScreen({
+     *   name: 'Customers',
+     *   suggestedPrompts: ['Adicionar cliente', 'Buscar por nome'],
+     * });
+     */
+    suggestedPrompts?: string[];
+}
+interface NavigationConfig {
+    /** Root navigator name */
+    rootNavigator?: string;
+    /** Map of screen names to metadata */
+    screens?: Record<string, ScreenMetadata>;
+    /** Navigation linking config */
+    linking?: {
+        prefixes?: string[];
+        config?: Record<string, unknown>;
+    };
+}
+
+/**
+ * Register a screen with metadata so the AI agent can understand it.
+ *
+ * @example
+ * ```tsx
+ * registerScreen({
+ *   name: 'ItemList',
+ *   title: 'Items',
+ *   description: 'Lists items available in this app',
+ *   actions: ['viewDetails', 'addItem'],
+ * });
+ * ```
+ */
+declare function registerScreen(metadata: ScreenMetadata): void;
+/** Get metadata for a specific screen */
+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;
+
+export { AppilotsNavigationContainer as A, type NavigationConfig as N, type ScreenActionMetadata as S, type ScreenFieldMetadata as a, type ScreenMetadata as b, clearScreenRegistry as c, getScreenMetadata as d, getAllScreens as g, registerScreen as r };

package/metro.js

@@ -0,0 +1,158 @@
+/**
+ * @appilots/sdk — Metro plugin
+ *
+ * Wraps your Metro config so AppilotsProvider auto-loads `.appilotsrc`.
+ *
+ * How it works:
+ * 1. Reads .appilotsrc JSON at Metro startup
+ * 2. Creates a tiny JS module that sets `global.__APPILOTS_RC__`
+ * 3. Registers it via resolver so the SDK can find it
+ * 4. The SDK's AppilotsProvider reads `global.__APPILOTS_RC__` and auto-inits
+ *
+ * The app's index.js just needs to import the setup module before the app:
+ *   require('@appilots/auto-init');
+ *
+ * Or use the `transformerPath` approach for zero-touch setup.
+ *
+ * Usage in metro.config.js:
+ * ```js
+ * const { withAppilots } = require('@appilots/sdk/metro');
+ * module.exports = withAppilots(mergeConfig(defaultConfig, config));
+ * ```
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+function parseConfigJSON(raw) {
+  const parsed = JSON.parse(raw);
+  return JSON.stringify(parsed, null, 2);
+}
+
+function createShimSource(configJSON) {
+  return (
+    '// Auto-generated by @appilots/sdk/metro — do not edit\n' +
+    'var _g = typeof globalThis !== "undefined" ? globalThis : global;\n' +
+    'var _config = ' + configJSON + ';\n' +
+    '_g.__APPILOTS_RC__ = _config;\n' +
+    '\n' +
+    '// Call initAppilots immediately so auto-tracking patches React.createElement\n' +
+    '// BEFORE any app components render.\n' +
+    'var _sdk = require("@appilots/sdk");\n' +
+    'if (_sdk && _sdk.initAppilots) { _sdk.initAppilots(_config); }\n' +
+    '\n' +
+    '// Pass JSX runtime modules to the SDK for auto-tracking.\n' +
+    '// These requires run in the app context (Metro), so they resolve correctly.\n' +
+    '// The SDK cannot require these itself because tsup transforms require() to __require().\n' +
+    'if (_sdk && _sdk.enableAppilotsAutoTracking && _sdk.isAutoTrackingEnabled && _sdk.isAutoTrackingEnabled()) {\n' +
+    '  // Auto-tracking was already enabled by initAppilots, but JSX runtime patches\n' +
+    '  // need the actual runtime modules from the app context.\n' +
+    '  try {\n' +
+    '    var _jsxRuntime = require("react/jsx-runtime");\n' +
+    '    var _jsxDevRuntime = null;\n' +
+    '    try { _jsxDevRuntime = require("react/jsx-dev-runtime"); } catch(e) {}\n' +
+    '    if (_sdk._patchJsxRuntimes) {\n' +
+    '      _sdk._patchJsxRuntimes(_jsxRuntime, _jsxDevRuntime);\n' +
+    '    }\n' +
+    '  } catch(e) {\n' +
+    '    console.warn("[Appilots] Could not patch JSX runtime: " + e.message);\n' +
+    '  }\n' +
+    '}\n'
+  );
+}
+
+function writeShim(configJSON, shimPath) {
+  fs.mkdirSync(path.dirname(shimPath), { recursive: true });
+  fs.writeFileSync(shimPath, createShimSource(configJSON));
+}
+
+function withAppilots(metroConfig, options = {}) {
+  const projectRoot = metroConfig.projectRoot || process.cwd();
+  const configPath = options.configPath || path.resolve(projectRoot, '.appilotsrc');
+
+  if (!fs.existsSync(configPath)) {
+    console.warn('[Appilots] .appilotsrc not found at ' + configPath);
+    return metroConfig;
+  }
+
+  const shimDir = path.resolve(projectRoot, 'node_modules', '.cache', 'appilots');
+  const shimPath = path.resolve(shimDir, 'auto-init.js');
+  let lastConfigSource = null;
+
+  const ensureShimFresh = () => {
+    const source = fs.readFileSync(configPath, 'utf8').trim();
+    if (source === lastConfigSource && fs.existsSync(shimPath)) {
+      return;
+    }
+    writeShim(parseConfigJSON(source), shimPath);
+    lastConfigSource = source;
+  };
+
+  try {
+    ensureShimFresh();
+  } catch (error) {
+    const message = error && error.message ? error.message : String(error);
+    console.warn('[Appilots] failed to generate auto-init shim from ' + configPath + ': ' + message);
+  }
+
+  // Resolve `@appilots/auto-init` to the shim
+  const existingResolveRequest = metroConfig.resolver?.resolveRequest;
+
+  // Metro < 0.79 does not read package.json "exports" by default
+  // (`unstable_enablePackageExports` is off), so deep imports like
+  // `@appilots/shared/match` — which the SDK dist emits since the shared
+  // element matcher landed — fail to resolve in consumer apps. Map
+  // `@appilots/shared/<subpath>` onto the package's built dist layout
+  // explicitly. Kept narrow on purpose: flipping
+  // unstable_enablePackageExports globally would change resolution for
+  // every dependency in the host app.
+  const SHARED_SUBPATH_RE = /^@appilots\/shared\/([A-Za-z0-9_-]+)$/;
+  function resolveSharedSubpath(moduleName) {
+    const match = SHARED_SUBPATH_RE.exec(moduleName);
+    if (!match) return null;
+    try {
+      // require.resolve('@appilots/shared') → <pkg>/dist/index.js; the
+      // package root is two levels up. (package.json itself is not in
+      // the exports map, so it can't be resolved directly.) __dirname
+      // as a fallback path: the SDK always sees shared as a sibling —
+      // node_modules/@appilots/{sdk,shared} in apps, workspace packages
+      // in the monorepo — even when projectRoot has no resolution
+      // chain to it.
+      const mainEntry = require.resolve('@appilots/shared', {
+        paths: [projectRoot, __dirname],
+      });
+      const packageRoot = path.dirname(path.dirname(mainEntry));
+      const candidate = path.join(packageRoot, 'dist', match[1], 'index.js');
+      if (fs.existsSync(candidate)) {
+        return { type: 'sourceFile', filePath: candidate };
+      }
+    } catch (error) {
+      // fall through to the default resolver (its error message names
+      // the module, which is more actionable than ours would be)
+    }
+    return null;
+  }
+
+  return {
+    ...metroConfig,
+    resolver: {
+      ...(metroConfig.resolver || {}),
+      resolveRequest: (context, moduleName, platform) => {
+        if (moduleName === '@appilots/auto-init') {
+          ensureShimFresh();
+          return { type: 'sourceFile', filePath: shimPath };
+        }
+        const shared = resolveSharedSubpath(moduleName);
+        if (shared) return shared;
+        if (existingResolveRequest) {
+          return existingResolveRequest(context, moduleName, platform);
+        }
+        return context.resolveRequest(context, moduleName, platform);
+      },
+    },
+  };
+}
+
+module.exports = { withAppilots };