diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index dce2bfd9..d4d131ed 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -26,3 +26,19 @@ jobs: - uses: actions/checkout@v4 - run: npm ci - run: npm run test:kotlin + + # The @faceclaw/evenhub-extensions npm package: typecheck (including + # compatibility with the stock SDK's container classes), build, and check + # that the committed API reference matches the source. + evenhub-extensions: + runs-on: ubuntu-latest + defaults: + run: + working-directory: evenhub-extensions + steps: + - uses: actions/checkout@v4 + - run: npm ci + - run: npm run check + - run: npm run build + - run: npm run docs + - run: git diff --exit-code -- docs diff --git a/.oxlintrc.json b/.oxlintrc.json index 5f63cfb3..1be2a6ac 100644 --- a/.oxlintrc.json +++ b/.oxlintrc.json @@ -78,7 +78,7 @@ "node_modules/**", "platforms/**", "dist/**", - "faceclaw-extensions/dist/**", + "evenhub-extensions/dist/**", "old/**", "tmp/**" ] diff --git a/app/apps/evenhub/compass-router.ts b/app/apps/evenhub/compass-router.ts index e9a33d46..dd37814d 100644 --- a/app/apps/evenhub/compass-router.ts +++ b/app/apps/evenhub/compass-router.ts @@ -14,7 +14,7 @@ import { isCompassCalibrated } from "../compass/calibration"; import { refreshDeclination } from "../compass/declination"; import { resolveHeading } from "../compass/heading"; -/** Wire shape of the `compass` extension event (faceclaw-extensions `CompassReading`). */ +/** Wire shape of the `compass` extension event (@faceclaw/evenhub-extensions `CompassReading`). */ export type EvenHubCompassReading = { headingDegrees: number; magneticHeadingDegrees: number; diff --git a/app/apps/evenhub/containers.ts b/app/apps/evenhub/containers.ts index edd3c751..b62f631b 100644 --- a/app/apps/evenhub/containers.ts +++ b/app/apps/evenhub/containers.ts @@ -130,6 +130,17 @@ export function readString(obj: Record, key: string, fallback: return fallback; } +/** + * A 0/1 protobuf flag. Stock apps send numbers; extension layouts may send + * booleans (the extension types allow both), and numeric strings show up in + * the wild. + */ +function readFlag(obj: Record, key: string): boolean { + const value = pickLoose(obj, key); + if (typeof value === "boolean") return value; + return readNumber(obj, key, 0) !== 0; +} + export function asRecord(value: unknown): Record { return value && typeof value === "object" && !Array.isArray(value) ? (value as Record) : {}; } @@ -150,9 +161,9 @@ function parseTextContainer(json: Record): EvenHubTextContainer borderWidth: readBorderWidth(json), borderRadius: readNumber(json, "borderRadius", 0), paddingLength: readNumber(json, "paddingLength", 0), - isEventCapture: readNumber(json, "isEventCapture", 0) !== 0, + isEventCapture: readFlag(json, "isEventCapture"), zOrderIndex: readOptionalNumber(json, "zOrderIndex"), - preserve: readNumber(json, "preserve", 0) !== 0, + preserve: readFlag(json, "preserve"), content: readString(json, "content", ""), textColor: readTextBrightness(json), }; @@ -220,7 +231,7 @@ function parseImageContainer(json: Record): EvenHubImageContain width: readNumber(json, "width", 0), height: readNumber(json, "height", 0), zOrderIndex: readOptionalNumber(json, "zOrderIndex"), - preserve: readNumber(json, "preserve", 0) !== 0, + preserve: readFlag(json, "preserve"), pixels: null, pixelsWidth: 0, pixelsHeight: 0, @@ -242,12 +253,12 @@ function parseListContainer(json: Record): EvenHubListContainer borderWidth: readBorderWidth(json), borderRadius: readNumber(json, "borderRadius", 0), paddingLength: readNumber(json, "paddingLength", 0), - isEventCapture: readNumber(json, "isEventCapture", 0) !== 0, + isEventCapture: readFlag(json, "isEventCapture"), zOrderIndex: readOptionalNumber(json, "zOrderIndex"), - preserve: readNumber(json, "preserve", 0) !== 0, + preserve: readFlag(json, "preserve"), itemNames, itemWidth: readNumber(itemContainer, "itemWidth", 0), - selectBorder: readNumber(itemContainer, "isItemSelectBorderEn", 0) !== 0, + selectBorder: readFlag(itemContainer, "isItemSelectBorderEn"), selectedIndex: 0, }; } diff --git a/app/apps/evenhub/session.ts b/app/apps/evenhub/session.ts index 95957c1d..5fe23a25 100644 --- a/app/apps/evenhub/session.ts +++ b/app/apps/evenhub/session.ts @@ -226,9 +226,15 @@ 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). + * capabilities. Its public contract (the `FaceclawExtensions` interface) is + * the @faceclaw/evenhub-extensions package in evenhub-extensions/. Keep the + * two in step (tests/evenhub-extensions-shim.test.cjs checks the member list). + * When adding members, bump API_VERSION and tag them `@since apiVersion N` in + * the 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`. @@ -239,13 +245,15 @@ export function buildFaceclawExtensionsScript(versionString: string): string { (function () { if (window.getFaceclawExtensions) return; var VERSION = ${JSON.stringify(versionString)}; + var API_VERSION = 1; 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); + if (ok) entry[0](value); + else entry[1](new Error(String(value))); }; function call(method, params) { return new Promise(function (resolve, reject) { @@ -260,9 +268,10 @@ export function buildFaceclawExtensionsScript(versionString: string): string { } var listeners = {}; window.__fcExtEvent = function (name, data) { - var arr = listeners[name]; - if (!arr) return; - for (var i = 0; i < arr.slice().length; i++) { + // Iterate a snapshot, so a listener that unsubscribes mid-dispatch + // doesn't make the next one get skipped. + var arr = (listeners[name] || []).slice(); + for (var i = 0; i < arr.length; i++) { try { arr[i](data); } catch (e) { if (window.console) console.error(e); } } }; @@ -318,6 +327,7 @@ export function buildFaceclawExtensionsScript(versionString: string): string { send("setAssistantTools", [specs]); } var extensions = { + apiVersion: API_VERSION, getVersion: function () { return VERSION; }, returnToAppSwitcher: function () { send("returnToAppSwitcher"); }, quit: function () { send("quit"); }, diff --git a/evenhub-extensions/LICENSE b/evenhub-extensions/LICENSE new file mode 100644 index 00000000..2f6aa349 --- /dev/null +++ b/evenhub-extensions/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 James Babcock + +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. diff --git a/evenhub-extensions/README.md b/evenhub-extensions/README.md new file mode 100644 index 00000000..0e056c09 --- /dev/null +++ b/evenhub-extensions/README.md @@ -0,0 +1,202 @@ +# @faceclaw/evenhub-extensions + +Types and a small helper for EvenHub apps that want to use +[Faceclaw](https://github.com/jimrandomh/faceclaw)'s extension APIs. + +Faceclaw is an alternative host for EvenHub apps on the Even Realities G2 +glasses. An app built against the standard +[`@evenrealities/even_hub_sdk`](https://www.npmjs.com/package/@evenrealities/even_hub_sdk) +runs in Faceclaw unchanged. This package lets the app detect that it is +running in Faceclaw and use some extra capabilities there: a taller canvas, the +glasses' compass and buzzer, window lifecycle events, voice-assistant tools, and +the user's API keys (with their consent). In the stock Even app the extensions +are absent, and the app runs as usual. + +- [API reference](docs/api/README.md) + +## Install + +```sh +npm install @faceclaw/evenhub-extensions +``` + +The package has no dependencies. It contains TypeScript types and one small +function, and ships as both an ES module and CommonJS. + +## Quick start + +```ts +import { getFaceclawExtensions } from "@faceclaw/evenhub-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.8.2" + + // Pause work while the app isn't on screen. + fc.addWindowLifecycleListener((e) => { + if (e.type === "hidden") pause(); + if (e.type === "visible") resume(); + }); + + // Beep. + await fc.playBuzzer([ + { freq: 880, ms: 90 }, + { freq: 0, duty: 0, ms: 40 }, // a rest + { freq: 1320, ms: 160 }, + ]); +} +``` + +`getFaceclawExtensions()` returns `null` everywhere except inside Faceclaw: +in the stock Even app, in the EvenHub simulator, in a browser, and in Node. +Faceclaw installs the API before any page script runs, so you can call it at +startup. You don't need to wait for the bridge first. + +## How it works + +Faceclaw injects one global function, `window.getFaceclawExtensions`, into the +app's webview. Every extension lives behind it. Faceclaw doesn't modify the +standard SDK, other globals, or any built-in prototype, so an app that uses +the extensions keeps working in any other host. `getFaceclawExtensions()` in +this package checks whether that global exists and calls it. + +## Checking for features + +New members will be added over time, and an app may run in a Faceclaw build +that is older than the version of this package it was built against. Use +`apiVersion` to check before calling anything newer than level 1: + +```ts +const fc = getFaceclawExtensions(); +if (fc && fc.apiVersion >= 2) { + // Safe to use members marked "@since apiVersion 2" in the reference. +} +``` + +Everything in this release is API level 1. + +## TypeScript + +The types are bundled; there is no separate `@types` package. Importing +anything from the package also adds the global to `Window`, so +`window.getFaceclawExtensions` is typed throughout your program. + +If you use the global directly and never import the package, add it to +`compilerOptions.types` in your `tsconfig.json`: + +```json +{ "compilerOptions": { "types": ["@faceclaw/evenhub-extensions"] } } +``` + +## API overview + +The [API reference](docs/api/README.md) documents every member in full. + +| Member | What it does | +| --- | --- | +| `apiVersion` | The extension API level the host implements, for feature checks. | +| `getVersion()` | The host's name and version, e.g. `"Faceclaw/0.8.2"`. | +| `returnToAppSwitcher()` | Give focus back to the app switcher, and keep running. | +| `quit()` | Close the app. Faceclaw treats the stock `shutDownPageContainer(1)` as "return to the switcher", so use this to really quit. | +| `addWindowLifecycleListener(fn)` | `visible` / `hidden` and `focused` / `blurred` events. | +| `getConfiguredApiKeys()` | Which services the user has keys for (names only). | +| `requestApiKeyAccess(services)` | Ask the user, on the glasses, to share those keys with the app. | +| `playBuzzer(steps)` | Play a tone sequence on the glasses' buzzer. | +| `addCompassListener(fn)` | Turn on the magnetometer and receive headings. | +| `createLayout(layout)` / `replaceLayout(layout)` | Build the page on the full 576×452 canvas, with no container limit, and optionally keep content across layouts. | +| `setAssistantTools(tools)` | Offer tools to Faceclaw's voice assistant. | + +### Extended layout + +`createLayout` and `replaceLayout` take the same `textObject` / `imageObject` / +`listObject` / `menuObject` shape as the stock `createStartUpPageContainer` and +`rebuildPageContainer`, so you can keep using the stock SDK's container +classes. The differences: + +- The canvas is the full 576×452 app area instead of 576×288, and an image + container can fill it (the stock limit is 288×144). +- There is no limit on the number of containers. +- A container with `preserve: true` keeps the content (text, pixels, or list + items and selection) of the same-named container in the previous layout. + Without it, the container starts blank. + +```ts +import { ImageContainerProperty, TextContainerProperty } from "@evenrealities/even_hub_sdk"; + +await fc.createLayout({ + imageObject: [new ImageContainerProperty({ containerID: 1, containerName: "map", xPosition: 0, yPosition: 0, width: 576, height: 452 })], + textObject: [new TextContainerProperty({ containerID: 2, containerName: "hud", xPosition: 16, yPosition: 16, width: 300, height: 40, content: "Ready", isEventCapture: 1 })], +}); + +// Later: move the HUD, keeping the map's pixels. +await fc.replaceLayout({ + imageObject: [{ containerID: 1, containerName: "map", xPosition: 0, yPosition: 0, width: 576, height: 452, preserve: true }], + textObject: [{ containerID: 2, containerName: "hud", xPosition: 16, yPosition: 396, width: 300, height: 40, content: "Ready", isEventCapture: 1 }], +}); +``` + +Keep using the stock `updateImageRawData` and `textContainerUpgrade` to update +content; they address containers by `containerID`. Once an app has used an +extended layout, its window stays at 576×452 for the rest of the session. + +### Compass + +Each `CompassReading` has several headings, all in degrees clockwise from north: + +- `headingDegrees` is the raw reading. The magnetometer is in the right arm, + which sits at a slightly different angle on every wearer, so this heading is + only relative. +- `magneticHeadingDegrees` adds the wearer's calibration from Faceclaw's + Compass app. `wearerCalibrated` says whether they have calibrated. +- `trueHeadingDegrees` also corrects for local magnetic declination. It is + absent when Faceclaw doesn't know the phone's location. + +Use `trueHeadingDegrees` when it is present, and otherwise +`magneticHeadingDegrees`. If `wearerCalibrated` is false, treat the heading as +relative, or let the user set their own zero. + +Readings arrive only while the app is in the foreground. The sensor turns off +when the last listener unsubscribes. + +### 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" (the default) + handler: ({ bpm }: { bpm: number }) => { + setTempo(bpm); + return `Tempo is now ${bpm}.`; + }, + }, +]); +``` + +The assistant sees each tool under your package name, as +`app..set_bpm`. Whatever the handler returns is reported back to +the assistant. If it throws, the assistant gets the error message. Tools are +removed when the app closes; call `setAssistantTools([])` to remove them +sooner. + +### API keys + +`getConfiguredApiKeys()` tells you which services (`openai`, `anthropic`, +`soniox`, `elevenlabs`, `mapbox`) the user has keys for, without revealing the +keys. `requestApiKeyAccess(services)` shows a consent prompt on the glasses and +resolves with the keys the user agreed to share. If the user declines, it +resolves to `{}`. A grant lasts until the app closes. + +## Stability + +This package is pre-1.0. Until 1.0 the API may still change. After that, changes +will only add new members, gated by `apiVersion`. + +## License + +MIT. Faceclaw itself is GPL-3.0, but this package is MIT-licensed so that apps +under any license can use it. diff --git a/evenhub-extensions/docs/api/README.md b/evenhub-extensions/docs/api/README.md new file mode 100644 index 00000000..62b3bfdf --- /dev/null +++ b/evenhub-extensions/docs/api/README.md @@ -0,0 +1,559 @@ +# @faceclaw/evenhub-extensions + +Types and a small helper for the Faceclaw extension API. + +[Faceclaw](https://github.com/jimrandomh/faceclaw) is an alternative host for +EvenHub apps: it runs them on the Even Realities G2 glasses without the stock +Even app. An app built against the standard `@evenrealities/even_hub_sdk` +runs unchanged. This package lets such an app detect that it is running +inside Faceclaw and use a few extra, Faceclaw-only capabilities. + +The only entry point is the injected global `window.getFaceclawExtensions`, +which is a function inside Faceclaw and `undefined` in the stock Even app and +every other host. Nothing on the standard SDK, on `window`, or on any built-in +prototype is modified, so an app that uses these extensions still runs +everywhere else; it just skips the extras. + +## Example + +```ts +import { getFaceclawExtensions } from "@faceclaw/evenhub-extensions"; + +const fc = getFaceclawExtensions(); +if (fc) { + console.log("Running in", fc.getVersion()); // "Faceclaw/0.8.2" + fc.addWindowLifecycleListener((e) => { + if (e.type === "hidden") pauseExpensiveWork(); + }); +} +``` + +## Entry point + +### FaceclawExtensions + +The Faceclaw-only capability surface, obtained with [getFaceclawExtensions](#getfaceclawextensions). +Everything here is in addition to the standard EvenHub SDK. + +Calls that return a promise reject with an `Error` if the host fails to +carry them out. + +#### Properties + +| Property | Modifier | Type | Description | +| ------ | ------ | ------ | ------ | +| `apiVersion` | `readonly` | `number` | The extension API level the host implements. It is `1` for the API described here, and increases by one each time members are added. Members added later are documented with the level that introduced them, so an app can check for them before calling: `if (fc.apiVersion >= 2) fc.someNewerMethod();` | + +#### Methods + +##### getVersion() + +```ts +getVersion(): string; +``` + +The host's name and version, for example `"Faceclaw/0.8.2"`. For display +and logging; use [FaceclawExtensions.apiVersion](#property-apiversion) for feature checks. + +###### Returns + +`string` + +##### returnToAppSwitcher() + +```ts +returnToAppSwitcher(): void; +``` + +Hand input focus back to Faceclaw's app switcher without closing the app, +which keeps running in the background. + +###### Returns + +`void` + +##### quit() + +```ts +quit(): void; +``` + +Close this app and tear down its window. + +Faceclaw treats the stock `shutDownPageContainer(1)` as "return to the app +switcher", so apps that quit on double-tap stay alive. This method always +quits. + +###### Returns + +`void` + +##### addWindowLifecycleListener() + +```ts +addWindowLifecycleListener(listener): () => void; +``` + +Subscribe to window lifecycle changes (see [WindowLifecycleEventType](#windowlifecycleeventtype)). + +###### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `listener` | (`event`) => `void` | Called on each transition. | + +###### Returns + +A function that unsubscribes `listener`. + +() => `void` + +##### getConfiguredApiKeys() + +```ts +getConfiguredApiKeys(): Promise; +``` + +List the services whose API keys the user has configured in Faceclaw. This +returns only the service names, never the keys, and doesn't prompt the user. +Use [FaceclawExtensions.requestApiKeyAccess](#requestapikeyaccess) to obtain the keys. + +###### Returns + +`Promise`\<[`ApiKeyService`](#apikeyservice)[]\> + +##### requestApiKeyAccess() + +```ts +requestApiKeyAccess(services): Promise>>; +``` + +Ask the user to share one or more configured API keys with this app. This +opens a consent prompt on the glasses, unless the user already granted +these services to this app earlier in the session. + +###### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `services` | [`ApiKeyService`](#apikeyservice)[] | The services whose keys the app wants. | + +###### Returns + +`Promise`\<`Partial`\<`Record`\<[`ApiKeyService`](#apikeyservice), `string`\>\>\> + +A map from service to key, containing only the services that were + both requested and configured. It is empty if the user declines. + +##### playBuzzer() + +```ts +playBuzzer(steps): Promise; +``` + +Play a tone sequence on the glasses' piezo buzzer. Sequences longer than the +firmware's per-message limit of 48 steps are split and paced automatically. + +###### Parameters + +| Parameter | Type | +| ------ | ------ | +| `steps` | [`BuzzerStep`](#buzzerstep)[] | + +###### Returns + +`Promise`\<`void`\> + +A promise that resolves once every part of the sequence has been + queued on the glasses, which can be before it finishes playing. + +##### addCompassListener() + +```ts +addCompassListener(listener): () => void; +``` + +Turn on the glasses' magnetometer and receive heading samples. The sensor +stays on while at least one listener is registered, and readings are only +delivered while the app is the foreground window. + +The magnetometer sits inside the right arm, which rests against the wearer's +head at an angle that differs between wearers (and between wears), so the +raw heading is only relative. See [CompassReading](#compassreading) for the corrected +headings and when to trust them. + +###### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `listener` | (`reading`) => `void` | Called with each sample. | + +###### Returns + +A function that unsubscribes `listener`. + +() => `void` + +##### createLayout() + +```ts +createLayout(layout): Promise; +``` + +Build the app's page from an extended layout. This is a superset of the +stock `createStartUpPageContainer`; see [FaceclawLayout](#faceclawlayout) for the +differences. + +Unlike the stock call it may be called more than once. Once an app uses an +extended layout, its window stays at the full 576×452 size for the rest of +the session, including for later stock `rebuildPageContainer` calls. + +###### Parameters + +| Parameter | Type | +| ------ | ------ | +| `layout` | [`FaceclawLayout`](#faceclawlayout) | + +###### Returns + +`Promise`\<`boolean`\> + +A promise that resolves to true on success. + +##### replaceLayout() + +```ts +replaceLayout(layout): Promise; +``` + +Replace the current page with a new extended layout. This is a superset of +the stock `rebuildPageContainer`. Containers marked `preserve` inherit +their content from the same-named container in the outgoing layout. + +###### Parameters + +| Parameter | Type | +| ------ | ------ | +| `layout` | [`FaceclawLayout`](#faceclawlayout) | + +###### Returns + +`Promise`\<`boolean`\> + +A promise that resolves to true on success. + +##### setAssistantTools() + +```ts +setAssistantTools(tools): void; +``` + +Declare the app's voice-assistant tools, replacing any set earlier. Each +tool's `handler` runs in the app when the assistant calls it. + +###### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `tools` | [`AssistantTool`](#assistanttool)\<`any`\>[] | The tools to offer. Pass `[]` to remove them all. | + +###### Returns + +`void` + +*** + +### getFaceclawExtensions() + +```ts +function getFaceclawExtensions(): FaceclawExtensions | null; +``` + +Return the Faceclaw extension API if the app is running inside Faceclaw, or +`null` otherwise (in the stock Even app, a browser, a simulator, or Node). +Safe to call anywhere, at any time; Faceclaw installs the API before any page +script runs. + +#### Returns + +[`FaceclawExtensions`](#faceclawextensions) \| `null` + +## Window lifecycle + +### WindowLifecycleEventType + +```ts +type WindowLifecycleEventType = "visible" | "hidden" | "focused" | "blurred"; +``` + +A window lifecycle transition, delivered to +[FaceclawExtensions.addWindowLifecycleListener](#addwindowlifecyclelistener). + +- `visible` / `hidden`: the app's glasses window became the shown surface, or + stopped being it. This happens when the user switches the foreground window + or the phone screen turns on or 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 (for + example, the user opened the app switcher). A blurred app can still be + visible, but it doesn't receive taps or scrolls. + +An app can assume it starts `visible` and `focused` at launch. Events report +changes from there. + +*** + +### WindowLifecycleEvent + +Payload of a [FaceclawExtensions.addWindowLifecycleListener](#addwindowlifecyclelistener) callback. + +#### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `type` | [`WindowLifecycleEventType`](#windowlifecycleeventtype) | Which transition happened. | + +## API keys + +### ApiKeyService + +```ts +type ApiKeyService = "openai" | "anthropic" | "soniox" | "elevenlabs" | "mapbox"; +``` + +Third-party services whose API keys the user may have configured in Faceclaw. + +## Buzzer + +### BuzzerStep + +One step of a piezo-buzzer tone sequence. The G2 has a single monophonic PWM +buzzer, and the firmware plays a sequence's steps back to back on its own timer. + +#### Properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `freq` | `number` | `undefined` | Tone frequency in Hz. The piezo is loudest around 1–4 kHz and faint below about 150 Hz. | +| `ms` | `number` | `undefined` | Step duration in milliseconds (1–65535). | +| `duty?` | `number` | `50` | PWM duty cycle, 0–100. Use `duty: 0` for a rest (silence) lasting `ms`. | + +## Compass + +### CompassReading + +A magnetometer heading sample from [FaceclawExtensions.addCompassListener](#addcompasslistener). +All headings are in degrees clockwise, in the range [0, 360). + +Prefer `trueHeadingDegrees` when it is present, then `magneticHeadingDegrees`. +If `wearerCalibrated` is false, treat both as relative headings, or let the +user zero them. + +#### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `headingDegrees` | `number` | Raw magnetic heading as reported by the glasses, with no correction for how they sit on the wearer's head. It is kept for apps that zero it themselves. | +| `magneticHeadingDegrees` | `number` | Magnetic heading corrected by the wearer's calibration offset from Faceclaw's Compass app. Equal to `headingDegrees` until the wearer calibrates. | +| `wearerCalibrated` | `boolean` | Whether the wearer has calibrated the compass in Faceclaw's Compass app. Only trust `magneticHeadingDegrees` and `trueHeadingDegrees` as absolute headings when this is true. | +| `declinationDegrees?` | `number` | Local magnetic declination in degrees (east positive), computed from the phone's location and the World Magnetic Model. Absent when Faceclaw has no location fix or no location permission. | +| `trueHeadingDegrees?` | `number` | `magneticHeadingDegrees` plus declination. Absent when `declinationDegrees` is. | + +## Extended layout + +### FaceclawContainerCommon + +Fields shared by every container in a [FaceclawLayout](#faceclawlayout). They match the +stock SDK's container-property classes, plus `preserve`. + +As in the stock SDK every field is optional, so the stock +`TextContainerProperty`, `ImageContainerProperty` and `ListContainerProperty` +classes can be passed directly. In practice you should set `containerID`, +`containerName` and the geometry on every container. + +#### Extended by + +- [`FaceclawTextContainer`](#faceclawtextcontainer) +- [`FaceclawListContainer`](#faceclawlistcontainer) + +#### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `containerID?` | `number` | Container identity. Stock content updates (`textContainerUpgrade`, `updateImageRawData`) address containers by this ID. | +| `containerName?` | `string` | Container name. `preserve` matches containers across layouts by name. | +| `xPosition?` | `number` | Left edge in pixels on the 576×452 canvas. | +| `yPosition?` | `number` | Top edge in pixels on the 576×452 canvas. | +| `width?` | `number` | Width in pixels. | +| `height?` | `number` | Height in pixels. | +| `zOrderIndex?` | `number` | Stacking order: higher values draw on top. | +| `isEventCapture?` | `number` \| `boolean` | When set to `1`/`true`, this container receives the app's tap and scroll events. Exactly one text or list container per layout should capture events. | +| `preserve?` | `boolean` | When true, inherit content (text, image pixels, or list items and selection) from the container of the same kind and `containerName` in the previous layout. Otherwise the container starts blank. | + +*** + +### FaceclawTextContainer + +A text container. The fields match the stock SDK's `TextContainerProperty`, plus `preserve`. + +#### Extends + +- [`FaceclawContainerCommon`](#faceclawcontainercommon) + +#### Properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `containerID?` | `number` | `undefined` | Container identity. Stock content updates (`textContainerUpgrade`, `updateImageRawData`) address containers by this ID. | +| `containerName?` | `string` | `undefined` | Container name. `preserve` matches containers across layouts by name. | +| `xPosition?` | `number` | `undefined` | Left edge in pixels on the 576×452 canvas. | +| `yPosition?` | `number` | `undefined` | Top edge in pixels on the 576×452 canvas. | +| `width?` | `number` | `undefined` | Width in pixels. | +| `height?` | `number` | `undefined` | Height in pixels. | +| `zOrderIndex?` | `number` | `undefined` | Stacking order: higher values draw on top. | +| `isEventCapture?` | `number` \| `boolean` | `undefined` | When set to `1`/`true`, this container receives the app's tap and scroll events. Exactly one text or list container per layout should capture events. | +| `preserve?` | `boolean` | `undefined` | When true, inherit content (text, image pixels, or list items and selection) from the container of the same kind and `containerName` in the previous layout. Otherwise the container starts blank. | +| `content?` | `string` | `undefined` | Text to show. Update it later with the stock `textContainerUpgrade`. | +| `textColor?` | `number` | `4` | Text brightness level, 0–4. | +| `borderWidth?` | `number` | `undefined` | Border width in pixels, 0–5. Wider values are clamped. | +| `borderColor?` | `number` | `undefined` | Accepted for compatibility with stock payloads. Faceclaw currently ignores it. | +| `borderRadius?` | `number` | `undefined` | Border corner radius in pixels. | +| `paddingLength?` | `number` | `undefined` | Padding between the border and the text, in pixels. | + +*** + +### FaceclawImageContainer + +```ts +type FaceclawImageContainer = FaceclawContainerCommon; +``` + +An image container. The fields match the stock SDK's `ImageContainerProperty`, +plus `preserve`. + +In the extended layout an image container may be as large as the whole +576×452 canvas; the stock limit is 288×144. Push pixels with the stock +`updateImageRawData`, which in Faceclaw accepts PNG, uncompressed BMP, or raw +grayscale sized to the container (8 bits per pixel, or 4 bits per pixel packed +two to a byte, high nibble first). + +*** + +### FaceclawListItems + +The items of a [FaceclawListContainer](#faceclawlistcontainer). Matches the stock `ListItemContainerProperty`. + +#### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `itemName?` | `string`[] | Item labels, in display order. | +| `itemCount?` | `number` | Accepted for compatibility with stock payloads. The length of `itemName` is used instead. | +| `itemWidth?` | `number` | Fixed width of each item's selection outline in pixels. `0` (the default) hugs the text. | +| `isItemSelectBorderEn?` | `number` \| `boolean` | Whether the selected item is outlined. | + +*** + +### FaceclawListContainer + +A list container. The fields match the stock SDK's `ListContainerProperty`, plus `preserve`. + +#### Extends + +- [`FaceclawContainerCommon`](#faceclawcontainercommon) + +#### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `containerID?` | `number` | Container identity. Stock content updates (`textContainerUpgrade`, `updateImageRawData`) address containers by this ID. | +| `containerName?` | `string` | Container name. `preserve` matches containers across layouts by name. | +| `xPosition?` | `number` | Left edge in pixels on the 576×452 canvas. | +| `yPosition?` | `number` | Top edge in pixels on the 576×452 canvas. | +| `width?` | `number` | Width in pixels. | +| `height?` | `number` | Height in pixels. | +| `zOrderIndex?` | `number` | Stacking order: higher values draw on top. | +| `isEventCapture?` | `number` \| `boolean` | When set to `1`/`true`, this container receives the app's tap and scroll events. Exactly one text or list container per layout should capture events. | +| `preserve?` | `boolean` | When true, inherit content (text, image pixels, or list items and selection) from the container of the same kind and `containerName` in the previous layout. Otherwise the container starts blank. | +| `itemContainer?` | [`FaceclawListItems`](#faceclawlistitems) | The list's items and selection style. | +| `borderWidth?` | `number` | Border width in pixels, 0–5. Wider values are clamped. | +| `borderColor?` | `number` | Accepted for compatibility with stock payloads. Faceclaw currently ignores it. | +| `borderRadius?` | `number` | Border corner radius in pixels. | +| `paddingLength?` | `number` | Padding between the border and the items, in pixels. | + +*** + +### FaceclawMenu + +The page's contextual menu. Matches the stock SDK's `MenuContainerProperty`, +with the same limits: at most 10 items, each `itemID` a unique non-zero +uint32, and each `itemName` at most 32 UTF-8 bytes. Selections arrive as the +stock `menuItemClickEvent`. + +#### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `menuItems?` | `object`[] | Menu entries, in display order. | + +*** + +### FaceclawLayout + +A page layout for [FaceclawExtensions.createLayout](#createlayout) and +[FaceclawExtensions.replaceLayout](#replacelayout). + +It has the same shape as the stock `CreateStartUpPageContainer` / +`RebuildPageContainer`, so you can build it with the stock SDK's container +classes, with three differences: + +- The canvas is the full 576×452 app area instead of 576×288, so image + containers may be up to 576×452. +- There is no limit on the number of containers. +- Each container may set `preserve: true` to inherit its content from the + same-named container in the previous layout. + +#### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `textObject?` | [`FaceclawTextContainer`](#faceclawtextcontainer)[] | Text containers. | +| `imageObject?` | [`FaceclawContainerCommon`](#faceclawcontainercommon)[] | Image containers. | +| `listObject?` | [`FaceclawListContainer`](#faceclawlistcontainer)[] | List containers. | +| `menuObject?` | [`FaceclawMenu`](#faceclawmenu) | The page's contextual menu. Omit it to clear any previous menu. | +| `containerTotalNum?` | `number` | Accepted for compatibility with stock payloads and ignored: there is no container limit. | + +## Assistant tools + +### JsonSchema + +```ts +type JsonSchema = Record; +``` + +A JSON Schema object describing a tool's arguments. + +*** + +### AssistantTool + +A tool the app contributes to Faceclaw's voice assistant, for use with +[FaceclawExtensions.setAssistantTools](#setassistanttools). + +The assistant sees the tool namespaced by the app's package name, as +`app..`. `name` here is the bare name without that prefix. + +#### Type Parameters + +| Type Parameter | Default type | Description | +| ------ | ------ | ------ | +| `Args` | `any` | The arguments object the assistant passes to `handler`, as described by `parameters`. | + +#### Properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `name` | `string` | `undefined` | Bare tool name (no package prefix), for example `"set_color"`. | +| `description` | `string` | `undefined` | What the tool does. The assistant reads this to decide when to call it. | +| `parameters?` | [`JsonSchema`](#jsonschema) | `{ type: "object", properties: {} }` | JSON Schema for the arguments object the assistant will pass to `handler`. | +| `availability?` | `"open"` \| `"foreground"` | `"foreground"` | When the tool can be called: `"foreground"` only while the app owns the visible window, or `"open"` any time the app is running, including in the background. | +| `handler` | (`args`) => `unknown` | `undefined` | Called when the assistant invokes the tool. Return a string, or any JSON-serializable value, to report back to the assistant. Throw (or reject) to report an error. May be async. | diff --git a/evenhub-extensions/package-lock.json b/evenhub-extensions/package-lock.json new file mode 100644 index 00000000..72a42897 --- /dev/null +++ b/evenhub-extensions/package-lock.json @@ -0,0 +1,1817 @@ +{ + "name": "faceclaw-extensions", + "version": "0.1.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "faceclaw-extensions", + "version": "0.1.0", + "license": "MIT", + "devDependencies": { + "@evenrealities/even_hub_sdk": "^0.0.16", + "tsup": "^8.5.1", + "typedoc": "^0.28.20", + "typedoc-plugin-markdown": "^4.13.1", + "typescript": "~5.9.0" + } + }, + "node_modules/@esbuild/aix-ppc64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.27.7.tgz", + "integrity": "sha512-EKX3Qwmhz1eMdEJokhALr0YiD0lhQNwDqkPYyPhiSwKrh7/4KRjQc04sZ8db+5DVVnZ1LmbNDI1uAMPEUBnQPg==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "aix" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-arm": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.27.7.tgz", + "integrity": "sha512-jbPXvB4Yj2yBV7HUfE2KHe4GJX51QplCN1pGbYjvsyCZbQmies29EoJbkEc+vYuU5o45AfQn37vZlyXy4YJ8RQ==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-arm64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.27.7.tgz", + "integrity": "sha512-62dPZHpIXzvChfvfLJow3q5dDtiNMkwiRzPylSCfriLvZeq0a1bWChrGx/BbUbPwOrsWKMn8idSllklzBy+dgQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-x64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.27.7.tgz", + "integrity": "sha512-x5VpMODneVDb70PYV2VQOmIUUiBtY3D3mPBG8NxVk5CogneYhkR7MmM3yR/uMdITLrC1ml/NV1rj4bMJuy9MCg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/darwin-arm64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.27.7.tgz", + "integrity": "sha512-5lckdqeuBPlKUwvoCXIgI2D9/ABmPq3Rdp7IfL70393YgaASt7tbju3Ac+ePVi3KDH6N2RqePfHnXkaDtY9fkw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/darwin-x64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.27.7.tgz", + "integrity": "sha512-rYnXrKcXuT7Z+WL5K980jVFdvVKhCHhUwid+dDYQpH+qu+TefcomiMAJpIiC2EM3Rjtq0sO3StMV/+3w3MyyqQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/freebsd-arm64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.27.7.tgz", + "integrity": "sha512-B48PqeCsEgOtzME2GbNM2roU29AMTuOIN91dsMO30t+Ydis3z/3Ngoj5hhnsOSSwNzS+6JppqWsuhTp6E82l2w==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/freebsd-x64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.27.7.tgz", + "integrity": "sha512-jOBDK5XEjA4m5IJK3bpAQF9/Lelu/Z9ZcdhTRLf4cajlB+8VEhFFRjWgfy3M1O4rO2GQ/b2dLwCUGpiF/eATNQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-arm": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.27.7.tgz", + "integrity": "sha512-RkT/YXYBTSULo3+af8Ib0ykH8u2MBh57o7q/DAs3lTJlyVQkgQvlrPTnjIzzRPQyavxtPtfg0EopvDyIt0j1rA==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-arm64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.27.7.tgz", + "integrity": "sha512-RZPHBoxXuNnPQO9rvjh5jdkRmVizktkT7TCDkDmQ0W2SwHInKCAV95GRuvdSvA7w4VMwfCjUiPwDi0ZO6Nfe9A==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-ia32": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.27.7.tgz", + "integrity": "sha512-GA48aKNkyQDbd3KtkplYWT102C5sn/EZTY4XROkxONgruHPU72l+gW+FfF8tf2cFjeHaRbWpOYa/uRBz/Xq1Pg==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-loong64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.27.7.tgz", + "integrity": "sha512-a4POruNM2oWsD4WKvBSEKGIiWQF8fZOAsycHOt6JBpZ+JN2n2JH9WAv56SOyu9X5IqAjqSIPTaJkqN8F7XOQ5Q==", + "cpu": [ + "loong64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-mips64el": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.27.7.tgz", + "integrity": "sha512-KabT5I6StirGfIz0FMgl1I+R1H73Gp0ofL9A3nG3i/cYFJzKHhouBV5VWK1CSgKvVaG4q1RNpCTR2LuTVB3fIw==", + "cpu": [ + "mips64el" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-ppc64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.27.7.tgz", + "integrity": "sha512-gRsL4x6wsGHGRqhtI+ifpN/vpOFTQtnbsupUF5R5YTAg+y/lKelYR1hXbnBdzDjGbMYjVJLJTd2OFmMewAgwlQ==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-riscv64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.27.7.tgz", + "integrity": "sha512-hL25LbxO1QOngGzu2U5xeXtxXcW+/GvMN3ejANqXkxZ/opySAZMrc+9LY/WyjAan41unrR3YrmtTsUpwT66InQ==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-s390x": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.27.7.tgz", + "integrity": "sha512-2k8go8Ycu1Kb46vEelhu1vqEP+UeRVj2zY1pSuPdgvbd5ykAw82Lrro28vXUrRmzEsUV0NzCf54yARIK8r0fdw==", + "cpu": [ + "s390x" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-x64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.27.7.tgz", + "integrity": "sha512-hzznmADPt+OmsYzw1EE33ccA+HPdIqiCRq7cQeL1Jlq2gb1+OyWBkMCrYGBJ+sxVzve2ZJEVeePbLM2iEIZSxA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/netbsd-arm64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.27.7.tgz", + "integrity": "sha512-b6pqtrQdigZBwZxAn1UpazEisvwaIDvdbMbmrly7cDTMFnw/+3lVxxCTGOrkPVnsYIosJJXAsILG9XcQS+Yu6w==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/netbsd-x64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.27.7.tgz", + "integrity": "sha512-OfatkLojr6U+WN5EDYuoQhtM+1xco+/6FSzJJnuWiUw5eVcicbyK3dq5EeV/QHT1uy6GoDhGbFpprUiHUYggrw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openbsd-arm64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.27.7.tgz", + "integrity": "sha512-AFuojMQTxAz75Fo8idVcqoQWEHIXFRbOc1TrVcFSgCZtQfSdc1RXgB3tjOn/krRHENUB4j00bfGjyl2mJrU37A==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openbsd-x64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.27.7.tgz", + "integrity": "sha512-+A1NJmfM8WNDv5CLVQYJ5PshuRm/4cI6WMZRg1by1GwPIQPCTs1GLEUHwiiQGT5zDdyLiRM/l1G0Pv54gvtKIg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openharmony-arm64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.27.7.tgz", + "integrity": "sha512-+KrvYb/C8zA9CU/g0sR6w2RBw7IGc5J2BPnc3dYc5VJxHCSF1yNMxTV5LQ7GuKteQXZtspjFbiuW5/dOj7H4Yw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openharmony" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/sunos-x64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.27.7.tgz", + "integrity": "sha512-ikktIhFBzQNt/QDyOL580ti9+5mL/YZeUPKU2ivGtGjdTYoqz6jObj6nOMfhASpS4GU4Q/Clh1QtxWAvcYKamA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "sunos" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-arm64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.27.7.tgz", + "integrity": "sha512-7yRhbHvPqSpRUV7Q20VuDwbjW5kIMwTHpptuUzV+AA46kiPze5Z7qgt6CLCK3pWFrHeNfDd1VKgyP4O+ng17CA==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-ia32": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.27.7.tgz", + "integrity": "sha512-SmwKXe6VHIyZYbBLJrhOoCJRB/Z1tckzmgTLfFYOfpMAx63BJEaL9ExI8x7v0oAO3Zh6D/Oi1gVxEYr5oUCFhw==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-x64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.27.7.tgz", + "integrity": "sha512-56hiAJPhwQ1R4i+21FVF7V8kSD5zZTdHcVuRFMW0hn753vVfQN8xlx4uOPT4xoGH0Z/oVATuR82AiqSTDIpaHg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@evenrealities/even_hub_sdk": { + "version": "0.0.16", + "resolved": "https://registry.npmjs.org/@evenrealities/even_hub_sdk/-/even_hub_sdk-0.0.16.tgz", + "integrity": "sha512-8/qMR4W3vna6xAM5/dFDmKoTR98D7Vo3TDBrtS0JgdUSvBVyAnUXuhODI3H587fI2TfLbp4T+FNT3EdkB3+Big==", + "dev": true, + "license": "MIT", + "engines": { + "node": "^20.0.0 || >=22.0.0" + } + }, + "node_modules/@gerrit0/mini-shiki": { + "version": "3.23.0", + "resolved": "https://registry.npmjs.org/@gerrit0/mini-shiki/-/mini-shiki-3.23.0.tgz", + "integrity": "sha512-bEMORlG0cqdjVyCEuU0cDQbORWX+kYCeo0kV1lbxF5bt4r7SID2l9bqsxJEM0zndaxpOUT7riCyIVEuqq/Ynxg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/engine-oniguruma": "^3.23.0", + "@shikijs/langs": "^3.23.0", + "@shikijs/themes": "^3.23.0", + "@shikijs/types": "^3.23.0", + "@shikijs/vscode-textmate": "^10.0.2" + } + }, + "node_modules/@jridgewell/gen-mapping": { + "version": "0.3.13", + "resolved": "https://registry.npmjs.org/@jridgewell/gen-mapping/-/gen-mapping-0.3.13.tgz", + "integrity": "sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@jridgewell/sourcemap-codec": "^1.5.0", + "@jridgewell/trace-mapping": "^0.3.24" + } + }, + "node_modules/@jridgewell/resolve-uri": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz", + "integrity": "sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6.0.0" + } + }, + "node_modules/@jridgewell/sourcemap-codec": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.6.0.tgz", + "integrity": "sha512-T7jf+5zgsZHwNJ4lvQ7/aezbyk0nNX+zJVWpmHA7VYsEx7a7qr5Rg5IbtJFqkgze5Y2sruq1RUY8Q837Od7iFw==", + "dev": true, + "license": "MIT" + }, + "node_modules/@jridgewell/trace-mapping": { + "version": "0.3.31", + "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.31.tgz", + "integrity": "sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@jridgewell/resolve-uri": "^3.1.0", + "@jridgewell/sourcemap-codec": "^1.4.14" + } + }, + "node_modules/@napi-rs/lzma-linux-x64-gnu": { + "version": "1.5.1", + "resolved": "https://registry.npmjs.org/@napi-rs/lzma-linux-x64-gnu/-/lzma-linux-x64-gnu-1.5.1.tgz", + "integrity": "sha512-oTXEIha4SsuXdTA4Iyskj0kpdx2yVXdhd75c2v3xGrHFfVMsbhTPZU/nMPL4sWKo4pBHm3aucLaqGlF696dTyQ==", + "cpu": [ + "x64" + ], + "dev": true, + "libc": [ + "glibc" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": "^22.20 || ^24.12 || >=25" + } + }, + "node_modules/@rollup/rollup-android-arm-eabi": { + "version": "4.64.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.64.0.tgz", + "integrity": "sha512-FLLpX941CD/7aBvX3GqLGBM9OvY5PGXTryPJkG5r5/OuBpZpV5k45Uo3RxAvqd35tsyc3hH1bhtz921IKzoIzg==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ] + }, + "node_modules/@rollup/rollup-android-arm64": { + "version": "4.64.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.64.0.tgz", + "integrity": "sha512-iI32XM/jnDYJsvx5ai/za/7gWO9XoSeFFtU06/ZCaRgyilfJOjaopD3nOpk2WrTCGOyeDt4hleUiGOAnd5tHNg==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ] + }, + "node_modules/@rollup/rollup-darwin-arm64": { + "version": "4.64.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.64.0.tgz", + "integrity": "sha512-dRBZlbt2sEtF8Mn4MODThze9fIPdDoOhVSlXMAKy5dQbOYK9pOOoPY4Fat3OTtr0+8zbJo5TTZwlsfxY/kDNJg==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ] + }, + "node_modules/@rollup/rollup-darwin-x64": { + "version": "4.64.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.64.0.tgz", + "integrity": "sha512-Y3whrJOMucfkhgNkvcM93M6j8C53iEAMmPMYD99C6G1kUy4ELigLWk9ar2/4aCBSRgsql0zdlOemLgW2m5GZgQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ] + }, + "node_modules/@rollup/rollup-freebsd-arm64": { + "version": "4.64.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.64.0.tgz", + "integrity": "sha512-S6S1GEzPjFF6IONYJX3AKt/799+8RgBgCcwRnUo+Ep1IvBxUbw5M51iU0TDdK2NWWVnSvCQ8yi6Em0fGASMOng==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ] + }, + "node_modules/@rollup/rollup-freebsd-x64": { + "version": "4.64.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.64.0.tgz", + "integrity": "sha512-Ed1DPoFENkXj4IGzSB12SesV40iP6LxCCrbTIkSGIQBpOOxpBM+0kj62lmaeIHfMWTDoddqTOtqc7s8LYfn+Pw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ] + }, + "node_modules/@rollup/rollup-linux-arm-gnueabihf": { + "version": "4.64.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.64.0.tgz", + "integrity": "sha512-J/6xhutJPtFyIkmHdf4olOdHHKH5kOJNumojdWn+Elv5ICEYTVOa362Vw27TxsK0BLzb1le3EDlO3UbvFK1lnQ==", + "cpu": [ + "arm" + ], + "dev": true, + "libc": [ + "glibc" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-arm-musleabihf": { + "version": "4.64.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.64.0.tgz", + "integrity": "sha512-G4L/Nnx59d2LvDoV/P4S5lZ7oVLT6hodOHMacqjiq2LL2gts86KbkEBTYL53+fBt0odhf7XPIbIATGoYiJctxg==", + "cpu": [ + "arm" + ], + "dev": true, + "libc": [ + "musl" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-arm64-gnu": { + "version": "4.64.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.64.0.tgz", + "integrity": "sha512-zF16pvJDEUksGYRbfnXne7pdklAyj2XDmJeYKgP93oq0cUyX9Y8O7lUo1R+IY1GagP/YBvCEDCe7eEcAKpw//g==", + "cpu": [ + "arm64" + ], + "dev": true, + "libc": [ + "glibc" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-arm64-musl": { + "version": "4.64.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.64.0.tgz", + "integrity": "sha512-nIggWn8n+w12+R5lsV+PYYoUY8vuObxPAQqJI7WES+9v0qspYuAHoZMfYM0yLxlipasT5BY9ht5W8t5c/rSCkg==", + "cpu": [ + "arm64" + ], + "dev": true, + "libc": [ + "musl" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-loong64-gnu": { + "version": "4.64.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.64.0.tgz", + "integrity": "sha512-WLOTiHPzszP0dxIMsHpFeDSOSB5I49Mj8K4+yKE3H1X/D0JRG5XZ5jrctJLMjnUc/LUzaKiwq6EHWNJ8pup8PA==", + "cpu": [ + "loong64" + ], + "dev": true, + "libc": [ + "glibc" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-loong64-musl": { + "version": "4.64.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.64.0.tgz", + "integrity": "sha512-35RK9aRhh7g7Pmeu5gQ01aCvrhXzj9LoBE6xtUcEH1ns+nyTaSzxSpADmBQINu4QiTDGvmQYwo1j5hlg1rRXFw==", + "cpu": [ + "loong64" + ], + "dev": true, + "libc": [ + "musl" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-ppc64-gnu": { + "version": "4.64.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.64.0.tgz", + "integrity": "sha512-RqTfnpoTjuWfPAmqK5p2edt2AMCDJWm6oTn7sKfmyx+6tRga0ip05SJ977o6udTcIiDeF/CJMUfkaN4gtWt6Aw==", + "cpu": [ + "ppc64" + ], + "dev": true, + "libc": [ + "glibc" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-ppc64-musl": { + "version": "4.64.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.64.0.tgz", + "integrity": "sha512-RQjZPigjxFvFZDijG6rjlSXxhRaTf9zLYVpGK+lVcga64oMqP1GbgVqCb46eHTTceSIgp89Ja0y5aPe3GFBYHg==", + "cpu": [ + "ppc64" + ], + "dev": true, + "libc": [ + "musl" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-riscv64-gnu": { + "version": "4.64.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.64.0.tgz", + "integrity": "sha512-tjL58mgQcTRnDRpeky+Sth1MKQeYi2Ct6r3Luq9E5aTSjnM/i/JbozqZkKqp9thM5+oDSZxo+05f9kdQedfTGA==", + "cpu": [ + "riscv64" + ], + "dev": true, + "libc": [ + "glibc" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-riscv64-musl": { + "version": "4.64.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.64.0.tgz", + "integrity": "sha512-ictoRyVaoZ8C67myHef+8hhCa6IplXJJ/xUCkVCxziV4zxMZh+jvhkhGsPBLqj1S72fnqD0QH5zL4lcaa4X7DQ==", + "cpu": [ + "riscv64" + ], + "dev": true, + "libc": [ + "musl" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-s390x-gnu": { + "version": "4.64.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.64.0.tgz", + "integrity": "sha512-8aVvZ2hfr9RLFzBQkQNmYeHLDja8fLeQAmLt757zdKN/B+8L809KlLJKctQjS22wZotptV8G6o7fVPuAs8S1tQ==", + "cpu": [ + "s390x" + ], + "dev": true, + "libc": [ + "glibc" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-x64-gnu": { + "version": "4.64.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.64.0.tgz", + "integrity": "sha512-2dEF8GAcDKwshUfydD+GhosppNyBzhVUHkdFF3CXd3FpOkzj/RZzF5aoEtzklujklT5qFVRU2GK/cFeLaTNKVg==", + "cpu": [ + "x64" + ], + "dev": true, + "libc": [ + "glibc" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-x64-musl": { + "version": "4.64.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.64.0.tgz", + "integrity": "sha512-3XHTvoo2hKkh0MiOfS7SkhHjMaaWF7P4F3drocZZaho/Z8w7h/jpnuBHm91BOQLfvrKHs1yR+zir4E8RI3XzTQ==", + "cpu": [ + "x64" + ], + "dev": true, + "libc": [ + "musl" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-openbsd-x64": { + "version": "4.64.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.64.0.tgz", + "integrity": "sha512-HKtkzodL4a3KFWDXDoO61cRynAWTR3LnAE0oGtfG9lcNFpNuVYUFOByxDgNqEvic9rvaQbAj+SFwTEWDptRaIw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ] + }, + "node_modules/@rollup/rollup-openharmony-arm64": { + "version": "4.64.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.64.0.tgz", + "integrity": "sha512-JBsxqiY16uyyCujtoC3s7zL+SrYyNElptD7K4V+KUoJ2V8/XG3hPWpheK+SuPwNh1cikJvIZmIdsrYXvD6PLJw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openharmony" + ] + }, + "node_modules/@rollup/rollup-win32-arm64-msvc": { + "version": "4.64.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.64.0.tgz", + "integrity": "sha512-S5Qrijh37qhnUYQ0ay8WN3LuWeKjow7wTUyCOPMZtnXiBXYXdsZETI6ZLfYnQAKovltckPLBFdNeD61P2rJc7g==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ] + }, + "node_modules/@rollup/rollup-win32-ia32-msvc": { + "version": "4.64.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.64.0.tgz", + "integrity": "sha512-zbZ6iMmLFEsCtTdc2/y1F/cDFVNNCPF7Ae8PCT/wdPE//hGwYp6r+MyCLMFX+kOeIe09Pz6ASfnnfpSTN1FJQQ==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ] + }, + "node_modules/@rollup/rollup-win32-x64-gnu": { + "version": "4.64.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.64.0.tgz", + "integrity": "sha512-L6Hw69oNpuYaOr1zCG30v0/DqKYCSRwodPGwIcVZ/6f8SOzq9rxtL/xNVI5MO4wjli+Ko0ErK9uHJL3mNPt8wQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ] + }, + "node_modules/@rollup/rollup-win32-x64-msvc": { + "version": "4.64.0", + "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.64.0.tgz", + "integrity": "sha512-nl+CTWIgOGszQmUz/kanfgrfFZ4qiwxKIfT/ryl3N3Ewk5tqizmYtNXiqb7Bu/fDtNgu1kyxdFiAUJNur3iysg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ] + }, + "node_modules/@shikijs/engine-oniguruma": { + "version": "3.23.0", + "resolved": "https://registry.npmjs.org/@shikijs/engine-oniguruma/-/engine-oniguruma-3.23.0.tgz", + "integrity": "sha512-1nWINwKXxKKLqPibT5f4pAFLej9oZzQTsby8942OTlsJzOBZ0MWKiwzMsd+jhzu8YPCHAswGnnN1YtQfirL35g==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/types": "3.23.0", + "@shikijs/vscode-textmate": "^10.0.2" + } + }, + "node_modules/@shikijs/langs": { + "version": "3.23.0", + "resolved": "https://registry.npmjs.org/@shikijs/langs/-/langs-3.23.0.tgz", + "integrity": "sha512-2Ep4W3Re5aB1/62RSYQInK9mM3HsLeB91cHqznAJMuylqjzNVAVCMnNWRHFtcNHXsoNRayP9z1qj4Sq3nMqYXg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/types": "3.23.0" + } + }, + "node_modules/@shikijs/themes": { + "version": "3.23.0", + "resolved": "https://registry.npmjs.org/@shikijs/themes/-/themes-3.23.0.tgz", + "integrity": "sha512-5qySYa1ZgAT18HR/ypENL9cUSGOeI2x+4IvYJu4JgVJdizn6kG4ia5Q1jDEOi7gTbN4RbuYtmHh0W3eccOrjMA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/types": "3.23.0" + } + }, + "node_modules/@shikijs/types": { + "version": "3.23.0", + "resolved": "https://registry.npmjs.org/@shikijs/types/-/types-3.23.0.tgz", + "integrity": "sha512-3JZ5HXOZfYjsYSk0yPwBrkupyYSLpAE26Qc0HLghhZNGTZg/SKxXIIgoxOpmmeQP0RRSDJTk1/vPfw9tbw+jSQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/vscode-textmate": "^10.0.2", + "@types/hast": "^3.0.4" + } + }, + "node_modules/@shikijs/vscode-textmate": { + "version": "10.0.2", + "resolved": "https://registry.npmjs.org/@shikijs/vscode-textmate/-/vscode-textmate-10.0.2.tgz", + "integrity": "sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/estree": { + "version": "1.0.9", + "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.9.tgz", + "integrity": "sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/hast": { + "version": "3.0.5", + "resolved": "https://registry.npmjs.org/@types/hast/-/hast-3.0.5.tgz", + "integrity": "sha512-rp/ezSWaD1m44dPKICGhiskI13nVr7qTloFwDa/IYkhhf5nzwP+zIQcIJh3WIFSBOy/H1PzB40jPjMDksN4F+g==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "*" + } + }, + "node_modules/@types/unist": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", + "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", + "dev": true, + "license": "MIT" + }, + "node_modules/acorn": { + "version": "8.18.0", + "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.18.0.tgz", + "integrity": "sha512-lGq+9yr1/GuAWaVYIHRjvvySG5/4VfKIvC8EWxStPdcDh/Ka7FG3twP6v4d5BkravUilhIAsG4Qj83t02LWUPQ==", + "dev": true, + "license": "MIT", + "bin": { + "acorn": "bin/acorn" + }, + "engines": { + "node": ">=0.4.0" + } + }, + "node_modules/any-promise": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/any-promise/-/any-promise-1.3.0.tgz", + "integrity": "sha512-7UvmKalWRt1wgjL1RrGxoSJW/0QZFIegpeGvZG9kjp8vrRu55XTHbwnqq2GpXm9uLbcuhxm3IqX9OB4MZR1b2A==", + "dev": true, + "license": "MIT" + }, + "node_modules/argparse": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", + "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==", + "dev": true, + "license": "Python-2.0" + }, + "node_modules/balanced-match": { + "version": "4.0.4", + "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz", + "integrity": "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==", + "dev": true, + "license": "MIT", + "engines": { + "node": "18 || 20 || >=22" + } + }, + "node_modules/brace-expansion": { + "version": "5.0.12", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.12.tgz", + "integrity": "sha512-YovQ3rzhaLMIrDjNDMkNS01tea93qhEhG5xy8f6+R0l+dw3Ki+5sCoIoI942iuLZTHWogWktgwVDhU09iNEimQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "balanced-match": "^4.0.2" + }, + "engines": { + "node": "20 || >=22" + } + }, + "node_modules/bundle-require": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/bundle-require/-/bundle-require-5.1.0.tgz", + "integrity": "sha512-3WrrOuZiyaaZPWiEt4G3+IffISVC9HYlWueJEBWED4ZH4aIAC2PnkdnuRrR94M+w6yGWn4AglWtJtBI8YqvgoA==", + "dev": true, + "license": "MIT", + "dependencies": { + "load-tsconfig": "^0.2.3" + }, + "engines": { + "node": "^12.20.0 || ^14.13.1 || >=16.0.0" + }, + "peerDependencies": { + "esbuild": ">=0.18" + } + }, + "node_modules/cac": { + "version": "6.7.14", + "resolved": "https://registry.npmjs.org/cac/-/cac-6.7.14.tgz", + "integrity": "sha512-b6Ilus+c3RrdDk+JhLKUAQfzzgLEPy6wcXqS7f/xe1EETvsDP6GORG7SFuOs6cID5YkqchW/LXZbX5bc8j7ZcQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/chokidar": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-4.0.3.tgz", + "integrity": "sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==", + "dev": true, + "license": "MIT", + "dependencies": { + "readdirp": "^4.0.1" + }, + "engines": { + "node": ">= 14.16.0" + }, + "funding": { + "url": "https://paulmillr.com/funding/" + } + }, + "node_modules/commander": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/commander/-/commander-4.1.1.tgz", + "integrity": "sha512-NOKm8xhkzAjzFx8B2v5OAHT+u5pRQc2UCa2Vq9jYL/31o2wi9mxBA7LIFs3sV5VSC49z6pEhfbMULvShKj26WA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 6" + } + }, + "node_modules/confbox": { + "version": "0.1.8", + "resolved": "https://registry.npmjs.org/confbox/-/confbox-0.1.8.tgz", + "integrity": "sha512-RMtmw0iFkeR4YV+fUOSucriAQNb9g8zFR52MWCtl+cCZOFRNL6zeB395vPzFhEjjn4fMxXudmELnl/KF/WrK6w==", + "dev": true, + "license": "MIT" + }, + "node_modules/consola": { + "version": "3.4.2", + "resolved": "https://registry.npmjs.org/consola/-/consola-3.4.2.tgz", + "integrity": "sha512-5IKcdX0nnYavi6G7TtOhwkYzyjfJlatbjMjuLSfE2kYT5pMDOilZ4OvMhi637CcDICTmz3wARPoyhqyX1Y+XvA==", + "dev": true, + "license": "MIT", + "engines": { + "node": "^14.18.0 || >=16.10.0" + } + }, + "node_modules/debug": { + "version": "4.4.3", + "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz", + "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==", + "dev": true, + "license": "MIT", + "dependencies": { + "ms": "^2.1.3" + }, + "engines": { + "node": ">=6.0" + }, + "peerDependenciesMeta": { + "supports-color": { + "optional": true + } + } + }, + "node_modules/entities": { + "version": "4.5.0", + "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz", + "integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==", + "dev": true, + "license": "BSD-2-Clause", + "engines": { + "node": ">=0.12" + }, + "funding": { + "url": "https://github.com/fb55/entities?sponsor=1" + } + }, + "node_modules/esbuild": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.27.7.tgz", + "integrity": "sha512-IxpibTjyVnmrIQo5aqNpCgoACA/dTKLTlhMHihVHhdkxKyPO1uBBthumT0rdHmcsk9uMonIWS0m4FljWzILh3w==", + "dev": true, + "hasInstallScript": true, + "license": "MIT", + "bin": { + "esbuild": "bin/esbuild" + }, + "engines": { + "node": ">=18" + }, + "optionalDependencies": { + "@esbuild/aix-ppc64": "0.27.7", + "@esbuild/android-arm": "0.27.7", + "@esbuild/android-arm64": "0.27.7", + "@esbuild/android-x64": "0.27.7", + "@esbuild/darwin-arm64": "0.27.7", + "@esbuild/darwin-x64": "0.27.7", + "@esbuild/freebsd-arm64": "0.27.7", + "@esbuild/freebsd-x64": "0.27.7", + "@esbuild/linux-arm": "0.27.7", + "@esbuild/linux-arm64": "0.27.7", + "@esbuild/linux-ia32": "0.27.7", + "@esbuild/linux-loong64": "0.27.7", + "@esbuild/linux-mips64el": "0.27.7", + "@esbuild/linux-ppc64": "0.27.7", + "@esbuild/linux-riscv64": "0.27.7", + "@esbuild/linux-s390x": "0.27.7", + "@esbuild/linux-x64": "0.27.7", + "@esbuild/netbsd-arm64": "0.27.7", + "@esbuild/netbsd-x64": "0.27.7", + "@esbuild/openbsd-arm64": "0.27.7", + "@esbuild/openbsd-x64": "0.27.7", + "@esbuild/openharmony-arm64": "0.27.7", + "@esbuild/sunos-x64": "0.27.7", + "@esbuild/win32-arm64": "0.27.7", + "@esbuild/win32-ia32": "0.27.7", + "@esbuild/win32-x64": "0.27.7" + } + }, + "node_modules/fdir": { + "version": "6.5.0", + "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz", + "integrity": "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12.0.0" + }, + "peerDependencies": { + "picomatch": "^3 || ^4" + }, + "peerDependenciesMeta": { + "picomatch": { + "optional": true + } + } + }, + "node_modules/fix-dts-default-cjs-exports": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/fix-dts-default-cjs-exports/-/fix-dts-default-cjs-exports-1.0.1.tgz", + "integrity": "sha512-pVIECanWFC61Hzl2+oOCtoJ3F17kglZC/6N94eRWycFgBH35hHx0Li604ZIzhseh97mf2p0cv7vVrOZGoqhlEg==", + "dev": true, + "license": "MIT", + "dependencies": { + "magic-string": "^0.30.17", + "mlly": "^1.7.4", + "rollup": "^4.34.8" + } + }, + "node_modules/fsevents": { + "version": "2.3.3", + "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz", + "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==", + "dev": true, + "hasInstallScript": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": "^8.16.0 || ^10.6.0 || >=11.0.0" + } + }, + "node_modules/joycon": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/joycon/-/joycon-3.1.1.tgz", + "integrity": "sha512-34wB/Y7MW7bzjKRjUKTa46I2Z7eV62Rkhva+KkopW7Qvv/OSWBqvkSY7vusOPrNuZcUG3tApvdVgNB8POj3SPw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=10" + } + }, + "node_modules/lilconfig": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/lilconfig/-/lilconfig-3.1.3.tgz", + "integrity": "sha512-/vlFKAoH5Cgt3Ie+JLhRbwOsCQePABiU3tJ1egGvyQ+33R/vcwM2Zl2QR/LzjsBeItPt3oSVXapn+m4nQDvpzw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=14" + }, + "funding": { + "url": "https://github.com/sponsors/antonk52" + } + }, + "node_modules/lines-and-columns": { + "version": "1.2.4", + "resolved": "https://registry.npmjs.org/lines-and-columns/-/lines-and-columns-1.2.4.tgz", + "integrity": "sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==", + "dev": true, + "license": "MIT" + }, + "node_modules/linkify-it": { + "version": "5.0.2", + "resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-5.0.2.tgz", + "integrity": "sha512-ONTm2jCMAVZjgQa/Fy1kScXsuOoF5NPTsoFBdE1KVIZ2vAh/r9+Bqo+0jINCBYnavTPQZz38QzFTme79ENoN3Q==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/puzrin" + }, + { + "type": "github", + "url": "https://github.com/sponsors/markdown-it" + } + ], + "license": "MIT", + "dependencies": { + "uc.micro": "^2.0.0" + } + }, + "node_modules/load-tsconfig": { + "version": "0.2.5", + "resolved": "https://registry.npmjs.org/load-tsconfig/-/load-tsconfig-0.2.5.tgz", + "integrity": "sha512-IXO6OCs9yg8tMKzfPZ1YmheJbZCiEsnBdcB03l0OcfK9prKnJb96siuHCr5Fl37/yo9DnKU+TLpxzTUspw9shg==", + "dev": true, + "license": "MIT", + "engines": { + "node": "^12.20.0 || ^14.13.1 || >=16.0.0" + } + }, + "node_modules/lunr": { + "version": "2.3.9", + "resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.9.tgz", + "integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==", + "dev": true, + "license": "MIT" + }, + "node_modules/magic-string": { + "version": "0.30.21", + "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.21.tgz", + "integrity": "sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@jridgewell/sourcemap-codec": "^1.5.5" + } + }, + "node_modules/markdown-it": { + "version": "14.3.2", + "resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-14.3.2.tgz", + "integrity": "sha512-sHHjZ5fJKlgrG4qns2YwVcdNep35h5fERrfkD2YNsb9UFk0UIHarbiTaHKVMlPuWAoiilyK8Fv/jAm11slsY7Q==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/puzrin" + }, + { + "type": "github", + "url": "https://github.com/sponsors/markdown-it" + } + ], + "license": "MIT", + "dependencies": { + "argparse": "^2.0.1", + "entities": "^4.5.0", + "linkify-it": "^5.0.2", + "mdurl": "^2.0.0", + "punycode.js": "^2.3.1", + "uc.micro": "^2.1.0" + }, + "bin": { + "markdown-it": "bin/markdown-it.mjs" + } + }, + "node_modules/mdurl": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/mdurl/-/mdurl-2.1.0.tgz", + "integrity": "sha512-1+HBaOx0zi/dQWht8rNv9MYf9qqpqL/kxI0hXImU6Y547zM6Sni8BQibt7ifgMcYtQg41ao3Ivd6cnSM86inpg==", + "dev": true, + "license": "MIT" + }, + "node_modules/minimatch": { + "version": "10.2.6", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.6.tgz", + "integrity": "sha512-vpLQEs+VLCr1nU0BXS07maYoFwlDAH0gngQuuttxIwutDFEMHq2blX+8vpgxDdK3J1PwjCJiep77OitTZ4Ll1A==", + "dev": true, + "license": "BlueOak-1.0.0", + "dependencies": { + "brace-expansion": "^5.0.8" + }, + "engines": { + "node": "18 || 20 || >=22" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/mlly": { + "version": "1.8.2", + "resolved": "https://registry.npmjs.org/mlly/-/mlly-1.8.2.tgz", + "integrity": "sha512-d+ObxMQFmbt10sretNDytwt85VrbkhhUA/JBGm1MPaWJ65Cl4wOgLaB1NYvJSZ0Ef03MMEU/0xpPMXUIQ29UfA==", + "dev": true, + "license": "MIT", + "dependencies": { + "acorn": "^8.16.0", + "pathe": "^2.0.3", + "pkg-types": "^1.3.1", + "ufo": "^1.6.3" + } + }, + "node_modules/ms": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", + "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", + "dev": true, + "license": "MIT" + }, + "node_modules/mz": { + "version": "2.7.0", + "resolved": "https://registry.npmjs.org/mz/-/mz-2.7.0.tgz", + "integrity": "sha512-z81GNO7nnYMEhrGh9LeymoE4+Yr0Wn5McHIZMK5cfQCl+NDX08sCZgUc9/6MHni9IWuFLm1Z3HTCXu2z9fN62Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "any-promise": "^1.0.0", + "object-assign": "^4.0.1", + "thenify-all": "^1.0.0" + } + }, + "node_modules/object-assign": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz", + "integrity": "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/pathe": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/pathe/-/pathe-2.0.3.tgz", + "integrity": "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==", + "dev": true, + "license": "MIT" + }, + "node_modules/picocolors": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz", + "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==", + "dev": true, + "license": "ISC" + }, + "node_modules/picomatch": { + "version": "4.0.7", + "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.7.tgz", + "integrity": "sha512-qcJu88Q2IWqJsDD529JKMdwGm/dvInW4HvQnRwiH9JtihJvzGOscDtHE3x1pBKeUOTysQ8kVmLnJ2kJu7yhcGA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/jonschlinkert" + } + }, + "node_modules/pirates": { + "version": "4.0.7", + "resolved": "https://registry.npmjs.org/pirates/-/pirates-4.0.7.tgz", + "integrity": "sha512-TfySrs/5nm8fQJDcBDuUng3VOUKsd7S+zqvbOTiGXHfxX4wK31ard+hoNuvkicM/2YFzlpDgABOevKSsB4G/FA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 6" + } + }, + "node_modules/pkg-types": { + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/pkg-types/-/pkg-types-1.3.1.tgz", + "integrity": "sha512-/Jm5M4RvtBFVkKWRu2BLUTNP8/M2a+UwuAX+ae4770q1qVGtfjG+WTCupoZixokjmHiry8uI+dlY8KXYV5HVVQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "confbox": "^0.1.8", + "mlly": "^1.7.4", + "pathe": "^2.0.1" + } + }, + "node_modules/postcss-load-config": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/postcss-load-config/-/postcss-load-config-6.0.1.tgz", + "integrity": "sha512-oPtTM4oerL+UXmx+93ytZVN82RrlY/wPUV8IeDxFrzIjXOLF1pN+EmKPLbubvKHT2HC20xXsCAH2Z+CKV6Oz/g==", + "dev": true, + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/postcss/" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "license": "MIT", + "dependencies": { + "lilconfig": "^3.1.1" + }, + "engines": { + "node": ">= 18" + }, + "peerDependencies": { + "jiti": ">=1.21.0", + "postcss": ">=8.0.9", + "tsx": "^4.8.1", + "yaml": "^2.4.2" + }, + "peerDependenciesMeta": { + "jiti": { + "optional": true + }, + "postcss": { + "optional": true + }, + "tsx": { + "optional": true + }, + "yaml": { + "optional": true + } + } + }, + "node_modules/punycode.js": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/punycode.js/-/punycode.js-2.3.1.tgz", + "integrity": "sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/readdirp": { + "version": "4.1.2", + "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-4.1.2.tgz", + "integrity": "sha512-GDhwkLfywWL2s6vEjyhri+eXmfH6j1L7JE27WhqLeYzoh/A3DBaYGEj2H/HFZCn/kMfim73FXxEJTw06WtxQwg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 14.18.0" + }, + "funding": { + "type": "individual", + "url": "https://paulmillr.com/funding/" + } + }, + "node_modules/resolve-from": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/resolve-from/-/resolve-from-5.0.0.tgz", + "integrity": "sha512-qYg9KP24dD5qka9J47d0aVky0N+b4fTU89LN9iDnjB5waksiC49rvMB0PrUJQGoTmH50XPiqOvAjDfaijGxYZw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/rollup": { + "version": "4.64.0", + "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.64.0.tgz", + "integrity": "sha512-gjA/kFeDfffII8COoPsvLPvE16hWDTEc1+0QKQNKUkuV8iJjqsC4xXs8/FzuL0v9EV39kuxTbAgcFoTRyy2TGQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/estree": "1.0.9" + }, + "bin": { + "rollup": "dist/bin/rollup" + }, + "engines": { + "node": ">=18.0.0", + "npm": ">=8.0.0" + }, + "optionalDependencies": { + "@napi-rs/lzma-linux-x64-gnu": "1.5.1", + "@rollup/rollup-android-arm-eabi": "4.64.0", + "@rollup/rollup-android-arm64": "4.64.0", + "@rollup/rollup-darwin-arm64": "4.64.0", + "@rollup/rollup-darwin-x64": "4.64.0", + "@rollup/rollup-freebsd-arm64": "4.64.0", + "@rollup/rollup-freebsd-x64": "4.64.0", + "@rollup/rollup-linux-arm-gnueabihf": "4.64.0", + "@rollup/rollup-linux-arm-musleabihf": "4.64.0", + "@rollup/rollup-linux-arm64-gnu": "4.64.0", + "@rollup/rollup-linux-arm64-musl": "4.64.0", + "@rollup/rollup-linux-loong64-gnu": "4.64.0", + "@rollup/rollup-linux-loong64-musl": "4.64.0", + "@rollup/rollup-linux-ppc64-gnu": "4.64.0", + "@rollup/rollup-linux-ppc64-musl": "4.64.0", + "@rollup/rollup-linux-riscv64-gnu": "4.64.0", + "@rollup/rollup-linux-riscv64-musl": "4.64.0", + "@rollup/rollup-linux-s390x-gnu": "4.64.0", + "@rollup/rollup-linux-x64-gnu": "4.64.0", + "@rollup/rollup-linux-x64-musl": "4.64.0", + "@rollup/rollup-openbsd-x64": "4.64.0", + "@rollup/rollup-openharmony-arm64": "4.64.0", + "@rollup/rollup-win32-arm64-msvc": "4.64.0", + "@rollup/rollup-win32-ia32-msvc": "4.64.0", + "@rollup/rollup-win32-x64-gnu": "4.64.0", + "@rollup/rollup-win32-x64-msvc": "4.64.0", + "fsevents": "~2.3.2" + } + }, + "node_modules/source-map": { + "version": "0.7.6", + "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.7.6.tgz", + "integrity": "sha512-i5uvt8C3ikiWeNZSVZNWcfZPItFQOsYTUAOkcUPGd8DqDy1uOUikjt5dG+uRlwyvR108Fb9DOd4GvXfT0N2/uQ==", + "dev": true, + "license": "BSD-3-Clause", + "engines": { + "node": ">= 12" + } + }, + "node_modules/sucrase": { + "version": "3.35.1", + "resolved": "https://registry.npmjs.org/sucrase/-/sucrase-3.35.1.tgz", + "integrity": "sha512-DhuTmvZWux4H1UOnWMB3sk0sbaCVOoQZjv8u1rDoTV0HTdGem9hkAZtl4JZy8P2z4Bg0nT+YMeOFyVr4zcG5Tw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@jridgewell/gen-mapping": "^0.3.2", + "commander": "^4.0.0", + "lines-and-columns": "^1.1.6", + "mz": "^2.7.0", + "pirates": "^4.0.1", + "tinyglobby": "^0.2.11", + "ts-interface-checker": "^0.1.9" + }, + "bin": { + "sucrase": "bin/sucrase", + "sucrase-node": "bin/sucrase-node" + }, + "engines": { + "node": ">=16 || 14 >=14.17" + } + }, + "node_modules/thenify": { + "version": "3.3.1", + "resolved": "https://registry.npmjs.org/thenify/-/thenify-3.3.1.tgz", + "integrity": "sha512-RVZSIV5IG10Hk3enotrhvz0T9em6cyHBLkH/YAZuKqd8hRkKhSfCGIcP2KUY0EPxndzANBmNllzWPwak+bheSw==", + "dev": true, + "license": "MIT", + "dependencies": { + "any-promise": "^1.0.0" + } + }, + "node_modules/thenify-all": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/thenify-all/-/thenify-all-1.6.0.tgz", + "integrity": "sha512-RNxQH/qI8/t3thXJDwcstUO4zeqo64+Uy/+sNVRBx4Xn2OX+OZ9oP+iJnNFqplFra2ZUVeKCSa2oVWi3T4uVmA==", + "dev": true, + "license": "MIT", + "dependencies": { + "thenify": ">= 3.1.0 < 4" + }, + "engines": { + "node": ">=0.8" + } + }, + "node_modules/tinyexec": { + "version": "0.3.2", + "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-0.3.2.tgz", + "integrity": "sha512-KQQR9yN7R5+OSwaK0XQoj22pwHoTlgYqmUscPYoknOoWCWfj/5/ABTMRi69FrKU5ffPVh5QcFikpWJI/P1ocHA==", + "dev": true, + "license": "MIT" + }, + "node_modules/tinyglobby": { + "version": "0.2.17", + "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.17.tgz", + "integrity": "sha512-wXR/dYpcqKmfWpEdZjiKJOwCNFndD0DMnrW/cYjVGttEkBfVgcLFHoNrlj47mjOVic9yyNu65alsgF4NQyTa2g==", + "dev": true, + "license": "MIT", + "dependencies": { + "fdir": "^6.5.0", + "picomatch": "^4.0.4" + }, + "engines": { + "node": ">=12.0.0" + }, + "funding": { + "url": "https://github.com/sponsors/SuperchupuDev" + } + }, + "node_modules/tree-kill": { + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/tree-kill/-/tree-kill-1.2.2.tgz", + "integrity": "sha512-L0Orpi8qGpRG//Nd+H90vFB+3iHnue1zSSGmNOOCh1GLJ7rUKVwV2HvijphGQS2UmhUZewS9VgvxYIdgr+fG1A==", + "dev": true, + "license": "MIT", + "bin": { + "tree-kill": "cli.js" + } + }, + "node_modules/ts-interface-checker": { + "version": "0.1.13", + "resolved": "https://registry.npmjs.org/ts-interface-checker/-/ts-interface-checker-0.1.13.tgz", + "integrity": "sha512-Y/arvbn+rrz3JCKl9C4kVNfTfSm2/mEp5FSz5EsZSANGPSlQrpRI5M4PKF+mJnE52jOO90PnPSc3Ur3bTQw0gA==", + "dev": true, + "license": "Apache-2.0" + }, + "node_modules/tsup": { + "version": "8.5.1", + "resolved": "https://registry.npmjs.org/tsup/-/tsup-8.5.1.tgz", + "integrity": "sha512-xtgkqwdhpKWr3tKPmCkvYmS9xnQK3m3XgxZHwSUjvfTjp7YfXe5tT3GgWi0F2N+ZSMsOeWeZFh7ZZFg5iPhing==", + "dev": true, + "license": "MIT", + "dependencies": { + "bundle-require": "^5.1.0", + "cac": "^6.7.14", + "chokidar": "^4.0.3", + "consola": "^3.4.0", + "debug": "^4.4.0", + "esbuild": "^0.27.0", + "fix-dts-default-cjs-exports": "^1.0.0", + "joycon": "^3.1.1", + "picocolors": "^1.1.1", + "postcss-load-config": "^6.0.1", + "resolve-from": "^5.0.0", + "rollup": "^4.34.8", + "source-map": "^0.7.6", + "sucrase": "^3.35.0", + "tinyexec": "^0.3.2", + "tinyglobby": "^0.2.11", + "tree-kill": "^1.2.2" + }, + "bin": { + "tsup": "dist/cli-default.js", + "tsup-node": "dist/cli-node.js" + }, + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "@microsoft/api-extractor": "^7.36.0", + "@swc/core": "^1", + "postcss": "^8.4.12", + "typescript": ">=4.5.0" + }, + "peerDependenciesMeta": { + "@microsoft/api-extractor": { + "optional": true + }, + "@swc/core": { + "optional": true + }, + "postcss": { + "optional": true + }, + "typescript": { + "optional": true + } + } + }, + "node_modules/typedoc": { + "version": "0.28.20", + "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.28.20.tgz", + "integrity": "sha512-uSKqkh8Cr48vllnEy+jdaAgOeR6Y+QCBW7usgUsKj7gJEfR7stw9U/fE49LBnj2tPRKPY0c0EBJSWe9Appmplg==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@gerrit0/mini-shiki": "^3.23.0", + "lunr": "^2.3.9", + "markdown-it": "^14.3.0", + "minimatch": "^10.2.5", + "yaml": "^2.9.0" + }, + "bin": { + "typedoc": "bin/typedoc" + }, + "engines": { + "node": ">= 18", + "pnpm": ">= 10" + }, + "peerDependencies": { + "typescript": "5.0.x || 5.1.x || 5.2.x || 5.3.x || 5.4.x || 5.5.x || 5.6.x || 5.7.x || 5.8.x || 5.9.x || 6.0.x" + } + }, + "node_modules/typedoc-plugin-markdown": { + "version": "4.13.1", + "resolved": "https://registry.npmjs.org/typedoc-plugin-markdown/-/typedoc-plugin-markdown-4.13.1.tgz", + "integrity": "sha512-d3jchJ4CyIrV9w9uozTSkfMYG8IEM1RvvGOaybJ/3rRporzoX7p0lprffo95GOGUviQqP0phjHJE3bY8PQbilA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 18" + }, + "peerDependencies": { + "typedoc": "0.28.x" + } + }, + "node_modules/typescript": { + "version": "5.9.3", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz", + "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==", + "dev": true, + "license": "Apache-2.0", + "bin": { + "tsc": "bin/tsc", + "tsserver": "bin/tsserver" + }, + "engines": { + "node": ">=14.17" + } + }, + "node_modules/uc.micro": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/uc.micro/-/uc.micro-2.1.0.tgz", + "integrity": "sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==", + "dev": true, + "license": "MIT" + }, + "node_modules/ufo": { + "version": "1.6.4", + "resolved": "https://registry.npmjs.org/ufo/-/ufo-1.6.4.tgz", + "integrity": "sha512-JFNbkD1Svwe0KvGi8GOeLcP4kAWQ609twvCdcHxq1oSL8svv39ZuSvajcD8B+5D0eL4+s1Is2D/O6KN3qcTeRA==", + "dev": true, + "license": "MIT" + }, + "node_modules/yaml": { + "version": "2.9.1", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.1.tgz", + "integrity": "sha512-3NxN8+78OdzbT7C/WjGsyfPAtJaN3FNDsWxv7Y7mcDsT/oOmgW8BpyQQFFBnvZE3j9Y2Sdz1ULFLezL7Eb2yFw==", + "dev": true, + "license": "ISC", + "bin": { + "yaml": "bin.mjs" + }, + "engines": { + "node": ">= 14.6" + }, + "funding": { + "url": "https://github.com/sponsors/eemeli" + } + } + } +} diff --git a/evenhub-extensions/package.json b/evenhub-extensions/package.json new file mode 100644 index 00000000..2ac15741 --- /dev/null +++ b/evenhub-extensions/package.json @@ -0,0 +1,59 @@ +{ + "name": "@faceclaw/evenhub-extensions", + "version": "0.1.0", + "description": "Types and a helper for EvenHub apps to detect Faceclaw and use its extension APIs on the Even Realities G2 glasses.", + "license": "MIT", + "repository": { + "type": "git", + "url": "git+https://github.com/jimrandomh/faceclaw.git", + "directory": "evenhub-extensions" + }, + "homepage": "https://github.com/jimrandomh/faceclaw/tree/main/evenhub-extensions#readme", + "bugs": { + "url": "https://github.com/jimrandomh/faceclaw/issues" + }, + "keywords": [ + "evenhub", + "even-realities", + "g2", + "faceclaw", + "smart-glasses" + ], + "type": "module", + "main": "./dist/index.cjs", + "module": "./dist/index.js", + "types": "./dist/index.d.ts", + "exports": { + ".": { + "import": { + "types": "./dist/index.d.ts", + "default": "./dist/index.js" + }, + "require": { + "types": "./dist/index.d.cts", + "default": "./dist/index.cjs" + } + }, + "./package.json": "./package.json" + }, + "files": [ + "dist" + ], + "sideEffects": false, + "publishConfig": { + "access": "public" + }, + "scripts": { + "build": "tsup", + "check": "tsc -p tsconfig.json", + "docs": "typedoc", + "prepublishOnly": "npm run check && npm run build" + }, + "devDependencies": { + "@evenrealities/even_hub_sdk": "^0.0.16", + "tsup": "^8.5.1", + "typedoc": "^0.28.20", + "typedoc-plugin-markdown": "^4.13.1", + "typescript": "~5.9.0" + } +} diff --git a/evenhub-extensions/src/index.ts b/evenhub-extensions/src/index.ts new file mode 100644 index 00000000..b0b0bccd --- /dev/null +++ b/evenhub-extensions/src/index.ts @@ -0,0 +1,472 @@ +/** + * Types and a small helper for the Faceclaw extension API. + * + * [Faceclaw](https://github.com/jimrandomh/faceclaw) is an alternative host for + * EvenHub apps: it runs them on the Even Realities G2 glasses without the stock + * Even app. An app built against the standard `@evenrealities/even_hub_sdk` + * runs unchanged. This package lets such an app detect that it is running + * inside Faceclaw and use a few extra, Faceclaw-only capabilities. + * + * The only entry point is the injected global `window.getFaceclawExtensions`, + * which is a function inside Faceclaw and `undefined` in the stock Even app and + * every other host. Nothing on the standard SDK, on `window`, or on any built-in + * prototype is modified, so an app that uses these extensions still runs + * everywhere else; it just skips the extras. + * + * @example + * ```ts + * import { getFaceclawExtensions } from "@faceclaw/evenhub-extensions"; + * + * const fc = getFaceclawExtensions(); + * if (fc) { + * console.log("Running in", fc.getVersion()); // "Faceclaw/0.8.2" + * fc.addWindowLifecycleListener((e) => { + * if (e.type === "hidden") pauseExpensiveWork(); + * }); + * } + * ``` + * + * @packageDocumentation + */ + +/** + * Third-party services whose API keys the user may have configured in Faceclaw. + * + * @group API keys + */ +export type ApiKeyService = "openai" | "anthropic" | "soniox" | "elevenlabs" | "mapbox"; + +/** + * One step of a piezo-buzzer tone sequence. The G2 has a single monophonic PWM + * buzzer, and the firmware plays a sequence's steps back to back on its own timer. + * + * @group Buzzer + */ +export interface BuzzerStep { + /** Tone frequency in Hz. The piezo is loudest around 1–4 kHz and faint below about 150 Hz. */ + freq: number; + /** Step duration in milliseconds (1–65535). */ + ms: number; + /** + * PWM duty cycle, 0–100. Use `duty: 0` for a rest (silence) lasting `ms`. + * @defaultValue 50 + */ + duty?: number; +} + +/** + * A window lifecycle transition, delivered to + * {@link FaceclawExtensions.addWindowLifecycleListener}. + * + * - `visible` / `hidden`: the app's glasses window became the shown surface, or + * stopped being it. This happens when the user switches the foreground window + * or the phone screen turns on or 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 (for + * example, the user opened the app switcher). A blurred app can still be + * visible, but it doesn't receive taps or scrolls. + * + * An app can assume it starts `visible` and `focused` at launch. Events report + * changes from there. + * + * @group Window lifecycle + */ +export type WindowLifecycleEventType = "visible" | "hidden" | "focused" | "blurred"; + +/** + * Payload of a {@link FaceclawExtensions.addWindowLifecycleListener} callback. + * + * @group Window lifecycle + */ +export interface WindowLifecycleEvent { + /** Which transition happened. */ + type: WindowLifecycleEventType; +} + +/** + * A magnetometer heading sample from {@link FaceclawExtensions.addCompassListener}. + * All headings are in degrees clockwise, in the range [0, 360). + * + * Prefer `trueHeadingDegrees` when it is present, then `magneticHeadingDegrees`. + * If `wearerCalibrated` is false, treat both as relative headings, or let the + * user zero them. + * + * @group Compass + */ +export interface CompassReading { + /** + * Raw magnetic heading as reported by the glasses, with no correction for how + * they sit on the wearer's head. It is kept for apps that zero it themselves. + */ + headingDegrees: number; + /** + * Magnetic heading corrected by the wearer's calibration offset from + * Faceclaw's Compass app. Equal to `headingDegrees` until the wearer calibrates. + */ + magneticHeadingDegrees: number; + /** + * Whether the wearer has calibrated the compass in Faceclaw's Compass app. + * Only trust `magneticHeadingDegrees` and `trueHeadingDegrees` as absolute + * headings when this is true. + */ + wearerCalibrated: boolean; + /** + * Local magnetic declination in degrees (east positive), computed from the + * phone's location and the World Magnetic Model. Absent when Faceclaw has no + * location fix or no location permission. + */ + declinationDegrees?: number; + /** `magneticHeadingDegrees` plus declination. Absent when `declinationDegrees` is. */ + trueHeadingDegrees?: number; +} + +// ---- Extended layout (a superset of the stock EvenHub page containers) ---- + +/** + * Fields shared by every container in a {@link FaceclawLayout}. They match the + * stock SDK's container-property classes, plus `preserve`. + * + * As in the stock SDK every field is optional, so the stock + * `TextContainerProperty`, `ImageContainerProperty` and `ListContainerProperty` + * classes can be passed directly. In practice you should set `containerID`, + * `containerName` and the geometry on every container. + * + * @group Extended layout + */ +export interface FaceclawContainerCommon { + /** + * Container identity. Stock content updates (`textContainerUpgrade`, + * `updateImageRawData`) address containers by this ID. + */ + containerID?: number; + /** Container name. `preserve` matches containers across layouts by name. */ + containerName?: string; + /** Left edge in pixels on the 576×452 canvas. */ + xPosition?: number; + /** Top edge in pixels on the 576×452 canvas. */ + yPosition?: number; + /** Width in pixels. */ + width?: number; + /** Height in pixels. */ + height?: number; + /** Stacking order: higher values draw on top. */ + zOrderIndex?: number; + /** + * When set to `1`/`true`, this container receives the app's tap and scroll + * events. Exactly one text or list container per layout should capture events. + */ + isEventCapture?: number | boolean; + /** + * When true, inherit content (text, image pixels, or list items and selection) + * from the container of the same kind and `containerName` in the previous + * layout. Otherwise the container starts blank. + */ + preserve?: boolean; +} + +/** + * A text container. The fields match the stock SDK's `TextContainerProperty`, plus `preserve`. + * + * @group Extended layout + */ +export interface FaceclawTextContainer extends FaceclawContainerCommon { + /** Text to show. Update it later with the stock `textContainerUpgrade`. */ + content?: string; + /** + * Text brightness level, 0–4. + * @defaultValue 4 + */ + textColor?: number; + /** Border width in pixels, 0–5. Wider values are clamped. */ + borderWidth?: number; + /** Accepted for compatibility with stock payloads. Faceclaw currently ignores it. */ + borderColor?: number; + /** Border corner radius in pixels. */ + borderRadius?: number; + /** Padding between the border and the text, in pixels. */ + paddingLength?: number; +} + +/** + * An image container. The fields match the stock SDK's `ImageContainerProperty`, + * plus `preserve`. + * + * In the extended layout an image container may be as large as the whole + * 576×452 canvas; the stock limit is 288×144. Push pixels with the stock + * `updateImageRawData`, which in Faceclaw accepts PNG, uncompressed BMP, or raw + * grayscale sized to the container (8 bits per pixel, or 4 bits per pixel packed + * two to a byte, high nibble first). + * + * @group Extended layout + */ +export type FaceclawImageContainer = FaceclawContainerCommon; + +/** + * The items of a {@link FaceclawListContainer}. Matches the stock `ListItemContainerProperty`. + * + * @group Extended layout + */ +export interface FaceclawListItems { + /** Item labels, in display order. */ + itemName?: string[]; + /** Accepted for compatibility with stock payloads. The length of `itemName` is used instead. */ + itemCount?: number; + /** Fixed width of each item's selection outline in pixels. `0` (the default) hugs the text. */ + itemWidth?: number; + /** Whether the selected item is outlined. */ + isItemSelectBorderEn?: number | boolean; +} + +/** + * A list container. The fields match the stock SDK's `ListContainerProperty`, plus `preserve`. + * + * @group Extended layout + */ +export interface FaceclawListContainer extends FaceclawContainerCommon { + /** The list's items and selection style. */ + itemContainer?: FaceclawListItems; + /** Border width in pixels, 0–5. Wider values are clamped. */ + borderWidth?: number; + /** Accepted for compatibility with stock payloads. Faceclaw currently ignores it. */ + borderColor?: number; + /** Border corner radius in pixels. */ + borderRadius?: number; + /** Padding between the border and the items, in pixels. */ + paddingLength?: number; +} + +/** + * The page's contextual menu. Matches the stock SDK's `MenuContainerProperty`, + * with the same limits: at most 10 items, each `itemID` a unique non-zero + * uint32, and each `itemName` at most 32 UTF-8 bytes. Selections arrive as the + * stock `menuItemClickEvent`. + * + * @group Extended layout + */ +export interface FaceclawMenu { + /** Menu entries, in display order. */ + menuItems?: { itemName?: string; itemID?: number }[]; +} + +/** + * A page layout for {@link FaceclawExtensions.createLayout} and + * {@link FaceclawExtensions.replaceLayout}. + * + * It has the same shape as the stock `CreateStartUpPageContainer` / + * `RebuildPageContainer`, so you can build it with the stock SDK's container + * classes, with three differences: + * + * - The canvas is the full 576×452 app area instead of 576×288, so image + * containers may be up to 576×452. + * - There is no limit on the number of containers. + * - Each container may set `preserve: true` to inherit its content from the + * same-named container in the previous layout. + * + * @group Extended layout + */ +export interface FaceclawLayout { + /** Text containers. */ + textObject?: FaceclawTextContainer[]; + /** Image containers. */ + imageObject?: FaceclawImageContainer[]; + /** List containers. */ + listObject?: FaceclawListContainer[]; + /** The page's contextual menu. Omit it to clear any previous menu. */ + menuObject?: FaceclawMenu; + /** Accepted for compatibility with stock payloads and ignored: there is no container limit. */ + containerTotalNum?: number; +} + +// ---- Voice-assistant tools ---- + +/** + * A JSON Schema object describing a tool's arguments. + * + * @group Assistant tools + */ +export type JsonSchema = Record; + +/** + * A tool the app contributes to Faceclaw's voice assistant, for use with + * {@link FaceclawExtensions.setAssistantTools}. + * + * The assistant sees the tool namespaced by the app's package name, as + * `app..`. `name` here is the bare name without that prefix. + * + * @typeParam Args - The arguments object the assistant passes to `handler`, + * as described by `parameters`. + * + * @group Assistant tools + */ +export interface AssistantTool { + /** Bare tool name (no package prefix), for example `"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`. + * @defaultValue { type: "object", properties: {} } + */ + parameters?: JsonSchema; + /** + * When the tool can be called: `"foreground"` only while the app owns the + * visible window, or `"open"` any time the app is running, including in the + * background. + * @defaultValue "foreground" + */ + availability?: "open" | "foreground"; + /** + * Called when the assistant invokes the tool. Return a string, or any + * JSON-serializable value, to report back to the assistant. Throw (or reject) + * to report an error. May be async. + */ + handler: (args: Args) => unknown; +} + +/** + * The Faceclaw-only capability surface, obtained with {@link getFaceclawExtensions}. + * Everything here is in addition to the standard EvenHub SDK. + * + * Calls that return a promise reject with an `Error` if the host fails to + * carry them out. + * + * @group Entry point + */ +export interface FaceclawExtensions { + /** + * The extension API level the host implements. It is `1` for the API + * described here, and increases by one each time members are added. Members + * added later are documented with the level that introduced them, so an app + * can check for them before calling: + * + * ```ts + * if (fc.apiVersion >= 2) fc.someNewerMethod(); + * ``` + */ + readonly apiVersion: number; + + /** + * The host's name and version, for example `"Faceclaw/0.8.2"`. For display + * and logging; use {@link FaceclawExtensions.apiVersion} for feature checks. + */ + getVersion(): string; + + /** + * Hand input focus back to Faceclaw's app switcher without closing the app, + * which keeps running in the background. + */ + returnToAppSwitcher(): void; + + /** + * Close this app and tear down its window. + * + * Faceclaw treats the stock `shutDownPageContainer(1)` as "return to the app + * switcher", so apps that quit on double-tap stay alive. This method always + * quits. + */ + quit(): void; + + /** + * Subscribe to window lifecycle changes (see {@link WindowLifecycleEventType}). + * + * @param listener - Called on each transition. + * @returns A function that unsubscribes `listener`. + */ + addWindowLifecycleListener(listener: (event: WindowLifecycleEvent) => void): () => void; + + /** + * List the services whose API keys the user has configured in Faceclaw. This + * returns only the service names, never the keys, and doesn't prompt the user. + * Use {@link FaceclawExtensions.requestApiKeyAccess} to obtain the keys. + */ + getConfiguredApiKeys(): Promise; + + /** + * Ask the user to share one or more configured API keys with this app. This + * opens a consent prompt on the glasses, unless the user already granted + * these services to this app earlier in the session. + * + * @param services - The services whose keys the app wants. + * @returns A map from service to key, containing only the services that were + * both requested and configured. It is empty if the user declines. + */ + requestApiKeyAccess(services: ApiKeyService[]): Promise>>; + + /** + * Play a tone sequence on the glasses' piezo buzzer. Sequences longer than the + * firmware's per-message limit of 48 steps are split and paced automatically. + * + * @returns A promise that resolves once every part of the sequence has been + * queued on the glasses, which can be before it finishes playing. + */ + playBuzzer(steps: BuzzerStep[]): Promise; + + /** + * Turn on the glasses' magnetometer and receive heading samples. The sensor + * stays on while at least one listener is registered, and readings are only + * delivered while the app is the foreground window. + * + * The magnetometer sits inside the right arm, which rests against the wearer's + * head at an angle that differs between wearers (and between wears), so the + * raw heading is only relative. See {@link CompassReading} for the corrected + * headings and when to trust them. + * + * @param listener - Called with each sample. + * @returns A function that unsubscribes `listener`. + */ + addCompassListener(listener: (reading: CompassReading) => void): () => void; + + /** + * Build the app's page from an extended layout. This is a superset of the + * stock `createStartUpPageContainer`; see {@link FaceclawLayout} for the + * differences. + * + * Unlike the stock call it may be called more than once. Once an app uses an + * extended layout, its window stays at the full 576×452 size for the rest of + * the session, including for later stock `rebuildPageContainer` calls. + * + * @returns A promise that resolves to true on success. + */ + createLayout(layout: FaceclawLayout): Promise; + + /** + * Replace the current page with a new extended layout. This is a superset of + * the stock `rebuildPageContainer`. Containers marked `preserve` inherit + * their content from the same-named container in the outgoing layout. + * + * @returns A promise that resolves to true on success. + */ + replaceLayout(layout: FaceclawLayout): Promise; + + /** + * Declare the app's voice-assistant tools, replacing any set earlier. Each + * tool's `handler` runs in the app when the assistant calls it. + * + * @param tools - The tools to offer. Pass `[]` to remove them all. + */ + setAssistantTools(tools: AssistantTool[]): void; +} + +declare global { + interface Window { + /** + * Injected by Faceclaw before any page script runs. `undefined` in the + * stock Even app and other hosts. Prefer {@link getFaceclawExtensions}, + * which checks for it. + */ + getFaceclawExtensions?: (() => FaceclawExtensions) | null; + } +} + +/** + * Return the Faceclaw extension API if the app is running inside Faceclaw, or + * `null` otherwise (in the stock Even app, a browser, a simulator, or Node). + * Safe to call anywhere, at any time; Faceclaw installs the API before any page + * script runs. + * + * @group Entry point + */ +export function getFaceclawExtensions(): FaceclawExtensions | null { + const getter = typeof window !== "undefined" ? window.getFaceclawExtensions : null; + return typeof getter === "function" ? getter() : null; +} diff --git a/evenhub-extensions/test/stock-sdk-compat.ts b/evenhub-extensions/test/stock-sdk-compat.ts new file mode 100644 index 00000000..e3d09263 --- /dev/null +++ b/evenhub-extensions/test/stock-sdk-compat.ts @@ -0,0 +1,64 @@ +// Compile-only check (run by `npm run check`): the stock SDK's container and +// page classes must be accepted wherever the extended layout types are, so +// apps can keep using the stock builders with createLayout/replaceLayout. +import { + CreateStartUpPageContainer, + ImageContainerProperty, + ListContainerProperty, + ListItemContainerProperty, + MenuContainerProperty, + MenuItemProperty, + RebuildPageContainer, + TextContainerProperty, +} from "@evenrealities/even_hub_sdk"; +import type { + FaceclawExtensions, + FaceclawImageContainer, + FaceclawLayout, + FaceclawListContainer, + FaceclawMenu, + FaceclawTextContainer, +} from "../src/index"; + +const text = new TextContainerProperty({ + containerID: 1, + containerName: "title", + xPosition: 0, + yPosition: 0, + width: 576, + height: 40, + content: "Hello", + textColor: 3, + isEventCapture: 1, +}); +const image = new ImageContainerProperty({ containerID: 2, containerName: "art", width: 576, height: 400 }); +const list = new ListContainerProperty({ + containerID: 3, + containerName: "menu", + itemContainer: new ListItemContainerProperty({ itemName: ["One", "Two"], isItemSelectBorderEn: 1 }), +}); +const menu = new MenuContainerProperty({ menuItems: [new MenuItemProperty({ itemID: 1, itemName: "Reset" })] }); + +const asText: FaceclawTextContainer = text; +const asImage: FaceclawImageContainer = image; +const asList: FaceclawListContainer = list; +const asMenu: FaceclawMenu = menu; +void [asText, asImage, asList, asMenu]; + +const fromCreate: FaceclawLayout = new CreateStartUpPageContainer({ containerTotalNum: 1, textObject: [text] }); +const fromRebuild: FaceclawLayout = new RebuildPageContainer({ imageObject: [image] }); + +// Stock instances mixed with the extended fields in a literal. +const mixed: FaceclawLayout = { + containerTotalNum: 3, + textObject: [Object.assign(new TextContainerProperty({ containerID: 1, containerName: "title" }), { preserve: true })], + imageObject: [image], + listObject: [list], + menuObject: menu, +}; + +declare const fc: FaceclawExtensions; +void fc.createLayout(fromCreate); +void fc.replaceLayout(fromRebuild); +void fc.replaceLayout(mixed); +void fc.replaceLayout(new RebuildPageContainer({ textObject: [new TextContainerProperty({ containerID: 1 })] })); diff --git a/faceclaw-extensions/tsconfig.json b/evenhub-extensions/tsconfig.json similarity index 56% rename from faceclaw-extensions/tsconfig.json rename to evenhub-extensions/tsconfig.json index f695761c..bd543739 100644 --- a/faceclaw-extensions/tsconfig.json +++ b/evenhub-extensions/tsconfig.json @@ -3,12 +3,10 @@ "target": "ES2020", "module": "ESNext", "moduleResolution": "bundler", - "declaration": true, - "rootDir": "src", - "outDir": "dist", "strict": true, + "noEmit": true, "skipLibCheck": true, - "lib": ["ESNext", "DOM"] + "lib": ["ES2020", "DOM"] }, - "include": ["src/**/*"] + "include": ["src/**/*", "test/**/*"] } diff --git a/evenhub-extensions/tsup.config.ts b/evenhub-extensions/tsup.config.ts new file mode 100644 index 00000000..911dc0dd --- /dev/null +++ b/evenhub-extensions/tsup.config.ts @@ -0,0 +1,9 @@ +import { defineConfig } from "tsup"; + +export default defineConfig({ + entry: ["src/index.ts"], + format: ["esm", "cjs"], + dts: true, + clean: true, + target: "es2020", +}); diff --git a/evenhub-extensions/typedoc.json b/evenhub-extensions/typedoc.json new file mode 100644 index 00000000..7133f76a --- /dev/null +++ b/evenhub-extensions/typedoc.json @@ -0,0 +1,42 @@ +{ + "$schema": "https://typedoc-plugin-markdown.org/schema.json", + "entryPoints": [ + "src/index.ts" + ], + "tsconfig": "tsconfig.json", + "plugin": [ + "typedoc-plugin-markdown" + ], + "out": "docs/api", + "readme": "none", + "outputFileStrategy": "modules", + "hidePageHeader": true, + "hideBreadcrumbs": true, + "useCodeBlocks": true, + "disableSources": true, + "excludeExternals": true, + "treatWarningsAsErrors": true, + "groupOrder": [ + "Entry point", + "Window lifecycle", + "API keys", + "Buzzer", + "Compass", + "Extended layout", + "Assistant tools", + "Properties", + "Methods", + "*" + ], + "sort": [ + "source-order" + ], + "interfacePropertiesFormat": "table", + "typeDeclarationFormat": "table", + "parametersFormat": "table", + "tableColumnSettings": { + "hideInherited": true, + "hideOverrides": true, + "hideSources": true + } +} diff --git a/faceclaw-extensions/README.md b/faceclaw-extensions/README.md deleted file mode 100644 index b5abe31a..00000000 --- a/faceclaw-extensions/README.md +++ /dev/null @@ -1,138 +0,0 @@ -# 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. | -| `addCompassListener(fn): () => void` | Activate the magnetometer; receive heading samples (see note). | -| `createLayout(layout): Promise` | Build the initial page (extended layout: full 576×452, no count limit, `preserve`). | -| `replaceLayout(layout): Promise` | 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 - -Each `CompassReading` carries several headings, all degrees clockwise in -[0, 360): - -- `headingDegrees` — the raw glasses reading. **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, so this is relative. -- `magneticHeadingDegrees` — raw reading corrected by the wearer's calibration - offset from the host's Compass app. `wearerCalibrated` says whether they have - calibrated; until then it equals `headingDegrees`. -- `declinationDegrees` / `trueHeadingDegrees` — local declination from the - phone's location, and the magnetic heading with it applied. Absent when the - host has no location (no permission, or no fix yet). - -Prefer `trueHeadingDegrees` when present, then `magneticHeadingDegrees`. If -`wearerCalibrated` is false, treat them as relative or let the user zero them. - -### 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..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. diff --git a/faceclaw-extensions/package.json b/faceclaw-extensions/package.json deleted file mode 100644 index 3cb3c8bc..00000000 --- a/faceclaw-extensions/package.json +++ /dev/null @@ -1,21 +0,0 @@ -{ - "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 deleted file mode 100644 index 5ca31f5c..00000000 --- a/faceclaw-extensions/src/index.ts +++ /dev/null @@ -1,279 +0,0 @@ -/** - * 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..`); `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; - - /** - * 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; - - /** - * 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; - - /** - * 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; - - /** - * 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; -} diff --git a/tests/evenhub-containers.test.cjs b/tests/evenhub-containers.test.cjs index 0e183d2f..2af839ae 100644 --- a/tests/evenhub-containers.test.cjs +++ b/tests/evenhub-containers.test.cjs @@ -103,3 +103,18 @@ test("a list without isItemSelectBorderEn has no selection border (protobuf defa assert.equal(page.containers[0].selectBorder, false); assert.equal(page.containers[0].itemWidth, 0); }); + +test("flags accept booleans (extension layouts) as well as 0/1 (stock)", () => { + const page = parsePage({ + listObject: [{ containerID: 1, containerName: "l", isEventCapture: true, preserve: true, itemContainer: { itemName: ["a"], isItemSelectBorderEn: true } }], + textObject: [ + { containerID: 2, containerName: "t", isEventCapture: 1, preserve: 1 }, + { containerID: 3, containerName: "u", isEventCapture: false, preserve: false }, + ], + }); + assert.deepEqual( + page.containers.map((c) => [c.name, c.isEventCapture, c.preserve]), + [["l", true, true], ["t", true, true], ["u", false, false]], + ); + assert.equal(page.containers[0].selectBorder, true); +}); diff --git a/tests/evenhub-extensions-shim.test.cjs b/tests/evenhub-extensions-shim.test.cjs new file mode 100644 index 00000000..1ad5e5f5 --- /dev/null +++ b/tests/evenhub-extensions-shim.test.cjs @@ -0,0 +1,101 @@ +const test = require('node:test'); +const assert = require('node:assert/strict'); +const fs = require('node:fs'); +const path = require('node:path'); +const vm = require('node:vm'); + +// The injected shim (app/apps/evenhub/session.ts) and the published types +// (evenhub-extensions/src/index.ts) describe the same API from two sides. +const source = fs.readFileSync(path.join(__dirname, '../app/apps/evenhub/session.ts'), 'utf8'); +const template = source.match(/export function buildFaceclawExtensionsScript[^`]*`([\s\S]*?)`;\n}/)[1]; +const shim = template.replace('${JSON.stringify(versionString)}', JSON.stringify('Faceclaw/9.9.9')); +const types = fs.readFileSync(path.join(__dirname, '../evenhub-extensions/src/index.ts'), 'utf8'); + +function interfaceMembers(name) { + const body = types.match(new RegExp(`export interface ${name} \\{([\\s\\S]*?)\\n\\}`))[1]; + const withoutComments = body.replace(/\/\*\*[\s\S]*?\*\//g, ''); + return [...withoutComments.matchAll(/^ {2}(?:readonly )?(\w+)[?(:]/gm)].map((m) => m[1]).sort(); +} + +function page() { + const posted = []; + const win = { + console, JSON, Promise, Array, Object, Error, String, + __faceclawEvenHub: { postMessage(name, argsJson, id) { posted.push({ name, args: JSON.parse(argsJson), id }); } }, + }; + win.window = win; + vm.createContext(win); + vm.runInContext(shim, win); + const fc = win.getFaceclawExtensions(); + return { win, fc, posted }; +} + +test('the shim implements exactly the members the package declares', () => { + const { fc } = page(); + assert.deepEqual(Object.keys(fc).sort(), interfaceMembers('FaceclawExtensions')); +}); + +test('version and api level are available synchronously', () => { + const { fc } = page(); + assert.equal(fc.getVersion(), 'Faceclaw/9.9.9'); + assert.equal(fc.apiVersion, 1); +}); + +test('calls resolve with the host value and reject with an Error', async () => { + const { win, fc, posted } = page(); + const ok = fc.getConfiguredApiKeys(); + const bad = fc.playBuzzer([{ freq: 440, ms: 100 }]); + assert.deepEqual(posted.map((p) => [p.name, p.args[0]]), [['faceclawExt', 'getConfiguredApiKeys'], ['faceclawExt', 'playBuzzer']]); + assert.ok(posted.every((p) => p.id > 0)); + win.__fcExtResolve(posted[0].id, true, ['openai']); + win.__fcExtResolve(posted[1].id, false, 'no glasses'); + assert.deepEqual(await ok, ['openai']); + await assert.rejects(bad, (error) => error instanceof win.Error && error.message === 'no glasses'); +}); + +test('fire-and-forget calls use id 0', () => { + const { fc, posted } = page(); + fc.returnToAppSwitcher(); + fc.quit(); + assert.deepEqual(posted.map((p) => [p.args[0], p.id]), [['returnToAppSwitcher', 0], ['quit', 0]]); +}); + +test('a listener that unsubscribes during dispatch does not skip the next one', () => { + const { win, fc } = page(); + const seen = []; + const offA = fc.addWindowLifecycleListener((e) => { seen.push(`a:${e.type}`); offA(); }); + fc.addWindowLifecycleListener((e) => seen.push(`b:${e.type}`)); + win.__fcExtEvent('windowLifecycle', { type: 'hidden' }); + win.__fcExtEvent('windowLifecycle', { type: 'visible' }); + assert.deepEqual(seen, ['a:hidden', 'b:hidden', 'b:visible']); +}); + +test('the compass is enabled for the first listener and disabled after the last', () => { + const { win, fc, posted } = page(); + const readings = []; + const off1 = fc.addCompassListener((r) => readings.push(r.headingDegrees)); + const off2 = fc.addCompassListener(() => {}); + win.__fcExtEvent('compass', { headingDegrees: 90 }); + off1(); + off2(); + assert.deepEqual(readings, [90]); + assert.deepEqual(posted.map((p) => p.args), [['setCompass', true], ['setCompass', false]]); +}); + +test('assistant tools send specs to the host and run handlers on invoke', async () => { + const { win, fc, posted } = page(); + fc.setAssistantTools([ + { name: 'double', description: 'Doubles n', handler: ({ n }) => n * 2 }, + { name: 'fail', description: 'Throws', availability: 'open', handler: () => { throw new Error('nope'); } }, + ]); + assert.deepEqual(posted[0].args, ['setAssistantTools', [ + { name: 'double', description: 'Doubles n', parameters: { type: 'object', properties: {} }, availability: 'foreground' }, + { name: 'fail', description: 'Throws', parameters: { type: 'object', properties: {} }, availability: 'open' }, + ]]); + win.__fcExtInvokeTool(7, 'double', { n: 21 }); + win.__fcExtInvokeTool(8, 'fail', {}); + win.__fcExtInvokeTool(9, 'missing', {}); + await new Promise((resolve) => setImmediate(resolve)); + const results = posted.filter((p) => p.name === 'faceclawExtToolResult').map((p) => p.args).sort((a, b) => a[0] - b[0]); + assert.deepEqual(results, [[7, true, 42], [8, false, 'nope'], [9, false, 'unknown tool missing']]); +});