@glassly/engine 0.1.0-dev.0

package/src/types/capabilities/simulated-glasses.ts

@@ -0,0 +1,95 @@
+/**
+ * @fileoverview Simulated Glasses Hardware Capabilities
+ *
+ * Capability profile for the Simulated Glasses model.
+ * Defines the hardware and software features available on this device.
+ * This profile matches the Vuzix Z100 capabilities for testing purposes.
+ */
+
+import type {Capabilities} from "../hardware"
+
+/**
+ * Simulated Glasses capability profile
+ */
+export const simulatedGlasses: Capabilities = {
+  modelName: "Simulated Glasses",
+
+  // Camera capabilities - does not have a camera
+  hasCamera: false,
+  camera: null,
+
+  // Display capabilities - has a green monochrome display
+  hasDisplay: true,
+  display: {
+    count: 1,
+    isColor: false,
+    color: "green",
+    canDisplayBitmap: true,
+    resolution: {width: 640, height: 480},
+    fieldOfView: {horizontal: 30},
+    maxTextLines: 7,
+    adjustBrightness: true,
+
+    // Scene display API — the simulated display is the phone-side mirror,
+    // which renders positioned text AND image elements natively. Mirror the
+    // G2's canvas and budgets so behavior verified here transfers to real
+    // hardware (without this block the scene pipeline degrades every frame
+    // to a text wall and image elements are silently dropped).
+    width: 576,
+    height: 288,
+    canPosition: true,
+    maxTextElements: 6,
+    maxImageElements: 4,
+    shapes: ["rect"],
+    // The mirror renders full 8-bit grayscale; 16 matches the G2's 4-bit
+    // panel so simulated output previews what real hardware can show.
+    intensityLevels: 16,
+    partialUpdate: true,
+  },
+
+  // Microphone capabilities - has a microphone (phone mic)
+  hasMicrophone: true,
+  microphone: {
+    count: 1,
+    hasVAD: false,
+  },
+
+  // Speaker capabilities - has a speaker (phone speaker)
+  hasSpeaker: true,
+  speaker: {
+    count: 1,
+    isPrivate: false,
+  },
+
+  // IMU capabilities - does not have an IMU
+  hasIMU: false,
+  imu: null,
+
+  // Button capabilities - Has one simulated button
+  hasButton: true,
+  button: {
+    count: 1,
+    buttons: [
+      {
+        type: "press",
+        events: ["press"],
+        isCapacitive: false,
+      },
+    ],
+  },
+
+  // Light capabilities - does not have lights
+  hasLight: false,
+  light: null,
+
+  // Power capabilities - does not have external battery
+  power: {
+    hasExternalBattery: false,
+  },
+
+  // WiFi capabilities - does not support WiFi
+  hasWifi: false,
+
+  // OTA capabilities - simulated glasses do not support OTA
+  hasOta: false,
+}

package/src/types/capabilities/vuzix-z100.ts

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview Vuzix Z100 Hardware Capabilities
+ *
+ * Capability profile for the Vuzix Z100 smart glasses model.
+ * Defines the hardware and software features available on this device.
+ */
+
+import type {Capabilities} from "../hardware"
+
+/**
+ * Vuzix Z100 capability profile
+ */
+export const vuzixZ100: Capabilities = {
+  modelName: "Vuzix Z100",
+
+  // Camera capabilities - does not have a camera
+  hasCamera: false,
+  camera: null,
+
+  // Display capabilities - has a green monochrome display
+  hasDisplay: true,
+  display: {
+    count: 1,
+    isColor: false,
+    color: "green",
+    canDisplayBitmap: false,
+    resolution: {width: 640, height: 480},
+    fieldOfView: {horizontal: 30},
+    maxTextLines: 7,
+    adjustBrightness: true,
+
+    // Scene display API — no positioned elements; scenes degrade to text walls.
+    canPosition: false,
+    maxImageElements: 0,
+  },
+
+  // Microphone capabilities - does not have a microphone
+  hasMicrophone: false,
+  microphone: null,
+
+  // Speaker capabilities - does not have a speaker
+  hasSpeaker: false,
+  speaker: null,
+
+  // IMU capabilities - does not have an IMU
+  hasIMU: false,
+  imu: null,
+
+  // Button capabilities - does not have buttons
+  hasButton: false,
+  button: null,
+
+  // Light capabilities - does not have lights
+  hasLight: false,
+  light: null,
+
+  // Power capabilities - does not have external battery
+  power: {
+    hasExternalBattery: false,
+  },
+
+  // WiFi capabilities - does not support WiFi
+  hasWifi: false,
+
+  // OTA capabilities - Z100 firmware updates are not driven by the ASG OTA flow
+  hasOta: false,
+}

