@glassly/engine 0.3.5 → 0.3.6-dev.846

package/src/services/MemoryStore.ts

@@ -17,7 +17,14 @@
  * user-scoped keys so existing history survives the move.
  */
 
-import type {MemoryEntry, MemoryNoteSource, MemorySession, MemorySummary} from "@glassly/miniapp"
+import type {
+  MemoryBackup,
+  MemoryEntry,
+  MemoryImportResult,
+  MemoryNoteSource,
+  MemorySession,
+  MemorySummary,
+} from "@glassly/miniapp"
 
 import {searchMemoryEntries} from "../utils/memory/search"
 
@@ -91,6 +98,14 @@ export interface MemoryStats {
   oldestAt: number | null
 }
 
+/** Thrown by importBackup for anything that isn't a backup this build can read. */
+export class MemoryBackupError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "MemoryBackupError"
+  }
+}
+
 export function hourStartOf(ms: number): number {
   return Math.floor(ms / HOUR_MS) * HOUR_MS
 }
@@ -359,6 +374,65 @@ export class MemoryStore {
     return Math.max(...hours)
   }
 
+  /** The whole timeline as a backup file body (Settings > Memory, session.memory.exportFile). */
+  async exportBackup(): Promise<MemoryBackup> {
+    await this.ensureLoaded()
+    return {
+      format: "glassly-memory",
+      version: 1,
+      exportedAt: Date.now(),
+      entries: [...this.entries],
+      summaries: [...this.summaries].sort((a, b) => a.hourStart - b.hourStart),
+    }
+  }
+
+  /**
+   * Merge a backup into the timeline. Skips entries whose id is stored, notes
+   * whose text is already in the same hour, and hours that already have a
+   * summary. Throws MemoryBackupError when `data` isn't a memory backup.
+   */
+  async importBackup(data: unknown): Promise<MemoryImportResult> {
+    const backup = parseBackup(data)
+    await this.ensureLoaded()
+    const result: MemoryImportResult = {entries: 0, summaries: 0, skipped: 0}
+
+    const ids = new Set(this.entries.map((e) => e.id))
+    const noteKeys = new Set(this.entries.filter((e) => e.kind === "note").map(noteKey))
+    for (const entry of backup.entries) {
+      const key = entry.kind === "note" ? noteKey(entry) : null
+      if (ids.has(entry.id) || (key != null && noteKeys.has(key))) {
+        result.skipped++
+        continue
+      }
+      ids.add(entry.id)
+      if (key != null) noteKeys.add(key)
+      this.entries.push(entry)
+      result.entries++
+    }
+
+    const byHour = new Map(this.summaries.map((s) => [s.hourStart, s]))
+    for (const summary of backup.summaries) {
+      if (byHour.get(summary.hourStart)?.text.trim()) {
+        result.skipped++
+        continue
+      }
+      byHour.set(summary.hourStart, summary)
+      result.summaries++
+    }
+
+    if (result.entries > 0) {
+      this.entries.sort((a, b) => a.at - b.at)
+      this.prune()
+      await this.persistLog()
+    }
+    if (result.summaries > 0) {
+      this.summaries = [...byHour.values()].sort((a, b) => a.hourStart - b.hourStart).slice(-MEMORY_BOUNDS.maxSummaries)
+      await this.persistSummaries()
+    }
+    if (result.entries > 0 || result.summaries > 0) this.emitChanged()
+    return result
+  }
+
   /** Plain-text export of a scope, for the OS share sheet. */
   async exportText(scope: "session" | "day" | "all", at?: number): Promise<string> {
     const sessions = (await this.sessionList()).filter((s) => {
@@ -563,10 +637,45 @@ function parseArray(raw: unknown): unknown[] {
 function normalize(text: string): string {
   return text
     .toLowerCase()
-    .replace(/[^a-z0-9]+/g, " ")
+    .replace(/[^\p{L}\p{N}]+/gu, " ")
     .trim()
 }
 
+function noteKey(entry: MemoryEntry): string {
+  return `${hourStartOf(entry.at)}:${normalize(entry.text)}`
+}
+
+function parseBackup(data: unknown): {entries: MemoryEntry[]; summaries: MemorySummary[]} {
+  const raw = data as Record<string, unknown> | null
+  if (!raw || typeof raw !== "object" || raw.format !== "glassly-memory" || !Array.isArray(raw.entries)) {
+    throw new MemoryBackupError("Not a Glassly memory backup")
+  }
+  if (typeof raw.version !== "number" || raw.version > 1) {
+    throw new MemoryBackupError(`Unsupported memory backup version ${String(raw.version)}`)
+  }
+  const entries: MemoryEntry[] = []
+  for (const v of raw.entries) {
+    if (!isEntry(v) || !v.id || !v.text.trim() || !Number.isFinite(v.at)) continue
+    entries.push({
+      id: v.id,
+      kind: v.kind,
+      text: v.text.trim(),
+      at: v.at,
+      speakerId: typeof v.speakerId === "string" ? v.speakerId : null,
+      ...(typeof v.resolvedSpeakerName === "string" && v.resolvedSpeakerName
+        ? {resolvedSpeakerName: v.resolvedSpeakerName}
+        : {}),
+      language: typeof v.language === "string" ? v.language : null,
+      ...(v.kind === "note" ? {source: v.source === "voice" || v.source === "auto" ? v.source : "ui"} : {}),
+    })
+  }
+  const summaries = (Array.isArray(raw.summaries) ? raw.summaries : [])
+    .filter(isSummary)
+    .filter((s) => s.text.trim() && Number.isFinite(s.hourStart))
+    .map((s) => ({hourStart: s.hourStart, text: s.text, createdAt: s.createdAt}))
+  return {entries, summaries}
+}
+
 function isEntry(v: unknown): v is MemoryEntry {
   if (!v || typeof v !== "object") return false
   const e = v as Record<string, unknown>

package/src/services/MiniappExitGesture.ts

@@ -4,6 +4,8 @@ interface ExitGestureApp {
   packageName: string
   name: string
   running: boolean
+  /** Running only for a placed widget: the wearer is not in it, so there is nothing to leave. */
+  widgetOnly?: boolean
 }
 
 interface ExitGestureState {
@@ -15,7 +17,8 @@ interface ExitGestureState {
 
 export interface ExitGestureDependencies {
   getState: () => ExitGestureState
-  getVisiblePackageName: () => string | null
+  /** The miniapp a double tap leaves right now, or null when the tap is the system's. */
+  getTargetPackageName: () => string | null
   beginExitNotice: (packageName: string, text: string) => boolean
   finishExitNotice: (packageName: string) => void
   cancelExitNotice: (packageName: string) => void
@@ -29,16 +32,16 @@ export class MiniappExitGesture {
 
   public constructor(private readonly deps: ExitGestureDependencies) {}
 
-  /** Returns true when the system gesture was consumed by a visible miniapp exit. */
-  public tryExitVisibleMiniapp(): boolean {
+  /** Returns true when the system gesture was consumed by a miniapp exit. */
+  public tryExitMiniapp(): boolean {
     // Swallow repeat taps while the notice is already counting down.
     if (this.pending) return true
 
-    const packageName = this.deps.getVisiblePackageName()
+    const packageName = this.deps.getTargetPackageName()
     if (!packageName) return false
 
     const app = this.deps.getState().apps.find((candidate) => candidate.packageName === packageName)
-    if (!app?.running) return false
+    if (!app?.running || app.widgetOnly) return false
 
     const name = app.name.trim() || packageName
     if (!this.deps.beginExitNotice(packageName, `Exiting ${name}…`)) return false

package/src/services/MiniappWidgetMode.ts

@@ -2,25 +2,27 @@
  * Widget mode: a miniapp whose background context runs only because a host
  * (the dashboard) placed one of its widgets. It is running, but it has no
  * card in the app switcher, draws nothing of its own on the glasses and
- * hears no touch input; the Widgets pill lists it. Opening the app from the
- * home screen promotes it to a normal run; closing a placed app from the
- * tray demotes it back here instead of stopping it.
+ * hears no touch input; the Widgets pill lists it. Foregrounding the app on
+ * the phone promotes it to a normal run (the store's start/setForeground);
+ * closing a placed app from the tray demotes it back here instead of
+ * stopping it.
  *
  * The runtime is the writer (placements come and go through it); the apps
  * store projects `widgetOnly` from here beside `running`.
  */
 
-type Listener = () => void
+/** Called with the app whose mode changed and whether it is now widget-only. */
+type Listener = (packageName: string, widgetOnly: boolean) => void
 
 const widgetOnly = new Set<string>()
 /** Providers with at least one widget placed by some host. */
 const placed = new Set<string>()
 const listeners = new Set<Listener>()
 
-function notify(): void {
+function notify(packageName: string, on: boolean): void {
   for (const fn of listeners) {
     try {
-      fn()
+      fn(packageName, on)
     } catch (e) {
       console.warn("MiniappWidgetMode: listener threw", e)
     }
@@ -32,7 +34,7 @@ export const miniappWidgetMode = {
   setWidgetOnly(packageName: string, on: boolean): void {
     const changed = on ? !widgetOnly.has(packageName) : widgetOnly.delete(packageName)
     if (on) widgetOnly.add(packageName)
-    if (changed) notify()
+    if (changed) notify(packageName, on)
   },
 
   isWidgetOnly(packageName: string): boolean {

package/src/services/ProviderKeyValidation.ts

@@ -51,6 +51,11 @@ export function validateOpenAiApiKey(apiKey: string): Promise<KeyValidationResul
   return probe("https://api.openai.com/v1/models", {Authorization: `Bearer ${apiKey.trim()}`}, [401, 403])
 }
 
+/** GET /models with the candidate key; DeepSeek answers 401 for bad keys. */
+export function validateDeepSeekApiKey(apiKey: string): Promise<KeyValidationResult> {
+  return probe("https://api.deepseek.com/models", {Authorization: `Bearer ${apiKey.trim()}`}, [401, 403])
+}
+
 /** GET /v1/user with the candidate key; ElevenLabs answers 401 for bad keys. */
 export function validateElevenLabsApiKey(apiKey: string): Promise<KeyValidationResult> {
   return probe("https://api.elevenlabs.io/v1/user", {"xi-api-key": apiKey.trim()}, [401, 403])

package/src/services/SceneRenderer.ts

@@ -66,7 +66,9 @@ const MAX_SETTLE_MS = 255 * 33
 function settleTimeOf(elements: FrameElement[]): number {
   let ms = 0
   for (const el of elements) {
-    if (el.change !== "updated" && el.change !== "moved") continue
+    // Entering and leaving elements tween too, from or to their offset.
+    const edge = el.transition?.exit !== undefined || (el.change === "created" && el.transition?.enter !== undefined)
+    if (el.change !== "updated" && el.change !== "moved" && !edge) continue
     const t = el.transition?.durationMs ?? 0
     // Rotation has its own millisecond clock, beyond the geometry frame limit.
     const duration = Math.min(t, el.rotation !== undefined ? 65535 : MAX_SETTLE_MS)

package/src/services/ScreenshotFixture.ts

@@ -0,0 +1,113 @@
+/**
+ * Screenshot fixture — dresses Phone Mode up as a paired Even Realities G2
+ * with a Meta Neural Band and an R1 ring, for the store-screenshot build only
+ * (EXPO_PUBLIC_SCREENSHOT_MODE=1, set by scripts/maestro-screenshots-*.mjs
+ * for its own Release build and never by a shipped one).
+ *
+ * The fixture is applied where hosts READ — engine.pairing.identity and
+ * engine.glasses.status/info/controllers.* — not where native writes: the
+ * Simulated driver keeps running underneath (so the mirror has frames),
+ * nothing is persisted, and native never learns of the fixture, so no
+ * reconnect, demotion or driver path can act on it. It is active only while
+ * the underlying identity is the simulated device: home enters Phone Mode as
+ * usual (identity `none` passes through untouched), the simulated pairing
+ * then flips the read-models to the fixture, and real glasses on a fixture
+ * build stay real.
+ */
+import type {ControllerStatus, PairedController} from "@glassly/bluetooth-sdk"
+
+import {ControllerTypes, DeviceTypes} from "../types/enums"
+import type {IdentitySnapshot} from "./PairingIdentity"
+
+export function isScreenshotMode(): boolean {
+  return process.env.EXPO_PUBLIC_SCREENSHOT_MODE === "1"
+}
+
+export const FIXTURE_GLASSES = {
+  model: DeviceTypes.G2,
+  name: "Even G2_7F3A",
+  battery: 87,
+  caseBattery: 100,
+  signal: -58,
+} as const
+
+interface FixtureController extends PairedController {
+  batteryLevel: number
+}
+
+// The R1's id is its ring id (from the BLE name); the band's is an opaque
+// peripheral id. Both are stable fixtures so flows can target
+// `controller-tile-<id>`.
+export const FIXTURE_CONTROLLERS: readonly FixtureController[] = [
+  {id: "7C1A2B9E", model: ControllerTypes.NEURAL_BAND, name: "Meta Neural Band", batteryLevel: 73},
+  {id: "CEC5BA", model: ControllerTypes.R1, name: "CEC5BA", batteryLevel: 58},
+]
+
+/** The fixture dresses Phone Mode only. */
+export function fixtureActive(identity: IdentitySnapshot): boolean {
+  return isScreenshotMode() && identity.kind === "paired" && identity.model.includes(DeviceTypes.SIMULATED)
+}
+
+export function fixtureIdentity(identity: IdentitySnapshot): IdentitySnapshot {
+  if (!fixtureActive(identity)) return identity
+  return {kind: "paired", model: FIXTURE_GLASSES.model, name: FIXTURE_GLASSES.name}
+}
+
+interface StatusLike {
+  battery: number
+  charging: boolean
+  case: {battery: number; charging: boolean; open: boolean; removed: boolean}
+  signal: number
+}
+
+export function fixtureStatus<T extends StatusLike>(status: T, identity: IdentitySnapshot): T {
+  if (!fixtureActive(identity)) return status
+  return {
+    ...status,
+    battery: FIXTURE_GLASSES.battery,
+    charging: false,
+    case: {battery: FIXTURE_GLASSES.caseBattery, charging: false, open: false, removed: false},
+    signal: FIXTURE_GLASSES.signal,
+  }
+}
+
+interface InfoLike {
+  model: string
+  firmwareUpdateAvailable: boolean
+}
+
+export function fixtureInfo<T extends InfoLike>(info: T, identity: IdentitySnapshot): T {
+  if (!fixtureActive(identity)) return info
+  return {...info, model: FIXTURE_GLASSES.model, firmwareUpdateAvailable: false}
+}
+
+/** Fixture controllers first, then any real records that are not the fixture's. */
+export function fixtureControllerList(list: PairedController[], identity: IdentitySnapshot): PairedController[] {
+  if (!fixtureActive(identity)) return list
+  const fixture = FIXTURE_CONTROLLERS.map(({id, model, name}) => ({id, model, name}))
+  const ids = new Set(fixture.map((record) => record.id))
+  return [...fixture, ...list.filter((record) => !ids.has(record.id))]
+}
+
+export function fixtureControllerStatuses(
+  statuses: Record<string, ControllerStatus>,
+  identity: IdentitySnapshot,
+): Record<string, ControllerStatus> {
+  if (!fixtureActive(identity)) return statuses
+  const result = {...statuses}
+  for (const {id, model, name, batteryLevel} of FIXTURE_CONTROLLERS) {
+    result[id] = {
+      id,
+      model,
+      name,
+      connected: true,
+      fullyBooted: true,
+      searching: false,
+      batteryLevel,
+      charging: false,
+      macAddress: "",
+      signalStrength: -62,
+    }
+  }
+  return result
+}

package/src/services/actionInvoke.ts

@@ -0,0 +1,105 @@
+import {MiniappErrorCode} from "@glassly/miniapp"
+
+import type {ClientApp} from "../types/applet"
+
+export type ActionError = {code: string; message: string} & Record<string, unknown>
+export type ActionOutcome = {ok: true; data: unknown} | {ok: false; error: ActionError}
+
+export const actionFailure = (code: string, message: string): ActionOutcome => ({ok: false, error: {code, message}})
+
+/** Installed, compatible, and declares the action. */
+export function appDeclaresAction(app: ClientApp | undefined, actionId: string): boolean {
+  if (!app) return false
+  if (app.compatibility && app.compatibility.isCompatible === false) return false
+  return (app.actions ?? []).some((a) => a.id === actionId)
+}
+
+/**
+ * Gates shared by miniapp->miniapp invoke and host invoke. Declared actions are
+ * public by default; `visibility: "system"` ones need a system caller.
+ */
+export function checkActionAccess(
+  app: ClientApp | undefined,
+  target: string | undefined,
+  actionId: string | undefined,
+  callerIsSystem: boolean,
+): ActionError | null {
+  if (!target || !app) {
+    return {
+      code: MiniappErrorCode.APP_NOT_FOUND,
+      message: `Miniapp not found: ${target ?? "(missing targetPackageName)"}`,
+    }
+  }
+  if (!actionId) return {code: MiniappErrorCode.ACTION_NOT_FOUND, message: "invoke requires an actionId"}
+  if (app.compatibility && app.compatibility.isCompatible === false) {
+    return {
+      code: MiniappErrorCode.APP_NOT_COMPATIBLE,
+      message: `${target} is not compatible with the connected glasses`,
+    }
+  }
+  const declared = (app.actions ?? []).find((a) => a.id === actionId)
+  if (!declared) {
+    return {code: MiniappErrorCode.ACTION_NOT_FOUND, message: `${target} does not declare action "${actionId}"`}
+  }
+  if (declared.visibility === "system" && !callerIsSystem) {
+    return {
+      code: MiniappErrorCode.NOT_PERMITTED,
+      message: `Action "${actionId}" on ${target} is restricted to system apps`,
+    }
+  }
+  return null
+}
+
+/** BgTimer's shape; passed in so this module stays loadable without the native timer. */
+export interface ActionTimers {
+  setTimeout: (cb: () => void, ms: number) => number
+  clearTimeout: (id: number) => void
+}
+
+/** Outstanding ACTION_CALLs awaiting an ACTION_RESULT, keyed by host-generated callId. */
+export class PendingActionCalls {
+  private readonly calls = new Map<string, {target: string; settle: (o: ActionOutcome) => void; timer: number}>()
+
+  constructor(
+    private readonly timers: ActionTimers,
+    private readonly payloadTooLarge: (value: unknown) => boolean,
+  ) {}
+
+  /** Register a call; resolves with its outcome, or ACTION_TIMEOUT. */
+  register(callId: string, target: string, actionId: string, timeoutMs: number): Promise<ActionOutcome> {
+    return new Promise((resolve) => {
+      const timer = this.timers.setTimeout(() => {
+        this.calls.delete(callId)
+        resolve(actionFailure(MiniappErrorCode.ACTION_TIMEOUT, `action "${actionId}" timed out after ${timeoutMs}ms`))
+      }, timeoutMs)
+      this.calls.set(callId, {target, settle: resolve, timer})
+    })
+  }
+
+  /** Settle from a target's ACTION_RESULT payload. Only the invoked target may resolve a call. */
+  handleResult(targetPackageName: string, payload: Record<string, unknown>): void {
+    const callId = payload.callId as string | undefined
+    if (!callId) return
+    const pending = this.calls.get(callId)
+    // callIds are guessable (timestamp + seq): a different miniapp must not spoof someone else's result.
+    if (!pending || pending.target !== targetPackageName) return
+    this.calls.delete(callId)
+    this.timers.clearTimeout(pending.timer)
+
+    if (payload.ok === true) {
+      if (this.payloadTooLarge(payload.result)) {
+        pending.settle(actionFailure(MiniappErrorCode.PAYLOAD_TOO_LARGE, "action result exceeded the 256 KB cap"))
+        return
+      }
+      pending.settle({ok: true, data: payload.result ?? null})
+      return
+    }
+    pending.settle({
+      ok: false,
+      error: (payload.error as ActionError | undefined) ?? {
+        code: MiniappErrorCode.INTERNAL,
+        message: "action handler error",
+      },
+    })
+  }
+}