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

Merged
SA
18d ago
+144-12

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 #1297/#1410: bindings carry both keyboardVisible and refsGeneration, and current() reads main's latestScreen. Overlaps #1300 only in relocated(): if #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 1a7a331bthis branch
ERROR: Expected values to be strictly equal: + 'Complete' - 'Reopen'✓ taps include the snapshot version
Taps send @e4Taps send @e4~s7
A tap with a ref from an older capture goes throughA 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