@glassly/engine 0.3.3-dev.670 → 0.3.4-dev.675

package/src/facades/glasses.ts

@@ -14,9 +14,11 @@ import BluetoothSdk from "@glassly/bluetooth-sdk/internal"
 import type {
   ButtonPressEvent,
   ConnectOptions,
+  ControllerStatus,
   Device,
   KeyboardAdvertEvent,
   KeyboardPairingEvent,
+  PairedController,
   TouchEvent,
 } from "@glassly/bluetooth-sdk"
 import {useGlassesStore} from "../stores/glasses"
@@ -26,9 +28,11 @@ import micStateCoordinator from "../services/MicStateCoordinator"
 import {projectPairingIdentity} from "../services/PairingIdentity"
 import {isGlassesConnected, isGlassesReady} from "../services/GlassesReadiness"
 import {pushAllBluetoothSettings} from "../services/GlassesSettingsSync"
+import {isControllerReady, pairedControllersFrom, readyControllers} from "../services/controllers"
 import neuralBandInput, {
   type NeuralBandClaimStatus,
   type NeuralBandHandwritingStatus,
+  type NeuralBandHandwritingUpdate,
 } from "../services/neuralBand/NeuralBandInput"
 import {recordSupportProfileConnectionFailure} from "../services/SupportProfileSync"
 import {getModelCapabilities, type DeviceTypes} from "../types"
@@ -55,14 +59,17 @@ function projectStatus() {
   }
 }
 
