Files
faceclaw/faceclaw-extensions/src/index.ts
T

280 lines
11 KiB
TypeScript
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 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;
}
/**
* A magnetometer heading sample from {@link FaceclawExtensions.addCompassListener}.
* All headings are degrees clockwise in [0, 360).
*/
export interface CompassReading {
/**
* Raw magnetic heading as reported by the glasses, with no correction for
* how they sit on the wearer's head. Kept for apps that zero it themselves.
*/
headingDegrees: number;
/**
* Magnetic heading corrected by the wearer's calibration offset from the
* host's Compass app. Equal to `headingDegrees` until they calibrate.
*/
magneticHeadingDegrees: number;
/**
* Whether the wearer has been through the host's compass calibration, i.e.
* whether `magneticHeadingDegrees` and `trueHeadingDegrees` can be trusted
* as absolute rather than relative.
*/
wearerCalibrated: boolean;
/**
* Local magnetic declination (east positive), from the phone's location and
* the World Magnetic Model. Absent when the host has no location.
*/
declinationDegrees?: number;
/** `magneticHeadingDegrees` plus declination. Absent when declination is. */
trueHeadingDegrees?: number;
}
// ---- Extended layout (a superset of the stock EvenHub page containers) ----
//
// createLayout/replaceLayout take the same textObject/imageObject/listObject
// shape as the stock createStartUpPageContainer/rebuildPageContainer (so you can
// keep using the SDK's container-property builders), with three differences:
// - the canvas is the full 576x452 app area (vs the stock 576x288), so image
// containers may be up to 576x452;
// - there is no maximum container count;
// - each container may set `preserve: true` to inherit its content (image
// pixels / text / list items) from a same-named container in the previous
// layout — otherwise it starts blank.
// `containerID` is still the identity for content updates (the stock
// updateImageRawData / textContainerUpgrade address containers by it).
export interface FaceclawContainerCommon {
containerID: number;
containerName: string;
xPosition: number;
yPosition: number;
width: number;
height: number;
zOrderIndex?: number;
isEventCapture?: 0 | 1 | boolean;
/** Inherit content from the same-named container in the previous layout. */
preserve?: boolean;
}
export interface FaceclawTextContainer extends FaceclawContainerCommon {
content?: string;
borderWidth?: number;
borderRadius?: number;
paddingLength?: number;
}
/** Image containers may be up to 576x452 in the extended layout. */
export type FaceclawImageContainer = FaceclawContainerCommon;
export interface FaceclawListContainer extends FaceclawContainerCommon {
itemContainer?: {
itemName?: string[];
itemWidth?: number;
isItemSelectBorderEn?: 0 | 1 | boolean;
};
}
export interface FaceclawLayout {
textObject?: FaceclawTextContainer[];
imageObject?: FaceclawImageContainer[];
listObject?: FaceclawListContainer[];
}
// ---- Voice-assistant tools ----
/**
* A tool the app contributes to Faceclaw's voice assistant. The assistant sees
* it namespaced by the app's package name (`app.<packageName>.<name>`); `name`
* here is the bare, un-prefixed name.
*/
export interface AssistantTool {
/** Bare tool name (no package prefix), e.g. `"set_color"`. */
name: string;
/** What the tool does — the assistant reads this to decide when to call it. */
description: string;
/** JSON Schema for the arguments object the assistant will pass to `handler`. */
parameters?: object;
/**
* When the tool is callable: `"foreground"` (default) only while the app owns
* the visible window; `"open"` any time the app is running (even backgrounded).
*/
availability?: "open" | "foreground";
/**
* Invoked when the assistant calls the tool. Return a string (or any
* JSON-serializable value) to report back to the assistant; throw to report an
* error. May be async.
*/
handler: (args: any) => unknown;
}
/**
* 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<ApiKeyService[]>;
/**
* 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<Partial<Record<ApiKeyService, string>>>;
/**
* 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<void>;
/**
* Activate the glasses' magnetometer compass and receive heading samples.
* Returns an unsubscribe function; the sensor stays on while at least one
* listener is registered and the app is the foreground window.
*
* The magnetometer sits inside the right arm, which rests against the
* wearer's head with a slight curl that differs between wearers (and between
* wears), so `headingDegrees` is relative. The host's Compass app lets the
* wearer calibrate that away and adds local declination: prefer
* `trueHeadingDegrees` when present, then `magneticHeadingDegrees`, and check
* `wearerCalibrated` before trusting either as absolute.
*/
addCompassListener(listener: (reading: CompassReading) => void): () => void;
/**
* Build the app's initial page from an extended layout (superset of the stock
* createStartUpPageContainer — full 576x452 canvas, no container-count limit,
* per-container `preserve`). Resolves true on success.
*/
createLayout(layout: FaceclawLayout): Promise<boolean>;
/**
* Replace the current page with a new extended layout (superset of the stock
* rebuildPageContainer). Containers marked `preserve` inherit their content
* from the same-named container in the outgoing layout. Resolves true on success.
*/
replaceLayout(layout: FaceclawLayout): Promise<boolean>;
/**
* Declare the app's voice-assistant tools, replacing any previously set. Each
* tool's `handler` runs in the app when the assistant calls it. The assistant
* sees the tools namespaced by the app's package name. Pass `[]` to remove all.
*/
setAssistantTools(tools: AssistantTool[]): void;
}
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;
}