@appilots/cli 0.4.0 → 0.10.0

package/dist/index.js

@@ -83,6 +83,45 @@ function hasJsxAttribute(element, name) {
 }
 
 // src/ast/jsx/classify.ts
+var NON_INTERACTION_HANDLERS = /* @__PURE__ */ new Set([
+  "onLayout",
+  "onScroll",
+  "onScrollBeginDrag",
+  "onScrollEndDrag",
+  "onMomentumScrollBegin",
+  "onMomentumScrollEnd",
+  "onContentSizeChange",
+  "onEndReached",
+  "onViewableItemsChanged",
+  "onLoad",
+  "onLoadStart",
+  "onLoadEnd",
+  "onError",
+  "onProgress",
+  "onFocus",
+  "onBlur"
+]);
+var VALUE_HANDLERS = /* @__PURE__ */ new Set([
+  "onChange",
+  "onChangeText",
+  "onValueChange",
+  "onSelect",
+  "onSelectionChange",
+  "onSubmitEditing"
+]);
+function pressHandlerProp(element) {
+  let fallback;
+  for (const attr of element.attributes) {
+    if (attr.type !== "JSXAttribute" || attr.name.type !== "JSXIdentifier") continue;
+    const name = attr.name.name;
+    if (!/^on[A-Z]/.test(name)) continue;
+    if (attr.value?.type !== "JSXExpressionContainer") continue;
+    if (name === "onPress") return name;
+    if (NON_INTERACTION_HANDLERS.has(name) || VALUE_HANDLERS.has(name)) continue;
+    fallback ??= name;
+  }
+  return fallback;
+}
 var VIEW_COMPONENTS = /* @__PURE__ */ new Set(["View", "ScrollView", "SafeAreaView", "KeyboardAvoidingView"]);
 var INPUT_COMPONENTS = /* @__PURE__ */ new Set(["TextInput", "Input", "HocInput"]);
 var BUTTON_COMPONENTS = /* @__PURE__ */ new Set(["TouchableOpacity", "Pressable", "Button"]);
@@ -97,17 +136,16 @@ function classifyJsxComponent(name, element) {
   if (INPUT_COMPONENTS.has(name)) return "input";
   if (BUTTON_COMPONENTS.has(name)) return "button";
   if (element) {
-    const hasOptions = hasJsxAttribute(element, "options");
+    const hasOptions = hasJsxAttribute(element, "options") || hasJsxAttribute(element, "segments") || hasJsxAttribute(element, "choices") || hasJsxAttribute(element, "tabs");
     const hasValue = hasJsxAttribute(element, "value");
     const hasChecked = hasJsxAttribute(element, "checked") || hasJsxAttribute(element, "selected");
     const hasOnChange = hasJsxAttribute(element, "onChange") || hasJsxAttribute(element, "onValueChange") || hasJsxAttribute(element, "onChangeText");
-    const hasOnPress = hasJsxAttribute(element, "onPress");
     if (hasOptions && (hasValue || hasOnChange)) return "select";
     if (hasChecked && hasOnChange) return "toggle";
     if (hasOnChange && (hasJsxAttribute(element, "label") || hasJsxAttribute(element, "placeholder"))) {
       return "input";
     }
-    if (hasOnPress) return "button";
+    if (pressHandlerProp(element)) return "button";
     if (getStringAttr(element, "visible") || getExpressionIdentifierAttr(element, "visible")) {
       return "modal";
     }
@@ -445,12 +483,17 @@ var ScreenAnalyzer = class {
         }
       } catch (error) {
         if (this.verbose) {
-          console.warn(`[ScreenAnalyzer] Failed to parse ${file}:`, error instanceof Error ? error.message : error);
+          console.warn(
+            `[ScreenAnalyzer] Failed to parse ${file}:`,
+            error instanceof Error ? error.message : error
+          );
         }
       }
     }
     if (this.verbose && this.strictScreens) {
-      console.log(`[ScreenAnalyzer] Strict mode: ${screens.length} included, ${this.screensFilteredOut} filtered out`);
+      console.log(
+        `[ScreenAnalyzer] Strict mode: ${screens.length} included, ${this.screensFilteredOut} filtered out`
+      );
     }
     return screens;
   }
