@ishlabs/cli 0.26.1 → 0.27.0

package/dist/lib/api-client.d.ts

@@ -53,6 +53,7 @@ export declare class ApiClient {
         platform?: string;
         previous_frame_version_id?: string;
         same_screen_continuation?: boolean;
+        native_screen_signature?: string;
     }): Promise<{
         frame_version_id: string;
     }>;

package/dist/lib/local-sim/adb.d.ts

@@ -40,6 +40,22 @@ export declare function appBuildFromDevice(pkg: string): Promise<{
     version: string | null;
     build: string | null;
 } | null>;
+/**
+ * Pull `"pkg/activity"` out of `dumpsys activity activities`. The foreground
+ * activity surfaces as `topResumedActivity=ActivityRecord{... u0 pkg/activity
+ * t123}` (older builds: `mResumedActivity=...`); we take the `pkg/activity`
+ * token from whichever line is present. The activity may be a short `.Name`
+ * (relative to the package) — kept as-is, exactly what dumpsys reports. Returns
+ * "" when neither line is present.
+ */
+export declare function parseTopActivity(out: string): string;
+/**
+ * The foreground `"pkg/activity"` from `dumpsys activity activities`, a coarse
+ * input for the screen signature. Best-effort: returns "" on any failure (the
+ * signature degrades to its package-only coarse token, and the run never
+ * depends on this read).
+ */
+export declare function currentActivity(): Promise<string>;
 /**
  * Capture the current screen as raw PNG bytes via `adb exec-out screencap -p`.
  * `exec-out` (not `shell`) avoids the CRLF translation that corrupts binary

package/dist/lib/local-sim/adb.js

@@ -152,6 +152,38 @@ export async function appBuildFromDevice(pkg) {
         return null;
     }
 }
+/**
+ * Pull `"pkg/activity"` out of `dumpsys activity activities`. The foreground
+ * activity surfaces as `topResumedActivity=ActivityRecord{... u0 pkg/activity
+ * t123}` (older builds: `mResumedActivity=...`); we take the `pkg/activity`
+ * token from whichever line is present. The activity may be a short `.Name`
+ * (relative to the package) — kept as-is, exactly what dumpsys reports. Returns
+ * "" when neither line is present.
+ */
+export function parseTopActivity(out) {
+    const m = /topResumedActivity=ActivityRecord\{[^}]*\s(\S+\/\S+)/.exec(out) ??
+        /mResumedActivity:\s*ActivityRecord\{[^}]*\s(\S+\/\S+)/.exec(out) ??
+        /mResumedActivity=ActivityRecord\{[^}]*\s(\S+\/\S+)/.exec(out);
+    if (!m)
+        return "";
+    // The token can carry a trailing task id glued by the regex boundary? No —
+    // `\S+/\S+` stops at the first whitespace, so it is exactly `pkg/activity`.
+    return m[1];
+}
+/**
+ * The foreground `"pkg/activity"` from `dumpsys activity activities`, a coarse
+ * input for the screen signature. Best-effort: returns "" on any failure (the
+ * signature degrades to its package-only coarse token, and the run never
+ * depends on this read).
+ */
+export async function currentActivity() {
+    try {
+        return parseTopActivity(await adbShell(["dumpsys", "activity", "activities"], 15_000));
+    }
+    catch {
+        return "";
+    }
+}
 /**
  * Capture the current screen as raw PNG bytes via `adb exec-out screencap -p`.
  * `exec-out` (not `shell`) avoids the CRLF translation that corrupts binary
@@ -191,8 +223,21 @@ export async function requireOneDevice() {
     if (online.length === 0) {
         throw new AdbError("No Android device/emulator online. Run `ish check android` to check your setup and how to boot one.");
     }
+    // Honor ANDROID_SERIAL (the standard adb convention): when it names an online
+    // device, pin to it instead of failing on "more than one device". The adb
+    // wrapper inherits process.env, so every subsequent `adb` call already targets
+    // that serial — this lets multiple emulators run in parallel, each driven by a
+    // CLI invocation with its own ANDROID_SERIAL.
+    const pinned = process.env.ANDROID_SERIAL?.trim();
+    if (pinned) {
+        if (online.some((l) => l.startsWith(`${pinned}\t`)))
+            return;
+        throw new AdbError(`ANDROID_SERIAL=${pinned} is set but that device is not online. ` +
+            `Online: ${online.map((l) => l.split("\t")[0]).join(", ") || "none"}.`);
+    }
     if (online.length > 1) {
-        throw new AdbError(`Expected exactly one Android device, found ${online.length}. Stop the extras (the sim drives a single device).`);
+        throw new AdbError(`Expected exactly one Android device, found ${online.length}. ` +
+            `Stop the extras, or set ANDROID_SERIAL=<serial> to pin one (parallel runs).`);
     }
 }
 // --- Input gestures (all in screencap pixel space) ---

package/dist/lib/local-sim/android.d.ts

@@ -66,9 +66,11 @@ export declare class AndroidDevice implements SimulationDevice {
     private refreshDimensions;
     observe(): Promise<DeviceObservation>;
     /**
-     * Dump + serialize the uiautomator a11y tree. Any failure (dump retries
-     * exhausted, parse error) degrades to an empty tree so the backend falls back
-     * to the vision path — a missing tree must never abort the observation.
+     * Dump + serialize the uiautomator a11y tree. Returns the serialized tree, the
+     * node map, the FLAT parsed nodes (for the screen signature) and the
+     * foreground package read off the dump. Any failure (dump retries exhausted,
+     * parse error) degrades to an empty tree so the backend falls back to the
+     * vision path — a missing tree must never abort the observation.
      */
     private dumpTree;
     captureScreenshot(): Promise<string>;

package/dist/lib/local-sim/android.js

@@ -19,10 +19,11 @@
  *   - Vision path: px = round(x / 1000 * screencapWidth); same for y.
  */
 import { resolveTextValue } from "./actions.js";
-import { requireOneDevice, screencapPng, pngDimensions, dumpUiautomatorXml, inputTap, inputSwipe, inputDrag, inputLongPress, setUserRotation, forceStop, launchApp, installApk, isPackageInstalled, listPackages, isAdbKeyboardInstalled, enableAdbKeyboard, setIme, resetIme, currentIme, adbKeyboardType, adbKeyboardClear, pressKeyEvent, statusbarExpand, appBuildFromDevice, ADB_KEYBOARD_PKG, } from "./adb.js";
+import { requireOneDevice, screencapPng, pngDimensions, dumpUiautomatorXml, inputTap, inputSwipe, inputDrag, inputLongPress, setUserRotation, forceStop, launchApp, installApk, isPackageInstalled, listPackages, isAdbKeyboardInstalled, enableAdbKeyboard, setIme, resetIme, currentIme, adbKeyboardType, adbKeyboardClear, pressKeyEvent, statusbarExpand, appBuildFromDevice, currentActivity, ADB_KEYBOARD_PKG, } from "./adb.js";
 import { isLocalPath } from "../upload.js";
 import { deNormalizePoint, deNormalizeDrag } from "./coordinates.js";
