refactor(ios): converge Limrun snapshots through engine

[thymikee]

Summary

Completes the Limrun half of the iOS snapshot-engine convergence from #2195. Current main is integrated at db0854802, including the landed Appium/WebDriver implementation from #2224 and the accepted replacement for #2178 in #2228, plus #2229.

The Limrun adapter acquires the full vendor tree once, derives viewport evidence from the tree root with a deviceInfo fallback, preserves Limrun provenance, and lets the shared engine own raw, regular, depth, scope, and interactive projection. Limrun declares the engine as its presentation owner while retaining incomplete acquisition-depth facts.

The presentation boundary is registry-owned: Appium/WebDriver and Limrun are presented by the shared iOS snapshot engine, while the existing daemon fallback remains only for snapshot-state-owned acquired XCTest and legacy no-producer inputs. This preserves the declared publication policy without re-presenting engine-owned sources. The private presentation marker/evidence plumbing is deleted; the private object-identity sidecar remains only for the genuinely shared Android clickability and occlusion facts. No duplicate provider adapter, serialization branch, or new compatibility path was added.

Limrun's missing truncation metadata remains explicit: the shared contract, daemon serializer, CLI result, and client omit truncated when completeness is unknown. Missing or invalid viewport evidence still fails regular presentation with a typed engine reason and a --raw remediation hint.

Refs #2195

Validation

• Integrated current origin/main at db0854802; final pushed head is b042aa5e1.
• The two requested focused regression files passed unchanged: 7/7 tests in snapshot-presentation-transitions.test.ts and snapshot-publication-membership.test.ts.
• Focused snapshot ownership/composition coverage passes 21/21: the Appium owner-boundary canary remains intact, and a real Limrun interactor/runtime now proves the engine-presented tree survives daemon publication while unknown truncation stays absent from daemon and CLI output.
• The final pnpm check:affected --run passed formatting, lint, typecheck, layering, build, package, and integration checks; its parallel Vitest-related lane hit one unrelated hermetic-signal guard failure in session-open-runtime.test.ts (357/358 files and 2,484/2,485 tests passed). The exact test passes in isolation 1/1, confirming host/process contention. GitHub-authoritative device and coverage lanes remain CI-owned.

Tradeoffs and residual risk

The adapter remains provider-specific only where the Limrun SDK shape requires it: tree flattening, viewport extraction, residue warnings, and typed error hints. Presentation, capability ownership, projection, and unknown-truncation behavior are shared with Appium through capture-kit.

Live Limrun device verification was not available in this workspace; the remaining runtime check is pnpm ad snapshot -i --session <configured Limrun iOS session> against a live Limrun iOS instance.

The latest CI size report shows JavaScript raw +2.3 kB, gzip +1.3 kB, npm tarball +591 B, npm unpacked +2.4 kB, and npm clean-installed +2.4 kB; Apple snapshot presentation source is unchanged. The reconciliation reuses the existing engine/registry seam, adds no package-output or serialization branch, and restores only the declaration-owned fallback that the conflict resolution had accidentally bypassed.

The design checkpoint explicitly chose the smallest ownership repair: retain the existing registry-gated snapshot-state path for its declared owner, keep Appium/Limrun on the shared engine, remove the superseded private presentation evidence, and retain the shared clickability/occlusion sidecar required by Android consumers.

Touched files in the PR comparison against main: 17.

This PR remains open and will not be merged by this task.

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	2.58 MB	2.58 MB	+2.9 kB
JS gzip	866.3 kB	867.8 kB	+1.4 kB
npm bundled raw	2.58 MB	2.58 MB	+2.9 kB
npm bundled gzip	866.3 kB	867.8 kB	+1.4 kB
npm tarball	1.02 MB	1.02 MB	+765 B
npm unpacked	3.46 MB	3.46 MB	+2.9 kB
npm clean-installed	3.46 MB	3.46 MB	+2.9 kB

npm unpacked components

Component	Base	Current	Diff
JS / dist source	2.73 MB	2.74 MB	+2.9 kB
Apple runner source/project	544.4 kB	544.4 kB	0 B
Apple snapshot presentation source	33.8 kB	33.8 kB	0 B
macOS helper source	54.8 kB	54.8 kB	0 B
Android helper artifacts	43.3 kB	43.3 kB	0 B
Other package files	46.3 kB	46.3 kB	0 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	28.7 ms	29.1 ms	+0.4 ms
CLI --help	77.9 ms	77.2 ms	-0.7 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
dist/src/ios-snapshot-engine.js	+8 B	+7 B

