Merge remote-tracking branch 'origin/main' into garrytan/cairo-v3

# Conflicts:
#	CHANGELOG.md
#	VERSION
#	package.json

test/fixtures/ios-qa/FixtureApp/.gitignore

@@ -0,0 +1,8 @@
+.build/
+.swiftpm/
+DerivedData/
+*.xcodeproj/
+*.xcworkspace/
+Package.resolved
+*.xcodeproj/xcuserdata/
+*.xcodeproj/project.xcworkspace/xcuserdata/

test/fixtures/ios-qa/FixtureApp/Package.swift

@@ -0,0 +1,53 @@
+// swift-tools-version:5.9
+// Test fixture: minimal SwiftUI app + DebugBridge SPM package.
+// DebugBridgeCore (Foundation+Network) builds cross-platform.
+// DebugBridgeUI (UIKit/SwiftUI) is iOS-only.
+// DebugBridgeTouch (Objective-C) is iOS-only — in-process tap synthesis
+// derived from KIF (MIT). DEBUG-only.
+
+import PackageDescription
+
+let package = Package(
+    name: "FixtureApp",
+    platforms: [
+        .iOS(.v16),
+        .macOS(.v13),
+    ],
+    products: [
+        .library(name: "DebugBridgeCore", targets: ["DebugBridgeCore"]),
+        .library(name: "DebugBridgeUI", targets: ["DebugBridgeUI"]),
+        .library(name: "DebugBridgeTouch", targets: ["DebugBridgeTouch"]),
+    ],
+    targets: [
+        .target(
+            name: "DebugBridgeCore",
+            dependencies: [],
+            path: "Sources/DebugBridgeCore",
+            swiftSettings: [
+                .define("DEBUG", .when(configuration: .debug)),
+            ]
+        ),
+        .target(
+            name: "DebugBridgeTouch",
+            dependencies: [],
+            path: "Sources/DebugBridgeTouch",
+            publicHeadersPath: "include",
+            linkerSettings: [
+                .linkedFramework("UIKit", .when(platforms: [.iOS])),
+            ]
+        ),
+        .target(
+            name: "DebugBridgeUI",
+            dependencies: ["DebugBridgeCore", "DebugBridgeTouch"],
+            path: "Sources/DebugBridgeUI",
+            swiftSettings: [
+                .define("DEBUG", .when(configuration: .debug)),
+            ]
+        ),
+        .testTarget(
+            name: "DebugBridgeCoreTests",
+            dependencies: ["DebugBridgeCore"],
+            path: "Tests/DebugBridgeCoreTests"
+        ),
+    ]
+)

test/fixtures/ios-qa/FixtureApp/Sources/DebugBridgeCore/DebugBridgeManager.swift

@@ -0,0 +1,49 @@
+// AUTO-GENERATED from gstack/ios-qa/templates/DebugBridgeManager.swift.template
+//
+// Bootstraps StateServer on app launch. Lives in DebugBridgeCore (no UIKit
+// dependency). The DebugOverlay install is wired separately by the consuming
+// app — it lives in DebugBridgeUI which depends on DebugBridgeCore (not the
+// other way around). Everything is #if DEBUG-gated; this file does not exist
+// in Release builds.
+
+#if DEBUG
+
+import Foundation
+
+@MainActor
+public final class DebugBridgeManager {
+    public static let shared = DebugBridgeManager()
+
+    public func start(appState: AppState) {
+        // 1. Register the canonical AppState struct + accessor wiring.
+        //    AppStateAccessor.register(_:) is generated by gen-accessors-tool.
+        AppStateAccessor.register(appState)
+
+        // 2. Boot the StateServer.
+        StateServer.shared.start()
+
+        // 3. The consuming app installs DebugOverlayWindow separately. See
+        //    the example in DebugBridgeWiring.swift.template:
+        //
+        //      #if canImport(UIKit)
+        //      DebugOverlayWindow.shared.install(recording: recording)
+        //      #endif
+    }
+}
+
+// Placeholder. gen-accessors-tool emits the real `AppStateAccessor` enum next
+// to the app's canonical state struct. Apps that haven't run codegen get a
+// stub that registers no accessors (snapshot is empty, restore returns
+// missing-key for every key).
+@MainActor
+public enum AppStateAccessor {
+    public static var register: (Any) -> Void = { _ in }
+}
+
+// Apps declare their canonical state struct; codegen reads it and emits
+// AppStateAccessor.register. The app's struct must be `@Observable` and
+// must hold all snapshot-eligible state in `@Snapshotable`-marked fields.
+@MainActor
+public protocol AppState: AnyObject {}
+
+#endif // DEBUG

test/fixtures/ios-qa/FixtureApp/Sources/DebugBridgeCore/StateServer.swift

