@glassly/engine 0.3.8-dev.998 → 0.4.0-dev.1017

package/src/facades/ai.ts

@@ -21,6 +21,12 @@ export const ai = {
     /** The Settings > Offline Models pick. */
     selectedModelId: (): LocalLlmModelId => localLlmModelManager.selectedModelId(),
     select: (id: LocalLlmModelId): Promise<void> => localLlmModelManager.select(id),
+    /** Whether the model fits this phone's memory at all. */
+    fitsDevice: (id: LocalLlmModelId): boolean => localLlmModelManager.fitsDevice(id),
+    /** The OS killed the app while this model loaded; picking it again retries it. */
+    isBlocked: (id: LocalLlmModelId): boolean => localLlmModelManager.isBlocked(id),
+    /** Why the model will not load on this phone, or null when it can. */
+    unusableReason: (id: LocalLlmModelId): string | null => localLlmModelManager.unusableReason(id),
     isDownloaded: (id?: LocalLlmModelId): Promise<boolean> => localLlmModelManager.isModelAvailable(id),
     downloadedModelIds: (): Promise<LocalLlmModelId[]> => localLlmModelManager.downloadedModelIds(),
     download: (id?: LocalLlmModelId): Promise<void> => localLlmModelManager.downloadModel(id),

package/src/facades/glasses.ts

@@ -19,6 +19,7 @@ import type {
   Device,
   KeyboardAdvertEvent,
   KeyboardPairingEvent,
+  NeuralBandFirmwareEvent,
   PairedController,
   TouchEvent,
 } from "@glassly/bluetooth-sdk"
@@ -39,6 +40,7 @@ import {pushAllBluetoothSettings} from "../services/GlassesSettingsSync"
 import {isControllerReady, pairedControllersFrom, readyControllers} from "../services/controllers"
 import neuralBandInput, {
   type NeuralBandClaimStatus,
+  type NeuralBandFirmwareStatus,
   type NeuralBandHandwritingStatus,
   type NeuralBandHandwritingUpdate,
 } from "../services/neuralBand/NeuralBandInput"
@@ -344,6 +346,21 @@ export const glasses = {
     /** The band's air mouse; movement reaches miniapps on the pointer stream. */
     setPointer: (id: string, enabled: boolean): Promise<void> => BluetoothSdk.neuralBandSetPointer(id, enabled),
     setHand: (id: string, hand: "left" | "right"): Promise<void> => BluetoothSdk.neuralBandSetHand(id, hand),
+    firmwareStatus: (id: string): NeuralBandFirmwareStatus => ({...neuralBandInput.firmwareStatus(id)}),
+    onFirmwareStatus: (cb: (update: {id: string; status: NeuralBandFirmwareStatus}) => void): (() => void) =>
+      neuralBandInput.onFirmwareStatus(cb),
+    refreshFirmware: async (id: string): Promise<NeuralBandFirmwareStatus> => {
+      const info = await BluetoothSdk.neuralBandFirmwareInfo(id)
+      neuralBandInput.handleFirmware({
+        ...(info as object),
+        type: "neural_band_firmware",
+        controllerId: id,
+      } as NeuralBandFirmwareEvent)
+      return neuralBandInput.firmwareStatus(id)
+    },
+    checkFirmware: (id: string): Promise<void> => BluetoothSdk.neuralBandCheckFirmware(id),
+    updateFirmware: (id: string, mode: "update" | "cancel" | "key" | "send" | "trial" | "install"): Promise<void> =>
+      BluetoothSdk.neuralBandUpdateFirmware(id, mode),
   },
 
   // --- watch: an Apple Watch over WatchConnectivity (iOS), a Wear OS watch over the Data Layer (Android) ---

package/src/generated/releaseMetadata.ts

@@ -11,10 +11,10 @@ export interface EngineReleaseMetadata {
 
 export const ENGINE_RELEASE_METADATA: Readonly<EngineReleaseMetadata> = Object.freeze({
   "schemaVersion": 1,
-  "familyBaseVersion": "0.3.8",
-  "releaseIdentity": "0.3.8-dev.998",
-  "releaseSetId": "glassly-0.3.8-dev.998",
-  "sourceCommit": "56392e6a51a274b34157ef34792183652af28ebe",
+  "familyBaseVersion": "0.4.0",
+  "releaseIdentity": "0.4.0-dev.1017",
+  "releaseSetId": "glassly-0.4.0-dev.1017",
+  "sourceCommit": "2d95873e90b2de55f29df33e0e361469fc2b58f8",
   "otaManifestUrl": null,
   "otaManifestSha256": null
 })

package/src/index.ts

@@ -239,6 +239,7 @@ export {
 } from "./services/neuralBand/MetaAuth"
 export type {
   NeuralBandClaimStatus,
+  NeuralBandFirmwareStatus,
   NeuralBandHandwritingStatus,
   NeuralBandHandwritingUpdate,
 } from "./services/neuralBand/NeuralBandInput"

package/src/services/CloudClientService.ts

@@ -19,6 +19,7 @@ import type {
   RuntimeSnapshot,
   StoreCatalogResponse,
   StoreListing,
+  StoreReleasesResponse,
 } from "@glassly/cloud-client/react-native"
 import type {SubjectTokenType} from "@glassly/cloud-client"
 import {AppState, Platform} from "react-native"
@@ -778,6 +779,13 @@ export const cloudClientService = {
     return c.core.store.get(packageName)
   },
 
+  async getStoreReleases(packageName: string): Promise<StoreReleasesResponse> {
+    if (!client) this.init()
+    const c = client
+    if (!c?.core) throw new Error("cloud client core is unavailable")
+    return c.core.store.releases(packageName)
+  },
+
   /** Bytes of a store icon or screenshot; these routes need the user Bearer. */
   async fetchStoreAsset(url: string): Promise<Uint8Array> {
     if (!client) this.init()

package/src/services/DeviceEventRouter.ts

@@ -245,6 +245,7 @@ export function startDeviceEventRouter(): void {
   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(BluetoothSdk.addListener("neural_band_firmware", (event) => neuralBandInput.handleFirmware(event)))
   subs.push({
     remove: useGlassesStore.subscribe(
       (s) => s.keyboardConnected === true,

package/src/services/GlassesSensorService.ts

@@ -110,7 +110,7 @@ export class GlassesSensorService {
   private commandFailed(): never {
     fail(
       MiniappErrorCode.INTERNAL,
-      "Sensor command failed: connect G2 custom firmware and keep its miniapp display active",
+      "Sensor command failed: the glasses need Glassly custom firmware with this sensor, and on the G2 an active miniapp display",
     )
   }
 

package/src/services/LocalLlmModelManager.ts

@@ -15,6 +15,7 @@ import {Platform} from "react-native"
 import * as RNFS from "@dr.pogodin/react-native-fs"
 
 import {SETTINGS, useSettingsStore} from "../stores/settings"
+import {storage} from "../utils/storage"
 
 export type LocalLlmModelId = "qwen3-0.6b" | "qwen3-1.7b" | "qwen3-4b"
 
@@ -28,7 +29,7 @@ export interface LocalLlmModelConfig {
   sizeBytes: number
   /** Exact size of the published .pte; the availability check compares against it. */
   modelBytes: number
-  /** Rough resident memory while loaded; the Settings copy warns above ~half of device RAM. */
+  /** Rough resident memory while loaded; `fitsDevice` holds it against the phone's RAM. */
   ramBytes: number
   urls: {
     model: string
@@ -106,6 +107,36 @@ export function isLocalLlmModelId(value: unknown): value is LocalLlmModelId {
   return typeof value === "string" && value in MODELS
 }
 
+// Without the increased-memory-limit entitlement iOS kills a foreground app
+// at roughly 60% of physical RAM (Android's low-memory killer is no kinder),
+// and the host holds about 1 GB besides the model: JS runtimes, WebViews,
+// the speech model. A 4 GB phone fits the 0.6B model and nothing larger.
+const APP_MEMORY_SHARE = 0.6
+const HOST_BASELINE_BYTES = 1 * GB
+
+export function modelFitsMemory(model: LocalLlmModelConfig, deviceMemoryBytes: number | null): boolean {
+  if (!deviceMemoryBytes) return true
+  return model.ramBytes + HOST_BASELINE_BYTES <= deviceMemoryBytes * APP_MEMORY_SHARE
+}
+
+let deviceMemory: number | null | undefined
+function deviceMemoryBytes(): number | null {
+  if (deviceMemory === undefined) {
+    try {
+      deviceMemory = (require("expo-device") as {totalMemory?: number | null}).totalMemory ?? null
+    } catch {
+      deviceMemory = null
+    }
+  }
+  return deviceMemory
+}
+
+// Written before a model's first load and generation, cleared after either
+// ends. A marker still there at the next launch means the OS killed the app
+// mid-load (out of memory), so that model stays off until picked again.
+const COLD_LOAD_KEY = "local_llm_cold_load"
+const BLOCKED_MODELS_KEY = "local_llm_blocked_models"
+
 type StatusListener = (status: LocalLlmDownloadStatus | null) => void
 
 class LocalLlmModelManager {
@@ -114,6 +145,7 @@ class LocalLlmModelManager {
   private downloadJobId?: number
   private inFlight: {modelId: LocalLlmModelId; promise: Promise<void>} | null = null
   private cancelled = false
+  private coldLoadRecovered = false
   private currentStatus: LocalLlmDownloadStatus | null = null
   private listeners = new Set<StatusListener>()
   private modelReadyListeners = new Set<(modelId: LocalLlmModelId) => void>()
@@ -135,16 +167,89 @@ class LocalLlmModelManager {
     return MODELS[id]
   }
 
-  /** The Settings > AI Models pick; garbage in the store resolves to the default. */
+  /**
+   * The model on-device requests use: the Settings > Offline Models pick
+   * (garbage resolves to the default) while it is usable, else the largest
+   * model that is. With nothing usable it stays the pick, and loading it
+   * fails with `unusableReason`.
+   */
   selectedModelId(): LocalLlmModelId {
     const raw = useSettingsStore.getState().getSetting(SETTINGS.local_llm_model.key)
-    return isLocalLlmModelId(raw) ? raw : DEFAULT_LOCAL_LLM_MODEL
+    const picked = isLocalLlmModelId(raw) ? raw : DEFAULT_LOCAL_LLM_MODEL
+    if (this.isUsable(picked)) return picked
+    const fallback = this.models()
+      .filter((m) => this.isUsable(m.id))
+      .sort((a, b) => b.ramBytes - a.ramBytes)[0]
+    return fallback?.id ?? picked
   }
 
+  /** Picking a model in Settings is also the way to retry one that crashed the app. */
   async select(id: LocalLlmModelId): Promise<void> {
+    this.unblock(id)
     await useSettingsStore.getState().setSetting(SETTINGS.local_llm_model.key, id)
   }
 
+  fitsDevice(id: LocalLlmModelId): boolean {
+    return modelFitsMemory(MODELS[id], deviceMemoryBytes())
+  }
+
+  /** The OS killed the app while this model loaded; it stays off until picked again. */
+  isBlocked(id: LocalLlmModelId): boolean {
+    return this.blockedModelIds().includes(id)
+  }
+
+  isUsable(id: LocalLlmModelId): boolean {
+    return this.fitsDevice(id) && !this.isBlocked(id)
+  }
+
+  /** Why `id` will not load on this phone, or null when it can. */
+  unusableReason(id: LocalLlmModelId): string | null {
+    const label = MODELS[id].label
+    if (!this.fitsDevice(id)) {
+      return `${label} needs more memory than this phone has. Pick a smaller model in Settings > Offline Models.`
+    }
+    if (this.isBlocked(id)) {
+      return `${label} closed the app the last time it loaded. Pick it again in Settings > Offline Models to retry, or pick a smaller model.`
+    }
+    return null
+  }
+
+  /** Mark the start of a model's first load and generation in this process. */
+  beginColdLoad(id: LocalLlmModelId): void {
+    this.recoverColdLoad()
+    storage.save(COLD_LOAD_KEY, id)
+  }
+
+  endColdLoad(): void {
+    storage.removeMultiple([COLD_LOAD_KEY])
+  }
+
+  private blockedModelIds(): LocalLlmModelId[] {
+    this.recoverColdLoad()
+    const stored = storage.load<unknown>(BLOCKED_MODELS_KEY)
+    const ids = stored.is_ok() ? stored.value : []
+    return Array.isArray(ids) ? ids.filter(isLocalLlmModelId) : []
+  }
+
+  private unblock(id: LocalLlmModelId): void {
+    const remaining = this.blockedModelIds().filter((blocked) => blocked !== id)
+    storage.save(BLOCKED_MODELS_KEY, remaining)
+  }
+
+  // A cold-load marker left by an earlier process: that load never finished.
+  private recoverColdLoad(): void {
+    if (this.coldLoadRecovered) return
+    this.coldLoadRecovered = true
+    const marker = storage.load<unknown>(COLD_LOAD_KEY)
+    if (!marker.is_ok() || !isLocalLlmModelId(marker.value)) return
+    const id = marker.value
+    console.warn(`LOCAL_LLM: the app was killed while ${id} loaded; keeping it off until it is picked again`)
+    const stored = storage.load<unknown>(BLOCKED_MODELS_KEY)
+    const blocked = stored.is_ok() && Array.isArray(stored.value) ? stored.value.filter(isLocalLlmModelId) : []
+    if (!blocked.includes(id)) storage.save(BLOCKED_MODELS_KEY, [...blocked, id])
+    storage.removeMultiple([COLD_LOAD_KEY])
+  }
+
   getModelDirectory(): string {
     return `${RNFS.DocumentDirectoryPath}/llm_models`
   }
@@ -210,6 +315,7 @@ class LocalLlmModelManager {
   async ensureSelectedModel(): Promise<boolean> {
     const id = this.selectedModelId()
     if (await this.isModelAvailable(id)) return true
+    if (!this.fitsDevice(id)) return false
     void this.downloadModel(id).catch((error) => {
       console.warn(`LOCAL_LLM: background download of ${id} failed:`, error)
     })
@@ -222,6 +328,7 @@ class LocalLlmModelManager {
    * the running one — the RNFS job slot is singular.
    */
   async downloadModel(id: LocalLlmModelId = this.selectedModelId()): Promise<void> {
+    if (!this.fitsDevice(id)) throw new Error(this.unusableReason(id) ?? `${MODELS[id].label} does not fit this phone.`)
     if (this.inFlight) {
       if (this.inFlight.modelId === id) return this.inFlight.promise
       await this.inFlight.promise.catch(() => undefined)

package/src/services/LocalLlmProvider.ts

@@ -187,6 +187,11 @@ class LocalLlmProvider {
 
   private async completeInner(request: LlmCompleteRequest): Promise<LocalLlmCompleteResult> {
     this.clearIdleTimer()
+    // Loading and the first generation are where memory peaks; if the OS kills
+    // the app in between, the marker keeps the next launch from looping on it.
+    const selectedId = localLlmModelManager.selectedModelId()
+    const coldModelId = this.loaded?.modelId === selectedId ? null : selectedId
+    if (coldModelId) localLlmModelManager.beginColdLoad(coldModelId)
     try {
       const model = await this.ensureLoaded()
       const jsonMode = request.jsonMode === true
@@ -248,6 +253,7 @@ class LocalLlmProvider {
       )
       return {...completion, modelId: model.modelId}
     } finally {
+      if (coldModelId) localLlmModelManager.endColdLoad()
       this.armIdleTimer()
     }
   }
@@ -272,6 +278,8 @@ class LocalLlmProvider {
     // Runs inside the request queue, so nothing is generating; unload() would
     // wait on that same queue.
     this.releaseRunner()
+    const unusable = localLlmModelManager.unusableReason(modelId)
+    if (unusable) throw new Error(unusable)
     if (!(await localLlmModelManager.isModelAvailable(modelId))) {
       throw new Error(`on-device model ${modelId} is not downloaded`)
     }

package/src/services/LocalMiniappRuntime.ts

@@ -673,6 +673,9 @@ class LocalMiniappRuntime {
   private connectedApps: Map<string, ConnectedMiniapp> = new Map()
   /** Claimed gestures (CLAIM_GESTURES): a stack per gesture, the most recent claimer holding it. */
   private gestureClaims: GestureClaimState = emptyGestureClaims()
+  /** Apps with a text field open on the glasses (TEXT_FIELD). */
+  private textFieldApps = new Set<string>()
+  private textFieldListeners = new Set<(open: boolean) => void>()
   // The last main-view frame each app asked to render. Widget mode refuses
   // frames and demotion clears them, and an app that has drawn once may not
   // draw again on its own, so promotion replays this.
@@ -1295,6 +1298,7 @@ class LocalMiniappRuntime {
     }
     // Its gesture claims go back to whoever claimed them before.
     this.applyGestureClaimChanges(dropGestureClaims(this.gestureClaims, packageName))
+    this.setTextFieldOpen(packageName, false)
     this.retainedRenders.delete(packageName)
 
     // Warm-up is a request-owned camera lease. Cancel it even if the app record was already
@@ -1478,6 +1482,9 @@ class LocalMiniappRuntime {
       case MiniappRequestType.CLAIM_GESTURES:
         this.handleClaimGestures(packageName, payload, requestId)
         break
+      case MiniappRequestType.TEXT_FIELD:
+        this.handleTextField(packageName, payload, requestId)
+        break
       case MiniappRequestType.DISPLAY:
         this.handleDisplay(packageName, payload, requestId)
         break
@@ -2214,6 +2221,48 @@ class LocalMiniappRuntime {
     }
   }
 
+  /**
+   * TEXT_FIELD (session.input.setTextFieldOpen): the app has a text field on
+   * the glasses, or no longer does. Text entry that costs power to leave on
+   * (Neural Band handwriting) runs while any app has one. Cleared on app stop.
+   */
+  private handleTextField(packageName: string, payload: Record<string, unknown>, requestId?: string): void {
+    if (typeof payload.open !== "boolean") {
+      this.sendResult(packageName, requestId, false, undefined, {
+        code: MiniappErrorCode.INVALID_ARGUMENT,
+        message: "Text field open must be a boolean",
+      })
+      return
+    }
+    if (this.connectedApps.has(packageName)) this.setTextFieldOpen(packageName, payload.open)
+    this.sendResult(packageName, requestId, true)
+  }
+
+  private setTextFieldOpen(packageName: string, open: boolean): void {
+    const before = this.textFieldApps.size > 0
+    if (open) this.textFieldApps.add(packageName)
+    else this.textFieldApps.delete(packageName)
+    const after = this.textFieldApps.size > 0
+    if (before === after) return
+    for (const cb of this.textFieldListeners) {
+      try {
+        cb(after)
+      } catch (err) {
+        console.warn(`${LOG_TAG}: text field listener failed:`, err)
+      }
+    }
+  }
+
+  /** True while any running miniapp has a text field open on the glasses. */
+  public hasOpenTextField(): boolean {
+    return this.textFieldApps.size > 0
+  }
+
+  public onTextFieldChange(cb: (open: boolean) => void): () => void {
+    this.textFieldListeners.add(cb)
+    return () => this.textFieldListeners.delete(cb)
+  }
+
   /** The app holding `gesture` (the most recent claimer), or null when it is unclaimed. */
   public gestureClaimant(gesture: string): string | null {
     const claimant = gestureClaimant(this.gestureClaims, gesture)
@@ -4322,6 +4371,18 @@ class LocalMiniappRuntime {
     primaryError: {code: MiniappErrorCode; message: string} | null,
   ): Promise<void> {
     const modelId = localLlmModelManager.selectedModelId()
+    const unusable = localLlmModelManager.unusableReason(modelId)
+    if (unusable) {
+      console.warn(`${LOG_TAG}: ai.complete on-device for ${packageName} (${reason}): ${unusable}`)
+      this.sendResult(
+        packageName,
+        requestId,
+        false,
+        undefined,
+        primaryError ?? {code: MiniappErrorCode.AI_LOCAL_UNAVAILABLE, message: unusable},
+      )
+      return
+    }
     if (!(await localLlmModelManager.ensureSelectedModel())) {
       const status = localLlmModelManager.getStatus()
       const state =
@@ -4338,7 +4399,7 @@ class LocalMiniappRuntime {
         undefined,
         primaryError ?? {
           code: MiniappErrorCode.AI_LOCAL_UNAVAILABLE,
-          message: `The on-device model (${localLlmModelManager.model(modelId).label}) ${state}. Manage it in Settings > AI Models.`,
+          message: `The on-device model (${localLlmModelManager.model(modelId).label}) ${state}. Manage it in Settings > Offline Models.`,
         },
       )
       return

package/src/services/controllers.ts

@@ -55,6 +55,8 @@ const INPUT_SURFACES: Readonly<Record<string, readonly InputSurface[]>> = {
   [ControllerTypes.WEAR_OS]: [WATCH_SURFACE],
   [ControllerTypes.GAMEBRICK]: [GAMEBRICK_SURFACE],
   [ControllerTypes.IINE_ANANKE]: [GAMEBRICK_SURFACE],
+  [ControllerTypes.ZERO2]: [GAMEBRICK_SURFACE],
+  [ControllerTypes.MICRO]: [GAMEBRICK_SURFACE],
   [ControllerTypes.R1]: [],
 }
 

package/src/services/neuralBand/HandwritingGate.ts

@@ -0,0 +1,111 @@
+/**
+ * Decides when each connected Meta Neural Band runs its handwriting model. The
+ * model streams to the phone for as long as it runs, written on or not, so it
+ * runs only while it can type somewhere: the wearer has handwriting enabled
+ * and a miniapp has a text field open on the glasses. It outlives the last
+ * field by OFF_DELAY_MS, so moving between fields doesn't restart it. A session
+ * the band ends on its own (timeout, refused setting, silence) isn't retried
+ * until no field is open, so a band that can't run the model isn't asked again
+ * and again.
+ */
+import type {NeuralBandHandwritingStatus} from "./NeuralBandInput"
+
+type Phase = NeuralBandHandwritingStatus["phase"]
+
+export interface HandwritingGateDeps {
+  enabled: () => boolean
+  textFieldOpen: () => boolean
+  setHandwriting: (id: string, enabled: boolean) => Promise<void>
+  setTimeout: (fn: () => void, ms: number) => unknown
+  clearTimeout: (handle: unknown) => void
+}
+
+interface Band {
+  /** What we last asked this band for. */
+  requested: boolean
+  failed: boolean
+  phase: Phase
+}
+
+export const OFF_DELAY_MS = 5_000
+const ACTIVE = new Set<Phase>(["preparing", "ready", "restoring"])
+
+export class HandwritingGate {
+  private bands = new Map<string, Band>()
+  private offTimer: unknown = null
+
+  constructor(private readonly deps: HandwritingGateDeps) {}
+
+  /** The connected bands. A band keeps nothing across connections, so a reconnect starts fresh. */
+  setBands(ids: string[]): void {
+    for (const id of [...this.bands.keys()]) if (!ids.includes(id)) this.bands.delete(id)
+    for (const id of ids) if (!this.bands.has(id)) this.bands.set(id, {requested: false, failed: false, phase: "idle"})
+    this.update()
+  }
+
+  /** A band reported its handwriting phase. */
+  status(id: string, phase: Phase): void {
+    const band = this.bands.get(id)
+    if (!band) return
+    band.phase = phase
+    if (phase === "finished" && band.requested) {
+      band.requested = false
+      band.failed = true
+    }
+    this.update()
+  }
+
+  /** Re-evaluate after the setting or the open text fields changed. */
+  update(): void {
+    const enabled = this.deps.enabled()
+    if (enabled && this.deps.textFieldOpen()) {
+      this.clearOffTimer()
+      for (const [id, band] of this.bands) {
+        // A session still winding down (or one we didn't start) has to finish first.
+        if (band.requested || band.failed || ACTIVE.has(band.phase)) continue
+        this.request(id, band, true)
+      }
+      return
+    }
+    for (const band of this.bands.values()) band.failed = false
+    if (![...this.bands.values()].some((band) => band.requested)) {
+      this.clearOffTimer()
+      return
+    }
+    if (!enabled) {
+      this.clearOffTimer()
+      this.stopAll()
+    } else if (this.offTimer === null) {
+      this.offTimer = this.deps.setTimeout(() => {
+        this.offTimer = null
+        if (!this.deps.textFieldOpen() || !this.deps.enabled()) this.stopAll()
+      }, OFF_DELAY_MS)
+    }
+  }
+
+  dispose(): void {
+    this.clearOffTimer()
+    this.bands.clear()
+  }
+
+  private stopAll(): void {
+    for (const [id, band] of this.bands) if (band.requested) this.request(id, band, false)
+  }
+
+  private request(id: string, band: Band, enabled: boolean): void {
+    band.requested = enabled
+    this.deps.setHandwriting(id, enabled).catch((err) => {
+      console.warn(`HandwritingGate: turning handwriting ${enabled ? "on" : "off"} failed:`, err)
+      if (enabled && this.bands.get(id) === band && band.requested) {
+        band.requested = false
+        band.failed = true
+      }
+    })
+  }
+
+  private clearOffTimer(): void {
+    if (this.offTimer === null) return
+    this.deps.clearTimeout(this.offTimer)
+    this.offTimer = null
+  }
+}

package/src/services/neuralBand/NeuralBandInput.ts

@@ -6,7 +6,12 @@
  * latest claim is also kept on its own, since the pairing screen runs before
  * the band's id reaches JS.
  */
-import type {NeuralBandClaimEvent, NeuralBandHandwritingEvent, NeuralBandPointerEvent} from "@glassly/bluetooth-sdk"
+import type {
+  NeuralBandClaimEvent,
+  NeuralBandFirmwareEvent,
+  NeuralBandHandwritingEvent,
+  NeuralBandPointerEvent,
+} from "@glassly/bluetooth-sdk"
 import {MiniappStreamType} from "@glassly/miniapp"
 
 import type {KeyboardEventPayload} from "../GlassesKeyboardInput"
@@ -34,6 +39,8 @@ export interface NeuralBandHandwritingUpdate {
   status: NeuralBandHandwritingStatus
 }
 
+export type NeuralBandFirmwareStatus = Omit<NeuralBandFirmwareEvent, "type" | "controllerId"> & {known: boolean}
+
 export interface NeuralBandInputOptions {
   forward?: (stream: string, payload: unknown) => void
   now?: () => number
@@ -67,13 +74,25 @@ function codeFor(char: string): string {
 
 const IDLE_CLAIM: NeuralBandClaimStatus = {stage: "idle", sessionExpired: false}
 const IDLE_HANDWRITING: NeuralBandHandwritingStatus = {phase: "idle", message: "", text: ""}
+const IDLE_FIRMWARE: NeuralBandFirmwareStatus = {
+  known: false,
+  connected: false,
+  hasMetaSession: false,
+  checked: false,
+  updateAvailable: false,
+  phase: "idle",
+  progress: 0,
+  message: "",
+}
 
 export class NeuralBandInput {
   private latestClaim: NeuralBandClaimStatus = IDLE_CLAIM
   private claims = new Map<string, NeuralBandClaimStatus>()
   private handwriting = new Map<string, NeuralBandHandwritingStatus>()
+  private firmware = new Map<string, NeuralBandFirmwareStatus>()
   private claimListeners = new Set<(status: NeuralBandClaimStatus) => void>()
   private handwritingListeners = new Set<(update: NeuralBandHandwritingUpdate) => void>()
+  private firmwareListeners = new Set<(update: {id: string; status: NeuralBandFirmwareStatus}) => void>()
   private readonly forward: (stream: string, payload: unknown) => void
   private readonly now: () => number
 
@@ -102,6 +121,15 @@ export class NeuralBandInput {
     return () => this.handwritingListeners.delete(cb)
   }
 
+  firmwareStatus(controllerId: string): NeuralBandFirmwareStatus {
+    return this.firmware.get(controllerId) ?? IDLE_FIRMWARE
+  }
+
+  onFirmwareStatus(cb: (update: {id: string; status: NeuralBandFirmwareStatus}) => void): () => void {
+    this.firmwareListeners.add(cb)
+    return () => this.firmwareListeners.delete(cb)
+  }
+
   /** A new pairing attempt starts from a clean slate. */
   resetClaim(): void {
     this.latestClaim = IDLE_CLAIM
@@ -112,6 +140,14 @@ export class NeuralBandInput {
   forget(controllerId: string): void {
     this.claims.delete(controllerId)
     this.handwriting.delete(controllerId)
+    this.firmware.delete(controllerId)
+  }
+
+  handleFirmware(event: NeuralBandFirmwareEvent): void {
+    const {type: _type, controllerId, ...rest} = event
+    const status: NeuralBandFirmwareStatus = {...rest, known: true}
+    this.firmware.set(controllerId, status)
+    for (const cb of this.firmwareListeners) cb({id: controllerId, status})
   }
 
   handleClaim(event: NeuralBandClaimEvent): void {