@elizaos/plugin-facewear 2.0.3-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shaw Walters and elizaOS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,10 @@
+# @elizaos/plugin-facewear
+
+Unified facewear integration for XR headsets and smartglasses.
+
+- View Manager pages at `/apps/facewear` and `/apps/smartglasses`.
+- Even Realities G1/G2 whole-headset pairing, display, microphone, side-tap, diagnostics, and bridge Wi-Fi setup.
+- XR session/view hosting for Meta Quest, XReal, Apple Vision Pro, simulator, and other WebXR clients.
+
+Detailed Even Realities implementation notes and hardware proof workflow live in
+`docs/smartglasses.md`.

package/assets/hero-facewear.svg

@@ -0,0 +1,70 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024" width="1024" height="1024" role="img" aria-label="Facewear">
+  <defs>
+    <linearGradient id="bg-facewear" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#152528"/>
+      <stop offset="1" stop-color="#0b1319"/>
+    </linearGradient>
+    <radialGradient id="blobA-facewear" cx="0.5" cy="0.5" r="0.5">
+      <stop offset="0" stop-color="#2fbeda" stop-opacity="0.55"/>
+      <stop offset="1" stop-color="#2fbeda" stop-opacity="0"/>
+    </radialGradient>
+    <radialGradient id="blobB-facewear" cx="0.5" cy="0.5" r="0.5">
+      <stop offset="0" stop-color="#2861c3" stop-opacity="0.5"/>
+      <stop offset="1" stop-color="#2861c3" stop-opacity="0"/>
+    </radialGradient>
+    <radialGradient id="vig-facewear" cx="0.5" cy="0.42" r="0.75">
+      <stop offset="0" stop-color="#000000" stop-opacity="0"/>
+      <stop offset="0.72" stop-color="#000000" stop-opacity="0"/>
+      <stop offset="1" stop-color="#000000" stop-opacity="0.5"/>
+    </radialGradient>
+    <linearGradient id="label-facewear" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#000000" stop-opacity="0"/>
+      <stop offset="1" stop-color="#000000" stop-opacity="0.55"/>
+    </linearGradient>
+    <filter id="soft-facewear" x="-30%" y="-30%" width="160%" height="160%">
+      <feGaussianBlur stdDeviation="46"/>
+    </filter>
+    <filter id="iglow-facewear" x="-40%" y="-40%" width="180%" height="180%">
+      <feDropShadow dx="0" dy="0" stdDeviation="14" flood-color="#45d1ed" flood-opacity="0.45"/>
+    </filter>
+  </defs>
+
+  <rect width="1024" height="1024" fill="url(#bg-facewear)"/>
+
+  <g opacity="0.9">
+    <circle cx="232" cy="220" r="300" fill="url(#blobA-facewear)" filter="url(#soft-facewear)"/>
+    <circle cx="840" cy="800" r="340" fill="url(#blobB-facewear)" filter="url(#soft-facewear)"/>
+  </g>
+
+  <g stroke="#d7e7ea" stroke-width="1.4" opacity="0.06">
+    <line x1="0" y1="256" x2="1024" y2="256"/>
+    <line x1="0" y1="512" x2="1024" y2="512"/>
+    <line x1="0" y1="768" x2="1024" y2="768"/>
+    <line x1="256" y1="0" x2="256" y2="1024"/>
+    <line x1="512" y1="0" x2="512" y2="1024"/>
+    <line x1="768" y1="0" x2="768" y2="1024"/>
+  </g>
+
+  <g opacity="0.5">
+    <path d="M120 470 A 400 400 0 0 1 904 470" fill="none" stroke="#45d1ed" stroke-width="3" opacity="0.35"/>
+  </g>
+
+  <g transform="translate(512 432)" filter="url(#iglow-facewear)"
+     color="#d7e7ea" stroke="#d7e7ea" stroke-width="20"
+     stroke-linecap="round" stroke-linejoin="round" fill="none">
+    <path d="M-140 30 V-10 A140 140 0 0 1 140 -10 V30"/>
+    <rect x="-160" y="26" width="58" height="110" rx="26" fill="currentColor" stroke-width="0"/>
+    <rect x="102" y="26" width="58" height="110" rx="26" fill="currentColor" stroke-width="0"/>
+    <rect x="-160" y="26" width="58" height="110" rx="26"/>
+    <rect x="102" y="26" width="58" height="110" rx="26"/>
+  </g>
+
+  <rect x="0" y="784" width="1024" height="240" fill="url(#label-facewear)"/>
+  <text x="512" y="892" text-anchor="middle"
+        font-family="system-ui, -apple-system, Segoe UI, Roboto, sans-serif"
+        font-size="76" font-weight="600" letter-spacing="0.5"
+        fill="#d7e7ea">Facewear</text>
+  <rect x="460" y="924" width="104" height="6" rx="3" fill="#45d1ed"/>
+
+  <rect width="1024" height="1024" fill="url(#vig-facewear)"/>
+</svg>

package/assets/hero-smartglasses.svg

@@ -0,0 +1,70 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024" width="1024" height="1024" role="img" aria-label="Smartglasses">
+  <defs>
+    <linearGradient id="bg-smartglasses" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#281528"/>
+      <stop offset="1" stop-color="#190b16"/>
+    </linearGradient>
+    <radialGradient id="blobA-smartglasses" cx="0.5" cy="0.5" r="0.5">
+      <stop offset="0" stop-color="#da2fda" stop-opacity="0.55"/>
+      <stop offset="1" stop-color="#da2fda" stop-opacity="0"/>
+    </radialGradient>
+    <radialGradient id="blobB-smartglasses" cx="0.5" cy="0.5" r="0.5">
+      <stop offset="0" stop-color="#c3287a" stop-opacity="0.5"/>
+      <stop offset="1" stop-color="#c3287a" stop-opacity="0"/>
+    </radialGradient>
+    <radialGradient id="vig-smartglasses" cx="0.5" cy="0.42" r="0.75">
+      <stop offset="0" stop-color="#000000" stop-opacity="0"/>
+      <stop offset="0.72" stop-color="#000000" stop-opacity="0"/>
+      <stop offset="1" stop-color="#000000" stop-opacity="0.5"/>
+    </radialGradient>
+    <linearGradient id="label-smartglasses" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#000000" stop-opacity="0"/>
+      <stop offset="1" stop-color="#000000" stop-opacity="0.55"/>
+    </linearGradient>
+    <filter id="soft-smartglasses" x="-30%" y="-30%" width="160%" height="160%">
+      <feGaussianBlur stdDeviation="46"/>
+    </filter>
+    <filter id="iglow-smartglasses" x="-40%" y="-40%" width="180%" height="180%">
+      <feDropShadow dx="0" dy="0" stdDeviation="14" flood-color="#ed45ed" flood-opacity="0.45"/>
+    </filter>
+  </defs>
+
+  <rect width="1024" height="1024" fill="url(#bg-smartglasses)"/>
+
+  <g opacity="0.9">
+    <circle cx="232" cy="220" r="300" fill="url(#blobA-smartglasses)" filter="url(#soft-smartglasses)"/>
+    <circle cx="840" cy="800" r="340" fill="url(#blobB-smartglasses)" filter="url(#soft-smartglasses)"/>
+  </g>
+
+  <g stroke="#ead7ea" stroke-width="1.4" opacity="0.06">
+    <line x1="0" y1="256" x2="1024" y2="256"/>
+    <line x1="0" y1="512" x2="1024" y2="512"/>
+    <line x1="0" y1="768" x2="1024" y2="768"/>
+    <line x1="256" y1="0" x2="256" y2="1024"/>
+    <line x1="512" y1="0" x2="512" y2="1024"/>
+    <line x1="768" y1="0" x2="768" y2="1024"/>
+  </g>
+
+  <g opacity="0.5">
+    <path d="M120 470 A 400 400 0 0 1 904 470" fill="none" stroke="#ed45ed" stroke-width="3" opacity="0.35"/>
+  </g>
+
+  <g transform="translate(512 432)" filter="url(#iglow-smartglasses)"
+     color="#ead7ea" stroke="#ead7ea" stroke-width="20"
+     stroke-linecap="round" stroke-linejoin="round" fill="none">
+    <circle cx="-86" cy="20" r="68"/>
+    <circle cx="86" cy="20" r="68"/>
+    <path d="M-18 20 Q0 -2 18 20"/>
+    <line x1="-154" y1="-12" x2="-180" y2="-44"/>
+    <line x1="154" y1="-12" x2="180" y2="-44"/>
+  </g>
+
+  <rect x="0" y="784" width="1024" height="240" fill="url(#label-smartglasses)"/>
+  <text x="512" y="892" text-anchor="middle"
+        font-family="system-ui, -apple-system, Segoe UI, Roboto, sans-serif"
+        font-size="76" font-weight="600" letter-spacing="0.5"
+        fill="#ead7ea">Smartglasses</text>
+  <rect x="460" y="924" width="104" height="6" rx="3" fill="#ed45ed"/>
+
+  <rect width="1024" height="1024" fill="url(#vig-smartglasses)"/>
+</svg>