@@ -0,0 +1,569 @@
+// AUTO-GENERATED from gstack/ios-qa/templates/StateServer.swift.template
+// Regenerate with: /ios-sync
+//
+// StateServer — HTTP server embedded in the iOS app under test. Loopback-only.
+// All tailnet ingress is the responsibility of the Mac-side daemon.
+//
+// Threat model: this surface is reachable from the local Mac via the CoreDevice
+// IPv6 tunnel. It MUST refuse any caller without a current bearer token. The
+// boot token is rotated within ~5 seconds of daemon spawn so anything scraping
+// os_log past that window sees a dead credential.
+
+import Foundation
+import Network
+import os.log
+
+#if DEBUG
+
+public typealias JSONDict = [String: Any]
+
+@MainActor
+public final class StateServer {
+    // MARK: Public surface
+
+    public static let shared = StateServer()
+
+    // MARK: Configuration
+
+    private let logger = Logger(subsystem: "gstack.ios-qa", category: "StateServer")
+    private let port: UInt16
+    private let bootTokenPath: String
+
+    // Two listeners for dual-stack loopback. The fork's single-listener IPv6-only
+    // binding was caught in eng + outside-voice review as incomplete.
+    private var ipv6Listener: NWListener?
+    private var ipv4Listener: NWListener?
+
+    // Auth state. The boot token is what we wrote to os_log on first launch.
+    // It exists ONLY long enough for the daemon to call /auth/rotate.
+    private var bootToken: String
+    private var rotatedToken: String?  // set after first /auth/rotate
+    private var bootTokenValid: Bool = true
+
+    // MARK: Session lock (per-device, sliding window on mutations only)
+
+    private struct Session {
+        let id: String
+        var lastMutationAt: Date
+    }
+    private var activeSession: Session?
+    private let sessionTtlSeconds: TimeInterval = 300  // 5 min orphan timeout
+
+    // MARK: Accessor registry (populated by codegen)
+
+    public typealias ReadHandler = () -> Any?
+    public typealias WriteHandler = (Any) -> Bool
+    public typealias TypeName = String
+
+    private var readHandlers: [String: ReadHandler] = [:]
+    private var writeHandlers: [String: WriteHandler] = [:]
+    private var typeNames: [String: TypeName] = [:]
+
+    // Atomic-restore hook. Codegen wires this to the canonical AppState struct.
+    // Restore replaces the entire struct in one assignment so SwiftUI's Combine
+    // pipeline observes exactly one change notification — true observable
+    // atomicity. @MainActor alone doesn't guarantee that.
+    public typealias AtomicRestoreFn = (JSONDict) -> RestoreResult
+    public enum RestoreResult {
+        case ok
+        case missingKey(String)
+        case typeMismatch(String)
+        case schemaMismatch(expected: String, got: String)
+    }
+    private var atomicRestore: AtomicRestoreFn?
+
+    // Snapshot schema hash — written by codegen, stable across builds with
+    // identical accessor signatures.
+    private var accessorHash: String = "uninitialized"
+    private var appBuildId: String = "uninitialized"
+
+    // Agent identity for the DebugOverlay attribution chip. Display-only,
+    // never used for auth.
+    public private(set) var lastAgentIdentity: String = "Claude Code (local)"
+
+    // MARK: Lifecycle
+
+    private init(port: UInt16 = 9999) {
+        self.port = port
+        self.bootToken = UUID().uuidString
+        self.bootTokenPath = NSTemporaryDirectory() + "gstack-ios-qa.token"
+    }
+
+    public func start() {
+        // 1. Persist boot token to a 0600 file (best-effort fallback for the
+        //    daemon if os_log scrape misses).
+        try? bootToken.write(toFile: bootTokenPath, atomically: true, encoding: .utf8)
+        try? FileManager.default.setAttributes([.posixPermissions: 0o600], ofItemAtPath: bootTokenPath)
+
+        // 2. Log the boot token EXACTLY ONCE so the daemon can scrape it.
+        //    The daemon will rotate immediately; this log line is dead within
+        //    seconds.
+        logger.notice("gstack-ios-qa-bootstrap token=\(self.bootToken, privacy: .public) port=\(self.port, privacy: .public) build=\(self.appBuildId, privacy: .public)")
+
+        // 3. Bind both IPv6 and IPv4 loopback. CoreDevice tunnel uses IPv6;
+        //    local tooling may use IPv4. Never bind 0.0.0.0 or ::.
+        startListener(family: .ipv6)
+        startListener(family: .ipv4)
+    }
+
+    public func register(buildId: String, accessorHash: String, atomicRestore: @escaping AtomicRestoreFn) {
+        self.appBuildId = buildId
+        self.accessorHash = accessorHash
+        self.atomicRestore = atomicRestore
+    }
+
+    public func registerAccessor(key: String, type: String, read: @escaping ReadHandler, write: @escaping WriteHandler) {
+        readHandlers[key] = read
+        writeHandlers[key] = write
+        typeNames[key] = type
+    }
+
+    // MARK: Listener setup
+
+    private enum AddressFamily {
+        case ipv4
+        case ipv6
+
+        var host: NWEndpoint.Host {
+            switch self {
+            case .ipv4: return NWEndpoint.Host("127.0.0.1")
+            case .ipv6: return NWEndpoint.Host("::1")
+            }
+        }
+    }
+
+    private func startListener(family: AddressFamily) {
+        do {
+            // Binding strategy: accept connections from the device's loopback
+            // AND from the CoreDevice tunnel (the USB-mounted tunnel the Mac
+            // daemon uses to reach this app — appears as a non-loopback
+            // utun-style interface on the device with the peer's source
+            // address in the fd*/fc* ULA range). We can't use
+            // params.acceptLocalOnly — Network.framework's definition of
+            // "local" is strictly loopback and silently drops CoreDevice
+            // tunnel peers. Instead we accept on the wildcard interface and
+            // do a per-connection peer-address check below: loopback OR
+            // RFC 4193 ULA (fc00::/7) → accept, everything else → cancel.
+            let params = NWParameters.tcp
+            params.allowLocalEndpointReuse = true
+
+            let listener = try NWListener(using: params, on: NWEndpoint.Port(rawValue: port)!)
+            listener.stateUpdateHandler = { [weak self] state in
+                Task { @MainActor in
+                    if case .ready = state {
+                        self?.logger.notice("StateServer listening on \(String(describing: family))")
+                    } else if case .failed(let err) = state {
+                        self?.logger.error("StateServer listener failed: \(err.localizedDescription, privacy: .public)")
+                    }
+                }
+            }
+            listener.newConnectionHandler = { [weak self] connection in
+                Task { @MainActor in
+                    // Defense-in-depth: even with .loopback interface gate, double-check
+                    // the peer is loopback. Reject otherwise.
+                    if let self, self.isLoopbackPeer(connection) {
+                        self.handle(connection)
+                    } else {
+                        connection.cancel()
+                    }
+                }
+            }
+            listener.start(queue: .global(qos: .userInitiated))
+
+            switch family {
+            case .ipv6: ipv6Listener = listener
+            case .ipv4: ipv4Listener = listener
+            }
+        } catch {
+            logger.error("Listener bind failed (\(String(describing: family))): \(error.localizedDescription, privacy: .public)")
+        }
+    }
+
+    private func isLoopbackPeer(_ connection: NWConnection) -> Bool {
+        switch connection.endpoint {
+        case .hostPort(let host, _):
+            switch host {
+            case .ipv4(let addr):
+                return addr == .loopback
+            case .ipv6(let addr):
+                // Loopback (::1) — local same-device traffic
+                if addr.isLoopback { return true }
+                // CoreDevice ULA range (fd00::/8 unique-local addresses) —
+                // the USB tunnel that the Mac daemon uses to reach this app.
+                // Apple's CoreDevice tunnel uses fd-prefixed ULAs like
+                // fd72:8347:2ead::1 (Mac-facing) and fd72:8347:2ead::2
+                // (device-facing). We accept the entire ULA range since
+                // the prefix is regenerated per session.
+                let bytes = addr.rawValue
+                if bytes.count >= 1 && (bytes[0] & 0xFE) == 0xFC {
+                    // RFC 4193 ULA range (fc00::/7) — fc* or fd* prefix.
+                    return true
+                }
+                return false
+            case .name(let name, _):
+                return name == "localhost"
+            @unknown default: return false
+            }
+        default: return false
+        }
+    }
+
+    // MARK: Request handling
+
+    private func handle(_ connection: NWConnection) {
+        connection.start(queue: .global(qos: .userInitiated))
+        receive(connection: connection, buffer: Data())
+    }
+
+    private static let maxBodyBytes = 1_048_576  // 1MB hard cap
+
+    private func receive(connection: NWConnection, buffer: Data) {
+        connection.receive(minimumIncompleteLength: 1, maximumLength: 65_536) { [weak self] data, _, isComplete, error in
+            guard let self else { return }
+            Task { @MainActor in
+                var current = buffer
+                if let data = data { current.append(data) }
+                if current.count > Self.maxBodyBytes {
+                    self.send(connection: connection, status: 413, body: ["error": "body_too_large"])
+                    return
+                }
+                if let req = self.tryParseRequest(current) {
+                    self.route(connection: connection, request: req)
+                } else if isComplete || error != nil {
+                    self.send(connection: connection, status: 400, body: ["error": "bad_request"])
+                } else {
+                    self.receive(connection: connection, buffer: current)
+                }
+            }
+        }
+    }
+
+    struct ParsedRequest {
+        let method: String
+        let path: String
+        let headers: [String: String]
+        let body: Data
+    }
+
+    private func tryParseRequest(_ data: Data) -> ParsedRequest? {
+        guard let headerEnd = data.range(of: Data("\r\n\r\n".utf8)) else { return nil }
+        let headerData = data.subdata(in: 0..<headerEnd.lowerBound)
+        let body = data.subdata(in: headerEnd.upperBound..<data.count)
+        guard let headerStr = String(data: headerData, encoding: .utf8) else { return nil }
+        let lines = headerStr.components(separatedBy: "\r\n")
+        guard let requestLine = lines.first else { return nil }
+        let parts = requestLine.components(separatedBy: " ")
+        guard parts.count >= 2 else { return nil }
+
+        var headers: [String: String] = [:]
+        for line in lines.dropFirst() {
+            guard let colon = line.firstIndex(of: ":") else { continue }
+            let key = String(line[..<colon]).lowercased()
+            let value = line[line.index(after: colon)...].trimmingCharacters(in: .whitespaces)
+            headers[key] = value
+        }
+
+        if let lenStr = headers["content-length"], let len = Int(lenStr), body.count < len {
+            return nil  // need more bytes
+        }
+        return ParsedRequest(method: parts[0], path: parts[1], headers: headers, body: body)
+    }
+
+    private func route(connection: NWConnection, request: ParsedRequest) {
+        // Update display attribution from header (display only — never trusted
+        // for auth).
+        if let agent = request.headers["x-agent-identity"], !agent.isEmpty, agent.count < 200 {
+            lastAgentIdentity = agent
+        }
+
+        let path = request.path
+
+        // 1. Public on loopback: /healthz.
+        if request.method == "GET" && path == "/healthz" {
+            send(connection: connection, status: 200, body: [
+                "version": "1.0.0",
+                "build": appBuildId,
+                "accessor_hash": accessorHash,
+            ])
+            return
+        }
+
+        // 2. Auth bootstrap: /auth/rotate is the ONLY endpoint that accepts the
+        //    boot token. Everything else requires the rotated token.
+        if request.method == "POST" && path == "/auth/rotate" {
+            handleAuthRotate(connection: connection, request: request)
+            return
+        }
+
+        // 3. All other endpoints require Bearer auth with the rotated token.
+        guard authorize(request: request) else {
+            send(connection: connection, status: 401, body: ["error": "unauthorized"])
+            return
+        }
+
+        switch (request.method, path) {
+        case ("POST", "/session/acquire"): handleSessionAcquire(connection: connection)
+        case ("POST", "/session/release"): handleSessionRelease(connection: connection)
+        case ("POST", "/session/heartbeat"): handleSessionHeartbeat(connection: connection, request: request)
+        case ("GET", "/state/snapshot"): handleSnapshotGet(connection: connection)
+        case ("POST", "/state/restore"): handleSnapshotRestore(connection: connection, request: request)
+        case ("GET", "/elements"): handleElements(connection: connection)
+        case ("GET", "/screenshot"): handleScreenshot(connection: connection)
+        case ("POST", "/tap"): handleMutation(connection: connection, request: request, op: "tap")
+        case ("POST", "/swipe"): handleMutation(connection: connection, request: request, op: "swipe")
+        case ("POST", "/type"): handleMutation(connection: connection, request: request, op: "type")
+        case ("GET", let p) where p.hasPrefix("/state/"):
+            let key = String(p.dropFirst("/state/".count))
+            handleStateGet(connection: connection, key: key)
+        case ("POST", let p) where p.hasPrefix("/state/"):
+            let key = String(p.dropFirst("/state/".count))
+            handleStateWrite(connection: connection, request: request, key: key)
+        default:
+            send(connection: connection, status: 404, body: ["error": "not_found", "path": path])
+        }
+    }
+
+    // MARK: Auth
+
+    private func authorize(request: ParsedRequest) -> Bool {
+        guard let auth = request.headers["authorization"], auth.hasPrefix("Bearer ") else { return false }
+        let token = String(auth.dropFirst("Bearer ".count))
+        return token == rotatedToken
+    }
+
+    private func handleAuthRotate(connection: NWConnection, request: ParsedRequest) {
+        // Validate boot token (still alive AND used only once).
+        guard bootTokenValid,
+              let auth = request.headers["authorization"],
+              auth.hasPrefix("Bearer "),
+              String(auth.dropFirst("Bearer ".count)) == bootToken else {
+            send(connection: connection, status: 401, body: ["error": "boot_token_invalid"])
+            return
+        }
+
+        guard let dict = try? JSONSerialization.jsonObject(with: request.body) as? JSONDict,
+              let newToken = dict["new_token"] as? String,
+              newToken.count >= 16 else {
+            send(connection: connection, status: 400, body: ["error": "invalid_rotate_payload"])
+            return
+        }
+
+        rotatedToken = newToken
+        bootTokenValid = false
+        // Best-effort scrub of on-disk boot token file.
+        try? FileManager.default.removeItem(atPath: bootTokenPath)
+
+        logger.notice("Boot token rotated; original now invalid")
+        send(connection: connection, status: 200, body: ["ok": true])
+    }
+
+    // MARK: Session lock
+
+    private static let mutatingPaths: Set<String> = ["/tap", "/swipe", "/type", "/state/restore"]
+
+    private func mutatingPathRequiresSession(_ path: String, method: String) -> Bool {
+        if method != "POST" { return false }
+        if path.hasPrefix("/state/") && path != "/state/restore" { return true }  // /state/<key> writes
+        return Self.mutatingPaths.contains(path)
+    }
+
+    private func requireSession(in request: ParsedRequest, connection: NWConnection) -> Bool {
+        guard let id = request.headers["x-session-id"] else {
+            send(connection: connection, status: 409, body: ["error": "session_required"])
+            return false
+        }
+        guard let current = activeSession, current.id == id else {
+            send(connection: connection, status: 409, body: ["error": "session_invalid_or_expired"])
+            return false
+        }
+        // Mutation slides the lock; reads do not.
+        activeSession?.lastMutationAt = Date()
+        return true
+    }
+
+    private func handleSessionAcquire(connection: NWConnection) {
+        // Reap orphaned session.
+        if let s = activeSession, Date().timeIntervalSince(s.lastMutationAt) > sessionTtlSeconds {
+            activeSession = nil
+        }
+        if activeSession != nil {
+            send(connection: connection, status: 423, body: ["error": "device_locked"])
+            return
+        }
+        let id = UUID().uuidString
+        activeSession = Session(id: id, lastMutationAt: Date())
+        send(connection: connection, status: 200, body: [
+            "session_id": id,
+            "ttl_seconds": Int(sessionTtlSeconds),
+        ])
+    }
+
+    private func handleSessionRelease(connection: NWConnection) {
+        activeSession = nil
+        send(connection: connection, status: 200, body: ["ok": true])
+    }
+
+    private func handleSessionHeartbeat(connection: NWConnection, request: ParsedRequest) {
+        guard let id = request.headers["x-session-id"],
+              activeSession?.id == id else {
+            send(connection: connection, status: 409, body: ["error": "session_invalid_or_expired"])
+            return
+        }
+        activeSession?.lastMutationAt = Date()
+        send(connection: connection, status: 200, body: ["ok": true, "ttl_seconds": Int(sessionTtlSeconds)])
+    }
+
+    // MARK: State handlers
+
+    private func handleStateGet(connection: NWConnection, key: String) {
+        guard let handler = readHandlers[key] else {
+            send(connection: connection, status: 404, body: ["error": "unknown_key", "key": key])
+            return
+        }
+        let value = handler() ?? NSNull()
+        send(connection: connection, status: 200, body: ["key": key, "value": value])
+    }
+
+    private func handleStateWrite(connection: NWConnection, request: ParsedRequest, key: String) {
+        guard requireSession(in: request, connection: connection) else { return }
+        guard let handler = writeHandlers[key] else {
+            send(connection: connection, status: 404, body: ["error": "unknown_key", "key": key])
+            return
+        }
+        guard let payload = try? JSONSerialization.jsonObject(with: request.body) as? JSONDict,
+              let value = payload["value"] else {
+            send(connection: connection, status: 400, body: ["error": "missing_value"])
+            return
+        }
+        let ok = handler(value)
+        if ok {
+            send(connection: connection, status: 200, body: ["ok": true])
+        } else {
+            send(connection: connection, status: 400, body: ["error": "type_mismatch", "expected": typeNames[key] ?? "?"])
+        }
+    }
+
+    private func handleSnapshotGet(connection: NWConnection) {
+        var keys: JSONDict = [:]
+        for (k, read) in readHandlers {
+            keys[k] = read() ?? NSNull()
+        }
+        let envelope: JSONDict = [
+            "_schema_version": 1,
+            "_app_build_id": appBuildId,
+            "_accessor_hash": accessorHash,
+            "keys": keys,
+        ]
+        send(connection: connection, status: 200, body: envelope)
+    }
+
+    private func handleSnapshotRestore(connection: NWConnection, request: ParsedRequest) {
+        guard requireSession(in: request, connection: connection) else { return }
+        guard let envelope = try? JSONSerialization.jsonObject(with: request.body) as? JSONDict else {
+            send(connection: connection, status: 400, body: ["error": "invalid_json"])
+            return
+        }
+        // Schema gate.
+        if let hash = envelope["_accessor_hash"] as? String, hash != accessorHash {
+            send(connection: connection, status: 409, body: [
+                "error": "schema_mismatch",
+                "expected_hash": accessorHash,
+                "got_hash": hash,
+            ])
+            return
+        }
+        guard let keys = envelope["keys"] as? JSONDict else {
+            send(connection: connection, status: 400, body: ["error": "missing_keys"])
+            return
+        }
+        guard let restore = atomicRestore else {
+            send(connection: connection, status: 503, body: ["error": "atomic_restore_not_registered"])
+            return
+        }
+        // Validate-then-apply via the codegen-supplied closure. The closure does
+        // a single struct-assignment so SwiftUI sees one change notification.
+        switch restore(keys) {
+        case .ok:
+            send(connection: connection, status: 200, body: ["ok": true])
+        case .missingKey(let k):
+            send(connection: connection, status: 400, body: ["error": "validation_failed", "key": k, "reason": "missing"])
+        case .typeMismatch(let k):
+            send(connection: connection, status: 400, body: ["error": "validation_failed", "key": k, "reason": "type-mismatch"])
+        case .schemaMismatch(let expected, let got):
+            send(connection: connection, status: 409, body: ["error": "schema_mismatch", "expected_hash": expected, "got_hash": got])
+        }
+    }
+
+    // MARK: Stubs (real impls live in DebugBridgeManager + UIKit)
+
+    private func handleElements(connection: NWConnection) {
+        let tree = ElementsBridge.snapshot()
+        send(connection: connection, status: 200, body: ["elements": tree])
+    }
+
+    private func handleScreenshot(connection: NWConnection) {
+        if let png = ScreenshotBridge.capturePNG() {
+            send(connection: connection, status: 200, body: ["png_base64": png.base64EncodedString()])
+        } else {
+            send(connection: connection, status: 500, body: ["error": "screenshot_unavailable"])
+        }
+    }
+
+    private func handleMutation(connection: NWConnection, request: ParsedRequest, op: String) {
+        guard requireSession(in: request, connection: connection) else { return }
+        guard let payload = try? JSONSerialization.jsonObject(with: request.body) as? JSONDict else {
+            send(connection: connection, status: 400, body: ["error": "invalid_json"])
+            return
+        }
+        let ok = MutationBridge.dispatch(op: op, payload: payload)
+        send(connection: connection, status: ok ? 200 : 400, body: ["op": op, "ok": ok])
+    }
+
+    // MARK: Response
+
+    private func send(connection: NWConnection, status: Int, body: JSONDict) {
+        let json = (try? JSONSerialization.data(withJSONObject: body)) ?? Data("{}".utf8)
+        let statusText: String
+        switch status {
+        case 200: statusText = "OK"
+        case 400: statusText = "Bad Request"
+        case 401: statusText = "Unauthorized"
+        case 404: statusText = "Not Found"
+        case 409: statusText = "Conflict"
+        case 413: statusText = "Payload Too Large"
+        case 423: statusText = "Locked"
+        case 429: statusText = "Too Many Requests"
+        case 500: statusText = "Internal Server Error"
+        case 503: statusText = "Service Unavailable"
+        default: statusText = "Status"
+        }
+        let header = "HTTP/1.1 \(status) \(statusText)\r\nContent-Type: application/json\r\nContent-Length: \(json.count)\r\nConnection: close\r\n\r\n"
+        var packet = Data(header.utf8)
+        packet.append(json)
+        connection.send(content: packet, completion: .contentProcessed { _ in
+            connection.cancel()
+        })
+    }
+}
+
+// MARK: - Bridges (implementation provided by DebugBridgeManager)
+
+@MainActor
+public enum ElementsBridge {
+    public static var resolver: () -> [JSONDict] = { [] }
+    static func snapshot() -> [JSONDict] { resolver() }
+}
+
+@MainActor
+public enum ScreenshotBridge {
+    public static var resolver: () -> Data? = { nil }
+    static func capturePNG() -> Data? { resolver() }
+}
+
+@MainActor
+public enum MutationBridge {
+    public static var resolver: (String, JSONDict) -> Bool = { _, _ in false }
+    static func dispatch(op: String, payload: JSONDict) -> Bool { resolver(op, payload) }
+}
+
+#endif // DEBUG