package/src/types/enums.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared enums for Glassly
+ * These are runtime values (not pure types)
+ */
+
+// Hardware requirement enums — canonical defs live in @glassly/miniapp
+// (src/hardware.ts); re-exported here so engine-internal code and app code
+// importing from @glassly/engine keep a single source of truth.
+export {HardwareType, HardwareRequirementLevel} from "@glassly/miniapp"
+
+export enum DeviceTypes {
+  NONE = "None",
+  SIMULATED = "Simulated Glasses",
+  AR99 = "AR99",
+  G1 = "Even Realities G1",
+  G2 = "Even Realities G2",
+  LIVE = "Mentra Live",
+  MACH1 = "Mentra Mach1",
+  Z100 = "Vuzix Z100",
+  NEX = "Mentra Display",
+  NIMO = "NIMO",
+  FRAME = "Brilliant Frame",
+}
+
+export enum ControllerTypes {
+  R1 = "Even Realities R1",
+}

package/src/types/hardware.ts

@@ -0,0 +1,220 @@
+/**
+ * Hardware capability types
+ */
+
+import {evenRealitiesG1} from "./capabilities/even-realities-g1"
+import {evenRealitiesG2} from "./capabilities/even-realities-g2"
+import {mentraDisplay} from "./capabilities/mentra-display"
+import {mentraLive} from "./capabilities/mentra-live"
+import {simulatedGlasses} from "./capabilities/simulated-glasses"
+import {nimo} from "./capabilities/nimo"
+import {vuzixZ100} from "./capabilities/vuzix-z100"
+import {none} from "./capabilities/none"
+import {DeviceTypes} from "./enums"
+
+// Canonical def lives in @glassly/miniapp; re-exported for engine consumers.
+export type {HardwareRequirement} from "@glassly/miniapp"
+
+/**
+ * Camera capabilities
+ */
+export interface CameraCapabilities {
+  resolution?: {width: number; height: number}
+  hasHDR?: boolean
+  hasFocus?: boolean
+  video: {
+    canRecord: boolean
+    canStream: boolean
+    supportedStreamTypes?: string[]
+    supportedResolutions?: {width: number; height: number}[]
+  }
+}
+
+/**
+ * Display capabilities
+ */
+export interface DisplayCapabilities {
+  count?: number
+  isColor?: boolean
+  color?: string // e.g., "green", "full_color", "pallet"
+  canDisplayBitmap?: boolean
+  resolution?: {width: number; height: number}
+  fieldOfView?: {horizontal?: number; vertical?: number}
+  maxTextLines?: number
+  adjustBrightness?: boolean
+
+  // --- Scene display API (display.render()) — typed capabilities ---
+  // Pure DATA the host scene pipeline acts on generically; a device without
+  // canPosition renders scenes via the host degrade path instead.
+  /** Public drawable canvas in px — the raw coordinate space for render() boxes. */
+  width?: number
+  height?: number
+  /** True ⇒ the device renders positioned elements (containers / canvas components). */
+  canPosition?: boolean
+  /** Element budgets. Rects share the text pool on container-based devices. */
+  maxTextElements?: number
+  maxImageElements?: number
+  /** Per-image dimension cap (box-level), when the firmware has one. */
+  maxImagePx?: {width: number; height: number}
+  shapes?: "rect"[]
+  intensityLevels?: number
+  partialUpdate?: boolean
+}
+
+/**
+ * Microphone capabilities
+ */
+export interface MicrophoneCapabilities {
+  count?: number
+  hasVAD?: boolean // Voice Activity Detection
+}
+
+/**
+ * Speaker capabilities
+ */
+export interface SpeakerCapabilities {
+  count?: number
+  isPrivate?: boolean // e.g., bone conduction
+}
+
+/**
+ * IMU (Inertial Measurement Unit) capabilities
+ */
+export interface IMUCapabilities {
+  axisCount?: number
+  hasAccelerometer?: boolean
+  hasCompass?: boolean
+  hasGyroscope?: boolean
+}
+
+/**
+ * Button capabilities
+ */
+export interface ButtonCapabilities {
+  count?: number
+  buttons?: {
+    type: "press" | "swipe1d" | "swipe2d"
+    events: string[] // e.g., "press", "double_press", "long_press", "swipe_up", "swipe_down"
+    isCapacitive?: boolean
+  }[]
+}
+
+/**
+ * Light capabilities
+ */
+export interface LightCapabilities {
+  count?: number
+  lights?: {
+    id: string // Unique identifier for the LED (e.g., "privacy", "user_feedback")
+    purpose: "privacy" | "user_feedback" | "general" // LED purpose/function
+    isFullColor: boolean
+    color?: string // e.g., "white", "rgb"
+    position?: "front_facing" | "user_facing" | "side" | "unknown" // LED physical position
+  }[]
+}
+
+/**
+ * Power capabilities
+ */
+export interface PowerCapabilities {
+  hasExternalBattery: boolean // e.g., a case or puck
+}
+
+/**
+ * Device hardware capabilities
+ * Complete information about what hardware a device has
+ */
+export interface Capabilities {
+  modelName: string
+
+  // Camera capabilities
+  hasCamera: boolean
+  camera: CameraCapabilities | null
+
+  // Display capabilities
+  hasDisplay: boolean
+  display: DisplayCapabilities | null
+
+  // Microphone capabilities
+  hasMicrophone: boolean
+  microphone: MicrophoneCapabilities | null
+
+  // Speaker capabilities
+  hasSpeaker: boolean
+  speaker: SpeakerCapabilities | null
+
+  // IMU capabilities
+  hasIMU: boolean
+  imu: IMUCapabilities | null
+
+  // Button capabilities
+  hasButton: boolean
+  button: ButtonCapabilities | null
+
+  // Light capabilities
+  hasLight: boolean
+  light: LightCapabilities | null
+
+  // Power capabilities
+  power: PowerCapabilities
+
+  // WiFi capability
+  hasWifi: boolean
+
+  // OTA capability
+  hasOta?: boolean
+
+  // Native dashboard capability
+  // True when the device renders its own dashboard in firmware (e.g. Even
+  // Realities' built-in dashboard on G2). Glassly does not manage or expose
+  // dashboard settings for these devices. Absent/false means Glassly owns the
+  // dashboard.
+  hasNativeDashboard?: boolean
+
+  // True when the device renders its own turn-by-turn nav UI in firmware
+  // (G2 nav mode: instruction card + map slots + magnetometer compass); nav
+  // apps feed it structured fields and map bitmaps instead of scene elements
+  hasNativeNavigation?: boolean
+}
+
+/**
+ * Hardware capability profiles for supported glasses models
+ * Key: model_name string (e.g., "Even Realities G1", "Mentra Live")
+ * Value: Capabilities object defining device features
+ */
+export const HARDWARE_CAPABILITIES: Record<string, Capabilities> = {
+  [evenRealitiesG1.modelName]: evenRealitiesG1,
+  [evenRealitiesG2.modelName]: evenRealitiesG2,
+  [mentraDisplay.modelName]: mentraDisplay,
+  [mentraLive.modelName]: mentraLive,
+  [simulatedGlasses.modelName]: simulatedGlasses,
+  [vuzixZ100.modelName]: vuzixZ100,
+  [DeviceTypes.MACH1]: vuzixZ100, // Mach1 uses same Vuzix Ultralite hardware as Z100
+  [nimo.modelName]: nimo,
+  [DeviceTypes.AR99]: {
+    ...evenRealitiesG1,
+    modelName: DeviceTypes.AR99,
+    display: {
+      ...evenRealitiesG1.display,
+      canDisplayBitmap: false,
+    },
+    hasMicrophone: true,
+    hasOta: true,
+    microphone: {
+      count: 1,
+      hasVAD: false,
+    },
+  },
+  [none.modelName]: none,
+}
+
+export const getModelCapabilities = (deviceType: DeviceTypes): Capabilities => {
+  const modelName = deviceType as string
+  if (!HARDWARE_CAPABILITIES[modelName]) {
+    return HARDWARE_CAPABILITIES[DeviceTypes.NONE]
+  }
+  return HARDWARE_CAPABILITIES[modelName]
+}
+
+// export * from "./capabilities"
+export {simulatedGlasses, evenRealitiesG1, evenRealitiesG2, mentraLive, vuzixZ100, mentraDisplay, nimo}

