@glassly/bluetooth-sdk 0.1.0-dev.98 → 0.2.8-dev.444

package/android/src/main/java/com/glassly/bluetoothsdk/sgcs/G2KeyboardBridge.kt

@@ -0,0 +1,452 @@
+package com.glassly.bluetoothsdk.sgcs
+
+import android.content.SharedPreferences
+import com.glassly.bluetoothsdk.Bridge
+import com.glassly.bluetoothsdk.DeviceStore
+import kotlinx.coroutines.CancellationException
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.launch
+import kotlin.math.min
+import kotlin.math.pow
+
+/**
+ * Owns the phone side of the CFW keyboard bridge for one G2 connection: the
+ * client, the remembered keyboard, the reconnect loop, and what the app sees
+ * (glasses-status keys plus `keyboard_*` events). The G2 driver hands it
+ * right-lens field-131 payloads and a sender for settings payloads; everything
+ * else stays in here so the driver only tracks link lifecycle.
+ *
+ * Firmware state is volatile (a lens reboot returns to stock behaviour), so
+ * the remembered keyboard is re-enabled and reconnected on every CFW
+ * detection and after every keyboard-side disconnect, with backoff. The
+ * discovered handle mapping is only valid for one connection epoch and is
+ * never persisted. All calls run on [scope] (the driver's main-thread scope).
+ */
+internal class G2KeyboardBridge(
+    private val scope: CoroutineScope,
+    private val prefs: SharedPreferences,
+    private val send: (ByteArray) -> Unit,
+) {
+    companion object {
+        const val MINIMUM_REVISION = 39
+        private const val KEY_ADDRESS = "g2_keyboard_address"
+        private const val KEY_ADDRESS_TYPE = "g2_keyboard_address_type"
+        private const val KEY_NAME = "g2_keyboard_name"
+
+        fun advertValues(advert: G2KeyboardProtocol.Advert): Map<String, Any> =
+            mapOf(
+                "address" to advert.addressText, "addressType" to advert.addressType, "name" to advert.name,
+                "hid" to advert.hid, "rssi" to advert.rssi,
+            )
+
+        /** Drop the remembered keyboard without a live driver. */
+        fun forgetSaved(prefs: SharedPreferences) {
+            prefs.edit().remove(KEY_ADDRESS).remove(KEY_ADDRESS_TYPE).remove(KEY_NAME).apply()
+            DeviceStore.apply("glasses", "keyboardSaved", false)
+            DeviceStore.apply("glasses", "keyboardName", "")
+        }
+    }
+
+    data class Saved(val address: String, val addressType: Int, val name: String)
+
+    enum class State(val value: String) {
+        IDLE("idle"), SCANNING("scanning"), CONNECTING("connecting"), PAIRING("pairing"),
+        CONFIGURING("configuring"), CONNECTED("connected"), ERROR("error"),
+    }
+
+    class BridgeException(message: String) : Exception(message)
+
+    private var client: G2KeyboardClient? = null
+    var supported = false
+        private set
+    var ready = false
+        private set
+    var state = State.IDLE
+        private set
+    private var busy = false
+    /** `busy` is held by the automatic reconnect loop (not the user). */
+    private var autoReconnecting = false
+    private var userDisconnected = false
+    private var lastError: String? = null
+    private var connectedName = ""
+    private val scanResults = ArrayList<G2KeyboardProtocol.Advert>()
+    private var reconnectJob: Job? = null
+    private var reconnectAttempt = 0
+    var saved: Saved? = loadSaved()
+        private set(value) {
+            field = value
+            val editor = prefs.edit()
+            if (value == null) {
+                editor.remove(KEY_ADDRESS).remove(KEY_ADDRESS_TYPE).remove(KEY_NAME)
+            } else {
+                editor.putString(KEY_ADDRESS, value.address).putInt(KEY_ADDRESS_TYPE, value.addressType).putString(KEY_NAME, value.name)
+            }
+            editor.apply()
+        }
+
+    private fun loadSaved(): Saved? {
+        val address = prefs.getString(KEY_ADDRESS, null) ?: return null
+        return Saved(address, prefs.getInt(KEY_ADDRESS_TYPE, 1), prefs.getString(KEY_NAME, "") ?: "")
+    }
+
+    // ---------- Link lifecycle (driven by G2) ----------
+
+    /** CFW classification landed (or changed). Re-arms the remembered keyboard. */
+    fun cfwDetected(revision: Int?) {
+        val now = (revision ?: 0) >= MINIMUM_REVISION
+        if (now != supported) Bridge.log("G2: keyboard bridge ${if (now) "available" else "unavailable"} (revision ${revision ?: 0})")
+        supported = now
+        userDisconnected = false
+        reconnectAttempt = 0
+        if (!supported) teardownClient()
+        publish()
+        if (supported && saved != null) scheduleReconnect(1_000)
+    }
+
+    /** The glasses link is gone: drop everything but the remembered keyboard. */
+    fun linkLost() {
+        supported = false
+        teardownClient()
+        publish()
+    }
+
+    /** Right-lens sid-0x09 field 131. */
+    fun accept(payload: ByteArray) {
+        client?.accept(payload)
+    }
+
+    private fun teardownClient() {
+        reconnectJob?.cancel()
+        reconnectJob = null
+        client?.close()
+        client = null
+        ready = false
+        busy = false
+        state = State.IDLE
+        lastError = null
+    }
+
+    // ---------- App-facing commands ----------
+
+    /** Five-second active scan; returns every distinct advertiser seen. */
+    suspend fun scan(): List<G2KeyboardProtocol.Advert> {
+        requireSupported()
+        interruptReconnect()
+        requireIdle()
+        busy = true
+        try {
+            val client = ensureClient()
+            scanResults.clear()
+            lastError = null
+            setState(State.SCANNING)
+            try {
+                releaseLink(client)
+                client.enable()
+                client.scan()
+                setState(State.IDLE)
+            } catch (e: Exception) {
+                if (e is CancellationException) throw e
+                fail(e)
+                throw friendly(e)
+            }
+            return scanResults.toList()
+        } finally {
+            busy = false
+        }
+    }
+
+    /** Connect, pair and subscribe a keyboard, then remember it. */
+    suspend fun connect(address: String, addressType: Int, name: String) {
+        requireSupported()
+        val bytes = G2KeyboardProtocol.addressFromText(address)
+        if (bytes == null || addressType !in 0..3) throw BridgeException("Invalid keyboard address")
+        interruptReconnect()
+        requireIdle()
+        busy = true
+        try {
+            userDisconnected = false
+            val client = ensureClient()
+            lastError = null
+            setState(State.CONNECTING)
+            try {
+                releaseLink(client)
+                client.enable()
+                client.connect(addressType, bytes)
+                setState(State.CONFIGURING)
+                val config = client.configure()
+                ready = true
+                connectedName = name
+                saved = Saved(address, addressType, name)
+                reconnectAttempt = 0
+                Bridge.log("G2: keyboard ready — ${config.inputCount} input reports, epoch ${config.epoch}")
+                setState(State.CONNECTED)
+            } catch (e: Exception) {
+                ready = false
+                if (e is CancellationException) throw e
+                fail(e)
+                throw friendly(e)
+            }
+        } finally {
+            busy = false
+        }
+    }
+
+    /**
+     * Drop the keyboard link but keep the bond and the remembered identity. No
+     * automatic reconnect until the next CFW detection or explicit connect.
+     */
+    suspend fun disconnect() {
+        userDisconnected = true
+        cancelReconnect()
+        ready = false
+        val client = client
+        if (client == null) {
+            setState(State.IDLE)
+            return
+        }
+        try {
+            client.disable()
+            setState(State.IDLE)
+        } catch (e: Exception) {
+            fail(e)
+            throw e
+        }
+    }
+
+    /** Forget the remembered keyboard. The firmware keeps its bond. */
+    suspend fun forget() {
+        runCatching { disconnect() }
+        saved = null
+        connectedName = ""
+        publish()
+    }
+
+    /** Reconnect the remembered keyboard now (an app-driven retry). */
+    suspend fun reconnect() {
+        val saved = saved ?: throw BridgeException("No remembered keyboard")
+        connect(saved.address, saved.addressType, saved.name)
+    }
+
+    suspend fun passkey(pin: Int) {
+        val client = client
+        if (client == null || pin !in 0..999_999) throw BridgeException("No pending keyboard pairing")
+        client.authenticate(pin)
+    }
+
+    suspend fun compare(accept: Boolean) {
+        val client = client ?: throw BridgeException("No pending keyboard pairing")
+        client.confirm(accept)
+    }
+
+    /** Firmware status query plus the bridge's own view. */
+    suspend fun status(): Map<String, Any> {
+        val values = statusValues().toMutableMap()
+        val client = client
+        if (client != null && supported) {
+            runCatching { client.query() }.getOrNull()?.let { status ->
+                values["firmware"] = mapOf(
+                    "enabled" to status.enabled, "conn" to status.conn, "connected" to status.connected,
+                    "encrypted" to status.encrypted, "scanning" to status.scanning,
+                )
+            }
+        }
+        return values
+    }
+
+    // ---------- Internals ----------
+
+    private fun requireSupported() {
+        if (!supported) throw BridgeException("Keyboard bridge requires Glassly CFW revision $MINIMUM_REVISION on connected G2 glasses")
+    }
+
+    private fun requireIdle() {
+        if (busy) throw BridgeException("Keyboard operation already in progress")
+    }
+
+    private fun ensureClient(): G2KeyboardClient {
+        client?.let { return it }
+        val created = G2KeyboardClient(scope, { payload, _ -> send(payload) }) { handle(it) }
+        client = created
+        return created
+    }
+
+    private fun setState(next: State) {
+        state = next
+        publish()
+    }
+
+    private fun fail(error: Throwable) {
+        lastError = error.message ?: error.toString()
+        Bridge.log("G2: keyboard error — $lastError")
+        setState(State.ERROR)
+    }
+
+    private fun cancelReconnect() {
+        reconnectJob?.cancel()
+        reconnectJob = null
+    }
+
+    /**
+     * Hand the bridge to a user-driven scan/connect: cancel a pending retry
+     * and, when an attempt is mid-flight (a sleeping keyboard keeps one busy
+     * for up to 30 s at a time), let it unwind before continuing. Without
+     * this the scan screen mostly saw "operation already in progress"
+     * whenever a keyboard was remembered.
+     */
+    private suspend fun interruptReconnect() {
+        val job = reconnectJob ?: return
+        reconnectJob = null
+        job.cancel()
+        job.join()
+    }
+
+    /**
+     * The firmware refuses SCAN/CONNECT while it still owns a keyboard slot,
+     * and an interrupted connect keeps initiating until DM close: drop the
+     * link and poll until the slot is free (close is asynchronous).
+     */
+    private suspend fun releaseLink(client: G2KeyboardClient) {
+        // DISABLE is epoch-checked and a fresh client has not seen the
+        // firmware's epoch yet (it bumps on every CONNECT); QUERY is not, and
+        // its STATUS record carries the epoch, so sync before disabling.
+        client.query()
+        client.disable()
+        ready = false
+        repeat(20) {
+            if (client.query().conn == 0) return
+            delay(150)
+        }
+        throw BridgeException("The glasses are still closing the previous keyboard link; try again in a moment")
+    }
+
+    /**
+     * Firmware BUSY almost always means the ring's own scan/reconnect holds
+     * the radio; say so instead of leaking the raw control error.
+     */
+    private fun friendly(e: Exception): Exception =
+        if (e.message?.endsWith("firmware busy") == true) {
+            BridgeException("The glasses' radio is busy (usually the ring reconnecting). Wait a few seconds and try again.")
+        } else {
+            e
+        }
+
+    private fun scheduleReconnect(delayMs: Long) {
+        cancelReconnect()
+        // The job stays in `reconnectJob` for the whole attempt so
+        // interruptReconnect() can join it.
+        reconnectJob = scope.launch {
+            delay(delayMs)
+            attemptReconnect()
+        }
+    }
+
+    private suspend fun attemptReconnect() {
+        val saved = saved
+        if (!supported || saved == null || userDisconnected || ready || busy) return
+        autoReconnecting = true
+        try {
+            connect(saved.address, saved.addressType, saved.name)
+        } catch (e: CancellationException) {
+            throw e // a user scan/connect took over
+        } catch (e: Exception) {
+            reconnectAttempt++
+            // Keyboards sleep and the ring's own scan can hold the controller
+            // (BUSY); back off to 30 s and keep trying while the glasses stay up.
+            val seconds = min(30.0, 5.0 * 2.0.pow(min(reconnectAttempt - 1, 3).toDouble()))
+            scheduleReconnect((seconds * 1000).toLong())
+        } finally {
+            autoReconnecting = false
+        }
+    }
+
+    private fun handle(event: G2KeyboardClient.Event) {
+        when (event) {
+            is G2KeyboardClient.Event.Keys -> {
+                val now = System.currentTimeMillis()
+                for (e in event.events) {
+                    Bridge.sendTypedMessage(
+                        "keyboard_key",
+                        mapOf("page" to e.page, "usage" to e.usage, "down" to e.down, "timestamp" to now),
+                    )
+                }
+            }
+            is G2KeyboardClient.Event.Advertisement -> {
+                // An active scan reports the advertisement and its scan response
+                // as separate records, and the name usually only rides in the
+                // latter: merge per address instead of keeping whichever came first.
+                val advert = event.advert
+                val i = scanResults.indexOfFirst { it.address == advert.address && it.addressType == advert.addressType }
+                val merged = if (i >= 0) {
+                    val next = scanResults[i].merging(advert)
+                    if (next == scanResults[i]) return
+                    scanResults[i] = next
+                    next
+                } else {
+                    scanResults.add(advert)
+                    advert
+                }
+                Bridge.sendTypedMessage("keyboard_advert", advertValues(merged))
+            }
+            is G2KeyboardClient.Event.StatusChanged -> {
+                if (ready && (!event.status.connected || !event.status.encrypted)) keyboardDropped("status")
+            }
+            G2KeyboardClient.Event.Gap -> Unit
+            is G2KeyboardClient.Event.Dm -> {
+                if (event.event == 0x28 || event.event == 0x2B || event.event == 0x2D) {
+                    Bridge.log("G2: keyboard DM event 0x${event.event.toString(16)} status ${event.status}")
+                    if (ready) keyboardDropped("dm")
+                }
+            }
+            G2KeyboardClient.Event.PasskeyRequest -> {
+                setState(State.PAIRING)
+                Bridge.sendTypedMessage("keyboard_pairing", mapOf("kind" to "passkey"))
+            }
+            is G2KeyboardClient.Event.PasskeyDisplay -> {
+                setState(State.PAIRING)
+                Bridge.sendTypedMessage("keyboard_pairing", mapOf("kind" to "display", "value" to event.pin))
+            }
+            is G2KeyboardClient.Event.CompareRequest -> {
+                setState(State.PAIRING)
+                Bridge.sendTypedMessage("keyboard_pairing", mapOf("kind" to "compare", "value" to event.value))
+            }
+            G2KeyboardClient.Event.ServicesChanged -> {
+                Bridge.log("G2: keyboard services changed; rediscovering")
+                ready = false
+                publish()
+                val saved = saved ?: return
+                scope.launch {
+                    busy = false
+                    runCatching { connect(saved.address, saved.addressType, saved.name) }
+                }
+            }
+            is G2KeyboardClient.Event.Error -> {
+                lastError = event.message
+                Bridge.log("G2: keyboard — ${event.message}")
+                publish()
+            }
+        }
+    }
+
+    private fun keyboardDropped(reason: String) {
+        Bridge.log("G2: keyboard disconnected ($reason)")
+        ready = false
+        setState(State.IDLE)
+        if (saved != null && !userDisconnected) scheduleReconnect(2_000)
+    }
+
+    private fun statusValues(): Map<String, Any> =
+        mapOf(
+            "keyboardBridge" to supported,
+            "keyboardConnected" to ready,
+            "keyboardName" to (if (ready) connectedName else saved?.name ?: ""),
+            "keyboardSaved" to (saved != null),
+            "keyboardState" to state.value,
+            "keyboardError" to (lastError ?: ""),
+        )
+
+    private fun publish() {
+        for ((key, value) in statusValues()) DeviceStore.apply("glasses", key, value)
+    }
+}