test/fixtures/ios-qa/FixtureApp/Sources/DebugBridgeTouch/DebugBridgeTouch.m

@@ -0,0 +1,301 @@
+//
+//  DebugBridgeTouch.m — minimal port of KIF's in-process touch synthesis.
+//  Original code: https://github.com/kif-framework/KIF — MIT-licensed
+//  (Square, Inc. + KIF contributors). Adapted to a single-file, tap-only,
+//  iOS 18+ aware subset for the gstack/ios-qa DebugBridge.
+//
+//  Uses these private UIKit selectors (DEBUG-only; never shipped to App Store):
+//    UITouch:  _setLocationInWindow:resetPrevious:, _setIsFirstTouchForView:,
+//              setPhase:, setTimestamp:, setView:, setWindow:, setTapCount:,
+//              _setHidEvent:
+//    UIEvent:  _clearTouches, _addTouch:forDelayedDelivery:, _setHIDEvent:
+//    UIApplication: _touchesEvent
+//    UIView:   _hitTestWithContext: (iOS 18+ for SwiftUI hit-testing)
+//    NSObject: _UIHitTestContext contextWithPoint:radius: (iOS 18+)
+//
+//  IOKit private symbols (linked dynamically via the IOKit framework on iOS):
+//    IOHIDEventCreateDigitizerEvent, IOHIDEventCreateDigitizerFingerEventWithQuality,
+//    IOHIDEventSetIntegerValue, IOHIDEventAppendEvent.
+
+#import "DebugBridgeTouch.h"
+#import <TargetConditionals.h>
+
+#if TARGET_OS_IOS
+
+#import <UIKit/UIKit.h>
+#import <objc/runtime.h>
+#import <objc/message.h>
+#import <mach/mach_time.h>
+
+#pragma mark - IOHIDEvent (private symbols from IOKit)
+
+typedef struct __IOHIDEvent * IOHIDEventRef;
+
+#define IOHIDEventFieldBase(type) (type << 16)
+#ifdef __LP64__
+typedef double IOHIDFloat;
+#else
+typedef float IOHIDFloat;
+#endif
+typedef UInt32 IOOptionBits;
+typedef uint32_t IOHIDDigitizerTransducerType;
+typedef uint32_t IOHIDEventField;
+
+enum {
+    kIOHIDDigitizerTransducerTypeStylus = 0,
+    kIOHIDDigitizerTransducerTypePuck,
+    kIOHIDDigitizerTransducerTypeFinger,
+    kIOHIDDigitizerTransducerTypeHand
+};
+
+enum {
+    kIOHIDEventTypeDigitizer = 11,
+};
+
+enum {
+    kIOHIDDigitizerEventRange    = 0x00000001,
+    kIOHIDDigitizerEventTouch    = 0x00000002,
+    kIOHIDDigitizerEventPosition = 0x00000004,
+};
+
+enum {
+    kIOHIDEventFieldDigitizerX = IOHIDEventFieldBase(kIOHIDEventTypeDigitizer),
+    kIOHIDEventFieldDigitizerY,
+    kIOHIDEventFieldDigitizerZ,
+    kIOHIDEventFieldDigitizerButtonMask,
+    kIOHIDEventFieldDigitizerType,
+    kIOHIDEventFieldDigitizerIndex,
+    kIOHIDEventFieldDigitizerIdentity,
+    kIOHIDEventFieldDigitizerEventMask,
+    kIOHIDEventFieldDigitizerRange,
+    kIOHIDEventFieldDigitizerTouch,
+    kIOHIDEventFieldDigitizerPressure,
+    kIOHIDEventFieldDigitizerAuxiliaryPressure,
+    kIOHIDEventFieldDigitizerTwist,
+    kIOHIDEventFieldDigitizerTiltX,
+    kIOHIDEventFieldDigitizerTiltY,
+    kIOHIDEventFieldDigitizerAltitude,
+    kIOHIDEventFieldDigitizerAzimuth,
+    kIOHIDEventFieldDigitizerQuality,
+    kIOHIDEventFieldDigitizerDensity,
+    kIOHIDEventFieldDigitizerIrregularity,
+    kIOHIDEventFieldDigitizerMajorRadius,
+    kIOHIDEventFieldDigitizerMinorRadius,
+    kIOHIDEventFieldDigitizerCollection,
+    kIOHIDEventFieldDigitizerCollectionChord,
+    kIOHIDEventFieldDigitizerChildEventMask,
+    kIOHIDEventFieldDigitizerIsDisplayIntegrated,
+};
+
+// IOKit is a PRIVATE framework on iOS — we can't link it via -framework. Load
+// at runtime via dlopen/dlsym. This is the standard approach for KIF-style
+// touch synthesis on iOS, including in DEBUG-only test harnesses.
+#import <dlfcn.h>
+
+typedef IOHIDEventRef (*IOHIDEventCreateDigitizerEventFn)(CFAllocatorRef, AbsoluteTime,
+    IOHIDDigitizerTransducerType, uint32_t, uint32_t, uint32_t, uint32_t,
+    IOHIDFloat, IOHIDFloat, IOHIDFloat, IOHIDFloat, IOHIDFloat, Boolean, Boolean, IOOptionBits);
+
+typedef IOHIDEventRef (*IOHIDEventCreateDigitizerFingerEventWithQualityFn)(CFAllocatorRef,
+    AbsoluteTime, uint32_t, uint32_t, uint32_t, IOHIDFloat, IOHIDFloat, IOHIDFloat,
+    IOHIDFloat, IOHIDFloat, IOHIDFloat, IOHIDFloat, IOHIDFloat, IOHIDFloat,
+    IOHIDFloat, Boolean, Boolean, IOOptionBits);
+
+typedef void (*IOHIDEventSetIntegerValueFn)(IOHIDEventRef, IOHIDEventField, int);
+typedef void (*IOHIDEventAppendEventFn)(IOHIDEventRef, IOHIDEventRef);
+
+static IOHIDEventCreateDigitizerEventFn _IOHIDEventCreateDigitizerEvent;
+static IOHIDEventCreateDigitizerFingerEventWithQualityFn _IOHIDEventCreateDigitizerFingerEventWithQuality;
+static IOHIDEventSetIntegerValueFn _IOHIDEventSetIntegerValue;
+static IOHIDEventAppendEventFn _IOHIDEventAppendEvent;
+
+static BOOL _IOKitLoaded = NO;
+static BOOL DBT_LoadIOKit(void) {
+    if (_IOKitLoaded) return YES;
+    void *handle = dlopen("/System/Library/Frameworks/IOKit.framework/IOKit", RTLD_NOW);
+    if (!handle) {
+        handle = dlopen("/System/Library/PrivateFrameworks/IOKit.framework/IOKit", RTLD_NOW);
+    }
+    if (!handle) return NO;
+    _IOHIDEventCreateDigitizerEvent = (IOHIDEventCreateDigitizerEventFn)dlsym(handle, "IOHIDEventCreateDigitizerEvent");
+    _IOHIDEventCreateDigitizerFingerEventWithQuality = (IOHIDEventCreateDigitizerFingerEventWithQualityFn)dlsym(handle, "IOHIDEventCreateDigitizerFingerEventWithQuality");
+    _IOHIDEventSetIntegerValue = (IOHIDEventSetIntegerValueFn)dlsym(handle, "IOHIDEventSetIntegerValue");
+    _IOHIDEventAppendEvent = (IOHIDEventAppendEventFn)dlsym(handle, "IOHIDEventAppendEvent");
+    _IOKitLoaded = (_IOHIDEventCreateDigitizerEvent && _IOHIDEventCreateDigitizerFingerEventWithQuality &&
+                    _IOHIDEventSetIntegerValue && _IOHIDEventAppendEvent);
+    return _IOKitLoaded;
+}
+
+static IOHIDEventRef DBT_IOHIDEventWithTouch(UITouch *touch) CF_RETURNS_RETAINED;
+static IOHIDEventRef DBT_IOHIDEventWithTouch(UITouch *touch) {
+    if (!DBT_LoadIOKit()) return NULL;
+    uint64_t abTime = mach_absolute_time();
+    AbsoluteTime timeStamp;
+    timeStamp.hi = (UInt32)(abTime >> 32);
+    timeStamp.lo = (UInt32)(abTime);
+
+    IOHIDEventRef handEvent = _IOHIDEventCreateDigitizerEvent(kCFAllocatorDefault,
+        timeStamp, kIOHIDDigitizerTransducerTypeHand,
+        0, 0, kIOHIDDigitizerEventTouch, 0,
+        0, 0, 0, 0, 0,
+        0, true, 0);
+    _IOHIDEventSetIntegerValue(handEvent, kIOHIDEventFieldDigitizerIsDisplayIntegrated, 1);
+
+    uint32_t eventMask = (touch.phase == UITouchPhaseMoved)
+        ? kIOHIDDigitizerEventPosition
+        : (kIOHIDDigitizerEventRange | kIOHIDDigitizerEventTouch);
+    uint32_t isTouching = (touch.phase == UITouchPhaseEnded) ? 0 : 1;
+
+    CGPoint loc = [touch locationInView:touch.window];
+
+    IOHIDEventRef fingerEvent = _IOHIDEventCreateDigitizerFingerEventWithQuality(kCFAllocatorDefault,
+        timeStamp, 1, 2, eventMask,
+        (IOHIDFloat)loc.x, (IOHIDFloat)loc.y, 0.0,
+        0, 0, 5.0, 5.0, 1.0, 1.0, 1.0,
+        (IOHIDFloat)isTouching, (IOHIDFloat)isTouching, 0);
+    _IOHIDEventSetIntegerValue(fingerEvent, kIOHIDEventFieldDigitizerIsDisplayIntegrated, 1);
+
+    _IOHIDEventAppendEvent(handEvent, fingerEvent);
+    CFRelease(fingerEvent);
+
+    return handEvent;
+}
+
+#pragma mark - Private selectors
+
+@interface UITouch ()
+- (void)setWindow:(UIWindow *)window;
+- (void)setView:(UIView *)view;
+- (void)setTapCount:(NSUInteger)tapCount;
+- (void)setTimestamp:(NSTimeInterval)timestamp;
+- (void)setPhase:(UITouchPhase)touchPhase;
+- (void)setGestureView:(UIView *)view;
+- (void)_setLocationInWindow:(CGPoint)location resetPrevious:(BOOL)resetPrevious;
+- (void)_setIsFirstTouchForView:(BOOL)firstTouchForView;
+- (void)_setHidEvent:(IOHIDEventRef)event;
+@end
+
+@interface UIEvent (DBTPrivate)
+- (void)_clearTouches;
+- (void)_addTouch:(UITouch *)touch forDelayedDelivery:(BOOL)delayed;
+- (void)_setHIDEvent:(IOHIDEventRef)event;
+- (void)_setTimestamp:(NSTimeInterval)timestamp;
+@end
+
+@interface UIApplication (DBTPrivate)
+- (UIEvent *)_touchesEvent;
+@end
+
+@interface UIView (DBTPrivate)
+- (id)_hitTestWithContext:(id)context;
+@end
+
+#pragma mark - SwiftUI-aware hit test (iOS 18+)
+
+// Returns `id` because iOS 18's _hitTestWithContext: can return either a UIView
+// OR a SwiftUI.UIKitGestureContainer (a plain UIResponder, NOT a UIView).
+// The latter is the case for SwiftUI Buttons. KIF's observation: the returned
+// responder is still compatible with UITouch.setView: even when it isn't a
+// UIView — so we pass it through as-is. Filtering by isKindOfClass:UIView
+// here would drop every SwiftUI Button tap silently. Mirrors KIF PR #1323.
+static id DBT_HitTestView(UIWindow *window, CGPoint point) {
+    UIView *fallback = [window hitTest:point withEvent:nil];
+
+    if (@available(iOS 18.0, *)) {
+        Class ctxClass = NSClassFromString(@"_UIHitTestContext");
+        SEL ctxSel = NSSelectorFromString(@"contextWithPoint:radius:");
+        if (ctxClass && [ctxClass respondsToSelector:ctxSel] &&
+            [UIView instancesRespondToSelector:@selector(_hitTestWithContext:)]) {
+            id (*sendCtx)(id, SEL, CGPoint, CGFloat) =
+                (id (*)(id, SEL, CGPoint, CGFloat))objc_msgSend;
+            id ctx = sendCtx(ctxClass, ctxSel, point, 0);
+            if (ctx) {
+                id found = nil;
+                UIView *current = fallback;
+                while (found == nil && current != nil) {
+                    found = [current _hitTestWithContext:ctx];
+                    current = current.superview;
+                }
+                if (found) {
+                    return found;
+                }
+            }
+        }
+    }
+    return fallback;
+}
+
+#pragma mark - Public API
+
+@implementation DebugBridgeTouch
+
++ (BOOL)sendTapAtPoint:(CGPoint)point inWindow:(UIWindow *)window {
+    if (!window) return NO;
+
+    id hit = DBT_HitTestView(window, point);
+    if (!hit) return NO;
+
+    // Build a single synthetic UITouch via private setters. Order matters —
+    // setWindow: clears internal state and must come first.
+    UITouch *touch = [[UITouch alloc] init];
+    [touch setWindow:window];
+    [touch setTapCount:1];
+    [touch _setLocationInWindow:point resetPrevious:YES];
+    // setView: typed UIView * but accepts SwiftUI.UIKitGestureContainer
+    // (UIResponder) too — that's how SwiftUI Buttons get routed on iOS 18+.
+    [touch setView:(UIView *)hit];
+    [touch setPhase:UITouchPhaseBegan];
+    if ([touch respondsToSelector:@selector(_setIsFirstTouchForView:)]) {
+        [touch _setIsFirstTouchForView:YES];
+    }
+    [touch setTimestamp:[[NSProcessInfo processInfo] systemUptime]];
+    if ([touch respondsToSelector:@selector(setGestureView:)] &&
+        [hit isKindOfClass:[UIView class]]) {
+        [touch setGestureView:(UIView *)hit];
+    }
+
+    // Attach a real IOHIDEvent (required iOS 9+).
+    IOHIDEventRef hidEventBegan = DBT_IOHIDEventWithTouch(touch);
+    [touch _setHidEvent:hidEventBegan];
+
+    UIEvent *event = [[UIApplication sharedApplication] _touchesEvent];
+    if (!event) {
+        CFRelease(hidEventBegan);
+        return NO;
+    }
+    [event _clearTouches];
+    [event _setHIDEvent:hidEventBegan];
+    [event _addTouch:touch forDelayedDelivery:NO];
+
+    [[UIApplication sharedApplication] sendEvent:event];
+    CFRelease(hidEventBegan);
+
+    // Ended phase
+    [touch setPhase:UITouchPhaseEnded];
+    [touch setTimestamp:[[NSProcessInfo processInfo] systemUptime]];
+    IOHIDEventRef hidEventEnded = DBT_IOHIDEventWithTouch(touch);
+    [touch _setHidEvent:hidEventEnded];
+    [event _clearTouches];
+    [event _setHIDEvent:hidEventEnded];
+    [event _addTouch:touch forDelayedDelivery:NO];
+    [[UIApplication sharedApplication] sendEvent:event];
+    CFRelease(hidEventEnded);
+
+    return YES;
+}
+
+@end
+
+#else // !TARGET_OS_IOS
+
+// macOS / Catalyst / other non-iOS host build: no-op stub so the module
+// resolves cleanly without UIKit or IOKit. The Swift cross-platform tests
+// don't exercise touch synthesis; that's iOS-only by definition.
+@implementation DebugBridgeTouch
++ (BOOL)sendTapAtPoint:(CGPoint)point inWindow:(UIWindow *)window {
+    (void)point; (void)window;
+    return NO;
+}
+@end
+
+#endif // TARGET_OS_IOS

