@appilots/sdk 0.7.0 → 0.10.0

package/dist/navigation/index.d.mts

@@ -1,5 +1,160 @@
-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';
+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;
 
 /**
  * Global navigation state — lightweight singleton so any part of the SDK
@@ -7,6 +162,19 @@ import 'react';
  *
  * Updated by AppilotsNavigationContainer and read by useAppilotsChat().
  */
+/**
+ * Tell the SDK which screen the user is on.
+ *
+ * `AppilotsNavigationContainer` calls this for you on every React
+ * Navigation state change. It is public API for the apps that have no
+ * `NavigationContainer` to wrap — Expo Router and other file-based
+ * routers — where manifest mode declares the screens but nothing tracks
+ * which one is live. Without it `currentScreen` stays null and the agent
+ * does not know where it is, even with a perfect application map.
+ *
+ * The name must match the screen's name in the map, or the agent will
+ * look up metadata for a screen that does not exist.
+ */
 declare function setCurrentScreen(screen: string): void;
 /**
  * Get the current screen name. Prefers a LIVE reading from the navigation
@@ -40,4 +208,4 @@ interface RuntimeNavigationStateSnapshot {
  */
 declare function getNavigationStateSnapshot(): RuntimeNavigationStateSnapshot | null;
 
-export { type RuntimeNavigationStateSnapshot, getActiveRouteNames, getCurrentScreen, getNavigationRef, getNavigationStateSnapshot, setCurrentScreen, setNavigationRef };
+export { AppilotsNavigationContainer, type NavigationConfig, type RuntimeNavigationStateSnapshot, type ScreenActionMetadata, type ScreenFieldMetadata, type ScreenMetadata, clearScreenRegistry, getActiveRouteNames, getAllScreens, getCurrentScreen, getNavigationRef, getNavigationStateSnapshot, getScreenMetadata, registerScreen, setCurrentScreen, setNavigationRef };

package/dist/navigation/index.d.ts

@@ -1,5 +1,160 @@
-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';
+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;
 
 /**
  * Global navigation state — lightweight singleton so any part of the SDK
@@ -7,6 +162,19 @@ import 'react';
  *
  * Updated by AppilotsNavigationContainer and read by useAppilotsChat().
  */
+/**
+ * Tell the SDK which screen the user is on.
+ *
+ * `AppilotsNavigationContainer` calls this for you on every React
+ * Navigation state change. It is public API for the apps that have no
+ * `NavigationContainer` to wrap — Expo Router and other file-based
+ * routers — where manifest mode declares the screens but nothing tracks
+ * which one is live. Without it `currentScreen` stays null and the agent
+ * does not know where it is, even with a perfect application map.
+ *
+ * The name must match the screen's name in the map, or the agent will
+ * look up metadata for a screen that does not exist.
+ */
 declare function setCurrentScreen(screen: string): void;
 /**
  * Get the current screen name. Prefers a LIVE reading from the navigation
@@ -40,4 +208,4 @@ interface RuntimeNavigationStateSnapshot {
  */
 declare function getNavigationStateSnapshot(): RuntimeNavigationStateSnapshot | null;
 
-export { type RuntimeNavigationStateSnapshot, getActiveRouteNames, getCurrentScreen, getNavigationRef, getNavigationStateSnapshot, setCurrentScreen, setNavigationRef };
+export { AppilotsNavigationContainer, type NavigationConfig, type RuntimeNavigationStateSnapshot, type ScreenActionMetadata, type ScreenFieldMetadata, type ScreenMetadata, clearScreenRegistry, getActiveRouteNames, getAllScreens, getCurrentScreen, getNavigationRef, getNavigationStateSnapshot, getScreenMetadata, registerScreen, setCurrentScreen, setNavigationRef };

package/dist/navigation/index.js

@@ -1,51 +1,51 @@
 'use strict';
 
