@glassly/engine 0.1.0-dev.99 → 0.2.9-beta.448

package/src/services/notifications/notificationPolicy.ts

@@ -0,0 +1,87 @@
+/**
+ * Notification policy, pure: what the glasses should do with phone
+ * notifications, from settings and the current state of the phone and the
+ * glasses. Two questions live here. `glassesNotificationConfig` is the
+ * behaviour pushed to firmware that presents notifications itself.
+ * `presentationOwner` names the one thing that may draw a notification for
+ * the wearer; every other consumer stays quiet. The adapters
+ * (PhoneNotificationsSync, the host) snapshot inputs and act on the answers.
+ */
+import type {GlassesNotificationConfig} from "@glassly/bluetooth-sdk"
+
+export interface NotificationApp {
+  appId: string
+  displayName: string
+}
+
+export interface NotificationConfigInput {
+  enabled: boolean
+  popups: boolean
+  popupSeconds: number
+  holdDuringApps: boolean
+  /** Hold popups while the wearer can see the phone. */
+  ignoreWhileActive: boolean
+  phoneActive: boolean
+  blockedApps: string[]
+  /** Catalog ∪ apps the glasses reported, for allowlist firmware. */
+  knownApps: NotificationApp[]
+}
+
+/**
+ * Popups fold the ignore-while-active gate in: firmware that pops
+ * notifications up by itself has no other way to hold them while the wearer
+ * is on the phone. The engine's viewer applies the same gate from its env.
+ */
+export function effectivePopups(popups: boolean, ignoreWhileActive: boolean, phoneActive: boolean): boolean {
+  if (!popups) return false
+  if (!ignoreWhileActive) return true
+  return !phoneActive
+}
+
+export function glassesNotificationConfig(input: NotificationConfigInput): GlassesNotificationConfig {
+  const blocked = new Set(input.blockedApps)
+  const seconds = Number(input.popupSeconds)
+  // Known apps travel even while nothing is blocked so a first block enables
+  // the allowlist against the wearer's current list, not an empty one.
+  const allowedApps = input.knownApps
+    .filter((app) => app.appId && !blocked.has(app.appId))
+    .map((app) => ({id: app.appId, name: app.displayName || app.appId}))
+  return {
+    enabled: input.enabled,
+    popups: effectivePopups(input.popups, input.ignoreWhileActive, input.phoneActive),
+    popupSeconds: Number.isFinite(seconds) && seconds > 0 ? Math.round(seconds) : 0,
+    holdDuringApps: input.holdDuringApps,
+    blockedApps: [...blocked],
+    allowedApps,
+  }
+}
+
+/**
+ * Who draws a phone notification for the wearer.
+ *  viewer   — the notifications viewer on connected Glassly CFW glasses, while it runs
+ *  firmware — the glasses' own notification centre (hasNativeNotifications)
+ *  host     — the host app's card and speech, while its presentation surface runs
+ *  none     — nobody: notifications are off, or nothing is there to show them
+ * Miniapp forwarding is not presentation and is never gated by this.
+ */
+export type PresentationOwner = "viewer" | "firmware" | "host" | "none"
+
+export interface PresentationInput {
+  enabled: boolean
+  /** Pages may show on the connected glasses. */
+  pagesEligible: boolean
+  /** The viewer's app is running, so a page can actually show. */
+  viewerRunning: boolean
+  /** The connected model presents notifications in firmware. */
+  nativeNotifications: boolean
+  /** The Notifications miniapp is running, enabling the host fallback. */
+  hostActive: boolean
+}
+
+export function presentationOwner(input: PresentationInput): PresentationOwner {
+  if (!input.enabled) return "none"
+  if (input.pagesEligible && input.viewerRunning) return "viewer"
+  if (input.nativeNotifications) return "firmware"
+  if (input.hostActive) return "host"
+  return "none"
+}

package/src/services/pages/OverlayPages.ts

