Skip to content

fix(mobile): pin each action's ref to the snapshot it came from - #1413

Merged
okwasniewski merged 7 commits into
e2e-inc:mainfrom
samanyudas:fix/issue-1406
Oct 29, 2026
Merged

okwasniewski merged 7 commits into
e2e-inc:mainfrom
samanyudas:fix/issue-1406

Conversation

@samanyudas

@samanyudas samanyudas commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

What and why

  • agent-device tells us which capture a snapshot's refs came from (refsGeneration). The mobile engine dropped that number and sent plain @e4. The daemon resolves a plain ref against its newest snapshot. So a ref from an older capture could tap a different element.
  • Each node binding now keeps its capture's generation, and every ref action sends @e4~s7. When a newer snapshot has replaced that capture, the daemon refuses the ref with ref_generation_mismatch. The engine already maps that to retryable NODE_STALE, so the action finds its node again.
  • One case needed more than that. A test's dragTo locates the drop target in a second snapshot after the source's. With both ends pinned, the source would be one generation old on every retry until the timeout. So the drag finds both nodes again in the newest capture first (current() in packages/mobile/src/surface.ts). It only accepts a node that is still in the same place. If the node moved or disappeared, the drag fails as stale before anything is sent, and the action locates both ends again. An identical sibling can't stand in for the source.
  • An agent-device that reports no generation still gets plain refs, so older daemons behave as before.
  • Merged with main after fix(mobile): reobserve targets after keyboard transitions #1297/fix(mobile): revalidate input bindings before fill and clear #1410: bindings carry both keyboardVisible and refsGeneration, and current() reads main's latestScreen. Overlaps fix(mobile): reject stale refs after transition refresh #1300 only in relocated(): if fix(mobile): reject stale refs after transition refresh #1300 lands first, keep its NODE_STALE throw and this.bind(found, projected).

Issue

Fixes #1406

Verified

Ran it locally: yes. I used the built packages with a fake agent-device HTTP daemon, not a simulator.

  • The issue's own repro (generation.e2e.ts, run with the built e2e run CLI). The fake daemon flips the button to Reopen only when the tap carries ~s7.
  • A drag check over the same fake daemon. It locates the source and the target in two separate snapshots and refuses any ref from an older one. The real client sent {"kind":"drag","source":"@e1~s2","destination":"@e2~s2"}, both from the newest snapshot, and the daemon refused none.
  • New unit tests in packages/mobile/tests/unit/engine.test.ts. They fail on main. The drag test also fails if the change only pins refs, without current(): it gets ref_generation_mismatch. Another test drags a source that disappears between the two locates while an identical twin stays on screen. The drag fails as NODE_STALE and no drag is sent. A third test pins a tap on a control found again after a transition.
main 1a7a331b this branch
ERROR: Expected values to be strictly equal: + 'Complete' - 'Reopen' ✓ taps include the snapshot version
Taps send @e4 Taps send @e4~s7
A tap with a ref from an older capture goes through A tap with a ref from an older capture is refused as NODE_STALE

I didn't run this on a real simulator or emulator.

I wrote this with help from an AI agent (Claude Code), and I reviewed the change myself.

Checklist

  • Changeset added (pnpm changeset) for any change to a published package, or the change is testbed, docs, or CI only.
  • Breaking change: title carries !, the changeset body names what breaks and what replaces it, and the deprecation warning landed a window earlier (stability policy in CONTRIBUTING.md).
  • Docs updated in the same PR: the docs/**/*.mdx page for the behavior, and skills/e2e/ if the skill describes it.
  • Contract change: emitted .d.ts reviewed, tests/types/sdk-types.ts updated; wire change edits the schema and both fixtures.
  • Engine contract change (e2e/engine): changesets for e2e, @e2e-dev/web, and @e2e-dev/mobile.

Reviewed with sol-loop: 3 rounds with gpt-6.1-sol. sol verdict: approved

🤖 Generated with Claude Code