package/src/types/index.ts

@@ -0,0 +1,38 @@
+/**
+ * Engine shared types. Hardware requirement types (HardwareType,
+ * HardwareRequirementLevel, HardwareRequirement) are canonical in
+ * @glassly/miniapp and re-exported here; the rest (DeviceTypes, capability
+ * profiles under ./capabilities/, applet types) are engine-owned.
+ */
+
+// Enums (runtime values)
+export {HardwareType, HardwareRequirementLevel, DeviceTypes, ControllerTypes} from "./enums"
+
+// Hardware types
+export type {
+  HardwareRequirement,
+  CameraCapabilities,
+  DisplayCapabilities,
+  MicrophoneCapabilities,
+  SpeakerCapabilities,
+  IMUCapabilities,
+  ButtonCapabilities,
+  LightCapabilities,
+  PowerCapabilities,
+  Capabilities,
+} from "./hardware"
+
+export {
+  HARDWARE_CAPABILITIES,
+  getModelCapabilities,
+  simulatedGlasses,
+  evenRealitiesG1,
+  evenRealitiesG2,
+  mentraLive,
+  vuzixZ100,
+  mentraDisplay,
+  nimo,
+} from "./hardware"
+
+// Applet types
+export type {AppletType, AppPermissionType, AppletPermission, AppletInterface, ClientApp} from "./applet"