@@ -0,0 +1,86 @@
+/**
+ * The overlay apps' pages (ADR-0006): one Page per app that has taken the
+ * slot, the only Page implementation the page host shows. The engine keeps
+ * the slot and the eligibility watch; a page only relays: holding the slot
+ * is reported to its app as a view change, and the app's frames reach the
+ * slot through `renderOverlay` under its package name. Whichever app asked
+ * last holds the slot; the previous one hears it was replaced. The runtime
+ * supplies the sink that delivers to apps, so this module never imports it.
+ */
+import pageHost, {type Page, type PageHiddenReason} from "./PageHost"
+import {isOverlayApp} from "./overlayApps"
+import {pagesEligible} from "./pageEligibility"
+
+export type DashboardViewChangeReason = "shown" | "hidden" | "replaced" | "ineligible"
+
+export interface OverlayPagesSink {
+  /** Deliver a display_view event to the app. */
+  send(packageName: string, event: Record<string, unknown>): void
+}
+
+class OverlayPages {
+  private sink: OverlayPagesSink | null = null
+  private pages = new Map<string, Page>()
+  /** Set while an app's page is torn down with the app; it hears nothing then. */
+  private silent = new Set<string>()
+
+  setSink(sink: OverlayPagesSink | null): void {
+    this.sink = sink
+  }
+
+  /** The app whose page holds the slot, or null. */
+  get showingPackage(): string | null {
+    const showing = pageHost.showing
+    if (!showing) return null
+    for (const [packageName, page] of this.pages) if (page === showing) return packageName
+    return null
+  }
+
+  /** Give the app the slot (a no-op when it already shows or pages are not eligible). */
+  show(packageName: string): boolean {
+    if (!isOverlayApp(packageName) || !pagesEligible()) return false
+    const page = this.pageFor(packageName)
+    pageHost.show(page)
+    return pageHost.showing === page
+  }
+
+  /** Release the slot if the app holds it. */
+  hide(packageName: string): void {
+    const page = this.pages.get(packageName)
+    if (page) pageHost.hide(page)
+  }
+
+  /** The app stopped: release the slot without telling it, and forget its page. */
+  remove(packageName: string): void {
+    const page = this.pages.get(packageName)
+    if (!page) return
+    this.silent.add(packageName)
+    try {
+      pageHost.hide(page)
+    } finally {
+      this.silent.delete(packageName)
+    }
+    this.pages.delete(packageName)
+  }
+
+  private pageFor(packageName: string): Page {
+    let page = this.pages.get(packageName)
+    if (page) return page
+    page = {
+      id: packageName,
+      onShown: () => this.emit(packageName, {kind: "change", view: "dashboard", reason: "shown"}),
+      onHidden: (reason: PageHiddenReason) => this.emit(packageName, {kind: "change", view: "main", reason}),
+    }
+    this.pages.set(packageName, page)
+    return page
+  }
+
+  private emit(packageName: string, event: Record<string, unknown>): void {
+    if (this.silent.has(packageName) || !isOverlayApp(packageName)) return
+    this.sink?.send(packageName, event)
+  }
+}
+
+const overlayPages = new OverlayPages()
+export default overlayPages
+export {OverlayPages}

package/src/services/pages/PageHost.ts

