Fix BLE button click detection and add Triki integration recipes.

Resolve button edges once per pollInput so Dev Mode and menus see bleButtonClick; add TrikiRecipes helpers, Bowling button confirm, and updated SDK docs.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: koderhack

.cursor/skills/veltokit/SKILL.md

@@ -19,12 +19,16 @@ description: VeltoKit BLE motion SDK and gametriki sample app. Use when editing
 
 ## Frame pipeline
 
-`BLE → MotionSDK.enqueueBLE / connect() → MotionEngine.updateFrame → GameInput → game.update(input:)`
+`BLE → MotionSDK.connect() → pollInput → GameInput → your game`
 
 ```swift
-let input = motion.pollInput(deltaTime: dt)  // after connect()
+motion.configureForPong()  // or Menu / PointerGame / GestureGame
+let input = motion.pollInput(deltaTime: dt)
 ```
 
+Helpers: `TrikiRecipes.swift` — `TrikiSimplePong`, `TrikiUIPicker`, `TrikiGameActions`, `TrikiButtonGate`.
+Docs: `website/docs/sdk/recipes.md`.
+
 ## MotionMode → games
 
 | Mode | Games | Main fields |

AGENTS.md

@@ -27,6 +27,7 @@ Unofficial / educational. Do not invent hardware brands or packet layouts not in
 ```text
 VeltoKit/
   MotionSDK.swift      # Public API — start here for SDK questions
+  Triki/TrikiRecipes.swift  # configureForPong/Menu + TrikiUIPicker, TrikiSimplePong
   MotionEngine.swift   # Per-frame processing, modes, calibration
   GameInput.swift      # Output contract — start here for game logic
   MotionConfig.swift   # Presets per MotionMode
@@ -106,7 +107,7 @@ Mode setup in app: `app/Engine/GameManager.swift`. Per-game docs: `website/docs/
 
 | Task | Read first |
 |------|------------|
-| Integrate SDK in a new app | `website/docs/quick-start.md`, `sdk/motion-sdk.md`, `sdk/game-input.md` |
+| Integrate SDK in a new app | `website/docs/sdk/recipes.md`, `quick-start.md`, `sdk/game-input.md` |
 | BLE packets / debugging | `sdk/ble-integration.md`, `VeltoKit/BLE/` |
 | Change gesture / throw | `sdk/gestures.md`, `VeltoKit/GestureDetector.swift` |
 | Triki menus / focus | `sdk/triki-ui.md`, `app/UI/TrikiUI/` |

VeltoKit/BLEButtonDecoder.swift

