@mentra/bluetooth-sdk 3.3.0-dev.317 → 3.3.0-dev.320

package/ios/Source/sgcs/NimoCanvasCodec.swift

@@ -0,0 +1,269 @@
+import Foundation
+import zlib
+
+/// Dynamic Layout V1, shared with the Android NIMO adapter. All limits are checked
+/// before sending anything; an invalid scene leaves the last accepted scene intact.
+enum NimoCanvasCodec {
+    static let width = 500
+    static let height = 220
+    static let maxStream = 12288
+    static let appId = 0xFD
+    static let lineHeight = 20
+
+    enum Invalid: Error { case value(String) }
+
+    static func require(_ condition: Bool, _ message: String = "Invalid canvas value") throws {
+        if !condition { throw Invalid.value(message) }
+    }
+
+    struct Object {
+        let type: Int
+        let payload: Data
+        var textBytes = 0
+        var pixels = 0
+    }
+
+    static func imageBytes(_ input: String) throws -> Data {
+        try require(input.utf8.count <= 2_800_000, "Encoded image exceeds limit")
+        var encoded = input
+        var mime: String?
+        for kind in ["png", "bmp", "jpeg"] where input.hasPrefix("data:image/\(kind);base64,") {
+            mime = kind
+            encoded = String(input.dropFirst("data:image/\(kind);base64,".count))
+        }
+        try require(!input.hasPrefix("data:") || mime != nil, "Unsupported image data URI")
+        try require(encoded.utf8.count % 4 == 0, "Base64 must be padded")
+        guard let data = Data(base64Encoded: encoded) else { throw Invalid.value("Invalid Base64") }
+        try require((24 ... 2_000_000).contains(data.count), "Image file exceeds limit")
+        let png = data.prefix(8) == Data([0x89, 0x50, 0x4E, 0x47, 13, 10, 26, 10])
+        let bmp = data.count >= 54 && data.prefix(2) == Data([0x42, 0x4D])
+        let jpeg = data.prefix(3) == Data([0xFF, 0xD8, 0xFF])
+        let kind: String? = png ? "png" : bmp ? "bmp" : jpeg ? "jpeg" : nil
+        try require(kind != nil && (mime == nil || mime == kind), "Image must be PNG, BMP or JPEG matching its MIME type")
+        return data
+    }
+
+    static func region(_ x: Int, _ y: Int, _ w: Int, _ h: Int) throws {
+        try require((0 ..< width).contains(x) && (0 ..< height).contains(y)
+            && (1 ... width).contains(w) && (1 ... height).contains(h))
+        try require(x + w <= width && y + h <= height, "Region exceeds 500x220")
+    }
+
+    static func line(_ x0: Int, _ y0: Int, _ x1: Int, _ y1: Int, stroke: Int = 1, intensity: Int = 255) throws -> Object {
+        try region(x0, y0, 1, 1)
+        try region(x1, y1, 1, 1)
+        try require((1 ... 32).contains(stroke) && (0 ... 255).contains(intensity))
+        return Object(type: 0, payload: words(x0, y0, x1, y1) + bytes(stroke, intensity))
+    }
+
+    static func rectangle(_ x: Int, _ y: Int, _ w: Int, _ h: Int, stroke: Int = 1,
+                          radius: Int = 0, intensity: Int = 255, filled: Bool = false) throws -> Object
+    {
+        try region(x, y, w, h)
+        try require((0 ... 32).contains(stroke) && (0 ... 255).contains(radius) && (0 ... 255).contains(intensity))
+        return Object(type: 1, payload: words(x, y, w, h) + bytes(stroke, radius, intensity, filled ? 1 : 0))
+    }
+
+    static func circle(_ x: Int, _ y: Int, radius: Int, stroke: Int = 1, intensity: Int = 255, filled: Bool = false) throws -> Object {
+        try require((1 ... 110).contains(radius))
+        try region(x, y, 1, 1)
+        try require(x - radius >= 0 && y - radius >= 0 && x + radius < width && y + radius < height)
+        try require((0 ... 32).contains(stroke) && (0 ... 255).contains(intensity))
+        return Object(type: 2, payload: words(x, y, radius) + bytes(stroke, intensity, filled ? 1 : 0))
+    }
+
+    static func label(_ text: String, _ x: Int, _ y: Int, _ w: Int, _ h: Int,
+                      font: Int = 0, language: Int = 0, intensity: Int = 255) throws -> Object
+    {
+        try region(x, y, w, h)
+        try require((0 ... 3).contains(font) && (0 ... 20).contains(language) && (0 ... 255).contains(intensity))
+        let utf8 = Data(text.utf8)
+        try require((1 ... 2048).contains(utf8.count) && !utf8.contains(0), "Label exceeds 2048 UTF-8 bytes or contains NUL")
+        return Object(type: 3, payload: words(x, y, w, h, language) + bytes(font, intensity) + words(utf8.count) + utf8,
+                      textBytes: utf8.count)
+    }
+
+    /// Empty rows still consume vertical space. The host already wrapped each row.
+    static func textRows(_ text: String, _ x: Int, _ y: Int, _ w: Int, _ h: Int) throws -> [Object] {
+        try region(x, y, w, h)
+        try require(text.utf16.count <= 8192 && !text.utf8.contains(0))
+        let rows = text.components(separatedBy: "\n")
+        try require(rows.count <= 64)
+        return try rows.enumerated().compactMap { index, row in
+            let offset = index * lineHeight
+            guard offset < h, !row.isEmpty else { return nil }
+            return try label(row, x, y + offset, w, min(lineHeight, h - offset))
+        }
+    }
+
+    static func text(_ text: String, _ x: Int, _ y: Int, _ w: Int, _ h: Int, border: Int, radius: Int) throws -> [Object] {
+        try region(x, y, w, h)
+        try require((0 ... 32).contains(border) && (0 ... 255).contains(radius))
+        var objects: [Object] = []
+        if border > 0 { try objects.append(rectangle(x, y, w, h, stroke: border, radius: radius)) }
+        if !text.isEmpty, !text.contains("\n") {
+            try objects.append(label(text, x, y, w, h))
+        } else {
+            objects += try textRows(text, x, y, w, h)
+        }
+        return objects
+    }
+
+    /// 00=white, 11=black. Pack continuously across rows; pad with black.
+    static func pack2(_ gray: Data) throws -> Data {
+        try require((1 ... 110_000).contains(gray.count))
+        var output = Data(repeating: 0xFF, count: (gray.count + 3) / 4)
+        for (i, value) in gray.enumerated() {
+            let shift = 6 - 2 * (i % 4)
+            let code = min(3, (255 - Int(value) + 42) / 85)
+            output[i / 4] = (output[i / 4] & ~UInt8(3 << shift)) | UInt8(code << shift)
+        }
+        return output
+    }
+
+    static func rle(_ data: Data) throws -> Data {
+        try require(data.count <= 110_000)
+        let input = [UInt8](data)
+        var output = Data()
+        var i = 0
+        func run(_ start: Int) -> Int {
+            var n = 1
+            while start + n < input.count, n < 127, input[start + n] == input[start] {
+                n += 1
+            }
+            return n
+        }
+        while i < input.count {
+            let count = run(i)
+            if count >= 3 {
+                output.append(contentsOf: [UInt8(count), input[i]])
+                i += count
+            } else {
+                let start = i
+                i += count
+                while i < input.count, i - start < 127 {
+                    let next = run(i)
+                    if next >= 3 { break }
+                    i += min(next, 127 - (i - start))
+                }
+                output.append(UInt8(0x80 | (i - start)))
+                output.append(contentsOf: input[start ..< i])
+            }
+        }
+        return output
+    }
+
+    static func bitmap(_ x: Int, _ y: Int, _ w: Int, _ h: Int, gray: Data) throws -> Object {
+        try region(x, y, w, h)
+        try require(gray.count == w * h)
+        let packed = try pack2(gray)
+        let runs = try rle(packed)
+        let compressed = try zlib(packed)
+        let compression = runs.count <= compressed.count ? 3 : 7
+        let body = compression == 3 ? runs : compressed
+        let packet = bytes(0) + words(w, h) + bytes(2, compression) + dword(packed.count) + dword(body.count) + body
+        try require(packet.count <= 65535)
+        return Object(type: 4, payload: words(x, y, w, h, 0, 1, packet.count) + packet, pixels: gray.count)
+    }
+
+    static func scene(_ elements: [SceneElement], decodeImage: (String, Int, Int) throws -> Data) throws -> Data {
+        try require(elements.count <= 64)
+        var pixels = 0
+        // Validate every region and the aggregate image budget before decoding any image.
+        for e in elements {
+            try region(Int(e.x), Int(e.y), Int(e.w), Int(e.h))
+            try require(["text", "rect", "image"].contains(e.type)
+                && (0 ... 32).contains(e.border) && (0 ... 255).contains(e.radius))
+            if e.type == "image" {
+                try require(e.data != nil)
+                pixels += Int(e.w) * Int(e.h)
+                try require(pixels <= 110_000, "Frame exceeds image pixel budget")
+            }
+        }
+        var objects: [Object] = []
+        for e in elements {
+            let (x, y, w, h) = (Int(e.x), Int(e.y), Int(e.w), Int(e.h))
+            switch e.type {
+            case "text":
+                if e.border > 0 { try objects.append(rectangle(x, y, w, h, stroke: Int(e.border), radius: Int(e.radius))) }
+                objects += try textRows(e.text ?? "", x, y, w, h)
+            case "rect": try objects.append(rectangle(x, y, w, h, stroke: max(1, Int(e.border)), radius: Int(e.radius)))
+            case "image": try objects.append(bitmap(x, y, w, h, gray: decodeImage(e.data!, w, h)))
+            default: break // Validated above.
+            }
+            try require(objects.count <= 64)
+        }
+        return try replace(objects)
+    }
+
+    static func replace(_ objects: [Object]) throws -> Data {
+        try require(objects.count <= 64, "More than 64 canvas objects")
+        try require(objects.reduce(0) { $0 + $1.textBytes } <= 8192, "Frame text exceeds 8192 bytes")
+        try require(objects.reduce(0) { $0 + $1.pixels } <= 110_000, "Frame exceeds image pixel budget")
+        try require(3 + objects.reduce(0) { $0 + 3 + $1.payload.count } <= maxStream - 8, "Frame exceeds reassembly budget")
+        var output = words(objects.count) + bytes(1)
+        for object in objects {
+            try require((0 ... 4).contains(object.type))
+            output += bytes(object.type) + words(object.payload.count) + object.payload
+        }
+        return output
+    }
+
+    static func frames(key: Int, content: Data = Data(), writeCapacity: Int) throws -> [Data] {
+        try require((20 ... 512).contains(writeCapacity))
+        let payload: Data
+        switch key {
+        case 1: payload = bytes(appId, 0)
+        case 3: payload = bytes(appId)
+        case 4: payload = bytes(appId, 0, 0, 0) + content
+        default: throw Invalid.value("Unsupported canvas command")
+        }
+        try require(payload.count + 4 <= maxStream)
+        let stream = bytes(7, key) + words(payload.count) + payload
+        let chunkSize = writeCapacity - 8
+        let count = (stream.count + chunkSize - 1) / chunkSize
+        return (0 ..< count).map { index in
+            let chunk = stream.subdata(in: index * chunkSize ..< min(stream.count, (index + 1) * chunkSize))
+            return bytes(0xBF, 0) + words(chunk.count, Int(nimoCrc16(chunk)), index == count - 1 ? 0 : index + 1) + chunk
+        }
+    }
+
+    /// Canvas responses count the status byte in the application payload length.
+    static func response(_ packet: Data) -> (key: Int, payload: Data)? {
+        let packet = Data(packet)
+        guard packet.count >= 13, packet[0] == 0xBF, packet[1] == 0 else { return nil }
+        func word(_ i: Int) -> Int {
+            Int(packet[i]) | (Int(packet[i + 1]) << 8)
+        }
+        guard word(2) == packet.count - 8, word(6) == 0, packet[8] == 7,
+              word(4) == Int(nimoCrc16(packet.subdata(in: 8 ..< packet.count))),
+              word(10) == packet.count - 12, [1, 3, 4].contains(Int(packet[9])) else { return nil }
+        return (Int(packet[9]), packet.subdata(in: 12 ..< packet.count))
+    }
+
+    private static func zlib(_ input: Data) throws -> Data {
+        var size = compressBound(uLong(input.count))
+        var output = Data(count: Int(size))
+        let status = output.withUnsafeMutableBytes { dst in
+            input.withUnsafeBytes { src in
+                compress2(dst.bindMemory(to: UInt8.self).baseAddress!, &size,
+                          src.bindMemory(to: UInt8.self).baseAddress!, uLong(input.count), 6)
+            }
+        }
+        try require(status == Z_OK, "Image compression failed")
+        output.count = Int(size)
+        return output
+    }
+
+    private static func bytes(_ values: Int...) -> Data {
+        Data(values.map { UInt8(truncatingIfNeeded: $0) })
+    }
+
+    private static func words(_ values: Int...) -> Data {
+        Data(values.flatMap { [UInt8(truncatingIfNeeded: $0), UInt8(truncatingIfNeeded: $0 >> 8)] })
+    }
+
+    private static func dword(_ value: Int) -> Data {
+        bytes(value, value >> 8, value >> 16, value >> 24)
+    }
+}