package/src/utils/GlobalEventEmitter.ts

@@ -0,0 +1,15 @@
+// @ts-nocheck — `events` (node builtin, RN-polyfilled) ships no types in engine's
+// standalone build; the host build resolves them fine.
+import {EventEmitter} from "events"
+
+/**
+ * Process-wide event bus — moved into engine so engine-owned services (e.g.
+ * DeviceEventRouter) and the host share ONE emitter instance across the
+ * engine↔host boundary.
+ * Re-exported through the host's `@/utils/GlobalEventEmitter` shim.
+ *
+ * @deprecated Use BluetoothSDK subscriptions directly instead.
+ */
+const GlobalEventEmitter = new EventEmitter()
+
+export default GlobalEventEmitter

package/src/utils/cloudClient/RnUdpAdapter.ts

@@ -0,0 +1,47 @@
+/**
+ * @fileoverview react-native-udp backed UdpSocketLike for @glassly/cloud-client.
+ *
+ * The cloud-client encrypts each audio frame in shared code (NaCl secretbox) and
+ * hands the raw bytes here; this adapter only owns the native dgram socket and
+ * sends them. Audio bytes never round-trip through extra JS here beyond the
+ * Buffer wrap the native module needs.
+ */
+import dgram from "react-native-udp"
+import type {UdpSocketLike} from "@glassly/cloud-client"
+
+type CloudUdpSocket = ReturnType<typeof dgram.createSocket> & {
+  on(event: "error", cb: (err: Error) => void): void
+  on(event: "message", cb: (msg: Uint8Array) => void): void
+}
+
+export function createCloudUdpSocket(): UdpSocketLike {
+  const socket = dgram.createSocket({type: "udp4"}) as CloudUdpSocket
+  let onBytes: ((bytes: Uint8Array) => void) | null = null
+
+  socket.on("error", (err: Error) => {
+    console.warn(`[cloud-client udp] socket error: ${err.message}`)
+  })
+  socket.on("message", (msg: Uint8Array) => {
+    onBytes?.(new Uint8Array(msg))
+  })
+  // Bind to any available port so the socket is ready to send.
+  socket.bind(0)
+
+  return {
+    send(bytes: Uint8Array, host: string, port: number): void {
+      socket.send(bytes, 0, bytes.length, port, host, (err?: Error) => {
+        if (err) console.warn(`[cloud-client udp] send failed to ${host}:${port}: ${err.message}`)
+      })
+    },
+    onMessage(cb: (bytes: Uint8Array) => void): void {
+      onBytes = cb
+    },
+    close(): void {
+      try {
+        socket.close()
+      } catch {
+        /* already closed */
+      }
+    },
+  }
+}