test/fixtures/ios-qa/FixtureApp/Sources/DebugBridgeTouch/include/DebugBridgeTouch.h

@@ -0,0 +1,34 @@
+//
+//  DebugBridgeTouch.h — public Objective-C interface for in-process touch
+//  synthesis. Implementation derived from KIF (https://github.com/kif-framework/KIF),
+//  MIT-licensed. The minimal subset needed to deliver a real UITouch to a
+//  point on the key window, including SwiftUI Buttons via iOS 18+
+//  _UIHitTestContext. DEBUG-only — never link in Release.
+
+#import <Foundation/Foundation.h>
+#import <CoreGraphics/CoreGraphics.h>
+#import <TargetConditionals.h>
+
+#if TARGET_OS_IOS
+#import <UIKit/UIKit.h>
+#else
+// macOS build: forward-declare UIWindow so the module compiles without UIKit.
+// The host CI runs swift build on macOS to validate the cross-platform Swift
+// surface; DebugBridgeTouch's implementation is a no-op there. On iOS the
+// real UIWindow comes from UIKit and the implementation is active.
+@class UIWindow;
+#endif
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface DebugBridgeTouch : NSObject
+
+/// Synthesize a single tap (TouchPhaseBegan + TouchPhaseEnded) at the given
+/// window-coordinate point. Returns YES if the touch was delivered (a hit
+/// view was found and the event passed through UIApplication.sendEvent).
+/// On non-iOS platforms returns NO unconditionally.
++ (BOOL)sendTapAtPoint:(CGPoint)point inWindow:(UIWindow *)window;
+
+@end
+
+NS_ASSUME_NONNULL_END