package/docs/smartglasses-completion-audit.md

@@ -0,0 +1,118 @@
+# Smartglasses Completion Audit
+
+This audit tracks the requested Even Realities smartglasses objective against
+current repository evidence. It is intentionally stricter than the software
+test suite: the goal is not complete until real hardware evidence proves the
+physical microphone and tap path.
+
+## Requirements
+
+| Requirement | Evidence | Status |
+| --- | --- | --- |
+| Pull the 12 requested upstream repositories into a gitignored research folder. | `.gitignore` ignores `research/even-realities/`; `docs/smartglasses-upstream-audit.md` lists all 12 local checkouts and reviewed files. | Complete |
+| Review upstream command, display, BLE, bridge, and simulator behavior. | `docs/smartglasses-upstream-audit.md` maps each upstream source to implemented files and tests. | Complete |
+| Implement `plugins/plugin-facewear`. | `src/index.ts`, `src/protocol/smartglasses.ts`, `src/services/smartglasses-service.ts`, `src/actions/*.ts`, `src/providers/smartglasses-status.ts`, and `src/transport/*.ts`. | Complete |
+| Stream and format display text properly. | `src/protocol/smartglasses.ts` implements G1 glyph-width wrapping, page/chunk encoding, Even AI and Text Show modes, and RSVP display; covered by `src/__tests__/protocol-smartglasses.test.ts` and example smokes. | Complete |
+| Receive microphone data. | Direct G1 LC3 packets and bridge PCM/LC3/transcript events are handled in `SmartglassesService` and transports; covered by service, bridge, package, runtime, and parser tests. | Software-complete |
+| Side tap enables/disables microphone input. | `SmartglassesService` maps single tap/long press to right-lens mic enable and double tap/stop recording to mic disable; covered by service and example tests. | Software-complete |
+| Connect the whole headset, not a single lens. | Web Bluetooth, Noble, Bleak, bridge, and View Manager flows require left and right lens records; validators reject missing lens evidence. Web Bluetooth rejects visible side mismatches and duplicate device IDs during picker flow so a wrong or repeated lens selection cannot satisfy whole-headset pairing. Public Web Bluetooth and Noble whole-headset `connect()` calls clean up partial connections on failure. Native bridge status exposes both virtual lens records when the bridge is connected. | Software-complete |
+| Provide an Eliza View Manager view for connect/test/setup. | `src/index.ts` declares Facewear and Smartglasses views and app nav tabs; `src/register.ts` registers `/apps/facewear` and `/apps/smartglasses`; `src/ui/SmartglassesView.tsx` implements connect, diagnostics, Wi-Fi bridge, and guided validation; exported diagnostics now include pairing `scanDiagnosis`, `physicalBlocker`, setup hint, next action, observed serial number, packet writes, and audio chunk metadata; `packages/app-core/src/registry/entries/plugins/facewear.json` launches the internal tab and advertises whole-headset pairing, side-tap mic control, and Wi-Fi provisioning; `bun run --cwd plugins/plugin-facewear verify:app` covers app registry and registration tests. | Complete |
+| Support iOS, Android, desktop setup paths where possible. | View Manager setup copy and transports cover native bridge, Web Bluetooth, Noble/Bleak, and EvenHub/Mentra bridge APIs. Bridge-backed Wi-Fi now supports scan/status/configure plus Mentra-style native `requestWifiSetup(reason)` setup prompts for hosts that expose a setup flow instead of direct credentials. The Even Realities Android companion now scans for `_L_` and `_R_` lenses, connects the whole headset, uses current G1 command framing, and forwards `g1_raw`/`mic_lc3` events to the agent. Direct G1 BLE Wi-Fi provisioning remains unverified upstream and is bridge-only. | Complete with documented Wi-Fi limit |
+| Add an example in `packages/examples`. | `packages/examples/smartglasses` contains package/runtime/simulator/browser/Noble/Bleak smokes, validation helpers, and docs. | Complete |
+| Test with Eliza end to end. | `npm run verify:smartglasses-software` passed on 2026-05-20 after the Facewear build scripts were hardened to use the workspace `tsup` binary for `build:js` and stable `vite@7.2.7` for `build:views`. The root verifier now runs Facewear plugin lint/typecheck/test/app-registration gates, then the full smartglasses example software gate, repairs any Bun lock churn back to `@elizaos/plugin-facewear`, and reruns the consolidation, Even research self-test, Even research audit, and completion self-test guards before the completion gate is evaluated. `bun run --cwd plugins/plugin-facewear test` passed with all 20 plugin test files / 185 tests, including view bundle build and CLI emulator build before Vitest. `bun run --cwd packages/examples/smartglasses verify:software` passed end to end: example lint, Bun tests, protocol tests, Bleak parser test, hardware doctor syntax check, dependency-aware Turbo typecheck, public package smoke, AgentRuntime smoke with setup-friendly aliases, and simulator display/tap automation. `bun run --cwd packages/examples/smartglasses smoke:package` covers 92 mock whole-headset writes, including start AI, clear display, exit dashboard/function, side-specific page-up/page-down, silent mode, brightness, head-up angle, wear detection, app allowlist, notification, BMP transfer, Wi-Fi setup, navigation, translation, notes, display, mic, audio, transcript, and status provider assertions. The same software gate includes `hardware:test-doctor`, a non-hardware syntax check for the macOS Bluetooth/headset diagnostic, and its `typecheck` script builds Facewear dependencies through Turbo before invoking `tsc` so missing workspace declaration artifacts cannot hide dependency-resolution failures. `verify:app` passed with the Facewear app registration tests. The focused action tests prove display/microphone actions fail cleanly without transport, the control action returns structured operation results for invalid parameters and generated commands, package smoke verifies public action failure behavior plus G1 setup/navigation packet counts, and AgentRuntime smoke verifies display/mic return values, invalid control failure payloads, setup-friendly alias canonicalization, alias Wi-Fi requests, alias app allowlist packets, alias QuickNote packets, and previous/next-page alias packet routing. The standalone consolidation guard passed after lock repair and scanned 34,567 files across `packages`, `plugins`, `apps`, and `scripts`; the stale `plugin-smartglasses` spot check was empty after the repair, and the completion gate now also checks critical lockfile/manifest paths plus the stable Facewear build scripts. Earlier focused passes also covered Web Bluetooth side-mismatch/duplicate-device hardening, whole-headset partial-connect cleanup, bridge lens status reporting, View Manager diagnostics, Wi-Fi setup prompts, voice-note list/fetch/delete/delete-all, battery status, dashboard positioning, native Android bridge routing, package/runtime/simulator smokes, hardware doctor paired-but-not-advertising diagnosis coverage, ordered tap-to-mic hardware validator requirements, View Manager ordered tap-to-mic report requirements, and View Manager display packet sequencing. | Software-complete |
+| Prove physical hardware tap and microphone path. | Earlier `/tmp/smartglasses-hardware-report-latest.json` from 2026-05-20 06:38:56Z connected both lenses and observed serial `S110LABC040019`, 17 writes, 14 parsed events, init/display/settings responses, heartbeat packets, and a right-lens mic-disable response, but no physical-state packet, taps, right-lens mic-enable write, or audio. A Noble attempt from 2026-05-20 07:26:42Z wrote a fresh report but failed before scanning because the native Noble binding is unavailable for the current macOS ARM64 Node/Bun ABI, reported as `physicalBlocker: "transport_unavailable"`. The freshest Bleak attempt from 2026-05-20 10:39:00Z found 30 BLE devices but zero Even/G1 name matches and zero Nordic UART-service candidates, so it reports `physicalBlocker: "headset_not_found"` with `status.connected: false`, no serial, no writes, no taps, and no audio. The hardware doctor confirms macOS Bluetooth is on and both lenses are paired (`Even G1_51_L_138507` and `Even G1_51_R_8C0CDF`) but listed under "Not Connected", so the remaining blocker is physical advertising/availability rather than software wiring. | Blocked on physical headset advertising/availability |
+
+## Hardware Completion Gate
+
+Completion requires a hardware report that passes:
+
+```bash
+npm run smartglasses:hardware:validate
+```
+
+For the final physical attempt, the latest-report proof helpers run the smoke,
+print the status summary even on failure, then invoke the validator:
+
+```bash
+npm run smartglasses:hardware:prove
+```
+
+```bash
+npm run smartglasses:hardware:prove:noble
+```
+
+The report must include:
+
+- left and right lens connection records
+- final service status with both lenses connected
+- connection-ready/init writes
+- display writes
+- serial request and observed serial response
+- settings writes
+- `wearing` physical state
+- single-tap or long-press mic-enable event followed by a right-lens `0x0E 0x01` mic-enable write
+- non-empty right-lens microphone audio
+- double-tap or stop-recording mic-disable event followed by a right-lens `0x0E 0x00` mic-disable write
+- final service status audio counters
+
+For upstream research evidence, use the standalone Node guard:
+
+```bash
+npm run audit:even-research
+npm run audit:even-research:self-test
+```
+
+For a single completion gate that also inspects the latest physical report, use:
+
+```bash
+npm run audit:smartglasses-completion
+npm run audit:smartglasses-completion:self-test
+```
+
+The current latest report from 2026-05-20 10:39:00Z refreshed the physical
+proof attempt, but it now fails the completion gate with `reportStale`.
+CoreBluetooth was scanning and discovered 30 BLE devices, but
+zero matched Even/G1 names and zero advertised the G1 UART service UUID. It
+therefore did not discover either lens, and `npm run smartglasses:hardware:status` summarizes
+it with `wholeHeadsetConnected: false`, `wearingReady: false`, and
+`physicalBlocker: "headset_not_found"`. The completion gate hardware summary
+now also includes `pairedG1Devices`, `pairedG1DeviceCount`,
+`pairedWholeHeadset`, and `bluetoothAdapter`; for older latest reports that
+predate those fields, it augments the summary from the live macOS Bluetooth
+inventory. The latest-report status and validator summaries also echo those
+fields once the Bleak proof report contains them, and include
+`bluetoothPreflightSource` to distinguish report data from local fallback data.
+macOS Bluetooth system state still lists
+both G1 lenses as paired (`Even G1_51_L_138507` and `Even G1_51_R_8C0CDF`), but
+they are under "Not Connected"; `npm run smartglasses:hardware:doctor` reports this paired-but-not-
+advertising state directly. A Noble report from
+2026-05-20 07:26:42Z failed before scanning because the Noble native binding is
+unavailable for the current runtime and reported
+`physicalBlocker: "transport_unavailable"`. An earlier 2026-05-20 06:38:56Z
+Bleak run
+proved direct BLE connectivity and command/response coverage for both lenses
+(`Even G1_51_L_138507` and `Even G1_51_R_8C0CDF`) and serial
+`S110LABC040019`, but it is stale and did not observe `wearing`, tap events,
+a right-lens mic-enable write, or right-lens audio. Remove both lenses from the
+charging base, keep them near this device, wear the glasses until the report
+shows `physical: "wearing"`, then perform single tap, speech, and double tap.
+Use the watch helper for a longer discovery and worn-state window:
+
+```bash
+npm run smartglasses:hardware:prove
+npm run smartglasses:hardware:validate
+```
+
+```bash
+npm run smartglasses:hardware:prove:watch
+```
+
+or the full watch proof wrapper:
+
+```bash
+npm run smartglasses:hardware:prove:watch
+```
+
+```bash
+npm run smartglasses:hardware:prove:noble:watch
+```