@@ -0,0 +1,116 @@
+/**
+ * The page host owns the overlay slot: the single native view above the main
+ * content. At most one page shows at a time; showing a page replaces whatever
+ * was showing, hiding releases the slot and the main content replays. Which
+ * app gets the wearer's gestures is the gesture claims' business, not the
+ * host's. Show and hide run through one queue so a page
+ * that hides itself from inside its own transition is hidden afterwards, never
+ * re-entered. Eligibility (Glassly CFW, dashboard enabled) is checked before a
+ * show and watched while a page is up.
+ */
+import {useGlassesStore} from "../../stores/glasses"
+import {SETTINGS, useSettingsStore} from "../../stores/settings"
+import localDisplayManager from "../LocalDisplayManager"
+import {pagesEligible} from "./pageEligibility"
+
+export type PageHiddenReason = "hidden" | "replaced" | "ineligible"
+
+export interface Page {
+  /** Scene app id; the overlay owner while the page shows. */
+  readonly id: string
+  /** The page holds the slot: draw the first frame. */
+  onShown(): void
+  /** The slot was released, taken by another page, or lost with eligibility. */
+  onHidden(reason: PageHiddenReason): void
+}
+
+class PageHost {
+  private showingPage: Page | null = null
+  private ops: Array<() => void> = []
+  private draining = false
+  private listeners = new Set<(page: Page | null) => void>()
+  private unsubs: Array<() => void> = []
+  private started = false
+
+  start(): void {
+    if (this.started) return
+    this.started = true
+    const check = () => {
+      if (this.showingPage && !pagesEligible()) this.release("ineligible")
+    }
+    this.unsubs.push(
+      useGlassesStore.subscribe(
+        (state) => `${state.connection.state}:${state.deviceModel}:${state.firmwareVersion}`,
+        check,
+      ),
+      useSettingsStore.subscribe((state) => state.getSetting(SETTINGS.custom_dashboard_enabled.key), check),
+    )
+  }
+
+  stop(): void {
+    for (const unsub of this.unsubs) unsub()
+    this.unsubs = []
+    this.release("hidden")
+    this.started = false
+  }
+
+  get showing(): Page | null {
+    return this.showingPage
+  }
+
+  /** Give `page` the slot; no-op when it already shows or pages are not eligible. */
+  show(page: Page): void {
+    this.enqueue(() => {
+      if (this.showingPage === page || !pagesEligible()) return
+      const previous = this.showingPage
+      this.showingPage = page
+      localDisplayManager.setOverlayOwner(page.id)
+      previous?.onHidden("replaced")
+      page.onShown()
+      this.emit()
+    })
+  }
+
+  /** Release the slot if `page` holds it. */
+  hide(page: Page): void {
+    this.enqueue(() => {
+      if (this.showingPage !== page) return
+      this.release("hidden")
+    })
+  }
+
+  onChange(listener: (page: Page | null) => void): () => void {
+    this.listeners.add(listener)
+    return () => {
+      this.listeners.delete(listener)
+    }
+  }
+
+  private release(reason: PageHiddenReason): void {
+    const page = this.showingPage
+    if (!page) return
+    this.showingPage = null
+    localDisplayManager.setOverlayOwner(null)
+    page.onHidden(reason)
+    this.emit()
+  }
+
+  private emit(): void {
+    for (const listener of Array.from(this.listeners)) listener(this.showingPage)
+  }
+
+  private enqueue(op: () => void): void {
+    this.ops.push(op)
+    if (this.draining) return
+    this.draining = true
+    try {
+      while (this.ops.length) (this.ops.shift() as () => void)()
+    } finally {
+      this.draining = false
+    }
+  }
+}
+
+const pageHost = new PageHost()
+export default pageHost
+export {PageHost}

package/src/services/pages/overlayApps.ts

@@ -0,0 +1,72 @@
+/**
+ * The overlay apps: the connected miniapps whose manifest type is
+ * "system_dashboard" (the dashboard, the notifications viewer). They alone
+ * may take the overlay slot through `session.display.showView("dashboard")`
+ * and have "dashboard" in their `display.views` capability while the
+ * glasses are eligible. The runtime adds an app when it connects and
+ * removes it when it stops; the engine never knows what any of them draws.
+ * Kept free of imports so the runtime and the notification policy can both
+ * read it without a cycle.
+ */
+
+export type DisplayView = "main" | "dashboard"
+
+const apps = new Set<string>()
+/** Overlay apps listening to the phone's notifications: something on the glasses presents them. */
+const viewers = new Set<string>()
+const listeners = new Set<() => void>()
+
+export function isOverlayApp(packageName: string): boolean {
+  return apps.has(packageName)
+}
+
+export function overlayApps(): readonly string[] {
+  return [...apps]
+}
+
+export function addOverlayApp(packageName: string): void {
+  if (apps.has(packageName)) return
+  apps.add(packageName)
+  emit()
+}
+
+export function removeOverlayApp(packageName: string): void {
+  viewers.delete(packageName)
+  if (!apps.delete(packageName)) return
+  emit()
+}
+
+/** Record whether an overlay app subscribes to phone notifications (it is a viewer while it does). */
+export function setOverlayViewer(packageName: string, listening: boolean): void {
+  const was = viewers.has(packageName)
+  if (listening && apps.has(packageName)) viewers.add(packageName)
+  else viewers.delete(packageName)
+  if (was !== viewers.has(packageName)) emit()
+}
+
+/** An overlay app that presents phone notifications is running. */
+export function overlayViewerRunning(): boolean {
+  return viewers.size > 0
+}
+
+export function onOverlayAppsChange(listener: () => void): () => void {
+  listeners.add(listener)
+  return () => {
+    listeners.delete(listener)
+  }
+}
+
+/** The views `packageName` may draw: main for everyone, the dashboard for overlay apps on eligible glasses. */
+export function displayViewsFor(packageName: string, eligible: boolean): DisplayView[] {
+  return apps.has(packageName) && eligible ? ["main", "dashboard"] : ["main"]
+}
+
+function emit(): void {
+  for (const listener of Array.from(listeners)) listener()
+}
+
+/** Tests only. */
+export function _resetOverlayAppsForTest(): void {
+  apps.clear()
+  viewers.clear()
+}

