@glassly/engine

中文文档
0.4.3发布于 2026/11/17MITTypeScriptCommonJS近 30 天下载 5.5万

Glassly Engine — miniapp registry, WebView bridge, and miniapp store

原始使用文档
文档目录7 节
  1. Installation
  2. Entry points
  3. Public surface
  4. Mentra Live OTA flow
  5. Phone notifications
  6. Imports
  7. Testing

@glassly/engine

Glassly Engine — the on-device miniapp library.

Installation

npm install @glassly/engine

Peer packages: the engine's @glassly/* peer dependencies (crust, cloud-client, cloud-protocol, miniapp) must be available to your package manager. Until every peer is published to npm, consume the engine from this monorepo's workspace (as the example OEM app does).

Module format: the published entry points target React Native / Metro consumers (the react-native exports condition). Loading @glassly/engine from plain Node (require/ESM) is not supported at 0.1.x — the default condition's build output is ESM with extensionless imports and will not resolve under Node's loader.

Entry points

The package exposes its Engine entry points and a supported Bluetooth SDK facade (declared in package.json exports, with the react-native condition pointing at src/ so Metro, tsc and jest resolve live TypeScript source):

  • @glassly/engine (main, src/index.ts) — the OEM-facing surface: the engine namespace (configure/start/stop + typed domain facades), contract/read-model types, and pure helpers host UI renders with (decideReconnect, deriveDisplayState, the useApps-style hooks, OTA policy constants, hardware capability tables, BgTimer). Judgment rule: read models, commands, pure functions and types are main; anything that mutates runtime state or exposes a store/service is not.
  • @glassly/engine/ota (src/react/index.ts) — the complete Mentra Live OTA controller plus its stock full-screen renderer. useMentraLiveOta owns the check, hotspot or Wi-Fi install, APK/MTK/BES progress, reboot, retry, and final verification behavior. MentraLiveOtaFlow renders that same public hook.
  • @glassly/engine/bluetooth-sdk (src/bluetooth-sdk/index.ts) — the complete public Bluetooth SDK surface, re-exported without a wrapper so it has the same singleton identity as @glassly/bluetooth-sdk. The supported SDK react, types, photo-receiver, ota-transport, and debug subpaths are mirrored below this path. The SDK's internal entrypoint is deliberately not exposed.

See cloud/docs/issues/020-glasses-status-boundary/integration-review.md §D for the burn-down plan.

This module owns the pieces of miniapp logic and handling that aren't tied to the rest of the manager app: the WebView message bus, the in-memory running registry, and the JS globals that we inject into every miniapp WebView.

The goal is for all miniapp logic to live here over time. Today the move is incremental — only the self-contained services have moved. Cross-cutting services (LocalMiniappRuntime, MantleManager, Composer install pipeline) still live under mobile/src/ because they reach back into the manager's stores and sockets.

Public surface

import {engine, decideDevLaunchRoute} from "@glassly/engine"
import BluetoothSdk from "@glassly/engine/bluetooth-sdk"
  • decideDevLaunchRoute — pre-flight a dev URL's miniapp.json to decide whether to mount live or take the user to the offline screen.

Mentra Live OTA flow

Bluetooth-only hosts can render the OTA flow without configuring or starting the authenticated cloud connection or miniapp runtime:

import {MentraLiveOtaFlow} from "@glassly/engine/ota"
;<MentraLiveOtaFlow onFinished={() => setShowOta(false)} onOpenWifiSetup={() => setShowWifiSetup(true)} />

The component starts only the glasses-status and OTA projections. A host that already called engine.start() should pass initializeRuntime={false}. Show the flow after a Mentra Live connects. Hosts must provide onOpenWifiSetup; the flow invokes it only for older glasses that cannot provide the OTA hotspot transport.

Apps that need different pages can render the same controller directly:

import {useMentraLiveOta} from "@glassly/engine/ota"

const ota = useMentraLiveOta({onFinished, onOpenWifiSetup})
// Render ota.state.screen and invoke ota.install(), retryInstall(), finish(), etc.

On up_to_date, use ota.state.completedUpdate to distinguish a completed update session from a standalone check. releaseTransition is optional release metadata and is not a completion marker.

Customize presentation only. Engine must remain responsible for OTA ordering, hotspot staging, restart recovery, retries, and verification. The canonical stock and custom integration guide is Update Mentra Live.

Released Engine packages contain a literal immutable OTA manifest URL and SHA-256 generated by coordinated release CI. Modern-glasses manifest selection is developer override, host-app release pin, then Engine release pin. It does not derive a URL from the Bluetooth SDK version or fall through to a glasses-reported or mutable production URL. An unpinned source build has OTA disabled unless an Expo/React Native host explicitly sets EXPO_PUBLIC_ASG_OTA_VERSION_URL; native source hosts use the Bluetooth SDK's debug setOtaVersionUrl surface. Pre-39 glasses retain their separate legacy path because those clients ignore the URL sent by the phone.