package/docs/smartglasses-upstream-audit.md

@@ -0,0 +1,127 @@
+# Smartglasses Upstream Audit
+
+This plugin was built from the gitignored research checkouts under
+`research/even-realities/`. The repository root `.gitignore` ignores that
+checkout folder, so these upstream repos remain local evidence and are not part
+of the committed package.
+
+## Repository Coverage
+
+| Requested source | Local checkout | Primary files reviewed | Capability carried into `@elizaos/plugin-facewear` |
+| --- | --- | --- | --- |
+| `fabioglimb/even-toolkit` | `research/even-realities/even-toolkit` | `glasses/bridge.ts`, `glasses/glass-format.ts`, `glasses/paginate-text.ts`, `glasses/gestures.ts`, `stt/sources/glass-bridge.ts`, `stt/audio/pcm-utils.ts` | G2/EvenHub bridge display, event, and PCM audio assumptions; text pagination and gesture normalization informed `src/transport/even-bridge.ts` and `src/protocol/smartglasses.ts`. |
+| `BxNxM/even-dev` | `research/even-realities/even-dev` | `apps/_shared/even-events.ts`, `apps/_shared/autoconnect.ts`, `apps/base_app/src/base-template.ts`, `README.md` | Simulator bridge lifecycle, `sendStartUpPage`, app bridge readiness, and click/double-click input expectations used by `packages/examples/smartglasses/evenhub-smoke.ts` and `simulator-automation-smoke.ts`. |
+| `emingenc/even_glasses` | `research/even-realities/even_glasses` | `even_glasses/models.py`, `even_glasses/utils.py`, `even_glasses/commands.py`, `even_glasses/notification_handlers.py`, `even_glasses/bluetooth_manager.py`, `even_glasses/README.md` | G1 command constants, display packet framing, RSVP, mic control, mic response parsing, LC3 notification parsing, heartbeat, dashboard/settings, BMP, and notification handling in `src/protocol/smartglasses.ts` and `src/services/smartglasses-service.ts`. |
+| `binarythinktank/eveng1_python_sdk` | `research/even-realities/eveng1_python_sdk` | `connector/bluetooth_manager.py`, `services/commands.py`, `services/notification_handlers.py`, `utils/message_utils.py`, `examples/*.py` | Nordic UART UUIDs, broad scan plus `_L_`/`_R_` lens matching, heartbeat bytes, LC3 mic chunks, and display packet shape used by `src/transport/noble.ts`, `src/transport/web-bluetooth.ts`, and protocol tests. |
+| `meyskens/fahrplan` | `research/even-realities/fahrplan` | `lib/bluetooth_manager.dart`, `lib/services/*`, `lib/features/*`, `README.md` | Practical G1 app coverage for dashboard/checklist display, notification mirroring, navigation, translation, QuickNote/voice-note list/fetch/delete/delete-all packets, and live transcription expectations reflected in `src/actions/facewear-control.ts`, `src/protocol/smartglasses.ts`, and package smoke coverage. |
+| `nickustinov/weather-even-g2` | `research/even-realities/weather-even-g2` | `g2/index.ts`, `g2/events.ts`, `g2/ui.tsx`, `_shared/*`, `README.md` | G2 captured-event behavior, list/text/system event handling, and zero-value index edge cases used by EvenHub event normalization. |
+| `jappyjan/even-realities` | `research/even-realities/even-realities` | `packages/*`, `apps/*`, SDK/app examples | EvenHub SDK wrapper patterns for page startup, rebuild, and listener registration used by `EvenBridgeTransport`. |
+| `emingenc/g1_flutter_blue_plus` | `research/even-realities/g1_flutter_blue_plus` | `lib/services/commands.dart`, `lib/services/reciever.dart`, `lib/services/bluetooth_manager.dart`, `lib/main.dart` | Flutter BLE discovery and direct G1 receiver behavior cross-checked command constants, `_L_`/`_R_` pairing, `0xF5` taps, `0x0E` mic responses, and `0xF1` voice data. |
+| `nickustinov/tesla-even-g2` | `research/even-realities/tesla-even-g2` | `g2/events.ts`, `g2/renderer.ts`, `g2/navigation.ts`, `g2/ui.tsx`, `README.md` | G2 bridge event normalization for nested event keys, click/double-click/scroll fallback, and dashboard/menu rendering expectations used by `src/transport/even-bridge.ts` and simulator smoke. |
+| `galfaroth/awesome-even-realities-g1` | `research/even-realities/awesome-even-realities-g1` | `README.md` | Ecosystem cross-check for the G1 SDK/demo sources and command families. |
+| `even-realities/EvenDemoApp` | `research/even-realities/EvenDemoApp` | `lib/ble_manager.dart`, `lib/services/ble.dart`, `lib/services/evenai.dart`, `lib/services/features_services.dart`, `lib/controllers/bmp_update_manager.dart`, `ios/Runner/BluetoothManager.swift`, `android/app/src/main/kotlin/com/example/demo_ai_even/bluetooth/BleManager.kt` | Official demo behavior for right-lens mic, LC3 audio, text streaming, native exit, serial request, app whitelist, iOS same-init (`0x4D 0x01` to both lenses), Android same-init (`0xF4 0x01` to both lenses), notification flows, and BMP transfer. |
+| `Mentra-Community/MentraOS` | `research/even-realities/MentraOS` | `cloud/docs/sdk/display-layouts.mdx`, `cloud/docs/cloud-architecture/managers/audio-manager.mdx`, `cloud/docs/cloud-architecture/managers/microphone-manager.mdx`, `cloud/docs/cloud-architecture/managers/transcription-manager.mdx`, `sdk/*`, `mobile/*` | Bridge/native display APIs, `setMicState`, `mic_pcm`/`mic_lc3`, local transcription streams, display width/glyph constraints, G1 dashboard height/depth position packets, `0x2C 0x01` battery status request/response parsing, and hardware validation requirements used by `src/transport/even-bridge.ts`, display wrapping, transcript events, dashboard position controls, battery status, and hardware smoke evidence. |
+
+## Implemented Surface
+
+The upstream review maps to the following local implementation:
+
+- Direct G1 BLE packet protocol and parsing: `src/protocol/smartglasses.ts`
+- Eliza service lifecycle, display streaming, mic control, tap handling,
+  audio/transcript events, heartbeat, and settings: `src/services/smartglasses-service.ts`
+- Eliza actions/providers: `src/actions/*.ts`,
+  `src/providers/smartglasses-status.ts`
+- Direct BLE transports: `src/transport/web-bluetooth.ts`, `src/transport/noble.ts`
+- EvenHub/G2/Mentra bridge transport: `src/transport/even-bridge.ts`
+- Mock transport for deterministic Eliza tests: `src/transport/mock.ts`
+- Physical validation harnesses:
+  - `packages/examples/smartglasses/hardware-smoke.ts`
+  - `packages/examples/smartglasses/noble-hardware-smoke.ts`
+  - `packages/examples/smartglasses/hardware-evidence.ts`
+- Simulator validation harness:
+  - `packages/examples/smartglasses/evenhub-smoke.ts`
+  - `packages/examples/smartglasses/simulator-automation-smoke.ts`
+
+## Test Coverage
+
+The implementation is covered by:
+
+- `src/__tests__/protocol-smartglasses.test.ts`: packet encoding, pixel-aware display
+  wrapping, display chunking, mic commands, tap/audio/serial parsing, settings,
+  dashboard position/content, navigation, translation, notifications, notes, voice-note
+  list/fetch/delete/delete-all, BMP, heartbeat, init modes, and app whitelist/setup.
+- `src/__tests__/facewear-service.test.ts`: Eliza service display streaming, RSVP,
+  sequence counters, mic toggle state, side tap behavior, long press/stop
+  recording, raw and decoded audio paths, transcript events, startup auto-init,
+  heartbeat loop, pre-connected transport listener attachment, and transport
+  preference.
+- `src/__tests__/functional-parity.test.ts`: exported action/provider/service wiring.
+- `src/__tests__/even-bridge.test.ts`: G2/EvenHub/Mentra bridge rendering,
+  audio, transcription, and input normalization.
+- `src/__tests__/web-bluetooth.test.ts` and `src/__tests__/noble.test.ts`:
+  direct BLE lens pairing, UART subscription/write behavior, and notification
+  parsing.
+- `packages/examples/smartglasses/smartglasses.test.ts`: package example packet
+  path plus physical evidence helper requirements.
+- `packages/examples/smartglasses/package-smoke.ts`: public package export,
+  Eliza event emission, status provider, and action path.
+
+## Remaining Physical Gate
+
+The code includes physical G1 validation paths and direct BLE smoke coverage.
+An earlier report from `2026-05-20T06:38:56Z` reached both lenses on the
+plugged-in headset and proved whole-headset direct BLE connectivity, serial
+response, init/display/settings responses, heartbeats, and right-lens
+mic-disable response for serial `S110LABC040019`. It did not complete the
+physical gate because that run did not observe a physical-state packet with
+`wearing`, so tap and microphone audio evidence could not be observed. The
+freshest short Bleak attempt from `2026-05-20T07:42:31Z` did not discover
+either lens. CoreBluetooth did discover 36 BLE devices, but zero matched
+Even/G1 names and zero advertised the G1 UART service UUID. Both status and
+validator output report
+`physicalBlocker: "headset_not_found"` for that case, which means the next
+Bleak attempt needs both lenses out of the charging base, nearby, advertising,
+and worn before the tap/audio validation window. The Bleak raw report also
+records `status.connected: false`, service UUID/manufacturer scan inventory,
+and the same blocker-aware setup hint when no lenses are found. A Noble attempt from
+`2026-05-20T07:26:42Z` failed before scanning because the native Noble BLE
+binding is unavailable for the current macOS ARM64 Node/Bun ABI; that path now
+writes a report and reports `physicalBlocker: "transport_unavailable"` instead
+of silently leaving an older hardware report in place.
+
+Use the root helpers for the next hardware proof attempt:
+
+```bash
+npm run smartglasses:hardware:prove:watch
+npm run smartglasses:hardware:status
+npm run smartglasses:hardware:validate
+```
+
+The lower-level package commands remain available when debugging inside the
+example:
+
+```bash
+bun run --cwd packages/examples/smartglasses hardware:prove:bleak
+bun run --cwd packages/examples/smartglasses hardware:status-latest
+bun run --cwd packages/examples/smartglasses hardware:validate-latest
+```
+
+The Noble/Web Bluetooth paths are still available for adapter/browser-specific
+checks:
+
+```bash
+npm run smartglasses:hardware:prove:noble
+npm run smartglasses:dev:hardware
+```
+
+The required evidence checklist is enforced by
+`packages/examples/smartglasses/hardware-evidence.ts`: connected lenses,
+connection-ready/init writes, display packets, serial request and response,
+settings writes, `wearing` physical state, single-tap mic enable, right-lens
+mic-enable write, microphone audio, double-tap mic disable, and right-lens
+mic-disable write.
+
+The Bleak/CoreBluetooth proof report also captures macOS Bluetooth preflight
+metadata (`bluetoothAdapter` and `pairedG1Devices`) before scanning. That keeps
+the latest JSON artifact self-contained when diagnosing the paired-but-not-
+advertising state that blocks the physical tap/audio gate.