-var chunkKYFAXT6V_js = require('../chunk-KYFAXT6V.js');
-var chunkDZ7QRFHD_js = require('../chunk-DZ7QRFHD.js');
+var chunk2GCWCPSD_js = require('../chunk-2GCWCPSD.js');
+var chunkYB77RYCC_js = require('../chunk-YB77RYCC.js');
 
 
 
 Object.defineProperty(exports, "AppilotsNavigationContainer", {
   enumerable: true,
-  get: function () { return chunkKYFAXT6V_js.AppilotsNavigationContainer; }
+  get: function () { return chunk2GCWCPSD_js.AppilotsNavigationContainer; }
 });
 Object.defineProperty(exports, "clearScreenRegistry", {
   enumerable: true,
-  get: function () { return chunkDZ7QRFHD_js.clearScreenRegistry; }
+  get: function () { return chunkYB77RYCC_js.clearScreenRegistry; }
 });
 Object.defineProperty(exports, "getActiveRouteNames", {
   enumerable: true,
-  get: function () { return chunkDZ7QRFHD_js.getActiveRouteNames; }
+  get: function () { return chunkYB77RYCC_js.getActiveRouteNames; }
 });
 Object.defineProperty(exports, "getAllScreens", {
   enumerable: true,
-  get: function () { return chunkDZ7QRFHD_js.getAllScreens; }
+  get: function () { return chunkYB77RYCC_js.getAllScreens; }
 });
 Object.defineProperty(exports, "getCurrentScreen", {
   enumerable: true,
-  get: function () { return chunkDZ7QRFHD_js.getCurrentScreen; }
+  get: function () { return chunkYB77RYCC_js.getCurrentScreen; }
 });
 Object.defineProperty(exports, "getNavigationRef", {
   enumerable: true,
-  get: function () { return chunkDZ7QRFHD_js.getNavigationRef; }
+  get: function () { return chunkYB77RYCC_js.getNavigationRef; }
 });
 Object.defineProperty(exports, "getNavigationStateSnapshot", {
   enumerable: true,
-  get: function () { return chunkDZ7QRFHD_js.getNavigationStateSnapshot; }
+  get: function () { return chunkYB77RYCC_js.getNavigationStateSnapshot; }
 });
 Object.defineProperty(exports, "getScreenMetadata", {
   enumerable: true,
-  get: function () { return chunkDZ7QRFHD_js.getScreenMetadata; }
+  get: function () { return chunkYB77RYCC_js.getScreenMetadata; }
 });
 Object.defineProperty(exports, "registerScreen", {
   enumerable: true,
-  get: function () { return chunkDZ7QRFHD_js.registerScreen; }
+  get: function () { return chunkYB77RYCC_js.registerScreen; }
 });
 Object.defineProperty(exports, "setCurrentScreen", {
   enumerable: true,
-  get: function () { return chunkDZ7QRFHD_js.setCurrentScreen; }
+  get: function () { return chunkYB77RYCC_js.setCurrentScreen; }
 });
 Object.defineProperty(exports, "setNavigationRef", {
   enumerable: true,
-  get: function () { return chunkDZ7QRFHD_js.setNavigationRef; }
+  get: function () { return chunkYB77RYCC_js.setNavigationRef; }
 });

package/dist/navigation/index.mjs

@@ -1,2 +1,2 @@
-export { AppilotsNavigationContainer } from '../chunk-DR75QTYK.mjs';
-export { clearScreenRegistry, getActiveRouteNames, getAllScreens, getCurrentScreen, getNavigationRef, getNavigationStateSnapshot, getScreenMetadata, registerScreen, setCurrentScreen, setNavigationRef } from '../chunk-R4D34FEW.mjs';
+export { AppilotsNavigationContainer } from '../chunk-IHPLS5FE.mjs';
+export { clearScreenRegistry, getActiveRouteNames, getAllScreens, getCurrentScreen, getNavigationRef, getNavigationStateSnapshot, getScreenMetadata, registerScreen, setCurrentScreen, setNavigationRef } from '../chunk-AHHDOUVX.mjs';

package/metro.d.ts

@@ -30,12 +30,27 @@ export interface WithAppilotsOptions {
    * @default `<projectRoot>/.appilotsrc`
    */
   configPath?: string;
+
+  /**
+   * Treat a missing `.appilotsrc` as "no auto-init wanted" and return the
+   * Metro config untouched, instead of throwing.
+   *
+   * Only set this if you also drop `import '@appilots/auto-init'` from your
+   * entry file and pass the config to `<AppilotsProvider config={…}>`
+   * yourself — otherwise the import has nothing to resolve to and Metro
+   * fails later with a message that does not mention `.appilotsrc` at all.
+   *
+   * A malformed `.appilotsrc` always throws, `optional` or not.
+   *
+   * @default false
+   */
+  optional?: boolean;
 }
 
 /**
  * Wraps a Metro config so `AppilotsProvider` auto-loads `.appilotsrc`.
  *
- * Returns the config unchanged (with a warning) when no `.appilotsrc` is found.
+ * Throws when no `.appilotsrc` is found, unless `options.optional` is set.
  *
  * @example
  * ```js

package/metro.js

@@ -31,11 +31,47 @@ function parseConfigJSON(raw) {
   return JSON.stringify(parsed, null, 2);
 }
 
+/**
+ * The error for "there is no .appilotsrc".
+ *
+ * This used to be a `console.warn` followed by `return metroConfig`, which
+ * made the plugin a no-op — and then the `import '@appilots/auto-init'` line
+ * in the app's index.js had nothing to resolve to. What the developer saw was
+ * a Metro resolution failure (or, once the shim had been written and the file
+ * later removed, a bare `ENOENT: no such file or directory, open
+ * '…/.appilotsrc'` red screen) with no mention of the missing config or of
+ * how to create it. A warning that is only visible in Metro's scrollback,
+ * seconds before an unrelated-looking error, is not a warning.
+ *
+ * Failing here instead stops the build at the actual cause and names the fix.
+ */
+function missingConfigError(configPath) {
+  return new Error(
+    '[Appilots] .appilotsrc not found at ' +
+      configPath +
+      '\n' +
+      '\n' +
+      'withAppilots() reads it to generate the module that\n' +
+      '  import "@appilots/auto-init";\n' +
+      'resolves to, so the bundle cannot be built without it.\n' +
+      '\n' +
+      'Fix, whichever fits:\n' +
+      '  • cp .appilotsrc.example .appilotsrc   (if your project ships one)\n' +
+      '  • npx @appilots/cli init               (creates one for this project)\n' +
+      '  • withAppilots(config, { optional: true })\n' +
+      '        to make the file optional. Then also drop the\n' +
+      '        `import "@appilots/auto-init"` line and pass the config\n' +
+      '        yourself: <AppilotsProvider config={{ projectId, apiKey }}>.',
+  );
+}
+
 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' +