package/src/services/pages/pageEligibility.ts

@@ -0,0 +1,30 @@
+/**
+ * Whether the dashboard view may show right now: connected Glassly CFW
+ * glasses with the dashboard enabled. The page host reads it before showing
+ * a page and hides the showing page when it turns false; the miniapp runtime
+ * folds it into the designated app's `display.views` capability. Read at
+ * decision time, never cached.
+ */
+import {useGlassesStore} from "../../stores/glasses"
+import {SETTINGS, useSettingsStore} from "../../stores/settings"
+import {DeviceTypes} from "../../types/enums"
+import {isGlassesConnected} from "../GlassesReadiness"
+
+/** G2.swift appends this marker after the firmware advertises Glassly CFW capabilities. */
+export function isCfwFirmwareVersion(firmwareVersion: string | null | undefined): boolean {
+  return firmwareVersion?.toLowerCase().includes("glassly cfw") === true
+}
+
+/** Stock G2 and NIMO are intentionally excluded. */
+export function isCustomDashboardEligible(info: {model?: string | null; firmwareVersion?: string | null}): boolean {
+  return info.model === DeviceTypes.G2 && isCfwFirmwareVersion(info.firmwareVersion)
+}
+
+export function pagesEligible(): boolean {
+  if (useSettingsStore.getState().getSetting(SETTINGS.custom_dashboard_enabled.key) === false) return false
+  const state = useGlassesStore.getState()
+  return (
+    isGlassesConnected(state.connection) &&
+    isCustomDashboardEligible({model: state.deviceModel, firmwareVersion: state.firmwareVersion})
+  )
+}

package/src/services/settingsBridge.ts

