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_test.go

@@ -0,0 +1,199 @@
+package ioscompanion
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"github.com/priyanshujain/sanderling/internal/hierarchy"
+)
+
+// fakeClock advances its internal time only when Sleep is called, so the poll
+// loop runs instantly and deterministically without real sleeping.
+type fakeClock struct {
+	now time.Time
+}
+
+func (c *fakeClock) Now() time.Time { return c.now }
+
+func (c *fakeClock) Sleep(d time.Duration) { c.now = c.now.Add(d) }
+
+func mustTree(t *testing.T, json string) *hierarchy.Tree {
+	t.Helper()
+	tree, err := hierarchy.Parse(json)
+	if err != nil {
+		t.Fatalf("parse hierarchy: %v", err)
+	}
+	return tree
+}
+
+// fetcher returns a fetch function yielding trees in sequence; once the
+// sequence is exhausted the last tree repeats forever.
+func fetcher(trees ...*hierarchy.Tree) func() *hierarchy.Tree {
+	index := 0
+	return func() *hierarchy.Tree {
+		tree := trees[index]
+		if index < len(trees)-1 {
+			index++
+		}
+		return tree
+	}
+}
+
+const singleScreenJSON = `{
+  "attributes": {"resource-id": "homeScreen", "text": "Home"},
+  "children": [
+    {"attributes": {"text": "Welcome", "bounds": "[0,0,100,50]"}, "children": []}
+  ]
+}`
+
+// twoScreenJSON carries two route Screens (a navigation cross-fade), which must
+// be treated as transitional.
+const twoScreenJSON = `{
+  "attributes": {"resource-id": "rootView"},
+  "children": [
+    {"attributes": {"testTag": "homeScreen"}, "children": []},
+    {"attributes": {"testTag": "detailScreen"}, "children": []}
+  ]
+}`
+
+func TestCountRouteScreens(t *testing.T) {
+	tests := []struct {
+		name string
+		json string
+		want int
+	}{
+		{"single screen", singleScreenJSON, 1},
+		{"two screens", twoScreenJSON, 2},
+		{"no screens", `{"attributes": {"text": "plain"}, "children": []}`, 0},
+		{
+			"one node only counts once across route keys",
+			`{"attributes": {"resource-id": "fooScreen", "testTag": "barScreen"}, "children": []}`,
+			1,
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			got := CountRouteScreens(mustTree(t, test.json))
+			if got != test.want {
+				t.Fatalf("CountRouteScreens = %d, want %d", got, test.want)
+			}
+		})
+	}
+}
+
+func TestStabilitySnapshotTreatsTwoScreensAsTransitional(t *testing.T) {
+	snap := StabilitySnapshot(mustTree(t, twoScreenJSON))
+	if snap.valid {
+		t.Fatalf("snapshot with two route Screens should be invalid (transitional)")
+	}
+}
+
+func TestStructuralHashIgnoresBoundsButNotTextOrStructure(t *testing.T) {
+	base := `{"attributes": {"text": "Hi", "bounds": "[0,0,10,10]"}, "children": [
+    {"attributes": {"text": "child", "bounds": "[0,0,5,5]"}, "children": []}
+  ]}`
+	boundsShifted := `{"attributes": {"text": "Hi", "bounds": "[5,5,20,20]"}, "children": [
+    {"attributes": {"text": "child", "bounds": "[5,5,9,9]"}, "children": []}
+  ]}`
+	textChanged := `{"attributes": {"text": "Bye", "bounds": "[0,0,10,10]"}, "children": [
+    {"attributes": {"text": "child", "bounds": "[0,0,5,5]"}, "children": []}
+  ]}`
+	structureChanged := `{"attributes": {"text": "Hi", "bounds": "[0,0,10,10]"}, "children": [
+    {"attributes": {"text": "child", "bounds": "[0,0,5,5]"}, "children": []},
+    {"attributes": {"text": "extra"}, "children": []}
+  ]}`
+
+	baseHash := StructuralHash(mustTree(t, base))
+	if got := StructuralHash(mustTree(t, boundsShifted)); got != baseHash {
+		t.Fatalf("bounds-only change must not alter hash:\n base=%q\n shift=%q", baseHash, got)
+	}
+	if got := StructuralHash(mustTree(t, textChanged)); got == baseHash {
+		t.Fatalf("text change must alter hash, both were %q", baseHash)
+	}
+	if got := StructuralHash(mustTree(t, structureChanged)); got == baseHash {
+		t.Fatalf("structure change must alter hash, both were %q", baseHash)
+	}
+}
+
+func TestPollUntilStableTwoScreensNeverStable(t *testing.T) {
+	clock := &fakeClock{now: time.Unix(0, 0)}
+	fetch := fetcher(mustTree(t, twoScreenJSON))
+	start := clock.Now()
+	PollUntilStable(context.Background(), clock, fetch)
+	elapsed := clock.Now().Sub(start)
+	if elapsed < StabilityPollCap {
+		t.Fatalf("a perpetually transitional UI must poll until the cap, elapsed=%v cap=%v", elapsed, StabilityPollCap)
+	}
+}
+
+func TestPollUntilStableReturnsAfterStreak(t *testing.T) {
+	clock := &fakeClock{now: time.Unix(0, 0)}
+	fetch := fetcher(mustTree(t, singleScreenJSON))
+	start := clock.Now()
+	PollUntilStable(context.Background(), clock, fetch)
+	elapsed := clock.Now().Sub(start)
+	// prior is sampled at t0, then equal snapshots accumulate the streak. The
+	// streak starts at the first matching tick and must reach MinStableStreak.
+	if elapsed > StabilityPollCap {
+		t.Fatalf("stable UI must settle before the cap, elapsed=%v", elapsed)
+	}
+	if elapsed < MinStableStreak {
+		t.Fatalf("must observe a full stable streak before returning, elapsed=%v streak=%v", elapsed, MinStableStreak)
+	}
+}
+
+func TestPollUntilStableResetsStreakOnMidStreakChange(t *testing.T) {
+	clock := &fakeClock{now: time.Unix(0, 0)}
+	stable := mustTree(t, singleScreenJSON)
+	churned := mustTree(t, `{"attributes": {"resource-id": "homeScreen", "text": "Loading"}, "children": []}`)
+	// Two stable ticks build part of a streak (250ms, 500ms accumulated since
+	// the streak start at the first match) then a changed tree resets it, after
+	// which a fresh full 750ms streak is required.
+	fetch := fetcher(stable, stable, stable, churned, stable)
+	start := clock.Now()
+	PollUntilStable(context.Background(), clock, fetch)
+	elapsed := clock.Now().Sub(start)
+	// The streak that succeeds begins after the churn, so total elapsed must
+	// exceed a single uninterrupted streak. Without a reset the loop would have
+	// returned far earlier.
+	if elapsed < MinStableStreak+3*StabilityPollInterval {
+		t.Fatalf("mid-streak change must reset and require a fresh streak, elapsed=%v", elapsed)
+	}
+	if elapsed > StabilityPollCap {
+		t.Fatalf("expected settle before cap once a clean streak completes, elapsed=%v", elapsed)
+	}
+}
+
+func TestPollUntilStableCapReturnsWhenNeverStable(t *testing.T) {
+	clock := &fakeClock{now: time.Unix(0, 0)}
+	// Each fetch yields a structurally different tree, so the streak never
+	// grows and only the cap can end the loop.
+	tick := 0
+	fetch := func() *hierarchy.Tree {
+		tick++
+		return mustTree(t, fmt.Sprintf(`{"attributes": {"text": "frame-%d"}, "children": []}`, tick))
+	}
+	start := clock.Now()
+	PollUntilStable(context.Background(), clock, fetch)
+	elapsed := clock.Now().Sub(start)
+	if elapsed < StabilityPollCap {
+		t.Fatalf("never-stable UI must poll up to the cap, elapsed=%v cap=%v", elapsed, StabilityPollCap)
+	}
+	if elapsed > StabilityPollCap+StabilityPollInterval {
+		t.Fatalf("must not overshoot the cap by more than one interval, elapsed=%v", elapsed)
+	}
+}
+
+func TestPollUntilStableHonorsContextCancellation(t *testing.T) {
+	clock := &fakeClock{now: time.Unix(0, 0)}
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	fetch := fetcher(mustTree(t, twoScreenJSON))
+	start := clock.Now()
+	PollUntilStable(ctx, clock, fetch)
+	if elapsed := clock.Now().Sub(start); elapsed > StabilityPollInterval {
+		t.Fatalf("cancelled context must stop the loop promptly, elapsed=%v", elapsed)
+	}
+}