@ishlabs/cli 0.26.0 → 0.27.0

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

@@ -5,10 +5,12 @@
  * 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 } from "./actions.js";
+import { detectNoVisibleChange, describeAction, classifyStepKind } from "./actions.js";
 import { createDevice } from "./device.js";
+import pkg from "../../../package.json" with { type: "json" };
 import { enableDebug, isDebugEnabled, debugRawResponse, debugNormalizedActions, debugActionExecution, debugForwards, debugStepSummary, debugRecord, } from "./debug.js";
 /**
  * Native (mobile) platforms drive a single physical device via screenshot →
@@ -18,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
@@ -113,6 +167,34 @@ const SENTIMENT_ICONS = {
     Positive: "+", Negative: "-", Neutral: "~",
     Frustrated: "!", Confused: "?", Delighted: "*",
 };
+const CLI_VERSION = pkg.version;
+/**
+ * Stamp the app build this run drove onto the iteration, so the web app's
+ * run-settings card can show which build the iteration is on. Best-effort:
+ * a native run never depends on this landing, so failures are warned, not
+ * thrown. Only native platforms carry a build.
+ */
+async function reportObservedApp(client, iterationId, platform, build, log) {
+    if (platform !== "ios" && platform !== "android")
+        return;
+    try {
+        await client.post(`/iterations/${iterationId}/observed-app`, {
+            platform,
+            package: build.package,
+            version: build.version,
+            build: build.build,
+            cli_version: CLI_VERSION,
+        });
+        const label = [build.version, build.build ? `(${build.build})` : null]
+            .filter(Boolean)
+            .join(" ");
+        log(`Recorded app build${label ? `: ${label}` : ""}`);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`Could not record app build for the iteration: ${msg}`);
+    }
+}
 /**
  * Run local simulations — parallel when multiple participants, sequential by default.
  * Use --parallel <n> to control concurrency (default: number of participants).
@@ -139,6 +221,16 @@ export async function runLocalSimulations(client, opts) {
         log("Native (android/ios) runs drive a single device — running sequentially.");
     }
     const concurrency = isNativeRun ? 1 : (opts.parallel ?? opts.participantIds.length);
+    // Native runs stamp the app build onto the iteration once — every
+    // participant in a run drives the same installed build, so dedupe to a
+    // single best-effort POST after the first device resolves its app.
+    let appBuildReported = false;
+    const reportAppBuild = (build, platform) => {
+        if (appBuildReported)
+            return;
+        appBuildReported = true;
+        void reportObservedApp(client, opts.iterationId, platform, build, log);
+    };
     try {
         if (concurrency <= 1 || opts.participantIds.length <= 1) {
             // Sequential execution — each participant owns its own browser
@@ -149,7 +241,7 @@ export async function runLocalSimulations(client, opts) {
                 log(`\nStarting local simulation for ${participantName}...`);
                 try {
                     const participantLog = (msg) => log(`[${participantName}] ${msg}`);
-                    await runSingleSimulation(client, participantId, participantName, opts, participantLog, () => cancelled);
+                    await runSingleSimulation(client, participantId, participantName, opts, participantLog, () => cancelled, reportAppBuild);
                     log(`Completed: ${participantName}`);
                 }
                 catch (err) {
@@ -183,7 +275,7 @@ export async function runLocalSimulations(client, opts) {
                         const participantLog = (msg) => log(`[${participantName}] ${msg}`);
                         participantLog("Starting...");
                         try {
-                            await runSingleSimulation(client, participantId, participantName, opts, participantLog, () => cancelled, sharedBrowser);
+                            await runSingleSimulation(client, participantId, participantName, opts, participantLog, () => cancelled, reportAppBuild, sharedBrowser);
                             participantLog("Completed");
                         }
                         catch (err) {
@@ -203,7 +295,7 @@ export async function runLocalSimulations(client, opts) {
         process.off("SIGINT", onSigint);
     }
 }
-async function runSingleSimulation(client, participantId, participantName, opts, log, isCancelled, sharedBrowser) {
+async function runSingleSimulation(client, participantId, participantName, opts, log, isCancelled, onAppBuild, sharedBrowser) {
     // Step 1: Initialize session
     const initResponse = await client.localSimInit({
         participant_id: participantId,
@@ -274,6 +366,19 @@ async function runSingleSimulation(client, participantId, participantName, opts,
     try {
         // Step 3: Launch / navigate the target to its starting point.
         await device.launchOrReset(launchTarget);
+        // Step 3b: Capture the installed app's build (native only). Best-effort —
+        // the dedupe in runLocalSimulations keeps this to one POST per run, and a
+        // failed read or report never disturbs the simulation.
+        if (onAppBuild) {
+            try {
+                const observed = await device.appBuild?.();
+                if (observed)
+                    onAppBuild(observed, platform);
+            }
+            catch {
+                // ignore — build capture is non-essential
+            }
+        }
         // Step 4: Run assignment loop
         for (let assignmentIdx = 0; assignmentIdx < session.assignments.length; assignmentIdx++) {
             const assignment = session.assignments[assignmentIdx];
@@ -284,6 +389,12 @@ async function runSingleSimulation(client, participantId, participantName, opts,
             // status when the loop ends because the agent terminated (completed vs
             // abandoned). Stays "in_progress" if the loop hits max_steps.
             let lastAssignmentStatus = "in_progress";
+            // Frame continuity (native): carry the PREVIOUS step's logical-screen
+            // classification + matched frame forward, so this step's match-frame call
+            // can tell the backend to reuse the frame when the screen didn't change
+            // (pure scroll / non-submitting keyboard). Reset per assignment.
+            let lastStepKind = "none";
+            let lastFrameVersionId;
             while (step < maxSteps && !assignmentCompleted && !isCancelled()) {
                 // OBSERVE — the device refreshes its own active surface (popup /
                 // switch_tab for browser) before capturing. (The browser device emits
@@ -291,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");
@@ -395,12 +511,16 @@ async function runSingleSimulation(client, participantId, participantName, opts,
                 const actionDescs = [];
                 const elementNames = [];
                 const actionDebugEntries = [];
+                // Per-action success (index-aligned with stepResponse.actions), used to
+                // classify this step's logical-screen kind for frame continuity.
+                const perActionSuccess = [];
                 const preActionScreenshot = await device.captureScreenshot();
                 for (let i = 0; i < stepResponse.actions.length; i++) {
                     if (isCancelled())
                         break;
                     const action = stepResponse.actions[i];
                     const result = await device.executeAction(action);
+                    perActionSuccess[i] = result.success;
                     const desc = describeAction(action);
                     debugActionExecution(i, action, result, action.node_id ? "cdp" : "playwright");
                     const openedNewTab = result.openedNewTab;
@@ -415,29 +535,44 @@ async function runSingleSimulation(client, participantId, participantName, opts,
                     const actionType = action.type || "unknown";
                     const INTERNAL_ACTIONS = new Set(["think"]);
                     if (!INTERNAL_ACTIONS.has(actionType)) {
+                        // Pack `data` to match the hosted sim's map_action_to_db so native
+                        // rows render identically. value_type lets the FE flag var/secret;
+                        // drag's full path goes under data.coordinates (0-1000), not a
+                        // bespoke drag_end. Secret `value` stays masked (it's the variable
+                        // key, not the resolved secret — masking is strictly safer than the
+                        // web path, and value_type now drives the FE lock glyph).
+                        const actionData = {
+                            ...(action.value !== undefined && action.value !== null && { value: action.value_type === "secret" ? "***" : action.value }),
+                            ...(action.value_type && { value_type: action.value_type }),
+                            ...(action.mode && { mode: action.mode }),
+                            ...(action.submit && { submit: action.submit }),
+                            ...(action.direction && { direction: action.direction }),
+                            ...(action.amount && { amount: action.amount }),
+                            ...(action.count && action.count > 1 && { count: action.count }),
+                            ...(action.duration_ms && { duration_ms: action.duration_ms }),
+                            ...(action.modifiers?.length && { modifiers: action.modifiers }),
+                            ...(action.key && { key: action.key }),
+                            ...(action.tab_id && { tab_id: action.tab_id }),
+                            ...(action.orientation && { orientation: action.orientation }),
+                            ...(action.panel && { panel: action.panel }),
+                            ...(action.drag && {
+                                coordinates: {
+                                    startX: action.drag.startX,
+                                    startY: action.drag.startY,
+                                    endX: action.drag.endX,
+                                    endY: action.drag.endY,
+                                },
+                            }),
+                            ...(openedNewTab && { opened_new_tab: true }),
+                        };
                         actionDatas.push({
                             action_type: actionType,
                             element_label: action.element_name ?? null,
                             element_type: action.element_type ?? null,
-                            coordinates: normalizedCoords,
-                            data: {
-                                ...(action.value !== undefined && action.value !== null && { value: action.value_type === "secret" ? "***" : action.value }),
-                                ...(action.mode && { mode: action.mode }),
-                                ...(action.submit && { submit: action.submit }),
-                                ...(action.direction && { direction: action.direction }),
-                                ...(action.amount && { amount: action.amount }),
-                                ...(action.count && action.count > 1 && { count: action.count }),
-                                ...(action.duration_ms && { duration_ms: action.duration_ms }),
-                                ...(action.modifiers?.length && { modifiers: action.modifiers }),
-                                ...(action.key && { key: action.key }),
-                                ...(action.tab_id && { tab_id: action.tab_id }),
-                                ...(action.orientation && { orientation: action.orientation }),
-                                ...(action.panel && { panel: action.panel }),
-                                // The recorded `coordinates` is the drag START; persist the END
-                                // (normalized 0-1000) too so the journey captures the full path.
-                                ...(action.drag && { drag_end: { x: action.drag.endX, y: action.drag.endY } }),
-                                ...(openedNewTab && { opened_new_tab: true }),
-                            },
+                            // Drag's path lives in data.coordinates; the hosted sim leaves the
+                            // top-level coordinates null for a drag.
+                            coordinates: action.drag ? null : normalizedCoords,
+                            data: Object.keys(actionData).length ? actionData : null,
                             order: i,
                         });
                     }
@@ -494,6 +629,24 @@ async function runSingleSimulation(client, participantId, participantName, opts,
                         // Native: drive FrameSourceType.ANDROID/IOS directly; browser falls
                         // back to screen_format server-side.
                         platform,
+                        // Frame continuity: these describe the transition INTO this
+                        // observation, produced by the PREVIOUS step's action. When that
+                        // step was a pure scroll / non-submitting keyboard on a native
+                        // device, the logical screen didn't change — tell the backend to
+                        // reuse the previous frame instead of minting a new one off the
+                        // shifted pixels. Carried from lastStepKind / lastFrameVersionId,
+                        // 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;
                 }
@@ -501,6 +654,31 @@ 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.
+                lastStepKind = classifyStepKind(stepResponse.actions, perActionSuccess);
+                lastFrameVersionId = frameVersionId;
                 // Debug-only: capture post-action screenshot to show result
                 let postActionBase64;
                 if (isDebugEnabled()) {
@@ -520,7 +698,7 @@ async function runSingleSimulation(client, participantId, participantName, opts,
                     forwards.push({ type: "LOOP_DETECTED", content: "A repetitive action cycle was detected. Try a different approach." });
                 }
                 // Record interaction (1-indexed step for backend)
-                interactions.push({
+                const interaction = {
                     step: step + 1,
                     assignment_id: assignment.id,
                     ...(screenshotUrl ? { screenshot_url: screenshotUrl } : { screenshot_base64: obsBase64 }),
@@ -544,7 +722,24 @@ async function runSingleSimulation(client, participantId, participantName, opts,
                     // Server reduces this to Interaction.tab when N >= 2; omit on
                     // single-tab steps to keep the payload (and DB column) null.
                     ...(tabsSnapshot.length >= 2 ? { tabs: tabsSnapshot } : {}),
-                });
+                };
+                // Keep the in-memory array for the debug HTML report.
+                interactions.push(interaction);
+                // Stream this interaction live so the backend persists + commits it
+                // immediately and fires INTERACTION_CREATED in realtime. A streaming
+                // failure must never abort the run — log and continue (the run-end
+                // finalize call still records the terminal state).
+                try {
+                    await client.localSimRecordInteraction({
+                        participant_id: session.participant_id,
+                        product_id: session.product_id,
+                        interaction,
+                    });
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    log(`  Warning: failed to stream interaction ${step + 1} — ${msg}`);
+                }
                 // Update history for next step
                 history.push({
                     comment: stepResponse.comment,
@@ -635,7 +830,6 @@ async function runSingleSimulation(client, participantId, participantName, opts,
             await client.localSimRecord({
                 participant_id: session.participant_id,
                 product_id: session.product_id,
-                interactions,
                 final_status: finalStatus,
                 assignment_statuses: assignmentStatuses,
             });

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;