iOS simulator driver: Go-native companion-backed backend (#62)

* perf(ios): use prebuilt XCTest runner to cut startup

* chore(ioscompanion): add companion asset prepare script

* feat(ioscompanion): embed and extract simulator companion bundle

* test(ioscompanion): cover companion stub and embedded extraction

* docs: add third party notices for vendored companion

* chore: ignore vendored companion bundle artifact

* build(proto): pin simulator companion proto v1.1.8

* build(proto): add dedicated buf module and gen template for pinned proto

* build(proto): exclude pinned companion proto from root buf workspace

* feat(ioscompanion): commit generated companion gRPC stubs

* feat(ioscompanion): map flat companion describe dump to TreeNode JSON

* test(ioscompanion): add hierarchy-map golden and unit tests

* feat(ioscompanion): port screen-settle stability polling to Go

* test(ioscompanion): cover settle transitional, hash, streak, and cap rules

* feat(ioscompanion): add USB HID keymap module

* test(ioscompanion): cover keymap branches and paste-chord constants

* build: embed companion assets via withcompanion tag

* feat(ioscompanion): add transport companion interface

* feat(ioscompanion): add HID event wrapper and builders

* feat(ioscompanion): wire gRPC companion client and Dial

* test(ioscompanion): cover HID builders and unit conversions

* test(ioscompanion): cover Dial, process-state mapping, and install archive

* test(ioscompanion): add gated simulator integration smoke test

* feat(ioscompanion): text input and gesture HID composition with pasteboard fallback

* test(ioscompanion): cover input composers, paste dialog loop, and pure helpers

* feat(ioscompanion): add Describe to companion transport

* feat(ioscompanion): implement DeviceDriver with companion supervision

* test(ioscompanion): unit tests with fake companion transport

* test(ioscompanion): gated companion smoke test

* feat(ios): add ResolveTarget for simulator vs physical-device routing

* feat(testrun): route iOS simulators through the native companion driver

* refactor(testrun): defer the java preflight check to the physical-device path

* feat(cli): add --ios-app-path flag

* feat(doctor): split iOS checks into simulator and physical-device paths

* test(folio): add gate-analyzer fixtures for G1-G5

* feat(folio): add iOS conformance gate script

* chore(folio): wire gates recipe, app path, and ignore gate output

* style: gofmt struct alignment drift

* fix(doctor): probe simctl via xcrun instead of PATH lookup

* fix(ioscompanion): spawn companion under driver-lifetime context

* test(ioscompanion): prove companion child outlives startup context

* fix(ioscompanion): chunk install payload under companion message cap

* test(ioscompanion): cover install payload chunking

* fix(ioscompanion): reinstall via simctl and sanitize companion env

* fix(ioscompanion): wait out unresolved accessibility values after launch

* perf(ioscompanion): paste long text for atomic landing

* test(ioscompanion): cover paste threshold, retry flow, and sentinel detection

* fix(ioscompanion): treat unresolved bridge values as transitional, never as content

* fix(ioscompanion): accept masked secure-field values as paste landing

* test(ioscompanion): cover sentinel mapping and masked-field landing

* fix(ioscompanion): atomic erase and single-send paste to prevent doubling

* test(ioscompanion): cover atomic erase, single chord, unverifiable field

* fix(ioscompanion): verify paste on a time budget that outlasts the bridge blackout

* test(ioscompanion): cover bridge-blackout paste verification

* fix(ioscompanion): drop unresolved-value settle gate that never let empty-field screens settle

* refactor(ioscompanion): name the empty-editable-field sentinel for what it is

* perf(ioscompanion): tighten settle streak for the fast companion transport

* feat(ioscompanion): pre-grant pasteboard access so unicode input skips the OS prompt

* refactor(ioscompanion): drop paste warm-up now that the grant suppresses the prompt

* test(ioscompanion): cover pasteboard grant on launch, drop warm-up tests

* fix(ioscompanion): retry describe past transient collapsed accessibility dumps

* test(ioscompanion): cover collapsed-dump detection

* perf(ioscompanion): split raw and retrying describe so settle does not double-wait collapses

* perf(ioscompanion): tighten settle now that collapses are handled separately

* fix(ioscompanion): replace field content on input so blackout-skipped erase cannot accumulate text

* test(ioscompanion): cover replace-on-input and TextReplacer capability

* refactor(ioscompanion): neutralize HID events behind the transport seam

* feat(companion): add simulator runner project skeleton

* feat(companion): serve accessibility snapshots over the wire protocol

* feat(companion): synthesize timestamped touch gestures

* feat(companion): type text with replace semantics

* feat(companion): serve the wire protocol from a parked runner

* feat(ioscompanion): add TextEditor capability and unavailable sentinel to the transport seam

* feat(ioscompanion): route text input through a text-editing companion when available

* fix(companion): bind listener by port and source screen size from snapshot

* feat(ioscompanion): add runner companion JSON transport

* test(ioscompanion): cover runner transport protocol mapping

* fix(companion): synthesize gestures synchronously to avoid the async completion crash

* fix(companion): type on the main thread and recover from focus assertions

* fix(companion): keep serving after an automation failure

* refactor(companion): tidy snapshot serialization

* fix(companion): honor sequential tap gaps and survive synthesis exceptions

* feat(ioscompanion): expose native typing with an explicit replace flag

* chore(companion): add runner asset prepare script

* feat(ioscompanion): embed and extract the runner test bundle

* test(ioscompanion): cover runner asset extraction

* build(ioscompanion): commit runner asset archive

* feat(ioscompanion): pair the legacy companion with the in-simulator runner

* test(ioscompanion): cover hybrid routing, paste-grant skip, and port binding

* fix(ioscompanion): reconnect after interrupted runner calls instead of restarting

* fix(ioscompanion): route hybrid lifecycle through the runner and harden restarts

* feat(companion): launch and terminate apps through the automation session

* build(ioscompanion): refresh runner asset with session lifecycle

* fix(ioscompanion): classify connection deadline expiry as caller budget

* fix(companion): capture snapshots on the main thread inside the catch bridge

* build(ioscompanion): refresh runner asset with main-thread snapshots

* perf(ioscompanion): count read spans toward settle and capture snapshots concurrently

* feat(ioscompanion): make the hybrid simulator companion the default

* test(folio): cover runner-session orphans in the gate harness

* test(ioscompanion): pin the child-lifetime test to the legacy path

* fix(ioscompanion): keep mappable text on one HID stream and verify unicode clears

* fix(ioscompanion): pause the clear chord so selection applies before the delete

* fix(companion): prune the keyboard subtree from snapshots

* build(ioscompanion): refresh runner asset without keyboard elements

* fix(ioscompanion): capture the screenshot transport before a recovery can reassign it

* fix(companion): pin the runner listener to loopback

* fix(companion): size the replace delete prefix to cover any focused field

* build(ioscompanion): refresh runner asset with loopback bind and replace fix

* fix(cli): cancel the run context on SIGINT so spawned children are reaped

* fix(testrun): point the device java preflight hint at the ios-device doctor

* fix(folio): word-bound the G2 ERROR scan and drop the dead objc allowlist glob

* test(ioscompanion): cover stopProcess, restart, and failed bring-up supervision

* chore: add test-companion target for the withcompanion-tagged suite

* chore(ioscompanion): stop tracking the runner archive build artifact

* build: produce the runner archive from source like the companion bundle

* refactor(conformance): move the gate harness out of examples/folio

* chore(folio): drop the gate harness wiring from the example app

internal/driver/ioscompanion/settle.go

@@ -0,0 +1,198 @@
+// Package ioscompanion drives an iOS simulator through the native simulator
+// companion. This file ports the screen-settle (stability polling) logic that
+// waits for the on-device UI to stop churning before the runner reads a
+// hierarchy and screenshot pair.
+package ioscompanion
+
+import (
+	"context"
+	"strings"
+	"time"
+
+	"github.com/priyanshujain/sanderling/internal/hierarchy"
+)
+
+// StabilityPollInterval is how long the loop waits between hierarchy probes.
+// The companion answers describe-all in tens of milliseconds, so a tight
+// interval samples transitions promptly without backing the stream up.
+const StabilityPollInterval = 100 * time.Millisecond
+
+// MinStableStreak is how long the tree must stay structurally identical (and
+// non-transitional) before the poll declares settle. Actions whose effect is
+// async (a tap that fires a write which later pops the back stack) leave the
+// UI momentarily stable before the navigation transition fires; requiring an
+// uninterrupted streak means churn that starts during the window resets the
+// clock instead of being missed. The streak is shorter than the JVM sidecar's
+// (which polls a slower, flakier adb hierarchy): the companion's describe is
+// fast and deterministic, so three consecutive identical samples are a solid
+// stability signal, and cross-fade transitions are caught separately by the
+// route-screen transitional check rather than by streak length.
+const MinStableStreak = 300 * time.Millisecond
+
+// StabilityPollCap bounds total time spent polling so a UI that never settles
+// does not block the runner indefinitely. A genuinely still-churning screen
+// hands a transitional snapshot to the next step, which settles it, so the cap
+// trades a slightly stale read for bounded latency rather than dropping work.
+const StabilityPollCap = 1500 * time.Millisecond
+
+// Clock abstracts time so the poll loop can be driven by a fake in tests
+// without sleeping for real.
+type Clock interface {
+	Now() time.Time
+	Sleep(duration time.Duration)
+}
+
+// systemClock is the production Clock backed by the standard library.
+type systemClock struct{}
+
+func (systemClock) Now() time.Time        { return time.Now() }
+func (systemClock) Sleep(d time.Duration) { time.Sleep(d) }
+
+// SystemClock returns a Clock backed by the standard library wall clock.
+func SystemClock() Clock { return systemClock{} }
+
+// PollUntilStable returns once StabilitySnapshot has been non-transitional and
+// equal to itself for an uninterrupted stretch of at least MinStableStreak,
+// capped at StabilityPollCap. fetch returns the current hierarchy tree (nil on
+// fetch failure, treated like a transitional snapshot so the streak resets).
+//
+// The stable stretch is measured from the start of the earliest read in the
+// current run of identical snapshots: a fetch is not instantaneous (a runner
+// snapshot takes a fair fraction of the streak itself), and the UI changing
+// mid-read would change the snapshot, so the read's own duration is evidence
+// of stability. A transitional snapshot, a changed snapshot, or a fetch
+// failure resets the run. The function returns when the stretch reaches
+// MinStableStreak or the cap elapses, and respects context cancellation.
+func PollUntilStable(ctx context.Context, clock Clock, fetch func() *hierarchy.Tree) {
+	deadline := clock.Now().Add(StabilityPollCap)
+	runStart := clock.Now()
+	prior := snapshot(fetch)
+	for clock.Now().Before(deadline) {
+		if ctx.Err() != nil {
+			return
+		}
+		clock.Sleep(StabilityPollInterval)
+		currentStart := clock.Now()
+		current := snapshot(fetch)
+		if prior.valid && current.valid && prior.hash == current.hash {
+			if clock.Now().Sub(runStart) >= MinStableStreak {
+				return
+			}
+		} else {
+			runStart = currentStart
+		}
+		prior = current
+	}
+}
+
+// stableSnapshot is the result of probing a single hierarchy tree. valid is
+// false when the snapshot is transitional (mid route transition) or the fetch
+// failed, both of which must reset the stable streak.
+type stableSnapshot struct {
+	hash  string
+	valid bool
+}
+
+func snapshot(fetch func() *hierarchy.Tree) stableSnapshot {
+	tree := fetch()
+	if tree == nil {
+		return stableSnapshot{}
+	}
+	return StabilitySnapshot(tree)
+}
+
+// StabilitySnapshot probes a hierarchy tree for both structural shape and route
+// transition state. An empty tree is a valid stable snapshot (the blank-tree
+// case in the companion). A tree with more than one route Screen is
+// transitional and reported invalid: a navigation host keeps both source and
+// destination destinations alive during a cross-fade, and a snapshot taken in
+// that window is unreliable because lazy lists in the incoming screen mount
+// over several frames. Otherwise the snapshot carries the structural hash.
+func StabilitySnapshot(tree *hierarchy.Tree) stableSnapshot {
+	if tree == nil || tree.Root == nil {
+		return stableSnapshot{valid: true}
+	}
+	if CountRouteScreens(tree) > 1 {
+		return stableSnapshot{}
+	}
+	return stableSnapshot{hash: StructuralHash(tree), valid: true}
+}
+
+// routeTagKeys are the attribute keys whose value, when it ends with "Screen",
+// marks a node as a route-level destination. Mirrors the companion's set.
+var routeTagKeys = []string{
+	"resource-id", "resourceId", "testTag",
+	"identifier", "accessibilityIdentifier",
+}
+
+// CountRouteScreens counts nodes that carry a route-level destination tag (a
+// route-tag attribute whose value ends with "Screen"). At most one tag is
+// counted per node, matching the companion which breaks on the first match.
+func CountRouteScreens(tree *hierarchy.Tree) int {
+	if tree == nil || tree.Root == nil {
+		return 0
+	}
+	return countRouteScreens(tree.Root)
+}
+
+func countRouteScreens(node *hierarchy.Node) int {
+	count := 0
+	for _, key := range routeTagKeys {
+		value, ok := node.Attributes[key]
+		if !ok {
+			continue
+		}
+		if strings.HasSuffix(value, "Screen") {
+			count++
+			break
+		}
+	}
+	for _, child := range node.Children {
+		count += countRouteScreens(child)
+	}
+	return count
+}
+
+// stableAttributeKeys are the identity attributes folded into the structural
+// hash, in this exact order. The transient bounds attribute is deliberately
+// excluded so a measure pass that shifts pixels without changing what is on
+// screen does not extend the wait; structure (via tree shape) and text are
+// included so a real content or layout-tree change does reset stability.
+var stableAttributeKeys = []string{
+	"resource-id", "resourceId",
+	"class", "className",
+	"content-desc", "contentDescription", "accessibilityText",
+	"text",
+	"testTag", "identifier", "accessibilityIdentifier",
+}
+
+// StructuralHash walks the tree and concatenates only the stable identity
+// attributes (excluding bounds), in tree order, wrapping each node in
+// parentheses so tree shape is encoded. The result is compared by equality, so
+// it is the hash itself rather than a digest of it.
+func StructuralHash(tree *hierarchy.Tree) string {
+	if tree == nil || tree.Root == nil {
+		return ""
+	}
+	var builder strings.Builder
+	walkForStructuralHash(tree.Root, &builder)
+	return builder.String()
+}
+
+func walkForStructuralHash(node *hierarchy.Node, out *strings.Builder) {
+	out.WriteByte('(')
+	for _, key := range stableAttributeKeys {
+		value, ok := node.Attributes[key]
+		if !ok {
+			continue
+		}
+		out.WriteString(key)
+		out.WriteByte(':')
+		out.WriteString(value)
+		out.WriteByte('|')
+	}
+	for _, child := range node.Children {
+		walkForStructuralHash(child, out)
+	}
+	out.WriteByte(')')
+}