forked from Blendman974/faceclaw
Use TTF fonts throughout the UI; also add some more functions to app extension API
This commit is contained in:
1 parent
5abbe2a405
commit
96842ceb23
82 files changed
+2666
-288
No files matched your search
@@ -79,9 +79,47 @@ brief:
|
||||
| `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
|
||||
|
||||
Vendored
+90
@@ -62,6 +62,67 @@ export type WindowLifecycleEventType = "visible" | "hidden" | "focused" | "blurr
|
||||
export interface WindowLifecycleEvent {
|
||||
type: WindowLifecycleEventType;
|
||||
}
|
||||
/** A magnetometer heading sample from {@link FaceclawExtensions.addCompassListener}. */
|
||||
export interface CompassReading {
|
||||
/** Magnetic heading in degrees [0, 360). */
|
||||
headingDegrees: number;
|
||||
}
|
||||
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[];
|
||||
}
|
||||
/**
|
||||
* 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 | Promise<unknown>;
|
||||
}
|
||||
/**
|
||||
* The Faceclaw-only capability surface. Obtained via {@link getFaceclawExtensions}.
|
||||
* Every method is additive to the standard EvenHub SDK.
|
||||
@@ -106,6 +167,35 @@ export interface FaceclawExtensions {
|
||||
* 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.
|
||||
*
|
||||
* NOT pre-calibrated: 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). Treat `headingDegrees` as relative — let the user zero
|
||||
* it against a known direction rather than trusting it as true/magnetic north.
|
||||
*/
|
||||
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 {
|
||||
|
||||
@@ -67,6 +67,90 @@ export interface WindowLifecycleEvent {
|
||||
type: WindowLifecycleEventType;
|
||||
}
|
||||
|
||||
/** A magnetometer heading sample from {@link FaceclawExtensions.addCompassListener}. */
|
||||
export interface CompassReading {
|
||||
/** Magnetic heading in degrees [0, 360). */
|
||||
headingDegrees: 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 | Promise<unknown>;
|
||||
}
|
||||
|
||||
/**
|
||||
* The Faceclaw-only capability surface. Obtained via {@link getFaceclawExtensions}.
|
||||
* Every method is additive to the standard EvenHub SDK.
|
||||
@@ -117,6 +201,39 @@ export interface FaceclawExtensions {
|
||||
* 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.
|
||||
*
|
||||
* NOT pre-calibrated: 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). Treat `headingDegrees` as relative — let the user zero
|
||||
* it against a known direction rather than trusting it as true/magnetic north.
|
||||
*/
|
||||
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 {
|
||||
|
||||
Reference in new issue
Block a user