+    'var _config = ' +
+    configJSON +
+    ';\n' +
     '_g.__APPILOTS_RC__ = _config;\n' +
     '\n' +
     '// Call initAppilots immediately so auto-tracking patches React.createElement\n' +
@@ -73,8 +109,8 @@ function withAppilots(metroConfig, options = {}) {
   const configPath = options.configPath || path.resolve(projectRoot, '.appilotsrc');
 
   if (!fs.existsSync(configPath)) {
-    console.warn('[Appilots] .appilotsrc not found at ' + configPath);
-    return metroConfig;
+    if (options.optional) return metroConfig;
+    throw missingConfigError(configPath);
   }
 
   const shimDir = path.resolve(projectRoot, 'node_modules', '.cache', 'appilots');
@@ -82,20 +118,29 @@ function withAppilots(metroConfig, options = {}) {
   let lastConfigSource = null;
 
   const ensureShimFresh = () => {
-    const source = fs.readFileSync(configPath, 'utf8').trim();
+    let source;
+    try {
+      source = fs.readFileSync(configPath, 'utf8').trim();
+    } catch (error) {
+      // Reached when the file existed at config load and is gone by the time
+      // Metro resolves the import — deleted, renamed, or a checkout switched
+      // underneath a running bundler. Raw, this is the `ENOENT … open
+      // '.appilotsrc'` red screen; the point of catching it is that the
+      // message names the file's role and how to restore it.
+      if (error && error.code === 'ENOENT') throw missingConfigError(configPath);
+      throw error;
+    }
     if (source === lastConfigSource && fs.existsSync(shimPath)) {
       return;
     }
+    // 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);
     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);
-  }
+  ensureShimFresh();
 
   // Resolve `@appilots/auto-init` to the shim
   const existingResolveRequest = metroConfig.resolver?.resolveRequest;
@@ -115,6 +160,55 @@ function withAppilots(metroConfig, options = {}) {
         return context.resolveRequest(context, moduleName, platform);
       },
     },
+    transformer: withPreservedNames(metroConfig.transformer),
+  };
+}
+
+/**
+ * Keep function and class names through minification (#386).
+ *
+ * The introspection matches several React Native components by name,
+ * and the ones with no `displayName` — `Switch`, `Modal`, `FlatList`,
+ * `SectionList`, `VirtualizedList` — fall through to the function or
+ * class name, which is exactly what a minifier rewrites. Bundling
+ * `apps/example-app` with `--minify true` (Metro 0.81.5 / RN 0.76.9)
+ * drops every one of those names to zero occurrences.
+ *
+ * Metro's default minifier config sets neither flag
+ * (`metro-config/src/defaults/index.js`), and its `toplevel: false`
+ * does not help: Metro wraps each module in `__d(function (…) {`, so
+ * these are local names, not top-level ones.
+ *
+ * This is a SAFETY NET, not the fix. The React Native CLI's release
+ * build does not minify at all when Hermes is on (the default since
+ * 0.70), and `withAppilots()` cannot reach an app that builds its Metro
+ * config by hand or uses Re.Pack. The detection itself is what must
+ * survive without names, which is why the walker falls back to
+ * accessibility roles, the native modal host, and the list props
+ * signature.
+ *
+ * The app's own `minifierConfig` wins on every key it sets, including
+ * these two — a project that deliberately mangles names keeps doing so.
+ */
+function withPreservedNames(transformer) {
+  const existing = transformer || {};
+  const minifierConfig = existing.minifierConfig || {};
+  const mangle = minifierConfig.mangle;
+  return {
+    ...existing,
+    minifierConfig: {
+      keep_fnames: true,
+      keep_classnames: true,
+      ...minifierConfig,
+      // Terser reads `keep_fnames` inside `mangle` as well as at the
+      // top level, and the nested one is what actually governs
+      // renaming. Only added when the app already configures `mangle`
+      // as an object — `mangle: false` means "do not mangle at all",
+      // and turning that into an object would switch mangling ON.
+      ...(mangle && typeof mangle === 'object'
+        ? { mangle: { keep_fnames: true, keep_classnames: true, ...mangle } }
+        : {}),
+    },
   };
 }