test/fixtures/ios-qa/FixtureApp/Sources/DebugBridgeUI/Bridges.swift

@@ -0,0 +1,308 @@
+// AUTO-GENERATED from gstack/ios-qa/templates/Bridges.swift.template
+//
+// Real UIKit-backed implementations of the three bridges StateServer
+// declares: ScreenshotBridge (PNG capture), ElementsBridge (accessibility
+// tree), MutationBridge (tap/swipe/type via accessibility actions + hit
+// testing). Everything #if DEBUG && canImport(UIKit) so Release builds
+// don't link UIKit or carry any of this code.
+//
+// Wire from the consuming app:
+//
+//   #if DEBUG && canImport(UIKit)
+//   import DebugBridgeUI
+//   DebugBridgeUIWiring.installAll()
+//   #endif
+
+#if DEBUG && canImport(UIKit)
+
+import DebugBridgeCore
+import DebugBridgeTouch
+import Foundation
+import SwiftUI
+import UIKit
+
+@MainActor
+public enum DebugBridgeUIWiring {
+    /// Install all three bridge resolvers. Idempotent — calling multiple
+    /// times reinstalls the same closures. Must be called on @MainActor
+    /// because every UIKit access requires the main actor.
+    public static func installAll() {
+        ScreenshotBridge.resolver = { ScreenshotBridgeImpl.capturePNG() }
+        ElementsBridge.resolver = { ElementsBridgeImpl.snapshot() }
+        MutationBridge.resolver = { op, payload in MutationBridgeImpl.dispatch(op: op, payload: payload) }
+    }
+}
+
+// MARK: - ScreenshotBridge implementation
+
+@MainActor
+enum ScreenshotBridgeImpl {
+    /// Capture a PNG of the active window. Uses UIGraphicsImageRenderer
+    /// (modern API, replaces UIGraphicsBeginImageContext). Returns nil if
+    /// no key window is available (e.g., app backgrounded).
+    static func capturePNG() -> Data? {
+        guard let scene = activeScene(), let window = activeKeyWindow(in: scene) else { return nil }
+        let bounds = window.bounds
+        let renderer = UIGraphicsImageRenderer(bounds: bounds)
+        let image = renderer.image { _ in
+            // drawHierarchy is the documented way to snapshot real UIKit
+            // layers including layer-backed views. afterScreenUpdates: false
+            // because we want the CURRENT visible state, not a forced layout.
+            window.drawHierarchy(in: bounds, afterScreenUpdates: false)
+        }
+        return image.pngData()
+    }
+
+    private static func activeScene() -> UIWindowScene? {
+        UIApplication.shared.connectedScenes
+            .compactMap { $0 as? UIWindowScene }
+            .first { $0.activationState == .foregroundActive }
+            ?? (UIApplication.shared.connectedScenes.first as? UIWindowScene)
+    }
+
+    private static func activeKeyWindow(in scene: UIWindowScene) -> UIWindow? {
+        scene.windows.first(where: { $0.isKeyWindow }) ?? scene.windows.first
+    }
+}
+
+// MARK: - ElementsBridge implementation
+
+@MainActor
+enum ElementsBridgeImpl {
+    /// Walk the accessibility hierarchy + emit a flat list of elements.
+    /// Each entry has frame (in window coords), accessibility label,
+    /// identifier, traits as a bitmask, and a parent path. Skips
+    /// non-accessible / hidden views.
+    static func snapshot() -> [JSONDict] {
+        guard let scene = activeScene(), let window = activeKeyWindow(in: scene) else { return [] }
+        var elements: [JSONDict] = []
+        collect(view: window, parentPath: "", windowBounds: window.bounds, into: &elements)
+        return elements
+    }
+
+    private static func collect(view: UIView, parentPath: String, windowBounds: CGRect, into elements: inout [JSONDict]) {
+        // Skip hidden / zero-size / off-screen subtrees early.
+        if view.isHidden || view.alpha < 0.01 { return }
+
+        let frameInWindow = view.convert(view.bounds, to: nil)
+        if !windowBounds.intersects(frameInWindow) { return }
+
+        let isAccessible = view.isAccessibilityElement
+        let label = view.accessibilityLabel ?? ""
+        let identifier = view.accessibilityIdentifier ?? ""
+        let traits = Int(view.accessibilityTraits.rawValue)
+        let value = (view.accessibilityValue ?? "") as String
+        let className = String(describing: type(of: view))
+        let path = parentPath.isEmpty ? className : "\(parentPath) > \(className)"
+
+        // Emit if any of:
+        //   - Marked accessible (covers UIKit-native widgets)
+        //   - Has explicit AX label / identifier
+        //   - Is a known interactive type (UIControl, UITextField, UIScrollView)
+        //   - Hosts a SwiftUI view (UIHostingController's view class)
+        let isInteractive = view is UIControl || view is UIScrollView || view is UITextInput
+        let isHosting = className.contains("Hosting") || className.contains("SwiftUI")
+        if isAccessible || !label.isEmpty || !identifier.isEmpty || isInteractive || isHosting {
+            elements.append([
+                "path": path,
+                "class": className,
+                "label": label,
+                "identifier": identifier,
+                "value": value,
+                "traits": traits,
+                "frame": [
+                    "x": Int(frameInWindow.origin.x),
+                    "y": Int(frameInWindow.origin.y),
+                    "w": Int(frameInWindow.size.width),
+                    "h": Int(frameInWindow.size.height),
+                ],
+                "is_user_interaction_enabled": view.isUserInteractionEnabled,
+            ])
+        }
+
+        // Recurse into accessibility-elements first (some custom views vend
+        // synthetic children), then UIView subviews. SwiftUI's host views
+        // populate accessibilityElements lazily — many return nil before
+        // VoiceOver triggers them. Force population by reading accessibilityElementCount.
+        _ = view.accessibilityElementCount()
+        if let axElements = view.accessibilityElements {
+            for case let element as NSObject in axElements {
+                if let v = element as? UIView {
+                    collect(view: v, parentPath: path, windowBounds: windowBounds, into: &elements)
+                } else {
+                    // Synthetic accessibility element (no UIView). Capture frame in screen coords.
+                    let af = (element.value(forKey: "accessibilityFrame") as? CGRect) ?? .zero
+                    elements.append([
+                        "path": "\(path) > <synthetic>",
+                        "class": "AccessibilityElement",
+                        "label": (element.value(forKey: "accessibilityLabel") as? String) ?? "",
+                        "identifier": (element.value(forKey: "accessibilityIdentifier") as? String) ?? "",
+                        "value": (element.value(forKey: "accessibilityValue") as? String) ?? "",
+                        "traits": (element.value(forKey: "accessibilityTraits") as? NSNumber)?.intValue ?? 0,
+                        "frame": [
+                            "x": Int(af.origin.x),
+                            "y": Int(af.origin.y),
+                            "w": Int(af.size.width),
+                            "h": Int(af.size.height),
+                        ],
+                        "is_user_interaction_enabled": true,
+                    ])
+                }
+            }
+        } else {
+            // accessibilityElements is nil — iterate by index. SwiftUI uses
+            // this dynamic protocol pattern; many AX elements only respond
+            // to accessibilityElementCount + accessibilityElement(at:).
+            let count = view.accessibilityElementCount()
+            for i in 0..<count {
+                guard let element = view.accessibilityElement(at: i) as? NSObject else { continue }
+                if let v = element as? UIView {
+                    collect(view: v, parentPath: path, windowBounds: windowBounds, into: &elements)
+                } else {
+                    let af = (element.value(forKey: "accessibilityFrame") as? CGRect) ?? .zero
+                    elements.append([
+                        "path": "\(path) > <ax\(i)>",
+                        "class": String(describing: type(of: element)),
+                        "label": (element.value(forKey: "accessibilityLabel") as? String) ?? "",
+                        "identifier": (element.value(forKey: "accessibilityIdentifier") as? String) ?? "",
+                        "value": (element.value(forKey: "accessibilityValue") as? String) ?? "",
+                        "traits": (element.value(forKey: "accessibilityTraits") as? NSNumber)?.intValue ?? 0,
+                        "frame": [
+                            "x": Int(af.origin.x),
+                            "y": Int(af.origin.y),
+                            "w": Int(af.size.width),
+                            "h": Int(af.size.height),
+                        ],
+                        "is_user_interaction_enabled": true,
+                    ])
+                }
+            }
+        }
+        for sub in view.subviews {
+            collect(view: sub, parentPath: path, windowBounds: windowBounds, into: &elements)
+        }
+    }
+
+    private static func activeScene() -> UIWindowScene? {
+        UIApplication.shared.connectedScenes
+            .compactMap { $0 as? UIWindowScene }
+            .first { $0.activationState == .foregroundActive }
+            ?? (UIApplication.shared.connectedScenes.first as? UIWindowScene)
+    }
+
+    private static func activeKeyWindow(in scene: UIWindowScene) -> UIWindow? {
+        scene.windows.first(where: { $0.isKeyWindow }) ?? scene.windows.first
+    }
+}
+
+// MARK: - MutationBridge implementation
+
+@MainActor
+enum MutationBridgeImpl {
+    /// Route a mutation op to the right handler. Returns true on success,
+    /// false on failure (which the StateServer surfaces as 400 to the agent).
+    static func dispatch(op: String, payload: JSONDict) -> Bool {
+        switch op {
+        case "tap":     return handleTap(payload)
+        case "type":    return handleType(payload)
+        case "swipe":   return handleSwipe(payload)
+        default:        return false
+        }
+    }
+
+    /// Tap at (x, y) in window coordinates. Delegates to DebugBridgeTouch
+    /// (KIF-derived in-process touch synthesis). The Obj-C target builds a
+    /// real UITouch + IOHIDEvent + UIEvent and dispatches via
+    /// `UIApplication.sendEvent`, which is what UIKit uses for real touches.
+    /// This works for UIControl, SwiftUI Button (via iOS 18+
+    /// `_UIHitTestContext`), gesture recognizers, and anything else that
+    /// listens to the real event-dispatch path.
+    private static func handleTap(_ payload: JSONDict) -> Bool {
+        guard let x = payload["x"] as? NSNumber,
+              let y = payload["y"] as? NSNumber else { return false }
+        let point = CGPoint(x: x.doubleValue, y: y.doubleValue)
+        guard let scene = activeScene(), let window = activeKeyWindow(in: scene) else { return false }
+        return DebugBridgeTouch.sendTap(at: point, in: window)
+    }
+
+    /// Set text on the first responder if it's a UITextField or UITextView.
+    private static func handleType(_ payload: JSONDict) -> Bool {
+        guard let text = payload["text"] as? String else { return false }
+        guard let scene = activeScene(), let window = activeKeyWindow(in: scene) else { return false }
+        guard let responder = findFirstResponder(in: window) else { return false }
+        if let field = responder as? UITextField {
+            field.text = text
+            field.sendActions(for: .editingChanged)
+            return true
+        }
+        if let view = responder as? UITextView {
+            view.text = text
+            view.delegate?.textViewDidChange?(view)
+            return true
+        }
+        return false
+    }
+
+    /// Swipe via UIScrollView programmatic scroll OR via setContentOffset on
+    /// the deepest UIScrollView in the hit-tested ancestor chain. Less
+    /// faithful than synthesized touches but covers common scroll scenarios.
+    private static func handleSwipe(_ payload: JSONDict) -> Bool {
+        guard let fx = payload["from_x"] as? NSNumber,
+              let fy = payload["from_y"] as? NSNumber,
+              let tx = payload["to_x"] as? NSNumber,
+              let ty = payload["to_y"] as? NSNumber else { return false }
+        let from = CGPoint(x: fx.doubleValue, y: fy.doubleValue)
+        let to = CGPoint(x: tx.doubleValue, y: ty.doubleValue)
+
+        guard let scene = activeScene(), let window = activeKeyWindow(in: scene) else { return false }
+        guard let hit = window.hitTest(from, with: nil) else { return false }
+
+        // Find the nearest enclosing UIScrollView.
+        var node: UIView? = hit
+        while let cur = node {
+            if let scroll = cur as? UIScrollView {
+                let dx = from.x - to.x
+                let dy = from.y - to.y
+                var off = scroll.contentOffset
+                off.x = max(0, min(scroll.contentSize.width - scroll.bounds.width, off.x + dx))
+                off.y = max(0, min(scroll.contentSize.height - scroll.bounds.height, off.y + dy))
+                scroll.setContentOffset(off, animated: true)
+                return true
+            }
+            node = cur.superview
+        }
+        return false
+    }
+
+    // MARK: helpers
+
+    private static func walkUp(_ view: UIView) -> UIView? {
+        var node: UIView? = view
+        while let cur = node {
+            if cur is UIControl { return cur }
+            node = cur.superview
+        }
+        return view
+    }
+
+    private static func findFirstResponder(in view: UIView) -> UIResponder? {
+        if view.isFirstResponder { return view }
+        for sub in view.subviews {
+            if let found = findFirstResponder(in: sub) { return found }
+        }
+        return nil
+    }
+
+    private static func activeScene() -> UIWindowScene? {
+        UIApplication.shared.connectedScenes
+            .compactMap { $0 as? UIWindowScene }
+            .first { $0.activationState == .foregroundActive }
+            ?? (UIApplication.shared.connectedScenes.first as? UIWindowScene)
+    }
+
+    private static func activeKeyWindow(in scene: UIWindowScene) -> UIWindow? {
+        scene.windows.first(where: { $0.isKeyWindow }) ?? scene.windows.first
+    }
+}
+
+#endif // DEBUG && canImport(UIKit)