@@ -0,0 +1,111 @@
+/**
+ * The settings bridge's vocabulary (session.settings): which engine settings
+ * a system miniapp may read or write, the derived read-only keys the engine
+ * computes rather than stores, and the request validation. Pure, so the
+ * runtime's handlers stay thin and this can be tested without the native
+ * import surface the runtime pulls in.
+ *
+ * The dashboard miniapp is the consumer: it edits the same dashboard,
+ * notification and glasses-menu keys the phone's settings screens used to,
+ * through the store, so persistence, server sync and the Bluetooth sync of
+ * `menu_apps` behave as if a phone screen wrote them.
+ */
+
+export type SettingsBridgeAccess = "read" | "write"
+
+/** Stored settings the bridge serves, by key, with what a system app may do to each. */
+export const SETTINGS_BRIDGE_KEYS: Readonly<Record<string, SettingsBridgeAccess>> = {
+  // The dashboard's master switch is a phone-side debug knob.
+  custom_dashboard_enabled: "read",
+  custom_dashboard_clock_style: "write",
+  custom_dashboard_clock_show_date: "write",
+  custom_dashboard_battery_style: "write",
+  custom_dashboard_layout: "write",
+  custom_dashboard_calendar_event_count: "write",
+  custom_dashboard_calendar_days_ahead: "write",
+  contextual_dashboard: "write",
+  twelve_hour_time: "write",
+  menu_apps: "write",
+  notifications_enabled: "write",
+  notifications_popups: "write",
+  notifications_popup_seconds: "write",
+  notifications_hold_during_apps: "write",
+  notifications_ignore_while_active: "write",
+  notifications_blocklist: "write",
+  // Apps the glasses reported posting notifications; the engine records it.
+  notification_seen_apps: "read",
+}
+
+/**
+ * Read-only keys the engine computes: whether the wearer can see the phone,
+ * whether the foreground miniapp is drawing on the glasses, and the ring's
+ * battery. They change on their own clocks; the runtime pushes them like
+ * stored keys.
+ */
+export const DERIVED_SETTINGS_KEYS = ["phone_active", "foreground_app_on_screen", "ring_battery"] as const
+export type DerivedSettingsKey = (typeof DERIVED_SETTINGS_KEYS)[number]
+
+export function isDerivedSettingsKey(key: string): key is DerivedSettingsKey {
+  return (DERIVED_SETTINGS_KEYS as readonly string[]).includes(key)
+}
+
+/** What a system app may do with `key`, or null when the bridge does not serve it. */
+export function settingsBridgeAccess(key: string): SettingsBridgeAccess | null {
+  if (isDerivedSettingsKey(key)) return "read"
+  return SETTINGS_BRIDGE_KEYS[key] ?? null
+}
+
+/** Every key the bridge serves, stored then derived. */
+export function allSettingsBridgeKeys(): string[] {
+  return [...Object.keys(SETTINGS_BRIDGE_KEYS), ...DERIVED_SETTINGS_KEYS]
+}
+
+/**
+ * The keys a SETTINGS_GET asks for: everything when `requested` is absent,
+ * else the known ones among the requested strings (unknown keys are left
+ * out, never rejected).
+ */
+export function selectSettingsBridgeKeys(requested: unknown): string[] {
+  if (requested === undefined || requested === null) return allSettingsBridgeKeys()
+  if (!Array.isArray(requested)) return []
+  return requested.filter((key): key is string => typeof key === "string" && settingsBridgeAccess(key) !== null)
+}
+
+export type SettingsSetValidation =
+  | {ok: true; key: string; value: unknown}
+  | {ok: false; code: "INVALID_ARGUMENT" | "NOT_PERMITTED"; message: string}
+
+/** A SETTINGS_SET payload: a writable key and a JSON value (undefined is not a value). */
+export function validateSettingsSet(payload: Record<string, unknown>): SettingsSetValidation {
+  const key = payload.key
+  if (typeof key !== "string" || !key) {
+    return {ok: false, code: "INVALID_ARGUMENT", message: "settings.set requires a key"}
+  }
+  const access = settingsBridgeAccess(key)
+  if (access === null) return {ok: false, code: "INVALID_ARGUMENT", message: `Unknown setting "${key}"`}
+  if (access !== "write") return {ok: false, code: "NOT_PERMITTED", message: `Setting "${key}" is read-only`}
+  if (!("value" in payload) || payload.value === undefined) {
+    return {ok: false, code: "INVALID_ARGUMENT", message: "settings.set requires a value"}
+  }
+  return {ok: true, key, value: payload.value}
+}
+
+/** The ring's battery as the dashboard shows it: the relayed ring first, else the controller. */
+export interface RingBattery {
+  connected: boolean
+  /** -1 when unknown. */
+  level: number
+}
+
+export function ringBatteryFrom(glasses: {
+  ringConnected: boolean
+  ringBatteryLevel: number
+  controllerConnected: boolean
+  controllerBatteryLevel: number
+}): RingBattery {
+  const relayed = glasses.ringConnected && glasses.ringBatteryLevel >= 0
+  return {
+    connected: relayed || glasses.controllerConnected,
+    level: relayed ? glasses.ringBatteryLevel : glasses.controllerBatteryLevel,
+  }
+}

package/src/services/speakerProfileStoreInstance.ts