package/docs/smartglasses.md

@@ -0,0 +1,429 @@
+# @elizaos/plugin-facewear
+
+Even Realities G1/G2 smartglasses integration for ElizaOS.
+
+## Implemented Surfaces
+
+- View Manager page at `/apps/smartglasses` for whole-headset pairing,
+  diagnostics, platform setup guidance, report export, and bridge-backed Wi-Fi
+  scan/configuration/setup prompts when a native bridge exposes those APIs.
+  The page uses a native Even/Mentra bridge when present for iOS/Android-style
+  hosts and falls back to direct Web Bluetooth for desktop browsers.
+- G1 UART protocol constants for Nordic UART service:
+  - service `6E400001-B5A3-F393-E0A9-E50E24DCCA9E`
+  - TX `6E400002-B5A3-F393-E0A9-E50E24DCCA9E`
+  - RX `6E400003-B5A3-F393-E0A9-E50E24DCCA9E`
+- Display text streaming with G1 `0x4E` packets, five-line page wrapping using the hardware-derived G1 glyph width profile, official 191-byte payload chunking, Even AI in-progress/completion status (`0x31`/`0x40`), and direct Text Show status (`0x71`).
+- RSVP word-group display using the same wrapped G1 display path for rapid reading-style presentation.
+- Microphone open/close with G1 `0x0E` packets and right-lens mic routing.
+- Direct G1 `0xF1` mic data is exposed as raw LC3 audio (`audioData`, `audioEncoding: "lc3"`) with packet sequence tracking and gap counts. A native/platform LC3 decoder can be injected with `setAudioDecoder` or `setSmartglassesAudioDecoderForRuntime` to convert those chunks into PCM16 for `onAudio` callbacks. EvenHub/G2 bridge `audioEvent.audioPcm` data and MentraOS `mic_pcm` events are exposed as 16 kHz PCM16 and converted to float samples automatically; MentraOS `mic_lc3` events are preserved as LC3.
+- MentraOS/G2 `local_transcription` and `transcription:*` bridge events are normalized into `SMARTGLASSES_TRANSCRIPT` runtime events and `onTranscript` callbacks, so host STT output from the glasses microphone reaches Eliza.
+- Side tap handling:
+  - single tap enables mic
+  - double tap disables mic
+  - long press / Even AI activation (`0xF5 0x17`) enables mic
+  - Even AI recording stop (`0xF5 0x18`) disables mic
+- EvenHub simulator click/double-click events are normalized to the same tap labels, so simulator input exercises the same microphone toggle path.
+- EvenHub/G2 scroll-up and scroll-down events are normalized and routed to the same manual page controls as direct G1 page-up/page-down.
+- Incoming hardware event parsing for interaction, physical, battery, device, init, display-result, notification, dashboard, serial-number response, heartbeat, mic response, mic data, response, and error categories.
+- Runtime events:
+  - `SMARTGLASSES_EVENT`
+  - `SMARTGLASSES_AUDIO`
+  - `SMARTGLASSES_TRANSCRIPT`
+- Managed heartbeat loop for G1 connection maintenance, matching the upstream SDK pattern of periodic `0x25` packets.
+- G1 controls:
+  - clear display
+  - start AI, connection-ready init (`0x4D 0x01` left / `0xF4 0x01` right by default, official EvenDemoApp iOS same-init `0x4D 0x01` to both lenses, or EvenDemoApp Android `0xF4 0x01` to both lenses), exit to dashboard, native function exit (`0x18`), serial request/response (`0x34`), app whitelist (`0x04`), raw packet writes, one-shot heartbeat, and managed heartbeat start/stop
+  - manual-mode page up/down (`0xF5 0x01`, left for page-up and right for page-down)
+  - silent mode
+  - brightness
+  - dashboard show/hide, legacy position, and official height/depth positioning
+  - dashboard layout, calendar item, time/weather, and setup payload packets from the Fahrplan G1 dashboard model
+  - navigation init, direction text, primary/secondary image, poller, and end packets
+  - translation setup/start/language/original/translated text overlay packets
+  - head-up angle
+  - wear detection
+  - notes add/delete
+  - QuickNote voice-note list parsing plus voice-note audio fetch/delete subcommands
+  - notifications, including notification ID packet headers
+  - 1-bit BMP generation/transfer framing with CRC for native `576x136` image payloads
+- Dual-lens writes are serialized left-then-right for commands that target both lenses, matching the native G1 guidance. Microphone activation remains right-lens only.
+- Transports:
+  - `EvenBridgeTransport` for EvenHub/G2-style bridge hosts, including simulator-style `sendStartUpPage`, `onEvenHubEvent`, and `audioControl`, plus MentraOS Bluetooth SDK `displayText`, `clearDisplay`, `setMicState`, `mic_pcm`, `mic_lc3`, and local transcription events
+  - `WebBluetoothG1Transport` for direct browser BLE
+  - `NobleG1Transport` for optional Node/Bun BLE through `@abandonware/noble`
+  - `MockSmartglassesTransport` for tests and examples
+
+Direct G1 BLE does not expose a verified Wi-Fi provisioning command in the
+reviewed upstreams. Wi-Fi scan/configuration is therefore available only through
+native/bridge APIs such as Mentra/ASG bridge surfaces.
+
+## Eliza Actions
+
+- `SMARTGLASSES_DISPLAY_TEXT`
+- `SMARTGLASSES_MICROPHONE`
+- `SMARTGLASSES_CONTROL`
+- `SMARTGLASSES_STATUS`
+
+`SMARTGLASSES_DISPLAY_TEXT` accepts plain text or JSON:
+
+```json
+{ "text": "Show this on the glasses", "mode": "text" }
+```
+
+Use `mode: "ai"` for the default Even AI streaming/completion display path or
+`mode: "text"` for the direct Text Show path documented by EvenDemoApp. JSON
+input can also include `pageHoldMs` between pages and `completionDelayMs`
+before sending the final completion frame:
+
+```json
+{ "text": "Paced multi-page display", "mode": "ai", "pageHoldMs": 1200, "completionDelayMs": 250 }
+```
+
+`SMARTGLASSES_CONTROL` accepts JSON such as:
+
+```json
+{ "op": "brightness", "level": 10, "auto": true }
+```
+
+Supported `op` values: `connect`, `disconnect`, `clear`, `exit_dashboard`, `exit_function`, `start_ai`, `connection_ready`, `page_up`, `page_down`, `rsvp_text`, `heartbeat`, `heartbeat_start`, `heartbeat_stop`, `battery_status`, `raw`, `get_serial`, `app_whitelist`, `g1_setup`, `silent_mode`, `brightness`, `wifi_scan`, `wifi_status`, `wifi_configure`, `wifi_setup`, `dashboard`, `dashboard_position`, `dashboard_layout`, `dashboard_calendar`, `dashboard_time_weather`, `headup_angle`, `wear_detection`, `navigation_start`, `navigation_directions`, `navigation_primary_image`, `navigation_secondary_image`, `navigation_poller`, `navigation_end`, `translate_setup`, `translate_start`, `translate_languages`, `translate_original`, `translate_translated`, `note_add`, `note_delete`, `voice_note_list`, `voice_note_fetch`, `voice_note_delete`, `voice_note_delete_all`, `notification`, `bmp_image`.
+
+`connect` pairs or reconnects the whole headset through the configured
+transport and sends connection-ready init packets by default. Aliases include
+`pair`, `pair_headset`, and `connect_headset`. Pass `init: false` to reconnect
+without sending init packets:
+
+```json
+{ "op": "connect", "init": false }
+```
+
+`disconnect` closes the active headset transport. Aliases include `unpair` and
+`disconnect_headset`.
+
+Bridge-backed Wi-Fi actions are available only when the active transport
+exposes native phone/headset setup APIs:
+
+```json
+{ "op": "wifi_scan" }
+```
+
+```json
+{ "op": "wifi_configure", "ssid": "Home Wi-Fi", "password": "secret" }
+```
+
+Mentra-style SDK hosts can expose a native setup prompt instead of direct
+credential APIs:
+
+```json
+{ "op": "wifi_setup", "reason": "Eliza needs headset Wi-Fi" }
+```
+
+`heartbeat_start` accepts optional `intervalMs` and `immediate` fields. By
+default it sends a heartbeat immediately and then every 8 seconds until
+`heartbeat_stop`, service disconnect, or service stop.
+
+`rsvp_text` accepts `text`, optional `wordsPerGroup`, `wpm`, `paddingChar`,
+`mode`, and `skipDelay`. It mirrors the RSVP display pattern from the Python
+examples while still using the plugin's normal display packet encoder:
+
+```json
+{ "op": "rsvp_text", "text": "Rapid serial visual presentation", "wordsPerGroup": 2, "wpm": 250 }
+```
+
+`raw` accepts `data`, `bytes`, `hex`, or `base64` plus optional `side`/`target`
+(`left`, `right`, or `both`). This keeps low-level SDK commands such as native
+connection-ready packets reachable while `connection_ready` covers the common
+left/right initialization pair directly. Pass `initMode: "official"` to send
+the EvenDemoApp iOS same-init form (`0x4D 0x01`) to both lenses, or
+`initMode: "android-f4"` to send the EvenDemoApp Android form (`0xF4 0x01`) to
+both lenses:
+
+```json
+{ "op": "connection_ready", "initMode": "official" }
+```
+
+`bmp_image` accepts prebuilt BMP bytes through `hex`, `base64`, or `data`.
+It can also generate a native 1-bit BMP from grayscale pixels:
+
+```json
+{ "op": "bmp_image", "pixels": [0, 255, 255, 0], "width": 2, "height": 2 }
+```
+
+Dashboard/navigation/translation operations expose the packet families used by
+Fahrplan in addition to plain text display:
+
+```json
+{ "op": "dashboard_position", "height": 3, "depth": 7 }
+```
+
+```json
+{ "op": "dashboard_calendar", "name": "Standup", "time": "13:30-14:30", "location": "Lab" }
+```
+
+```json
+{ "op": "navigation_directions", "totalDuration": "4 min", "totalDistance": "1 km", "direction": "Main St", "distance": "200 m", "speed": "30", "directionTurn": 3 }
+```
+
+Navigation image operations accept `image` as an array, hex, or base64 bit
+plane. `overlay` uses the same formats and defaults to an all-zero overlay when
+omitted, which keeps secondary navigation image action payloads compact enough
+for Eliza JSON extraction:
+
+```json
+{ "op": "navigation_secondary_image", "image": "<base64 bit plane>" }
+```
+
+```json
+{ "op": "translate_translated", "text": "bonjour", "syncId": 3 }
+```
+
+## Configuration
+
+- `SMARTGLASSES_TRANSPORT`: `auto` (default), `even-bridge`, `web-bluetooth`, or `noble`.
+- `SMARTGLASSES_SCAN_TIMEOUT_MS`: optional Noble BLE scan timeout in milliseconds.
+- `SMARTGLASSES_AUTO_INIT`: send left/right initialization packets after Eliza-managed startup. Defaults to `true`.
+- `SMARTGLASSES_INIT_MODE`: `lens-specific` (default) sends `0x4D 0x01` to the left lens and `0xF4 0x01` to the right lens; `official` sends `0x4D 0x01` to both lenses as in EvenDemoApp iOS; `android-f4` sends `0xF4 0x01` to both lenses as in EvenDemoApp Android.
+
+## Microphone Audio
+
+EvenHub/G2 bridge hosts and the EvenHub simulator deliver `audioEvent.audioPcm`
+as signed 16 kHz PCM16, which the service converts to `Float32Array` samples for
+`onAudio`. MentraOS Bluetooth SDK bridge hosts can also deliver `mic_pcm` events
+with signed 16 kHz PCM16, or `mic_lc3` events that flow through the same LC3
+decoder hook as direct G1 packets.
+
+Direct G1 hardware sends `0xF1` packets containing LC3 frames. The upstream
+Android/iOS examples decode those frames with platform-native LC3 code, so this
+package preserves raw LC3 by default and exposes a decoder hook for host apps
+that have a native or WASM LC3 decoder:
+
+```ts
+service.setAudioDecoder(async (audio, context) => {
+  if (context.encoding !== "lc3") return null;
+  return decodeLc3ToPcm16(audio);
+});
+```
+
+For plugin-managed startup, register the same hook before the service starts:
+
+```ts
+setSmartglassesAudioDecoderForRuntime(decodeLc3ToPcm16);
+```
+
+## Upstream Evidence
+
+The implementation was derived from the ignored research checkouts in
+`research/even-realities/`. The reviewed sources and resulting implementation
+choices are:
+
+See `docs/smartglasses-upstream-audit.md` for the full
+source-to-implementation audit with local file references and test coverage.
+
+| Source | Relevant findings applied here |
+| --- | --- |
+| `fabioglimb/even-toolkit` | EvenHub/G2 bridge audio uses `rawBridge.audioControl` or `callEvenApp("audioControl", { isOpen })`; PCM arrives as `event.audioEvent.audioPcm` at 16 kHz. |
+| `BxNxM/even-dev` | Simulator apps use `waitForEvenAppBridge`, `onEvenHubEvent`, `sendStartUpPage`, `createStartUpPageContainer`, `rebuildPageContainer`, click/double-click event codes, and the `@evenrealities/evenhub-simulator` automation/audio model. |
+| `emingenc/even_glasses` | G1 command models for `0x4E` display, RSVP word-group display, `0x0E` mic control, `0x25` heartbeat, settings, notes, notifications, BMP transfer, and incoming notification handlers for init/display/notification events; BLE discovery identifies lenses by `_L_` and `_R_`. |
+| `binarythinktank/eveng1_python_sdk` | Nordic UART UUIDs, heartbeat packet `[0x25, 0x06, 0x00, seq, 0x04, seq]`, managed heartbeat loop for connection health, display packet header shape, mic response semantics, LC3 mic chunks, and broad BLE scan followed by left/right name matching. |
+| `meyskens/fahrplan` | Confirms practical G1 app surfaces: notification mirroring, dashboard/checklist style display, dashboard calendar/time-weather/setup packet families, navigation mode packets, translation overlay packets, QuickNote/voice-note `0x21` metadata, `0x1E` voice-note audio fetch/delete subcommands, and live transcription using the glasses microphone; Linux BLE caveats informed the explicit hardware smoke paths. |
+| `nickustinov/weather-even-g2` | G2 app event handling treats captured `listEvent`, `textEvent`, and `sysEvent` payloads as click/scroll sources and handles missing zero-value list indices from protobuf. |
+| `jappyjan/even-realities` | EvenHub SDK wrapper patterns for startup/rebuild page containers and event listener registration. |
+| `emingenc/g1_flutter_blue_plus` | Flutter BLE connection flow scans broadly, matches `_L_`/`_R_`, then discovers the Nordic UART service and TX/RX characteristics. |
+| `nickustinov/tesla-even-g2` | G2 bridge event normalization for nested `eventType`, `event_type`, `Event_Type`, click/double-click/scroll codes, and captured-event fallback to click. |
+| `galfaroth/awesome-even-realities-g1` | Cross-check index for the G1 ecosystem and the Python wrapper sources used above. |
+| `even-realities/EvenDemoApp` | Official demo evidence for mic on the right lens, `0xF1` LC3 mic packet shape, text streaming, notification flows, native function exit, serial request, app whitelist packetization, connection-ready same-init packets (`0x4D 0x01` to both lenses), and BMP data/end/CRC framing. |
+| `MentraOS/MentraOS` | Confirmed official-style dashboard height/depth position packets (`0x26 0x08 0x00 seq 0x02 0x01 height depth`) and G1 battery status requests/responses. |
+| `Mentra-Community/MentraOS` | Architecture context for smartglasses apps as BLE-to-phone/cloud pipelines, native bridge display APIs (`displayText`, `clearDisplay`), `setMicState`, `mic_pcm`/`mic_lc3` event streams, `local_transcription`/`transcription:*` events, G1 glyph-width display profile for pixel-aware wrapping, display bandwidth limits, and hardware-dependent verification requirements. |
+
+The implementation intentionally separates direct G1 BLE transports from the EvenHub/G2 bridge transport because the upstream projects expose those as different runtime surfaces.
+
+## Verification
+
+For the full software proof from the repository root:
+
+```bash
+npm run verify:smartglasses-software
+```
+
+That command runs the Facewear plugin lint/typecheck/test/app-registration
+gates, then the example software gate, repairs Facewear lockfile churn, and
+reruns the consolidation, Even research self-test, Even research audit, and
+completion self-test guards.
+
+```bash
+bun run --cwd plugins/plugin-facewear lint
+bun run --cwd plugins/plugin-facewear typecheck
+bun run --cwd plugins/plugin-facewear test
+bun run --cwd plugins/plugin-facewear build
+bun run --cwd packages/examples/smartglasses test
+bun run --cwd packages/examples/smartglasses start
+bun run --cwd packages/examples/smartglasses smoke:package
+bun run --cwd packages/examples/smartglasses smoke:simulator
+bun run --cwd packages/examples/smartglasses typecheck
+bun run --cwd packages/examples/smartglasses verify:software
+bun run --cwd packages/examples/smartglasses hardware:status-latest
+```
+
+## Hardware Smoke
+
+The browser hardware smoke example exercises the direct G1 BLE path:
+
+```bash
+npm run smartglasses:dev:hardware
+```
+
+```bash
+bun run --cwd packages/examples/smartglasses dev:hardware
+```
+
+Open `http://127.0.0.1:5178/hardware-smoke.html` in a Web Bluetooth-capable
+browser. Use **Connect Headset** for the two-step whole-headset flow; the same
+button prompts for the left lens and then the right lens because browsers
+require a user gesture for each Bluetooth picker. The page sends
+connection-ready/init, serial request, display, mic, brightness, dashboard,
+head-up angle, and wear-detection commands, then logs a structured evidence
+checklist for single-tap mic enable, double-tap mic disable, LC3 audio
+notifications, serial responses, packet writes, and final service status.
+
+The View Manager page at `/apps/smartglasses` exposes the same setup and
+diagnostic intent inside Eliza. Its copied/downloaded report includes
+whole-headset `scanDiagnosis`, `physicalBlocker`, setup hint, next action,
+observed serial number, outbound G1 write evidence, and microphone audio
+metadata including sample rate, encoding, sequence when available, side, and
+byte count. The View Manager checklist treats serial request and observed
+serial response as separate evidence so a request packet alone does not satisfy
+the serial proof.
+
+The EvenHub simulator can exercise the G2 bridge surface without physical hardware:
+
+```bash
+npm run smartglasses:dev:simulator
+npm run smartglasses:simulator
+```
+
+```bash
+bun run --cwd packages/examples/smartglasses dev:simulator
+bun run --cwd packages/examples/smartglasses simulator
+```
+
+An automated simulator smoke harness is also available:
+
+```bash
+npm run smartglasses:smoke:simulator
+```
+
+```bash
+bun run --cwd packages/examples/smartglasses smoke:simulator
+```
+
+The simulator currently publishes 16 kHz signed PCM audio events through the EvenHub bridge. It is useful for bridge display, input, audio-control, and automation checks, but it is not a replacement for physical G1/G2 validation.
+
+To exercise simulator microphone delivery, pass an EvenHub simulator audio
+input ID. The automated smoke will forward it as `--aid`, click to enable the
+bridge microphone, and wait for an `audioEvent.audioPcm` event:
+
+```bash
+SMARTGLASSES_SIMULATOR_AUDIO_DEVICE="coreaudio:BuiltInMicrophoneDevice" bun run --cwd packages/examples/smartglasses smoke:simulator
+```
+
+The Node/Bun hardware smoke exercises the Noble transport:
+
+```bash
+bun run --cwd packages/examples/smartglasses hardware:noble
+```
+
+It scans for left/right lenses, connects to the UART service, sends
+connection-ready/init, serial request, display, and settings packets, disables
+the right microphone, waits for a `wearing` physical state, then requires a
+single tap to enable microphone capture, speech audio, and a double tap to
+disable capture during the smoke window. The glasses must be out of the
+charging cradle and worn for tap and microphone evidence.
+`SMARTGLASSES_SCAN_TIMEOUT_MS`, `SMARTGLASSES_HOLD_MS`,
+`SMARTGLASSES_WEARING_TIMEOUT_MS=30000`,
+`SMARTGLASSES_INIT_MODE=official|lens-specific|android-f4`, and
+`SMARTGLASSES_DIRECT_MIC_MS=15000` can tune scan, microphone wait time, wearing
+wait, init variant, and direct mic diagnostics. Set
+`SMARTGLASSES_REPORT_PATH=./smartglasses-hardware-report.json` to write a
+structured evidence artifact covering packet writes, serial state, headset
+physical/battery/device state, side-tap mic state, audio chunks, and final
+service status.
+
+For the final auditable hardware proof run, use the bundled latest-report
+helpers. They write `/tmp/smartglasses-hardware-report-latest.json`, print a
+setup/status summary even when the smoke fails, and then run the strict
+validator:
+
+```bash
+npm run smartglasses:hardware:prove
+```
+
+```bash
+bun run --cwd packages/examples/smartglasses hardware:prove:bleak
+```
+
+```bash
+npm run smartglasses:hardware:prove:noble
+```
+
+```bash
+bun run --cwd packages/examples/smartglasses hardware:prove:noble
+```
+
+If the short proof run connects both lenses but never observes worn state, run
+the watch proof wrapper. It waits longer while preserving the same
+latest-report, status, and freshness-validation flow:
+
+If the status summary reports `physicalBlocker: "headset_not_found"`, the scan
+did not discover either lens. Remove both lenses from the charging base, keep
+them near this device, and rerun the watch proof. Failed Bleak reports include
+`discoveredDevices`, `discoveredDeviceCount`, and `discoveredG1DeviceCount` to
+show whether CoreBluetooth saw nearby BLE devices but no Even/G1 lenses.
+If Noble reports `physicalBlocker: "transport_unavailable"` on macOS, the
+native Noble binding is not usable for this runtime; use the Bleak/CoreBluetooth
+proof or rebuild `@abandonware/noble` for the current Node/Bun ABI.
+
+```bash
+npm run smartglasses:hardware:prove:watch
+```
+
+```bash
+bun run --cwd packages/examples/smartglasses hardware:prove:bleak:watch
+```
+
+```bash
+npm run smartglasses:hardware:prove:noble:watch
+```
+
+```bash
+bun run --cwd packages/examples/smartglasses hardware:prove:noble:watch
+```
+
+Inspect and validate that latest artifact independently before treating
+physical hardware support as proven. The latest validator requires the `/tmp`
+report to be fresh within ten minutes; use `hardware:validate-report <path>`
+for historical artifacts:
+
+```bash
+npm run smartglasses:hardware:status
+npm run smartglasses:hardware:validate
+```
+
+```bash
+bun run --cwd packages/examples/smartglasses hardware:status-latest
+bun run --cwd packages/examples/smartglasses hardware:validate-latest
+```
+
+A passing report must show real lens connection, connection-ready/init writes,
+display packet writes, serial request and observed serial response, settings
+writes, observed tap events, single-tap microphone enable, double-tap
+microphone disable, non-empty microphone audio, and final connected service
+status with serial and audio counters. Simulator and mock tests are useful
+regression coverage, but they do not satisfy this physical hardware gate. The
+validator reports `headsetInCradle` and `wearingStateNotObserved` separately
+when the setup state explains missing tap or microphone evidence.
+
+To validate a custom report path instead of the latest helper output:
+
+```bash
+bun run --cwd packages/examples/smartglasses hardware:validate-report ./smartglasses-hardware-report.json
+```

