ci: dispatch workflows for folio and the replay ui (#73)

* feat(runner): stop the step loop at the first violation on request * feat(testrun): report violations as a typed error under exit-on-violation * feat(cli): add --exit-on-violation and exit 2 when it fires * docs(cli): document --exit-on-violation, --max-steps, and exit codes * fix(web): enumerate and query across shadow roots in both producers * test(chrome): compare both producers on a shadow-dom parity page * test(browser): drive a canvas-under-shadow-root fixture end to end * fix(web): select the focused field inside a shadow root before typing * fix(web): report the pathname as the screen when there is no hash route * fix(web): settle on dom quiescence instead of returning at body ready * feat(replay-ui): add data-testid hooks the dogfood spec drives * feat(replay-ui): add the dogfood spec sanderling runs against the replay ui * fix(replay-ui): scope the screenshot property to the named state panel * chore(make): add per-platform sanderling build targets * ci: add dispatch workflows for folio and the replay ui * docs: describe the dispatch workflows and how to read a failure * ci(folio): give the ios leg its jdk, android sdk, just, and a clean app start * refactor(web): use max for the settle budget * ci: pin calibrated seeds, skip the flaky ios reinstall, bound every job * ci: authenticate and pin the buf setup step the anonymous release download hit the shared runner ip rate limit and failed the job with 'socket hang up' after three retries. * docs: record that canvas apps need a dom proxy to be text-fuzzable * fix(ios): bound lifecycle rpcs and claim the target device a launch the simulator rejects sent the xctest session into a recovery chain that answered minutes late or never, and the rpc had no deadline, so the run hung with no trace and no error. also take a per-udid flock: a second run's reinstall lands under the first's live automation session and wedges it. * docs(ci): correct the ios hang wording and note the device lock * refactor(verifier): derive the lastAction shape from one field list both hosts must show a spec the same lastAction. one ordered list now feeds the goja object and the json the web host installs, so they cannot drift. * fix(web): install lastAction in the page before extractors read it state.lastAction was hardcoded null on web, so every property reading it was silently vacuous: a correct property passed without ever firing. * fix(web): carry element identity on actions and fix findAll on paths an action's target was coordinates only, so a property matching on which element was acted upon could never fire. ax.findAll([a,b]) also returned nothing on web. * fix(chrome): wait out a route transition before sampling facts the tree stays byte-identical and quiet across a cross-fade, so both the quiet timer and the unchanged-tree escape called it settled mid-flight and extractors read two screens at once. * fix: bound the pre-run app launch launch happens before the runner starts, so --duration never covered it and a wedged driver hung with no trace and no error. * fix(folio): read balances from merged cards and treat unreadable as unknown compose for web merges the whole accountcard subtree, so the balance child never exists there and every card parsed as 0. the property then compared 0 to 0 and fired on any submit, which is a false positive generator. unknown is now null and null is vacuously true. * test(folio): cover merged-card parsing and unknown balances * ci(folio): make web an expect-the-bug leg the web runtime can observe the double submit now, so the health gate understates it. seed 1 finds it at step 109, 3 runs out of 3. * docs(ci): explain why a submit tap landing on home is the bug * fix(ios): read a StaticText's label as its text AXValue was the only source for text, but a StaticText carries its string in AXLabel, so nothing on screen had .text on ios: a spec reading it saw everything on android and nothing here. * docs(ci): correct the calibrated step ranges * fix(folio): stop convicting on arithmetic float64 cannot hold past 2^53 cents the gap between representable values is 128, so a real 1600-cent move reads back as something else and the equality is false for a healthy submit as readily as a double one. also match parseCents: a sign or an oversized amount is rejected, not read as an amount. * test(folio): pin the safe-integer guard and its boundary * docs: stop teaching the zero-default that caused a false alarm * docs: write down the silent-vacuity failure modes * feat(folio): tag the home total and the card transaction count the total was the only untagged node on the screen, so the spec had to sum cards and a clipped card broke the sum. * fix(folio): read the app's own total and refuse contaminated windows summing cards went null when one was clipped, and the null poisoned the carrier for the rest of the run. the balance window also spanned every transaction since the last home visit, so the property convicted on deltas it could not attribute: the old web witness was 3.16x the typed amount, not 2x. * test(folio): pin the window rules and the count invariant * fix(folio): never read a frame that shows two screens android dumps a cross-fade with both screens in the tree. the route said add-transaction while an unscoped find said home, so the oracle took a half-rendered total as fresh and convicted on a tap that committed nothing. one function now decides the route and returns null when the frame is ambiguous. * test(folio): cover transition frames, card readings and creation * fix(folio): only disambiguate counts that came from merged text the equal-length digit rule exists because web merges the card and an account named -1 makes '12' ambiguous. a dedicated count node has nothing to disambiguate, so applying it there threw away real evidence. * ci(folio): pin the recalibrated seeds and drop android to a health gate web 3 and ios 7 convict 3 runs out of 3 with an exactly 2x witness. android convicts 2 in 5 because the same seed does not walk the same trajectory there, so it proves the app runs instead. * docs(ci): describe the two properties and why android cannot convict * fix(android): wait out a route cross-fade before snapshotting the dump could hold two screens at once, and the runner refuses to act on such a tree, so a quarter of android steps applied no action and the count varied per run: the same seed never walked the same trajectory. the ios companion and the chrome driver already do this. * ci(folio): let the android leg run far enough to see its conviction * docs: only the repo owner merges * ci(folio): a thrown predicate is not a conviction exit 2 means the run recorded a violation, and a predicate that throws is recorded as one too. so was newAccountBalanceIsZero, an unrelated property in the same spec. the gate read the exit code and went green with detection dead. * ci: install idb-companion from its tap and stop interpolating inputs idb-companion is not in homebrew-core, so the ios leg died before it built anything. replay-ui expanded dispatch inputs into the shell. * docs: correct the snippets and numbers that drifted from the code * test(sidecar): pin that a slow read counts toward the stability streak * fix(web): read the page's extractors only on steps that count the page advances the spec's carriers when it evaluates, but the runner applied the result only on non-transitional steps. a discarded step moved the window forward anyway, so the next accepted pair bracketed two transactions while counting one submit, and convicted a healthy app. extractor errors now fail the run instead of leaving goja's values in current against v8's in previous. * fix(chrome): anchor the transition deadline when the dom goes quiet it was anchored at script start, so a page that churned past the window reached the check already expired and returned mid cross-fade. the driver now publishes the idle timeout it needs, since the caller's 1s could never spend the 800ms window. * fix(web): fail on a partial extractor override same mixed-producer hazard as the install error: some extractors hold the page's value and the rest hold goja's, and a property comparing across that split fires on a healthy app. * docs: six of seven, the seventh is the stock property * fix(folio): drop a name two cards answer to homeTxnCountsOf keyed on the account name and let the last card win, so two accounts the fuzzer named the same collapsed into one entry. a reading that saw one Travel card and a later one that saw both then subtracted two different accounts' counts, and submitCommitsOneTransactionPerAction convicted a healthy app of double-submitting. it is a gated property in folio-run.sh, so that reads as "found the submit bug" over a card scrolling into view. same rule createdAccountHasNonZeroBalance already applies: a name nothing can attribute is no evidence. counted over every card, since an unreadable twin spoils the identity too. * perf(folio): read each frame once every extractor asked routeOf, and routeOf does five ax.find calls. on web each find walks the document and every shadow root beneath it, so the spec cost 110 tree walks a step; homeCards was parsed four times over. now 5 and once. keyed on the identity of the state object because both hosts build a new one per step and hand that one object to every getter, so it cannot outlive its frame. holding the reference is what keeps that true rather than likely. * fix(web): keep an undefined reading's index through JSON json has no undefined, so an extractor whose getter returned one had its whole index dropped by JSON.stringify. that index then kept goja's dump-derived value while its neighbours held the page's, and a property comparing previous to current across the split fires on a healthy app. folio has nine on(route, tag) extractors, so this was most extractors on most steps. each reading is wrapped in a {value} envelope: the drop now happens inside the entry, and an absent value means the getter returned undefined, which is what the goja host records for the same getter. a json null would instead claim it returned null and x.current === undefined would answer differently on the two hosts. * feat(verifier): report the registered extractor count the web path needs it to check the page sent one reading per extractor. * fix(runner): fail when the page reports fewer readings than extractors the comment here already claimed a partial override was fatal. it was not: the skipped check only catches indices outside the extractor list, so a page reporting values for some extractors and not others left the rest holding goja's reading of the dump with nothing said. * test(browser): drive an undefined reading through the whole web path four layers carry it: the page's envelope, the driver's unwrap, the runner's count check and the verifier's decode. each has a unit test and only a run proves they compose. goes red both ways, decoding an absent value as null and dropping the envelope. * fix(web): offer the aria roles a user activates only role=button was in the tappable set, so link, checkbox, radio, switch, tab, option, the menuitems and treeitem were invisible to the enumeration however plain the control looked. the replay ui builds its step rows as <li role="option">, and the spec dogfooding it had to hand-write an action to reach them because no default verb could see a single row. both producers build the set from the same role list, since the parity test compares them element by element. * test(browser): tap a role-based control end to end every control on the page is an <li role="option">, the shape the replay ui gives its step rows, and the spec carries no action of its own: the property firing is the evidence the default enumeration offered a tap on one. * fix(web): read aria-disabled as disabled the enabled fact came off the disabled property, which only real form controls have. it reads undefined on the role-based controls the tappable set now covers, so every one of them looked enabled however plainly it was marked otherwise, and the fuzzer would spend actions on inert ones. both producers answer the same two ways, and the parity fixture carries a disabled row so the comparison covers it: reverting one side alone names the element and the fact. * docs(replay-ui): the enumeration reaches step rows now the comment said role="option" is not in the tappable selector set, which stopped being true a few commits ago. selectAStep stays, for the reason the tab weight below it stays: one row among the page's clickable elements is a thin chance, and both step-facing properties go vacuous on a run that never selects one. * test(runner): bound the last-action test by steps, not wall clock 100ms of wall clock against an assertion that two steps ran fatals under load with "the web path never installed it", which reads as a regression. every sibling test in the package uses a long duration and MaxSteps. * ci: run the kotlin tests in make test RouteTransitionTest and the stability poll cover the android settle and nothing in ci ran them. :sidecar:test needs no android sdk, checked by running it with ANDROID_HOME pointed at nothing. * fix(sidecar): measure the stability streak as observed quiet parameterising pollUntilStable also moved the clock to the start of the read that opened a run of identical snapshots, so a read's own duration counted as quiet. the pre-existing caller polls a real uiautomator dump: at 400ms a read, 750ms of required quiet became 250ms of observed quiet and the poll settled in two reads instead of four. the parameters stay, the semantics go back. * test(sidecar): pin the transition cap by driving it it asserted 1500 >= 700 + 300, two constants, which can only fail if someone edits a constant. it now drives awaitSettledTree against a fade that lands after 700ms and asserts it hands back the settled tree before the cap. cut the cap to 1000 and it goes red. * ci: pin buf-setup-action to a commit it takes a token now, so a floating tag is a token handed to whatever that tag moves to. note v1 there is a branch, not a tag, so the ref lookup that resolves it is matching-refs/heads/v1. * ci: declare least-privilege permissions none of the three declared any, so each got the repository default. release.yml and docs.yml already do this. all three only check out, build, test and upload artifacts. * ci: fail fast when a server never comes up the readiness loops fell through silently after 30 tries, so a server that never started surfaced as an opaque driver failure minutes later. each now says what did not answer and on which port. * ci(folio): a missing trace is not a verdict with no trace the android gate ran its grep against ./trace.jsonl and reported "never reached AddTransactionScreen, so it never got past login", which is not what happened. the web and ios branches had the same misdiagnosis on exit 0. same class, one line up: the classifier's own failure was swallowed, so with the evidence reader dead the gate printed a healthy run and exited 0. * ci(replay-ui): skip a run directory with no trace the summarise step is if: always(), and under github's bash -eo pipefail an unmatched glob stays literal, the redirect fails, pipefail carries it into the assignment and -e kills the step. so a failed fuzz run went red twice, once for the real reason.
2026-10-02 11:07:10 +00:00 · 2026-08-15 13:01:27 +05:30
1 parent 1f71e052d7
commit b02e86b2e3
@@ -63,14 +63,82 @@ internal const val STABILITY_POLL_CAP_MILLIS = 2000L
 // missed.
 internal const val MIN_STABLE_STREAK_MILLIS = 750L

+// TRANSITION_* bound the wait a snapshot pays when the tree it read shows two
+// routes at once, which on Compose means a NavHost cross-fade is in flight.
+// They are shorter than the constants above because this wait has one job,
+// outlasting the fade, where the poll above must also catch an async effect
+// that fires late.
+//
+// The streak matches the iOS companion's 300ms for the same reason: what this
+// wait is for is the cross-fade, and the cross-fade is caught by the
+// route-screen check rather than by streak length, so the streak only has to
+// be long enough that the reads spanning it are not all inside one frame.
+// MIN_STABLE_STREAK's 750ms is sized for a poll that must also catch an async
+// effect firing late, and at ~160ms per read-and-interval it costs three or
+// four more reads than this does.
+internal const val TRANSITION_STABLE_STREAK_MILLIS = 300L
+
+// The interval is the iOS companion's rather than STABILITY_POLL_INTERVAL's
+// 250ms: the wide interval exists to stop a per-step poll hammering
+// UiAutomation, and this one runs only on the frames that show two routes,
+// about a quarter of steps on folio. The read itself paces the loop.
+internal const val TRANSITION_POLL_INTERVAL_MILLIS = 100L
+
+// The cap is the iOS companion's 1500ms, and it has to be at least this: the
+// NavHost cross-fade is a 700ms tween (Compose navigation's default enter and
+// exit), it starts when the action lands rather than when the snapshot begins,
+// and the streak above has to fit after it. Measured on the emulator, a 600ms
+// cap left about a third of fades unfinished.
+//
+// A layout that holds two routes at rest pays the full cap on every snapshot
+// RPC it is read with, and the runner issues more than one: fetchSyncedState
+// (internal/runner) re-fetches a tree it considers transitional up to 4 times.
+// It stops early once two consecutive fetches come back byte-identical, so such
+// a layout costs 2 caps on a still tree and up to 4 on one that jitters
+// underneath. Per step, not once per step.
+internal const val TRANSITION_POLL_CAP_MILLIS = 1500L
+
+// awaitSettledTree reads the hierarchy and, while the tree it gets back holds
+// more than one route, keeps reading until the cross-fade lands or the cap
+// expires. It returns the last tree read, so the caller gets the settled one
+// rather than paying for another read.
+//
+// Two nodes carrying the SAME route id are one destination, not a transition;
+// countRouteScreens counts distinct tags, so a screen that nests a repeat of
+// its own id does not pay this wait at all.
+internal fun awaitSettledTree(read: () -> String): String {
+    var json = read()
+    if (countRouteScreens(json) <= 1) return json
+    pollUntilStable(
+        TRANSITION_POLL_CAP_MILLIS,
+        TRANSITION_STABLE_STREAK_MILLIS,
+        TRANSITION_POLL_INTERVAL_MILLIS,
+    ) {
+        json = read()
+        stabilitySnapshot(json)
+    }
+    return json
+}
+
 // pollUntilStable returns when the snapshot has been non-null and equal to
-// itself for an uninterrupted stretch of at least MIN_STABLE_STREAK_MILLIS,
-// capped at timeoutMillis. snapshot must omit transient attributes (e.g.
-// measure-pass bounds) so layout-only flicker doesn't extend the wait, and
-// must return null when the snapshot looks transitional (e.g. mid NavHost
-// cross-fade) so the streak resets and the loop keeps polling instead of
-// declaring a partial state stable.
-internal fun pollUntilStable(timeoutMillis: Long, snapshot: () -> String?) {
+// itself for an uninterrupted stretch of at least streakMillis, capped at
+// timeoutMillis. snapshot must omit transient attributes (e.g. measure-pass
+// bounds) so layout-only flicker doesn't extend the wait, and must return null
+// when the snapshot looks transitional (e.g. mid NavHost cross-fade) so the
+// streak resets and the loop keeps polling instead of declaring a partial
+// state stable.
+//
+// streakMillis is quiet the poll OBSERVED: the clock starts when the read that
+// first matched its predecessor returns, so the reads spanning it are not
+// charged to it. A hierarchy fetch on Android costs more than the poll
+// interval, and charging it would let a 500ms read clear the default 750ms
+// streak having watched 250ms of quiet.
+internal fun pollUntilStable(
+    timeoutMillis: Long,
+    streakMillis: Long = MIN_STABLE_STREAK_MILLIS,
+    intervalMillis: Long = STABILITY_POLL_INTERVAL_MILLIS,
+    snapshot: () -> String?,
+) {
    if (timeoutMillis <= 0) return
    val deadline = System.currentTimeMillis() + timeoutMillis
    var prior = try {
@@ -80,7 +148,7 @@ internal fun pollUntilStable(timeoutMillis: Long, snapshot: () -> String?) {
    }
    var streakStart = 0L
    while (System.currentTimeMillis() < deadline) {
-        Thread.sleep(STABILITY_POLL_INTERVAL_MILLIS)
+        Thread.sleep(intervalMillis)
        val current = try {
            snapshot()
        } catch (_: Exception) {
@@ -89,7 +157,7 @@ internal fun pollUntilStable(timeoutMillis: Long, snapshot: () -> String?) {
        val now = System.currentTimeMillis()
        if (prior != null && current != null && prior == current) {
            if (streakStart == 0L) streakStart = now
-            if (now - streakStart >= MIN_STABLE_STREAK_MILLIS) return
+            if (now - streakStart >= streakMillis) return
        } else {
            streakStart = 0L
        }
@@ -119,36 +187,43 @@ private val ROUTE_TAG_KEYS = setOf(

 private val jsonMapper = com.fasterxml.jackson.module.kotlin.jacksonObjectMapper()

+// countRouteScreens counts DISTINCT route-level destination tags, not the nodes
+// carrying them. A screen that nests a node repeating its own route id puts two
+// tagged nodes in the tree while only one destination is on screen; counting
+// nodes would read that as a cross-fade that never ends, and the caller would
+// pay its full poll budget on every step of that screen and never settle.
 internal fun countRouteScreens(treeJson: String): Int {
    if (treeJson.isBlank()) return 0
    return try {
        val root = jsonMapper.readTree(treeJson)
-        countRouteScreens(root)
+        val tags = mutableSetOf<String>()
+        collectRouteScreens(root, tags)
+        tags.size
    } catch (_: Exception) {
        0
    }
 }

-private fun countRouteScreens(
+private fun collectRouteScreens(
    node: com.fasterxml.jackson.databind.JsonNode,
-): Int {
-    var count = 0
+    into: MutableSet<String>,
+) {
    val attributes = node.get("attributes")
    if (attributes != null && attributes.isObject) {
        for (key in ROUTE_TAG_KEYS) {
            val value = attributes.get(key) ?: continue
            if (value.isNull) continue
-            if (value.asText().endsWith("Screen")) {
-                count++
+            val text = value.asText()
+            if (text.endsWith("Screen")) {
+                into.add(text)
                break
            }
        }
    }
    val children = node.get("children")
    if (children != null && children.isArray) {
-        for (child in children) count += countRouteScreens(child)
+        for (child in children) collectRouteScreens(child, into)
    }
-    return count
 }

 // structuralHash hashes a Maestro TreeNode-shaped JSON string by walking it
@@ -873,13 +948,29 @@ class MaestroDriverBackend(private val serial: String?) : DriverBackend {
    override fun recentLogs(sinceUnixMillis: Long, minLevel: String) =
        readLogcat(serial, sinceUnixMillis, minLevel)

+    // snapshot waits out a NavHost cross-fade before it reads, so the runner is
+    // never handed a tree holding two routes at once. It belongs here rather
+    // than in waitForIdle: the runner gives waitForIdle a one-second deadline
+    // and abandons the RPC when it expires, which is not enough room for a
+    // 700ms fade that began before the settle did, and a wait that outlives the
+    // deadline just races the runner's own fetch on the device-side server.
+    // The snapshot RPC carries the step's deadline instead, so the wait can run
+    // to a bound that actually covers the animation.
+    //
+    // The predicate costs nothing on a settled frame: the read it needs is the
+    // read the snapshot was going to do anyway. That is what makes this
+    // affordable, where the structural poll that used to run in waitForIdle was
+    // not: it fetched the hierarchy ~4 more times on every mutating step.
+    override fun snapshot(): SnapshotSample =
+        SnapshotSample(awaitSettledTree { hierarchy() }, screenshot())
+
    override fun waitForIdle(durationMillis: Long) {
        // waitForAppToSettle blocks on the View-system animation and maestro's
-        // own structural settle, which is enough on its own. A follow-up
-        // structural-hash poll used to run here, but each hierarchy fetch is
-        // ~500ms on a physical device, so it cost ~2.8s per mutating step for
-        // marginal benefit; the runner already re-fetches while a frame still
-        // looks transitional.
+        // own structural settle. It cannot see a Compose cross-fade: the fade
+        // keeps both routes alive with the tree byte-identical, so a settle
+        // that watches for change returns in the middle of one. That is what
+        // snapshot above waits out; a structural poll here used to try, cost
+        // ~2.8s per mutating step, and was removed.
        driver.waitForAppToSettle(null, null, durationMillis.toInt())
    }

@@ -0,0 +1,108 @@
+package dev.sanderling.sidecar
+
+import org.junit.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertTrue
+
+// The Android backend's snapshot waits out a NavHost cross-fade before it
+// reads. Without that wait the runner is handed a tree holding two routes at
+// once, refuses to act on it, and the step applies nothing; how many steps land
+// that way varies run to run, so the same seed walks a different trajectory
+// each time. These cover the wait (awaitSettledTree) and what it costs.
+class RouteTransitionTest {
+    private fun screen(id: String, child: String = "") =
+        """{"attributes":{"resource-id":"$id"},"children":[$child]}"""
+
+    private fun tree(vararg children: String) =
+        """{"attributes":{"resource-id":"root"},"children":[${children.joinToString(",")}]}"""
+
+    private val crossFade = tree(screen("LedgerScreen"), screen("AddTransactionScreen"))
+    private val landed = tree(screen("AddTransactionScreen"))
+
+    @Test fun waitsForTheCrossFadeToLandAndReturnsTheLandedTree() {
+        // The first read caught both routes alive. The wait must keep reading
+        // until only the destination is left, and hand back that tree: the
+        // caller records what it returns, so returning the fade would put the
+        // frame in the trace whether or not the wait happened.
+        var reads = 0
+        val settled = awaitSettledTree {
+            reads++
+            if (reads <= 3) crossFade else landed
+        }
+        assertTrue(reads > 3, "must keep reading until the fade lands, reads=$reads")
+        assertEquals(1, countRouteScreens(settled), "must return a tree with one route")
+    }
+
+    @Test fun settledFrameCostsExactlyOneRead() {
+        // A hierarchy read is the expensive part of a step, and this one is the
+        // read the snapshot was going to do anyway. A frame that is already on
+        // one route must not pay for a second: that cost, on every step, is why
+        // the unconditional structural poll was removed from waitForIdle.
+        var reads = 0
+        val settled = awaitSettledTree {
+            reads++
+            landed
+        }
+        assertEquals(1, reads, "a one-route frame must read once and return")
+        assertEquals(landed, settled)
+    }
+
+    @Test fun repeatedRouteIdIsOneScreenNotATransition() {
+        // A screen nesting a node that repeats its own route id puts two tagged
+        // nodes in the tree while one destination is on screen. Counting nodes
+        // would read that as a fade that never ends: every step of that screen
+        // would burn the whole poll budget and still hand over a frame the
+        // runner refuses to act on.
+        val nested = tree(screen("HomeScreen", screen("HomeScreen")))
+        assertEquals(1, countRouteScreens(nested), "the same id twice is one route")
+        var reads = 0
+        awaitSettledTree {
+            reads++
+            nested
+        }
+        assertEquals(1, reads, "a repeated route id must not be treated as a transition")
+    }
+
+    @Test fun aLayoutThatKeepsTwoRoutesIsBoundedByTheCap() {
+        // Two routes alive at rest is a real layout, not a fade, and no amount
+        // of waiting will resolve it. The wait is bounded by wall clock, so
+        // such a screen costs the cap once per step and nothing more.
+        val start = System.currentTimeMillis()
+        val settled = awaitSettledTree { crossFade }
+        val elapsed = System.currentTimeMillis() - start
+        assertTrue(
+            elapsed >= TRANSITION_POLL_CAP_MILLIS,
+            "must actually wait out a two-route tree, elapsed=${elapsed}ms",
+        )
+        assertTrue(
+            elapsed < TRANSITION_POLL_CAP_MILLIS + 1000L,
+            "must stop at the cap, elapsed=${elapsed}ms",
+        )
+        assertEquals(crossFade, settled, "the caller still gets a tree to record")
+    }
+
+    @Test fun capCoversTheNavHostFadePlusTheStreak() {
+        // Compose navigation's default enter and exit are a 700ms tween, and
+        // the fade starts when the action lands, not when the snapshot begins.
+        // A cap that does not clear the fade and the streak after it hands the
+        // caller a transitional frame, which is the whole defect.
+        val fadeMillis = 700L
+        val start = System.currentTimeMillis()
+        val settled = awaitSettledTree {
+            if (System.currentTimeMillis() - start < fadeMillis) crossFade else landed
+        }
+        val elapsed = System.currentTimeMillis() - start
+
+        assertEquals(landed, settled, "must hand back the landed tree, not the fade")
+        assertTrue(
+            elapsed >= fadeMillis,
+            "cannot have settled before the fade ended, elapsed=${elapsed}ms",
+        )
+        assertTrue(
+            elapsed < TRANSITION_POLL_CAP_MILLIS,
+            "the ${TRANSITION_POLL_CAP_MILLIS}ms cap has to leave room for a ${fadeMillis}ms " +
+                "fade and the ${TRANSITION_STABLE_STREAK_MILLIS}ms streak after it, but the " +
+                "wait ran to the cap instead, elapsed=${elapsed}ms",
+        )
+    }
+}
@@ -16,28 +16,68 @@ class StabilityPollTest {
        assertTrue(elapsed < 3000L, "should not run to cap when stable, elapsed=${elapsed}ms")
    }

+    @Test fun slowSnapshotReadsDoNotEatTheStreak() {
+        // Every other test here uses an instant lambda and so passes whether or
+        // not a read is charged to the streak; this one is the difference.
+        // StubDriverBackend's waitForIdle polls a real `uiautomator dump`,
+        // which costs hundreds of milliseconds, so the slow read is the case it
+        // runs in.
+        val readMillis = 400L
+        val sampleStarts = mutableListOf<Long>()
+        val sampleEnds = mutableListOf<Long>()
+        val start = System.currentTimeMillis()
+        pollUntilStable(5000L) {
+            sampleStarts += System.currentTimeMillis() - start
+            Thread.sleep(readMillis)
+            sampleEnds += System.currentTimeMillis() - start
+            "stable"
+        }
+
+        // What the poll actually watched: the last read began this long after
+        // the first one returned, and every sample in between matched.
+        val observedQuiet = sampleStarts.last() - sampleEnds.first()
+        assertTrue(
+            observedQuiet >= MIN_STABLE_STREAK_MILLIS,
+            "the poll returned having observed only ${observedQuiet}ms of quiet, not " +
+                "${MIN_STABLE_STREAK_MILLIS}ms; starts=$sampleStarts ends=$sampleEnds",
+        )
+        assertTrue(
+            sampleStarts.size >= 3,
+            "a ${readMillis}ms read cannot clear the streak in one pair, starts=$sampleStarts",
+        )
+    }
+
    @Test fun streakResetsOnAnyChange() {
        // A late transition that fires after the prior streak has already
        // begun must reset the clock: the post-transition stable window has
        // to start over and meet MIN_STABLE_STREAK_MILLIS from scratch.
        var calls = 0
-        val start = System.currentTimeMillis()
-        // First 4 samples are "calm", then 1 transient change, then "stable"
-        // forever - the calm prefix is meaningless because of the transition.
+        var transientAt = 0L
+        // A short "calm" prefix, one transient change, then "stable" forever.
+        // The prefix is meaningless because of the transition: only the streak
+        // that starts after it can end the wait.
        pollUntilStable(3000L) {
            calls++
            when {
-                calls <= 4 -> "calm"
-                calls == 5 -> "transient"
+                calls <= 2 -> "calm"
+                calls == 3 -> {
+                    transientAt = System.currentTimeMillis()
+                    "transient"
+                }
                else -> "stable"
            }
        }
-        val elapsed = System.currentTimeMillis() - start
+        val sinceTransition = System.currentTimeMillis() - transientAt
        assertTrue(
-            elapsed >= MIN_STABLE_STREAK_MILLIS,
-            "post-transition streak must reach ${MIN_STABLE_STREAK_MILLIS}ms, elapsed=${elapsed}ms",
+            calls >= 8,
+            "after the transition the poll needs a fresh matching pair and then a full " +
+                "${MIN_STABLE_STREAK_MILLIS}ms of quiet, which is 8 samples, got $calls",
+        )
+        assertTrue(
+            sinceTransition >= MIN_STABLE_STREAK_MILLIS,
+            "the calm prefix must not count: a full ${MIN_STABLE_STREAK_MILLIS}ms streak has to " +
+                "start over after the transition, returned ${sinceTransition}ms after it",
        )
-        assertTrue(calls >= 10, "expected enough samples to span calm + transient + stable streak, got $calls")
    }

    @Test fun transitionalNullsForceLoopToKeepWaiting() {