visor-ai 0.2.8 → 0.2.9

package/dist/appMap.js

@@ -22,6 +22,10 @@ const RISKY_WORDS = [
 ];
 const INPUT_WORDS = ['password', 'email', 'username', 'search', 'input', 'text field', 'textfield'];
 const AUTH_WORDS = ['login', 'log in', 'sign in', 'password', 'username', 'auth', 'authentication'];
+const DEFAULT_ACTION_SETTLE_MS = 400;
+const DEFAULT_ACTION_SETTLE_POLL_MS = 400;
+const DEFAULT_CRAWL_SETTLE_MS = 1500;
+const DEFAULT_CRAWL_SETTLE_POLL_MS = 300;
 function envNoMap() {
     const raw = process.env.VISOR_NO_MAP ?? process.env.VISOR_DISABLE_MAP;
     return ['1', 'true', 'yes', 'on'].includes(String(raw ?? '').trim().toLowerCase());
@@ -33,9 +37,21 @@ function resolveOptions(platform, options) {
         rootDir: options?.rootDir ?? process.env.VISOR_APP_MAP_DIR ?? path.join(process.cwd(), '.visor', 'maps'),
         appId: options?.appId ?? `default-${platform}`,
         repairDepth: options?.repairDepth ?? 2,
-        repairTimeoutMs: options?.repairTimeoutMs ?? 30000
+        repairTimeoutMs: options?.repairTimeoutMs ?? 30000,
+        repair: options?.repair === true,
+        crawl: options?.crawl === true,
+        crawlDepth: options?.crawlDepth ?? 2,
+        crawlLimit: options?.crawlLimit ?? 24,
+        crawlSettleMs: nonNegativeNumber(options?.crawlSettleMs, DEFAULT_CRAWL_SETTLE_MS),
+        crawlSettlePollMs: positiveNumber(options?.crawlSettlePollMs, DEFAULT_CRAWL_SETTLE_POLL_MS)
     };
 }
+function nonNegativeNumber(value, defaultValue) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : defaultValue;
+}
+function positiveNumber(value, defaultValue) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : defaultValue;
+}
 function mapIdentity(platform, appId) {
     return `${platform}:${appId}`;
 }
@@ -67,8 +83,15 @@ function readMap(filePath, platform, appId) {
             return { map: newMap(platform, appId), scrubbed: false };
         }
         const originalEdgeCount = parsed.edges.length;
+        let enrichedActions = false;
+        for (const variant of parsed.variants) {
+            if (!Array.isArray(variant.actions)) {
+                variant.actions = actionAffordancesForElements(variant.elements);
+                enrichedActions = true;
+            }
+        }
         parsed.edges = parsed.edges.filter((edge) => !isValueBearingAction(edge.command, edge.args));
-        return { map: parsed, scrubbed: parsed.edges.length !== originalEdgeCount };
+        return { map: parsed, scrubbed: parsed.edges.length !== originalEdgeCount || enrichedActions };
     }
     catch {
         return { map: newMap(platform, appId), scrubbed: false };
@@ -130,10 +153,20 @@ function attributeMap(input) {
     const attrs = {};
     const pattern = /([A-Za-z_:][-A-Za-z0-9_:.]*)\s*=\s*("([^"]*)"|'([^']*)')/g;
     for (const match of input.matchAll(pattern)) {
-        attrs[match[1]] = match[3] ?? match[4] ?? '';
+        attrs[match[1]] = decodeXmlEntities(match[3] ?? match[4] ?? '');
     }
     return attrs;
 }