package/package.json

@@ -0,0 +1,139 @@
+{
+  "name": "@elizaos/plugin-facewear",
+  "version": "2.0.3-beta.2",
+  "type": "module",
+  "description": "Unified facewear plugin — Meta Quest 3, XReal, Even Realities G1/G2, Apple Vision Pro. Bidirectional voice+camera streaming, smartglasses display, view panels, device management.",
+  "main": "./dist/index.js",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "eliza-source": {
+        "types": "./src/index.ts",
+        "import": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./register": {
+      "types": "./dist/register.d.ts",
+      "import": "./dist/register.js",
+      "default": "./dist/register.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "eliza-source": {
+        "types": "./src/*.ts",
+        "import": "./src/*.ts",
+        "default": "./src/*.ts"
+      },
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    }
+  },
+  "scripts": {
+    "typecheck": "bunx tsc --noEmit -p tsconfig.json",
+    "lint": "bunx @biomejs/biome check src",
+    "test": "bun run build:views && bun run emulator:build && NODE_OPTIONS='--experimental-sqlite' vitest run --config ./vitest.config.ts",
+    "build": "bun run build:js && bun run build:views && bun run build:types",
+    "build:js": "tsup --config ../tsup.plugin-packages.shared.ts",
+    "build:types": "bunx tsc --noCheck -p tsconfig.build.json",
+    "build:views": "bunx --bun vite build --config vite.config.views.ts",
+    "emulator:build": "cd emulator && bun install --force && bun run build",
+    "emulator:watch": "cd emulator && bun run build:watch",
+    "emulator:cli": "bun run --cwd emulator src/cli.ts",
+    "verify:app": "bunx vitest --root ../.. run packages/app-core/src/registry/facewear-registry.test.ts packages/app/src/plugin-registrations.test.ts"
+  },
+  "dependencies": {
+    "@elizaos/agent": "2.0.3-beta.2",
+    "@elizaos/core": "2.0.3-beta.2",
+    "@elizaos/ui": "2.0.3-beta.2",
+    "lucide-react": "^1.0.0",
+    "ws": "^8.18.0",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "optionalDependencies": {
+    "@abandonware/noble": "^1.9.2-25"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.14",
+    "@types/node": "^25.0.3",
+    "@types/react": "^19.2.3",
+    "@types/react-dom": "^19.2.3",
+    "@types/ws": "^8.5.10",
+    "bun-types": "^1.3.14",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vite": "8.0.16",
+    "vitest": "^4.0.17"
+  },
+  "elizaos": {
+    "plugin": {
+      "displayName": "Facewear",
+      "category": "hardware"
+    }
+  },
+  "agentConfig": {
+    "pluginType": "elizaos:plugin:1.0.0",
+    "pluginParameters": {
+      "FACEWEAR_WS_PORT": {
+        "type": "number",
+        "description": "WebSocket port for XR streaming (Quest 3, XReal, Vision Pro).",
+        "required": false,
+        "default": 31338
+      },
+      "FACEWEAR_SMARTGLASSES_TRANSPORT": {
+        "type": "string",
+        "description": "Even Realities transport selection.",
+        "required": false,
+        "default": "auto",
+        "enum": [
+          "auto",
+          "even-bridge",
+          "web-bluetooth",
+          "noble"
+        ]
+      },
+      "FACEWEAR_SCAN_TIMEOUT_MS": {
+        "type": "number",
+        "description": "BLE scan timeout (ms) for Noble transport.",
+        "required": false,
+        "default": 10000
+      },
+      "FACEWEAR_AUTO_INIT": {
+        "type": "boolean",
+        "description": "Send G1 connection-ready init packets automatically.",
+        "required": false,
+        "default": true
+      },
+      "FACEWEAR_INIT_MODE": {
+        "type": "string",
+        "description": "G1 connection-ready init mode.",
+        "required": false,
+        "default": "lens-specific",
+        "enum": [
+          "lens-specific",
+          "official",
+          "android-f4"
+        ]
+      }
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "assets",
+    "dist",
+    "docs"
+  ],
+  "gitHead": "82fe0f44215954c2417328203f5bd6510985c1fc"
+}