@appilots/sdk 0.11.0 → 0.11.3

package/dist/{chunk-NA5H4IHH.mjs → chunk-2ZDELL54.mjs}

@@ -1,4 +1,4 @@
-import { getFiberRoot, appilotsDebugWarn, recordIntrospectionFailure, getCurrentScreen, walkFiber, getActiveRouteNames, clampSnapshotToWireLimits, deriveInteractionElements, rectForNode, toWireElement, attachElementIdsToChoiceGroups, elementRegistry, appilotsDebugLog, getLastWalkDiagnostics, SDK_VERSION, geometryStats, geometryAvailability, getNameManglingProbe, emptyDetectorCounts, getAutoTrackingState, getIntrospectionDiagnostics, getDefaultRegistry, useAppilotsContext, ChatSessionMachine, getCurrentScreenSignature, ActionQueueMachine, getScreenMetadata, setCurrentScreen, useResolvedRegistry, totalDetectorHits, listRegistry, getOpenNativeDialog, componentRegistry, getLastAnsweredNativeDialog, probeLoadingState, isListItemPressTarget, waitForLoadingSettle, describeValue, waitForScreenSettle, screenDepartedBaseline, routesBelongToSameFeature, actionPressTargetId, getNavigationStateSnapshot, getNavigationRef, isOptionalStepAutomationFailure, OPTIONAL_STEP_AUTOMATION_HINT, normalize3, matchScore, FORM_VALIDATION_TEXT_RE, idLooselyMatches, parseStableElementId, shouldSkipSubtree, isAlwaysListContainer, isHeuristicListContainer, findListItems, getTypeName, foldForCompare, isModalFiber, getAllScreens, snapshotShowsOpenCreateForm, switchValue, isReferenceable, looksDestructiveActionLabel, isGenericSelectValue, FORM_WRITE_SUCCESS_TEXT_RE, isSwitchLike, TOUCHABLE_NAMES } from './chunk-G6KI7KVH.mjs';
+import { createSnapshotDeltaTracker, getFiberRoot, appilotsDebugWarn, recordIntrospectionFailure, getCurrentScreen, walkFiber, getActiveRouteNames, clampSnapshotToWireLimits, deriveInteractionElements, rectForNode, toWireElement, attachElementIdsToChoiceGroups, elementRegistry, appilotsDebugLog, getLastWalkDiagnostics, SDK_VERSION, geometryStats, geometryAvailability, getNameManglingProbe, emptyDetectorCounts, getAutoTrackingState, getIntrospectionDiagnostics, getDefaultRegistry, useAppilotsContext, ChatSessionMachine, getCurrentScreenSignature, ActionQueueMachine, getScreenMetadata, setCurrentScreen, useResolvedRegistry, totalDetectorHits, listRegistry, getOpenNativeDialog, componentRegistry, getLastAnsweredNativeDialog, probeLoadingState, isListItemPressTarget, waitForLoadingSettle, describeValue, waitForScreenSettle, screenDepartedBaseline, routesBelongToSameFeature, actionPressTargetId, getNavigationStateSnapshot, getNavigationRef, isOptionalStepAutomationFailure, OPTIONAL_STEP_AUTOMATION_HINT, isSwitchLike, idLooselyMatches, normalize3, matchScore, FORM_VALIDATION_TEXT_RE, parseStableElementId, shouldSkipSubtree, isAlwaysListContainer, isHeuristicListContainer, findListItems, getTypeName, foldForCompare, isModalFiber, switchValue, getAllScreens, snapshotShowsOpenCreateForm, isReferenceable, looksDestructiveActionLabel, isGenericSelectValue, FORM_WRITE_SUCCESS_TEXT_RE, TOUCHABLE_NAMES } from './chunk-ROXXCDIG.mjs';
 import React, { useMemo, useRef, useSyncExternalStore, useEffect, useCallback, useState } from 'react';
 import { Alert } from 'react-native';
 
@@ -270,6 +270,39 @@ function appilotsSelfCheck() {
   };
 }
 