test/fixtures/ios-qa/FixtureApp/Sources/DebugBridgeUI/DebugOverlay.swift

@@ -0,0 +1,137 @@
+// AUTO-GENERATED from gstack/ios-qa/templates/DebugOverlay.swift.template
+//
+// DebugOverlay — on-device visual presence. Animated brand-colored border +
+// agent attribution chip + (optional) recording watermark. Renders above
+// sheets, alerts, and modals via a dedicated UIWindow with high windowLevel.
+//
+// Everything in this file is gated #if DEBUG and gone in Release.
+
+#if DEBUG && canImport(UIKit)
+
+import SwiftUI
+import UIKit
+
+@MainActor
+public final class DebugOverlayWindow {
+    public static let shared = DebugOverlayWindow()
+
+    private var window: UIWindow?
+
+    public func install(recording: Bool = false) {
+        guard window == nil else { return }
+        guard let scene = UIApplication.shared.connectedScenes.compactMap({ $0 as? UIWindowScene }).first else { return }
+
+        let w = PassThroughWindow(windowScene: scene)
+        w.windowLevel = .alert + 1
+        w.backgroundColor = .clear
+        w.isUserInteractionEnabled = false
+
+        let host = UIHostingController(rootView: OverlayRoot(recording: recording))
+        host.view.backgroundColor = .clear
+        w.rootViewController = host
+        w.isHidden = false
+
+        window = w
+    }
+
+    public func setAttribution(_ identity: String) {
+        OverlayAttributionState.shared.identity = identity
+    }
+}
+
+/// A window that lets touches pass through to underlying windows.
+private final class PassThroughWindow: UIWindow {
+    override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
+        let view = super.hitTest(point, with: event)
+        return view == rootViewController?.view ? nil : view
+    }
+}
+
+@MainActor
+final class OverlayAttributionState: ObservableObject {
+    static let shared = OverlayAttributionState()
+    @Published var identity: String = "Claude Code (local)"
+}
+
+private struct OverlayRoot: View {
+    @StateObject private var attribution = OverlayAttributionState.shared
+    @State private var phase: CGFloat = 0
+    let recording: Bool
+
+    var body: some View {
+        ZStack {
+            // Animated brand border
+            BorderShape()
+                .stroke(
+                    AngularGradient(
+                        gradient: Gradient(colors: [
+                            BrandColor.accent.opacity(0.0),
+                            BrandColor.accent.opacity(0.8),
+                            BrandColor.accent.opacity(0.0),
+                        ]),
+                        center: .center,
+                        angle: .degrees(phase * 360)
+                    ),
+                    lineWidth: 4
+                )
+                .ignoresSafeArea()
+                .onAppear {
+                    withAnimation(.linear(duration: 2.0).repeatForever(autoreverses: false)) {
+                        phase = 1.0
+                    }
+                }
+
+            // Attribution chip (top safe area)
+            VStack {
+                HStack {
+                    Spacer()
+                    Text("Driven by \(attribution.identity)")
+                        .font(.caption2.weight(.semibold))
+                        .foregroundColor(.white)
+                        .padding(.horizontal, 10)
+                        .padding(.vertical, 4)
+                        .background(
+                            Capsule().fill(BrandColor.accent.opacity(0.85))
+                        )
+                        .padding(.trailing, 12)
+                        .padding(.top, 8)
+                    Spacer().frame(width: 0)
+                }
+                Spacer()
+            }
+
+            // Recording watermark (diagonal, bottom-right)
+            if recording {
+                VStack {
+                    Spacer()
+                    HStack {
+                        Spacer()
+                        Text("AGENT DEMO")
+                            .font(.system(size: 10, weight: .heavy, design: .monospaced))
+                            .foregroundColor(.red.opacity(0.7))
+                            .rotationEffect(.degrees(-30))
+                            .padding(.trailing, 16)
+                            .padding(.bottom, 30)
+                    }
+                }
+            }
+        }
+        .allowsHitTesting(false)
+    }
+}
+
+private struct BorderShape: Shape {
+    func path(in rect: CGRect) -> Path {
+        var p = Path()
+        p.addRoundedRect(in: rect.insetBy(dx: 2, dy: 2), cornerSize: CGSize(width: 16, height: 16))
+        return p
+    }
+}
+
+private enum BrandColor {
+    // gstack brand color — resolved from DESIGN.md when codegen runs.
+    // Default falls back to a deep blue.
+    static let accent = Color(red: 0.0, green: 0.46, blue: 1.0)
+}
+
+#endif // DEBUG && canImport(UIKit)

test/fixtures/ios-qa/FixtureApp/Sources/FixtureApp/FixtureAppApp.swift

@@ -0,0 +1,60 @@
+// FixtureApp — minimal SwiftUI app used by the ios-qa device-path E2E test.
+//
+// On launch:
+//   1. Boot StateServer (loopback :::1/127.0.0.1 + 9999)
+//   2. Log boot token to os_log so devicectl + the Mac daemon can scrape it
+//   3. Render a single ContentView so the app stays foreground
+//
+// Everything ios-qa-related is gated #if DEBUG. Release builds compile this
+// to a no-op app (no StateServer, no DebugBridge import, no overlay).
+
+import SwiftUI
+
+#if DEBUG
+import DebugBridgeCore
+#endif
+
+#if DEBUG && canImport(UIKit)
+import DebugBridgeUI
+#endif
+
+@main
+struct FixtureAppApp: App {
+    init() {
+        #if DEBUG
+        StateServer.shared.start()
+        // Wire the three UIKit-backed bridges so /screenshot, /elements,
+        // /tap, /type, /swipe actually do something on the device.
+        #if canImport(UIKit)
+        DebugBridgeUIWiring.installAll()
+        #endif
+        #endif
+    }
+
+    var body: some Scene {
+        WindowGroup {
+            ContentView()
+        }
+    }
+}
+
+struct ContentView: View {
+    @State private var counter: Int = 0
+
+    var body: some View {
+        VStack(spacing: 24) {
+            Text("ios-qa fixture")
+                .font(.largeTitle.bold())
+            Text("StateServer should be on :9999")
+                .font(.subheadline)
+                .foregroundColor(.secondary)
+            Button("Tap (\(counter))") {
+                counter += 1
+            }
+            .buttonStyle(.borderedProminent)
+            .accessibilityIdentifier("tap-button")
+        }
+        .padding()
+        .accessibilityIdentifier("fixture-content")
+    }
+}

test/fixtures/ios-qa/FixtureApp/Sources/FixtureApp/FixtureAppState.swift

