@astur-mobile/cli 0.1.0-beta.4 → 0.3.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({
@@ -373,30 +442,39 @@ export function startInspectorServer(inspector, device, options) {
                         };
                         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 selectedWebNode = selectedUid
+                        ? currentNodes.find((node) => node.uid === selectedUid && node.web)
+                        : 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 }
-                            });
-                        }
-                        await syncInspectorState();
-                        broadcast({ type: 'status', message: `Action OK: ${event.action === 'fill' ? 'Filled' : 'Tapped'}` });
+                        await runDeviceAction(async () => {
+                            if (selectedWebNode?.web && activeInspector.webAct) {
+                                await activeInspector.webAct(selectedWebNode.web, event.action === 'fill' ? 'fill' : 'tap', event.value);
+                            }
+                            else 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 }
+                                });
+                            }
+                        });
+                        broadcast({ type: 'status', message: `Action OK: ${event.action === 'fill' ? 'Filled' : 'Tapped'}${selectedWebNode ? ' (web)' : ''}` });
                     }
                     catch (error) {
                         ws.send(JSON.stringify({
@@ -491,6 +569,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.' }));
@@ -689,7 +790,7 @@ export function startInspectorServer(inspector, device, options) {
         let frameTimer;
         let frameInFlight = false;
         async function pushFrame() {
-            if (clients.size === 0 || frameInFlight) {
+            if (clients.size === 0 || frameInFlight || devicePollingPaused()) {
                 return 'busy';
             }
             frameInFlight = true;
@@ -740,7 +841,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 +856,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 +927,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 +1048,98 @@ 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)})`;
+    }
+}
+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 +1206,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 +1308,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) {
@@ -1770,10 +1990,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>
@@ -1842,7 +2063,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 +2144,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;
@@ -1990,6 +2229,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 +2435,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 +3015,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;
 }
 
@@ -2814,18 +3078,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 };
 }
 
@@ -3524,10 +3795,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();