-function projectControllerStatus() {
-  const s = useGlassesStore.getState()
-  return {
-    connected: s.controllerConnected,
-    fullyBooted: s.controllerFullyBooted,
-    battery: s.controllerBatteryLevel,
-    signal: s.controllerSignalStrength,
+function projectControllerList(): PairedController[] {
+  return pairedControllersFrom(useSettingsStore.getState().getSetting(SETTINGS.controllers.key))
+}
+
+// Copies: snapshots must not hand callers mutable references into the store.
+function projectControllerStatuses(): Record<string, ControllerStatus> {
+  const statuses: Record<string, ControllerStatus> = {}
+  for (const [id, status] of Object.entries(useGlassesStore.getState().controllers ?? {})) {
+    statuses[id] = {...status}
   }
+  return statuses
 }
 
 function projectKeyboardStatus() {
@@ -107,7 +114,6 @@ function projectInfo() {
 }
 
 export type GlassesStatusSnapshot = ReturnType<typeof projectStatus>
-export type ControllerStatusSnapshot = ReturnType<typeof projectControllerStatus>
 export type KeyboardStatusSnapshot = ReturnType<typeof projectKeyboardStatus>
 export type GlassesInfoSnapshot = ReturnType<typeof projectInfo>
 
@@ -259,45 +265,68 @@ export const glasses = {
     },
   },
 
-  // --- ring controller (optional input device) ---
-  controller: {
-    connectDefault: (): Promise<void> => BluetoothSdk.connectDefaultController(),
-    disconnect: (): Promise<void> => BluetoothSdk.disconnectController(),
-    forget: (): Promise<void> => BluetoothSdk.forgetController(),
-    status: (): ControllerStatusSnapshot => projectControllerStatus(),
-    onStatus: (cb: (status: ControllerStatusSnapshot) => void): (() => void) => {
-      let last = JSON.stringify(projectControllerStatus())
-      return useGlassesStore.subscribe(() => {
-        const snap = projectControllerStatus()
-        const key = JSON.stringify(snap)
+  // --- controllers (input accessories linked to the phone), by registry id ---
+  controllers: {
+    /** Paired controllers in pairing order. */
+    list: (): PairedController[] => projectControllerList(),
+    onList: (cb: (controllers: PairedController[]) => void): (() => void) => {
+      let last = JSON.stringify(projectControllerList())
+      return useSettingsStore.subscribe(() => {
+        const list = projectControllerList()
+        const key = JSON.stringify(list)
         if (key === last) return
         last = key
-        cb(snap)
+        cb(list)
       })
     },
+    /** Live driver statuses by id; a paired controller without an entry is idle. */
+    statuses: (): Record<string, ControllerStatus> => projectControllerStatuses(),
+    status: (id: string): ControllerStatus | undefined => projectControllerStatuses()[id],
+    onStatus: (cb: (statuses: Record<string, ControllerStatus>) => void): (() => void) =>
+      useGlassesStore.subscribe(
+        (s) => s.controllers,
+        () => cb(projectControllerStatuses()),
+      ),
+    /** Controllers delivering input (linked, route or claim done). */
+    connected: (): ControllerStatus[] => readyControllers(projectControllerStatuses()),
+    isConnected: (model?: string): boolean =>
+      Object.values(useGlassesStore.getState().controllers ?? {}).some(
+        (status) => isControllerReady(status) && (model === undefined || status.model === model),
+      ),
+    connect: (id: string): Promise<void> => BluetoothSdk.connectController(id),
+    /** Reconnect every paired controller that is not connected. */
+    connectAll: (): Promise<void> => BluetoothSdk.connectControllers(),
+    /** Drop an in-flight controller scan or pairing; paired records are untouched. */
+    cancelAttempt: (): Promise<void> => BluetoothSdk.cancelControllerAttempt(),
+    /** Disconnect; the controller stays paired. */
+    disconnect: (id: string): Promise<void> => BluetoothSdk.disconnectController(id),
+    forget: async (id: string): Promise<void> => {
+      await BluetoothSdk.forgetController(id)
+      neuralBandInput.forget(id)
+    },
   },
 
-  // --- Meta Neural Band (a controller with a claim step and its own features) ---
+  // --- Meta Neural Band (a controller with a claim step and its own features), by controller id ---
   neuralBand: {
-    /** Store the Meta account session the one-time band claim uses. */
+    /** Store the Meta account session the one-time band claim uses (account-wide). */
     setMetaSession: (accessToken: string, userId: string): Promise<void> =>
       BluetoothSdk.neuralBandSetMetaSession(accessToken, userId),
     clearMetaSession: (): Promise<void> => BluetoothSdk.neuralBandClearMetaSession(),
     hasMetaSession: (): Promise<boolean> => BluetoothSdk.neuralBandHasMetaSession(),
-    /** A band identity is stored on this phone, so the remembered band connects without a claim. */
-    isClaimed: (): Promise<boolean> => BluetoothSdk.neuralBandIsClaimed(),
-    /** The latest claim progress, kept across screens. */
-    claimStatus: (): NeuralBandClaimStatus => neuralBandInput.claimStatus(),
+    /** This band's identity is stored on this phone, so it reconnects without a claim. */
+    isClaimed: (id: string): Promise<boolean> => BluetoothSdk.neuralBandIsClaimed(id),
+    /** The latest claim progress of any band (with its `controllerId`), kept across screens. */
+    claimStatus: (): NeuralBandClaimStatus => ({...neuralBandInput.claimStatus()}),
     resetClaim: (): void => neuralBandInput.resetClaim(),
     onClaimStatus: (cb: (status: NeuralBandClaimStatus) => void): (() => void) => neuralBandInput.onClaimStatus(cb),
     /** The band's handwriting model; writing arrives on the miniapp keyboard stream. */
-    setHandwriting: (enabled: boolean): Promise<void> => BluetoothSdk.neuralBandSetHandwriting(enabled),
-    handwritingStatus: (): NeuralBandHandwritingStatus => neuralBandInput.handwritingStatus(),
-    onHandwritingStatus: (cb: (status: NeuralBandHandwritingStatus) => void): (() => void) =>
+    setHandwriting: (id: string, enabled: boolean): Promise<void> => BluetoothSdk.neuralBandSetHandwriting(id, enabled),
+    handwritingStatus: (id: string): NeuralBandHandwritingStatus => ({...neuralBandInput.handwritingStatus(id)}),
+    onHandwritingStatus: (cb: (update: NeuralBandHandwritingUpdate) => void): (() => void) =>
       neuralBandInput.onHandwritingStatus(cb),
     /** The band's air mouse; movement reaches miniapps on the pointer stream. */
-    setPointer: (enabled: boolean): Promise<void> => BluetoothSdk.neuralBandSetPointer(enabled),
-    setHand: (hand: "left" | "right"): Promise<void> => BluetoothSdk.neuralBandSetHand(hand),
+    setPointer: (id: string, enabled: boolean): Promise<void> => BluetoothSdk.neuralBandSetPointer(id, enabled),
+    setHand: (id: string, hand: "left" | "right"): Promise<void> => BluetoothSdk.neuralBandSetHand(id, hand),
   },
 
   // --- audio (glasses media-volume, own-app playback hint, live mic level) ---

package/src/facades/glassesSettings.ts

@@ -23,6 +23,7 @@ const INTERNAL_KEYS = new Set<string>([
   SETTINGS.device_name.key,
   SETTINGS.device_address.key,
   SETTINGS.project_name.key,
+  SETTINGS.controllers.key,
   SETTINGS.pending_controller.key,
   SETTINGS.default_controller.key,
   SETTINGS.controller_device_name.key,

package/src/facades/pairing.ts

@@ -13,7 +13,7 @@ import BluetoothSdk from "@glassly/bluetooth-sdk/internal"
 import type {ConnectOptions, Device, DeviceModel, PairFailureEvent, GlassesNotReadyEvent} from "@glassly/bluetooth-sdk"
 import {useCoreStore} from "../stores/core"
 import {useGlassesStore} from "../stores/glasses"
-import {SETTINGS, useSettingsStore} from "../stores/settings"
+import {useSettingsStore} from "../stores/settings"
 import {hasDefaultDevice} from "../services/DeviceStoreHydration"
 import {
   markPendingSelection,
@@ -28,7 +28,7 @@ import {
   type AutomaticReportSubmissionStatus,
 } from "../services/AutomaticReportResult"
 import {pushAllBluetoothSettings} from "../services/GlassesSettingsSync"
-import {ControllerTypes} from "../types"
+import {isControllerModel, isControllerReady} from "../services/controllers"
 import {submitAutomaticReport} from "./reports"
 
 import {BgTimer} from "../utils/timers"
@@ -63,12 +63,15 @@ function projectTargetReady(options: Pick<PairingReadyWaitOptions, "deviceModel"
   const {deviceModel, deviceName} = options
   const glasses = useGlassesStore.getState()
 
-  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)
-    const pairedName = settings.getSetting(SETTINGS.controller_device_name.key)
-    return (!deviceModel || pairedModel === deviceModel) && (!deviceName || pairedName === deviceName)
+  // A controller target is ready once some driver of that model delivers input;
+  // the scan's device name is the R1's ring id or the band's Bluetooth name.
+  if (isControllerModel(deviceModel)) {
+    return Object.values(glasses.controllers ?? {}).some(
+      (status) =>
+        status.model === deviceModel &&
+        isControllerReady(status) &&
+        (!deviceName || status.name === deviceName || status.id === deviceName),
+    )
   }
 
   if (!isGlassesReady(glasses.connection)) return false
@@ -283,17 +286,12 @@ export const pairing = {
    * host renders it as a finish-pairing affordance until pairing succeeds. */
   markPendingSelection: (model: string) => markPendingSelection(model),
 
-  /** Start scanning for nearby glasses. Results land on `searchResults()`/`onFound()`. */
+  /** Start scanning for nearby glasses or controllers of `model`. Results land on `searchResults()`/`onFound()`. */
   scan: (model: DeviceModel): Promise<void> => BluetoothSdk.startScan(model),
   /** Whether a scan is currently in progress. */
   scanning: (): boolean => useCoreStore.getState().searching,
   /** Subscribe to scan-in-progress changes; fires only when it changes. Returns an unsubscribe. */
   onScanning: (cb: (scanning: boolean) => void): (() => void) => useCoreStore.subscribe((s) => s.searching, cb),
-  /** Whether a controller scan is currently in progress. */
-  scanningController: (): boolean => useCoreStore.getState().searchingController,
-  /** Subscribe to controller-scan-in-progress changes; fires only when it changes. Returns an unsubscribe. */
-  onScanningController: (cb: (scanning: boolean) => void): (() => void) =>
-    useCoreStore.subscribe((s) => s.searchingController, cb),
   /** Whether the phone has another Bluetooth (audio) device connected — the BT Classic pairing hint. */
   otherBtConnected: (): boolean => useCoreStore.getState().otherBtConnected,
   /** Subscribe to other-Bluetooth-device-connected changes; fires only when it changes. Returns an unsubscribe. */
@@ -394,6 +392,12 @@ export const pairing = {
     await BluetoothSdk.forget()
   },
 
+  /**
+   * Abandon an in-flight controller pairing (back-out, failure retry). Only the
+   * attempt's driver is dropped; paired controllers and the glasses are untouched.
+   */
+  abandonControllerAttempt: (): Promise<void> => BluetoothSdk.cancelControllerAttempt(),
+
   /** Subscribe to pairing failures; returns an unsubscribe. */
   onPairFailure: (cb: (event: PairFailureEvent) => void): (() => void) => {
     const sub = BluetoothSdk.addListener("pair_failure", cb)

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.3",
-  "releaseIdentity": "0.3.3-dev.670",
-  "releaseSetId": "glassly-0.3.3-dev.670",
-  "sourceCommit": "2a19d64f1d228e74e3e49f4321264e7bfe446b75",
+  "familyBaseVersion": "0.3.4",
+  "releaseIdentity": "0.3.4-dev.675",
+  "releaseSetId": "glassly-0.3.4-dev.675",
+  "sourceCommit": "9f5acf0ba693d861ad1e1a038b8dc565b1fc4d86",
   "otaManifestUrl": null,
   "otaManifestSha256": null
 })

package/src/index.ts

@@ -46,12 +46,22 @@ export type {
 export {SETTINGS, useSetting, AI_DATA_CONSENT_VERSION} from "./stores/settings"
 export {isCfwFirmwareVersion, isCustomDashboardEligible} from "./services/pages/pageEligibility"
 export {getEffectiveCapabilities} from "./services/effectiveCapabilities"
+export {isControllerModel, isControllerReady} from "./services/controllers"
 
 // AI tier registry: the curated per-tier model dropdown options and helpers
 // the Settings > AI Models screen renders. Resolution itself runs inside
 // LocalMiniappRuntime; the screen only reads/writes the ai_model_* settings.
 export {AI_TIERS, TIER_MODEL_OPTIONS, parseTierSetting} from "./services/AiTierResolution"
 export type {AiTier, AiTierProvider, TierModelOption} from "./services/AiTierResolution"
+// On-device LLM: the model catalog and download status the same screen
+// renders for the phone-side model (engine.ai.local).
+export type {
+  LocalLlmDownloadStage,
+  LocalLlmDownloadStatus,
+  LocalLlmModelConfig,
+  LocalLlmModelId,
+} from "./services/LocalLlmModelManager"
+export {DEFAULT_LOCAL_LLM_MODEL, isLocalLlmModelId} from "./services/LocalLlmModelManager"
 
 // Shared user memory timeline (engine.memory / Settings > Memory). Entry and
 // session shapes are canonical in @glassly/miniapp (the session.memory
@@ -157,7 +167,7 @@ export type {
 
 // Bluetooth SDK event types host UI subscribes to via engine facades (the
 // BluetoothSdk singleton passthrough itself is internal).
-export type {PairFailureEvent, GlassesNotReadyEvent} from "@glassly/bluetooth-sdk"
+export type {PairFailureEvent, GlassesNotReadyEvent, PairedController, ControllerStatus} from "@glassly/bluetooth-sdk"
 
 // Cloud connection status enum (read model; the connection store is internal).
 export {WebSocketStatus} from "./stores/connection"
@@ -215,7 +225,11 @@ export {
   type MetaSession,
   type MetaSsoTokens,
 } from "./services/neuralBand/MetaAuth"
-export type {NeuralBandClaimStatus, NeuralBandHandwritingStatus} from "./services/neuralBand/NeuralBandInput"
+export type {
+  NeuralBandClaimStatus,
+  NeuralBandHandwritingStatus,
+  NeuralBandHandwritingUpdate,
+} from "./services/neuralBand/NeuralBandInput"
 
 // Hardware types and capability profiles.
 export {

package/src/services/DeviceEventRouter.ts

@@ -40,6 +40,13 @@ import dashboardOpenTrace from "./debug/DashboardOpenTrace"
 
 let subs: Array<{remove: () => void}> = []
 
+// Array/object echoes (the controller registry) arrive as fresh objects.
+function sameSettingValue(current: unknown, next: unknown): boolean {
+  if (current === next) return true
+  if (typeof current !== "object" || typeof next !== "object" || current === null || next === null) return false
+  return JSON.stringify(current) === JSON.stringify(next)
+}
+
 export function startDeviceEventRouter(): void {
   if (subs.length) return
 
@@ -173,7 +180,7 @@ export function startDeviceEventRouter(): void {
       // Damp the relay: native re-echoes some settings unconditionally (e.g.
       // the identity block at every handleDeviceReady) — a same-value echo
       // must not become a store write (persistence churn + change-push noise).
-      if (settings.getSetting(event.key) !== event.value) {
+      if (!sameSettingValue(settings.getSetting(event.key), event.value)) {
         await settings.setSetting(event.key, event.value)
       }
       // Two-phase identity: a promoted default retires the pending selection

package/src/services/GestureDotsService.ts

@@ -53,14 +53,18 @@ function fingerGlyph(glyph: GestureDotGlyph, finger: number): GestureDotGlyph {
   return finger === 1 ? (MIDDLE_FINGER_GLYPHS[glyph] ?? glyph) : glyph
 }
 
+function fingerKey(controllerId: string | undefined, finger: number): string {
+  return `${controllerId ?? ""}:${finger}`
+}
+
 class GestureDotsService {
   private started = false
   private flash: GestureDotGlyph | null = null
   private flashTimer: number | null = null
-  /** Raw controller holds survive hold recognition/dial events until their own release. */
-  private presses = new Map<number, {raw: boolean; glyph: GestureDotGlyph}>()
+  /** Raw controller holds survive hold recognition/dial events until their own release. Keyed by fingerKey. */
+  private presses = new Map<string, {raw: boolean; glyph: GestureDotGlyph}>()
   /** When each finger last sent a press edge (touch_down, or tap_end after one). */
-  private lastEdgeAt = new Map<number, number>()
+  private lastEdgeAt = new Map<string, number>()
   /** Avoid sending identical images for successive phases of the same press. */
   private renderedGlyph: GestureDotGlyph | null = null
   /** Whether the indicator scene currently has anything on it (needs a clear when the flash ends). */
@@ -120,15 +124,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. `fingerIndex` is the
-   * Neural Band's finger on its pinches and press edges (1 = middle).
+   * Neural Band's finger on its pinches and press edges (1 = middle);
+   * `controllerId` keeps two controllers' fingers apart.
    */
-  noteGesture(gestureName: string, claimed = false, fingerIndex?: number): void {
+  noteGesture(gestureName: string, claimed = false, fingerIndex?: number, controllerId?: string): void {
     if (!this.started || !this.enabled()) return
-    this.applyGesture(gestureName, claimed, fingerIndex)
+    this.applyGesture(gestureName, claimed, fingerIndex, controllerId)
     this.trace("input", {gestureName, claimed})
   }
 
-  private applyGesture(gestureName: string, claimed: boolean, fingerIndex?: number): void {
+  private applyGesture(gestureName: string, claimed: boolean, fingerIndex?: number, controllerId?: string): void {
     if (localDisplayManager.hasActiveDisplay() || useDisplayStore.getState().overlayOwner !== null) {
       this.relinquish()
       return
@@ -139,9 +144,10 @@ class GestureDotsService {
       return
     }
     const finger = fingerIndex ?? 0
-    const press = this.presses.get(finger)
+    const key = fingerKey(controllerId, finger)
+    const press = this.presses.get(key)
     if (gestureName === "touch_down" || gestureName === "tap_start") {
-      if (gestureName === "touch_down") this.lastEdgeAt.set(finger, Date.now())
+      if (gestureName === "touch_down") this.lastEdgeAt.set(key, Date.now())
       if (press) {
         // Both reports describe one press: after touch_down, tap_start means it is held.
         if (gestureName === "touch_down") press.raw = true
@@ -150,14 +156,14 @@ class GestureDotsService {
         return
       }
       this.clearFlash()
-      this.presses.set(finger, {raw: gestureName === "touch_down", glyph: fingerGlyph("dot", finger)})
+      this.presses.set(key, {raw: gestureName === "touch_down", glyph: fingerGlyph("dot", finger)})
       this.render()
       return
     }
     if (gestureName === "tap_end") {
       if (!press) return
-      this.presses.delete(finger)
-      if (press.raw) this.lastEdgeAt.set(finger, Date.now())
+      this.presses.delete(key)
+      if (press.raw) this.lastEdgeAt.set(key, Date.now())
       this.render()
       return
     }
@@ -173,11 +179,11 @@ class GestureDotsService {
       this.render()
       return
     }
-    const lastEdgeAt = this.lastEdgeAt.get(finger)
+    const lastEdgeAt = this.lastEdgeAt.get(key)
     if (!press && shownByPress && lastEdgeAt !== undefined && Date.now() - lastEdgeAt < EDGE_REPORT_GRACE_MS) return
     // Completed taps/swipes become one continuous pulse, even if the device
     // omits tap_end. Older tap_start-only devices retain the same fallback.
-    this.presses.delete(finger)
+    this.presses.delete(key)
     if (glyph) this.startFlash(glyph)
     this.render()
   }

package/src/services/GlassesTouchInput.ts

@@ -28,16 +28,18 @@ const miniappExitGesture = new MiniappExitGesture({
 // Raw ring reports include every scroll step, whether the CFW forwards them
 // (deviceModel G2) or the ring sends them to the phone itself (deviceModel R1);
 // both tag source 2. Rate-limit scroll actions separately from press/release
-// recognition, using native receipt timestamps so a JS backlog does not
-// collapse otherwise separate gestures.
+// recognition, per ring, using native receipt timestamps so a JS backlog does
+// not collapse otherwise separate gestures.
 const RING_SCROLL_INTERVAL_MS = 100
-let lastRingScrollAt: number | null = null
+const lastRingScrollAt = new Map<string, number>()
 
 function shouldForwardScroll(event: TouchEvent): boolean {
   if (event.source !== 2 || (event.gestureName !== "swipe_up" && event.gestureName !== "swipe_down")) return true
-  const elapsed = lastRingScrollAt === null ? null : event.timestamp - lastRingScrollAt
+  const ring = event.controllerId ?? `source:${event.source}`
+  const last = lastRingScrollAt.get(ring)
+  const elapsed = last === undefined ? null : event.timestamp - last
   if (elapsed !== null && elapsed >= 0 && elapsed < RING_SCROLL_INTERVAL_MS) return false
-  lastRingScrollAt = event.timestamp
+  lastRingScrollAt.set(ring, event.timestamp)
   return true
 }
 
@@ -72,7 +74,7 @@ export function dispatchTouchEvent(event: TouchEvent): void {
       !localMiniappRuntime.hasGestureClaim(visible, gesture) &&
       miniappExitGesture.tryExitVisibleMiniapp()
     ) {
-      gestureDotsService.noteGesture(gesture, true)
+      gestureDotsService.noteGesture(gesture, true, event.index, event.controllerId)
       return
     }
   }
@@ -83,7 +85,7 @@ export function dispatchTouchEvent(event: TouchEvent): void {
       dashboardOpenTrace.trigger(osHeadUp ? "head-up" : "double-tap", event.timestamp)
     }
     // The press may have started before this app claimed its release edge.
-    gestureDotsService.noteGesture(gesture, true, event.index)
+    gestureDotsService.noteGesture(gesture, true, event.index, event.controllerId)
     if (!shouldForwardScroll(event)) return
     localMiniappRuntime.forwardEvent("touch_event", event, undefined, claimant)
     return
@@ -92,7 +94,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, false, event.index)
+  gestureDotsService.noteGesture(gesture, false, event.index, event.controllerId)
 
   if (!shouldForwardScroll(event)) return
   localMiniappRuntime.forwardEvent("touch_event", event)
@@ -116,7 +118,7 @@ export function dispatchTouchEvent(event: TouchEvent): void {
 
 export function resetTouchInput(): void {
   miniappExitGesture.reset()
-  lastRingScrollAt = null
+  lastRingScrollAt.clear()
 }
 
 /** Phone mirror input uses the same dashboard/miniapp policy as real glasses. */

package/src/services/LlmRouting.ts

@@ -0,0 +1,49 @@
+/**
+ * LlmRouting — pure decision logic for where one session.ai.complete call
+ * runs: the PRIMARY path (vendor-direct on a user key, or the cloud relay) or
+ * the on-device model. Same shape as TranscriptionRouting.ts so the rules are
+ * unit-testable; LocalMiniappRuntime supplies the inputs and does the work.
+ */
+
+export interface LlmRouteInputs {
+  /** Request asked for on-device only (`forceLocal: true`). */
+  forceLocal: boolean
+  /** Request accepts on-device when the primary is down (`localFallback: true`). */
+  localFallback: boolean
+  /**
+   * Whether the primary path is currently believed usable: a saved user key
+   * for the resolved provider, or cloud connected + not disabled in Privacy
+   * + monthly AI credit not exhausted.
+   */
+  primaryUp: boolean
+}
+
+/**
+ * - "local": run on-device, never touch the primary.
+ * - "primary": primary only; failures surface as today.
+ * - "primary_then_local": try the primary, and on any failure serve the same
+ *   request on-device.
+ */
+export type LlmRoute = "local" | "primary" | "primary_then_local"
+
+export function decideLlmRoute({forceLocal, localFallback, primaryUp}: LlmRouteInputs): LlmRoute {
+  if (forceLocal) return "local"
+  if (!localFallback) return "primary"
+  return primaryUp ? "primary_then_local" : "local"
+}
+
+/** Why a request landed on-device; reported in logs and the result's `model` line. */
+export type LocalLlmReason = "force_local" | "cloud_disconnected" | "cloud_disabled" | "llm_quota" | "primary_failed"
+
+export function localLlmReason(inputs: {
+  forceLocal: boolean
+  cloudDisabled: boolean
+  cloudConnected: boolean
+  quotaBlocked: boolean
+}): LocalLlmReason {
+  if (inputs.forceLocal) return "force_local"
+  if (inputs.cloudDisabled) return "cloud_disabled"
+  if (inputs.quotaBlocked) return "llm_quota"
+  if (!inputs.cloudConnected) return "cloud_disconnected"
+  return "primary_failed"
+}