@astur-mobile/cli 0.1.0-beta.4 → 0.4.0-beta.0

package/dist/inspectorServer.js

@@ -35,6 +35,73 @@ export function startInspectorServer(inspector, device, options) {
         let gestureCommandInFlight = false;
         let lastGestureCommandAt = 0;
         const bundleUploads = new Map();
+        // ── WebView DOM probe ──────────────────────────────────────────────────────
+        // Pulling a WebView's DOM means opening a remote-debugging transport, which is
+        // far heavier than a native tree read — so probe it on its own adaptive cadence
+        // (fast while a WebView is present, slow while absent) and cache the raw DOM.
+        // Each native tree push re-splices the cached DOM against the *current* native
+        // nodes (cheap, in-memory) so coordinates track the live host node.
+        let cachedWebTree;
+        let webProbeNextAt = 0;
+        let webProbeInFlight = false;
+        const WEB_PROBE_PRESENT_MS = 1_500;
+        const WEB_PROBE_ABSENT_MS = 6_000;
+        // ── Device-action scheduler ────────────────────────────────────────────
+        // Serialize device actions ahead of the background screenshot/tree/WebView
+        // polls. While a fill/tap/swipe/etc. runs, polling is paused so it cannot
+        // pile commands onto the single-threaded agent, re-focus the field mid-type
+        // (the "autofill tag keeps reappearing" retry feel), or dispose the WebView
+        // context between two fills. After the last action settles, refresh once.
+        let pendingDeviceActions = 0;
+        let actionSettleTimer;
+        const ACTION_SETTLE_MS = 350;
+        const devicePollingPaused = () => pendingDeviceActions > 0 || actionSettleTimer !== undefined;
+        async function runDeviceAction(fn) {
+            pendingDeviceActions += 1;
+            if (actionSettleTimer) {
+                clearTimeout(actionSettleTimer);
+                actionSettleTimer = undefined;
+            }
+            try {
+                return await fn();
+            }
+            finally {
+                pendingDeviceActions -= 1;
+                if (pendingDeviceActions === 0) {
+                    // Let the keyboard/scroll animation finish, then do a single refresh
+                    // (one tree+frame read) instead of many mid-action reads.
+                    actionSettleTimer = setTimeout(() => {
+                        actionSettleTimer = undefined;
+                        void syncInspectorState();
+                    }, ACTION_SETTLE_MS);
+                }
+            }
+        }
+        function maybeProbeWebTree() {
+            if (!activeInspector.webSnapshot || webProbeInFlight || Date.now() < webProbeNextAt) {
+                return;
+            }
+            webProbeInFlight = true;
+            void (async () => {
+                try {
+                    const web = await activeInspector.webSnapshot?.();
+                    const had = Boolean(cachedWebTree);
+                    cachedWebTree = web ?? undefined;
+                    webProbeNextAt = Date.now() + (cachedWebTree ? WEB_PROBE_PRESENT_MS : WEB_PROBE_ABSENT_MS);
+                    // Surface a newly found (or newly lost) WebView DOM promptly.
+                    if (Boolean(cachedWebTree) !== had) {
+                        void pushTree({ reportFirstError: false }).catch(() => undefined);
+                    }
+                }
+                catch {
+                    cachedWebTree = undefined;
+                    webProbeNextAt = Date.now() + WEB_PROBE_ABSENT_MS;
+                }
+                finally {
+                    webProbeInFlight = false;
+                }
+            })();
+        }
         // ── HTTP server ────────────────────────────────────────────────────────
         const server = createServer((req, res) => {
             const url = req.url ?? '/';
@@ -348,16 +415,18 @@ export function startInspectorServer(inspector, device, options) {
                     }
                     if (shouldRecordTap && suggestions[0]) {
                         try {
-                            if (options.performTap) {
-                                await options.performTap({ x: event.x, y: event.y });
-                            }
-                            else {
-                                await activeInspector.executeAction({
-                                    kind: 'tap',
-                                    selector: suggestions[0].selector,
-                                    options: { timeout: 2_000 }
-                                });
-                            }
+                            await runDeviceAction(async () => {
+                                if (options.performTap) {
+                                    await options.performTap({ x: event.x, y: event.y });
+                                }
+                                else {
+                                    await activeInspector.executeAction({
+                                        kind: 'tap',
+                                        selector: suggestions[0].selector,
+                                        options: { timeout: 2_000 }
+                                    });
+                                }
+                            });
                         }
                         catch (error) {
                             ws.send(JSON.stringify({
@@ -366,37 +435,63 @@ export function startInspectorServer(inspector, device, options) {
                             }));
                             return;
                         }
-                        const step = {
-                            index: steps.length,
-                            action: 'tap',
-                            locator: normalizeRecordingLocator(suggestions[0].code),
-                        };
+                        const recordedLocator = normalizeRecordingLocator(suggestions[0].code);
+                        const step = recordedLocator
+                            ? { index: steps.length, action: 'tap', locator: recordedLocator }
+                            : { index: steps.length, action: 'tapPoint', locator: '', point: { x: event.x, y: event.y } };
                         steps.push(step);
                         broadcast({ type: 'step', ...step });
-                        await syncInspectorState();
                         broadcast({ type: 'status', message: 'Action OK: Tap recorded' });
                     }
                     break;
                 }
                 case 'direct_action': {
+                    // The fill/tap buttons act on the currently selected node. When that is a
+                    // spliced WebView DOM node, drive it by its DOM locator (in-page JS)
+                    // instead of the native driver.
+                    const selectedNode = selectedUid
+                        ? currentNodes.find((node) => node.uid === selectedUid)
+                        : undefined;
+                    const selectedWebNode = selectedNode
+                        ? webActionTargetForSelectedNode(selectedNode, currentNodes, event.action)
+                        : undefined;
                     try {
-                        if (event.action === 'fill') {
-                            await activeInspector.executeAction({
-                                kind: 'fill',
-                                selector: event.selector,
-                                value: event.value ?? '',
-                                options: { timeout: 2_000 }
-                            });
-                        }
-                        else {
-                            await activeInspector.executeAction({
-                                kind: 'tap',
-                                selector: event.selector,
-                                options: { timeout: 2_000 }
-                            });
+                        const runNative = () => activeInspector.executeAction(event.action === 'fill'
+                            ? { kind: 'fill', selector: event.selector, value: event.value ?? '', options: { timeout: 2_000 } }
+                            : { kind: 'tap', selector: event.selector, options: { timeout: 2_000 } });
+                        let usedWeb = false;
+                        await runDeviceAction(async () => {
+                            if (selectedWebNode?.web && activeInspector.webAct) {
+                                try {
+                                    await activeInspector.webAct(selectedWebNode.web, event.action === 'fill' ? 'fill' : 'tap', event.value);
+                                    usedWeb = true;
+                                }
+                                catch {
+                                    // The WebView DOM context may have momentarily dropped — fall back to
+                                    // the native driver rather than failing the action outright.
+                                    await runNative();
+                                }
+                            }
+                            else {
+                                await runNative();
+                            }
+                        });
+                        // Record the Fill/Tap button action while recording so codegen captures it.
+                        // Web actions record as a webContext call; native actions as a device locator.
+                        if (recording) {
+                            const value = event.action === 'fill' ? (event.value ?? '') : undefined;
+                            const step = usedWeb && selectedWebNode?.web
+                                ? { index: steps.length, action: event.action, locator: webContextLocatorCall(selectedWebNode.web), web: true, value }
+                                : {
+                                    index: steps.length,
+                                    action: event.action,
+                                    locator: normalizeRecordingLocator(selectedNode ? (suggestLocatorsForNode(selectedNode, currentNodes)[0]?.code ?? '') : ''),
+                                    value
+                                };
+                            steps.push(step);
+                            broadcast({ type: 'step', ...step });
                         }
-                        await syncInspectorState();
-                        broadcast({ type: 'status', message: `Action OK: ${event.action === 'fill' ? 'Filled' : 'Tapped'}` });
+                        broadcast({ type: 'status', message: `Action OK: ${event.action === 'fill' ? 'Filled' : 'Tapped'}${usedWeb ? ' (web)' : ''}` });
                     }
                     catch (error) {
                         ws.send(JSON.stringify({
@@ -491,6 +586,29 @@ export function startInspectorServer(inspector, device, options) {
                     setTimeout(() => process.exit(0), 300);
                     break;
                 }
+                case 'release_session': {
+                    if (!options.releaseSession) {
+                        ws.send(JSON.stringify({ type: 'status', message: 'Action Error: Release is unavailable in this session.' }));
+                        break;
+                    }
+                    broadcast({ type: 'status', message: 'Action Pending: Releasing session...' });
+                    try {
+                        await options.releaseSession();
+                    }
+                    catch (error) {
+                        broadcast({
+                            type: 'status',
+                            message: `Action Error: Release failed: ${formatActionError(error)}`
+                        });
+                        break;
+                    }
+                    broadcast({
+                        type: 'terminated',
+                        message: 'Session released. The device session was closed; the emulator/simulator was left running. You can close this tab.'
+                    });
+                    setTimeout(() => process.exit(0), 300);
+                    break;
+                }
                 case 'app_action': {
                     if (!options.performAppAction) {
                         ws.send(JSON.stringify({ type: 'status', message: 'Action Error: App actions are unavailable in this session.' }));
@@ -567,6 +685,49 @@ export function startInspectorServer(inspector, device, options) {
                     }
                     break;
                 }
+                case 'drag': {
+                    if (!options.performDrag) {
+                        ws.send(JSON.stringify({ type: 'status', message: 'Action Error: Drag is unavailable in this session.' }));
+                        break;
+                    }
+                    const now = Date.now();
+                    if (gestureCommandInFlight || now - lastGestureCommandAt < 350) {
+                        ws.send(JSON.stringify({ type: 'gesture_ack' }));
+                        break;
+                    }
+                    gestureCommandInFlight = true;
+                    lastGestureCommandAt = now;
+                    try {
+                        await runDeviceAction(() => options.performDrag(event.gesture));
+                        if (recording && event.record !== false) {
+                            // Record element-sourced when the drag start resolves to a stable
+                            // locator (getByTestId(...).dragTo({x,y})); else fall back to a raw
+                            // coordinate drag.
+                            const startNode = findUiNodeAtPoint(currentNodes, event.gesture.start, { preferActionable: true });
+                            const srcSuggestions = startNode ? suggestLocatorsForNode(startNode, currentNodes) : [];
+                            const srcLocator = srcSuggestions[0] ? normalizeRecordingLocator(srcSuggestions[0].code) : '';
+                            const step = {
+                                index: steps.length,
+                                action: 'drag',
+                                locator: srcLocator,
+                                gesture: event.gesture
+                            };
+                            steps.push(step);
+                            broadcast({ type: 'step', ...step });
+                        }
+                        broadcast({ type: 'status', message: recording ? 'Action OK: Drag recorded' : 'Action OK: Dragged' });
+                    }
+                    catch (error) {
+                        ws.send(JSON.stringify({
+                            type: 'status',
+                            message: `Action Error: Drag failed: ${formatActionError(error)}`
+                        }));
+                    }
+                    finally {
+                        gestureCommandInFlight = false;
+                    }
+                    break;
+                }
                 case 'record_toggle': {
                     recording = !recording;
                     broadcast({ type: 'status', message: recording ? 'Recording ON' : 'Recording OFF' });
@@ -689,6 +850,11 @@ export function startInspectorServer(inspector, device, options) {
         let frameTimer;
         let frameInFlight = false;
         async function pushFrame() {
+            // Keep the mirror live even during a device action. A screenshot is read-only:
+            // it can't disturb the fill, re-focus the field, or drop the WebView context.
+            // Pausing it (only the heavy tree/WebView reads are paused — see pushTree) made
+            // a fill look like nothing happened in the mirror while the simulator already
+            // showed the typed text and keyboard.
             if (clients.size === 0 || frameInFlight) {
                 return 'busy';
             }
@@ -740,7 +906,9 @@ export function startInspectorServer(inspector, device, options) {
         let lastTreeErrorAt = 0;
         let consecutiveTreeErrors = 0;
         async function pushTree(options = {}) {
-            if (treeInFlight) {
+            // Bootstrap/manual refreshes (reportFirstError) bypass the action gate;
+            // background polls pause while a device action is running or settling.
+            if (treeInFlight || (devicePollingPaused() && !options.reportFirstError)) {
                 return 'busy';
             }
             // Avoid expensive UI-tree reads (e.g. adb `uiautomator dump`, broad XCUI
@@ -753,6 +921,17 @@ export function startInspectorServer(inspector, device, options) {
             try {
                 for await (const update of activeInspector.subscribeTree({ maxUpdates: 1 })) {
                     const nodes = flattenSnapshot(update.root);
+                    // Splice any WebView DOM (cached from the adaptive probe) under its native
+                    // host so its elements appear in the tree with real DOM locators.
+                    maybeProbeWebTree();
+                    if (cachedWebTree) {
+                        try {
+                            nodes.push(...buildWebNodes(cachedWebTree, nodes));
+                        }
+                        catch {
+                            // Best-effort: never let WebView DOM block the native tree.
+                        }
+                    }
                     const viewport = estimateViewport(nodes);
                     currentNodes = nodes;
                     currentViewport = viewport;
@@ -813,7 +992,12 @@ export function startInspectorServer(inspector, device, options) {
             return { frame, tree: 'busy' };
         }
         function scheduleTree() {
-            const interval = clients.size === 0
+            // Back off hard when the tree read keeps failing/timing out — e.g. XCUITest
+            // stalling on a heavy WebView snapshot. Retrying every interval just piles
+            // commands onto an already-stuck agent; poll slowly until it recovers (a
+            // successful read resets consecutiveTreeErrors and snaps back to base).
+            const stalled = consecutiveTreeErrors >= 3;
+            const interval = clients.size === 0 || stalled
                 ? maxIdleIntervalMs
                 : nextPollInterval(baseTreeIntervalMs, treeIdleStreak, maxIdleIntervalMs);
             treeTimer = setTimeout(async () => {
@@ -929,6 +1113,110 @@ function flattenNode(node, depth, uid, parentUid) {
         bounds: node.bounds,
     };
 }
+function webLocatorCode(descriptor) {
+    switch (descriptor.strategy) {
+        case 'testid': return `device.getByTestId(${JSON.stringify(descriptor.value)})`;
+        case 'id': return `device.getById(${JSON.stringify(descriptor.value)})`;
+        case 'role': return `device.getByRole(${JSON.stringify(descriptor.value)}${descriptor.name ? `, { name: ${JSON.stringify(descriptor.name)} }` : ''})`;
+        case 'text': return `device.getByText(${JSON.stringify(descriptor.value)})`;
+        default: return `device.locator(${JSON.stringify(descriptor.value)})`;
+    }
+}
+// Call form for a WebView DOM locator under a `web` context handle (no `device.`
+// prefix), e.g. `getByTestId('astur-password')` — used in recorded codegen as
+// `web.<call>.fill(...)` after `const web = await device.webContext();`.
+function webContextLocatorCall(descriptor) {
+    switch (descriptor.strategy) {
+        case 'testid': return `getByTestId(${JSON.stringify(descriptor.value)})`;
+        case 'role': return `getByRole(${JSON.stringify(descriptor.value)}${descriptor.name ? `, { name: ${JSON.stringify(descriptor.name)} }` : ''})`;
+        case 'text': return `getByText(${JSON.stringify(descriptor.value)})`;
+        case 'id':
+        default: return `getById(${JSON.stringify(descriptor.value)})`;
+    }
+}
+function webLocatorSuggestion(descriptor) {
+    const code = webLocatorCode(descriptor);
+    // Web actions are routed by the DOM locator (node.web), not this selector, so it
+    // only needs to be a valid placeholder for display/typing.
+    const selector = descriptor.strategy === 'role' ? { strategy: 'role', value: descriptor.value, name: descriptor.name }
+        : descriptor.strategy === 'text' ? { strategy: 'text', value: descriptor.value }
+            : { strategy: 'id', value: descriptor.value };
+    return { code, selector, score: 0.96, uniqueness: 1, stability: 0.9, readable: code.length <= 88, crossPlatform: true };
+}
+function webNodeTitle(node) {
+    const tag = node.tag.toLowerCase();
+    const handle = node.testId ? `[testid=${node.testId}]` : node.id ? `#${node.id}` : '';
+    const name = (node.name ?? '').replace(/\s+/g, ' ').trim().slice(0, 40);
+    return `<${tag}>${handle ? ` ${handle}` : ''}${name ? ` ${name}` : ''}`.trim();
+}
+/**
+ * Locate the native node that hosts the WebView surface: the one whose device-px
+ * bounds best match the web viewport scaled by the device pixel ratio. Used to
+ * map DOM (CSS px) coordinates onto the device screen for overlays/hit-testing.
+ */
+function findWebHostNode(web, nativeNodes) {
+    const dpr = web.devicePixelRatio || 1;
+    const targetW = web.viewport.width * dpr;
+    const targetH = web.viewport.height * dpr;
+    if (targetW < 8 || targetH < 8) {
+        return undefined;
+    }
+    let best;
+    let bestScore = Number.POSITIVE_INFINITY;
+    for (const node of nativeNodes) {
+        if (!node.visible || node.bounds.width < 8 || node.bounds.height < 8) {
+            continue;
+        }
+        const dw = Math.abs(node.bounds.width - targetW);
+        const dh = Math.abs(node.bounds.height - targetH);
+        if (dw <= targetW * 0.25 && dh <= targetH * 0.25 && dw + dh < bestScore) {
+            best = node;
+            bestScore = dw + dh;
+        }
+    }
+    return best;
+}
+/**
+ * Flatten a WebView DOM snapshot into UiNodes spliced under its native host. DOM
+ * actions run by locator (engine JS), so even when the host can't be matched the
+ * nodes stay browsable/fillable — only the screenshot overlay needs the bounds.
+ */
+function buildWebNodes(web, nativeNodes) {
+    if (!web.root) {
+        return [];
+    }
+    const host = findWebHostNode(web, nativeNodes);
+    const dpr = web.devicePixelRatio || 1;
+    const mapBounds = (b) => host
+        ? {
+            x: Math.round(host.bounds.x + b.x * dpr),
+            y: Math.round(host.bounds.y + b.y * dpr),
+            width: Math.round(b.width * dpr),
+            height: Math.round(b.height * dpr)
+        }
+        : { x: 0, y: 0, width: 0, height: 0 };
+    const out = [];
+    const visit = (node, depth, uid, parentUid) => {
+        out.push({
+            uid,
+            parentUid,
+            depth,
+            title: webNodeTitle(node),
+            type: `web:${node.tag.toLowerCase()}`,
+            id: node.id,
+            label: node.name,
+            text: node.role ? undefined : node.name,
+            value: node.value,
+            visible: node.visible,
+            enabled: node.enabled,
+            bounds: mapBounds(node.bounds),
+            web: node.locator
+        });
+        node.children.forEach((child, index) => visit(child, depth + 1, `${uid}/${index}`, uid));
+    };
+    visit(web.root, host ? host.depth + 1 : 1, 'web', host?.uid);
+    return out;
+}
 function estimateViewport(nodes) {
     const root = nodes[0];
     if (root?.bounds && root.bounds.width > 0 && root.bounds.height > 0) {
@@ -995,6 +1283,10 @@ const INSPECTOR_ROLES = [
     'textbox'
 ];
 function suggestLocatorsForNode(node, nodes) {
+    if (node.web) {
+        // DOM nodes carry the in-page best locator; the native ranking doesn't apply.
+        return [webLocatorSuggestion(node.web)];
+    }
     const target = resolveInspectableNode(node, nodes);
     const candidates = buildLocalLocatorCandidates(target);
     const suggestions = [];
@@ -1093,6 +1385,11 @@ function buildLocalLocatorCandidates(node) {
     return candidates;
 }
 function resolveInspectableNode(node, nodes, options = {}) {
+    // WebView DOM nodes are already their own best target — never re-resolve them to
+    // a native ancestor, or selection/action routing would lose the DOM locator.
+    if (node.web) {
+        return node;
+    }
     const targetIsUsable = hasUsableLocator(node) && !isDecorativeNode(node);
     const targetIsActionable = targetIsUsable && isActionableNode(node);
     if (!options.preferActionable && targetIsUsable) {
@@ -1134,6 +1431,13 @@ function scoreInspectableNode(node, options = {}) {
         return Number.NEGATIVE_INFINITY;
     }
     let score = 0;
+    // Prefer the WebView DOM node over an overlapping native accessibility node at the
+    // same point. Inside a WebView both exist; the DOM node fills/taps reliably (webAct),
+    // while the native overlay — especially secure text fields — often fails. This only
+    // affects spliced web nodes (WebView regions); native screens are unchanged, and the
+    // tree still lets you pick the native node explicitly.
+    if (node.web)
+        score += 100;
     if (normalizeLocatorToken(node.id))
         score += 80;
     if (normalizeLocatorToken(node.label))
@@ -1160,6 +1464,51 @@ function scoreInspectableNode(node, options = {}) {
     }
     return score + Math.min(node.depth, 14);
 }
+function webActionTargetForSelectedNode(selected, nodes, action) {
+    if (selected.web && webNodeSupportsAction(selected, action)) {
+        return selected;
+    }
+    const selectedArea = selected.bounds.width * selected.bounds.height;
+    if (selectedArea <= 0) {
+        return undefined;
+    }
+    const selectedCenter = centerOfBounds(selected.bounds);
+    let best;
+    let bestScore = Number.NEGATIVE_INFINITY;
+    for (const node of nodes) {
+        if (!node.web || !node.visible || !node.enabled || !webNodeSupportsAction(node, action)) {
+            continue;
+        }
+        const overlap = intersectionArea(selected.bounds, node.bounds);
+        const nodeArea = node.bounds.width * node.bounds.height;
+        if (nodeArea <= 0 || overlap <= 0) {
+            continue;
+        }
+        const overlapRatio = overlap / Math.min(selectedArea, nodeArea);
+        const centerHit = containsPoint(node.bounds, selectedCenter);
+        if (!centerHit && overlapRatio < 0.55) {
+            continue;
+        }
+        const score = overlapRatio * 100
+            + (centerHit ? 20 : 0)
+            + Math.min(node.depth, 20)
+            - Math.log10(nodeArea) * 2;
+        if (!best || score > bestScore) {
+            best = node;
+            bestScore = score;
+        }
+    }
+    return best;
+}
+function webNodeSupportsAction(node, action) {
+    if (!node.web) {
+        return false;
+    }
+    if (action === 'fill') {
+        return isFillableNode(node);
+    }
+    return isActionableNode(node);
+}
 function uiNodeMatchesSelector(node, selector) {
     switch (selector.strategy) {
         case 'accessibility':
@@ -1232,6 +1581,8 @@ function rolesForNode(node) {
         roles.add('tab');
     if (type.includes('edittext') || type.includes('textfield') || type.includes('securetextfield') || type.includes('searchfield') || type.includes('textinput'))
         roles.add('textbox');
+    if (type === 'web:input' || type === 'web:textarea' || type.includes('contenteditable'))
+        roles.add('textbox');
     if (type.includes('textview') || type.includes('statictext') || type.includes('label'))
         roles.add('text');
     return [...roles];
@@ -1355,6 +1706,19 @@ function containsPoint(bounds, point) {
         && point.x <= bounds.x + bounds.width
         && point.y <= bounds.y + bounds.height;
 }
+function centerOfBounds(bounds) {
+    return {
+        x: Math.round(bounds.x + bounds.width / 2),
+        y: Math.round(bounds.y + bounds.height / 2)
+    };
+}
+function intersectionArea(a, b) {
+    const left = Math.max(a.x, b.x);
+    const top = Math.max(a.y, b.y);
+    const right = Math.min(a.x + a.width, b.x + b.width);
+    const bottom = Math.min(a.y + a.height, b.y + b.height);
+    return Math.max(0, right - left) * Math.max(0, bottom - top);
+}
 async function readAsturLogoDataUri() {
     const candidates = [
         fileURLToPath(new URL('../assets/brand/astur-logo-dark.png', import.meta.url)),
@@ -1391,14 +1755,28 @@ function generateTestCode(steps, lang) {
     const importLine = lang === 'typescript'
         ? `import { test, expect } from '@astur-mobile/test';`
         : `const { test, expect } = require('@astur-mobile/test');`;
-    const lines = steps.map((s) => generateRecordedStepCode(s));
+    // Web steps run through a WebView DOM context — emit the handle once.
+    const setup = steps.some((s) => s.web) ? ['  const web = await device.webContext();'] : [];
+    const lines = setup.concat(steps.map((s) => generateRecordedStepCode(s)));
     return `${importLine}\n\ntest('recorded flow', async ({ device }) => {\n${lines.join('\n')}\n});\n`;
 }
 function generateRecordedStepCode(step) {
     const locator = normalizeRecordingLocator(step.locator);
+    if (step.web && locator) {
+        // WebView DOM action via the `web` context handle.
+        return step.action === 'fill'
+            ? `  await web.${locator}.fill(${JSON.stringify(step.value ?? '')});`
+            : `  await web.${locator}.tap();`;
+    }
     if (step.action === 'swipe' && step.gesture) {
         return `  await device.swipe(${JSON.stringify(step.gesture)});`;
     }
+    if (step.action === 'drag' && step.gesture) {
+        if (locator) {
+            return `  await device.${locator}.dragTo({ x: ${step.gesture.end.x}, y: ${step.gesture.end.y} });`;
+        }
+        return `  await device.drag(${JSON.stringify(step.gesture)});`;
+    }
     if (step.action === 'tapPoint' && step.point) {
         return `  await device.tap(${JSON.stringify(step.point)});`;
     }
@@ -1423,6 +1801,13 @@ function generateRecordedStepCode(step) {
                 return `  await expect(${actual}).toBeVisible();`;
         }
     }
+    if (!locator) {
+        // Never emit broken `device..tap()` — fall back to a coordinate tap when we
+        // have a point, otherwise leave a clear marker to re-record.
+        return step.point
+            ? `  await device.tap(${JSON.stringify(step.point)});`
+            : `  // TODO: tap target had no stable locator — re-record this step in Inspect mode`;
+    }
     return `  await device.${locator}.tap();`;
 }
 const BASE_INSPECTOR_DEVICE_ACTIONS = [
@@ -1655,6 +2040,7 @@ html,body{height:100%;overflow:hidden;background:var(--bg);color:var(--text);fon
 #phone-notch{display:none}
 #mirror-stage{position:relative;cursor:crosshair;overflow:hidden;border-radius:28px;background:#0a0a0f;box-shadow:0 24px 64px rgba(0,0,0,.48),0 0 0 1px rgba(255,255,255,.08);width:360px;height:720px;max-width:calc(100vw - 420px);max-height:calc(100vh - 96px)}
 #mirror-stage[data-mode="interact"]{cursor:pointer}
+#mirror-stage[data-mode="drag"]{cursor:grab}
 #mirror-stage.dragging{cursor:grabbing}
 #mirror-img{display:block;max-width:100%;user-select:none;pointer-events:none;border-radius:inherit}
 #mirror-img.placeholder{opacity:.15}
@@ -1770,10 +2156,11 @@ html,body{height:100%;overflow:hidden;background:var(--bg);color:var(--text);fon
         ${renderInspectorDeviceActionMenu(device)}
         <div class="device-menu-section">
           <div class="device-menu-label">Session</div>
-          <div class="device-row">
-            <button type="button" class="device-action-btn danger" id="terminate-session-btn">Terminate session</button>
+          <div class="device-menu-actions">
+            <button type="button" class="device-action-btn icon" id="release-session-btn" title="Release session" aria-label="Release session">${iconSvg('<path d="M5 17h14"/><path d="M12 4 5 13h14z"/>')}</button>
+            <button type="button" class="device-action-btn icon danger" id="terminate-session-btn" title="Terminate session" aria-label="Terminate session">${iconSvg('<path d="M12 2v10"/><path d="M18.4 6.6a9 9 0 1 1-12.8 0"/>')}</button>
           </div>
-          <div class="device-help">Closes the device session and powers off the emulator/simulator to free memory. Real devices stay on.</div>
+          <div class="device-help"><strong>Release</strong> closes the device session but leaves the emulator/simulator running for reuse. <strong>Terminate</strong> also powers it off to free memory. Real devices stay on.</div>
         </div>
       </div>
     </div>
@@ -1792,6 +2179,7 @@ html,body{height:100%;overflow:hidden;background:var(--bg);color:var(--text);fon
           <div class="action-mode-row" role="group" aria-label="Mirror click mode">
             <button type="button" id="inspect-mode-btn" class="mode-btn active" title="Select elements in the mirror">Inspect</button>
             <button type="button" id="interact-mode-btn" class="mode-btn" title="Tap the device without recording">Interact</button>
+            <button type="button" id="drag-mode-btn" class="mode-btn" title="Press and drag on the mirror to move an element (e.g. drag-and-drop)">Drag</button>
           </div>
           <div class="element-action-row">
             <button type="button" id="element-tap-btn" class="element-action-btn" disabled>Tap</button>
@@ -1842,7 +2230,11 @@ html,body{height:100%;overflow:hidden;background:var(--bg);color:var(--text);fon
     <div id="right-panel">
       <!-- Tree -->
       <div id="tree-panel">
-        <div class="panel-header">UI Tree <span id="tree-badge" style="font-weight:400;color:var(--text-muted)"></span></div>
+        <div class="panel-header" style="display:flex;align-items:center;gap:8px">
+          <span>UI Tree</span>
+          <span id="tree-badge" style="font-weight:400;color:var(--text-muted)"></span>
+          <button type="button" class="device-action-btn icon" id="tree-refresh-btn" title="Refresh UI tree" aria-label="Refresh UI tree" style="margin-left:auto;width:26px;height:24px">${inspectorDeviceActionIcon('tree.refresh')}</button>
+        </div>
         <div id="tree-search-row">
           <input id="tree-search" type="search" placeholder="Search element…"/>
         </div>
@@ -1919,6 +2311,20 @@ let activeTab = 'code';
 let currentDevice = ${JSON.stringify(toBootstrapDevice(device))};
 let devices = [currentDevice];
 let busyCount = 0;
+let busyWatchdog = null;
+// Hard ceiling on how long the "Running action…" overlay may stay up. If the
+// device/agent stops responding (e.g. XCUITest stalls while snapshotting a heavy
+// WebView), no status ever comes back and the overlay would otherwise spin
+// forever, bricking the session. The watchdog force-clears it so the user can
+// keep working (switch screens, terminate, etc.).
+//
+// Must sit ABOVE the native agent command timeout (iOS default 30s) — otherwise a
+// slow-but-succeeding action gets a premature, misleading "timed out" while the
+// agent is still completing it (e.g. filling a field inside a never-idle WKWebView,
+// where each keystroke's bounded idle-wait makes a clear+type land around ~16s). At
+// 35s the agent's own success/timeout response always arrives first, so the user
+// sees the real outcome; this stays purely a backstop for a truly hung session.
+const BUSY_WATCHDOG_MS = 35000;
 let socketConnected = false;
 let hasFrame = false;
 let hasTree = false;
@@ -1954,6 +2360,7 @@ const highlightOverlay = $('highlight-overlay');
 const inspectorHint = $('inspector-hint');
 const inspectModeBtn = $('inspect-mode-btn');
 const interactModeBtn = $('interact-mode-btn');
+const dragModeBtn = $('drag-mode-btn');
 const elementTapBtn = $('element-tap-btn');
 const elementFillInput = $('element-fill-input');
 const elementFillBtn = $('element-fill-btn');
@@ -1990,6 +2397,8 @@ const revokePermissionBtn = $('revoke-permission-btn');
 const clearDataBtn = $('clear-data-btn');
 const clearCacheBtn = $('clear-cache-btn');
 const terminateSessionBtn = $('terminate-session-btn');
+const releaseSessionBtn = $('release-session-btn');
+const treeRefreshBtn = $('tree-refresh-btn');
 const main = $('main');
 const leftColumnSplitter = $('left-column-splitter');
 const rightColumnSplitter = $('right-column-splitter');
@@ -2194,6 +2603,25 @@ function toggleDeviceSwitcher() {
 
 function setBusy(active) {
   busyCount = Math.max(0, busyCount + (active ? 1 : -1));
+  if (busyWatchdog) {
+    clearTimeout(busyWatchdog);
+    busyWatchdog = null;
+  }
+  if (busyCount > 0) {
+    busyWatchdog = setTimeout(onBusyWatchdogExpired, BUSY_WATCHDOG_MS);
+  }
+  updateDeviceReadiness();
+}
+
+// Fires when an action's overlay has been up too long with no response. Clears
+// the overlay and tells the user the session is still live so they can recover
+// (common when a native+web hybrid screen leaves XCUITest mid-snapshot).
+function onBusyWatchdogExpired() {
+  busyWatchdog = null;
+  if (busyCount === 0) return;
+  busyCount = 0;
+  releaseGestureLock();
+  showDeviceStatus('Action timed out — the device is slow to respond (a heavy web view can stall the UI tree). The session is still live; try again or switch screens.', 'error');
   updateDeviceReadiness();
 }
 
@@ -2755,6 +3183,10 @@ function nodeRoles(node) {
   if (type.includes('switch')) roles.push('switch');
   if (type.includes('tab')) roles.push('tab');
   if (type.includes('edittext') || type.includes('textfield') || type.includes('securetextfield') || type.includes('searchfield') || type.includes('textinput')) roles.push('textbox');
+  // Spliced WebView DOM nodes ('web:input', 'web:textarea'): text inputs are fillable
+  // (and contenteditable surfaces). Without this the Fill control stays disabled for
+  // web-context elements even though the server routes them through webAct.
+  if (type === 'web:input' || type === 'web:textarea' || type.includes('contenteditable')) roles.push('textbox');
   return roles;
 }
 
@@ -2782,13 +3214,16 @@ function updateStepControls() {
 
 function setMirrorMode(mode) {
   mirrorMode = mode;
-  const interacting = mode === 'interact';
-  inspectModeBtn.classList.toggle('active', !interacting);
-  interactModeBtn.classList.toggle('active', interacting);
+  inspectModeBtn.classList.toggle('active', mode === 'inspect');
+  interactModeBtn.classList.toggle('active', mode === 'interact');
+  dragModeBtn.classList.toggle('active', mode === 'drag');
   mirrorStage.dataset.mode = mode;
-  inspectorHint.textContent = interacting
-    ? 'Tap the screen to interact with the device without recording.'
-    : 'Tap on the screen or select an element in the tree to generate locators.';
+  inspectorHint.textContent =
+    mode === 'interact'
+      ? 'Tap the screen to interact with the device without recording.'
+      : mode === 'drag'
+        ? 'Press and drag on the mirror to move an element. Turn on Record to capture it as a drag step.'
+        : 'Tap on the screen or select an element in the tree to generate locators.';
 }
 
 // ── Details ────────────────────────────────────────────────────────────────
@@ -2814,18 +3249,25 @@ function renderDetails(node) {
 
 // ── Mirror click ───────────────────────────────────────────────────────────
 function resolveMirrorSourceSize() {
-  const viewportWidth = Number(viewport.width || 0);
-  const viewportHeight = Number(viewport.height || 0);
-  if (viewportWidth > 1 && viewportHeight > 1) {
-    return { width: viewportWidth, height: viewportHeight };
-  }
-
+  // Size the stage to the screenshot's own pixels first: those are exactly what
+  // gets drawn, and the image is sized with explicit width/height (no
+  // object-fit), so any aspect-ratio mismatch stretches it. On rotation the
+  // landscape frame arrives a tick before the tree's viewport updates — if we
+  // trusted the (still portrait) viewport here, the landscape image would be
+  // squeezed into a portrait stage. Fall back to the viewport, then a square,
+  // until the first frame has loaded.
   const naturalWidth = Number(mirrorImg.naturalWidth || 0);
   const naturalHeight = Number(mirrorImg.naturalHeight || 0);
   if (naturalWidth > 1 && naturalHeight > 1) {
     return { width: naturalWidth, height: naturalHeight };
   }
 
+  const viewportWidth = Number(viewport.width || 0);
+  const viewportHeight = Number(viewport.height || 0);
+  if (viewportWidth > 1 && viewportHeight > 1) {
+    return { width: viewportWidth, height: viewportHeight };
+  }
+
   return { width: 1, height: 1 };
 }
 
@@ -2861,8 +3303,11 @@ mirrorStage.addEventListener('click', e => {
 
   const point = mirrorEventPoint(e);
   const performTap = mirrorMode === 'interact' && !recording;
-  if (recording || performTap) setBusy(true);
-  send({ type: 'click', x: point.x, y: point.y, record: recording, perform: performTap });
+  // In Drag mode a click only selects/inspects — it must never record a tap, so a
+  // small-movement drag can't leak a locator-less tap into the recording.
+  const recordTap = recording && mirrorMode !== 'drag';
+  if (recordTap || performTap) setBusy(true);
+  send({ type: 'click', x: point.x, y: point.y, record: recordTap, perform: performTap });
 });
 
 mirrorStage.addEventListener('wheel', e => {
@@ -2894,11 +3339,13 @@ mirrorStage.addEventListener('pointerup', e => {
 
   suppressNextClick = true;
   const end = mirrorEventPoint(e);
-  sendGesture({
-    start: start.point,
-    end,
-    durationMs: 350
-  });
+  if (mirrorMode === 'drag') {
+    // Press-and-hold then drag — routes to device.drag (no swipe/scroll shortcut),
+    // so draggable tiles actually pick up instead of scrolling the screen.
+    sendDrag({ start: start.point, end, durationMs: 700 });
+  } else {
+    sendGesture({ start: start.point, end, durationMs: 350 });
+  }
 });
 
 mirrorStage.addEventListener('pointercancel', e => {
@@ -2919,7 +3366,7 @@ function mirrorEventPoint(e) {
   };
 }
 
-function sendGesture(gesture) {
+function sendMirrorGesture(type, gesture) {
   const now = Date.now();
   if (gestureInFlight || now < nextGestureAllowedAt) {
     return false;
@@ -2929,7 +3376,7 @@ function sendGesture(gesture) {
   nextGestureAllowedAt = now + 450;
   setBusy(true);
   send({
-    type: 'swipe',
+    type,
     record: recording,
     gesture
   });
@@ -2946,6 +3393,14 @@ function sendGesture(gesture) {
   return true;
 }
 
+function sendGesture(gesture) {
+  return sendMirrorGesture('swipe', gesture);
+}
+
+function sendDrag(gesture) {
+  return sendMirrorGesture('drag', gesture);
+}
+
 function wheelSwipeGesture(e) {
   const horizontal = Math.abs(e.deltaX) > Math.abs(e.deltaY);
   const width = viewport.width || 1;
@@ -3161,7 +3616,16 @@ function updateCodeBlock() {
   if (!steps.length) { codeBlock.textContent = '// No steps recorded yet'; return; }
   const lines = steps.map(s => {
     const locator = normalizeLocatorCode(s.locator);
+    if (s.web && locator) {
+      return s.action === 'fill'
+        ? '  await web.' + locator + '.fill(' + JSON.stringify(s.value || '') + ');'
+        : '  await web.' + locator + '.tap();';
+    }
     if (s.action === 'swipe' && s.gesture) return '  await device.swipe(' + JSON.stringify(s.gesture) + ');';
+    if (s.action === 'drag' && s.gesture) {
+      if (locator) return '  await device.' + locator + '.dragTo({ x: ' + s.gesture.end.x + ', y: ' + s.gesture.end.y + ' });';
+      return '  await device.drag(' + JSON.stringify(s.gesture) + ');';
+    }
     if (s.action === 'tapPoint' && s.point) return '  await device.tap(' + JSON.stringify(s.point) + ');';
     if (s.action === 'fill') return '  await device.' + locator + '.fill(' + JSON.stringify(s.value || '') + ');';
     if (s.action === 'expect') {
@@ -3181,12 +3645,18 @@ function updateCodeBlock() {
           return '  await expect(' + actual + ').toBeVisible();';
       }
     }
+    if (!locator) {
+      return s.point ? '  await device.tap(' + JSON.stringify(s.point) + ');' : '  // TODO: tap target had no stable locator';
+    }
     return '  await device.' + locator + '.tap();';
   });
   const imp = codeLang === 'typescript'
     ? "import { test, expect } from '@astur-mobile/test';"
     : "const { test, expect } = require('@astur-mobile/test');";
-  const body = imp + "\\n\\ntest('recorded flow', async ({ device }) => {\\n" + lines.join('\\n') + "\\n});\\n";
+  const allLines = steps.some(s => s.web)
+    ? ['  const web = await device.webContext();'].concat(lines)
+    : lines;
+  const body = imp + "\\n\\ntest('recorded flow', async ({ device }) => {\\n" + allLines.join('\\n') + "\\n});\\n";
   codeBlock.textContent = body;
 }
 
@@ -3336,6 +3806,7 @@ function runSelectedElementFill() {
   });
 }
 
+dragModeBtn.addEventListener('click', () => setMirrorMode('drag'));
 inspectModeBtn.addEventListener('click', () => setMirrorMode('inspect'));
 interactModeBtn.addEventListener('click', () => setMirrorMode('interact'));
 elementTapBtn.addEventListener('click', runSelectedElementTap);
@@ -3524,10 +3995,23 @@ terminateSessionBtn.addEventListener('click', () => {
   if (!confirm('Terminate this inspector session?\\n\\nThe device session will be closed and any emulator or simulator will be powered off. Real devices stay on.')) return;
   closeDeviceMenu();
   terminateSessionBtn.disabled = true;
-  terminateSessionBtn.textContent = 'Terminating…';
+  releaseSessionBtn.disabled = true;
   send({ type: 'terminate_session' });
 });
 
+releaseSessionBtn.addEventListener('click', () => {
+  if (!confirm('Release this inspector session?\\n\\nThe device session will be closed, but the emulator or simulator will stay running so it can be reused without a cold boot.')) return;
+  closeDeviceMenu();
+  releaseSessionBtn.disabled = true;
+  terminateSessionBtn.disabled = true;
+  send({ type: 'release_session' });
+});
+
+treeRefreshBtn.addEventListener('click', () => {
+  showDeviceStatus('Refreshing UI tree...', 'pending');
+  send({ type: 'device_action', action: 'tree.refresh' });
+});
+
 document.addEventListener('click', () => {
   closeDeviceMenu();
   closeDeviceSwitcher();