@ishlabs/cli 0.26.1 → 0.27.1

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

@@ -5,10 +5,15 @@
  * 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";
 import { createDevice } from "./device.js";
+import { nativeStateResetWarning } from "./ios.js";
+import { provisionDevicePool, maxConcurrentDevices, totalMemBytes, PER_DEVICE_MB, } from "./device-pool.js";
+import { listOnlineSerials } from "./adb.js";
+import { listAvds } from "./emulator.js";
 import pkg from "../../../package.json" with { type: "json" };
 import { enableDebug, isDebugEnabled, debugRawResponse, debugNormalizedActions, debugActionExecution, debugForwards, debugStepSummary, debugRecord, } from "./debug.js";
 /**
@@ -19,6 +24,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
@@ -161,13 +218,59 @@ export async function runLocalSimulations(client, opts) {
         log("\nCancelling after current step...");
     };
     process.on("SIGINT", onSigint);
-    // Native runs share ONE physical device (emulator / simulator), so they
-    // can't run in parallel — force sequential regardless of --parallel.
     const isNativeRun = isNativePlatform(opts.platform);
-    if (isNativeRun && (opts.parallel ?? 1) > 1) {
-        log("Native (android/ios) runs drive a single device — running sequentially.");
+    const requested = opts.parallel ?? opts.participantIds.length;
+    // Native (iOS + Android) can drive a POOL of devices concurrently, auto-sized
+    // to the host's RAM (and, for Android, the number of AVDs) so a small machine
+    // just runs fewer in parallel + queues the rest — never errors. Browser uses
+    // the requested parallelism directly.
+    const NATIVE_PARALLEL_MAX = 5;
+    const nativeParallel = isNativeRun && requested > 1 && opts.participantIds.length > 1;
+    let concurrency;
+    if (nativeParallel) {
+        const cap = Math.min(requested, opts.participantIds.length, NATIVE_PARALLEL_MAX);
+        if (opts.platform === "android") {
+            // Bound by AVDs we can launch + emulators already online.
+            let slots = cap;
+            try {
+                const [avds, online] = await Promise.all([listAvds(), listOnlineSerials()]);
+                slots = avds.length + online.length;
+            }
+            catch {
+                /* fall back to cap if the toolchain query fails */
+            }
+            concurrency = maxConcurrentDevices({
+                totalMemBytes: totalMemBytes(),
+                perDeviceMb: PER_DEVICE_MB.android,
+                requested: cap,
+                deviceCount: Math.max(1, slots),
+            });
+        }
+        else {
+            concurrency = maxConcurrentDevices({
+                totalMemBytes: totalMemBytes(),
+                perDeviceMb: PER_DEVICE_MB.ios,
+                requested: cap,
+            });
+        }
+    }
+    else {
+        if (isNativeRun && requested > 1) {
+            log("Native parallel needs --parallel >1 and >1 participant; running sequentially.");
+        }
+        concurrency = isNativeRun ? 1 : requested;
+    }
+    // iOS: a bundle-id / system-app target can't be reinstalled, so its data
+    // isn't cleared between participants (a local .app IS reinstalled per
+    // participant — see ios.ts resolveBundleId). Warn once up front when that
+    // could skew a multi-participant run. (--app .app ⇒ reinstallable; a bundle id
+    // from --app or the iteration's app_artifact ⇒ not.)
+    if (opts.platform === "ios") {
+        const reinstallable = !!opts.appPath?.toLowerCase().endsWith(".app");
+        const warning = nativeStateResetWarning(reinstallable, opts.participantIds.length);
+        if (warning)
+            log(warning);
     }
-    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.
@@ -178,6 +281,15 @@ export async function runLocalSimulations(client, opts) {
         appBuildReported = true;
         void reportObservedApp(client, opts.iterationId, platform, build, log);
     };