+// src/introspection/switchFlip.ts
+function declaredState(props) {
+  if (typeof props?.value === "boolean") return props.value;
+  const aria = props?.["aria-checked"];
+  if (typeof aria === "boolean") return aria;
+  const checked = props?.accessibilityState?.checked;
+  return typeof checked === "boolean" ? checked : void 0;
+}
+function isReactNativeSwitch(fiber) {
+  return getTypeName(fiber?.type) === "Switch" || getTypeName(fiber?.elementType) === "Switch";
+}
+var SWITCH_FLIP_HANDLERS = ["onValueChange", "onChange", "onPress"];
+function flipSwitchFiber(fiber, next) {
+  const props = fiber?.memoizedProps ?? {};
+  const onValueChange = props.onValueChange;
+  const onChange = props.onChange;
+  const onPress = props.onPress;
+  const handler = typeof onValueChange === "function" ? { fn: onValueChange, via: "onValueChange" } : typeof onChange === "function" ? { fn: onChange, via: "onChange" } : typeof onPress === "function" ? { fn: onPress, via: "onPress" } : null;
+  if (!handler) return { ok: false, reason: "no-handler" };
+  try {
+    if (handler.via === "onPress") {
+      if (declaredState(props) === next) return { ok: true, via: "onPress", noop: true };
+      handler.fn();
+    } else if (handler.via === "onChange") {
+      if (isReactNativeSwitch(fiber)) handler.fn({ nativeEvent: { value: next }, value: next });
+      else handler.fn(next);
+    } else handler.fn(next);
+  } catch (err) {
+    return { ok: false, reason: "threw", error: err?.message ?? "switch handler threw" };
+  }
+  return { ok: true, via: handler.via };
+}
+
 // src/introspection/findInteractive.ts
 function getTypeName2(type) {
   if (!type) return null;
@@ -355,7 +388,7 @@ function shouldSkipSubtree2(fiber) {
   return false;
 }
 var normalize = foldForCompare;
-function scoreMatch(fiber, queryNorm, queryRaw) {
+function scoreMatchDetail(fiber, queryNorm, queryRaw) {
   const props = fiber.memoizedProps ?? {};
   const candidates = [];
   if (typeof props.testID === "string") candidates.push({ val: props.testID, weight: 100 });
@@ -378,13 +411,16 @@ function scoreMatch(fiber, queryNorm, queryRaw) {
     else if (queryNorm && (vNorm.includes(queryNorm) || queryNorm.includes(vNorm)))
       best = Math.max(best, weight - 20);
   }
-  if (best > 0 && props.disabled === true) {
+  const named = best >= IDENTITY_MATCH_SCORE;
+  const disabledProp = props.disabled === true;
+  const disabledA11y = typeof props.accessibilityState === "object" && props.accessibilityState !== null && props.accessibilityState.disabled === true;
+  if (best > 0 && disabledProp) {
     best = Math.max(1, best - 60);
   }
-  if (best > 0 && typeof props.accessibilityState === "object" && props.accessibilityState !== null && props.accessibilityState.disabled === true) {
+  if (best > 0 && disabledA11y) {
     best = Math.max(1, best - 60);
   }
-  return best;
+  return { score: best, named, disabled: disabledProp || disabledA11y };
 }
 function wrapTextInput(fiber) {
   const getProps = () => fiber.memoizedProps ?? {};
@@ -421,13 +457,31 @@ function wrapSwitch(fiber) {
   return {
     kind: "toggle",
     label: getProps().accessibilityLabel ?? getProps().testID,
-    getValue: () => !!getProps().value,
+    // `switchValue` reads `accessibilityState.checked` when there is no
+    // `value` prop. A CUSTOM switch (a Pressable with
+    // `accessibilityRole="switch"`) has only the former, and reporting
+    // `false` for a control that is on is worse than reporting nothing:
+    // the caller inverts this to decide where to move.
+    getValue: () => switchValue(getProps()),
     setValue: (value) => {
-      const { onValueChange, onChange } = getProps();
       const boolVal = typeof value === "boolean" ? value : value === "true" || value === true;
-      if (typeof onValueChange === "function") onValueChange(boolVal);
-      else if (typeof onChange === "function") onChange({ nativeEvent: { value: boolVal } });
-      else throw new Error("Switch has no onValueChange/onChange handler");
+      const flipped = flipSwitchFiber(fiber, boolVal);
+      if (flipped.ok) return;
+      if (flipped.reason === "no-handler") {
+        throw new Error(`Switch exposes none of: ${SWITCH_FLIP_HANDLERS.join(", ")}`);
+      }
+      throw new Error(flipped.error);
+    },
+    // A custom switch is a `Pressable` underneath, so it may well declare
+    // its own long press (hold to configure, hold for a shortcut menu).
+    // Classifying it as a toggle took it out of the `kind: 'target'`
+    // lookup, and without this the long press would fall through to the
+    // best remaining candidate — the card that WRAPS it.
+    longPress: () => {
+      const { onLongPress } = getProps();
+      if (typeof onLongPress !== "function") return false;
+      onLongPress();
+      return true;
     }
   };
 }
@@ -449,6 +503,19 @@ function wrapTouchable(fiber, label) {
     }
   };
 }
+var IDENTITY_MATCH_SCORE = 100;
+function describeCandidate(fiber, kind) {
+  const props = fiber?.memoizedProps ?? {};
+  return props.testID ?? props.accessibilityLabel ?? props.placeholder ?? (kind === "target" ? findChildText(fiber) : void 0);
+}
+function isDescendantOf(fiber, ancestor) {
+  if (!fiber || !ancestor) return false;
+  let node = fiber.return;
+  for (let depth = 0; node && depth < 200; depth++, node = node.return) {
+    if (node === ancestor) return true;
+  }
+  return false;
+}
 function findInteractiveByIdentifier(query, options = {}) {
   const root = getFiberRoot();
   if (!root) {
@@ -460,6 +527,10 @@ function findInteractiveByIdentifier(query, options = {}) {
   let bestScore = 0;
   let bestHandle = null;
   let bestId;
+  let bestFiber = null;
+  let bestNamed = false;
+  let bestDisabled = false;
+  let tied = [];
   const visited = /* @__PURE__ */ new WeakSet();
   const stack = [];
   if (root.child) stack.push(root.child);
@@ -469,26 +540,52 @@ function findInteractiveByIdentifier(query, options = {}) {
     visited.add(fiber);
     if (fiber.sibling) stack.push(fiber.sibling);
     if (shouldSkipSubtree2(fiber)) continue;
+    const props = fiber.memoizedProps ?? {};
     let kind = null;
     if (matchesName(fiber, "TextInput")) kind = "field";
-    else if (matchesName(fiber, "Switch")) kind = "toggle";
+    else if (isSwitchLike(fiber, props)) kind = "toggle";
     else if (isPressableTarget(fiber)) kind = "target";
     if (kind && (!options.kind || options.kind === kind)) {
-      const score = scoreMatch(fiber, queryNorm, queryRaw);
-      if (score > bestScore) {
+      const detail = scoreMatchDetail(fiber, queryNorm, queryRaw);
+      const score = detail.score;
+      if (score > 0) {
+        if (score > bestScore) tied = [{ fiber, kind }];
+        else if (score === bestScore) tied.push({ fiber, kind });
+      }
+      const beatsBest = score > bestScore || score > 0 && score === bestScore && isDescendantOf(fiber, bestFiber);
+      if (beatsBest) {
         bestScore = score;
-        const props = fiber.memoizedProps ?? {};
-        bestId = props.testID ?? props.accessibilityLabel ?? props.placeholder ?? (kind === "target" ? findChildText(fiber) : void 0);
+        bestFiber = fiber;
+        bestNamed = detail.named;
+        bestDisabled = detail.disabled;
+        bestId = describeCandidate(fiber, kind);
         if (kind === "field") bestHandle = wrapTextInput(fiber);
         else if (kind === "toggle") bestHandle = wrapSwitch(fiber);
         else bestHandle = wrapTouchable(fiber, findChildText(fiber));
       }
     }
+    if (kind === "toggle") continue;
     if (fiber.child) stack.push(fiber.child);
   }
+  if (bestHandle && bestScore < (options.minScore ?? 0)) {
+    appilotsDebugLog(
+      `findInteractiveByIdentifier: query="${query}" \u2192 best match scored ${bestScore}, below the requested floor of ${options.minScore} \u2014 refusing it`
+    );
+    return null;
+  }
   if (bestHandle) {
+    const independent = tied.filter(
+      (candidate) => !tied.some(
+        (other) => other.fiber !== candidate.fiber && isDescendantOf(other.fiber, candidate.fiber)
+      )
+    );
+    bestHandle.matchCount = independent.length;
+    bestHandle.named = bestNamed;
+    bestHandle.disabled = bestDisabled;
+    const candidates = independent.map(({ fiber, kind }) => describeCandidate(fiber, kind)).filter((id) => typeof id === "string" && id.length > 0).slice(0, 8);
+    if (candidates.length > 0) bestHandle.matchCandidates = candidates;
     appilotsDebugLog(
-      `findInteractiveByIdentifier: query="${query}" \u2192 kind=${bestHandle.kind} label="${bestHandle.label ?? bestId}" score=${bestScore}`
+      `findInteractiveByIdentifier: query="${query}" \u2192 kind=${bestHandle.kind} label="${bestHandle.label ?? bestId}" score=${bestScore} named=${bestNamed} disabled=${bestDisabled} tied=${independent.length}`
     );
   } else {
     appilotsDebugLog(`findInteractiveByIdentifier: query="${query}" \u2192 no match`);
@@ -898,11 +995,27 @@ function pressResolvedListItem(list, itemFiber, listIndex, itemIndex) {
   const safeIdentifiableTouchables = identifiableTouchables.filter(
     (candidate) => !touchableLooksDestructive(candidate)
   );
+  const rowSwitches = findSwitchFibers(itemFiber);
+  if (rowSwitches.length > 0) {
+    const switchCandidates = rowSwitches.map(
+      (fiber, index) => describeTouchable(fiber) ?? `switch ${index + 1} of "list-${listIndex}-item-${itemIndex}" (role=toggle element)`
+    );
+    const pressCandidates = identifiableTouchables.map(describeTouchable).filter((d) => !!d);
+    return {
+      ok: false,
+      reason: "ambiguous-touchables",
+      refusal: "row-has-switch",
+      error: `Item "list-${listIndex}-item-${itemIndex}" contains a switch, so pressing the row would activate the row itself and leave the switch untouched. To flip the switch, emit ui_interaction action="toggle" on the row's role=toggle element id from VISIBLE STATE` + (pressCandidates.length > 0 ? "; to activate the row instead, use a specific pressable id from the candidates." : "."),
+      containerType: list.containerType,
+      candidates: [...switchCandidates, ...pressCandidates].slice(0, 8)
+    };
+  }
   if (identifiableTouchables.length > 0 && safeIdentifiableTouchables.length === 0) {
     const candidates = identifiableTouchables.map(describeTouchable).filter((d) => !!d).slice(0, 8);
     return {
       ok: false,
       reason: "ambiguous-touchables",
+      refusal: "destructive-only",
       error: `Item "list-${listIndex}-item-${itemIndex}" only exposes destructive controls. Use the specific button id from the row (for example the cancel button id) instead of pressing the list ordinal.`,
       containerType: list.containerType,
       candidates
@@ -1126,24 +1239,22 @@ function toggleListItemByIdentity(locator, options) {
   const props = target?.memoizedProps ?? {};
   const current = switchValue(props);
   if (options?.expected !== void 0 && current === options.expected) {
-    return { ok: true, containerType: list.containerType, value: current };
+    return { ok: true, containerType: list.containerType, value: current, noop: true };
   }
-  const onValueChange = props.onValueChange ?? props.onChange;
-  if (typeof onValueChange !== "function") {
-    return {
-      ok: false,
-      reason: "no-touchable",
-      error: "The row has a switch but it exposes no onValueChange handler.",
-      containerType: list.containerType
-    };
-  }
-  try {
-    onValueChange(!current);
-  } catch (err) {
+  const flipped = flipSwitchFiber(target, !current);
+  if (!flipped.ok) {
+    if (flipped.reason === "no-handler") {
+      return {
+        ok: false,
+        reason: "no-touchable",
+        error: `The row has a switch but it exposes no handler that could flip it (looked for ${SWITCH_FLIP_HANDLERS.join(", ")}).`,
+        containerType: list.containerType
+      };
+    }
     return {
       ok: false,
       reason: "press-threw",
-      error: err?.message ?? "switch handler threw",
+      error: flipped.error,
       containerType: list.containerType
     };
   }
@@ -1171,6 +1282,9 @@ function screenDiagnose(targetId, category = "component-not-found") {
 function isPressLike(action) {
   return action === "press" || action === "tap" || action === "click" || action === "longPress";
 }
+function isPlainPress(action) {
+  return action === "press" || action === "tap" || action === "click";
+}
 function isElementIdentifier(value) {
   return value.trim().toLowerCase().startsWith("el:");
 }
@@ -1281,6 +1395,54 @@ function dispatchRegisteredTarget(targetId, registry, action) {
     diagnose: screenDiagnose(targetId)
   };
 }
+function dispatchIdentifiedToggle(targetId, action) {
+  if (!isPressLike(action)) return null;
+  const winner = findInteractiveByIdentifier(targetId, { minScore: IDENTITY_MATCH_SCORE });
+  if (winner) {
+    if (winner.kind !== "toggle" || !winner.setValue) return null;
+    if ((winner.matchCount ?? 1) > 1) {
+      return {
+        success: false,
+        error: `"${targetId}" names ${winner.matchCount} controls on this screen \u2014 aim at one of the candidates instead`,
+        diagnose: {
+          ...screenDiagnose(targetId, "ambiguous-target"),
+          recoverable: true,
+          ...winner.matchCandidates && winner.matchCandidates.length > 0 ? { candidates: winner.matchCandidates } : {}
+        }
+      };
+    }
+    if (!isPlainPress(action)) {
+      if (winner.longPress?.()) return { success: true };
+      return {
+        success: false,
+        error: `"${targetId}" names a switch and it declares no long-press handler. Use action="toggle" to flip it.`,
+        diagnose: { ...screenDiagnose(targetId, "unknown"), recoverable: true }
+      };
+    }
+    appilotsDebugLog(
+      `elementDispatch: "${action}" on "${targetId}" names a switch \u2014 flipping it instead of pressing, so the verb cannot land on an ancestor`
+    );
+    try {
+      winner.setValue(!winner.getValue?.());
+      return { success: true, effect: "changed" };
+    } catch (err) {
+      return {
+        success: false,
+        error: err?.message ?? `Could not flip the switch named "${targetId}"`,
+        diagnose: screenDiagnose(targetId, "unknown")
+      };
+    }
+  }
+  const disabledToggle = findInteractiveByIdentifier(targetId, { kind: "toggle" });
+  if (disabledToggle?.named && disabledToggle.disabled) {
+    return {
+      success: false,
+      error: `The switch named "${targetId}" is currently disabled`,
+      diagnose: screenDiagnose(targetId, "disabled")
+    };
+  }
+  return null;
+}
 function dispatchFiberTarget(targetId, action) {
   const kind = action === "toggle" ? "toggle" : action === "focus" ? "field" : "target";
   const handle = findInteractiveByIdentifier(targetId, { kind });
@@ -1330,6 +1492,8 @@ function dispatchLegacyTarget(targetId, registry, action) {
   }
   const registered = dispatchRegisteredTarget(targetId, registry, action);
   if (registered.success) return registered;
+  const named = dispatchIdentifiedToggle(targetId, action);
+  if (named) return named;
   const fiber = dispatchFiberTarget(targetId, action);
   if (fiber.success) return fiber;
   return {
@@ -1346,6 +1510,9 @@ function dispatchElement(element, registry, action) {
       diagnose: screenDiagnose(element.id, "disabled")
     };
   }
+  if (element.role === "toggle" && (action === "toggle" || isPressLike(action))) {
+    return dispatchToggleElement(element, registry);
+  }
   if (element.listContext && isPressLike(action)) {
     const pressed = pressListItemByIdentity({
       ...element.listContext,
@@ -1354,6 +1521,18 @@ function dispatchElement(element, registry, action) {
       texts: element.texts
     });
     if (pressed.ok) return { success: true };
+    if (pressed.refusal) {
+      return {
+        success: false,
+        error: pressed.error ?? `Could not press element "${element.id}" (${pressed.reason})`,
+        diagnose: {
+          ...screenDiagnose(element.id),
+          category: "ambiguous-target",
+          recoverable: true,
+          ...pressed.candidates && pressed.candidates.length > 0 ? { candidates: pressed.candidates } : {}
+        }
+      };
+    }
     if (element.targetId && element.targetId !== element.id) {
       const fallback = dispatchLegacyTarget(element.targetId, registry, action);
       if (fallback.success) return fallback;
@@ -1385,50 +1564,6 @@ function dispatchElement(element, registry, action) {
       diagnose: { ...screenDiagnose(element.id, "unknown"), recoverable: true }
     };
   }
-  if (element.role === "toggle" && (action === "toggle" || isPressLike(action))) {
-    if (element.listContext) {
-      const toggled = toggleListItemByIdentity(
-        {
-          listIndex: element.listContext.listIndex,
-          listId: element.listContext.listId,
-          listLabel: element.listContext.listLabel,
-          itemIndex: element.listContext.itemIndex,
-          itemKey: element.listContext.itemKey,
-          reactKey: element.listContext.reactKey,
-          syntheticId: element.listContext.syntheticId,
-          label: element.label,
-          texts: element.texts
-        },
-        // The observation's `selected` is the state BEFORE this action.
-        // Passing the desired end state makes the flip idempotent: a
-        // retry or a recovery hop must not undo the work and call it
-        // success. A toggle only knows how to invert, so without this the
-        // second attempt silently returns the row to where it started.
-        typeof element.selected === "boolean" ? { expected: !element.selected } : void 0
-      );
-      if (toggled.ok) {
-        return {
-          success: true,
-          // Grounded: read back off the fiber after the handler ran, not
-          // inferred from "the call did not throw".
-          effect: "changed"
-        };
-      }
-      return {
-        success: false,
-        error: toggled.error ?? `Could not flip the switch in row "${element.label ?? element.id}" (${toggled.reason})`,
-        diagnose: {
-          ...screenDiagnose(
-            element.id,
-            toggled.reason === "ambiguous-touchables" || toggled.reason === "ambiguous-items" ? "ambiguous-target" : "component-not-found"
-          ),
-          ...toggled.candidates && toggled.candidates.length > 0 ? { candidates: toggled.candidates } : {}
-        }
-      };
-    }
-    const targetId = element.targetId ?? element.label ?? element.id;
-    return dispatchLegacyTarget(targetId, registry, "toggle");
-  }
   if (element.role === "input" && (action === "focus" || isPressLike(action))) {
     const targetId = element.targetId ?? element.label ?? element.id;
     return dispatchLegacyTarget(targetId, registry, "focus");
@@ -1443,6 +1578,54 @@ function dispatchElement(element, registry, action) {
     diagnose: screenDiagnose(element.id, "unknown")
   };
 }
+function dispatchToggleElement(element, registry) {
+  if (element.listContext) {
+    const toggled = toggleListItemByIdentity(
+      {
+        listIndex: element.listContext.listIndex,
+        listId: element.listContext.listId,
+        listLabel: element.listContext.listLabel,
+        itemIndex: element.listContext.itemIndex,
+        itemKey: element.listContext.itemKey,
+        reactKey: element.listContext.reactKey,
+        syntheticId: element.listContext.syntheticId,
+        label: element.label,
+        texts: element.texts
+      },
+      // The observation's `selected` is the state BEFORE this action.
+      // Passing the desired end state makes the flip idempotent: a
+      // retry or a recovery hop must not undo the work and call it
+      // success. A toggle only knows how to invert, so without this the
+      // second attempt silently returns the row to where it started.
+      typeof element.selected === "boolean" ? { expected: !element.selected } : void 0
+    );
+    if (toggled.ok) {
+      return {
+        success: true,
+        // Honest split (#504): a real flip is 'changed'; the idempotent
+        // no-op — the switch already held the requested state, nothing
+        // was touched — is 'completed' (goal state verified), NEVER
+        // 'changed' (nothing changed this hop) and NEVER 'none' (which
+        // would send recovery re-flipping a switch that is already
+        // right).
+        effect: toggled.noop ? "completed" : "changed"
+      };
+    }
+    return {
+      success: false,
+      error: toggled.error ?? `Could not flip the switch in row "${element.label ?? element.id}" (${toggled.reason})`,
+      diagnose: {
+        ...screenDiagnose(
+          element.id,
+          toggled.reason === "ambiguous-touchables" || toggled.reason === "ambiguous-items" ? "ambiguous-target" : "component-not-found"
+        ),
+        ...toggled.candidates && toggled.candidates.length > 0 ? { candidates: toggled.candidates } : {}
+      }
+    };
+  }
+  const targetId = element.targetId ?? element.label ?? element.id;
+  return dispatchLegacyTarget(targetId, registry, "toggle");
+}
 function dispatchStructuredElementId(identifier, action) {
   if (!isElementIdentifier(identifier) || !isPressLike(action)) return null;
   const parsed = parseStableElementId(identifier);
@@ -1469,6 +1652,8 @@ function dispatchElementOrTarget(identifier, registry, action = "press") {
     if (result.success) return result;
     if (result.diagnose?.category === "disabled") return result;
     if (element.role === "slider") return result;
+    if (element.role === "toggle") return result;
+    if (result.diagnose?.category === "ambiguous-target") return result;
   }
   const structured = dispatchStructuredElementId(identifier, action);
   if (structured?.success) return structured;
@@ -2207,7 +2392,6 @@ function uiInteractionHandler(payload, context) {
       appilotsDebugLog(
         `uiInteractionHandler: interaction element dispatch succeeded for "${rawComponentId}"`
       );
-      return { success: true };
     }
     return result;
   }
@@ -2239,12 +2423,12 @@ function uiInteractionHandler(payload, context) {
       };
     }
     if (result.reason === "ambiguous-touchables") {
-      const isDestructiveOnly = /only exposes destructive controls/i.test(result.error ?? "");
+      const namesConcreteChoice = result.refusal !== void 0 || /only exposes destructive controls|contains a switch/i.test(result.error ?? "");
       return {
         success: false,
         error: result.error ?? `Synthetic list ordinal press failed (${result.reason ?? "unknown"})`,
         diagnose: {
-          category: isDestructiveOnly ? "ambiguous-target" : "unknown",
+          category: namesConcreteChoice ? "ambiguous-target" : "unknown",
           targetId: rawComponentId,
           screen,
           recoverable: true,
@@ -2320,6 +2504,8 @@ function uiInteractionHandler(payload, context) {
   appilotsDebugLog(
     `uiInteractionHandler: registry miss for "${componentId}", falling back to fiber tree`
   );
+  const namedToggle = dispatchIdentifiedToggle(componentId, actionStr);
+  if (namedToggle) return namedToggle;
   const handle = findInteractiveByIdentifier(componentId, {
     kind: actionStr === "toggle" ? "toggle" : actionStr === "focus" ? "field" : "target"
   });
@@ -2332,10 +2518,6 @@ function uiInteractionHandler(payload, context) {
         );
         return { success: true };
       }
-      if (actionStr === "press" && handle.kind === "toggle" && handle.setValue) {
-        handle.setValue(!handle.getValue?.());
-        return { success: true };
-      }
       if (actionStr === "toggle" && handle.kind === "toggle" && handle.setValue) {
         handle.setValue(!handle.getValue?.());
         return { success: true };
@@ -3217,6 +3399,14 @@ async function formFillHandler(payload, context) {
     allSuccess = false;
   }
   if (payload.submitAfterFill === true) {
+    if (!permissions.canSubmitForms) {
+      return {
+        success: false,
+        error: "Form submission is not permitted",
+        fieldResults,
+        diagnose: { category: "unknown", screen: screenPath }
+      };
+    }
     if (!allSuccess) {
       const failedIds = fieldResults.filter((result) => !result.success).map((result) => result.fieldId);
       appilotsDebugWarn(
@@ -3224,6 +3414,9 @@ async function formFillHandler(payload, context) {
       );
     } else {
       await sleep2(120);
+      if (!permissions.canSubmitForms) {
+        return { success: false, error: "Form submission is not permitted", fieldResults };
+      }
       const submitResult = pressSubmitButton(
         {
           screen,
@@ -3529,6 +3722,59 @@ async function confirmHandler(_actionId, _payload) {
   return { success: true, effect: "unknown" };
 }
 
+// src/platform/asyncBudget.ts
+var POST_ACTION_LOADING_MAX_MS = 6e3;
+var INFERRED_ASYNC_LOADING_MAX_MS = 1e4;
+var POST_NAVIGATE_LOADING_MAX_MS = 3e3;
+var MAX_DECLARED_ASYNC_BUDGET_MS = 12e4;
+var ASYNC_BUSY_CEILING_MS = MAX_DECLARED_ASYNC_BUDGET_MS;
+function declaredBudgetMs(hints) {
+  const declared = hints?.asyncBudgetMs;
+  if (typeof declared !== "number" || !Number.isFinite(declared) || declared <= 0) return void 0;
+  return Math.min(declared, MAX_DECLARED_ASYNC_BUDGET_MS);
+}
+function resolveSettleCapMs(hints) {
+  const declared = declaredBudgetMs(hints);
+  if (declared !== void 0) return declared;
+  return hints?.isAsyncTrigger === true ? INFERRED_ASYNC_LOADING_MAX_MS : POST_ACTION_LOADING_MAX_MS;
+}
+function resolveBusyCeilingMs(hints) {
+  return declaredBudgetMs(hints) === void 0 ? ASYNC_BUSY_CEILING_MS : void 0;
+}
+function resolvePostNavigateCapMs(hints) {
+  return Math.max(POST_NAVIGATE_LOADING_MAX_MS, declaredBudgetMs(hints) ?? 0);
+}
+function resolveActionHints(screen, pressedComponentId, actionPayload) {
+  if (actionPayload && typeof actionPayload === "object") {
+    const payload = actionPayload;
+    const inline = payload._appilotsInferred;
+    const declared = payload._appilotsAsyncBudgetMs;
+    if (inline && typeof inline === "object") {
+      const hints = { ...inline };
+      if (typeof declared === "number") hints.asyncBudgetMs = declared;
+      return hints;
+    }
+    if (typeof declared === "number") return { asyncBudgetMs: declared };
+  }
+  if (!screen || !pressedComponentId) return void 0;
+  const meta = getScreenMetadata(screen);
+  const actions = meta?.actions;
+  if (!actions || actions.length === 0) return void 0;
+  for (const a of actions) {
+    if (typeof a === "string") continue;
+    if (idLooselyMatches(a.id, pressedComponentId)) {
+      const inferred = a.appilotsInferred;
+      const declared = a.asyncBudgetMs;
+      const hints = {
+        ...inferred && typeof inferred === "object" ? inferred : {},
+        ...typeof declared === "number" ? { asyncBudgetMs: declared } : {}
+      };
+      return Object.keys(hints).length > 0 ? hints : void 0;
+    }
+  }
+  return void 0;
+}
+
 // src/executor/postInteractionSettle.ts
 var sleepMs = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 function targetIdFromPayload(payload) {
@@ -3577,7 +3823,8 @@ async function waitForPostInteractionSettle(payload) {
     if (discreteFieldSignature() !== baselineFields) return { effect: "changed" };
     return { effect: settled.fingerprint !== baseline.fingerprint ? "changed" : "none" };
   };
-  const capMs = isListItemPressTarget(targetId) ? 5e3 : 1e4;
+  const declared = declaredBudgetMs(resolveActionHints(fromScreen, targetId || null, payload));
+  const capMs = declared ?? (isListItemPressTarget(targetId) ? 5e3 : 1e4);
   if (modalOrLoading || fingerprintChanged) {
     await waitForLoadingSettle({
       pressedComponentId: targetId || null,
@@ -3874,7 +4121,7 @@ async function runWithConfirmedDestructiveContext(enabled, host, fn) {
 }
 
 // src/platform/reactNativeAdapter.ts
-var POST_ACTION_LOADING_MAX_MS = 6e3;
+var deltaTracker = createSnapshotDeltaTracker();
 function resolveScreenMetadata() {
   const activePath = getActiveRouteNames();
   for (let i = activePath.length - 1; i >= 0; i--) {
@@ -3888,6 +4135,7 @@ function resolveScreenMetadata() {
   return screen ? getScreenMetadata(screen) : void 0;
 }
 function buildAgentContext(extras = {}) {
+  if (extras.newMission === true) deltaTracker.reset();
   const context = {};
   context.platform = "react-native";
   const screen = getCurrentScreen();
@@ -3897,7 +4145,10 @@ function buildAgentContext(extras = {}) {
   const screenMeta = resolveScreenMetadata();
   if (screenMeta) context.screenMetadata = screenMeta;
   try {
-    context.snapshot = captureSnapshot();
+    const snapshot = captureSnapshot();
+    const delta = deltaTracker.observe(snapshot);
+    if (delta) snapshot.delta = delta;
+    context.snapshot = snapshot;
   } catch (err) {
     appilotsDebugWarn("buildAgentContext: captureSnapshot failed", err);
   }
@@ -3913,33 +4164,21 @@ function buildAgentContext(extras = {}) {
   if (extras.loadingPending === true) context.loadingPending = true;
   return context;
 }
-function resolveActionHints(screen, pressedComponentId, actionPayload) {
-  if (actionPayload && typeof actionPayload === "object") {
-    const inline = actionPayload._appilotsInferred;
-    if (inline && typeof inline === "object") {
-      return inline;
-    }
-  }
-  if (!screen || !pressedComponentId) return void 0;
-  const meta = getScreenMetadata(screen);
-  const actions = meta?.actions;
-  if (!actions || actions.length === 0) return void 0;
-  for (const a of actions) {
-    if (typeof a === "string") continue;
-    if (idLooselyMatches(a.id, pressedComponentId)) {
-      const inferred = a.appilotsInferred;
-      if (inferred && typeof inferred === "object") return inferred;
-      return void 0;
-    }
-  }
-  return void 0;
-}
 async function settleTurn(input) {
   const toolWithoutEffectIds = /* @__PURE__ */ new Set();
   let loadingPending = false;
   const { turnActions, pressedComponentId: pressedId, navigateTargetScreen } = input;
   const successById = new Map(input.results.map((r) => [r.actionId, r.success]));
   const typeById = new Map(input.results.map((r) => [r.actionId, r.type]));
+  const pressedAction = turnActions.find(
+    (a) => a.type === "ui_interaction" && a.payload?.componentId === pressedId
+  );
+  const hints = resolveActionHints(
+    getCurrentScreen(),
+    pressedId,
+    pressedAction?.payload
+  );
+  const capSource = typeof hints?.asyncBudgetMs === "number" && hints.asyncBudgetMs > 0 ? " (app-declared)" : hints?.isAsyncTrigger ? " (mcp-inferred)" : "";
   if (input.hadNavigate) {
     const settle = await waitForScreenSettle({
       expectingChange: true,
@@ -3960,27 +4199,26 @@ async function settleTurn(input) {
         if (type === "navigate") toolWithoutEffectIds.add(actionId);
       }
     }
+    const postNavigateCapMs = resolvePostNavigateCapMs(hints);
     const loadSettle = await waitForLoadingSettle({
       fromScreen: settle.screen ?? null,
-      maxMs: 3e3
+      maxMs: postNavigateCapMs
     });
     appilotsDebugLog(
-      `settleTurn: post-navigate loading settle \u2014 settled=${loadSettle.settled} loadingPending=${loadSettle.loadingPending} probes=${loadSettle.probeCount} waitedMs=${loadSettle.waitedMs}`
+      `settleTurn: post-navigate loading settle \u2014 settled=${loadSettle.settled} loadingPending=${loadSettle.loadingPending} probes=${loadSettle.probeCount} waitedMs=${loadSettle.waitedMs} cap=${postNavigateCapMs}${capSource}`
     );
     if (loadSettle.loadingPending) loadingPending = true;
   } else {
-    const pressedAction = turnActions.find(
-      (a) => a.type === "ui_interaction" && a.payload?.componentId === pressedId
-    );
-    const hints = resolveActionHints(getCurrentScreen(), pressedId, pressedAction?.payload);
-    const settleCapMs = hints?.isAsyncTrigger === true ? 1e4 : POST_ACTION_LOADING_MAX_MS;
+    const settleCapMs = resolveSettleCapMs(hints);
+    const busyMaxMs = resolveBusyCeilingMs(hints);
     const loadSettle = await waitForLoadingSettle({
       pressedComponentId: pressedId,
       fromScreen: getCurrentScreen(),
-      maxMs: settleCapMs
+      maxMs: settleCapMs,
+      ...busyMaxMs !== void 0 ? { busyMaxMs } : {}
     });
     appilotsDebugLog(
-      `settleTurn: post-action loading settle \u2014 pressedId="${pressedId ?? ""}" settled=${loadSettle.settled} transitioned=${loadSettle.transitioned} loadingPending=${loadSettle.loadingPending} probes=${loadSettle.probeCount} waitedMs=${loadSettle.waitedMs} cap=${settleCapMs}${hints?.isAsyncTrigger ? " (mcp-inferred)" : ""}`
+      `settleTurn: post-action loading settle \u2014 pressedId="${pressedId ?? ""}" settled=${loadSettle.settled} transitioned=${loadSettle.transitioned} loadingPending=${loadSettle.loadingPending} probes=${loadSettle.probeCount} waitedMs=${loadSettle.waitedMs} cap=${settleCapMs}${capSource}${busyMaxMs !== void 0 ? ` busyCap=${busyMaxMs}` : ""}`
     );
     if (loadSettle.loadingPending) loadingPending = true;
     const listPressActions = turnActions.filter((action) => {