@@ -738,7 +781,11 @@ var ScreenAnalyzer = class {
     for (const form of secondary) {
       const existing = out.find((candidate) => candidate.id === form.id) ?? this.findFormWithSharedFields(out, form);
       if (!existing) {
-        out.push({ ...form, fields: [...form.fields], submitAction: this.namedSubmitAction(form.submitAction) });
+        out.push({
+          ...form,
+          fields: [...form.fields],
+          submitAction: this.namedSubmitAction(form.submitAction)
+        });
         continue;
       }
       for (const field of form.fields) {
@@ -757,9 +804,12 @@ var ScreenAnalyzer = class {
   findEquivalentField(fields, incoming) {
     return fields.find((field) => {
       if (field.name && incoming.name && field.name === incoming.name) return true;
-      if (field.valueBinding && incoming.valueBinding && field.valueBinding === incoming.valueBinding) return true;
-      if (field.locator?.id && incoming.locator?.id && field.locator.id === incoming.locator.id) return true;
-      if (field.placeholder && incoming.placeholder && field.placeholder === incoming.placeholder) return true;
+      if (field.valueBinding && incoming.valueBinding && field.valueBinding === incoming.valueBinding)
+        return true;
+      if (field.locator?.id && incoming.locator?.id && field.locator.id === incoming.locator.id)
+        return true;
+      if (field.placeholder && incoming.placeholder && field.placeholder === incoming.placeholder)
+        return true;
       if (field.locator?.accessibilityLabel && incoming.locator?.accessibilityLabel && field.locator.accessibilityLabel === incoming.locator.accessibilityLabel) {
         return true;
       }
@@ -919,9 +969,11 @@ var ScreenAnalyzer = class {
               source: field.locator?.source ?? "accessibilityLabel"
             });
           } else if (attrName === "keyboardType") {
-            if (attr.value.value === "email-address" || attr.value.value === "email") field.type = "email";
+            if (attr.value.value === "email-address" || attr.value.value === "email")
+              field.type = "email";
             if (attr.value.value === "phone-pad") field.type = "phone";
-            if (attr.value.value === "numeric" || attr.value.value === "number-pad") field.type = "number";
+            if (attr.value.value === "numeric" || attr.value.value === "number-pad")
+              field.type = "number";
           }
         } else if (BabelTypes__namespace.isJSXExpressionContainer(attr.value)) {
           if (attrName === "value" && BabelTypes__namespace.isIdentifier(attr.value.expression)) {
@@ -1087,8 +1139,10 @@ var ScreenAnalyzer = class {
       };
       if (handler.nativeConfirmationExpected) action.nativeConfirmationExpected = true;
       if (handler.targetScreen && !action.targetScreen) action.targetScreen = handler.targetScreen;
-      if (handler.successSignal && !action.successSignal) action.successSignal = handler.successSignal;
-      if (handler.failureSignal && !action.failureSignal) action.failureSignal = handler.failureSignal;
+      if (handler.successSignal && !action.successSignal)
+        action.successSignal = handler.successSignal;
+      if (handler.failureSignal && !action.failureSignal)
+        action.failureSignal = handler.failureSignal;
       if (handler.opensModal && !action.opensModal) action.opensModal = handler.opensModal;
       if (handler.destructive || action.destructive === true || action.requiresConfirmation === true || action.effect === "destructive" || action.riskLevel === "high") {
         action.destructive = true;
@@ -1106,6 +1160,7 @@ var ScreenAnalyzer = class {
         if (!BabelTypes__namespace.isJSXIdentifier(element.name)) return;
         const componentName = element.name.name;
         if (classifyJsxComponent(componentName, element) !== "button") return;
+        const pressProp = pressHandlerProp(element);
         let label;
         let handler;
         for (const attr of element.attributes) {
@@ -1115,7 +1170,7 @@ var ScreenAnalyzer = class {
           if ((attrName === "title" || attrName === "accessibilityLabel" || attrName === "label") && BabelTypes__namespace.isStringLiteral(attr.value)) {
             label = attr.value.value;
           }
-          if (attrName === "onPress" && BabelTypes__namespace.isJSXExpressionContainer(attr.value) && BabelTypes__namespace.isIdentifier(attr.value.expression)) {
+          if (attrName === pressProp && BabelTypes__namespace.isJSXExpressionContainer(attr.value) && BabelTypes__namespace.isIdentifier(attr.value.expression)) {
             handler = attr.value.expression.name;
           }
         }
@@ -1181,10 +1236,13 @@ var ScreenAnalyzer = class {
       }
     };
     if (fn.body) {
-      traverse4__default.default(fn.body, {
-        noScope: true,
-        enter: (nodePath) => inspectNode(nodePath.node)
-      });
+      traverse4__default.default(
+        fn.body,
+        {
+          noScope: true,
+          enter: (nodePath) => inspectNode(nodePath.node)
+        }
+      );
     }
     const expectedOutcome = targetScreen ? "navigation" : hasStateSetter ? "inline-feedback" : hasAwait || hasThen ? "mixed" : "none";
     return {
@@ -1242,6 +1300,7 @@ var ScreenAnalyzer = class {
     };
     const componentName = BabelTypes__namespace.isJSXIdentifier(element.name) ? element.name.name : void 0;
     action.sourceComponent = componentName;
+    const pressProp = pressHandlerProp(element) ?? "onPress";
     let handlerName;
     for (const attr of element.attributes) {
       if (!BabelTypes__namespace.isJSXAttribute(attr)) continue;
@@ -1276,7 +1335,7 @@ var ScreenAnalyzer = class {
             }
           }
         } else if (BabelTypes__namespace.isJSXExpressionContainer(attr.value)) {
-          if (attrName === "onPress" && BabelTypes__namespace.isIdentifier(attr.value.expression)) {
+          if (attrName === pressProp && BabelTypes__namespace.isIdentifier(attr.value.expression)) {
             handlerName = attr.value.expression.name.toLowerCase();
             action.handler = attr.value.expression.name;
             if (handlerName.includes("submit")) {
@@ -1284,7 +1343,7 @@ var ScreenAnalyzer = class {
             } else if (handlerName.includes("navigate")) {
               action.type = "navigation";
             }
-          } else if (attrName === "onPress") {
+          } else if (attrName === pressProp) {
             const inline = this.extractInlineOnPressMetadata(attr.value.expression);
             if (inline.handler) {
               handlerName = inline.handler.toLowerCase();
@@ -1308,7 +1367,11 @@ var ScreenAnalyzer = class {
       }
     }
     if (!action.locator && action.id) {
-      action.locator = { id: action.id, label: action.label, source: action.label ? "label" : "inferred" };
+      action.locator = {
+        id: action.id,
+        label: action.label,
+        source: action.label ? "label" : "inferred"
+      };
     }
     if (this.isElementDestructive(element, handlerName, action.id)) {
       action.destructive = true;
@@ -1450,24 +1513,27 @@ var ScreenAnalyzer = class {
   }
   extractRowAction(fn) {
     let action;
-    traverse4__default.default(fn.body, {
-      noScope: true,
-      CallExpression: (nodePath) => {
-        const node = nodePath.node;
-        if (!BabelTypes__namespace.isMemberExpression(node.callee) || !BabelTypes__namespace.isIdentifier(node.callee.object) || node.callee.object.name !== "navigation" || !BabelTypes__namespace.isIdentifier(node.callee.property) || !["navigate", "push", "replace"].includes(node.callee.property.name)) {
-          return;
+    traverse4__default.default(
+      fn.body,
+      {
+        noScope: true,
+        CallExpression: (nodePath) => {
+          const node = nodePath.node;
+          if (!BabelTypes__namespace.isMemberExpression(node.callee) || !BabelTypes__namespace.isIdentifier(node.callee.object) || node.callee.object.name !== "navigation" || !BabelTypes__namespace.isIdentifier(node.callee.property) || !["navigate", "push", "replace"].includes(node.callee.property.name)) {
+            return;
+          }
+          const firstArg = node.arguments[0];
+          if (!BabelTypes__namespace.isStringLiteral(firstArg)) return;
+          const params = this.extractNavigationParams(node.arguments[1]);
+          action = {
+            type: "navigation",
+            targetScreen: firstArg.value,
+            ...Object.keys(params).length > 0 ? { params } : {},
+            description: `Pressing a row opens ${firstArg.value}`
+          };
         }
-        const firstArg = node.arguments[0];
-        if (!BabelTypes__namespace.isStringLiteral(firstArg)) return;
-        const params = this.extractNavigationParams(node.arguments[1]);
-        action = {
-          type: "navigation",
-          targetScreen: firstArg.value,
-          ...Object.keys(params).length > 0 ? { params } : {},
-          description: `Pressing a row opens ${firstArg.value}`
-        };
       }
-    });
+    );
     return action;
   }
   extractNavigationParams(arg) {
@@ -1500,15 +1566,18 @@ var ScreenAnalyzer = class {
     } else if (BabelTypes__namespace.isIdentifier(firstParam)) {
       itemNames.add(firstParam.name);
     }
-    traverse4__default.default(fn.body, {
-      noScope: true,
-      MemberExpression: (nodePath) => {
-        const node = nodePath.node;
-        if (BabelTypes__namespace.isIdentifier(node.object) && itemNames.has(node.object.name) && BabelTypes__namespace.isIdentifier(node.property)) {
-          fields.add(node.property.name);
+    traverse4__default.default(
+      fn.body,
+      {
+        noScope: true,
+        MemberExpression: (nodePath) => {
+          const node = nodePath.node;
+          if (BabelTypes__namespace.isIdentifier(node.object) && itemNames.has(node.object.name) && BabelTypes__namespace.isIdentifier(node.property)) {
+            fields.add(node.property.name);
+          }
         }
       }
-    });
+    );
     return Array.from(fields).sort();
   }
   inferItemType(dataSource, renderItem, displayFields) {
@@ -1520,11 +1589,19 @@ var ScreenAnalyzer = class {
     if (displayFields.length > 0) return "Item";
     return void 0;
   }
+  /**
+   * Identity comes from how a field is NAMED, not from what the app
+   * sells: `id`/`uuid`/`key`/`slug` are conventions any codebase uses,
+   * `name`/`title`/`email` are how any row introduces itself. `plate`
+   * used to sit in this list and read like one of them — but it is the
+   * example app's schema, and no other tenant ever got its equivalent
+   * (`mrn`, `trackingNumber`, `sku`) added here.
+   */
   inferIdentityFields(keyField, displayFields) {
     const out = /* @__PURE__ */ new Set();
     if (keyField) out.add(keyField);
     for (const field of displayFields) {
-      if (/^(id|uuid|key|name|title|plate|email|slug)$/i.test(field)) out.add(field);
+      if (/^(id|uuid|key|name|title|email|slug)$/i.test(field)) out.add(field);
     }
     return Array.from(out);
   }
@@ -1535,17 +1612,23 @@ var ScreenAnalyzer = class {
       CallExpression: (nodePath) => {
         const node = nodePath.node;
         if (!BabelTypes__namespace.isMemberExpression(node.callee)) return;
-        if (!BabelTypes__namespace.isIdentifier(node.callee.property) || node.callee.property.name !== "filter") return;
-        if (!BabelTypes__namespace.isIdentifier(node.callee.object) || node.callee.object.name !== dataSource) return;
+        if (!BabelTypes__namespace.isIdentifier(node.callee.property) || node.callee.property.name !== "filter")
+          return;
+        if (!BabelTypes__namespace.isIdentifier(node.callee.object) || node.callee.object.name !== dataSource)
+          return;
         const fn = node.arguments[0];
-        if (!BabelTypes__namespace.isArrowFunctionExpression(fn) && !BabelTypes__namespace.isFunctionExpression(fn)) return;
-        traverse4__default.default(fn.body, {
-          noScope: true,
-          Identifier: (innerPath) => {
-            const name = innerPath.node.name;
-            if (/query|search|filter/i.test(name)) queryBinding = queryBinding ?? name;
+        if (!BabelTypes__namespace.isArrowFunctionExpression(fn) && !BabelTypes__namespace.isFunctionExpression(fn))
+          return;
+        traverse4__default.default(
+          fn.body,
+          {
+            noScope: true,
+            Identifier: (innerPath) => {
+              const name = innerPath.node.name;
+              if (/query|search|filter/i.test(name)) queryBinding = queryBinding ?? name;
+            }
           }
-        });
+        );
       }
     });
     return queryBinding;
@@ -1689,11 +1772,7 @@ var NavigationAnalyzer = class {
                 if (BabelTypes__namespace.isJSXAttribute(initialRouteAttr) && BabelTypes__namespace.isStringLiteral(initialRouteAttr.value)) {
                   navigator.initialRouteName = initialRouteAttr.value.value;
                 }
-                const screens = this.extractScreensFromNavigator(
-                  node,
-                  objectName,
-                  navigator.type
-                );
+                const screens = this.extractScreensFromNavigator(node, objectName, navigator.type);
                 screensByNavigator.set(objectName, screens);
               }
             }
@@ -1710,27 +1789,112 @@ var NavigationAnalyzer = class {
     }
     return navigators;
   }
+  /**
+   * Is this JSX element `<navigatorVarName.MEMBER …>`?
+   */
+  // Deliberately NOT a type predicate (`node is t.JSXElement`): a false
+  // result would then narrow `node` to "not a JSXElement", and the very
+  // next check — the same node against a different member — would see
+  // `never`. It is a question about the member name, not about the node
+  // kind.
+  isNavigatorMember(node, navigatorVarName, member) {
+    if (!BabelTypes__namespace.isJSXElement(node)) return false;
+    const name = node.openingElement.name;
+    return BabelTypes__namespace.isJSXMemberExpression(name) && BabelTypes__namespace.isJSXIdentifier(name.object) && name.object.name === navigatorVarName && BabelTypes__namespace.isJSXIdentifier(name.property) && name.property.name === member;
+  }
+  /**
+   * Flatten a navigator's JSX children into the `<X.Screen>` elements they
+   * contain, unwrapping every container a real app puts in between.
+   *
+   * The old version compared `t.isJSXElement(child)` against the direct
+   * children only. A ternary is a `JSXExpressionContainer`, so an
+   * auth-gated root — the modal shape of a commercial app, and the shape
+   * of this repo's own `apps/example-app` — contributed ZERO screens to
+   * the graph while `appilots sync` reported success (#396).
+   *
+   * Both branches of a conditional are collected on purpose. The graph is
+   * a design-time map of what routes EXIST, not a prediction of which one
+   * a given session will render; the agent needs the destination name to
+   * be there whether or not the user happens to be logged in right now.
+   */
+  collectScreenElements(children, navigatorVarName, depth = 0) {
+    if (depth > 12) return [];
+    const found = [];
+    const visit = (node) => {
+      if (!node) return;
+      if (this.isNavigatorMember(node, navigatorVarName, "Screen")) {
+        found.push(node);
+        return;
+      }
+      if (this.isNavigatorMember(node, navigatorVarName, "Group")) {
+        const group = node;
+        found.push(...this.collectScreenElements(group.children, navigatorVarName, depth + 1));
+        return;
+      }
+      if (BabelTypes__namespace.isJSXElement(node)) {
+        const name = node.openingElement.name;
+        const isForeignNavigator = BabelTypes__namespace.isJSXMemberExpression(name) && BabelTypes__namespace.isJSXIdentifier(name.property) && name.property.name === "Navigator";
+        if (isForeignNavigator) return;
+        found.push(...this.collectScreenElements(node.children, navigatorVarName, depth + 1));
+        return;
+      }
+      if (BabelTypes__namespace.isJSXFragment(node)) {
+        found.push(...this.collectScreenElements(node.children, navigatorVarName, depth + 1));
+        return;
+      }
+      if (BabelTypes__namespace.isJSXExpressionContainer(node)) {
+        visit(node.expression);
+        return;
+      }
+      if (BabelTypes__namespace.isConditionalExpression(node)) {
+        visit(node.consequent);
+        visit(node.alternate);
+        return;
+      }
+      if (BabelTypes__namespace.isLogicalExpression(node)) {
+        visit(node.left);
+        visit(node.right);
+        return;
+      }
+      if (BabelTypes__namespace.isCallExpression(node)) {
+        for (const arg of node.arguments) {
+          if (BabelTypes__namespace.isArrowFunctionExpression(arg) || BabelTypes__namespace.isFunctionExpression(arg)) {
+            if (BabelTypes__namespace.isBlockStatement(arg.body)) {
+              for (const stmt of arg.body.body) {
+                if (BabelTypes__namespace.isReturnStatement(stmt)) visit(stmt.argument);
+              }
+            } else {
+              visit(arg.body);
+            }
+          }
+        }
+        return;
+      }
+      if (BabelTypes__namespace.isArrayExpression(node)) {
+        for (const el of node.elements) visit(el);
+        return;
+      }
+      if (BabelTypes__namespace.isTSAsExpression(node) || BabelTypes__namespace.isTSNonNullExpression(node)) {
+        visit(node.expression);
+      }
+    };
+    for (const child of children) visit(child);
+    return found;
+  }
   /** Extract screens from a navigator JSX element */
   extractScreensFromNavigator(navigatorElement, navigatorVarName, navigatorType) {
     const screens = [];
     if (!navigatorElement.children) return screens;
-    for (const child of navigatorElement.children) {
-      if (BabelTypes__namespace.isJSXElement(child) && BabelTypes__namespace.isJSXMemberExpression(child.openingElement.name)) {
-        const memberExpr = child.openingElement.name;
-        if (BabelTypes__namespace.isJSXIdentifier(memberExpr.object) && memberExpr.object.name === navigatorVarName && BabelTypes__namespace.isJSXIdentifier(memberExpr.property) && memberExpr.property.name === "Screen") {
-          const screenName = this.extractAttributeValue(
-            child.openingElement.attributes,
-            "name"
-          );
-          if (screenName) {
-            screens.push({
-              name: screenName,
-              navigatorName: navigatorVarName,
-              navigatorType
-            });
-          }
-        }
-      }
+    const seen = /* @__PURE__ */ new Set();
+    for (const element of this.collectScreenElements(navigatorElement.children, navigatorVarName)) {
+      const screenName = this.extractAttributeValue(element.openingElement.attributes, "name");
+      if (!screenName || seen.has(screenName)) continue;
+      seen.add(screenName);
+      screens.push({
+        name: screenName,
+        navigatorName: navigatorVarName,
+        navigatorType
+      });
     }
     return screens;
   }
@@ -1789,9 +1953,7 @@ var NavigationAnalyzer = class {
       if (member.type === "TSPropertySignature" && member.key) {
         const keyName = member.key.type === "Identifier" ? member.key.name : null;
         if (keyName && member.typeAnnotation) {
-          const params = this.extractParamsFromType(
-            member.typeAnnotation.typeAnnotation
-          );
+          const params = this.extractParamsFromType(member.typeAnnotation.typeAnnotation);
           entries.set(keyName, params);
         }
       }
@@ -1870,6 +2032,11 @@ var NavigationAnalyzer = class {
     let initialScreen = "";
     for (const navigator of parsedNavigators) {
       const screenNames = navigator.screens.map((s) => s.name);
+      if (screenNames.length === 0) {
+        console.warn(
+          `[MCPGenerator] navigator "${navigator.name}" (${navigator.type}) declared no reachable screens. Its routes will be missing from the app map, so the agent will have no destination name for them. If the screens are there in the source, this is a parser gap \u2014 please report it with the file.`
+        );
+      }
       navigators.push({
         name: navigator.name,
         type: navigator.type,
@@ -2657,7 +2824,9 @@ var WebScreenAnalyzer = class {
       include = ["**/*.tsx", "**/*.ts", "**/*.jsx", "**/*.js"],
       exclude = ["**/node_modules/**", "**/dist/**", "**/build/**"]
     } = this.config;
-    const files = await glob__default.default(include, { cwd: this.config.rootDir, ignore: exclude });
+    const files = (await glob__default.default(include, { cwd: this.config.rootDir, ignore: exclude })).filter(
+      (file) => !file.endsWith(".d.ts")
+    );
     const patternMatches = await glob__default.default(this.screenPatterns, {
       cwd: this.config.rootDir,
       ignore: exclude
@@ -3028,7 +3197,8 @@ var WebScreenAnalyzer = class {
     if (type === "email") return "email";
     if (type === "tel") return "phone";
     if (type === "number") return "number";
-    if (type === "date" || type === "datetime-local" || type === "month" || type === "week") return "date";
+    if (type === "date" || type === "datetime-local" || type === "month" || type === "week")
+      return "date";
     const inputMode = getStringAttr(opening, "inputMode") ?? getStringAttr(opening, "inputmode");
     if (inputMode === "email") return "email";
     if (inputMode === "tel") return "phone";
@@ -3342,7 +3512,9 @@ var WebScreenAnalyzer = class {
         }
         const callback = expr.arguments[0];
         if (!BabelTypes__namespace.isArrowFunctionExpression(callback) && !BabelTypes__namespace.isFunctionExpression(callback)) return;
-        const enclosing = nodePath.findParent((p) => p.isJSXElement());
+        const enclosing = nodePath.findParent(
+          (p) => p.isJSXElement()
+        );
         const enclosingName = enclosing ? getJsxElementName(enclosing.node.openingElement) : null;
         const enclosingRole = enclosing && enclosingName ? classifyWebJsxComponent(enclosingName, enclosing.node.openingElement) : null;
         const returnsListItem = callbackReturnsTag(callback, /* @__PURE__ */ new Set(["li", "tr"]));
@@ -3444,16 +3616,19 @@ function firstCalledFunctionName(node) {
 }
 function containsWindowConfirm(body) {
   let found = false;
-  traverse4__default.default(body, {
-    noScope: true,
-    CallExpression: (nodePath) => {
-      const callee = nodePath.node.callee;
-      if (BabelTypes__namespace.isIdentifier(callee) && callee.name === "confirm") found = true;
-      if (BabelTypes__namespace.isMemberExpression(callee) && BabelTypes__namespace.isIdentifier(callee.object) && callee.object.name === "window" && BabelTypes__namespace.isIdentifier(callee.property) && callee.property.name === "confirm") {
-        found = true;
+  traverse4__default.default(
+    body,
+    {
+      noScope: true,
+      CallExpression: (nodePath) => {
+        const callee = nodePath.node.callee;
+        if (BabelTypes__namespace.isIdentifier(callee) && callee.name === "confirm") found = true;
+        if (BabelTypes__namespace.isMemberExpression(callee) && BabelTypes__namespace.isIdentifier(callee.object) && callee.object.name === "window" && BabelTypes__namespace.isIdentifier(callee.property) && callee.property.name === "confirm") {
+          found = true;
+        }
       }
     }
-  });
+  );
   return found;
 }
 function mergeLocator(current, next) {
@@ -3493,32 +3668,38 @@ function collectionItemNames(callback) {
 function collectionDisplayFields(callback, itemNames) {
   const fields = /* @__PURE__ */ new Set();
   if (!callback.body) return [];
-  traverse4__default.default(callback.body, {
-    noScope: true,
-    MemberExpression: (nodePath) => {
-      const node = nodePath.node;
-      if (BabelTypes__namespace.isIdentifier(node.object) && itemNames.has(node.object.name) && BabelTypes__namespace.isIdentifier(node.property)) {
-        fields.add(node.property.name);
+  traverse4__default.default(
+    callback.body,
+    {
+      noScope: true,
+      MemberExpression: (nodePath) => {
+        const node = nodePath.node;
+        if (BabelTypes__namespace.isIdentifier(node.object) && itemNames.has(node.object.name) && BabelTypes__namespace.isIdentifier(node.property)) {
+          fields.add(node.property.name);
+        }
       }
     }
-  });
+  );
   return Array.from(fields).sort();
 }
 function collectionKeyField(callback, itemNames) {
   let keyField;
   if (!callback.body) return void 0;
-  traverse4__default.default(callback.body, {
-    noScope: true,
-    JSXAttribute: (nodePath) => {
-      const attr = nodePath.node;
-      if (!BabelTypes__namespace.isJSXIdentifier(attr.name) || attr.name.name !== "key") return;
-      if (!attr.value || !BabelTypes__namespace.isJSXExpressionContainer(attr.value)) return;
-      const expr = attr.value.expression;
-      if (BabelTypes__namespace.isMemberExpression(expr) && BabelTypes__namespace.isIdentifier(expr.object) && itemNames.has(expr.object.name) && BabelTypes__namespace.isIdentifier(expr.property)) {
-        keyField = keyField ?? expr.property.name;
+  traverse4__default.default(
+    callback.body,
+    {
+      noScope: true,
+      JSXAttribute: (nodePath) => {
+        const attr = nodePath.node;
+        if (!BabelTypes__namespace.isJSXIdentifier(attr.name) || attr.name.name !== "key") return;
+        if (!attr.value || !BabelTypes__namespace.isJSXExpressionContainer(attr.value)) return;
+        const expr = attr.value.expression;
+        if (BabelTypes__namespace.isMemberExpression(expr) && BabelTypes__namespace.isIdentifier(expr.object) && itemNames.has(expr.object.name) && BabelTypes__namespace.isIdentifier(expr.property)) {
+          keyField = keyField ?? expr.property.name;
+        }
       }
     }
-  });
+  );
   return keyField;
 }
 function collectionRowAction(callback) {
@@ -3566,7 +3747,7 @@ function inferIdentityFields(keyField, displayFields) {
   const out = /* @__PURE__ */ new Set();
   if (keyField) out.add(keyField);
   for (const field of displayFields) {
-    if (/^(id|uuid|key|name|title|plate|email|slug)$/i.test(field)) out.add(field);
+    if (/^(id|uuid|key|name|title|email|slug)$/i.test(field)) out.add(field);
   }
   return Array.from(out);
 }
@@ -7950,7 +8131,7 @@ var coerce = {
 };
 var NEVER = INVALID;
 
-// ../shared/dist/chunk-MSOZJNXB.mjs
+// ../shared/dist/chunk-PKS3VDNB.mjs
 var locatorSourceSchema = external_exports.enum([
   "appilotsId",
   "testID",
@@ -7976,7 +8157,16 @@ var locatorDescriptorSchema = external_exports.object({
   source: locatorSourceSchema.optional()
 }).passthrough();
 var signalDescriptorSchema = external_exports.object({
-  type: external_exports.enum(["navigation", "goBack", "toast", "modal", "inline-error", "data-arrival", "loading", "none"]).or(external_exports.string().min(1).max(60)),
+  type: external_exports.enum([
+    "navigation",
+    "goBack",
+    "toast",
+    "modal",
+    "inline-error",
+    "data-arrival",
+    "loading",
+    "none"
+  ]).or(external_exports.string().min(1).max(60)),
   target: external_exports.string().optional(),
   description: external_exports.string().optional()
 }).passthrough();
@@ -7990,7 +8180,20 @@ var waitPolicyDescriptorSchema = external_exports.object({
   signals: external_exports.array(signalDescriptorSchema).optional(),
   maxMs: external_exports.number().finite().optional()
 }).passthrough();
-var targetDescriptorRoleSchema = external_exports.enum(["button", "submit", "input", "toggle", "select", "date", "list", "row", "menuItem", "modal", "custom"]).or(external_exports.string().min(1).max(60));
+var targetDescriptorRoleSchema = external_exports.enum([
+  "button",
+  "submit",
+  "input",
+  "toggle",
+  "select",
+  "date",
+  "list",
+  "row",
+  "menuItem",
+  "modal",
+  "custom"
+]).or(external_exports.string().min(1).max(60));
+var targetOriginSchema = external_exports.enum(["analyzer", "manifest"]).or(external_exports.string().min(1).max(40));
 var targetDescriptorSchema = external_exports.object({
   id: external_exports.string(),
   role: targetDescriptorRoleSchema,
@@ -8004,10 +8207,20 @@ var targetDescriptorSchema = external_exports.object({
   requiresConfirmation: external_exports.boolean().optional(),
   opensModal: external_exports.string().optional(),
   opensBottomSheet: external_exports.string().optional(),
-  sourceComponent: external_exports.string().optional()
+  sourceComponent: external_exports.string().optional(),
+  origin: targetOriginSchema.optional()
 }).passthrough();
 var flowStepDescriptorSchema = external_exports.object({
-  type: external_exports.enum(["navigate", "fill", "press", "select", "toggle", "wait", "confirm", "choose-list-item"]).or(external_exports.string().min(1).max(60)),
+  type: external_exports.enum([
+    "navigate",
+    "fill",
+    "press",
+    "select",
+    "toggle",
+    "wait",
+    "confirm",
+    "choose-list-item"
+  ]).or(external_exports.string().min(1).max(60)),
   target: external_exports.string().optional(),
   label: external_exports.string().optional(),
   description: external_exports.string().optional(),
@@ -8229,6 +8442,15 @@ external_exports.object({
   password: external_exports.string().min(1, "Password is required"),
   code: totpCodeSchema
 });
+external_exports.object({
+  password: external_exports.string().min(1, "Password is required"),
+  code: totpCodeSchema.optional(),
+  recoveryCode: recoveryCodeSchema.optional(),
+  confirm: external_exports.literal("DELETE MY ACCOUNT")
+}).refine((v) => !(v.code && v.recoveryCode), {
+  message: "Provide either a TOTP code or a recovery code, not both",
+  path: ["code"]
+});
 var createProjectSchema = external_exports.object({
   name: external_exports.string().min(1).max(100),
   description: external_exports.string().max(500).optional(),
@@ -8264,6 +8486,7 @@ external_exports.object({
   content: external_exports.record(external_exports.unknown())
 });
 var apiKeyScopeSchema = external_exports.enum(["sdk", "operator"]);
+var apiKeyEnvironmentSchema = external_exports.enum(["test", "live"]);
 external_exports.object({
   name: external_exports.string().min(1).max(100),
   // Required for `sdk` (default), forbidden/ignored for `operator` —
@@ -8271,6 +8494,7 @@ external_exports.object({
   // missing scope still validates as the pre-existing SDK shape.
   projectId: external_exports.string().min(1).optional(),
   scope: apiKeyScopeSchema.default("sdk"),
+  environment: apiKeyEnvironmentSchema.optional(),
   expiresAt: external_exports.string().datetime().optional()
 }).refine((v) => v.scope !== "sdk" || !!v.projectId, {
   message: 'projectId is required for scope "sdk"',
@@ -8278,13 +8502,23 @@ external_exports.object({
 });
 var boundedString = (max) => external_exports.string().max(max);
 var clientPlatformSchema = external_exports.enum(["react-native", "web", "android", "ios"]).or(external_exports.string().min(1).max(40));
+var identityProvenanceSchema = external_exports.enum(["declared", "derived", "positional"]).or(external_exports.string().min(1).max(40));
 var snapshotInputSchema = external_exports.object({
   id: boundedString(160).optional(),
+  provenance: identityProvenanceSchema.optional(),
+  /**
+   * False when the control is mounted but currently OUTSIDE the window —
+   * below the fold, scrolled off, pushed sideways. Absent means the client
+   * cannot tell (old React Native architecture, or any SDK published
+   * before the field existed), which must never be read as `false`.
+   */
+  onScreen: external_exports.boolean().optional(),
   label: boundedString(300).optional(),
   value: boundedString(4096).optional(),
   placeholder: boundedString(300).optional(),
   editable: external_exports.boolean().optional(),
   secure: external_exports.boolean().optional(),
+  submitsOnReturn: external_exports.boolean().optional(),
   type: boundedString(40).optional(),
   required: external_exports.boolean().optional(),
   invalid: external_exports.boolean().optional(),
@@ -8292,6 +8526,14 @@ var snapshotInputSchema = external_exports.object({
 }).passthrough();
 var snapshotButtonSchema = external_exports.object({
   id: boundedString(160).optional(),
+  provenance: identityProvenanceSchema.optional(),
+  /**
+   * False when the control is mounted but currently OUTSIDE the window —
+   * below the fold, scrolled off, pushed sideways. Absent means the client
+   * cannot tell (old React Native architecture, or any SDK published
+   * before the field existed), which must never be read as `false`.
+   */
+  onScreen: external_exports.boolean().optional(),
   label: boundedString(300).optional(),
   disabled: external_exports.boolean().optional(),
   inModal: external_exports.boolean().optional(),
@@ -8301,12 +8543,28 @@ var snapshotButtonSchema = external_exports.object({
 }).passthrough();
 var snapshotToggleSchema = external_exports.object({
   id: boundedString(160).optional(),
+  provenance: identityProvenanceSchema.optional(),
+  /**
+   * False when the control is mounted but currently OUTSIDE the window —
+   * below the fold, scrolled off, pushed sideways. Absent means the client
+   * cannot tell (old React Native architecture, or any SDK published
+   * before the field existed), which must never be read as `false`.
+   */
+  onScreen: external_exports.boolean().optional(),
   label: boundedString(300).optional(),
   value: external_exports.boolean().optional(),
   inModal: external_exports.boolean().optional()
 }).passthrough();
 var snapshotSliderSchema = external_exports.object({
   id: boundedString(160).optional(),
+  provenance: identityProvenanceSchema.optional(),
+  /**
+   * False when the control is mounted but currently OUTSIDE the window —
+   * below the fold, scrolled off, pushed sideways. Absent means the client
+   * cannot tell (old React Native architecture, or any SDK published
+   * before the field existed), which must never be read as `false`.
+   */
+  onScreen: external_exports.boolean().optional(),
   label: boundedString(300).optional(),
   value: external_exports.number().finite().optional(),
   min: external_exports.number().finite().optional(),
@@ -8347,6 +8605,26 @@ var snapshotListSchema = external_exports.object({
   // should chase, and the relay only reads a known subset.
   items: external_exports.array(external_exports.record(external_exports.unknown())).max(500).optional()
 }).passthrough();
+var snapshotNativeDialogSchema = external_exports.object({
+  id: boundedString(160),
+  title: boundedString(300).optional(),
+  message: boundedString(2e3).optional(),
+  buttons: external_exports.array(
+    external_exports.object({
+      label: boundedString(160),
+      style: external_exports.enum(["default", "cancel", "destructive"]).optional()
+    }).passthrough()
+  ).max(10)
+}).passthrough();
+var snapshotScrollableSchema = external_exports.object({
+  id: boundedString(160),
+  containerType: boundedString(60).optional(),
+  label: boundedString(300).optional(),
+  scrollOffsetY: external_exports.number().finite().optional(),
+  canScrollUp: external_exports.boolean().optional(),
+  canScrollDown: external_exports.boolean().optional(),
+  horizontal: external_exports.boolean().optional()
+}).passthrough();
 var snapshotChoiceGroupSchema = external_exports.object({
   index: external_exports.number().int().optional(),
   id: boundedString(160).optional(),
@@ -8363,6 +8641,14 @@ var snapshotElementSchema = external_exports.object({
   disabled: external_exports.boolean().optional(),
   selected: external_exports.boolean().optional(),
   source: boundedString(40).optional(),
+  provenance: identityProvenanceSchema.optional(),
+  /**
+   * False when the control is mounted but currently OUTSIDE the window —
+   * below the fold, scrolled off, pushed sideways. Absent means the client
+   * cannot tell (old React Native architecture, or any SDK published
+   * before the field existed), which must never be read as `false`.
+   */
+  onScreen: external_exports.boolean().optional(),
   targetId: boundedString(160).optional(),
   listContext: external_exports.record(external_exports.unknown()).optional(),
   inModal: external_exports.boolean().optional()
@@ -8379,7 +8665,34 @@ var agentSnapshotSchema = external_exports.object({
   modalOpen: external_exports.boolean().optional(),
   lists: external_exports.array(snapshotListSchema).max(100).optional(),
   choiceGroups: external_exports.array(snapshotChoiceGroupSchema).max(100).optional(),
-  elements: external_exports.array(snapshotElementSchema).max(1e3).optional()
+  scrollables: external_exports.array(snapshotScrollableSchema).max(20).optional(),
+  nativeDialog: snapshotNativeDialogSchema.optional(),
+  elements: external_exports.array(snapshotElementSchema).max(1e3).optional(),
+  /**
+   * The client clamped this observation to the caps above and lost
+   * data doing it (`clampSnapshotToWireLimits` in
+   * `@appilots/client-core`). Read by the prompt serializer so the
+   * model is told the view is partial — a screen truncated at 500
+   * texts must not be read as a screen that only has 500 things on
+   * it. Optional: older SDKs never clamp and never send it.
+   */
+  truncated: external_exports.boolean().optional(),
+  /**
+   * How many of this screen's controls the client could name, split by
+   * `identityProvenance`. Diagnostic only — the relay never grounds an
+   * action on it — but it is the number that says whether an app needs
+   * annotating, and comparing it between a debug and a release build is
+   * the first direct measurement of what minification costs the agent.
+   */
+  stats: external_exports.object({
+    visitedFibers: external_exports.number().int().nonnegative().optional(),
+    skippedHidden: external_exports.number().int().nonnegative().optional(),
+    identity: external_exports.object({
+      declared: external_exports.number().int().nonnegative().optional(),
+      derived: external_exports.number().int().nonnegative().optional(),
+      positional: external_exports.number().int().nonnegative().optional()
+    }).passthrough().optional()
+  }).passthrough().optional()
 }).passthrough();
 var agentContextSchema = external_exports.object({
   /**
@@ -8429,6 +8742,19 @@ var agentContextSchema = external_exports.object({
   ).max(200).optional(),
   loadingPending: external_exports.boolean().optional()
 }).passthrough();
+var introspectionFailureReasonSchema = external_exports.enum([
+  "sentinel-missing-internals",
+  "never-mounted",
+  "render-crashed",
+  "names-mangled",
+  "walk-recognized-nothing"
+]);
+var introspectionDiagnosticsSchema = external_exports.object({
+  captured: external_exports.boolean(),
+  failureReason: introspectionFailureReasonSchema.nullish(),
+  reactVersion: boundedString(32).nullish(),
+  failureCount: external_exports.number().int().min(0).max(1e6).optional()
+});
 external_exports.object({
   content: external_exports.string().min(1).max(4096),
   sessionId: external_exports.string().optional(),
@@ -8438,7 +8764,20 @@ external_exports.object({
    * the active MCP doc and emits `mcp_version_mismatch` telemetry when
    * they differ. Optional — older SDKs simply skip the check.
    */
-  mcpVersion: external_exports.string().max(64).optional()
+  mcpVersion: external_exports.string().max(64).optional(),
+  /**
+   * SDK-side introspection health. Only sent when it FAILED — a client
+   * that reached the React tree omits the field entirely, so the happy
+   * path costs nothing on the wire.
+   *
+   * Without this, an app whose introspection is dead sends a snapshot
+   * that is empty but perfectly well-formed, indistinguishable from a
+   * genuinely empty screen. The server emits
+   * `introspection_unavailable` so the failure is visible to us instead
+   * of waiting for a bug report. Optional — older SDKs simply never
+   * send it.
+   */
+  introspection: introspectionDiagnosticsSchema.optional()
 });
 var agentActionTypeSchema = external_exports.enum([
   "navigate",
@@ -8449,11 +8788,22 @@ var agentActionTypeSchema = external_exports.enum([
   "custom"
 ]);
 var navigationPayloadSchema = external_exports.object({
-  screenName: external_exports.string().min(1),
+  // Optional ONLY so `goBack` can exist (#398): it returns to whatever
+  // is beneath on the stack and has no destination to name. Every other
+  // action is still required to carry one — enforced by the refine
+  // below rather than by the field, so the error names the real problem
+  // ("navigate needs a screenName") instead of a missing key.
+  screenName: external_exports.string().min(1).optional(),
   params: external_exports.record(external_exports.unknown()).optional(),
   navigationAction: external_exports.enum(["push", "navigate", "replace", "goBack", "reset"]).default("navigate").optional(),
   path: external_exports.array(external_exports.string().min(1)).optional()
-}).passthrough();
+}).passthrough().refine(
+  (payload) => payload.navigationAction === "goBack" || typeof payload.screenName === "string" && payload.screenName.length > 0,
+  {
+    message: 'screenName is required for every navigationAction except "goBack"',
+    path: ["screenName"]
+  }
+);
 var formFillFieldSchema = external_exports.object({
   fieldId: external_exports.string().min(1),
   fieldType: external_exports.enum(["text", "select", "toggle", "date", "number", "custom"]).default("text").optional(),
@@ -8787,6 +9137,8 @@ var sandboxObservationSchema = external_exports.object({
   inputs: external_exports.array(
     external_exports.object({
       id: external_exports.string().max(120),
+      provenance: identityProvenanceSchema.optional(),
+      onScreen: external_exports.boolean().optional(),
       label: external_exports.string().max(200).optional(),
       value: external_exports.string().max(2e3).optional(),
       disabled: external_exports.boolean().optional(),
@@ -8800,6 +9152,8 @@ var sandboxObservationSchema = external_exports.object({
   buttons: external_exports.array(
     external_exports.object({
       id: external_exports.string().max(120),
+      provenance: identityProvenanceSchema.optional(),
+      onScreen: external_exports.boolean().optional(),
       label: external_exports.string().max(200).optional(),
       disabled: external_exports.boolean().optional(),
       /** Risk metadata (e.g. "high") the SDK forwards for danger UI. */
@@ -8821,6 +9175,8 @@ var sandboxObservationSchema = external_exports.object({
   sliders: external_exports.array(
     external_exports.object({
       id: external_exports.string().max(120),
+      provenance: identityProvenanceSchema.optional(),
+      onScreen: external_exports.boolean().optional(),
       label: external_exports.string().max(200).optional(),
       value: external_exports.number().finite().optional(),
       min: external_exports.number().finite().optional(),
@@ -8850,6 +9206,44 @@ var sandboxObservationSchema = external_exports.object({
       ).max(200).optional()
     }).passthrough()
   ).max(20).optional(),
+  /**
+   * Toggles exactly as the SDK snapshot reports them (#390).
+   *
+   * Their absence is why `generality-component-control-smarthome`
+   * came back `errored` with a 422 instead of measuring anything:
+   * this schema is `.strict()`, so a scenario that declares a switch
+   * is rejected before the agent is ever asked. Which means the
+   * corpus could not express the single control behind failure 02 of
+   * the functional audit — "disable an agent; the switch never
+   * moves". The one defect the eval most needed to catch was the one
+   * shape it could not describe.
+   */
+  toggles: external_exports.array(
+    external_exports.object({
+      id: external_exports.string().max(120),
+      provenance: identityProvenanceSchema.optional(),
+      onScreen: external_exports.boolean().optional(),
+      label: external_exports.string().max(200).optional(),
+      value: external_exports.boolean().optional(),
+      disabled: external_exports.boolean().optional()
+    })
+  ).max(100).optional(),
+  /**
+   * The interaction graph — the `el:*` ids the prompt tells the model
+   * to prefer over ordinal handles. Passthrough per entry for the
+   * same reason `lists` is: the SDK adds fields faster than this
+   * schema should chase them.
+   */
+  elements: external_exports.array(
+    external_exports.object({
+      id: external_exports.string().max(160),
+      role: external_exports.string().max(40).optional(),
+      label: external_exports.string().max(300).optional()
+    }).passthrough()
+  ).max(500).optional(),
+  /** Screen-level state the relay renders and branches on. */
+  loading: external_exports.boolean().optional(),
+  modalOpen: external_exports.boolean().optional(),
   extra: external_exports.record(external_exports.unknown()).optional()
 }).strict();
 external_exports.object({
@@ -8890,13 +9284,29 @@ external_exports.object({
    * heuristics, forces tool choice when the last user message carries a
    * failure marker). Only meaningful alongside `history`.
    */
-  isRecoveryHop: external_exports.boolean().optional()
+  isRecoveryHop: external_exports.boolean().optional(),
+  /**
+   * Run this call against the application structure supplied here
+   * instead of the project's active MCP document.
+   *
+   * Sandbox-only, and the relay honours it only on a `dryRun` call —
+   * see `resolveMcpOverride` in apps/api. It exists because the eval
+   * corpus could otherwise only ever describe ONE app: every scenario
+   * resolves to the same seeded project, so every navigate destination,
+   * every screen title and every bit of domain priming in the prompt
+   * came from the same vehicle-management demo. A suite that can only
+   * pose questions about one app cannot measure whether the agent works
+   * on another one.
+   *
+   * Deliberately loose (`z.record`): the MCP document's shape is owned
+   * by the generator, and pinning it here would turn every additive
+   * generator change into a 422 in the sandbox.
+   */
+  applicationStructure: external_exports.record(external_exports.unknown()).optional()
 }).strict();
 var relayDiagnosticsSchema = external_exports.object({
   unverifiedTargets: external_exports.array(external_exports.string()),
-  guardsFired: external_exports.array(
-    external_exports.object({ guard: external_exports.string(), detail: external_exports.string().optional() })
-  ),
+  guardsFired: external_exports.array(external_exports.object({ guard: external_exports.string(), detail: external_exports.string().optional() })),
   repairMode: external_exports.enum(["repair", "strict", "disabled"]),
   promptVersion: external_exports.string(),
   // Defaulted for producers that predate the field: before it existed
@@ -9155,6 +9565,30 @@ external_exports.object({
   name: external_exports.string().min(1).max(200).optional(),
   identifiers: endUserIdentifiersSchema.optional()
 });
+var MAX_EXTERNAL_USER_ID_LENGTH = 128;
+function normalizeExternalUserId(value) {
+  let raw;
+  if (typeof value === "string") raw = value;
+  else if (typeof value === "number" && Number.isFinite(value)) raw = String(value);
+  else return void 0;
+  const trimmed = raw.trim();
+  if (!trimmed) return void 0;
+  if (trimmed.length > MAX_EXTERNAL_USER_ID_LENGTH) return void 0;
+  return trimmed;
+}
+var MAX_DEVICE_INFO_BYTES = 4096;
+var sessionDeviceInfoSchema = external_exports.object({
+  platform: external_exports.string().max(64).optional(),
+  osVersion: external_exports.string().max(64).optional(),
+  appVersion: external_exports.string().max(64).optional(),
+  sdkVersion: external_exports.string().max(64).optional()
+}).passthrough().refine((info) => JSON.stringify(info).length <= MAX_DEVICE_INFO_BYTES, {
+  message: `device_info exceeds ${MAX_DEVICE_INFO_BYTES} bytes`
+});
+external_exports.object({
+  userId: external_exports.preprocess(normalizeExternalUserId, external_exports.string().optional()),
+  deviceInfo: sessionDeviceInfoSchema.optional().catch(void 0)
+});
 external_exports.object({
   projectId: external_exports.string().min(1).max(64),
   externalId: external_exports.string().min(1).max(128),
@@ -9162,6 +9596,27 @@ external_exports.object({
   identifiers: endUserIdentifiersSchema.optional()
 });
 
+// src/utils/stringify.ts
+function stringifyUnknown(value) {
+  if (value instanceof Error) {
+    const message = value.message || value.name;
+    const cause = value.cause;
+    if (cause instanceof Error && cause.message && cause.message !== message) {
+      return `${message} (${cause.message})`;
+    }
+    return message;
+  }
+  if (typeof value === "string") return value;
+  if (value === null || value === void 0) return String(value);
+  if (typeof value !== "object") return String(value);
+  try {
+    const json = JSON.stringify(value);
+    if (json && json !== "{}") return json;
+  } catch {
+  }
+  return String(value);
+}
+
 // src/manifest/loadManifest.ts
 var DEFAULT_MANIFEST_FILENAME = "appilots.manifest.json";
 var manifestSchema = external_exports.object({
@@ -9178,14 +9633,16 @@ async function loadManifest(rootDir, manifestPath) {
     if (error?.code === "ENOENT") {
       return { manifest: null, resolvedPath };
     }
-    throw new Error(`Failed to read Appilots manifest at ${resolvedPath}: ${error?.message ?? String(error)}`);
+    throw new Error(
+      `Failed to read Appilots manifest at ${resolvedPath}: ${stringifyUnknown(error)}`
+    );
   }
   let parsedJson;
   try {
     parsedJson = JSON.parse(raw);
   } catch (error) {
     throw new Error(
-      `Appilots manifest at ${resolvedPath} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`
+      `Appilots manifest at ${resolvedPath} is not valid JSON: ${stringifyUnknown(error)}`
     );
   }
   const result = manifestSchema.safeParse(parsedJson);
@@ -9199,11 +9656,47 @@ Each entry in "screens" must match the ScreenDescriptor shape (see docs/platform
   }
   return { manifest: result.data, resolvedPath };
 }
+function mergeScreen(base, declared) {
+  const fields = { ...base };
+  for (const [key, value] of Object.entries(declared)) {
+    if (value === void 0) continue;
+    if (Array.isArray(value) && value.length === 0) continue;
+    fields[key] = value;
+  }
+  const merged = fields;
+  merged.targets = mergeById(base.targets, markManifestOrigin(declared.targets));
+  merged.actions = mergeById(base.actions, declared.actions) ?? [];
+  if (base.agentHints || declared.agentHints) {
+    merged.agentHints = { ...base.agentHints, ...declared.agentHints };
+  }
+  return merged;
+}
+function mergeById(base, overlay) {
+  if (!overlay || overlay.length === 0) return base;
+  if (!base || base.length === 0) return overlay;
+  const byId = /* @__PURE__ */ new Map();
+  for (const entry of base) byId.set(entry.id, entry);
+  for (const entry of overlay) {
+    const existing = byId.get(entry.id);
+    byId.set(entry.id, existing ? { ...existing, ...entry } : entry);
+  }
+  return Array.from(byId.values());
+}
+function markManifestOrigin(targets) {
+  if (!targets || targets.length === 0) return targets;
+  return targets.map((target) => ({ origin: "manifest", ...target }));
+}
 function mergeManifestScreens(analyzerScreens, manifestScreens) {
   if (!manifestScreens || manifestScreens.length === 0) return analyzerScreens;
   const byName = /* @__PURE__ */ new Map();
   for (const screen of analyzerScreens) byName.set(screen.name, screen);
-  for (const screen of manifestScreens) byName.set(screen.name, screen);
+  for (const declared of manifestScreens) {
+    const base = byName.get(declared.name);
+    byName.set(
+      declared.name,
+      base ? mergeScreen(base, declared) : { ...declared, targets: markManifestOrigin(declared.targets) }
+    );
+  }
   return Array.from(byName.values());
 }
 function mergeManifestNavigation(analyzerNavigation, manifestNavigation) {
@@ -9493,7 +9986,12 @@ var MCPGenerator = class _MCPGenerator {
     }
     const mergedScreens = mergeManifestScreens(analyzed.screens, manifest?.screens);
     const navigation = mergeManifestNavigation(analyzed.navigation, manifest?.navigation);
-    const agentReadyScreens = mergedScreens.map(enrichScreenForAgent);
+    const agentReadyScreens = mergedScreens.map(
+      (screen) => enrichScreenForAgent({
+        ...screen,
+        filePath: screen.filePath ? path8__namespace.default.relative(this.generatorConfig.rootDir, screen.filePath) : screen.filePath
+      })
+    );
     const projectInfo = await this.getProjectInfo();
     const projectName = projectInfo.name;
     console.log(`[MCPGenerator] Project name: ${projectName}`);
@@ -9516,10 +10014,7 @@ var MCPGenerator = class _MCPGenerator {
     };
     const serialized = JSON.stringify(document, null, 2);
     const checksum = this.calculateChecksum(serialized);
-    const filePath = path8__namespace.default.resolve(
-      outputDir,
-      `mcp-document.${this.options.format}`
-    );
+    const filePath = path8__namespace.default.resolve(outputDir, `mcp-document.${this.options.format}`);
     await fs.writeFile(filePath, serialized, "utf-8");
     console.log(`[MCPGenerator] Document written to: ${filePath}`);
     const checksumFilePath = path8__namespace.default.resolve(outputDir, ".appilots-checksum");
@@ -9574,6 +10069,70 @@ var MCPGenerator = class _MCPGenerator {
     }
   }
 };
+var DEFAULT_SERVER_URL = "http://localhost:4000";
+var KNOWN_CONFIG_KEYS = [
+  "apiKey",
+  "projectId",
+  "serverUrl",
+  "outputDir",
+  "include",
+  "exclude",
+  "autoActivate",
+  "strictScreens",
+  "screenPatterns",
+  "navigationInclude",
+  "navigationExclude",
+  "platform",
+  "manifestPath",
+  "eval"
+];
+var KEY_ALIASES = {
+  apiUrl: "serverUrl",
+  // `@appilots/sdk`'s own name for this. One `.appilotsrc` feeds both
+  // packages, so an integrator who wrote the SDK's key should not be told
+  // it is unrecognized.
+  apiBaseUrl: "serverUrl",
+  apiURL: "serverUrl",
+  baseUrl: "serverUrl",
+  url: "serverUrl",
+  host: "serverUrl",
+  endpoint: "serverUrl",
+  server: "serverUrl",
+  key: "apiKey",
+  token: "apiKey",
+  project: "projectId",
+  sourceDir: "include",
+  srcDir: "include",
+  source: "include",
+  outDir: "outputDir"
+};
+function editDistance(a, b) {
+  let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const current = [i];
+    for (let j = 1; j <= b.length; j++) {
+      const deletion = (previous[j] ?? 0) + 1;
+      const insertion = (current[j - 1] ?? 0) + 1;
+      const substitution = (previous[j - 1] ?? 0) + (a[i - 1] === b[j - 1] ? 0 : 1);
+      current.push(Math.min(deletion, insertion, substitution));
+    }
+    previous = current;
+  }
+  return previous[b.length] ?? 0;
+}
+function suggestConfigKey(key) {
+  const alias = KEY_ALIASES[key];
+  if (alias) return alias;
+  const lower = key.toLowerCase();
+  let best;
+  for (const known of KNOWN_CONFIG_KEYS) {
+    const distance = editDistance(lower, known.toLowerCase());
+    if (distance <= 2 && (!best || distance < best.distance)) {
+      best = { key: known, distance };
+    }
+  }
+  return best?.key;
+}
 function getEnvOverrides(env = process.env) {
   const clean = (value) => {
     const trimmed = value?.trim();
@@ -9585,7 +10144,7 @@ function getEnvOverrides(env = process.env) {
     serverUrl: clean(env.APPILOTS_SERVER_URL)
   };
 }
-function loadConfig() {
+function loadConfig(onWarn) {
   const configPath = getConfigPath();
   const env = getEnvOverrides();
   let fileConfig = {};
@@ -9593,13 +10152,15 @@ function loadConfig() {
     try {
       fileConfig = JSON.parse(fs$1.readFileSync(configPath, "utf-8"));
     } catch (error) {
-      throw new Error(`Failed to parse .appilotsrc at ${configPath}: ${error instanceof Error ? error.message : "Unknown error"}`);
+      throw new Error(
+        `Failed to parse .appilotsrc at ${configPath}: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
     }
   } else if (!env.apiKey) {
     return null;
   }
   const merged = {
-    serverUrl: "http://localhost:4000",
+    serverUrl: DEFAULT_SERVER_URL,
     outputDir: ".appilots",
     autoActivate: true,
     strictScreens: true,
@@ -9609,6 +10170,12 @@ function loadConfig() {
     ...env.serverUrl ? { serverUrl: env.serverUrl } : {}
   };
   const validation = validateConfig(merged);
+  if (onWarn) {
+    const source = configPath ?? "environment variables";
+    for (const warning of validation.warnings) {
+      onWarn(`${source}: ${warning}`);
+    }
+  }
   if (!validation.valid) {
     const source = configPath ?? "environment variables";
     throw new Error(
@@ -9624,7 +10191,7 @@ function saveConfig(dir, config) {
   const mergedConfig = {
     apiKey: config.apiKey || existingConfig?.apiKey || "",
     projectId: config.projectId || existingConfig?.projectId || "",
-    serverUrl: config.serverUrl || existingConfig?.serverUrl || "http://localhost:4000",
+    serverUrl: config.serverUrl || existingConfig?.serverUrl || DEFAULT_SERVER_URL,
     outputDir: config.outputDir || existingConfig?.outputDir || ".appilots",
     autoActivate: config.autoActivate !== void 0 ? config.autoActivate : existingConfig?.autoActivate ?? true,
     include: config.include || existingConfig?.include,
@@ -9640,7 +10207,9 @@ function saveConfig(dir, config) {
   try {
     fs$1.writeFileSync(configPath, JSON.stringify(mergedConfig, null, 2), "utf-8");
   } catch (error) {
-    throw new Error(`Failed to write .appilotsrc to ${configPath}: ${error instanceof Error ? error.message : "Unknown error"}`);
+    throw new Error(
+      `Failed to write .appilotsrc to ${configPath}: ${error instanceof Error ? error.message : "Unknown error"}`
+    );
   }
 }
 function getConfigPath() {
@@ -9667,14 +10236,25 @@ function getConfigPath() {
 }
 function validateConfig(config) {
   const errors = [];
+  const warnings = [];
   if (!config || typeof config !== "object") {
     return {
       valid: false,
-      errors: ["Configuration must be an object"]
+      errors: ["Configuration must be an object"],
+      warnings
     };
   }
+  for (const key of Object.keys(config)) {
+    if (KNOWN_CONFIG_KEYS.includes(key)) continue;
+    const suggestion = suggestConfigKey(key);
+    warnings.push(
+      `unknown key "${key}" \u2014 ignored` + (suggestion ? ` (did you mean "${suggestion}"?)` : "")
+    );
+  }
   if (!config.apiKey || typeof config.apiKey !== "string") {
-    errors.push("apiKey is required and must be a string (set it in .appilotsrc or via APPILOTS_API_KEY)");
+    errors.push(
+      "apiKey is required and must be a string (set it in .appilotsrc or via APPILOTS_API_KEY)"
+    );
   } else if (!config.apiKey.startsWith("ak_")) {
     errors.push('apiKey must start with "ak_"');
   }
@@ -9736,7 +10316,8 @@ function validateConfig(config) {
   }
   return {
     valid: errors.length === 0,
-    errors
+    errors,
+    warnings
   };
 }
 
@@ -9782,19 +10363,76 @@ function formatMetadataWarnings(warnings) {
   );
 }
 
+// ../shared/dist/chunk-UEMUBXFH.mjs
+var DEFAULT_API_BASE_URL = "https://api.appilots.com";
+var APPILOTS_API_PATH_PREFIX = "/api/v1";
+function normalizeApiBaseUrl(configured) {
+  const raw = (configured ?? DEFAULT_API_BASE_URL).trim().replace(/\/+$/, "");
+  if (!raw) return `${DEFAULT_API_BASE_URL}${APPILOTS_API_PATH_PREFIX}`;
+  if (new RegExp(`${APPILOTS_API_PATH_PREFIX}(/|$)`).test(raw)) return raw;
+  return `${raw}${APPILOTS_API_PATH_PREFIX}`;
+}
+
 // src/services/api-client.ts
-var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_TIMEOUT_MS2 = 3e4;
 var DEFAULT_MAX_RETRIES = 2;
 var RETRY_BASE_DELAY_MS = 500;
+function describeNetworkError(url, err) {
+  let origin = url;
+  try {
+    origin = new URL(url).origin;
+  } catch {
+  }
+  const cause = err?.cause;
+  const code = typeof cause?.code === "string" ? cause.code : void 0;
+  const detail = code ?? stringifyUnknown(err);
+  return new Error(`Cannot reach Appilots server at ${origin} (${detail})`);
+}
+function errorCodeOf(payload) {
+  const error = payload?.error;
+  if (error && typeof error === "object") {
+    const { code } = error;
+    if (typeof code === "string" && code.trim()) return code;
+  }
+  return void 0;
+}
+function describeApiError(payload, fallback) {
+  const error = payload?.error;
+  if (typeof error === "string" && error.trim()) return error;
+  if (error && typeof error === "object") {
+    const { code, message: message2 } = error;
+    const text = typeof message2 === "string" && message2.trim() ? message2 : void 0;
+    const tag = typeof code === "string" && code.trim() ? code : void 0;
+    if (text && tag) return `${text} (${tag})`;
+    if (text) return text;
+    if (tag) return tag;
+  }
+  const message = payload?.message;
+  if (typeof message === "string" && message.trim()) return message;
+  return fallback;
+}
 var AppilotsAPIClient = class {
-  serverUrl;
+  /**
+   * `serverUrl` with the API's mount prefix resolved — every path below
+   * is relative to THIS, not to the configured origin.
+   *
+   * It used to be the raw `serverUrl` with `/api/v1` hardcoded into each
+   * path, which made the field mean something different here than in the
+   * SDK. Both read the same `.appilotsrc`: the SDK completes the prefix
+   * when it is missing, so `https://api.appilots.com/api/v1` is correct
+   * there — and here that same value produced
+   * `/api/v1/api/v1/cli/sync`, a 404 whose body reads `Route not found`.
+   * Sharing `normalizeApiBaseUrl` is what makes one file mean one thing:
+   * with or without the prefix now works in both.
+   */
+  baseUrl;
   apiKey;
   timeoutMs;
   maxRetries;
   constructor(config) {
-    this.serverUrl = config.serverUrl.replace(/\/$/, "");
+    this.baseUrl = normalizeApiBaseUrl(config.serverUrl);
     this.apiKey = config.apiKey;
-    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS2;
     this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
   }
   /**
@@ -9818,7 +10456,7 @@ var AppilotsAPIClient = class {
         }
         return response;
       } catch (err) {
-        lastError = controller.signal.aborted ? new Error(`Request timed out after ${this.timeoutMs}ms: ${url}`) : err;
+        lastError = controller.signal.aborted ? new Error(`Request timed out after ${this.timeoutMs}ms: ${url}`) : describeNetworkError(url, err);
       } finally {
         clearTimeout(timer);
       }
@@ -9837,7 +10475,7 @@ var AppilotsAPIClient = class {
    */
   async sync(content, version, appVersion) {
     try {
-      const response = await this.request(`${this.serverUrl}/api/v1/cli/sync`, {
+      const response = await this.request(`${this.baseUrl}/cli/sync`, {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
@@ -9851,7 +10489,9 @@ var AppilotsAPIClient = class {
         return {
           success: false,
           unchanged: false,
-          error: errorData?.error || `HTTP ${response.status}: ${response.statusText}`
+          error: describeApiError(errorData, `HTTP ${response.status}: ${response.statusText}`),
+          errorCode: errorCodeOf(errorData),
+          errorStatus: response.status
         };
       }
       const json = await response.json();
@@ -9864,7 +10504,8 @@ var AppilotsAPIClient = class {
       return {
         success: false,
         unchanged: false,
-        error: error instanceof Error ? error.message : "Failed to sync with Appilots API"
+        error: error instanceof Error ? error.message : "Failed to sync with Appilots API",
+        errorStatus: 0
       };
     }
   }
@@ -9875,7 +10516,7 @@ var AppilotsAPIClient = class {
    */
   async status() {
     try {
-      const response = await this.request(`${this.serverUrl}/api/v1/cli/status`, {
+      const response = await this.request(`${this.baseUrl}/cli/status`, {
         method: "GET",
         headers: {
           Authorization: `Bearer ${this.apiKey}`
@@ -9884,7 +10525,7 @@ var AppilotsAPIClient = class {
       if (!response.ok) {
         const errorData = await response.json().catch(() => ({}));
         return {
-          error: errorData?.error || `HTTP ${response.status}: ${response.statusText}`
+          error: describeApiError(errorData, `HTTP ${response.status}: ${response.statusText}`)
         };
       }
       const json = await response.json();
@@ -9906,7 +10547,7 @@ var AppilotsAPIClient = class {
    */
   async evalRun(scenarios) {
     try {
-      const response = await this.request(`${this.serverUrl}/api/v1/cli/eval/run`, {
+      const response = await this.request(`${this.baseUrl}/cli/eval/run`, {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
@@ -9937,7 +10578,7 @@ var AppilotsAPIClient = class {
    */
   async health() {
     try {
-      const response = await this.request(`${this.serverUrl}/api/v1/health`, {
+      const response = await this.request(`${this.baseUrl}/health`, {
         method: "GET"
       });
       return response.ok;
@@ -9947,7 +10588,11 @@ var AppilotsAPIClient = class {
   }
 };
 
+// src/version.ts
+var CLI_VERSION = "0.10.0";
+
 exports.AppilotsAPIClient = AppilotsAPIClient;
+exports.CLI_VERSION = CLI_VERSION;
 exports.ComponentAnalyzer = ComponentAnalyzer;
 exports.DEFAULT_MANIFEST_FILENAME = DEFAULT_MANIFEST_FILENAME;
 exports.DEFAULT_WEB_SCREEN_PATTERNS = DEFAULT_WEB_SCREEN_PATTERNS;