@@ -7,9 +7,29 @@ public enum BLEButtonDecoder {
   /// Indeks bajtu przycisku w pakiecie.
   public static let buttonIndex = 1
 
-  /// Sprawdza, czy bajt reprezentuje stan wciśnięty.
+  /// Sprawdza, czy bajt reprezentuje stan wciśnięty (dowolna wartość ≠ 0).
   public static func isPressed(_ byte: UInt8) -> Bool {
-    byte == 1
+    byte != 0
+  }
+
+  /// Skanuje cały notify — każdy blok zaczynający się od `0x22`, przycisk na następnym bajcie.
+  public static func risingEdgeAnywhere(in data: [UInt8], lastButton: inout UInt8) -> Bool {
+    guard data.count > buttonIndex else { return false }
+    var edge = false
+    var i = 0
+    while i < data.count {
+      if data[i] == packetHeader, i + buttonIndex < data.count {
+        let button = data[i + buttonIndex]
+        if isPressed(button), !isPressed(lastButton) {
+          edge = true
+        }
+        lastButton = button
+        i += 2
+      } else {
+        i += 1
+      }
+    }
+    return edge
   }
 
   /// Zbocze narastające na `bytes[1]` (tylko gdy pakiet zaczyna się od `0x22`).

VeltoKit/ButtonDetector.swift

@@ -18,7 +18,13 @@ final class ButtonDetector {
     if data.count > BLEButtonDecoder.buttonIndex, data[0] == BLEButtonDecoder.packetHeader {
       lastSeenButtonByte = data[BLEButtonDecoder.buttonIndex]
     }
-    guard BLEButtonDecoder.risingEdge(in: data, lastButton: &lastButton) else { return }
+    if BLEButtonDecoder.risingEdgeAnywhere(in: data, lastButton: &lastButton) {
+      pendingClick = true
+    }
+  }
+
+  /// Ustawia oczekujący impuls (np. z TrikiParser preset v2).
+  func latchClick() {
     pendingClick = true
   }
 

VeltoKit/GameInput.swift

@@ -28,6 +28,8 @@ public struct GameInput {
   public var tiltRight: Bool = false
   /// Główna akcja wejścia (np. klik/strzał).
   public var primaryAction: Bool = false
+  /// Jednoklatkowy impuls fizycznego przycisku BLE (`bytes[1]`, zbocze 0→1).
+  public var bleButtonClick: Bool = false
   /// Opcjonalna akcja dodatkowa.
   public var secondaryAction: Bool? = nil
   /// Surowe sensory Triki przypisane do tej ramki.
@@ -94,6 +96,7 @@ public struct GameInput {
   ///   - tiltLeft: Sygnał przechyłu w lewo.
   ///   - tiltRight: Sygnał przechyłu w prawo.
   ///   - primaryAction: Główna akcja wejścia.
+  ///   - bleButtonClick: Impuls fizycznego przycisku BLE (jedna klatka).
   ///   - secondaryAction: Opcjonalna akcja dodatkowa.
   ///   - sensors: Zrzut surowych sensorów Triki.
   ///   - lateral: Oś boczna.
@@ -128,6 +131,7 @@ public struct GameInput {
     tiltLeft: Bool = false,
     tiltRight: Bool = false,
     primaryAction: Bool = false,
+    bleButtonClick: Bool = false,
     secondaryAction: Bool? = nil,
     sensors: TrikiSensors = TrikiSensors(),
     lateral: Double = 0,
@@ -162,6 +166,7 @@ public struct GameInput {
     self.tiltLeft = tiltLeft
     self.tiltRight = tiltRight
     self.primaryAction = primaryAction
+    self.bleButtonClick = bleButtonClick
     self.secondaryAction = secondaryAction
     self.sensors = sensors
     self.lateral = lateral

VeltoKit/Motion/MotionParser.swift

@@ -34,6 +34,7 @@ final class MotionParser: ObservableObject {
   private var rxBuffer: [UInt8] = []
   /// Ostatnio widziany `bytes[1]` (podgląd DEV).
   public private(set) var lastSeenButtonByte: UInt8 = 0
+  private var lastIngressButtonByte: UInt8 = 0
 
   private var smoothTiltX = 0.0
   private var smoothTiltY = 0.0
@@ -131,6 +132,7 @@ final class MotionParser: ObservableObject {
     sensors = TrikiSensors()
     recentFrames.removeAll()
     lastSeenButtonByte = 0
+    lastIngressButtonByte = 0
   }
 
   /// Czy klik był niedawno (DEV / HUD — impuls trwa ~1 klatkę).
@@ -139,8 +141,11 @@ final class MotionParser: ObservableObject {
     return sensors.click || (now - lastClickAt) < 0.25
   }
 
-  /// Podgląd `bytes[1]` — klik obsługuje `ButtonDetector` w MotionSDK.
+  /// Podgląd `bytes[1]` + impuls kliknięcia do `consumeImpulses()`.
   private func ingestBLEButtonEdges(from data: [UInt8]) {
+    if BLEButtonDecoder.risingEdgeAnywhere(in: data, lastButton: &lastIngressButtonByte) {
+      registerClickImpulse()
+    }
     if data.count > BLEButtonDecoder.buttonIndex, data[0] == BLEButtonDecoder.packetHeader {
       lastSeenButtonByte = data[BLEButtonDecoder.buttonIndex]
     }

VeltoKit/MotionSDK+Connection.swift

@@ -2,6 +2,7 @@ import Combine
 import Foundation
 
 private let motionHudPublishInterval: TimeInterval = 0.12
+private let buttonClickHighlightDuration: TimeInterval = 0.12
 
 /// Adds focused motion sdk helpers.
 extension MotionSDK {
@@ -36,12 +37,21 @@ extension MotionSDK {
     trikiController?.tick(deltaTime: deltaTime)
     applyTrikiGamepadToEngine()
 
+    let now = Date().timeIntervalSince1970
+
     guard let parser = streamParser else {
       updateFrame(deltaTime: deltaTime)
-      return input
+      let buttonClick = resolveButtonClick(impulses: (false, false), now: now)
+      var copy = input
+      copy.bleButtonClick = buttonClick
+      if config.mode == .paddle {
+        copy.primaryAction = buttonClick
+      } else if buttonClick {
+        copy.primaryAction = copy.primaryAction || buttonClick
+      }
+      latestEnrichedInput = copy
+      return copy
     }
-
-    let now = Date().timeIntervalSince1970
     let stale = trikiBLEMode.packetStaleSeconds
     if now - lastPacketAt > stale, isReceiving { isReceiving = false }
     syncTrikiPublishedState()
@@ -51,11 +61,13 @@ extension MotionSDK {
       parser.flushImpulsesOnly()
       let impulses = parser.consumeImpulses()
       let out = updateFrame(deltaTime: deltaTime)
+      let buttonClick = resolveButtonClick(impulses: impulses, now: now)
       var enriched = makeEnrichedGameInput(
         output: out,
         sdkInput: input,
         parser: parser,
-        impulses: impulses
+        impulses: impulses,
+        buttonClick: buttonClick
       )
       applyTrikiGamepadSignals(&enriched)
       finalizeAdaptiveInput(&enriched)
@@ -72,11 +84,13 @@ extension MotionSDK {
     )
     let out = updateFrame(deltaTime: deltaTime)
     let impulses = parser.consumeImpulses()
+    let buttonClick = resolveButtonClick(impulses: impulses, now: now)
     var enriched = makeEnrichedGameInput(
       output: out,
       sdkInput: input,
       parser: parser,
-      impulses: impulses
+      impulses: impulses,
+      buttonClick: buttonClick
     )
     applyTrikiGamepadSignals(&enriched)
     finalizeAdaptiveInput(&enriched)
@@ -287,19 +301,39 @@ extension MotionSDK {
     lastFramePosY = input.posY
   }
 
+  /// Jednorazowe zebranie impulsu przycisku BLE na końcu `pollInput` (nie w `publishInput`).
+  func resolveButtonClick(impulses: (click: Bool, shake: Bool), now: TimeInterval) -> Bool {
+    if trikiController?.consumeButtonEdge() == true {
+      button.latchClick()
+    }
+    let packetEdge = button.consumeClick()
+    let currentByte = button.lastSeenButtonByte
+    let levelEdge = BLEButtonDecoder.isPressed(currentByte)
+      && !BLEButtonDecoder.isPressed(lastSampledButtonByte)
+    lastSampledButtonByte = currentByte
+
+    let freshEdge = packetEdge || impulses.click || levelEdge
+    if freshEdge {
+      buttonClickHighlightUntil = now + buttonClickHighlightDuration
+    }
+    return freshEdge || now < buttonClickHighlightUntil
+  }
+
   /// Builds a UI/game-friendly input snapshot from raw engine output and parser state.
   ///
   /// - Parameters:
   ///   - output: Current processed motion output frame.
   ///   - sdkInput: Base input snapshot that will be enriched.
   ///   - parser: Optional parser containing latest sensor payload.
   ///   - impulses: Edge-triggered click/shake impulses for this frame.
+  ///   - buttonClick: Resolved BLE button edge for this poll (includes short HUD latch).
   /// - Returns: Enriched `GameInput` used by HUD and gameplay layers.
   func makeEnrichedGameInput(
     output: MotionOutput,
     sdkInput: GameInput,
     parser: MotionParser?,
-    impulses: (click: Bool, shake: Bool)
+    impulses: (click: Bool, shake: Bool),
+    buttonClick: Bool = false
   ) -> GameInput {
     let dbg = debug
     var enriched = sdkInput
@@ -321,13 +355,13 @@ extension MotionSDK {
       enriched.sensors = parser.sensors
       enriched.pointerDirection = pointerDirection(posX: output.x, posY: output.y)
     }
-    let buttonEdge = impulses.click || sdkInput.primaryAction
+    enriched.bleButtonClick = buttonClick
     if config.mode == .paddle {
-      enriched.primaryAction = buttonEdge
-    } else if impulses.click {
-      enriched.primaryAction = true
+      enriched.primaryAction = buttonClick
+    } else if buttonClick {
+      enriched.primaryAction = enriched.primaryAction || buttonClick
     }
-    applyClickToSensors(&enriched, clickEdge: buttonEdge)
+    applyClickToSensors(&enriched, clickEdge: buttonClick)
     return enriched
   }
 

VeltoKit/MotionSDK.swift

@@ -17,6 +17,9 @@ public final class MotionSDK: ObservableObject {
   /// Ostatni bajt przycisku BLE (DEV).
   public var lastButtonByte: UInt8 { button.lastSeenButtonByte }
 
+  /// Czy oczekuje nieodebrany impuls przycisku (DEV).
+  public var hasPendingButtonClick: Bool { button.didClick }
+
   /// Ostatnia opublikowana ramka wejścia.
   public private(set) var input = GameInput()
 
@@ -73,6 +76,10 @@ public final class MotionSDK: ObservableObject {
   private var latestPaddleRaw: Double?
   var lastFramePosX: Double?
   var lastFramePosY: Double?
+  /// Ostatni `bytes[1]` przy ostatnim `pollInput` (zbocze między pollami).
+  var lastSampledButtonByte: UInt8 = 0
+  /// Dev Mode / HUD: trzyma `bleButtonClick` przez krótki czas po zboczu.
+  var buttonClickHighlightUntil: TimeInterval = 0
 
   /// Tworzy instancję SDK ruchu.
   public init() {
@@ -221,25 +228,26 @@ public final class MotionSDK: ObservableObject {
     latestPaddleRaw = nil
     lastFramePosX = nil
     lastFramePosY = nil
+    lastSampledButtonByte = 0
+    buttonClickHighlightUntil = 0
     button.reset()
     engine.resetState()
     input = GameInput()
   }
 
   private func publishInput() {
     let out = engine.output
-    let click = button.consumeClick()
     let trikiAction = trikiController?.gameInput.isAction ?? false
     let throwShot = out.didShoot
     input.posX = out.x
     input.posY = out.y
     input.shotTriggered = throwShot
+    input.bleButtonClick = false
     switch engine.config.mode {
     case .paddle:
-      // Quiz / Pong / menu: only the physical BLE button — not velocity or throw.
-      input.primaryAction = click
+      input.primaryAction = false
     case .pointer, .gesture:
-      input.primaryAction = click || throwShot || trikiAction
+      input.primaryAction = throwShot || trikiAction
     }
     input.throwPower = throwShot ? engine.lastGestureThrowPower : 0
     input.gesturePrimed = engine.gesturePrimed

VeltoKit/Triki/TrikiGameController.swift

@@ -43,6 +43,7 @@ public final class TrikiGameController: ObservableObject {
   private var lastPollTime: TimeInterval?
   private var lastHudPublishAt: TimeInterval = 0
   private var lastWakeUpAttemptAt: TimeInterval = 0
+  private var pendingButtonEdge = false
 
   private var moveHandlers: [(Float) -> Void] = []
   private var shakeHandlers: [() -> Void] = []
@@ -103,6 +104,9 @@ public final class TrikiGameController: ObservableObject {
 
     let frames = parser.drainParsedFrames()
     if !frames.isEmpty {
+      if frames.contains(where: \.buttonEdge) {
+        pendingButtonEdge = true
+      }
       motion.ingest(parsed: frames, deltaTime: dt)
       publishGameInputIfNeeded(now: now)
       dispatchCallbacks()
@@ -114,6 +118,13 @@ public final class TrikiGameController: ObservableObject {
     return gameInput
   }
 
+  /// Jednorazowo zwraca impuls przycisku z parsera (preset v2 / legacy).
+  func consumeButtonEdge() -> Bool {
+    let edge = pendingButtonEdge
+    pendingButtonEdge = false
+    return edge
+  }
+
   public func resetSession() {
     parser.reset()
     motion.reset()
@@ -125,6 +136,7 @@ public final class TrikiGameController: ObservableObject {
     lastPollTime = nil
     lastHudPublishAt = 0
     lastWakeUpAttemptAt = 0
+    pendingButtonEdge = false
   }
 
   // MARK: - Public API

VeltoKit/Triki/TrikiParser.swift

@@ -63,7 +63,7 @@ public final class TrikiParser: @unchecked Sendable {
 
     let result: ParsedMotionData
     if Self.isPresetV2(data) {
-      result = Self.parsePresetV2(data)
+      result = Self.parsePresetV2(data, lastButton: &lastButtonByte)
     } else if Self.isLegacyBlock8(data) {
       result = Self.parseLegacyBlock8(data, lastButton: &lastButtonByte)
     } else if Self.isLegacyFrame14(data) {
@@ -135,21 +135,24 @@ public final class TrikiParser: @unchecked Sendable {
     return true
   }
 
-  public static func parsePresetV2(_ data: Data) -> ParsedMotionData {
+  public static func parsePresetV2(_ data: Data, lastButton: inout UInt8) -> ParsedMotionData {
     guard data.count >= 8 else {
       return ParsedMotionData(isValid: false, presetID: "v2-short")
     }
 
     let rawX = int16(data, 2)
     let rawY = int16(data, 4)
     let rawZ = int16(data, 6)
+    let header = [UInt8](data.prefix(min(8, data.count)))
+    let edge = BLEButtonDecoder.risingEdge(in: header, lastButton: &lastButton)
 
     return ParsedMotionData(
       x: Float(rawX) / 100.0,
       y: Float(rawY) / 100.0,
       z: Float(rawZ) / 100.0,
       isValid: true,
-      presetID: "v2"
+      presetID: "v2",
+      buttonEdge: edge
     )
   }