package/src/utils/cloudClient/cloudSecureStore.ts

@@ -0,0 +1,28 @@
+/**
+ * MMKV-backed KeyValueStore for @glassly/cloud-client — moved into engine so
+ * engine owns the cloud-v2 credential storage (the v2 refresh token, so a
+ * relaunch does not force a new login). A dedicated MMKV instance keeps
+ * cloud-v2 credentials out of the app's general store. Re-exported through the
+ * host's `@/utils/cloudClient/MmkvSecureStore` shim.
+ *
+ * NOTE: MMKV is not hardware-backed. Before production handling of the
+ * long-lived refresh token, swap this for a Keychain/Keystore-backed store
+ * (react-native-keychain). It is fine for dev / simulator e2e.
+ */
+import {createMMKV, type MMKV} from "react-native-mmkv"
+import type {KeyValueStore} from "@glassly/cloud-client"
+
+const store: MMKV = createMMKV({id: "glassly-cloud-v2"})
+
+export const cloudSecureStore: KeyValueStore = {
+  async get(key: string): Promise<string | null> {
+    return store.getString(key) ?? null
+  },
+  async set(key: string, value: string): Promise<void> {
+    store.set(key, value)
+  },
+  async delete(key: string): Promise<void> {
+    // react-native-mmkv v4's instance method is `remove`, not `delete`.
+    store.remove(key)
+  },
+}

package/src/utils/configuredDevHost.ts

@@ -0,0 +1,17 @@
+import {getConfigValues} from "../runtime/bootstrap"
+
+/**
+ * Explicit Metro / laptop host override used by stale-URL rewrite and launch
+ * failover. One source of truth so AppRegistry and decideDevLaunchRoute stay aligned.
+ */
+export function configuredDevHost(): string | undefined {
+  const explicit = process.env.EXPO_PUBLIC_LOCAL_MINIAPP_HOST
+  if (explicit) {
+    try {
+      return new URL(explicit).hostname
+    } catch {
+      if (/^[\w.-]+$/.test(explicit)) return explicit
+    }
+  }
+  return getConfigValues().devServerHost?.()
+}

package/src/utils/debouncedPatch.ts

@@ -0,0 +1,28 @@
+/**
+ * Merge partial patches and flush once after `delayMs` of quiet time.
+ * Uses global setTimeout so Jest fake timers can advance debounced writes.
+ */
+export function createDebouncedPatchFlusher<T extends Record<string, unknown>>(
+  flush: (patch: T) => void,
+  delayMs: number,
+) {
+  let pending = {} as T
+  let timer: ReturnType<typeof setTimeout> | null = null
+
+  const schedule = (callback: () => void) => {
+    timer = setTimeout(callback, delayMs) as ReturnType<typeof setTimeout>
+  }
+
+  return (patch: Partial<T>) => {
+    pending = {...pending, ...patch}
+    if (timer != null) {
+      clearTimeout(timer)
+    }
+    schedule(() => {
+      timer = null
+      const batch = pending
+      pending = {} as T
+      if (Object.keys(batch).length > 0) flush(batch)
+    })
+  }
+}