package/ios/Source/sgcs/NimoCanvasCoordinator.swift

@@ -0,0 +1,219 @@
+import Foundation
+
+typealias NimoScheduler = (TimeInterval, @escaping () -> Void) -> () -> Void
+
+/// All callers run on Main, including the injected scheduler and transport callbacks.
+final class NimoCanvasCoordinator {
+    private final class Flight {
+        let key: Int
+        var finalStarted = false
+        var complete = false
+        var earlyAck: Data?
+        init(key: Int) {
+            self.key = key
+        }
+    }
+
+    private let schedule: NimoScheduler
+    private let writeCapacity: () -> Int
+    private let enqueue: ([Data], @escaping () -> Void, @escaping () -> Void) -> Bool
+    private let reconnect: (String) -> Void
+    private let rejected: (Int) -> Void
+    private let session = NimoCanvasSession()
+    private var flight: Flight?
+    private var cancelDeadline: (() -> Void)?
+
+    init(schedule: @escaping NimoScheduler, writeCapacity: @escaping () -> Int,
+         enqueue: @escaping ([Data], @escaping () -> Void, @escaping () -> Void) -> Bool,
+         reconnect: @escaping (String) -> Void, rejected: @escaping (Int) -> Void)
+    {
+        self.schedule = schedule; self.writeCapacity = writeCapacity; self.enqueue = enqueue
+        self.reconnect = reconnect; self.rejected = rejected
+    }
+
+    func offer(_ bytes: Data, scope: String, force: Bool = false) {
+        run(session.offer(bytes, scope: scope, force: force))
+    }
+
+    func readiness(_ value: Bool, confirmed: Bool = false) {
+        run(session.readiness(value, confirmed: confirmed))
+    }
+
+    func exit() {
+        run(session.exit())
+    }
+
+    /// An expected Exit report must not discard a newer host encode queued behind Exit.
+    func nativeApp(_ appId: Int, entered: Bool) -> Bool {
+        let takeover = (appId == NimoCanvasCodec.appId && !entered) || (appId != NimoCanvasCodec.appId && entered)
+        let expectedExit = appId == NimoCanvasCodec.appId && !entered && flight?.key == 3
+        run(session.nativeApp(appId, entered: entered))
+        return takeover && !expectedExit
+    }
+
+    func disconnected() {
+        cancelDeadline?(); cancelDeadline = nil
+        flight = nil
+        session.disconnected()
+    }
+
+    func response(key: Int, payload: Data) {
+        guard let current = flight, session.acceptsResponse(key: key, payload: payload) else { return }
+        if !current.complete {
+            if current.finalStarted, current.earlyAck == nil { current.earlyAck = payload }
+            return
+        }
+        cancelDeadline?(); cancelDeadline = nil
+        flight = nil
+        run(session.response(key: key, payload: payload))
+    }
+
+    private func run(_ actions: [NimoCanvasSession.Action]) {
+        for action in actions {
+            switch action {
+            case let .send(key, frame, ticket):
+                cancelDeadline?()
+                let current = Flight(key: key)
+                flight = current
+                cancelDeadline = schedule(45) { [weak self] in
+                    guard let self, self.flight === current else { return }
+                    self.run(self.session.timeout(ticket))
+                }
+                do {
+                    let frames = try NimoCanvasCodec.frames(key: key, content: frame, writeCapacity: writeCapacity())
+                    let queued = enqueue(frames, { [weak self] in
+                        if self?.flight === current { current.finalStarted = true }
+                    }, { [weak self] in
+                        guard let self, self.flight === current else { return }
+                        current.complete = true
+                        if let ack = current.earlyAck { self.response(key: key, payload: ack) }
+                    })
+                    if !queued, flight === current { disconnected(); reconnect("Canvas transport unavailable") }
+                } catch {
+                    disconnected(); reconnect("Canvas framing failed: \(error)")
+                }
+            case let .reconnect(reason): disconnected(); reconnect(reason)
+            case let .rejected(status): rejected(status)
+            }
+        }
+    }
+}
+
+/// Serializes characteristic writes. A missing callback retires the link instead
+/// of allowing a late callback to acknowledge a different fragment.
+final class NimoWriteQueue<Characteristic: AnyObject> {
+    private final class Write {
+        let characteristic: Characteristic
+        let bytes: Data
+        let started: () -> Void
+        let completed: () -> Void
+        var callbackReceived = false
+        init(_ characteristic: Characteristic, _ bytes: Data, _ started: @escaping () -> Void, _ completed: @escaping () -> Void) {
+            self.characteristic = characteristic; self.bytes = bytes; self.started = started; self.completed = completed
+        }
+    }
+
+    private let schedule: NimoScheduler
+    private let write: (Characteristic, Data) -> Bool
+    private let failure: (String) -> Void
+    private var connection: AnyObject?
+    private var generation: UInt64 = 0
+    private var queue: [Write] = []
+    private var current: Write?
+    private var cancelDeadline: (() -> Void)?
+
+    init(schedule: @escaping NimoScheduler, write: @escaping (Characteristic, Data) -> Bool, failure: @escaping (String) -> Void) {
+        self.schedule = schedule; self.write = write; self.failure = failure
+    }
+
+    func connected(_ connection: AnyObject) {
+        reset(); self.connection = connection
+    }
+
+    func reset() {
+        generation &+= 1
+        connection = nil; current = nil; queue.removeAll()
+        cancelDeadline?(); cancelDeadline = nil
+    }
+
+    @discardableResult
+    func enqueue(_ connection: AnyObject, characteristic: Characteristic, frames: [Data],
+                 finalStarted: @escaping () -> Void = {}, completed: @escaping () -> Void = {}) -> Bool
+    {
+        guard connection === self.connection, !frames.isEmpty else { return false }
+        guard queue.count + frames.count <= 1100 else { fail("Fragment chain exceeds write budget"); return false }
+        for (i, frame) in frames.enumerated() {
+            let last = i == frames.count - 1
+            queue.append(Write(characteristic, frame, last ? finalStarted : {}, last ? completed : {}))
+        }
+        drain()
+        return true
+    }
+
+    func written(_ connection: AnyObject, characteristic: Characteristic, success: Bool) {
+        guard connection === self.connection, let item = current,
+              characteristic === item.characteristic, !item.callbackReceived else { return }
+        item.callbackReceived = true
+        cancelDeadline?(); cancelDeadline = nil
+        guard success else { fail("GATT write failed"); return }
+        let expected = generation
+        _ = schedule(0.005) { [weak self] in
+            guard let self, self.generation == expected, self.current === item else { return }
+            self.current = nil
+            item.completed()
+            self.drain()
+        }
+    }
+
+    private func drain() {
+        guard connection != nil, current == nil, !queue.isEmpty else { return }
+        let item = queue.removeFirst()
+        current = item
+        let expected = generation
+        guard write(item.characteristic, item.bytes) else { fail("GATT transport unavailable"); return }
+        item.started()
+        cancelDeadline = schedule(3) { [weak self] in
+            guard let self, self.generation == expected, self.current === item, !item.callbackReceived else { return }
+            self.fail("GATT write timed out")
+        }
+    }
+
+    private func fail(_ reason: String) {
+        reset(); failure(reason)
+    }
+}
+
+/// Coalesces pending encodes and fences running results on scene change, Exit and disconnect.
+final class NimoCanvasEncoder {
+    private let worker: NimoScheduler
+    private let main: NimoScheduler
+    private let failure: (Error) -> Void
+    private var generation: UInt64 = 0
+    private var cancelPending: (() -> Void)?
+
+    init(main: @escaping NimoScheduler, worker: @escaping NimoScheduler, failure: @escaping (Error) -> Void) {
+        self.main = main; self.worker = worker; self.failure = failure
+    }
+
+    /// submit/invalidate and delivery run on Main; the worker only reads its captured request.
+    func submit(encode: @escaping () throws -> Data, deliver: @escaping (Data) -> Void) {
+        invalidate()
+        let expected = generation
+        cancelPending = worker(0) { [weak self] in
+            let result = Result { try encode() }
+            guard let self else { return }
+            _ = self.main(0) { [weak self] in
+                guard let self, self.generation == expected else { return }
+                self.cancelPending = nil
+                switch result {
+                case let .success(bytes): deliver(bytes)
+                case let .failure(error): self.failure(error)
+                }
+            }
+        }
+    }
+
+    func invalidate() {
+        generation &+= 1; cancelPending?(); cancelPending = nil
+    }
+}

