Skip to content

refactor(ios): converge Appium and Limrun acquisition adapters #2195

Description

@thymikee

Parent: #2188

Blocked by: #2191

Outcome

Converge Appium/WebDriver and Limrun iOS snapshots as acquisition adapters for the engine established
by #2191. Both providers must report facts and limitations rather than applying their own snapshot
presentation policy.

This issue should use two independently reviewable PRs, one per provider package. They may run in
parallel from the exact #2191 head and must not share an ad-hoc helper outside the engine interface.

Shared adapter contract

Each provider adapter must:

  • parse/flatten only facts the provider actually supplied;
  • return stage: 'acquired' with producer, acquisition intent, capture hint, raw nodes, viewport
    evidence, target generation when available, typed residue, and truncation;
  • pass projection, interactive-only, depth, and scope to the engine rather than applying post-wire
    provider policy;
  • declare whether acquisition narrowing is complete for each requested intent and option;
  • report missing viewport, provider-pruned hierarchy, depth/node truncation, unavailable hittability,
    and other fidelity loss through typed residue;
  • never synthesize visibility, effective geometry, public depth, scope membership, or hittability.

Regular projection with neither a reported nor deterministically derivable viewport must fail typed;
it may not silently use an infinite viewport or publish an unfolded actionable tree.

Slice A: Appium/WebDriver

  • Add the adapter in the WebDriver provider package behind its existing runtime facet.
  • Remove synthesized WebDriver hittable and any provider-specific presentation/scope branch.
  • Replace ignored snapshot options with the typed engine plan.
  • Characterize supported Appium page-source attributes and disclose missing facts explicitly.
  • Extend provider contract coverage for regular/raw, depth, scope, interactive-only, viewport
    availability, truncation, and unavailable hittability.

Slice B: Limrun

  • Add the adapter in the Limrun provider package behind its existing runtime facet.
  • Flatten the vendor hierarchy without applying snapshot options or presentation semantics.
  • Replace ignored snapshot options and post-wire scope behavior with the typed engine plan.
  • Characterize the provider's actual hierarchy/viewport evidence; do not claim pagination, tenant
    isolation, or facts the SDK does not expose.
  • Extend provider contract coverage for the same projection/options/residue matrix.

Non-goals

  • No provider SDK upgrade unless separately justified by a missing required fact.
  • No Simulator bridge, XCTest runner, daemon routing, public flag, or physical-device change.
  • Do not delete the provider adapters themselves; only their duplicated presentation policy becomes
    prune-ready.
  • Do not alter generic refs, normalization, quality, occlusion, or Android behavior.

Acceptance and evidence

  • Both adapters pass the same engine-interface conformance corpus for facts they declare available.
  • The closest-negative test proves a rectangle plus enabled cannot activate hittability.
  • Regular/raw, depth, scope, and interactive-only behavior is consistent with refactor(ios): build and prove the converged snapshot engine #2191 and bounded by
    declared capability/residue.
  • Missing viewport and truncation produce typed outcomes and response-level disclosure.
  • Provider integration lanes prove no internal apple platform or internal engine facts leak onto
    the public wire.
  • Each PR deletes its own superseded provider-name branches and behavior-only tests after equivalent
    engine-interface coverage exists; do not defer obvious local deletion to the final cleanup issue.
  • Focused package/provider tests and pnpm check:affected --run pass on each exact PR head.

Worker stop conditions

  • Stop if a provider cannot supply enough evidence for regular presentation; report the limitation
    instead of manufacturing facts.
  • Stop if a change requires a public contract or SDK upgrade outside the accepted scope.
  • Do not merge the two provider implementations into one cross-package adapter.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions