simframe 0.4.1 → 0.5.0

package/native/simframed/Sources/simframed/main.swift

@@ -0,0 +1,357 @@
+import CoreGraphics
+import Foundation
+import PrivateAPI
+import SimframeCore
+
+let args = Array(CommandLine.arguments.dropFirst())
+func flag(_ name: String) -> String? {
+    guard let a = args.first(where: { $0.hasPrefix("--\(name)=") }) else { return nil }
+    return String(a.dropFirst(name.count + 3))
+}
+
+let command = args.first(where: { !$0.hasPrefix("--") }) ?? "run"
+let platform: SimulatorPlatform = args.contains("--stub") ? StubPlatform() : CoreSimulatorPlatform()
+let longEdge = Int(flag("max-dim") ?? "") ?? 700
+
+func fail(_ message: String) -> Never {
+    FileHandle.standardError.write("simframed: \(message)\n".data(using: .utf8)!)
+    exit(1)
+}
+
+switch command {
+case "devices":
+    do {
+        for d in try platform.bootedDevices() { print("\(d.udid)  \(d.name)  \(d.runtime)") }
+    } catch { fail("\(error)") }
+
+case "hash":
+    // One-shot: used to verify the Swift hashes match the JavaScript ones.
+    do {
+        let device = try platform.attach(udid: flag("udid"))
+        let t0 = DispatchTime.now().uptimeNanoseconds
+        let useCG = !args.contains("--box")
+        let (bmp, native) = try platform.withFrame { frame -> (Bitmap, (Int, Int)) in
+            let scaled = useCG
+                ? (CoreGraphicsScaler.bitmap(from: frame, targetLongEdge: longEdge) ?? Bitmap.from(frame, targetLongEdge: longEdge))
+                : Bitmap.from(frame, targetLongEdge: longEdge)
+            return (scaled, (frame.width, frame.height))
+        }
+        let ms = Double(DispatchTime.now().uptimeNanoseconds - t0) / 1e6
+        let json: [String: Any] = [
+            "device": ["udid": device.udid, "name": device.name, "runtime": device.runtime],
+            "native": ["width": native.0, "height": native.1],
+            "scaled": ["width": bmp.width, "height": bmp.height],
+            "hash": Hashing.frameHash(bmp),
+            "layoutHash": Hashing.layoutHash(bmp),
+            "regions": Hashing.signatureToHex(Hashing.regionSignature(bmp)),
+            "captureMs": (ms * 100).rounded() / 100,
+        ]
+        let data = try JSONSerialization.data(withJSONObject: json, options: [.sortedKeys])
+        print(String(data: data, encoding: .utf8)!)
+    } catch { fail("\(error)") }
+
+case "bench":
+    do {
+        _ = try platform.attach(udid: flag("udid"))
+        let n = Int(flag("n") ?? "") ?? 200
+        var grab: [Double] = [], full: [Double] = []
+        for _ in 0..<n {
+            let t0 = DispatchTime.now().uptimeNanoseconds
+            let bmp = try platform.withFrame { Bitmap.from($0, targetLongEdge: longEdge) }
+            let t1 = DispatchTime.now().uptimeNanoseconds
+            _ = Hashing.frameHash(bmp)
+            _ = Hashing.layoutHash(bmp)
+            let t2 = DispatchTime.now().uptimeNanoseconds
+            grab.append(Double(t1 - t0) / 1e6)
+            full.append(Double(t2 - t0) / 1e6)
+        }
+        func pct(_ xs: [Double], _ p: Double) -> Double {
+            let s = xs.sorted(); return (s[min(s.count - 1, Int(Double(s.count) * p))] * 100).rounded() / 100
+        }
+        print("n=\(n)  grab+scale median \(pct(grab, 0.5))ms p95 \(pct(grab, 0.95))ms  |  +hash median \(pct(full, 0.5))ms p95 \(pct(full, 0.95))ms")
+    } catch { fail("\(error)") }
+
+case "snap":
+    // Write one frame to disk so it can be looked at. Correct hashes prove
+    // nothing about channel order or row padding; a picture does.
+    do {
+        _ = try platform.attach(udid: flag("udid"))
+        let out = flag("out") ?? "simframed-snap.png"
+        let full = args.contains("--native")
+        let bmp = try platform.withFrame { frame -> Bitmap in
+            let edge = full ? max(frame.width, frame.height) : longEdge
+            return CoreGraphicsScaler.bitmap(from: frame, targetLongEdge: edge)
+                ?? Bitmap.from(frame, targetLongEdge: edge)
+        }
+        try PNGWriter.write(bmp, to: URL(fileURLWithPath: out))
+        print("\(out) — \(bmp.width)x\(bmp.height)")
+    } catch { fail("\(error)") }
+
+case "input":
+    do {
+        let device = try platform.attach(udid: flag("udid"))
+        let status = platform.inputStatus()
+        print("\(status.available ? "ok  " : "FAIL") \(status.detail)")
+        print("     \(device.name): \(device.pixelWidth)x\(device.pixelHeight)px @\(device.scale)x = \(device.pointWidth)x\(device.pointHeight)pt")
+    } catch { fail("\(error)") }
+
+case "tap", "swipe", "type", "paste", "press":
+    do {
+        _ = try platform.attach(udid: flag("udid"))
+        let positional = args.filter { !$0.hasPrefix("--") }.dropFirst()
+        let t0 = DispatchTime.now().uptimeNanoseconds
+        switch command {
+        case "tap":
+            guard positional.count >= 2, let x = Double(positional.first!), let y = Double(positional.dropFirst().first!) else {
+                fail("usage: simframed tap <x> <y> [--duration-ms=70]")
+            }
+            try platform.tap(at: CGPoint(x: x, y: y), durationMs: Double(flag("duration-ms") ?? "") ?? 70)
+        case "swipe":
+            let v = positional.compactMap(Double.init)
+            guard v.count >= 4 else { fail("usage: simframed swipe <x1> <y1> <x2> <y2> [--duration-ms=300]") }
+            try platform.swipe(from: CGPoint(x: v[0], y: v[1]), to: CGPoint(x: v[2], y: v[3]),
+                               durationMs: Double(flag("duration-ms") ?? "") ?? 300)
+        case "type":
+            guard !positional.isEmpty else { fail("usage: simframed type <text>") }
+            try platform.type(positional.joined(separator: " "))
+        case "paste":
+            guard !positional.isEmpty else { fail("usage: simframed paste <text>") }
+            try platform.paste(positional.joined(separator: " "))
+        default:
+            guard let name = positional.first, let button = HardwareButton(rawValue: name) else {
+                fail("usage: simframed press <\(HardwareButton.allCases.map(\.rawValue).joined(separator: "|"))>")
+            }
+            try platform.press(button)
+        }
+        print(String(format: "%@ in %.0fms", command, Double(DispatchTime.now().uptimeNanoseconds - t0) / 1e6))
+    } catch { fail("\(error)") }
+
+case "run":
+    // The capture loop. Driven by the display's damage callback rather than a
+    // timer, so an idle screen costs nothing and a moving one is picked up at
+    // once. A slow floor keeps state fresh enough for liveness checks.
+    do {
+        let device = try platform.attach(udid: flag("udid"))
+        var opts = FrameStore.Options()
+        opts.maxDim = longEdge
+        let store = try FrameStore(device: device, options: opts)
+        try store.claim()
+        defer { store.release() }
+
+        // `defer` does not run when a signal terminates the process, so a
+        // plain Ctrl-C would leave meta.json naming a dead pid. Node recovers
+        // from that on its own, but a daemon should tidy up after itself.
+        var stopping = false
+        let signalQueue = DispatchQueue(label: "simframe.signals")
+        var signalSources: [DispatchSourceSignal] = []
+        for sig in [SIGINT, SIGTERM] {
+            signal(sig, SIG_IGN)   // let the dispatch source own it
+            let source = DispatchSource.makeSignalSource(signal: sig, queue: signalQueue)
+            source.setEventHandler { stopping = true }
+            source.resume()
+            signalSources.append(source)
+        }
+
+        let minInterval = Double(flag("min-interval-ms") ?? "") ?? 80      // coalesce bursts
+        let idleInterval = Double(flag("idle-interval-ms") ?? "") ?? 2000  // keep state fresh
+        let idleExitMs = Double(flag("idle-exit-ms") ?? "") ?? 15 * 60_000
+
+        let lock = NSLock()
+        var dirty = true
+        var lastCapture = 0.0
+        var frames = 0
+        var lastReport = Date().timeIntervalSince1970
+        var latencies: [Double] = []
+
+        try platform.observeChanges {
+            lock.lock(); dirty = true; lock.unlock()
+        }
+
+        // Control socket: requests are served off the capture loop, because a
+        // swipe sleeps for its whole duration and must not stall frames.
+        let socketPath = store.controlSocketPath
+        let control = ControlSocket(path: socketPath) { request in
+            let action = request["action"] as? String ?? ""
+            let started = DispatchTime.now().uptimeNanoseconds
+            func done(_ extra: [String: Any] = [:]) -> [String: Any] {
+                var r: [String: Any] = ["ok": true]
+                r["ms"] = (Double(DispatchTime.now().uptimeNanoseconds - started) / 1e6 * 100).rounded() / 100
+                for (k, v) in extra { r[k] = v }
+                return r
+            }
+            func point(_ xKey: String, _ yKey: String) -> CGPoint? {
+                guard let x = request[xKey] as? Double ?? (request[xKey] as? Int).map(Double.init),
+                      let y = request[yKey] as? Double ?? (request[yKey] as? Int).map(Double.init) else { return nil }
+                return CGPoint(x: x, y: y)
+            }
+            do {
+                switch action {
+                case "ping":
+                    return done(["device": device.name, "udid": device.udid])
+                case "status":
+                    let input = platform.inputStatus()
+                    return done([
+                        "input": ["available": input.available, "detail": input.detail],
+                        "device": ["name": device.name, "udid": device.udid,
+                                   "pointWidth": device.pointWidth, "pointHeight": device.pointHeight,
+                                   "scale": device.scale],
+                        "engine": "simframed",
+                    ])
+                case "ui":
+                    // OCR straight off the framebuffer: no PNG encode, no file,
+                    // no process spawn. Runs on the socket queue, so a slow
+                    // recognition pass cannot stall frame capture.
+                    let started = DispatchTime.now().uptimeNanoseconds
+                    let elements = try platform.withFrame { frame in
+                        try VisionOCR.recognise(frame: frame, scale: device.scale)
+                    }
+                    let latest = store.latestState()
+                    let map = ScreenMap(
+                        fingerprint: latest?["layoutHash"] as? String ?? "",
+                        hash: latest?["hash"] as? String ?? "",
+                        size: CGSize(width: device.pointWidth, height: device.pointHeight),
+                        elements: elements,
+                        sources: ["ocr"],
+                        capturedAt: FrameStore.nowMs()
+                    )
+                    var payload = map.json
+                    payload["ocrMs"] = (Double(DispatchTime.now().uptimeNanoseconds - started) / 1e6 * 100).rounded() / 100
+                    return done(["screen": payload])
+                case "tap":
+                    guard let p = point("x", "y") else { return ["ok": false, "error": "tap needs x and y"] }
+                    try platform.tap(at: p, durationMs: request["durationMs"] as? Double ?? 70)
+                    return done()
+                case "swipe":
+                    guard let from = point("x1", "y1"), let to = point("x2", "y2") else {
+                        return ["ok": false, "error": "swipe needs x1, y1, x2, y2"]
+                    }
+                    try platform.swipe(from: from, to: to, durationMs: request["durationMs"] as? Double ?? 300)
+                    return done()
+                case "type":
+                    guard let text = request["text"] as? String else { return ["ok": false, "error": "type needs text"] }
+                    try platform.type(text)
+                    return done()
+                case "paste":
+                    guard let text = request["text"] as? String else { return ["ok": false, "error": "paste needs text"] }
+                    try platform.paste(text)
+                    return done()
+                case "longPress":
+                    guard let p = point("x", "y") else { return ["ok": false, "error": "longPress needs x and y"] }
+                    try platform.longPress(at: p, durationMs: request["durationMs"] as? Double ?? 600)
+                    return done()
+                case "drag":
+                    guard let from = point("x1", "y1"), let to = point("x2", "y2") else {
+                        return ["ok": false, "error": "drag needs x1, y1, x2, y2"]
+                    }
+                    try platform.drag(from: from, to: to,
+                                      holdMs: request["holdMs"] as? Double ?? 500,
+                                      durationMs: request["durationMs"] as? Double ?? 400)
+                    return done()
+                case "launch":
+                    guard let bundleId = request["bundleId"] as? String else { return ["ok": false, "error": "launch needs bundleId"] }
+                    let pid = try platform.launch(bundleId: bundleId,
+                                                  arguments: request["arguments"] as? [String] ?? [],
+                                                  environment: request["environment"] as? [String: String] ?? [:])
+                    return done(["pid": Int(pid)])
+                case "terminate":
+                    guard let bundleId = request["bundleId"] as? String else { return ["ok": false, "error": "terminate needs bundleId"] }
+                    try platform.terminate(bundleId: bundleId)
+                    return done()
+                case "openUrl":
+                    guard let url = request["url"] as? String else { return ["ok": false, "error": "openUrl needs url"] }
+                    try platform.openURL(url)
+                    return done()
+                case "permission":
+                    guard let action = request["permissionAction"] as? String, let service = request["service"] as? String else {
+                        return ["ok": false, "error": "permission needs permissionAction and service"]
+                    }
+                    try platform.permission(action: action, service: service, bundleId: request["bundleId"] as? String)
+                    return done()
+                case "press":
+                    guard let name = request["button"] as? String, let button = HardwareButton(rawValue: name) else {
+                        return ["ok": false, "error": "press needs a known button name"]
+                    }
+                    try platform.press(button)
+                    return done()
+                default:
+                    return ["ok": false, "error": "unknown action '\(action)'"]
+                }
+            } catch {
+                return ["ok": false, "error": "\(error)"]
+            }
+        }
+        do {
+            try control.start()
+            FileHandle.standardError.write("simframed: control socket at \(socketPath)\n".data(using: .utf8)!)
+        } catch {
+            // Capture is still useful without input; say so rather than dying.
+            FileHandle.standardError.write("simframed: control socket unavailable: \(error)\n".data(using: .utf8)!)
+        }
+        defer { control.stop() }
+
+        FileHandle.standardError.write("simframed: capturing \(device.name) (\(device.udid))\n".data(using: .utf8)!)
+
+        while true {
+            let now = Date().timeIntervalSince1970 * 1000
+            lock.lock()
+            let isDirty = dirty
+            lock.unlock()
+
+            let due = (isDirty && now - lastCapture >= minInterval) || (now - lastCapture >= idleInterval)
+            if due {
+                lock.lock(); dirty = false; lock.unlock()
+                let t0 = DispatchTime.now().uptimeNanoseconds
+                do {
+                    // One grab produces both sizes; the surface pointer is only
+                    // valid inside this call, so nothing may be deferred out of it.
+                    let wantFull = store.wantsFullFrame()
+                    let (bmp, full) = try platform.withFrame { frame -> (Bitmap, Bitmap?) in
+                        let scaled = CoreGraphicsScaler.bitmap(from: frame, targetLongEdge: longEdge)
+                            ?? Bitmap.from(frame, targetLongEdge: longEdge)
+                        let native = wantFull
+                            ? CoreGraphicsScaler.bitmap(from: frame, targetLongEdge: max(frame.width, frame.height))
+                            : nil
+                        return (scaled, native)
+                    }
+                    let ms = Double(DispatchTime.now().uptimeNanoseconds - t0) / 1e6
+                    try store.record(bmp, fullBitmap: full, captureMs: ms)
+                    latencies.append(Double(DispatchTime.now().uptimeNanoseconds - t0) / 1e6)
+                    frames += 1
+                    lastCapture = now
+                } catch {
+                    FileHandle.standardError.write("simframed: capture failed: \(error)\n".data(using: .utf8)!)
+                    Thread.sleep(forTimeInterval: 0.5)
+                }
+            }
+
+            let wall = Date().timeIntervalSince1970
+            if wall - lastReport >= 1 {
+                let sorted = latencies.sorted()
+                let median = sorted.isEmpty ? 0 : sorted[sorted.count / 2]
+                FileHandle.standardError.write(
+                    String(format: "simframed: %.1f fps, median %.2fms\n", Double(frames) / (wall - lastReport), median)
+                        .data(using: .utf8)!)
+                frames = 0; latencies.removeAll(); lastReport = wall
+            }
+
+            if stopping {
+                FileHandle.standardError.write("simframed: stopping\n".data(using: .utf8)!)
+                break
+            }
+            if store.heartbeatAge() > idleExitMs {
+                FileHandle.standardError.write("simframed: exiting, no client heartbeat\n".data(using: .utf8)!)
+                break
+            }
+            if !store.stillOwner() {
+                FileHandle.standardError.write("simframed: exiting, superseded by another capture loop\n".data(using: .utf8)!)
+                break
+            }
+            // The damage callback is delivered on a framework queue, so the
+            // main thread only needs to wake often enough to notice.
+            RunLoop.current.run(until: Date().addingTimeInterval(0.01))
+        }
+    } catch { fail("\(error)") }
+
+default:
+    fail("unknown command '\(command)' (try: devices, hash, bench, snap, run, input, tap, swipe, type, press)")
+}