package/android/src/main/java/com/glassly/bluetoothsdk/sgcs/G2KeyboardHid.kt

@@ -0,0 +1,208 @@
+package com.glassly.bluetoothsdk.sgcs
+
+/**
+ * Bounded HID report-descriptor decoder for the G2 keyboard bridge. HOGP
+ * passes the Report ID out of band (Report Reference descriptor), so a
+ * characteristic value is decoded as-is; byte zero is never stripped the way
+ * USB HID would. Ported from g2flash `demos/keyboard-hid.ts`; the descriptor
+ * limits match the firmware's 512-byte Report Map cap.
+ */
+internal object G2KeyboardHid {
+    data class Usage(val page: Int, val usage: Int)
+
+    data class KeyEvent(val page: Int, val usage: Int, val down: Boolean)
+
+    class Field(
+        val bit: Int,
+        val size: Int,
+        val count: Int,
+        val variable: Boolean,
+        val min: Int,
+        val max: Int,
+        val usages: List<Usage>,
+        val range: Pair<Usage, Usage>?,
+    )
+
+    class Report(val id: Int, var bits: Int, val fields: MutableList<Field>)
+
+    class DescriptorException(reason: String) : IllegalArgumentException("Unsupported or malformed HID descriptor: $reason")
+
+    class ReportException(reason: String) : IllegalArgumentException(reason)
+
+    private class Global(
+        var page: Int = 0,
+        var min: Int = 0,
+        var max: Int = 0,
+        var size: Int = 0,
+        var count: Int = 0,
+        var id: Int = 0,
+    ) {
+        fun copy() = Global(page, min, max, size, count, id)
+    }
+
+    /**
+     * Parse a Report Map into its input reports keyed by Report ID (0 when the
+     * map has no Report ID items). Rejects long items, usage delimiters, mixed
+     * numbered/unnumbered reports and oversized dimensions.
+     */
+    fun parseReportMap(bytes: ByteArray): Map<Int, Report> {
+        fun fail(reason: String): Nothing = throw DescriptorException(reason)
+        if (bytes.isEmpty() || bytes.size > 512) fail("report map must contain 1..512 bytes")
+        val reports = LinkedHashMap<Int, Report>()
+        var g = Global()
+        val stack = ArrayDeque<Global>()
+        var usages = ArrayList<Usage>()
+        var lo: Usage? = null
+        var hi: Usage? = null
+        var depth = 0
+        var p = 0
+        while (p < bytes.size) {
+            val prefix = bytes[p++].toInt() and 0xFF
+            if (prefix == 0xFE) fail("long items")
+            val n = intArrayOf(0, 1, 2, 4)[prefix and 3]
+            if (p + n > bytes.size) fail("truncated item")
+            var v = 0L
+            for (j in 0 until n) v += (bytes[p + j].toLong() and 0xFF) shl (8 * j)
+            p += n
+            val signed = if (n > 0 && v >= 1L shl (n * 8 - 1)) v - (1L shl (n * 8)) else v
+            val type = (prefix shr 2) and 3
+            val tag = prefix shr 4
+            fun usage(value: Long, width: Int): Usage =
+                if (width == 4) Usage((value shr 16).toInt(), (value and 0xFFFF).toInt()) else Usage(g.page, value.toInt())
+            when (type) {
+                1 -> when (tag) {
+                    0 -> g.page = v.toInt()
+                    1 -> g.min = signed.toInt()
+                    2 -> g.max = if (g.min < 0) signed.toInt() else v.toInt()
+                    7 -> g.size = v.toInt()
+                    8 -> {
+                        if (v == 0L || v > 255) fail("Report ID")
+                        g.id = v.toInt()
+                    }
+                    9 -> g.count = v.toInt()
+                    10 -> {
+                        if (stack.size >= 8) fail("global stack overflow")
+                        stack.addLast(g.copy())
+                    }
+                    11 -> g = stack.removeLastOrNull() ?: fail("global stack underflow")
+                    3, 4, 5, 6 -> Unit // physical range, unit/exponent
+                    else -> fail("unknown global item")
+                }
+                2 -> when {
+                    tag == 0 -> {
+                        if (usages.size >= 512) fail("too many usages")
+                        usages.add(usage(v, n))
+                    }
+                    tag == 1 -> lo = usage(v, n)
+                    tag == 2 -> hi = usage(v, n)
+                    tag == 10 -> fail("usage delimiters")
+                    tag > 9 -> fail("unknown local item")
+                }
+                0 -> {
+                    when (tag) {
+                        10 -> if (++depth > 32) fail("collection depth")
+                        12 -> if (--depth < 0) fail("collection underflow")
+                        8 -> {
+                            if (g.size == 0 || g.size > 32 || g.count == 0 || g.count > 512) fail("field dimensions")
+                            val r = reports.getOrPut(g.id) {
+                                if (reports.size >= 16) fail("too many input reports")
+                                Report(g.id, 0, ArrayList())
+                            }
+                            var range: Pair<Usage, Usage>? = null
+                            if (lo != null || hi != null) {
+                                val l = lo
+                                val h = hi
+                                if (l == null || h == null || l.page != h.page || h.usage < l.usage) fail("usage range")
+                                range = l to h
+                            }
+                            val field = Field(r.bits, g.size, g.count, (v.toInt() and 2) != 0, g.min, g.max, ArrayList(usages), range)
+                            r.bits += g.size * g.count
+                            if (r.bits > 4096) fail("report exceeds 512 bytes")
+                            // Constant padding and relative pointer axes are not keys.
+                            if ((v.toInt() and 1) == 0 && (v.toInt() and 4) == 0) r.fields.add(field)
+                        }
+                        9, 11 -> Unit
+                        else -> fail("unknown main item")
+                    }
+                    usages = ArrayList()
+                    lo = null
+                    hi = null
+                }
+                else -> fail("reserved item type")
+            }
+        }
+        if (depth != 0 || stack.isNotEmpty()) fail("unbalanced collection/global stack")
+        if (reports.containsKey(0) && reports.size > 1) fail("mixed numbered and unnumbered input reports")
+        if (reports.isEmpty()) fail("no input reports")
+        return reports
+    }
+
+    private fun usageAt(f: Field, index: Int): Usage? {
+        if (index < 0) return null
+        if (index < f.usages.size) return f.usages[index]
+        val rangeIndex = index - f.usages.size
+        val range = f.range
+        if (range != null && rangeIndex <= range.second.usage - range.first.usage) {
+            return Usage(range.first.page, range.first.usage + rangeIndex)
+        }
+        // Variable items reuse their last usage when Report Count exceeds usages.
+        if (f.variable) return range?.second ?: f.usages.lastOrNull()
+        return null
+    }
+
+    /**
+     * Keyboard (page 7) and consumer (page 12) usages currently asserted in one
+     * input report value. Throws on a length mismatch or a rollover report.
+     */
+    fun reportKeys(report: Report, data: ByteArray): List<Usage> {
+        if (data.size != (report.bits + 7) / 8) throw ReportException("HID input length does not match Report Map")
+        val keys = LinkedHashSet<Usage>()
+        for (f in report.fields) {
+            for (i in 0 until f.count) {
+                var value = 0
+                for (j in 0 until f.size) {
+                    val bit = f.bit + i * f.size + j
+                    if ((data[bit shr 3].toInt() and (1 shl (bit and 7))) != 0) value += 1 shl j
+                }
+                if (f.min < 0 && value >= 1 shl (f.size - 1)) value -= 1 shl f.size
+                if (value < f.min || value > f.max) continue // null state
+                val u = usageAt(f, if (f.variable) i else value - f.min) ?: continue
+                if (f.variable && value == 0) continue
+                if (u.usage == 0) continue
+                if (u.page == 7 && u.usage <= 3) throw ReportException("HID keyboard rollover/error report")
+                if (u.page == 7 || u.page == 12) keys.add(u)
+            }
+        }
+        return keys.toList()
+    }
+
+    /**
+     * Key ownership is per characteristic, then unioned: releasing one report
+     * cannot release a modifier still held by another report.
+     */
+    class HeldKeys {
+        private val reports = LinkedHashMap<Int, List<Usage>>()
+        private var held: List<Usage> = emptyList()
+
+        fun update(handle: Int, report: Report, data: ByteArray): List<KeyEvent> {
+            reports[handle] = reportKeys(report, data)
+            return diff()
+        }
+
+        fun reset(): List<KeyEvent> {
+            reports.clear()
+            return diff()
+        }
+
+        private fun diff(): List<KeyEvent> {
+            val next = LinkedHashSet<Usage>()
+            for (handle in reports.keys.sorted()) next.addAll(reports.getValue(handle))
+            val heldSet = held.toSet()
+            val events = ArrayList<KeyEvent>()
+            for (u in held) if (u !in next) events.add(KeyEvent(u.page, u.usage, false))
+            for (u in next) if (u !in heldSet) events.add(KeyEvent(u.page, u.usage, true))
+            held = next.toList()
+            return events
+        }
+    }
+}