package/ios/Source/sgcs/NimoCanvasImage.swift

@@ -0,0 +1,53 @@
+import CoreGraphics
+import Foundation
+import ImageIO
+
+/// Bounded image decoding independent of UIKit/AppKit and the Bluetooth actor.
+enum NimoCanvasImage {
+    static func source(_ input: String) throws -> CGImage {
+        let data = try NimoCanvasCodec.imageBytes(input)
+        guard let source = CGImageSourceCreateWithData(data as CFData, [kCGImageSourceShouldCache: false] as CFDictionary),
+              let properties = CGImageSourceCopyPropertiesAtIndex(source, 0, nil) as? [CFString: Any],
+              let w = properties[kCGImagePropertyPixelWidth] as? Int,
+              let h = properties[kCGImagePropertyPixelHeight] as? Int
+        else {
+            throw NimoCanvasCodec.Invalid.value("Invalid image")
+        }
+        try NimoCanvasCodec.require((1 ... 4096).contains(w) && (1 ... 4096).contains(h))
+        try NimoCanvasCodec.require(w * h <= 4_000_000, "Decoded image exceeds limit")
+        guard let image = CGImageSourceCreateImageAtIndex(source, 0, nil) else {
+            throw NimoCanvasCodec.Invalid.value("Image decode failed")
+        }
+        return image
+    }
+
+    static func decode(_ input: String, width: Int, height: Int) throws -> Data {
+        try grayscale(source(input), width: width, height: height)
+    }
+
+    static func grayscale(_ image: CGImage, width: Int, height: Int) throws -> Data {
+        try NimoCanvasCodec.region(0, 0, width, height)
+        guard let context = CGContext(data: nil, width: width, height: height, bitsPerComponent: 8,
+                                      bytesPerRow: width * 4, space: CGColorSpaceCreateDeviceRGB(),
+                                      bitmapInfo: CGBitmapInfo.byteOrder32Big.rawValue | CGImageAlphaInfo.premultipliedLast.rawValue)
+        else {
+            throw NimoCanvasCodec.Invalid.value("Image allocation failed")
+        }
+        context.setFillColor(red: 0, green: 0, blue: 0, alpha: 1)
+        context.fill(CGRect(x: 0, y: 0, width: width, height: height))
+        context.interpolationQuality = .medium
+        context.draw(image, in: CGRect(x: 0, y: 0, width: width, height: height))
+        guard let buffer = context.data?.assumingMemoryBound(to: UInt8.self) else {
+            throw NimoCanvasCodec.Invalid.value("Image buffer unavailable")
+        }
+        var gray = Data(capacity: width * height)
+        for y in 0 ..< height {
+            for x in 0 ..< width {
+                let offset = y * context.bytesPerRow + x * 4
+                let luminance = (77 * Int(buffer[offset]) + 150 * Int(buffer[offset + 1]) + 29 * Int(buffer[offset + 2]) + 128) >> 8
+                gray.append(UInt8(luminance))
+            }
+        }
+        return gray
+    }
+}

