@glassly/engine 0.3.2-dev.586 → 0.3.2-dev.595

package/src/facades/pairing.ts

@@ -63,7 +63,7 @@ function projectTargetReady(options: Pick<PairingReadyWaitOptions, "deviceModel"
   const {deviceModel, deviceName} = options
   const glasses = useGlassesStore.getState()
 
-  if (deviceModel === ControllerTypes.R1) {
+  if (deviceModel !== undefined && (Object.values(ControllerTypes) as string[]).includes(deviceModel)) {
     if (!glasses.controllerConnected || !glasses.controllerFullyBooted) return false
     const settings = useSettingsStore.getState()
     const pairedModel = settings.getSetting(SETTINGS.default_controller.key)

package/src/generated/releaseMetadata.ts

@@ -12,9 +12,9 @@ export interface EngineReleaseMetadata {
 export const ENGINE_RELEASE_METADATA: Readonly<EngineReleaseMetadata> = Object.freeze({
   "schemaVersion": 1,
   "familyBaseVersion": "0.3.2",
-  "releaseIdentity": "0.3.2-dev.586",
-  "releaseSetId": "glassly-0.3.2-dev.586",
-  "sourceCommit": "d6fda6d4ab62929d5449b0fee51cb3ac22e92be5",
+  "releaseIdentity": "0.3.2-dev.595",
+  "releaseSetId": "glassly-0.3.2-dev.595",
+  "sourceCommit": "fdafc60b7dfa2523c464e2fb8a6347b9975dd8b7",
   "otaManifestUrl": null,
   "otaManifestSha256": null
 })

package/src/index.ts

@@ -201,6 +201,20 @@ export {
 } from "./utils/devMiniappLaunch"
 export {HardwareCompatibility, type CompatibilityResult} from "./utils/hardware"
 export {BgTimer, throttle, debounce} from "./utils/timers"
+// Meta Neural Band: the account sign-in a claim needs (the WebView lives in the host).
+export {
+  MetaAuthError,
+  authEntryUrl,
+  callbackMatches,
+  callbackQuery,
+  decryptBlob,
+  isLoginCallback,
+  login,
+  tokensQuery,
+  type MetaSession,
+  type MetaSsoTokens,
+} from "./services/neuralBand/MetaAuth"
+export type {NeuralBandClaimStatus, NeuralBandHandwritingStatus} from "./services/neuralBand/NeuralBandInput"
 
 // Hardware types and capability profiles.
 export {

package/src/services/DeviceEventRouter.ts

@@ -35,6 +35,7 @@ import {retirePendingSelectionOnPromotion} from "./PairingIdentity"
 import GlobalEventEmitter from "../utils/GlobalEventEmitter"
 import {asgCameraApi} from "./asg/asgCameraApi"
 import {dispatchTouchEvent, resetTouchInput} from "./GlassesTouchInput"
+import neuralBandInput from "./neuralBand/NeuralBandInput"
 import dashboardOpenTrace from "./debug/DashboardOpenTrace"
 
 let subs: Array<{remove: () => void}> = []
@@ -233,6 +234,10 @@ export function startDeviceEventRouter(): void {
   // Physical keyboard bridged through G2 Glassly CFW: raw HID transitions →
   // layout-translated keyboard_event stream (with synthesized auto-repeat).
   subs.push(BluetoothSdk.addListener("keyboard_key", (event) => glassesKeyboardInput.handle(event)))
+  // Meta Neural Band: its gestures ride touch_event above; these are its own streams.
+  subs.push(BluetoothSdk.addListener("neural_band_claim", (event) => neuralBandInput.handleClaim(event)))
+  subs.push(BluetoothSdk.addListener("neural_band_handwriting", (event) => neuralBandInput.handleHandwriting(event)))
+  subs.push(BluetoothSdk.addListener("neural_band_pointer", (event) => neuralBandInput.handlePointer(event)))
   subs.push({
     remove: useGlassesStore.subscribe(
       (s) => s.keyboardConnected === true,

package/src/services/GestureDotsService.ts

@@ -1,8 +1,9 @@
 /**
  * Gesture dots — a debug indicator that flashes a small glyph top-right on the
  * glasses when a touch gesture arrives, while nothing else is on the display:
- * a filled circle for a single tap, an arrow for a swipe (cleared after a
- * short pulse), a bullseye while a CFW tap-then-hold is held. Extracted from
+ * a filled circle for a single tap, two for a double tap, an arrow for a swipe
+ * (cleared after a short pulse), a bullseye while a CFW tap-then-hold is held.
+ * The Neural Band's middle finger (index 1) draws the same shapes hollow. Extracted from
  * the CFW dashboard service; it renders through
  * the ordinary scene pipeline, so it works on any positioning device (stock
  * G2 included), and is gated by the gesture_dots debug setting.
@@ -27,6 +28,18 @@ const MARGIN_X = 16
 const MARGIN_TOP = 10
 // Off: tap_then_hold opens the side menu now.
 const HOLD_GLYPH_ENABLED = false
+/** Gestures that flash a glyph. */
+const FLASH_GLYPHS: Record<string, GestureDotGlyph> = {
+  single_tap: "dot",
+  double_tap: "double",
+  long_press: "hold",
+  swipe_up: "up",
+  swipe_down: "down",
+  swipe_left: "left",
+  swipe_right: "right",
+}
+/** The band's middle finger draws the filled shapes hollow. */
+const MIDDLE_FINGER_GLYPHS: Partial<Record<GestureDotGlyph, GestureDotGlyph>> = {dot: "ring", double: "doubleRing"}
 
 class GestureDotsService {
   private started = false
@@ -34,6 +47,8 @@ class GestureDotsService {
   private flashTimer: number | null = null
   /** Finger currently on the touch bar (tap_start..tap_end; the CFW forwards holds as these edges). */
   private held = false
+  /** The band's middle finger is down (its edges carry index 1); any other finger draws the disc. */
+  private heldMiddle = false
   /**
    * The CFW's tap_then_hold fired during this press (discrete recognition
    * event; the tap_end that follows on release is what clears it).
@@ -76,6 +91,7 @@ class GestureDotsService {
     this.flashTimer = null
     this.flash = null
     this.held = false
+    this.heldMiddle = false
     this.holdRecognized = false
   }
 
@@ -94,15 +110,16 @@ class GestureDotsService {
   /**
    * Flash a gesture on the indicator. Other gesture names are ignored.
    * Claimed gestures cancel any earlier press/flash without starting a new
-   * one: the claimant may also consume the release edge.
+   * one: the claimant may also consume the release edge. `fingerIndex` is the
+   * Neural Band's finger on its pinches and press edges (1 = middle).
    */
-  noteGesture(gestureName: string, claimed = false): void {
+  noteGesture(gestureName: string, claimed = false, fingerIndex?: number): void {
     if (!this.started || !this.enabled()) return
-    this.applyGesture(gestureName, claimed)
+    this.applyGesture(gestureName, claimed, fingerIndex)
     this.trace("input", {gestureName, claimed})
   }
 
-  private applyGesture(gestureName: string, claimed: boolean): void {
+  private applyGesture(gestureName: string, claimed: boolean, fingerIndex?: number): void {
     if (localDisplayManager.hasActiveDisplay() || useDisplayStore.getState().overlayOwner !== null) {
       this.relinquish()
       return
@@ -120,6 +137,7 @@ class GestureDotsService {
       const held = gestureName !== "tap_end"
       if (this.held === held) return
       this.held = held
+      this.heldMiddle = held && fingerIndex === 1
       if (!held) this.holdRecognized = false
       this.render()
       return
@@ -133,15 +151,10 @@ class GestureDotsService {
     // Any other gesture implies the finger is up, even if tap_end was lost.
     const released = this.held
     this.held = false
+    this.heldMiddle = false
     this.holdRecognized = false
-    const flash: GestureDotGlyph | null =
-      gestureName === "single_tap"
-        ? "dot"
-        : gestureName === "swipe_up"
-          ? "up"
-          : gestureName === "swipe_down"
-            ? "down"
-            : null
+    const shape = FLASH_GLYPHS[gestureName] ?? null
+    const flash = shape && fingerIndex === 1 ? MIDDLE_FINGER_GLYPHS[shape] ?? shape : shape
     if (!flash) {
       if (released) this.render()
       return
@@ -188,7 +201,7 @@ class GestureDotsService {
   private render(): void {
     if (!this.started) return
     if (localDisplayManager.hasActiveDisplay() || useDisplayStore.getState().overlayOwner !== null) return
-    const shown = this.flash ?? (this.held ? (this.holdRecognized ? "hold" : "dot") : null)
+    const shown = this.flash ?? (this.held ? (this.holdRecognized ? "hold" : this.heldMiddle ? "ring" : "dot") : null)
     if (!this.enabled()) {
       if (this.visible) {
         this.visible = false

package/src/services/GlassesTouchInput.ts

@@ -50,8 +50,11 @@ function shouldForwardScroll(event: TouchEvent): boolean {
 export function dispatchTouchEvent(event: TouchEvent): void {
   const gesture = event.gestureName
   const claimant = localMiniappRuntime.gestureClaimant(gesture)
+  // The Neural Band's middle finger (index 1) shares the tap names but is left
+  // to miniapps: the engine's own double-tap behaviors are the index finger's.
+  const osDoubleTap = gesture === "double_tap" && event.index !== 1
 
-  if (gesture === "double_tap") {
+  if (osDoubleTap) {
     // A visible main miniapp opts out of OS exit by registering double tap (the
     // terminal's back-to-menu). The latest claimant still receives it. Otherwise
     // the tap means "leave the app". The controller shows the bounded OS
@@ -72,7 +75,7 @@ export function dispatchTouchEvent(event: TouchEvent): void {
     // An overlay app claims the double tap on an empty screen to open the dashboard.
     if (gesture === "double_tap" && isOverlayApp(claimant)) dashboardOpenTrace.trigger("double-tap", event.timestamp)
     // The press may have started before this app claimed its release edge.
-    gestureDotsService.noteGesture(gesture, true)
+    gestureDotsService.noteGesture(gesture, true, event.index)
     if (!shouldForwardScroll(event)) return
     localMiniappRuntime.forwardEvent("touch_event", event, undefined, claimant)
     return
@@ -81,7 +84,7 @@ export function dispatchTouchEvent(event: TouchEvent): void {
   // Gesture-dots debug indicator (any device, gated by its setting). It
   // only paints while the screen is otherwise empty. Process even suppressed
   // scroll repeats here so their completion still clears a held dot.
-  gestureDotsService.noteGesture(gesture)
+  gestureDotsService.noteGesture(gesture, false, event.index)
 
   if (!shouldForwardScroll(event)) return
   localMiniappRuntime.forwardEvent("touch_event", event)
@@ -90,7 +93,7 @@ export function dispatchTouchEvent(event: TouchEvent): void {
   // Glassly CFW glasses the dashboard miniapp claims it while it runs
   // (ADR-0006); stock firmware keeps its native dashboard (ADR-0002). The
   // modal nav UI owns the screen; showDashboard would fight it.
-  if (gesture === "double_tap" && !nativeNavigationService.isActive) {
+  if (osDoubleTap && !nativeNavigationService.isActive) {
     useDisplayStore.getState().setDisplayEvent({layout: {layoutType: "unavailable", reason: "firmware-dashboard"}})
     void Promise.resolve(BluetoothSdk.showDashboard()).catch((err) => {
       console.error("DeviceEventRouter: showDashboard failed:", err)
@@ -113,7 +116,12 @@ export function sendGesture(
     | "tap_then_hold"
     | "touch_down"
     | "swipe_up"
-    | "swipe_down",
+    | "swipe_down"
+    | "swipe_left"
+    | "swipe_right"
+    | "long_press"
+    | "dial_up"
+    | "dial_down",
 ): void {
   const model = useGlassesStore.getState().deviceModel
   dispatchTouchEvent({

package/src/services/gestureDotGlyphs.ts

@@ -4,12 +4,17 @@
  */
 export const GESTURE_DOT_GLYPH_SIZE = 24
 
-export type GestureDotGlyph = "dot" | "up" | "down" | "hold" | "blank"
+export type GestureDotGlyph = "dot" | "double" | "ring" | "doubleRing" | "up" | "down" | "left" | "right" | "hold" | "blank"
 
 export const GESTURE_DOT_GLYPHS: Record<GestureDotGlyph, string> = {
   dot: "iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAAAAADFHGIkAAAALklEQVR4nM2QsQ0AAAjC/P/pmrhqZ+xIF6DqBQyWbwO3gduAmKjQuj7QL/ETEzQmMptl7Q9NBAAAAABJRU5ErkJggg==",
+  double: "iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAAAAADFHGIkAAAAG0lEQVR4nGNgGD7gPxjgYkN4yOyBlcDp3GEBAB3sd4lPaQxDAAAAAElFTkSuQmCC",
+  ring: "iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAAAAADFHGIkAAAANElEQVR4nGNgGBTgPxjgEseUgQphyCD4qDL/kSX+Y9WApoWqEjgsx+lc3B7EHSS4A3EgAAC+cEu1JTNREQAAAABJRU5ErkJggg==",
+  doubleRing: "iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAAAAADFHGIkAAAAIklEQVR4nGNgGD7gPxjgYkN4yGwGmBA6SV0JHJbjdO6wAADBMlep8zl7TAAAAABJRU5ErkJggg==",
   up: "iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAAAAADFHGIkAAAAMElEQVR4nGNgoCv4////f1zi2GT+/4ciTHE4RhdHIlDFUUhkcTQKQx9WBw8PCVoBAIcbOcf3xeeBAAAAAElFTkSuQmCC",
   down: "iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAAAAADFHGIkAAAALUlEQVR4nGNgoC/4/3+4SkBFUCkkNjKJIoMg0GRgGEMGgrC4CQSwuxanR2gEAO1/Ocfgp8uvAAAAAElFTkSuQmCC",
+  left: "iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAAAAADFHGIkAAAAI0lEQVR4nGNgoCv4j0sch8RAiTP8RwPESOAwajDI4JKgGQAAKO05x7DqJxIAAAAASUVORK5CYII=",
+  right: "iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAAAAADFHGIkAAAAIElEQVR4nGNgoDf4j1NiMMn8RwOEJYizZKDEcQc7bQAAS7w5x+ro2lsAAAAASUVORK5CYII=",
   hold: "iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAAAAADFHGIkAAAAR0lEQVR4nGNgIAj+gwF2UUy5//+xyyDzcLGRedjMhTEwXAKl0Z0Lof7DKbgMhBpQCZzOxedBHEGCMxAJBTXhKGRAA9hFMQEANr7jHQU9fO0AAAAASUVORK5CYII=",
   blank: "iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAAAAADFHGIkAAAAD0lEQVR4nGNgGAWjgPoAAAJYAAGgxYwDAAAAAElFTkSuQmCC",
 }

package/src/services/neuralBand/MetaAuth.ts

@@ -0,0 +1,192 @@
+/**
+ * The Meta account sign-in a Neural Band claim needs, ported from callbacked/kinesis
+ * (MIT, Copyright (c) 2026 callbacked): Sources/Kinesis/MetaAuth.swift.
+ *
+ * The chain: an anonymous tokens query, a WebView sign-in on auth.meta.com whose
+ * fb-viewapp://…frl_login redirect carries a token and a blob, a blob decrypt, and
+ * the ar-genai exchange that yields the user session. The session then goes to the
+ * native Bluetooth SDK (keychain / keystore), which runs the ownership exchanges;
+ * nothing here persists it.
+ */
+import {sha256Hex} from "./sha256"
+
+// Meta's own client identifiers, the same in every copy of Meta's apps. They name the
+// app that asks, not a person. They are not secrets, and no account or session is in them.
+const FRL_CLIENT = "FRL|388177446008673|083800dd7efbbd42eab18c9886d79c18"
+const AR_CLIENT = "AR|306760944872162|a919421a55a8ea18080ab2f10f57f1be"
+const TOKENS_QUERY_URL = "https://meta.graph.meta.com/webview_tokens_query"
+const BLOBS_DECRYPT_URL = "https://meta.graph.meta.com/webview_blobs_decrypt"
+const LOGIN_URL = "https://ar-genai.graph.meta.com/login"
+const AUTH_ENTRY_BASE =
+  "https://auth.meta.com/?native_app_id=388177446008673&source_app_id=388177446008673&native_sso_etoken="
+
+export class MetaAuthError extends Error {}
+
+export interface MetaSsoTokens {
+  nativeSsoToken: string
+  etoken: string
+}
+
+export interface MetaSession {
+  accessToken: string
+  userId: string
+}
+
+export function authEntryUrl(tokens: MetaSsoTokens): string {
+  return AUTH_ENTRY_BASE + encodeURIComponent(tokens.etoken)
+}
+
+/** The redirect that ends the sign-in: a custom scheme, or the frl_login marker on https. */
+export function isLoginCallback(url: string): boolean {
+  return url.toLowerCase().startsWith("fb-viewapp:") || url.includes("frl_login")
+}
+
+export function callbackQuery(url: string): {token?: string; blob?: string} {
+  const query = url.includes("?") ? url.slice(url.indexOf("?") + 1) : ""
+  const out: {token?: string; blob?: string} = {}
+  for (const pair of query.split("&")) {
+    const [key, value = ""] = pair.split("=")
+    if (key === "token") out.token = decodeURIComponent(value)
+    if (key === "blob") out.blob = decodeURIComponent(value)
+  }
+  return out
+}
+
+/** The first 16 hex digits of the request token's SHA-256, which the callback must present. */
+export function expectedCallbackToken(nativeSsoToken: string): string {
+  return sha256Hex(nativeSsoToken).slice(0, 16)
+}
+
+export function callbackMatches(token: string | undefined, nativeSsoToken: string): boolean {
+  if (!token || token.length !== 16) return false
+  const expected = expectedCallbackToken(nativeSsoToken)
+  let difference = 0
+  for (let i = 0; i < 16; i++) difference |= token.charCodeAt(i) ^ expected.charCodeAt(i)
+  return difference === 0
+}
+
+export function makeLsd(): string {
+  let digits = ""
+  for (let i = 0; i < 6; i++) digits += Math.floor(Math.random() * 10)
+  return "S0." + digits
+}
+
+export function jazoest(lsd: string): string {
+  let sum = 0
+  for (const char of lsd) sum += char.codePointAt(0) ?? 0
+  return "2" + sum
+}
+
+export function multipartBody(fields: [string, string][], boundary: string): string {
+  let body = ""
+  for (const [name, value] of fields) {
+    body += `--${boundary}\r\nContent-Disposition: form-data; name="${name}"\r\n\r\n${value}\r\n`
+  }
+  return body + `--${boundary}--\r\n`
+}
+
+export function urlForm(fields: [string, string][]): string {
+  return fields.map(([name, value]) => `${name}=${encodeURIComponent(value)}`).join("&")
+}
+
+type Json = Record<string, unknown>
+
+async function post(url: string, headers: Record<string, string>, body: string): Promise<Json> {
+  const response = await fetch(url, {method: "POST", headers, body})
+  let json: Json | null = null
+  try {
+    json = (await response.json()) as Json
+  } catch {
+    json = null
+  }
+  if (response.status !== 200 || json === null) {
+    throw new MetaAuthError(`Meta sign-in failed (HTTP ${response.status}). Try again.`)
+  }
+  if (json.error !== undefined) {
+    const error = json.error as {code?: number; error_subcode?: number} | null
+    throw new MetaAuthError(
+      `Meta sign-in failed (code ${error?.code ?? "-"}, subcode ${error?.error_subcode ?? "-"}). Try again.`,
+    )
+  }
+  return json
+}
+
+async function postMultipart(url: string, fields: [string, string][]): Promise<Json> {
+  const boundary = `glassly.form.${Date.now().toString(36)}${Math.random().toString(36).slice(2)}`
+  return post(
+    url,
+    {
+      "Content-Type": `multipart/form-data; boundary=${boundary}`,
+      "Accept": "application/json",
+      "Origin": "https://auth.meta.com",
+    },
+    multipartBody(fields, boundary),
+  )
+}
+
+/** Step 1: the anonymous WebView tokens query. */
+export async function tokensQuery(): Promise<MetaSsoTokens> {
+  const lsd = makeLsd()
+  const json = await postMultipart(TOKENS_QUERY_URL, [
+    ["access_token", FRL_CLIENT],
+    ["lsd", lsd],
+    ["jazoest", jazoest(lsd)],
+  ])
+  const nativeSsoToken = json.native_sso_token
+  const etoken = json.native_sso_etoken
+  if (typeof nativeSsoToken !== "string" || !nativeSsoToken || typeof etoken !== "string" || !etoken) {
+    throw new MetaAuthError("Meta didn't return sign-in tokens. Try again.")
+  }
+  return {nativeSsoToken, etoken}
+}
+
+/** Step 3: decrypt the login blob into the FRL access token. */
+export async function decryptBlob(blob: string, requestToken: string): Promise<string> {
+  const lsd = makeLsd()
+  const json = await postMultipart(BLOBS_DECRYPT_URL, [
+    ["blob", blob],
+    ["request_token", requestToken],
+    ["access_token", FRL_CLIENT],
+    ["lsd", lsd],
+    ["jazoest", jazoest(lsd)],
+  ])
+  const token = json.access_token
+  if (typeof token !== "string" || !token) throw new MetaAuthError("Meta didn't confirm the sign-in. Try again.")
+  return token
+}
+
+function randomId(): string {
+  const hex = () =>
+    Math.floor(Math.random() * 0x10000)
+      .toString(16)
+      .padStart(4, "0")
+  return `${hex()}${hex()}-${hex()}-${hex()}-${hex()}-${hex()}${hex()}${hex()}`.toUpperCase()
+}
+
+/** Step 4: exchange the FRL token for the ar user session. */
+export async function login(frlAccessToken: string): Promise<MetaSession> {
+  const json = await post(
+    LOGIN_URL,
+    {
+      "Content-Type": "application/x-www-form-urlencoded",
+      "Accept": "application/json",
+      "Authorization": "OAuth " + AR_CLIENT,
+    },
+    urlForm([
+      ["frl_access_token", frlAccessToken],
+      ["logging_session_id", randomId()],
+      ["format", "json"],
+      ["device_id", randomId()],
+      ["generate_session_cookies", "1"],
+      ["generate_analytics_claim", "1"],
+      ["method", "POST"],
+    ]),
+  )
+  const accessToken = json.access_token
+  const rawUserId = json.user_id
+  const userId = typeof rawUserId === "string" ? rawUserId : typeof rawUserId === "number" ? String(rawUserId) : ""
+  if (typeof accessToken !== "string" || !accessToken || !userId) {
+    throw new MetaAuthError("Meta didn't return an account session. Try again.")
+  }
+  return {accessToken, userId}
+}

package/src/services/neuralBand/NeuralBandInput.ts

@@ -0,0 +1,148 @@
+/**
+ * The Meta Neural Band's own event streams, past the gestures that ride `touch_event`:
+ * claim progress (for the pairing screens), the handwriting model (typed into the
+ * miniapp keyboard stream as synthesized key presses) and the air mouse (forwarded
+ * to miniapps on the pointer stream).
+ */
+import type {NeuralBandClaimEvent, NeuralBandHandwritingEvent, NeuralBandPointerEvent} from "@glassly/bluetooth-sdk"
+import {MiniappStreamType} from "@glassly/miniapp"
+
+import type {KeyboardEventPayload} from "../GlassesKeyboardInput"
+import localMiniappRuntime from "../LocalMiniappRuntime"
+
+export interface NeuralBandClaimStatus {
+  stage: "idle" | "progress" | "completed" | "failed"
+  message?: string
+  sessionExpired: boolean
+  bandName?: string
+}
+
+export interface NeuralBandHandwritingStatus {
+  phase: "idle" | "preparing" | "ready" | "restoring" | "finished"
+  message: string
+  problem?: string
+  /** The last text the band produced since handwriting was switched on. */
+  text: string
+}
+
+export interface NeuralBandInputOptions {
+  forward?: (stream: string, payload: unknown) => void
+  now?: () => number
+}
+
+const MODIFIERS = {shift: false, ctrl: false, alt: false, meta: false}
+
+/** One handwriting change as the key presses that would have typed it. */
+export function keyEventsForTextChange(previous: string, next: string, timestamp: number): KeyboardEventPayload[] {
+  let common = 0
+  while (common < previous.length && common < next.length && previous[common] === next[common]) common++
+  const events: KeyboardEventPayload[] = []
+  const press = (key: string, code: string, text?: string) => {
+    events.push({phase: "down", key, code, modifiers: MODIFIERS, text, repeat: false, timestamp})
+    events.push({phase: "up", key, code, modifiers: MODIFIERS, repeat: false, timestamp})
+  }
+  for (let i = common; i < previous.length; i++) press("Backspace", "Backspace")
+  for (const char of Array.from(next.slice(common))) {
+    if (char === "\n") press("Enter", "Enter")
+    else if (char === " ") press(" ", "Space", " ")
+    else press(char, codeFor(char), char)
+  }
+  return events
+}
+
+function codeFor(char: string): string {
+  if (/^[a-z]$/i.test(char)) return `Key${char.toUpperCase()}`
+  if (/^[0-9]$/.test(char)) return `Digit${char}`
+  return "Unidentified"
+}
+
+export class NeuralBandInput {
+  private claim: NeuralBandClaimStatus = {stage: "idle", sessionExpired: false}
+  private handwriting: NeuralBandHandwritingStatus = {phase: "idle", message: "", text: ""}
+  private claimListeners = new Set<(status: NeuralBandClaimStatus) => void>()
+  private handwritingListeners = new Set<(status: NeuralBandHandwritingStatus) => void>()
+  private readonly forward: (stream: string, payload: unknown) => void
+  private readonly now: () => number
+
+  constructor(options: NeuralBandInputOptions = {}) {
+    this.forward = options.forward ?? ((stream, payload) => localMiniappRuntime.forwardEvent(stream, payload))
+    this.now = options.now ?? (() => Date.now())
+  }
+
+  claimStatus(): NeuralBandClaimStatus {
+    return this.claim
+  }
+
+  onClaimStatus(cb: (status: NeuralBandClaimStatus) => void): () => void {
+    this.claimListeners.add(cb)
+    return () => this.claimListeners.delete(cb)
+  }
+
+  handwritingStatus(): NeuralBandHandwritingStatus {
+    return this.handwriting
+  }
+
+  onHandwritingStatus(cb: (status: NeuralBandHandwritingStatus) => void): () => void {
+    this.handwritingListeners.add(cb)
+    return () => this.handwritingListeners.delete(cb)
+  }
+
+  /** A new pairing attempt starts from a clean slate. */
+  resetClaim(): void {
+    this.setClaim({stage: "idle", sessionExpired: false})
+  }
+
+  handleClaim(event: NeuralBandClaimEvent): void {
+    this.setClaim({
+      stage: event.stage,
+      message: event.message,
+      sessionExpired: event.sessionExpired === true,
+      bandName: event.bandName,
+    })
+  }
+
+  handleHandwriting(event: NeuralBandHandwritingEvent): void {
+    if (event.kind === "state") {
+      const text = event.phase === "preparing" ? "" : this.handwriting.text
+      this.setHandwriting({phase: event.phase, message: event.message, problem: event.problem, text})
+      return
+    }
+    const previous = this.handwriting.text
+    if (event.text !== previous) {
+      for (const key of keyEventsForTextChange(previous, event.text, this.now())) {
+        this.forward(MiniappStreamType.KEYBOARD_EVENT, key)
+      }
+    }
+    this.setHandwriting({...this.handwriting, text: event.text})
+  }
+
+  handlePointer(event: NeuralBandPointerEvent): void {
+    if (event.kind === "move") {
+      this.forward(MiniappStreamType.POINTER_EVENT, {
+        kind: "move",
+        dx: event.dx,
+        dy: event.dy,
+        timestamp: event.timestamp,
+      })
+    } else {
+      this.forward(MiniappStreamType.POINTER_EVENT, {
+        kind: "buttons",
+        buttons: event.buttons,
+        timestamp: event.timestamp,
+      })
+    }
+  }
+
+  private setClaim(status: NeuralBandClaimStatus): void {
+    this.claim = status
+    for (const cb of this.claimListeners) cb(status)
+  }
+
+  private setHandwriting(status: NeuralBandHandwritingStatus): void {
+    this.handwriting = status
+    for (const cb of this.handwritingListeners) cb(status)
+  }
+}
+
+const neuralBandInput = new NeuralBandInput()
+export default neuralBandInput

package/src/services/neuralBand/NeuralBandSettingsSync.ts

@@ -0,0 +1,63 @@
+/**
+ * Pushes the Neural Band's user settings (air mouse, wearing hand) to the native
+ * controller: when the band connects, and whenever either setting changes while
+ * it is connected. The native side keeps nothing across connections.
+ */
+import BluetoothSdk from "@glassly/bluetooth-sdk/internal"
+
+import {useGlassesStore} from "../../stores/glasses"
+import {SETTINGS, useSettingsStore} from "../../stores/settings"
+import {ControllerTypes} from "../../types/enums"
+
+let unsubscribers: (() => void)[] = []
+
+function bandConnected(): boolean {
+  const glasses = useGlassesStore.getState()
+  const settings = useSettingsStore.getState()
+  return (
+    glasses.controllerConnected === true &&
+    glasses.controllerFullyBooted === true &&
+    settings.getSetting(SETTINGS.default_controller.key) === ControllerTypes.NEURAL_BAND
+  )
+}
+
+function pushAirMouse(): void {
+  if (!bandConnected()) return
+  const enabled = useSettingsStore.getState().getSetting(SETTINGS.neural_band_air_mouse.key) === true
+  void BluetoothSdk.neuralBandSetPointer(enabled).catch((err) =>
+    console.warn("NeuralBandSettingsSync: air mouse push failed:", err),
+  )
+}
+
+function pushHand(): void {
+  if (!bandConnected()) return
+  const hand = useSettingsStore.getState().getSetting(SETTINGS.neural_band_hand.key) === "left" ? "left" : "right"
+  void BluetoothSdk.neuralBandSetHand(hand).catch((err) =>
+    console.warn("NeuralBandSettingsSync: hand push failed:", err),
+  )
+}
+
+export function startNeuralBandSettingsSync(): void {
+  if (unsubscribers.length > 0) return
+  let wasConnected = bandConnected()
+  unsubscribers = [
+    useGlassesStore.subscribe(
+      (s) => s.controllerConnected === true && s.controllerFullyBooted === true,
+      () => {
+        const connected = bandConnected()
+        if (connected && !wasConnected) {
+          pushAirMouse()
+          pushHand()
+        }
+        wasConnected = connected
+      },
+    ),
+    useSettingsStore.subscribe((s) => s.getSetting(SETTINGS.neural_band_air_mouse.key), pushAirMouse),
+    useSettingsStore.subscribe((s) => s.getSetting(SETTINGS.neural_band_hand.key), pushHand),
+  ]
+}
+
+export function stopNeuralBandSettingsSync(): void {
+  for (const unsubscribe of unsubscribers) unsubscribe()
+  unsubscribers = []
+}