visor-ai 0.2.7 → 0.2.8

package/dist/appMap.js

@@ -0,0 +1,721 @@
+import { createHash, randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { resolveTapMode } from './adapters.js';
+import { canonicalJson, ensureDir, signatureFor, utcNowIso } from './utils.js';
+export const APP_MAP_SCHEMA_VERSION = 1;
+const RISKY_WORDS = [
+    'delete',
+    'remove',
+    'logout',
+    'log out',
+    'sign out',
+    'submit',
+    'send',
+    'pay',
+    'purchase',
+    'buy',
+    'confirm',
+    'destroy',
+    'archive'
+];
+const INPUT_WORDS = ['password', 'email', 'username', 'search', 'input', 'text field', 'textfield'];
+const AUTH_WORDS = ['login', 'log in', 'sign in', 'password', 'username', 'auth', 'authentication'];
+function envNoMap() {
+    const raw = process.env.VISOR_NO_MAP ?? process.env.VISOR_DISABLE_MAP;
+    return ['1', 'true', 'yes', 'on'].includes(String(raw ?? '').trim().toLowerCase());
+}
+function resolveOptions(platform, options) {
+    const enabled = options?.enabled !== false && !envNoMap();
+    return {
+        enabled,
+        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
+    };
+}
+function mapIdentity(platform, appId) {
+    return `${platform}:${appId}`;
+}
+function mapFilePath(rootDir, identity) {
+    const digest = createHash('sha256').update(identity, 'utf8').digest('hex').slice(0, 16);
+    return path.join(ensureDir(rootDir), `${digest}.json`);
+}
+function newMap(platform, appId) {
+    const now = utcNowIso();
+    return {
+        schema_version: APP_MAP_SCHEMA_VERSION,
+        identity: mapIdentity(platform, appId),
+        app_id: appId,
+        platform,
+        created_at: now,
+        updated_at: now,
+        screens: [],
+        variants: [],
+        edges: []
+    };
+}
+function readMap(filePath, platform, appId) {
+    if (!fs.existsSync(filePath)) {
+        return { map: newMap(platform, appId), scrubbed: false };
+    }
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        if (parsed.schema_version !== APP_MAP_SCHEMA_VERSION || parsed.identity !== mapIdentity(platform, appId)) {
+            return { map: newMap(platform, appId), scrubbed: false };
+        }
+        const originalEdgeCount = parsed.edges.length;
+        parsed.edges = parsed.edges.filter((edge) => !isValueBearingAction(edge.command, edge.args));
+        return { map: parsed, scrubbed: parsed.edges.length !== originalEdgeCount };
+    }
+    catch {
+        return { map: newMap(platform, appId), scrubbed: false };
+    }
+}
+function writeMap(filePath, map) {
+    ensureDir(path.dirname(filePath));
+    const tempPath = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+    fs.writeFileSync(tempPath, `${JSON.stringify(map, null, 2)}\n`, 'utf8');
+    fs.renameSync(tempPath, filePath);
+}
+export function createMapSummary(adapter, options) {
+    const platform = adapter.capability().platform;
+    const resolved = resolveOptions(platform, options);
+    const identity = mapIdentity(platform, resolved.appId);
+    return {
+        enabled: resolved.enabled,
+        used: false,
+        updated: false,
+        repaired: false,
+        repairs: 0,
+        schema_version: APP_MAP_SCHEMA_VERSION,
+        path: resolved.enabled ? mapFilePath(resolved.rootDir, identity) : undefined,
+        identity
+    };
+}
+export function createAppMapContext(adapter, options) {
+    const platform = adapter.capability().platform;
+    const resolved = resolveOptions(platform, options);
+    if (!resolved.enabled) {
+        return null;
+    }
+    const identity = mapIdentity(platform, resolved.appId);
+    const filePath = mapFilePath(resolved.rootDir, identity);
+    const summary = createMapSummary(adapter, options);
+    const loaded = readMap(filePath, platform, resolved.appId);
+    return {
+        adapter,
+        map: loaded.map,
+        filePath,
+        options: resolved,
+        summary,
+        changed: loaded.scrubbed
+    };
+}
+export function persistAppMapContext(context) {
+    if (!context) {
+        return undefined;
+    }
+    context.summary.updated = context.summary.updated || context.changed;
+    if (context.changed) {
+        context.map.updated_at = utcNowIso();
+        writeMap(context.filePath, context.map);
+        context.changed = false;
+    }
+    return context.summary;
+}
+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] ?? '';
+    }
+    return attrs;
+}
+function normalizeLabel(value) {
+    return value
+        .replace(/[0-9a-f]{8,}/gi, '<id>')
+        .replace(/\b\d{1,2}:\d{2}(?::\d{2})?\b/g, '<time>')
+        .replace(/\b\d+\b/g, '<number>')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .toLowerCase();
+}
+function unique(values) {
+    return Array.from(new Set(values.filter((value) => value.trim() !== '')));
+}
+function isLikelyFormControl(tag, attrs) {
+    const haystack = [
+        tag,
+        attrs.type ?? '',
+        attrs.class ?? '',
+        attrs.name ?? '',
+        attrs.label ?? '',
+        attrs.placeholder ?? ''
+    ]
+        .join(' ')
+        .toLowerCase();
+    return [
+        'input',
+        'textfield',
+        'text field',
+        'edittext',
+        'secure',
+        'password',
+        'email',
+        'username',
+        'search',
+        'phone',
+        'credit',
+        'card'
+    ].some((word) => haystack.includes(word));
+}
+function redactLabel(value) {
+    return value
+        .replace(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi, '<redacted-email>')
+        .replace(/\b(?:\+?\d[\d .()-]{7,}\d)\b/g, '<redacted-phone>')
+        .replace(/\b(?:\d[ -]*?){13,19}\b/g, '<redacted-card>');
+}
+function classifyControl(tag, labels, attrs) {
+    const haystack = [...labels, tag, attrs.type ?? '', attrs.class ?? ''].join(' ').toLowerCase();
+    if (RISKY_WORDS.some((word) => haystack.includes(word))) {
+        return 'risky';
+    }
+    if (INPUT_WORDS.some((word) => haystack.includes(word))) {
+        return 'needs-input';
+    }
+    if (tag.toLowerCase().includes('button') ||
+        attrs.clickable === 'true' ||
+        attrs.enabled === 'true' ||
+        attrs.accessible === 'true') {
+        return 'safe';
+    }
+    return 'unknown';
+}
+function extractElements(source) {
+    const elements = [];
+    const tagPattern = /<([A-Za-z][A-Za-z0-9_.:-]*)([^<>]*?)(?:\/>|>([^<>]*)<\/\1>)/g;
+    for (const match of source.matchAll(tagPattern)) {
+        const tag = match[1];
+        const attrs = attributeMap(match[2] ?? '');
+        const bodyText = (match[3] ?? '').trim();
+        const formControl = isLikelyFormControl(tag, attrs);
+        const rawLabels = unique([
+            redactLabel(attrs.name ?? ''),
+            redactLabel(attrs.label ?? ''),
+            formControl ? '' : redactLabel(attrs.text ?? ''),
+            formControl ? '' : redactLabel(attrs.value ?? ''),
+            redactLabel(attrs['content-desc'] ?? ''),
+            redactLabel(attrs['contentDescription'] ?? ''),
+            formControl ? '' : redactLabel(bodyText)
+        ]);
+        const id = attrs['resource-id'] ?? attrs.id ?? attrs.identifier ?? '';
+        const targets = unique([
+            ...rawLabels,
+            ...rawLabels.map((label) => `text=${label}`),
+            id ? `id=${id}` : ''
+        ]);
+        if (targets.length === 0) {
+            continue;
+        }
+        const stable = Boolean(rawLabels.length > 0 || id);
+        const selector = id ? `id=${id}` : rawLabels[0] ?? targets[0];
+        elements.push({
+            tag,
+            selector,
+            targets,
+            labels: rawLabels,
+            stable,
+            safety: classifyControl(tag, rawLabels, attrs)
+        });
+    }
+    return elements;
+}
+function observeSource(source) {
+    const elements = extractElements(source);
+    const normalizedLabels = elements.flatMap((element) => element.labels.map(normalizeLabel));
+    const elementKeys = unique([
+        ...elements.flatMap((element) => element.targets.map(normalizeLabel)),
+        ...normalizedLabels
+    ]).sort();
+    const normalizedFingerprint = signatureFor(elementKeys);
+    const authRequired = AUTH_WORDS.some((word) => normalizedLabels.some((label) => label.includes(word)));
+    return {
+        fingerprint: signatureFor(source),
+        normalized_fingerprint: normalizedFingerprint,
+        elements,
+        element_keys: elementKeys,
+        auth_required: authRequired
+    };
+}
+function similarity(left, right) {
+    if (left.length === 0 && right.length === 0) {
+        return 1;
+    }
+    const leftSet = new Set(left);
+    const rightSet = new Set(right);
+    const intersection = Array.from(leftSet).filter((value) => rightSet.has(value)).length;
+    const union = new Set([...left, ...right]).size;
+    const jaccard = union === 0 ? 0 : intersection / union;
+    const smaller = Math.min(leftSet.size, rightSet.size);
+    const containment = smaller === 0 ? 0 : intersection / smaller;
+    return containment >= 0.8 ? Math.max(jaccard, containment) : jaccard;
+}
+function elementIdentityKeys(elements) {
+    return unique(elements.flatMap((element) => {
+        const tag = element.tag.toLowerCase();
+        const labels = element.labels.map(normalizeLabel);
+        const ids = element.targets.filter((target) => target.startsWith('id=')).map(normalizeLabel);
+        return [...labels, ...ids].map((value) => `${tag}:${element.safety}:${value}`);
+    })).sort();
+}
+function newVariant(map, observation) {
+    const screen = {
+        id: `screen_${map.screens.length + 1}`,
+        variant_ids: []
+    };
+    const variant = {
+        id: `variant_${map.variants.length + 1}`,
+        screen_id: screen.id,
+        fingerprint: observation.fingerprint,
+        normalized_fingerprint: observation.normalized_fingerprint,
+        elements: observation.elements,
+        element_keys: observation.element_keys,
+        auth_required: observation.auth_required,
+        observations: 1,
+        confidence: 0.6,
+        last_observed_at: utcNowIso()
+    };
+    screen.variant_ids.push(variant.id);
+    map.screens.push(screen);
+    map.variants.push(variant);
+    return variant;
+}
+function upsertVariant(map, observation) {
+    let best = null;
+    let bestScore = 0;
+    for (const variant of map.variants) {
+        const score = variant.normalized_fingerprint === observation.normalized_fingerprint
+            ? 1
+            : similarity(elementIdentityKeys(variant.elements), elementIdentityKeys(observation.elements));
+        if (score > bestScore) {
+            best = variant;
+            bestScore = score;
+        }
+    }
+    if (!best || bestScore < 0.45) {
+        return {
+            observation,
+            variant: newVariant(map, observation),
+            created: true
+        };
+    }
+    best.fingerprint = observation.fingerprint;
+    best.normalized_fingerprint = observation.normalized_fingerprint;
+    best.elements = observation.elements;
+    best.element_keys = observation.element_keys;
+    best.auth_required = observation.auth_required;
+    best.observations += 1;
+    best.confidence = Math.min(1, best.confidence + 0.05);
+    best.last_observed_at = utcNowIso();
+    return {
+        observation,
+        variant: best,
+        created: false
+    };
+}
+async function observeCurrentScreen(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 });
+    const args = details.args;
+    const sourceArgs = args && typeof args === 'object' && !Array.isArray(args)
+        ? args
+        : {};
+    const detailPath = typeof sourceArgs.path === 'string'
+        ? sourceArgs.path
+        : sourcePath;
+    const source = fs.existsSync(detailPath) ? fs.readFileSync(detailPath, 'utf8') : '';
+    try {
+        fs.rmSync(detailPath, { force: true });
+    }
+    catch {
+        // Source observations are transient; stale temp files should not fail a run.
+    }
+    const observed = upsertVariant(context.map, observeSource(source));
+    context.changed = true;
+    return observed;
+}
+function targetDescriptor(command, args) {
+    if (isValueBearingAction(command, args)) {
+        return { kind: 'unknown', confidence: 0 };
+    }
+    if (command === 'tap') {
+        try {
+            if (resolveTapMode(args) === 'coordinates') {
+                return { kind: 'coordinate', confidence: 0 };
+            }
+        }
+        catch {
+            return { kind: 'unknown', confidence: 0 };
+        }
+    }
+    const target = typeof args.target === 'string' ? args.target : undefined;
+    if (!target) {
+        return { kind: 'unknown', confidence: 0 };
+    }
+    if (target.startsWith('text=')) {
+        return { kind: 'text', target, value: target.slice(5), confidence: 0.6 };
+    }
+    if (target.startsWith('xpath=')) {
+        return { kind: 'unknown', target, value: target.slice(6), confidence: 0.2 };
+    }
+    return { kind: 'stable', target, value: target.replace(/^(id=|accessibility=)/, ''), confidence: 0.9 };
+}
+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) {
+    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);
+    });
+}
+function candidateVariants(map, descriptor) {
+    return map.variants.filter((variant) => variantContainsTarget(variant, descriptor));
+}
+function summarizeEdge(edge) {
+    return {
+        command: edge.command,
+        target: edge.target,
+        confidence: Math.round(edge.confidence * 100) / 100
+    };
+}
+function summarizeControl(command, target, confidence) {
+    return {
+        command,
+        target,
+        confidence: Math.round(confidence * 100) / 100
+    };
+}
+function planRoute(map, fromVariantId, descriptor) {
+    if (descriptor.kind === 'coordinate' || descriptor.kind === 'unknown') {
+        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: [] }];
+    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) };
+        }
+        const outgoing = map.edges
+            .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;
+            }
+            visited.add(edge.to_variant_id);
+            queue.push({ variantId: edge.to_variant_id, edges: [...current.edges, edge] });
+        }
+    }
+    return { edges: [], ambiguous: false, authRequired: destinations.some((variant) => variant.auth_required) };
+}
+function contractTargets(variant) {
+    return variant.elements
+        .filter((element) => element.stable)
+        .flatMap((element) => element.targets)
+        .slice(0, 8);
+}
+function matchingEdge(map, fromVariantId, command, target) {
+    return map.edges.find((edge) => edge.from_variant_id === fromVariantId &&
+        edge.command === command &&
+        String(edge.target ?? '') === String(target ?? ''));
+}
+function recordEdgeSuccess(context, from, to, command, args, candidate) {
+    if (from.id === to.id) {
+        return;
+    }
+    const descriptor = targetDescriptor(command, args);
+    if (descriptor.kind === 'coordinate' || descriptor.kind === 'unknown') {
+        return;
+    }
+    const edge = matchingEdge(context.map, from.id, command, descriptor.target);
+    if (edge) {
+        edge.to_variant_id = to.id;
+        edge.successes += 1;
+        edge.failures = 0;
+        edge.stale = false;
+        edge.candidate = edge.candidate && edge.successes < 2;
+        edge.confidence = Math.min(1, edge.confidence + 0.15);
+        edge.destination_contract = {
+            variant_id: to.id,
+            required_targets: contractTargets(to),
+            normalized_fingerprint: to.normalized_fingerprint
+        };
+        edge.last_observed_at = utcNowIso();
+        context.changed = true;
+        return;
+    }
+    context.map.edges.push({
+        id: `edge_${context.map.edges.length + 1}`,
+        from_variant_id: from.id,
+        to_variant_id: to.id,
+        command,
+        args: structuredClone(args),
+        target: descriptor.target,
+        confidence: candidate ? 0.45 : descriptor.confidence,
+        successes: 1,
+        failures: 0,
+        stale: false,
+        candidate,
+        destination_contract: {
+            variant_id: to.id,
+            required_targets: contractTargets(to),
+            normalized_fingerprint: to.normalized_fingerprint
+        },
+        last_observed_at: utcNowIso()
+    });
+    context.changed = true;
+}
+function demoteEdge(context, edge) {
+    edge.failures += 1;
+    edge.confidence = Math.max(0, edge.confidence - 0.25);
+    if (edge.failures >= 2 || edge.confidence < 0.25) {
+        edge.stale = true;
+    }
+    edge.last_observed_at = utcNowIso();
+    context.changed = true;
+}
+function satisfiesContract(edge, observed) {
+    if (observed.variant.id === edge.destination_contract.variant_id) {
+        return true;
+    }
+    const observedTargets = new Set(observed.variant.elements.flatMap((element) => element.targets));
+    const required = edge.destination_contract.required_targets;
+    if (required.length === 0) {
+        return observed.variant.normalized_fingerprint === edge.destination_contract.normalized_fingerprint;
+    }
+    const matched = required.filter((target) => observedTargets.has(target)).length;
+    return matched / required.length >= 0.6;
+}
+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);
+        }
+        catch {
+            demoteEdge(context, edge);
+            try {
+                current = await observeCurrentScreen(context);
+            }
+            catch {
+                // Keep the last known screen if the app cannot provide source after a failed cached action.
+            }
+            return { current, failedEdge: edge };
+        }
+        if (!satisfiesContract(edge, observed)) {
+            demoteEdge(context, edge);
+            return { current: observed, failedEdge: edge };
+        }
+        recordEdgeSuccess(context, current.variant, observed.variant, edge.command, args, false);
+        current = observed;
+    }
+    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] ?? '';
+    }));
+}
+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 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;
+        }
+        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;
+}
+export async function runMappedCommand(context, command, args) {
+    const descriptor = targetDescriptor(command, args);
+    const metadata = {
+        enabled: true,
+        routed: false,
+        route: [],
+        repaired: false,
+        repairs: 0,
+        path: context.filePath
+    };
+    if (descriptor.kind === 'unknown' || descriptor.kind === 'coordinate') {
+        const details = await context.adapter[command](args);
+        return { ...details, map: metadata };
+    }
+    let before = await observeCurrentScreen(context);
+    if (!variantContainsTarget(before.variant, descriptor)) {
+        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;
+            }
+        }
+        else {
+            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;
+            }
+        }
+    }
+    if (!variantContainsTarget(before.variant, descriptor)) {
+        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 after = await observeCurrentScreen(context);
+    recordEdgeSuccess(context, before.variant, after.variant, command, args, false);
+    return { ...details, map: metadata };
+}
+export async function discoverAppMap(adapter, options) {
+    const context = createAppMapContext(adapter, options);
+    if (!context) {
+        return {
+            action: 'discover',
+            map: createMapSummary(adapter, options),
+            screen: null
+        };
+    }
+    try {
+        const observed = await observeCurrentScreen(context);
+        const summary = persistAppMapContext(context);
+        return {
+            action: 'discover',
+            map: summary,
+            screen: {
+                variant_id: observed.variant.id,
+                screen_id: observed.variant.screen_id,
+                element_count: observed.variant.elements.length,
+                auth_required: observed.variant.auth_required,
+                created: observed.created
+            }
+        };
+    }
+    finally {
+        persistAppMapContext(context);
+    }
+}
+export function mapDebugSnapshot(rootDir, platform, appId) {
+    const identity = mapIdentity(platform, appId);
+    const filePath = mapFilePath(rootDir, identity);
+    if (!fs.existsSync(filePath)) {
+        return null;
+    }
+    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    return JSON.parse(canonicalJson(parsed));
+}