Top changed packed files

Packed file	Base	Current	Diff
dist/src/snapshot4.js	0 B	6.3 kB	+6.3 kB
dist/src/ios-snapshot-adapter.js	0 B	2.7 kB	+2.7 kB
dist/src/snapshot2.js	5.0 kB	2.6 kB	-2.5 kB
dist/src/snapshot.js	2.6 kB	1.2 kB	-1.4 kB
dist/src/snapshot3.js	6.3 kB	5.0 kB	-1.3 kB
dist/src/device-session.js	10.8 kB	9.7 kB	-1.1 kB
dist/src/client-types.d.ts	56.8 kB	56.9 kB	+89 B
dist/src/ios-snapshot-engine.js	30.4 kB	30.4 kB	+8 B
dist/src/ios-snapshot-planning.js	4.5 kB	4.5 kB	+7 B
dist/src/src3.js	2.9 kB	2.9 kB	+2 B

[thymikee]

Reviewed exact head b5c457b99b0c00098bdb6915c9f47c1227bf2850: BLOCKED.

1. The Limrun adapter already presents through the shared iOS engine, but daemon buildSnapshotState classifies limrun-ios-tree as acquired and applies presentIosInteractiveSnapshot again for interactive snapshots. Current fixtures happen to be idempotent; the production owner is still duplicated. Carry an internal, non-serialized engine-presented result marker through the shared result/daemon boundary, strip it from public output, and add a provider-runtime → daemon regression. Do not add a Limrun-specific skip branch.

2. limrun-ios-tree declares raw traversal narrowing complete, yet elementTree() is always called without depth and the locked SDK exposes no depth parameter. Mark this capability incomplete so the engine owns raw-depth projection; replace the test that currently pins the false narrowing plan.

Residual: truncated: false is asserted without a vendor completeness signal. Attach vendor evidence that the returned tree is uncapped or disclose a typed limitation; absence of an SDK field is not proof of completeness. Focused tests pass, but live Limrun evidence is unavailable and iOS Smoke was still pending.

[thymikee]

Re-reviewed exact head 73d84bf0a1d6b33c3f8529bd0d18f73a74cc3c0d: still BLOCKED. The new delta improves viewport extraction and missing-viewport disclosure only. It does not stop the daemon’s second interactive presentation after Limrun already published through the engine; it does not change Limrun’s false rawTraversal: complete claim despite elementTree() accepting no depth; and it still hard-codes truncated: false without vendor completeness evidence or typed limitation disclosure. The prior required shared engine-presented carrier + provider-runtime/daemon regression, truthful incomplete narrowing capability, and truncation evidence/disclosure all remain.

[thymikee]

Reviewed exact head 0f5c6b9ee9768dda70684bd801a6c8f81628fba6: BLOCKED. The shared engine-presented carrier now prevents the daemon from presenting Limrun results twice, and Limrun correctly declares raw traversal incomplete. However, truncation is still falsely represented at the public boundary: the adapter omits it and records typed unavailable evidence plus a warning, while snapshotCommand converts an absent value to truncated: false and the client repeats the coercion. A real Limrun response therefore still asserts it was not truncated despite the SDK exposing no completeness metadata. Fix this at the shared snapshot contract/serialization boundary: represent known true, known false, and unknown truncation explicitly (or omit truncated when unknown while publishing typed truncation evidence), then add a Limrun → daemon → public-output regression. A warning alongside truncated: false is not sufficient evidence. Exact-head Repo Guards also fails on the inherited stale src/utils zone, so the branch needs a current-main update before it can be green.

[thymikee]

Re-reviewed exact head 771365491881f6f440960aefcfadd41e8aa25223. The earlier substantive issues are resolved: the Limrun tree enters the shared engine once, raw traversal is incomplete, and unknown truncation remains absent end-to-end with response warning disclosure. No additional code finding. This head is still blocked by an attributable Coverage failure: src/__tests__/client.test.ts grew to 1,608 lines (pin 1,592) and src/daemon/handlers/__tests__/snapshot-handler.test.ts grew to 2,191 (pin 2,138). Extract the new cases into focused sibling test modules; do not raise the pins. All other checks, including native smoke, pass and the PR is mergeable. Live Limrun device evidence is still unavailable, and the required cross-vendor pass remains a residual risk because export was not authorized. Leaving ready-for-human off.