-import { parseUiautomatorXml, serializeNativeTree, boundsCenter } from "./native-a11y.js";
+import { parseUiautomatorXml, serializeNativeTree, boundsCenter, androidPackage, } from "./native-a11y.js";
+import { computeScreenSignature } from "./screen-signature.js";
 import { packageNameFromApk } from "./apk-manifest.js";
 // Let animations/IME transitions settle before the next observation so the
 // screenshot the LLM reasons over reflects the action's result.
@@ -175,14 +176,24 @@ export class AndroidDevice {
         return png;
     }
     async observe() {
-        // Screencap and the a11y dump are independent reads — run them in parallel.
-        // The dump is wrapped so a failure degrades to the vision path (empty tree)
-        // rather than aborting the observation.
-        const [png, tree] = await Promise.all([
+        // Screencap, the a11y dump, and the foreground-activity read are independent
+        // — run them in parallel. The dump is wrapped so a failure degrades to the
+        // vision path (empty tree) rather than aborting the observation; the
+        // activity read is best-effort ("" on failure → package-only coarse token).
+        const [png, tree, activity] = await Promise.all([
             this.refreshDimensions(),
             this.dumpTree(),
+            currentActivity(),
         ]);
         this.lastNodeMap = tree.nodeMap;
+        // Scroll-invariant screen signature from this dump's parsed nodes + coarse
+        // inputs (foreground package/activity). Sent only when usable (see loop.ts).
+        const coarseInputs = {
+            platform: "android",
+            package: tree.package,
+            activity,
+        };
+        const screenSignature = computeScreenSignature(tree.nodes, coarseInputs);
         return {
             screenshot: png.toString("base64"),
             // Element path when the dump produced a tree; "" → backend vision branch.
@@ -193,12 +204,19 @@ export class AndroidDevice {
             // Native has no scrollable document; the screen IS the page.
             documentHeight: this.screenHeight,
             tabs: [],
+            screenSignature,
+            // Corpus-dump only (ISH_DUMP_CORPUS): the exact parsed nodes + coarse
+            // inputs the signature consumed, so any algorithm can be replayed offline.
+            nativeNodes: tree.nodes,
+            coarseInputs,
         };
     }
     /**
-     * Dump + serialize the uiautomator a11y tree. Any failure (dump retries
-     * exhausted, parse error) degrades to an empty tree so the backend falls back
-     * to the vision path — a missing tree must never abort the observation.
+     * Dump + serialize the uiautomator a11y tree. Returns the serialized tree, the
+     * node map, the FLAT parsed nodes (for the screen signature) and the
+     * foreground package read off the dump. Any failure (dump retries exhausted,
+     * parse error) degrades to an empty tree so the backend falls back to the
+     * vision path — a missing tree must never abort the observation.
      */
     async dumpTree() {
         try {
@@ -206,12 +224,12 @@ export class AndroidDevice {
             const nodes = parseUiautomatorXml(xml);
             const tree = serializeNativeTree(nodes);
             this.log(`a11y tree: ${tree.nodeMap.size} node(s)`);
-            return tree;
+            return { ...tree, nodes, package: androidPackage(xml) };
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
             this.log(`a11y dump failed, falling back to vision: ${msg}`);
-            return { simplified: "", nodeMap: new Map() };
+            return { simplified: "", nodeMap: new Map(), nodes: [], package: "" };
         }
     }
     async captureScreenshot() {

package/dist/lib/local-sim/device.d.ts

@@ -14,6 +14,8 @@
 import type { Browser } from "playwright-core";
 import type { LocalStepAction, LocalSimBrowserOptions, LocalTabInfo, ContextValue } from "./types.js";
 import type { BrowserSession } from "./browser.js";
+import type { ScreenSignature, CoarseInputs } from "./screen-signature.js";
+import type { NativeNode } from "./native-a11y.js";
 /**
  * One observation of the target's current state.
  *
@@ -39,6 +41,29 @@ export interface DeviceObservation {
     documentHeight: number;
     /** Open-tab snapshot (browser-only; empty for native). */
     tabs: LocalTabInfo[];
+    /**
+     * Native only: the scroll-invariant structural "screen signature" computed
+     * from this observation's a11y tree (see screen-signature.ts). The loop sends
+     * `value` as the match-frame anchor ONLY when `usable` is true; browser
+     * targets omit it. Undefined when the platform doesn't compute one.
+     */
+    screenSignature?: ScreenSignature;
+    /**
+     * Native only, corpus-dump only: the PARSED a11y nodes that
+     * `computeScreenSignature` consumed for this observation (the exact array, so
+     * any signature algorithm can be replayed offline against it). Populated by the
+     * android/ios `observe()`; the browser leaves it undefined. Only surfaced for
+     * the `ISH_DUMP_CORPUS` instrumentation in loop.ts — nothing in the live path
+     * reads it.
+     */
+    nativeNodes?: NativeNode[];
+    /**
+     * Native only, corpus-dump only: the `CoarseInputs` (platform / package /
+     * activity / bundleId) fed into `computeScreenSignature` for this observation.
+     * Populated by the android/ios `observe()`; the browser leaves it undefined.
+     * Same instrumentation-only purpose as `nativeNodes`.
+     */
+    coarseInputs?: CoarseInputs;
 }
 /**
  * Result of executing one action against the target.

package/dist/lib/local-sim/ios.d.ts

@@ -86,10 +86,11 @@ export declare class IOSDevice implements SimulationDevice {
     private refreshScreen;
     observe(): Promise<DeviceObservation>;
     /**
-     * Read + serialize WDA's /source a11y tree (bounds in POINTS). Any
-     * failure (retries exhausted on a trivial tree, parse error) degrades to an
-     * empty tree so the backend falls back to vision — a missing tree must never
-     * abort the observation.
+     * Read + serialize WDA's /source a11y tree (bounds in POINTS). Returns the
+     * serialized tree, the node map and the FLAT parsed nodes (for the screen
+     * signature). Any failure (retries exhausted on a trivial tree, parse error)
+     * degrades to an empty tree so the backend falls back to vision — a missing
+     * tree must never abort the observation.
      */
     private dumpTree;
     captureScreenshot(): Promise<string>;

package/dist/lib/local-sim/ios.js

@@ -33,10 +33,11 @@
 import { resolveTextValue } from "./actions.js";
 import { requireOneBootedSimulator, screenshotPng, terminateApp, launchApp, installApp, isAppInstalled, bundleIdFromApp, appBuildFromSimulator, } from "./simctl.js";
 // iOS UI interaction + a11y run through WebDriverAgent (XCUITest), not idb.
-import { ensureWda, closeWda, describeScreen, describeAll, uiTap, uiLongPress, uiSwipe, uiText, uiKey, HID_KEY_RETURN, } from "./xcuitest.js";
+import { ensureWda, closeWda, describeScreen, describeAll, activeBundleId, uiTap, uiLongPress, uiSwipe, uiText, uiKey, HID_KEY_RETURN, } from "./xcuitest.js";
 import { isLocalPath } from "../upload.js";
 import { deNormalizePoint, deNormalizeDrag, pointToPixel } from "./coordinates.js";
 import { parseXcuiHierarchy, serializeNativeTree, boundsCenter } from "./native-a11y.js";
+import { computeScreenSignature } from "./screen-signature.js";
 // Let animations/transitions settle before the next observation so the
 // screenshot the LLM reasons over reflects the action's result.
 const POST_GESTURE_SETTLE_MS = 500;
@@ -176,14 +177,26 @@ export class IOSDevice {
     }
     async observe() {
         // Refresh geometry each step (orientation can change), then capture the
-        // pixel screenshot and the a11y tree in parallel (independent reads). The
-        // dump is wrapped so a failure degrades to the vision path (empty tree).
+        // pixel screenshot, the a11y tree, and the active bundle id in parallel
+        // (independent reads). The dump is wrapped so a failure degrades to the
+        // vision path (empty tree); the bundle-id read is best-effort ("" on
+        // failure → the navTitle-only coarse token).
         await this.refreshScreen();
-        const [png, tree] = await Promise.all([
+        const [png, tree, bundleId] = await Promise.all([
             screenshotPng(),
             this.dumpTree(),
+            activeBundleId(this.udid),
         ]);
         this.lastNodeMap = tree.nodeMap;
+        // Scroll-invariant screen signature from this dump's parsed nodes + coarse
+        // inputs (active bundle id; navTitle is derived from the nodes). iOS is
+        // best-effort — sparse SwiftUI trees are usually unusable and fall back to
+        // Phase-1 continuity (sent only when usable; see loop.ts).
+        const coarseInputs = {
+            platform: "ios",
+            bundleId,
+        };
+        const screenSignature = computeScreenSignature(tree.nodes, coarseInputs);
         return {
             screenshot: png.toString("base64"),
             // Element path when describe-all produced a tree; "" → backend vision.
@@ -196,13 +209,19 @@ export class IOSDevice {
             // Native has no scrollable document; the screen IS the page.
             documentHeight: this.pixelHeight,
             tabs: [],
+            screenSignature,
+            // Corpus-dump only (ISH_DUMP_CORPUS): the exact parsed nodes + coarse
+            // inputs the signature consumed, so any algorithm can be replayed offline.
+            nativeNodes: tree.nodes,
+            coarseInputs,
         };
     }
     /**
-     * Read + serialize WDA's /source a11y tree (bounds in POINTS). Any
-     * failure (retries exhausted on a trivial tree, parse error) degrades to an
-     * empty tree so the backend falls back to vision — a missing tree must never
-     * abort the observation.
+     * Read + serialize WDA's /source a11y tree (bounds in POINTS). Returns the
+     * serialized tree, the node map and the FLAT parsed nodes (for the screen
+     * signature). Any failure (retries exhausted on a trivial tree, parse error)
+     * degrades to an empty tree so the backend falls back to vision — a missing
+     * tree must never abort the observation.
      */
     async dumpTree() {
         try {
@@ -210,12 +229,12 @@ export class IOSDevice {
             const nodes = parseXcuiHierarchy(json);
             const tree = serializeNativeTree(nodes);
             this.log(`a11y tree: ${tree.nodeMap.size} node(s)`);
-            return tree;
+            return { ...tree, nodes };
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
             this.log(`a11y describe-all failed, falling back to vision: ${msg}`);
-            return { simplified: "", nodeMap: new Map() };
+            return { simplified: "", nodeMap: new Map(), nodes: [] };
         }
     }
     async captureScreenshot() {

package/dist/lib/local-sim/loop.js

@@ -5,6 +5,7 @@
  * against a SimulationDevice (a Playwright browser today; a native Android
  * emulator next). The loop is device-agnostic — see device.ts.
  */
+import { appendFileSync } from "node:fs";
 import { launchSharedBrowser, FULL_PAGE_HEIGHT_CAP_PX_MOBILE, FULL_PAGE_HEIGHT_CAP_PX_DESKTOP, } from "./browser.js";
 import { uploadScreenshot } from "./upload.js";
 import { detectNoVisibleChange, describeAction, classifyStepKind } from "./actions.js";
@@ -19,6 +20,58 @@ import { enableDebug, isDebugEnabled, debugRawResponse, debugNormalizedActions,
 function isNativePlatform(platform) {
     return platform === "android" || platform === "ios";
 }
+/**
+ * Build ONE corpus-dump JSON line capturing everything needed to replay any
+ * screen-signature algorithm offline against this observation. Pure (input →
+ * string); the caller owns the I/O and the env gating. `app` is the coarse
+ * package (android) / bundle id (ios). Each node is projected down to the exact
+ * fields `computeScreenSignature` reads, so the line is a faithful replay basis.
+ */
+function buildCorpusDumpLine(input) {
+    const { coarse } = input;
+    return (JSON.stringify({
+        ts: input.ts,
+        app: (coarse.platform === "android" ? coarse.package : coarse.bundleId) ?? "",
+        platform: coarse.platform,
+        location: input.location,
+        coarse: {
+            platform: coarse.platform,
+            package: coarse.package ?? null,
+            activity: coarse.activity ?? null,
+            bundleId: coarse.bundleId ?? null,
+        },
+        nodes: input.nodes.map((n) => ({
+            role: n.role,
+            label: n.label,
+            resourceId: n.resourceId ?? null,
+            scrollable: n.scrollable,
+            insideScrollable: n.insideScrollable,
+        })),
+        signature: input.signature
+            ? {
+                value: input.signature.value,
+                usable: input.signature.usable,
+                tokenCount: input.signature.tokenCount,
+            }
+            : null,
+        frame_version_id: input.frameVersionId ?? null,
+        action_kind: input.actionKind,
+    }) + "\n");
+}
+/**
+ * Append one corpus-dump line to `path`. Best-effort: a dump failure (bad path,
+ * full disk) is swallowed so the instrumentation can NEVER abort a live sim.
+ * Gated entirely by the caller on ISH_DUMP_CORPUS + native source.
+ */
+function appendCorpusDumpLine(path, input, log) {
+    try {
+        appendFileSync(path, buildCorpusDumpLine(input));
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log(`    Warning: corpus dump append failed — ${msg}`);
+    }
+}
 /**
  * Convert a raw action (from either resolved_actions or output.action.actions)
  * into the flat LocalStepAction shape used by the executor. Exported for unit
@@ -349,6 +402,11 @@ async function runSingleSimulation(client, participantId, participantName, opts,
                 // TODO(perf): backend can downscale before the vision LLM; full-res sent for now.
                 const obs = await device.observe();
                 const currentScreenshot = obs.screenshot;
+                // Corpus dump (ISH_DUMP_CORPUS): the action_kind of the step that LED to
+                // THIS observation is the inbound lastStepKind (carried from the prior
+                // step; reassigned below AFTER the match-frame call). At step 0 nothing
+                // preceded this screen, so report it as "initial".
+                const inboundActionKind = step === 0 ? "initial" : lastStepKind;
                 // Capture JPEG of observation for upload and recording (pre-action)
                 const obsJpeg = await device.captureScreenshotJpeg();
                 const obsBase64 = obsJpeg.toString("base64");
@@ -580,6 +638,15 @@ async function runSingleSimulation(client, participantId, participantName, opts,
                         // updated AFTER this call for the next iteration.
                         ...(isNative && lastFrameVersionId ? { previous_frame_version_id: lastFrameVersionId } : {}),
                         same_screen_continuation: isNative && (lastStepKind === "scroll" || lastStepKind === "keyboard"),
+                        // Phase 2: scroll-invariant structural screen signature as an
+                        // entry/cross-run anchor. Sent ONLY when usable (>= 2 stable chrome
+                        // ids) — a sparse/empty id-set hashes to a colliding value that
+                        // would silently over-merge distinct screens, so we omit it and let
+                        // the backend fall back to Phase-1 continuity. Computed in the
+                        // device's observe() from this step's parsed a11y tree.
+                        ...(isNative && obs.screenSignature?.usable
+                            ? { native_screen_signature: obs.screenSignature.value }
+                            : {}),
                     });
                     frameVersionId = matchResult.frame_version_id;
                 }
@@ -587,6 +654,26 @@ async function runSingleSimulation(client, participantId, participantName, opts,
                     const msg = err instanceof Error ? err.message : String(err);
                     log(`    Warning: frame matching failed — ${msg}`);
                 }
+                // Corpus dump (ISH_DUMP_CORPUS, native only): one JSON line per
+                // observation with everything needed to replay any screen-signature
+                // algorithm offline — the LLM screen label (ground truth), the coarse
+                // inputs, the exact parsed NativeNode[], the current algorithm's
+                // signature, the backend frame id, and the inbound action_kind. Fully
+                // gated and best-effort: zero overhead/behavior change when unset, and a
+                // dump failure never aborts the sim. Requires the native observe()'s
+                // optional nativeNodes/coarseInputs (browser leaves them undefined).
+                const corpusDumpPath = process.env.ISH_DUMP_CORPUS;
+                if (corpusDumpPath && isNative && obs.nativeNodes && obs.coarseInputs) {
+                    appendCorpusDumpLine(corpusDumpPath, {
+                        ts: step,
+                        location: stepResponse.current_location,
+                        coarse: obs.coarseInputs,
+                        nodes: obs.nativeNodes,
+                        signature: obs.screenSignature,
+                        frameVersionId,
+                        actionKind: inboundActionKind,
+                    }, log);
+                }
                 // Carry THIS step's logical-screen classification + matched frame
                 // forward for the NEXT iteration's match-frame call (consumed above as
                 // last*). Classify after the call so ordering is consume-then-update.

package/dist/lib/local-sim/native-a11y.d.ts

@@ -45,6 +45,23 @@ export interface NativeNode {
     /** True for nodes whose own text/desc is a label (used to aggregate onto rows). */
     hasOwnLabel: boolean;
     resourceId?: string;
+    /**
+     * True for a scroll container (Android `scrollable="true"`; iOS
+     * ScrollView/Table/CollectionView). The screen-signature uses it to keep the
+     * container's OWN id as durable chrome — see screen-signature.ts.
+     */
+    scrollable: boolean;
+    /**
+     * True iff this node has a scrollable ANCESTOR — i.e. it is scroll CONTENT that
+     * shifts under a scroll. Computed STRUCTURALLY during parsing (tree ancestry),
+     * not geometrically: an overlay/FAB that merely sits inside a list's rect is
+     * NOT marked (it isn't a tree descendant), and on iOS the descendants of a
+     * pruned (isAccessible=0) scroll container still inherit the flag. The
+     * screen-signature excludes these from the stable token set so a scroll never
+     * changes the signature — see screen-signature.ts. A scroll container itself
+     * has `scrollable=true` but `insideScrollable=false` (unless nested).
+     */
+    insideScrollable: boolean;
     space: CoordinateSpace;
 }
 export interface NativeTree {
@@ -64,6 +81,13 @@ export interface NativeTree {
  * raw fields; the serializer decides which to emit and how to aggregate.
  */
 export declare function parseUiautomatorXml(xml: string): NativeNode[];
+/**
+ * The foreground app's package name from a uiautomator dump's `package="..."`
+ * attribute. uiautomator stamps every node with the owning package; the first
+ * one is the foreground app. Used as a coarse-token input for the screen
+ * signature (see screen-signature.ts). Returns "" when absent (best-effort).
+ */
+export declare function androidPackage(xml: string): string;
 /**
  * Parse WDA's `GET /source?format=json` — a NESTED accessibility tree — into the
  * FLAT, depth-first `NativeNode[]` (POINTS) that `parseXcuiHierarchy` produces,

package/dist/lib/local-sim/native-a11y.js

@@ -122,7 +122,11 @@ function unescapeXml(s) {
 export function parseUiautomatorXml(xml) {
     const root = buildAndroidTree(xml);
     const out = [];
-    const visit = (n) => {
+    // `parentScrollable` is true iff any ANCESTOR (not this node) had
+    // scrollable=true — i.e. this node is scroll CONTENT. Threaded down the
+    // descent so the screen-signature can exclude content structurally (a scroll
+    // moves these; chrome outside any scrollable keeps the signature stable).
+    const visit = (n, parentScrollable) => {
         // Drop nodes with no usable bounds (malformed/zero-area) — they have no
         // tappable center and would corrupt the nodeMap.
         if (n.bounds) {
@@ -134,14 +138,20 @@ export function parseUiautomatorXml(xml) {
                 clickable: n.clickable,
                 hasOwnLabel: label.length > 0,
                 resourceId: n.resourceId || undefined,
+                scrollable: n.scrollable,
+                insideScrollable: parentScrollable,
                 space: "px",
             });
         }
+        // A node inside a scrollable makes ALL its descendants scroll content; the
+        // container's own flag stays false (it's durable chrome) but its children
+        // inherit true.
+        const childScrollable = parentScrollable || n.scrollable;
         for (const c of n.children)
-            visit(c);
+            visit(c, childScrollable);
     };
     for (const c of root.children)
-        visit(c);
+        visit(c, false);
     return out;
 }
 /**
@@ -151,7 +161,7 @@ export function parseUiautomatorXml(xml) {
  * are its true descendants — required for ancestor-vs-leaf aggregation.
  */
 function buildAndroidTree(xml) {
-    const root = makeRawAndroidNode("", "", "", "", false, null);
+    const root = makeRawAndroidNode("", "", "", "", false, false, null);
     const stack = [root];
     // Match every <node ...> / <node .../> open tag and standalone </node> close.
     // Attribute values are consumed as atomic quoted runs (`"[^"]*"`) so a literal
@@ -171,19 +181,34 @@ function buildAndroidTree(xml) {
         // the greedy run above swallows the trailing slash, so a `(\/?)` capture
         // can't see it.
         const selfClosing = tag.endsWith("/>");
-        const node = makeRawAndroidNode(attr(tag, "class"), attr(tag, "text"), attr(tag, "content-desc"), attr(tag, "resource-id"), attr(tag, "clickable") === "true", parseAndroidBounds(attr(tag, "bounds")));
+        const node = makeRawAndroidNode(attr(tag, "class"), attr(tag, "text"), attr(tag, "content-desc"), attr(tag, "resource-id"), attr(tag, "clickable") === "true", attr(tag, "scrollable") === "true", parseAndroidBounds(attr(tag, "bounds")));
         stack[stack.length - 1].children.push(node);
         if (!selfClosing)
             stack.push(node);
     }
     return root;
 }
-function makeRawAndroidNode(role, text, contentDesc, resourceId, clickable, bounds) {
-    return { role, text, contentDesc, resourceId, clickable, bounds, children: [] };
+function makeRawAndroidNode(role, text, contentDesc, resourceId, clickable, scrollable, bounds) {
+    return { role, text, contentDesc, resourceId, clickable, scrollable, bounds, children: [] };
+}
+/**
+ * The foreground app's package name from a uiautomator dump's `package="..."`
+ * attribute. uiautomator stamps every node with the owning package; the first
+ * one is the foreground app. Used as a coarse-token input for the screen
+ * signature (see screen-signature.ts). Returns "" when absent (best-effort).
+ */
+export function androidPackage(xml) {
+    const m = /<node\b[^>]*?\spackage="([^"]*)"/.exec(xml);
+    return m ? unescapeXml(m[1]) : "";
 }
 // ---------------------------------------------------------------------------
 // iOS — shared helpers for the WebDriverAgent (XCUITest) /source parser below
 // ---------------------------------------------------------------------------
+/** iOS container types whose CONTENT scrolls. A node of one of these types (or
+ * any descendant of one) is marked `insideScrollable` so the screen signature
+ * excludes scroll content structurally while keeping the container's own id
+ * (see screen-signature.ts). */
+const IOS_SCROLLABLE_TYPES = new Set(["ScrollView", "Table", "CollectionView"]);
 /** iOS roles/types that are directly actionable (the device taps their center). */
 const IOS_ACTIONABLE_TYPES = new Set([
     "Button",
@@ -258,15 +283,47 @@ export function parseXcuiHierarchy(json) {
     if (!root || typeof root !== "object")
         return [];
     const out = [];
-    const visit = (n) => {
+    // `parentScrollable` is true iff this node OR any ANCESTOR is a scroll
+    // container. CRITICAL (the M1 fix): WDA's scroll CONTAINER is isAccessible=0
+    // and therefore NOT emitted, but its descendants are scroll content all the
+    // same — so the flag is threaded down the recursion regardless of whether the
+    // container node itself is emitted. The screen-signature excludes these
+    // structurally, so a scroll never changes the iOS signature.
+    const visit = (n, parentScrollable) => {
+        const rawType = n.type ?? "";
+        const typeKey = stripAxPrefix(rawType);
+        const isScroll = IOS_SCROLLABLE_TYPES.has(typeKey);
         const bounds = frameToBounds(n.rect ?? undefined);
+        // iOS NAVIGATION-BAR TITLE recovery. The bar carries the screen title in its
+        // `name`, but WDA marks the bar isAccessible=0 (so it's pruned) AND the large
+        // title StaticText scrolls WITH the content (insideScrollable). The title is
+        // then lost from the signature, silently OVER-MERGING distinct pushed screens
+        // (proven live: iOS Settings General/Accessibility/Privacy all reduced to the
+        // back button's parent label {tx:settings} → one frame). Emit the bar's name
+        // as a stable chrome node — it sits ABOVE the scroll (insideScrollable=false)
+        // and is scroll-invariant (constant as the large title collapses). Emitted
+        // first so `iosNavTitle` (find role==="navigationbar") sees the titled bar.
+        if (bounds && typeKey === "NavigationBar" && wdaTruthy(n.isVisible)) {
+            const navName = (n.name ?? "").trim();
+            if (navName) {
+                out.push({
+                    role: normalizeRole(rawType),
+                    label: navName,
+                    bounds,
+                    clickable: false,
+                    hasOwnLabel: true,
+                    resourceId: undefined,
+                    scrollable: false,
+                    insideScrollable: false,
+                    space: "points",
+                });
+            }
+        }
         if (bounds && wdaTruthy(n.isAccessible) && wdaTruthy(n.isVisible)) {
             // Prefer the spoken label; fall back to a STRING value (search fields
             // expose their placeholder as `value`). Non-string values (a Switch's 1/0)
             // are ignored for the label, exactly like the idb path.
             const label = (n.label ?? (typeof n.value === "string" ? n.value : "")).trim();
-            const rawType = n.type ?? "";
-            const typeKey = stripAxPrefix(rawType);
             // `isEnabled` absent ⇒ assume enabled (WDA omits it on always-enabled types).
             const enabled = n.isEnabled == null ? true : wdaTruthy(n.isEnabled);
             const actionable = IOS_ACTIONABLE_TYPES.has(typeKey) && enabled;
@@ -277,16 +334,21 @@ export function parseXcuiHierarchy(json) {
                 clickable: actionable,
                 hasOwnLabel: label.length > 0,
                 resourceId: (n.name || n.rawIdentifier) ?? undefined,
+                scrollable: isScroll,
+                insideScrollable: parentScrollable,
                 space: "points",
             });
         }
         // Recurse into ALL children — an accessible element can nest inside a
-        // non-accessible container (the Cell wrapping the Button), so we must not
-        // prune the walk by accessibility, only the emission.
+        // non-accessible container (the Cell wrapping the Button, or the pruned
+        // scroll container), so we must not prune the walk by accessibility, only
+        // the emission. The scroll flag propagates onto descendants even though the
+        // container itself wasn't emitted.
+        const childScrollable = parentScrollable || isScroll;
         for (const c of n.children ?? [])
-            visit(c);
+            visit(c, childScrollable);
     };
-    visit(root);
+    visit(root, false);
     return out;
 }
 // ---------------------------------------------------------------------------

package/dist/lib/local-sim/screen-signature.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Native "screen signature" v2 — a SCROLL-INVARIANT structural identity for a
+ * logical native screen, derived from the accessibility tree, sent to the
+ * backend as an entry/cross-run frame anchor (Phase 2 of native frame
+ * continuity; Phase 1 reuses the prior frame on pure scroll/keyboard steps).
+ *
+ * FCIS: this module is PURE (NativeNode[] + coarse inputs in, signature out) —
+ * no device access. The device gathers the coarse inputs (foreground activity /
+ * bundle id) and the parsed tree; this turns them into `{value, usable}`.
+ *
+ * The signature has two parts:
+ *   coarse  — a cheap, almost-always-available anchor (android `package|activity`,
+ *             ios `bundleId|navTitle`).
+ *   tokens  — the persistent CHROME tokens that are NOT scroll content. Each
+ *             chrome node contributes its resource-id (`id:…`) AND its label
+ *             (`tx:…`) when present. This is what makes the signature
+ *             scroll-invariant AND lets two same-activity screens be told apart.
+ *
+ * WHY v2 (two verified gaps in the id-only v1):
+ *  1. LABELS close the shared-chrome OVER-MERGE. A single-Activity app — Jetpack
+ *     Compose (exposes NO resource-ids beyond the framework `android:id/content`)
+ *     or a View app with a fixed toolbar+container shared across fragments —
+ *     gives two DISTINCT screens the SAME id-set → identical signature → SILENT
+ *     over-merge (the cardinal failure). But those screens DO differ in chrome
+ *     LABELS (a home screen vs a settings sub-screen show different toolbar /
+ *     button text). Including labels makes distinct screens produce distinct
+ *     signatures, and makes Compose usable at all (label-only tokens).
+ *  2. STRUCTURAL scroll-exclusion replaces v1's geometric `contains()`. v1
+ *     excluded scroll content by bounds-containment, which (a) mis-flagged an
+ *     overlay/FAB sitting inside a list's rect as content (→ could over-merge),
+ *     and (b) on iOS the scroll CONTAINER is isAccessible=0 and pruned from the
+ *     NativeNode[], so geometric exclusion never fired (scroll changed the
+ *     signature → over-split, feature inert). v2 excludes by TREE STRUCTURE: a
+ *     node is content iff `insideScrollable` (it has a scrollable ANCESTOR),
+ *     computed during parsing — see native-a11y.ts. The scroll container's OWN
+ *     tokens are kept (it's durable chrome; `insideScrollable` is about
+ *     descendants).
+ *
+ * The remaining failure mode after v2 is SAFE: dynamic chrome labels (a live
+ * clock, an unread badge) cause OVER-SPLIT (a new frame), never over-merge — the
+ * backend just mints a fresh frame, which is the conservative direction.
+ *
+ * USABLE GUARD (load-bearing, unchanged in spirit): `usable` is true only with
+ * >= MIN_STABLE_TOKENS tokens. A signature derived from an empty/sparse token
+ * set must NEVER be sent — sha1("") (and any near-empty set) collides across
+ * distinct screens and would silently over-merge them. When unusable the caller
+ * omits the field entirely and the backend falls back to Phase-1 continuity.
+ * This is the SAFE default: Flutter (no a11y tree) and the sparsest screens
+ * degrade here; id-rich Android and label-rich Compose are the validated wins.
+ */
+import type { NativeNode } from "./native-a11y.js";
+/** Minimum stable-chrome tokens for a signature to be usable (sent to the backend). */
+export declare const MIN_STABLE_TOKENS = 2;
+/** Coarse-token inputs gathered from the device (cheap, almost-always-available). */
+export interface CoarseInputs {
+    platform: "android" | "ios";
+    /** Android: foreground app package (uiautomator `package` attr). */
+    package?: string;
+    /** Android: foreground activity (`pkg/activity` from dumpsys). */
+    activity?: string;
+    /** iOS: active app bundle id (WDA /wda/activeAppInfo). navTitle is derived here. */
+    bundleId?: string;
+}
+export interface ScreenSignature {
+    /** `platform|coarse|sha1(tokens)` — the value sent as native_screen_signature. */
+    value: string;
+    /** True only with >= MIN_STABLE_TOKENS tokens; the caller omits the field when false. */
+    usable: boolean;
+    /** Number of stable chrome tokens — the guard's basis. */
+    tokenCount: number;
+}
+/**
+ * Compute the screen signature from this step's parsed tree + coarse inputs.
+ * `value` is `platform|coarse|sha1(tokens)`; `usable` gates whether it's safe to
+ * send (>= MIN_STABLE_TOKENS distinct stable chrome tokens).
+ */
+export declare function computeScreenSignature(nodes: NativeNode[], coarse: CoarseInputs): ScreenSignature;

package/dist/lib/local-sim/screen-signature.js

@@ -0,0 +1,166 @@
+/**
+ * Native "screen signature" v2 — a SCROLL-INVARIANT structural identity for a
+ * logical native screen, derived from the accessibility tree, sent to the
+ * backend as an entry/cross-run frame anchor (Phase 2 of native frame
+ * continuity; Phase 1 reuses the prior frame on pure scroll/keyboard steps).
+ *
+ * FCIS: this module is PURE (NativeNode[] + coarse inputs in, signature out) —
+ * no device access. The device gathers the coarse inputs (foreground activity /
+ * bundle id) and the parsed tree; this turns them into `{value, usable}`.
+ *
+ * The signature has two parts:
+ *   coarse  — a cheap, almost-always-available anchor (android `package|activity`,
+ *             ios `bundleId|navTitle`).
+ *   tokens  — the persistent CHROME tokens that are NOT scroll content. Each
+ *             chrome node contributes its resource-id (`id:…`) AND its label
+ *             (`tx:…`) when present. This is what makes the signature
+ *             scroll-invariant AND lets two same-activity screens be told apart.
+ *
+ * WHY v2 (two verified gaps in the id-only v1):
+ *  1. LABELS close the shared-chrome OVER-MERGE. A single-Activity app — Jetpack
+ *     Compose (exposes NO resource-ids beyond the framework `android:id/content`)
+ *     or a View app with a fixed toolbar+container shared across fragments —
+ *     gives two DISTINCT screens the SAME id-set → identical signature → SILENT
+ *     over-merge (the cardinal failure). But those screens DO differ in chrome
+ *     LABELS (a home screen vs a settings sub-screen show different toolbar /
+ *     button text). Including labels makes distinct screens produce distinct
+ *     signatures, and makes Compose usable at all (label-only tokens).
+ *  2. STRUCTURAL scroll-exclusion replaces v1's geometric `contains()`. v1
+ *     excluded scroll content by bounds-containment, which (a) mis-flagged an
+ *     overlay/FAB sitting inside a list's rect as content (→ could over-merge),
+ *     and (b) on iOS the scroll CONTAINER is isAccessible=0 and pruned from the
+ *     NativeNode[], so geometric exclusion never fired (scroll changed the
+ *     signature → over-split, feature inert). v2 excludes by TREE STRUCTURE: a
+ *     node is content iff `insideScrollable` (it has a scrollable ANCESTOR),
+ *     computed during parsing — see native-a11y.ts. The scroll container's OWN
+ *     tokens are kept (it's durable chrome; `insideScrollable` is about
+ *     descendants).
+ *
+ * The remaining failure mode after v2 is SAFE: dynamic chrome labels (a live
+ * clock, an unread badge) cause OVER-SPLIT (a new frame), never over-merge — the
+ * backend just mints a fresh frame, which is the conservative direction.
+ *
+ * USABLE GUARD (load-bearing, unchanged in spirit): `usable` is true only with
+ * >= MIN_STABLE_TOKENS tokens. A signature derived from an empty/sparse token
+ * set must NEVER be sent — sha1("") (and any near-empty set) collides across
+ * distinct screens and would silently over-merge them. When unusable the caller
+ * omits the field entirely and the backend falls back to Phase-1 continuity.
+ * This is the SAFE default: Flutter (no a11y tree) and the sparsest screens
+ * degrade here; id-rich Android and label-rich Compose are the validated wins.
+ */
+import { createHash } from "node:crypto";
+/** Minimum stable-chrome tokens for a signature to be usable (sent to the backend). */
+export const MIN_STABLE_TOKENS = 2;
+/**
+ * App-bar / title chrome resource-ids. A node whose resource-id matches carries
+ * the SCREEN TITLE (e.g. a CollapsingToolbar's title, an ActionBar/Toolbar title).
+ * On modern Android the title sits INSIDE the scrollable app-bar (CoordinatorLayout
+ * / NestedScrollView), so structural scroll-exclusion drops it — collapsing every
+ * sub-screen of a single host activity (e.g. Android Settings' `.SubSettings`) to
+ * the SAME generic outer-container ids and silently OVER-MERGING distinct screens
+ * (proven live: Display/Apps/Network all → one frame). We rescue the title LABEL
+ * even when `insideScrollable`: the title text is the screen's most reliable
+ * discriminator and is scroll-INVARIANT (it stays constant as the bar collapses).
+ *
+ * WHY no `_title$` here (removed): a trailing-`_title$` rescue was originally added
+ * to also catch Android `homepage_title`, but (a) `homepage_title` is the VOLATILE
+ * home big-title we deliberately do NOT want to rescue, and (b) `_title$`
+ * OVER-MATCHES iOS list-row section ids that are pure SCROLL CONTENT —
+ * `MOTION_TITLE`, `SPEECH_TITLE`, `LIVE_SPEECH_TITLE`, `VOCAL_SHORTCUTS_TITLE`
+ * (role=text, insideScrollable=true). Rescuing those re-includes scroll-content row
+ * labels in the signature, so scrolling reveals different rows and CHURNS the
+ * signature → over-fragment (iOS Settings/Accessibility split into two frames). The
+ * SubSettings over-merge discriminator rides on the explicitly-matched
+ * `collapsing_toolbar` / `action_bar` / `toolbar`, NOT on an arbitrary `_title$`.
+ */
+const TITLE_CHROME_ID = /(collapsing_toolbar|action_bar|toolbar)$/;
+function isTitleChrome(resourceId) {
+    return resourceId !== "" && TITLE_CHROME_ID.test(resourceId.toLowerCase());
+}
+/** Max length of a label token's value — bounds the hashed string on chatty labels. */
+const LABEL_TOKEN_MAX_LENGTH = 64;
+/**
+ * Normalized role of the iOS navigation bar after `normalizeRole` in
+ * native-a11y.ts (`AXNavigationBar`/`NavigationBar` → "navigationbar"). The
+ * spike matched the raw "NavigationBar" role; the CLI's NativeNode carries the
+ * normalized role, so we match the normalized form here.
+ */
+const IOS_NAV_BAR_ROLE = "navigationbar";
+function sha1(s) {
+    return createHash("sha1").update(s).digest("hex");
+}
+/** First nav-bar node's label (iOS), else "" — best-effort coarse signal. */
+function iosNavTitle(nodes) {
+    const nav = nodes.find((n) => n.role === IOS_NAV_BAR_ROLE);
+    return nav ? nav.label.trim() : "";
+}
+/** The coarse, almost-always-available anchor token. */
+function coarseToken(nodes, coarse) {
+    if (coarse.platform === "android") {
+        return `${coarse.package ?? ""}|${coarse.activity ?? ""}`;
+    }
+    return `${coarse.bundleId ?? ""}|${iosNavTitle(nodes)}`;
+}
+/** Collapse whitespace, lowercase, and cap length so a label token is stable. */
+function normalizeLabelToken(label) {
+    const collapsed = label.replace(/\s+/g, " ").trim().toLowerCase();
+    return collapsed.length <= LABEL_TOKEN_MAX_LENGTH
+        ? collapsed
+        : collapsed.slice(0, LABEL_TOKEN_MAX_LENGTH);
+}
+/**
+ * Sorted, de-duped token set of the persistent CHROME — every node that is NOT
+ * scroll content (`!insideScrollable`). Each such node contributes:
+ *   - `id:<resourceId>`  when its resource-id is non-empty, and
+ *   - `tx:<label>`       when its label is non-empty (normalized).
+ * A scroll CONTAINER's own tokens ARE kept (the container is durable chrome;
+ * `insideScrollable` flags its descendants, not the container). Labels are the
+ * v2 win: they discriminate single-Activity screens that share a chrome id-set
+ * (and give Compose, which exposes no ids, a usable signature at all).
+ */
+function stableTokenSet(nodes) {
+    const out = new Set();
+    for (const n of nodes) {
+        const id = (n.resourceId ?? "").trim();
+        const label = n.label.trim();
+        // App-bar / title chrome carries the screen's name but sits inside the
+        // scrollable app-bar on modern Android — rescue its scroll-invariant LABEL
+        // even when insideScrollable (its generic container id is NOT added; the
+        // label is the discriminator). See TITLE_CHROME_ID.
+        if (label && isTitleChrome(id))
+            out.add(`tx:${normalizeLabelToken(label)}`);
+        if (n.insideScrollable)
+            continue; // scroll content — shifts under a scroll
+        // Suppress the `id:` token for a self-named / generic nav control. On iOS,
+        // parseXcuiHierarchy promotes the WDA `name` to resourceId, but WDA reports a
+        // NON-DETERMINISTIC name for the nav back button — "BackButton" when fresh,
+        // the parent screen's title (e.g. "Settings") once scrolled — while its
+        // visible label stays constant. That churn flips the `id:` token between
+        // scroll states and fragments the same screen. Drop the id when it's the
+        // literal "BackButton" OR is redundant with the node's own label (id ===
+        // normalized label): in both cases the `id:` carries no identity beyond the
+        // already-emitted `tx:` label. We KEEP the `tx:` token below.
+        const redundantNavId = id !== "" &&
+            (id === "BackButton" ||
+                (label !== "" && normalizeLabelToken(id) === normalizeLabelToken(label)));
+        if (id && !redundantNavId)
+            out.add(`id:${id}`);
+        if (label)
+            out.add(`tx:${normalizeLabelToken(label)}`);
+    }
+    return [...out].sort();
+}
+/**
+ * Compute the screen signature from this step's parsed tree + coarse inputs.
+ * `value` is `platform|coarse|sha1(tokens)`; `usable` gates whether it's safe to
+ * send (>= MIN_STABLE_TOKENS distinct stable chrome tokens).
+ */
+export function computeScreenSignature(nodes, coarse) {
+    const tokens = stableTokenSet(nodes);
+    const value = `${coarse.platform}|${coarseToken(nodes, coarse)}|${sha1(tokens.join(","))}`;
+    return {
+        value,
+        usable: tokens.length >= MIN_STABLE_TOKENS,
+        tokenCount: tokens.length,
+    };
+}

package/dist/lib/local-sim/xcuitest.d.ts

@@ -45,6 +45,13 @@ export declare function closeWda(udid: string): Promise<void>;
 export declare function describeScreen(udid: string): Promise<IosScreen>;
 /** Raw WDA `/source?format=json` string — feed to `parseXcuiHierarchy`. */
 export declare function describeAll(udid: string): Promise<string>;
+/**
+ * The foreground app's bundle id via WDA `GET /wda/activeAppInfo`, a coarse
+ * input for the screen signature. Best-effort: returns "" on any failure (the
+ * signature degrades to a bundleId-less coarse token, and the run never depends
+ * on this read).
+ */
+export declare function activeBundleId(udid: string): Promise<string>;
 export declare function uiTap(udid: string, x: number, y: number): Promise<void>;
 export declare function uiLongPress(udid: string, x: number, y: number, durationMs?: number): Promise<void>;
 export declare function uiSwipe(udid: string, x1: number, y1: number, x2: number, y2: number, durationMs?: number): Promise<void>;

package/dist/lib/local-sim/xcuitest.js

@@ -250,6 +250,22 @@ export async function describeAll(udid) {
     const json = await wdaCall(s.port, "GET", `/session/${s.sessionId}/source?format=json`);
     return JSON.stringify(json);
 }
+/**
+ * The foreground app's bundle id via WDA `GET /wda/activeAppInfo`, a coarse
+ * input for the screen signature. Best-effort: returns "" on any failure (the
+ * signature degrades to a bundleId-less coarse token, and the run never depends
+ * on this read).
+ */
+export async function activeBundleId(udid) {
+    try {
+        const s = await getSession(udid);
+        const v = unwrap(await wdaCall(s.port, "GET", "/wda/activeAppInfo"));
+        return typeof v.bundleId === "string" ? v.bundleId : "";
+    }
+    catch {
+        return "";
+    }
+}
 // ── Gestures (W3C pointer actions; coordinates in POINTS) ────────────────────
 function pointerAction(steps) {
     return {

package/dist/lib/modality.js

@@ -97,8 +97,13 @@ export function iterationHasContent(details, modality) {
         const ep = readExternalChatbotEndpoint(details);
         return !!ep.endpoint || !!ep.chatbot_endpoint_id;
     }
-    // interactive (default)
-    return typeof d.url === "string" && d.url.length > 0;
+    // interactive (default): browser/figma iterations carry a `url`; native
+    // (ios/android) iterations carry an `app_artifact` instead and need no URL
+    // (the backend made url optional for native — ish-backend 9708e06e). Either
+    // satisfies "has content".
+    const hasUrl = typeof d.url === "string" && d.url.length > 0;
+    const hasApp = typeof d.app_artifact === "string" && d.app_artifact.length > 0;
+    return hasUrl || hasApp;
 }
 /** The flag fragment a user should pass to populate content for a given modality. */
 export function describeRequiredContentFlag(modality, chatMode) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ishlabs/cli",
-  "version": "0.26.1",
+  "version": "0.27.0",
   "description": "The command-line interface for ish",
   "type": "module",
   "bin": {