package/dist/cli.js

@@ -1,10 +1,11 @@
 import fs from 'node:fs';
 import { DEFAULT_SERVER_URL } from './adapters.js';
-import { DaemonRequestTimeoutError, DaemonUnavailableError, runDaemonAction, runDaemonScenario, startVisorDaemon, statusVisorDaemon, stopVisorDaemon } from './daemon.js';
+import { DaemonOperationError, DaemonRequestTimeoutError, DaemonUnavailableError, runDaemonAction, runDaemonDiscover, runDaemonScenario, startVisorDaemon, statusVisorDaemon, stopVisorDaemon } from './daemon.js';
 import { DeviceSelectionError, resolveRunningDevice } from './devices.js';
 import { makeError } from './errors.js';
+import { LocalRuntimeAdapter } from './localRuntime.js';
 import { writeReports } from './report.js';
-import { determinismCheck } from './runner.js';
+import { determinismCheck, runScenario } from './runner.js';
 import { errorMessage, makeId, utcNowIso } from './utils.js';
 import { parseAndValidate } from './validator.js';
 function packageVersion() {
@@ -29,6 +30,7 @@ const ALL_COMMANDS = new Set([
     ...ACTION_COMMANDS,
     'validate',
     'run',
+    'discover',
     'benchmark',
     'report',
     'start',
@@ -44,6 +46,7 @@ const GLOBAL_SPEC = {
     'server-url': 'string',
     'app-id': 'string',
     attach: 'boolean',
+    'no-map': 'boolean',
     verbose: 'boolean'
 };
 const ACTION_SPEC = {
@@ -68,9 +71,20 @@ const COMMAND_SPECS = {
         timeout: 'number',
         output: 'string',
         format: 'string',
+        runtime: 'string',
         'server-url': 'string',
         'app-id': 'string',
-        attach: 'boolean'
+        attach: 'boolean',
+        'no-map': 'boolean'
+    },
+    discover: {
+        device: 'string',
+        timeout: 'number',
+        format: 'string',
+        'server-url': 'string',
+        'app-id': 'string',
+        attach: 'boolean',
+        'no-map': 'boolean'
     },
     benchmark: {
         runs: 'number',
@@ -81,7 +95,8 @@ const COMMAND_SPECS = {
         format: 'string',
         'server-url': 'string',
         'app-id': 'string',
-        attach: 'boolean'
+        attach: 'boolean',
+        'no-map': 'boolean'
     },
     report: { format: 'string' },
     start: {
@@ -117,8 +132,9 @@ function helpText() {
         '',
         'Commands:',
         '  validate <scenario>',
-        '  run <scenario> [--output <dir>]',
+        '  run <scenario> [--output <dir>] [--runtime appium|local]',
         '  benchmark <scenario> [--runs <n>] [--threshold <percent>]',
+        '  discover [--app-id <id>]',
         '  report [path]',
         '  start [--server-url <url>] [--appium-cmd <cmd>]',
         '  status [--server-url <url>]',
@@ -127,8 +143,11 @@ function helpText() {
         '',
         'Examples:',
         '  visor validate scenarios/checkout-smoke.json',
+        '  visor run path/to/scenario.json --runtime local --output artifacts-local',
         '  visor start --server-url http://127.0.0.1:4723',
         '  visor run scenarios/checkout-smoke.json --output artifacts-test',
+        '  visor run scenarios/checkout-smoke.json --no-map',
+        '  visor discover --app-id com.example.app',
         '  visor scroll --device emulator-5554 --direction down',
         '  visor status'
     ].join('\n');
@@ -216,7 +235,10 @@ async function resolvedRuntime(options) {
         output_dir: String(options.output ?? 'artifacts'),
         server_url: String(options['server-url'] ?? DEFAULT_SERVER_URL),
         app_id: typeof options['app-id'] === 'string' ? options['app-id'] : undefined,
-        attach_to_running: Boolean(options.attach)
+        attach_to_running: Boolean(options.attach),
+        map: {
+            enabled: !Boolean(options['no-map'])
+        }
     };
 }
 function actionArgs(command, options) {
@@ -228,8 +250,10 @@ function actionArgs(command, options) {
         'verbose',
         'server-url',
         'seed',
+        'runtime',
         'app-id',
-        'attach'
+        'attach',
+        'no-map'
     ]);
     const args = Object.entries(options).reduce((acc, [key, value]) => {
         if (!commonIgnored.has(key) && value !== undefined) {
@@ -242,6 +266,10 @@ function actionArgs(command, options) {
     }
     return args;
 }
+function unsupportedRuntimeResult(commandId, startedAt, runtime) {
+    const response = envelopeFail(commandId, startedAt, 'INPUT_ERROR', 'Unsupported runtime', `Unsupported runtime '${String(runtime)}'`, 'Use --runtime appium or --runtime local');
+    return { code: 1, response };
+}
 function isTargetInitializationError(error) {
     const message = errorMessage(error);
     return (message.includes('Failed to create WebdriverIO Appium session') ||
@@ -270,6 +298,7 @@ function cmdHelp() {
         commands: Array.from(ALL_COMMANDS),
         examples: [
             'visor validate scenarios/checkout-smoke.json',
+            'visor run path/to/scenario.json --runtime local --output artifacts-local',
             'visor start --server-url http://127.0.0.1:4723',
             'visor run scenarios/checkout-smoke.json --output artifacts-test',
             'visor scroll --device emulator-5554 --direction down',
@@ -313,6 +342,19 @@ export async function cmdValidate(parsed) {
         return { code: 1, response };
     }
 }
+async function cmdRunLocal(commandId, startedAt, scenario, warnings, runtime) {
+    const result = await runScenario(scenario, new LocalRuntimeAdapter(), runtime.device, runtime.timeout, runtime.output_dir);
+    const outputs = writeReports(result, runtime.output_dir);
+    const response = result.status === 'ok'
+        ? envelopeOk(commandId, startedAt, Object.values(outputs), 'report')
+        : envelopeFail(commandId, startedAt, result.error?.code ?? 'ACTION_ERROR', result.error?.message ?? 'Local runtime scenario failed', result.error?.likely_cause ?? 'The deterministic local runtime did not satisfy the scenario', result.error?.next_step ?? 'Inspect local runtime scenario artifacts and retry');
+    response.artifacts = Object.values(outputs);
+    response.data = {
+        run: result,
+        warnings
+    };
+    return { code: result.status === 'ok' ? 0 : 2, response };
+}
 export async function cmdRun(parsed) {
     const commandId = makeId('cmd');
     const startedAt = utcNowIso();
@@ -323,6 +365,24 @@ export async function cmdRun(parsed) {
         response.data = { issues };
         return { code: 1, response };
     }
+    if (parsed.options.runtime !== undefined &&
+        parsed.options.runtime !== 'appium' &&
+        parsed.options.runtime !== 'local') {
+        return unsupportedRuntimeResult(commandId, startedAt, parsed.options.runtime);
+    }
+    if (parsed.options.runtime === 'local') {
+        const runtime = {
+            device: 'local',
+            timeout: typeof parsed.options.timeout === 'number'
+                ? parsed.options.timeout
+                : typeof scenario.config.timeoutMs === 'number'
+                    ? scenario.config.timeoutMs
+                    : undefined,
+            output_dir: String(parsed.options.output ??
+                (typeof scenario.config.artifactsDir === 'string' ? scenario.config.artifactsDir : 'artifacts'))
+        };
+        return cmdRunLocal(commandId, startedAt, scenario, warningIssues(issues), runtime);
+    }
     let runtime;
     try {
         runtime = await resolvedRuntime({
@@ -351,7 +411,10 @@ export async function cmdRun(parsed) {
             device: runtime.device,
             app_id: runtime.app_id,
             attach_to_running: runtime.attach_to_running
-        }, scenario, runtime.device, runtime.timeout, runtime.output_dir);
+        }, scenario, runtime.device, runtime.timeout, runtime.output_dir, {
+            ...runtime.map,
+            appId: runtime.app_id
+        });
         const outputs = writeReports(result, runtime.output_dir);
         if (result.status === 'fail' && result.error) {
             const response = envelopeFail(commandId, startedAt, result.error.code, result.error.message, result.error.likely_cause, result.error.next_step);
@@ -384,6 +447,51 @@ export async function cmdRun(parsed) {
         return { code: 1, response };
     }
 }
+export async function cmdDiscover(parsed) {
+    const commandId = makeId('cmd');
+    const startedAt = utcNowIso();
+    let runtime;
+    try {
+        runtime = await resolvedRuntime(parsed.options);
+    }
+    catch (error) {
+        if (!(error instanceof DeviceSelectionError)) {
+            throw error;
+        }
+        const response = envelopeFail(commandId, startedAt, 'TARGET_ERROR', 'Device selection failed', error.message, 'Start one target device or rerun with --device <device-id>');
+        response.data = { devices: error.devices };
+        return { code: 1, response };
+    }
+    try {
+        const result = await runDaemonDiscover({
+            platform: runtime.platform,
+            server_url: runtime.server_url,
+            device: runtime.device,
+            app_id: runtime.app_id,
+            attach_to_running: runtime.attach_to_running
+        }, {
+            ...runtime.map,
+            appId: runtime.app_id
+        });
+        const response = envelopeOk(commandId, startedAt, [], 'run');
+        response.data = result;
+        return { code: 0, response };
+    }
+    catch (error) {
+        const isDaemonUnavailable = error instanceof DaemonUnavailableError;
+        const isDaemonTimeout = error instanceof DaemonRequestTimeoutError;
+        const response = envelopeFail(commandId, startedAt, isDaemonUnavailable || isDaemonTimeout ? 'TARGET_ERROR' : 'ACTION_ERROR', isDaemonUnavailable
+            ? 'discover requires visor start'
+            : isDaemonTimeout
+                ? 'discover timed out waiting for Visor daemon'
+                : 'discover failed', errorMessage(error), isDaemonUnavailable
+            ? 'Run `visor start`, verify the target emulator/simulator is booted, and retry.'
+            : isDaemonTimeout
+                ? 'Inspect .visor/daemon/daemon.log and .visor/appium/*.log, then retry or run `visor stop --force` before restarting.'
+                : 'Check target app state and retry');
+        return { code: 1, response };
+    }
+}
 export async function cmdBenchmark(parsed) {
     const commandId = makeId('cmd');
     const startedAt = utcNowIso();
@@ -428,7 +536,10 @@ export async function cmdBenchmark(parsed) {
                 device: runtime.device,
                 app_id: runtime.app_id,
                 attach_to_running: runtime.attach_to_running
-            }, scenario, runtime.device, runtime.timeout, runtime.output_dir);
+            }, scenario, runtime.device, runtime.timeout, runtime.output_dir, {
+                ...runtime.map,
+                appId: runtime.app_id
+            });
             writeReports(result, runtime.output_dir);
             signatures.push(result.determinism_signature);
             runIds.push(result.run_id);
@@ -499,7 +610,10 @@ export async function cmdAction(command, parsed) {
             device: options.device,
             app_id: options.app_id,
             attach_to_running: options.attach_to_running
-        }, command, actionArgs(command, parsed.options));
+        }, command, actionArgs(command, parsed.options), {
+            ...options.map,
+            appId: options.app_id
+        });
         const actionPayload = payload.args;
         if (actionPayload && typeof actionPayload === 'object' && !Array.isArray(actionPayload)) {
             const maybePath = actionPayload.path;
@@ -509,6 +623,9 @@ export async function cmdAction(command, parsed) {
         }
     }
     catch (error) {
+        if (error instanceof DaemonOperationError && error.data) {
+            payload = error.data;
+        }
         actionError = error;
     }
     if (actionError) {
@@ -589,6 +706,9 @@ export async function executeCommand(argv) {
     if (parsed.command === 'run') {
         return cmdRun(parsed);
     }
+    if (parsed.command === 'discover') {
+        return cmdDiscover(parsed);
+    }
     if (parsed.command === 'benchmark') {
         return cmdBenchmark(parsed);
     }

package/dist/daemon.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { DEFAULT_SERVER_URL, getAdapter } from './adapters.js';
+import { createAppMapContext, createMapSummary, discoverAppMap, persistAppMapContext, runMappedCommand } from './appMap.js';
 import { DEFAULT_STARTUP_TIMEOUT_SECONDS, startManagedAppium, statusManagedAppium, stopManagedAppium } from './appiumLifecycle.js';
 import { runScenario } from './runner.js';
 import { ensureDir, errorMessage, resolveExecutable, sleep } from './utils.js';
@@ -19,6 +20,22 @@ export class DaemonRequestTimeoutError extends Error {
         this.name = 'DaemonRequestTimeoutError';
     }
 }
+export class DaemonOperationError extends Error {
+    data;
+    constructor(message, data) {
+        super(message);
+        this.name = 'DaemonOperationError';
+        this.data = data;
+    }
+}
+class DaemonResponseError extends Error {
+    data;
+    constructor(message, data) {
+        super(message);
+        this.name = 'DaemonResponseError';
+        this.data = data;
+    }
+}
 function daemonDir() {
     return ensureDir(path.join(process.cwd(), '.visor', 'daemon'));
 }
@@ -139,7 +156,7 @@ async function requestDaemon(request, timeoutMs = 1000) {
 async function daemonRequestData(request, timeoutMs = 1000) {
     const response = await requestDaemon(request, timeoutMs);
     if (!response.ok) {
-        throw new Error(response.error);
+        throw new DaemonOperationError(response.error, response.data);
     }
     return response.data;
 }
@@ -343,11 +360,14 @@ export async function stopVisorDaemon(serverUrl = DEFAULT_SERVER_URL, force = fa
         appium: await statusManagedAppium(serverUrl)
     };
 }
-export async function runDaemonAction(runtime, command, args) {
-    return daemonRequestData({ type: 'action', runtime, command, args }, 300000);
+export async function runDaemonAction(runtime, command, args, mapOptions) {
+    return daemonRequestData({ type: 'action', runtime, command, args, mapOptions }, 300000);
 }
-export async function runDaemonScenario(runtime, scenario, device, timeout, outputDir) {
-    return daemonRequestData({ type: 'scenario', runtime, scenario, device, timeout, outputDir }, 600000);
+export async function runDaemonScenario(runtime, scenario, device, timeout, outputDir, mapOptions) {
+    return daemonRequestData({ type: 'scenario', runtime, scenario, device, timeout, outputDir, mapOptions }, 600000);
+}
+export async function runDaemonDiscover(runtime, mapOptions) {
+    return daemonRequestData({ type: 'discover', runtime, mapOptions }, 300000);
 }
 export async function runDaemonFromEnv() {
     const options = {
@@ -398,10 +418,10 @@ export async function runDaemonFromEnv() {
             // The backing WebDriver session is already gone; removing it from the cache is enough.
         }
     }
-    async function runActionWithSessionRetry(runtime, command, args) {
+    async function runActionWithSessionRetry(runtime, command, args, mapOptions) {
         const adapter = await sessionFor(runtime);
         try {
-            return await adapter[command](args);
+            return await runActionWithMap(adapter, command, args, mapOptions);
         }
         catch (error) {
             if (!isRecoverableSessionCacheError(error)) {
@@ -409,7 +429,46 @@ export async function runDaemonFromEnv() {
             }
             await discardSession(runtime);
             const freshAdapter = await sessionFor(runtime);
-            return freshAdapter[command](args);
+            return runActionWithMap(freshAdapter, command, args, mapOptions);
+        }
+    }
+    async function runActionWithMap(adapter, command, args, mapOptions) {
+        const options = mapOptions;
+        const context = createAppMapContext(adapter, options);
+        if (!context) {
+            const summary = createMapSummary(adapter, options);
+            try {
+                const details = await adapter[command](args);
+                return {
+                    ...details,
+                    map: summary
+                };
+            }
+            catch (error) {
+                throw new DaemonResponseError(errorMessage(error), {
+                    map: summary
+                });
+            }
+        }
+        try {
+            const details = await runMappedCommand(context, command, args);
+            const stepMap = details.map && typeof details.map === 'object' ? details.map : {};
+            const summary = persistAppMapContext(context);
+            return {
+                ...details,
+                map: {
+                    ...summary,
+                    ...stepMap
+                }
+            };
+        }
+        catch (error) {
+            throw new DaemonResponseError(errorMessage(error), {
+                map: persistAppMapContext(context)
+            });
+        }
+        finally {
+            persistAppMapContext(context);
         }
     }
     function enqueue(work) {
@@ -463,11 +522,24 @@ export async function runDaemonFromEnv() {
                         });
                         return;
                     }
+                    else if (request.type === 'discover') {
+                        const data = await enqueue(async () => {
+                            activeOperation = `discover:${runtimeKey(request.runtime)}`;
+                            try {
+                                const adapter = await sessionFor(request.runtime);
+                                return await discoverAppMap(adapter, request.mapOptions);
+                            }
+                            finally {
+                                activeOperation = null;
+                            }
+                        });
+                        response = { ok: true, data };
+                    }
                     else if (request.type === 'action') {
                         const data = await enqueue(async () => {
                             activeOperation = `${request.command}:${runtimeKey(request.runtime)}`;
                             try {
-                                return await runActionWithSessionRetry(request.runtime, request.command, request.args);
+                                return await runActionWithSessionRetry(request.runtime, request.command, request.args, request.mapOptions);
                             }
                             finally {
                                 activeOperation = null;
@@ -480,7 +552,7 @@ export async function runDaemonFromEnv() {
                             activeOperation = `scenario:${runtimeKey(request.runtime)}`;
                             try {
                                 const adapter = await sessionFor(request.runtime);
-                                return await runScenario(request.scenario, adapter, request.device, request.timeout, request.outputDir, false);
+                                return await runScenario(request.scenario, adapter, request.device, request.timeout, request.outputDir, false, request.mapOptions);
                             }
                             finally {
                                 activeOperation = null;
@@ -490,7 +562,11 @@ export async function runDaemonFromEnv() {
                     }
                 }
                 catch (error) {
-                    response = { ok: false, error: errorMessage(error) };
+                    response = {
+                        ok: false,
+                        error: errorMessage(error),
+                        data: error instanceof DaemonResponseError ? error.data : undefined
+                    };
                 }
                 socket.end(`${JSON.stringify(response)}\n`);
             })();

package/dist/localRuntime.js

@@ -0,0 +1,116 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const TINY_PNG = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMB/axDRf0AAAAASUVORK5CYII=', 'base64');
+function resolveArtifactPath(args, extension, fallbackLabel) {
+    const label = String(args.label ?? fallbackLabel);
+    return path.resolve(typeof args.path === 'string' ? args.path : `${label}.${extension}`);
+}
+function targetValue(target) {
+    const separatorIndex = target.indexOf('=');
+    return separatorIndex === -1 ? target : target.slice(separatorIndex + 1);
+}
+export class LocalRuntimeAdapter {
+    counter = 0;
+    route = 'app://home';
+    capability() {
+        return {
+            platform: 'android',
+            commands: ['navigate', 'tap', 'act', 'scroll', 'screenshot', 'wait', 'source']
+        };
+    }
+    async navigate(args) {
+        this.route = String(args.to ?? this.route);
+        return {
+            action: 'navigate',
+            platform: 'android',
+            args: { to: this.route }
+        };
+    }
+    async tap(args) {
+        const target = String(args.target ?? '');
+        if (targetValue(target) === 'Increment') {
+            this.counter += 1;
+        }
+        return {
+            action: 'tap',
+            platform: 'android',
+            args: { target }
+        };
+    }
+    async act(args) {
+        return {
+            action: 'act',
+            platform: 'android',
+            args
+        };
+    }
+    async scroll(args) {
+        return {
+            action: 'scroll',
+            platform: 'android',
+            args: {
+                direction: args.direction ?? 'down',
+                percent: args.percent ?? 70
+            }
+        };
+    }
+    async screenshot(args) {
+        const label = String(args.label ?? 'capture');
+        const filePath = resolveArtifactPath(args, 'png', label);
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, TINY_PNG);
+        return {
+            action: 'screenshot',
+            platform: 'android',
+            args: {
+                label,
+                file: path.basename(filePath),
+                path: filePath,
+                width: 1,
+                height: 1
+            }
+        };
+    }
+    async wait(args) {
+        return {
+            action: 'wait',
+            platform: 'android',
+            args: { ms: Number(args.ms ?? 0) }
+        };
+    }
+    async source(args) {
+        const label = String(args.label ?? 'source');
+        const filePath = resolveArtifactPath(args, 'xml', label);
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        const content = this.sourceXml();
+        fs.writeFileSync(filePath, content, 'utf8');
+        return {
+            action: 'source',
+            platform: 'android',
+            args: {
+                label,
+                file: path.basename(filePath),
+                path: filePath,
+                format: 'xml',
+                bytes: Buffer.byteLength(content, 'utf8')
+            }
+        };
+    }
+    async exists(target) {
+        const value = targetValue(target);
+        return value === 'Increment' || value === String(this.counter) || this.sourceXml().includes(value);
+    }
+    async close() {
+        return undefined;
+    }
+    sourceXml() {
+        return [
+            '<hierarchy>',
+            `  <node text="Route: ${this.route}" />`,
+            `  <node text="${this.counter}" label="${this.counter}" name="${this.counter}" value="${this.counter}" />`,
+            '  <node text="Increment" content-desc="Increment" label="Increment" name="Increment" />',
+            '</hierarchy>',
+            ''
+        ].join('\n');
+    }
+}

package/dist/runner.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { performance } from 'node:perf_hooks';
+import { createAppMapContext, createMapSummary, persistAppMapContext, runMappedCommand } from './appMap.js';
 import { makeError } from './errors.js';
 import { makeId, signatureFor, utcNowIso } from './utils.js';
 async function runStep(adapter, command, args) {
@@ -59,15 +60,32 @@ function signatureSafeDetails(details) {
     if (args && typeof args === 'object' && !Array.isArray(args)) {
         delete args.path;
     }
+    const map = safe.map;
+    if (map && typeof map === 'object' && !Array.isArray(map)) {
+        const mapDetails = map;
+        const route = Array.isArray(mapDetails.route)
+            ? mapDetails.route
+                .filter((step) => Boolean(step) && typeof step === 'object' && !Array.isArray(step))
+                .map((step) => ({
+                command: step.command,
+                target: step.target
+            }))
+            : [];
+        safe.map = {
+            route
+        };
+    }
     return safe;
 }
-export async function runScenario(scenario, adapter, device = 'local', timeoutMs, artifactBaseDir, closeAdapter = true) {
+export async function runScenario(scenario, adapter, device = 'local', timeoutMs, artifactBaseDir, closeAdapter = true, mapOptions) {
     const started_at = utcNowIso();
     const run_id = makeId('run');
     const platform = adapter.capability().platform;
     const stepResults = [];
     const artifacts = [];
     let topError;
+    const mapContext = createAppMapContext(adapter, mapOptions);
+    const disabledMapSummary = mapContext ? undefined : createMapSummary(adapter, mapOptions);
     let screenshotDir;
     let sourceDir;
     if (artifactBaseDir) {
@@ -89,7 +107,9 @@ export async function runScenario(scenario, adapter, device = 'local', timeoutMs
                     const label = String(stepArgs.label ?? step.id);
                     stepArgs.path = path.join(sourceDir, `${label}.xml`);
                 }
-                const details = await runStep(adapter, step.command, stepArgs);
+                const details = mapContext
+                    ? await runMappedCommand(mapContext, step.command, stepArgs)
+                    : await runStep(adapter, step.command, stepArgs);
                 const durationMs = Math.round(performance.now() - started);
                 const result = {
                     id: step.id,
@@ -140,6 +160,7 @@ export async function runScenario(scenario, adapter, device = 'local', timeoutMs
         }
         const allPass = stepsOk && assertionEvaluation.ok;
         const ended_at = utcNowIso();
+        const mapSummary = persistAppMapContext(mapContext) ?? disabledMapSummary;
         const signatureInput = {
             platform,
             steps: stepResults.map((step) => ({
@@ -162,10 +183,12 @@ export async function runScenario(scenario, adapter, device = 'local', timeoutMs
             artifacts,
             determinism_signature: signatureFor(signatureInput),
             seed: typeof scenario.config.seed === 'number' ? scenario.config.seed : undefined,
+            map: mapSummary,
             error: topError
         };
     }
     finally {
+        persistAppMapContext(mapContext);
         if (closeAdapter) {
             await adapter.close();
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "visor-ai",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "Visor CLI for LLM-driven mobile app interaction and artifact capture",
   "type": "module",
   "license": "MIT",
@@ -30,7 +30,9 @@
     "build": "rm -rf dist && tsc -p tsconfig.json",
     "dev": "tsx src/main.ts",
     "test": "vitest run",
+    "test:e2e:local": "node scripts/local-e2e.mjs",
     "check": "npm run build && npm run test",
+    "verify": "npm run build && npm run test && npm run test:e2e:local",
     "release": "node scripts/release.mjs",
     "release:patch": "node scripts/release.mjs patch",
     "release:minor": "node scripts/release.mjs minor",
@@ -51,6 +53,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.13.10",
+    "appium-uiautomator2-driver": "^4.2.9",
     "appium-xcuitest-driver": "^9.10.5",
     "tsx": "^4.19.3",
     "typescript": "^5.8.2",