[thymikee]

Reviewed new exact head 8906038331ba04baf9d3232a815cdd33e8b709f5. The requested test extraction is topology-correct: focused sibling modules/shared fixtures replaced additions to the two oversized tests, and no pin was raised. Coverage now correctly requires locking in the shrink: lower src/__tests__/client.test.ts from pin 1,592 to its exact 1,554 lines and src/daemon/handlers/__tests__/snapshot-handler.test.ts from pin 2,138 to its exact 2,120 lines. This is required ratchet maintenance after the split, not a workaround. No new code finding. Android Smoke is non-attributable wait_capture_stalled with zero readable captures; iOS Smoke remains in progress. Leaving ready-for-human off until Coverage is green.

[thymikee]

Reviewed exact head 01e0e5c4bc97360d592fc3fbcc571b3d19674111. No remaining code finding. The focused test extraction remains intact and the two ratchet pins now exactly match the shrunken files (1,554 and 2,120); Coverage is green. The sole failing iOS Smoke check is non-attributable: fixture startup produced zero readable captures (wait_capture_stalled) before any Limrun-specific route. Android Smoke and every CI gate pass, and the PR is mergeable. I am leaving ready-for-human off while exact-head CI is red. Residual evidence remains: no live Limrun proof and no authorized cross-vendor pass.

[thymikee]

Current head 01e0e5c4bc97360d592fc3fbcc571b3d19674111 now conflicts with main db08548026423f69eda7084f3f5a6c44bd383f36 after #2224 merged. This is not purely mechanical. Git reports four textual conflicts: packages/contracts/src/client-capture.ts, src/commands/capture/runtime/snapshot.ts, src/core/snapshot-state.ts, and src/daemon/result-serialization.ts; the other both-modified files auto-merge and the extracted-test pins remain exact. Resolve onto #2224’s registry-owned design: set limrun-ios-tree.presentationOwner to ios-snapshot-engine, keep the centralized owner guard and snapshotTruncationForResult, remove #2222’s now-redundant private presentation-marker path, update the Limrun core test that still asserts legacy daemon presentation, and retain the provider-runtime → daemon/public-output regression. Preserve optional truncated and omit it when unknown in the contract/serializer conflicts. Taking main unchanged would restore double presentation and false truncated: false. No additional code finding beyond this rebase/ownership blocker.

[thymikee]

Reviewed exact head 61ad13eb9454bccd75087890ab32439eabe8685a: BLOCKED.

1. The required Limrun provider-to-daemon regression still stops before the provider adapter. snapshot-truncation.test.ts mocks captureSnapshotWithInteractor, directly returns a synthetic Limrun-shaped result, and configures a provider runtime whose getInteractor returns undefined. This proves only daemon/public omission, not the actual Limrun adapter → shared engine → daemon composition. Retain the direct adapter tests, but add/replace with a fixture Limrun interactor/runtime that proves engine presentation is not reapplied and unknown truncated remains absent through CLI output.

2. The conflict resolution removed refactor(ios): route Appium snapshots through engine #2224's separate Appium presentation-owner regression together with the stale Limrun legacy test. The remaining Appium hittability case does not lock preservation of the already-engine-presented CollectionView → Cell → Button hierarchy. Restore a focused Appium owner-boundary test; delete/rewrite only the stale Limrun case.

The registry ownership and optional-truncation resolution are otherwise correct. iOS Smoke is non-attributable RUNNER_BUSY during deep-link alert handling after an earlier watchdog-exceeded accessibility command; all other checks pass. Leave ready-for-human off. Live Limrun proof and the unauthorized cross-vendor pass remain residual evidence gaps.

[thymikee]

Reviewed exact head b042aa5e1c8aef241e1870623fda20c1fabf1c1b. Both prior regression blockers are resolved with no production workaround: the Appium presentation-owner hierarchy canary is restored, and the Limrun test now allocates the real fixture runtime, resolves the real interactor/adapter and shared engine, then proves the daemon/CLI preserve the already-presented tree while omitting unknown truncated. No remaining code finding.

Exact-head CI is not green: Android Smoke failed outside this Limrun-only delta while waiting for Alert result: cancelled after 11 readable captures; the surface remained on the automation screen. Coverage, Repo Guards, and all other completed gates pass; iOS Smoke is still running. Keep ready-for-human off because CI is red. Live Limrun proof and the unauthorized cross-vendor pass remain residual evidence gaps.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-09-02 08:15 UTC