package/native/simframed/Tests/SimframeCoreTests/HashingTests.swift

@@ -0,0 +1,240 @@
+import XCTest
+import PrivateAPI
+@testable import SimframeCore
+
+/// These run without a simulator, against StubPlatform, so the pure logic is
+/// testable on any machine — including CI, which has no booted device.
+final class HashingTests: XCTestCase {
+
+    private func solid(_ w: Int, _ h: Int, _ v: UInt8) -> Bitmap {
+        var data = [UInt8](repeating: 0, count: w * h * 4)
+        for i in stride(from: 0, to: data.count, by: 4) {
+            data[i] = v; data[i + 1] = v; data[i + 2] = v; data[i + 3] = 255
+        }
+        return Bitmap(width: w, height: h, data: data)
+    }
+
+    private func split(_ w: Int, _ h: Int, left: UInt8, right: UInt8) -> Bitmap {
+        var data = [UInt8](repeating: 0, count: w * h * 4)
+        for y in 0..<h {
+            for x in 0..<w {
+                let v = x < w / 2 ? left : right
+                let i = (y * w + x) * 4
+                data[i] = v; data[i + 1] = v; data[i + 2] = v; data[i + 3] = 255
+            }
+        }
+        return Bitmap(width: w, height: h, data: data)
+    }
+
+    func testFitMatchesSipsLongEdgeBehaviour() {
+        // The real device shapes this has to reproduce.
+        XCTAssertEqual(Bitmap.fit(width: 1206, height: 2622, longEdge: 700).0, 322)
+        XCTAssertEqual(Bitmap.fit(width: 1206, height: 2622, longEdge: 700).1, 700)
+        XCTAssertEqual(Bitmap.fit(width: 2064, height: 2752, longEdge: 700).0, 525)
+        XCTAssertEqual(Bitmap.fit(width: 2064, height: 2752, longEdge: 700).1, 700)
+        // Smaller than the target is left alone rather than upscaled.
+        XCTAssertEqual(Bitmap.fit(width: 100, height: 200, longEdge: 700).1, 200)
+    }
+
+    func testGrayGridAveragesToLuminance() {
+        XCTAssertEqual(Hashing.grayGrid(solid(20, 20, 255), cols: 2, rows: 2), [255, 255, 255, 255])
+        XCTAssertEqual(Hashing.grayGrid(solid(20, 20, 0), cols: 2, rows: 2), [0, 0, 0, 0])
+    }
+
+    func testIdenticalScreensHashIdentically() {
+        let a = split(64, 128, left: 20, right: 220)
+        let b = split(64, 128, left: 20, right: 220)
+        XCTAssertEqual(Hashing.frameHash(a), Hashing.frameHash(b))
+        XCTAssertEqual(Hashing.layoutHash(a), Hashing.layoutHash(b))
+        XCTAssertEqual(Hashing.signatureDiff(Hashing.regionSignature(a), Hashing.regionSignature(b)), 0)
+    }
+
+    func testMirroredLayoutIsFarAway() {
+        let a = split(64, 128, left: 20, right: 220)
+        let b = split(64, 128, left: 220, right: 20)
+        // Well beyond the tolerance of 12 the screen memory uses.
+        XCTAssertGreaterThan(Hashing.hashDistance(Hashing.layoutHash(a), Hashing.layoutHash(b)), 20)
+    }
+
+    func testHashesAreTheExpectedWidth() {
+        let bmp = split(64, 128, left: 20, right: 220)
+        XCTAssertEqual(Hashing.frameHash(bmp).count, 32, "128 bits as 32 hex characters")
+        XCTAssertEqual(Hashing.layoutHash(bmp).count, 72, "288 bits as 72 hex characters")
+        XCTAssertEqual(Hashing.signatureToHex(Hashing.regionSignature(bmp)).count, 64)
+    }
+
+    func testSignatureDiffTreatsMissingBaselineAsFullChange() {
+        XCTAssertEqual(Hashing.signatureDiff(Hashing.regionSignature(solid(8, 8, 100)), nil), 1)
+    }
+
+    func testHashDistanceCountsBits() {
+        XCTAssertEqual(Hashing.hashDistance("abcd", "abcd"), 0)
+        XCTAssertEqual(Hashing.hashDistance("0", "f"), 4)
+        XCTAssertEqual(Hashing.hashDistance("abc", "abcd"), Int.max, "different widths are incomparable")
+    }
+
+    func testStubPlatformProducesReadablePaddedFrames() throws {
+        let stub = StubPlatform(width: 120, height: 260)
+        _ = try stub.attach(udid: nil)
+        let bmp = try stub.withFrame { frame -> Bitmap in
+            // The stub pads its rows on purpose: honouring bytesPerRow is the
+            // single easiest thing to get wrong against a real surface.
+            XCTAssertEqual(frame.bytesPerRow, frame.width * 4 + 40)
+            return Bitmap.from(frame, targetLongEdge: 130)
+        }
+        XCTAssertEqual(bmp.height, 130)
+        XCTAssertEqual(bmp.width, 60)
+        // Left half dark, right half light — a shear from bad padding would blur this.
+        let leftPixel = Int(bmp.data[(65 * bmp.width + 5) * 4])
+        let rightPixel = Int(bmp.data[(65 * bmp.width + bmp.width - 5) * 4])
+        XCTAssertLessThan(leftPixel, 100)
+        XCTAssertGreaterThan(rightPixel, 150)
+    }
+
+    func testChangeIsDetectedAcrossStubFrames() throws {
+        let stub = StubPlatform(width: 80, height: 160)
+        _ = try stub.attach(udid: nil)
+        let before = try stub.withFrame { Hashing.regionSignature(Bitmap.from($0, targetLongEdge: 80)) }
+        stub.simulateChange()
+        let after = try stub.withFrame { Hashing.regionSignature(Bitmap.from($0, targetLongEdge: 80)) }
+        XCTAssertGreaterThan(Hashing.signatureDiff(after, before), 0.004)
+    }
+}
+
+/// The Platform surface, exercised through StubPlatform so gestures and app
+/// lifecycle can be tested with no simulator and no private frameworks.
+final class PlatformSurfaceTests: XCTestCase {
+    private func stub() throws -> StubPlatform {
+        let s = StubPlatform(width: 120, height: 260)
+        _ = try s.attach(udid: nil)
+        return s
+    }
+
+    func testGesturesReachThePlatform() throws {
+        let s = try stub()
+        try s.tap(at: CGPoint(x: 10, y: 20), durationMs: 70)
+        try s.longPress(at: CGPoint(x: 30, y: 40), durationMs: 600)
+        try s.drag(from: CGPoint(x: 1, y: 2), to: CGPoint(x: 3, y: 4), holdMs: 500, durationMs: 400)
+        try s.swipe(from: CGPoint(x: 5, y: 6), to: CGPoint(x: 7, y: 8), durationMs: 300)
+        XCTAssertEqual(s.recorded, [
+            "tap(10,20)",
+            "longPress(30,40,600)",
+            "drag(1,2->3,4,hold=500)",
+            "swipe(5,6->7,8)",
+        ])
+    }
+
+    func testAppLifecycleReachesThePlatform() throws {
+        let s = try stub()
+        _ = try s.launch(bundleId: "com.example.app", arguments: ["-a"], environment: ["K": "V"])
+        try s.terminate(bundleId: "com.example.app")
+        try s.openURL("myapp://x")
+        try s.permission(action: "grant", service: "photos", bundleId: "com.example.app")
+        XCTAssertEqual(s.recorded, [
+            "launch(com.example.app)",
+            "terminate(com.example.app)",
+            "openURL(myapp://x)",
+            "permission(grant,photos,com.example.app)",
+        ])
+    }
+
+    func testTextRoutesAreDistinct() throws {
+        let s = try stub()
+        try s.type("abc")
+        try s.paste("abc")
+        // Two different mechanisms: key events are layout-dependent, paste is not.
+        XCTAssertEqual(s.recorded, ["type(abc)", "paste(abc)"])
+    }
+
+    func testAsciiIsTypeableAndEmojiIsNot() {
+        XCTAssertTrue(HIDKeyboard.canType("Fryer 3!"))
+        XCTAssertFalse(HIDKeyboard.canType("Fryer 🍟"), "emoji has no usage code and must go via paste")
+    }
+
+    func testOnlyVerifiedButtonsHaveCodes() {
+        XCTAssertEqual(HIDKeyboard.buttonCode(.home), 2)
+        // Unverified codes must refuse rather than guess: a wrong Indigo button
+        // can crash backboardd or lock the device.
+        for button in [HardwareButton.lock, .siri, .volumeUp, .volumeDown] {
+            XCTAssertNil(HIDKeyboard.buttonCode(button), "\(button.rawValue) is not verified")
+        }
+    }
+}
+
+/// Motion analysis, on synthetic frames so the expected answer is known.
+final class MotionTests: XCTestCase {
+    private func grid(_ fill: (Int, Int) -> UInt8) -> [UInt8] {
+        var g = [UInt8](repeating: 0, count: Motion.cols * Motion.rows)
+        for r in 0..<Motion.rows { for c in 0..<Motion.cols { g[r * Motion.cols + c] = fill(c, r) } }
+        return g
+    }
+
+    /// Content that varies in both directions, so a shift has a unique best
+    /// match. Horizontally uniform content makes every horizontal offset score
+    /// identically, and the search then reports an arbitrary one.
+    private func striped(offsetRows: Int = 0) -> [UInt8] {
+        grid { c, r in UInt8((((r + offsetRows) * 13) + c * 7) % 256) }
+    }
+
+    func testIdenticalFramesAreStill() {
+        XCTAssertEqual(Motion.difference(striped(), striped()), 0)
+    }
+
+    func testSettleNeedsConsecutiveStillFrames() {
+        let still = striped()
+        var history: [Motion.Frame] = []
+        for i in 0..<5 { history.append(Motion.Frame(at: Double(i) * 100, gray: still)) }
+        let state = Motion.state(history: history, now: 500)
+        XCTAssertTrue(state.settled)
+        XCTAssertGreaterThanOrEqual(state.stillFrames, Motion.stillFramesRequired)
+    }
+
+    func testAChangingScreenIsNotSettled() {
+        var history: [Motion.Frame] = []
+        for i in 0..<5 { history.append(Motion.Frame(at: Double(i) * 100, gray: striped(offsetRows: i * 6))) }
+        XCTAssertFalse(Motion.state(history: history, now: 500).settled)
+    }
+
+    func testSpinnerIsNeitherStillNorASceneChange() {
+        // Everything holds still except a small patch that keeps changing.
+        var history: [Motion.Frame] = []
+        for i in 0..<5 {
+            var g = striped()
+            for r in 40..<45 { for c in 20..<25 { g[r * Motion.cols + c] = UInt8((i * 90) % 256) } }
+            history.append(Motion.Frame(at: Double(i) * 100, gray: g))
+        }
+        let state = Motion.state(history: history, now: 500)
+        XCTAssertFalse(state.settled, "a spinner must not read as settled")
+        XCTAssertNotNil(state.animatingRegion, "the moving patch should be localised")
+    }
+
+    func testVerticalShiftIsMeasured() {
+        let (dx, dy, score) = Motion.shift(striped(), striped(offsetRows: 8))
+        XCTAssertEqual(dy, -8, "content moved up by eight rows")
+        XCTAssertEqual(dx, 0)
+        XCTAssertLessThan(score, 0.02)
+    }
+
+    func testScrollIsClassifiedWithAnOffset() throws {
+        let t = Motion.classify(before: striped(), after: striped(offsetRows: 8),
+                                pointHeight: 874, pointWidth: 402)
+        XCTAssertEqual(t.kind, .scroll)
+        // XCTUnwrap rather than `!`: a force unwrap here kills the whole test
+        // process with signal 5 and hides every other result.
+        let offset = try XCTUnwrap(t.offset)
+        // Eight of ninety-six rows of an 874pt screen.
+        XCTAssertEqual(offset.y, -874 * 8 / 96, accuracy: 1)
+    }
+
+    func testIdenticalScreensClassifyAsNoChange() {
+        let t = Motion.classify(before: striped(), after: striped(), pointHeight: 874, pointWidth: 402)
+        XCTAssertEqual(t.kind, .none)
+    }
+
+    func testDimmingTheWholeScreenReadsAsSomethingPresenting() {
+        let base = striped()
+        let dimmed = base.map { UInt8(max(0, Int($0) - 60)) }
+        let t = Motion.classify(before: base, after: dimmed, pointHeight: 874, pointWidth: 402)
+        XCTAssertTrue([.sheetPresent, .alertPresent].contains(t.kind), "got \(t.kind)")
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simframe",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "mcpName": "io.github.lvlrSajjad/simframe",
   "description": "Always-warm iOS Simulator frames: agents read the screen in ~20ms instead of waiting on screenshots. MCP server + CLI.",
   "keywords": [
@@ -40,14 +40,20 @@
   },
   "files": [
     "src",
-    "native",
+    "native/ocr.swift",
+    "native/simframed/Package.swift",
+    "native/simframed/Sources",
+    "native/simframed/Tests",
+    "scripts",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test test/unit.test.mjs",
+    "test": "SIMFRAME_HOME=\"$(mktemp -d)\" node --test test/unit.test.mjs",
     "mcp": "node src/cli.js mcp",
-    "smoke": "node scripts/smoke.mjs"
+    "smoke": "node scripts/smoke.mjs",
+    "bench": "./scripts/bench.sh",
+    "check:package": "node scripts/check-package.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0"