+function decodeXmlEntities(value) {
+    return value
+        .replace(/&#x([0-9a-f]+);/gi, (_, hex) => String.fromCodePoint(Number.parseInt(hex, 16)))
+        .replace(/&#(\d+);/g, (_, decimal) => String.fromCodePoint(Number.parseInt(decimal, 10)))
+        .replace(/"/g, '"')
+        .replace(/'/g, "'")
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&amp;/g, '&');
+}
 function normalizeLabel(value) {
     return value
         .replace(/[0-9a-f]{8,}/gi, '<id>')
@@ -146,6 +179,40 @@ function normalizeLabel(value) {
 function unique(values) {
     return Array.from(new Set(values.filter((value) => value.trim() !== '')));
 }
+function isScrollableTag(tag) {
+    const normalized = tag.toLowerCase();
+    return (normalized.includes('scrollview') ||
+        normalized.includes('scroll') ||
+        normalized.includes('list') ||
+        normalized.includes('table'));
+}
+function attrBool(attrs, key, defaultValue) {
+    const raw = attrs[key];
+    if (raw === undefined) {
+        return defaultValue;
+    }
+    return raw.trim().toLowerCase() === 'true';
+}
+function attrNumber(attrs, key) {
+    const parsed = Number(attrs[key]);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function expandSemanticLabels(labels) {
+    return labels.flatMap((label) => {
+        const lines = unique(label.split(/\n+/).map((line) => line.trim()));
+        if (lines.length === 1 && lines[0] !== label) {
+            return [label, lines[0]];
+        }
+        if (lines.length > 1 && label.split(/\n+/).filter((line) => line.trim() !== '').every((line) => line.trim() === lines[0])) {
+            return [label, lines[0]];
+        }
+        const rawLines = label.split(/\n+/).map((line) => line.trim()).filter(Boolean);
+        if (rawLines.length >= 3 && rawLines[0] === rawLines[rawLines.length - 1]) {
+            return [label, rawLines[0]];
+        }
+        return [label];
+    });
+}
 function isLikelyFormControl(tag, attrs) {
     const haystack = [
         tag,
@@ -172,6 +239,19 @@ function isLikelyFormControl(tag, attrs) {
         'card'
     ].some((word) => haystack.includes(word));
 }
+function structuralElementTarget(tag, attrs) {
+    if (!isScrollableTag(tag)) {
+        return '';
+    }
+    return [
+        'scroll-container',
+        tag,
+        attrs.x ?? '',
+        attrs.y ?? '',
+        attrs.width ?? '',
+        attrs.height ?? ''
+    ].join('=');
+}
 function redactLabel(value) {
     return value
         .replace(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi, '<redacted-email>')
@@ -202,7 +282,7 @@ function extractElements(source) {
         const attrs = attributeMap(match[2] ?? '');
         const bodyText = (match[3] ?? '').trim();
         const formControl = isLikelyFormControl(tag, attrs);
-        const rawLabels = unique([
+        const rawLabels = unique(expandSemanticLabels([
             redactLabel(attrs.name ?? ''),
             redactLabel(attrs.label ?? ''),
             formControl ? '' : redactLabel(attrs.text ?? ''),
@@ -210,17 +290,19 @@ function extractElements(source) {
             redactLabel(attrs['content-desc'] ?? ''),
             redactLabel(attrs['contentDescription'] ?? ''),
             formControl ? '' : redactLabel(bodyText)
-        ]);
+        ]));
         const id = attrs['resource-id'] ?? attrs.id ?? attrs.identifier ?? '';
+        const structuralTarget = structuralElementTarget(tag, attrs);
         const targets = unique([
             ...rawLabels,
             ...rawLabels.map((label) => `text=${label}`),
-            id ? `id=${id}` : ''
+            id ? `id=${id}` : '',
+            structuralTarget
         ]);
         if (targets.length === 0) {
             continue;
         }
-        const stable = Boolean(rawLabels.length > 0 || id);
+        const stable = Boolean(rawLabels.length > 0 || id || structuralTarget);
         const selector = id ? `id=${id}` : rawLabels[0] ?? targets[0];
         elements.push({
             tag,
@@ -228,7 +310,14 @@ function extractElements(source) {
             targets,
             labels: rawLabels,
             stable,
-            safety: classifyControl(tag, rawLabels, attrs)
+            safety: classifyControl(tag, rawLabels, attrs),
+            enabled: attrBool(attrs, 'enabled', true),
+            visible: attrBool(attrs, 'visible', true),
+            clickable: attrBool(attrs, 'clickable', false),
+            x: attrNumber(attrs, 'x'),
+            y: attrNumber(attrs, 'y'),
+            width: attrNumber(attrs, 'width'),
+            height: attrNumber(attrs, 'height')
         });
     }
     return elements;
@@ -263,14 +352,49 @@ function similarity(left, right) {
     const containment = smaller === 0 ? 0 : intersection / smaller;
     return containment >= 0.8 ? Math.max(jaccard, containment) : jaccard;
 }
-function elementIdentityKeys(elements) {
+function identityKeys(elements, includeStatic) {
+    const navigationElements = new Set(navigationControlsForElements(elements).map((control) => control.element));
     return unique(elements.flatMap((element) => {
+        if (navigationElements.has(element)) {
+            return [];
+        }
         const tag = element.tag.toLowerCase();
-        const labels = element.labels.map(normalizeLabel);
+        if (!includeStatic && isStaticIdentityElement(element)) {
+            return [];
+        }
+        const labels = element.labels
+            .filter((label) => !isGlobalIdentityLabel(label, element))
+            .map(normalizeLabel);
         const ids = element.targets.filter((target) => target.startsWith('id=')).map(normalizeLabel);
         return [...labels, ...ids].map((value) => `${tag}:${element.safety}:${value}`);
     })).sort();
 }
+function isStaticIdentityElement(element) {
+    const tag = element.tag.toLowerCase();
+    return element.safety === 'unknown' || tag.includes('statictext') || tag.includes('image') || isScrollableTag(tag);
+}
+function screenSimilarity(left, right) {
+    const leftControlKeys = identityKeys(left, false);
+    const rightControlKeys = identityKeys(right, false);
+    const fullScore = similarity(identityKeys(left, true), identityKeys(right, true));
+    if (leftControlKeys.length === 0 && rightControlKeys.length === 0) {
+        return fullScore;
+    }
+    return Math.max(fullScore, similarity(leftControlKeys, rightControlKeys));
+}
+function isGlobalIdentityLabel(label, element) {
+    const normalized = normalizeControlTarget(label);
+    if (isBundleLikeLabel(normalized)) {
+        return true;
+    }
+    if (['settings settings', 'notifications notifications'].includes(normalized)) {
+        return true;
+    }
+    return false;
+}
+function isBundleLikeLabel(normalized) {
+    return /^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*){2,}$/.test(normalized);
+}
 function newVariant(map, observation) {
     const screen = {
         id: `screen_${map.screens.length + 1}`,
@@ -283,6 +407,7 @@ function newVariant(map, observation) {
         normalized_fingerprint: observation.normalized_fingerprint,
         elements: observation.elements,
         element_keys: observation.element_keys,
+        actions: actionAffordancesForElements(observation.elements),
         auth_required: observation.auth_required,
         observations: 1,
         confidence: 0.6,
@@ -296,16 +421,38 @@ function newVariant(map, observation) {
 function upsertVariant(map, observation) {
     let best = null;
     let bestScore = 0;
+    const observedNavigationTarget = preferredNavigationTargetForElements(observation.elements);
+    const observedHasBottomNavigation = navigationControlsForElements(observation.elements).length >= 2;
+    const observedHasScrollableSurface = elementsHaveScrollableSurface(observation.elements);
+    const observedControlKeys = identityKeys(observation.elements, false);
     for (const variant of map.variants) {
+        const variantNavigationTarget = preferredNavigationTarget(variant);
+        if (observedNavigationTarget &&
+            variantNavigationTarget &&
+            observedNavigationTarget !== variantNavigationTarget) {
+            continue;
+        }
+        if (observedHasScrollableSurface || hasScrollableSurface(variant)) {
+            const variantControlKeys = identityKeys(variant.elements, false);
+            if ((observedControlKeys.length > 0 || variantControlKeys.length > 0) &&
+                similarity(observedControlKeys, variantControlKeys) < 0.3) {
+                continue;
+            }
+        }
         const score = variant.normalized_fingerprint === observation.normalized_fingerprint
             ? 1
-            : similarity(elementIdentityKeys(variant.elements), elementIdentityKeys(observation.elements));
+            : screenSimilarity(variant.elements, observation.elements);
         if (score > bestScore) {
             best = variant;
             bestScore = score;
         }
     }
-    if (!best || bestScore < 0.45) {
+    const requiredScore = observedHasBottomNavigation || (best ? hasBottomNavigation(best) : false)
+        ? 0.62
+        : observedHasScrollableSurface || (best ? hasScrollableSurface(best) : false)
+            ? 0.62
+            : 0.45;
+    if (!best || bestScore < requiredScore) {
         return {
             observation,
             variant: newVariant(map, observation),
@@ -316,6 +463,7 @@ function upsertVariant(map, observation) {
     best.normalized_fingerprint = observation.normalized_fingerprint;
     best.elements = observation.elements;
     best.element_keys = observation.element_keys;
+    best.actions = actionAffordancesForElements(observation.elements);
     best.auth_required = observation.auth_required;
     best.observations += 1;
     best.confidence = Math.min(1, best.confidence + 0.05);
@@ -326,7 +474,7 @@ function upsertVariant(map, observation) {
         created: false
     };
 }
-async function observeCurrentScreen(context) {
+async function captureCurrentSource(context) {
     const sourceDir = ensureDir(path.join(os.tmpdir(), 'visor-app-map-source'));
     const sourcePath = path.join(sourceDir, `${process.pid}-${Date.now()}-${randomUUID()}.xml`);
     const details = await context.adapter.source({ label: 'app-map-source', path: sourcePath });
@@ -344,10 +492,143 @@ async function observeCurrentScreen(context) {
     catch {
         // Source observations are transient; stale temp files should not fail a run.
     }
-    const observed = upsertVariant(context.map, observeSource(source));
+    return { source };
+}
+function isTransientObservation(observation) {
+    return observation.elements.length === 0 || observation.element_keys.length === 0;
+}
+async function captureCurrentObservation(context) {
+    let observation = null;
+    for (let attempt = 0; attempt < 5; attempt += 1) {
+        const captured = await captureCurrentSource(context);
+        observation = observeSource(captured.source);
+        if (!isTransientObservation(observation) || attempt === 4) {
+            break;
+        }
+        await delay(500);
+    }
+    return observation ?? observeSource('');
+}
+function observeScreenObservation(context, observation) {
+    const observed = upsertVariant(context.map, observation);
     context.changed = true;
     return observed;
 }
+async function observeCurrentScreen(context) {
+    return observeScreenObservation(context, await captureCurrentObservation(context));
+}
+async function observeAfterAction(context, target, options = {}) {
+    const observed = await observeCurrentScreen(context);
+    if (target && restoreMatch(observed, target)) {
+        return observed;
+    }
+    if (!shouldSettleObservation(observed.observation)) {
+        return observed;
+    }
+    const settleMs = nonNegativeNumber(options.settleMs, DEFAULT_ACTION_SETTLE_MS);
+    if (settleMs === 0) {
+        return observed;
+    }
+    const pollMs = positiveNumber(options.pollMs, DEFAULT_ACTION_SETTLE_POLL_MS);
+    let best = observed;
+    let previous = observed;
+    let elapsed = 0;
+    while (elapsed < settleMs) {
+        const waitMs = Math.min(pollMs, settleMs - elapsed);
+        await settleDelay(context, waitMs);
+        elapsed += waitMs;
+        let next;
+        try {
+            next = await observeCurrentScreen(context);
+        }
+        catch {
+            return best;
+        }
+        if (target && restoreMatch(next, target)) {
+            return next;
+        }
+        if (isRicherObservation(next.observation, best.observation)) {
+            best = next;
+        }
+        if (next.observation.fingerprint === previous.observation.fingerprint && !shouldSettleObservation(next.observation)) {
+            return isRicherObservation(next.observation, best.observation) ? next : best;
+        }
+        previous = next;
+    }
+    return best;
+}
+async function observeAfterCrawlAction(context) {
+    const observation = await captureCurrentObservation(context);
+    const settled = await settleCrawlObservation(context, observation);
+    return observeScreenObservation(context, settled);
+}
+async function settleCrawlObservation(context, observation) {
+    const settleMs = context.options.crawlSettleMs;
+    if (settleMs === 0) {
+        return observation;
+    }
+    const pollMs = context.options.crawlSettlePollMs;
+    let best = observation;
+    let previous = observation;
+    let elapsed = 0;
+    while (elapsed < settleMs) {
+        const waitMs = Math.min(pollMs, settleMs - elapsed);
+        await settleDelay(context, waitMs);
+        elapsed += waitMs;
+        let next;
+        try {
+            next = await captureCurrentObservation(context);
+        }
+        catch {
+            return best;
+        }
+        if (isRicherObservation(next, best)) {
+            best = next;
+        }
+        if (next.fingerprint === previous.fingerprint && !shouldSettleObservation(next)) {
+            return isRicherObservation(next, best) ? next : best;
+        }
+        previous = next;
+    }
+    return best;
+}
+async function settleDelay(context, ms) {
+    if (ms <= 0) {
+        return;
+    }
+    try {
+        await context.adapter.wait({ ms, label: 'app-map-settle' });
+    }
+    catch {
+        await delay(ms);
+    }
+}
+function isRicherObservation(candidate, current) {
+    if (isTransientObservation(current) && !isTransientObservation(candidate)) {
+        return true;
+    }
+    if (isTransientObservation(candidate)) {
+        return false;
+    }
+    const candidateScore = observationRichness(candidate);
+    const currentScore = observationRichness(current);
+    return candidateScore > currentScore;
+}
+function observationRichness(observation) {
+    const stableControls = observation.elements.filter((element) => element.stable && element.visible !== false && element.safety === 'safe').length;
+    return observation.element_keys.length + observation.elements.length * 2 + stableControls * 3;
+}
+function shouldSettleObservation(observation) {
+    if (isTransientObservation(observation)) {
+        return true;
+    }
+    const labels = observation.elements.flatMap((element) => element.labels.map(normalizeControlTarget));
+    const hasTransitionLabel = labels.some((label) => /\b(loading|syncing|refreshing|please wait|progress)\b/.test(label));
+    return hasTransitionLabel && observation.elements.length <= 3;
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function targetDescriptor(command, args) {
     if (isValueBearingAction(command, args)) {
         return { kind: 'unknown', confidence: 0 };
@@ -355,17 +636,26 @@ function targetDescriptor(command, args) {
     if (command === 'tap') {
         try {
             if (resolveTapMode(args) === 'coordinates') {
-                return { kind: 'coordinate', confidence: 0 };
+                return { kind: 'coordinate', target: coordinateTarget(args), confidence: 0.5 };
             }
         }
         catch {
             return { kind: 'unknown', confidence: 0 };
         }
     }
+    if (command === 'scroll') {
+        return { kind: 'stable', target: scrollTarget(args), confidence: 0.4 };
+    }
     const target = typeof args.target === 'string' ? args.target : undefined;
     if (!target) {
         return { kind: 'unknown', confidence: 0 };
     }
+    if (target.startsWith('first-in-section=')) {
+        return { kind: 'section-first', target, value: target.slice(17), confidence: 0.55 };
+    }
+    if (target.startsWith('text~=')) {
+        return { kind: 'text-contains', target, value: target.slice(6), confidence: 0.45 };
+    }
     if (target.startsWith('text=')) {
         return { kind: 'text', target, value: target.slice(5), confidence: 0.6 };
     }
@@ -374,30 +664,75 @@ function targetDescriptor(command, args) {
     }
     return { kind: 'stable', target, value: target.replace(/^(id=|accessibility=)/, ''), confidence: 0.9 };
 }
+function coordinateTarget(args) {
+    const x = Number(args.x);
+    const y = Number(args.y);
+    const base = `x=${Number.isFinite(x) ? x : String(args.x)},y=${Number.isFinite(y) ? y : String(args.y)}`;
+    return args.normalized === true ? `${base},normalized=true` : base;
+}
+function scrollTarget(args) {
+    const direction = String(args.direction ?? 'down').trim().toLowerCase() || 'down';
+    const percent = args.percent === undefined ? '' : `,percent=${String(args.percent)}`;
+    return `scroll=${direction}${percent}`;
+}
 function isValueBearingAction(command, args) {
     return command === 'act' && args.name === 'type' && args.value !== undefined;
 }
 function replayableEdge(edge) {
     return !isValueBearingAction(edge.command, edge.args);
 }
-function variantContainsTarget(variant, descriptor) {
+function elementContainsTarget(element, descriptor) {
+    if (descriptor.kind === 'section-first') {
+        return false;
+    }
     if (!descriptor.target && !descriptor.value) {
         return false;
     }
     const target = descriptor.target ?? '';
     const value = descriptor.value ?? target;
-    return variant.elements.some((element) => {
-        if (element.targets.includes(target) || element.targets.includes(value)) {
-            return true;
-        }
-        if (descriptor.kind === 'text') {
-            return element.labels.some((label) => label === value);
-        }
-        return element.labels.some((label) => label === value);
-    });
+    if (element.targets.includes(target) || element.targets.includes(value)) {
+        return true;
+    }
+    if (descriptor.kind === 'text-contains') {
+        const normalizedValue = normalizeControlTarget(value);
+        return element.labels.some((label) => normalizeControlTarget(label).includes(normalizedValue));
+    }
+    return element.labels.some((label) => label === value);
+}
+function variantContainsTarget(variant, descriptor) {
+    if (descriptor.kind === 'section-first') {
+        return sectionFirstTapArgs(variant, descriptor) !== null;
+    }
+    return variant.elements.some((element) => elementContainsTarget(element, descriptor));
+}
+async function liveContainsTarget(context, descriptor) {
+    if (descriptor.kind === 'section-first') {
+        return false;
+    }
+    const target = descriptor.target ?? descriptor.value;
+    if (!target) {
+        return false;
+    }
+    try {
+        return await context.adapter.exists(target);
+    }
+    catch {
+        return false;
+    }
 }
 function candidateVariants(map, descriptor) {
-    return map.variants.filter((variant) => variantContainsTarget(variant, descriptor));
+    return map.variants.filter((variant) => variantContainsTarget(variant, descriptor) && variantMatchesDescriptorContext(map, variant, descriptor));
+}
+function variantMatchesDescriptorContext(map, variant, descriptor) {
+    if (descriptor.kind !== 'section-first') {
+        return true;
+    }
+    const navigationHint = sectionNavigationHint(descriptor.value ?? descriptor.target ?? '', map);
+    if (!navigationHint) {
+        return true;
+    }
+    const navigationTarget = preferredNavigationTarget(variant);
+    return !navigationTarget || navigationTarget === navigationHint;
 }
 function summarizeEdge(edge) {
     return {
@@ -414,29 +749,39 @@ function summarizeControl(command, target, confidence) {
     };
 }
 function planRoute(map, fromVariantId, descriptor) {
-    if (descriptor.kind === 'coordinate' || descriptor.kind === 'unknown') {
+    if (descriptor.kind === 'coordinate' || descriptor.kind === 'unknown' || !routeableDescriptor(descriptor)) {
         return { edges: [], ambiguous: false, authRequired: false };
     }
     const destinations = candidateVariants(map, descriptor);
     if (destinations.length === 0) {
         return { edges: [], ambiguous: false, authRequired: false };
     }
-    if (descriptor.kind === 'text' && destinations.length > 1) {
-        return { edges: [], ambiguous: true, authRequired: false };
-    }
     const destinationIds = new Set(destinations.map((variant) => variant.id));
     const visited = new Set([fromVariantId]);
     const queue = [{ variantId: fromVariantId, edges: [] }];
+    const reachableRoutes = [];
+    let shortestDestinationLength = null;
     while (queue.length > 0) {
         const current = queue.shift();
         if (!current) {
             break;
         }
         if (destinationIds.has(current.variantId)) {
-            const destination = map.variants.find((variant) => variant.id === current.variantId);
-            return { edges: current.edges, ambiguous: false, authRequired: Boolean(destination?.auth_required) };
+            if (shortestDestinationLength === null) {
+                shortestDestinationLength = current.edges.length;
+            }
+            if (current.edges.length === shortestDestinationLength) {
+                reachableRoutes.push(current);
+            }
+            continue;
+        }
+        if (shortestDestinationLength !== null && current.edges.length >= shortestDestinationLength) {
+            continue;
         }
-        const outgoing = map.edges
+        const outgoing = [
+            ...map.edges,
+            ...navigationVirtualEdges(map, map.variants.find((variant) => variant.id === current.variantId))
+        ]
             .filter((edge) => edge.from_variant_id === current.variantId && !edge.stale && edge.confidence >= 0.25 && replayableEdge(edge))
             .sort((left, right) => right.confidence - left.confidence);
         for (const edge of outgoing) {
@@ -447,13 +792,227 @@ function planRoute(map, fromVariantId, descriptor) {
             queue.push({ variantId: edge.to_variant_id, edges: [...current.edges, edge] });
         }
     }
+    if (reachableRoutes.length > 0) {
+        const rankedRoutes = reachableRoutes
+            .map((route) => ({
+            ...route,
+            score: destinationTargetScore(map, map.variants.find((variant) => variant.id === route.variantId), descriptor) + routeTargetScore(map, route.edges, descriptor)
+        }))
+            .sort((left, right) => right.score - left.score);
+        const best = rankedRoutes[0];
+        if (!best) {
+            return { edges: [], ambiguous: false, authRequired: false };
+        }
+        const tiedBest = rankedRoutes.filter((route) => route.score === best.score);
+        const ambiguous = (descriptor.kind === 'text' || descriptor.kind === 'text-contains' || descriptor.kind === 'section-first') &&
+            tiedBest.length > 1;
+        const diagnostics = routePlanDiagnostics(map, descriptor, rankedRoutes, ambiguous ? undefined : best, ambiguous);
+        if (ambiguous) {
+            return { edges: [], ambiguous: true, authRequired: false, diagnostics };
+        }
+        const route = best;
+        const destination = map.variants.find((variant) => variant.id === route?.variantId);
+        return {
+            edges: route?.edges ?? [],
+            ambiguous: false,
+            authRequired: Boolean(destination?.auth_required),
+            diagnostics
+        };
+    }
     return { edges: [], ambiguous: false, authRequired: destinations.some((variant) => variant.auth_required) };
 }
+function routePlanDiagnostics(map, descriptor, rankedRoutes, selected, ambiguous) {
+    const bestScore = rankedRoutes[0]?.score;
+    return {
+        target: descriptor.target ?? descriptor.value ?? descriptor.kind,
+        selected_variant_id: selected?.variantId,
+        ambiguous,
+        route_candidates: rankedRoutes.map((route) => {
+            const variant = map.variants.find((candidate) => candidate.id === route.variantId);
+            const isSelected = selected?.variantId === route.variantId;
+            return {
+                variant_id: route.variantId,
+                screen_id: variant?.screen_id,
+                score: Math.round(route.score * 100) / 100,
+                route: route.edges.map(summarizeEdge),
+                selected: isSelected,
+                ...(isSelected
+                    ? {}
+                    : { rejected_reason: ambiguous && route.score === bestScore ? 'ambiguous_tie' : 'lower_score' })
+            };
+        })
+    };
+}
+function routeableDescriptor(descriptor) {
+    if (descriptor.kind === 'section-first') {
+        const value = descriptor.value ?? descriptor.target ?? '';
+        return /[a-z]/i.test(value);
+    }
+    if (descriptor.kind !== 'text-contains') {
+        return true;
+    }
+    const value = descriptor.value ?? descriptor.target ?? '';
+    return /[a-z]/i.test(value);
+}
+function navigationVirtualEdges(map, variant) {
+    if (!variant) {
+        return [];
+    }
+    const currentNavigationTarget = preferredNavigationTarget(variant);
+    const edges = [];
+    const destinationsByTarget = new Map();
+    for (const destination of map.variants) {
+        if (destination.id === variant.id) {
+            continue;
+        }
+        const target = preferredNavigationTarget(destination);
+        if (!target || target === currentNavigationTarget || destinationsByTarget.has(target)) {
+            continue;
+        }
+        destinationsByTarget.set(target, destination);
+    }
+    for (const candidate of safeTapCandidates(variant, { skipCurrentNavigation: true })) {
+        const target = normalizeControlTarget(candidate.target);
+        const destination = destinationsByTarget.get(target);
+        if (!destination) {
+            continue;
+        }
+        if (hasRealEdgeForTap(map, variant.id, candidate)) {
+            continue;
+        }
+        edges.push({
+            id: `virtual_nav_${variant.id}_${target}`,
+            from_variant_id: variant.id,
+            to_variant_id: destination.id,
+            command: 'tap',
+            args: structuredClone(candidate.args),
+            target: targetDescriptor('tap', candidate.args).target,
+            confidence: 0.4,
+            successes: 0,
+            failures: 0,
+            stale: false,
+            candidate: true,
+            destination_contract: {
+                variant_id: destination.id,
+                required_targets: contractTargets(destination),
+                normalized_fingerprint: destination.normalized_fingerprint
+            },
+            last_observed_at: utcNowIso()
+        });
+    }
+    return edges;
+}
+function hasRealEdgeForTap(map, fromVariantId, candidate) {
+    const descriptor = targetDescriptor('tap', candidate.args);
+    const candidateTargets = new Set([candidate.key, candidate.target, descriptor.target, descriptor.value].filter(Boolean));
+    return map.edges.some((edge) => edge.from_variant_id === fromVariantId &&
+        !edge.stale &&
+        edge.confidence >= 0.25 &&
+        replayableEdge(edge) &&
+        candidateTargets.has(edge.target));
+}
+function destinationTargetScore(map, variant, descriptor) {
+    if (!variant) {
+        return 0;
+    }
+    if (descriptor.kind === 'section-first') {
+        const element = firstItemInSection(variant, descriptor);
+        if (!element) {
+            return 0;
+        }
+        let score = isHighValueContentCard(element) ? 10 : 7;
+        const navigationHint = sectionNavigationHint(descriptor.value ?? descriptor.target ?? '', map);
+        const navigationTarget = preferredNavigationTarget(variant);
+        if (navigationHint && navigationTarget === navigationHint) {
+            score += 5;
+        }
+        else if (navigationHint && navigationTarget && navigationTarget !== navigationHint) {
+            score -= 5;
+        }
+        return score;
+    }
+    let score = 0;
+    for (const element of variant.elements) {
+        if (!elementContainsTarget(element, descriptor)) {
+            continue;
+        }
+        let elementScore = 1;
+        if (isLikelyTapElement(element)) {
+            elementScore += 4;
+        }
+        else if (element.visible === false) {
+            elementScore -= 2;
+        }
+        if (isHighValueContentCard(element)) {
+            elementScore += 3;
+        }
+        const value = normalizeControlTarget(descriptor.value ?? descriptor.target ?? '');
+        if (value &&
+            element.labels.some((label) => normalizeControlTarget(label) === value ||
+                label.split(/\n+/).some((line) => normalizeControlTarget(line) === value))) {
+            elementScore += 2;
+        }
+        score = Math.max(score, elementScore);
+    }
+    if (preferredNavigationTarget(variant) && score > 0) {
+        score += 1;
+    }
+    if (score > 0 && isFeedLikeVariant(variant) && !descriptorTargetsFeed(descriptor)) {
+        score -= 3;
+    }
+    return score;
+}
+function isFeedLikeVariant(variant) {
+    return contentLabels(variant).some((label) => /^(for you|activity|feed|latest|timeline|updates?)$/.test(label));
+}
+function descriptorTargetsFeed(descriptor) {
+    const value = normalizeControlTarget(descriptor.value ?? descriptor.target ?? '');
+    return /\b(activity|feed|post|comment|update|timeline)\b/.test(value);
+}
+function routeTargetScore(map, route, descriptor) {
+    if (descriptor.kind !== 'section-first') {
+        return 0;
+    }
+    const navigationHint = sectionNavigationHint(descriptor.value ?? descriptor.target ?? '', map);
+    if (!navigationHint) {
+        return 0;
+    }
+    return route.reduce((score, edge) => {
+        const target = edgeNavigationTarget(map, edge);
+        if (!target) {
+            return score;
+        }
+        return score + (target === navigationHint ? 3 : -3);
+    }, 0);
+}
+function edgeNavigationTarget(map, edge) {
+    const normalizedTarget = normalizeControlTarget(edge.target ?? '');
+    const from = map.variants.find((variant) => variant.id === edge.from_variant_id);
+    if (from && isNavigationTarget(from, normalizedTarget)) {
+        return normalizedTarget;
+    }
+    if (!from || edge.command !== 'tap') {
+        return null;
+    }
+    const edgeCoordinateTarget = coordinateTarget(edge.args);
+    for (const control of navigationControls(from)) {
+        const elementCoordinateTarget = coordinateArgsForElement(control.element);
+        if (elementCoordinateTarget && coordinateTarget(elementCoordinateTarget) === edgeCoordinateTarget) {
+            return control.target;
+        }
+    }
+    return null;
+}
 function contractTargets(variant) {
-    return variant.elements
+    const navigationElements = new Set(navigationControls(variant).map((control) => control.element));
+    const contentTargets = variant.elements
         .filter((element) => element.stable)
-        .flatMap((element) => element.targets)
-        .slice(0, 8);
+        .filter((element) => !navigationElements.has(element))
+        .flatMap((element) => element.targets.filter((target) => !isGlobalIdentityLabel(normalizeControlTarget(target), element)));
+    const fallbackTargets = variant.elements
+        .filter((element) => element.stable)
+        .flatMap((element) => element.targets);
+    return unique([...contentTargets, ...fallbackTargets]).slice(0, 8);
 }
 function matchingEdge(map, fromVariantId, command, target) {
     return map.edges.find((edge) => edge.from_variant_id === fromVariantId &&
@@ -465,7 +1024,7 @@ function recordEdgeSuccess(context, from, to, command, args, candidate) {
         return;
     }
     const descriptor = targetDescriptor(command, args);
-    if (descriptor.kind === 'coordinate' || descriptor.kind === 'unknown') {
+    if (descriptor.kind === 'unknown') {
         return;
     }
     const edge = matchingEdge(context.map, from.id, command, descriptor.target);
@@ -515,25 +1074,87 @@ function demoteEdge(context, edge) {
     edge.last_observed_at = utcNowIso();
     context.changed = true;
 }
-function satisfiesContract(edge, observed) {
-    if (observed.variant.id === edge.destination_contract.variant_id) {
+function shouldRequireObservedEffect(command, args) {
+    return command === 'tap' || command === 'navigate' || command === 'scroll' || (command === 'act' && args.name === 'back');
+}
+function assertObservedEffect(command, args, before, after, descriptor) {
+    if (!shouldRequireObservedEffect(command, args)) {
+        return;
+    }
+    if (before.observation.fingerprint !== after.observation.fingerprint) {
+        return;
+    }
+    const target = descriptor.target ?? descriptor.value ?? command;
+    throw new Error(`Action '${command}' on '${target}' had no effect: screen source did not change after the command`);
+}
+function variantSatisfiesContract(variant, contract) {
+    if (variant.id === contract.variant_id) {
         return true;
     }
-    const observedTargets = new Set(observed.variant.elements.flatMap((element) => element.targets));
-    const required = edge.destination_contract.required_targets;
+    const observedTargets = new Set(variant.elements.flatMap((element) => element.targets));
+    const required = contract.required_targets;
     if (required.length === 0) {
-        return observed.variant.normalized_fingerprint === edge.destination_contract.normalized_fingerprint;
+        return variant.normalized_fingerprint === contract.normalized_fingerprint;
     }
     const matched = required.filter((target) => observedTargets.has(target)).length;
     return matched / required.length >= 0.6;
 }
+function restoreContractHasSharedAnchors(observed, target) {
+    const observedTargets = new Set(observed.elements.flatMap((element) => element.targets));
+    const required = contractTargets(target);
+    if (required.length === 0) {
+        return false;
+    }
+    const matched = unique(required.filter((targetValue) => observedTargets.has(targetValue)));
+    return matched.length >= 2 && matched.length / required.length >= 0.25;
+}
+function restoreMatch(observed, target) {
+    if (observed.variant.id === target.variant.id) {
+        return { acceptedBy: 'exact' };
+    }
+    const observedNavigationTarget = preferredNavigationTarget(observed.variant);
+    const targetNavigationTarget = preferredNavigationTarget(target.variant);
+    if (observedNavigationTarget && targetNavigationTarget && observedNavigationTarget !== targetNavigationTarget) {
+        return null;
+    }
+    if (hasScrollableSurface(observed.variant) || hasScrollableSurface(target.variant)) {
+        const observedControlKeys = identityKeys(observed.variant.elements, false);
+        const targetControlKeys = identityKeys(target.variant.elements, false);
+        if ((observedControlKeys.length > 0 || targetControlKeys.length > 0) &&
+            similarity(observedControlKeys, targetControlKeys) < 0.3) {
+            return null;
+        }
+    }
+    const contract = {
+        variant_id: target.variant.id,
+        required_targets: contractTargets(target.variant),
+        normalized_fingerprint: target.variant.normalized_fingerprint
+    };
+    if (variantSatisfiesContract(observed.variant, contract)) {
+        return { acceptedBy: 'contract' };
+    }
+    if (observedNavigationTarget &&
+        targetNavigationTarget &&
+        observedNavigationTarget === targetNavigationTarget &&
+        restoreContractHasSharedAnchors(observed.variant, target.variant)) {
+        return { acceptedBy: 'contract' };
+    }
+    const score = screenSimilarity(target.variant.elements, observed.variant.elements);
+    if (score >= 0.72) {
+        return { acceptedBy: 'similarity', score };
+    }
+    return null;
+}
+function satisfiesContract(edge, observed) {
+    return variantSatisfiesContract(observed.variant, edge.destination_contract);
+}
 async function driveRoute(context, current, route) {
     for (const edge of route) {
         const args = structuredClone(edge.args);
         let observed;
         try {
             await context.adapter[edge.command](args);
-            observed = await observeCurrentScreen(context);
+            observed = await observeAfterAction(context);
         }
         catch {
             demoteEdge(context, edge);
@@ -554,63 +1175,731 @@ async function driveRoute(context, current, route) {
     }
     return { current };
 }
-function safeTapTargets(variant) {
-    return unique(variant.elements
-        .filter((element) => element.safety === 'safe' && element.stable)
-        .map((element) => {
-        const plainLabel = element.targets.find((target) => !target.includes('='));
-        return plainLabel ?? element.targets[0] ?? '';
-    }));
+function safeTapCandidates(variant, options = {}) {
+    const candidates = [];
+    const seen = new Set();
+    const currentNavigationTarget = options.skipCurrentNavigation ? preferredNavigationTarget(variant) : null;
+    const elements = [...variant.elements].sort((left, right) => {
+        const priority = tapElementPriority(left, variant, options) - tapElementPriority(right, variant, options);
+        if (priority !== 0) {
+            return priority;
+        }
+        return (left.y ?? 0) - (right.y ?? 0) || (left.x ?? 0) - (right.x ?? 0);
+    });
+    for (const element of elements) {
+        if (!(element.safety === 'safe' && element.stable && isLikelyTapElement(element))) {
+            continue;
+        }
+        const target = plainTapTargets(element)[0] ?? element.selector;
+        if (!target) {
+            continue;
+        }
+        const normalizedTarget = normalizeControlTarget(target);
+        if (options.excludeNavigation && isNavigationTarget(variant, normalizedTarget)) {
+            continue;
+        }
+        if (currentNavigationTarget && normalizedTarget === currentNavigationTarget) {
+            continue;
+        }
+        const coordinateArgs = coordinateArgsForElement(element);
+        const args = coordinateArgs ?? { target };
+        const key = coordinateArgs ? coordinateTarget(coordinateArgs) : target;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        candidates.push({ target, args, key });
+    }
+    return candidates;
 }
-async function repairToTarget(context, current, descriptor, depth, deadline, blockedTargets) {
-    if (Date.now() > deadline || depth <= 0) {
-        return null;
+function tapElementPriority(element, variant, options = {}) {
+    const target = plainTapTargets(element)[0] ?? element.selector;
+    const normalized = normalizeControlTarget(target);
+    if (options.preferContent && isHighValueContentCard(element)) {
+        return 5;
     }
-    const attemptedTargets = new Map();
-    const attemptFrom = async (start, remainingDepth, route) => {
-        let cursor = start;
-        let depthLeft = remainingDepth;
-        let routeSoFar = route;
-        while (Date.now() <= deadline) {
-            if (variantContainsTarget(cursor.variant, descriptor)) {
-                return { found: true, current: cursor, route: routeSoFar, remainingDepth: depthLeft };
-            }
-            if (depthLeft <= 0) {
-                return { found: false, current: cursor, route: routeSoFar, remainingDepth: depthLeft };
-            }
-            const attemptsForVariant = attemptedTargets.get(cursor.variant.id) ?? new Set();
-            attemptedTargets.set(cursor.variant.id, attemptsForVariant);
-            const target = safeTapTargets(cursor.variant).find((candidate) => !blockedTargets.has(candidate) && !attemptsForVariant.has(candidate));
-            if (!target) {
-                return { found: false, current: cursor, route: routeSoFar, remainingDepth: depthLeft };
-            }
-            attemptsForVariant.add(target);
-            const args = { target };
-            let observed;
-            try {
-                await context.adapter.tap(args);
-                observed = await observeCurrentScreen(context);
-            }
-            catch {
-                try {
-                    cursor = await observeCurrentScreen(context);
-                }
-                catch {
-                    // If both the exploratory tap and source read fail, keep the last observed screen.
-                }
-                continue;
-            }
-            recordEdgeSuccess(context, cursor.variant, observed.variant, 'tap', args, true);
-            const nextRoute = [...routeSoFar, summarizeControl('tap', target, 0.45)];
-            const nested = await attemptFrom(observed, depthLeft - 1, nextRoute);
-            if (nested.found) {
-                return nested;
-            }
-            cursor = nested.current;
-            depthLeft = nested.remainingDepth;
-            routeSoFar = nested.route;
+    const navPriority = navigationControlPriority(variant, normalized);
+    if (navPriority !== undefined) {
+        if (options.preferContent) {
+            return 80 + navPriority;
         }
-        return { found: false, current: cursor, route: routeSoFar, remainingDepth: depthLeft };
+        return navPriority;
+    }
+    if (normalized === 'see all') {
+        return 10;
+    }
+    if (isBackControl(element)) {
+        return 90;
+    }
+    if (element.tag.toLowerCase().includes('button')) {
+        return 40;
+    }
+    if (element.tag.toLowerCase().includes('other')) {
+        return 60;
+    }
+    return 50;
+}
+function isHighValueContentCard(element) {
+    if (!isLikelyTapElement(element)) {
+        return false;
+    }
+    const target = plainTapTargets(element)[0] ?? element.selector;
+    const normalizedTarget = normalizeControlTarget(target);
+    if (normalizedTarget === 'see all' || /^(back|close|dismiss|done)$/i.test(target)) {
+        return false;
+    }
+    const lines = unique(element.labels.flatMap((label) => label.split(/\n+/).map((line) => line.trim())));
+    const area = (element.width ?? 0) * (element.height ?? 0);
+    return (lines.length >= 2 ||
+        (element.tag.toLowerCase().includes('other') && area >= 3000) ||
+        ((element.width ?? 0) >= 120 && (element.height ?? 0) >= 64 && element.labels.length > 0));
+}
+function actionAffordancesForElements(elements) {
+    const navigationElements = new Set(navigationControlsForElements(elements).map((control) => control.element));
+    const navigationTarget = preferredNavigationTargetForElements(elements) ?? undefined;
+    const actions = [];
+    const seen = new Set();
+    const candidates = [...elements]
+        .filter((element) => element.safety === 'safe' && element.stable && isLikelyTapElement(element))
+        .filter((element) => !navigationElements.has(element) && !isBackControl(element))
+        .sort((left, right) => (left.y ?? 0) - (right.y ?? 0) || (left.x ?? 0) - (right.x ?? 0));
+    for (const element of candidates) {
+        const label = actionLabel(element);
+        if (!label) {
+            continue;
+        }
+        const coordinateArgs = coordinateArgsForElement(element);
+        const stableTarget = plainTapTargets(element)[0] ?? element.selector;
+        const args = coordinateArgs ?? { target: stableTarget };
+        const target = coordinateArgs ? coordinateTarget(coordinateArgs) : stableTarget;
+        const scope = actionScopeForElement(elements, element);
+        const dedupeKey = [
+            actionIntent(label),
+            target,
+            scope?.kind ?? '',
+            scope?.label ?? ''
+        ].join('|');
+        if (seen.has(dedupeKey)) {
+            continue;
+        }
+        seen.add(dedupeKey);
+        actions.push({
+            command: 'tap',
+            intent: actionIntent(label),
+            label,
+            target,
+            args,
+            safety: element.safety,
+            ...(scope ? { scope } : {}),
+            ...(navigationTarget ? { navigation_target: navigationTarget } : {}),
+            source: {
+                tag: element.tag,
+                x: element.x,
+                y: element.y,
+                width: element.width,
+                height: element.height
+            }
+        });
+    }
+    return actions;
+}
+function actionLabel(element) {
+    const target = plainTapTargets(element)[0] ?? element.labels[0] ?? element.selector;
+    return target.split(/\n+/).map((line) => line.trim()).filter(Boolean)[0] ?? target.trim();
+}
+function actionIntent(label) {
+    const normalized = normalizeControlTarget(label);
+    const intentPatterns = [
+        ['like', /\blike\b/],
+        ['comment', /\bcomment\b/],
+        ['share', /\bshare\b/],
+        ['save', /\b(save|bookmark)\b/],
+        ['follow', /\bfollow\b/],
+        ['watchlist', /\bwatchlist\b/],
+        ['search', /\bsearch\b/],
+        ['create', /\b(create|new)\b/],
+        ['filter', /\bfilter\b/],
+        ['sort', /\bsort\b/],
+        ['dismiss', /\b(close|dismiss|skip)\b/]
+    ];
+    const matched = intentPatterns.find(([, pattern]) => pattern.test(normalized));
+    if (matched) {
+        return matched[0];
+    }
+    return normalized.split(/[^a-z0-9]+/).filter(Boolean)[0] ?? 'tap';
+}
+function actionScopeForElement(elements, element) {
+    const content = nearestContentScopeElement(elements, element);
+    if (content) {
+        return {
+            kind: 'content',
+            label: content.labels[0]
+        };
+    }
+    const section = nearestActionSectionElement(elements, element);
+    if (section) {
+        return {
+            kind: 'section',
+            label: section.labels[0]
+        };
+    }
+    return { kind: 'screen' };
+}
+function nearestContentScopeElement(elements, element) {
+    if (element.y === null) {
+        return null;
+    }
+    return elements
+        .filter((candidate) => candidate !== element && candidate.y !== null && candidate.height !== null)
+        .filter((candidate) => isHighValueContentCard(candidate))
+        .filter((candidate) => {
+        const candidateTop = candidate.y;
+        const candidateBottom = candidateTop + Math.max(0, candidate.height ?? 0);
+        return candidateTop <= element.y && candidateBottom + 96 >= element.y;
+    })
+        .sort((left, right) => (right.y ?? 0) - (left.y ?? 0))[0] ?? null;
+}
+function nearestActionSectionElement(elements, element) {
+    if (element.y === null) {
+        return null;
+    }
+    return elements
+        .filter((candidate) => candidate.y !== null && candidate.y < element.y && isActionSectionElement(candidate))
+        .sort((left, right) => (right.y ?? 0) - (left.y ?? 0))[0] ?? null;
+}
+function isActionSectionElement(element) {
+    if (isLikelyTapElement(element) || element.labels.length === 0) {
+        return false;
+    }
+    return element.labels.some((label) => {
+        const normalized = normalizeControlTarget(label);
+        if (!/[a-z]/i.test(normalized)) {
+            return false;
+        }
+        const words = normalized.split(/\s+/).filter(Boolean);
+        return words.length <= 8;
+    });
+}
+function normalizeControlTarget(target) {
+    return target.replace(/\s+/g, ' ').trim().toLowerCase();
+}
+function sectionNavigationHint(value, map) {
+    const normalized = normalizeControlTarget(value);
+    const targets = unique(map.variants.flatMap((variant) => navigationControls(variant).map((control) => control.target)))
+        .sort((left, right) => right.length - left.length);
+    for (const target of targets) {
+        if (normalized.includes(target)) {
+            return target;
+        }
+    }
+    return null;
+}
+function crawlCandidateOptions(variant) {
+    const preferredTarget = preferredNavigationTarget(variant);
+    const preferContent = preferredTarget !== null && !isPrimaryNavigationTarget(variant, preferredTarget);
+    return {
+        preferContent,
+        excludeNavigation: preferContent,
+        skipCurrentNavigation: true
+    };
+}
+function crawlTemplateKey(variant) {
+    const navigationTarget = preferredNavigationTarget(variant) ?? 'none';
+    const elementKeys = unique(variant.elements.flatMap((element) => crawlTemplateElementKeys(variant, element))).sort();
+    return signatureFor([`nav=${navigationTarget}`, ...elementKeys]);
+}
+function crawlTemplateElementKeys(variant, element) {
+    if (element.visible === false || element.stable === false) {
+        return [];
+    }
+    const tag = element.tag.toLowerCase();
+    const layout = `${bucketNumber(element.width, 24)}x${bucketNumber(element.height, 24)}`;
+    if (isScrollableTag(tag)) {
+        return [`scroll:${layout}`];
+    }
+    if (isNavigationElement(variant, element)) {
+        return [`nav-control:${normalizeControlTarget(plainTapTargets(element)[0] ?? element.selector)}:${layout}`];
+    }
+    if (isHighValueContentCard(element)) {
+        return [`content-card:${contentLineCount(element)}:${layout}`];
+    }
+    if (isLikelyTapElement(element)) {
+        return [`tap:${tag}:${templateControlLabel(element)}:${layout}`];
+    }
+    return [];
+}
+function templateControlLabel(element) {
+    if (isBackControl(element)) {
+        return 'back';
+    }
+    const target = normalizeControlTarget(plainTapTargets(element)[0] ?? element.selector);
+    const words = target.split(/\s+/).filter(Boolean);
+    if (target && words.length <= 4 && target.length <= 48) {
+        return target;
+    }
+    return 'control';
+}
+function repeatedContentCandidateKey(variant, candidate) {
+    const element = elementForTapCandidate(variant, candidate);
+    if (!element || !isHighValueContentCard(element)) {
+        return null;
+    }
+    const section = nearestSectionHeadingLabel(variant, element) ?? 'section=none';
+    const tag = element.tag.toLowerCase();
+    const shape = [
+        crawlTemplateKey(variant),
+        section,
+        tag,
+        `lines=${contentLineCount(element)}`,
+        `size=${bucketNumber(element.width, 24)}x${bucketNumber(element.height, 24)}`
+    ];
+    return signatureFor(shape);
+}
+function elementForTapCandidate(variant, candidate) {
+    const candidateCoordinate = typeof candidate.args.x === 'number' && typeof candidate.args.y === 'number'
+        ? coordinateTarget(candidate.args)
+        : null;
+    for (const element of variant.elements) {
+        if (candidateCoordinate) {
+            const elementCoordinate = coordinateArgsForElement(element);
+            if (elementCoordinate && coordinateTarget(elementCoordinate) === candidateCoordinate) {
+                return element;
+            }
+        }
+        const target = plainTapTargets(element)[0] ?? element.selector;
+        if (target === candidate.target || element.targets.includes(candidate.target)) {
+            return element;
+        }
+    }
+    return null;
+}
+function nearestSectionHeadingLabel(variant, element) {
+    if (element.y === null) {
+        return null;
+    }
+    const heading = variant.elements
+        .filter((candidate) => candidate.y !== null && candidate.y < element.y && isLikelySectionHeading(variant, candidate))
+        .sort((left, right) => (right.y ?? 0) - (left.y ?? 0))[0];
+    const label = heading?.labels[0];
+    return label ? `section=${normalizeControlTarget(label)}` : null;
+}
+function contentLineCount(element) {
+    const lines = unique(element.labels.flatMap((label) => label.split(/\n+/).map((line) => line.trim()).filter(Boolean)));
+    return lines.length;
+}
+function bucketNumber(value, size) {
+    if (value === null || !Number.isFinite(value)) {
+        return 0;
+    }
+    return Math.round(value / size) * size;
+}
+function crawlScrollCandidates(context, variant) {
+    if (!context.adapter.capability().commands.includes('scroll') || !shouldExploreScroll(variant)) {
+        return [];
+    }
+    const args = { direction: 'down', percent: 70 };
+    return [
+        {
+            target: scrollTarget(args),
+            args,
+            key: 'scroll:down:70'
+        }
+    ];
+}
+function shouldExploreScroll(variant) {
+    return hasScrollableSurface(variant) || hasBottomReachableContent(variant);
+}
+function hasScrollableSurface(variant) {
+    return elementsHaveScrollableSurface(variant.elements);
+}
+function elementsHaveScrollableSurface(elements) {
+    return elements.some((element) => isScrollableTag(element.tag));
+}
+function hasBottomReachableContent(variant) {
+    const content = scrollProbeElements(variant);
+    if (content.length < 3) {
+        return false;
+    }
+    const navControls = navigationControls(variant);
+    const navTop = navControls
+        .map((control) => control.element.y)
+        .filter((value) => value !== null)
+        .sort((left, right) => left - right)[0] ?? null;
+    if (navTop === null) {
+        return false;
+    }
+    const viewportBottom = navTop ?? Math.max(...content.map((element) => (element.y ?? 0) + (element.height ?? 0)));
+    return content.some((element) => ((element.y ?? 0) + (element.height ?? 0)) >= viewportBottom - 48);
+}
+function scrollProbeElements(variant) {
+    const navigationElements = new Set(navigationControls(variant).map((control) => control.element));
+    return variant.elements.filter((element) => {
+        if (element.visible === false || element.y === null || element.height === null || navigationElements.has(element)) {
+            return false;
+        }
+        if (isBackControl(element)) {
+            return false;
+        }
+        const tag = element.tag.toLowerCase();
+        return !isScrollableTag(tag);
+    });
+}
+function preferredNavigationTarget(variant) {
+    return preferredNavigationTargetForElements(variant.elements);
+}
+function preferredNavigationTargetForElements(elements) {
+    const controls = navigationControlsForElements(elements);
+    if (controls.length === 0) {
+        return null;
+    }
+    const labels = contentLabelsForElements(elements);
+    const matched = controls.find((control) => labels.some((label) => labelMatchesNavigationTarget(label, control.target)));
+    if (matched) {
+        return matched.target;
+    }
+    return controls[0]?.target ?? null;
+}
+function hasBottomNavigation(variant) {
+    return navigationControls(variant).length >= 2;
+}
+function contentLabels(variant) {
+    return contentLabelsForElements(variant.elements);
+}
+function contentLabelsForElements(elements) {
+    const navigationElements = new Set(navigationControlsForElements(elements).map((control) => control.element));
+    return elements.flatMap((element) => element.labels
+        .filter(() => !navigationElements.has(element))
+        .filter((label) => !isGlobalIdentityLabel(label, element))
+        .map(normalizeControlTarget));
+}
+function navigationControls(variant) {
+    return navigationControlsForElements(variant.elements);
+}
+function navigationControlsForElements(elements) {
+    const candidates = elements
+        .filter((element) => element.safety === 'safe' && element.stable && isLikelyTapElement(element))
+        .filter((element) => !isBackControl(element))
+        .filter((element) => coordinateArgsForElement(element) !== null)
+        .map((element) => ({ element, target: normalizeControlTarget(plainTapTargets(element)[0] ?? element.selector) }))
+        .filter((candidate) => isCompactNavigationLabel(candidate.element, candidate.target));
+    if (candidates.length < 2) {
+        return [];
+    }
+    const maxY = Math.max(...candidates.map((candidate) => candidate.element.y ?? 0));
+    const bottomRow = candidates
+        .filter((candidate) => (candidate.element.y ?? 0) >= maxY - 12)
+        .sort((left, right) => (left.element.x ?? 0) - (right.element.x ?? 0));
+    if (bottomRow.length < 2) {
+        return [];
+    }
+    return bottomRow.map((candidate, priority) => ({
+        ...candidate,
+        priority
+    }));
+}
+function isCompactNavigationLabel(element, target) {
+    if (!target || target.includes('\n') || target.length > 32 || target === 'see all') {
+        return false;
+    }
+    if ((element.height ?? 0) > 72) {
+        return false;
+    }
+    const lines = unique(element.labels.flatMap((label) => label.split(/\n+/).map((line) => normalizeControlTarget(line))));
+    return lines.length <= 2 && lines.some((line) => line === target);
+}
+function isNavigationElement(variant, element) {
+    return navigationControls(variant).some((control) => control.element === element);
+}
+function isNavigationTarget(variant, normalizedTarget) {
+    return navigationControls(variant).some((control) => control.target === normalizedTarget);
+}
+function navigationControlPriority(variant, normalizedTarget) {
+    return navigationControls(variant).find((control) => control.target === normalizedTarget)?.priority;
+}
+function isPrimaryNavigationTarget(variant, normalizedTarget) {
+    return navigationControls(variant)[0]?.target === normalizedTarget;
+}
+function labelMatchesNavigationTarget(label, target) {
+    if (label === target) {
+        return true;
+    }
+    const labelWords = new Set(label.split(/[^a-z0-9]+/).filter(Boolean));
+    const targetWords = target.split(/[^a-z0-9]+/).filter(Boolean);
+    if (targetWords.length === 1) {
+        const words = Array.from(labelWords);
+        return words.length <= 2 && words[0] === targetWords[0];
+    }
+    return targetWords.length > 0 && targetWords.every((word) => labelWords.has(word));
+}
+function currentScreenTapArgs(variant, descriptor) {
+    if (descriptor.kind === 'section-first') {
+        return sectionFirstTapArgs(variant, descriptor);
+    }
+    const action = matchingAction(variant, descriptor);
+    if (action) {
+        return structuredClone(action.args);
+    }
+    for (const element of variant.elements) {
+        if (!elementContainsTarget(element, descriptor)) {
+            continue;
+        }
+        if (!(element.safety === 'safe' && element.stable && isLikelyTapElement(element))) {
+            continue;
+        }
+        const coordinateArgs = coordinateArgsForElement(element);
+        if (coordinateArgs) {
+            return coordinateArgs;
+        }
+        const stableTarget = plainTapTargets(element)[0] ?? element.selector;
+        if (stableTarget && shouldUseStableTargetFallback(element, descriptor)) {
+            return { target: stableTarget };
+        }
+    }
+    return null;
+}
+function currentScreenLiveTapArgs(variant, descriptor) {
+    const action = matchingAction(variant, descriptor);
+    return action && shouldUseActionForLiveSemanticTap(action)
+        ? structuredClone(action.args)
+        : null;
+}
+function matchingAction(variant, descriptor) {
+    return variant.actions.find((candidate) => actionMatchesDescriptor(candidate, descriptor));
+}
+function actionMatchesDescriptor(action, descriptor) {
+    if (action.command !== 'tap' || action.safety !== 'safe') {
+        return false;
+    }
+    if (descriptor.kind === 'text-contains') {
+        return false;
+    }
+    const target = descriptor.target ?? '';
+    const value = descriptor.value ?? target;
+    const normalizedValue = normalizeControlTarget(value);
+    const normalizedTarget = normalizeControlTarget(target);
+    const normalizedActionLabel = normalizeControlTarget(action.label);
+    const normalizedActionTarget = normalizeControlTarget(action.target ?? '');
+    if (!normalizedValue && !normalizedTarget) {
+        return false;
+    }
+    return [normalizedActionLabel, normalizedActionTarget].some((candidate) => candidate !== '' && (candidate === normalizedValue || candidate === normalizedTarget));
+}
+function shouldUseActionForLiveSemanticTap(action) {
+    return (typeof action.args.x === 'number' &&
+        typeof action.args.y === 'number' &&
+        action.source.tag.toLowerCase().includes('xcuielementtype'));
+}
+function shouldUseStableTargetFallback(element, descriptor) {
+    if (descriptor.kind !== 'text-contains') {
+        return false;
+    }
+    const value = descriptor.value ?? '';
+    return value !== '' && !element.labels.some((label) => label.includes(value));
+}
+function sectionFirstTapArgs(variant, descriptor) {
+    const element = firstItemInSection(variant, descriptor);
+    return element ? coordinateArgsForElement(element) : null;
+}
+function firstItemInSection(variant, descriptor) {
+    const value = descriptor.value ?? descriptor.target ?? '';
+    if (!/[a-z]/i.test(value)) {
+        return null;
+    }
+    const section = sectionHeadingElement(variant, value);
+    if (!section || section.y === null || section.height === null) {
+        return null;
+    }
+    const sectionY = section.y;
+    const sectionBottom = sectionY + Math.max(0, section.height);
+    const nextSectionY = variant.elements
+        .filter((element) => element !== section &&
+        element.y !== null &&
+        element.y > sectionY &&
+        isLikelySectionHeading(variant, element))
+        .map((element) => element.y)
+        .sort((left, right) => left - right)[0] ?? null;
+    const candidates = variant.elements
+        .filter((element) => isSectionItemCandidate(variant, element, value) &&
+        element.y !== null &&
+        element.y > sectionBottom &&
+        (nextSectionY === null || element.y < nextSectionY))
+        .sort((left, right) => (left.y ?? 0) - (right.y ?? 0) || (left.x ?? 0) - (right.x ?? 0));
+    return candidates[0] ?? null;
+}
+function sectionHeadingElement(variant, value) {
+    const matches = variant.elements
+        .filter((element) => element.visible !== false &&
+        element.y !== null &&
+        element.height !== null &&
+        elementLabelMatchesValue(element, value))
+        .sort((left, right) => (left.y ?? 0) - (right.y ?? 0) || (left.x ?? 0) - (right.x ?? 0));
+    return matches[0] ?? null;
+}
+function isSectionItemCandidate(variant, element, sectionValue) {
+    if (!(element.safety === 'safe' && element.stable && isLikelyTapElement(element))) {
+        return false;
+    }
+    if (!coordinateArgsForElement(element)) {
+        return false;
+    }
+    if (isBackControl(element) || elementLabelMatchesValue(element, sectionValue)) {
+        return false;
+    }
+    const target = normalizeControlTarget(plainTapTargets(element)[0] ?? element.selector);
+    if (isNavigationTarget(variant, target) || target === 'see all') {
+        return false;
+    }
+    return true;
+}
+function isLikelySectionHeading(variant, element) {
+    if (isHighValueContentCard(element)) {
+        return false;
+    }
+    const labels = element.labels.map(normalizeControlTarget);
+    if (labels.some((label) => label === 'see all' || isNavigationTarget(variant, label))) {
+        return false;
+    }
+    return labels.some((label) => {
+        if (!/[a-z]/i.test(label)) {
+            return false;
+        }
+        const words = label.split(/\s+/).filter(Boolean);
+        const lineCount = label.split(/\n+/).filter(Boolean).length;
+        return words.length <= 8 && lineCount <= 2;
+    });
+}
+function elementLabelMatchesValue(element, value) {
+    const normalizedValue = normalizeControlTarget(value);
+    if (!normalizedValue) {
+        return false;
+    }
+    return element.labels.some((label) => {
+        const normalizedLabel = normalizeControlTarget(label);
+        return (normalizedLabel === normalizedValue ||
+            normalizedLabel.includes(normalizedValue) ||
+            label.split(/\n+/).some((line) => normalizeControlTarget(line) === normalizedValue));
+    });
+}
+function coordinateArgsForElement(element) {
+    if (element.x === null ||
+        element.y === null ||
+        element.width === null ||
+        element.height === null ||
+        element.width <= 0 ||
+        element.height <= 0) {
+        return null;
+    }
+    if (isBackControl(element)) {
+        return {
+            x: Math.round(element.x + Math.min(40, element.width / 2)),
+            y: Math.round(element.y + element.height / 2)
+        };
+    }
+    return {
+        x: Math.round(element.x + element.width / 2),
+        y: Math.round(element.y + element.height / 2)
+    };
+}
+function isBackControl(element) {
+    if (!element.tag.toLowerCase().includes('button')) {
+        return false;
+    }
+    return element.labels.some((label) => label.split(/\n+/).some((line) => line.trim().toLowerCase() === 'back'));
+}
+function plainTapTargets(element) {
+    return element.targets
+        .filter((target) => !target.includes('='))
+        .sort((left, right) => tapTargetScore(left) - tapTargetScore(right));
+}
+function tapTargetScore(target) {
+    let score = target.length;
+    if (target.includes('\n')) {
+        score += 1000;
+    }
+    return score;
+}
+function isLikelyTapElement(element) {
+    if (element.enabled === false || element.visible === false) {
+        return false;
+    }
+    if (element.width !== null &&
+        element.height !== null &&
+        (element.width <= 0 || element.height <= 0)) {
+        return false;
+    }
+    const tag = element.tag.toLowerCase();
+    if (tag.includes('statictext') ||
+        tag.includes('image') ||
+        tag.includes('textfield') ||
+        isScrollableTag(tag)) {
+        return false;
+    }
+    if (tag.includes('button') || element.clickable) {
+        return true;
+    }
+    if (tag.includes('other')) {
+        const width = element.width ?? 0;
+        const height = element.height ?? 0;
+        return width >= 20 && height >= 20 && element.labels.length > 0;
+    }
+    return false;
+}
+async function repairToTarget(context, current, descriptor, depth, deadline, blockedTargets) {
+    if (Date.now() > deadline || depth <= 0) {
+        return null;
+    }
+    const attemptedTargets = new Map();
+    const attemptFrom = async (start, remainingDepth, route) => {
+        let cursor = start;
+        let depthLeft = remainingDepth;
+        let routeSoFar = route;
+        while (Date.now() <= deadline) {
+            if (variantContainsTarget(cursor.variant, descriptor)) {
+                return { found: true, current: cursor, route: routeSoFar, remainingDepth: depthLeft };
+            }
+            if (depthLeft <= 0) {
+                return { found: false, current: cursor, route: routeSoFar, remainingDepth: depthLeft };
+            }
+            const attemptsForVariant = attemptedTargets.get(cursor.variant.id) ?? new Set();
+            attemptedTargets.set(cursor.variant.id, attemptsForVariant);
+            const candidate = safeTapCandidates(cursor.variant).find((tapCandidate) => !blockedTargets.has(tapCandidate.target) &&
+                !blockedTargets.has(tapCandidate.key) &&
+                !attemptsForVariant.has(tapCandidate.key));
+            if (!candidate) {
+                return { found: false, current: cursor, route: routeSoFar, remainingDepth: depthLeft };
+            }
+            attemptsForVariant.add(candidate.key);
+            const args = candidate.args;
+            let observed;
+            try {
+                await context.adapter.tap(args);
+                observed = await observeCurrentScreen(context);
+            }
+            catch {
+                try {
+                    cursor = await observeCurrentScreen(context);
+                }
+                catch {
+                    // If both the exploratory tap and source read fail, keep the last observed screen.
+                }
+                continue;
+            }
+            recordEdgeSuccess(context, cursor.variant, observed.variant, 'tap', args, true);
+            const nextRoute = [...routeSoFar, summarizeControl('tap', candidate.target, 0.45)];
+            const nested = await attemptFrom(observed, depthLeft - 1, nextRoute);
+            if (nested.found) {
+                return nested;
+            }
+            if (nested.current.variant.id === cursor.variant.id) {
+                cursor = nested.current;
+                routeSoFar = nested.route;
+                continue;
+            }
+            cursor = nested.current;
+            depthLeft = nested.remainingDepth;
+            routeSoFar = nested.route;
+        }
+        return { found: false, current: cursor, route: routeSoFar, remainingDepth: depthLeft };
     };
     const attempt = await attemptFrom(current, depth, []);
     return attempt.found ? { current: attempt.current, route: attempt.route } : null;
@@ -625,63 +1914,537 @@ export async function runMappedCommand(context, command, args) {
         repairs: 0,
         path: context.filePath
     };
-    if (descriptor.kind === 'unknown' || descriptor.kind === 'coordinate') {
+    if (descriptor.kind === 'unknown') {
         const details = await context.adapter[command](args);
         return { ...details, map: metadata };
     }
     let before = await observeCurrentScreen(context);
-    if (!variantContainsTarget(before.variant, descriptor)) {
+    if (descriptor.kind === 'coordinate' || command === 'scroll') {
+        const details = await context.adapter[command](args);
+        const after = await observeCurrentScreen(context);
+        assertObservedEffect(command, args, before, after, descriptor);
+        recordEdgeSuccess(context, before.variant, after.variant, command, args, false);
+        return { ...details, map: metadata };
+    }
+    let liveTargetVisible = await liveContainsTarget(context, descriptor);
+    if (!variantContainsTarget(before.variant, descriptor) && !liveTargetVisible) {
         if (before.variant.auth_required) {
             throw new Error(`Target '${descriptor.target ?? descriptor.value}' requires authentication from the current screen`);
         }
-        const route = planRoute(context.map, before.variant.id, descriptor);
-        if (route.ambiguous) {
-            throw new Error(`Target '${descriptor.target ?? descriptor.value}' is ambiguous in the app map`);
-        }
-        if (route.authRequired) {
-            throw new Error(`Target '${descriptor.target ?? descriptor.value}' is behind an auth-required screen`);
-        }
-        if (route.edges.length > 0) {
-            context.summary.used = true;
-            metadata.routed = true;
-            metadata.route = route.edges.map(summarizeEdge);
-            const driven = await driveRoute(context, before, route.edges);
-            before = driven.current;
-            if (driven.failedEdge) {
-                const repair = await repairToTarget(context, before, descriptor, context.options.repairDepth, Date.now() + context.options.repairTimeoutMs, new Set(driven.failedEdge.target ? [driven.failedEdge.target] : []));
-                if (!repair) {
-                    throw new Error(`Cached app-map route for '${driven.failedEdge.target ?? driven.failedEdge.command}' could not be repaired within the bounded repair budget`);
-                }
-                context.summary.repaired = true;
-                context.summary.repairs += 1;
-                metadata.repaired = true;
-                metadata.repairs = context.summary.repairs;
-                metadata.route = [...metadata.route, ...repair.route];
-                before = repair.current;
+        if (routeableDescriptor(descriptor)) {
+            const route = planRoute(context.map, before.variant.id, descriptor);
+            if (route.ambiguous) {
+                throw new Error(`Target '${descriptor.target ?? descriptor.value}' is ambiguous in the app map`);
             }
-        }
-        else {
-            const repair = await repairToTarget(context, before, descriptor, context.options.repairDepth, Date.now() + context.options.repairTimeoutMs, new Set());
-            if (repair) {
+            if (route.authRequired) {
+                throw new Error(`Target '${descriptor.target ?? descriptor.value}' is behind an auth-required screen`);
+            }
+            if (route.edges.length > 0) {
                 context.summary.used = true;
-                context.summary.repaired = true;
-                context.summary.repairs += 1;
-                metadata.routed = repair.route.length > 0;
-                metadata.repaired = true;
-                metadata.repairs = context.summary.repairs;
-                metadata.route = repair.route;
-                before = repair.current;
+                metadata.routed = true;
+                metadata.route = route.edges.map(summarizeEdge);
+                if (route.diagnostics) {
+                    metadata.diagnostics = route.diagnostics;
+                }
+                const driven = await driveRoute(context, before, route.edges);
+                before = driven.current;
+                liveTargetVisible = await liveContainsTarget(context, descriptor);
+                const targetReachedDespiteStaleContract = variantContainsTarget(before.variant, descriptor) || liveTargetVisible;
+                if (driven.failedEdge && !targetReachedDespiteStaleContract) {
+                    if (!context.options.repair) {
+                        throw new Error(`Cached app-map route for '${driven.failedEdge.target ?? driven.failedEdge.command}' failed; rerun with repair enabled to explore an alternate route`);
+                    }
+                    const repair = await repairToTarget(context, before, descriptor, context.options.repairDepth, Date.now() + context.options.repairTimeoutMs, new Set(driven.failedEdge.target ? [driven.failedEdge.target] : []));
+                    if (!repair) {
+                        throw new Error(`Cached app-map route for '${driven.failedEdge.target ?? driven.failedEdge.command}' could not be repaired within the bounded repair budget`);
+                    }
+                    context.summary.repaired = true;
+                    context.summary.repairs += 1;
+                    metadata.repaired = true;
+                    metadata.repairs = context.summary.repairs;
+                    metadata.route = [...metadata.route, ...repair.route];
+                    before = repair.current;
+                    liveTargetVisible = await liveContainsTarget(context, descriptor);
+                }
+            }
+            else if (context.options.repair) {
+                const repair = await repairToTarget(context, before, descriptor, context.options.repairDepth, Date.now() + context.options.repairTimeoutMs, new Set());
+                if (repair) {
+                    context.summary.used = true;
+                    context.summary.repaired = true;
+                    context.summary.repairs += 1;
+                    metadata.routed = repair.route.length > 0;
+                    metadata.repaired = true;
+                    metadata.repairs = context.summary.repairs;
+                    metadata.route = repair.route;
+                    before = repair.current;
+                    liveTargetVisible = await liveContainsTarget(context, descriptor);
+                }
             }
         }
     }
-    if (!variantContainsTarget(before.variant, descriptor)) {
+    if (!variantContainsTarget(before.variant, descriptor) && !liveTargetVisible) {
         throw new Error(`Target '${descriptor.target ?? descriptor.value}' is not reachable from the current app-map state`);
     }
-    const details = await context.adapter[command](args);
+    const executableArgs = command === 'tap'
+        ? liveTargetVisible
+            ? currentScreenLiveTapArgs(before.variant, descriptor) ?? args
+            : currentScreenTapArgs(before.variant, descriptor) ?? args
+        : args;
+    const details = await context.adapter[command](executableArgs);
     const after = await observeCurrentScreen(context);
-    recordEdgeSuccess(context, before.variant, after.variant, command, args, false);
+    assertObservedEffect(command, executableArgs, before, after, descriptor);
+    recordEdgeSuccess(context, before.variant, after.variant, command, executableArgs, false);
     return { ...details, map: metadata };
 }
+function restoreAttemptDiagnostic(strategy, result, observed, match, target, command, error) {
+    return {
+        strategy,
+        result,
+        ...(command ? { command } : {}),
+        ...(target ? { target } : {}),
+        ...(observed
+            ? {
+                observed_variant_id: observed.variant.id,
+                observed_screen_id: observed.variant.screen_id
+            }
+            : {}),
+        ...(match ? { accepted_by: match.acceptedBy } : {}),
+        ...(error instanceof Error ? { error: error.message } : {})
+    };
+}
+function makeRestoreDiagnostic(from, target) {
+    return {
+        from_variant_id: from.variant.id,
+        target_variant_id: target.variant.id,
+        result: 'failed',
+        attempts: []
+    };
+}
+async function tryTapRestoreCandidate(context, current, target, candidate, strategy, diagnostic) {
+    const args = candidate.args;
+    try {
+        await context.adapter.tap(args);
+        const observed = await observeAfterAction(context, target);
+        recordEdgeSuccess(context, current.variant, observed.variant, 'tap', args, true);
+        const match = restoreMatch(observed, target);
+        diagnostic.attempts.push(restoreAttemptDiagnostic(strategy, match ? 'matched' : 'mismatched', observed, match, targetDescriptor('tap', args).target ?? candidate.target, 'tap'));
+        return { current: observed, match };
+    }
+    catch (error) {
+        diagnostic.attempts.push(restoreAttemptDiagnostic(strategy, 'error', undefined, null, candidate.target, 'tap', error));
+        try {
+            return { current: await observeCurrentScreen(context), match: null };
+        }
+        catch {
+            return { current, match: null };
+        }
+    }
+}
+async function tryScrollRestoreCandidate(context, current, target, candidate, diagnostic) {
+    const args = candidate.args;
+    try {
+        await context.adapter.scroll(args);
+        const observed = await observeAfterAction(context, target);
+        recordEdgeSuccess(context, current.variant, observed.variant, 'scroll', args, true);
+        const match = restoreMatch(observed, target);
+        diagnostic.attempts.push(restoreAttemptDiagnostic('reverse-scroll', match ? 'matched' : 'mismatched', observed, match, candidate.target, 'scroll'));
+        return { current: observed, match };
+    }
+    catch (error) {
+        diagnostic.attempts.push(restoreAttemptDiagnostic('reverse-scroll', 'error', undefined, null, candidate.target, 'scroll', error));
+        try {
+            return { current: await observeCurrentScreen(context), match: null };
+        }
+        catch {
+            return { current, match: null };
+        }
+    }
+}
+function targetRestoreCandidates(current, target) {
+    const preferredTarget = preferredNavigationTarget(target.variant);
+    return safeTapCandidates(current.variant).filter((candidate) => {
+        if (/^(back|close|dismiss|done)$/i.test(candidate.target)) {
+            return false;
+        }
+        const normalizedTarget = normalizeControlTarget(candidate.target);
+        if (preferredTarget) {
+            return normalizedTarget === preferredTarget;
+        }
+        if (isGlobalIdentityLabel(candidate.target)) {
+            return false;
+        }
+        const descriptor = targetDescriptor('tap', { target: candidate.target });
+        return descriptor.kind !== 'unknown' && variantContainsTarget(target.variant, descriptor);
+    });
+}
+function reverseScrollRestoreCandidates(current, target) {
+    if (!shouldTryReverseScrollRestore(current.variant, target.variant)) {
+        return [];
+    }
+    const args = { direction: 'up', percent: 70 };
+    return [
+        {
+            target: scrollTarget(args),
+            args,
+            key: 'scroll:up:70'
+        }
+    ];
+}
+function shouldTryReverseScrollRestore(current, target) {
+    if (hasScrollableSurface(current) || hasScrollableSurface(target)) {
+        return true;
+    }
+    const currentNavigationTarget = preferredNavigationTarget(current);
+    const targetNavigationTarget = preferredNavigationTarget(target);
+    if (currentNavigationTarget && targetNavigationTarget && currentNavigationTarget === targetNavigationTarget) {
+        return true;
+    }
+    return similarity(current.element_keys, target.element_keys) >= 0.2;
+}
+function navigationResetCandidates(current, root) {
+    const rootTarget = preferredNavigationTarget(root.variant);
+    if (!rootTarget) {
+        return [];
+    }
+    return safeTapCandidates(current.variant).filter((candidate) => normalizeControlTarget(candidate.target) === rootTarget);
+}
+function shortestRouteToVariant(map, fromVariantId, toVariantId) {
+    if (fromVariantId === toVariantId) {
+        return [];
+    }
+    const visited = new Set([fromVariantId]);
+    const queue = [{ variantId: fromVariantId, edges: [] }];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (!current) {
+            break;
+        }
+        const variant = map.variants.find((candidate) => candidate.id === current.variantId);
+        const outgoing = [
+            ...map.edges,
+            ...navigationVirtualEdges(map, variant)
+        ]
+            .filter((edge) => edge.from_variant_id === current.variantId && !edge.stale && edge.confidence >= 0.25 && replayableEdge(edge))
+            .sort((left, right) => right.confidence - left.confidence);
+        for (const edge of outgoing) {
+            if (visited.has(edge.to_variant_id)) {
+                continue;
+            }
+            const edges = [...current.edges, edge];
+            if (edge.to_variant_id === toVariantId) {
+                return edges;
+            }
+            visited.add(edge.to_variant_id);
+            queue.push({ variantId: edge.to_variant_id, edges });
+        }
+    }
+    return null;
+}
+async function restoreViaRootRoute(context, current, target, root, diagnostic) {
+    let resetCurrent = current;
+    const rootMatch = restoreMatch(resetCurrent, root);
+    if (!rootMatch) {
+        for (const candidate of navigationResetCandidates(resetCurrent, root)) {
+            const restored = await tryTapRestoreCandidate(context, resetCurrent, root, candidate, 'root-navigation', diagnostic);
+            resetCurrent = restored.current;
+            if (restored.match) {
+                break;
+            }
+        }
+    }
+    const matchedRoot = restoreMatch(resetCurrent, root);
+    if (!matchedRoot) {
+        return null;
+    }
+    if (restoreMatch(resetCurrent, target)) {
+        diagnostic.result = 'restored';
+        diagnostic.accepted_by = 'root';
+        return { current: target, restored: true, acceptedBy: 'root', diagnostic };
+    }
+    const route = shortestRouteToVariant(context.map, root.variant.id, target.variant.id);
+    if (!route || route.length === 0) {
+        return null;
+    }
+    const driven = await driveRoute(context, root, route);
+    const match = restoreMatch(driven.current, target);
+    diagnostic.attempts.push(restoreAttemptDiagnostic('root-route', match ? 'matched' : 'mismatched', driven.current, match ? { ...match, acceptedBy: 'root-route' } : null, route.map((edge) => edge.target ?? edge.command).join(' -> '), 'tap'));
+    if (!match) {
+        return { current: driven.current, restored: false, diagnostic };
+    }
+    diagnostic.result = 'restored';
+    diagnostic.accepted_by = 'root-route';
+    return { current: target, restored: true, acceptedBy: 'root-route', diagnostic };
+}
+async function restoreToVariant(context, current, target, root) {
+    const diagnostic = makeRestoreDiagnostic(current, target);
+    const initialMatch = restoreMatch(current, target);
+    if (initialMatch) {
+        diagnostic.result = 'restored';
+        diagnostic.accepted_by = initialMatch.acceptedBy;
+        return { current: target, restored: true, acceptedBy: initialMatch.acceptedBy, diagnostic };
+    }
+    const restoreTargets = safeTapCandidates(current.variant).filter((candidate) => /^(back|close|dismiss|done)$/i.test(candidate.target));
+    for (const restoreCandidate of restoreTargets) {
+        const restored = await tryTapRestoreCandidate(context, current, target, restoreCandidate, 'dismiss-control', diagnostic);
+        current = restored.current;
+        if (restored.match) {
+            diagnostic.result = 'restored';
+            diagnostic.accepted_by = restored.match.acceptedBy;
+            return { current: target, restored: true, acceptedBy: restored.match.acceptedBy, diagnostic };
+        }
+    }
+    for (const restoreCandidate of targetRestoreCandidates(current, target)) {
+        const restored = await tryTapRestoreCandidate(context, current, target, restoreCandidate, 'target-navigation', diagnostic);
+        current = restored.current;
+        if (restored.match) {
+            diagnostic.result = 'restored';
+            diagnostic.accepted_by = restored.match.acceptedBy;
+            return { current: target, restored: true, acceptedBy: restored.match.acceptedBy, diagnostic };
+        }
+    }
+    for (const restoreCandidate of reverseScrollRestoreCandidates(current, target)) {
+        const restored = await tryScrollRestoreCandidate(context, current, target, restoreCandidate, diagnostic);
+        current = restored.current;
+        if (restored.match) {
+            diagnostic.result = 'restored';
+            diagnostic.accepted_by = restored.match.acceptedBy;
+            return { current: target, restored: true, acceptedBy: restored.match.acceptedBy, diagnostic };
+        }
+    }
+    try {
+        await context.adapter.act({ name: 'back' });
+        const observed = await observeAfterAction(context, target);
+        const match = restoreMatch(observed, target);
+        diagnostic.attempts.push(restoreAttemptDiagnostic('platform-back', match ? 'matched' : 'mismatched', observed, match, 'back', 'act'));
+        if (match) {
+            diagnostic.result = 'restored';
+            diagnostic.accepted_by = match.acceptedBy;
+            return { current: target, restored: true, acceptedBy: match.acceptedBy, diagnostic };
+        }
+        current = observed;
+    }
+    catch (error) {
+        diagnostic.attempts.push(restoreAttemptDiagnostic('platform-back', 'error', undefined, null, 'back', 'act', error));
+    }
+    if (root) {
+        const rooted = await restoreViaRootRoute(context, current, target, root, diagnostic);
+        if (rooted) {
+            return rooted;
+        }
+    }
+    return { current, restored: false, diagnostic };
+}
+async function crawlAppMap(context, start) {
+    const visited = new Set();
+    const visitedTemplates = new Set();
+    const exploredRepeatedContentCandidates = new Set();
+    const attemptedTargets = new Map();
+    const restoreDiagnostics = [];
+    let restoreFailures = 0;
+    let actions = 0;
+    let stoppedReason = 'complete';
+    const restore = async (current, target) => {
+        const result = await restoreToVariant(context, current, target, start);
+        if (result.diagnostic.attempts.length > 0 || result.diagnostic.accepted_by) {
+            restoreDiagnostics.push(result.diagnostic);
+        }
+        if (!result.restored) {
+            restoreFailures += 1;
+        }
+        return result;
+    };
+    const markPartial = () => {
+        if (stoppedReason === 'complete') {
+            stoppedReason = 'partial';
+        }
+    };
+    const visit = async (origin, depth, allowScrollFirst = true) => {
+        if (depth <= 0) {
+            return origin;
+        }
+        if (actions >= context.options.crawlLimit) {
+            stoppedReason = 'limit';
+            return origin;
+        }
+        const originTemplateKey = crawlTemplateKey(origin.variant);
+        if (visitedTemplates.has(originTemplateKey) && !visited.has(origin.variant.id)) {
+            return origin;
+        }
+        visitedTemplates.add(originTemplateKey);
+        visited.add(origin.variant.id);
+        const attemptsForVariant = attemptedTargets.get(origin.variant.id) ?? new Set();
+        attemptedTargets.set(origin.variant.id, attemptsForVariant);
+        const candidates = safeTapCandidates(origin.variant, crawlCandidateOptions(origin.variant))
+            .filter((candidate) => !attemptsForVariant.has(candidate.key));
+        let current = origin;
+        const exploreScrollCandidates = async (scrollCandidatesToExplore) => {
+            for (const candidate of scrollCandidatesToExplore) {
+                if (actions >= context.options.crawlLimit) {
+                    stoppedReason = 'limit';
+                    return true;
+                }
+                if (!restoreMatch(current, origin)) {
+                    if (restoreMatch(current, start)) {
+                        markPartial();
+                        current = start;
+                        return true;
+                    }
+                    stoppedReason = 'restore_failed';
+                    return true;
+                }
+                current = origin;
+                attemptsForVariant.add(candidate.key);
+                const args = candidate.args;
+                let observed;
+                try {
+                    await context.adapter.scroll(args);
+                    actions += 1;
+                    observed = await observeAfterCrawlAction(context);
+                }
+                catch {
+                    try {
+                        current = await observeCurrentScreen(context);
+                    }
+                    catch {
+                        // Stay on the last known origin if a failed scroll also prevents source capture.
+                    }
+                    continue;
+                }
+                if (observed.variant.id === origin.variant.id || observed.observation.fingerprint === origin.observation.fingerprint) {
+                    current = origin;
+                    continue;
+                }
+                recordEdgeSuccess(context, origin.variant, observed.variant, 'scroll', args, true);
+                visited.add(observed.variant.id);
+                if (observed.variant.id !== origin.variant.id && depth > 1) {
+                    const nestedCurrent = await visit(observed, depth - 1, false);
+                    const restored = await restore(nestedCurrent, origin);
+                    current = restored.current;
+                    if (!restored.restored) {
+                        if (restoreMatch(current, start)) {
+                            markPartial();
+                            current = start;
+                            return true;
+                        }
+                        stoppedReason = 'restore_failed';
+                        return true;
+                    }
+                }
+                else {
+                    const restored = await restore(observed, origin);
+                    current = restored.current;
+                    if (!restored.restored) {
+                        if (restoreMatch(current, start)) {
+                            markPartial();
+                            if (restoreMatch(origin, start)) {
+                                current = origin;
+                                continue;
+                            }
+                            current = start;
+                            return true;
+                        }
+                        stoppedReason = 'restore_failed';
+                        return true;
+                    }
+                }
+            }
+            return false;
+        };
+        const scrollCandidates = crawlScrollCandidates(context, origin.variant)
+            .filter((candidate) => !attemptsForVariant.has(candidate.key));
+        if (allowScrollFirst && hasScrollableSurface(origin.variant) && await exploreScrollCandidates(scrollCandidates)) {
+            return current;
+        }
+        for (const candidate of candidates) {
+            const repeatedCandidateKey = repeatedContentCandidateKey(origin.variant, candidate);
+            if (repeatedCandidateKey && exploredRepeatedContentCandidates.has(repeatedCandidateKey)) {
+                continue;
+            }
+            if (actions >= context.options.crawlLimit) {
+                stoppedReason = 'limit';
+                return current;
+            }
+            if (!restoreMatch(current, origin)) {
+                if (restoreMatch(current, start)) {
+                    markPartial();
+                    return start;
+                }
+                stoppedReason = 'restore_failed';
+                return current;
+            }
+            current = origin;
+            attemptsForVariant.add(candidate.key);
+            const args = candidate.args;
+            let observed;
+            try {
+                await context.adapter.tap(args);
+                actions += 1;
+                observed = await observeAfterCrawlAction(context);
+            }
+            catch {
+                try {
+                    current = await observeCurrentScreen(context);
+                }
+                catch {
+                    // Stay on the last known origin if a failed tap also prevents source capture.
+                }
+                continue;
+            }
+            recordEdgeSuccess(context, origin.variant, observed.variant, 'tap', args, true);
+            visited.add(observed.variant.id);
+            if (repeatedCandidateKey && observed.variant.id !== origin.variant.id) {
+                exploredRepeatedContentCandidates.add(repeatedCandidateKey);
+            }
+            if (observed.variant.id !== origin.variant.id && depth > 1) {
+                const nestedCurrent = await visit(observed, depth - 1);
+                const restored = await restore(nestedCurrent, origin);
+                current = restored.current;
+                if (!restored.restored) {
+                    if (restoreMatch(current, start)) {
+                        markPartial();
+                        return start;
+                    }
+                    stoppedReason = 'restore_failed';
+                    return current;
+                }
+            }
+            else {
+                const restored = restoreMatch(observed, origin)
+                    ? { current: origin, restored: true }
+                    : await restore(observed, origin);
+                current = restored.current;
+                if (!restored.restored) {
+                    if (restoreMatch(current, start)) {
+                        markPartial();
+                        if (restoreMatch(origin, start)) {
+                            current = origin;
+                            continue;
+                        }
+                        return start;
+                    }
+                    stoppedReason = 'restore_failed';
+                    return current;
+                }
+            }
+        }
+        const remainingScrollCandidates = crawlScrollCandidates(context, origin.variant)
+            .filter((candidate) => !attemptsForVariant.has(candidate.key));
+        if (await exploreScrollCandidates(remainingScrollCandidates)) {
+            return current;
+        }
+        return current;
+    };
+    await visit(start, context.options.crawlDepth);
+    return {
+        enabled: true,
+        actions,
+        variants: visited.size,
+        stopped_reason: stoppedReason,
+        ...(restoreFailures > 0 ? { restore_failures: restoreFailures } : {}),
+        ...(restoreDiagnostics.length > 0 ? { restore_diagnostics: restoreDiagnostics } : {})
+    };
+}
 export async function discoverAppMap(adapter, options) {
     const context = createAppMapContext(adapter, options);
     if (!context) {
@@ -693,10 +2456,12 @@ export async function discoverAppMap(adapter, options) {
     }
     try {
         const observed = await observeCurrentScreen(context);
+        const crawl = context.options.crawl ? await crawlAppMap(context, observed) : undefined;
         const summary = persistAppMapContext(context);
         return {
             action: 'discover',
             map: summary,
+            ...(crawl ? { crawl } : {}),
             screen: {
                 variant_id: observed.variant.id,
                 screen_id: observed.variant.screen_id,