@@ -0,0 +1,32 @@
+// Canonical app state for the fixture. Every snapshot-eligible field is
+// marked with the @Snapshotable property wrapper that the codegen tool
+// detects via attribute scan.
+//
+// Note: we DON'T use @Observable here because the macro expansion converts
+// stored properties into computed ones, which the @Snapshotable wrapper
+// can't apply to. In production apps that need both observability AND
+// snapshotting, the right pattern is:
+//   - Use ObservableObject + @Published (older API), or
+//   - Hold all @Snapshotable state in a nested struct + replace it
+//     wholesale on restore so SwiftUI sees a single change notification
+//     (the canonical-state-struct atomicity strategy from the plan).
+
+import Foundation
+
+public final class FixtureAppState {
+    @Snapshotable public var isLoggedIn: Bool = false
+    @Snapshotable public var username: String = ""
+    @Snapshotable public var tapCounter: Int = 0
+    /// Not snapshotted — ephemeral cache that should never leak via /state/snapshot.
+    public var ephemeralCache: [String: String] = [:]
+
+    public init() {}
+}
+
+/// Property wrapper marker for snapshot-eligible state. The actual wrapper
+/// is a no-op at runtime; codegen-tool detection happens via attribute scan.
+@propertyWrapper
+public struct Snapshotable<Value> {
+    public var wrappedValue: Value
+    public init(wrappedValue: Value) { self.wrappedValue = wrappedValue }
+}

test/fixtures/ios-qa/FixtureApp/Sources/FixtureApp/Info.plist

@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleDevelopmentRegion</key>
+	<string>$(DEVELOPMENT_LANGUAGE)</string>
+	<key>CFBundleDisplayName</key>
+	<string>ios-qa fixture</string>
+	<key>CFBundleExecutable</key>
+	<string>$(EXECUTABLE_NAME)</string>
+	<key>CFBundleIdentifier</key>
+	<string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
+	<key>CFBundleInfoDictionaryVersion</key>
+	<string>6.0</string>
+	<key>CFBundleName</key>
+	<string>$(PRODUCT_NAME)</string>
+	<key>CFBundlePackageType</key>
+	<string>APPL</string>
+	<key>CFBundleShortVersionString</key>
+	<string>1.0</string>
+	<key>CFBundleVersion</key>
+	<string>1</string>
+	<key>UILaunchScreen</key>
+	<dict/>
+	<key>UIRequiredDeviceCapabilities</key>
+	<array>
+		<string>arm64</string>
+	</array>
+	<key>UISupportedInterfaceOrientations</key>
+	<array>
+		<string>UIInterfaceOrientationPortrait</string>
+	</array>
+</dict>
+</plist>

test/fixtures/ios-qa/FixtureApp/Tests/DebugBridgeCoreTests/StateServerSmokeTests.swift

@@ -0,0 +1,107 @@
+// XCTest unit test for StateServer. Runs the real Swift implementation on
+// macOS (#if DEBUG, loopback bind, full Foundation+Network stack) and
+// exercises the auth flow + session lock + snapshot endpoints over HTTP.
+//
+// This is what validates that the production Swift code actually works,
+// not just that it compiles. Daemon integration tests already cover the
+// TS side; this covers the Swift side without an iPhone.
+
+import XCTest
+import Foundation
+@testable import DebugBridgeCore
+
+#if DEBUG
+
+@MainActor
+final class StateServerSmokeTests: XCTestCase {
+
+    /// Build URL for a loopback call. Use IPv6 since CoreDevice tunnels are IPv6,
+    /// and the StateServer template uses IPv6 first.
+    func loopbackURL(port: UInt16, path: String) -> URL {
+        URL(string: "http://[::1]:\(port)\(path)")!
+    }
+
+    /// Issue an HTTP request and decode JSON. Returns (status, body).
+    func request(method: String, url: URL, headers: [String: String] = [:], body: Data? = nil) async throws -> (Int, [String: Any]) {
+        var req = URLRequest(url: url)
+        req.httpMethod = method
+        for (k, v) in headers { req.setValue(v, forHTTPHeaderField: k) }
+        if let body = body { req.httpBody = body }
+        let (data, response) = try await URLSession.shared.data(for: req)
+        let status = (response as? HTTPURLResponse)?.statusCode ?? 0
+        let json = (try? JSONSerialization.jsonObject(with: data)) as? [String: Any] ?? [:]
+        return (status, json)
+    }
+
+    /// Spin up StateServer on a random port, wait briefly for binding to settle.
+    /// Returns the port. Uses StateServer.shared since it's a singleton.
+    func spinUp() async throws -> UInt16 {
+        // Port 0 doesn't work with NWListener directly; pick a high random.
+        let port: UInt16 = UInt16.random(in: 30000...39999)
+        StateServer.shared.start()  // starts on default 9999, but template uses fixed
+        // The template hardcodes port 9999 — we test against that.
+        // Sleep briefly for binding to complete.
+        try await Task.sleep(nanoseconds: 100_000_000)  // 100ms
+        return 9999
+    }
+
+    func test_healthz_returns_200_without_auth() async throws {
+        let port = try await spinUp()
+        let (status, body) = try await request(method: "GET", url: loopbackURL(port: port, path: "/healthz"))
+        XCTAssertEqual(status, 200, "healthz should return 200 without auth on loopback")
+        XCTAssertEqual(body["version"] as? String, "1.0.0")
+    }
+
+    func test_tap_requires_auth() async throws {
+        let port = try await spinUp()
+        let (status, _) = try await request(method: "POST", url: loopbackURL(port: port, path: "/tap"))
+        XCTAssertEqual(status, 401, "mutating endpoint without bearer must return 401")
+    }
+
+    /// Boot token rotation is the load-bearing security property. Confirm:
+    /// 1. Boot token is required for /auth/rotate
+    /// 2. After rotation, boot token is dead
+    /// 3. Rotated token works for subsequent calls
+    func test_boot_token_rotation_kills_original() async throws {
+        let port = try await spinUp()
+
+        // Read boot token from os_log scrape — in production this comes from
+        // devicectl process launch. For this test we can read it from the
+        // bootTokenPath file. (StateServer writes a 0600 file as fallback.)
+        let bootTokenPath = NSTemporaryDirectory() + "gstack-ios-qa.token"
+        let bootToken = try? String(contentsOfFile: bootTokenPath, encoding: .utf8)
+        guard let bt = bootToken?.trimmingCharacters(in: .whitespacesAndNewlines), !bt.isEmpty else {
+            throw XCTSkip("Boot token file not written — StateServer may not have started cleanly")
+        }
+
+        // Rotate.
+        let newToken = "rotated-test-token-\(UUID().uuidString)"
+        let rotateBody = try JSONSerialization.data(withJSONObject: ["new_token": newToken])
+        let (rotateStatus, _) = try await request(
+            method: "POST",
+            url: loopbackURL(port: port, path: "/auth/rotate"),
+            headers: ["Authorization": "Bearer \(bt)", "Content-Type": "application/json"],
+            body: rotateBody
+        )
+        XCTAssertEqual(rotateStatus, 200, "rotate with valid boot token should succeed")
+
+        // Original boot token should now be dead.
+        let (deadStatus, _) = try await request(
+            method: "POST",
+            url: loopbackURL(port: port, path: "/auth/rotate"),
+            headers: ["Authorization": "Bearer \(bt)", "Content-Type": "application/json"],
+            body: rotateBody
+        )
+        XCTAssertEqual(deadStatus, 401, "boot token must be dead after rotation")
+
+        // New token works.
+        let (acqStatus, _) = try await request(
+            method: "POST",
+            url: loopbackURL(port: port, path: "/session/acquire"),
+            headers: ["Authorization": "Bearer \(newToken)"]
+        )
+        XCTAssertEqual(acqStatus, 200, "rotated token must work for session acquire")
+    }
+}
+
+#endif // DEBUG

test/fixtures/ios-qa/FixtureApp/project.yml

@@ -0,0 +1,49 @@
+name: FixtureApp
+options:
+  deploymentTarget:
+    iOS: "16.0"
+  bundleIdPrefix: com.gstack.iosqa
+  developmentLanguage: en
+  createIntermediateGroups: true
+
+settings:
+  DEVELOPMENT_TEAM: 623FYQ2M88
+  CODE_SIGN_STYLE: Automatic
+  ENABLE_USER_SCRIPT_SANDBOXING: NO
+  # Personal-team bundle IDs are scoped per-team; this prefix is unique.
+  PRODUCT_BUNDLE_IDENTIFIER: com.gstack.iosqa.fixture
+
+# Local SPM package providing DebugBridgeCore + DebugBridgeUI as dependencies.
+# packages keyword (with `path:`) means a sibling local package next to project.yml.
+packages:
+  DebugBridge:
+    path: .
+
+targets:
+  FixtureApp:
+    type: application
+    platform: iOS
+    deploymentTarget: "16.0"
+    sources:
+      - path: Sources/FixtureApp
+    dependencies:
+      - package: DebugBridge
+        product: DebugBridgeCore
+      - package: DebugBridge
+        product: DebugBridgeUI
+    info:
+      path: Sources/FixtureApp/Info.plist
+      properties:
+        CFBundleDisplayName: ios-qa fixture
+        UILaunchScreen: {}
+        UISupportedInterfaceOrientations: [UIInterfaceOrientationPortrait]
+        UIRequiredDeviceCapabilities: [arm64]
+    settings:
+      base:
+        PRODUCT_BUNDLE_IDENTIFIER: com.gstack.iosqa.fixture
+        DEVELOPMENT_TEAM: 623FYQ2M88
+        CODE_SIGN_STYLE: Automatic
+        TARGETED_DEVICE_FAMILY: "1"
+        SWIFT_VERSION: "5.9"
+        IPHONEOS_DEPLOYMENT_TARGET: "16.0"
+        ENABLE_PREVIEWS: YES