Phone notifications

engine.phoneNotifications owns the notification policy for every host. Capture (Android's listener, or glasses that read the phone's stream) is never gated by it. Presentation has one owner per event, from presentationOwner(hostActive):

  • viewer — the engine's notifications page, on connected Glassly CFW glasses
  • firmware — glasses whose firmware presents notifications (hasNativeNotifications); on Android the host hands the event over with uploadToGlasses(event), on iOS the glasses already have it
  • host — the host's own card and speech, while its surface (Notify) runs
  • none — notifications are off, or nothing is there to show them

Miniapp forwarding is not presentation and stays independent.

Four settings drive firmware and viewer alike: notifications_enabled, notifications_popups, notifications_popup_seconds (0 = the presenter's default) and notifications_hold_during_apps, plus the shared notifications_blocklist and the phone-activity gate notifications_ignore_while_active. PhoneNotificationsSync folds them into one GlassesNotificationConfig and pushes it through the Bluetooth SDK on every change and every connection; the pure mapping lives in services/notifications/notificationPolicy.ts. captureAuthorization() tells the settings UI whether the glasses may read the phone's notifications (not_needed where the phone captures); popupSecondsOptions() lists the durations the connected firmware accepts.

notifications_batch_seconds (0 = off) is the viewer's alone: a burst from one app pops up once that app has been quiet that long, at most a minute after its first notification, behind a summary card.

Imports

Inside mobile/modules/engine/src/, use relative paths (./services/..., ../utils/...). The mobile app's @/* alias is not configured here — there is no build-time path rewriter for this module.

Testing

Run the suite with bun run test (from this directory). It executes scripts/test.sh, which runs each test file in its own bun process — do not replace it with a single bun test src.

Why: bun's mock.module patches one process-wide module registry with live ESM bindings, last write wins. Several suites mock the same specifiers ("@glassly/bluetooth-sdk/internal" alone is mocked by audioTestMocks.ts, PhonePhotoCoordinator.test.ts, and others), so in a shared process one file's mock clobbers another's and suites that pass alone fail in the combined run. Per-file processes give every suite an isolated registry.

The same rule applies when writing tests: it is fine to mock.module any specifier your suite needs, but never rely on a mock installed by a different test file — each file must set up everything it imports.

版本与发布记录

@glassly/engine 共发布 559 个版本,首次发布于 2026/08/24;过去 12 个月发布了 559 个版本。

版本发布日期距今
0.4.3latest2026/11/17今天
0.4.3-beta.1211beta2026/11/17今天
0.4.3-dev.1207dev2026/11/17今天
0.4.3-dev.12062026/11/17今天
0.4.3-dev.12052026/11/17今天
0.4.3-dev.12002026/11/17今天

关于 @glassly/engine 的常见问题

@glassly/engine 是什么?

Glassly Engine — miniapp registry, WebView bridge, and miniapp store

如何安装 @glassly/engine?

在项目目录运行 npm install @glassly/engine,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:expo(>=55.0.0)、axios(*)、react(*)、zustand(*)、expo-audio(>=55.0.0)、expo-device(>=55.0.0)、@types/react(*)、expo-battery(>=55.0.0)、react-native(*)、expo-calendar(>=55.0.0)、expo-location(>=55.0.0)、expo-clipboard(>=55.0.0)、expo-constants(>=55.0.0)、expo-file-system(>=55.0.0)、react-native-svg(*)、react-native-udp(*)、expo-modules-core(>=55.0.0)、expo-task-manager(>=55.0.0)、react-native-mmkv(*)、expo-notifications(>=55.0.0)、react-native-share(*)、react-native-localize(*)、react-native-worklets(>=0.7.4 <1)、expo-image-manipulator(>=55.0.0)、react-native-blob-util(*)、react-native-executorch(>=0.11.0 <0.12)、react-native-reanimated(>=4.2.1 <5)、react-native-ble-manager(*)、react-native-permissions(*)、react-native-wifi-reborn(*)、react-native-zip-archive(9.5.3)、react-native-nitro-modules(*)、@dr.pogodin/react-native-fs(*)、react-native-nitro-bg-timer(*)、@craftzdog/react-native-buffer(*)、react-native-safe-area-context(*)、@react-native-community/netinfo(*)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@glassly/engine 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@glassly/engine 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@glassly/engine 可以商用吗?

@glassly/engine 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@glassly/engine 的下载量有多少?

根据 npm 官方下载统计,@glassly/engine 在 2026/10/17 – 2026/11/15 这 30 天内被下载 54,768 次,日均约 1,826 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@glassly/engine 还在维护吗?

最新版本 0.4.3 发布于 2026/11/17(今天);至今共发布 559 个版本,其中过去 12 个月发布了 559 个;首次发布于 2026/08/24。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。