package/ios/Source/sgcs/NimoCanvasSession.swift

@@ -0,0 +1,150 @@
+import Foundation
+
+/// Serializes launch/update/exit. A business ACK means acceptance, not visible pixels.
+final class NimoCanvasSession {
+    enum Action: Equatable {
+        case send(key: Int, frame: Data, ticket: UInt64)
+        case reconnect(String)
+        case rejected(Int)
+    }
+
+    private struct Flight {
+        let key: Int
+        let frame: Data
+        let ticket: UInt64
+    }
+
+    private var ready = false
+    private var active = false
+    private var locked = false
+    private var launchBlocked = false
+    private var waitingReadiness = false
+    private var observedNotReady = false
+    private var readinessRetries = 0
+    private var exitRequested = false
+    private var desired: Data?
+    private var accepted: Data?
+    private var rejected: Data?
+    private var scope: String?
+    private var forceRevision: UInt64 = 0
+    private var sentRevision: UInt64 = 0
+    private var ticket: UInt64 = 0
+    private var flight: Flight?
+
+    func offer(_ frame: Data, scope: String, force: Bool = false) -> [Action] {
+        if self.scope != scope || force { forceRevision &+= 1 }
+        self.scope = scope
+        desired = frame
+        exitRequested = false
+        return pump()
+    }
+
+    /// Only a fresh heartbeat samples both TWS and peer Companion readiness.
+    func readiness(_ value: Bool, confirmed: Bool = false) -> [Action] {
+        if !value { readinessRetries = 0 }
+        if !value, flight != nil { return resetLink("Readiness lost during canvas command") }
+        if waitingReadiness {
+            if !value { observedNotReady = true }
+            else if !observedNotReady {
+                if !confirmed || readinessRetries >= 3 { return [] }
+                readinessRetries += 1
+            }
+        }
+        ready = value
+        if !value { active = false; accepted = nil }
+        if value { waitingReadiness = false }
+        return pump()
+    }
+
+    /// Keep only the latest desired scene across a new transport generation.
+    func disconnected() {
+        ready = false; active = false; locked = false; launchBlocked = false
+        waitingReadiness = false; observedNotReady = false; readinessRetries = 0
+        accepted = nil; rejected = nil; flight = nil
+        ticket &+= 1; forceRevision &+= 1
+    }
+
+    func exit() -> [Action] {
+        desired = nil; scope = nil; accepted = nil; rejected = nil; exitRequested = true
+        return pump()
+    }
+
+    func nativeApp(_ appId: Int, entered: Bool) -> [Action] {
+        if (appId == NimoCanvasCodec.appId && !entered) || (appId != NimoCanvasCodec.appId && entered) {
+            if flight?.key == 3 {
+                active = false; accepted = nil
+                if appId != NimoCanvasCodec.appId, entered { desired = nil; rejected = nil; scope = nil }
+                return []
+            }
+            let ambiguous = flight != nil
+            desired = nil; accepted = nil; rejected = nil; active = false; exitRequested = false; scope = nil
+            if ambiguous { return resetLink("Native app transition interrupted canvas command") }
+        }
+        return []
+    }
+
+    func acceptsResponse(key: Int, payload: Data) -> Bool {
+        guard let current = flight, current.key == key, let status = payload.first else { return false }
+        let echo = key == 4 ? Data([0, 0xFD, 0, 0, 0]) : Data([0, 0xFD])
+        if status == 0 { return payload == echo }
+        return payload.count == 1 || (payload.count == echo.count && payload.dropFirst() == echo.dropFirst())
+    }
+
+    func response(key: Int, payload: Data) -> [Action] {
+        guard acceptsResponse(key: key, payload: payload), let current = flight, let first = payload.first else { return [] }
+        let status = Int(first)
+        flight = nil
+        if status != 0 {
+            switch status {
+            case 7:
+                ready = false; waitingReadiness = true; observedNotReady = false; active = false; accepted = nil
+            case 8:
+                locked = true; active = false; accepted = nil
+            case 2:
+                return [.rejected(status)] + resetLink("Canvas device timeout is ambiguous")
+            default:
+                if key == 4 { rejected = current.frame }
+                else {
+                    if key == 1 { launchBlocked = true } else { desired = nil }
+                    active = false; exitRequested = false
+                }
+            }
+            return [.rejected(status)] + pump()
+        }
+        switch key {
+        case 1: active = true
+        case 4: accepted = current.frame; rejected = nil; readinessRetries = 0
+        case 3: active = false; accepted = nil; exitRequested = false
+        default: break
+        }
+        return pump()
+    }
+
+    func timeout(_ expectedTicket: UInt64) -> [Action] {
+        guard flight?.ticket == expectedTicket else { return [] }
+        return resetLink("Canvas ACK timeout; reconnect before reusing a command key")
+    }
+
+    private func resetLink(_ reason: String) -> [Action] {
+        ready = false; active = false; accepted = nil; flight = nil
+        ticket &+= 1; forceRevision &+= 1
+        return [.reconnect(reason)]
+    }
+
+    private func pump() -> [Action] {
+        guard ready, !locked, !launchBlocked, !waitingReadiness, flight == nil else { return [] }
+        let key: Int
+        if exitRequested, active { key = 3 }
+        else if exitRequested { exitRequested = false; return [] }
+        else if desired == nil { return [] }
+        else if !active { key = 1 }
+        else if desired == rejected { return [] }
+        else if desired == accepted, sentRevision == forceRevision { return [] }
+        else { key = 4 }
+        let frame = key == 4 ? desired! : Data()
+        if key == 4 { sentRevision = forceRevision }
+        ticket &+= 1
+        flight = Flight(key: key, frame: frame, ticket: ticket)
+        return [.send(key: key, frame: frame, ticket: ticket)]
+    }
+}