@glassly/engine 0.1.0-dev.99 → 0.2.8-dev.445

package/src/services/HeadingService.ts

@@ -22,8 +22,6 @@ class HeadingService {
   private nativeSub: {remove: () => void} | null = null
   private lastDegrees: number | null = null
   private nativeStarted = false
-  /** While true, an external source (glasses magnetometer) owns the stream and phone-compass ticks are dropped. */
-  private externalSourceActive = false
 
   private constructor() {}
 
@@ -34,27 +32,6 @@ class HeadingService {
     return HeadingService.instance
   }
 
-  /** While active, phone compass updates are suppressed in favor of pushExternalHeading(). */
-  public setExternalSourceActive(active: boolean): void {
-    if (this.externalSourceActive === active) return
-    this.externalSourceActive = active
-    console.log(`${LOG_TAG}: external heading source ${active ? "active" : "inactive"}`)
-  }
-
-  /** Fan an external heading (degrees 0…359) out to listeners; no-op unless the external source is active. */
-  public pushExternalHeading(degrees: number): void {
-    if (!this.externalSourceActive) return
-    if (!Number.isFinite(degrees)) return
-    this.lastDegrees = degrees
-    this.listeners.forEach((l) => {
-      try {
-        l(degrees)
-      } catch (err) {
-        console.error(`${LOG_TAG}: listener threw`, err)
-      }
-    })
-  }
-
   public addListener(listener: HeadingListener): () => void {
     this.listeners.add(listener)
     if (!this.nativeStarted) {
@@ -79,7 +56,6 @@ class HeadingService {
     if (this.nativeStarted) return
     this.nativeStarted = true
     this.nativeSub = CrustModule.addListener("onHeading", (data) => {
-      if (this.externalSourceActive) return
       const deg = Number(data.degrees)
       if (!Number.isFinite(deg)) return
       this.lastDegrees = deg

package/src/services/HotspotShutdown.ts

@@ -1,3 +1,5 @@
+import {BgTimer} from "../utils/timers"
+
 type HotspotState = {state: "disabled" | "enabled"}
 
 type HotspotShutdownOptions = {
@@ -7,7 +9,7 @@ type HotspotShutdownOptions = {
   sleep?: (delayMs: number) => Promise<void>
 }
 
-const sleep = (delayMs: number) => new Promise<void>((resolve) => setTimeout(resolve, delayMs))
+const sleep = (delayMs: number) => new Promise<void>((resolve) => BgTimer.setTimeout(resolve, delayMs))
 
 /**
  * Disable a glasses hotspot with a bounded retry. ASG APK replacement keeps the

package/src/services/JSCrashloopReportService.ts

@@ -25,7 +25,7 @@ export async function submitJSCrashloopReport(params: {
     trigger: {
       type: "automatic",
       source: "miniapp_crashloop",
-      reason: "glasslyjs_crashloop_disabled",
+      reason: "js_crashloop_disabled",
       sourceAppletPackageName: packageName,
       sourceAppletName: appName,
     },
@@ -34,7 +34,7 @@ export async function submitJSCrashloopReport(params: {
       actualBehavior: JSON.stringify({reason, lastLogLines}, null, 2),
       systemPriority: "critical",
     },
-    throttleKey: `glasslyjs_crashloop:${packageName}`,
+    throttleKey: `js_crashloop:${packageName}`,
   })
 
   const status = toAutomaticReportSubmissionStatus(result)

package/src/services/JSRouter.ts

@@ -4,14 +4,14 @@
  * {@link LocalMiniappRuntime} handler set.
  *
  * Rather than re-implement the 33 dispatch arms inline, the router
- * consumes Crust's `glasslyjs_message` Expo event and forwards its
+ * consumes Crust's `js_message` Expo event and forwards its
  * `__bridge.send(raw)` payloads to {@link LocalMiniappRuntime.handleRawMessage}.
  * The SDK envelope shape (`{type: "DISPLAY", ...}` etc.) is unchanged from
  * the WebView path, so every existing handler runs verbatim. What changes
  * is the *transport*:
  *
  *   - **Inbound** (background JS → host): `__dispatch("__bridge", "send",
- *     [rawJsonString])` → `glasslyjs_message` event → router →
+ *     [rawJsonString])` → `js_message` event → router →
  *     `LocalMiniappRuntime.handleRawMessage(packageName, raw)`.
  *   - **Outbound** (host → background JS): every package registered with
  *     the router gets a `sendMessage(raw)` fn that calls
@@ -38,6 +38,8 @@ import type {EventSubscription} from "expo-modules-core"
 
 import devServerBridge from "./DevServerBridge"
 import type localMiniappRuntime from "./LocalMiniappRuntime"
+import type {MiniappLaunchSource} from "@glassly/miniapp"
+
 import type {InstalledMiniappManifest} from "./LocalMiniappRuntime"
 import type {JSCrashController} from "./JSCrashController"
 import {JSLogRingBuffer, JSLogThrottle, redactSecrets} from "./JSLogPipeline"
@@ -45,6 +47,8 @@ import {islandNotifications} from "./NotificationsEmitter"
 import type {UIRouter} from "./UIRouter"
 import {miniappRunningRegistry} from "./MiniappRunningRegistry"
 
+import {BgTimer} from "../utils/timers"
+
 /** The runtime's runtime instance type — the singleton exported from
  * LocalMiniappRuntime.ts (the file's `export default` is the instance,
  * not the class).
@@ -96,6 +100,7 @@ interface SpawnCache {
   miniappJs: string
   permissions: string[]
   installedManifest?: InstalledMiniappManifest
+  launchSource?: MiniappLaunchSource
 }
 
 export class JSRouter {
@@ -104,7 +109,7 @@ export class JSRouter {
   /** Cached spawn arguments so the crash controller can respawn after a backoff. */
   private readonly spawnCache: Map<string, SpawnCache> = new Map()
   /** Active respawn timers (so unregister() can cancel a pending respawn). */
-  private readonly respawnTimers: Map<string, ReturnType<typeof setTimeout>> = new Map()
+  private readonly respawnTimers: Map<string, number> = new Map()
 
   /**
    * Optional crash controller. When wired, every `__error` frame from a
@@ -148,12 +153,12 @@ export class JSRouter {
   ) {}
 
   /**
-   * Subscribe to Crust's `glasslyjs_message` event. Idempotent — calling
+   * Subscribe to Crust's `js_message` event. Idempotent — calling
    * start() twice attaches a single listener.
    */
   start(): void {
     if (this.subscription) return
-    this.subscription = this.crust.addListener("glasslyjs_message", (raw) => {
+    this.subscription = this.crust.addListener("js_message", (raw) => {
       try {
         this.handleOutbound(raw as unknown as OutboundMessagePayload)
       } catch (e) {
@@ -192,13 +197,18 @@ export class JSRouter {
    * (e.g. {@link spawnAndRegister} below, or the host's miniapp launch
    * pipeline) should call this once per spawn.
    */
-  registerApp(packageName: string, installedManifest?: InstalledMiniappManifest): void {
+  registerApp(
+    packageName: string,
+    installedManifest?: InstalledMiniappManifest,
+    launchSource?: MiniappLaunchSource,
+  ): void {
     this.runtime.registerApp(
       packageName,
       (raw: string) => {
         this.dispatchBridgeRaw(packageName, raw)
       },
       installedManifest,
+      launchSource,
     )
     this.registered.add(packageName)
     // JSContext is the source-of-truth for "miniapp running". The
@@ -218,7 +228,11 @@ export class JSRouter {
   async spawnAndRegister(
     packageName: string,
     miniappJs: string,
-    options?: {permissions?: string[]; installedManifest?: InstalledMiniappManifest},
+    options?: {
+      permissions?: string[]
+      installedManifest?: InstalledMiniappManifest
+      launchSource?: MiniappLaunchSource
+    },
   ): Promise<boolean> {
     if (!this.crust.jsSpawn) {
       this.logger.warn("jsSpawn not available — host binding missing native function")
@@ -243,7 +257,7 @@ export class JSRouter {
     if (options?.permissions && options.permissions.length > 0) {
       await this.crust.jsSetManifest(packageName, options.permissions)
     }
-    this.registerApp(packageName, options?.installedManifest)
+    this.registerApp(packageName, options?.installedManifest, options?.launchSource)
     // Cache spawn arguments so the crash controller can respawn the
     // same code after a backoff. permissions + manifest are cached too
     // because the native side resets setManifest on every spawn and
@@ -253,6 +267,7 @@ export class JSRouter {
       miniappJs,
       permissions: options?.permissions ?? [],
       installedManifest: options?.installedManifest,
+      launchSource: options?.launchSource,
     })
     this.crashController?.onSpawn(packageName)
 
@@ -299,8 +314,8 @@ export class JSRouter {
     if (outcome.scheduleRespawnAfterMs == null) return
     // Cancel any prior pending respawn before scheduling a new one.
     const existing = this.respawnTimers.get(packageName)
-    if (existing) clearTimeout(existing)
-    const timer = setTimeout(() => {
+    if (existing) BgTimer.clearTimeout(existing)
+    const timer = BgTimer.setTimeout(() => {
       this.respawnTimers.delete(packageName)
       void (async () => {
         try {
@@ -316,7 +331,7 @@ export class JSRouter {
         if (cached.permissions.length > 0) {
           await this.crust.jsSetManifest(packageName, cached.permissions)
         }
-        this.registerApp(packageName, cached.installedManifest)
+        this.registerApp(packageName, cached.installedManifest, cached.launchSource)
         controller.onSpawn(packageName)
         // Re-fire the init envelope so the respawned context's
         // `registerMiniapp` handler runs again.
@@ -346,7 +361,7 @@ export class JSRouter {
     // want a stale timer to re-spawn a miniapp the user just disabled.
     const pending = this.respawnTimers.get(packageName)
     if (pending) {
-      clearTimeout(pending)
+      BgTimer.clearTimeout(pending)
       this.respawnTimers.delete(packageName)
     }
     this.spawnCache.delete(packageName)
@@ -389,7 +404,7 @@ export class JSRouter {
   private handleOutbound(msg: OutboundMessagePayload): void {
     const {packageName, iface, method} = msg
     if (!packageName || !iface || !method) {
-      this.logger.warn(`bad glasslyjs_message — missing fields`, msg)
+      this.logger.warn(`bad js_message — missing fields`, msg)
       return
     }
 
@@ -453,7 +468,7 @@ export class JSRouter {
       this.logRing.push(packageName, line)
       // Forward to the `glassly-miniapp dev` sidecar (if one is connected
       // for this package). Source="background" so the CLI tags lines as
-      // [GlasslyJS]. The bridge silently drops when no dev server is up,
+      // [JSRuntime]. The bridge silently drops when no dev server is up,
       // which makes this safe to call unconditionally in prod.
       const argsForBridge = Array.isArray(safeArgs) ? (safeArgs as unknown[]) : [safeArgs]
       devServerBridge.forwardLog(packageName, method, argsForBridge, Date.now(), "background")

package/src/services/LocalDisplayManager.ts

@@ -11,7 +11,7 @@
  *
  * Scope is deliberately local-only. Cloud-originated displays are untouched
  * and may race with local displays during dev; that's acceptable per plan
- * (agents/local-display-manager-plan.md).
+ * (notes/archive/agents/local-display-manager-plan.md).
  *
  * Display pacing is NOT done here. A JS-side ~300ms throttle used to live in
  * this class, but JS timers (and therefore the throttle's trailing flush) do
@@ -29,7 +29,8 @@
 import BluetoothSdk from "@glassly/bluetooth-sdk/internal"
 import displayProcessor from "./DisplayProcessor"
 import {useDisplayStore} from "../stores/display"
-import sceneRenderer from "./SceneRenderer"
+import sceneRenderer, {type SceneEmitResult} from "./SceneRenderer"
+import dashboardOpenTrace from "./debug/DashboardOpenTrace"
 import {isGlassesConnected} from "./GlassesReadiness"
 import {useGlassesStore} from "../stores/glasses"
 import type {SceneElementInput} from "../utils/display/scene"
@@ -53,6 +54,10 @@ export interface DisplayRequestResult {
   status: "displayed" | "blocked"
   degraded?: boolean
   dropped?: string[]
+  /** Scene frames: the glasses had the frame (and finished its transitions) before this resolved. */
+  presented?: boolean
+  /** A newer frame from the same app settled this one. */
+  superseded?: boolean
   reason?: string
 }
 
@@ -99,6 +104,10 @@ const SYSTEM_BOOT_PKG = "system.boot"
 // Sentinel package for transient OS notices (quota exhausted, etc.).
 const SYSTEM_NOTICE_PKG = "system.notice"
 const SYSTEM_NOTICE_DURATION_MS = 6_000
+// A scene frame native never reports on (page rebuilding, link stalled)
+// resolves presented:false after this — long enough for a full-frame BLE
+// image transfer with retries, short enough that an awaiting app isn't stuck.
+const PRESENTATION_TIMEOUT_MS = 3_000
 
 /** "Render nothing" — an empty scene or an explicit clear_view layout. */
 function isClearPayload(payload: DisplayPayload): boolean {
@@ -153,8 +162,8 @@ class LocalDisplayManager {
   private bootingApp: BootingApp | null = null
   private bootQueue: Map<string, {payload: DisplayPayload; resolve?: DisplayRequestResolver}> = new Map()
 
-  /** While true the dashboard owns the glasses: main frames are retained but not sent. */
-  private dashboardActive = false
+  /** The page holding the overlay slot; while set, main frames are retained but not sent. */
+  private overlayOwner: string | null = null
 
   /** Miniapp whose visible frame is temporarily covered by an OS exit notice. */
   private exitingApp: {packageName: string; coveredDisplay: ActiveDisplay} | null = null
@@ -268,7 +277,7 @@ class LocalDisplayManager {
 
   /**
    * The package that currently owns the glasses screen, for gesture-claim
-   * arbitration (see LocalMiniappRuntime.foregroundClaimsGesture). This is
+   * arbitration (the double-tap exit rule in GlassesTouchInput). This is
    * glasses ownership, not the phone's Compositor foreground: a background
    * miniapp rendering to the glasses with the phone pocketed is the owner.
    *
@@ -293,6 +302,8 @@ class LocalDisplayManager {
    * and therefore must not be closed by the system double-tap gesture.
    */
   public getVisibleMiniappPackageName(): string | null {
+    // Main content is retained while an overlay covers it, but is not visible.
+    if (this.overlayOwner !== null) return null
     const current = this.currentDisplay?.packageName ?? null
     if (!current || current === SYSTEM_BOOT_PKG || current === SYSTEM_NOTICE_PKG) return null
     return current
@@ -348,6 +359,12 @@ class LocalDisplayManager {
     }
   }
 
+  /** The foreground (core) miniapp is drawing on the glasses right now. */
+  public foregroundAppOnScreen(): boolean {
+    const current = this.currentDisplay
+    return current !== null && this.coreApp !== null && current.packageName === this.coreApp
+  }
+
   /** Report-safe ownership snapshot for incident diagnostics. */
   public getDiagnosticSnapshot(): Record<string, unknown> {
     return {
@@ -430,12 +447,27 @@ class LocalDisplayManager {
    * Dashboard cover state. On deactivate the retained main frame repaints
    * (scenes replay create-based; legacy re-sends), or the glasses clear.
    */
-  public setDashboardActive(active: boolean): void {
-    if (this.dashboardActive === active) return
-    this.dashboardActive = active
-    useDisplayStore.getState().setDashboardActive(active)
-    if (active) return
-    sceneRenderer.markViewStale("dashboard")
+  /** The page holding the overlay slot, or null while the main content shows. */
+  public getOverlayOwner(): string | null {
+    return this.overlayOwner
+  }
+
+  /**
+   * Hand the overlay slot to `owner` (a page's scene app id) or release it.
+   * A new owner replaces the previous page: its retained scene is dropped so
+   * the first frame paints from empty. Releasing replays the retained main
+   * content, or clears when it has expired.
+   */
+  public setOverlayOwner(owner: string | null): void {
+    const previous = this.overlayOwner
+    if (previous === owner) return
+    this.overlayOwner = owner
+    useDisplayStore.getState().setOverlayOwner(owner)
+    if (previous !== null) {
+      sceneRenderer.markViewStale("dashboard")
+      sceneRenderer.clearApp(previous)
+    }
+    if (owner !== null) return
     const current = this.currentDisplay
     if (current && (current.expiresAt === null || this.now() < current.expiresAt)) {
       this.replayCurrent()
@@ -444,14 +476,37 @@ class LocalDisplayManager {
     }
   }
 
-  /** Dashboard renderers only; bypasses arbitration and main ownership state. */
-  public renderDashboard(packageName: string, payload: DisplayPayload): void {
-    if (!this.dashboardActive) return
+  /**
+   * The overlay slot only; bypasses arbitration and main ownership state.
+   * Frames from an owner other than the slot's are dropped. Returns the scene
+   * frame's seq (0 when nothing went to the glasses). With `resolve` (an
+   * awaited render from the designated miniapp) the outcome settles the way
+   * a main frame's does: `presented` once the glasses have the frame, or
+   * false at once when the slot is not this owner's.
+   */
+  public renderOverlay(packageName: string, payload: DisplayPayload, resolve?: DisplayRequestResolver): number {
+    if (this.overlayOwner !== packageName) {
+      resolve?.({status: "displayed", presented: false, reason: "dashboard view not showing"})
+      return 0
+    }
     if (payload.scene) {
-      sceneRenderer.emitScene(packageName, "dashboard", payload.scene)
-      return
+      const result = sceneRenderer.emitScene(packageName, "dashboard", payload.scene)
+      if (result.kind === "no-display") {
+        resolve?.({status: "blocked", reason: "no display connected"})
+        return 0
+      }
+      if (result.kind === "legacy") {
+        resolve?.({status: "displayed", degraded: result.degraded, dropped: result.dropped})
+        return 0
+      }
+      if (resolve) this.settleScene(packageName, result, resolve)
+      if (result.sent) dashboardOpenTrace.frameSent(result.seq)
+      return result.sent ? result.seq : 0
+    }
+    if (!payload.layout) {
+      resolve?.({status: "displayed", presented: false, reason: "empty frame"})
+      return 0
     }
-    if (!payload.layout) return
     const rawEvent = {view: "dashboard", layout: payload.layout}
     let processedEvent: Record<string, unknown>
     try {
@@ -461,6 +516,8 @@ class LocalDisplayManager {
       processedEvent = rawEvent
     }
     this.pushToNative(processedEvent)
+    resolve?.({status: "displayed"})
+    return 0
   }
 
   // ===========================================================================
@@ -484,11 +541,10 @@ class LocalDisplayManager {
       return
     }
 
-    // Dashboard view: only visible while the dashboard covers the glasses.
-    // Local miniapp dashboard content remains a stub.
+    // The overlay slot: only its owner (the designated dashboard miniapp,
+    // under its package name) draws there; anyone else's frame is dropped.
     if (payload.view === "dashboard") {
-      this.renderDashboard(packageName, payload)
-      resolve?.({status: "displayed"})
+      this.renderOverlay(packageName, payload, resolve)
       return
     }
 
@@ -717,7 +773,37 @@ class LocalDisplayManager {
         this.handleExpiry(packageName)
       }, delay)
     }
-    resolve?.({status: "displayed", degraded: result.degraded, dropped: result.dropped})
+    if (!resolve) return
+    this.settleScene(packageName, result, resolve)
+  }
+
+  /**
+   * Settle an awaited render() once the glasses have the frame and its
+   * transitions have played out. A frame that stayed phone-side (the other
+   * view is showing) settles at once with `presented: false`. The timeout
+   * keeps a frame the device never reports on from hanging the app.
+   */
+  private settleScene(
+    packageName: string,
+    result: Extract<SceneEmitResult, {kind: "scene"}>,
+    resolve: DisplayRequestResolver,
+  ): void {
+    const base = {status: "displayed" as const, degraded: result.degraded, dropped: result.dropped}
+    if (!result.sent) {
+      resolve({...base, presented: false, reason: "dashboard active"})
+      return
+    }
+    void sceneRenderer.whenPresented(result.seq, PRESENTATION_TIMEOUT_MS, packageName).then((p) => {
+      const finish = () =>
+        resolve({
+          ...base,
+          presented: p.presented,
+          ...(p.superseded ? {superseded: true} : {}),
+          ...(p.reason !== undefined ? {reason: p.reason} : {}),
+        })
+      if (p.presented && result.settleMs > 0) BgTimer.setTimeout(finish, result.settleMs)
+      else finish()
+    })
   }
 
   private sendToNative(packageName: string, rawEvent: Record<string, unknown>, expiresAt: number | null): void {
@@ -729,9 +815,9 @@ class LocalDisplayManager {
       processedEvent = rawEvent
     }
 
-    // While the dashboard covers the glasses, main frames only update the
-    // retained state; setDashboardActive(false) replays the latest.
-    if (!this.dashboardActive) this.pushToNative(processedEvent)
+    // While a page holds the overlay slot, main frames only update the
+    // retained state; setOverlayOwner(null) replays the latest.
+    if (this.overlayOwner === null) this.pushToNative(processedEvent)
 
     this.currentDisplay = {packageName, processedEvent, expiresAt}
 
@@ -964,7 +1050,7 @@ class LocalDisplayManager {
     this.currentDisplay = null
     this.backgroundLock = null
     this.exitingApp = null
-    this.dashboardActive = false
+    this.overlayOwner = null
     this.bootQueue.clear()
     this.now = () => Date.now()
     this.unsubscribeGlassesStatus?.()

package/src/services/LocalMiniappDataMigration.ts

@@ -12,7 +12,7 @@
  *   - SimpleStorage  `localstorage_{userId}_{pkg}_{key}`
  *   - blob metadata  `blobmeta_{userId}_{pkg}_{key}`
  *   - memory store   `memory_{userId}_{log|summaries}`
- * Blob *file* bytes live under a `{documents}/glassly_blobs/{userId}/` dir and
+ * Blob *file* bytes live under a `{documents}/blobs/{userId}/` dir and
  * are moved by the caller (see migrateLocalBlobFiles) — this module stays
  * dependency-free so it can be unit-tested without a filesystem.
  *