Files
faceclaw/faceclaw-extensions/README.md
T

127 lines
4.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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<ApiKeyService[]>` | Which keys the user configured (names only). |
| `requestApiKeyAccess(services): Promise<Partial<Record<ApiKeyService, string>>>` | Prompt for and return key values. |
| `playBuzzer(steps): Promise<void>` | Play a piezo tone sequence. |
| `addCompassListener(fn): () => void` | Activate the magnetometer; receive heading samples. Uncalibrated (see note). |
| `createLayout(layout): Promise<boolean>` | Build the initial page (extended layout: full 576×452, no count limit, `preserve`). |
| `replaceLayout(layout): Promise<boolean>` | Replace the page; `preserve` containers inherit content by name. |
| `setAssistantTools(tools): void` | Contribute voice-assistant tools (namespaced by package name). |
`ApiKeyService` is one of `"openai" | "anthropic" | "soniox" | "elevenlabs" | "mapbox"`.
### Compass
`addCompassListener` is **not pre-calibrated**: the magnetometer is inside the
right arm, which rests on the head with a slight curl that differs between
wearers and wears. Treat the heading as relative — let the user zero it.
### Extended layout
`createLayout` / `replaceLayout` accept the same `textObject` / `imageObject` /
`listObject` shape as the stock `createStartUpPageContainer` /
`rebuildPageContainer` (so you can keep using the SDK's container builders),
plus: the canvas is the full **576×452** app area (image containers may fill it),
there is **no container-count limit**, and any container may set `preserve: true`
to inherit its content from the same-named container in the previous layout.
`containerID` remains the identity for `updateImageRawData` / `textContainerUpgrade`.
### Voice-assistant tools
```ts
fc.setAssistantTools([
{
name: "set_bpm",
description: "Set the metronome tempo.",
parameters: { type: "object", properties: { bpm: { type: "number" } }, required: ["bpm"] },
availability: "open", // or "foreground" (default)
handler: ({ bpm }) => { setTempo(bpm); return `tempo is now ${bpm}`; },
},
]);
```
The assistant sees each tool namespaced by your package name
(`app.<packageName>.set_bpm`). The handler's return value is reported back to the
assistant; throwing reports an error.
## Stability
Pre-1.0: the surface may still change. Once it stabilizes, additive-only changes
are the rule.