samanyudas and others added 2 commits October 28, 2026 02:20
Fails on main: taps send plain @en refs, so agent-device cannot refuse a
ref from a superseded capture (e2e-inc#1406).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
agent-device reports the capture its refs were issued from as
refsGeneration. The engine dropped it and sent plain @en, which the daemon
resolves against its newest snapshot, so a ref from an older capture could
tap a different element. Each binding now keeps its capture's generation
and every ref action sends @en~sG, so the daemon refuses a superseded ref
(ref_generation_mismatch, already NODE_STALE) instead.

A test's dragTo locates its drop target in a second capture after the
source's, so both ends are found again in the newest capture before the
drag. A daemon that reports no generation still gets plain refs.

Fixes e2e-inc#1406

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mintlify

mintlify Bot commented Oct 27, 2026 •

Copy link
Copy Markdown

Preview approval required

This pull request comes from a fork, so Mintlify won't build a preview until someone with write access approves commit 422bdb1.

Approve preview

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

2 issues found across 4 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/reference/mobile.mdx">

<violation number="1" location="docs/reference/mobile.mdx:352">
P2: This sentence overstates the guarantee for generation-less agent-device versions: `actionTarget()` intentionally sends plain refs when no `refsGeneration` is reported, so those daemons can still resolve a ref against a newer snapshot. Qualify the pinning/refusal behavior and mention the plain-ref backward-compatibility fallback.</violation>
</file>

<file name=".changeset/mobile-ref-generation.md">

<violation number="1" location=".changeset/mobile-ref-generation.md:5">
P2: This release note overstates the guarantee for generation-less agent-devices and for nodes absent from the newest capture. Qualify the generation pinning and say `dragTo` refreshes each node when it can be found, while preserving the stale-ref fallback.</violation>
</file>

Heads up: you’ve reached your flex budget. Increase your flex budget or wait for usage to reset.

View guided diff | Re-trigger cubic

Comment thread packages/mobile/src/surface.ts Resolved
Comment thread docs/reference/mobile.mdx Resolved
Comment thread .changeset/mobile-ref-generation.md Resolved
current() matched a drag end by role, test id, name, and text, then took
the closest candidate, so a source that disappeared between the two
locates could be swapped for an identical sibling. It now takes the
re-found node only at the same rect and otherwise keeps the old pin for
agent-device to refuse as stale.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@okwasniewski okwasniewski left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this. The core fix is right: it carries refsGeneration through project()/bind() and sends @eN~sG, which is what #1406 asked for. I checked it against the vendored agent-device 0.21.31. Plain refs are already refused once a device action expires the ref frame (ref_frame_expired). This PR closes the remaining gap: a newer capture with no action in between. pnpm check and the mobile unit suite (355 tests) pass on da77b8e.

current() is fine as a shape. It uses the identity rule settled() already uses ("found by refind, at the same rect"), so it is not a new heuristic.

Must fix

  1. The main drag case has no test. packages/mobile/tests/unit/engine.test.ts "drags between nodes located in separate captures" runs with the default transition, so settled() already re-captures the source, and the destination's current() is the only one doing work. If I replace const source = this.current(target) with const source = target (surface.ts:1316), all 4 new tests still pass. But this is the normal case in a test: the source is not in transition, so settled() returns it bound to the older capture. Please add the same drag with harness({ transition: 0 }), expecting { source: '@e4~s8', destination: '@e3~s8' }. I ran that as a scratch test: it passes on your branch and fails with the mutation above.
  2. current() (surface.ts:1153-1158): when the node is gone or has moved, don't send a ref we already know agent-device will refuse. Throw new EngineError('NODE_STALE', ..., { retryable: true }) directly. That saves a device round-trip, and it matches what #1300 (Ready, merges first) does in relocated() for the same "no longer listed" case. The JSDoc ("else as it was, for agent-device to refuse as stale") then goes away.
  3. Rebase on #1300. It conflicts textually in relocated() (surface.ts:1220-1225), since both of you rewrite its return line. After #1300, relocated() throws when nothing is found, so your version only needs raw.refsGeneration on the bind.

Nits

  1. Simpler state: latestIndex and latestGeneration (surface.ts:427-429, 1001-1002) are two parallel fields that must always be set together. bind() also takes the generation as a separate argument at 3 call sites, next to projected.index. Put refsGeneration on ProjectedSnapshot (nodes.ts:32, set in project()), keep one latest projection, and have bind(entry, projected) read it from there. That removes the extra field and argument, and it is also the shape #1297 moves bind() to (it takes a ProjectedScreen), so the two PRs will rebase into each other more easily.
  2. current() and the settled() early return (surface.ts:1205-1208) both do "refind, then sameRect". A small samePlace(entry, index) helper used by both keeps them from drifting apart.
  3. relocated() binding with raw.refsGeneration is untested: binding with undefined there passes every test. One assertion on a tap after a transition ('@e4~s8') covers it.
  4. Docs and changeset: per our docs rules, leave out the wire format (@e4~s7) and the NODE_STALE mechanics, and say what users see: an action on a node that a newer snapshot replaced finds it again instead of acting on a different element. "A dragTo sends both nodes from the newest snapshot" is not always true: a moved node is retried, not sent.

On cubic's points: the undefined === undefined P1 is real in principle, but it only affects a daemon that reports no generation, which then behaves as it does on main. agent-device has reported refsGeneration since at least 0.19, and mobile, limrun and testmu all pin 0.21.31. So there is nothing to fix there beyond leaving out the generation-less wording per nit 7. The two P2s (docs and changeset overstate) are covered by nit 7.

Overlap: #1410 also edits settled()/relocated() in surface.ts; it will need raw.refsGeneration on its bind after this lands.

This was an automated review.

Review follow-up. current() now throws a retryable NODE_STALE when a drag
end is gone or moved, instead of sending a ref agent-device will refuse.
refsGeneration lives on ProjectedSnapshot, so one latest projection
replaces the two parallel fields and bind() reads it from the projection.
samePlace() holds the refind-at-the-same-rect rule current() and
settled() share. Tests cover the drag with no transition, a tap found
again after a transition, and a vanished source. Docs and changeset say
what users see.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 5 files (changes from recent commits).

Heads up: you’ve reached your flex budget. Increase your flex budget or wait for usage to reset.

Requires human review: Auto-approval blocked because this review re-detected 2 unresolved issues already reported by Cubic.

View guided diff | Re-trigger cubic

Both tests relied on setup finishing inside the 500 ms transition budget,
so a slow worker could skip the re-capture and fail them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@samanyudas

Copy link
Copy Markdown
Contributor Author

Thanks for the careful review. All points except the rebase are in 8aa5753: the transition: 0 drag test, current() now throws a retryable NODE_STALE before sending, refsGeneration lives on ProjectedSnapshot with one latest field, a shared samePlace() helper, a relocated() test pinned to @e4~s8, and the docs/changeset reworded to what users see. #1300 is still open, so I haven't rebased yet. Once it lands I'll merge main in and resolve the relocated() conflict, which should be small since I reverted relocated() to its original shape. Written with help from an AI agent.

@okwasniewski

Copy link
Copy Markdown
Member

Thanks, this round covers everything. I checked each earlier ask at 422bdb1:

  1. Drag test with transition: 0: done. If I send the source unchanged (const source = target), "drags between nodes located in separate captures from the newest one" fails, as it should.
  2. current() throws a retryable NODE_STALE before sending: done (surface.ts:1147-1155). If I put the old "send it anyway" return back, the "refuses a drag ... before sending it" test fails.
  3. Rebase on fix(mobile): reject stale refs after transition refresh #1300: not yet. That is expected, since fix(mobile): reject stale refs after transition refresh #1300 is still open. Your plan is right. In a test merge onto fix(mobile): reject stale refs after transition refresh #1300's head, the only conflict is the relocated() return line. Keep fix(mobile): reject stale refs after transition refresh #1300's throw and use this.bind(found, projected). fix(mobile): reobserve targets after keyboard transitions #1297 also edits bind()/surface.ts, so expect one more small conflict depending on which lands first.
  4. refsGeneration on ProjectedSnapshot, one latest field, bind(entry, projected): done.
  5. samePlace() shared by current() and settled(): done.
  6. relocated() generation test: done. If I bind there without a generation, "pins a control found again after a transition..." fails.
  7. Docs and changeset now describe what users see: done. This also covers cubic's two P2s.

pnpm check and the mobile unit suite (357 tests) pass on this head.

Nits

  1. After the rebase, update the relocated() JSDoc (surface.ts:1219, "the binding as it was when the snapshot no longer lists it"), because fix(mobile): reject stale refs after transition refresh #1300 makes that case throw.

CI: test (24.8.0) was cancelled at the job timeout after the mobile tests had passed, and spec gate fails only because of that cancellation. Every other Node version passes, and so do iOS and Android deterministic. Looks unrelated; I re-ran it.

This was an automated review.

@okwasniewski
okwasniewski dismissed their stale review October 27, 2026 22:14

Addressed, see latest automated review.

# Conflicts:
#	packages/mobile/src/surface.ts
@github-actions github-actions Bot added size:M Up to 99 changed lines, not counting tests, fixtures, or the lockfile and removed Ready for Human Review labels Oct 28, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Ready for Human Review size:M Up to 99 changed lines, not counting tests, fixtures, or the lockfile

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Mobile taps omit the snapshot version from control references

2 participants