+    // With a device pool, N workers would each read the app build (a redundant
+    // simctl listapps / dumpsys per device). Let only the first worker do it.
+    let appBuildClaimed = false;
+    const claimAppBuild = () => {
+        if (appBuildClaimed)
+            return false;
+        appBuildClaimed = true;
+        return true;
+    };
     try {
         if (concurrency <= 1 || opts.participantIds.length <= 1) {
             // Sequential execution — each participant owns its own browser
@@ -197,6 +309,47 @@ export async function runLocalSimulations(client, opts) {
                 }
             }
         }
+        else if (nativeParallel) {
+            // Native device pool — N simulators/emulators, one participant per device.
+            const deviceWord = opts.platform === "ios" ? "simulator" : "emulator";
+            // nativeParallel ⇒ opts.platform is "ios" | "android" (isNativePlatform true).
+            const pool = await provisionDevicePool({ platform: opts.platform, size: concurrency, log });
+            try {
+                const poolN = pool.devices.length;
+                log(`\nRunning ${opts.participantIds.length} ${opts.platform} simulations across a pool of ` +
+                    `${poolN} ${deviceWord}${poolN === 1 ? "" : "s"}` +
+                    (poolN < Math.min(requested, opts.participantIds.length, NATIVE_PARALLEL_MAX)
+                        ? " (auto-sized to fit this machine)"
+                        : "") +
+                    "...");
+                // Launch all participants; each awaits a free device, so actual
+                // concurrency is bounded by the pool size. A finished worker releases
+                // its device to the next in line.
+                const runOne = async (participantId) => {
+                    if (cancelled)
+                        return;
+                    const participantName = opts.participantNames.get(participantId) ?? participantId;
+                    const participantLog = (msg) => log(`[${participantName}] ${msg}`);
+                    const device = await pool.claim();
+                    try {
+                        participantLog(`Starting on ${deviceWord} ${device.id}`);
+                        await runSingleSimulation(client, participantId, participantName, opts, participantLog, () => cancelled, reportAppBuild, undefined, device, claimAppBuild);
+                        log(`Completed: ${participantName}`);
+                    }
+                    catch (err) {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        log(`Failed: ${participantName} — ${msg}`);
+                    }
+                    finally {
+                        pool.release(device);
+                    }
+                };
+                await Promise.allSettled(opts.participantIds.map(runOne));
+            }
+            finally {
+                await pool.teardown();
+            }
+        }
         else {
             // Parallel execution — shared browser, one tab per participant
             log(`\nRunning ${opts.participantIds.length} simulations in parallel (concurrency: ${concurrency})...`);
@@ -242,7 +395,7 @@ export async function runLocalSimulations(client, opts) {
         process.off("SIGINT", onSigint);
     }
 }
-async function runSingleSimulation(client, participantId, participantName, opts, log, isCancelled, onAppBuild, sharedBrowser) {
+async function runSingleSimulation(client, participantId, participantName, opts, log, isCancelled, onAppBuild, sharedBrowser, pooledDevice, claimAppBuild) {
     // Step 1: Initialize session
     const initResponse = await client.localSimInit({
         participant_id: participantId,
@@ -300,6 +453,8 @@ async function runSingleSimulation(client, participantId, participantName, opts,
         contextValues: session.context_values,
         sharedBrowser,
         appPath: opts.appPath,
+        deviceId: pooledDevice?.id,
+        wdaPort: pooledDevice?.wdaPort,
         log,
     });
     const history = [];
@@ -314,9 +469,10 @@ async function runSingleSimulation(client, participantId, participantName, opts,
         // 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) {
+        // the dedupe in runLocalSimulations keeps this to one POST per run. With a
+        // device pool, only the worker that wins claimAppBuild() reads it (one
+        // simctl/dumpsys read total, not one per device).
+        if (onAppBuild && (!claimAppBuild || claimAppBuild())) {
             try {
                 const observed = await device.appBuild?.();
                 if (observed)
@@ -349,6 +505,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 +741,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 +757,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;