From 221dbb77ea90adbb2fe63b89680d04f680552038 Mon Sep 17 00:00:00 2001 From: James Babcock Date: Mon, 17 Aug 2026 01:57:14 -0700 Subject: [PATCH] Add extensions to the EvenHub API --- README.md | 22 ++- app/apps/evenhub/api-key-dialog.ts | 113 +++++++++++ app/apps/evenhub/evenhub-window.ts | 1 + app/apps/evenhub/session.ts | 289 +++++++++++++++++++++++++++- app/apps/evenhub/webview.ts | 8 +- faceclaw-extensions/README.md | 88 +++++++++ faceclaw-extensions/dist/index.d.ts | 120 ++++++++++++ faceclaw-extensions/dist/index.js | 40 ++++ faceclaw-extensions/package.json | 21 ++ faceclaw-extensions/src/index.ts | 136 +++++++++++++ faceclaw-extensions/tsconfig.json | 13 ++ 11 files changed, 844 insertions(+), 7 deletions(-) create mode 100644 app/apps/evenhub/api-key-dialog.ts create mode 100644 faceclaw-extensions/README.md create mode 100644 faceclaw-extensions/dist/index.d.ts create mode 100644 faceclaw-extensions/dist/index.js create mode 100644 faceclaw-extensions/package.json create mode 100644 faceclaw-extensions/src/index.ts create mode 100644 faceclaw-extensions/tsconfig.json diff --git a/README.md b/README.md index f9ee76e2..96270b26 100644 --- a/README.md +++ b/README.md @@ -38,11 +38,12 @@ To install, run ## Features * A voice assistant that wakes up when you say "Hey Even", transcribes text - with an on-device model, OpenAI Whisper, ElevenLabs, or Soniox API, and responds - to queries and commands using an Anthropic or OpenAI model (requires an API - key), or using your own long-running OpenClaw agent (see "Connecting an - external agent" below). + with an on-device model, OpenAI Whisper, ElevenLabs, or Soniox API, and + responds to queries and commands using an onboard model (Qwen3 4B, slow) + or with an Anthropic or OpenAI model (requires an API key), or using your + own long-running OpenClaw agent (see "Connecting an external agent" below). * Multitasking, with an app-switcher sidebar and app launcher + * Mostly-compatible with EvenHub apps * A lock screen; glasses lock automatically when you take them off and unlock when you unlock your phone * Full-screen apps can use the full 640x480 display area (rather than the @@ -88,6 +89,19 @@ OpenClaw agent with the phone plugged into its host can perform the whole setup itself. Note that a pulled settings file contains your API keys, so treat it as a secret (the default output path is gitignored here). +## EvenHub App Notes + +Faceclaw is mostly compatible with EvenHub apps. If you are developing an +app or using an open source app, you can package it into an EHPK file, send +it to your phone, and open it in the file browser to install. Or, you can log +into EvenHub and download apps there. + +Faceclaw runs EvenHub apps through an emulation layer; you may run into bugs +and differences in behavior. If you run into bugs, please try tunning them in +the stock Android app before you report them to the app's creator. If you're +developing your own app and plan to submit it to the Hub, be sure to test it in +the stock Android app before submitting. + ## Additional Caveats Some permissions are used, but may not reliably prompted for. Go to Android diff --git a/app/apps/evenhub/api-key-dialog.ts b/app/apps/evenhub/api-key-dialog.ts new file mode 100644 index 00000000..b5e3916a --- /dev/null +++ b/app/apps/evenhub/api-key-dialog.ts @@ -0,0 +1,113 @@ +import { getDefaultSmallFont } from "../../graphics/bdffont"; +import { GrayImage } from "../../graphics/image"; +import { truncateText } from "../../graphics/textwrap"; +import { Layer, type DashboardInputEvent, type LayerContext, type PaintBelow } from "../../ui/layers"; +import { drawSelectionHighlight } from "../../ui/menu"; + +const DIALOG_X = 8; +const DIALOG_Y = 8; +const DIALOG_WIDTH = 272; +const PADDING = 10; +const HEADER_STEP = 16; +const SERVICE_STEP = 15; +const ACTION_ROW_HEIGHT = 20; + +const SERVICE_LABELS: Record = { + openai: "OpenAI", + anthropic: "Anthropic", + soniox: "Soniox", + elevenlabs: "ElevenLabs", + mapbox: "Mapbox", +}; + +export type ApiKeyRequestItem = { id: string; configured: boolean }; + +/** + * Consent dialog shown when an EvenHub app calls requestApiKeyAccess: lists the + * requested API-key services (marking any the user hasn't configured) and asks + * Allow / Deny. Allow shares the configured keys' values with the app; Deny (or + * double-click) shares nothing. + */ +export class EvenHubApiKeyDialogLayer implements Layer { + /** 0 = Allow, 1 = Deny. */ + private selectedIndex = 0; + private resolved = false; + + constructor( + private readonly appName: string, + private readonly services: ApiKeyRequestItem[], + private readonly onConfirm: () => void, + private readonly onCancel: () => void, + ) {} + + paint(ctx: LayerContext, paintBelow: PaintBelow): GrayImage { + const font = getDefaultSmallFont(); + const { height: viewportHeight } = ctx.stack.getBaseSize(); + const image = paintBelow(); + const textWidth = DIALOG_WIDTH - 2 * PADDING - 4; + const left = DIALOG_X + PADDING + 2; + + const bodyTop = PADDING + HEADER_STEP + 6 + this.services.length * SERVICE_STEP + 8; + const height = Math.min(bodyTop + 2 * ACTION_ROW_HEIGHT + PADDING, viewportHeight - 2 * DIALOG_Y); + + image.fillRoundedRect(DIALOG_X, DIALOG_Y, DIALOG_WIDTH, height, 1); + image.drawRoundedRect(DIALOG_X, DIALOG_Y, DIALOG_WIDTH, height, 72); + + let y = DIALOG_Y + PADDING; + image.drawText(font, left, y, truncateText(font, `${this.appName} wants your keys:`, textWidth), 235); + y += HEADER_STEP + 6; + + for (const service of this.services) { + const label = SERVICE_LABELS[service.id] ?? service.id; + const text = service.configured ? label : `${label} (not set)`; + image.drawText(font, left + 8, y, truncateText(font, text, textWidth - 8), service.configured ? 220 : 130); + y += SERVICE_STEP; + } + y += 4; + + const focused = ctx.stack.isFocused(); + const actions = ["Allow", "Deny"]; + for (let index = 0; index < actions.length; index++) { + const rowY = y + index * ACTION_ROW_HEIGHT; + const selected = index === this.selectedIndex; + if (selected) { + drawSelectionHighlight(image, DIALOG_X + 12, rowY, DIALOG_WIDTH - 24, ACTION_ROW_HEIGHT - 1, focused, 8); + } + image.drawText(font, DIALOG_X + 22, rowY + 3, actions[index]!, selected ? 255 : 200); + } + return image; + } + + handleInput(event: DashboardInputEvent, ctx: LayerContext): void { + switch (event.type) { + case "scroll-up": + case "scroll-down": + this.selectedIndex = (this.selectedIndex + 1) % 2; + return; + case "click": + this.resolve(ctx, this.selectedIndex === 0); + return; + case "double-click": + this.resolve(ctx, false); + return; + default: + return; + } + } + + onRemoved(): void { + // Dismissed some other way (window closed): treat as deny. + if (!this.resolved) { + this.resolved = true; + this.onCancel(); + } + } + + private resolve(ctx: LayerContext, allowed: boolean): void { + if (this.resolved) return; + this.resolved = true; + ctx.stack.pop(); + if (allowed) this.onConfirm(); + else this.onCancel(); + } +} diff --git a/app/apps/evenhub/evenhub-window.ts b/app/apps/evenhub/evenhub-window.ts index f25a2a06..15173ed7 100644 --- a/app/apps/evenhub/evenhub-window.ts +++ b/app/apps/evenhub/evenhub-window.ts @@ -68,6 +68,7 @@ export function createEvenHubWindow( requestRender: created.requestRender, closeWindow: () => shell.closeWindow(windowId), focusSwitcher: () => shell.yieldFocusToSidebar(), + pushOverlay: (layer) => created.stack.push(layer), }); // FOREGROUND_ENTER/EXIT for the app on shell focus changes. diff --git a/app/apps/evenhub/session.ts b/app/apps/evenhub/session.ts index c4685f54..43d3bf74 100644 --- a/app/apps/evenhub/session.ts +++ b/app/apps/evenhub/session.ts @@ -20,7 +20,21 @@ import { ApplicationSettings } from "@nativescript/core"; import { GrayImage } from "../../graphics/image"; import { EvenHubFont } from "../../graphics/evenhub-font"; -import { type DashboardInputEvent } from "../../ui/layers"; +import { type DashboardInputEvent, type Layer } from "../../ui/layers"; +import { + anthropicApiKeySetting, + elevenLabsApiKeySetting, + mapboxApiKeySetting, + openAiApiKeySetting, + sonioxApiKeySetting, +} from "../../ui/dashboard-settings"; +import { + buildSoundSequencePayload, + phraseDurationMs, + CFW_SEQ_MAX, + type Step, +} from "../../ui/sound-effects"; +import { EvenHubApiKeyDialogLayer } from "./api-key-dialog"; import { asRecord, eventCaptureContainer, @@ -44,6 +58,8 @@ import { ensureFineLocationPermission } from "../../g2/android-permissions"; const UPNG = require("upng-js"); +declare const com: any; + /** OsEventTypeList values (PB ordinals). */ const CLICK_EVENT = 0; const SCROLL_TOP_EVENT = 1; @@ -157,6 +173,72 @@ export const EVENHUB_BRIDGE_INJECT_SCRIPT = ` })(); `; +/** + * Injected at document-start (after the stock bridge shim): defines + * `window.getFaceclawExtensions`, the single entry point for Faceclaw-only + * capabilities (see the faceclaw-extensions package). It never touches the + * standard SDK or any prototype — everything lives behind this one global, so + * apps stay compatible with the stock Even app (where the global is absent). + * + * RPC uses its own id-keyed promise map and `__fcExtResolve`, kept separate + * from the stock `__fcResolve` channel. Events arrive via `__fcExtEvent`. + * `` is interpolated by buildFaceclawExtensionsScript at load. + */ +export function buildFaceclawExtensionsScript(versionString: string): string { + return ` +(function () { + if (window.getFaceclawExtensions) return; + var VERSION = ${JSON.stringify(versionString)}; + var pending = {}; + var nextId = 1; + window.__fcExtResolve = function (id, ok, value) { + var entry = pending[id]; + if (!entry) return; + delete pending[id]; + (ok ? entry[0] : entry[1])(value); + }; + function call(method, params) { + return new Promise(function (resolve, reject) { + var id = nextId++; + pending[id] = [resolve, reject]; + window.__faceclawEvenHub.postMessage("faceclawExt", JSON.stringify([method].concat(params || [])), id); + }); + } + function send(method, params) { + // Fire-and-forget: id 0 tells the host no response is expected. + window.__faceclawEvenHub.postMessage("faceclawExt", JSON.stringify([method].concat(params || [])), 0); + } + var listeners = {}; + window.__fcExtEvent = function (name, data) { + var arr = listeners[name]; + if (!arr) return; + for (var i = 0; i < arr.slice().length; i++) { + try { arr[i](data); } catch (e) { if (window.console) console.error(e); } + } + }; + function on(name, cb) { + (listeners[name] || (listeners[name] = [])).push(cb); + return function () { + var arr = listeners[name]; + if (!arr) return; + var i = arr.indexOf(cb); + if (i >= 0) arr.splice(i, 1); + }; + } + var extensions = { + getVersion: function () { return VERSION; }, + returnToAppSwitcher: function () { send("returnToAppSwitcher"); }, + quit: function () { send("quit"); }, + addWindowLifecycleListener: function (cb) { return on("windowLifecycle", cb); }, + getConfiguredApiKeys: function () { return call("getConfiguredApiKeys"); }, + requestApiKeyAccess: function (services) { return call("requestApiKeyAccess", [services || []]); }, + playBuzzer: function (steps) { return call("playBuzzer", [steps || []]); } + }; + window.getFaceclawExtensions = function () { return extensions; }; +})(); +`; +} + /** Stock blocks a repeated createStartUpPageContainer ~2s before failing it. */ const DUPLICATE_CREATE_DELAY_MS = 2000; @@ -172,6 +254,8 @@ export type EvenHubWindowHooks = { closeWindow: () => void; /** Hand focus to the app switcher (used to decline an app's quit request). */ focusSwitcher: () => void; + /** Push a modal overlay layer onto the app window (e.g. a consent prompt). */ + pushOverlay: (layer: Layer) => void; }; export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient { @@ -195,6 +279,13 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient { private imuRequested = false; /** Non-null while the app has an active location subscription. */ private locationTracker: LocationTracker | null = null; + // Window-lifecycle tracking for the extension API (apps launch visible+focused). + private lastVisible = true; + private lastFocused = true; + /** Shell input focus on this window, sampled during paint. */ + private shellFocused = true; + /** API-key services the user has granted this app this session. */ + private readonly grantedApiKeys = new Set(); private log: (message: string) => void; constructor(manifest: EvenHubManifest, distDir: string, log: (message: string) => void) { @@ -238,6 +329,9 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient { } paint(size: { width: number; height: number }, focused: boolean): GrayImage { + // Focus changes always trigger a repaint of the foreground window, so paint + // is a reliable place to sample shell input-focus for lifecycle events. + this.updateShellFocus(focused); if (!this.pageCreated || !this.page) { const image = new GrayImage(size.width, size.height, 0); const font = EvenHubFont.get(); @@ -308,6 +402,10 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient { // reads the accelerometer). if (this.micRequested) evenHubMicRouter.notifyEligibilityChanged(); if (this.imuRequested) evenHubImuRouter.notifyEligibilityChanged(); + // Focus is unknown until the next paint (a re-shown window repaints and + // re-asserts it; a hidden one won't, so treat it as unfocused meanwhile). + this.shellFocused = false; + this.recomputeLifecycle(); if (!this.pageCreated) return; this.emitSysEvent(foreground ? FOREGROUND_ENTER_EVENT : FOREGROUND_EXIT_EVENT, 0); } @@ -317,6 +415,36 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient { if (this.screenOn === on) return; this.screenOn = on; if (this.micRequested) evenHubMicRouter.notifyEligibilityChanged(); + // As in setForeground: let the next paint re-assert focus. + this.shellFocused = false; + this.recomputeLifecycle(); + } + + // ----- extension window lifecycle ----- + + /** Sample shell input-focus (from paint) and emit focused/blurred on change. */ + private updateShellFocus(focused: boolean): void { + if (this.shellFocused === focused) return; + this.shellFocused = focused; + this.recomputeLifecycle(); + } + + /** + * Emit visible/hidden and focused/blurred extension events on transition. + * visible = foreground && screen on; focused additionally needs shell input + * focus on this window. + */ + private recomputeLifecycle(): void { + const visible = this.foreground && this.screenOn; + const focused = visible && this.shellFocused; + if (visible !== this.lastVisible) { + this.lastVisible = visible; + this.pushExtEvent("windowLifecycle", { type: visible ? "visible" : "hidden" }); + } + if (focused !== this.lastFocused) { + this.lastFocused = focused; + this.pushExtEvent("windowLifecycle", { type: focused ? "focused" : "blurred" }); + } } // ----- microphone (EvenHubMicClient) ----- @@ -461,6 +589,10 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient { * (kept lenient: a bare object works too). */ handleBridgeCall(handlerName: string, argsJson: string, callId: number): void { + if (handlerName === "faceclawExt") { + this.handleExtensionCall(argsJson, callId); + return; + } void (async () => { let result: unknown = null; try { @@ -638,6 +770,19 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient { ); } + private resolveExtCall(callId: number, ok: boolean, value: unknown): void { + this.webViewHandle?.evaluateJs( + `window.__fcExtResolve && window.__fcExtResolve(${callId}, ${ok ? "true" : "false"}, ${JSON.stringify(value ?? null)})`, + ); + } + + /** Deliver an extension event to the app (e.g. windowLifecycle). */ + private pushExtEvent(name: string, data: unknown): void { + this.webViewHandle?.evaluateJs( + `window.__fcExtEvent && window.__fcExtEvent(${JSON.stringify(name)}, ${JSON.stringify(data)})`, + ); + } + private pushEvenHubEvent(payloadType: "sysEvent" | "textEvent" | "listEvent", jsonData: Record): void { this.pushMessage("evenHubEvent", { type: payloadType, jsonData: elideZeroFields(jsonData) }); } @@ -656,6 +801,102 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient { }); } + // ----- Faceclaw extensions (faceclawExt channel) ----- + + private handleExtensionCall(argsJson: string, callId: number): void { + void (async () => { + let ok = true; + let result: unknown = null; + try { + const args = JSON.parse(argsJson) as unknown[]; + const method = String(args[0]); + result = await this.dispatchExtension(method, args.slice(1)); + } catch (error) { + ok = false; + result = String(error); + this.log(`evenhub: extension call failed: ${error}`); + } + // id 0 is a fire-and-forget send; nothing is awaiting it. + if (callId !== 0) this.resolveExtCall(callId, ok, result); + })(); + } + + private async dispatchExtension(method: string, params: unknown[]): Promise { + switch (method) { + case "returnToAppSwitcher": + this.windowHooks?.focusSwitcher(); + return null; + case "quit": + // A real quit — bypasses the shutDown(1) → return-to-switcher behavior. + setTimeout(() => this.close(), 0); + return null; + case "getConfiguredApiKeys": + return configuredApiKeyServices(); + case "requestApiKeyAccess": + return this.requestApiKeyAccess(Array.isArray(params[0]) ? params[0].map(String) : []); + case "playBuzzer": + await this.playBuzzer(Array.isArray(params[0]) ? params[0] : []); + return null; + default: + this.log(`evenhub: unknown extension method ${method}`); + return null; + } + } + + /** + * Prompt the user (on the glasses) to share configured API keys with the app, + * resolving with the granted values. Services already granted this session + * skip the prompt; declining resolves with an empty map. + */ + private requestApiKeyAccess(services: string[]): Promise> { + const requested = services.filter(isKnownApiKeyService); + const buildGrant = (): Record => { + const out: Record = {}; + for (const id of requested) { + if (!this.grantedApiKeys.has(id)) continue; + const value = apiKeyValue(id); + if (value) out[id] = value; + } + return out; + }; + if (requested.length === 0 || requested.every((id) => this.grantedApiKeys.has(id))) { + return Promise.resolve(buildGrant()); + } + if (!this.windowHooks) return Promise.resolve({}); + return new Promise((resolve) => { + const dialog = new EvenHubApiKeyDialogLayer( + this.manifest.name, + requested.map((id) => ({ id, configured: apiKeyValue(id).length > 0 })), + () => { + for (const id of requested) this.grantedApiKeys.add(id); + resolve(buildGrant()); + }, + () => resolve({}), + ); + this.windowHooks?.pushOverlay(dialog); + this.windowHooks?.requestRender(); + }); + } + + /** Play a piezo tone sequence, chunking/pacing past the firmware's 48-step cap. */ + private async playBuzzer(rawSteps: unknown[]): Promise { + const steps = normalizeBuzzerSteps(rawSteps); + if (steps.length === 0) return; + const communicator = activeCommunicator(); + if (!communicator) return; + for (let i = 0; i < steps.length; i += CFW_SEQ_MAX) { + const chunk = steps.slice(i, i + CFW_SEQ_MAX); + const payload = buildSoundSequencePayload(chunk); + try { + communicator.playBuzzerSequence(payload.buffer); + } catch (error) { + this.log(`evenhub: playBuzzer failed: ${error}`); + return; + } + if (i + CFW_SEQ_MAX < steps.length) await delay(phraseDurationMs(chunk)); + } + } + // ----- teardown ----- /** Close everything: glasses window, WebView, session. Idempotent. */ @@ -741,6 +982,52 @@ function clampImuFreq(freq: number): number { return Math.min(1000, Math.max(100, snapped)); } +function activeCommunicator(): any { + if (!global.isAndroid) return null; + try { + return com.faceclaw.app.FaceclawBleCommunicator.getActive(); + } catch { + return null; + } +} + +/** The API-key services the extension API can surface, and their settings. */ +const API_KEY_SERVICES = [ + { id: "openai", setting: openAiApiKeySetting }, + { id: "anthropic", setting: anthropicApiKeySetting }, + { id: "soniox", setting: sonioxApiKeySetting }, + { id: "elevenlabs", setting: elevenLabsApiKeySetting }, + { id: "mapbox", setting: mapboxApiKeySetting }, +] as const; + +function isKnownApiKeyService(id: string): boolean { + return API_KEY_SERVICES.some((service) => service.id === id); +} + +function apiKeyValue(id: string): string { + return API_KEY_SERVICES.find((service) => service.id === id)?.setting.get().trim() ?? ""; +} + +/** Service ids the user has actually configured (non-empty key), names only. */ +function configuredApiKeyServices(): string[] { + return API_KEY_SERVICES.filter((service) => service.setting.get().trim()).map((service) => service.id); +} + +/** Coerce an app-supplied buzzer step list into validated {freq, ms, duty?}. */ +function normalizeBuzzerSteps(raw: unknown[]): Step[] { + const out: Step[] = []; + for (const item of raw) { + if (!item || typeof item !== "object") continue; + const record = item as Record; + const freq = Number(record.freq); + const ms = Number(record.ms); + if (!Number.isFinite(freq) || !Number.isFinite(ms)) continue; + const duty = record.duty === undefined ? undefined : Number(record.duty); + out.push({ freq, ms, duty: duty !== undefined && Number.isFinite(duty) ? duty : undefined }); + } + return out; +} + /** * Decode an uncompressed Windows BMP ('BM', BI_RGB) to 8bpp grayscale. Handles * 1/4/8-bit paletted and 24/32-bit BGR(A), top-down or bottom-up. Returns null diff --git a/app/apps/evenhub/webview.ts b/app/apps/evenhub/webview.ts index 597fd6cb..5429e872 100644 --- a/app/apps/evenhub/webview.ts +++ b/app/apps/evenhub/webview.ts @@ -12,7 +12,8 @@ * host app is backgrounded (see FaceclawEvenHubWebView / the host). */ import { Application, Utils } from "@nativescript/core"; -import { EVENHUB_BRIDGE_INJECT_SCRIPT, type EvenHubSession } from "./session"; +import { EVENHUB_BRIDGE_INJECT_SCRIPT, buildFaceclawExtensionsScript, type EvenHubSession } from "./session"; +import { FACECLAW_VERSION } from "../../version"; declare const android: any; declare const com: any; @@ -56,8 +57,11 @@ export function createEvenHubWebView(session: EvenHubSession): EvenHubWebView { }); const host = originHost(session); + // Stock bridge shim first, then the Faceclaw extensions global (both at + // document-start, before any app JS). + const injectScript = EVENHUB_BRIDGE_INJECT_SCRIPT + buildFaceclawExtensionsScript(`Faceclaw/${FACECLAW_VERSION}`); webView.setWebViewClient( - new com.faceclaw.app.FaceclawEvenHubWebViewClient(session.distDir, host, EVENHUB_BRIDGE_INJECT_SCRIPT, listener), + new com.faceclaw.app.FaceclawEvenHubWebViewClient(session.distDir, host, injectScript, listener), ); webView.addJavascriptInterface(new com.faceclaw.app.FaceclawEvenHubJsBridge(listener), "__faceclawEvenHub"); diff --git a/faceclaw-extensions/README.md b/faceclaw-extensions/README.md new file mode 100644 index 00000000..aa35f064 --- /dev/null +++ b/faceclaw-extensions/README.md @@ -0,0 +1,88 @@ +# faceclaw-extensions + +Type definitions and a tiny helper for EvenHub apps that want to detect and use +**Faceclaw**-specific extension APIs. + +[Faceclaw](https://github.com/jimrandomh/faceclaw) is an alternative host for +EvenHub apps: it runs them directly on the Even Realities G2 glasses instead of +through the stock Even Realities phone app. An app built against the standard +[`@evenrealities/even_hub_sdk`](https://www.npmjs.com/package/@evenrealities/even_hub_sdk) +runs unchanged. This package lets it *optionally* light up a few extra +capabilities when it detects it's running inside Faceclaw. + +## Design + +There is exactly one entry point: the injected global +`window.getFaceclawExtensions`. + +- Inside Faceclaw it is `(() => FaceclawExtensions) | null`. +- In the stock Even app (and browsers, and any other host) it is `undefined`. + +Nothing on the standard SDK, on `window`, or on any built-in prototype is +modified — every Faceclaw capability lives behind this single global. That keeps +it obvious what is an extension, and means an app that uses these APIs still runs +correctly everywhere else (it just skips the extras). New capabilities are only +ever *added*, never changed, so pinning a version stays backwards-compatible. + +## Install + +```sh +npm install faceclaw-extensions +``` + +(Type-only today; no runtime dependencies.) + +## Usage + +```ts +import { getFaceclawExtensions } from "faceclaw-extensions"; + +const fc = getFaceclawExtensions(); +if (!fc) { + // Not running in Faceclaw — use only the standard EvenHub SDK. +} else { + console.log("host:", fc.getVersion()); // e.g. "Faceclaw/0.4.0" + + // Pause work while the app isn't on-screen. + const off = fc.addWindowLifecycleListener((e) => { + if (e.type === "hidden" || e.type === "blurred") pause(); + if (e.type === "visible" || e.type === "focused") resume(); + }); + + // Ask for the user's OpenAI key (opens a consent prompt on the glasses). + const configured = await fc.getConfiguredApiKeys(); + if (configured.includes("openai")) { + const granted = await fc.requestApiKeyAccess(["openai"]); + if (granted.openai) startCloudFeature(granted.openai); + } + + // Beep. + await fc.playBuzzer([ + { freq: 880, ms: 90 }, + { freq: 0, duty: 0, ms: 40 }, // a rest + { freq: 1320, ms: 160 }, + ]); +} +``` + +## API + +See `src/index.ts` for the full, documented `FaceclawExtensions` interface. In +brief: + +| Method | Description | +| --- | --- | +| `getVersion(): string` | Host version, e.g. `"Faceclaw/0.4.0"`. | +| `returnToAppSwitcher(): void` | Yield focus to the app switcher; keep running. | +| `quit(): void` | Close the app for real (not overridable). | +| `addWindowLifecycleListener(fn): () => void` | `visible`/`hidden` and `focused`/`blurred` events. | +| `getConfiguredApiKeys(): Promise` | Which keys the user configured (names only). | +| `requestApiKeyAccess(services): Promise>>` | Prompt for and return key values. | +| `playBuzzer(steps): Promise` | Play a piezo tone sequence. | + +`ApiKeyService` is one of `"openai" | "anthropic" | "soniox" | "elevenlabs" | "mapbox"`. + +## Stability + +Pre-1.0: the surface may still change. Once it stabilizes, additive-only changes +are the rule. diff --git a/faceclaw-extensions/dist/index.d.ts b/faceclaw-extensions/dist/index.d.ts new file mode 100644 index 00000000..9e8297ec --- /dev/null +++ b/faceclaw-extensions/dist/index.d.ts @@ -0,0 +1,120 @@ +/** + * faceclaw-extensions — type definitions for the Faceclaw extension API. + * + * Faceclaw (https://github.com/…/faceclaw) is an alternative host for EvenHub + * apps that runs them directly on the Even Realities G2 glasses instead of the + * stock Even app. An app built against the standard `@evenrealities/even_hub_sdk` + * runs unchanged. When it happens to be running inside Faceclaw, this package + * lets it detect that and reach a few extra, Faceclaw-only capabilities. + * + * Design contract: + * - The only entry point is the injected global `window.getFaceclawExtensions`. + * It is `(() => FaceclawExtensions) | null` inside Faceclaw and `undefined` + * in the stock Even app (and any other host). Nothing on the standard SDK or + * on built-in prototypes is modified — every Faceclaw capability lives behind + * this one global, so it is always obvious what is an extension and standard + * apps keep working everywhere. + * - New functionality is only ever *added* here; existing members keep their + * behavior, so pinning a version stays backwards-compatible. + * + * Usage: + * ```ts + * import { getFaceclawExtensions } from "faceclaw-extensions"; + * + * const fc = getFaceclawExtensions(); + * if (fc) { + * console.log("Running in", fc.getVersion()); // "Faceclaw/0.4.0" + * fc.addWindowLifecycleListener((e) => { + * if (e.type === "hidden") pauseExpensiveWork(); + * }); + * } + * ``` + */ +/** Third-party API-key services whose keys the user may have configured in Faceclaw. */ +export type ApiKeyService = "openai" | "anthropic" | "soniox" | "elevenlabs" | "mapbox"; +/** + * One step of a piezo-buzzer tone sequence. The G2 has a single monophonic PWM + * buzzer; a sequence plays back-to-back steps on the firmware's own timer. + */ +export interface BuzzerStep { + /** Tone frequency in Hz. The piezo is loudest ~1–4 kHz; faint below ~150 Hz. */ + freq: number; + /** Step duration in milliseconds (1–65535). */ + ms: number; + /** PWM duty cycle, 0–100 (default 50). `duty: 0` is a rest (silence) for `ms`. */ + duty?: number; +} +/** + * Window lifecycle transitions, delivered to + * {@link FaceclawExtensions.addWindowLifecycleListener}: + * - `visible` / `hidden`: the app's glasses window became the shown surface, or + * stopped being it — because the user switched the foreground window or the + * phone screen turned on/off. A hidden app keeps running (Faceclaw keeps its + * webview alive) but nothing it renders reaches the glasses. + * - `focused` / `blurred`: input focus moved onto or off the app's window (e.g. + * the user opened the app switcher). A blurred-but-visible app is still shown + * but no longer receives taps/scrolls. + * + * An app can assume it starts `visible` and `focused` at launch; events report + * changes from there. + */ +export type WindowLifecycleEventType = "visible" | "hidden" | "focused" | "blurred"; +export interface WindowLifecycleEvent { + type: WindowLifecycleEventType; +} +/** + * The Faceclaw-only capability surface. Obtained via {@link getFaceclawExtensions}. + * Every method is additive to the standard EvenHub SDK. + */ +export interface FaceclawExtensions { + /** Host version string, e.g. `"Faceclaw/0.4.0"`. */ + getVersion(): string; + /** + * Hand input focus back to Faceclaw's app switcher without closing the app + * (it keeps running in the background). Equivalent to the user double-tapping + * out, but explicit. + */ + returnToAppSwitcher(): void; + /** + * Close this app for real and tear down its window. Unlike the stock + * `shutDownPageContainer(1)` — which Faceclaw interprets as "return to the app + * switcher" so double-tap-to-quit apps stay alive — this always quits. + */ + quit(): void; + /** + * Subscribe to window lifecycle changes (see {@link WindowLifecycleEvent}). + * Returns an unsubscribe function. + */ + addWindowLifecycleListener(listener: (event: WindowLifecycleEvent) => void): () => void; + /** + * List which API-key services the user has configured in Faceclaw. Returns + * only the service names, never the key values — use + * {@link requestApiKeyAccess} to obtain values (with the user's consent). + */ + getConfiguredApiKeys(): Promise; + /** + * Ask the user to share one or more configured API keys with this app. Opens + * a consent prompt on the glasses. Resolves with a map of the granted keys' + * values (only for services that are both requested and configured); services + * the user declines, or that aren't configured, are absent. Resolves with an + * empty object if the user denies. + */ + requestApiKeyAccess(services: ApiKeyService[]): Promise>>; + /** + * Play a tone sequence on the glasses' piezo buzzer. Sequences longer than the + * firmware's per-message cap (48 steps) are split and paced automatically. + * Resolves once every message has been queued. + */ + playBuzzer(steps: BuzzerStep[]): Promise; +} +declare global { + interface Window { + /** Injected by Faceclaw; `undefined` in the stock Even app and other hosts. */ + getFaceclawExtensions?: (() => FaceclawExtensions) | null; + } +} +/** + * Return the Faceclaw extension API if the app is running inside Faceclaw, or + * `null` otherwise (the stock Even app, a browser, etc.). Safe to call anywhere. + */ +export declare function getFaceclawExtensions(): FaceclawExtensions | null; diff --git a/faceclaw-extensions/dist/index.js b/faceclaw-extensions/dist/index.js new file mode 100644 index 00000000..88c290ac --- /dev/null +++ b/faceclaw-extensions/dist/index.js @@ -0,0 +1,40 @@ +/** + * faceclaw-extensions — type definitions for the Faceclaw extension API. + * + * Faceclaw (https://github.com/…/faceclaw) is an alternative host for EvenHub + * apps that runs them directly on the Even Realities G2 glasses instead of the + * stock Even app. An app built against the standard `@evenrealities/even_hub_sdk` + * runs unchanged. When it happens to be running inside Faceclaw, this package + * lets it detect that and reach a few extra, Faceclaw-only capabilities. + * + * Design contract: + * - The only entry point is the injected global `window.getFaceclawExtensions`. + * It is `(() => FaceclawExtensions) | null` inside Faceclaw and `undefined` + * in the stock Even app (and any other host). Nothing on the standard SDK or + * on built-in prototypes is modified — every Faceclaw capability lives behind + * this one global, so it is always obvious what is an extension and standard + * apps keep working everywhere. + * - New functionality is only ever *added* here; existing members keep their + * behavior, so pinning a version stays backwards-compatible. + * + * Usage: + * ```ts + * import { getFaceclawExtensions } from "faceclaw-extensions"; + * + * const fc = getFaceclawExtensions(); + * if (fc) { + * console.log("Running in", fc.getVersion()); // "Faceclaw/0.4.0" + * fc.addWindowLifecycleListener((e) => { + * if (e.type === "hidden") pauseExpensiveWork(); + * }); + * } + * ``` + */ +/** + * Return the Faceclaw extension API if the app is running inside Faceclaw, or + * `null` otherwise (the stock Even app, a browser, etc.). Safe to call anywhere. + */ +export function getFaceclawExtensions() { + const getter = typeof window !== "undefined" ? window.getFaceclawExtensions : null; + return typeof getter === "function" ? getter() : null; +} diff --git a/faceclaw-extensions/package.json b/faceclaw-extensions/package.json new file mode 100644 index 00000000..3cb3c8bc --- /dev/null +++ b/faceclaw-extensions/package.json @@ -0,0 +1,21 @@ +{ + "name": "faceclaw-extensions", + "version": "0.1.0", + "description": "Type definitions and helpers for EvenHub apps to detect and use Faceclaw-specific extension APIs.", + "license": "MIT", + "type": "module", + "main": "dist/index.js", + "types": "dist/index.d.ts", + "exports": { + ".": { + "types": "./dist/index.d.ts", + "import": "./dist/index.js" + } + }, + "files": ["dist", "README.md"], + "scripts": { + "build": "tsc -p tsconfig.json" + }, + "keywords": ["evenhub", "even-realities", "g2", "faceclaw", "smart-glasses"], + "sideEffects": false +} diff --git a/faceclaw-extensions/src/index.ts b/faceclaw-extensions/src/index.ts new file mode 100644 index 00000000..f6275b94 --- /dev/null +++ b/faceclaw-extensions/src/index.ts @@ -0,0 +1,136 @@ +/** + * faceclaw-extensions — type definitions for the Faceclaw extension API. + * + * Faceclaw (https://github.com/…/faceclaw) is an alternative host for EvenHub + * apps that runs them directly on the Even Realities G2 glasses instead of the + * stock Even app. An app built against the standard `@evenrealities/even_hub_sdk` + * runs unchanged. When it happens to be running inside Faceclaw, this package + * lets it detect that and reach a few extra, Faceclaw-only capabilities. + * + * Design contract: + * - The only entry point is the injected global `window.getFaceclawExtensions`. + * It is `(() => FaceclawExtensions) | null` inside Faceclaw and `undefined` + * in the stock Even app (and any other host). Nothing on the standard SDK or + * on built-in prototypes is modified — every Faceclaw capability lives behind + * this one global, so it is always obvious what is an extension and standard + * apps keep working everywhere. + * - New functionality is only ever *added* here; existing members keep their + * behavior, so pinning a version stays backwards-compatible. + * + * Usage: + * ```ts + * import { getFaceclawExtensions } from "faceclaw-extensions"; + * + * const fc = getFaceclawExtensions(); + * if (fc) { + * console.log("Running in", fc.getVersion()); // "Faceclaw/0.4.0" + * fc.addWindowLifecycleListener((e) => { + * if (e.type === "hidden") pauseExpensiveWork(); + * }); + * } + * ``` + */ + +/** Third-party API-key services whose keys the user may have configured in Faceclaw. */ +export type ApiKeyService = "openai" | "anthropic" | "soniox" | "elevenlabs" | "mapbox"; + +/** + * One step of a piezo-buzzer tone sequence. The G2 has a single monophonic PWM + * buzzer; a sequence plays back-to-back steps on the firmware's own timer. + */ +export interface BuzzerStep { + /** Tone frequency in Hz. The piezo is loudest ~1–4 kHz; faint below ~150 Hz. */ + freq: number; + /** Step duration in milliseconds (1–65535). */ + ms: number; + /** PWM duty cycle, 0–100 (default 50). `duty: 0` is a rest (silence) for `ms`. */ + duty?: number; +} + +/** + * Window lifecycle transitions, delivered to + * {@link FaceclawExtensions.addWindowLifecycleListener}: + * - `visible` / `hidden`: the app's glasses window became the shown surface, or + * stopped being it — because the user switched the foreground window or the + * phone screen turned on/off. A hidden app keeps running (Faceclaw keeps its + * webview alive) but nothing it renders reaches the glasses. + * - `focused` / `blurred`: input focus moved onto or off the app's window (e.g. + * the user opened the app switcher). A blurred-but-visible app is still shown + * but no longer receives taps/scrolls. + * + * An app can assume it starts `visible` and `focused` at launch; events report + * changes from there. + */ +export type WindowLifecycleEventType = "visible" | "hidden" | "focused" | "blurred"; + +export interface WindowLifecycleEvent { + type: WindowLifecycleEventType; +} + +/** + * The Faceclaw-only capability surface. Obtained via {@link getFaceclawExtensions}. + * Every method is additive to the standard EvenHub SDK. + */ +export interface FaceclawExtensions { + /** Host version string, e.g. `"Faceclaw/0.4.0"`. */ + getVersion(): string; + + /** + * Hand input focus back to Faceclaw's app switcher without closing the app + * (it keeps running in the background). Equivalent to the user double-tapping + * out, but explicit. + */ + returnToAppSwitcher(): void; + + /** + * Close this app for real and tear down its window. Unlike the stock + * `shutDownPageContainer(1)` — which Faceclaw interprets as "return to the app + * switcher" so double-tap-to-quit apps stay alive — this always quits. + */ + quit(): void; + + /** + * Subscribe to window lifecycle changes (see {@link WindowLifecycleEvent}). + * Returns an unsubscribe function. + */ + addWindowLifecycleListener(listener: (event: WindowLifecycleEvent) => void): () => void; + + /** + * List which API-key services the user has configured in Faceclaw. Returns + * only the service names, never the key values — use + * {@link requestApiKeyAccess} to obtain values (with the user's consent). + */ + getConfiguredApiKeys(): Promise; + + /** + * Ask the user to share one or more configured API keys with this app. Opens + * a consent prompt on the glasses. Resolves with a map of the granted keys' + * values (only for services that are both requested and configured); services + * the user declines, or that aren't configured, are absent. Resolves with an + * empty object if the user denies. + */ + requestApiKeyAccess(services: ApiKeyService[]): Promise>>; + + /** + * Play a tone sequence on the glasses' piezo buzzer. Sequences longer than the + * firmware's per-message cap (48 steps) are split and paced automatically. + * Resolves once every message has been queued. + */ + playBuzzer(steps: BuzzerStep[]): Promise; +} + +declare global { + interface Window { + /** Injected by Faceclaw; `undefined` in the stock Even app and other hosts. */ + getFaceclawExtensions?: (() => FaceclawExtensions) | null; + } +} + +/** + * Return the Faceclaw extension API if the app is running inside Faceclaw, or + * `null` otherwise (the stock Even app, a browser, etc.). Safe to call anywhere. + */ +export function getFaceclawExtensions(): FaceclawExtensions | null { + const getter = typeof window !== "undefined" ? window.getFaceclawExtensions : null; + return typeof getter === "function" ? getter() : null; +} diff --git a/faceclaw-extensions/tsconfig.json b/faceclaw-extensions/tsconfig.json new file mode 100644 index 00000000..a9bd75c7 --- /dev/null +++ b/faceclaw-extensions/tsconfig.json @@ -0,0 +1,13 @@ +{ + "compilerOptions": { + "target": "ES2020", + "module": "ESNext", + "moduleResolution": "bundler", + "declaration": true, + "outDir": "dist", + "strict": true, + "skipLibCheck": true, + "lib": ["ESNext", "DOM"] + }, + "include": ["src/**/*"] +}