@@ -9,7 +9,7 @@ import {cloudClientService} from "./CloudClientService"
 import {SpeakerProfileStore} from "./SpeakerProfileStore"
 
 export const speakerProfileStore = new SpeakerProfileStore({
-  getUserId: () => cloudClientService.resolveGlasslyUserId(),
+  getUserId: () => cloudClientService.resolveUserId(),
   backend: {
     get(key: string): unknown | null {
       const result = mmkvStorage.load<unknown>(key)

package/src/services/uiShim.ts

@@ -10,7 +10,7 @@
  *   - Buffers `glassly.send(channel, payload)` calls until `glassly.ready()`
  *     fires + the host acks the channel is open. WebView-side BUFFERS (the
  *     WebView is the short-lived side and shouldn't drop user input).
- *   - Installs `window.__glassly.recv(envelope)` for the host to push
+ *   - Installs `window.__host.recv(envelope)` for the host to push
  *     background → WebView messages via `webview.injectJavaScript(...)`.
  *   - Sends `__heartbeat__` every 5s; host considers the WebView gone
  *     after 15s of silence.
@@ -39,12 +39,12 @@ export interface UiShimOptions {
 export function buildUiShim(options: UiShimOptions): string {
   const packageNameJson = JSON.stringify(options.packageName)
   // The IIFE assembles a typed `glassly` global plus an internal
-  // `__glassly` for host inbound calls. Quoted strings are JSON-safe so
+  // `__host` for host inbound calls. Quoted strings are JSON-safe so
   // direct injection inside another JS literal also works.
   return `
 (function () {
   if (typeof window === 'undefined') return;
-  if (window.glassly && window.__glassly) return;
+  if (window.glassly && window.__host) return;
   var packageName = ${packageNameJson};
   // Resolve window.ReactNativeWebView.postMessage LAZILY, not once at shim-eval.
   // On Android the shim is injected as a WebViewCompat document-start script
@@ -369,7 +369,7 @@ export function buildUiShim(options: UiShimOptions): string {
     /** @internal — packageName for diagnostic logs only. */
     _packageName: packageName,
   };
-  window.__glassly = { recv: recv };
+  window.__host = { recv: recv };
 })();
 `.trim()
 }

package/src/stores/appVisibility.ts

@@ -1,3 +1,48 @@
 /** Combine registry-enforced visibility with the user's home-screen choice. */
 export const resolveHiddenStatus = (registryHidden: boolean, userHidden: boolean): boolean =>
   registryHidden || userHidden
+
+/**
+ * Miniapps that start off the primary home screen. They stay listed under
+ * "view all apps", where "Add to Home" saves an explicit choice that wins
+ * over this default from then on.
+ */
+export const DEFAULT_HIDDEN_PACKAGES: ReadonlySet<string> = new Set(["com.glassly.camera", "com.glassly.recorder"])
+
+/** The home-screen visibility of an app the user has never hidden or added. */
+export const defaultHiddenStatus = (packageName: string): boolean => DEFAULT_HIDDEN_PACKAGES.has(packageName)
+
+/**
+ * Miniapps that exist only for developers: the Miniapp Developer launcher and
+ * the bundled sample/test miniapps. They are projected into the app store
+ * only while the `dev_tools` setting is on; off, they are absent from every
+ * launcher surface (home, all apps, glasses menu, AI listing), not merely
+ * hidden from the primary home screen.
+ */
+export const DEV_TOOLS_PACKAGES: ReadonlySet<string> = new Set([
+  "com.glassly.miniappdev",
+  "com.glassly.example",
+  "com.glassly.tetris",
+  "com.glassly.compass",
+  "com.glassly.showcase",
+])
+
+/** True when the app is dev-only and developer tools are off. */
+export const isGatedByDevTools = (packageName: string, devToolsEnabled: boolean): boolean =>
+  !devToolsEnabled && DEV_TOOLS_PACKAGES.has(packageName)
+
+/**
+ * Miniapps that unlock once a real pair of glasses has been paired on this
+ * phone (`has_paired_glasses`, latched by PairedGlassesLatch and never
+ * cleared, so forgetting the glasses keeps them). Developer tools open them
+ * early. Until either, they are absent from every launcher surface like the
+ * dev-only set above.
+ */
+export const PAIRED_GLASSES_PACKAGES: ReadonlySet<string> = new Set(["com.glassly.store"])
+
+/** True when the app waits on a pairing that hasn't happened and dev tools are off. */
+export const isGatedUntilPaired = (
+  packageName: string,
+  devToolsEnabled: boolean,
+  hasPairedGlasses: boolean,
+): boolean => !devToolsEnabled && !hasPairedGlasses && PAIRED_GLASSES_PACKAGES.has(packageName)