From 4ee0af86cc13ec9e10c8b73111234f5afee750aa Mon Sep 17 00:00:00 2001 From: James Babcock Date: Tue, 6 Oct 2026 23:02:08 -0700 Subject: [PATCH 01/65] EvenHub API extensions: Set package name, fix some bugs --- .github/workflows/tests.yml | 16 + .oxlintrc.json | 2 +- app/apps/evenhub/compass-router.ts | 2 +- app/apps/evenhub/containers.ts | 23 +- app/apps/evenhub/session.ts | 24 +- evenhub-extensions/LICENSE | 21 + evenhub-extensions/README.md | 202 ++ evenhub-extensions/docs/api/README.md | 559 +++++ evenhub-extensions/package-lock.json | 1817 +++++++++++++++++ evenhub-extensions/package.json | 59 + evenhub-extensions/src/index.ts | 472 +++++ evenhub-extensions/test/stock-sdk-compat.ts | 64 + .../tsconfig.json | 8 +- evenhub-extensions/tsup.config.ts | 9 + evenhub-extensions/typedoc.json | 42 + faceclaw-extensions/README.md | 138 -- faceclaw-extensions/package.json | 21 - faceclaw-extensions/src/index.ts | 279 --- tests/evenhub-containers.test.cjs | 15 + tests/evenhub-extensions-shim.test.cjs | 101 + 20 files changed, 3416 insertions(+), 458 deletions(-) create mode 100644 evenhub-extensions/LICENSE create mode 100644 evenhub-extensions/README.md create mode 100644 evenhub-extensions/docs/api/README.md create mode 100644 evenhub-extensions/package-lock.json create mode 100644 evenhub-extensions/package.json create mode 100644 evenhub-extensions/src/index.ts create mode 100644 evenhub-extensions/test/stock-sdk-compat.ts rename {faceclaw-extensions => evenhub-extensions}/tsconfig.json (56%) create mode 100644 evenhub-extensions/tsup.config.ts create mode 100644 evenhub-extensions/typedoc.json delete mode 100644 faceclaw-extensions/README.md delete mode 100644 faceclaw-extensions/package.json delete mode 100644 faceclaw-extensions/src/index.ts create mode 100644 tests/evenhub-extensions-shim.test.cjs 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']]); +}); From 84baee9c7668c84bdc848a15ca2d3c2d6e8960a5 Mon Sep 17 00:00:00 2001 From: James Babcock Date: Wed, 7 Oct 2026 01:22:42 -0700 Subject: [PATCH 02/65] EvenHub extensions: Fonts, window icons, touch-start events --- app/apps/evenhub/compositor.ts | 20 +- app/apps/evenhub/containers.ts | 22 +- app/apps/evenhub/device-status-source.ts | 28 ++ app/apps/evenhub/device-status.ts | 63 +++ app/apps/evenhub/evenhub-window.ts | 25 +- app/apps/evenhub/font-spec.ts | 171 ++++++++ app/apps/evenhub/fonts.ts | 139 +++++++ app/apps/evenhub/manager.ts | 5 +- app/apps/evenhub/session.ts | 255 +++++++++--- app/apps/evenhub/window-icon.ts | 119 ++++++ app/g2/ios-preview-controller.ts | 7 + app/graphics/bdffont.ts | 23 ++ app/ui/shell/shell.ts | 27 +- evenhub-extensions/README.md | 129 +++++- evenhub-extensions/docs/api/README.md | 414 +++++++++++++++++--- evenhub-extensions/src/index.ts | 270 ++++++++++++- evenhub-extensions/test/stock-sdk-compat.ts | 12 + evenhub-extensions/typedoc.json | 7 +- tests/evenhub-containers.test.cjs | 23 ++ tests/evenhub-device-status.test.cjs | 45 +++ tests/evenhub-extensions-shim.test.cjs | 63 +++ tests/evenhub-font-spec.test.cjs | 84 ++++ tests/evenhub-window-icon.test.cjs | 56 +++ tests/ios-glanceboard.test.cjs | 1 + tests/tsconfig.json | 3 + 25 files changed, 1884 insertions(+), 127 deletions(-) create mode 100644 app/apps/evenhub/device-status-source.ts create mode 100644 app/apps/evenhub/device-status.ts create mode 100644 app/apps/evenhub/font-spec.ts create mode 100644 app/apps/evenhub/fonts.ts create mode 100644 app/apps/evenhub/window-icon.ts create mode 100644 tests/evenhub-device-status.test.cjs create mode 100644 tests/evenhub-font-spec.test.cjs create mode 100644 tests/evenhub-window-icon.test.cjs diff --git a/app/apps/evenhub/compositor.ts b/app/apps/evenhub/compositor.ts index e154ed41..8518facf 100644 --- a/app/apps/evenhub/compositor.ts +++ b/app/apps/evenhub/compositor.ts @@ -4,7 +4,8 @@ * * Text uses Even's extracted 20px firmware font (via EvenHubFont), measured * and wrapped with @evenrealities/pretext, so glyph widths and line breaks - * match what apps expect. + * match what apps expect. Extended layouts may pick other fonts per container + * (fonts.ts), which wrap with Faceclaw's own text wrapping. * * Known deviations from stock, acceptable for now: * - List rendering is a plain vertical list. A non-zero itemWidth sets the @@ -13,7 +14,7 @@ * - Lists scroll with our menus' animation and bounce (see list-menu.ts). */ import { GrayImage } from "../../graphics/image"; -import { EvenHubFont } from "../../graphics/evenhub-font"; +import { containerFace } from "./fonts"; import { type EvenHubContainer, type EvenHubImageContainer, @@ -47,14 +48,11 @@ function paintTextContainer(image: GrayImage, container: EvenHubTextContainer): // the container's border at full brightness regardless. paintBorder(image, container); const inset = container.borderWidth + container.paddingLength; - EvenHubFont.get().drawTextWrapped( - image, - container.x + inset, - container.y + inset, - Math.max(1, container.width - 2 * inset), - container.content, - textGrey(container.textColor), - ); + const face = containerFace(container.font); + const lines = face.wrap(container.content, Math.max(1, container.width - 2 * inset)); + for (let i = 0; i < lines.length; i++) { + face.drawText(image, container.x + inset, container.y + inset + i * face.lineHeight, lines[i]!, textGrey(container.textColor)); + } } function paintBorder( @@ -94,7 +92,7 @@ function paintImageContainer(image: GrayImage, container: EvenHubImageContainer) function paintListContainer(image: GrayImage, container: EvenHubListContainer, focused: boolean): void { paintBorder(image, container); - paintListItems(image, container, EvenHubFont.get(), focused); + paintListItems(image, container, containerFace(container.font), focused); } /** Bottom-to-top paint order for a page's containers. */ diff --git a/app/apps/evenhub/containers.ts b/app/apps/evenhub/containers.ts index b62f631b..6cb7f629 100644 --- a/app/apps/evenhub/containers.ts +++ b/app/apps/evenhub/containers.ts @@ -5,6 +5,7 @@ * (Container_ID), and numbers sometimes arrive as strings, so all field * reads go through loose key matching (the SDK's pickLoose behavior). */ +import { mergeFontSpecs, parseFontSpec, type EvenHubFontSpec } from "./font-spec"; export type EvenHubTextContainer = { kind: "text"; @@ -24,6 +25,8 @@ export type EvenHubTextContainer = { content: string; /** SDK 0.0.14 textColor: brightness level 0..4; undefined means the device default (4). */ textColor: number | undefined; + /** Extended-layout font (merged with the layout's default); undefined is the stock font. */ + font: EvenHubFontSpec | undefined; }; export type EvenHubImageContainer = { @@ -63,6 +66,8 @@ export type EvenHubListContainer = { selectBorder: boolean; /** Selection is host-local: scroll moves it with no app round-trip. */ selectedIndex: number; + /** Extended-layout font (merged with the layout's default); undefined is the stock font. */ + font: EvenHubFontSpec | undefined; }; export type EvenHubContainer = EvenHubTextContainer | EvenHubImageContainer | EvenHubListContainer; @@ -149,7 +154,12 @@ function readBorderWidth(json: Record): number { return Math.max(0, Math.min(MAX_BORDER_WIDTH, readNumber(json, "borderWidth", 0))); } -function parseTextContainer(json: Record): EvenHubTextContainer { +/** A container's font: its own `font` over the layout-wide default. */ +function readFont(json: Record, layoutFont: EvenHubFontSpec | undefined): EvenHubFontSpec | undefined { + return mergeFontSpecs(layoutFont, parseFontSpec(pickLoose(json, "font"))); +} + +function parseTextContainer(json: Record, layoutFont: EvenHubFontSpec | undefined): EvenHubTextContainer { return { kind: "text", id: readNumber(json, "containerID", 0), @@ -166,6 +176,7 @@ function parseTextContainer(json: Record): EvenHubTextContainer preserve: readFlag(json, "preserve"), content: readString(json, "content", ""), textColor: readTextBrightness(json), + font: readFont(json, layoutFont), }; } @@ -238,7 +249,7 @@ function parseImageContainer(json: Record): EvenHubImageContain }; } -function parseListContainer(json: Record): EvenHubListContainer { +function parseListContainer(json: Record, layoutFont: EvenHubFontSpec | undefined): EvenHubListContainer { const itemContainer = asRecord(pickLoose(json, "itemContainer")); const itemNamesRaw = pickLoose(itemContainer, "itemName"); const itemNames = Array.isArray(itemNamesRaw) ? itemNamesRaw.map(String) : []; @@ -260,6 +271,7 @@ function parseListContainer(json: Record): EvenHubListContainer itemWidth: readNumber(itemContainer, "itemWidth", 0), selectBorder: readFlag(itemContainer, "isItemSelectBorderEn"), selectedIndex: 0, + font: readFont(json, layoutFont), }; } @@ -274,9 +286,11 @@ function parseListContainer(json: Record): EvenHubListContainer */ export function parsePage(data: Record): EvenHubPage { const containers: EvenHubContainer[] = []; + // Extended layouts may set a default font for every text and list container. + const layoutFont = parseFontSpec(pickLoose(data, "font")); const lists = pickLoose(data, "listObject"); if (Array.isArray(lists)) { - for (const item of lists) containers.push(parseListContainer(asRecord(item))); + for (const item of lists) containers.push(parseListContainer(asRecord(item), layoutFont)); } const images = pickLoose(data, "imageObject"); if (Array.isArray(images)) { @@ -284,7 +298,7 @@ export function parsePage(data: Record): EvenHubPage { } const texts = pickLoose(data, "textObject"); if (Array.isArray(texts)) { - for (const item of texts) containers.push(parseTextContainer(asRecord(item))); + for (const item of texts) containers.push(parseTextContainer(asRecord(item), layoutFont)); } return { containers, menuItems: parseMenuItems(data) }; } diff --git a/app/apps/evenhub/device-status-source.ts b/app/apps/evenhub/device-status-source.ts new file mode 100644 index 00000000..82423308 --- /dev/null +++ b/app/apps/evenhub/device-status-source.ts @@ -0,0 +1,28 @@ +/** + * The live data behind an EvenHub app's device status: glasses presence (fed + * by the connection controller), the headset battery (from the shell's top + * bar state), and the paired glasses' serial. + */ +import { shell } from "../../ui/shell/shell"; +import { getGlassesPresence, onGlassesPresenceChanged } from "../../g2/glasses-presence"; +import { loadPairedGlassesIdentity } from "../../g2/device-addresses"; +import { type EvenHubDeviceStatusSource } from "./device-status"; + +export const liveDeviceStatusSource: EvenHubDeviceStatusSource = { + read: () => { + const presence = getGlassesPresence(); + return { + serial: loadPairedGlassesIdentity()?.serial ?? null, + connected: presence.connected, + worn: presence.worn, + battery: shell.getBatteryLevels().headset, + charging: presence.charging, + }; + }, + subscribe: (listener) => { + const offs = [onGlassesPresenceChanged(listener), shell.onBatteryLevelsChanged(listener)]; + return () => { + for (const off of offs) off(); + }; + }, +}; diff --git a/app/apps/evenhub/device-status.ts b/app/apps/evenhub/device-status.ts new file mode 100644 index 00000000..e281733c --- /dev/null +++ b/app/apps/evenhub/device-status.ts @@ -0,0 +1,63 @@ +/** + * The stock SDK's DeviceStatus (getGlassesInfo().status and the + * deviceStatusChanged push), built from what Faceclaw actually knows about + * the glasses. Pure, so it can be tested without NativeScript. + */ + +/** Used when no glasses have been paired (preview-only mode). */ +export const PLACEHOLDER_SERIAL = "FACECLAW-G2"; + +/** Wire shape of the SDK's DeviceStatus. Unknown fields are omitted rather than guessed. */ +export type EvenHubDeviceStatus = { + sn: string; + connectType: "connected" | "disconnected"; + isWearing?: boolean; + batteryLevel?: number; + isCharging?: boolean; + isInCase?: boolean; +}; + +export type EvenHubDeviceStatusInput = { + /** The paired glasses' serial number, or null when none are paired. */ + serial: string | null; + connected: boolean; + /** null until the firmware reports a wear state this session. */ + worn: boolean | null; + /** Last known headset battery percentage, or null if never reported. */ + battery: number | null; + charging: boolean; +}; + +/** Where a session reads the device status from (live in the app; fixed in tests). */ +export type EvenHubDeviceStatusSource = { + read(): EvenHubDeviceStatusInput; + /** Call `listener` after anything read() reports may have changed. Returns an unsubscribe function. */ + subscribe(listener: () => void): () => void; +}; + +/** No glasses: what a session reports when it isn't given a live source. */ +export const OFFLINE_DEVICE_STATUS_SOURCE: EvenHubDeviceStatusSource = { + read: () => ({ serial: null, connected: false, worn: null, battery: null, charging: false }), + subscribe: () => () => {}, +}; + +export function buildEvenHubDeviceStatus(input: EvenHubDeviceStatusInput): EvenHubDeviceStatus { + const status: EvenHubDeviceStatus = { + // The SDK only applies a status push whose sn matches getGlassesInfo's, + // so both must come from here. + sn: input.serial?.trim() || PLACEHOLDER_SERIAL, + connectType: input.connected ? "connected" : "disconnected", + isCharging: input.charging, + // The G2 only charges in its case, and Faceclaw has no separate + // in-case report. + isInCase: input.charging, + }; + if (input.worn !== null) status.isWearing = input.worn; + if (input.battery !== null) status.batteryLevel = input.battery; + return status; +} + +export function sameDeviceStatus(a: EvenHubDeviceStatus, b: EvenHubDeviceStatus): boolean { + return a.sn === b.sn && a.connectType === b.connectType && a.isWearing === b.isWearing && + a.batteryLevel === b.batteryLevel && a.isCharging === b.isCharging && a.isInCase === b.isInCase; +} diff --git a/app/apps/evenhub/evenhub-window.ts b/app/apps/evenhub/evenhub-window.ts index 09d399d1..d359b2ee 100644 --- a/app/apps/evenhub/evenhub-window.ts +++ b/app/apps/evenhub/evenhub-window.ts @@ -5,7 +5,7 @@ */ import { GrayImage } from "../../graphics/image"; import { EVENHUB_SCREEN_WIDTH } from "./compositor"; -import { type InputEvent } from "../../ui/gestures"; +import { directionalFallback, isDirectionalInput, type InputEvent } from "../../ui/gestures"; import { type Layer, type LayerContext } from "../../ui/layers"; import { createInProcessWindow, @@ -18,6 +18,13 @@ import { EvenHubSession } from "./session"; import { renderInstalledEvenHubIcon } from "./installed-apps"; class EvenHubAppLayer implements Layer { + /** + * Watch swipes become the usual stock gestures here rather than in the + * stack's fallback, which labels them as ring input: an app reading the + * extension's source field should see that they came from the watch. + */ + readonly acceptsDirectional = true; + constructor(private readonly session: EvenHubSession) {} paint(ctx: LayerContext): GrayImage { @@ -40,7 +47,7 @@ class EvenHubAppLayer implements Layer { // menu intercepts tap-then-hold), which is the guaranteed way out since // EvenHub apps own double-click. Tap-then-hold is still reported to the // app as LONG_PRESS_EVENT — see the handleInput wrapper below. - this.session.handleGesture(event); + this.session.handleGesture(isDirectionalInput(event) ? ({ ...directionalFallback(event), source: "watch" } as InputEvent) : event); } } @@ -50,6 +57,7 @@ export function createEvenHubWindow( session: EvenHubSession, options: InProcessAppOptions, onShowPhone: () => void, + requestShellRender: () => void, ): InProcessWindow { const fallbackIcon = windowIcon("package", session.manifest.name.charAt(0).toUpperCase() || "E"); const created = createInProcessWindow({ @@ -58,11 +66,14 @@ export function createEvenHubWindow( title: session.manifest.name, iconLetter: session.manifest.name.charAt(0).toUpperCase() || "E", closeable: true, + // An icon the app set at runtime (extension setWindowIcon) wins over the + // package's. drawIcon: makeImageWindowIcon( - (size) => renderInstalledEvenHubIcon(session.manifest.packageId, size), + (size) => session.renderWindowIcon(size) ?? renderInstalledEvenHubIcon(session.manifest.packageId, size), fallbackIcon, ), heightMode: "medium", + keepsScreenOn: () => session.keepsScreenOn(), // The window's context menu doubles as the OS contextual menu EvenHub // apps register with `menuObject` (SDK 0.0.14): the app's own entries come // first, then the host entries. Evaluated at open time, so a rebuild that @@ -99,6 +110,14 @@ export function createEvenHubWindow( // The extended layout uses the full 576x452 app area ("max"); stock apps // stay in the 576x288 band ("medium"). setTallCanvas: (tall) => created.setHeightMode(tall ? "max" : "medium"), + setAttention: (attention) => shell.setWindowAttention(windowId, attention), + // Only while the app listens for text: otherwise the shell's Type Into App + // destinations (voice dialog, phone keyboard, watch) would send into a void. + setAcceptsTextInput: (accept) => { + created.window.receiveTextInput = accept ? (text, textOptions) => session.deliverTextInput(text, textOptions) : undefined; + }, + startVoiceInput: () => shell.foregroundWindow()?.windowId === windowId && shell.startVoiceInput(), + iconChanged: requestShellRender, windowId, }); diff --git a/app/apps/evenhub/font-spec.ts b/app/apps/evenhub/font-spec.ts new file mode 100644 index 00000000..a16318b1 --- /dev/null +++ b/app/apps/evenhub/font-spec.ts @@ -0,0 +1,171 @@ +/** + * Font options for EvenHub text and list containers (the extension layout's + * `font: { family, size, weight }`): parsing, inheritance from the layout's + * default, and choosing a face from what is installed. Pure, so it can be + * tested without NativeScript; app/apps/evenhub/fonts.ts loads the result. + * + * A container with no font anywhere keeps the stock firmware font, exactly as + * on stock. Naming any font option switches to Faceclaw's fonts, with the + * defaults below filling the options left out. + */ + +/** A container's font request, after parsing. Absent fields take the defaults. */ +export type EvenHubFontSpec = { + family?: string; + size?: number; + weight?: number; +}; + +export const DEFAULT_FONT_FAMILY = "Roboto"; +/** The stock firmware font's size, so switching family alone keeps text about the same size. */ +export const DEFAULT_FONT_SIZE = 20; +export const DEFAULT_FONT_WEIGHT = 400; +export const MIN_FONT_SIZE = 6; +/** Larger glyphs leave the glyph-cache path (255px limit), so text stops being cheap to send. */ +export const MAX_FONT_SIZE = 128; + +/** + * Parse a `font` object from a layout or container. Undefined when there is + * none; unusable fields are dropped, so `{}` means "Faceclaw's default font". + */ +export function parseFontSpec(raw: unknown): EvenHubFontSpec | undefined { + if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined; + const record = raw as Record; + const spec: EvenHubFontSpec = {}; + if (typeof record.family === "string" && record.family.trim()) spec.family = record.family.trim(); + const size = typeof record.size === "string" ? Number(record.size) : record.size; + if (typeof size === "number" && Number.isFinite(size)) { + spec.size = Math.min(MAX_FONT_SIZE, Math.max(MIN_FONT_SIZE, Math.round(size))); + } + const weight = parseWeight(record.weight); + if (weight !== undefined) spec.weight = weight; + return spec; +} + +function parseWeight(raw: unknown): number | undefined { + if (typeof raw === "string") { + const keyword = raw.trim().toLowerCase(); + if (keyword === "normal") return 400; + if (keyword === "bold") return 700; + raw = Number(keyword); + } + if (typeof raw !== "number" || !Number.isFinite(raw)) return undefined; + return Math.min(1000, Math.max(1, Math.round(raw))); +} + +/** A container's font: its own options over the layout default's, field by field. */ +export function mergeFontSpecs( + layoutDefault: EvenHubFontSpec | undefined, + own: EvenHubFontSpec | undefined, +): EvenHubFontSpec | undefined { + if (!layoutDefault) return own; + if (!own) return layoutDefault; + return { ...layoutDefault, ...own }; +} + +/** One loadable face: a TTF file, a Terminus weight, or the stock font. */ +export type FontFaceCandidate = { + /** Family as the font names itself (e.g. "Inter 18pt"). */ + family: string; + /** 100..900. */ + weight: number; + /** The sizes a bitmap face comes in; null for a scalable face. */ + sizes: readonly number[] | null; + monospace: boolean; + /** Identifies the face to the loader. */ + key: string; +}; + +/** + * The family name apps use: an optical-size suffix ("Inter 18pt") is dropped, + * since the bundled Inter is its 18pt cut and apps would ask for "Inter". + */ +export function displayFamily(family: string): string { + return family.replace(/\s+\d+\s*pt$/i, "").trim() || family; +} + +function normalizeFamily(name: string): string { + return name.toLowerCase().replace(/[^a-z0-9]/g, ""); +} + +export function familyMatches(candidate: string, requested: string): boolean { + const wanted = normalizeFamily(requested); + return normalizeFamily(candidate) === wanted || normalizeFamily(displayFamily(candidate)) === wanted; +} + +/** + * Pick the face and pixel size for a spec. An unknown family falls back to + * DEFAULT_FONT_FAMILY; null when even that is missing (the caller then uses + * the stock font). Weight follows CSS's font matching: 400–500 look up to + * 500 first, lighter requests look lighter first, heavier ones heavier + * first. A bitmap face takes its nearest size (the smaller on a tie). + */ +export function selectFontFace( + spec: EvenHubFontSpec, + candidates: readonly FontFaceCandidate[], +): { face: FontFaceCandidate; size: number } | null { + const family = spec.family ?? DEFAULT_FONT_FAMILY; + let faces = candidates.filter((candidate) => familyMatches(candidate.family, family)); + if (faces.length === 0) faces = candidates.filter((candidate) => familyMatches(candidate.family, DEFAULT_FONT_FAMILY)); + if (faces.length === 0) return null; + const desired = spec.weight ?? DEFAULT_FONT_WEIGHT; + const face = [...faces].sort((a, b) => weightRank(a.weight, desired) - weightRank(b.weight, desired))[0]!; + const requestedSize = spec.size ?? DEFAULT_FONT_SIZE; + return { face, size: face.sizes ? nearestSize(face.sizes, requestedSize) : requestedSize }; +} + +/** Lower is better: CSS font-weight matching as a sort key. */ +function weightRank(weight: number, desired: number): number { + const distance = Math.abs(weight - desired); + if (weight === desired) return 0; + if (desired >= 400 && desired <= 500) { + if (weight > desired && weight <= 500) return distance; + if (weight < desired) return 1000 + distance; + return 2000 + distance; + } + const preferLighter = desired < 400; + return (weight < desired) === preferLighter ? distance : 1000 + distance; +} + +function nearestSize(sizes: readonly number[], requested: number): number { + let best = sizes[0]!; + for (const size of sizes) { + const better = Math.abs(size - requested) < Math.abs(best - requested) || + (Math.abs(size - requested) === Math.abs(best - requested) && size < best); + if (better) best = size; + } + return best; +} + +/** A family as the extension's getFonts() reports it. */ +export type FontFamilyInfo = { + family: string; + weights: number[]; + /** Bitmap families' sizes; absent for scalable families. */ + sizes?: number[]; + monospace: boolean; +}; + +/** Group faces into families for getFonts(), sorted by name. */ +export function describeFontFamilies(candidates: readonly FontFaceCandidate[]): FontFamilyInfo[] { + const families = new Map(); + for (const candidate of candidates) { + const name = displayFamily(candidate.family); + const key = normalizeFamily(name); + let info = families.get(key); + if (!info) { + info = { family: name, weights: [], monospace: candidate.monospace }; + families.set(key, info); + } + if (!info.weights.includes(candidate.weight)) info.weights.push(candidate.weight); + if (candidate.sizes) info.sizes = Array.from(new Set([...(info.sizes ?? []), ...candidate.sizes])); + info.monospace = info.monospace && candidate.monospace; + } + return Array.from(families.values()) + .map((info) => ({ + ...info, + weights: [...info.weights].sort((a, b) => a - b), + ...(info.sizes ? { sizes: [...info.sizes].sort((a, b) => a - b) } : {}), + })) + .sort((a, b) => a.family.localeCompare(b.family)); +} diff --git a/app/apps/evenhub/fonts.ts b/app/apps/evenhub/fonts.ts new file mode 100644 index 00000000..52b4236f --- /dev/null +++ b/app/apps/evenhub/fonts.ts @@ -0,0 +1,139 @@ +/** + * Loads the fonts EvenHub text and list containers ask for (see font-spec.ts + * for the matching rules): the stock firmware font, Terminus at its bitmap + * sizes, and every installed TTF/OTF — the bundled Roboto, Inter, Montserrat + * and Roboto Mono, plus any the user installed from the Files app. + */ +import { EvenHubFont } from "../../graphics/evenhub-font"; +import { getTerminusFont, TERMINUS_SIZES } from "../../graphics/bdffont"; +import { TtfFont } from "../../graphics/ttf-font"; +import { listInstalledFonts } from "../../graphics/installed-fonts"; +import { wrapText } from "../../graphics/textwrap"; +import type { GrayImage, UiFont } from "../../graphics/image"; +import { + describeFontFamilies, + familyMatches, + selectFontFace, + type EvenHubFontSpec, + type FontFaceCandidate, + type FontFamilyInfo, +} from "./font-spec"; + +/** What containers draw text with: the stock font's interface, which UiFonts are adapted to. */ +export type EvenHubTextFace = { + readonly lineHeight: number; + measureLine(text: string): number; + wrap(text: string, maxWidth: number): string[]; + drawText(image: GrayImage, x: number, y: number, text: string, value?: number): void; +}; + +class UiFontFace implements EvenHubTextFace { + constructor(private readonly font: UiFont) {} + + get lineHeight(): number { + return this.font.lineHeight; + } + + measureLine(text: string): number { + return this.font.measureText(text); + } + + wrap(text: string, maxWidth: number): string[] { + return wrapText(this.font, text, maxWidth); + } + + drawText(image: GrayImage, x: number, y: number, text: string, value = 255): void { + this.font.drawText(image, x, y, text, value); + } +} + +const STOCK_KEY = "stock"; +const TERMINUS_KEY_PREFIX = "terminus:"; +const TTF_KEY_PREFIX = "ttf:"; + +const BUILT_IN_FACES: readonly FontFaceCandidate[] = [ + // The firmware font: one size, one weight. + { family: "EvenHub", weight: 400, sizes: [20], monospace: false, key: STOCK_KEY }, + { family: "Terminus", weight: 400, sizes: TERMINUS_SIZES, monospace: true, key: `${TERMINUS_KEY_PREFIX}400` }, + { family: "Terminus", weight: 700, sizes: TERMINUS_SIZES, monospace: true, key: `${TERMINUS_KEY_PREFIX}700` }, +]; + +/** A family the listing lacks is re-listed at most this often (the user may have just installed it). */ +const RELIST_INTERVAL_MS = 30_000; + +let faces: FontFaceCandidate[] | null = null; +let listedAtMs = 0; + +function listFaces(): FontFaceCandidate[] { + const installed = listInstalledFonts() + // Upright faces only: there is no italic option yet. + .filter((font) => font.weightOrder < 1000) + .map((font): FontFaceCandidate => ({ + family: font.family, + weight: font.weightOrder, + sizes: null, + monospace: font.monospace, + key: `${TTF_KEY_PREFIX}${font.path}`, + })); + faces = [...BUILT_IN_FACES, ...installed]; + listedAtMs = Date.now(); + return faces; +} + +/** Whether some listed face has the family (no family asks for the default, which is bundled). */ +function hasFamily(available: readonly FontFaceCandidate[], family: string | undefined): boolean { + return !family || available.some((face) => familyMatches(face.family, family)); +} + +/** Resolved faces by spec; null means the stock font (asked for, or nothing loadable). */ +const resolved = new Map(); + +/** The face for a spec, and whether it is in the family asked for (rather than the fallback). */ +function loadFace(spec: EvenHubFontSpec): { face: EvenHubTextFace | null; exact: boolean } { + let available = faces ?? listFaces(); + if (!hasFamily(available, spec.family) && Date.now() - listedAtMs > RELIST_INTERVAL_MS) available = listFaces(); + const exact = hasFamily(available, spec.family); + return { face: openFace(selectFontFace(spec, available)), exact }; +} + +function openFace(choice: { face: FontFaceCandidate; size: number } | null): EvenHubTextFace | null { + if (!choice || choice.face.key === STOCK_KEY) return null; + const { face, size } = choice; + if (face.key.startsWith(TERMINUS_KEY_PREFIX)) { + const font = getTerminusFont(size, face.weight >= 600); + return font ? new UiFontFace(font) : null; + } + const font = TtfFont.load(face.key.slice(TTF_KEY_PREFIX.length), size); + return font ? new UiFontFace(font) : null; +} + +/** + * The face a container draws with: the stock font when it names no font, + * otherwise the closest match to its spec. + */ +export function containerFace(spec: EvenHubFontSpec | undefined): EvenHubTextFace { + if (!spec) return EvenHubFont.get(); + const key = `${spec.family ?? ""}|${spec.size ?? ""}|${spec.weight ?? ""}`; + let face = resolved.get(key); + if (face === undefined) { + const loaded = loadFace(spec); + face = loaded.face; + // A fallback isn't kept, so a family the user installs later gets picked up. + if (loaded.exact) resolved.set(key, face); + } + // Not cached as an object: EvenHubFont.get() changes once firmware fonts are extracted. + return face ?? EvenHubFont.get(); +} + +/** The font families apps can ask for (extension getFonts). Re-lists installed fonts. */ +export function availableFontFamilies(): FontFamilyInfo[] { + return describeFontFamilies(listFaces()); +} + +/** Width of the widest line of `text` and the line height, in the font a container would use. */ +export function measureContainerText(text: string, spec: EvenHubFontSpec | undefined): { width: number; lineHeight: number } { + const face = containerFace(spec); + let width = 0; + for (const line of text.split("\n")) width = Math.max(width, face.measureLine(line)); + return { width: Math.ceil(width), lineHeight: face.lineHeight }; +} diff --git a/app/apps/evenhub/manager.ts b/app/apps/evenhub/manager.ts index 0b12dabe..14b9382f 100644 --- a/app/apps/evenhub/manager.ts +++ b/app/apps/evenhub/manager.ts @@ -22,6 +22,7 @@ import { unpackRuntime } from "./unpack-runtime"; import { type EvenHubPermission } from "./permissions"; import { EvenHubSession } from "./session"; import { createEvenHubWindow } from "./evenhub-window"; +import { liveDeviceStatusSource } from "./device-status-source"; import { createEvenHubWebView, type EvenHubWebView } from "./webview"; import { shell } from "../../ui/shell/shell"; import { GrayImage } from "../../graphics/image"; @@ -126,7 +127,7 @@ async function startApp( ): Promise { const windowId = `evenhub:app:${nextSerial++}`; const session = new EvenHubSession(manifest, distDir, ctx.appendLog, remoteUrl, - payload => ctx.actions.playBuzzerSequence(payload)); + payload => ctx.actions.playBuzzerSequence(payload), liveDeviceStatusSource); const webView = createEvenHubWebView(session); session.attachWebView({ evaluateJs: webView.evaluateJs, @@ -147,7 +148,7 @@ async function startApp( try { await ctx.launchInProcessApp(windowId, `window:${windowId}`, (options) => - createEvenHubWindow(windowId, appId, session, options, () => showOnPhone(windowId)), + createEvenHubWindow(windowId, appId, session, options, () => showOnPhone(windowId), () => ctx.requestShellRender()), ); } catch (error) { session.close(); throw error; } } diff --git a/app/apps/evenhub/session.ts b/app/apps/evenhub/session.ts index 5fe23a25..90d9034e 100644 --- a/app/apps/evenhub/session.ts +++ b/app/apps/evenhub/session.ts @@ -63,6 +63,16 @@ import { toolRegistry, type ToolResult, type ToolSpec } from "../../assistant/to import { getCurrentLocation } from "../../native/location"; import { LocationTracker, type TrackedLocation } from "../../native/location-tracker"; import { ensureFineLocationPermission } from "../../native/location-permissions"; +import { + buildEvenHubDeviceStatus, + OFFLINE_DEVICE_STATUS_SOURCE, + sameDeviceStatus, + type EvenHubDeviceStatus, + type EvenHubDeviceStatusSource, +} from "./device-status"; +import { parseWindowIcon, WindowIconRenderer } from "./window-icon"; +import { availableFontFamilies, containerFace, measureContainerText } from "./fonts"; +import { parseFontSpec } from "./font-spec"; const UPNG = require("upng-js"); @@ -284,19 +294,29 @@ export function buildFaceclawExtensionsScript(versionString: string): string { if (i >= 0) arr.splice(i, 1); }; } - // Compass: enable on first listener, disable when the last one leaves. - var compassListeners = []; - function addCompass(cb) { - compassListeners.push(cb); - if (compassListeners.length === 1) send("setCompass", [true]); - var off = on("compass", cb); - return function () { - off(); - var i = compassListeners.indexOf(cb); - if (i >= 0) compassListeners.splice(i, 1); - if (compassListeners.length === 0) send("setCompass", [false]); + // Events the host only produces on request (compass, touch-down, text + // input): it is told to start on the first listener and to stop when the + // last one leaves. Each unsubscribe function works once. + function counted(name, setMethod) { + var count = 0; + return function (cb) { + var off = on(name, cb); + if (++count === 1) send(setMethod, [true]); + var active = true; + return function () { + if (!active) return; + active = false; + off(); + if (--count === 0) send(setMethod, [false]); + }; }; } + function setWindowIcon(icon) { + if (!icon) return call("setWindowIcon", [null]); + // Typed arrays (ImageData.data) don't survive JSON; send a plain array. + var data = Array.prototype.slice.call(icon.data || []); + return call("setWindowIcon", [{ width: icon.width, height: icon.height, data: data }]); + } // Voice-assistant tools: specs go to the host; handlers stay here and run when // the host invokes a tool via __fcExtInvokeTool. var toolHandlers = {}; @@ -335,10 +355,18 @@ export function buildFaceclawExtensionsScript(versionString: string): string { getConfiguredApiKeys: function () { return call("getConfiguredApiKeys"); }, requestApiKeyAccess: function (services) { return call("requestApiKeyAccess", [services || []]); }, playBuzzer: function (steps) { return call("playBuzzer", [steps || []]); }, - addCompassListener: addCompass, + addCompassListener: counted("compass", "setCompass"), createLayout: function (layout) { return call("createLayout", [layout || {}]); }, replaceLayout: function (layout) { return call("replaceLayout", [layout || {}]); }, - setAssistantTools: setAssistantTools + setAssistantTools: setAssistantTools, + addTouchDownListener: counted("touchDown", "setTouchDown"), + addTextInputListener: counted("textInput", "setTextInput"), + startVoiceInput: function () { return call("startVoiceInput"); }, + setWindowIcon: setWindowIcon, + setAttention: function (attention) { send("setAttention", [!!attention]); }, + setKeepScreenOn: function (keepOn) { send("setKeepScreenOn", [!!keepOn]); }, + getFonts: function () { return call("getFonts"); }, + measureText: function (text, font) { return call("measureText", [String(text), font || null]); } }; window.getFaceclawExtensions = function () { return extensions; }; })(); @@ -364,6 +392,14 @@ export type EvenHubWindowHooks = { pushOverlay: (layer: Layer) => void; /** Switch the window between the stock 576x288 band and the full 576x452 canvas. */ setTallCanvas: (tall: boolean) => void; + /** Show or clear the attention dot on the window's switcher icon. */ + setAttention: (attention: boolean) => void; + /** Offer (or stop offering) the window as the shell's "Type Into App" destination. */ + setAcceptsTextInput: (accept: boolean) => void; + /** Open the shell's voice dialog aimed at the window; false if it can't open now. */ + startVoiceInput: () => boolean; + /** The app changed its window icon: repaint the switcher. */ + iconChanged: () => void; /** The shell window id (unique per running instance; used for tool registration). */ windowId: string; }; @@ -414,6 +450,21 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenH private shellFocused = true; /** API-key services the user has granted this app this session. */ private readonly grantedApiKeys = new Set(); + /** The app listens for touch-down (extension addTouchDownListener). */ + private touchDownRequested = false; + /** The app listens for text input, so the shell offers it as a Type Into App destination. */ + private textInputRequested = false; + /** The app asked for the attention dot on its switcher icon. */ + private attention = false; + /** The app asked the idle screen timeout to wait while it is in the foreground. */ + private keepScreenOnRequested = false; + /** The app's own switcher icon; null draws the package icon. */ + private windowIcon: WindowIconRenderer | null = null; + /** The paired glasses' serial, read once so getGlassesInfo and every status push agree. */ + private glassesSerial: string | null | undefined = undefined; + /** The last deviceStatusChanged sent, and the subscriptions that refresh it. */ + private lastDeviceStatus: EvenHubDeviceStatus | null = null; + private readonly deviceStatusOffs: (() => void)[] = []; private log: (message: string) => void; constructor( @@ -422,6 +473,7 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenH log: (message: string) => void, remoteUrl = "", private readonly sendBuzzerSequence: (payload: Uint8Array) => Promise | void = () => {}, + private readonly deviceStatusSource: EvenHubDeviceStatusSource = OFFLINE_DEVICE_STATUS_SOURCE, ) { this.manifest = manifest; this.distDir = distDir; @@ -447,14 +499,8 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenH // Launched to drive the glasses (from the on-glasses file browser), so // apps that branch on this should take their glasses path. this.pushMessage("evenAppLaunchSource", { launchSource: "glassesMenu" }); - this.pushMessage("deviceStatusChanged", { - sn: "FACECLAW-G2", - connectType: "connected", - isWearing: true, - batteryLevel: 100, - isCharging: false, - isInCase: false, - }); + this.pushDeviceStatus(); + this.deviceStatusOffs.push(this.deviceStatusSource.subscribe(() => this.pushDeviceStatus())); } // ----- glasses window wiring ----- @@ -462,6 +508,10 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenH attachWindow(hooks: EvenHubWindowHooks): void { this.windowHooks = hooks; this.shellWindowId = hooks.windowId; + // Requests the app made before the window existed. + if (this.textInputRequested) hooks.setAcceptsTextInput(true); + if (this.attention) hooks.setAttention(true); + if (this.windowIcon) hooks.iconChanged(); } windowClosed(): void { @@ -491,18 +541,29 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenH * locally with events only for clicks and boundary scrolls. */ handleGesture(event: InputEvent): void { + // Touch-down has no stock event (an unknown eventType would parse as a + // click), so it goes only to apps that subscribed through the extension. + if (event.type === "ring-press") { + if (this.touchDownRequested) { + this.pushExtEvent("touchDown", { source: extensionInputSource(event.source), timestampMs: event.timestampMs }); + } + return; + } if (!this.page) return; - const capture = this.page ? eventCaptureContainer(this.page) : undefined; + const capture = eventCaptureContainer(this.page); + // The stock eventSource can't tell the watch from the ring, and scrolls + // carry none; the extension field names the device when it is known. + const inputSource = "source" in event && event.source ? extensionInputSource(event.source) : undefined; switch (event.type) { case "click": if (capture?.kind === "list") { - this.emitListEvent(capture, CLICK_EVENT); + this.emitListEvent(capture, CLICK_EVENT, inputSource); } else { - this.emitSysEvent(CLICK_EVENT, gestureSource(event.source)); + this.emitSysEvent(CLICK_EVENT, gestureSource(event.source), inputSource); } break; case "double-click": - this.emitSysEvent(DOUBLE_CLICK_EVENT, gestureSource(event.source)); + this.emitSysEvent(DOUBLE_CLICK_EVENT, gestureSource(event.source), inputSource); break; case "long-press": case "short-then-long-press": @@ -516,9 +577,9 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenH // given exclusive use of the gesture. const eventType = event.type === "long-press-release" ? LONG_PRESS_RELEASE_EVENT : LONG_PRESS_EVENT; if (capture?.kind === "list") { - this.emitListEvent(capture, eventType); + this.emitListEvent(capture, eventType, inputSource); } else { - this.emitSysEvent(eventType, gestureSource(event.source)); + this.emitSysEvent(eventType, gestureSource(event.source), inputSource); } break; } @@ -526,9 +587,9 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenH case "scroll-down": { const eventType = event.type === "scroll-up" ? SCROLL_TOP_EVENT : SCROLL_BOTTOM_EVENT; if (capture?.kind === "list") { - this.scrollList(capture, eventType); + this.scrollList(capture, eventType, inputSource); } else { - this.emitSysEvent(eventType, 0); + this.emitSysEvent(eventType, 0, inputSource); } break; } @@ -551,11 +612,11 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenH this.pushMessage("evenHubEvent", { type: "menuItemClickEvent", jsonData: { itemID } }); } - private scrollList(list: EvenHubListContainer, eventType: number): void { + private scrollList(list: EvenHubListContainer, eventType: number, inputSource?: ExtensionInputSource): void { // Swipe up selects the previous item, swipe down the next (stock direction). const delta = eventType === SCROLL_TOP_EVENT ? -1 : 1; // At a boundary the selection stays put (the list bounces) and the app hears about it. - if (!stepListSelection(list, EvenHubFont.get(), delta)) this.emitListEvent(list, eventType); + if (!stepListSelection(list, containerFace(list.font), delta)) this.emitListEvent(list, eventType, inputSource); this.windowHooks?.requestRender(); } @@ -820,19 +881,10 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenH return ApplicationSettings.getString(this.storageKey(readString(data, "key", "")), ""); case "getUserInfo": return { uid: 0, name: "Faceclaw", avatar: "", country: "" }; - case "getGlassesInfo": - return { - model: "g2", - sn: "FACECLAW-G2", - status: { - sn: "FACECLAW-G2", - connectType: "connected", - isWearing: true, - batteryLevel: 100, - isCharging: false, - isInCase: false, - }, - }; + case "getGlassesInfo": { + const status = this.deviceStatus(); + return { model: "g2", sn: status.sn, status }; + } case "audioControl": return this.audioControl(data); case "getAppLocation": @@ -1001,17 +1053,18 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenH this.pushMessage("evenHubEvent", { type: payloadType, jsonData: elideZeroFields(jsonData) }); } - private emitSysEvent(eventType: number, eventSource: number): void { - this.pushEvenHubEvent("sysEvent", { eventType, eventSource }); + private emitSysEvent(eventType: number, eventSource: number, inputSource?: ExtensionInputSource): void { + this.pushEvenHubEvent("sysEvent", { eventType, eventSource, [INPUT_SOURCE_FIELD]: inputSource }); } - private emitListEvent(list: EvenHubListContainer, eventType: number): void { + private emitListEvent(list: EvenHubListContainer, eventType: number, inputSource?: ExtensionInputSource): void { this.pushEvenHubEvent("listEvent", { containerID: list.id, containerName: list.name, currentSelectItemIndex: list.selectedIndex, currentSelectItemName: list.itemNames[list.selectedIndex] ?? "", eventType, + [INPUT_SOURCE_FIELD]: inputSource, }); } @@ -1027,7 +1080,7 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenH result = await this.dispatchExtension(method, args.slice(1)); } catch (error) { ok = false; - result = String(error); + result = error instanceof Error ? error.message : String(error); this.log(`evenhub: extension call failed: ${error}`); } // id 0 is a fire-and-forget send; nothing is awaiting it. @@ -1060,12 +1113,96 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenH case "setAssistantTools": this.setAssistantTools(Array.isArray(params[0]) ? params[0] : []); return null; + case "setTouchDown": + this.touchDownRequested = params[0] === true; + return null; + case "setTextInput": + this.setTextInputRequested(params[0] === true); + return null; + case "startVoiceInput": + // Without a text listener the dialog would have nowhere in the app to send to. + return this.textInputRequested && (this.windowHooks?.startVoiceInput() ?? false); + case "setWindowIcon": + this.setWindowIcon(params[0]); + return null; + case "setAttention": + this.attention = params[0] === true; + this.windowHooks?.setAttention(this.attention); + return null; + case "setKeepScreenOn": + this.keepScreenOnRequested = params[0] === true; + return null; + case "getFonts": + return availableFontFamilies(); + case "measureText": + // No font measures in the stock font, as a container without one draws. + return measureContainerText(String(params[0] ?? ""), parseFontSpec(params[1])); default: this.log(`evenhub: unknown extension method ${method}`); return null; } } + // ----- device status (stock getGlassesInfo / deviceStatusChanged) ----- + + private deviceStatus(): EvenHubDeviceStatus { + const input = this.deviceStatusSource.read(); + if (this.glassesSerial === undefined) this.glassesSerial = input.serial; + return buildEvenHubDeviceStatus({ ...input, serial: this.glassesSerial }); + } + + /** Push deviceStatusChanged if the status differs from the last one sent. */ + private pushDeviceStatus(): void { + if (this.closed) return; + const status = this.deviceStatus(); + if (this.lastDeviceStatus && sameDeviceStatus(status, this.lastDeviceStatus)) return; + this.lastDeviceStatus = status; + this.pushMessage("deviceStatusChanged", status); + } + + // ----- window controls and text input (extensions) ----- + + /** Whether the idle screen timeout should wait while this window is in the foreground. */ + keepsScreenOn(): boolean { + return this.keepScreenOnRequested; + } + + /** The app's own switcher icon at `size`, or null to draw the package icon. */ + renderWindowIcon(size: number): GrayImage | null { + return this.windowIcon?.render(size) ?? null; + } + + private setWindowIcon(raw: unknown): void { + if (raw == null) { + this.windowIcon = null; + } else { + const image = parseWindowIcon(raw); + if (!image) { + throw new Error( + "setWindowIcon: expected {width, height, data} of at most 256x256, with data holding " + + "width*height grayscale or width*height*4 RGBA bytes", + ); + } + this.windowIcon = new WindowIconRenderer(image); + } + this.windowHooks?.iconChanged(); + } + + private setTextInputRequested(accept: boolean): void { + if (this.textInputRequested === accept) return; + this.textInputRequested = accept; + this.windowHooks?.setAcceptsTextInput(accept); + } + + /** + * Text the shell routed to this window: the voice dialog's Type Into App, + * the phone keyboard, the watch, or remote input. Only arrives while the + * app listens (setAcceptsTextInput). + */ + deliverTextInput(text: string, options?: { submit?: boolean }): void { + this.pushExtEvent("textInput", options?.submit === undefined ? { text } : { text, submit: options.submit }); + } + // ----- compass (EvenHubCompassClient) ----- deliverCompass(reading: EvenHubCompassReading): void { @@ -1249,6 +1386,7 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenH this.pendingToolCalls.clear(); this.locationTracker?.stop(); this.locationTracker = null; + for (const off of this.deviceStatusOffs.splice(0)) off(); if (!this.systemExitSent) { // Best effort: lets the app's teardown handlers run before the webview dies. this.emitSysEvent(SYSTEM_EXIT_EVENT, 0); @@ -1451,6 +1589,27 @@ function luminance(r: number, g: number, b: number): number { return Math.round(0.2126 * r + 0.7152 * g + 0.0722 * b); } +/** + * Input-device names in the extension API: the touchDown event's source, and + * the `faceclawInputSource` field added to stock gesture events. + */ +type ExtensionInputSource = "ring" | "left-touchpad" | "right-touchpad" | "watch"; + +const INPUT_SOURCE_FIELD = "faceclawInputSource"; + +function extensionInputSource(source: InputSource): ExtensionInputSource { + switch (source) { + case "ring": + return "ring"; + case "left-arm": + return "left-touchpad"; + case "right-arm": + return "right-touchpad"; + case "watch": + return "watch"; + } +} + /** * ring/left-arm/right-arm -> PB EventSourceType. The watch is reported to * EvenHub apps as the ring: they only know stock hardware, and the watch's diff --git a/app/apps/evenhub/window-icon.ts b/app/apps/evenhub/window-icon.ts new file mode 100644 index 00000000..87ff6f5e --- /dev/null +++ b/app/apps/evenhub/window-icon.ts @@ -0,0 +1,119 @@ +/** + * App-supplied window icons (the extension setWindowIcon): parse the pixel + * buffer an app sends and scale it to the sizes the app switcher draws at. + * Pure, so it can be tested without NativeScript. + */ +import { GrayImage } from "../../graphics/image"; + +/** Larger icons are refused: they only cost bridge traffic, since switcher icons are ~32px. */ +export const MAX_WINDOW_ICON_DIMENSION = 256; + +/** + * Parse `{width, height, data}` from the bridge into a grayscale image. + * `data` is width*height brightness bytes, or width*height*4 RGBA bytes (an + * ImageData), which are reduced to luminance times alpha. Arrays arrive as + * plain arrays or as JSON-ified typed arrays ({"0": n, ...}). Returns null for + * anything malformed. + */ +export function parseWindowIcon(raw: unknown): GrayImage | null { + if (!raw || typeof raw !== "object") return null; + const record = raw as Record; + const width = Number(record.width); + const height = Number(record.height); + if (!Number.isInteger(width) || !Number.isInteger(height)) return null; + if (width < 1 || height < 1 || width > MAX_WINDOW_ICON_DIMENSION || height > MAX_WINDOW_ICON_DIMENSION) return null; + const data = toNumberArray(record.data); + if (!data) return null; + const area = width * height; + const image = new GrayImage(width, height, 0); + if (data.length === area) { + for (let i = 0; i < area; i++) image.pixels[i] = clampByte(data[i]!); + } else if (data.length === area * 4) { + for (let i = 0; i < area; i++) { + const o = i * 4; + const luminance = 0.2126 * data[o]! + 0.7152 * data[o + 1]! + 0.0722 * data[o + 2]!; + image.pixels[i] = clampByte((luminance * data[o + 3]!) / 255); + } + } else { + return null; + } + return image; +} + +/** + * Scale an icon to fit a size x size box, keeping its aspect ratio, with an + * area-averaging filter. Results are cached per size, since the switcher + * repaints often. + */ +export class WindowIconRenderer { + private readonly scaled = new Map(); + + constructor(private readonly source: GrayImage) {} + + render(size: number): GrayImage { + const box = Math.max(1, Math.round(size)); + let image = this.scaled.get(box); + if (!image) { + image = scaleToFit(this.source, box); + this.scaled.set(box, image); + } + return image; + } +} + +function scaleToFit(source: GrayImage, box: number): GrayImage { + const scale = Math.min(box / source.width, box / source.height); + const width = Math.max(1, Math.round(source.width * scale)); + const height = Math.max(1, Math.round(source.height * scale)); + if (width === source.width && height === source.height) return source; + const out = new GrayImage(width, height, 0); + for (let y = 0; y < height; y++) { + const y0 = (y * source.height) / height; + const y1 = ((y + 1) * source.height) / height; + for (let x = 0; x < width; x++) { + const x0 = (x * source.width) / width; + const x1 = ((x + 1) * source.width) / width; + out.pixels[y * width + x] = clampByte(areaAverage(source, x0, y0, x1, y1)); + } + } + return out; +} + +/** Mean of the source over the rectangle [x0,x1) x [y0,y1), weighting partly covered pixels. */ +function areaAverage(source: GrayImage, x0: number, y0: number, x1: number, y1: number): number { + let sum = 0; + let weight = 0; + for (let sy = Math.floor(y0); sy < Math.min(source.height, Math.ceil(y1)); sy++) { + const wy = Math.min(y1, sy + 1) - Math.max(y0, sy); + for (let sx = Math.floor(x0); sx < Math.min(source.width, Math.ceil(x1)); sx++) { + const w = wy * (Math.min(x1, sx + 1) - Math.max(x0, sx)); + sum += source.pixels[sy * source.width + sx]! * w; + weight += w; + } + } + return weight > 0 ? sum / weight : 0; +} + +function toNumberArray(raw: unknown): number[] | null { + let values: unknown[]; + if (Array.isArray(raw)) { + values = raw; + } else if (raw && typeof raw === "object") { + const record = raw as Record; + values = []; + for (let i = 0; String(i) in record; i++) values.push(record[String(i)]); + } else { + return null; + } + const out: number[] = []; + for (const entry of values) { + const value = Number(entry); + if (!Number.isFinite(value)) return null; + out.push(value); + } + return out; +} + +function clampByte(value: number): number { + return Math.max(0, Math.min(255, Math.round(value))); +} diff --git a/app/g2/ios-preview-controller.ts b/app/g2/ios-preview-controller.ts index 12c1574e..ac4e4971 100644 --- a/app/g2/ios-preview-controller.ts +++ b/app/g2/ios-preview-controller.ts @@ -25,6 +25,7 @@ import { GlanceHost, type GlanceDisplay } from './glance-host' import { createLockScreenImage, LOCK_SCREEN_SURFACE_ID } from './lock-screen' import { OsEventTypeList } from './events' import { loadDeviceAddresses } from './device-addresses' +import { updateGlassesPresence } from './glasses-presence' import { firmwareIncompatibilityMessage, hasCompatibleFirmware } from './firmware-compat' import { isHaltedSessionPhase, suppressAutoReconnect } from './reconnect-policy' import { deviceAddressError } from './ios-peripheral-identity' @@ -373,6 +374,7 @@ export class IosPreviewController { // a session's first snapshot) wakes the screen, to the lock notice if locked. const putOn = wearing && this.glassesWorn === false this.glassesWorn = wearing + this.syncPresence() this.logBluetooth(`Glasses wear state: ${wearing ? 'ON_HEAD' : 'OFF_HEAD'}`) if (!wearing && this.phoneLocked && this.lockEnabled) this.setGlassesLocked(true) if (putOn && this.runtimeRunning && !shell.isScreenOn()) shell.wake('sidebar') @@ -672,6 +674,10 @@ export class IosPreviewController { this.logBluetooth(status) this.emitState() } + /** Mirror the session into glasses-presence (read by EvenHub's device status and Timers). */ + private syncPresence(): void { + updateGlassesPresence({ connected: this.state.phase === 'connected', worn: this.glassesWorn, charging: this.state.charging ?? false }) + } private emitState(): void { if (this.state.phase !== 'connected') resetRingInputFilter() this.pushBrightness() @@ -679,6 +685,7 @@ export class IosPreviewController { if (this.state.phase !== 'connected' && this.state.phase !== 'connecting') this.glassesWorn = null if (this.state.phase !== 'connected') iosVoiceInput.handleSessionEnded() shell.setBatteryLevels({ headset: this.state.battery, headsetCharging: this.state.charging }) + this.syncPresence() this.syncRuntime() if (this.active) this.onConnectionState({ ...this.state }) this.requestShellRender() diff --git a/app/graphics/bdffont.ts b/app/graphics/bdffont.ts index 8bf9dfec..1d43ad05 100644 --- a/app/graphics/bdffont.ts +++ b/app/graphics/bdffont.ts @@ -248,6 +248,29 @@ export function getFont(font: EmbeddedFontName): BdfFont { return loadEmbeddedFont(font); } +/** Every Terminus size bundled under fonts/terminus, each in normal and bold. */ +export const TERMINUS_SIZES = [12, 14, 16, 18, 20, 22, 24, 28, 32] as const; + +const terminusFonts = new Map(); + +/** + * Terminus at any bundled size, normal or bold (EvenHub apps pick fonts by + * size and weight). Null for a size that isn't bundled. The sizes the UI + * already uses come back as the same objects getFont returns. + */ +export function getTerminusFont(size: number, bold: boolean): BdfFont | null { + if (!(TERMINUS_SIZES as readonly number[]).includes(size)) return null; + const name = `terminus${size}${bold ? "b" : ""}`; + if (name in embeddedFonts) return loadEmbeddedFont(name as EmbeddedFontName); + let font = terminusFonts.get(name); + if (!font) { + const text = knownFolders.currentApp().getFile(`fonts/terminus/ter-u${size}${bold ? "b" : "n"}.bdf`).readTextSync(); + font = BdfFont.parse(text, { atlasKey: name }); + terminusFonts.set(name, font); + } + return font; +} + // NOTE: the default UI font getters (getDefaultSmallFont & co.) live in // ./ui-fonts, which resolves the user's font settings to a BdfFont or // TtfFont. This module stays a pure BDF loader. diff --git a/app/ui/shell/shell.ts b/app/ui/shell/shell.ts index 1ad07d0b..632b444f 100644 --- a/app/ui/shell/shell.ts +++ b/app/ui/shell/shell.ts @@ -394,6 +394,7 @@ class Shell { private battery: ShellChromeState["battery"] = { headset: null, headsetCharging: null, ring: null, ringCharging: null, watch: null, watchCharging: null, }; + private readonly batteryListeners = new Set<() => void>(); private attention = new Map(); /** Set while the switcher's selection is on a notification (see NotificationSelection). */ private selectedNotification: NotificationSelection | null = null; @@ -584,7 +585,19 @@ class Shell { } setBatteryLevels(levels: Partial): void { - this.battery = { ...this.battery, ...levels }; + const next = { ...this.battery, ...levels }; + const keys = Object.keys(next) as (keyof ShellChromeState["battery"])[]; + if (keys.every((key) => next[key] === this.battery[key])) return; + this.battery = next; + for (const listener of Array.from(this.batteryListeners)) listener(); + } + + /** Called after any battery level or charging state changes. Returns an unsubscribe function. */ + onBatteryLevelsChanged(listener: () => void): () => void { + this.batteryListeners.add(listener); + return () => { + this.batteryListeners.delete(listener); + }; } /** @@ -1397,16 +1410,20 @@ class Shell { * Open the voice dialog aimed at the foreground window. Called when the * user picks Voice input from the system menu (or an app asks via a * start-voice-input message). The menu click already ended the press, so - * the dialog finishes on click instead of long-press-release. + * the dialog finishes on click instead of long-press-release. Returns + * false when the dialog can't open now (voice input disabled, screen off, + * another dialog or overlay up); true means it is opening, though a + * microphone-permission prompt can still stop it. */ - startVoiceInput(): void { - if (this.config.voiceInputEnabled === false) return; - if (!this.screenOn || this.activeVoiceLayer || !this.stack.isAtBase()) return; + startVoiceInput(): boolean { + if (this.config.voiceInputEnabled === false || this.voiceDialogPending) return false; + if (!this.screenOn || this.activeVoiceLayer || !this.stack.isAtBase()) return false; // The transcript is aimed at the window whose menu requested it; the menu // entry point defaults the highlight to Type Into App. this.focus = "window"; this.openVoiceDialog({ finishOnClick: true, defaultTarget: "app" }); this.config.requestShellRender(); + return true; } /** diff --git a/evenhub-extensions/README.md b/evenhub-extensions/README.md index 0e056c09..56a3d613 100644 --- a/evenhub-extensions/README.md +++ b/evenhub-extensions/README.md @@ -7,10 +7,12 @@ 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. +running in Faceclaw and use some extra capabilities there: a taller canvas, +choice of fonts, the glasses' compass and buzzer, touch-down events and which device an input came +from, dictated or typed text, control of the app's switcher icon and the screen +timeout, 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) @@ -57,11 +59,15 @@ 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 +app's webview. Every extension method 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. +The one addition outside that global is data: Faceclaw adds a +`faceclawInputSource` field to the raw JSON of stock gesture events, which +`getInputSource()` reads. Stock apps ignore it. + ## Checking for features New members will be added over time, and an app may run in a Faceclaw build @@ -107,6 +113,18 @@ The [API reference](docs/api/README.md) documents every member in full. | `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. | +| `addTouchDownListener(fn)` | Hear the moment a finger touches the ring or watch, before the gesture is known. | +| `addTextInputListener(fn)` | Receive dictated or typed text: the app becomes a "Type Into App" destination. | +| `startVoiceInput()` | Open the voice dialog for the app. | +| `setWindowIcon(icon)` | Replace the app's switcher icon with a pixel buffer. | +| `setAttention(on)` | Show or clear the attention dot on the app's switcher icon. | +| `setKeepScreenOn(on)` | Stop the display from sleeping for inactivity while the app is in front. | +| `getFonts()` | List the font families available to text and list containers. | +| `measureText(text, font)` | Measure text in a font, to size or centre it. | + +The package also exports `getInputSource(event)`, which tells you which device +(`ring`, `left-touchpad`, `right-touchpad` or `watch`) produced a stock gesture +event. ### Extended layout @@ -121,6 +139,7 @@ classes. The differences: - 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. +- Text and list containers can use other fonts (see [Fonts](#fonts)). ```ts import { ImageContainerProperty, TextContainerProperty } from "@evenrealities/even_hub_sdk"; @@ -141,6 +160,92 @@ 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. +### Fonts + +In an extended layout, text and list containers can set a `font` with a +`family`, `size` (in pixels) and `weight`. A `font` on the layout is the +default for all of them, and a container's own `font` overrides it field by +field. Without either, text is in the stock firmware font, as before. + +```ts +await fc.createLayout({ + font: { family: "Inter", size: 22 }, + textObject: [ + { containerID: 1, containerName: "title", xPosition: 16, yPosition: 12, width: 544, height: 50, content: "Today", font: { size: 40, weight: "bold" } }, + { containerID: 2, containerName: "body", xPosition: 16, yPosition: 70, width: 544, height: 360, content: "...", isEventCapture: 1 }, + ], +}); +``` + +Faceclaw bundles Roboto, Inter, Montserrat and Roboto Mono (weights 300, 400 +and 700, any size from 6 to 128) and the bitmap font Terminus (sizes 12 to +32, weights 400 and 700). `EvenHub` is the stock font, at 20px only. Users +can install more fonts, and `getFonts()` lists everything available. An +unknown family falls back to Roboto, and the nearest available weight and +(for bitmap fonts) size are used. + +`measureText(text, font)` returns the text's width and line height in a +font, so you can size containers or centre text. A list row is the font's +line height plus 12 pixels. + +### Input sources and touch-down + +The stock `eventSource` field can't tell the watch from the ring, and scrolls +don't carry it at all. Pass the event your `onEvenHubEvent` handler receives +to `getInputSource()` to find out which device it came from: + +```ts +import { getFaceclawExtensions, getInputSource } from "@faceclaw/evenhub-extensions"; + +bridge.onEvenHubEvent((event) => { + const source = getInputSource(event); // "ring", "left-touchpad", "right-touchpad", "watch" or null +}); +``` + +It returns `null` when the source is unknown (some scrolls), for non-gesture +events, and outside Faceclaw. + +A touch-down is the moment a finger lands on the ring or the watch's +touchpad, before Faceclaw knows whether it will become a tap, a scroll or a +hold. The interpreted gesture still arrives afterwards as the usual stock +event. Touch-downs suit games and other latency-sensitive input: + +```ts +fc.addTouchDownListener(({ source, timestampMs }) => flap()); +``` + +The glasses' own touchpads don't report touch-down. + +### Text input + +While the app has a text-input listener, Faceclaw offers it as the "Type Into +App" destination for its voice dialog, the phone keyboard and the watch. The +app can also open the voice dialog itself: + +```ts +fc.addTextInputListener(({ text }) => addNote(text)); + +// For example, from a "Dictate" item in the app's menu: +const opened = await fc.startVoiceInput(); +``` + +### Window icon, attention dot, and screen timeout + +```ts +// Draw a 32x32 icon on a canvas, light on black, and use it in the app switcher. +fc.setWindowIcon(ctx.getImageData(0, 0, 32, 32)); + +// Flag new activity while the app is in the background; clear it when seen. +fc.setAttention(true); + +// Keep the display awake while the app is in front (e.g. a teleprompter). +fc.setKeepScreenOn(true); +``` + +`setWindowIcon` takes `{ width, height, data }` with grayscale or RGBA pixels, +up to 256×256, so an `ImageData` works as is. Pass `null` to restore the +package's icon. + ### Compass Each `CompassReading` has several headings, all in degrees clockwise from north: @@ -191,6 +296,18 @@ 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. +## Stock APIs in Faceclaw + +Faceclaw implements the stock SDK too. Some differences worth knowing: + +- `getDeviceInfo()` and `onDeviceStatusChanged` report the real glasses: + their serial number, whether they are connected and worn, the battery level, + and whether they are charging. `isInCase` is the same as `isCharging`, since + the G2 only charges in its case. Fields Faceclaw doesn't know yet (wear state + before the glasses first report it) are left out. +- `shutDownPageContainer(1)` returns to the app switcher instead of asking to + quit. Use `quit()` to really quit. + ## Stability This package is pre-1.0. Until 1.0 the API may still change. After that, changes diff --git a/evenhub-extensions/docs/api/README.md b/evenhub-extensions/docs/api/README.md index 62b3bfdf..6d1b113e 100644 --- a/evenhub-extensions/docs/api/README.md +++ b/evenhub-extensions/docs/api/README.md @@ -261,6 +261,168 @@ tool's `handler` runs in the app when the assistant calls it. `void` +##### addTouchDownListener() + +```ts +addTouchDownListener(listener): () => void; +``` + +Receive touch-downs: the moment a finger touches the ring or the watch's +touchpad, before Faceclaw knows whether it will become a tap, a scroll or +a hold. The interpreted gesture still arrives afterwards as the usual +stock event. Use it where latency matters, as in games. + +Touch-downs arrive only while the app's window has input focus. The +glasses' own touchpads don't report them. + +###### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `listener` | (`event`) => `void` | Called on each touch-down. | + +###### Returns + +A function that unsubscribes `listener`. + +() => `void` + +##### addTextInputListener() + +```ts +addTextInputListener(listener): () => void; +``` + +Receive text the user sends to the app. While at least one listener is +registered and the app is in the foreground, Faceclaw offers the app as +the "Type Into App" destination of its voice dialog, the phone keyboard +and the watch. + +###### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `listener` | (`event`) => `void` | Called with each piece of text. | + +###### Returns + +A function that unsubscribes `listener`. + +() => `void` + +##### startVoiceInput() + +```ts +startVoiceInput(): Promise; +``` + +Open Faceclaw's voice dialog for this app. When the user sends the +dictation with Type Into App, it arrives at the text-input listeners. + +###### Returns + +`Promise`\<`boolean`\> + +A promise that resolves to true if the dialog is opening, or + false if it can't open: there is no text-input listener, the app isn't + in the foreground, voice input is unavailable, or another dialog is up. + +##### setWindowIcon() + +```ts +setWindowIcon(icon): Promise; +``` + +Replace the app's icon in the app switcher, or pass `null` to go back to +the package's icon. See [WindowIconImage](#windowiconimage) for the format. + +###### Parameters + +| Parameter | Type | +| ------ | ------ | +| `icon` | [`WindowIconImage`](#windowiconimage) \| `null` | + +###### Returns + +`Promise`\<`void`\> + +A promise that resolves once the icon is set, and rejects if the + image is malformed or larger than 256×256. + +##### setAttention() + +```ts +setAttention(attention): void; +``` + +Show or clear the attention dot on the app's switcher icon, for example +when something new arrives while the app is in the background. The dot +stays until the app clears it or closes. + +###### Parameters + +| Parameter | Type | +| ------ | ------ | +| `attention` | `boolean` | + +###### Returns + +`void` + +##### setKeepScreenOn() + +```ts +setKeepScreenOn(keepOn): void; +``` + +Stop the glasses display from turning off for inactivity while the app is +in the foreground, as a teleprompter or navigation app needs. It has no +effect while another window is in front, and the user can still turn the +display off. Pass `false` to restore the normal timeout. + +###### Parameters + +| Parameter | Type | +| ------ | ------ | +| `keepOn` | `boolean` | + +###### Returns + +`void` + +##### getFonts() + +```ts +getFonts(): Promise; +``` + +List the font families available for [FaceclawFont.family](#property-family), +including any the user has installed. + +###### Returns + +`Promise`\<[`FaceclawFontFamily`](#faceclawfontfamily)[]\> + +##### measureText() + +```ts +measureText(text, font?): Promise; +``` + +Measure text as a container with this font would draw it, for example to +size a text container or centre a label. + +###### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `text` | `string` | The text. Lines split at `\n` are measured separately. | +| `font?` | [`FaceclawFont`](#faceclawfont) | The font to measure in. Unlike a container's font, it isn't combined with a layout default. Omit it to measure in the stock font. | + +###### Returns + +`Promise`\<[`TextMeasurement`](#textmeasurement)\> + *** ### getFaceclawExtensions() @@ -278,7 +440,7 @@ script runs. [`FaceclawExtensions`](#faceclawextensions) \| `null` -## Window lifecycle +## Window ### WindowLifecycleEventType @@ -312,51 +474,107 @@ Payload of a [FaceclawExtensions.addWindowLifecycleListener](#addwindowlifecycle | ------ | ------ | ------ | | `type` | [`WindowLifecycleEventType`](#windowlifecycleeventtype) | Which transition happened. | -## API keys +*** -### ApiKeyService +### WindowIconImage -```ts -type ApiKeyService = "openai" | "anthropic" | "soniox" | "elevenlabs" | "mapbox"; -``` +An image for [FaceclawExtensions.setWindowIcon](#setwindowicon). An `ImageData` (from +a canvas's `getImageData`) fits this shape and can be passed directly. -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. +Draw it like Faceclaw's own icons: light strokes on black. Brightness is +coverage, so black is transparent, and Faceclaw inverts the icon for the +selected window. The switcher draws icons at about 32×32; larger images are +scaled down to fit, keeping their aspect ratio. #### 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. | +| `width` | `number` | Width in pixels, 1–256. | +| `height` | `number` | Height in pixels, 1–256. | +| `data` | `ArrayLike`\<`number`\> | Pixels in rows from the top left: either `width * height` grayscale values (0–255), or `width * height * 4` RGBA values, which Faceclaw converts to grayscale (luminance times alpha). | + +## Input + +### InputSource + +```ts +type InputSource = "ring" | "left-touchpad" | "right-touchpad" | "watch"; +``` + +The device an input came from: + +- `ring`: the Even R1 ring (or the ring pad in Faceclaw's phone app). +- `left-touchpad` / `right-touchpad`: the touch areas on the glasses' arms. +- `watch`: Faceclaw's Wear OS watch remote (or the watch pad in Faceclaw's + phone app). + +*** + +### TouchDownEvent + +A touch-down, from [FaceclawExtensions.addTouchDownListener](#addtouchdownlistener). + +#### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `source` | [`InputSource`](#inputsource) | Which device was touched. Currently always `ring` or `watch`: the glasses' touchpads don't report touch-down. | +| `timestampMs` | `number` | When Faceclaw received the touch, in milliseconds since the epoch (comparable with `Date.now()`). | + +*** + +### getInputSource() + +```ts +function getInputSource(event): InputSource | null; +``` + +Which device produced a stock EvenHub gesture event, or `null` if Faceclaw +didn't say. + +The stock `eventSource` field only knows the stock devices, so Faceclaw +reports the watch there as the ring. Faceclaw adds the real device to the +event's raw JSON as `faceclawInputSource`, and this function reads it. Pass +the event object your `onEvenHubEvent` handler receives. + +Faceclaw adds the field to clicks, double-clicks, long-presses and their +releases, and scrolls, in both `sysEvent` and `listEvent`. It is missing when +the glasses don't report a scroll's source, on non-gesture events, and in +every other host. + +#### Parameters + +| Parameter | Type | +| ------ | ------ | +| `event` | \| \{ `jsonData?`: `Record`\<`string`, `unknown`\>; \} \| `null` \| `undefined` | + +#### Returns + +[`InputSource`](#inputsource) \| `null` + +#### Example + +```ts +bridge.onEvenHubEvent((event) => { + if (event.sysEvent && getInputSource(event) === "watch") { + // ... + } +}); +``` + +## Text input + +### TextInputEvent + +Text sent to the app, from [FaceclawExtensions.addTextInputListener](#addtextinputlistener). + +#### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `text` | `string` | The finished text: a whole dictation, or a typed entry. | +| `submit?` | `boolean` | Present when the sender said whether to submit the text (`true`, like pressing Enter after it) or only insert it (`false`). Faceclaw's remote-input tool sets it; dictation and the phone keyboard leave it out. | ## Extended layout @@ -383,8 +601,8 @@ classes can be passed directly. In practice you should set `containerID`, | `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. | +| `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. | @@ -407,8 +625,8 @@ A text container. The fields match the stock SDK's `TextContainerProperty`, plus | `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. | +| `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. | @@ -418,6 +636,7 @@ A text container. The fields match the stock SDK's `TextContainerProperty`, plus | `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. | +| `font?` | [`FaceclawFont`](#faceclawfont) | `undefined` | The text's font. Its fields override the layout's [FaceclawLayout.font](#property-font-2) one by one. With neither, the text is in the stock firmware font. | *** @@ -469,8 +688,8 @@ A list container. The fields match the stock SDK's `ListContainerProperty`, plus | `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. | +| `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. | @@ -479,6 +698,7 @@ A list container. The fields match the stock SDK's `ListContainerProperty`, plus | `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. | +| `font?` | [`FaceclawFont`](#faceclawfont) | The items' font. Its fields override the layout's [FaceclawLayout.font](#property-font-2) one by one. With neither, the items are in the stock firmware font. Each row is the font's line height plus 12 pixels. | *** @@ -512,6 +732,8 @@ classes, with three differences: - Each container may set `preserve: true` to inherit its content from the same-named container in the previous layout. +Text and list containers can also use other fonts (see [FaceclawFont](#faceclawfont)). + #### Properties | Property | Type | Description | @@ -521,6 +743,110 @@ classes, with three differences: | `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. | +| `font?` | [`FaceclawFont`](#faceclawfont) | The default font for every text and list container in the layout. | + +## Fonts + +### FaceclawFont + +A font for text and list containers in an extended layout, from +[FaceclawLayout.font](#property-font-2) and the containers' own `font`. A container +that has no font, and whose layout has none, uses the stock firmware font. + +Available families (see [FaceclawExtensions.getFonts](#getfonts)): + +- `Roboto`, `Inter`, `Montserrat` and `Roboto Mono`: bundled TrueType + fonts in weights 300, 400 and 700, at any size. +- `Terminus`: a monospace bitmap font, in sizes 12, 14, 16, 18, 20, 22, 24, + 28 and 32, and weights 400 and 700. +- `EvenHub`: the stock firmware font, 20px only. Use it to bring back the + stock font for one container when the layout sets another. +- Any font the user has installed in Faceclaw. + +Text in the stock font wraps exactly as on the stock firmware. Text in +other fonts wraps with Faceclaw's own line breaking. + +#### Properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `family?` | `string` | `"Roboto"` | Font family, matched without regard to case, spaces or punctuation. An unknown family falls back to Roboto. | +| `size?` | `number` | `20` | Size in pixels: the em size, as in CSS `font-size`. A line is somewhat taller; [FaceclawExtensions.measureText](#measuretext) reports its height. 6–128. Bitmap families use their nearest size. | +| `weight?` | `number` \| `"normal"` \| `"bold"` | `400` | Weight, 100–900, where `"normal"` is 400 and `"bold"` is 700. The nearest weight the family has is used, as CSS chooses it. | + +*** + +### FaceclawFontFamily + +A font family Faceclaw can draw, from [FaceclawExtensions.getFonts](#getfonts). + +#### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `family` | `string` | The name to use as [FaceclawFont.family](#property-family). | +| `weights` | `number`[] | The weights the family has, lightest first. | +| `sizes?` | `number`[] | For a bitmap family, the sizes it has. Absent for a scalable family, which takes any size. | +| `monospace` | `boolean` | Whether every character has the same width. | + +*** + +### TextMeasurement + +The size of some text, from [FaceclawExtensions.measureText](#measuretext). + +#### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `width` | `number` | Width in pixels of the widest line (lines are split at `\n`). | +| `lineHeight` | `number` | Height in pixels of one line. A text container advances by this much per line. | + +## 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. | ## Assistant tools diff --git a/evenhub-extensions/src/index.ts b/evenhub-extensions/src/index.ts index b0b0bccd..4fbebd07 100644 --- a/evenhub-extensions/src/index.ts +++ b/evenhub-extensions/src/index.ts @@ -69,20 +69,121 @@ export interface BuzzerStep { * An app can assume it starts `visible` and `focused` at launch. Events report * changes from there. * - * @group Window lifecycle + * @group Window */ export type WindowLifecycleEventType = "visible" | "hidden" | "focused" | "blurred"; /** * Payload of a {@link FaceclawExtensions.addWindowLifecycleListener} callback. * - * @group Window lifecycle + * @group Window */ export interface WindowLifecycleEvent { /** Which transition happened. */ type: WindowLifecycleEventType; } +/** + * An image for {@link FaceclawExtensions.setWindowIcon}. An `ImageData` (from + * a canvas's `getImageData`) fits this shape and can be passed directly. + * + * Draw it like Faceclaw's own icons: light strokes on black. Brightness is + * coverage, so black is transparent, and Faceclaw inverts the icon for the + * selected window. The switcher draws icons at about 32×32; larger images are + * scaled down to fit, keeping their aspect ratio. + * + * @group Window + */ +export interface WindowIconImage { + /** Width in pixels, 1–256. */ + width: number; + /** Height in pixels, 1–256. */ + height: number; + /** + * Pixels in rows from the top left: either `width * height` grayscale + * values (0–255), or `width * height * 4` RGBA values, which Faceclaw + * converts to grayscale (luminance times alpha). + */ + data: ArrayLike; +} + +// ---- Input ---- + +/** + * The device an input came from: + * + * - `ring`: the Even R1 ring (or the ring pad in Faceclaw's phone app). + * - `left-touchpad` / `right-touchpad`: the touch areas on the glasses' arms. + * - `watch`: Faceclaw's Wear OS watch remote (or the watch pad in Faceclaw's + * phone app). + * + * @group Input + */ +export type InputSource = "ring" | "left-touchpad" | "right-touchpad" | "watch"; + +/** + * A touch-down, from {@link FaceclawExtensions.addTouchDownListener}. + * + * @group Input + */ +export interface TouchDownEvent { + /** + * Which device was touched. Currently always `ring` or `watch`: the + * glasses' touchpads don't report touch-down. + */ + source: InputSource; + /** When Faceclaw received the touch, in milliseconds since the epoch (comparable with `Date.now()`). */ + timestampMs: number; +} + +/** + * Which device produced a stock EvenHub gesture event, or `null` if Faceclaw + * didn't say. + * + * The stock `eventSource` field only knows the stock devices, so Faceclaw + * reports the watch there as the ring. Faceclaw adds the real device to the + * event's raw JSON as `faceclawInputSource`, and this function reads it. Pass + * the event object your `onEvenHubEvent` handler receives. + * + * Faceclaw adds the field to clicks, double-clicks, long-presses and their + * releases, and scrolls, in both `sysEvent` and `listEvent`. It is missing when + * the glasses don't report a scroll's source, on non-gesture events, and in + * every other host. + * + * @example + * ```ts + * bridge.onEvenHubEvent((event) => { + * if (event.sysEvent && getInputSource(event) === "watch") { + * // ... + * } + * }); + * ``` + * + * @group Input + */ +export function getInputSource(event: { jsonData?: Record } | null | undefined): InputSource | null { + const value = event?.jsonData?.faceclawInputSource; + return value === "ring" || value === "left-touchpad" || value === "right-touchpad" || value === "watch" ? value : null; +} + +// ---- Text input ---- + +/** + * Text sent to the app, from {@link FaceclawExtensions.addTextInputListener}. + * + * @group Text input + */ +export interface TextInputEvent { + /** The finished text: a whole dictation, or a typed entry. */ + text: string; + /** + * Present when the sender said whether to submit the text (`true`, like + * pressing Enter after it) or only insert it (`false`). Faceclaw's + * remote-input tool sets it; dictation and the phone keyboard leave it out. + */ + submit?: boolean; +} + /** * A magnetometer heading sample from {@link FaceclawExtensions.addCompassListener}. * All headings are in degrees clockwise, in the range [0, 360). @@ -120,6 +221,78 @@ export interface CompassReading { trueHeadingDegrees?: number; } +// ---- Fonts ---- + +/** + * A font for text and list containers in an extended layout, from + * {@link FaceclawLayout.font} and the containers' own `font`. A container + * that has no font, and whose layout has none, uses the stock firmware font. + * + * Available families (see {@link FaceclawExtensions.getFonts}): + * + * - `Roboto`, `Inter`, `Montserrat` and `Roboto Mono`: bundled TrueType + * fonts in weights 300, 400 and 700, at any size. + * - `Terminus`: a monospace bitmap font, in sizes 12, 14, 16, 18, 20, 22, 24, + * 28 and 32, and weights 400 and 700. + * - `EvenHub`: the stock firmware font, 20px only. Use it to bring back the + * stock font for one container when the layout sets another. + * - Any font the user has installed in Faceclaw. + * + * Text in the stock font wraps exactly as on the stock firmware. Text in + * other fonts wraps with Faceclaw's own line breaking. + * + * @group Fonts + */ +export interface FaceclawFont { + /** + * Font family, matched without regard to case, spaces or punctuation. An + * unknown family falls back to Roboto. + * @defaultValue "Roboto" + */ + family?: string; + /** + * Size in pixels: the em size, as in CSS `font-size`. A line is somewhat + * taller; {@link FaceclawExtensions.measureText} reports its height. 6–128. + * Bitmap families use their nearest size. + * @defaultValue 20 + */ + size?: number; + /** + * Weight, 100–900, where `"normal"` is 400 and `"bold"` is 700. The nearest + * weight the family has is used, as CSS chooses it. + * @defaultValue 400 + */ + weight?: number | "normal" | "bold"; +} + +/** + * A font family Faceclaw can draw, from {@link FaceclawExtensions.getFonts}. + * + * @group Fonts + */ +export interface FaceclawFontFamily { + /** The name to use as {@link FaceclawFont.family}. */ + family: string; + /** The weights the family has, lightest first. */ + weights: number[]; + /** For a bitmap family, the sizes it has. Absent for a scalable family, which takes any size. */ + sizes?: number[]; + /** Whether every character has the same width. */ + monospace: boolean; +} + +/** + * The size of some text, from {@link FaceclawExtensions.measureText}. + * + * @group Fonts + */ +export interface TextMeasurement { + /** Width in pixels of the widest line (lines are split at `\n`). */ + width: number; + /** Height in pixels of one line. A text container advances by this much per line. */ + lineHeight: number; +} + // ---- Extended layout (a superset of the stock EvenHub page containers) ---- /** @@ -185,6 +358,12 @@ export interface FaceclawTextContainer extends FaceclawContainerCommon { borderRadius?: number; /** Padding between the border and the text, in pixels. */ paddingLength?: number; + /** + * The text's font. Its fields override the layout's + * {@link FaceclawLayout.font} one by one. With neither, the text is in the + * stock firmware font. + */ + font?: FaceclawFont; } /** @@ -233,6 +412,13 @@ export interface FaceclawListContainer extends FaceclawContainerCommon { borderRadius?: number; /** Padding between the border and the items, in pixels. */ paddingLength?: number; + /** + * The items' font. Its fields override the layout's + * {@link FaceclawLayout.font} one by one. With neither, the items are in + * the stock firmware font. Each row is the font's line height plus 12 + * pixels. + */ + font?: FaceclawFont; } /** @@ -262,6 +448,8 @@ export interface FaceclawMenu { * - Each container may set `preserve: true` to inherit its content from the * same-named container in the previous layout. * + * Text and list containers can also use other fonts (see {@link FaceclawFont}). + * * @group Extended layout */ export interface FaceclawLayout { @@ -275,6 +463,8 @@ export interface FaceclawLayout { menuObject?: FaceclawMenu; /** Accepted for compatibility with stock payloads and ignored: there is no container limit. */ containerTotalNum?: number; + /** The default font for every text and list container in the layout. */ + font?: FaceclawFont; } // ---- Voice-assistant tools ---- @@ -445,6 +635,82 @@ export interface FaceclawExtensions { * @param tools - The tools to offer. Pass `[]` to remove them all. */ setAssistantTools(tools: AssistantTool[]): void; + + /** + * Receive touch-downs: the moment a finger touches the ring or the watch's + * touchpad, before Faceclaw knows whether it will become a tap, a scroll or + * a hold. The interpreted gesture still arrives afterwards as the usual + * stock event. Use it where latency matters, as in games. + * + * Touch-downs arrive only while the app's window has input focus. The + * glasses' own touchpads don't report them. + * + * @param listener - Called on each touch-down. + * @returns A function that unsubscribes `listener`. + */ + addTouchDownListener(listener: (event: TouchDownEvent) => void): () => void; + + /** + * Receive text the user sends to the app. While at least one listener is + * registered and the app is in the foreground, Faceclaw offers the app as + * the "Type Into App" destination of its voice dialog, the phone keyboard + * and the watch. + * + * @param listener - Called with each piece of text. + * @returns A function that unsubscribes `listener`. + */ + addTextInputListener(listener: (event: TextInputEvent) => void): () => void; + + /** + * Open Faceclaw's voice dialog for this app. When the user sends the + * dictation with Type Into App, it arrives at the text-input listeners. + * + * @returns A promise that resolves to true if the dialog is opening, or + * false if it can't open: there is no text-input listener, the app isn't + * in the foreground, voice input is unavailable, or another dialog is up. + */ + startVoiceInput(): Promise; + + /** + * Replace the app's icon in the app switcher, or pass `null` to go back to + * the package's icon. See {@link WindowIconImage} for the format. + * + * @returns A promise that resolves once the icon is set, and rejects if the + * image is malformed or larger than 256×256. + */ + setWindowIcon(icon: WindowIconImage | null): Promise; + + /** + * Show or clear the attention dot on the app's switcher icon, for example + * when something new arrives while the app is in the background. The dot + * stays until the app clears it or closes. + */ + setAttention(attention: boolean): void; + + /** + * Stop the glasses display from turning off for inactivity while the app is + * in the foreground, as a teleprompter or navigation app needs. It has no + * effect while another window is in front, and the user can still turn the + * display off. Pass `false` to restore the normal timeout. + */ + setKeepScreenOn(keepOn: boolean): void; + + /** + * List the font families available for {@link FaceclawFont.family}, + * including any the user has installed. + */ + getFonts(): Promise; + + /** + * Measure text as a container with this font would draw it, for example to + * size a text container or centre a label. + * + * @param text - The text. Lines split at `\n` are measured separately. + * @param font - The font to measure in. Unlike a container's font, it + * isn't combined with a layout default. Omit it to measure in the stock + * font. + */ + measureText(text: string, font?: FaceclawFont): Promise; } declare global { diff --git a/evenhub-extensions/test/stock-sdk-compat.ts b/evenhub-extensions/test/stock-sdk-compat.ts index e3d09263..554dbc77 100644 --- a/evenhub-extensions/test/stock-sdk-compat.ts +++ b/evenhub-extensions/test/stock-sdk-compat.ts @@ -10,9 +10,12 @@ import { MenuItemProperty, RebuildPageContainer, TextContainerProperty, + type EvenHubEvent, } from "@evenrealities/even_hub_sdk"; +import { getInputSource } from "../src/index"; import type { FaceclawExtensions, + InputSource, FaceclawImageContainer, FaceclawLayout, FaceclawListContainer, @@ -62,3 +65,12 @@ void fc.createLayout(fromCreate); void fc.replaceLayout(fromRebuild); void fc.replaceLayout(mixed); void fc.replaceLayout(new RebuildPageContainer({ textObject: [new TextContainerProperty({ containerID: 1 })] })); + +// The stock event the SDK hands onEvenHubEvent carries the source field. +declare const stockEvent: EvenHubEvent; +const source: InputSource | null = getInputSource(stockEvent); +void source; + +// A canvas ImageData is accepted as a window icon. +declare const imageData: ImageData; +void fc.setWindowIcon(imageData); diff --git a/evenhub-extensions/typedoc.json b/evenhub-extensions/typedoc.json index 7133f76a..5faa1991 100644 --- a/evenhub-extensions/typedoc.json +++ b/evenhub-extensions/typedoc.json @@ -18,11 +18,14 @@ "treatWarningsAsErrors": true, "groupOrder": [ "Entry point", - "Window lifecycle", + "Window", + "Input", + "Text input", + "Extended layout", + "Fonts", "API keys", "Buzzer", "Compass", - "Extended layout", "Assistant tools", "Properties", "Methods", diff --git a/tests/evenhub-containers.test.cjs b/tests/evenhub-containers.test.cjs index 2af839ae..7527df66 100644 --- a/tests/evenhub-containers.test.cjs +++ b/tests/evenhub-containers.test.cjs @@ -118,3 +118,26 @@ test("flags accept booleans (extension layouts) as well as 0/1 (stock)", () => { ); assert.equal(page.containers[0].selectBorder, true); }); + +test("a layout font is the default for text and list containers, which override it field by field", () => { + const page = parsePage({ + font: { family: "Inter", size: 24 }, + listObject: [{ containerID: 1, containerName: "l", font: { weight: "bold" } }], + textObject: [{ containerID: 2, containerName: "t" }, { containerID: 3, containerName: "u", font: { family: "Terminus" } }], + imageObject: [{ containerID: 4, containerName: "i" }], + }); + assert.deepEqual( + page.containers.map((c) => [c.name, c.font]), + [ + ["l", { family: "Inter", size: 24, weight: 700 }], + ["i", undefined], + ["t", { family: "Inter", size: 24 }], + ["u", { family: "Terminus", size: 24 }], + ], + ); +}); + +test("containers without a font anywhere keep the stock font", () => { + const page = parsePage({ textObject: [{ containerID: 1, containerName: "t", content: "x" }] }); + assert.equal(page.containers[0].font, undefined); +}); diff --git a/tests/evenhub-device-status.test.cjs b/tests/evenhub-device-status.test.cjs new file mode 100644 index 00000000..3092997f --- /dev/null +++ b/tests/evenhub-device-status.test.cjs @@ -0,0 +1,45 @@ +// The stock DeviceStatus an EvenHub app sees (getGlassesInfo().status and the +// deviceStatusChanged push), built from Faceclaw's view of the glasses. +const test = require("node:test"); +const assert = require("node:assert/strict"); + +const { buildEvenHubDeviceStatus, sameDeviceStatus, PLACEHOLDER_SERIAL } = require("../.test-build/app/apps/evenhub/device-status.js"); + +const worn = { serial: "S200LAAJ0123", connected: true, worn: true, battery: 73, charging: false }; + +test("connected, worn glasses report their real values", () => { + assert.deepEqual(buildEvenHubDeviceStatus(worn), { + sn: "S200LAAJ0123", + connectType: "connected", + isWearing: true, + batteryLevel: 73, + isCharging: false, + isInCase: false, + }); +}); + +test("charging means in the case, since the G2 only charges there", () => { + const status = buildEvenHubDeviceStatus({ ...worn, worn: false, charging: true }); + assert.equal(status.isCharging, true); + assert.equal(status.isInCase, true); + assert.equal(status.isWearing, false); +}); + +test("unknown wear state and battery are omitted, not guessed", () => { + const status = buildEvenHubDeviceStatus({ serial: null, connected: false, worn: null, battery: null, charging: false }); + assert.deepEqual(status, { sn: PLACEHOLDER_SERIAL, connectType: "disconnected", isCharging: false, isInCase: false }); + assert.equal("isWearing" in status, false); + assert.equal("batteryLevel" in status, false); +}); + +test("a blank serial falls back to the placeholder", () => { + assert.equal(buildEvenHubDeviceStatus({ ...worn, serial: " " }).sn, PLACEHOLDER_SERIAL); +}); + +test("sameDeviceStatus compares every field", () => { + const a = buildEvenHubDeviceStatus(worn); + assert.equal(sameDeviceStatus(a, buildEvenHubDeviceStatus(worn)), true); + assert.equal(sameDeviceStatus(a, buildEvenHubDeviceStatus({ ...worn, battery: 72 })), false); + assert.equal(sameDeviceStatus(a, buildEvenHubDeviceStatus({ ...worn, worn: null })), false); + assert.equal(sameDeviceStatus(a, buildEvenHubDeviceStatus({ ...worn, connected: false })), false); +}); diff --git a/tests/evenhub-extensions-shim.test.cjs b/tests/evenhub-extensions-shim.test.cjs index 1ad5e5f5..bb43d0bb 100644 --- a/tests/evenhub-extensions-shim.test.cjs +++ b/tests/evenhub-extensions-shim.test.cjs @@ -99,3 +99,66 @@ test('assistant tools send specs to the host and run handlers on invoke', async 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']]); }); + +test('touch-down and text input are requested while someone listens, and unsubscribing twice is harmless', () => { + const { win, fc, posted } = page(); + const seen = []; + const offTouch = fc.addTouchDownListener((e) => seen.push(`touch:${e.source}`)); + const offText1 = fc.addTextInputListener((e) => seen.push(`text1:${e.text}`)); + const offText2 = fc.addTextInputListener((e) => seen.push(`text2:${e.text}`)); + win.__fcExtEvent('touchDown', { source: 'watch', timestampMs: 5 }); + win.__fcExtEvent('textInput', { text: 'hi' }); + offText1(); + offText1(); + win.__fcExtEvent('textInput', { text: 'again' }); + offText2(); + offTouch(); + assert.deepEqual(seen, ['touch:watch', 'text1:hi', 'text2:hi', 'text2:again']); + assert.deepEqual(posted.map((p) => p.args), [ + ['setTouchDown', true], + ['setTextInput', true], + ['setTextInput', false], + ['setTouchDown', false], + ]); +}); + +test('window icons are sent as plain arrays, and clearing sends null', async () => { + const { win, fc, posted } = page(); + const set = fc.setWindowIcon({ width: 1, height: 2, data: new Uint8ClampedArray([7, 9]) }); + const clear = fc.setWindowIcon(null); + assert.deepEqual(posted.map((p) => p.args), [ + ['setWindowIcon', { width: 1, height: 2, data: [7, 9] }], + ['setWindowIcon', null], + ]); + win.__fcExtResolve(posted[0].id, true, null); + win.__fcExtResolve(posted[1].id, false, 'setWindowIcon: bad'); + await set; + await assert.rejects(clear, /setWindowIcon: bad/); +}); + +test('window controls are fire-and-forget; startVoiceInput resolves the host answer', async () => { + const { win, fc, posted } = page(); + fc.setAttention(1); + fc.setKeepScreenOn(false); + const voice = fc.startVoiceInput(); + assert.deepEqual(posted.map((p) => [p.args, p.id === 0]), [ + [['setAttention', true], true], + [['setKeepScreenOn', false], true], + [['startVoiceInput'], false], + ]); + win.__fcExtResolve(posted[2].id, true, false); + assert.equal(await voice, false); +}); + +test('font queries are calls; measureText sends null for no font', () => { + const { fc, posted } = page(); + void fc.getFonts(); + void fc.measureText('hi'); + void fc.measureText(42, { family: 'Inter', size: 30 }); + assert.deepEqual(posted.map((p) => p.args), [ + ['getFonts'], + ['measureText', 'hi', null], + ['measureText', '42', { family: 'Inter', size: 30 }], + ]); + assert.ok(posted.every((p) => p.id > 0)); +}); diff --git a/tests/evenhub-font-spec.test.cjs b/tests/evenhub-font-spec.test.cjs new file mode 100644 index 00000000..ef4fcb39 --- /dev/null +++ b/tests/evenhub-font-spec.test.cjs @@ -0,0 +1,84 @@ +// Font options for EvenHub text and list containers (extension layouts): +// parsing, layout-default inheritance, and choosing a face. +const test = require("node:test"); +const assert = require("node:assert/strict"); + +const { + parseFontSpec, + mergeFontSpecs, + selectFontFace, + describeFontFamilies, + MAX_FONT_SIZE, +} = require("../.test-build/app/apps/evenhub/font-spec.js"); + +const TERMINUS_SIZES = [12, 14, 16, 18, 20, 22, 24, 28, 32]; +const ttf = (family, weight, monospace = false) => ({ family, weight, sizes: null, monospace, key: `ttf:${family}:${weight}` }); +const FACES = [ + { family: "EvenHub", weight: 400, sizes: [20], monospace: false, key: "stock" }, + { family: "Terminus", weight: 400, sizes: TERMINUS_SIZES, monospace: true, key: "terminus:400" }, + { family: "Terminus", weight: 700, sizes: TERMINUS_SIZES, monospace: true, key: "terminus:700" }, + ttf("Inter 18pt", 300), ttf("Inter 18pt", 400), ttf("Inter 18pt", 700), + ttf("Roboto", 300), ttf("Roboto", 400), ttf("Roboto", 700), + ttf("Roboto Mono", 300, true), ttf("Roboto Mono", 400, true), ttf("Roboto Mono", 700, true), +]; +const pick = (spec, faces = FACES) => { + const choice = selectFontFace(spec, faces); + return choice && `${choice.face.key}@${choice.size}`; +}; + +test("no font object means no spec (the stock font); an empty one means the defaults", () => { + assert.equal(parseFontSpec(undefined), undefined); + assert.equal(parseFontSpec("Roboto"), undefined); + assert.deepEqual(parseFontSpec({}), {}); + assert.equal(pick({}), "ttf:Roboto:400@20"); +}); + +test("sizes are rounded and clamped, weights take keywords and numeric strings", () => { + assert.deepEqual(parseFontSpec({ family: " Inter ", size: 17.6, weight: "bold" }), { family: "Inter", size: 18, weight: 700 }); + assert.deepEqual(parseFontSpec({ size: 1000, weight: "normal" }), { size: MAX_FONT_SIZE, weight: 400 }); + assert.deepEqual(parseFontSpec({ size: 2, weight: "300" }), { size: 6, weight: 300 }); + assert.deepEqual(parseFontSpec({ family: "", size: "x", weight: "heavy" }), {}); +}); + +test("a container's font overrides the layout default field by field", () => { + assert.deepEqual(mergeFontSpecs({ family: "Inter", size: 24 }, { size: 30 }), { family: "Inter", size: 30 }); + assert.deepEqual(mergeFontSpecs(undefined, { size: 30 }), { size: 30 }); + assert.deepEqual(mergeFontSpecs({ family: "Inter" }, undefined), { family: "Inter" }); + assert.equal(mergeFontSpecs(undefined, undefined), undefined); +}); + +test("families match loosely, including without an optical-size suffix", () => { + assert.equal(pick({ family: "inter" }), "ttf:Inter 18pt:400@20"); + assert.equal(pick({ family: "Inter 18pt" }), "ttf:Inter 18pt:400@20"); + assert.equal(pick({ family: "robotomono", size: 14 }), "ttf:Roboto Mono:400@14"); + assert.equal(pick({ family: "ROBOTO" }), "ttf:Roboto:400@20", "Roboto doesn't pick up Roboto Mono"); +}); + +test("an unknown family falls back to Roboto, and with no Roboto there is no choice", () => { + assert.equal(pick({ family: "Comic Sans", weight: 700 }), "ttf:Roboto:700@20"); + assert.equal(pick({ family: "Comic Sans" }, FACES.slice(0, 3)), null); +}); + +test("weights follow CSS matching", () => { + assert.equal(pick({ family: "Inter", weight: 500 }), "ttf:Inter 18pt:400@20", "400-500 look lighter before heavier"); + assert.equal(pick({ family: "Inter", weight: 600 }), "ttf:Inter 18pt:700@20", "heavier requests look heavier first"); + assert.equal(pick({ family: "Inter", weight: 350 }), "ttf:Inter 18pt:300@20", "lighter requests look lighter first"); + assert.equal(pick({ family: "Inter", weight: 100 }), "ttf:Inter 18pt:300@20"); + assert.equal(pick({ family: "Inter", weight: 900 }), "ttf:Inter 18pt:700@20"); +}); + +test("bitmap families snap to their nearest size", () => { + assert.equal(pick({ family: "Terminus", size: 25 }), "terminus:400@24"); + assert.equal(pick({ family: "Terminus", size: 26, weight: 700 }), "terminus:700@24", "a tie takes the smaller size"); + assert.equal(pick({ family: "Terminus", size: 100 }), "terminus:400@32"); + assert.equal(pick({ family: "EvenHub", size: 40, weight: 700 }), "stock@20"); +}); + +test("families are listed once each, by their app-facing name", () => { + const families = describeFontFamilies(FACES); + assert.deepEqual(families.map((f) => f.family), ["EvenHub", "Inter", "Roboto", "Roboto Mono", "Terminus"]); + const terminus = families.find((f) => f.family === "Terminus"); + assert.deepEqual(terminus, { family: "Terminus", weights: [400, 700], sizes: TERMINUS_SIZES, monospace: true }); + const inter = families.find((f) => f.family === "Inter"); + assert.deepEqual(inter, { family: "Inter", weights: [300, 400, 700], monospace: false }); +}); diff --git a/tests/evenhub-window-icon.test.cjs b/tests/evenhub-window-icon.test.cjs new file mode 100644 index 00000000..3559cfe6 --- /dev/null +++ b/tests/evenhub-window-icon.test.cjs @@ -0,0 +1,56 @@ +// App-supplied switcher icons (extension setWindowIcon): parsing the pixel +// buffer from the bridge, and scaling it to the switcher's icon size. +const test = require("node:test"); +const assert = require("node:assert/strict"); + +const { parseWindowIcon, WindowIconRenderer, MAX_WINDOW_ICON_DIMENSION } = require("../.test-build/app/apps/evenhub/window-icon.js"); + +test("grayscale data is taken as-is", () => { + const icon = parseWindowIcon({ width: 2, height: 2, data: [0, 64, 128, 255] }); + assert.deepEqual([...icon.pixels], [0, 64, 128, 255]); +}); + +test("RGBA data (an ImageData) becomes luminance times alpha", () => { + const icon = parseWindowIcon({ + width: 3, + height: 1, + data: [255, 255, 255, 255, 255, 255, 255, 0, 0, 255, 0, 255], + }); + assert.deepEqual([...icon.pixels], [255, 0, 182]); +}); + +test("a JSON-ified typed array parses like a plain array", () => { + const icon = parseWindowIcon({ width: 2, height: 1, data: { 0: 10, 1: 20 } }); + assert.deepEqual([...icon.pixels], [10, 20]); +}); + +test("malformed icons are refused", () => { + assert.equal(parseWindowIcon(null), null); + assert.equal(parseWindowIcon({ width: 2, height: 2, data: [1, 2, 3] }), null, "wrong length"); + assert.equal(parseWindowIcon({ width: 0, height: 2, data: [] }), null, "empty"); + assert.equal(parseWindowIcon({ width: 1.5, height: 2, data: [1, 2, 3] }), null, "fractional size"); + assert.equal(parseWindowIcon({ width: 1, height: 1, data: ["x"] }), null, "non-numeric data"); + const big = MAX_WINDOW_ICON_DIMENSION + 1; + assert.equal(parseWindowIcon({ width: big, height: 1, data: new Array(big).fill(0) }), null, "too wide"); +}); + +test("icons shrink to fit the box, keeping their aspect ratio and averaging pixels", () => { + const data = []; + for (let y = 0; y < 4; y++) for (let x = 0; x < 8; x++) data.push(x < 4 ? 0 : 200); + const renderer = new WindowIconRenderer(parseWindowIcon({ width: 8, height: 4, data })); + const small = renderer.render(4); + assert.equal(small.width, 4); + assert.equal(small.height, 2); + assert.deepEqual([...small.pixels], [0, 0, 200, 200, 0, 0, 200, 200]); + const odd = renderer.render(3); + assert.equal(odd.width, 3); + // The middle column straddles the edge between the halves. + assert.equal(odd.pixels[1], 100); +}); + +test("renders are cached per size, and a fitting icon is used unscaled", () => { + const source = parseWindowIcon({ width: 4, height: 4, data: new Array(16).fill(9) }); + const renderer = new WindowIconRenderer(source); + assert.equal(renderer.render(32), renderer.render(32)); + assert.equal(renderer.render(4), source); +}); diff --git a/tests/ios-glanceboard.test.cjs b/tests/ios-glanceboard.test.cjs index 30c1155a..e86366d8 100644 --- a/tests/ios-glanceboard.test.cjs +++ b/tests/ios-glanceboard.test.cjs @@ -146,6 +146,7 @@ function fixture() { '../native/weather': { weatherBridge: { setSessionActive() {} } }, './glance-host': { GlanceHost }, './events': events, './lock-screen': { LOCK_SCREEN_SURFACE_ID: 'lock-screen', createLockScreenImage: () => new images.GrayImage(640, 480, 123) }, + './glasses-presence': load('app/g2/glasses-presence.ts', {}), './device-addresses': { loadDeviceAddresses: () => ({ right: 'AA', left: 'BB', ring: '' }) }, './ios-peripheral-identity': { deviceAddressError: () => null }, './firmware-compat': load('app/g2/firmware-compat.ts', {}), './reconnect-policy': load('app/g2/reconnect-policy.ts', {}), '../apps/launcher': { launcherEntries: () => [] }, diff --git a/tests/tsconfig.json b/tests/tsconfig.json index cc9c2fc3..a1c2e944 100644 --- a/tests/tsconfig.json +++ b/tests/tsconfig.json @@ -47,6 +47,9 @@ "../app/apps/microphones/name-guess.ts", "../app/apps/evenhub/containers.ts", "../app/apps/evenhub/list-menu.ts", + "../app/apps/evenhub/device-status.ts", + "../app/apps/evenhub/font-spec.ts", + "../app/apps/evenhub/window-icon.ts", "../app/apps/timer/timer-model.ts", "../app/apps/teleprompter/script-tracker.ts", "../app/apps/nightscout/nightscout-alerts.ts", From d6180e445760d2ef1521e53c18176cd8f35e53f1 Mon Sep 17 00:00:00 2001 From: James Babcock Date: Sat, 10 Oct 2026 17:03:45 -0700 Subject: [PATCH 03/65] Use ANCS notification categories for icons --- CHANGELOG | 1 + app/graphics/icons.ts | 19 ++++++++++ app/native/notification-icons.ios.ts | 26 ++++++++++---- tests/ios-notification-icons.test.cjs | 51 +++++++++++++++++++++++++++ 4 files changed, 90 insertions(+), 7 deletions(-) create mode 100644 tests/ios-notification-icons.test.cjs diff --git a/CHANGELOG b/CHANGELOG index 1c45f736..77c8e6b3 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -5,6 +5,7 @@ * Fix several issues that would cause disconnection and disconnect-looping * Add a client for T3 Code * Weather app shows an icon for current conditions, and can add the weather to the status bar and the Glanceboard system card (Weather menu > Settings) +* iOS Notifications have an icon based on ANCS category ## 0.8.2 - 2026-10-03 diff --git a/app/graphics/icons.ts b/app/graphics/icons.ts index c18b69ae..65862693 100644 --- a/app/graphics/icons.ts +++ b/app/graphics/icons.ts @@ -70,6 +70,25 @@ export const ICON_SVGS = { '', calendar: '', + // iOS notification categories (with bell, message-circle and calendar). + "phone-incoming": + '', + "phone-missed": + '', + voicemail: + '', + mail: + '', + newspaper: + '', + "heart-pulse": + '', + briefcase: + '', + "map-pin": + '', + tv: + '', "cloud-sun": '', "flask-conical": diff --git a/app/native/notification-icons.ios.ts b/app/native/notification-icons.ios.ts index 95a387ed..4b327118 100644 --- a/app/native/notification-icons.ios.ts +++ b/app/native/notification-icons.ios.ts @@ -1,6 +1,8 @@ import { GrayImage } from '../graphics/image' +import { renderIcon, type IconName } from '../graphics/icons' import { AncsClient, ANCS_CONNECT_MESSAGE, type AncsState } from '../g2/ancs-client' import { rememberNotificationSources } from './notification-sources' +import type { AndroidNotification } from './notification-types' export type { AndroidNotification, AndroidNotificationAction } from './notification-types' export type { NotificationIconsResult, NotificationIconResult } from './notification-icons' @@ -26,8 +28,17 @@ export function dismissNotification(key: string): boolean { return active?.dismi export function onAndroidNotificationPosted(listener: (key: string) => void): () => void { listeners.add(listener); return () => { listeners.delete(listener) } } -// ANCS does not provide app icons. Use a local bell; never fetch notification -// sources or content from a third-party icon service. +// ANCS does not provide app icons, so show one for the notification's ANCS +// category; never fetch notification sources or content from a third-party +// icon service. Indexed by CategoryID: Other, IncomingCall, MissedCall, +// Voicemail, Social, Schedule, Email, News, HealthAndFitness, +// BusinessAndFinance, Location, Entertainment. +const CATEGORY_ICONS: readonly IconName[] = ['bell','phone-incoming','phone-missed','voicemail','message-circle', + 'calendar','mail','newspaper','heart-pulse','briefcase','map-pin','tv'] +function categoryIcon(category: string): GrayImage { + return renderIcon(CATEGORY_ICONS[Number(category)] ?? 'bell',24)?.clone() ?? bell() +} +// Drawn fallback for when the SVG rasterizer fails. function bell(): GrayImage { const image = new GrayImage(24,24,0) image.fillRoundedRect(6,5,12,13,220,5) @@ -37,11 +48,12 @@ function bell(): GrayImage { } export function readActiveNotificationIcons(maxIcons: number, _allowStale: boolean) { // One icon per source, standing for its first notification. - const sources = new Map() - for (const n of readActiveNotifications(ALL_NOTIFICATIONS)) if (!sources.has(n.packageName)) sources.set(n.packageName, n.key) - const keys = Array.from(sources.values()).slice(0,Math.max(0,maxIcons)) - return {icons: keys.map(() => bell()),keys,stale:false} + const sources = new Map() + for (const n of readActiveNotifications(ALL_NOTIFICATIONS)) if (!sources.has(n.packageName)) sources.set(n.packageName, n) + const shown = Array.from(sources.values()).slice(0,Math.max(0,maxIcons)) + return {icons: shown.map(n => categoryIcon(n.category)),keys: shown.map(n => n.key),stale:false} } export function readNotificationIconByKey(key: string, _allowStale: boolean) { - return {icon: readActiveNotifications(ALL_NOTIFICATIONS).some(n => n.key === key) ? bell() : null,stale:false} + const notification = readActiveNotifications(ALL_NOTIFICATIONS).find(n => n.key === key) + return {icon: notification ? categoryIcon(notification.category) : null,stale:false} } diff --git a/tests/ios-notification-icons.test.cjs b/tests/ios-notification-icons.test.cjs new file mode 100644 index 00000000..e47e8146 --- /dev/null +++ b/tests/ios-notification-icons.test.cjs @@ -0,0 +1,51 @@ +const test = require('node:test'); +const assert = require('node:assert/strict'); +const { loader } = require('./helpers/load-typescript.cjs'); + +class FakeImage { + constructor(name) { this.name = name; } + clone() { return new FakeImage(this.name); } + fillRoundedRect() {} + fillRect() {} +} + +function setup(notifications, render = name => new FakeImage(name)) { + const icons = loader({}, { + '../graphics/image': { GrayImage: class extends FakeImage { constructor() { super('drawn-bell'); } } }, + '../graphics/icons': { renderIcon: (name, size) => { assert.equal(size, 24); return render(name); } }, + '../g2/ancs-client': { AncsClient: class {}, ANCS_CONNECT_MESSAGE: '' }, + './notification-sources': { rememberNotificationSources() {} }, + })('app/native/notification-icons.ios.ts'); + icons.bindIosNotifications({ read: () => notifications }); + return icons; +} + +const notification = (key, packageName, category) => ({ key, packageName, category }); + +test('tray icons follow each source\'s first notification category', () => { + const icons = setup([ + notification('a', 'com.apple.mobilephone', '2'), + notification('b', 'com.apple.mobilephone', '1'), + notification('c', 'com.apple.mobilemail', '6'), + notification('d', 'com.example.tv', '11'), + ]); + const result = icons.readActiveNotificationIcons(10, false); + assert.deepEqual([...result.keys], ['a', 'c', 'd']); + assert.deepEqual([...result.icons].map(icon => icon.name), ['phone-missed', 'mail', 'tv']); + assert.equal(icons.readActiveNotificationIcons(1, false).icons.length, 1); +}); + +test('unknown categories use the bell; a failed rasterization uses the drawn bell', () => { + const icons = setup([notification('a', 'x', '0'), notification('b', 'y', '12'), notification('c', 'z', '')]); + assert.deepEqual([...icons.readActiveNotificationIcons(10, false).icons].map(icon => icon.name), ['bell', 'bell', 'bell']); + assert.equal(icons.readNotificationIconByKey('missing', false).icon, null); + + const failing = setup([notification('a', 'x', '4')], () => null); + assert.equal(failing.readNotificationIconByKey('a', false).icon.name, 'drawn-bell'); +}); + +test('icons are copies, so callers can draw on them', () => { + const shared = new FakeImage('message-circle'); + const icons = setup([notification('a', 'x', '4')], () => shared); + assert.notEqual(icons.readNotificationIconByKey('a', false).icon, shared); +}); From 406cefe0c5eca71db16de453328614bf7f60224c Mon Sep 17 00:00:00 2001 From: James Babcock Date: Sat, 10 Oct 2026 17:33:32 -0700 Subject: [PATCH 04/65] Add stats collection and first-run on-glasses onboarding app --- .github/workflows/tests.yml | 29 ++ .../com/faceclaw/app/FaceclawBleManager.kt | 1 + App_Resources/iOS/build.xcconfig | 2 +- CHANGELOG | 4 +- PRIVACY | 50 ++- app/analytics/analytics-sources.ts | 84 ++++ app/analytics/analytics-store.ts | 410 ++++++++++++++++++ app/analytics/analytics.ts | 182 ++++++++ app/apps/all-apps.ts | 2 + app/apps/onboarding/data-collection-page.ts | 75 ++++ app/apps/onboarding/index.ts | 17 + app/apps/onboarding/onboarding-app.ts | 98 +++++ app/apps/onboarding/onboarding-fonts.ts | 38 ++ app/apps/onboarding/onboarding-page.ts | 48 ++ app/apps/onboarding/onboarding-progress.ts | 34 ++ app/apps/onboarding/text-size-page.ts | 159 +++++++ app/apps/onboarding/welcome-page.ts | 51 +++ app/bootstrap.android.ts | 5 + app/bootstrap.ios.ts | 4 + app/g2/dashboard-controller.ts | 34 +- app/g2/ios-preview-controller.ts | 20 +- app/g2/wear-remote.ts | 3 + app/graphics/icons.ts | 2 + app/graphics/imagefile.ts | 10 +- app/graphics/installed-fonts.ts | 5 + app/graphics/logo.ts | 54 +++ app/native/build-info.ios.ts | 19 + app/native/build-info.ts | 54 +++ app/native/connection-counters.ios.ts | 10 + app/native/connection-counters.ts | 14 + app/phone-ui/onboarding-state.ts | 23 +- app/ui/dashboard-settings.ts | 62 +++ app/ui/dashboard/settings-menus.ts | 8 + app/ui/font-picker.ts | 9 +- build_paths.sh.template | 2 + .../g2protocol/session/ConnectionCounters.kt | 44 ++ .../session/GlassesSessionControls.kt | 22 + .../g2protocol/session/GlassesSessionCore.kt | 20 +- .../g2protocol/session/GlassesSessionSend.kt | 6 +- .../com/faceclaw/app/ble/IosBleCentral.kt | 1 + .../__pycache__/ios_config.cpython-314.pyc | Bin 0 -> 14621 bytes scripts/find-firmware-fonts.py | 53 +++ scripts/ios.sh | 9 + scripts/resetOnboarding.sh | 3 +- scripts/test/annotate_config.py | 188 ++++++++ scripts/test/build-evenhub-font.mjs | 207 +++++++++ scripts/test/pack-ehpk.mjs | 91 ++++ scripts/test/pinball-sim.js | 302 +++++++++++++ scripts/test/resetAndRun.sh | 90 ++++ .../test/set_show_ime_with_hard_keyboard.sh | 4 + stats-server/PROTOCOL.md | 92 ++++ stats-server/README.md | 64 +++ stats-server/deploy.sh | 32 ++ stats-server/deploy/faceclaw-stats.service | 21 + stats-server/deploy/nginx-site.conf | 33 ++ stats-server/deploy/run.sh | 9 + stats-server/deploy/setup-server.sh | 57 +++ stats-server/deploy/stats.env | 7 + stats-server/package-lock.json | 211 +++++++++ stats-server/package.json | 23 + stats-server/schema.sql | 57 +++ stats-server/src/db.ts | 69 +++ stats-server/src/report.ts | 126 ++++++ stats-server/src/server.ts | 91 ++++ stats-server/test/db.test.ts | 43 ++ stats-server/test/report.test.ts | 61 +++ stats-server/test/sample.ts | 14 + stats-server/tsconfig.json | 17 + tests/analytics-store.test.cjs | 205 +++++++++ tests/ios-app-host.test.cjs | 48 +- tests/ios-glanceboard.test.cjs | 3 +- .../faceclaw/app/ConnectionCountersTest.kt | 33 ++ website/privacy.html | 26 +- 73 files changed, 3906 insertions(+), 98 deletions(-) create mode 100644 app/analytics/analytics-sources.ts create mode 100644 app/analytics/analytics-store.ts create mode 100644 app/analytics/analytics.ts create mode 100644 app/apps/onboarding/data-collection-page.ts create mode 100644 app/apps/onboarding/index.ts create mode 100644 app/apps/onboarding/onboarding-app.ts create mode 100644 app/apps/onboarding/onboarding-fonts.ts create mode 100644 app/apps/onboarding/onboarding-page.ts create mode 100644 app/apps/onboarding/onboarding-progress.ts create mode 100644 app/apps/onboarding/text-size-page.ts create mode 100644 app/apps/onboarding/welcome-page.ts create mode 100644 app/native/build-info.ios.ts create mode 100644 app/native/build-info.ts create mode 100644 app/native/connection-counters.ios.ts create mode 100644 app/native/connection-counters.ts create mode 100644 native/kotlin/shared/src/commonMain/kotlin/com/faceclaw/app/g2protocol/session/ConnectionCounters.kt create mode 100644 scripts/__pycache__/ios_config.cpython-314.pyc create mode 100755 scripts/find-firmware-fonts.py create mode 100755 scripts/test/annotate_config.py create mode 100644 scripts/test/build-evenhub-font.mjs create mode 100644 scripts/test/pack-ehpk.mjs create mode 100644 scripts/test/pinball-sim.js create mode 100755 scripts/test/resetAndRun.sh create mode 100755 scripts/test/set_show_ime_with_hard_keyboard.sh create mode 100644 stats-server/PROTOCOL.md create mode 100644 stats-server/README.md create mode 100755 stats-server/deploy.sh create mode 100644 stats-server/deploy/faceclaw-stats.service create mode 100644 stats-server/deploy/nginx-site.conf create mode 100755 stats-server/deploy/run.sh create mode 100755 stats-server/deploy/setup-server.sh create mode 100644 stats-server/deploy/stats.env create mode 100644 stats-server/package-lock.json create mode 100644 stats-server/package.json create mode 100644 stats-server/schema.sql create mode 100644 stats-server/src/db.ts create mode 100644 stats-server/src/report.ts create mode 100644 stats-server/src/server.ts create mode 100644 stats-server/test/db.test.ts create mode 100644 stats-server/test/report.test.ts create mode 100644 stats-server/test/sample.ts create mode 100644 stats-server/tsconfig.json create mode 100644 tests/analytics-store.test.cjs create mode 100644 tests/kotlin/src/commonTest/kotlin/com/faceclaw/app/ConnectionCountersTest.kt diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index d4d131ed..65ba1739 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -27,6 +27,35 @@ jobs: - run: npm ci - run: npm run test:kotlin + # The stats.faceclaw.org server: typecheck, and the tests including the + # database one against a throwaway Postgres. + stats-server: + runs-on: ubuntu-latest + defaults: + run: + working-directory: stats-server + services: + postgres: + image: postgres:16 + env: + POSTGRES_PASSWORD: postgres + ports: ["5432:5432"] + options: >- + --health-cmd pg_isready --health-interval 5s --health-timeout 5s --health-retries 10 + env: + PGHOST: localhost + PGUSER: postgres + PGPASSWORD: postgres + STATS_TEST_DATABASE: postgres + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 22 + - run: npm ci + - run: npm run check + - run: npm test + # 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. diff --git a/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawBleManager.kt b/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawBleManager.kt index 8cc7808a..4cbaf7b2 100644 --- a/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawBleManager.kt +++ b/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawBleManager.kt @@ -507,6 +507,7 @@ class FaceclawBleManager(context: Context) { override fun onConnectionStateChange(gatt: BluetoothGatt, status: Int, newState: Int) { val address = gatt.device.address Log.i(TAG, "onConnectionStateChange: address=$address status=$status newState=$newState") + if (status != BluetoothGatt.GATT_SUCCESS) ConnectionCounters.increment("ble.gatt-status.$status") val link = links[address] val current = link?.gatt if (link == null || (current != null && current !== gatt)) { diff --git a/App_Resources/iOS/build.xcconfig b/App_Resources/iOS/build.xcconfig index f657ddce..48087eb6 100644 --- a/App_Resources/iOS/build.xcconfig +++ b/App_Resources/iOS/build.xcconfig @@ -2,7 +2,7 @@ IPHONEOS_DEPLOYMENT_TARGET = 15.1; TARGETED_DEVICE_FAMILY = 1; CODE_SIGN_STYLE = Automatic; -// Select the local signing team in Xcode or pass --teamId to the iOS scripts. +// Set IOS_TEAM_ID in build_paths.sh (or pass --teamId) to choose the signing team. OTHER_LDFLAGS = $(inherited) -framework CoreBluetooth -framework CoreLocation -framework CoreText -framework Speech -framework AVFoundation -framework WebKit -framework UniformTypeIdentifiers -framework ImageIO -framework EventKit ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon; diff --git a/CHANGELOG b/CHANGELOG index 1c45f736..c2c70625 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -4,7 +4,9 @@ * Fix several issues that would cause disconnection and disconnect-looping * Add a client for T3 Code -* Weather app shows an icon for current conditions, and can add the weather to the status bar and the Glanceboard system card (Weather menu > Settings) +* Weather app is more graphical, and can appear on the status bar and glanceboard Glanceboard system card +* Optional anonymous usage statistics (Settings>Privacy>Data collection; off by default) +* Add an on-glasses Onboarding app, which prompts you to configure some things ## 0.8.2 - 2026-10-03 diff --git a/PRIVACY b/PRIVACY index 8b9251c7..28d7a5df 100644 --- a/PRIVACY +++ b/PRIVACY @@ -1,10 +1,50 @@ # Faceclaw Privacy Policy -Faceclaw is a privacy-conscious app. The developers of Faceclaw don't collect -or store user data. Faceclaw does integrate with some third-party services, -which have their own privacy policies; this document describes what those -services are, what they're used for and what data they collect, and links to -their privacy policies. +Faceclaw is a privacy-conscious app. Unless you choose to share anonymous +usage statistics (described below), the developers of Faceclaw don't collect +or store any data about you or how you use the app. Faceclaw does integrate +with some third-party services, which have their own privacy policies; this +document describes what those services are, what they're used for and what +data they collect, and links to their privacy policies. + + +## Usage Statistics + +The first time you connect your glasses, Faceclaw asks whether to share +anonymous usage statistics with its developers, to help them fix problems and +improve the app. The choices are None, Minimal and Full, and you can change +your choice at any time in Settings > Privacy. Until you choose, it is None. + +With None, Faceclaw sends nothing and keeps no statistics on your phone. + +With Minimal, Faceclaw keeps counts on your phone and sends them about once a +day to stats.faceclaw.org, a server run by Faceclaw's developers: + + - the Faceclaw version, whether it runs on Android or iOS, and whether it is + an official release or a build someone compiled themselves; + - whether glasses and a ring are paired, and which devices (glasses, ring, + Wear OS watch) were in use each day; + - counts of connection events: connection attempts, disconnections and + their causes, message timeouts and retries, Bluetooth error codes, and + how long connections lasted. + +With Full, it also sends: + + - which kinds of API key are set (for example, that an Anthropic key is + set), but never the keys themselves; + - how many terminal and T3 Code connections are set up, and which of + Faceclaw's built-in fonts is in use; + - the values of settings chosen from fixed options, such as on/off + switches and pick-one lists. Settings you type in, such as addresses, + URLs and names, are never sent. + +Statistics never include your name or contact details, your location, +Bluetooth device addresses, anything you say or type, or what is shown on +your glasses. Each report carries a random identifier, created when you turn +statistics on, which links your reports to each other but not to you. +Turning statistics off deletes that identifier and everything kept on the +phone, and stops all reports; turning them back on starts a new identifier. +The statistics server doesn't record the IP addresses reports come from. ## Audio diff --git a/app/analytics/analytics-sources.ts b/app/analytics/analytics-sources.ts new file mode 100644 index 00000000..65b026e7 --- /dev/null +++ b/app/analytics/analytics-sources.ts @@ -0,0 +1,84 @@ +/** + * The app-wide things analytics reports (the reliability counts come from + * Kotlin, drained in analytics.ts): + * - Minimal: which devices are paired, and which were in use each day; + * - Full: which kinds of API key are set, how many terminal and T3 Code + * connections there are, the UI font, and every fixed-choice setting. + * Never anything a person typed in: no keys, addresses, names or URLs. + */ +import { loadEnvironments } from "../apps/t3code/t3-environments"; +import { loadConnections } from "../apps/terminal/connections"; +import { loadDeviceAddresses } from "../g2/device-addresses"; +import { onGlassesPresenceChanged } from "../g2/glasses-presence"; +import { isPreinstalledFont } from "../graphics/installed-fonts"; +import { getUiFontSelection } from "../graphics/ui-fonts"; +import { getStringSetting } from "../native/settings-store"; +import { isPreviewOnlyMode } from "../phone-ui/onboarding-state"; +import { fixedChoiceSettingValues, ringConnectionModeSetting } from "../ui/dashboard-settings"; +import { addInputListener } from "../ui/input-monitor"; +import { flagAnalyticsEvent, registerAnalyticsSnapshot, startAnalytics } from "./analytics"; +import type { Snapshot } from "./analytics-store"; + +/** Settings holding API keys and tokens, reported only as set or not, by kind. */ +const API_KEY_SETTINGS: Record = { + anthropic: "llm.anthropicApiKey", + openai: "voice.openAiApiKey", + elevenlabs: "voice.elevenLabsApiKey", + soniox: "voice.sonioxApiKey", + mapbox: "maps.mapboxApiKey", + roam: "integrations.roam.apiToken", + nightscout: "integrations.nightscout.apiToken", + "agent-bridge": "assistant.bridgeToken", + evenhub: "integrations.evenhub.token", +}; + +let started = false; + +/** Registers the sources above and starts analytics. Main thread, at boot. */ +export function startAppAnalytics(): void { + if (started) return; + started = true; + registerAnalyticsSnapshot("minimal", deviceSnapshot); + registerAnalyticsSnapshot("full", configurationSnapshot); + + onGlassesPresenceChanged((presence) => { + if (presence.connected) flagAnalyticsEvent("minimal", "device.g2.used"); + }); + addInputListener((event) => { + if (!("source" in event)) return; + if (event.source === "ring") flagAnalyticsEvent("minimal", "device.r1.used"); + else if (event.source === "left-arm" || event.source === "right-arm") flagAnalyticsEvent("minimal", "device.g2.touchpad-used"); + }); + startAnalytics(); +} + +function deviceSnapshot(): Snapshot { + const addresses = loadDeviceAddresses(); + return { + "device.g2.paired": Boolean(addresses.left && addresses.right), + "device.g2.preview-only": isPreviewOnlyMode(), + "device.r1.paired": Boolean(addresses.ring), + "device.r1.connection": ringConnectionModeSetting.get(), + }; +} + +function configurationSnapshot(): Snapshot { + const snapshot: Snapshot = {}; + for (const [kind, storageKey] of Object.entries(API_KEY_SETTINGS)) { + snapshot[`apikey.${kind}`] = getStringSetting(storageKey, "").trim() !== ""; + } + snapshot["config.nightscout-site"] = getStringSetting("integrations.nightscout.siteUrl", "").trim() !== ""; + snapshot["config.terminal-connections"] = loadConnections().length; + snapshot["config.t3code-environments"] = loadEnvironments().length; + + const font = getUiFontSelection(); + snapshot["config.ui-font"] = + font.kind === "bitmap" + ? font.face + : `${isPreinstalledFont(font.file) ? font.file.replace(/\.ttf$/i, "") : "installed"}:${font.size}`; + + for (const [storageKey, value] of Object.entries(fixedChoiceSettingValues())) { + snapshot[`setting.${storageKey}`] = value; + } + return snapshot; +} diff --git a/app/analytics/analytics-store.ts b/app/analytics/analytics-store.ts new file mode 100644 index 00000000..a38cbd45 --- /dev/null +++ b/app/analytics/analytics-store.ts @@ -0,0 +1,410 @@ +/** + * Opt-in analytics, held on the phone between daily uploads to + * stats.faceclaw.org. This is the platform-free core: storage, clock, the + * data-collection setting and the network are passed in (analytics.ts wires + * them up), so the tests can drive it directly. + * + * Data is recorded at a level, and only while the data-collection setting is + * at that level or above: + * - "minimal": the app version and build, which devices are paired and in + * use, and connection-reliability counts; + * - "full": also API-key presence (never the keys) and settings chosen from + * fixed options. + * Turning the setting down discards what was kept above the new level; + * turning it off deletes everything, including the install id, and stops all + * writes and uploads. + * + * Counters accumulate in pending.json (per UTC day). Once a day the pending + * counters and a snapshot of the current state are sealed into an outbox + * report, and every outbox report is posted; each stays until the server + * accepts it, under a report id the server deduplicates on. The report + * format is stats-server/PROTOCOL.md. + */ + +export type AnalyticsLevel = "minimal" | "full"; +export type DataCollectionLevel = "none" | AnalyticsLevel; +export type SnapshotValue = boolean | number | string; +export type Snapshot = Record; + +export interface AppInfo { + version: string; + platform: string; + build: string; +} + +/** Named text files in the analytics directory. */ +export interface AnalyticsStorage { + read(name: string): string | null; + write(name: string, text: string): void; + remove(name: string): void; + list(): string[]; + /** Deletes the directory and everything in it. */ + removeAll(): void; +} + +export interface AnalyticsDeps { + storage: AnalyticsStorage; + /** The data-collection setting, read fresh on every use. */ + level(): DataCollectionLevel; + appInfo(): AppInfo; + now(): number; + randomId(): string; + /** The current state to report at `level` (each level's keys, not cumulative). */ + snapshot(level: AnalyticsLevel): Snapshot; + /** POSTs a report body; resolves to the HTTP status, rejects on network failure. */ + send(body: string): Promise; + log?(message: string): void; +} + +/** UTC day (YYYY-MM-DD) → counter name → count. */ +type Counters = Record>; +type ByLevel = { minimal: T; full: T }; + +interface PendingFile { + format: 1; + /** The app version the counts were made under; a different one seals them. */ + version: string; + counters: ByLevel; +} + +interface OutboxReport { + format: 1; + reportId: string; + createdAt: string; + app: AppInfo; + counters: ByLevel; + snapshot: ByLevel; +} + +interface StateFile { + format: 1; + installId: string; + lastSealAt: number; + /** When to retry after a failed upload; 0 when none failed. */ + retryAt: number; +} + +export const REPORT_SCHEMA_VERSION = 1; +export const DAY_MS = 24 * 60 * 60 * 1000; +export const RETRY_MS = 60 * 60 * 1000; +/** Unsent reports kept while the server is unreachable; the oldest go first. */ +export const MAX_OUTBOX_REPORTS = 30; +/** Distinct counter names per day and level, so a runaway name can't grow the file. */ +export const MAX_NAMES_PER_DAY = 300; +const FLUSH_DELAY_MS = 15_000; + +const PENDING_FILE = "pending.json"; +const STATE_FILE = "state.json"; +const OUTBOX_PREFIX = "outbox-"; + +/** Counter names and snapshot keys the server accepts (stats-server/src/report.ts). */ +const COUNTER_NAME = /^[a-z0-9][a-z0-9_.:-]{0,119}$/; +const SNAPSHOT_KEY = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,119}$/; +const MAX_SNAPSHOT_STRING = 200; + +export class AnalyticsStore { + private pending: PendingFile | null = null; + private dirty = false; + private flushTimer: ReturnType | null = null; + private uploading = false; + /** Bumped by discardAll, so an upload in flight knows not to write its state back. */ + private generation = 0; + + constructor(private readonly deps: AnalyticsDeps) {} + + /** Whether data at `level` is being kept. */ + allows(level: AnalyticsLevel): boolean { + const setting = this.deps.level(); + return setting === "full" || (setting === "minimal" && level === "minimal"); + } + + /** Adds `amount` to today's count of `name`. */ + count(level: AnalyticsLevel, name: string, amount = 1): void { + if (!this.allows(level) || !(amount > 0)) return; + if (!COUNTER_NAME.test(name)) { + this.log(`analytics: dropping bad counter name ${name}`); + return; + } + const day = this.dayCounters(level); + if (day[name] === undefined && Object.keys(day).length >= MAX_NAMES_PER_DAY) return; + day[name] = (day[name] ?? 0) + Math.round(amount); + this.markDirty(); + } + + /** Records that `name` happened today (a count of 1, however often it happens). */ + flag(level: AnalyticsLevel, name: string): void { + if (!this.allows(level)) return; + if (!COUNTER_NAME.test(name)) { + this.log(`analytics: dropping bad counter name ${name}`); + return; + } + const day = this.dayCounters(level); + if (day[name] !== undefined || Object.keys(day).length >= MAX_NAMES_PER_DAY) return; + day[name] = 1; + this.markDirty(); + } + + /** + * Brings the files in line with the setting: off deletes everything, + * minimal drops what was kept for full. Called at start and whenever the + * setting changes. + */ + applyLevel(): void { + const setting = this.deps.level(); + if (setting === "none") { + this.discardAll(); + return; + } + if (setting === "full") return; + const pending = this.loadPending(); + if (Object.keys(pending.counters.full).length) { + pending.counters.full = {}; + this.writePending(pending); + } + for (const name of this.outboxNames()) { + const report = this.readJson(name) as OutboxReport | null; + if (!report) continue; + if (Object.keys(report.counters.full).length || Object.keys(report.snapshot.full).length) { + report.counters.full = {}; + report.snapshot.full = {}; + this.deps.storage.write(name, JSON.stringify(report)); + } + } + } + + /** Writes pending counts now, if any changed. */ + flush(): void { + if (this.flushTimer !== null) { + clearTimeout(this.flushTimer); + this.flushTimer = null; + } + if (!this.dirty || !this.pending) return; + this.dirty = false; + if (this.deps.level() === "none") { + this.discardAll(); + return; + } + this.writePending(this.pending); + } + + /** + * The daily upload: once a day, seal the pending counts into a report and + * post every unsent report; after a failure, retry hourly. Does nothing, + * and makes no connection, while the setting is off. + */ + async uploadIfDue(): Promise { + if (this.uploading) return; + if (this.deps.level() === "none") { + this.discardAll(); + return; + } + this.uploading = true; + const generation = this.generation; + try { + const now = this.deps.now(); + const state = this.loadState(); + let sealed = false; + // A clock set backwards shouldn't stall the schedule until it catches up. + if (now - state.lastSealAt >= DAY_MS || now < state.lastSealAt) { + this.seal(); + state.lastSealAt = now; + this.writeState(state); + sealed = true; + } + if (!sealed && !(state.retryAt > 0 && now >= state.retryAt)) return; + + for (const name of this.outboxNames()) { + const report = this.readJson(name) as OutboxReport | null; + if (!report) { + this.deps.storage.remove(name); + continue; + } + let status: number | null; + try { + status = await this.deps.send(this.reportBody(report, state.installId)); + } catch (error) { + this.log(`analytics: upload failed: ${error}`); + status = null; + } + // The setting may have been turned off (and maybe on again) while the + // request was out; then everything this upload knew about is gone. + if (this.deps.level() === "none") { + this.discardAll(); + return; + } + if (this.generation !== generation) return; + if (status !== null && status >= 200 && status < 300) { + this.deps.storage.remove(name); + } else if (status === 400 || status === 413) { + // Rejected as malformed or too large: sending it again won't help. + // (Anything else, like a 404 from a misconfigured server, is retried.) + this.log(`analytics: server rejected report ${report.reportId} (HTTP ${status})`); + this.deps.storage.remove(name); + } else { + state.retryAt = now + RETRY_MS; + this.writeState(state); + return; + } + } + if (state.retryAt !== 0) { + state.retryAt = 0; + this.writeState(state); + } + } finally { + this.uploading = false; + } + } + + /** Deletes everything kept, including the install id. */ + discardAll(): void { + if (this.flushTimer !== null) { + clearTimeout(this.flushTimer); + this.flushTimer = null; + } + this.pending = null; + this.dirty = false; + this.generation++; + this.deps.storage.removeAll(); + } + + /** The JSON body posted for `report`, including only what the current setting allows. */ + reportBody(report: OutboxReport, installId: string): string { + const level: AnalyticsLevel = this.deps.level() === "full" ? "full" : "minimal"; + const counters: Counters = {}; + for (const source of level === "full" ? [report.counters.minimal, report.counters.full] : [report.counters.minimal]) { + for (const [day, counts] of Object.entries(source)) { + const target = (counters[day] ??= {}); + for (const [name, count] of Object.entries(counts)) target[name] = (target[name] ?? 0) + count; + } + } + return JSON.stringify({ + schema: REPORT_SCHEMA_VERSION, + reportId: report.reportId, + installId, + level, + createdAt: report.createdAt, + app: report.app, + counters, + snapshot: level === "full" ? { ...report.snapshot.minimal, ...report.snapshot.full } : report.snapshot.minimal, + }); + } + + private dayCounters(level: AnalyticsLevel): Record { + const day = new Date(this.deps.now()).toISOString().slice(0, 10); + return (this.loadPending().counters[level][day] ??= {}); + } + + private markDirty(): void { + this.dirty = true; + this.flushTimer ??= setTimeout(() => { + this.flushTimer = null; + this.flush(); + }, FLUSH_DELAY_MS); + } + + private loadPending(): PendingFile { + if (this.pending) return this.pending; + const version = this.deps.appInfo().version; + const stored = this.readJson(PENDING_FILE) as PendingFile | null; + if (stored && stored.format === 1 && stored.counters?.minimal && stored.counters?.full) { + this.pending = stored; + if (stored.version !== version && hasCounts(stored)) { + // Counts from before an upgrade go out under the version they were made with. + this.seal(); + } + } + return (this.pending ??= emptyPending(version)); + } + + /** Moves the pending counts, with a snapshot of the current state, into a new outbox report. */ + private seal(): void { + const pending = this.loadPending(); + const app = { ...this.deps.appInfo(), version: pending.version }; + const report: OutboxReport = { + format: 1, + reportId: this.deps.randomId(), + createdAt: new Date(this.deps.now()).toISOString(), + app, + counters: pending.counters, + snapshot: { + minimal: this.takeSnapshot("minimal"), + full: this.allows("full") ? this.takeSnapshot("full") : {}, + }, + }; + this.deps.storage.write(`${OUTBOX_PREFIX}${report.createdAt.replace(/[^0-9]/g, "")}-${report.reportId}.json`, JSON.stringify(report)); + this.pending = emptyPending(this.deps.appInfo().version); + this.dirty = false; + this.writePending(this.pending); + const outbox = this.outboxNames(); + for (const name of outbox.slice(0, Math.max(0, outbox.length - MAX_OUTBOX_REPORTS))) this.deps.storage.remove(name); + } + + private takeSnapshot(level: AnalyticsLevel): Snapshot { + const snapshot: Snapshot = {}; + let entries: [string, SnapshotValue][]; + try { + entries = Object.entries(this.deps.snapshot(level)); + } catch (error) { + this.log(`analytics: ${level} snapshot failed: ${error}`); + return snapshot; + } + for (const [key, value] of entries) { + const ok = + SNAPSHOT_KEY.test(key) && + (typeof value === "boolean" || + (typeof value === "number" && Number.isFinite(value)) || + (typeof value === "string" && value.length <= MAX_SNAPSHOT_STRING)); + if (ok) snapshot[key] = value; + else this.log(`analytics: dropping bad snapshot entry ${key}`); + } + return snapshot; + } + + /** Outbox file names, oldest first (the names start with the seal time). */ + private outboxNames(): string[] { + return this.deps.storage + .list() + .filter((name) => name.startsWith(OUTBOX_PREFIX)) + .sort(); + } + + private loadState(): StateFile { + const stored = this.readJson(STATE_FILE) as StateFile | null; + if (stored && stored.format === 1 && typeof stored.installId === "string") return stored; + const state: StateFile = { format: 1, installId: this.deps.randomId(), lastSealAt: 0, retryAt: 0 }; + this.writeState(state); + return state; + } + + private writeState(state: StateFile): void { + this.deps.storage.write(STATE_FILE, JSON.stringify(state)); + } + + private writePending(pending: PendingFile): void { + this.deps.storage.write(PENDING_FILE, JSON.stringify(pending)); + } + + private readJson(name: string): unknown { + const text = this.deps.storage.read(name); + if (text === null) return null; + try { + return JSON.parse(text); + } catch { + this.log(`analytics: discarding unreadable ${name}`); + this.deps.storage.remove(name); + return null; + } + } + + private log(message: string): void { + this.deps.log?.(message); + } +} + +function emptyPending(version: string): PendingFile { + return { format: 1, version, counters: { minimal: {}, full: {} } }; +} + +function hasCounts(pending: PendingFile): boolean { + return Object.keys(pending.counters.minimal).length > 0 || Object.keys(pending.counters.full).length > 0; +} diff --git a/app/analytics/analytics.ts b/app/analytics/analytics.ts new file mode 100644 index 00000000..c73ca20a --- /dev/null +++ b/app/analytics/analytics.ts @@ -0,0 +1,182 @@ +/** + * The app's analytics API. What is collected, when it's kept and when it's + * sent is described in analytics-store.ts; the snapshot providers (devices, + * API-key presence, settings) are in analytics-snapshots.ts. + * + * Record from the main thread only. The store is created by startAnalytics() + * at boot, which app workers never run, so calls made in a worker are + * dropped. Kotlin-side connection events go through ConnectionCounters + * (drained here) instead. + */ +import { File, Folder, knownFolders, path as fsPath } from "@nativescript/core"; +import { buildKind } from "../native/build-info"; +import { drainConnectionCounters } from "../native/connection-counters"; +import { onSettingsStoreChanged } from "../native/settings-store"; +import { DATA_COLLECTION_KEY, dataCollectionSetting } from "../ui/dashboard-settings"; +import { fetchTextWithUserAgent } from "../util/http"; +import { FACECLAW_VERSION } from "../version"; +import { + AnalyticsStore, + type AnalyticsLevel, + type AnalyticsStorage, + type Snapshot, +} from "./analytics-store"; + +export type { AnalyticsLevel, Snapshot } from "./analytics-store"; + +declare const global: any; + +const REPORT_URL = "https://stats.faceclaw.org/v1/report"; +const REQUEST_TIMEOUT_MS = 30_000; +/** How often to see whether the daily upload is due (it usually isn't). */ +const UPLOAD_CHECK_INTERVAL_MS = 60 * 60 * 1000; +/** The first check, a little after boot or after analytics is turned on. */ +const FIRST_UPLOAD_CHECK_DELAY_MS = 2 * 60 * 1000; +/** How often the Kotlin connection counts are moved into the store. */ +const DRAIN_INTERVAL_MS = 5 * 60 * 1000; + +let store: AnalyticsStore | null = null; +let firstCheckTimer: ReturnType | null = null; +const snapshotProviders: { level: AnalyticsLevel; provide: () => Snapshot }[] = []; + +/** + * Adds `amount` to today's count of `name`, if the data-collection setting + * includes `level`. Names are lowercase, dot-separated (e.g. "g2.connect"). + */ +export function countAnalyticsEvent(level: AnalyticsLevel, name: string, amount = 1): void { + store?.count(level, name, amount); +} + +/** Records that `name` happened today: a count of 1 however often it happens. */ +export function flagAnalyticsEvent(level: AnalyticsLevel, name: string): void { + store?.flag(level, name); +} + +/** + * Adds state to report with each daily upload, when the setting includes + * `level`. Called when the report is sealed; keys must be namespaced like + * "device.g2.paired", and values booleans, numbers or short strings. + */ +export function registerAnalyticsSnapshot(level: AnalyticsLevel, provide: () => Snapshot): void { + snapshotProviders.push({ level, provide }); +} + +/** Starts the store, the daily upload schedule and the counter drain. Main thread, once, at boot. */ +export function startAnalytics(): void { + if (store) return; + const analytics = new AnalyticsStore({ + storage: createStorage(), + level: () => dataCollectionSetting.get(), + appInfo: () => ({ version: FACECLAW_VERSION, platform: global.isIOS ? "ios" : "android", build: buildKind() }), + now: () => Date.now(), + randomId: randomUuid, + snapshot: collectSnapshot, + send: sendReport, + log: (message) => console.log(message), + }); + store = analytics; + analytics.applyLevel(); + + onSettingsStoreChanged((key) => { + if (key !== DATA_COLLECTION_KEY) return; + analytics.applyLevel(); + if (dataCollectionSetting.get() !== "none") scheduleFirstCheck(analytics); + }); + setInterval(() => drainKotlinCounters(analytics), DRAIN_INTERVAL_MS); + setInterval(() => void checkUpload(analytics), UPLOAD_CHECK_INTERVAL_MS); + scheduleFirstCheck(analytics); +} + +function scheduleFirstCheck(analytics: AnalyticsStore): void { + if (firstCheckTimer !== null) clearTimeout(firstCheckTimer); + firstCheckTimer = setTimeout(() => { + firstCheckTimer = null; + void checkUpload(analytics); + }, FIRST_UPLOAD_CHECK_DELAY_MS); +} + +async function checkUpload(analytics: AnalyticsStore): Promise { + drainKotlinCounters(analytics); + try { + await analytics.uploadIfDue(); + } catch (error) { + console.warn(`analytics: upload check failed: ${error}`); + } +} + +function drainKotlinCounters(analytics: AnalyticsStore): void { + let counts: Record; + try { + counts = drainConnectionCounters(); + } catch (error) { + console.warn(`analytics: could not read connection counters: ${error}`); + return; + } + // Drained either way, so counts from while analytics was off don't pile up. + for (const [name, count] of Object.entries(counts)) analytics.count("minimal", name, count); + analytics.flush(); +} + +function collectSnapshot(level: AnalyticsLevel): Snapshot { + const snapshot: Snapshot = {}; + for (const provider of snapshotProviders) { + if (provider.level !== level) continue; + try { + Object.assign(snapshot, provider.provide()); + } catch (error) { + console.warn(`analytics: snapshot provider failed: ${error}`); + } + } + return snapshot; +} + +async function sendReport(body: string): Promise { + let timeout: ReturnType | undefined; + const timedOut = new Promise((_resolve, reject) => { + timeout = setTimeout(() => reject(new Error("timed out")), REQUEST_TIMEOUT_MS); + }); + try { + const response = await Promise.race([ + fetchTextWithUserAgent(REPORT_URL, { method: "POST", headers: { "Content-Type": "application/json" }, body }), + timedOut, + ]); + return response.status; + } finally { + clearTimeout(timeout); + } +} + +/** + * Files in an `analytics` directory: the app's private files directory on + * Android; on iOS, Library rather than Documents, which the Files app shows. + */ +function createStorage(): AnalyticsStorage { + const base = global.isIOS ? knownFolders.ios.library().path : knownFolders.documents().path; + const dir = fsPath.join(base, "analytics"); + const filePath = (name: string) => fsPath.join(dir, name); + return { + read: (name) => (File.exists(filePath(name)) ? File.fromPath(filePath(name)).readTextSync() : null), + write: (name, text) => { + Folder.fromPath(dir); + File.fromPath(filePath(name)).writeTextSync(text); + }, + remove: (name) => { + if (File.exists(filePath(name))) File.fromPath(filePath(name)).removeSync(); + }, + list: () => (Folder.exists(dir) ? Folder.fromPath(dir).getEntitiesSync().map((entity) => entity.name) : []), + removeAll: () => { + if (Folder.exists(dir)) Folder.fromPath(dir).removeSync(); + }, + }; +} + +function randomUuid(): string { + const bytes = new Uint8Array(16); + const crypto = (globalThis as { crypto?: { getRandomValues?: (array: Uint8Array) => Uint8Array } }).crypto; + if (crypto?.getRandomValues) crypto.getRandomValues(bytes); + else for (let index = 0; index < bytes.length; index++) bytes[index] = Math.floor(Math.random() * 256); + bytes[6] = (bytes[6]! & 0x0f) | 0x40; + bytes[8] = (bytes[8]! & 0x3f) | 0x80; + const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join(""); + return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`; +} diff --git a/app/apps/all-apps.ts b/app/apps/all-apps.ts index 1ba6d4c5..3c3d3598 100644 --- a/app/apps/all-apps.ts +++ b/app/apps/all-apps.ts @@ -26,6 +26,7 @@ import developerApp from "./developer"; import evenhubApp from "./evenhub"; import glanceboardApp from "./glanceboard"; import settingsApp from "./settings"; +import onboardingApp from "./onboarding"; /** * Every app, in launcher-grid order (the launcher itself is first but hidden @@ -60,4 +61,5 @@ export const ALL_APPS: readonly AppDefinition[] = [ evenhubApp, glanceboardApp, settingsApp, + onboardingApp, ]; diff --git a/app/apps/onboarding/data-collection-page.ts b/app/apps/onboarding/data-collection-page.ts new file mode 100644 index 00000000..21e824fe --- /dev/null +++ b/app/apps/onboarding/data-collection-page.ts @@ -0,0 +1,75 @@ +import type { GrayImage } from "../../graphics/image"; +import { truncateText } from "../../graphics/textwrap"; +import { dataCollectionSetting, dataCollectionSummary, type DataCollectionLevel } from "../../ui/dashboard-settings"; +import type { InputEvent } from "../../ui/gestures"; +import { Menu, type MenuDrawArgs } from "../../ui/menu-core"; +import { LIST_ROW_TEXT_INSET, listRowHeight } from "../../ui/metrics"; +import { onboardingFont } from "./onboarding-fonts"; +import { drawPageHeading, PAGE_X, type OnboardingNav, type OnboardingPage } from "./onboarding-page"; + +const CONTENT_GAP = 10; +const BOTTOM_MARGIN = 8; +const LABEL_GAP = 24; + +/** None / Minimal / Full, each with a one-line summary; a tap saves the selected level. */ +export class DataCollectionPage implements OnboardingPage { + /** Width of the level-name column, measured each paint. */ + private labelColumnWidth = 0; + private readonly menu = new Menu({ + items: dataCollectionSetting.values, + wrap: false, + rowGap: 2, + highlight: { radius: 8 }, + getHeight: () => listRowHeight(onboardingFont("body")), + draw: (args) => this.drawRow(args), + }); + + enter(): void { + this.menu.select(dataCollectionSetting.values.indexOf(dataCollectionSetting.get())); + } + + paint(image: GrayImage, focused: boolean): void { + const top = drawPageHeading( + image, + "Data collection", + "Choose what Faceclaw may send its developers to help fix problems and improve the app. " + + "You can change this later in Settings > Privacy.", + 3, + ) + CONTENT_GAP; + const body = onboardingFont("body"); + this.labelColumnWidth = + Math.max(...dataCollectionSetting.values.map((level) => body.measureText(dataCollectionSetting.displayValue(level)))) + + LABEL_GAP; + this.menu.paint( + image, + { x: PAGE_X - 10, y: top, width: image.width - 2 * (PAGE_X - 10), height: image.height - top - BOTTOM_MARGIN }, + focused, + ); + } + + handleInput(event: InputEvent, nav: OnboardingNav): void { + switch (event.type) { + case "scroll-up": + case "scroll-down": + void this.menu.handleInput(event); + return; + case "click": { + const level = this.menu.selectedItem; + if (level !== null) dataCollectionSetting.set(level); + nav.next(); + return; + } + default: + return; + } + } + + private drawRow({ image, item: level, x, y, width, height, selected }: MenuDrawArgs): void { + const body = onboardingFont("body"); + const detail = onboardingFont("detail"); + image.drawText(body, x + 10, y + LIST_ROW_TEXT_INSET, dataCollectionSetting.displayValue(level), selected ? 255 : 200); + const summaryX = x + 10 + this.labelColumnWidth; + const summary = truncateText(detail, dataCollectionSummary(level), x + width - 10 - summaryX); + image.drawText(detail, summaryX, y + Math.round((height - detail.lineHeight) / 2), summary, selected ? 210 : 150); + } +} diff --git a/app/apps/onboarding/index.ts b/app/apps/onboarding/index.ts new file mode 100644 index 00000000..2210022a --- /dev/null +++ b/app/apps/onboarding/index.ts @@ -0,0 +1,17 @@ +import { type AppDefinition } from "../app-definition"; +import { createOnboardingAppWindow, ONBOARDING_SURFACE_ID, ONBOARDING_WINDOW_ID } from "./onboarding-app"; +import { ONBOARDING_APP_ID } from "./onboarding-progress"; + +/** + * First-run setup on the glasses: welcome, text size, data-collection + * preference. The connection controllers open it on their own when it is + * due (claimGlassesOnboardingAutoLaunch); the launcher entry reruns it. + */ +const onboardingApp: AppDefinition = { + appId: ONBOARDING_APP_ID, + title: "Onboarding", + icon: "sparkles", + launch: (ctx) => ctx.launchInProcessApp(ONBOARDING_WINDOW_ID, ONBOARDING_SURFACE_ID, createOnboardingAppWindow), +}; + +export default onboardingApp; diff --git a/app/apps/onboarding/onboarding-app.ts b/app/apps/onboarding/onboarding-app.ts new file mode 100644 index 00000000..52e77a0e --- /dev/null +++ b/app/apps/onboarding/onboarding-app.ts @@ -0,0 +1,98 @@ +import { GrayImage } from "../../graphics/image"; +import type { InputEvent } from "../../ui/gestures"; +import type { Layer, LayerActions, LayerContext } from "../../ui/layers"; +import { createInProcessWindow, type InProcessAppOptions, type InProcessWindow } from "../../ui/shell/in-process-window"; +import { shell } from "../../ui/shell/shell"; +import { findSoundEffect, playSoundEffect } from "../../ui/sound-effects"; +import { DataCollectionPage } from "./data-collection-page"; +import { markGlassesOnboardingFinished, ONBOARDING_APP_ID } from "./onboarding-progress"; +import type { OnboardingPage } from "./onboarding-page"; +import { TextSizePage } from "./text-size-page"; +import { WelcomePage } from "./welcome-page"; + +export const ONBOARDING_WINDOW_ID = "onboarding"; +export const ONBOARDING_SURFACE_ID = "window:onboarding"; + +/** + * The on-glasses onboarding: a fixed sequence of pages, opened automatically + * on the first connection after phone-side setup and after each upgrade + * (see onboarding-progress.ts), and from the launcher any time. Finishing + * the last page records this version as onboarded and closes the window; + * closing it early leaves onboarding due. + */ +export function createOnboardingAppWindow(options: InProcessAppOptions): InProcessWindow { + const pages: OnboardingPage[] = [new WelcomePage(), new TextSizePage(), new DataCollectionPage()]; + const app = createInProcessWindow({ + appId: ONBOARDING_APP_ID, + windowId: ONBOARDING_WINDOW_ID, + title: "Onboarding", + iconLetter: "On", + icon: "sparkles", + closeable: true, + actions: options.actions, + baseLayer: new OnboardingLayer(pages, () => { + markGlassesOnboardingFinished(); + shell.closeWindow(ONBOARDING_WINDOW_ID); + }), + submitFrame: options.submitFrame, + setSurfaceVisible: options.setSurfaceVisible, + removeSurface: options.removeSurface, + reconfigureSurface: options.reconfigureSurface, + onClosed: options.onClosed, + }); + playWelcomeSound(options.actions); + return app; +} + +/** The celebratory jingle that greets the welcome page (formerly played on the first connection). */ +function playWelcomeSound(actions: LayerActions): void { + const effect = findSoundEffect("questcomplete"); + if (!effect) return; + playSoundEffect( + effect, + (payload) => actions.playBuzzerSequence(payload), + (ms) => new Promise((resolve) => setTimeout(resolve, ms)), + ).catch((error) => console.warn(`onboarding welcome sound failed: ${error}`)); +} + +/** + * Hosts the current page. Double-click steps back a page, or leaves the app + * from the first one (the standard yield to the app switcher); every other + * gesture goes to the page. + */ +class OnboardingLayer implements Layer { + private index = 0; + + constructor( + private readonly pages: readonly OnboardingPage[], + private readonly finish: () => void, + ) { + pages[0]!.enter?.(); + } + + paint(ctx: LayerContext): GrayImage { + const { width, height } = ctx.stack.getBaseSize(); + const image = new GrayImage(width, height, 0); + this.pages[this.index]!.paint(image, ctx.stack.isFocused()); + return image; + } + + async handleInput(event: InputEvent): Promise { + if (event.type === "double-click") { + if (this.index === 0) shell.yieldFocusToSidebar(); + else this.show(this.index - 1); + return; + } + await this.pages[this.index]!.handleInput(event, { next: () => this.next() }); + } + + private next(): void { + if (this.index + 1 < this.pages.length) this.show(this.index + 1); + else this.finish(); + } + + private show(index: number): void { + this.index = index; + this.pages[index]!.enter?.(); + } +} diff --git a/app/apps/onboarding/onboarding-fonts.ts b/app/apps/onboarding/onboarding-fonts.ts new file mode 100644 index 00000000..e74ac400 --- /dev/null +++ b/app/apps/onboarding/onboarding-fonts.ts @@ -0,0 +1,38 @@ +/** + * The onboarding's own fonts: bundled Roboto at fixed sizes, deliberately + * not the user's UI font, so the pages are readable before (and while) the + * text size is being chosen. Bitmap Terminus stands in where TTF rendering + * is unavailable. + */ +import { getFont, getTerminusFont } from "../../graphics/bdffont"; +import type { UiFont } from "../../graphics/image"; +import { ensurePreinstalledFonts, installedFontPath } from "../../graphics/installed-fonts"; +import { TtfFont } from "../../graphics/ttf-font"; + +export type OnboardingFontRole = "hero" | "title" | "body" | "detail"; + +const ROLE_FONTS: Record UiFont }> = { + /** The welcome page's "Faceclaw". */ + hero: { file: "Roboto-Regular.ttf", size: 44, fallback: () => getFont("terminus32") }, + /** Page titles. */ + title: { file: "Roboto-Regular.ttf", size: 26, fallback: () => getFont("terminus24") }, + /** Prompts and choices. */ + body: { file: "Roboto-Regular.ttf", size: 20, fallback: () => getTerminusFont(20, false) ?? getFont("terminus16") }, + /** Explanations under titles and beside choices. */ + detail: { file: "Roboto-Regular.ttf", size: 16, fallback: () => getFont("terminus16") }, +}; + +let fontsEnsured = false; + +export function onboardingFont(role: OnboardingFontRole): UiFont { + if (!fontsEnsured) { + fontsEnsured = true; + try { + ensurePreinstalledFonts(); // onboarding may be the first thing to draw TTF text + } catch (error) { + console.warn(`onboarding font preinstall failed: ${error}`); + } + } + const spec = ROLE_FONTS[role]; + return TtfFont.load(installedFontPath(spec.file), spec.size) ?? spec.fallback(); +} diff --git a/app/apps/onboarding/onboarding-page.ts b/app/apps/onboarding/onboarding-page.ts new file mode 100644 index 00000000..175f21a5 --- /dev/null +++ b/app/apps/onboarding/onboarding-page.ts @@ -0,0 +1,48 @@ +import type { GrayImage } from "../../graphics/image"; +import { wrapText } from "../../graphics/textwrap"; +import type { InputEvent } from "../../ui/gestures"; +import { onboardingFont } from "./onboarding-fonts"; + +/** Page-to-flow navigation, handed to a page's input handler. */ +export type OnboardingNav = { + /** Go to the next page, or finish onboarding from the last one. */ + next: () => void; +}; + +/** + * One onboarding step. The flow owns the page list, back navigation + * (double-click) and finishing; a page paints itself into the window's + * viewport and handles every other gesture. + */ +export interface OnboardingPage { + /** The page became current, going forward or back. */ + enter?(): void; + paint(image: GrayImage, focused: boolean): void; + handleInput(event: InputEvent, nav: OnboardingNav): void | Promise; +} + +/** Left margin and title position shared by the pages (the UI-wide (18, 10) title spot). */ +export const PAGE_X = 18; +export const TITLE_Y = 10; + +/** + * Draw a page's title and its wrapped explanation (at most `maxLines` + * lines) in the onboarding fonts. Returns the y just below the explanation. + */ +export function drawPageHeading( + image: GrayImage, + title: string, + explanation: string, + maxLines = 2, +): number { + const titleFont = onboardingFont("title"); + const detailFont = onboardingFont("detail"); + image.drawText(titleFont, PAGE_X, TITLE_Y, title, 230); + let y = TITLE_Y + titleFont.lineHeight + 2; + const lines = wrapText(detailFont, explanation, image.width - 2 * PAGE_X).slice(0, maxLines); + for (const line of lines) { + image.drawText(detailFont, PAGE_X, y, line, 160); + y += detailFont.lineHeight; + } + return y; +} diff --git a/app/apps/onboarding/onboarding-progress.ts b/app/apps/onboarding/onboarding-progress.ts new file mode 100644 index 00000000..7c897ff8 --- /dev/null +++ b/app/apps/onboarding/onboarding-progress.ts @@ -0,0 +1,34 @@ +/** + * Whether the on-glasses onboarding is due: it is recorded as finished per + * Faceclaw version, so it runs on the first connection after phone-side + * setup and again after any upgrade. The key shares the phone onboarding's + * "onboarding." prefix so scripts/resetOnboarding.sh clears it too. + */ +import { getStringSetting, setStringSetting } from "../../native/settings-store"; +import { FACECLAW_VERSION } from "../../version"; + +export const ONBOARDING_APP_ID = "onboarding"; + +const FINISHED_VERSION_KEY = "onboarding.glassesFinishedVersion"; + +export function isGlassesOnboardingDue(): boolean { + return getStringSetting(FINISHED_VERSION_KEY, "") !== FACECLAW_VERSION; +} + +export function markGlassesOnboardingFinished(): void { + setStringSetting(FINISHED_VERSION_KEY, FACECLAW_VERSION); +} + +let autoLaunchChecked = false; + +/** + * Asked by the connection controllers on each rendered frame (the session + * is warm by then, so the onboarding's welcome jingle won't be dropped). + * True at most once per run, and only when onboarding is due: closing it + * unfinished brings it back on the next app start, not on every reconnect. + */ +export function claimGlassesOnboardingAutoLaunch(): boolean { + if (autoLaunchChecked) return false; + autoLaunchChecked = true; + return isGlassesOnboardingDue(); +} diff --git a/app/apps/onboarding/text-size-page.ts b/app/apps/onboarding/text-size-page.ts new file mode 100644 index 00000000..7694aa9d --- /dev/null +++ b/app/apps/onboarding/text-size-page.ts @@ -0,0 +1,159 @@ +import { GrayImage, type UiFont } from "../../graphics/image"; +import { installedFontPath } from "../../graphics/installed-fonts"; +import { wrapText } from "../../graphics/textwrap"; +import { TtfFont } from "../../graphics/ttf-font"; +import { + fontSelectionLabel, + getDefaultSmallFont, + getUiFontSelection, + setUiFontSelection, + uiFontSizeAllowed, +} from "../../graphics/ui-fonts"; +import { FONT_SIZE_CHOICES } from "../../ui/font-picker"; +import type { InputEvent } from "../../ui/gestures"; +import { Menu, MENU_HIGHLIGHT_FILL, MENU_HIGHLIGHT_STROKE, type MenuBox, type MenuDrawArgs } from "../../ui/menu-core"; +import { LIST_ROW_TEXT_INSET, listRowHeight } from "../../ui/metrics"; +import { onboardingFont } from "./onboarding-fonts"; +import { drawPageHeading, PAGE_X, type OnboardingNav, type OnboardingPage } from "./onboarding-page"; + +const CONTENT_GAP = 10; +const BOTTOM_MARGIN = 8; +const SIZE_COLUMN_WIDTH = 84; +const COLUMN_GAP = 12; +const PREVIEW_PADDING = 10; +const ROW_GAP = 2; +const PREVIEW_TEXT = "This is how text will look on your glasses."; +/** Drawn while they fit, so smaller sizes visibly show more rows. */ +const PREVIEW_ROWS = ["Timers", "Weather", "Music", "Settings", "Files"]; + +/** The UI font's face, as far as this page is concerned: resizable (TTF) or not (bitmap). */ +type Face = + | { kind: "sized"; file: string; path: string; sizes: number[] } + | { kind: "fixed"; label: string }; + +/** + * The UI font's size, over a preview of list rows and body text in the + * chosen size. The face and weight stay as they are (they live in the + * Settings font picker); a bitmap face has only one size, so the page just + * says so. The size is saved on tap, not while scrolling. + */ +export class TextSizePage implements OnboardingPage { + private face: Face = { kind: "fixed", label: "Terminus" }; + private readonly sizeMenu = new Menu({ + wrap: false, + rowGap: ROW_GAP, + highlight: { radius: 8 }, + getHeight: () => listRowHeight(onboardingFont("body")), + draw: (args) => this.drawSizeRow(args), + }); + + enter(): void { + // Re-read on every visit: the face may have changed in Settings meanwhile. + const selection = getUiFontSelection(); + if (selection.kind === "ttf") { + const path = installedFontPath(selection.file); + const sizes = FONT_SIZE_CHOICES.filter((size) => uiFontSizeAllowed(path, size)); + if (sizes.length) { + this.face = { kind: "sized", file: selection.file, path, sizes }; + this.sizeMenu.setItems(sizes, nearestIndex(sizes, selection.size)); + return; + } + } + // An unloadable TTF selection renders as Terminus, so call it that. + this.face = { kind: "fixed", label: selection.kind === "bitmap" ? fontSelectionLabel(selection) : "Terminus" }; + } + + paint(image: GrayImage, focused: boolean): void { + if (this.face.kind === "fixed") { + const top = drawPageHeading( + image, + "Text size", + `Your UI font, ${this.face.label}, comes in one size. To choose a size, pick a different font in ` + + "Settings > Customization. Tap to continue.", + 3, + ) + CONTENT_GAP; + drawPreview(image, getDefaultSmallFont(), { + x: PAGE_X - 10, + y: top, + width: image.width - 2 * (PAGE_X - 10), + height: image.height - top - BOTTOM_MARGIN, + }); + return; + } + const top = drawPageHeading( + image, + "Text size", + "Swipe to choose a size, then tap to continue. The typeface and weight can be changed in Settings.", + ) + CONTENT_GAP; + const height = image.height - top - BOTTOM_MARGIN; + const menuBox = { x: PAGE_X - 10, y: top, width: SIZE_COLUMN_WIDTH, height }; + this.sizeMenu.paint(image, menuBox, focused); + const previewX = menuBox.x + menuBox.width + COLUMN_GAP; + const size = this.sizeMenu.selectedItem; + const font = (size !== null ? TtfFont.load(this.face.path, size) : null) ?? getDefaultSmallFont(); + drawPreview(image, font, { x: previewX, y: top, width: image.width - (PAGE_X - 10) - previewX, height }); + } + + handleInput(event: InputEvent, nav: OnboardingNav): void { + switch (event.type) { + case "scroll-up": + case "scroll-down": + if (this.face.kind === "sized") void this.sizeMenu.handleInput(event); + return; + case "click": + this.save(); + nav.next(); + return; + default: + return; + } + } + + private save(): void { + const size = this.sizeMenu.selectedItem; + if (this.face.kind !== "sized" || size === null) return; + const current = getUiFontSelection(); + if (current.kind === "ttf" && current.file === this.face.file && current.size === size) return; + setUiFontSelection({ kind: "ttf", file: this.face.file, size }); + } + + private drawSizeRow({ image, item: size, x, y, selected }: MenuDrawArgs): void { + image.drawText(onboardingFont("body"), x + 10, y + LIST_ROW_TEXT_INSET, `${size} px`, selected ? 255 : 190); + } +} + +/** A framed sample in `font`: a sentence, then menu rows with the first one selected, as many as fit. */ +function drawPreview(image: GrayImage, font: UiFont, box: MenuBox): void { + image.drawRoundedRect(box.x, box.y, box.width, box.height, 60, 8); + const left = box.x + PREVIEW_PADDING; + const width = box.width - 2 * PREVIEW_PADDING; + const bottom = box.y + box.height - PREVIEW_PADDING; + let y = box.y + PREVIEW_PADDING; + for (const line of wrapText(font, PREVIEW_TEXT, width)) { + if (y + font.lineHeight > bottom) return; + image.drawText(font, left, y, line, 220); + y += font.lineHeight; + } + y += PREVIEW_PADDING; + const rowHeight = listRowHeight(font); + for (let index = 0; index < PREVIEW_ROWS.length; index++) { + if (y + rowHeight - ROW_GAP > bottom) return; + const label = PREVIEW_ROWS[index]!; + if (index === 0) { + const row = new GrayImage(width, rowHeight - ROW_GAP, 0); + row.drawText(font, 10, LIST_ROW_TEXT_INSET, label, 255); + image.drawMenuSelection(row, left, y, MENU_HIGHLIGHT_FILL, MENU_HIGHLIGHT_STROKE, 8, 0); + } else { + image.drawText(font, left + 10, y + LIST_ROW_TEXT_INSET, label, 200); + } + y += rowHeight; + } +} + +function nearestIndex(values: readonly number[], target: number): number { + let best = 0; + for (let index = 1; index < values.length; index++) { + if (Math.abs(values[index]! - target) < Math.abs(values[best]! - target)) best = index; + } + return best; +} diff --git a/app/apps/onboarding/welcome-page.ts b/app/apps/onboarding/welcome-page.ts new file mode 100644 index 00000000..b14005b3 --- /dev/null +++ b/app/apps/onboarding/welcome-page.ts @@ -0,0 +1,51 @@ +import type { GrayImage, UiFont } from "../../graphics/image"; +import { getFullLogo } from "../../graphics/logo"; +import { wrapText } from "../../graphics/textwrap"; +import type { InputEvent } from "../../ui/gestures"; +import { FACECLAW_VERSION } from "../../version"; +import { onboardingFont } from "./onboarding-fonts"; +import { PAGE_X, type OnboardingNav, type OnboardingPage } from "./onboarding-page"; + +const LOGO_MAX_HEIGHT = 180; +const LOGO_MARGIN = 12; +const LOGO_TEXT_GAP = 28; +const PROMPT_GAP = 22; +const PROMPT = "Tap the ring or touchpad to continue"; + +type TextLine = { font: UiFont; text: string; value: number; spaceBefore: number }; + +/** The splash: logo beside the name, version and how to go on, centred as one group. */ +export class WelcomePage implements OnboardingPage { + paint(image: GrayImage): void { + const { width, height } = image; + const logo = getFullLogo(Math.min(LOGO_MAX_HEIGHT, height - 2 * LOGO_MARGIN)); + const logoWidth = logo ? logo.width + LOGO_TEXT_GAP : 0; + const body = onboardingFont("body"); + const lines: TextLine[] = [ + { font: onboardingFont("hero"), text: "Faceclaw", value: 240, spaceBefore: 0 }, + { font: body, text: `Version ${FACECLAW_VERSION}`, value: 150, spaceBefore: 0 }, + ...wrapText(body, PROMPT, width - 2 * PAGE_X - logoWidth).map((text, index) => ({ + font: body, + text, + value: 215, + spaceBefore: index === 0 ? PROMPT_GAP : 0, + })), + ]; + const textWidth = Math.max(...lines.map((line) => line.font.measureText(line.text))); + const textHeight = lines.reduce((total, line) => total + line.spaceBefore + line.font.lineHeight, 0); + const left = Math.max(PAGE_X, Math.round((width - logoWidth - textWidth) / 2)); + if (logo) { + image.bitBlt(logo, left, Math.round((height - logo.height) / 2), { transparentZero: true }); + } + let y = Math.round((height - textHeight) / 2); + for (const line of lines) { + y += line.spaceBefore; + image.drawText(line.font, left + logoWidth, y, line.text, line.value); + y += line.font.lineHeight; + } + } + + handleInput(event: InputEvent, nav: OnboardingNav): void { + if (event.type === "click") nav.next(); + } +} diff --git a/app/bootstrap.android.ts b/app/bootstrap.android.ts index 0e42f85c..f5734a2f 100644 --- a/app/bootstrap.android.ts +++ b/app/bootstrap.android.ts @@ -6,5 +6,10 @@ import { registerPhoneRotation } from './native/phone-rotation' installNativeUserAgent() registerShareIntentHandler() registerPhoneRotation() +// Opt-in analytics (app/analytics/), started once the app is up rather than +// loading its imports on the boot path. +Application.on(Application.launchEvent, () => { + setTimeout(() => require('./analytics/analytics-sources').startAppAnalytics(), 0) +}) Application.run({ moduleName: 'app-root' }) diff --git a/app/bootstrap.ios.ts b/app/bootstrap.ios.ts index 7ef6831e..14195c12 100644 --- a/app/bootstrap.ios.ts +++ b/app/bootstrap.ios.ts @@ -4,6 +4,10 @@ declare const FaceclawConfigPort: any // Apply transferred preferences before settings getters or app workers load. FaceclawConfigPort.processPendingRequest() require('./phone-ui/onboarding-register.ios') +// Opt-in analytics (app/analytics/), started once the app is up. +Application.on(Application.launchEvent, () => { + setTimeout(() => require('./analytics/analytics-sources').startAppAnalytics(), 0) +}) const { hasCompletedOnboarding } = require('./phone-ui/onboarding-state') as typeof import('./phone-ui/onboarding-state') Application.run({ create: () => { const frame = new Frame() diff --git a/app/g2/dashboard-controller.ts b/app/g2/dashboard-controller.ts index bfde6f13..3bee2934 100644 --- a/app/g2/dashboard-controller.ts +++ b/app/g2/dashboard-controller.ts @@ -45,10 +45,10 @@ const MIRROR_TOUCH_GESTURES: Record, WearRemoteI "swipe-left": "swipe-left", "swipe-right": "swipe-right", }; -import { findSoundEffect, playSoundEffect } from "../ui/sound-effects"; import { GlanceHost } from "./glance-host"; import { type GlanceEvent } from "./glance-state"; -import { isPreviewOnlyMode, isWelcomeSoundPending, setWelcomeSoundPending } from "../phone-ui/onboarding-state"; +import { isPreviewOnlyMode } from "../phone-ui/onboarding-state"; +import { claimGlassesOnboardingAutoLaunch, ONBOARDING_APP_ID } from "../apps/onboarding/onboarding-progress"; import { beginRenderPass, endRenderPass } from "../util/render-freshness"; import { voiceControlBridge } from "../native/voice-control"; import { G2_LENS_HEIGHT, G2_LENS_WIDTH, GrayImage } from "../graphics/image"; @@ -278,9 +278,6 @@ class DashboardController { // drop-off right after a low reading can be explained as a flat battery. private lastHeadsetBattery: number | null = null; private readonly listeners = new Set(); - // Set at connect time from the persisted flag; the one-time post-onboarding - // welcome sound plays on the first rendered frame (proof the session is warm). - private welcomeSoundArmed = false; private communicator: FaceclawCommunicatorBridge | null = null; // Headless stand-in for the compositor when no glasses are paired @@ -1413,7 +1410,6 @@ class DashboardController { this.teardownPreviewDisplay(); this.lastInput = "waiting..."; this.lastSys = "none yet"; - this.welcomeSoundArmed = isWelcomeSoundPending(); this.firmwareWarningMessage = ""; this.glassesWorn = null; this.wakeAfterChargingReconnect = false; @@ -1580,11 +1576,12 @@ class DashboardController { // parked by the previous session (or by an EvenHub suspend) resumes. this.resumeVoiceCapture(); // A rendered frame means the session is warmed up (fixedLayoutCreated), - // so the buzzer won't be dropped. Play the one-time welcome sound now. - if (this.welcomeSoundArmed) { - this.welcomeSoundArmed = false; - setWelcomeSoundPending(false); - void this.playWelcomeSound(); + // so the onboarding's welcome jingle won't be dropped. Open the + // on-glasses onboarding if this version hasn't been through it. + if (claimGlassesOnboardingAutoLaunch()) { + this.launchApp(ONBOARDING_APP_ID).catch((error) => { + this.appendLog(`onboarding launch failed: ${this.formatError(error)}`); + }); } } }); @@ -2741,21 +2738,6 @@ class DashboardController { await this.communicator.playBuzzerSequence(payload); } - /** One-time celebratory jingle on the first connection after onboarding. */ - private async playWelcomeSound(): Promise { - const effect = findSoundEffect("questcomplete"); - if (!effect) return; - try { - await playSoundEffect( - effect, - (payload) => this.playBuzzerSequence(payload), - (ms) => new Promise((resolve) => setTimeout(resolve, ms)), - ); - } catch (error) { - this.appendLog(`welcome sound failed: ${this.formatError(error)}`); - } - } - private clearDashboardTimer(): void { this.cancelEvenHubSuspendTimer(); if (this.shellRefreshTimer) { diff --git a/app/g2/ios-preview-controller.ts b/app/g2/ios-preview-controller.ts index ac4e4971..feace883 100644 --- a/app/g2/ios-preview-controller.ts +++ b/app/g2/ios-preview-controller.ts @@ -48,8 +48,7 @@ import { DISPLAY_MODE_VALUES, displayModeLabel, displayModeSetting, onAnySetting previewColorSetting, lockScreenEnabledSetting, getBrightnessPreferences, getStringSettingById, nightscoutSiteUrlSetting, nightscoutApiTokenSetting } from '../ui/dashboard-settings' import type { PhoneGesture } from '../phone-ui/phone-gestures' -import { isWelcomeSoundPending, setWelcomeSoundPending } from '../phone-ui/onboarding-state' -import { findSoundEffect, playSoundEffect } from '../ui/sound-effects' +import { claimGlassesOnboardingAutoLaunch, ONBOARDING_APP_ID } from '../apps/onboarding/onboarding-progress' const SHELL_SURFACE_ID = 'shell' const SHELL_SURFACE_Z_ORDER = 1 @@ -681,7 +680,7 @@ export class IosPreviewController { private emitState(): void { if (this.state.phase !== 'connected') resetRingInputFilter() this.pushBrightness() - this.maybePlayWelcomeSound(this.state) + this.maybeLaunchOnboarding(this.state) if (this.state.phase !== 'connected' && this.state.phase !== 'connecting') this.glassesWorn = null if (this.state.phase !== 'connected') iosVoiceInput.handleSessionEnded() shell.setBatteryLevels({ headset: this.state.battery, headsetCharging: this.state.charging }) @@ -770,7 +769,7 @@ export class IosPreviewController { if (this.communicator !== communicator) return this.state = { ...this.state, frames: this.state.frames + 1 } this.onActivity() - this.maybePlayWelcomeSound(this.state) + this.maybeLaunchOnboarding(this.state) if (this.active) this.onConnectionState({ ...this.state }) this.schedulePreviewUpdate() }), @@ -878,16 +877,13 @@ export class IosPreviewController { this.glance.reset() await communicator.close().catch(error => this.logBluetooth(`Close: ${String(error)}`)) } - private maybePlayWelcomeSound(state: SessionState): void { + private maybeLaunchOnboarding(state: SessionState): void { const firstNewFrame = state.frames > this.acknowledgedFrames this.acknowledgedFrames = state.frames - // Match Android: wait for an acknowledged frame before consuming the jingle. - if (!firstNewFrame || state.phase !== 'connected' || !isWelcomeSoundPending()) return - setWelcomeSoundPending(false) - const effect = findSoundEffect('questcomplete') - if (effect) void playSoundEffect(effect, payload => this.actions.playBuzzerSequence(payload), - ms => new Promise(resolve => setTimeout(resolve, ms))) - .catch(error => this.logBluetooth(`Welcome sound failed: ${error}`)) + // Match Android: wait for an acknowledged frame (a warm session, so the + // onboarding's welcome jingle isn't dropped) before opening it. + if (!firstNewFrame || state.phase !== 'connected' || !claimGlassesOnboardingAutoLaunch()) return + void this.launchApp(ONBOARDING_APP_ID) } startVoiceInput(): void { if (!this.glassesLocked) shell.startVoiceInput() } private async prepareVoiceCapture(): Promise { diff --git a/app/g2/wear-remote.ts b/app/g2/wear-remote.ts index 84e04dee..492fb9d8 100644 --- a/app/g2/wear-remote.ts +++ b/app/g2/wear-remote.ts @@ -23,6 +23,7 @@ * Transport is app/native/wear-bridge.ts (Java FaceclawWearBridge); the * message shapes are documented in wear/PROTOCOL.md. */ +import { flagAnalyticsEvent } from "../analytics/analytics"; import { type AppDefinition } from "../apps/app-definition"; import { getInstalledEvenHubApps, installedEvenHubAppId } from "../apps/evenhub/installed-apps"; import { WEAR_PATHS, wearBridge, type WearMessage } from "../native/wear-bridge"; @@ -167,6 +168,7 @@ export class WearRemote { // with it (no placeholder). if (changed) this.watchBatteryPollsUnanswered = 0; if (connection.reachable) { + flagAnalyticsEvent("minimal", "device.wear.reachable"); this.publishNow(true); this.pollWatchBattery(true); } else if (changed) { @@ -326,6 +328,7 @@ export class WearRemote { return; } + flagAnalyticsEvent("minimal", "device.wear.used"); switch (message.path) { case WEAR_PATHS.input: await this.handleInput(message.payload, ack); diff --git a/app/graphics/icons.ts b/app/graphics/icons.ts index c18b69ae..f7ab0fa8 100644 --- a/app/graphics/icons.ts +++ b/app/graphics/icons.ts @@ -76,6 +76,8 @@ export const ICON_SVGS = { '', wrench: '', + sparkles: + '', settings: '', mic: diff --git a/app/graphics/imagefile.ts b/app/graphics/imagefile.ts index 2acf9ef0..d2479e36 100644 --- a/app/graphics/imagefile.ts +++ b/app/graphics/imagefile.ts @@ -6,7 +6,12 @@ declare const interop: any; const UPNG = require("upng-js"); -export function loadPngAsGrayImage(path: string): GrayImage { +/** + * Decode a PNG to grayscale, premultiplied by alpha so transparency reads as + * black. With `invert`, the PNG is dark art on a light or transparent ground + * (e.g. the phone-side logo) and its ink is drawn white instead. + */ +export function loadPngAsGrayImage(path: string, options: { invert?: boolean } = {}): GrayImage { const file = resolveFile(path); const raw = file.readSync(); const pngBuffer = toArrayBuffer(raw); @@ -25,7 +30,8 @@ export function loadPngAsGrayImage(path: string): GrayImage { const g = rgba[offset + 1] ?? 0; const b = rgba[offset + 2] ?? 0; const a = (rgba[offset + 3] ?? 0) / 255; - const gray = Math.round((0.2126 * r + 0.7152 * g + 0.0722 * b) * a); + const luminance = 0.2126 * r + 0.7152 * g + 0.0722 * b; + const gray = Math.round((options.invert ? 255 - luminance : luminance) * a); image.pixels[y * decoded.width + x] = gray; } } diff --git a/app/graphics/installed-fonts.ts b/app/graphics/installed-fonts.ts index 8eec0c04..afba6f49 100644 --- a/app/graphics/installed-fonts.ts +++ b/app/graphics/installed-fonts.ts @@ -44,6 +44,11 @@ export type InstalledFont = { monospace: boolean; }; +/** Whether `fileName` is one of the fonts the app ships, rather than one the user installed. */ +export function isPreinstalledFont(fileName: string): boolean { + return (PREINSTALLED_FONT_FILES as readonly string[]).includes(fileName); +} + /** The app-internal fonts directory (created on first use). */ export function installedFontsDir(): string { return knownFolders.documents().getFolder("fonts").path; diff --git a/app/graphics/logo.ts b/app/graphics/logo.ts index 8515515f..c6932348 100644 --- a/app/graphics/logo.ts +++ b/app/graphics/logo.ts @@ -14,3 +14,57 @@ export function getDashboardLogo(): GrayImage | null { } return cachedDashboardLogo; } + +const FULL_LOGO_PATH = "images/faceclaw-logo.png"; +let fullLogoSource: GrayImage | null | undefined; +const scaledFullLogos = new Map(); + +/** + * The full Faceclaw logo (the lobster over the smiley face), white on black, + * scaled to `height` pixels tall for splash screens. The source is the phone + * UI's black-on-transparent PNG, inverted, and area-averaged down so the + * edges stay antialiased. + */ +export function getFullLogo(height: number): GrayImage | null { + const targetHeight = Math.max(1, Math.round(height)); + const cached = scaledFullLogos.get(targetHeight); + if (cached) return cached; + if (fullLogoSource === undefined) { + try { + fullLogoSource = loadPngAsGrayImage(FULL_LOGO_PATH, { invert: true }); + } catch (error) { + console.warn(`Could not load ${FULL_LOGO_PATH}: ${error}`); + fullLogoSource = null; + } + } + if (!fullLogoSource) return null; + const scale = Math.min(1, targetHeight / fullLogoSource.height); + const scaled = downscaleArea( + fullLogoSource, + Math.max(1, Math.round(fullLogoSource.width * scale)), + Math.max(1, Math.round(fullLogoSource.height * scale)), + ); + scaledFullLogos.set(targetHeight, scaled); + return scaled; +} + +/** Box-filter downscale: each output pixel averages the source pixels it covers. */ +function downscaleArea(source: GrayImage, width: number, height: number): GrayImage { + if (width === source.width && height === source.height) return source; + const output = new GrayImage(width, height, 0); + for (let y = 0; y < height; y++) { + const y0 = Math.floor((y * source.height) / height); + const y1 = Math.max(y0 + 1, Math.floor(((y + 1) * source.height) / height)); + for (let x = 0; x < width; x++) { + const x0 = Math.floor((x * source.width) / width); + const x1 = Math.max(x0 + 1, Math.floor(((x + 1) * source.width) / width)); + let sum = 0; + for (let sy = y0; sy < y1; sy++) { + const row = sy * source.width; + for (let sx = x0; sx < x1; sx++) sum += source.pixels[row + sx]!; + } + output.pixels[y * width + x] = Math.round(sum / ((y1 - y0) * (x1 - x0))); + } + } + return output; +} diff --git a/app/native/build-info.ios.ts b/app/native/build-info.ios.ts new file mode 100644 index 00000000..d8d7ddef --- /dev/null +++ b/app/native/build-info.ios.ts @@ -0,0 +1,19 @@ +import type { BuildKind } from './build-info' + +declare const NSBundle: any +declare const NSProcessInfo: any + +let cached: BuildKind | null = null + +/** + * App Store (and TestFlight) builds carry no provisioning profile; anything + * installed from Xcode or as an ad hoc build does. Simulator builds have none + * either, so they're recognized by the simulator's environment. + */ +export function buildKind(): BuildKind { + if (cached) return cached + if (NSProcessInfo.processInfo.environment.objectForKey('SIMULATOR_DEVICE_NAME')) cached = 'debug' + else if (NSBundle.mainBundle.pathForResourceOfType('embedded', 'mobileprovision')) cached = 'self-built' + else cached = 'official' + return cached +} diff --git a/app/native/build-info.ts b/app/native/build-info.ts new file mode 100644 index 00000000..cd35d5cc --- /dev/null +++ b/app/native/build-info.ts @@ -0,0 +1,54 @@ +/** + * Which kind of build this is, for analytics: an official release, or one + * compiled by somebody else. Official releases are signed with the key + * scripts/release.sh uses; anything else was built by whoever installed it. + */ +import { Utils } from "@nativescript/core"; + +declare const android: any; +declare const java: any; + +/** + * `debug` is a debuggable build (build.sh / build_and_run.sh); `self-built` + * is a release build signed with someone else's key. + */ +export type BuildKind = "official" | "self-built" | "debug" | "unknown"; + +/** SHA-256 of the release signing certificate (`apksigner verify --print-certs dist/Faceclaw-*.apk`). */ +const OFFICIAL_SIGNING_CERT_SHA256 = "c1efe42d74f3fc4e9a13bcfc8c99e018344a55525e5b300fa960c89431e382ad"; + +let cached: BuildKind | null = null; + +export function buildKind(): BuildKind { + cached ??= detectBuildKind(); + return cached; +} + +function detectBuildKind(): BuildKind { + try { + const context = Utils.android.getApplicationContext(); + const packageManager = context.getPackageManager(); + const PackageManager = android.content.pm.PackageManager; + const signatures = + android.os.Build.VERSION.SDK_INT >= 28 + ? packageManager + .getPackageInfo(context.getPackageName(), PackageManager.GET_SIGNING_CERTIFICATES) + .signingInfo.getApkContentsSigners() + : packageManager.getPackageInfo(context.getPackageName(), PackageManager.GET_SIGNATURES).signatures; + for (let index = 0; index < signatures.length; index++) { + const digest = java.security.MessageDigest.getInstance("SHA-256").digest(signatures[index].toByteArray()); + if (hex(digest) === OFFICIAL_SIGNING_CERT_SHA256) return "official"; + } + const debuggable = (context.getApplicationInfo().flags & android.content.pm.ApplicationInfo.FLAG_DEBUGGABLE) !== 0; + return debuggable ? "debug" : "self-built"; + } catch (error) { + console.warn(`build-info: could not read the signing certificate: ${error}`); + return "unknown"; + } +} + +function hex(bytes: any): string { + let text = ""; + for (let index = 0; index < bytes.length; index++) text += ((bytes[index] & 0xff) + 0x100).toString(16).slice(1); + return text; +} diff --git a/app/native/connection-counters.ios.ts b/app/native/connection-counters.ios.ts new file mode 100644 index 00000000..786ae3ab --- /dev/null +++ b/app/native/connection-counters.ios.ts @@ -0,0 +1,10 @@ +declare const FaceclawKitConnectionCounters: any + +export function drainConnectionCounters(): Record { + const counts: Record = {} + const parsed = JSON.parse(String(FaceclawKitConnectionCounters.shared.drain())) as Record + for (const [name, count] of Object.entries(parsed)) { + if (typeof count === 'number' && count > 0) counts[name] = count + } + return counts +} diff --git a/app/native/connection-counters.ts b/app/native/connection-counters.ts new file mode 100644 index 00000000..3863496d --- /dev/null +++ b/app/native/connection-counters.ts @@ -0,0 +1,14 @@ +declare const com: any; + +/** + * Connection-reliability event counts since the last call, from the shared + * Kotlin session core (ConnectionCounters.kt), which keeps them process-wide. + */ +export function drainConnectionCounters(): Record { + const counts: Record = {}; + const parsed = JSON.parse(String(com.faceclaw.app.ConnectionCounters.drain())) as Record; + for (const [name, count] of Object.entries(parsed)) { + if (typeof count === "number" && count > 0) counts[name] = count; + } + return counts; +} diff --git a/app/phone-ui/onboarding-state.ts b/app/phone-ui/onboarding-state.ts index 451a5ef4..9f478373 100644 --- a/app/phone-ui/onboarding-state.ts +++ b/app/phone-ui/onboarding-state.ts @@ -2,32 +2,17 @@ import { ApplicationSettings } from "@nativescript/core"; const ONBOARDING_COMPLETE_KEY = "onboarding.complete"; const PREVIEW_ONLY_KEY = "onboarding.previewOnly"; -const WELCOME_SOUND_PENDING_KEY = "onboarding.welcomeSoundPending"; export function hasCompletedOnboarding(): boolean { return ApplicationSettings.getBoolean(ONBOARDING_COMPLETE_KEY, false); } -export function setOnboardingCompleted(completed: boolean): void { - const wasCompleted = hasCompletedOnboarding(); - ApplicationSettings.setBoolean(ONBOARDING_COMPLETE_KEY, completed); - // Arm the one-time welcome sound on the first-ever completion (not on the - // idempotent re-completions that happen when installing from the main menu). - if (completed && !wasCompleted) { - setWelcomeSoundPending(true); - } -} - /** - * True when onboarding just completed and the celebratory sound hasn't played - * yet. Consumed (and cleared) on the first successful glasses connection. + * Phone-side onboarding. The on-glasses onboarding that follows it on the + * first connection is tracked separately (app/apps/onboarding/). */ -export function isWelcomeSoundPending(): boolean { - return ApplicationSettings.getBoolean(WELCOME_SOUND_PENDING_KEY, false); -} - -export function setWelcomeSoundPending(pending: boolean): void { - ApplicationSettings.setBoolean(WELCOME_SOUND_PENDING_KEY, pending); +export function setOnboardingCompleted(completed: boolean): void { + ApplicationSettings.setBoolean(ONBOARDING_COMPLETE_KEY, completed); } /** diff --git a/app/ui/dashboard-settings.ts b/app/ui/dashboard-settings.ts index a8fb4300..8c8ce4df 100644 --- a/app/ui/dashboard-settings.ts +++ b/app/ui/dashboard-settings.ts @@ -23,6 +23,7 @@ import { MENU_ANIMATION_KEY } from "./menu-animation-pref"; import { LIST_ROW_TEXT_INSET, lineStep } from "./metrics"; import { Layer, type LayerContext } from "./layers"; import { GrayImage } from "~/graphics/image"; +import type { DataCollectionLevel } from "../analytics/analytics-store"; export type NightscoutSettings = { siteUrl: string; @@ -47,6 +48,11 @@ type ConfigSettingOptions = { formatValue?: (value: TValue) => string; /** Extended description shown in the Settings panel when the row is selected. */ description?: string; + /** + * Boolean and enum settings only take fixed values, so Full analytics + * reports them (fixedChoiceSettingValues); false keeps this one out. + */ + reportInAnalytics?: boolean; }; // Fired after any setting changes, in any isolate (storage lives in the Java @@ -74,6 +80,21 @@ onSettingsStoreChanged(() => { }, 0); }); +// Boolean and enum settings by storage key, for fixedChoiceSettingValues. +// Settings built repeatedly (per-app or per-slot) just replace themselves. +const fixedChoiceSettings = new Map | ConfigSetting>(); + +/** + * The current value of every boolean and enum setting this isolate has + * loaded, keyed by storage key: what Full analytics reports as settings. + * Free-text settings never appear. + */ +export function fixedChoiceSettingValues(): Record { + const values: Record = {}; + for (const [storageKey, setting] of fixedChoiceSettings) values[storageKey] = setting.get(); + return values; +} + export abstract class ConfigSetting { readonly id: TId; readonly label: string; @@ -104,6 +125,7 @@ export class ConfigSettingBoolean extends ConfigSet // Widens ConfigSetting's protected constructor. public constructor(options: ConfigSettingOptions) { super(options); + if (options.reportInAnalytics !== false) fixedChoiceSettings.set(options.storageKey, this); } get(): boolean { @@ -134,6 +156,7 @@ export class ConfigSettingEnum) { super(options); + if (options.reportInAnalytics !== false) fixedChoiceSettings.set(options.storageKey, this); this.values = options.values; this.disabledPredicate = options.isDisabled ?? (() => false); if (options.normalize) { @@ -660,6 +683,45 @@ export const navigateVerticalPositionSetting = appVerticalPositionSetting("navig export const terminalDisplayModeSetting = appDisplayModeSetting("terminal", "default"); export const terminalVerticalPositionSetting = appVerticalPositionSetting("terminal"); +export type { DataCollectionLevel }; + +/** The data-collection setting's key, for observers (app/analytics/analytics.ts). */ +export const DATA_COLLECTION_KEY = "privacy.dataCollection"; + +const DATA_COLLECTION_LABELS: Record = { + none: "None", + minimal: "Minimal", + full: "Full", +}; + +// What each level collects is set out in app/analytics/analytics-store.ts and +// the privacy policy (PRIVACY); keep these in step with both. +const DATA_COLLECTION_SUMMARIES: Record = { + none: "Send nothing", + minimal: "Version, devices, connection reliability", + full: "Also settings and API-key presence", +}; + +/** One-line summary of what a data-collection level sends (onboarding, settings). */ +export function dataCollectionSummary(level: DataCollectionLevel): string { + return DATA_COLLECTION_SUMMARIES[level]; +} + +/** Chosen in the on-glasses onboarding; changeable in Settings > Privacy. */ +export const dataCollectionSetting = new ConfigSettingEnum({ + id: "data-collection", + label: "Data collection", + storageKey: DATA_COLLECTION_KEY, + defaultValue: "none", + values: ["none", "minimal", "full"], + formatValue: (value) => DATA_COLLECTION_LABELS[value], + description: + "Anonymous statistics Faceclaw may send its developers once a day, to help fix problems and improve the " + + "app. None: send nothing, and keep nothing on the phone. Minimal: the app version, which devices are " + + "paired and in use, and how reliable the connection to them is. Full: also settings chosen from fixed " + + "options, and which kinds of API key are set (never the keys themselves).", +}); + export const voiceControlEnabledSetting = new ConfigSettingBoolean({ id: "voice-control-enabled", label: "Enable", diff --git a/app/ui/dashboard/settings-menus.ts b/app/ui/dashboard/settings-menus.ts index 99dc6a6d..945470ab 100644 --- a/app/ui/dashboard/settings-menus.ts +++ b/app/ui/dashboard/settings-menus.ts @@ -45,6 +45,7 @@ import { autoBrightnessMinSetting, autoBrightnessMaxSetting, autoBrightnessCurveSetting, + dataCollectionSetting, glassesBatteryVisibilitySetting, phoneBatteryVisibilitySetting, ringBatteryVisibilitySetting, @@ -191,6 +192,13 @@ function settingsSections(): SettingsSection[] { toggleSettingMenuItem(showBleBandwidthSetting), ], }, + { + label: "Privacy", + items: [ + // First chosen in the on-glasses onboarding (app/apps/onboarding/). + enumSettingMenuItem(dataCollectionSetting), + ], + }, { label: "About", // The version/license blurb (renderDetail) draws above the bundled diff --git a/app/ui/font-picker.ts b/app/ui/font-picker.ts index eda1c8f5..f9fdac7c 100644 --- a/app/ui/font-picker.ts +++ b/app/ui/font-picker.ts @@ -31,7 +31,8 @@ import { Menu, type MenuDrawArgs } from "./menu-core"; import { LIST_ROW_TEXT_INSET, listRowHeight } from "./metrics"; import type { Layer, LayerContext } from "./layers"; -const SIZE_CHOICES = [8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 20, 22, 24, 26, 28] as const; +/** Pixel sizes offered for TTF faces (also by the onboarding's text-size page). */ +export const FONT_SIZE_CHOICES = [8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 20, 22, 24, 26, 28] as const; const DEFAULT_TTF_SIZE = 16; const PREVIEW_TEXT = "The quick brown fox jumps over 0123456789"; const INHERIT_UI_FONT_LABEL = "Same as UI font"; @@ -279,7 +280,7 @@ export class FontPickerLayer implements Layer { const allowed = this.options.sizeAllowed; if (!allowed || allowed(font.path, size)) return size; let best = -1; - for (const candidate of SIZE_CHOICES) { + for (const candidate of FONT_SIZE_CHOICES) { if (!allowed(font.path, candidate)) continue; if (best < 0 || Math.abs(candidate - size) < Math.abs(best - size)) best = candidate; } @@ -302,7 +303,7 @@ export class FontPickerLayer implements Layer { private openSizeMenu(ctx: LayerContext): void { if (this.draft.kind !== "ttf") return; const draft = this.draft; - const sizes = SIZE_CHOICES.filter((size) => + const sizes = FONT_SIZE_CHOICES.filter((size) => this.options.sizeAllowed === undefined || this.options.sizeAllowed(draft.font.path, size), ); const items = sizes.map((size): MenuItem => ({ @@ -312,7 +313,7 @@ export class FontPickerLayer implements Layer { innerCtx.stack.pop(); }, })); - openModalMenu(ctx, "Size", items, Math.max(0, sizes.indexOf(draft.size as (typeof SIZE_CHOICES)[number]))); + openModalMenu(ctx, "Size", items, Math.max(0, sizes.indexOf(draft.size as (typeof FONT_SIZE_CHOICES)[number]))); } } diff --git a/build_paths.sh.template b/build_paths.sh.template index 991937b3..ea3b4cb7 100644 --- a/build_paths.sh.template +++ b/build_paths.sh.template @@ -6,4 +6,6 @@ #export PATH= #export ANDROID_KEYSTORE= #export DEVICE_ID= +# Apple signing team for iOS device builds (Xcode > Settings > Accounts) +#export IOS_TEAM_ID= diff --git a/native/kotlin/shared/src/commonMain/kotlin/com/faceclaw/app/g2protocol/session/ConnectionCounters.kt b/native/kotlin/shared/src/commonMain/kotlin/com/faceclaw/app/g2protocol/session/ConnectionCounters.kt new file mode 100644 index 00000000..539c931d --- /dev/null +++ b/native/kotlin/shared/src/commonMain/kotlin/com/faceclaw/app/g2protocol/session/ConnectionCounters.kt @@ -0,0 +1,44 @@ +package com.faceclaw.app + +import kotlin.jvm.JvmStatic + +/** + * Process-wide counts of connection-reliability events: connect attempts, + * transport failures by reason, ack timeouts, CFW replays, arm drops, how long + * sessions lasted, and the like. The phone app's analytics drains them + * (app/native/connection-counters.ts, app/analytics/). Only counts under fixed + * event names are kept, never addresses or message contents. They pile up in + * memory whether or not analytics is on; the app throws a drain away when it + * is off. + */ +object ConnectionCounters { + /** Distinct names kept between drains; new names past this are dropped. */ + private const val MAX_NAMES = 200 + + private val lock = protocolPlatform().createLock() + private var counts = LinkedHashMap() + + @JvmStatic + fun increment(name: String) { + lock.withLock { + val current = counts[name] + if (current != null) counts[name] = current + 1 + else if (counts.size < MAX_NAMES) counts[name] = 1 + } + } + + /** The counts since the last drain, as a JSON object of name to count, and starts over. */ + @JvmStatic + fun drain(): String { + val drained = lock.withLock { + val out = counts + counts = LinkedHashMap() + out + } + return Json.write(drained) + } + + /** An event name from fixed text: "CFW recovery retry limit" -> "cfw-recovery-retry-limit". */ + @JvmStatic + fun slug(text: String): String = text.lowercase().replace(Regex("[^a-z0-9]+"), "-").trim('-').take(60) +} diff --git a/native/kotlin/shared/src/commonMain/kotlin/com/faceclaw/app/g2protocol/session/GlassesSessionControls.kt b/native/kotlin/shared/src/commonMain/kotlin/com/faceclaw/app/g2protocol/session/GlassesSessionControls.kt index 882dfff8..2f853d19 100644 --- a/native/kotlin/shared/src/commonMain/kotlin/com/faceclaw/app/g2protocol/session/GlassesSessionControls.kt +++ b/native/kotlin/shared/src/commonMain/kotlin/com/faceclaw/app/g2protocol/session/GlassesSessionControls.kt @@ -359,6 +359,7 @@ internal fun GlassesSessionCore.firstUnpairedArm(): String? { */ internal fun GlassesSessionCore.handleUnpairedFailure(address: String) { logError("Connect failed and $address is not paired; suspending reconnect") + ConnectionCounters.increment("g2.unpaired") monitor.withLock { haltReconnectLocked("arm not paired: $address") } if (!userDisconnectRequested) { setStateDisplay( @@ -387,6 +388,7 @@ internal fun GlassesSessionCore.handleIncompatibleFirmware() { incompatibleFirmware = null pending } ?: return + ConnectionCounters.increment("g2.incompatible-firmware") logError("Glasses report incompatible firmware L=" + info.leftVersion + " R=" + info.rightVersion + " ext=\"" + info.extension + "\" (need Faceclaw/" + requiredFirmwareRevision + "); suspending reconnect") monitor.withLock { haltReconnectLocked("incompatible firmware") } @@ -429,11 +431,13 @@ internal fun GlassesSessionCore.haltReconnectLocked(reason: String) { */ internal fun GlassesSessionCore.handleTransportFailure(reason: String?, displayStatus: String? = null) { logError("Transport failure: $reason") + ConnectionCounters.increment("g2.failure." + ConnectionCounters.slug(reason ?: "unknown")) val retryDelayMs: Long monitor.withLock { maybeEmitEvenAppConflictLocked(reason) finishBenchmarkLocked(true, "transport failure") val sessionWasReady = sessionReady + if (sessionWasReady) countSessionEnded("failure") sessionReady = false fixedLayoutCreated = false startupProbePending = false @@ -460,6 +464,23 @@ internal fun GlassesSessionCore.handleTransportFailure(reason: String?, displayS interruptibleSleep.interrupt() } +/** + * Counts a ready session ending, by [cause] and by how long it had been up + * (for the analytics in app/analytics/). + */ +internal fun GlassesSessionCore.countSessionEnded(cause: String) { + ConnectionCounters.increment("g2.session-end.$cause") + val minutes = (now() - lastSessionReadyAtMs) / 60_000 + ConnectionCounters.increment( + "g2.session-length." + when { + minutes < 1 -> "under-1m" + minutes < 10 -> "1m-10m" + minutes < 60 -> "10m-1h" + else -> "over-1h" + } + ) +} + /** * Set [reconnectAfterMs] for the next attempt after a failure and return the delay. Repeated * failures back off along RECONNECT_BACKOFF_MS; a session that stayed up for @@ -737,6 +758,7 @@ internal fun GlassesSessionCore.maybeEmitEvenAppConflictLocked(reason: String?) return } lastEvenAppConflictAtMs = now + ConnectionCounters.increment("g2.even-app-conflict") emitEvenAppConflict("The Even Realities app still appears to be running. It can hold the glasses BLE link and cause Faceclaw write failures. Open its app settings and force stop it, then reconnect Faceclaw.") } diff --git a/native/kotlin/shared/src/commonMain/kotlin/com/faceclaw/app/g2protocol/session/GlassesSessionCore.kt b/native/kotlin/shared/src/commonMain/kotlin/com/faceclaw/app/g2protocol/session/GlassesSessionCore.kt index 8a41081d..9a966edc 100644 --- a/native/kotlin/shared/src/commonMain/kotlin/com/faceclaw/app/g2protocol/session/GlassesSessionCore.kt +++ b/native/kotlin/shared/src/commonMain/kotlin/com/faceclaw/app/g2protocol/session/GlassesSessionCore.kt @@ -410,6 +410,8 @@ class GlassesSessionCore( releaseFaceclawFramebufferLease() } monitor.withLock { + ConnectionCounters.increment("g2.disconnect-requested") + if (sessionReady) countSessionEnded("requested") userDisconnectRequested = true running = false audioCaptureActive = false @@ -1384,6 +1386,7 @@ class GlassesSessionCore( val ingress = if (message.isLeftArmMessage) leftAddress else rightAddress if (message.sid == CfwTransport.SID && address.equals(ingress, ignoreCase = true) && message.magic == ack.streamId) { message.acceptCfwAck(ack) + if (ack.nack) ConnectionCounters.increment("g2.cfw-nack") logLine("CFW " + (if (ack.nack) "NACK" else "ACK") + " id=" + ack.streamId + " ordinal=" + ack.messageId + " lens=" + ack.lens + " txseq=" + (data[2].toInt() and 255) + " redundant=" + (ack !== acks[0]) @@ -1583,6 +1586,11 @@ class GlassesSessionCore( if (decoded.eventType == BleProtocol.EVENT_ABNORMAL_EXIT || decoded.eventType == BleProtocol.EVENT_SYSTEM_EXIT) { if (shutdownRequested) { lastShutdownExitAtMs = now() + } else { + ConnectionCounters.increment( + if (decoded.eventType == BleProtocol.EVENT_ABNORMAL_EXIT) "g2.firmware-abnormal-exit" + else "g2.firmware-system-exit" + ) } fixedLayoutCreated = false displayedFingerprint = "" @@ -1691,6 +1699,7 @@ class GlassesSessionCore( ringReconnectAfterMs = now() + ConnectionOptions.RING_RECONNECT_DELAY_MS } } + ConnectionCounters.increment(if (connected) "ring.direct.connect" else "ring.direct.disconnect") logLine(if (connected) "direct ring BLE connected" else "direct ring BLE disconnected") interruptibleSleep.interrupt() return @@ -1709,6 +1718,12 @@ class GlassesSessionCore( // dropping mid-setup): the connect sequence notices on its own and // schedules the retry, so leave the backoff alone. lostSession = sessionReady + if (lostSession) { + ConnectionCounters.increment( + if (address.equals(rightAddress, ignoreCase = true)) "g2.arm-drop.right" else "g2.arm-drop.left" + ) + countSessionEnded("arm-drop") + } sessionReady = false fixedLayoutCreated = false startupProbePending = false @@ -1740,6 +1755,7 @@ class GlassesSessionCore( wearState = -1 } setStateDisplay("connecting", "Connecting to the glasses...") + ConnectionCounters.increment("g2.connect-attempt") try { // Dial both arms at once, so the left arm's attempt is already pending (and // can land) while the right arm is being set up; they share one window. @@ -1793,6 +1809,7 @@ class GlassesSessionCore( } } setStateDisplay("connected", "Connected.") + ConnectionCounters.increment("g2.session-ready") logLine("session ready") monitor.withLock { // Query settings at the start of every session so firmware @@ -1999,6 +2016,7 @@ class GlassesSessionCore( monitor.withLock { if (!inFlightMessages.isEmpty()) { clearInFlightMessagesLocked("security auth timeout") + ConnectionCounters.increment("g2.auth-unacknowledged") logLine("security auth not acknowledged; continuing (2.2.9 stock requires it; older/custom firmware may not answer)") return } @@ -2025,7 +2043,7 @@ class GlassesSessionCore( prelude.onAck = MessageCallback { } prelude.onTimeout = MessageCallback { - handleTransportFailure("ack timeout") + handleTransportFailure("prelude ack timeout") } prelude.sentAtMs = now writeMessage(prelude) diff --git a/native/kotlin/shared/src/commonMain/kotlin/com/faceclaw/app/g2protocol/session/GlassesSessionSend.kt b/native/kotlin/shared/src/commonMain/kotlin/com/faceclaw/app/g2protocol/session/GlassesSessionSend.kt index 58a99ffe..58bd4325 100644 --- a/native/kotlin/shared/src/commonMain/kotlin/com/faceclaw/app/g2protocol/session/GlassesSessionSend.kt +++ b/native/kotlin/shared/src/commonMain/kotlin/com/faceclaw/app/g2protocol/session/GlassesSessionSend.kt @@ -87,6 +87,7 @@ internal fun GlassesSessionCore.driveSession(): Long { val oldest = inFlightMessages.firstOrNull() val replay = CfwMessageWindow.replayWindow(inFlightMessages, now) if (!replay.isEmpty()) { + ConnectionCounters.increment("g2.cfw-replay") logLine("CFW recovery: replay " + replay.size + " unresolved message(s) from id=" + replay[0].magic) for (candidate in replay) { @@ -665,7 +666,7 @@ internal fun GlassesSessionCore.enqueueCreateLayoutLocked() { } startupProbePending = false } - handleTransportFailure("ack timeout") + handleTransportFailure("create layout ack timeout") } pendingMessages.addLast(message) logLine("queue create layout") @@ -706,7 +707,7 @@ internal fun GlassesSessionCore.enqueueStartupProbeLocked() { if (hasPendingOrInflightKindLocked("create-layout")) { return@MessageCallback } - handleTransportFailure("ack timeout") + handleTransportFailure("startup probe ack timeout") } pendingMessages.addLast(message) startupProbePending = true @@ -1279,6 +1280,7 @@ internal fun GlassesSessionCore.hasPendingMagicLocked(sid: Int, magic: Int): Boo internal fun GlassesSessionCore.handleAckTimeoutLocked(message: OutboundMessage) { consecutiveAckTimeouts += 1 + ConnectionCounters.increment("g2.ack-timeout") val onTimeout = message.onTimeout if (onTimeout != null) { diff --git a/native/kotlin/shared/src/iosMain/kotlin/com/faceclaw/app/ble/IosBleCentral.kt b/native/kotlin/shared/src/iosMain/kotlin/com/faceclaw/app/ble/IosBleCentral.kt index 9101e159..2cc2ddb8 100644 --- a/native/kotlin/shared/src/iosMain/kotlin/com/faceclaw/app/ble/IosBleCentral.kt +++ b/native/kotlin/shared/src/iosMain/kotlin/com/faceclaw/app/ble/IosBleCentral.kt @@ -584,6 +584,7 @@ class IosBleCentral(private val platform: ProtocolPlatform = IosProtocolPlatform private fun onDisconnected(peripheral: CBPeripheral, error: NSError?) { val peer = remember(peripheral) + if (error != null) ConnectionCounters.increment("ble.ios-disconnect-error." + error.code) failPeer(peer, error?.localizedDescription ?: "Disconnected", notifyListeners = true) } diff --git a/scripts/__pycache__/ios_config.cpython-314.pyc b/scripts/__pycache__/ios_config.cpython-314.pyc new file mode 100644 index 0000000000000000000000000000000000000000..3580cabda70ad22a6a5873c91b67254f2364e937 GIT binary patch literal 14621 zcmb7rdr%u^wrA`8MgobqfW|z9jqn3(3>e$tVXzH|2Fu2gVPvTR*+NpfTeeZ+3^VuM z3Qn?XoS9wY8Q(Iga&1U$w!+lSR-BsIigS~>n_D%t+gM_x?cwfZYo}^!?;l%E;;qSM z|Jn0(tGfk}Guh9k`|Iy{zSlXwbIzx|1r{R);a^XGc;%n#Fzmmh4>72-k+1(3M3yiD zW3XwAPz);=1^-quO8%{4RQy}bsNt;~)(mMGZH-V?$LRPxJ)`H}2FAd@jf|0hn-~-S zHV;|i${K8_fU(wKgo?2dYNn8|Fhzu>6l3g!7M>2GfY6mJ76WSF*1bSA~@qaFBVtA7BN9b9S z!Uz2UG7$D($72);-((~}(s-N>Mdt7efoPCyqH#JNi$y7h4C4M+tThmgF#b>ks-E-= z)9z81f>V3^%zVNYh%UHiv(34oXrkh5=rZM}7Td&5`l6B9(3}Sv3uLL{Y16_}1%F>Z zfz&0;C*^rDpHiS6!`id4rffp65Y2#3Bj$TCaij#+`E!^dGoP;$^9hBRKdM)lkgaNUM_JJEQGQjU6oF*9t_85&vFJFN){CbF)$Ndbx5TzNs zegDzJI2mE65J`tHScimTIC9M&4h6+}c*MUzCXP>ttt`Z$T6SmR(MWg^r=d2qzYo70 zjfP3s?6^M?#Aid15JTdT_`+q9qFrXr7=o=%Gk)0ioH`f^Fq|q(MmVF_AC8j)6cwd7 z4b)hmITf_XshPzX6hv)us!)XCG_&ETpW)OCZ~{1eh!#3`r_?ns$BepB&y;CCJAqvI*~e{ni}aqh{*Id*;_eKC@{7~!i= zCyQoS^URk9thDK=5i>iM#=ZtRu^q=BZ65yk|ATt>@fSCf2j%Yy;&F{Ba+rX0(0qug z@FC~GNr#@0m<2Ecg~ue8mEU6P9_cvBc`_>zkHUZ=_!D%H2qm;;l}m~-v9+U+FbBsA zN~->H$t(+#sm?iE^6~dbhg<9o!{E3|GZ9mIl^(Q3b_GJyd0k?Yavxf8&gT_vSWM+r z+OPq|AdD%d_NqOlyBdK{LMPUUY0gie5q^hmy;uTfTb-8{125Fd(9A#yc<&C~5_1(; z7Kk%rOgr-SbJ{cU?d{99myc?*NE1=Q)6B2Rb4DnawR8@_OlU{Q=k#03w{;rzTZu-J zZ{7=d+MKA2uTmW6^Li$XBFh%(9jWkD{r}ejnoT}=l?%nz=5tSvw7_EiqN2Yz%B4r+2jLGjEyHe+?6LY*eU%eO?M=MbPYX^Hmmv`scMQWxM zdH1qI%!hrKzlCD4L`>xqyTrVbIIhER%%>M=(_%pozfP`Qsj0WNhAP{jRe&{xcg%}VNxSs-97G-3F#;F$kv4l$!v?n7$DvHGB zJQNMK=3=}aDA~)Yc|lszACHAY0gxv<1T3c&q$r1Rx~v$b5VHX>NX1DCamEBLN@kF$ zBozwe;7FX8d83KCa}gOriWJGD@PkUUjFL2h207_So})pB=v{-<(t&w$!JjxLjZ*}e z2m^qK6yStVstZ5Bi+;a2G!b)92tc`%6go^G$NgcNbg3vnjWE7&G&0AJ&*h*H?&ORV z=?~6aUSvp`LXw5koE;tk6s<#XZ5Yi{j57j|pcooq8BPPBnWQ-7z$9m!rJ@VjnN%_U zIZic40%Tyw8w}q^w$CecG{R{BP6TNR1R+KtXv@oYm!4C{5Wr9e{fwVeQ_(2HQ_rap zHlY9s161WH5ysDNDZm+gpzJ8e#1BBorVc_%4gAqx!hS@c!MdV;qbqH~H%)lbv}dV* zTW4Hu|EtBHccgS>JalMF7VKyB`!hPzYcK!g<-fX_*41q4YSz?gT|-jWkTI36wm;~) z*Y(Sul&NXG`%(SJEg!Y~dS7bqAP)n4$)ZcF`O>zv@b=BuZ>~-zt$UW$8I$#P=dI3_ zc*^ADOARH9hFSA)#$LRv-*%KO_h*Vq?l#|PUOk*F+Oyo3u@=4g0)hN z8LR#FjaxTXJ5$!WOquh6;hy1vb=A5?+|gtTi|>}*DO;UN6*jK7zu)<8=f(QhLh2Ipt?BhuEtN$*D;4T=dSsGd)&X%hnDiOHQ%2Q`^>} zmG;|GxqYkU3a=xuO#g*m@kukWhiN?V%1gOJS)e__B_KB zFo^AndbZ(IvSR4-AnPEWs!-auG&;DyZ9J(P)+_%}Up9P~G; zWOX$;y3QP68xUkt3m&w0cZFKeucs9R=v{5fX(fUFsg7jJ5o(aqQt+SywJV6=sV;{V zdn8>or1NzXj01pBA>WNniHY* zstDbYEQpOraPv$z=uWwPNx5C_LZbRrwH` z;Dc9!0UilxhIobl6vP>3`5!{O-lnTS8aDU1}FUJA{bOF@;R zIDjyW!qEer2@nQ+Dq^JxO`Mr+?VNNeIXxIfqCwCmIqQvu@JxzvS>(UC`Uj^h)ZK$j)0n}Gv9%v+@8hHUAaDR(HPF91Y`XL+r(fyKIe zkGD;h+g-1Bt&mBR6Qo9obM?Z5>3h@3s@C6^xOwdo^ilHuMA}sQ#8jK5wuhS{>q2HT3|Ae=!cYIKv#*aL~kK8%>S%M|br>1=AQNr z)z%Mv5O~z^cURJf2R9E7CJzs#&BI@su+p|?W=x}dZTP3d%fY`MLsWIY-o3)C%{^jL zrvAtAEz?<6eU>VQ;qKsdXd%$4{QAH0g0K?v!G{n$5=RqLkXl7xZs1~Likxy;J|>rf zGcA4OW_!#w-OJ5+LBF3Zo(sR6*)~j zxjCv-18S=VgEr8f-xYpf8$4$MbxcwN=M|Gm9ym+wdC-2`6#z^h$o4LcEePikWQkPL zBk>3+3D#f|$r2TzZqLqqTv-KHCZ9ATvJ@b+Ignh>X>J6lcx2M0M!+^0jiUp}1mSq` zr;gJxp#>6BDWsGos(JG#K=Es#013EqVF4MCP>~=Gg%YFRpWlrGMh#rWnR&2kG4muI zn~z3Fgk=GPMY3ivXfPfLgZ+mLjwUMeHaP1Kg~_1H2;ee)IYvdnJPWoc7zS8fhdl#a z!K6SmK;aNTe9qPvU5JHAfYP39VKWg2ePJPM%>p3H#3{tkNNNbi$!U1(N}Yl@a8b3N znxhe?36r3Ikerqx>3EnC3|Eaf&rPT^P?mp8K!pAT9!uC$rABjIv0YesxB9K>wNe(} zzupdy-&A~D^HEJ|{KfS6k2c4D#Liu1E-b!G6M)s?*iFtcLy@PlLb zj-@Nzo0aZl<^FW#6}Ixq#^8q|zZyxmpW19cm24jt64{X}$%3n_{%XclxHR(3GYe)e zNt^07P4&+(70~fVlYQG>mA1Q|*xl>Q#`q&8+v7{xFFgSeT2R4OUQHH+S?U_AzxGsz z%705E6TwfrUTDJpzRB6QPxYy~96f6+@XXIKTAquJzSmfV`6Pak?^J+{#PaQW0xb7O zvK*;fF{6kpE-?$a=sWts34zmFLEo9@*V9+I7w^;@#gdUbEsB%B-4sq262re*_o;V z0}Y`;|Jt*-40xCZ@vX@pP*+s+acnOpa_Tu)A14+9Pfr!_RP+zEmo*4z2LVZ_f+332 z21#^2LrXx&BzRAZ3n3c$TV|qHM_mPix~cbHrla9F96&uNc(GaF0bJ22*t~<2@EJu; zl|huIje%YdhH?a3IAxUPG=cerXpqxfr$94A*6BD6y67yu7zuD%)J!DG>A=_=20sm_ z1?CfqTy?3bR;W+8Q6pO5Z86}C2GlR#5sfx10uut1F#DP4LMSl9_dv}--VFTF{{bF3 znq>8+sXA%G0TUPs(}wydhWd5K`<3rjK022+^lcgX9$y0uZ?)t><-N+JqhZPVTZv+*}a#UkFjm+oBp*-XmZfKpDsetKmwWp4Vy zT%0yLH_gshWNLs{ z;n{4=vqy}{Z{T?v587|L!fu{N6zt0x7h%r*ifO%C8+J|?SGuvdauAfGm#*hs5o?>| zugsfo6X${`M7uQW5d=NNs~c6G0j7XVyD@!Cmt!E64Ej3^uP$*oM2?x*3%>DOx(R#k z7p$~2lRoHE2p$;C?(kiYcFaIHyau8;|Cwu3#*AJC2`Jl%ov$EDkS3P1Du~(b3a~0h zq7?p>i8`kT5bEwAu2IaCGan{#4t>b9#)llYlRPiwVmUBKD~XC7yUgr0dpgA0@|&n6 zoZ<BzGr7ian@?Ek&`(s8i_iho@gK%0kJd@&4eq5H?+w6$}78X z_R3>+7s##dYI7g4hi|i0ZqF_4co=z?IB%XFF($v|eL7v9yNzQ7z|XBew63?H6Ew2m z2G5Vae>H(q!D?Cv_l{Mxjr70{+m*I!ob^Q8bLLLk8N~kFF%WxmW>w-F?t+~w2?!Gx z=i@ot&-O#OU#!qun3rQoZXK`SHUudOlB6(Z9Vv&t<<&VMQX#)VVjhs!{mefCm$S~A zQGFlCBOwq6#S(Bzt$8UpB$kjQhoHGiZ9J!5JJBJYQn3Z-BR^(1%wvYX;dg+QIFidX ziIUteKnXHe$crg_1LD}c3R$v3zu$vDJcD8#`Ry5&<6=zYheRiGjY^}->MC$r&WI(6 zqd6Q?a!;EvqANcokkfrolCE&}t8&`v@mh&vxw8PJd*#y&U&nLn5`d<_Z4U?o1;7}J zI*^(*@E6mC0Q38Lg&dF(&0_435^NN_{6L6)KylXn15rP;okjg8z;Oczd^BMbFLa>$ zQ{bU$1>mnmzOK*>&Nw_aG1EWb9qt?8wBTn0-5m@Qp@jew<_f`8Gy`|3kmXLecE!W= zgjujl&~DyqWDvek1$8(?Gn_7)ov^gFq7tnFs;4GlY@8!&fdKC!*a*N&g?x#eiHU<< zB0Rw$wcj8aDH0tMaA_wryT}_cLLT0V!Qa+tZOz(7&h-!XA`&RZ>XUQHSA?aP|pqJBoY>F3B)EeWqNI=-m@aq3dIz$AB`?%`;GT z$b>mtkDm-=vDFD`5g0Pa8!#Q9Ss{IfS_nm8aA5mIb_?*@`QwqmJkrOIiHB1MqHwcD z$wa@^i$g=x7mO~zb+=aj;*Skhq90svK!~sy3Ajr6BaPG#K7fC3ahF{e#1lo+zrY}MG6;$FODbXMx!`fI||H0RnhM$ z6~)i-cBLH46S7|MSDnIP+>c+5hr&U@O$tkmHY6x}k|TK^su#h*R75ShL9e{Z=@!85 zKYmBM$v1b zXq?XRDAV|5KeDyq@fb`6p0Krvh1}r&rWv=Zk-82e;QgbV8mY_FMfm25B(1w2jBEk8 zrnSiH>C~&JG{7ma@sp8jAu1Z75ZL1kaD3xo(3C0OPR40pI5*mVc7V6CQRAqR0X_Dj z2NJNHfp^dHE@7nc34UdDJPs#EgP!daxQZ|e;SCBY6r5(^Di{-Z{hQMg10!RT1K?5y zGaqMIh{BzKXe1QibYm0QJ8X2ABxBSVs@{*PYw7qb@E+;}-&PE~3XH3WB2Yfk^f>kP zD0P(|9?uJe-OlOIEWvi8UP5IQaH{>+z&`1}3=cyd7}? z7#pV#f*&1>4iFRfDkp9G8Q#fl2*6eifv20Kkx^Q7WAnaj{vp^Q^x_Vr{tc8`fIoT+ z#Mu(|g{$@b>UXOj9ZtDUzWFlvrH|e_nzA-LW|oE|V+6aeH*Gk+WjOx0ecNhZ>3<^u z{%G(SSKg^i7xu7)Jr9-d7~eL&Q}A}d`YTDiXIYE9)xEcSmwPkCmFeOpwzz5a#`55H zne+a{S~I)v_~Vk_m9XRI+1d-qs;P9;kfUcI(?=-Pwv z)$ws$+Ol^PRkW5!;(TCw)xM*WBGU%A<$lgqk{$^OJtliAa(_p~g&$tA2s@y8eQ;y&(do~%tY?Px)0yIy_Xamkf2L)Jr?yT^u`gapg`;fj zW-|OL5LSFb`BaIWQI0A9H&E$OK2>Wi#oJE&!RcR|Ub~rY>fLPWO*WlKI!~?`GIr

rJ+Ox3-_l`VET8C4+9ujHe_yUg&pjtGczs%T zvJ76IbvI3v>VMm$MbFk#R!I8Yv6EVO{U>$Lgj4;WvEvYDu|5mDlBF8-bQVq=&?Q?{ zD865T;s^M6yJ=Em2ta>QK%xLa*028o;Pg_iV=N1=rIHY-#ioyoN(I1f;DtiS?`8lv ztQ5@(F=UEF0%=!3=5j*ghU*Kmn*N-UIzmqv{$eRGo{0(qxDE36$vgcCt7w9GZaEuK zNE8wF9p!S2cH&S(^(2Pw`GTUiJBSKgu%1`66!}~tQW=m(U>?NsIYbCaDFur2wvuD$ z1XBkxbmpfhryQ(3ZxAi^Dk3_Oa!_$4!)vY^W*VHJpvXAHay~FO3qdwx_#|_p2Nc%b z;gA{>9x%c=F>okJW;vo{QfbBxD!*T;CrahjufmA3nDV%C8WbTR7E*|+ldJrH9*2Gt z4-q_UL&^~z8k>-Rh9aQRZV~CxJc0%2=f(+84gh`8!tYXqJADz!e~KKnWH=h*uSp7s z-i;$PiNm$TIjDuMAchfGgzNY;pvgdhgnRY4cpnj6y95puL1c~2p*8D3(QABcc6I(3a2;@Nty_9p(d2Avk7f$E5eWv4^lrtgPzOkPe@~G zLpLw?p*|(7h=U%LRjs77ZW!3CAGu(0K+m#+o1d$^f z4QwAy!c|B3B@qAH1t{kaBeH}c%qA*Cop(mW=Wh5F1Fzd8bUZHY!a*6k1#OQ4_~c=< zCcfaOuX1{rL(t)9k}Eh#&GC0%J?N9-%>H0-26Fi{&d3)+-@+2`jd2=q=>zgcxRCl+ z=z-3T0Dc=G#u@pxcnYXhl%S#)Y2F)-?h)}#QUVtK_mIo`z5#d&uoHgi5sFYBLHY*D zYXChIU7*pvHuTe><#TZN#8RBL)IYJ*gZMdkK?UNcU`n+#m{A+k>e5Yh>8fdcc4L-p zJ;tg_Q|ewhUAq?GlUn2?_3C^|-IV)%1zO!drG$deu;!vt&aZ zCTG%Az0{BHY%adGxU{%3d3WmW)XG#wUvS%e%gh!Jr1XOT%I+HO7}B;u);730`C#ha zln`fI2ABH(dibeQtts5r+g2QJ7JRA4%$9GS=`f4q=NBJ3-=p5Y`R+~DbnF?XL}e^1 zx>e1}b+(}9Vc?xBZ(rHcANVJ$?f*X2K<>A68BEt_8t|WCpA|I>;HuA#R1Z|Dep{)5 zIH#YPLGwB@1Lq2dgEi=Ka=Murxc59WL;VVB3aS#i=#o{pkg5=dpO+y)NS#KH577gu zYt+xs<2F3FV$ek0pv97;JA1)u65_ByP!ea#N#k#7QU3zfd<#90k|kX0I*4NZ=z%O* zyv8MLEwl*`<>(;K%y4SZ=cY%f(PIXh2p [...] + +Scans the main-app component (ota/s200_firmware_ota.bin, loaded at 0x438000 +after a 0x20-byte preamble) for lv_font_fmt_txt_dsc_t structs with 4 bpp, +bitmap format 3 and a plausible cmap table, and prints one row per font. After +a firmware rebase, match rows to FONT_SPECS by cmap count / code-point count +(the EvenHub fallback chain is n=12/8081, n=9/9566, n=4/11590) and copy the +new `dsc` addresses into firmware-fonts.ts. +""" +import struct, sys +BASE=0x438000 +def mainapp(path): + d=open(path,'rb').read() + for i in range(8): + toc=0x40+i*16; off=struct.unpack_from('len(d): continue + size=struct.unpack_from('>9)&0xf; fmt=(packed>>14)&3 + if bpp!=4 or fmt!=3 or n==0 or n>64: continue + # cmap entries 20 bytes: range_start u32, range_length u16, glyph_id_start u16, list ptr, list ptr, list_length u16, type u8 + good=True; total=0 + for i in range(n): + c=cm+i*20 + if not img.ok(c,20): good=False;break + rs=img.u32(c); rl=img.u16(c+4); t=img.b[c-BASE+19] + if t>3 or rl==0 or rs>0x10FFFF: good=False;break + total+=rl + if not good: continue + out.append((a,bm,gd,cm,kd,n,total)) + return out +for path in sys.argv[1:]: + print("==",path); img=Img(mainapp(path)) + for a,bm,gd,cm,kd,n,total in find_dscs(img): + print(f"dsc 0x{a:08x} bitmap 0x{bm:08x} glyphs 0x{gd:08x} cmaps 0x{cm:08x} n={n} codepoints={total}") diff --git a/scripts/ios.sh b/scripts/ios.sh index e5e9f0d5..3904dc08 100755 --- a/scripts/ios.sh +++ b/scripts/ios.sh @@ -20,4 +20,13 @@ if command -v ruby >/dev/null 2>&1; then fi node scripts/install-hooks.cjs + +# NativeScript otherwise guesses the signing team from installed provisioning +# profiles; once a free team's profile expires and Xcode deletes it, the guess +# is null and the generated project gets an unloadable DEVELOPMENT_TEAM. +if [[ -n "${IOS_TEAM_ID:-}" && " $* " != *" --teamId"* ]]; then + case "${1:-}" in + build|run|debug|deploy) set -- "$@" --teamId "$IOS_TEAM_ID" ;; + esac +fi exec ns "$@" diff --git a/scripts/resetOnboarding.sh b/scripts/resetOnboarding.sh index e6cf31d5..9daed669 100755 --- a/scripts/resetOnboarding.sh +++ b/scripts/resetOnboarding.sh @@ -4,7 +4,8 @@ # pre-onboarding state, for testing the onboarding flow repeatedly. # # By default this only clears the onboarding-related preference keys -# (onboarding.complete, onboarding.previewOnly, ...) and leaves everything +# (onboarding.complete, onboarding.previewOnly, the on-glasses onboarding's +# onboarding.glassesFinishedVersion, ...) and leaves everything # else — notably the saved glasses/ring MAC addresses — intact, so you don't # have to re-scan devices on every test pass. Pass --all to wipe ALL app data # (a true fresh-install state, addresses included). diff --git a/scripts/test/annotate_config.py b/scripts/test/annotate_config.py new file mode 100755 index 00000000..5001cb7f --- /dev/null +++ b/scripts/test/annotate_config.py @@ -0,0 +1,188 @@ +#!/usr/bin/env python3 +"""Annotate a pulled faceclaw_settings.xml with placeholders for unset settings. + +Settings that have never been configured are absent from the SharedPreferences +file, which makes it unclear what keys exist or where to add them. This script +scans the app's TypeScript source for ConfigSetting declarations (the settings +catalog) and appends a commented-out XML node for every setting not already +present in the file, so pull_config.sh -> edit -> push_config.sh is a +convenient way to configure things like API keys. + +Usage: annotate_config.py [settings-xml] [app-src-dir] +Defaults: faceclaw_settings.xml, /app (relative to this script). +""" + +import re +import sys +import xml.etree.ElementTree as ET +from pathlib import Path + + +def find_setting_blocks(source: str): + """Yield (kind, block_text) for each `new ConfigSetting*({...})` in source.""" + for match in re.finditer( + r"new\s+ConfigSetting(Boolean|Enum|String)(?:<[^>(]*>)?\s*\(\s*\{", source + ): + kind = match.group(1) + # Walk to the matching close brace of the options object literal. + depth = 1 + pos = match.end() + while pos < len(source) and depth > 0: + ch = source[pos] + if ch == "{": + depth += 1 + elif ch == "}": + depth -= 1 + pos += 1 + yield kind, source[match.end() : pos - 1] + + +STRING_LITERAL = r'"((?:[^"\\]|\\.)*)"' + + +def unescape(literal: str) -> str: + return re.sub(r"\\(.)", r"\1", literal) + + +def field_string(block: str, name: str): + m = re.search(rf"{name}:\s*{STRING_LITERAL}", block) + return unescape(m.group(1)) if m else None + + +def field_string_or_ident(block: str, name: str): + """Return ('literal', value) or ('ident', name) or None.""" + m = re.search(rf"{name}:\s*(?:{STRING_LITERAL}|([A-Za-z_][A-Za-z0-9_]*))", block) + if not m: + return None + if m.group(1) is not None: + return ("literal", unescape(m.group(1))) + return ("ident", m.group(2)) + + +def parse_string_array(text: str): + return [unescape(m.group(1)) for m in re.finditer(STRING_LITERAL, text)] + + +def build_constant_tables(sources): + """Map identifier -> string value, and identifier -> list of strings.""" + string_consts = {} + array_consts = {} + for source in sources: + for m in re.finditer( + rf"const\s+([A-Za-z_][A-Za-z0-9_]*)\s*=\s*{STRING_LITERAL}", source + ): + string_consts[m.group(1)] = unescape(m.group(2)) + for m in re.finditer( + r"const\s+([A-Za-z_][A-Za-z0-9_]*)\s*=\s*\[([^\]]*)\]", source, re.S + ): + values = parse_string_array(m.group(2)) + if values: + array_consts[m.group(1)] = values + return string_consts, array_consts + + +def collect_settings(app_dir: Path): + sources = [p.read_text(encoding="utf-8") for p in sorted(app_dir.rglob("*.ts"))] + string_consts, array_consts = build_constant_tables(sources) + settings = [] + for source in sources: + for kind, block in find_setting_blocks(source): + key_ref = field_string_or_ident(block, "storageKey") + if key_ref is None: + continue + key = key_ref[1] if key_ref[0] == "literal" else string_consts.get(key_ref[1]) + if key is None: + print( + f"warning: could not resolve storageKey {key_ref[1]}", + file=sys.stderr, + ) + continue + + if kind == "Boolean": + m = re.search(r"defaultValue:\s*(true|false)", block) + default = m.group(1) if m else "false" + else: + default = field_string(block, "defaultValue") or "" + + values = None + if kind == "Enum": + m = re.search(r"values:\s*(?:\[([^\]]*)\]|([A-Za-z_][A-Za-z0-9_]*))", block, re.S) + if m and m.group(1) is not None: + values = parse_string_array(m.group(1)) + elif m: + values = array_consts.get(m.group(2)) + + settings.append( + { + "key": key, + "kind": kind, + "default": default, + "label": field_string(block, "label"), + "description": field_string(block, "description"), + "values": values, + } + ) + return settings + + +def xml_escape(text: str) -> str: + return text.replace("&", "&").replace("<", "<").replace(">", ">") + + +def comment_safe(text: str) -> str: + # "--" is illegal inside an XML comment. + return re.sub(r"-{2,}", "-", text) + + +def placeholder_comment(setting) -> str: + lines = [] + title = setting["label"] or setting["key"] + desc = f": {setting['description']}" if setting["description"] else "" + lines.append(f"{title}{desc}") + if setting["values"]: + lines.append(f"Allowed values: {', '.join(setting['values'])}") + if setting["kind"] == "Boolean": + node = f'' + else: + node = f'{xml_escape(setting["default"])}' + lines.append(node) + body = "\n ".join(comment_safe(line) for line in lines) + return f" " + + +def main() -> int: + xml_path = Path(sys.argv[1]) if len(sys.argv) > 1 else Path("faceclaw_settings.xml") + app_dir = ( + Path(sys.argv[2]) if len(sys.argv) > 2 else Path(__file__).resolve().parent.parent / "app" + ) + + content = xml_path.read_text(encoding="utf-8") + present = { + child.get("name") + for child in ET.fromstring(content) + if child.get("name") is not None + } + + missing = [s for s in collect_settings(app_dir) if s["key"] not in present] + if not missing: + return 0 + missing.sort(key=lambda s: s["key"]) + + close_tag = content.rfind("") + if close_tag < 0: + print(f"error: no in {xml_path}", file=sys.stderr) + return 1 + + header = ( + " \n" + ) + block = header + "\n".join(placeholder_comment(s) for s in missing) + "\n" + xml_path.write_text(content[:close_tag] + block + content[close_tag:], encoding="utf-8") + print(f"Added placeholders for {len(missing)} unset setting(s) to {xml_path}") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/test/build-evenhub-font.mjs b/scripts/test/build-evenhub-font.mjs new file mode 100644 index 00000000..49188f91 --- /dev/null +++ b/scripts/test/build-evenhub-font.mjs @@ -0,0 +1,207 @@ +#!/usr/bin/env node +/** + * Preprocess Even's extracted 20px firmware fonts into a single asset Faceclaw + * bundles and renders (app/fonts/evenhub/evenhub-20.json). + * + * Source: reverse-engineered LVGL lv_font_fmt_txt glyph data under + * g2/downloads/s200_embedded_fonts/{background_latin_20, background_greek_ + * cyrillic_20, shared_emoji_20}. The Chinese font is intentionally excluded + * (we will substitute an OFL font for CJK later). + * + * Only glyph BITMAPS + boxes are taken from here; text SIZING/KERNING at + * runtime comes from @evenrealities/pretext, whose advance tables these + * bitmaps were cross-validated against. The three fonts are merged with the + * EvenHub fallback priority (latin > greek/cyrillic > emoji); the first font + * that owns a codepoint wins, matching pretext's chain. + * + * Bitmaps are 4bpp, high-nibble-first, row stride = floor(box_w/2)+1 (Even's + * pipeline pads every row by a nibble). The UI fonts are effectively 1-bit + * (nibbles are 0 or 0xF) but we keep 4bpp verbatim so any anti-aliasing + * survives. + * + * Output JSON: + * { lineHeight, baseline, glyphs: { "": [boxW, boxH, ofsX, ofsY, off, len] }, + * bitmapBase64 } + * where off/len index the decoded bitmap blob. lineHeight/baseline come from + * the latin font (the layout reference; pretext uses the same 27px height). + */ +import { readFileSync, writeFileSync, mkdirSync } from "node:fs"; +import { dirname, join } from "node:path"; +import { fileURLToPath } from "node:url"; + +const here = dirname(fileURLToPath(import.meta.url)); +const FONT_SRC = join(here, "../../downloads/s200_embedded_fonts"); +const OUT = join(here, "../app/fonts/evenhub/evenhub-20.json"); + +// Priority order = EvenHub fallback chain (minus cn). +const FONTS = ["background_latin_20", "background_greek_cyrillic_20", "shared_emoji_20"]; + +function rowStride(boxW) { + return Math.floor(boxW / 2) + 1; +} + +const merged = new Map(); // codepoint -> {boxW,boxH,ofsX,ofsY,bytes:Uint8Array} + +for (const font of FONTS) { + const dir = join(FONT_SRC, font); + const glyphs = JSON.parse(readFileSync(join(dir, "glyphs.json"), "utf8")); + const bitmap = readFileSync(join(dir, "glyph_bitmap.bin")); + for (const g of glyphs) { + if (g.codepoint === undefined) continue; // reserved / unmapped glyph slots + if (merged.has(g.codepoint)) continue; // earlier font in the chain wins + const len = g.box_height > 0 && g.box_width > 0 ? rowStride(g.box_width) * g.box_height : 0; + // Guard against the known slightly-truncated bitmap tails: pad short reads. + const bytes = new Uint8Array(len); + for (let i = 0; i < len; i++) bytes[i] = bitmap[g.bitmap_index + i] ?? 0; + merged.set(g.codepoint, { + boxW: g.box_width, + boxH: g.box_height, + ofsX: g.offset_x, + ofsY: g.offset_y, + bytes, + }); + } +} + +// Layout metrics from the latin font (also what pretext uses: 27px line). +const latinFont = JSON.parse(readFileSync(join(FONT_SRC, "background_latin_20", "manifest.json"), "utf8")); +const lineHeight = latinFont.line_height; // 27 +const baseline = lineHeight - latinFont.base_line; // 27 - 5 = 22 (px below line top) + +// --------------------------------------------------------------------------- +// Symbol / fullwidth glyphs from the CJK flash font (s200_font.bin). +// +// The three embedded UI fonts above cover latin/greek/emoji only, so grid- +// graphics apps come out blank: snake draws its board from U+3000 (ideographic +// space), U+25A6/U+25C6 (pieces) and fullwidth forms; block/box-drawing bars +// use U+2500-259F. Those glyphs live only in the SourceHanSans CJK font on the +// separate flash partition. We pull just the non-Han SYMBOL ranges from it +// (not the 21k ideographs — those wait for the OFL substitute) so grid UIs +// render. pretext already returns 20px advances for these, so only the bitmaps +// were missing. Format per notes/font-formats.txt (LVGL lv_font_fmt_txt in the +// "ZZZZ" flash wrapper, memory-mapped at 0x80100000). +const CJK_FONT = join(here, "../../downloads/s200_font.bin"); +const CJK_MMAP_BASE = 0x80100000; +// Non-Han symbol ranges grid/graphics apps rely on (inclusive). +const SYMBOL_RANGES = [ + [0x2000, 0x206f], // general punctuation (incl. various spaces/dashes) + [0x2100, 0x214f], // letterlike symbols (℃ ℉ №, etc.) + [0x2190, 0x21ff], // arrows + [0x2200, 0x22ff], // mathematical operators + [0x2500, 0x257f], // box drawing + [0x2580, 0x259f], // block elements + [0x25a0, 0x25ff], // geometric shapes (snake pieces) + [0x2600, 0x26ff], // miscellaneous symbols + [0x2700, 0x27bf], // dingbats + [0x3000, 0x303f], // CJK symbols & punctuation (ideographic space) + [0xff00, 0xffef], // halfwidth & fullwidth forms +]; + +function loadCjkSymbols(existing) { + let added = 0; + const cjk = readFileSync(CJK_FONT); + const off = (ptr) => ptr - CJK_MMAP_BASE; + const descPtr = cjk.readUInt32LE(0x34); + const cjkLineHeight = cjk.readUInt16LE(0x38); + const cjkBaseLine = cjk.readUInt16LE(0x3a); + const cjkBaseline = cjkLineHeight - cjkBaseLine; // 25 - 6 = 19 + // Our single composite baseline differs, so shift ofsY to keep the glyph's + // designed vertical placement when drawn against our baseline. + const baselineShift = baseline - cjkBaseline; + + let d = off(descPtr); + const glyphBitmapOff = off(cjk.readUInt32LE(d)); + const glyphDscOff = off(cjk.readUInt32LE(d + 4)); + const cmapOff = off(cjk.readUInt32LE(d + 8)); + // kerning ptr (d+12) is null; packed field after gives cmap_num. + const packed = cjk.readUInt16LE(d + 18); + const cmapNum = packed & 0x1ff; + + // Parse the cmap table into lookup records. + const cmaps = []; + for (let i = 0; i < cmapNum; i++) { + const base = cmapOff + i * 20; + cmaps.push({ + rangeStart: cjk.readUInt32LE(base), + rangeLength: cjk.readUInt16LE(base + 4), + glyphIdStart: cjk.readUInt16LE(base + 6), + unicodeListPtr: cjk.readUInt32LE(base + 8), + glyphIdOfsListPtr: cjk.readUInt32LE(base + 12), + listLength: cjk.readUInt16LE(base + 16), + type: cjk.readUInt8(base + 18), + }); + } + + const glyphIdFor = (cp) => { + for (const c of cmaps) { + if (cp < c.rangeStart || cp >= c.rangeStart + c.rangeLength) continue; + const rel = cp - c.rangeStart; + if (c.type === 2) return c.glyphIdStart + rel; // contiguous + if (c.type === 0) { + // u8 glyph-id-offset array + return c.glyphIdStart + cjk.readUInt8(off(c.glyphIdOfsListPtr) + rel); + } + if (c.type === 3) { + // sparse: u16 unicode-delta list; index in the list is the glyph offset + const listOff = off(c.unicodeListPtr); + for (let k = 0; k < c.listLength; k++) { + if (cjk.readUInt16LE(listOff + k * 2) === rel) { + const gid = c.glyphIdOfsListPtr + ? cjk.readUInt8(off(c.glyphIdOfsListPtr) + k) + : k; + return c.glyphIdStart + gid; + } + } + return 0; + } + } + return 0; + }; + + for (const [start, end] of SYMBOL_RANGES) { + for (let cp = start; cp <= end; cp++) { + if (existing.has(cp)) continue; // don't override latin/greek/emoji + const gid = glyphIdFor(cp); + if (!gid) continue; + const dsc = glyphDscOff + gid * 16; + const bitmapIndex = cjk.readUInt32LE(dsc); + const boxW = cjk.readUInt16LE(dsc + 8); + const boxH = cjk.readUInt16LE(dsc + 10); + const ofsX = cjk.readInt16LE(dsc + 12); + const ofsY = cjk.readInt16LE(dsc + 14); + const len = boxW > 0 && boxH > 0 ? rowStride(boxW) * boxH : 0; + const bytes = new Uint8Array(len); + for (let i = 0; i < len; i++) bytes[i] = cjk[glyphBitmapOff + bitmapIndex + i] ?? 0; + existing.set(cp, { boxW, boxH, ofsX, ofsY: ofsY + baselineShift, bytes }); + added++; + } + } + return added; +} + +const cjkAdded = loadCjkSymbols(merged); + +// Concatenate bitmaps and record offsets. +const chunks = []; +let offset = 0; +const glyphRecords = {}; +for (const [cp, g] of [...merged].sort((a, b) => a[0] - b[0])) { + chunks.push(g.bytes); + glyphRecords[cp] = [g.boxW, g.boxH, g.ofsX, g.ofsY, offset, g.bytes.length]; + offset += g.bytes.length; +} +const blob = Buffer.concat(chunks.map((c) => Buffer.from(c))); + +const asset = { + lineHeight, + baseline, + glyphs: glyphRecords, + bitmapBase64: blob.toString("base64"), +}; + +mkdirSync(dirname(OUT), { recursive: true }); +writeFileSync(OUT, JSON.stringify(asset)); +console.log( + `wrote ${OUT}: ${merged.size} glyphs (${cjkAdded} from CJK symbols), ` + + `${blob.length} bitmap bytes, ${(JSON.stringify(asset).length / 1024).toFixed(1)} KiB json`, +); diff --git a/scripts/test/pack-ehpk.mjs b/scripts/test/pack-ehpk.mjs new file mode 100644 index 00000000..4cbdcfff --- /dev/null +++ b/scripts/test/pack-ehpk.mjs @@ -0,0 +1,91 @@ +#!/usr/bin/env node +/** + * Pack a web-app directory into an EvenHub .ehpk, dependency-free (Node >= 22.15 + * for node:zlib zstd). Format reverse-engineered in + * ../../ehpk-unpacker/ehpk_unpack.py and consumed by app/apps/evenhub/ehpk.ts: + * + * header "EHPK" | u16 major=1 | u16 minor=1 | u32 firstRecord=20 + * | u32 recordCount | u32 reserved=0 + * FILE E4 BA A9 BA | u32 compLen | u32 uncompLen | u16 tag=0xB701 + * | u16 nameLen | xor(path) | xor(zstd(content)) + * DIR E5 BA A9 BA | u16 tag=0xAABD | u16 nameLen | xor(path) + * FOOTER E3 BA A9 BA | sha512 of every byte before this record + * + * Paths and content are XORed with the repeating key "EVEN REALITIES". + * The manifest is stored as "app.json", project files under "dist/". + * + * Usage: node scripts/pack-ehpk.mjs [-o out.ehpk] + */ +import { readFileSync, writeFileSync, readdirSync } from "node:fs"; +import { join } from "node:path"; +import { createHash } from "node:crypto"; +import { zstdCompressSync } from "node:zlib"; + +const KEY = Buffer.from("EVEN REALITIES", "ascii"); + +function xor(buf) { + const out = Buffer.from(buf); + for (let i = 0; i < out.length; i++) out[i] ^= KEY[i % KEY.length]; + return out; +} + +function fileRecord(path, content) { + const comp = xor(zstdCompressSync(content)); + const name = xor(Buffer.from(path, "utf8")); + const head = Buffer.alloc(16); + head.writeUInt32LE(0xbaa9bae4, 0); + head.writeUInt32LE(comp.length, 4); + head.writeUInt32LE(content.length, 8); + head.writeUInt16LE(0xb701, 12); + head.writeUInt16LE(name.length, 14); + return Buffer.concat([head, name, comp]); +} + +function dirRecord(path) { + const name = xor(Buffer.from(path, "utf8")); + const head = Buffer.alloc(8); + head.writeUInt32LE(0xbaa9bae5, 0); + head.writeUInt16LE(0xaabd, 4); + head.writeUInt16LE(name.length, 6); + return Buffer.concat([head, name]); +} + +function walk(dir, archivePrefix, records) { + for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) { + if (entry.name.startsWith(".") || entry.name.endsWith(".ehpk")) continue; + const archivePath = `${archivePrefix}/${entry.name}`; + if (entry.isDirectory()) { + records.push(dirRecord(archivePath)); + walk(join(dir, entry.name), archivePath, records); + } else if (entry.isFile()) { + records.push(fileRecord(archivePath, readFileSync(join(dir, entry.name)))); + } + } +} + +const args = process.argv.slice(2); +const outIndex = args.indexOf("-o"); +const output = outIndex >= 0 ? args.splice(outIndex, 2)[1] : "out.ehpk"; +const [manifestPath, projectDir] = args; +if (!manifestPath || !projectDir) { + console.error("usage: pack-ehpk.mjs [-o out.ehpk]"); + process.exit(1); +} + +const records = [fileRecord("app.json", readFileSync(manifestPath)), dirRecord("dist")]; +walk(projectDir, "dist", records); + +const header = Buffer.alloc(20); +header.write("EHPK", 0, "ascii"); +header.writeUInt16LE(1, 4); +header.writeUInt16LE(1, 6); +header.writeUInt32LE(20, 8); +header.writeUInt32LE(records.length + 1, 12); // + footer +header.writeUInt32LE(0, 16); + +const body = Buffer.concat([header, ...records]); +const footerHead = Buffer.alloc(4); +footerHead.writeUInt32LE(0xbaa9bae3, 0); +const footer = Buffer.concat([footerHead, createHash("sha512").update(body).digest()]); +writeFileSync(output, Buffer.concat([body, footer])); +console.log(`${output}: ${records.length + 1} records, ${body.length + footer.length} bytes`); diff --git a/scripts/test/pinball-sim.js b/scripts/test/pinball-sim.js new file mode 100644 index 00000000..623796fb --- /dev/null +++ b/scripts/test/pinball-sim.js @@ -0,0 +1,302 @@ +// Headless verification harness for the pinball worker's table geometry and +// physics. Ported 1:1 from app/workers/pinball-app.worker.ts (keep in sync by +// hand if the worker changes). Renders the table plus simulated trajectories +// to grayscale PGM files and logs events/anomalies. +const fs = require("fs"); + +// --- geometry (must match worker) --- +const LEFT = 10, RIGHT = 260, TOP = 4, BOTTOM = 256, LANE_X = 232; +const BALL_R = 6; +const PLUNGER_X = (LANE_X + RIGHT) / 2, PLUNGER_Y = 240; +const GRAVITY = 240, DRAG_PER_S = 0.12, MAX_SPEED = 600, PHYSICS_DT = 1 / 120; +const LAUNCH_SPEEDS = [320, 380, 440, 500, 560]; +const BUMPER_KICK = 340, SLING_KICK = 300; +const FLIPPER_LEN = 37, FLIPPER_R = 5; +const FLIPPER_REST_DEG = 32, FLIPPER_UP_DEG = -34; +const FLIPPER_RISE_DEG_PER_S = 950, FLIPPER_FALL_DEG_PER_S = 480; +const FLIPPER_HOLD_MS = 140, FLIPPER_E = 0.4; + +function seg(x0, y0, x1, y1, e, shade = 150, kind = "wall") { + return { x0, y0, x1, y1, e, kind, shade }; +} +function chain(points, e, shade = 150) { + const out = []; + for (let i = 1; i < points.length; i++) + out.push(seg(points[i - 1][0], points[i - 1][1], points[i][0], points[i][1], e, shade)); + return out; +} +const SEGMENTS = [ + ...chain([[LEFT, BOTTOM], [LEFT, 54], [16, 24], [34, 8], [58, TOP]], 0.45, 160), + seg(58, TOP, 210, TOP, 0.45, 160), + ...chain([[210, TOP], [236, 10], [254, 26], [RIGHT, 56]], 0.35, 160), + seg(RIGHT, 56, RIGHT, BOTTOM, 0.3, 160), + seg(LANE_X, BOTTOM, RIGHT, BOTTOM, 0.3, 160), + seg(LANE_X, 66, LANE_X, BOTTOM, 0.3, 140), + seg(RIGHT, 56, 226, 68, 0.2, 90, "gate"), + seg(103, 20, 103, 46, 0.35, 130), + seg(139, 20, 139, 46, 0.35, 130), + seg(LEFT, 184, 83, 230.5, 0.35, 150), + seg(LANE_X, 184, 159, 230.5, 0.35, 150), + seg(58, 166, 84, 204, 0.4, 170, "sling"), + seg(58, 166, 58, 196, 0.4, 130), + seg(58, 196, 84, 204, 0.4, 130), + seg(184, 166, 158, 204, 0.4, 170, "sling"), + seg(184, 166, 184, 196, 0.4, 130), + seg(158, 204, 184, 196, 0.4, 130), +]; +const BUMPERS = [ + { x: 75, y: 78, r: 13 }, + { x: 167, y: 78, r: 13 }, + { x: 121, y: 128, r: 13 }, +]; +const ROLLOVERS = [{ x: 85, y: 34 }, { x: 121, y: 34 }, { x: 157, y: 34 }]; +const FLIPPER_PIVOTS = [ + { x: 76, y: 232, mirror: 1 }, + { x: 166, y: 232, mirror: -1 }, +]; + +const clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v)); + +function makeState() { + return { + ballX: PLUNGER_X, ballY: PLUNGER_Y, ballVx: 0, ballVy: 0, + flippers: FLIPPER_PIVOTS.map((p) => ({ + pivotX: p.x, pivotY: p.y, mirror: p.mirror, + angleDeg: FLIPPER_REST_DEG, state: "rest", holdUntilMs: 0, + })), + nowMs: 0, events: [], drained: false, + }; +} + +function flipperOmega(f) { + if (f.state === "rising") return (-FLIPPER_RISE_DEG_PER_S * Math.PI) / 180; + if (f.state === "falling") return (FLIPPER_FALL_DEG_PER_S * Math.PI) / 180; + return 0; +} + +function stepFlippers(s, dt) { + for (const f of s.flippers) { + switch (f.state) { + case "rising": + f.angleDeg -= FLIPPER_RISE_DEG_PER_S * dt; + if (f.angleDeg <= FLIPPER_UP_DEG) { + f.angleDeg = FLIPPER_UP_DEG; f.state = "hold"; f.holdUntilMs = s.nowMs + FLIPPER_HOLD_MS; + } + break; + case "hold": + if (s.nowMs >= f.holdUntilMs) f.state = "falling"; + break; + case "falling": + f.angleDeg += FLIPPER_FALL_DEG_PER_S * dt; + if (f.angleDeg >= FLIPPER_REST_DEG) { f.angleDeg = FLIPPER_REST_DEG; f.state = "rest"; } + break; + } + } +} + +function collideSegment(s, segment) { + const dx = segment.x1 - segment.x0, dy = segment.y1 - segment.y0; + const lengthSq = dx * dx + dy * dy; + const t = clamp(((s.ballX - segment.x0) * dx + (s.ballY - segment.y0) * dy) / lengthSq, 0, 1); + const cx = segment.x0 + t * dx, cy = segment.y0 + t * dy; + const offX = s.ballX - cx, offY = s.ballY - cy; + const dist = Math.hypot(offX, offY); + if (dist >= BALL_R || dist === 0) return; + const nx = offX / dist, ny = offY / dist; + if (segment.kind === "gate" && ny > -0.3) return; + s.ballX += nx * (BALL_R - dist); + s.ballY += ny * (BALL_R - dist); + const vn = s.ballVx * nx + s.ballVy * ny; + if (vn >= 0) return; + if (segment.kind === "sling") { + s.ballVx = s.ballVx - vn * nx + nx * SLING_KICK; + s.ballVy = s.ballVy - vn * ny + ny * SLING_KICK; + s.events.push(`${(s.nowMs / 1000).toFixed(2)}s sling`); + return; + } + s.ballVx -= (1 + segment.e) * vn * nx; + s.ballVy -= (1 + segment.e) * vn * ny; +} + +function collideFlipper(s, f) { + const angle = (f.angleDeg * Math.PI) / 180; + const dirX = f.mirror * Math.cos(angle), dirY = Math.sin(angle); + const relX = s.ballX - f.pivotX, relY = s.ballY - f.pivotY; + const t = clamp(relX * dirX + relY * dirY, 0, FLIPPER_LEN); + const cx = f.pivotX + t * dirX, cy = f.pivotY + t * dirY; + const offX = s.ballX - cx, offY = s.ballY - cy; + const dist = Math.hypot(offX, offY); + const reach = BALL_R + FLIPPER_R; + if (dist >= reach || dist === 0) return; + const nx = offX / dist, ny = offY / dist; + s.ballX += nx * (reach - dist); + s.ballY += ny * (reach - dist); + const omega = flipperOmega(f); + const surfaceVx = -t * omega * f.mirror * dirY; + const surfaceVy = t * omega * f.mirror * dirX; + const relVn = (s.ballVx - surfaceVx) * nx + (s.ballVy - surfaceVy) * ny; + if (relVn >= 0) return; + s.ballVx -= (1 + FLIPPER_E) * relVn * nx; + s.ballVy -= (1 + FLIPPER_E) * relVn * ny; +} + +function collideBumpers(s) { + for (const b of BUMPERS) { + const offX = s.ballX - b.x, offY = s.ballY - b.y; + const dist = Math.hypot(offX, offY); + const reach = BALL_R + b.r; + if (dist >= reach || dist === 0) continue; + const nx = offX / dist, ny = offY / dist; + s.ballX += nx * (reach - dist); + s.ballY += ny * (reach - dist); + const tangential = s.ballVx * -ny + s.ballVy * nx; + s.ballVx = nx * BUMPER_KICK + -ny * tangential * 0.3; + s.ballVy = ny * BUMPER_KICK + nx * tangential * 0.3; + s.events.push(`${(s.nowMs / 1000).toFixed(2)}s bumper`); + } +} + +function stepPhysics(s) { + const dt = PHYSICS_DT; + s.nowMs += dt * 1000; + stepFlippers(s, dt); + if (s.drained) return; + s.ballVy += GRAVITY * dt; + const drag = Math.max(0, 1 - DRAG_PER_S * dt); + s.ballVx *= drag; s.ballVy *= drag; + const speed = Math.hypot(s.ballVx, s.ballVy); + if (speed > MAX_SPEED) { s.ballVx *= MAX_SPEED / speed; s.ballVy *= MAX_SPEED / speed; } + s.ballX += s.ballVx * dt; + s.ballY += s.ballVy * dt; + for (let pass = 0; pass < 2; pass++) { + for (const segment of SEGMENTS) collideSegment(s, segment); + for (const f of s.flippers) collideFlipper(s, f); + collideBumpers(s); + } + if (s.ballY > BOTTOM + 2 * BALL_R || s.ballY < TOP - 40 || s.ballX < LEFT - 40 || s.ballX > RIGHT + 40) { + s.drained = true; + s.events.push(`${(s.nowMs / 1000).toFixed(2)}s DRAIN at x=${s.ballX.toFixed(0)}`); + } +} + +// --- rendering --- +const W = 276, H = 276; +function render(trailPoints, label) { + const px = new Uint8Array(W * H); + const line = (x0, y0, x1, y1, v) => { + const steps = Math.max(Math.abs(x1 - x0), Math.abs(y1 - y0)) * 2 + 1; + for (let i = 0; i <= steps; i++) { + const x = Math.round(x0 + ((x1 - x0) * i) / steps); + const y = Math.round(y0 + ((y1 - y0) * i) / steps); + if (x >= 0 && y >= 0 && x < W && y < H) px[y * W + x] = v; + } + }; + for (const s of SEGMENTS) line(s.x0, s.y0, s.x1, s.y1, s.shade); + for (const b of BUMPERS) + for (let a = 0; a < 120; a++) { + const x = Math.round(b.x + b.r * Math.cos((a / 120) * 2 * Math.PI)); + const y = Math.round(b.y + b.r * Math.sin((a / 120) * 2 * Math.PI)); + if (x >= 0 && y >= 0 && x < W && y < H) px[y * W + x] = 130; + } + for (const r of ROLLOVERS) + for (let a = 0; a < 40; a++) { + const x = Math.round(r.x + 5 * Math.cos((a / 40) * 2 * Math.PI)); + const y = Math.round(r.y + 5 * Math.sin((a / 40) * 2 * Math.PI)); + if (x >= 0 && y >= 0 && x < W && y < H) px[y * W + x] = 110; + } + for (const f of FLIPPER_PIVOTS) { + const a = (FLIPPER_REST_DEG * Math.PI) / 180; + line(f.x, f.y, f.x + f.mirror * FLIPPER_LEN * Math.cos(a), f.y + FLIPPER_LEN * Math.sin(a), 255); + } + for (const [x, y] of trailPoints) { + const xi = Math.round(x), yi = Math.round(y); + if (xi >= 0 && yi >= 0 && xi < W && yi < H) px[yi * W + xi] = Math.max(px[yi * W + xi], 220); + } + const header = Buffer.from(`P5\n${W} ${H}\n255\n`); + fs.writeFileSync(`${__dirname}/pinball-${label}.pgm`, Buffer.concat([header, Buffer.from(px)])); +} + +// --- scenarios --- +function runScenario(label, power, flipPolicy, maxSeconds = 40) { + const s = makeState(); + s.ballY = PLUNGER_Y - 2; + s.ballVy = -LAUNCH_SPEEDS[power - 1]; + const trail = []; + let stuckMs = 0, stuckReported = null, minY = 999; + const steps = Math.round(maxSeconds / PHYSICS_DT); + for (let i = 0; i < steps && !s.drained; i++) { + stepPhysics(s); + minY = Math.min(minY, s.ballY); + if (!Number.isFinite(s.ballX) || !Number.isFinite(s.ballY)) { + s.events.push(`${(s.nowMs / 1000).toFixed(2)}s NON-FINITE POSITION`); + break; + } + if (i % 4 === 0) trail.push([s.ballX, s.ballY]); + const speed = Math.hypot(s.ballVx, s.ballVy); + if (speed < 6) stuckMs += PHYSICS_DT * 1000; else stuckMs = 0; + // A slow ball near the flippers may just be trapped on one (legitimate); + // fire the flippers and only call it stuck if that fails to eject it. + if (stuckMs > 1200 && Math.round(stuckMs) % 600 < PHYSICS_DT * 1000) { + for (const f of s.flippers) if (f.state === "rest") f.state = "rising"; + } + if (stuckMs > 2500 && !stuckReported) { + stuckReported = `STUCK ~2.5s at (${s.ballX.toFixed(0)},${s.ballY.toFixed(0)})`; + s.events.push(stuckReported); + } + flipPolicy(s); + } + render(trail, label); + const outcome = s.drained ? "drained" : stuckReported ? "stuck" : "still live at timeout"; + console.log(`\n=== ${label} (power ${power}): ${outcome}, minY=${minY.toFixed(0)}, ${(s.nowMs / 1000).toFixed(1)}s sim ===`); + const counts = {}; + for (const e of s.events) { + const kind = e.split(" ")[1] || e; + counts[kind] = (counts[kind] || 0) + 1; + } + console.log("events:", JSON.stringify(counts)); + console.log("last events:", s.events.slice(-6).join(" | ")); +} + +const noFlips = () => {}; +// Flip both flippers whenever the ball descends into the flipper zone. +function reactiveFlips(s) { + if (s.ballVy > 0 && s.ballY > 195 && s.ballY < 235 && s.ballX > 55 && s.ballX < 190) { + for (const f of s.flippers) if (f.state === "rest") f.state = "rising"; + } +} + +runScenario("p1-noflip", 1, noFlips); +runScenario("p3-noflip", 3, noFlips); +runScenario("p5-noflip", 5, noFlips); +runScenario("p4-flips", 4, reactiveFlips, 90); +runScenario("p2-flips", 2, reactiveFlips, 90); + +// Randomized robustness sweep: random power, jittery/erratic flipping. +let bad = 0; +for (let run = 0; run < 30; run++) { + const power = 1 + Math.floor(Math.random() * 5); + const policy = (s) => { + if (Math.random() < 0.004) { + const f = s.flippers[Math.floor(Math.random() * 2)]; + if (f.state === "rest") f.state = "rising"; + } + reactiveFlips(s); + }; + const s = makeState(); + s.ballY = PLUNGER_Y - 2; + s.ballVy = -LAUNCH_SPEEDS[power - 1]; + let stuckMs = 0, failed = null; + for (let i = 0; i < Math.round(120 / PHYSICS_DT) && !s.drained; i++) { + stepPhysics(s); + if (!Number.isFinite(s.ballX) || !Number.isFinite(s.ballY)) { failed = "non-finite"; break; } + const speed = Math.hypot(s.ballVx, s.ballVy); + if (speed < 6) stuckMs += PHYSICS_DT * 1000; else stuckMs = 0; + if (stuckMs > 1200 && Math.round(stuckMs) % 600 < PHYSICS_DT * 1000) { + for (const f of s.flippers) if (f.state === "rest") f.state = "rising"; + } + if (stuckMs > 2500) { failed = `stuck at (${s.ballX.toFixed(0)},${s.ballY.toFixed(0)})`; break; } + policy(s); + } + if (failed) { bad++; console.log(`run ${run} power ${power}: ${failed}`); } +} +console.log(`\nrandom sweep: ${bad}/30 runs failed`); diff --git a/scripts/test/resetAndRun.sh b/scripts/test/resetAndRun.sh new file mode 100755 index 00000000..5306bbf9 --- /dev/null +++ b/scripts/test/resetAndRun.sh @@ -0,0 +1,90 @@ +#!/usr/bin/env bash +# +# resetAndRun.sh — rebuild Faceclaw and put a phone into an approximately +# never-had-faceclaw state for onboarding-flow testing, then install and +# launch the fresh build. Unlike resetOnboarding.sh this also forgets the +# glasses/ring Bluetooth pairings, and takes the target device explicitly +# (we test on several phones now, so no hardcoded default). +# +# Steps: build → uninstall → install → unpair "EVEN R1*" / "Even G2*" bonds +# → wipe app data + reset BLUETOOTH_CONNECT to undecided → launch. +# +# Usage: +# scripts/resetAndRun.sh # serial or host:port +# +# Android has no adb command to remove a Bluetooth bond, so the unpair step +# works through FaceclawDebugUnpairReceiver inside the app: we install the +# fresh build first, temporarily `pm grant` BLUETOOTH_CONNECT, broadcast the +# unpair request, then `pm clear` + revoke so the app still looks +# freshly-installed when it launches. + +set -euo pipefail + +PACKAGE="com.faceclaw.app" +UNPAIR_PREFIXES="EVEN R1,Even G2" + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +ROOT="$(dirname "$SCRIPT_DIR")" +APK="$ROOT/platforms/android/app/build/outputs/apk/debug/app-debug.apk" + +if [ $# -ne 1 ] || [ "$1" = "-h" ] || [ "$1" = "--help" ]; then + sed -n '2,20p' "$0" | sed 's/^# \{0,1\}//' + exit 2 +fi +DEVICE_ID="$1" + +# Match build.sh's tool locations so adb is on PATH even from a bare shell. +export ANDROID_HOME="${ANDROID_HOME:-/Users/jbabcock/Library/Android/sdk}" +export PATH="$ANDROID_HOME/platform-tools:$PATH" + +ADB="adb -s $DEVICE_ID" + +# Network devices (host:port) need an explicit connect first. +case "$DEVICE_ID" in + *:*) adb connect "$DEVICE_ID" >/dev/null ;; +esac + +if ! $ADB get-state >/dev/null 2>&1; then + echo "error: adb device '$DEVICE_ID' not connected." >&2 + echo " Connected devices:" >&2 + adb devices -l | sed '1d' >&2 + exit 1 +fi + +echo "==> Building..." +"$ROOT/build.sh" +[ -f "$APK" ] || { echo "error: build produced no APK at $APK" >&2; exit 1; } + +echo "==> Uninstalling $PACKAGE..." +$ADB uninstall "$PACKAGE" >/dev/null 2>&1 || echo " (was not installed)" + +echo "==> Installing $(basename "$APK")..." +$ADB install "$APK" + +echo "==> Unpairing Bluetooth devices matching: $UNPAIR_PREFIXES" +# The receiver needs BLUETOOTH_CONNECT; grant it just for this step. The +# whole remote command must be ONE quoted string — adb flattens multi-arg +# commands, which would lose the quoting around the space-containing extras. +$ADB shell pm grant "$PACKAGE" android.permission.BLUETOOTH_CONNECT +UNPAIR_OUT="$($ADB shell "am broadcast -n $PACKAGE/.FaceclawDebugUnpairReceiver \ + -a com.faceclaw.app.action.DEBUG_UNPAIR --es prefixes '$UNPAIR_PREFIXES'")" +UNPAIR_RESULT="$(printf '%s\n' "$UNPAIR_OUT" | sed -n 's/.*data="\(.*\)".*/\1/p')" +echo " ${UNPAIR_RESULT:-no result from unpair receiver: $UNPAIR_OUT}" +case "$UNPAIR_RESULT" in + error:*|"") echo " WARNING: unpair step did not run cleanly; pairings may remain." >&2 ;; +esac + +# Return the app to fresh-install state: the broadcast booted the app process +# (which may have written data), and the grant above must not leak into the +# onboarding permissions test. clear-permission-flags removes the user-set +# mark pm revoke leaves, so the permission dialog is still allowed to appear. +echo "==> Resetting app data and permissions to fresh-install state..." +$ADB shell am force-stop "$PACKAGE" +$ADB shell pm clear "$PACKAGE" >/dev/null +$ADB shell pm revoke "$PACKAGE" android.permission.BLUETOOTH_CONNECT +$ADB shell pm clear-permission-flags "$PACKAGE" \ + android.permission.BLUETOOTH_CONNECT user-set user-fixed + +echo "==> Launching..." +$ADB shell am start -n "$PACKAGE/com.tns.NativeScriptActivity" >/dev/null +echo "Done. Faceclaw should be starting its first-run onboarding." diff --git a/scripts/test/set_show_ime_with_hard_keyboard.sh b/scripts/test/set_show_ime_with_hard_keyboard.sh new file mode 100755 index 00000000..cba21b9b --- /dev/null +++ b/scripts/test/set_show_ime_with_hard_keyboard.sh @@ -0,0 +1,4 @@ +#!/bin/bash + +adb shell settings put secure show_ime_with_hard_keyboard 1 + diff --git a/stats-server/PROTOCOL.md b/stats-server/PROTOCOL.md new file mode 100644 index 00000000..9bbf699d --- /dev/null +++ b/stats-server/PROTOCOL.md @@ -0,0 +1,92 @@ +# Analytics report protocol + +The phone app (app/analytics/) sends opt-in usage statistics to +`https://stats.faceclaw.org/v1/report`, at most about once a day per install, +plus hourly retries after a failure. Nothing is sent, or kept on the phone, +while Settings > Privacy > Data collection is None. What each level collects +is described in app/analytics/analytics-store.ts and in the privacy policy +(../PRIVACY); this file is the wire format. + +## Request + +`POST /v1/report` with a JSON body of at most 64 KiB: + +```json +{ + "schema": 1, + "reportId": "0f8fad5b-d9cb-469f-a165-70867728950e", + "installId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", + "level": "minimal", + "createdAt": "2026-10-10T12:00:00.000Z", + "app": { "version": "0.8.3", "platform": "android", "build": "official" }, + "counters": { "2026-10-10": { "g2.connect-attempt": 3, "g2.session-ready": 3 } }, + "snapshot": { "device.g2.paired": true, "device.r1.paired": false } +} +``` + +- `reportId`: a random UUID per report. The phone resends a report until it + gets a 2xx, so the server stores each id once and treats repeats as + success. +- `installId`: a random UUID made when analytics is first turned on, deleted + (with everything else) when it is turned off. It ties one install's reports + together and nothing else. +- `level`: `minimal` or `full`, the setting when the report was sent. A + minimal report carries only minimal data. +- `createdAt`: when the phone sealed the report (its counters may cover + earlier days, e.g. after a failed upload). +- `app.build`: `official` (signed with the release key), `self-built` (a + release build signed with another key), `debug` (a debuggable build), or + `unknown`. +- `counters`: UTC day, then counter name (`[a-z0-9][a-z0-9_.:-]*`), then a + non-negative integer count. +- `snapshot`: state when the report was sealed, as flat keys + (`[A-Za-z0-9][A-Za-z0-9_.:-]*`) to a boolean, number or string of up to 200 + characters. + +The server ignores unknown fields and rejects (400) a report with anything +malformed or over its limits (100 days, 2000 counters, 500 snapshot keys). + +## Response + +`200 {"ok": true}` once stored (or already stored). Errors are +`{"error": "..."}` with 400 (malformed, not retried), 405, 413 (too large), +429 (rate-limited by nginx, retried) or 500 (retried). Later versions may add +fields to the 200 response, such as the latest released version for update +checks. + +## Current counters and snapshot keys + +Minimal level: + +| Name | Kind | Meaning | +| --- | --- | --- | +| `g2.connect-attempt`, `g2.session-ready` | counter | Connection attempts to the glasses, and those that got a working session | +| `g2.failure.` | counter | Transport failures that dropped or aborted a session, by reason (e.g. `ack-timeout`, `write-failed`, `glasses-not-found`, `left-arm-not-found`, `heartbeat-ack-timeout`, `cfw-recovery-retry-limit`) | +| `g2.session-end.` | counter | Working sessions ending: `failure`, `arm-drop`, `requested` | +| `g2.session-length.` | counter | How long ended sessions lasted: `under-1m`, `1m-10m`, `10m-1h`, `over-1h` | +| `g2.arm-drop.left`, `g2.arm-drop.right` | counter | An arm's BLE link dropping mid-session | +| `g2.disconnect-requested` | counter | Disconnects the app asked for | +| `g2.unpaired`, `g2.incompatible-firmware` | counter | Connections halted for a missing bond or incompatible firmware | +| `g2.ack-timeout`, `g2.cfw-replay`, `g2.cfw-nack` | counter | Recovered message-level problems | +| `g2.firmware-abnormal-exit`, `g2.firmware-system-exit` | counter | Firmware closing the app's page outside a shutdown | +| `g2.auth-unacknowledged`, `g2.even-app-conflict` | counter | Security auth not acked; write failures blamed on the Even app | +| `ring.direct.connect`, `ring.direct.disconnect` | counter | Direct (not via glasses) R1 ring links | +| `ble.gatt-status.` | counter | Android GATT connection-state callbacks with a non-success status (e.g. 8, 133) | +| `ble.ios-disconnect-error.` | counter | iOS disconnects with an error | +| `device.g2.used`, `device.g2.touchpad-used`, `device.r1.used`, `device.wear.reachable`, `device.wear.used` | counter (1 per day) | Which devices were in use that day | +| `device.g2.paired`, `device.r1.paired` | snapshot | Whether glasses and a ring are paired | +| `device.g2.preview-only` | snapshot | Whether the app is in phone-preview-only mode | +| `device.r1.connection` | snapshot | `glasses` or `direct` ring connection | + +Full level adds: + +| Name | Kind | Meaning | +| --- | --- | --- | +| `apikey.` | snapshot | Whether an API key or token of that kind is set (`anthropic`, `openai`, `elevenlabs`, `soniox`, `mapbox`, `roam`, `nightscout`, `agent-bridge`, `evenhub`), never the key | +| `config.nightscout-site` | snapshot | Whether a Nightscout site is set (not its URL) | +| `config.terminal-connections`, `config.t3code-environments` | snapshot | How many are configured | +| `config.ui-font` | snapshot | The UI font: a bundled font's name and size, `installed:` for a user-installed one, or the bitmap face | +| `setting.` | snapshot | The value of every setting chosen from fixed options (on/off and pick-one settings), by its storage key; free-text settings are never included | + +Connection counts are kept by the shared Kotlin session core +(ConnectionCounters.kt) and drained into the app's store every few minutes. diff --git a/stats-server/README.md b/stats-server/README.md new file mode 100644 index 00000000..b6dc4d25 --- /dev/null +++ b/stats-server/README.md @@ -0,0 +1,64 @@ +# stats.faceclaw.org + +Receives the opt-in analytics reports the phone app sends (format: +PROTOCOL.md) and stores them in Postgres. A small Node server with no +framework, behind nginx on the `cumulus` VPS. + + src/server.ts HTTP server: POST /v1/report, GET /healthz + src/report.ts report validation + src/db.ts storing a report + schema.sql tables and views (idempotent, applied on every deploy) + deploy.sh deploy from this working tree + deploy/ systemd unit, nginx site, env and one-time setup script + +Node runs the TypeScript directly (type stripping, Node 22.18 or later), so +there is no build step. `npm run check` type-checks; `npm test` runs the +tests. The database test needs a scratch database: +`STATS_TEST_DATABASE= npm test`, with the other `PG*` variables +pointing at its server. + +## Deploying + + ./deploy.sh + +copies this directory to `~/faceclaw-stats` on the server, installs the +dependencies, applies `schema.sql` and restarts the service. The first +time, it stops after copying, and the one-time root setup must be run there: + + ssh -t cumulus 'sudo bash ~/faceclaw-stats/deploy/setup-server.sh' + +That creates a Postgres role named after the deploy user and the +`faceclaw_stats` database on the Postgres 16 cluster (port 5433; the older +14 cluster on 5432 is left alone), installs and starts +`faceclaw-stats.service`, adds the nginx site, and gets its certificate +with certbot. It is safe to rerun. The nginx site is only installed the first +time, since certbot edits it afterwards, so later changes to +`deploy/nginx-site.conf` have to be made on the server too. + +The service runs as the deploy user with `Restart=always`, so `deploy.sh` +restarts it by ending the process, without needing root. + +## Privacy + +nginx keeps no access log for this site and the server stores only the +report body, so the database has no IP addresses. Reports carry a random +install id that the phone deletes when analytics is turned off. + +## Looking at the data + + ssh cumulus psql -p 5433 faceclaw_stats + +Views: + +- `daily_counters`: counter totals per day, split by version, platform and + build, with how many installs reported each. +- `latest_reports`: each install's most recent report. +- `latest_snapshot_values`: snapshot values across installs' latest reports. + +For example, installs and connection failures per version over the last +week: + + select app_version, name, sum(total) as total, max(installs) as installs + from daily_counters + where day > current_date - 7 and name like 'g2.failure.%' + group by 1, 2 order by 1, 3 desc; diff --git a/stats-server/deploy.sh b/stats-server/deploy.sh new file mode 100755 index 00000000..61dee686 --- /dev/null +++ b/stats-server/deploy.sh @@ -0,0 +1,32 @@ +#!/bin/bash +# Deploys the stats server from this working tree to the VPS: copies the +# sources to ~/faceclaw-stats, installs dependencies and, once the one-time +# root setup (deploy/setup-server.sh) has been done, applies schema.sql and +# restarts the service. Set FACECLAW_STATS_HOST to deploy somewhere other +# than the `cumulus` ssh host. +set -euo pipefail +cd "$(dirname "$0")" +HOST="${FACECLAW_STATS_HOST:-cumulus}" +DIR=faceclaw-stats + +rsync -az --delete --exclude node_modules --exclude .DS_Store ./ "$HOST:$DIR/" +ssh "$HOST" bash -s -- "$DIR" "$HOST" <<'REMOTE' +set -euo pipefail +cd "$HOME/$1" +export NVM_DIR="$HOME/.nvm" +. "$NVM_DIR/nvm.sh" >/dev/null +nvm use 22 >/dev/null +npm ci --omit=dev --no-audit --no-fund --loglevel=error --no-update-notifier +if [ ! -f /etc/systemd/system/faceclaw-stats.service ]; then + echo "Copied. Now run the one-time setup: ssh -t $2 'sudo bash ~/$1/deploy/setup-server.sh'" + exit 0 +fi +set -a; . deploy/stats.env; set +a +psql -v ON_ERROR_STOP=1 -q -f schema.sql +# The service runs as this user with Restart=always, so ending the process +# restarts it on the new code without needing root. +pkill -TERM -u "$USER" -f "$PWD/src/server.ts" || true +sleep 3 +systemctl is-active faceclaw-stats +curl -fsS "http://127.0.0.1:$PORT/healthz" && echo +REMOTE diff --git a/stats-server/deploy/faceclaw-stats.service b/stats-server/deploy/faceclaw-stats.service new file mode 100644 index 00000000..fe99c2ff --- /dev/null +++ b/stats-server/deploy/faceclaw-stats.service @@ -0,0 +1,21 @@ +# Template: setup-server.sh fills in @USER@ and @DIR@ and installs it as +# /etc/systemd/system/faceclaw-stats.service. +[Unit] +Description=Faceclaw stats server (stats.faceclaw.org) +After=network.target postgresql.service + +[Service] +Type=simple +User=@USER@ +WorkingDirectory=@DIR@ +EnvironmentFile=@DIR@/deploy/stats.env +ExecStart=@DIR@/deploy/run.sh +# deploy.sh restarts the server by ending the process. +Restart=always +RestartSec=2 +NoNewPrivileges=yes +PrivateTmp=yes +ProtectSystem=full + +[Install] +WantedBy=multi-user.target diff --git a/stats-server/deploy/nginx-site.conf b/stats-server/deploy/nginx-site.conf new file mode 100644 index 00000000..d2e12199 --- /dev/null +++ b/stats-server/deploy/nginx-site.conf @@ -0,0 +1,33 @@ +# stats.faceclaw.org, installed by setup-server.sh as +# /etc/nginx/sites-available/stats.faceclaw.org. certbot then adds the TLS +# server block and the HTTP-to-HTTPS redirect to the installed copy, so +# setup-server.sh never overwrites it; make later changes on the server too. + +limit_req_zone $binary_remote_addr zone=faceclaw_stats:1m rate=10r/m; + +server { + listen 80; + server_name stats.faceclaw.org; + + # Reports are anonymous: don't keep the IP addresses they come from. + access_log off; + limit_req_log_level notice; + client_max_body_size 64k; + + location = /v1/report { + limit_req zone=faceclaw_stats burst=20 nodelay; + limit_req_status 429; + proxy_pass http://127.0.0.1:8290; + proxy_http_version 1.1; + proxy_set_header Host $host; + } + + location = /healthz { + proxy_pass http://127.0.0.1:8290; + } + + location / { + default_type text/plain; + return 200 "Faceclaw's opt-in usage statistics endpoint. See https://faceclaw.org/privacy.html\n"; + } +} diff --git a/stats-server/deploy/run.sh b/stats-server/deploy/run.sh new file mode 100755 index 00000000..54eb5517 --- /dev/null +++ b/stats-server/deploy/run.sh @@ -0,0 +1,9 @@ +#!/bin/bash +# Started by faceclaw-stats.service, with deploy/stats.env in the environment. +# Node comes from nvm, as for the other services on this host. +cd "$(dirname "$0")/.." +export NVM_DIR="$HOME/.nvm" +. "$NVM_DIR/nvm.sh" +nvm use 22 >/dev/null +# The absolute path lets deploy.sh find this process to restart it. +exec node "$PWD/src/server.ts" diff --git a/stats-server/deploy/setup-server.sh b/stats-server/deploy/setup-server.sh new file mode 100755 index 00000000..b783ae2b --- /dev/null +++ b/stats-server/deploy/setup-server.sh @@ -0,0 +1,57 @@ +#!/bin/bash +# One-time root setup for the stats server on the VPS; safe to rerun. Run it +# via sudo, as the user that owns the deployed copy (deploy.sh puts it there): +# +# ssh -t cumulus 'sudo bash ~/faceclaw-stats/deploy/setup-server.sh' +# +# It creates a Postgres role (named after that user, so the service and +# psql connect by peer auth) and the database on the cluster in stats.env, +# installs and starts the systemd service, adds the nginx site, and gets the +# site's Let's Encrypt certificate with certbot. +set -euo pipefail +[ "$(id -u)" = 0 ] || { echo "Run this with sudo." >&2; exit 1; } +DEPLOY_USER="${SUDO_USER:?Run this via sudo from the user that owns the deployed copy.}" +DIR="$(cd "$(dirname "$0")/.." && pwd)" +DOMAIN=stats.faceclaw.org +set -a; . "$DIR/deploy/stats.env"; set +a +cd / + +echo "== Postgres: role $DEPLOY_USER, database $PGDATABASE (port $PGPORT)" +pg_lsclusters --no-header | awk -v port="$PGPORT" '$3 == port && $4 == "online" { found = 1 } END { exit !found }' \ + || { echo "No online Postgres cluster on port $PGPORT." >&2; exit 1; } +sudo -u postgres psql -p "$PGPORT" -v ON_ERROR_STOP=1 -q -c \ + "do \$\$ begin if not exists (select from pg_roles where rolname = '$DEPLOY_USER') then create role \"$DEPLOY_USER\" login; end if; end \$\$;" +if ! sudo -u postgres psql -p "$PGPORT" -Atc "select 1 from pg_database where datname = '$PGDATABASE'" | grep -q 1; then + sudo -u postgres createdb -p "$PGPORT" -O "$DEPLOY_USER" "$PGDATABASE" +fi +sudo -u "$DEPLOY_USER" psql -h "$PGHOST" -p "$PGPORT" -d "$PGDATABASE" -v ON_ERROR_STOP=1 -q -f "$DIR/schema.sql" + +echo "== systemd: faceclaw-stats.service" +[ -d "$DIR/node_modules" ] || { echo "No node_modules in $DIR; run deploy.sh first." >&2; exit 1; } +sed -e "s|@USER@|$DEPLOY_USER|g" -e "s|@DIR@|$DIR|g" "$DIR/deploy/faceclaw-stats.service" \ + > /etc/systemd/system/faceclaw-stats.service +systemctl daemon-reload +systemctl enable faceclaw-stats.service +systemctl restart faceclaw-stats.service + +echo "== nginx: $DOMAIN" +SITE="/etc/nginx/sites-available/$DOMAIN" +# certbot edits the installed copy, so only install it the first time. +[ -e "$SITE" ] || cp "$DIR/deploy/nginx-site.conf" "$SITE" +ln -sf "$SITE" "/etc/nginx/sites-enabled/$DOMAIN" +if ! nginx -t; then + # Don't leave a broken site enabled: it would block reloads for every site. + rm -f "/etc/nginx/sites-enabled/$DOMAIN" + echo "nginx rejected the site config; it has been disabled again." >&2 + exit 1 +fi +systemctl reload nginx + +echo "== TLS certificate" +if [ ! -d "/etc/letsencrypt/live/$DOMAIN" ]; then + certbot --nginx -d "$DOMAIN" --non-interactive --redirect +fi + +echo "== Checking https://$DOMAIN/healthz" +sleep 2 +curl -fsS "https://$DOMAIN/healthz" && echo diff --git a/stats-server/deploy/stats.env b/stats-server/deploy/stats.env new file mode 100644 index 00000000..550c00e8 --- /dev/null +++ b/stats-server/deploy/stats.env @@ -0,0 +1,7 @@ +# Server settings, read by the systemd unit (EnvironmentFile) and sourced by +# setup-server.sh and deploy.sh. The database is on the Postgres 16 cluster +# (port 5433); the server's older 14 cluster on 5432 is left alone. +PORT=8290 +PGHOST=/var/run/postgresql +PGPORT=5433 +PGDATABASE=faceclaw_stats diff --git a/stats-server/package-lock.json b/stats-server/package-lock.json new file mode 100644 index 00000000..a74d0fdd --- /dev/null +++ b/stats-server/package-lock.json @@ -0,0 +1,211 @@ +{ + "name": "faceclaw-stats-server", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "faceclaw-stats-server", + "license": "GPL-3.0-or-later", + "dependencies": { + "pg": "^8.16.3" + }, + "devDependencies": { + "@types/node": "^22.18.0", + "@types/pg": "^8.15.5", + "typescript": "~5.9.0" + }, + "engines": { + "node": ">=22.18" + } + }, + "node_modules/@types/node": { + "version": "22.20.5", + "resolved": "https://registry.npmjs.org/@types/node/-/node-22.20.5.tgz", + "integrity": "sha512-U2+DNr+wSjpsTS/wZGYHq7GcwfuSmKiKvoPvK22zwTlRhU91yOniN4qRR5KhIjvif7ysw/dz/hKmfDH0Ris4aA==", + "dev": true, + "license": "MIT", + "dependencies": { + "undici-types": "~6.21.0" + } + }, + "node_modules/@types/pg": { + "version": "8.23.1", + "resolved": "https://registry.npmjs.org/@types/pg/-/pg-8.23.1.tgz", + "integrity": "sha512-fKVHpikPdg4GKks3JuLEhvwSyvwzF23hnabPy6DD8ljVbC7+6J5dQzdv4arV6jqq57djnMgs1HKBxX4P8aBI3A==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/node": "*", + "pg-protocol": "*", + "pg-types": "^2.2.0" + } + }, + "node_modules/pg": { + "version": "8.23.1", + "resolved": "https://registry.npmjs.org/pg/-/pg-8.23.1.tgz", + "integrity": "sha512-aL96AHANtWjPLDOLqnhx+ngp9+UK7ETEU8VJrDCGvsSSi/mGLcWYsS6Herg7lmaBJe4uwrfqsa7gTEFaSizDoQ==", + "license": "MIT", + "dependencies": { + "pg-connection-string": "^2.14.1", + "pg-pool": "^3.14.0", + "pg-protocol": "^1.16.1", + "pg-types": "2.2.0", + "pgpass": "1.0.5" + }, + "engines": { + "node": ">= 16.0.0" + }, + "optionalDependencies": { + "pg-cloudflare": "^1.4.1" + }, + "peerDependencies": { + "pg-native": ">=3.0.1" + }, + "peerDependenciesMeta": { + "pg-native": { + "optional": true + } + } + }, + "node_modules/pg-cloudflare": { + "version": "1.4.1", + "resolved": "https://registry.npmjs.org/pg-cloudflare/-/pg-cloudflare-1.4.1.tgz", + "integrity": "sha512-6PQbsFWZcp9EmJEwy5cGQ2La+AMWpP46lgbb8X+U/XsHIUweYDNCpeuKck5RxL2MdVFi7krbbEi5nX4Zh7JhrQ==", + "license": "MIT", + "optional": true + }, + "node_modules/pg-connection-string": { + "version": "2.14.1", + "resolved": "https://registry.npmjs.org/pg-connection-string/-/pg-connection-string-2.14.1.tgz", + "integrity": "sha512-qR3kGNPBLpCNtz0evbKA0Y/MRFXwSSdT+pTJvYp/bXTcReZbvX1kzF0IyTc1QnxqF7AZbOeBhNL8R5mYQZV/MA==", + "license": "MIT" + }, + "node_modules/pg-int8": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/pg-int8/-/pg-int8-1.0.1.tgz", + "integrity": "sha512-WCtabS6t3c8SkpDBUlb1kjOs7l66xsGdKpIPZsg4wR+B3+u9UAum2odSsF9tnvxg80h4ZxLWMy4pRjOsFIqQpw==", + "license": "ISC", + "engines": { + "node": ">=4.0.0" + } + }, + "node_modules/pg-pool": { + "version": "3.14.0", + "resolved": "https://registry.npmjs.org/pg-pool/-/pg-pool-3.14.0.tgz", + "integrity": "sha512-gKtPkFdQPU3DksooVLi9LsjZxrsBUZIpa+7aVx+LV5pNh0KzP4Zleud2po+ConrxbuXGBJ6Hfer6hdgpIBpBaw==", + "license": "MIT", + "peerDependencies": { + "pg": ">=8.0" + } + }, + "node_modules/pg-protocol": { + "version": "1.16.1", + "resolved": "https://registry.npmjs.org/pg-protocol/-/pg-protocol-1.16.1.tgz", + "integrity": "sha512-p9VOFMiHB/ZbJATetbg+99PxssTVSQRnyuPSQ67mN1+1KBOjZaZ83ZQzltnxPhJwSsC3nwVjJ10DVJlerbFzLg==", + "license": "MIT" + }, + "node_modules/pg-types": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/pg-types/-/pg-types-2.2.0.tgz", + "integrity": "sha512-qTAAlrEsl8s4OiEQY69wDvcMIdQN6wdz5ojQiOy6YRMuynxenON0O5oCpJI6lshc6scgAY8qvJ2On/p+CXY0GA==", + "license": "MIT", + "dependencies": { + "pg-int8": "1.0.1", + "postgres-array": "~2.0.0", + "postgres-bytea": "~1.0.0", + "postgres-date": "~1.0.4", + "postgres-interval": "^1.1.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/pgpass": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/pgpass/-/pgpass-1.0.5.tgz", + "integrity": "sha512-FdW9r/jQZhSeohs1Z3sI1yxFQNFvMcnmfuj4WBMUTxOrAyLMaTcE1aAMBiTlbMNaXvBCQuVi0R7hd8udDSP7ug==", + "license": "MIT", + "dependencies": { + "split2": "^4.1.0" + } + }, + "node_modules/postgres-array": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/postgres-array/-/postgres-array-2.0.0.tgz", + "integrity": "sha512-VpZrUqU5A69eQyW2c5CA1jtLecCsN2U/bD6VilrFDWq5+5UIEVO7nazS3TEcHf1zuPYO/sqGvUvW62g86RXZuA==", + "license": "MIT", + "engines": { + "node": ">=4" + } + }, + "node_modules/postgres-bytea": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/postgres-bytea/-/postgres-bytea-1.0.1.tgz", + "integrity": "sha512-5+5HqXnsZPE65IJZSMkZtURARZelel2oXUEO8rH83VS/hxH5vv1uHquPg5wZs8yMAfdv971IU+kcPUczi7NVBQ==", + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/postgres-date": { + "version": "1.0.7", + "resolved": "https://registry.npmjs.org/postgres-date/-/postgres-date-1.0.7.tgz", + "integrity": "sha512-suDmjLVQg78nMK2UZ454hAG+OAW+HQPZ6n++TNDUX+L0+uUlLywnoxJKDou51Zm+zTCjrCl0Nq6J9C5hP9vK/Q==", + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/postgres-interval": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/postgres-interval/-/postgres-interval-1.2.0.tgz", + "integrity": "sha512-9ZhXKM/rw350N1ovuWHbGxnGh/SNJ4cnxHiM0rxE4VN41wsg8P8zWn9hv/buK00RP4WvlOyr/RBDiptyxVbkZQ==", + "license": "MIT", + "dependencies": { + "xtend": "^4.0.0" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/split2": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/split2/-/split2-4.2.0.tgz", + "integrity": "sha512-UcjcJOWknrNkF6PLX83qcHM6KHgVKNkV62Y8a5uYDVv9ydGQVwAHMKqHdJje1VTWpljG0WYpCDhrCdAOYH4TWg==", + "license": "ISC", + "engines": { + "node": ">= 10.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/undici-types": { + "version": "6.21.0", + "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz", + "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/xtend": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/xtend/-/xtend-4.0.2.tgz", + "integrity": "sha512-LKYU1iAXJXUgAXn9URjiu+MWhyUXHsvfp7mcuYm9dSUKK0/CjtrUwFAxD82/mCWbtLsGjFIad0wIsod4zrTAEQ==", + "license": "MIT", + "engines": { + "node": ">=0.4" + } + } + } +} diff --git a/stats-server/package.json b/stats-server/package.json new file mode 100644 index 00000000..cbf3e941 --- /dev/null +++ b/stats-server/package.json @@ -0,0 +1,23 @@ +{ + "name": "faceclaw-stats-server", + "private": true, + "description": "Receives Faceclaw's opt-in analytics reports at stats.faceclaw.org and stores them in Postgres.", + "license": "GPL-3.0-or-later", + "type": "module", + "engines": { + "node": ">=22.18" + }, + "scripts": { + "start": "node src/server.ts", + "check": "tsc -p tsconfig.json", + "test": "node --test test/*.test.ts" + }, + "dependencies": { + "pg": "^8.16.3" + }, + "devDependencies": { + "@types/node": "^22.18.0", + "@types/pg": "^8.15.5", + "typescript": "~5.9.0" + } +} diff --git a/stats-server/schema.sql b/stats-server/schema.sql new file mode 100644 index 00000000..3144529c --- /dev/null +++ b/stats-server/schema.sql @@ -0,0 +1,57 @@ +-- Schema for the analytics reports (PROTOCOL.md). Idempotent: deploy.sh +-- applies it on every deploy, so changes must be written as additive +-- `if not exists` / `create or replace` statements. + +create table if not exists reports ( + report_id uuid primary key, + install_id uuid not null, + received_at timestamptz not null default now(), + created_at timestamptz not null, + schema_version integer not null, + level text not null, + app_version text not null, + platform text not null, + build text not null, + -- The validated report as received, for anything the tables below don't cover. + payload jsonb not null +); +create index if not exists reports_received_at_idx on reports (received_at); +create index if not exists reports_install_idx on reports (install_id, received_at); + +create table if not exists report_counters ( + report_id uuid not null references reports (report_id) on delete cascade, + day date not null, + name text not null, + value bigint not null, + primary key (report_id, day, name) +); +create index if not exists report_counters_day_name_idx on report_counters (day, name); + +create table if not exists report_snapshot ( + report_id uuid not null references reports (report_id) on delete cascade, + key text not null, + value jsonb not null, + primary key (report_id, key) +); + +-- Counter totals per day, split by version, platform and build, with how +-- many installs reported each. +create or replace view daily_counters as +select r.app_version, r.platform, r.build, c.day, c.name, + sum(c.value) as total, count(distinct r.install_id) as installs +from report_counters c +join reports r using (report_id) +group by r.app_version, r.platform, r.build, c.day, c.name; + +-- Each install's most recent report. +create or replace view latest_reports as +select distinct on (install_id) * +from reports +order by install_id, received_at desc; + +-- Snapshot values from each install's most recent report, counted. +create or replace view latest_snapshot_values as +select r.app_version, r.platform, s.key, s.value, count(*) as installs +from latest_reports r +join report_snapshot s using (report_id) +group by r.app_version, r.platform, s.key, s.value; diff --git a/stats-server/src/db.ts b/stats-server/src/db.ts new file mode 100644 index 00000000..8e638ead --- /dev/null +++ b/stats-server/src/db.ts @@ -0,0 +1,69 @@ +import type { Pool } from "pg"; +import type { Report } from "./report.ts"; + +/** + * Stores one report and its rows in a single transaction. The phone keeps + * resending a report until it sees a 2xx, so a report id that is already + * stored is a retry whose response was lost, not new data. + */ +export async function saveReport(pool: Pool, report: Report): Promise<"saved" | "duplicate"> { + const client = await pool.connect(); + try { + await client.query("begin"); + const inserted = await client.query( + `insert into reports + (report_id, install_id, created_at, schema_version, level, app_version, platform, build, payload) + values ($1, $2, $3, $4, $5, $6, $7, $8, $9) + on conflict (report_id) do nothing`, + [ + report.reportId, + report.installId, + report.createdAt, + report.schema, + report.level, + report.app.version, + report.app.platform, + report.app.build, + JSON.stringify(report), + ], + ); + if (inserted.rowCount === 0) { + await client.query("rollback"); + return "duplicate"; + } + + const days: string[] = []; + const names: string[] = []; + const values: number[] = []; + for (const [day, counts] of Object.entries(report.counters)) { + for (const [name, value] of Object.entries(counts)) { + days.push(day); + names.push(name); + values.push(value); + } + } + if (names.length) { + await client.query( + `insert into report_counters (report_id, day, name, value) + select $1, day::date, name, value from unnest($2::text[], $3::text[], $4::bigint[]) as t(day, name, value)`, + [report.reportId, days, names, values], + ); + } + + const keys = Object.keys(report.snapshot); + if (keys.length) { + await client.query( + `insert into report_snapshot (report_id, key, value) + select $1, key, value from unnest($2::text[], $3::jsonb[]) as t(key, value)`, + [report.reportId, keys, keys.map((key) => JSON.stringify(report.snapshot[key]))], + ); + } + await client.query("commit"); + return "saved"; + } catch (error) { + await client.query("rollback").catch(() => undefined); + throw error; + } finally { + client.release(); + } +} diff --git a/stats-server/src/report.ts b/stats-server/src/report.ts new file mode 100644 index 00000000..d7080116 --- /dev/null +++ b/stats-server/src/report.ts @@ -0,0 +1,126 @@ +/** + * The analytics report format the phone app uploads (PROTOCOL.md), and its + * validation. The app-side producer is app/analytics/analytics-report.ts; + * keep the two in step. + * + * Everything is checked against tight limits so a malformed or hostile + * client can't store much: unknown fields are ignored, and anything + * out of range rejects the whole report. + */ + +export const REPORT_SCHEMA_VERSION = 1; + +export type ReportLevel = "minimal" | "full"; +export type SnapshotValue = boolean | number | string; + +export interface Report { + schema: number; + reportId: string; + installId: string; + level: ReportLevel; + /** When the phone sealed the report (ISO 8601). */ + createdAt: string; + app: { version: string; platform: string; build: string }; + /** UTC day (YYYY-MM-DD) → counter name → count. */ + counters: Record>; + /** Point-in-time state (devices, API-key presence, settings), flat namespaced keys. */ + snapshot: Record; +} + +export class ReportError extends Error {} + +const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/; +const VERSION = /^[0-9A-Za-z.+-]{1,32}$/; +const TOKEN = /^[a-z0-9-]{1,24}$/; +const DAY = /^\d{4}-\d{2}-\d{2}$/; +const COUNTER_NAME = /^[a-z0-9][a-z0-9_.:-]{0,119}$/; +// Snapshot keys embed the app's settings keys, which are camelCase. +const SNAPSHOT_KEY = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,119}$/; + +const MAX_DAYS = 100; +const MAX_COUNTERS = 2000; +const MAX_COUNT = 1_000_000_000; +const MAX_SNAPSHOT_KEYS = 500; +const MAX_SNAPSHOT_STRING = 200; + +export function parseReport(value: unknown): Report { + const body = record(value, "report"); + if (body.schema !== REPORT_SCHEMA_VERSION) throw new ReportError(`unsupported schema ${String(body.schema)}`); + const level = body.level; + if (level !== "minimal" && level !== "full") throw new ReportError("bad level"); + const app = record(body.app, "app"); + return { + schema: REPORT_SCHEMA_VERSION, + reportId: uuid(body.reportId, "reportId"), + installId: uuid(body.installId, "installId"), + level, + createdAt: timestamp(body.createdAt, "createdAt"), + app: { + version: matching(app.version, VERSION, "app.version"), + platform: matching(app.platform, TOKEN, "app.platform"), + build: matching(app.build, TOKEN, "app.build"), + }, + counters: counters(body.counters ?? {}), + snapshot: snapshot(body.snapshot ?? {}), + }; +} + +function counters(value: unknown): Report["counters"] { + const days = record(value, "counters"); + const dayKeys = Object.keys(days); + if (dayKeys.length > MAX_DAYS) throw new ReportError("too many days"); + const result: Report["counters"] = {}; + let total = 0; + for (const day of dayKeys) { + if (!DAY.test(day) || Number.isNaN(Date.parse(`${day}T00:00:00Z`))) throw new ReportError(`bad day ${day}`); + const entries = record(days[day], `counters.${day}`); + const counts: Record = {}; + for (const [name, count] of Object.entries(entries)) { + if (!COUNTER_NAME.test(name)) throw new ReportError(`bad counter name ${name}`); + if (typeof count !== "number" || !Number.isSafeInteger(count) || count < 0 || count > MAX_COUNT) { + throw new ReportError(`bad count for ${name}`); + } + if (++total > MAX_COUNTERS) throw new ReportError("too many counters"); + counts[name] = count; + } + result[day] = counts; + } + return result; +} + +function snapshot(value: unknown): Report["snapshot"] { + const entries = Object.entries(record(value, "snapshot")); + if (entries.length > MAX_SNAPSHOT_KEYS) throw new ReportError("too many snapshot keys"); + const result: Report["snapshot"] = {}; + for (const [key, item] of entries) { + if (!SNAPSHOT_KEY.test(key)) throw new ReportError(`bad snapshot key ${key}`); + const ok = + typeof item === "boolean" || + (typeof item === "number" && Number.isFinite(item)) || + (typeof item === "string" && item.length <= MAX_SNAPSHOT_STRING); + if (!ok) throw new ReportError(`bad snapshot value for ${key}`); + result[key] = item; + } + return result; +} + +function record(value: unknown, what: string): Record { + if (typeof value !== "object" || value === null || Array.isArray(value)) throw new ReportError(`${what} must be an object`); + return value as Record; +} + +function uuid(value: unknown, what: string): string { + const text = typeof value === "string" ? value.toLowerCase() : ""; + if (!UUID.test(text)) throw new ReportError(`bad ${what}`); + return text; +} + +function matching(value: unknown, pattern: RegExp, what: string): string { + if (typeof value !== "string" || !pattern.test(value)) throw new ReportError(`bad ${what}`); + return value; +} + +function timestamp(value: unknown, what: string): string { + if (typeof value !== "string" || value.length > 40 || Number.isNaN(Date.parse(value))) throw new ReportError(`bad ${what}`); + return new Date(value).toISOString(); +} diff --git a/stats-server/src/server.ts b/stats-server/src/server.ts new file mode 100644 index 00000000..e7a99da4 --- /dev/null +++ b/stats-server/src/server.ts @@ -0,0 +1,91 @@ +import { createServer, type IncomingMessage, type ServerResponse } from "node:http"; +import { Pool } from "pg"; +import { saveReport } from "./db.ts"; +import { parseReport, ReportError } from "./report.ts"; + +/** + * Receives the phone app's daily analytics reports (PROTOCOL.md) and stores + * them in Postgres. Runs behind nginx, which terminates TLS and rate-limits; + * the database connection comes from the standard PG* environment variables. + * + * Nothing about the request itself is stored or logged: no IP address, no + * headers, only the report body. + */ + +const PORT = Number(process.env.PORT ?? 8290); +const HOST = process.env.HOST ?? "127.0.0.1"; +const MAX_BODY_BYTES = 64 * 1024; + +const pool = new Pool({ max: 4 }); +pool.on("error", (error) => console.error("idle database client failed:", error.message)); + +const server = createServer((request, response) => { + handle(request, response).catch((error: unknown) => { + console.error("request failed:", error instanceof Error ? error.message : error); + if (!response.headersSent) reply(response, 500, { error: "internal error" }); + }); +}); + +async function handle(request: IncomingMessage, response: ServerResponse): Promise { + const path = (request.url ?? "/").split("?")[0]; + if (path === "/v1/report") { + if (request.method !== "POST") return reply(response, 405, { error: "POST only" }); + if (Number(request.headers["content-length"] ?? 0) > MAX_BODY_BYTES) { + response.setHeader("connection", "close"); + return reply(response, 413, { error: "too large" }); + } + const body = await readBody(request); + if (body === null) return reply(response, 413, { error: "too large" }); + let report; + try { + report = parseReport(JSON.parse(body)); + } catch (error) { + if (error instanceof SyntaxError || error instanceof ReportError) { + return reply(response, 400, { error: error.message }); + } + throw error; + } + await saveReport(pool, report); + // Room for more later (e.g. the latest released version, for update checks). + return reply(response, 200, { ok: true }); + } + if (path === "/healthz" && request.method === "GET") { + await pool.query("select 1"); + return reply(response, 200, { ok: true }); + } + reply(response, 404, { error: "not found" }); +} + +/** + * The request body as text, or null if it is over MAX_BODY_BYTES. An + * oversized body is still read to the end (and dropped) so the client gets + * the 413 instead of a reset connection; nginx caps it before it gets here. + */ +function readBody(request: IncomingMessage): Promise { + return new Promise((resolve, reject) => { + const chunks: Buffer[] = []; + let size = 0; + request.on("data", (chunk: Buffer) => { + size += chunk.length; + if (size <= MAX_BODY_BYTES) chunks.push(chunk); + }); + request.on("end", () => resolve(size > MAX_BODY_BYTES ? null : Buffer.concat(chunks).toString("utf8"))); + request.on("error", reject); + }); +} + +function reply(response: ServerResponse, status: number, body: object): void { + response.writeHead(status, { "content-type": "application/json", "cache-control": "no-store" }); + response.end(JSON.stringify(body)); +} + +function shutdown(): void { + server.close(() => { + void pool.end().finally(() => process.exit(0)); + }); + setTimeout(() => process.exit(0), 5000).unref(); +} +process.on("SIGTERM", shutdown); +process.on("SIGINT", shutdown); + +server.listen(PORT, HOST, () => console.log(`faceclaw-stats listening on ${HOST}:${PORT}`)); diff --git a/stats-server/test/db.test.ts b/stats-server/test/db.test.ts new file mode 100644 index 00000000..31957b36 --- /dev/null +++ b/stats-server/test/db.test.ts @@ -0,0 +1,43 @@ +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { test } from "node:test"; +import { Pool } from "pg"; +import { saveReport } from "../src/db.ts"; +import { parseReport } from "../src/report.ts"; +import { sampleReport } from "./sample.ts"; + +// Needs a scratch database: set STATS_TEST_DATABASE to its name (the other +// PG* variables pick the server). The tables are created if missing, and +// emptied before the test. +const database = process.env.STATS_TEST_DATABASE; + +void test("stores a report once, with its counters and snapshot", { skip: !database && "STATS_TEST_DATABASE not set" }, async () => { + const pool = new Pool({ database }); + try { + await pool.query(readFileSync(new URL("../schema.sql", import.meta.url), "utf8")); + await pool.query("truncate reports cascade"); + + const report = parseReport(sampleReport()); + assert.equal(await saveReport(pool, report), "saved"); + assert.equal(await saveReport(pool, report), "duplicate"); + + const counters = await pool.query( + "select day::text, name, value::int from report_counters order by day, name", + ); + assert.deepEqual(counters.rows, [ + { day: "2026-10-09", name: "g2.connect", value: 3 }, + { day: "2026-10-09", name: "g2.disconnect", value: 2 }, + { day: "2026-10-10", name: "g2.connect", value: 1 }, + ]); + const snapshot = await pool.query("select key, value from report_snapshot order by key"); + assert.deepEqual(snapshot.rows, [ + { key: "apikey.anthropic", value: false }, + { key: "device.g2.paired", value: true }, + { key: "setting.ui-font", value: "Roboto-Light.ttf:16" }, + ]); + const daily = await pool.query("select total::int, installs::int from daily_counters where name = 'g2.connect' and day = '2026-10-09'"); + assert.deepEqual(daily.rows, [{ total: 3, installs: 1 }]); + } finally { + await pool.end(); + } +}); diff --git a/stats-server/test/report.test.ts b/stats-server/test/report.test.ts new file mode 100644 index 00000000..da78cdba --- /dev/null +++ b/stats-server/test/report.test.ts @@ -0,0 +1,61 @@ +import assert from "node:assert/strict"; +import { test } from "node:test"; +import { parseReport, ReportError } from "../src/report.ts"; +import { sampleReport } from "./sample.ts"; + +void test("accepts a well-formed report and normalizes ids and timestamps", () => { + const report = parseReport( + sampleReport({ reportId: "0F8FAD5B-D9CB-469F-A165-70867728950E", createdAt: "2026-10-10T08:00:00-04:00" }), + ); + assert.equal(report.reportId, "0f8fad5b-d9cb-469f-a165-70867728950e"); + assert.equal(report.createdAt, "2026-10-10T12:00:00.000Z"); + assert.deepEqual(report.counters["2026-10-09"], { "g2.connect": 3, "g2.disconnect": 2 }); + assert.equal(report.snapshot["setting.ui-font"], "Roboto-Light.ttf:16"); +}); + +void test("accepts camelCase snapshot keys but only lowercase counter names", () => { + assert.equal(parseReport(sampleReport({ snapshot: { "setting.display.timeFormat": "12h" } })).snapshot["setting.display.timeFormat"], "12h"); + assert.throws(() => parseReport(sampleReport({ counters: { "2026-10-10": { "g2.Connect": 1 } } })), ReportError); +}); + +void test("ignores unknown fields", () => { + const report = parseReport(sampleReport({ extra: "x" })); + assert.equal("extra" in report, false); +}); + +void test("rejects malformed reports", () => { + const bad: Record[] = [ + { schema: 2 }, + { level: "everything" }, + { reportId: "not-a-uuid" }, + { app: { version: "0.8.3; drop table", platform: "android", build: "official" } }, + { app: { version: "0.8.3", platform: "Android", build: "official" } }, + { createdAt: "yesterday" }, + { counters: { "2026-13-45": { a: 1 } } }, + { counters: { "2026-10-10": { "Bad Name": 1 } } }, + { counters: { "2026-10-10": { a: -1 } } }, + { counters: { "2026-10-10": { a: 1.5 } } }, + { counters: [] }, + { snapshot: { a: { nested: true } } }, + { snapshot: { "bad key": true } }, + { snapshot: { a: "x".repeat(201) } }, + { snapshot: { a: Number.NaN } }, + ]; + for (const overrides of bad) { + assert.throws(() => parseReport(sampleReport(overrides)), ReportError, JSON.stringify(overrides)); + } + assert.throws(() => parseReport(null), ReportError); + assert.throws(() => parseReport([]), ReportError); +}); + +void test("caps how many counters and snapshot keys a report may carry", () => { + const manyDays: Record> = {}; + for (let day = 0; day < 101; day++) { + manyDays[new Date(Date.UTC(2026, 0, 1 + day)).toISOString().slice(0, 10)] = { a: 1 }; + } + assert.throws(() => parseReport(sampleReport({ counters: manyDays })), /too many days/); + + const manyKeys: Record = {}; + for (let index = 0; index < 501; index++) manyKeys[`k${index}`] = true; + assert.throws(() => parseReport(sampleReport({ snapshot: manyKeys })), /too many snapshot keys/); +}); diff --git a/stats-server/test/sample.ts b/stats-server/test/sample.ts new file mode 100644 index 00000000..f0b8b329 --- /dev/null +++ b/stats-server/test/sample.ts @@ -0,0 +1,14 @@ +/** A valid report body, with top-level fields replaced by `overrides`. */ +export function sampleReport(overrides: Record = {}): Record { + return { + schema: 1, + reportId: "0f8fad5b-d9cb-469f-a165-70867728950e", + installId: "7c9e6679-7425-40de-944b-e07fc1f90ae7", + level: "full", + createdAt: "2026-10-10T12:00:00.000Z", + app: { version: "0.8.3", platform: "android", build: "official" }, + counters: { "2026-10-09": { "g2.connect": 3, "g2.disconnect": 2 }, "2026-10-10": { "g2.connect": 1 } }, + snapshot: { "device.g2.paired": true, "apikey.anthropic": false, "setting.ui-font": "Roboto-Light.ttf:16" }, + ...overrides, + }; +} diff --git a/stats-server/tsconfig.json b/stats-server/tsconfig.json new file mode 100644 index 00000000..21f3efe7 --- /dev/null +++ b/stats-server/tsconfig.json @@ -0,0 +1,17 @@ +{ + // Node runs the .ts sources directly (type stripping, Node >= 22.18), so + // this is for type checking only. + "compilerOptions": { + "target": "ES2023", + "module": "NodeNext", + "moduleResolution": "NodeNext", + "strict": true, + "noEmit": true, + "allowImportingTsExtensions": true, + "erasableSyntaxOnly": true, + "verbatimModuleSyntax": true, + "skipLibCheck": true, + "types": ["node"] + }, + "include": ["src/**/*", "test/**/*"] +} diff --git a/tests/analytics-store.test.cjs b/tests/analytics-store.test.cjs new file mode 100644 index 00000000..c83af856 --- /dev/null +++ b/tests/analytics-store.test.cjs @@ -0,0 +1,205 @@ +const test = require('node:test'); +const assert = require('node:assert/strict'); +const { loader } = require('./helpers/load-typescript.cjs'); + +const DAY_MS = 24 * 60 * 60 * 1000; +const HOUR_MS = 60 * 60 * 1000; +const START = Date.parse('2026-10-10T12:00:00Z'); + +/** analytics-store.ts over in-memory files, a settable clock and setting, and a fake server. */ +function harness({ level = 'minimal', version = '0.8.3', statuses = [] } = {}) { + const files = new Map(); + const sent = []; + const h = { + files, sent, level, version, now: START, statuses: [...statuses], + pendingSend: null, + snapshots: { minimal: { 'device.g2.paired': true }, full: { 'apikey.anthropic': true } }, + }; + let nextId = 1; + const { AnalyticsStore } = loader({ + setTimeout: () => 0, + clearTimeout: () => {}, + })('app/analytics/analytics-store.ts'); + h.store = new AnalyticsStore({ + storage: { + read: name => files.get(name) ?? null, + write: (name, text) => files.set(name, text), + remove: name => files.delete(name), + list: () => [...files.keys()], + removeAll: () => files.clear(), + }, + level: () => h.level, + appInfo: () => ({ version: h.version, platform: 'android', build: 'official' }), + now: () => h.now, + randomId: () => `00000000-0000-4000-8000-${String(nextId++).padStart(12, '0')}`, + snapshot: level => ({ ...h.snapshots[level] }), + send: async body => { + sent.push(JSON.parse(body)); + if (h.pendingSend) await h.pendingSend; + const status = h.statuses.length ? h.statuses.shift() : 200; + if (status === 'network') throw new Error('offline'); + return status; + }, + }); + h.outbox = () => [...files.keys()].filter(name => name.startsWith('outbox-')); + h.state = () => JSON.parse(files.get('state.json')); + return h; +} + +test('Analytics keeps only what the data-collection setting allows', () => { + const h = harness({ level: 'minimal' }); + h.store.count('minimal', 'g2.connect'); + h.store.count('full', 'app.launch.timer'); + h.store.flush(); + const pending = JSON.parse(h.files.get('pending.json')); + assert.deepEqual(pending.counters.minimal, { '2026-10-10': { 'g2.connect': 1 } }); + assert.deepEqual(pending.counters.full, {}); + + const off = harness({ level: 'none' }); + off.store.count('minimal', 'g2.connect'); + off.store.flush(); + off.store.applyLevel(); + assert.equal(off.files.size, 0); +}); + +test('Analytics drops bad counter names and flags count once a day', () => { + const h = harness(); + h.store.count('minimal', 'Bad Name'); + h.store.flag('minimal', 'device.r1.used'); + h.store.flag('minimal', 'device.r1.used'); + h.store.count('minimal', 'g2.ack-timeout', 3); + h.store.flush(); + assert.deepEqual(JSON.parse(h.files.get('pending.json')).counters.minimal['2026-10-10'], { + 'device.r1.used': 1, 'g2.ack-timeout': 3, + }); +}); + +test('Analytics seals and uploads a report once a day', async () => { + const h = harness({ level: 'full' }); + h.store.count('minimal', 'g2.connect', 2); + h.store.count('full', 'feature.used'); + await h.store.uploadIfDue(); + assert.equal(h.sent.length, 1); + const [report] = h.sent; + assert.equal(report.schema, 1); + assert.equal(report.level, 'full'); + assert.match(report.installId, /^00000000-/); + assert.deepEqual(report.app, { version: '0.8.3', platform: 'android', build: 'official' }); + assert.deepEqual(report.counters, { '2026-10-10': { 'g2.connect': 2, 'feature.used': 1 } }); + assert.deepEqual(report.snapshot, { 'device.g2.paired': true, 'apikey.anthropic': true }); + assert.deepEqual(h.outbox(), []); + + h.store.count('minimal', 'g2.connect'); + h.now += 3 * HOUR_MS; + await h.store.uploadIfDue(); + assert.equal(h.sent.length, 1, 'not due again the same day'); + + h.now = START + DAY_MS; + await h.store.uploadIfDue(); + assert.equal(h.sent.length, 2); + assert.equal(h.sent[1].installId, report.installId); + assert.notEqual(h.sent[1].reportId, report.reportId); + assert.deepEqual(h.sent[1].counters, { '2026-10-10': { 'g2.connect': 1 } }); +}); + +test('Analytics retries a failed upload hourly with the same report id, and drops rejected ones', async () => { + const h = harness({ statuses: ['network', 503] }); + h.store.count('minimal', 'g2.connect'); + await h.store.uploadIfDue(); + assert.equal(h.outbox().length, 1); + + h.now += 30 * 60 * 1000; + await h.store.uploadIfDue(); + assert.equal(h.sent.length, 1, 'no retry within the hour'); + + h.now = START + HOUR_MS; + await h.store.uploadIfDue(); + assert.equal(h.sent.length, 2); + assert.equal(h.sent[1].reportId, h.sent[0].reportId); + assert.equal(h.outbox().length, 1, 'kept after a 503'); + + h.now = START + 2 * HOUR_MS; + await h.store.uploadIfDue(); + assert.equal(h.sent.length, 3); + assert.deepEqual(h.outbox(), []); + assert.equal(h.state().retryAt, 0); + + const rejected = harness({ statuses: [400] }); + await rejected.store.uploadIfDue(); + assert.deepEqual(rejected.outbox(), [], 'a 400 is not retried'); +}); + +test('Analytics turned off deletes everything, and a new install id is made when it comes back', async () => { + const h = harness(); + h.store.count('minimal', 'g2.connect'); + await h.store.uploadIfDue(); + const firstInstall = h.sent[0].installId; + h.store.count('minimal', 'g2.connect'); + h.store.flush(); + + h.level = 'none'; + h.store.applyLevel(); + assert.equal(h.files.size, 0); + await h.store.uploadIfDue(); + assert.equal(h.sent.length, 1, 'no connection while off'); + + h.level = 'minimal'; + h.now += DAY_MS; + await h.store.uploadIfDue(); + assert.equal(h.sent.length, 2); + assert.notEqual(h.sent[1].installId, firstInstall); + assert.deepEqual(h.sent[1].counters, {}, 'counts from before turning off are gone'); +}); + +test('Analytics turned down to minimal drops what was kept for full', async () => { + const h = harness({ level: 'full', statuses: ['network'] }); + h.store.count('minimal', 'g2.connect'); + h.store.count('full', 'feature.used'); + await h.store.uploadIfDue(); + h.store.count('full', 'feature.used'); + h.store.flush(); + + h.level = 'minimal'; + h.store.applyLevel(); + assert.deepEqual(JSON.parse(h.files.get('pending.json')).counters.full, {}); + const [outbox] = h.outbox(); + assert.deepEqual(JSON.parse(h.files.get(outbox)).snapshot.full, {}); + + h.now += HOUR_MS; + await h.store.uploadIfDue(); + const retried = h.sent[1]; + assert.equal(retried.level, 'minimal'); + assert.deepEqual(retried.counters, { '2026-10-10': { 'g2.connect': 1 } }); + assert.deepEqual(retried.snapshot, { 'device.g2.paired': true }); +}); + +test('Analytics sends counts from before an upgrade under the old version', async () => { + const h = harness({ version: '0.8.3' }); + h.store.count('minimal', 'g2.connect'); + h.store.flush(); + + // A new process after the upgrade. + const files = h.files; + const upgraded = harness({ version: '0.8.4' }); + for (const [name, text] of files) upgraded.files.set(name, text); + upgraded.store.count('minimal', 'g2.connect', 5); + await upgraded.store.uploadIfDue(); + assert.deepEqual(upgraded.sent.map(report => [report.app.version, report.counters['2026-10-10']]), [ + ['0.8.3', { 'g2.connect': 1 }], + ['0.8.4', { 'g2.connect': 5 }], + ]); +}); + +test('Analytics turned off and on during an upload keeps none of the old state', async () => { + const h = harness(); + let release; + h.pendingSend = new Promise(resolve => { release = resolve; }); + const upload = h.store.uploadIfDue(); + await Promise.resolve(); + h.level = 'none'; + h.store.applyLevel(); + h.level = 'minimal'; + release(); + await upload; + assert.equal(h.files.size, 0, 'the old install id is not written back'); +}); diff --git a/tests/ios-app-host.test.cjs b/tests/ios-app-host.test.cjs index e29bd398..ac8130fd 100644 --- a/tests/ios-app-host.test.cjs +++ b/tests/ios-app-host.test.cjs @@ -269,31 +269,37 @@ test('iOS compositor rejects missing and removed surfaces before crossing into K assert.equal(nativeSubmissions, 1); }); -test('iOS welcome sound waits for a new acknowledged frame and is consumed once', async () => { - let pending = true; - const played = [], sounds = load('app/ui/sound-effects.ts', { require: name => { assert.equal(name, '../g2/cfw-message-type'); return load('app/g2/cfw-message-type.ts', {}); } }); - const { IosPreviewController } = load('app/g2/ios-preview-controller.ts', { +test('iOS opens the on-glasses onboarding on a new acknowledged frame, once per run while due', () => { + const settings = new Map(); + const progress = load('app/apps/onboarding/onboarding-progress.ts', { require: id => ({ - '../phone-ui/onboarding-state': { isWelcomeSoundPending: () => pending, setWelcomeSoundPending: value => { pending = value; } }, - '../ui/sound-effects': sounds, - })[id] ?? {}, - setTimeout: fn => { fn(); return 1; }, + '../../native/settings-store': { + getStringSetting: (key, fallback) => settings.get(key) ?? fallback, + setStringSetting: (key, value) => settings.set(key, value), + }, + '../../version': { FACECLAW_VERSION: '9.9.9' }, + })[id], + }); + const launched = []; + const { IosPreviewController } = load('app/g2/ios-preview-controller.ts', { + require: id => ({ '../apps/onboarding/onboarding-progress': progress })[id] ?? {}, }); const host = Object.create(IosPreviewController.prototype); host.acknowledgedFrames = 0; - host.actions = { playBuzzerSequence: bytes => played.push([...bytes]) }; - host.logBluetooth = assert.fail; - host.maybePlayWelcomeSound({ phase: 'connecting', frames: 0 }); - host.maybePlayWelcomeSound({ phase: 'connected', frames: 0 }); - assert.equal(pending, true); assert.equal(played.length, 0); - host.maybePlayWelcomeSound({ phase: 'connected', frames: 1 }); - assert.equal(pending, false); - await new Promise(resolve => setImmediate(resolve)); - assert.ok(played.length > 0); - const count = played.length; - host.maybePlayWelcomeSound({ phase: 'connected', frames: 1 }); - host.maybePlayWelcomeSound({ phase: 'connected', frames: 2 }); - assert.equal(played.length, count); + host.launchApp = id => { launched.push(id); return Promise.resolve(); }; + host.maybeLaunchOnboarding({ phase: 'connecting', frames: 0 }); + host.maybeLaunchOnboarding({ phase: 'connected', frames: 0 }); + assert.deepEqual(launched, []); + host.maybeLaunchOnboarding({ phase: 'connected', frames: 1 }); + assert.deepEqual(launched, ['onboarding']); + // Still unfinished, but a reconnect in the same run doesn't reopen it. + host.maybeLaunchOnboarding({ phase: 'connected', frames: 2 }); + assert.deepEqual(launched, ['onboarding']); + assert.equal(progress.isGlassesOnboardingDue(), true); + progress.markGlassesOnboardingFinished(); + assert.equal(progress.isGlassesOnboardingDue(), false); + settings.set('onboarding.glassesFinishedVersion', '9.9.8'); + assert.equal(progress.isGlassesOnboardingDue(), true, 'an upgrade makes onboarding due again'); }); test('iOS preview voice uses the phone microphone, while connected capture stays on glasses', async () => { diff --git a/tests/ios-glanceboard.test.cjs b/tests/ios-glanceboard.test.cjs index e86366d8..e08a585a 100644 --- a/tests/ios-glanceboard.test.cjs +++ b/tests/ios-glanceboard.test.cjs @@ -153,8 +153,7 @@ function fixture() { '../apps/evenhub/installed-apps': {}, '../apps/evenhub/manager': {}, '../apps/evenhub/updates': {}, '../apps/evenhub': {}, '../apps/launcher/launcher-app': { createLauncherWindow: () => window, LAUNCHER_SURFACE_ID: 'launcher' }, '../apps/all-apps': { ALL_APPS: [{ appId: 'glanceboard', glanceboard: provider }] }, - '../phone-ui/onboarding-state': { isWelcomeSoundPending: () => false }, - '../ui/sound-effects': {}, + '../apps/onboarding/onboarding-progress': { claimGlassesOnboardingAutoLaunch: () => false }, '../ui/shell/worker-window': {}, '../ui/shell/in-process-window': {}, '../ui/dashboard-settings': { brightnessSetting: { get: () => 'auto' }, brightnessSettingToLevel: () => null, getBrightnessPreferences: () => ({ auto: true, level: 50, minimum: 2, maximum: 100, curve: '0:0,1000:100', fadeMs: 280 }), lockScreenEnabledSetting: { get: () => settings.lock }, onAnySettingChanged: fn => { settingsChanged = fn; return () => {}; }, previewColorSetting: { get: () => 'white' } }, '../native/phone-battery': { readPhoneBatteryState: () => ({ battery: 80, charging: false }) }, diff --git a/tests/kotlin/src/commonTest/kotlin/com/faceclaw/app/ConnectionCountersTest.kt b/tests/kotlin/src/commonTest/kotlin/com/faceclaw/app/ConnectionCountersTest.kt new file mode 100644 index 00000000..2bff3512 --- /dev/null +++ b/tests/kotlin/src/commonTest/kotlin/com/faceclaw/app/ConnectionCountersTest.kt @@ -0,0 +1,33 @@ +package com.faceclaw.app + +import kotlin.test.Test +import kotlin.test.assertEquals + +class ConnectionCountersTest { + @Test + fun drainReturnsTheCountsSinceTheLastDrain() { + ConnectionCounters.drain() + ConnectionCounters.increment("g2.connect-attempt") + ConnectionCounters.increment("g2.connect-attempt") + ConnectionCounters.increment("g2.session-ready") + assertEquals("""{"g2.connect-attempt":2,"g2.session-ready":1}""", ConnectionCounters.drain()) + assertEquals("{}", ConnectionCounters.drain()) + } + + @Test + fun keepsCountingKnownNamesPastTheNameCap() { + ConnectionCounters.drain() + for (index in 0 until 250) ConnectionCounters.increment("name-$index") + ConnectionCounters.increment("name-0") + val drained = Json.parseObject(ConnectionCounters.drain()) + assertEquals(200, drained.size) + assertEquals(JsonNumber("2"), drained["name-0"]) + } + + @Test + fun slugsFailureReasons() { + assertEquals("cfw-recovery-retry-limit", ConnectionCounters.slug("CFW recovery retry limit")) + assertEquals("left-arm-not-found", ConnectionCounters.slug("left arm not found")) + assertEquals("evenhub-resume-prelude-failed", ConnectionCounters.slug("EvenHub resume prelude failed")) + } +} diff --git a/website/privacy.html b/website/privacy.html index 3cd84806..938337ac 100644 --- a/website/privacy.html +++ b/website/privacy.html @@ -27,7 +27,31 @@

Faceclaw Privacy Policy

-

Faceclaw is a privacy-conscious app. The developers of Faceclaw don't collect or store user data. Faceclaw does integrate with some third-party services, which have their own privacy policies; this document describes what those services are, what they're used for and what data they collect, and links to their privacy policies.

+

Faceclaw is a privacy-conscious app. Unless you choose to share anonymous usage statistics (described below), the developers of Faceclaw don't collect or store any data about you or how you use the app. Faceclaw does integrate with some third-party services, which have their own privacy policies; this document describes what those services are, what they're used for and what data they collect, and links to their privacy policies.

+

Usage Statistics

+

The first time you connect your glasses, Faceclaw asks whether to share anonymous usage statistics with its developers, to help them fix problems and improve the app. The choices are None, Minimal and Full, and you can change your choice at any time in Settings > Privacy. Until you choose, it is None.

+

With None, Faceclaw sends nothing and keeps no statistics on your phone.

+

With Minimal, Faceclaw keeps counts on your phone and sends them about once a day to stats.faceclaw.org, a server run by Faceclaw's developers:

+ +

With Full, it also sends:

+ +

Statistics never include your name or contact details, your location, Bluetooth device addresses, anything you say or type, or what is shown on your glasses. Each report carries a random identifier, created when you turn statistics on, which links your reports to each other but not to you. Turning statistics off deletes that identifier and everything kept on the phone, and stops all reports; turning them back on starts a new identifier. The statistics server doesn't record the IP addresses reports come from.

Audio

Faceclaw allows users to transcribe audio (for use with the voice assistant, the Transcribe app, typing into Terminal, and other apps). The default setting is that this is done using an on-device model running on your phone. If an on-device model is selected, audio never leaves your device, and is not stored after it is processed.

Users can also provide their own API key for a third-party transcription service such as OpenAI Whisper, ElevenLabs, or Soniox, which may offer better accuracy. Faceclaw never transmits audio to any party other than a user-selected transcription service. If a third-party transcription service is selected, audio will be sent to that third party, is linked to the account with which that API key was created, and is subject to that party's privacy and retention policies:

From 58990d9617a0069eb0822f710e86b1f02015e063 Mon Sep 17 00:00:00 2001 From: James Babcock Date: Sat, 10 Oct 2026 17:34:06 -0700 Subject: [PATCH 05/65] Fix iOS styling issues on pairing screen --- app/app.css | 237 +-------------------------------- app/app.ios.css | 142 +------------------- app/phone-ui/pairing-page.xml | 4 +- app/phone-ui/pairing.css | 238 ++++++++++++++++++++++++++++++++++ 4 files changed, 242 insertions(+), 379 deletions(-) create mode 100644 app/phone-ui/pairing.css diff --git a/app/app.css b/app/app.css index d1f86d93..9c8460c5 100644 --- a/app/app.css +++ b/app/app.css @@ -1,6 +1,7 @@ @import '@nativescript/theme/css/core.css'; @import '@nativescript/theme/css/default.css'; @import './phone-ui/remote-controls.css'; +@import './phone-ui/pairing.css'; Page { background-color: #ffffff; @@ -183,242 +184,6 @@ Button.-primary { margin-bottom: 12; } -/* - * Pairing scan list (phone-ui/pairing-page). Rows are Repeater items: product - * art (or a colourway swatch) on the left, decoded SKU + proximity + serial in - * the middle, a chevron/check on the right. - */ -.pairing-instructions { - color: #555555; - font-size: 14; -} - -.pairing-status { - font-size: 14; - margin-left: 8; -} - -.pairing-section { - font-size: 16; - font-weight: bold; - margin-bottom: 4; -} - -.pairing-empty { - color: #777777; - font-size: 14; - padding: 8 0; -} - -.pairing-row { - background-color: #f4f4f4; - border-color: #dddddd; - border-width: 1; - border-radius: 10; - padding: 10; - margin-bottom: 8; -} - -.pairing-row-selected { - background-color: #e6f0ff; - border-color: #3b6fd6; -} - -.pairing-row-incomplete { - background-color: #fafafa; - border-color: #e6e6e6; -} - -.pairing-art { - vertical-align: center; -} - -.pairing-title { - font-size: 16; - font-weight: bold; - color: #222222; -} - -.pairing-badge { - font-size: 11; - font-weight: bold; - color: #2a5bc4; - background-color: #dbe6fb; - border-radius: 9; - padding: 1 7; -} - -.pairing-variant { - font-size: 13; - font-weight: bold; - color: #333333; -} - -.pairing-proximity { - font-size: 12; - color: #666666; -} - -.pairing-proximity-immediate { - color: #2a5bc4; - font-weight: bold; -} - -.pairing-serial { - font-size: 12; - color: #666666; - font-family: monospace; -} - -.pairing-arms { - font-size: 12; - color: #444444; -} - -.pairing-warning { - font-size: 12; - color: #a33a1f; - margin-top: 4; -} - -.pairing-swatch-label { - font-size: 11; - color: #555555; -} - -.pairing-chevron { - font-size: 22; - color: #444444; - margin-left: 6; -} - -.pairing-selection { - background-color: #eef4ff; - border-radius: 10; - padding: 10; -} - -Button.pairing-link { - background-color: transparent; - color: #2a5bc4; - font-size: 14; - border-width: 0; - /* Buttons keep their Material elevation shadow even with a transparent - * background, which shows up as a stray, downward-offset outline. */ - android-elevation: 0; - android-dynamic-elevation-offset: 0; -} - -/* - * Permissions screen (phone-ui/permissions-page). Cards reuse the pairing-row - * / pairing-title / pairing-badge look above; these add the explanation body - * and the already-granted checkmark. - */ -.permissions-description { - font-size: 13; - color: #555555; - margin-top: 2; -} - -.permissions-check { - font-size: 24; - color: #2e7d32; - margin-left: 10; -} - -/* Continue with required permissions still missing: looks disabled but stays - * tappable (the tap raises an are-you-sure prompt instead of being ignored). */ -Button.permissions-primary-dimmed { - opacity: 0.45; -} - -/* - * Dark-mode pairing page. The cards keep their light-mode look above; here - * they go dark-gray, and every text colour set above gets a light counterpart - * so nothing renders dark-on-dark (the instructions) or dark-on-a-dark-card. - * Order matters: the -selected/-incomplete rules must follow .pairing-row so - * they win at equal specificity. - */ -.ns-dark .pairing-instructions { - color: #b0b0b0; -} - -.ns-dark .pairing-empty { - color: #999999; -} - -.ns-dark .pairing-row { - background-color: #2e2e2e; - border-color: #4a4a4a; -} - -.ns-dark .pairing-row-selected { - background-color: #333c4c; - border-color: #5b8def; -} - -.ns-dark .pairing-row-incomplete { - background-color: #282828; - border-color: #3c3c3c; -} - -.ns-dark .pairing-title { - color: #f0f0f0; -} - -.ns-dark .pairing-badge { - color: #a8c4f5; - background-color: #2a3b5e; -} - -.ns-dark .pairing-variant { - color: #cccccc; -} - -.ns-dark .pairing-proximity { - color: #a0a0a0; -} - -.ns-dark .pairing-proximity-immediate { - color: #7da7f5; -} - -.ns-dark .pairing-serial { - color: #a0a0a0; -} - -.ns-dark .pairing-arms { - color: #c0c0c0; -} - -.ns-dark .pairing-warning { - color: #e08a66; -} - -.ns-dark .pairing-swatch-label { - color: #aaaaaa; -} - -.ns-dark .pairing-chevron { - color: #bbbbbb; -} - -.ns-dark .pairing-selection { - background-color: #2e2e2e; -} - -.ns-dark Button.pairing-link { - color: #7da7f5; -} - -.ns-dark .permissions-description { - color: #b0b0b0; -} - -.ns-dark .permissions-check { - color: #7bc47f; -} - /* * Conversation review (phone-ui/conversations-page, conversation-page, * speakers-page). Cards follow the pairing-row look; speaker/emotion chips diff --git a/app/app.ios.css b/app/app.ios.css index 17bcf99b..3f433cc5 100644 --- a/app/app.ios.css +++ b/app/app.ios.css @@ -1,146 +1,6 @@ @import '@nativescript/theme/css/core.css'; @import './phone-ui/remote-controls.css'; - -.pairing-instructions { - color: #555555; - font-size: 14; -} - -.pairing-status { - font-size: 14; - margin-left: 8; -} - -.pairing-section { - font-size: 16; - font-weight: bold; - margin-bottom: 4; -} - -.pairing-empty { - color: #777777; - font-size: 14; - padding: 8 0; -} - -.pairing-row { - background-color: #f4f4f4; - border-color: #dddddd; - border-width: 1; - border-radius: 10; - padding: 10; - margin-bottom: 8; -} - -.pairing-row-selected { - background-color: #e6f0ff; - border-color: #3b6fd6; -} - -.pairing-row-incomplete { - background-color: #fafafa; - border-color: #e6e6e6; -} - -.pairing-art { - vertical-align: center; -} - -.pairing-title { - font-size: 16; - font-weight: bold; - color: #222222; -} - -.pairing-badge { - font-size: 11; - font-weight: bold; - color: #2a5bc4; - background-color: #dbe6fb; - border-radius: 9; - padding: 1 7; -} - -.pairing-variant { - font-size: 13; - font-weight: bold; - color: #333333; -} - -.pairing-proximity { - font-size: 12; - color: #666666; -} - -.pairing-proximity-immediate { - color: #2a5bc4; - font-weight: bold; -} - -.pairing-serial { - font-size: 12; - color: #666666; - font-family: monospace; -} - -.pairing-arms { - font-size: 12; - color: #444444; -} - -.pairing-warning { - font-size: 12; - color: #a33a1f; - margin-top: 4; -} - -.pairing-swatch-label { - font-size: 11; - color: #555555; -} - -.pairing-chevron { - font-size: 22; - color: #444444; - margin-left: 6; -} - -.pairing-selection { - background-color: #eef4ff; - border-radius: 10; - padding: 10; -} - -Button.pairing-link { - background-color: transparent; - color: #2a5bc4; - font-size: 14; - border-width: 0; -} - -/* - * Permissions screen (phone-ui/permissions-page). Cards reuse the pairing-row - * / pairing-title / pairing-badge look above; these add the explanation body - * and the already-granted checkmark. - */ -.permissions-description { - font-size: 13; - color: #555555; - margin-top: 2; -} - -.permissions-check { - font-size: 24; - color: #2e7d32; - margin-left: 10; -} - -/* Continue with required permissions still missing: looks disabled but stays - * tappable (the tap raises an are-you-sure prompt instead of being ignored). */ -Button.permissions-primary-dimmed { - opacity: 0.45; -} - +@import './phone-ui/pairing.css'; .body-text { font-size: 18; } .h1 { font-size: 28; font-weight: bold; } diff --git a/app/phone-ui/pairing-page.xml b/app/phone-ui/pairing-page.xml index b1704d29..60af9a44 100644 --- a/app/phone-ui/pairing-page.xml +++ b/app/phone-ui/pairing-page.xml @@ -82,8 +82,8 @@
diff --git a/website/privacy.html b/website/privacy.html index 938337ac..48700a64 100644 --- a/website/privacy.html +++ b/website/privacy.html @@ -27,10 +27,10 @@

Faceclaw Privacy Policy

-

Faceclaw is a privacy-conscious app. Unless you choose to share anonymous usage statistics (described below), the developers of Faceclaw don't collect or store any data about you or how you use the app. Faceclaw does integrate with some third-party services, which have their own privacy policies; this document describes what those services are, what they're used for and what data they collect, and links to their privacy policies.

+

Faceclaw's own usage statistics are off unless you opt in. Separately, Apple collects and shares information when you use an iOS TestFlight build, even when Faceclaw statistics are set to None. Information you voluntarily send us, such as feedback, may also identify you. This policy describes these separate channels and the third-party services you can choose to use.

Usage Statistics

-

The first time you connect your glasses, Faceclaw asks whether to share anonymous usage statistics with its developers, to help them fix problems and improve the app. The choices are None, Minimal and Full, and you can change your choice at any time in Settings > Privacy. Until you choose, it is None.

-

With None, Faceclaw sends nothing and keeps no statistics on your phone.

+

The first time you connect your glasses, Faceclaw asks whether to share usage statistics with its developers, to help them fix problems and improve the app. The choices are None, Minimal and Full, and you can change your choice at any time in Settings > Privacy > Faceclaw statistics. Until you choose, it is None. This setting controls only Faceclaw's own statistics.

+

With None, Faceclaw sends and stores none of its own usage statistics. This does not disable Apple's TestFlight reports or services you choose to use.

With Minimal, Faceclaw keeps counts on your phone and sends them about once a day to stats.faceclaw.org, a server run by Faceclaw's developers:

-

Statistics never include your name or contact details, your location, Bluetooth device addresses, anything you say or type, or what is shown on your glasses. Each report carries a random identifier, created when you turn statistics on, which links your reports to each other but not to you. Turning statistics off deletes that identifier and everything kept on the phone, and stops all reports; turning them back on starts a new identifier. The statistics server doesn't record the IP addresses reports come from.

+

Faceclaw's own statistics never include your name or contact details, your location, Bluetooth device addresses, anything you say or type, or what is shown on your glasses. Each report carries a random identifier, created when you turn statistics on, which links your reports to each other but not to you. Turning statistics off deletes that identifier and everything kept on the phone, and stops all reports; turning them back on starts a new identifier. The statistics server doesn't record the IP addresses reports come from.

+

iOS and TestFlight

+

For TestFlight builds, Apple automatically collects crash reports and beta usage information and shares them with us. This includes installations, sessions, crashes, app/build and OS versions, device model and identifier, and language. It is separate from Faceclaw statistics, with no in-app opt-out.

+

Joining only through a public TestFlight link hides your name and email from us, not from Apple. Email invitations can identify you to us. Apple also collects your device's name (not shared with us) and may use your IP address to estimate your region for beta availability.

+

Feedback is optional. Comments, screenshots and diagnostics submitted through TestFlight go to Apple and us. Public-link testers can omit their email in the feedback form. Email sent directly to us reveals your email even after public-link enrollment, but is not shared with Apple. Check screenshots and comments for private content; feedback can include device state such as battery level, free storage and network type.

+

Faceclaw has no public iOS API to switch off TestFlight's automatic reporting. Its statistics setting and iOS tracking permissions do not control it. To leave, select Stop Testing on Faceclaw's TestFlight information page, then stop using and uninstall the beta. This does not erase previous reports. Self-built installations do not use TestFlight reporting.

+

For ordinary iOS analytics, use iPhone Settings > Privacy & Security > Analytics & Improvements, including Share With App Developers. Faceclaw cannot change these system settings. TestFlight crash reporting applies regardless of those settings. See https://www.apple.com/legal/privacy/data/en/app-analytics/.

+

We use TestFlight reports only to improve Faceclaw, not for advertising or sharing with third parties. Apple retains feedback for one year and may keep crash/usage reports until bugs are resolved. For access/deletion requests, contact us using the developer email in TestFlight; manage Apple's data at https://privacy.apple.com/.

+

Apple's details: https://www.apple.com/legal/privacy/data/en/test-flight/ and https://testflight.apple.com/.

Audio

Faceclaw allows users to transcribe audio (for use with the voice assistant, the Transcribe app, typing into Terminal, and other apps). The default setting is that this is done using an on-device model running on your phone. If an on-device model is selected, audio never leaves your device, and is not stored after it is processed.

Users can also provide their own API key for a third-party transcription service such as OpenAI Whisper, ElevenLabs, or Soniox, which may offer better accuracy. Faceclaw never transmits audio to any party other than a user-selected transcription service. If a third-party transcription service is selected, audio will be sent to that third party, is linked to the account with which that API key was created, and is subject to that party's privacy and retention policies:

From 8f0d4b0f8caf657317659cfe24c0c59760285d4e Mon Sep 17 00:00:00 2001 From: James Babcock Date: Sat, 10 Oct 2026 18:43:37 -0700 Subject: [PATCH 07/65] Match iPhone signup requirements to TestFlight --- website/install.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/install.html b/website/install.html index 2419e987..e93167e7 100644 --- a/website/install.html +++ b/website/install.html @@ -35,7 +35,7 @@

What you need

  • A pair of Even Realities G2 glasses, or use Preview Only to explore on your phone without glasses.
  • -
  • An Android phone or an iPhone running iOS 15.1 or later. Faceclaw talks to the glasses over Bluetooth LE.
  • +
  • An Android phone or an iPhone running iOS 16 or later for TestFlight. Faceclaw talks to the glasses over Bluetooth LE.
  • On Android, optionally a Wear OS 3+ watch, if you want the watch remote instead of the R1 ring.

Some features are platform-specific: Android notification access, Android media controls and the Wear OS remote are Android features.

From 1d257e8bb68e5d02e363b3fa7b1643ad408d5f74 Mon Sep 17 00:00:00 2001 From: James Babcock Date: Sat, 10 Oct 2026 20:11:38 -0700 Subject: [PATCH 08/65] Fix spurious unit test failures --- .../kotlin/com/faceclaw/app/PreviewAnimationListenerTest.kt | 6 ++++-- .../kotlin/com/faceclaw/app/GlassesSessionCoreTest.kt | 2 +- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/tests/kotlin/src/androidHostTest/kotlin/com/faceclaw/app/PreviewAnimationListenerTest.kt b/tests/kotlin/src/androidHostTest/kotlin/com/faceclaw/app/PreviewAnimationListenerTest.kt index 9a573d88..0ecd9f64 100644 --- a/tests/kotlin/src/androidHostTest/kotlin/com/faceclaw/app/PreviewAnimationListenerTest.kt +++ b/tests/kotlin/src/androidHostTest/kotlin/com/faceclaw/app/PreviewAnimationListenerTest.kt @@ -10,9 +10,11 @@ import kotlin.test.* */ class PreviewAnimationListenerTest { // FrameDisplayListTest's menu golden (a 2x2 highlight sliding in to rest at (3, 2)), - // restarted at 0 of its 240 ms so the slide is still in flight at the first pull. + // restarted at 1 of its 240 ms so the slide is still in flight at the first pull. Not 0: + // at exactly 0 the highlight is wholly above this 8x8 screen, so a pull in the same + // millisecond as the submit (a warm JIT) would match the settled frame. private val menu = "077f0000000300020002000200022a00000096000000010002000200ffffffff0200080000ff24017e30020000000001812c8001812c1611010017328001812c16103001812c3023414031ff24017c30020000000001812c8001812c1611010017328001812c16103001812c30234140310200020001000103100400000000000000001f" - .chunked(2).map { it.toInt(16).toByte() }.toByteArray().also { it.fill(0, 18, 22) } + .chunked(2).map { it.toInt(16).toByte() }.toByteArray().also { it.fill(0, 18, 22); it[18] = 1 } private fun settledPreview(): ByteArray { val reader = ArrayByteReader(menu) diff --git a/tests/kotlin/src/commonTest/kotlin/com/faceclaw/app/GlassesSessionCoreTest.kt b/tests/kotlin/src/commonTest/kotlin/com/faceclaw/app/GlassesSessionCoreTest.kt index 00604823..a615af76 100644 --- a/tests/kotlin/src/commonTest/kotlin/com/faceclaw/app/GlassesSessionCoreTest.kt +++ b/tests/kotlin/src/commonTest/kotlin/com/faceclaw/app/GlassesSessionCoreTest.kt @@ -453,7 +453,7 @@ class GlassesSessionCoreTest { s.core.interruptibleSleep.interrupt() assertTrue(waitUntil(3_000) { s.listener.phases.contains("retrying") }, s.host.logs().takeLast(10).toString()) assertTrue(s.host.hasLog("message timed out: create-layout")) - assertTrue(s.host.hasLog("Transport failure: ack timeout")) + assertTrue(s.host.hasLog("Transport failure: create layout ack timeout")) assertTrue(s.link.disconnected.containsAll(listOf(RIGHT, LEFT))) s.core.disconnect() assertEquals("disconnected", s.listener.phases.last()) From 6b1e64c5acff2c1d6ecb08d591eba8e9afc41b5b Mon Sep 17 00:00:00 2001 From: James Babcock Date: Sat, 10 Oct 2026 21:52:19 -0700 Subject: [PATCH 09/65] Onboarding: Add layout and depth pages --- app/apps/onboarding/data-collection-page.ts | 5 +- app/apps/onboarding/depth-page.ts | 71 ++++++ app/apps/onboarding/index.ts | 3 +- app/apps/onboarding/ios-privacy-page.ts | 1 + app/apps/onboarding/layout-page.ts | 259 ++++++++++++++++++++ app/apps/onboarding/onboarding-app.ts | 50 ++-- app/apps/onboarding/onboarding-page.ts | 8 + app/apps/onboarding/text-size-page.ts | 80 +++--- app/apps/onboarding/welcome-page.ts | 2 + app/ui/dashboard-settings.ts | 6 +- app/ui/shell/chrome-layer.ts | 12 +- app/ui/shell/geometry.ts | 40 ++- app/ui/shell/in-process-window.ts | 31 ++- app/ui/shell/shell.ts | 7 +- tests/ai-chat.test.cjs | 2 +- tests/app-layout.test.cjs | 46 ++++ tests/onboarding-layout.test.cjs | 217 ++++++++++++++++ 17 files changed, 766 insertions(+), 74 deletions(-) create mode 100644 app/apps/onboarding/depth-page.ts create mode 100644 app/apps/onboarding/layout-page.ts create mode 100644 tests/onboarding-layout.test.cjs diff --git a/app/apps/onboarding/data-collection-page.ts b/app/apps/onboarding/data-collection-page.ts index badb9fd0..91e944df 100644 --- a/app/apps/onboarding/data-collection-page.ts +++ b/app/apps/onboarding/data-collection-page.ts @@ -13,6 +13,7 @@ const LABEL_GAP = 24; /** None / Minimal / Full, each with a one-line summary; a tap saves the selected level. */ export class DataCollectionPage implements OnboardingPage { + readonly fullscreen = true; /** Width of the level-name column, measured each paint. */ private labelColumnWidth = 0; private readonly menu = new Menu({ @@ -31,9 +32,9 @@ export class DataCollectionPage implements OnboardingPage { paint(image: GrayImage, focused: boolean): void { const top = drawPageHeading( image, - "Faceclaw statistics", + "Data Sharing", (global.isIOS ? "If using TestFlight, crash/usage reports cannot be disabled here. " : "") + - "Choose optional Faceclaw statistics. Change later in Settings > Privacy.", + "Choose how much data you want to share. Change later in Settings > Privacy.", 3, ) + CONTENT_GAP; const body = onboardingFont("body"); diff --git a/app/apps/onboarding/depth-page.ts b/app/apps/onboarding/depth-page.ts new file mode 100644 index 00000000..fb7bd26a --- /dev/null +++ b/app/apps/onboarding/depth-page.ts @@ -0,0 +1,71 @@ +import type { GrayImage } from "../../graphics/image"; +import { appSwitcherPositionSetting, uiDepthSetting, type UiDepth } from "../../ui/dashboard-settings"; +import type { InputEvent } from "../../ui/gestures"; +import { Menu, type MenuDrawArgs } from "../../ui/menu-core"; +import { LIST_ROW_TEXT_INSET, listRowHeight } from "../../ui/metrics"; +import { layoutHasDepth } from "./layout-page"; +import { onboardingFont } from "./onboarding-fonts"; +import { drawPageHeading, PAGE_X, type OnboardingNav, type OnboardingPage } from "./onboarding-page"; + +const CONTENT_GAP = 10; +const BOTTOM_MARGIN = 8; +const COLUMN_WIDTH = 220; + +/** + * The whole display's stereo depth, after a layout that has one (Bottom or + * Popup). Not fullscreen, so the page sits in the chosen layout, and the + * depth is saved as the selection moves: the shell shifts everything with + * it, which is the only way to see the difference. + */ +export class DepthPage implements OnboardingPage { + private readonly menu = new Menu({ + items: uiDepthSetting.values, + wrap: false, + rowGap: 2, + highlight: { radius: 8 }, + getHeight: () => listRowHeight(onboardingFont("body")), + draw: (args) => this.drawRow(args), + }); + + applies(): boolean { + return layoutHasDepth(appSwitcherPositionSetting.get()); + } + + enter(): void { + this.menu.select(uiDepthSetting.values.indexOf(uiDepthSetting.get())); + } + + paint(image: GrayImage, focused: boolean): void { + const top = drawPageHeading( + image, + "Depth", + "Swipe to move the display nearer or farther away, then tap to continue. Change later in Settings > Customization.", + ) + CONTENT_GAP; + this.menu.paint( + image, + { x: PAGE_X - 10, y: top, width: COLUMN_WIDTH, height: image.height - top - BOTTOM_MARGIN }, + focused, + ); + } + + handleInput(event: InputEvent, nav: OnboardingNav): void { + switch (event.type) { + case "scroll-up": + case "scroll-down": { + void this.menu.handleInput(event); + const depth = this.menu.selectedItem; + if (depth !== null) uiDepthSetting.set(depth); + return; + } + case "click": + nav.next(); + return; + default: + return; + } + } + + private drawRow({ image, item: depth, x, y, selected }: MenuDrawArgs): void { + image.drawText(onboardingFont("body"), x + 10, y + LIST_ROW_TEXT_INSET, uiDepthSetting.displayValue(depth), selected ? 255 : 190); + } +} diff --git a/app/apps/onboarding/index.ts b/app/apps/onboarding/index.ts index 2210022a..8de05881 100644 --- a/app/apps/onboarding/index.ts +++ b/app/apps/onboarding/index.ts @@ -4,7 +4,8 @@ import { ONBOARDING_APP_ID } from "./onboarding-progress"; /** * First-run setup on the glasses: welcome, text size, data-collection - * preference. The connection controllers open it on their own when it is + * preference, layout (app switcher position) and, for layouts that have + * one, depth. The connection controllers open it on their own when it is * due (claimGlassesOnboardingAutoLaunch); the launcher entry reruns it. */ const onboardingApp: AppDefinition = { diff --git a/app/apps/onboarding/ios-privacy-page.ts b/app/apps/onboarding/ios-privacy-page.ts index 7a55c469..726d41af 100644 --- a/app/apps/onboarding/ios-privacy-page.ts +++ b/app/apps/onboarding/ios-privacy-page.ts @@ -7,6 +7,7 @@ import { drawPageHeading, PAGE_X, type OnboardingNav, type OnboardingPage } from /** Paginate the notice so no disclosure is silently clipped on a short glasses viewport. */ export class IosPrivacyPage implements OnboardingPage { + readonly fullscreen = true; private page = 0; private pageCount = 1; diff --git a/app/apps/onboarding/layout-page.ts b/app/apps/onboarding/layout-page.ts new file mode 100644 index 00000000..51aa7c05 --- /dev/null +++ b/app/apps/onboarding/layout-page.ts @@ -0,0 +1,259 @@ +import { G2_LENS_WIDTH, type GrayImage, type UiFont } from "../../graphics/image"; +import { appSwitcherPositionSetting, statusBarPositionSetting, type AppSwitcherPosition } from "../../ui/dashboard-settings"; +import type { InputEvent } from "../../ui/gestures"; +import { MENU_HIGHLIGHT_FILL, MENU_HIGHLIGHT_STROKE } from "../../ui/menu-core"; +import { MIN_WINDOW_HEIGHT, SIDEBAR_WIDTH, SWITCHER_ROW_HEIGHT, TOP_BAR_HEIGHT } from "../../ui/shell/geometry"; +import { onboardingFont } from "./onboarding-fonts"; +import { drawPageHeading, type OnboardingNav, type OnboardingPage } from "./onboarding-page"; + +const CONTENT_GAP = 10; +const BOTTOM_MARGIN = 8; +/** Diagram width as a fraction of the display's: the most a diagram is drawn at. */ +const DIAGRAM_SCALE = 0.4; +/** The real-display area a diagram covers: a 288px window band and a bottom switcher row under it. */ +const DIAGRAM_AREA_HEIGHT = MIN_WINDOW_HEIGHT + SWITCHER_ROW_HEIGHT; +/** Padding inside a cell's selection box, round the diagram and its caption. */ +const CELL_PADDING = 8; +const CAPTION_GAP = 4; +const COLUMN_GAP = 16; +const ROW_GAP = 6; +const DEPTH_SUBTITLE = "Customizable Depth"; +/** Grid order, in rows of two: the layouts with depth on top. */ +const LAYOUT_ORDER: readonly AppSwitcherPosition[] = ["bottom", "popup", "left", "right"]; +/** Selected on the first visit, and marked. */ +const RECOMMENDED_LAYOUT: AppSwitcherPosition = "bottom"; + +/** Whether a layout leaves the side margins the display's stereo depth shifts into (geometry.ts uiDepth). */ +export function layoutHasDepth(position: AppSwitcherPosition): boolean { + return position === "bottom" || position === "popup"; +} + +/** + * The app switcher position, as a 2×2 grid of captioned diagrams of each + * layout, Bottom (recommended, and selected at first) and Popup on top; + * swipes move through them in reading order, a tap saves the selected one. + * The page is fullscreen, so the diagrams get 40% of the display's width + * each. Choosing a layout reflows open windows (the dashboard controller + * watches the setting). + */ +export class LayoutPage implements OnboardingPage { + readonly fullscreen = true; + /** Kept across visits, so going back returns to the last choice. */ + private selected = LAYOUT_ORDER.indexOf(RECOMMENDED_LAYOUT); + + paint(image: GrayImage, focused: boolean): void { + const top = drawPageHeading( + image, + "Layout", + "Swipe to choose where the app switcher goes, then tap to continue.", + ) + CONTENT_GAP; + const title = onboardingFont("body"); + const subtitle = onboardingFont("detail"); + const captionHeight = CAPTION_GAP + title.lineHeight + subtitle.lineHeight; + const available = image.height - top - BOTTOM_MARGIN; + // Short of DIAGRAM_SCALE only where two rows of cells wouldn't fit. + const scale = Math.min( + DIAGRAM_SCALE, + ((available - ROW_GAP) / 2 - 2 * CELL_PADDING - captionHeight) / DIAGRAM_AREA_HEIGHT, + ((image.width - COLUMN_GAP) / 2 - 2 * CELL_PADDING) / G2_LENS_WIDTH, + ); + const diagramWidth = Math.round(G2_LENS_WIDTH * scale); + const diagramHeight = Math.round(DIAGRAM_AREA_HEIGHT * scale); + const cellWidth = diagramWidth + 2 * CELL_PADDING; + const cellHeight = diagramHeight + 2 * CELL_PADDING + captionHeight; + const left = Math.round((image.width - 2 * cellWidth - COLUMN_GAP) / 2); + const gridTop = top + Math.max(0, Math.round((available - 2 * cellHeight - ROW_GAP) / 2)); + LAYOUT_ORDER.forEach((position, index) => { + const x = left + (index % 2) * (cellWidth + COLUMN_GAP); + const y = gridTop + Math.floor(index / 2) * (cellHeight + ROW_GAP); + const selected = index === this.selected; + if (selected) { + if (focused) image.fillRoundedRect(x, y, cellWidth, cellHeight, MENU_HIGHLIGHT_FILL, 8); + image.drawRoundedRect(x, y, cellWidth, cellHeight, MENU_HIGHLIGHT_STROKE, 8); + } + drawLayoutDiagram(new Diagram(image, x + CELL_PADDING, y + CELL_PADDING, scale), position); + const centre = (text: string, font: UiFont, textY: number, value: number) => + image.drawText(font, x + Math.round((cellWidth - font.measureText(text)) / 2), textY, text, value); + const captionTop = y + CELL_PADDING + diagramHeight + CAPTION_GAP; + const name = appSwitcherPositionSetting.displayValue(position); + const caption = position === RECOMMENDED_LAYOUT ? `${name} (Recommended)` : name; + centre(caption, title, captionTop, selected ? 255 : 190); + if (layoutHasDepth(position)) { + centre(DEPTH_SUBTITLE, subtitle, captionTop + title.lineHeight, selected ? 210 : 150); + } + }); + } + + handleInput(event: InputEvent, nav: OnboardingNav): void { + const last = LAYOUT_ORDER.length - 1; + switch (event.type) { + case "scroll-up": + this.selected = Math.max(0, this.selected - 1); + return; + case "scroll-down": + this.selected = Math.min(last, this.selected + 1); + return; + case "click": + appSwitcherPositionSetting.set(LAYOUT_ORDER[this.selected]!); + nav.next(); + return; + default: + return; + } + } +} + +// Diagram brightnesses: brighter than the real chrome's, which the diagrams +// shrink to a few pixels. +const AREA_OUTLINE = 30; +const CHROME_LINE = 100; +const WINDOW_FRAME = 140; +const ICON = 160; +const SELECTED_ICON = 230; +const STATUS = 140; +const CONTENT = 110; +const CONTENT_TITLE = 170; +/** Window content under a popup switcher, which dims it. */ +const DIM = 0.5; + +/** + * Draws in real-display pixels, scaled into a cell: the DIAGRAM_AREA_HEIGHT + * rows from the diagram's top, or from `top` rows down (see from). + */ +class Diagram { + constructor( + private readonly image: GrayImage, + private readonly x: number, + private readonly y: number, + private readonly scale: number, + private readonly top = 0, + ) {} + + /** The same diagram with its row 0 `top` rows down. */ + from(top: number): Diagram { + return new Diagram(this.image, this.x, this.y, this.scale, top); + } + + private box(x: number, y: number, width: number, height: number) { + y += this.top; + const left = this.x + Math.round(x * this.scale), top = this.y + Math.round(y * this.scale); + return { + x: left, + y: top, + width: Math.max(1, this.x + Math.round((x + width) * this.scale) - left), + height: Math.max(1, this.y + Math.round((y + height) * this.scale) - top), + }; + } + + fill(x: number, y: number, width: number, height: number, value: number, radius = 0): void { + const box = this.box(x, y, width, height); + if (radius) this.image.fillRoundedRect(box.x, box.y, box.width, box.height, value, Math.max(1, Math.round(radius * this.scale))); + else this.image.fillRect(box.x, box.y, box.width, box.height, value); + } + + outline(x: number, y: number, width: number, height: number, value: number, radius = 0): void { + const box = this.box(x, y, width, height); + this.image.drawRoundedRect(box.x, box.y, box.width, box.height, value, Math.max(0, Math.round(radius * this.scale))); + } + + /** A one-pixel line along a real-pixel row (horizontal) or column. */ + hline(x: number, y: number, width: number, value: number): void { + const box = this.box(x, y, width, 1); + this.image.fillRect(box.x, box.y, box.width, 1, value); + } + + vline(x: number, y: number, height: number, value: number): void { + const box = this.box(x, y, 1, height); + this.image.fillRect(box.x, box.y, 1, box.height, value); + } +} + +/** + * A layout as the real chrome lays it out (geometry.ts, chrome-layer.ts), + * to scale and simplified: the window band with its status bar and frame, + * and the switcher with a few icons, the first selected. Status bar + * placement follows the current setting. Only a bottom switcher row takes + * rows under the band; without one, the band sits centred in their place, + * as the band and row share the screen's slack. + */ +function drawLayoutDiagram(area: Diagram, position: AppSwitcherPosition): void { + area.outline(0, 0, G2_LENS_WIDTH, DIAGRAM_AREA_HEIGHT, AREA_OUTLINE, 12); + const d = position === "bottom" ? area : area.from((DIAGRAM_AREA_HEIGHT - MIN_WINDOW_HEIGHT) / 2); + const statusAtBottom = statusBarPositionSetting.get() === "bottom"; + const windowLeft = SIDEBAR_WIDTH / 2, windowWidth = G2_LENS_WIDTH - SIDEBAR_WIDTH; + switch (position) { + case "left": + case "right": { + const stripLeft = position === "left" ? 0 : G2_LENS_WIDTH - SIDEBAR_WIDTH; + const contentLeft = position === "left" ? SIDEBAR_WIDTH : 0; + drawStatusBar(d, contentLeft, 0, windowWidth, true); + drawContent(d, contentLeft, TOP_BAR_HEIGHT, windowWidth, MIN_WINDOW_HEIGHT - TOP_BAR_HEIGHT, 1); + const separator = position === "left" ? SIDEBAR_WIDTH - 1 : stripLeft; + d.vline(separator, TOP_BAR_HEIGHT, MIN_WINDOW_HEIGHT - TOP_BAR_HEIGHT, CHROME_LINE); + // One column of icons against the separator. + const column = position === "left" ? SIDEBAR_WIDTH - 36 : stripLeft; + for (let slot = 0; slot < 4; slot++) drawIcon(d, column + 2, TOP_BAR_HEIGHT + 10 + slot * 40, slot === 0); + return; + } + case "bottom": { + // With the status bar in the row, the window's header is just the frame's top. + const contentTop = statusAtBottom ? 1 : TOP_BAR_HEIGHT; + if (!statusAtBottom) drawStatusBar(d, windowLeft, 0, windowWidth, false); + drawContent(d, windowLeft, contentTop, windowWidth, MIN_WINDOW_HEIGHT - contentTop, 1); + d.outline(windowLeft - 1, contentTop - 1, windowWidth + 2, MIN_WINDOW_HEIGHT - contentTop + 2, WINDOW_FRAME, 8); + for (let slot = 0; slot < 4; slot++) drawIcon(d, windowLeft + 1 + slot * 40, MIN_WINDOW_HEIGHT + 2, slot === 0); + if (statusAtBottom) drawStatusItems(d, windowLeft + windowWidth, MIN_WINDOW_HEIGHT + 4); + return; + } + case "popup": { + const statusTop = statusAtBottom ? MIN_WINDOW_HEIGHT - TOP_BAR_HEIGHT : 0; + const contentTop = statusAtBottom ? 1 : TOP_BAR_HEIGHT; + const contentHeight = MIN_WINDOW_HEIGHT - TOP_BAR_HEIGHT - 1; + drawStatusBar(d, windowLeft, statusTop, windowWidth, false); + drawContent(d, windowLeft, contentTop, windowWidth, contentHeight, DIM); + d.outline(windowLeft - 1, contentTop - 1, windowWidth + 2, contentHeight + 2, WINDOW_FRAME, 8); + // The popup: a row of icons over the selected window's title, centred on the content. + const box = { width: 272, height: 98 }; + const boxLeft = (G2_LENS_WIDTH - box.width) / 2; + const boxTop = contentTop + (contentHeight - box.height) / 2; + d.fill(boxLeft, boxTop, box.width, box.height, 0); + d.outline(boxLeft, boxTop, box.width, box.height, WINDOW_FRAME); + const iconsLeft = boxLeft + (box.width - (3 * 48 - 4)) / 2; + for (let slot = 0; slot < 3; slot++) drawIcon(d, iconsLeft + slot * 48 + 6, boxTop + 18, slot === 0); + d.fill(G2_LENS_WIDTH / 2 - 50, boxTop + 70, 100, 12, STATUS, 6); + return; + } + } +} + +/** A status bar along a window's top or bottom edge; `divider` draws its line toward the window. */ +function drawStatusBar(d: Diagram, x: number, y: number, width: number, divider: boolean): void { + if (divider) d.hline(x, y + TOP_BAR_HEIGHT - 1, width, CHROME_LINE); + drawStatusItems(d, x + width, y); +} + +/** Notification icons, a battery and the clock, ending at `right`, in a status bar's 28 rows from `top`. */ +function drawStatusItems(d: Diagram, right: number, top: number): void { + d.fill(right - 64, top + 7, 56, 14, STATUS, 4); + d.outline(right - 108, top + 8, 32, 12, STATUS, 2); + d.outline(right - 148, top + 4, 20, 20, CHROME_LINE, 4); + d.outline(right - 176, top + 4, 20, 20, CHROME_LINE, 4); +} + +/** A switcher icon (32px); the selected one filled, as the switcher's selection tab is. */ +function drawIcon(d: Diagram, x: number, y: number, selected: boolean): void { + if (selected) d.fill(x, y, 32, 32, SELECTED_ICON, 6); + else d.outline(x, y, 32, 32, ICON, 6); +} + +/** Stand-in window content: a title and list rows, the first selected. */ +function drawContent(d: Diagram, x: number, y: number, width: number, height: number, brightness: number): void { + const rowWidths = [width - 60, 300, 360, 240]; + d.fill(x + 18, y + 14, 150, 18, CONTENT_TITLE * brightness, 6); + d.outline(x + 8, y + 44, width - 16, 34, CONTENT * brightness, 8); + for (let row = 0; row < rowWidths.length; row++) { + const rowTop = y + 52 + row * 44; + if (rowTop + 18 > y + height) break; + d.fill(x + 18, rowTop, Math.min(rowWidths[row]!, width - 36), 18, CONTENT * brightness, 6); + } +} diff --git a/app/apps/onboarding/onboarding-app.ts b/app/apps/onboarding/onboarding-app.ts index 5fe90178..1aa56c96 100644 --- a/app/apps/onboarding/onboarding-app.ts +++ b/app/apps/onboarding/onboarding-app.ts @@ -5,7 +5,9 @@ import { createInProcessWindow, type InProcessAppOptions, type InProcessWindow } import { shell } from "../../ui/shell/shell"; import { findSoundEffect, playSoundEffect } from "../../ui/sound-effects"; import { DataCollectionPage } from "./data-collection-page"; +import { DepthPage } from "./depth-page"; import { IosPrivacyPage } from "./ios-privacy-page"; +import { LayoutPage } from "./layout-page"; import { markGlassesOnboardingFinished, ONBOARDING_APP_ID } from "./onboarding-progress"; import type { OnboardingPage } from "./onboarding-page"; import { TextSizePage } from "./text-size-page"; @@ -25,7 +27,7 @@ export function createOnboardingAppWindow(options: InProcessAppOptions): InProce const pages: OnboardingPage[] = [ new WelcomePage(), new TextSizePage(), ...(global.isIOS ? [new IosPrivacyPage()] : []), - new DataCollectionPage(), + new DataCollectionPage(), new LayoutPage(), new DepthPage(), ]; const app = createInProcessWindow({ appId: ONBOARDING_APP_ID, @@ -34,11 +36,17 @@ export function createOnboardingAppWindow(options: InProcessAppOptions): InProce iconLetter: "On", icon: "sparkles", closeable: true, + fullscreen: pages[0]!.fullscreen, actions: options.actions, - baseLayer: new OnboardingLayer(pages, () => { - markGlassesOnboardingFinished(); - shell.closeWindow(ONBOARDING_WINDOW_ID); - }), + baseLayer: new OnboardingLayer( + pages, + // Only called on page changes, by when `app` is set. + (fullscreen) => app.setFullscreen(fullscreen), + () => { + markGlassesOnboardingFinished(); + shell.closeWindow(ONBOARDING_WINDOW_ID); + }, + ), submitFrame: options.submitFrame, setSurfaceVisible: options.setSurfaceVisible, removeSurface: options.removeSurface, @@ -61,15 +69,17 @@ function playWelcomeSound(actions: LayerActions): void { } /** - * Hosts the current page. Double-click steps back a page, or leaves the app - * from the first one (the standard yield to the app switcher); every other - * gesture goes to the page. + * Hosts the current page, fullscreen or not as it asks. Double-click steps + * back a page, or leaves the app from the first one (the standard yield to + * the app switcher); every other gesture goes to the page. Pages that don't + * apply (Depth beside a side-strip app switcher) are skipped either way. */ -class OnboardingLayer implements Layer { +export class OnboardingLayer implements Layer { private index = 0; constructor( private readonly pages: readonly OnboardingPage[], + private readonly setFullscreen: (fullscreen: boolean) => void, private readonly finish: () => void, ) { pages[0]!.enter?.(); @@ -84,20 +94,32 @@ class OnboardingLayer implements Layer { async handleInput(event: InputEvent): Promise { if (event.type === "double-click") { - if (this.index === 0) shell.yieldFocusToSidebar(); - else this.show(this.index - 1); + const previous = this.applicableIndex(this.index - 1, -1); + if (previous === null) shell.yieldFocusToSidebar(); + else this.show(previous); return; } await this.pages[this.index]!.handleInput(event, { next: () => this.next() }); } private next(): void { - if (this.index + 1 < this.pages.length) this.show(this.index + 1); - else this.finish(); + const next = this.applicableIndex(this.index + 1, 1); + if (next === null) this.finish(); + else this.show(next); + } + + /** The first page from `index` on in direction `step` that applies, if any. */ + private applicableIndex(index: number, step: 1 | -1): number | null { + for (; index >= 0 && index < this.pages.length; index += step) { + if (this.pages[index]!.applies?.() ?? true) return index; + } + return null; } private show(index: number): void { this.index = index; - this.pages[index]!.enter?.(); + const page = this.pages[index]!; + page.enter?.(); + this.setFullscreen(page.fullscreen ?? false); } } diff --git a/app/apps/onboarding/onboarding-page.ts b/app/apps/onboarding/onboarding-page.ts index 175f21a5..8f2d1541 100644 --- a/app/apps/onboarding/onboarding-page.ts +++ b/app/apps/onboarding/onboarding-page.ts @@ -15,6 +15,14 @@ export type OnboardingNav = { * viewport and handles every other gesture. */ export interface OnboardingPage { + /** + * Show the page fullscreen: the whole 640×480 panel, with the app switcher + * and status bar hidden. Otherwise it is an ordinary window in the + * chosen layout. + */ + readonly fullscreen?: boolean; + /** Whether the page belongs in the flow right now; skipped both ways when false. */ + applies?(): boolean; /** The page became current, going forward or back. */ enter?(): void; paint(image: GrayImage, focused: boolean): void; diff --git a/app/apps/onboarding/text-size-page.ts b/app/apps/onboarding/text-size-page.ts index 7694aa9d..49969c36 100644 --- a/app/apps/onboarding/text-size-page.ts +++ b/app/apps/onboarding/text-size-page.ts @@ -1,4 +1,4 @@ -import { GrayImage, type UiFont } from "../../graphics/image"; +import type { GrayImage, UiFont } from "../../graphics/image"; import { installedFontPath } from "../../graphics/installed-fonts"; import { wrapText } from "../../graphics/textwrap"; import { TtfFont } from "../../graphics/ttf-font"; @@ -11,20 +11,29 @@ import { } from "../../graphics/ui-fonts"; import { FONT_SIZE_CHOICES } from "../../ui/font-picker"; import type { InputEvent } from "../../ui/gestures"; -import { Menu, MENU_HIGHLIGHT_FILL, MENU_HIGHLIGHT_STROKE, type MenuBox, type MenuDrawArgs } from "../../ui/menu-core"; +import { Menu, type MenuBox, type MenuDrawArgs } from "../../ui/menu-core"; import { LIST_ROW_TEXT_INSET, listRowHeight } from "../../ui/metrics"; import { onboardingFont } from "./onboarding-fonts"; import { drawPageHeading, PAGE_X, type OnboardingNav, type OnboardingPage } from "./onboarding-page"; const CONTENT_GAP = 10; const BOTTOM_MARGIN = 8; -const SIZE_COLUMN_WIDTH = 84; const COLUMN_GAP = 12; const PREVIEW_PADDING = 10; const ROW_GAP = 2; -const PREVIEW_TEXT = "This is how text will look on your glasses."; -/** Drawn while they fit, so smaller sizes visibly show more rows. */ -const PREVIEW_ROWS = ["Timers", "Weather", "Music", "Settings", "Files"]; +/** Between a size and its "Recommended" note. */ +const NOTE_GAP = 8; +/** The sizes offered here; Settings has the full range. */ +const SIZE_CHOICES = FONT_SIZE_CHOICES.filter((size) => size >= 12 && size <= 18); +/** Selected on the first visit, and marked. */ +const RECOMMENDED_SIZE = 16; +const RECOMMENDED_NOTE = "Recommended"; +/** Drawn while they fit, so smaller sizes visibly show more words. */ +const PREVIEW_PARAGRAPHS = [ + "This is how text will look on your glasses.", + "Smaller sizes fit more words on the display at once, while larger sizes are easier to read at a " + + "glance or on the move. Most people find the recommended size a good balance between the two.", +]; /** The UI font's face, as far as this page is concerned: resizable (TTF) or not (bitmap). */ type Face = @@ -32,12 +41,14 @@ type Face = | { kind: "fixed"; label: string }; /** - * The UI font's size, over a preview of list rows and body text in the - * chosen size. The face and weight stay as they are (they live in the - * Settings font picker); a bitmap face has only one size, so the page just - * says so. The size is saved on tap, not while scrolling. + * The UI font's size, 12 to 18px (16 recommended, and selected at first), + * beside a preview of text in the selected size. The face and weight stay + * as they are (they live in the Settings font picker); a bitmap face has + * only one size, so the page just says so. The size is saved on tap, not + * while scrolling. */ export class TextSizePage implements OnboardingPage { + readonly fullscreen = true; private face: Face = { kind: "fixed", label: "Terminus" }; private readonly sizeMenu = new Menu({ wrap: false, @@ -52,10 +63,11 @@ export class TextSizePage implements OnboardingPage { const selection = getUiFontSelection(); if (selection.kind === "ttf") { const path = installedFontPath(selection.file); - const sizes = FONT_SIZE_CHOICES.filter((size) => uiFontSizeAllowed(path, size)); + const sizes = SIZE_CHOICES.filter((size) => uiFontSizeAllowed(path, size)); if (sizes.length) { this.face = { kind: "sized", file: selection.file, path, sizes }; - this.sizeMenu.setItems(sizes, nearestIndex(sizes, selection.size)); + // The recommended size the first time; on a return, what was left selected. + this.sizeMenu.setItems(sizes, nearestIndex(sizes, this.sizeMenu.selectedItem ?? RECOMMENDED_SIZE)); return; } } @@ -86,7 +98,10 @@ export class TextSizePage implements OnboardingPage { "Swipe to choose a size, then tap to continue. The typeface and weight can be changed in Settings.", ) + CONTENT_GAP; const height = image.height - top - BOTTOM_MARGIN; - const menuBox = { x: PAGE_X - 10, y: top, width: SIZE_COLUMN_WIDTH, height }; + const body = onboardingFont("body"); + const columnWidth = 20 + Math.max(...this.face.sizes.map((size) => body.measureText(sizeLabel(size)))) + + NOTE_GAP + onboardingFont("detail").measureText(RECOMMENDED_NOTE); + const menuBox = { x: PAGE_X - 10, y: top, width: columnWidth, height }; this.sizeMenu.paint(image, menuBox, focused); const previewX = menuBox.x + menuBox.width + COLUMN_GAP; const size = this.sizeMenu.selectedItem; @@ -117,36 +132,35 @@ export class TextSizePage implements OnboardingPage { setUiFontSelection({ kind: "ttf", file: this.face.file, size }); } - private drawSizeRow({ image, item: size, x, y, selected }: MenuDrawArgs): void { - image.drawText(onboardingFont("body"), x + 10, y + LIST_ROW_TEXT_INSET, `${size} px`, selected ? 255 : 190); + private drawSizeRow({ image, item: size, x, y, height, selected }: MenuDrawArgs): void { + const body = onboardingFont("body"); + const label = sizeLabel(size); + image.drawText(body, x + 10, y + LIST_ROW_TEXT_INSET, label, selected ? 255 : 190); + if (size !== RECOMMENDED_SIZE) return; + const detail = onboardingFont("detail"); + const noteY = y + Math.round((height - detail.lineHeight) / 2); + image.drawText(detail, x + 10 + body.measureText(label) + NOTE_GAP, noteY, RECOMMENDED_NOTE, selected ? 210 : 150); } } -/** A framed sample in `font`: a sentence, then menu rows with the first one selected, as many as fit. */ +function sizeLabel(size: number): string { + return `${size} px`; +} + +/** A framed sample in `font`: paragraphs of text, as many whole lines as fit. */ function drawPreview(image: GrayImage, font: UiFont, box: MenuBox): void { image.drawRoundedRect(box.x, box.y, box.width, box.height, 60, 8); const left = box.x + PREVIEW_PADDING; const width = box.width - 2 * PREVIEW_PADDING; const bottom = box.y + box.height - PREVIEW_PADDING; let y = box.y + PREVIEW_PADDING; - for (const line of wrapText(font, PREVIEW_TEXT, width)) { - if (y + font.lineHeight > bottom) return; - image.drawText(font, left, y, line, 220); - y += font.lineHeight; - } - y += PREVIEW_PADDING; - const rowHeight = listRowHeight(font); - for (let index = 0; index < PREVIEW_ROWS.length; index++) { - if (y + rowHeight - ROW_GAP > bottom) return; - const label = PREVIEW_ROWS[index]!; - if (index === 0) { - const row = new GrayImage(width, rowHeight - ROW_GAP, 0); - row.drawText(font, 10, LIST_ROW_TEXT_INSET, label, 255); - image.drawMenuSelection(row, left, y, MENU_HIGHLIGHT_FILL, MENU_HIGHLIGHT_STROKE, 8, 0); - } else { - image.drawText(font, left + 10, y + LIST_ROW_TEXT_INSET, label, 200); + for (const [index, paragraph] of PREVIEW_PARAGRAPHS.entries()) { + if (index > 0) y += font.lineHeight >> 1; + for (const line of wrapText(font, paragraph, width)) { + if (y + font.lineHeight > bottom) return; + image.drawText(font, left, y, line, 220); + y += font.lineHeight; } - y += rowHeight; } } diff --git a/app/apps/onboarding/welcome-page.ts b/app/apps/onboarding/welcome-page.ts index b14005b3..1a96b715 100644 --- a/app/apps/onboarding/welcome-page.ts +++ b/app/apps/onboarding/welcome-page.ts @@ -16,6 +16,8 @@ type TextLine = { font: UiFont; text: string; value: number; spaceBefore: number /** The splash: logo beside the name, version and how to go on, centred as one group. */ export class WelcomePage implements OnboardingPage { + readonly fullscreen = true; + paint(image: GrayImage): void { const { width, height } = image; const logo = getFullLogo(Math.min(LOGO_MAX_HEIGHT, height - 2 * LOGO_MARGIN)); diff --git a/app/ui/dashboard-settings.ts b/app/ui/dashboard-settings.ts index 1f610789..cafb2501 100644 --- a/app/ui/dashboard-settings.ts +++ b/app/ui/dashboard-settings.ts @@ -698,9 +698,9 @@ const DATA_COLLECTION_LABELS: Record = { // What each level collects is set out in app/analytics/analytics-store.ts and // the privacy policy (PRIVACY); keep these in step with both. const DATA_COLLECTION_SUMMARIES: Record = { - none: "No Faceclaw statistics", - minimal: "Version, devices, connection reliability", - full: "Also settings and API-key presence", + none: "Disable all data sharing", + minimal: "Version, devices, and connection reliability statistics", + full: "More detailed usage data", }; /** One-line summary of what a data-collection level sends (onboarding, settings). */ diff --git a/app/ui/shell/chrome-layer.ts b/app/ui/shell/chrome-layer.ts index 4fe7f0a3..5d81a9d1 100644 --- a/app/ui/shell/chrome-layer.ts +++ b/app/ui/shell/chrome-layer.ts @@ -27,6 +27,7 @@ import { scrollToKeepSelectionVisible } from "../menu"; import { lineStep } from "../metrics"; import { appViewportRect, + isFullscreen, MIN_WINDOW_HEIGHT, minWindowTop, SHELL_OPAQUE_BLACK, @@ -275,14 +276,15 @@ type StatusBarPlacement = { left: number; right: number; top: number; contentTop /** * The status bar's placement for the foreground window, or null when it - * isn't drawn as a bar: when it shares a bottom switcher row, or when it - * overlays the window (geometry.ts statusBarOverlays) and the popup - * switcher isn't up. An overlaying bar sits inside a window frame, whose - * side runs along its outer row, so it keeps its divider. + * isn't drawn as a bar: when the window is fullscreen, when it shares a + * bottom switcher row, or when it overlays the window (geometry.ts + * statusBarOverlays) and the popup switcher isn't up. An overlaying bar + * sits inside a window frame, whose side runs along its outer row, so it + * keeps its divider. */ function statusBarPlacement(state: ShellChromeState): StatusBarPlacement | null { const appId = state.foregroundAppId; - if (statusInSwitcherRow(appId)) return null; + if (isFullscreen(appId) || statusInSwitcherRow(appId)) return null; const overlays = statusBarOverlays(); if (overlays && !sidebarStripVisible(state.focus, appId)) return null; const { left, right } = topBarSpan(state); diff --git a/app/ui/shell/geometry.ts b/app/ui/shell/geometry.ts index 01302c35..c8e19754 100644 --- a/app/ui/shell/geometry.ts +++ b/app/ui/shell/geometry.ts @@ -60,9 +60,33 @@ export function displayMode(appId?: string): DisplayModeSetting { return mode === "global" || mode === "default" ? displayModeSetting.get() : mode; } -/** The full-panel mode: windows fill the panel; the switcher overlays them only while it has focus. */ +/** + * Apps whose windows are fullscreen right now: the whole panel, with no + * status bar, window frame or room kept for the switcher (which overlays + * them only while it has focus, as in the full-panel mode), at depth 0. An + * app switches it at runtime (InProcessWindow.setFullscreen; the onboarding's + * first pages), so it is per app, like the per-app display modes. + */ +const fullscreenApps = new Set(); + +/** Mark an app's windows fullscreen or not; true if that changed anything. */ +export function setAppFullscreen(appId: string, fullscreen: boolean): boolean { + if (fullscreenApps.has(appId) === fullscreen) return false; + if (fullscreen) fullscreenApps.add(appId); + else fullscreenApps.delete(appId); + return true; +} + +export function isFullscreen(appId?: string): boolean { + return appId !== undefined && fullscreenApps.has(appId); +} + +/** + * The full-panel mode (or a fullscreen app): windows fill the panel; the + * switcher overlays them only while it has focus. + */ function fullPanel(appId?: string): boolean { - return displayMode(appId) === "640x480"; + return isFullscreen(appId) || displayMode(appId) === "640x480"; } /** @@ -176,9 +200,10 @@ export function statusBarOverlays(): boolean { * Rows the shell draws along one edge of each window's content: the status * bar's (the top bar, as a header), the frame's side, or none. A bottom * switcher row's band has no footer: the frame's bottom side is the row's - * top edge. + * top edge. A fullscreen window has neither. */ function windowEdgeHeight(edge: "top" | "bottom", appId?: string): number { + if (isFullscreen(appId)) return 0; if (switcherPosition() !== "popup") { return edge === "bottom" ? 0 : statusInSwitcherRow(appId) ? 1 : TOP_BAR_HEIGHT; } @@ -261,17 +286,20 @@ export function appViewportLeft(appId?: string): number { * the firmware's depth units; the shell scene carries it to the compositor, * which shifts the screen and everything drawn over it per lens. Only with * the switcher at the bottom or a popup, where the windows' side margins, - * less the window frame's pixel, leave room for the shift. + * less the window frame's pixel, leave room for the shift; not while the + * given (foreground) app is fullscreen, which has no margins. */ -export function uiDepth(): number { - return sideStrip() ? 0 : Number(uiDepthSetting.get()); +export function uiDepth(appId?: string): number { + return sideStrip() || isFullscreen(appId) ? 0 : Number(uiDepthSetting.get()); } /** * Explicit app sizes (including Use global) replace the requested height. * The default keeps legacy per-window heights, such as tall terminal sessions. + * A fullscreen app is always the whole height. */ export function effectiveHeightMode(mode: WindowHeightMode, appId?: string): WindowHeightMode { + if (isFullscreen(appId)) return "max"; return displayMode(appId) === "576x288" ? (appDisplayMode(appId) === "default" ? mode : "min") : "max"; } diff --git a/app/ui/shell/in-process-window.ts b/app/ui/shell/in-process-window.ts index b372593a..ae5cecb0 100644 --- a/app/ui/shell/in-process-window.ts +++ b/app/ui/shell/in-process-window.ts @@ -8,7 +8,7 @@ import { type MenuItem } from "../menu"; import { WindowMenuLayer } from "../window-menu"; import { windowIcon } from "./chrome-layer"; import { type IconName } from "../../graphics/icons"; -import { appViewportSize, type WindowHeightMode } from "./geometry"; +import { appViewportSize, setAppFullscreen, type WindowHeightMode } from "./geometry"; import { shell, type ShellWindow } from "./shell"; /** @@ -30,6 +30,8 @@ export type InProcessWindowOptions = { closeable: boolean; /** Window height: the standard 288px band ("min", default) or full screen ("max"). */ heightMode?: WindowHeightMode; + /** Open fullscreen: the whole panel, without the status bar (see geometry.ts isFullscreen). */ + fullscreen?: boolean; /** * The window's tap-then-hold context menu: app-specific entries only (the * shared Focus app switcher / Voice input / Close window entries live in @@ -73,6 +75,12 @@ export type InProcessWindow = { requestRender: () => void; /** Change the window's height band at runtime (resizes the viewport + surface). */ setHeightMode: (mode: WindowHeightMode) => void; + /** + * Enter or leave fullscreen at runtime (resizes the viewport + surface). + * It is per app (geometry.ts isFullscreen), so an app with several + * windows switches them all. + */ + setFullscreen: (fullscreen: boolean) => void; }; /** The controller-provided plumbing common to every in-process app window. */ @@ -102,10 +110,12 @@ export function createInProcessWindow(options: InProcessWindowOptions): InProces // Handed to app code as a bare callback, so it takes no arguments. const requestRender = () => renderInNewFrame(0); let heightMode = options.heightMode ?? "min"; + setAppFullscreen(options.appId, options.fullscreen ?? false); + const viewportSize = () => appViewportSize(heightMode, options.appId); const stack = new LayerStack( options.baseLayer, { ...options.actions, requestRender }, - appViewportSize(heightMode), + viewportSize(), () => shell.isWindowFocused(options.windowId), ); @@ -172,6 +182,7 @@ export function createInProcessWindow(options: InProcessWindowOptions): InProces hasAppMenu: () => appMenuItems().length > 0, close: () => { closed = true; + setAppFullscreen(options.appId, false); // Fire onRemoved for any pushed layers so they release resources (e.g. a // demo that enabled a hardware stream) even when closed from within. stack.clearToBase(); @@ -210,7 +221,7 @@ export function createInProcessWindow(options: InProcessWindowOptions): InProces }, requestRender, relayout: () => { - stack.setBaseSize(appViewportSize(heightMode)); + stack.setBaseSize(viewportSize()); options.reconfigureSurface?.(heightMode); requestRender(); }, @@ -226,15 +237,21 @@ export function createInProcessWindow(options: InProcessWindowOptions): InProces options.onForegroundChanged?.(foreground); }, }; + const resize = () => { + stack.setBaseSize(viewportSize()); + options.reconfigureSurface?.(heightMode); + requestRender(); + }; const setHeightMode = (mode: WindowHeightMode) => { if (heightMode === mode) return; heightMode = mode; window.heightMode = mode; - stack.setBaseSize(appViewportSize(mode)); - options.reconfigureSurface?.(mode); - requestRender(); + resize(); }; - return { window, stack, requestRender, setHeightMode }; + const setFullscreen = (fullscreen: boolean) => { + if (!closed && setAppFullscreen(options.appId, fullscreen)) resize(); + }; + return { window, stack, requestRender, setHeightMode, setFullscreen }; } /** diff --git a/app/ui/shell/shell.ts b/app/ui/shell/shell.ts index 632b444f..9ff5c5d0 100644 --- a/app/ui/shell/shell.ts +++ b/app/ui/shell/shell.ts @@ -831,10 +831,13 @@ class Shell { /** * Paint the shell surface: transparent chrome, or all-transparent when - * asleep. The scene also carries the whole display's stereo depth. + * asleep. The scene also carries the whole display's stereo depth (none + * under a fullscreen window). */ paintScene(): Uint8Array { - return this.screenOn ? encodeShellScene(this.stack.paintUndimmed(), uiDepth()) : encodeShellScene([]); + return this.screenOn + ? encodeShellScene(this.stack.paintUndimmed(), uiDepth(this.foregroundWindow()?.appId)) + : encodeShellScene([]); } paintSurface(): Plane[] { diff --git a/tests/ai-chat.test.cjs b/tests/ai-chat.test.cjs index 7bd82e94..b5a3d9b8 100644 --- a/tests/ai-chat.test.cjs +++ b/tests/ai-chat.test.cjs @@ -271,7 +271,7 @@ function shellEnv({ wakeAction = 'voice-input', skipConfirmation = false } = {}) '../../graphics/image': images, '../../native/frame-timings': timings, '../../util/render-freshness': { beginRenderPass() {}, endRenderPass: () => false }, '../layers': layers, '../window-menu': { WindowMenuLayer: Menu }, - './chrome-layer': { windowIcon: () => () => null }, './geometry': { appViewportSize: () => ({ width: 576, height: 260 }) }, + './chrome-layer': { windowIcon: () => () => null }, './geometry': { appViewportSize: () => ({ width: 576, height: 260 }), setAppFullscreen: () => false }, './shell': { shell }, }); const input = [], menus = []; diff --git a/tests/app-layout.test.cjs b/tests/app-layout.test.cjs index cc0cb72a..18bb4fed 100644 --- a/tests/app-layout.test.cjs +++ b/tests/app-layout.test.cjs @@ -204,6 +204,33 @@ test('a bottom app switcher centres 576-wide windows and hangs one tall tab unde assert.equal(g.windowFramed(), false); }); +test('a fullscreen app fills the panel without chrome rows, frame or depth, in any layout', () => { + const panel = { x: 0, y: 0, width: 640, height: 480 }; + for (const position of ['left', 'right', 'bottom', 'popup']) { + const g = geometry(); + g.settings.appSwitcherPositionSetting.value = position; + g.settings.statusBarPositionSetting.value = 'bottom'; + g.settings.uiDepthSetting.value = '48'; + assert.equal(g.setAppFullscreen('onboarding', true), true); + assert.equal(g.setAppFullscreen('onboarding', true), false); + for (const mode of ['min', 'medium', 'max']) assert.deepEqual(g.rect(mode, 'onboarding'), panel, position); + assert.equal(g.windowFramed('onboarding'), false); + assert.equal(g.statusInSwitcherRow('onboarding'), false); + // The switcher overlays it while focused, as in the full-panel mode. + assert.equal(g.sidebarStripVisible('window', 'onboarding'), false); + assert.equal(g.sidebarStripVisible('sidebar', 'onboarding'), true); + assert.equal(g.uiDepth('onboarding'), 0); + // Other apps keep the layout and its depth. + const depth = position === 'bottom' || position === 'popup' ? 48 : 0; + assert.equal(g.uiDepth('launcher'), depth); + assert.equal(g.uiDepth(), depth); + assert.notDeepEqual(g.rect('min', 'launcher'), panel); + assert.equal(g.setAppFullscreen('onboarding', false), true); + assert.deepEqual(g.rect('min', 'onboarding'), g.rect('min', 'launcher')); + assert.equal(g.uiDepth('onboarding'), depth); + } +}); + // The real chrome layer over the given geometry, with platform pieces stubbed: // a 4px-per-character font that paints each character as a 2x6 block, up to // `notifications` 24px notification icons (keyed n0, n1, ...), and a phone @@ -296,6 +323,25 @@ test('a bottom app switcher frames the foreground window\'s content in a rounded assert.equal(chrome.paintParts().flatMap((p) => frames(p.image)).length, 0); }); +test('over a fullscreen window the chrome draws only the switcher, and only while it has focus', () => { + for (const position of ['bottom', 'popup', 'left']) { + const g = geometry(); + g.settings.appSwitcherPositionSetting.value = position; + g.settings.statusBarPositionSetting.value = position === 'left' ? 'top' : 'bottom'; + g.setAppFullscreen('onboarding', true); + const { chrome, state } = chromeLayer(g, { windows: 2, notifications: 1 }); + state.foregroundAppId = 'onboarding'; + assert.equal(chrome.paintParts().length, 0, position); + assert.equal(chrome.paint().pixels.some((value) => value !== 0), false, position); + state.focus = 'sidebar'; + const parts = chrome.paintParts(); + // No status bar (key 2), not even in a bottom row. + assert.equal(parts.length, 1, position); + assert.notEqual(parts[0].shellKey, 2, position); + if (position === 'bottom') assert.deepEqual([parts[0].x, parts[0].y, parts[0].image.width], [0, 444, 640]); + } +}); + test('the launcher\'s tab lines up with the window frame, whose corner squares to meet it', () => { const g = geometry(); g.settings.appSwitcherPositionSetting.value = 'bottom'; diff --git a/tests/onboarding-layout.test.cjs b/tests/onboarding-layout.test.cjs new file mode 100644 index 00000000..dc116fb2 --- /dev/null +++ b/tests/onboarding-layout.test.cjs @@ -0,0 +1,217 @@ +const test = require('node:test'); +const assert = require('node:assert/strict'); +const { loader } = require('./helpers/load-typescript.cjs'); + +// Roboto's line heights at the onboarding sizes, and a fixed advance. +const FONTS = { title: 31, body: 24, detail: 19, hero: 52 }; +const font = (role) => ({ lineHeight: FONTS[role], measureText: (text) => text.length * 8, getGlyph: () => ({ dwidthX: 8 }) }); + +function setting(value, values) { + return { value, values, get() { return this.value; }, set(next) { this.value = next; this.writes.push(next); }, + writes: [], displayValue: (v) => v[0].toUpperCase() + v.slice(1) }; +} + +function harness() { + const settings = { + appSwitcherPositionSetting: setting('bottom', ['left', 'right', 'bottom', 'popup']), + statusBarPositionSetting: setting('bottom', ['top', 'bottom']), + uiDepthSetting: setting('48', ['-62', '-48', '-32', '-16', '0', '16', '32', '48', '62']), + }; + const load = loader({}, { + './onboarding-fonts': { onboardingFont: font }, + '../../graphics/image': { G2_LENS_WIDTH: 640 }, + '../../ui/dashboard-settings': settings, + '../../ui/shell/geometry': { MIN_WINDOW_HEIGHT: 288, SIDEBAR_WIDTH: 64, SWITCHER_ROW_HEIGHT: 36, TOP_BAR_HEIGHT: 28 }, + }); + return { settings, load }; +} + +/** An image that records what is drawn, checking it all lands on the image. */ +function recorder(width, height) { + const calls = []; + const inside = (kind, x, y, w, h) => { + assert.ok(x >= 0 && y >= 0 && x + w <= width && y + h <= height, `${kind} out of bounds: ${[x, y, w, h]}`); + }; + return { + width, height, calls, + fillRect(x, y, w, h, value) { inside('fillRect', x, y, w, h); calls.push({ kind: 'fill', x, y, w, h, value }); }, + fillRoundedRect(x, y, w, h, value) { inside('fillRoundedRect', x, y, w, h); calls.push({ kind: 'fill', x, y, w, h, value }); }, + drawRoundedRect(x, y, w, h, value) { inside('drawRoundedRect', x, y, w, h); calls.push({ kind: 'outline', x, y, w, h, value }); }, + drawText(f, x, y, text, value) { + inside(`text "${text}"`, x, y, f.measureText(text), f.lineHeight); + calls.push({ kind: 'text', x, y, text, value }); + }, + }; +} + +test('the layout page fits four 40%-wide diagrams with captions on the fullscreen panel', () => { + const { load } = harness(); + const { LayoutPage } = load('app/apps/onboarding/layout-page.ts'); + const page = new LayoutPage(); + assert.equal(page.fullscreen, true); + const image = recorder(640, 480); + page.paint(image, true); + // Each diagram's outline spans the display's width at 40%. + const areas = image.calls.filter((call) => call.kind === 'outline' && call.w === 256); + assert.equal(areas.length, 4); + assert.deepEqual(areas.map((area) => area.h), [130, 130, 130, 130]); + // A 2x2 grid, the layouts with depth on top, captioned under each diagram. + const text = (label) => image.calls.filter((call) => call.kind === 'text' && call.text === label); + const [bottom, popup, left, right] = ['Bottom (Recommended)', 'Popup', 'Left', 'Right'].map((label) => text(label)[0]); + assert.equal(bottom.y, popup.y); + assert.equal(left.y, right.y); + assert.ok(left.y > bottom.y); + assert.ok(popup.x > bottom.x && right.x > left.x); + for (const [caption, area] of [[bottom, areas[0]], [popup, areas[1]], [left, areas[2]], [right, areas[3]]]) { + assert.ok(caption.y >= area.y + area.h, `${caption.text} sits under its diagram`); + assert.ok(caption.x > area.x && caption.x + caption.text.length * 8 < area.x + area.w, `${caption.text} sits under its diagram`); + } + // Customizable Depth under Bottom and Popup only. + const depth = text('Customizable Depth'); + assert.equal(depth.length, 2); + for (const [subtitle, title] of [[depth[0], bottom], [depth[1], popup]]) { + assert.equal(subtitle.y, title.y + FONTS.body); + assert.ok(Math.abs(subtitle.x + 'Customizable Depth'.length * 4 - (title.x + title.text.length * 4)) <= 1, 'centred together'); + } + // Bottom, recommended, is the selected cell at first, filled while focused. + const box = image.calls.find((call) => call.kind === 'fill' && call.value === 15); + assert.ok(box.x <= areas[0].x && box.y <= areas[0].y && box.y + box.h >= bottom.y); +}); + +test('the layout page starts on Bottom whatever is set, swipes in reading order, and a tap saves the choice', () => { + const { load, settings } = harness(); + const { LayoutPage } = load('app/apps/onboarding/layout-page.ts'); + const page = new LayoutPage(); + settings.appSwitcherPositionSetting.value = 'right'; + page.enter?.(); + let next = 0; + const nav = { next: () => next++ }; + page.handleInput({ type: 'click' }, nav); + assert.deepEqual(settings.appSwitcherPositionSetting.writes, ['bottom']); + page.handleInput({ type: 'scroll-up' }, nav); + for (let i = 0; i < 2; i++) page.handleInput({ type: 'scroll-down' }, nav); + assert.deepEqual(settings.appSwitcherPositionSetting.writes, ['bottom'], 'scrolling saves nothing'); + page.handleInput({ type: 'click' }, nav); + for (let i = 0; i < 5; i++) page.handleInput({ type: 'scroll-down' }, nav); + // Coming back keeps the last choice. + page.enter?.(); + page.handleInput({ type: 'click' }, nav); + assert.deepEqual(settings.appSwitcherPositionSetting.writes, ['bottom', 'left', 'right']); + assert.equal(next, 3); +}); + +test('the text size page offers 12 to 18px, starts on the recommended 16px, and previews plain text', () => { + const menu = { selected: null, items: [], setItems(items, index) { this.items = items; this.selected = index; }, + get selectedItem() { return this.items[this.selected] ?? null; }, paint(image, box) { this.box = box; }, + async handleInput(event) { this.selected = Math.max(0, Math.min(this.items.length - 1, this.selected + (event.type === 'scroll-down' ? 1 : -1))); } }; + let menuOptions; + let selection = { kind: 'ttf', file: 'Roboto-Light.ttf', size: 14 }; + const saved = []; + const load = loader({}, { + './onboarding-fonts': { onboardingFont: font }, + '../../graphics/installed-fonts': { installedFontPath: (file) => `/fonts/${file}` }, + '../../graphics/ttf-font': { TtfFont: { load: (path, size) => font(size === 12 ? 'title' : 'detail') } }, + '../../graphics/ui-fonts': { fontSelectionLabel: () => 'Terminus', getDefaultSmallFont: () => font('detail'), + getUiFontSelection: () => selection, setUiFontSelection: (value) => { selection = value; saved.push(value.size); }, + uiFontSizeAllowed: (path, size) => size !== 13 }, + '../../ui/font-picker': { FONT_SIZE_CHOICES: [8, 10, 11, 12, 13, 14, 15, 16, 17, 18, 20, 24] }, + '../../ui/menu-core': { Menu: class { constructor(options) { menuOptions = options; return menu; } } }, + '../../ui/metrics': { LIST_ROW_TEXT_INSET: 4, listRowHeight: (f) => f.lineHeight + 8 }, + }); + const { TextSizePage } = load('app/apps/onboarding/text-size-page.ts'); + const page = new TextSizePage(); + page.enter(); + assert.deepEqual(Array.from(menu.items), [12, 14, 15, 16, 17, 18]); + assert.equal(menu.selectedItem, 16, 'recommended, not the current 14'); + // Only 16 carries the note, beside its size. + const rows = []; + for (const size of menu.items) { + const row = recorder(menu.box?.width ?? 200, 32); + menuOptions.draw({ image: row, item: size, x: 0, y: 0, width: row.width, height: 32, selected: size === 16 }); + rows.push(row.calls.map((call) => call.text)); + } + assert.deepEqual(rows[3], ['16 px', 'Recommended']); + assert.deepEqual(rows.filter((texts) => texts.length > 1).length, 1); + // The size column holds the note; the preview is paragraphs of text, no menu. + const image = recorder(640, 480); + page.paint(image, true); + assert.ok(menu.box.width >= 10 + '16 px'.length * 8 + 8 + 'Recommended'.length * 8); + const preview = image.calls.filter((call) => call.kind === 'text' && call.x > menu.box.x + menu.box.width); + assert.equal(preview[0].text.startsWith('This is how text will look'), true); + assert.ok(preview.length > 3); + assert.equal(image.calls.some((call) => call.kind === 'text' && call.text === 'Timers'), false); + // A tap saves; coming back keeps the size chosen. + page.handleInput({ type: 'scroll-up' }, { next: () => {} }); + page.handleInput({ type: 'click' }, { next: () => {} }); + assert.deepEqual(saved, [15]); + page.enter(); + assert.equal(menu.selectedItem, 15); +}); + +test('the depth page follows layouts that have depth, sits in the layout, and applies depth as it scrolls', () => { + const { load, settings } = harness(); + const menu = { selected: 0, items: [], select(index) { this.selected = index; }, + get selectedItem() { return this.items[this.selected] ?? null; }, paint() {}, + async handleInput(event) { this.selected = Math.max(0, Math.min(this.items.length - 1, this.selected + (event.type === 'scroll-down' ? 1 : -1))); } }; + const mocks = loader({}, { + './onboarding-fonts': { onboardingFont: font }, + '../../ui/dashboard-settings': settings, + '../../ui/menu-core': { Menu: class { constructor(options) { menu.items = options.items; return menu; } } }, + '../../ui/metrics': { LIST_ROW_TEXT_INSET: 4, listRowHeight: (f) => f.lineHeight + 8 }, + './layout-page': { layoutHasDepth: (position) => position === 'bottom' || position === 'popup' }, + }); + const { DepthPage } = mocks('app/apps/onboarding/depth-page.ts'); + const page = new DepthPage(); + assert.equal(page.fullscreen, undefined); + for (const [position, applies] of [['left', false], ['right', false], ['bottom', true], ['popup', true]]) { + settings.appSwitcherPositionSetting.value = position; + assert.equal(page.applies(), applies, position); + } + page.enter(); + assert.equal(menu.selectedItem, '48'); + let next = 0; + page.handleInput({ type: 'scroll-down' }, { next: () => next++ }); + page.handleInput({ type: 'scroll-up' }, { next: () => next++ }); + page.handleInput({ type: 'scroll-up' }, { next: () => next++ }); + assert.deepEqual(settings.uiDepthSetting.writes, ['62', '48', '32']); + page.handleInput({ type: 'click' }, { next: () => next++ }); + assert.equal(next, 1); +}); + +test('the flow switches fullscreen per page and skips pages that do not apply, both ways', async () => { + const shell = { yields: 0, yieldFocusToSidebar() { this.yields++; } }; + const load = loader({}, { + '../../graphics/image': { GrayImage: class {} }, + '../../ui/shell/in-process-window': {}, '../../ui/shell/shell': { shell }, '../../ui/sound-effects': {}, + './data-collection-page': {}, './depth-page': {}, './ios-privacy-page': {}, './layout-page': {}, + './onboarding-progress': {}, './text-size-page': {}, './welcome-page': {}, + }); + const { OnboardingLayer } = load('app/apps/onboarding/onboarding-app.ts'); + let depthApplies = false; + const entered = []; + const page = (name, extra) => ({ ...extra, enter: () => entered.push(name), + handleInput: (event, nav) => { if (event.type === 'click') nav.next(); } }); + const fullscreen = []; + let finished = 0; + const layer = new OnboardingLayer([ + page('welcome', { fullscreen: true }), page('layout', { fullscreen: true }), + page('depth', { applies: () => depthApplies }), page('voice', {}), + ], (value) => fullscreen.push(value), () => finished++); + const input = (type) => layer.handleInput({ type }); + await input('click'); + await input('click'); + assert.deepEqual(entered, ['welcome', 'layout', 'voice'], 'depth skipped going forward'); + assert.deepEqual(fullscreen, [true, false]); + await input('double-click'); + assert.deepEqual(entered.at(-1), 'layout', 'and going back'); + depthApplies = true; + await input('click'); + await input('click'); + assert.deepEqual(entered.slice(-2), ['depth', 'voice']); + assert.deepEqual(fullscreen, [true, false, true, false, false]); + await input('click'); + assert.equal(finished, 1); + for (let i = 0; i < 4; i++) await input('double-click'); + assert.equal(entered.at(-1), 'welcome'); + assert.equal(shell.yields, 1, 'double-click on the first page leaves the app'); +}); From 5a9ca08921a154658a29973ad0feed7fe0c4832a Mon Sep 17 00:00:00 2001 From: James Babcock Date: Sat, 10 Oct 2026 22:48:26 -0700 Subject: [PATCH 10/65] Unify vertical position and display mode settings; add to onboarding --- app/apps/blocks/blocks-app.worker.ts | 2 +- app/apps/evenhub/evenhub-window.ts | 6 +- app/apps/navigate/navigate-app.worker.ts | 8 +- app/apps/onboarding/data-collection-page.ts | 2 +- app/apps/onboarding/depth-page.ts | 2 +- app/apps/onboarding/display-mode-page.ts | 94 ++++++++ app/apps/onboarding/index.ts | 4 +- app/apps/onboarding/ios-privacy-page.ts | 2 +- app/apps/onboarding/layout-diagram.ts | 177 +++++++++++++++ app/apps/onboarding/layout-page.ts | 173 ++------------- app/apps/onboarding/onboarding-app.ts | 13 +- app/apps/onboarding/onboarding-page.ts | 8 +- app/apps/onboarding/text-size-page.ts | 2 +- app/apps/onboarding/welcome-page.ts | 2 +- app/apps/pinball/pinball-app.worker.ts | 2 +- app/apps/terminal/terminal-app.worker.ts | 6 +- app/g2/dashboard-controller.ts | 32 +-- app/g2/ios-preview-controller.ts | 7 +- app/g2/wear-remote.ts | 15 -- app/phone-ui/remote-controls-view-model.ts | 17 +- app/phone-ui/remote-controls.xml | 2 +- app/ui/dashboard-settings.ts | 202 ++++++++++-------- app/ui/dashboard/settings-menus.ts | 11 +- app/ui/shell/chrome-layer.ts | 16 +- app/ui/shell/geometry.ts | 180 ++++++++-------- app/ui/shell/in-process-window.ts | 22 +- app/ui/shell/shell.ts | 4 +- tests/ai-chat.test.cjs | 2 +- tests/app-layout.test.cjs | 190 +++++++++------- tests/display-layout-setting.test.cjs | 66 ++++++ tests/ios-app-host.test.cjs | 2 +- tests/onboarding-layout.test.cjs | 66 +++++- tests/remote-controls.test.cjs | 9 +- wear/PROTOCOL.md | 6 +- .../main/kotlin/com/faceclaw/wear/Protocol.kt | 17 -- .../com/faceclaw/wear/ui/StatusScreen.kt | 15 -- 36 files changed, 810 insertions(+), 574 deletions(-) create mode 100644 app/apps/onboarding/display-mode-page.ts create mode 100644 app/apps/onboarding/layout-diagram.ts create mode 100644 tests/display-layout-setting.test.cjs diff --git a/app/apps/blocks/blocks-app.worker.ts b/app/apps/blocks/blocks-app.worker.ts index 2b570197..239a3366 100644 --- a/app/apps/blocks/blocks-app.worker.ts +++ b/app/apps/blocks/blocks-app.worker.ts @@ -49,7 +49,7 @@ const PANEL_X = 230; /** * Height the layout above is drawn for: a min-height window's viewport under * the standard top bar. A taller viewport (the status bar folded into the - * switcher row, a full-panel display) centers it vertically. + * switcher row, a Tall or Full Screen display) centers it vertically. */ const LAYOUT_HEIGHT = 260; diff --git a/app/apps/evenhub/evenhub-window.ts b/app/apps/evenhub/evenhub-window.ts index d359b2ee..a0937cb5 100644 --- a/app/apps/evenhub/evenhub-window.ts +++ b/app/apps/evenhub/evenhub-window.ts @@ -29,9 +29,9 @@ class EvenHubAppLayer implements Layer { paint(ctx: LayerContext): GrayImage { const size = ctx.stack.getBaseSize(); - // EvenHub apps lay out for the stock 576-wide surface. In the full-panel - // display mode the window is 640 wide; paint at stock width and centre - // it rather than leaving all the slack on the right. + // EvenHub apps lay out for the stock 576-wide surface. In the Full + // Screen display mode the window is 640 wide; paint at stock width and + // centre it rather than leaving all the slack on the right. if (size.width > EVENHUB_SCREEN_WIDTH) { const content = this.session.paint({ width: EVENHUB_SCREEN_WIDTH, height: size.height }, ctx.stack.isFocused()); const image = new GrayImage(size.width, size.height, 0); diff --git a/app/apps/navigate/navigate-app.worker.ts b/app/apps/navigate/navigate-app.worker.ts index db34f057..b79b09b1 100644 --- a/app/apps/navigate/navigate-app.worker.ts +++ b/app/apps/navigate/navigate-app.worker.ts @@ -33,8 +33,7 @@ import { navigateDestinationAddressDraftSetting, navigateDestinationNameDraftSetting, navigateRememberRecentSetting, - navigateDisplayModeSetting, - navigateVerticalPositionSetting, + navigateDisplayLayoutSetting, mapboxApiKeySetting, enumSettingMenuItem, type ConfigSettingString, @@ -935,10 +934,7 @@ function windowMenuItems(): MenuItem[] { }, }); } - items.push( - enumSettingMenuItem(navigateDisplayModeSetting), - enumSettingMenuItem(navigateVerticalPositionSetting), - ); + items.push(enumSettingMenuItem(navigateDisplayLayoutSetting)); items.push(submenuItem("Saved destinations", (ctx) => { ctx.stack.push(new WindowMenuLayer("Saved destinations", savedDestinationMenuItems())); })); diff --git a/app/apps/onboarding/data-collection-page.ts b/app/apps/onboarding/data-collection-page.ts index 91e944df..ad52e32b 100644 --- a/app/apps/onboarding/data-collection-page.ts +++ b/app/apps/onboarding/data-collection-page.ts @@ -13,7 +13,7 @@ const LABEL_GAP = 24; /** None / Minimal / Full, each with a one-line summary; a tap saves the selected level. */ export class DataCollectionPage implements OnboardingPage { - readonly fullscreen = true; + readonly immersive = true; /** Width of the level-name column, measured each paint. */ private labelColumnWidth = 0; private readonly menu = new Menu({ diff --git a/app/apps/onboarding/depth-page.ts b/app/apps/onboarding/depth-page.ts index fb7bd26a..ad3b1c1d 100644 --- a/app/apps/onboarding/depth-page.ts +++ b/app/apps/onboarding/depth-page.ts @@ -13,7 +13,7 @@ const COLUMN_WIDTH = 220; /** * The whole display's stereo depth, after a layout that has one (Bottom or - * Popup). Not fullscreen, so the page sits in the chosen layout, and the + * Popup). Not immersive, so the page sits in the chosen layout, and the * depth is saved as the selection moves: the shell shifts everything with * it, which is the only way to see the difference. */ diff --git a/app/apps/onboarding/display-mode-page.ts b/app/apps/onboarding/display-mode-page.ts new file mode 100644 index 00000000..b9d0a8e2 --- /dev/null +++ b/app/apps/onboarding/display-mode-page.ts @@ -0,0 +1,94 @@ +import type { GrayImage } from "../../graphics/image"; +import { wrapText } from "../../graphics/textwrap"; +import { displayLayoutSetting, type DisplayLayout } from "../../ui/dashboard-settings"; +import type { InputEvent } from "../../ui/gestures"; +import { Menu, type MenuDrawArgs } from "../../ui/menu-core"; +import { LIST_ROW_TEXT_INSET, listRowHeight } from "../../ui/metrics"; +import { onboardingFont } from "./onboarding-fonts"; +import { drawPageHeading, PAGE_X, type OnboardingNav, type OnboardingPage } from "./onboarding-page"; + +const CONTENT_GAP = 10; +const BOTTOM_MARGIN = 8; +const COLUMN_GAP = 16; + +const DESCRIPTIONS = { + band: "The stock 288px band, at this height in your view, leaving the rest of it clear.", + tall: "Windows use the display's full height.", + fullscreen: "Full height, and the display's whole width. Depth is turned off, since windows reach its edges.", +}; + +/** + * The display mode: how much of the display windows use (a band at one of + * five heights, Tall, or Full Screen where the layout allows it), with a + * line about the selected one. Not immersive, and the mode is saved as the + * selection moves, so this window itself shows each mode as it really is + * (the dashboard controller moves or resizes it, and every other window). + */ +export class DisplayModePage implements OnboardingPage { + private readonly menu = new Menu({ + wrap: false, + rowGap: 2, + highlight: { radius: 8 }, + getHeight: () => listRowHeight(onboardingFont("body")), + draw: (args) => this.drawRow(args), + }); + + enter(): void { + // Full Screen comes and goes with the layout; where the layout doesn't + // allow it, a saved Full Screen shows as Tall, as the shell does. + const values = displayLayoutSetting.values.filter((value) => !displayLayoutSetting.isDisabled(value)); + const index = values.indexOf(displayLayoutSetting.get()); + this.menu.setItems(values, index >= 0 ? index : values.indexOf("tall")); + } + + paint(image: GrayImage, focused: boolean): void { + const top = drawPageHeading( + image, + "Display mode", + "Swipe to choose how much of the display windows use; it changes as you go. Tap to continue.", + ) + CONTENT_GAP; + const body = onboardingFont("body"); + const columnWidth = 20 + Math.max(...this.menu.items.map((value) => body.measureText(displayLayoutSetting.displayValue(value)))); + const menuBox = { x: PAGE_X - 10, y: top, width: columnWidth, height: image.height - top - BOTTOM_MARGIN }; + this.menu.paint(image, menuBox, focused); + const layout = this.menu.selectedItem; + if (layout === null) return; + const detail = onboardingFont("detail"); + const left = menuBox.x + columnWidth + COLUMN_GAP; + let y = top + LIST_ROW_TEXT_INSET; + for (const line of wrapText(detail, description(layout), image.width - PAGE_X - left)) { + if (y + detail.lineHeight > image.height - BOTTOM_MARGIN) break; + image.drawText(detail, left, y, line, 170); + y += detail.lineHeight; + } + } + + handleInput(event: InputEvent, nav: OnboardingNav): void { + switch (event.type) { + case "scroll-up": + case "scroll-down": + void this.menu.handleInput(event); + this.apply(); + return; + case "click": + this.apply(); + nav.next(); + return; + default: + return; + } + } + + private apply(): void { + const layout = this.menu.selectedItem; + if (layout !== null && layout !== displayLayoutSetting.get()) displayLayoutSetting.set(layout); + } + + private drawRow({ image, item: layout, x, y, selected }: MenuDrawArgs): void { + image.drawText(onboardingFont("body"), x + 10, y + LIST_ROW_TEXT_INSET, displayLayoutSetting.displayValue(layout), selected ? 255 : 190); + } +} + +function description(layout: DisplayLayout): string { + return layout === "tall" || layout === "fullscreen" ? DESCRIPTIONS[layout] : DESCRIPTIONS.band; +} diff --git a/app/apps/onboarding/index.ts b/app/apps/onboarding/index.ts index 8de05881..727eac24 100644 --- a/app/apps/onboarding/index.ts +++ b/app/apps/onboarding/index.ts @@ -4,8 +4,8 @@ import { ONBOARDING_APP_ID } from "./onboarding-progress"; /** * First-run setup on the glasses: welcome, text size, data-collection - * preference, layout (app switcher position) and, for layouts that have - * one, depth. The connection controllers open it on their own when it is + * preference, layout (app switcher position), depth for layouts that have + * one, and display mode. The connection controllers open it on their own when it is * due (claimGlassesOnboardingAutoLaunch); the launcher entry reruns it. */ const onboardingApp: AppDefinition = { diff --git a/app/apps/onboarding/ios-privacy-page.ts b/app/apps/onboarding/ios-privacy-page.ts index 726d41af..dd3b94c6 100644 --- a/app/apps/onboarding/ios-privacy-page.ts +++ b/app/apps/onboarding/ios-privacy-page.ts @@ -7,7 +7,7 @@ import { drawPageHeading, PAGE_X, type OnboardingNav, type OnboardingPage } from /** Paginate the notice so no disclosure is silently clipped on a short glasses viewport. */ export class IosPrivacyPage implements OnboardingPage { - readonly fullscreen = true; + readonly immersive = true; private page = 0; private pageCount = 1; diff --git a/app/apps/onboarding/layout-diagram.ts b/app/apps/onboarding/layout-diagram.ts new file mode 100644 index 00000000..3ade4108 --- /dev/null +++ b/app/apps/onboarding/layout-diagram.ts @@ -0,0 +1,177 @@ +/** + * Schematic diagrams of the shell's layouts for the onboarding's Layout + * page: to scale in real-display pixels, simplified, and drawn brighter + * than the real chrome, which they shrink to a few pixels. + */ +import { G2_LENS_WIDTH, type GrayImage } from "../../graphics/image"; +import { statusBarPositionSetting, type AppSwitcherPosition } from "../../ui/dashboard-settings"; +import { SIDEBAR_WIDTH, SWITCHER_ROW_HEIGHT, MIN_WINDOW_HEIGHT, TOP_BAR_HEIGHT } from "../../ui/shell/geometry"; + +export const AREA_OUTLINE = 30; +const CHROME_LINE = 100; +const WINDOW_FRAME = 140; +const ICON = 160; +const SELECTED_ICON = 230; +const STATUS = 140; +const CONTENT = 110; +const CONTENT_TITLE = 170; +/** Window content under a popup switcher, which dims it. */ +const DIM = 0.5; + +/** Draws in real-display pixels, scaled into an image at (x, y). */ +export class Diagram { + constructor( + private readonly image: GrayImage, + private readonly x: number, + private readonly y: number, + private readonly scale: number, + ) {} + + private box(x: number, y: number, width: number, height: number) { + const left = this.x + Math.round(x * this.scale), top = this.y + Math.round(y * this.scale); + return { + x: left, + y: top, + width: Math.max(1, this.x + Math.round((x + width) * this.scale) - left), + height: Math.max(1, this.y + Math.round((y + height) * this.scale) - top), + }; + } + + fill(x: number, y: number, width: number, height: number, value: number, radius = 0): void { + const box = this.box(x, y, width, height); + if (radius) this.image.fillRoundedRect(box.x, box.y, box.width, box.height, value, Math.max(1, Math.round(radius * this.scale))); + else this.image.fillRect(box.x, box.y, box.width, box.height, value); + } + + outline(x: number, y: number, width: number, height: number, value: number, radius = 0): void { + const box = this.box(x, y, width, height); + this.image.drawRoundedRect(box.x, box.y, box.width, box.height, value, Math.max(0, Math.round(radius * this.scale))); + } + + /** A one-pixel line along a real-pixel row (horizontal) or column. */ + hline(x: number, y: number, width: number, value: number): void { + const box = this.box(x, y, width, 1); + this.image.fillRect(box.x, box.y, box.width, 1, value); + } + + vline(x: number, y: number, height: number, value: number): void { + const box = this.box(x, y, 1, height); + this.image.fillRect(box.x, box.y, 1, box.height, value); + } +} + +/** + * The foreground window's band, in real-display rows: its top and height + * (header and content; a bottom switcher row hangs under it), and whether + * it spans the panel's whole width (Full Screen; never beside a side strip). + */ +export type DiagramBand = { top: number; height: number; fullWidth: boolean }; + +/** + * A layout as the real chrome lays it out (geometry.ts, chrome-layer.ts): + * the window band with its status bar and frame, and the switcher with a + * few icons, the first selected. A popup switcher shows only with + * `popupOpen`, dimming the window as it does. Status bar placement follows + * the current setting. + */ +export function drawLayout(d: Diagram, position: AppSwitcherPosition, band: DiagramBand, popupOpen: boolean): void { + const statusAtBottom = statusBarPositionSetting.get() === "bottom"; + const { top, height } = band; + switch (position) { + case "left": + case "right": { + const stripLeft = position === "left" ? 0 : G2_LENS_WIDTH - SIDEBAR_WIDTH; + const contentLeft = position === "left" ? SIDEBAR_WIDTH : 0; + const windowWidth = G2_LENS_WIDTH - SIDEBAR_WIDTH; + drawStatusBar(d, contentLeft, top, windowWidth, TOP_BAR_HEIGHT - 1); + drawContent(d, contentLeft, top + TOP_BAR_HEIGHT, windowWidth, height - TOP_BAR_HEIGHT, 1); + // The strip keeps to the 288px band's height, even beside taller windows. + const separator = position === "left" ? SIDEBAR_WIDTH - 1 : stripLeft; + d.vline(separator, top + TOP_BAR_HEIGHT, MIN_WINDOW_HEIGHT - TOP_BAR_HEIGHT, CHROME_LINE); + // One column of icons against the separator. + const column = position === "left" ? SIDEBAR_WIDTH - 36 : stripLeft; + for (let slot = 0; slot < 4; slot++) drawIcon(d, column + 2, top + TOP_BAR_HEIGHT + 10 + slot * 40, slot === 0); + return; + } + case "bottom": { + const { left, width, framed } = windowSpan(band); + // With the status bar in the row, the window's header is just the frame's top. + const header = !statusAtBottom ? TOP_BAR_HEIGHT : framed ? 1 : 0; + if (!statusAtBottom) drawStatusBar(d, left, top, width, framed ? null : TOP_BAR_HEIGHT - 1); + drawContent(d, left, top + header, width, height - header, 1); + if (framed) d.outline(left - 1, top + header - 1, width + 2, height - header + 2, WINDOW_FRAME, 8); + else d.hline(left, top + height, width, CHROME_LINE); + // The first cell starts at the frame's side, or inset like a scrolled row's (chrome-layer switcherLayout). + const cellsLeft = framed ? left - 1 : left + 8; + for (let slot = 0; slot < 4; slot++) drawIcon(d, cellsLeft + 2 + slot * 40, top + height + 2, slot === 0); + if (statusAtBottom) drawStatusItems(d, left + width, top + height + 4); + return; + } + case "popup": { + const { left, width, framed } = windowSpan(band); + const edge = framed ? 1 : 0; + const statusTop = statusAtBottom ? top + height - TOP_BAR_HEIGHT : top; + const contentTop = statusAtBottom ? top + edge : top + TOP_BAR_HEIGHT; + const contentHeight = height - TOP_BAR_HEIGHT - edge; + drawStatusBar(d, left, statusTop, width, framed ? null : statusAtBottom ? 0 : TOP_BAR_HEIGHT - 1); + drawContent(d, left, contentTop, width, contentHeight, popupOpen ? DIM : 1); + if (framed) d.outline(left - 1, contentTop - 1, width + 2, contentHeight + 2, WINDOW_FRAME, 8); + if (!popupOpen) return; + // The popup: a row of icons over the selected window's title, centred on the content. + const box = { width: 272, height: 98 }; + const boxLeft = left + (width - box.width) / 2; + const boxTop = contentTop + (contentHeight - box.height) / 2; + d.fill(boxLeft, boxTop, box.width, box.height, 0); + d.outline(boxLeft, boxTop, box.width, box.height, WINDOW_FRAME); + const iconsLeft = boxLeft + (box.width - (3 * 48 - 4)) / 2; + for (let slot = 0; slot < 3; slot++) drawIcon(d, iconsLeft + slot * 48 + 6, boxTop + 18, slot === 0); + d.fill(boxLeft + box.width / 2 - 50, boxTop + 70, 100, 12, STATUS, 6); + return; + } + } +} + +/** A bottom row or popup layout's window: centred at 576 wide and framed, or the panel's width without a frame. */ +function windowSpan(band: DiagramBand): { left: number; width: number; framed: boolean } { + return band.fullWidth + ? { left: 0, width: G2_LENS_WIDTH, framed: false } + : { left: SIDEBAR_WIDTH / 2, width: G2_LENS_WIDTH - SIDEBAR_WIDTH, framed: true }; +} + +/** + * A status bar's 28 rows from `y`; `divider` is the row (within them) of its + * line toward the window, if it draws one rather than meeting a frame. + */ +function drawStatusBar(d: Diagram, x: number, y: number, width: number, divider: number | null): void { + if (divider !== null) d.hline(x, y + divider, width, CHROME_LINE); + drawStatusItems(d, x + width, y); +} + +/** Notification icons, a battery and the clock, ending at `right`, in a status bar's 28 rows from `top`. */ +function drawStatusItems(d: Diagram, right: number, top: number): void { + d.fill(right - 64, top + 7, 56, 14, STATUS, 4); + d.outline(right - 108, top + 8, 32, 12, STATUS, 2); + d.outline(right - 148, top + 4, 20, 20, CHROME_LINE, 4); + d.outline(right - 176, top + 4, 20, 20, CHROME_LINE, 4); +} + +/** A switcher icon (32px); the selected one filled, as the switcher's selection tab is. */ +function drawIcon(d: Diagram, x: number, y: number, selected: boolean): void { + if (selected) d.fill(x, y, 32, 32, SELECTED_ICON, 6); + else d.outline(x, y, 32, 32, ICON, 6); +} + +/** Stand-in window content: a title and as many list rows as fit, the first selected. */ +function drawContent(d: Diagram, x: number, y: number, width: number, height: number, brightness: number): void { + const rowWidths = [width - 60, 300, 360, 240]; + d.fill(x + 18, y + 14, 150, 18, Math.round(CONTENT_TITLE * brightness), 6); + d.outline(x + 8, y + 44, width - 16, 34, Math.round(CONTENT * brightness), 8); + for (let row = 0; ; row++) { + const rowTop = y + 52 + row * 44; + if (rowTop + 18 > y + height - 8) break; + d.fill(x + 18, rowTop, Math.min(rowWidths[row % rowWidths.length]!, width - 36), 18, Math.round(CONTENT * brightness), 6); + } +} + +/** Real-display rows the Layout page's diagrams cover: a 288px band and a bottom switcher row under it. */ +export const LAYOUT_AREA_HEIGHT = MIN_WINDOW_HEIGHT + SWITCHER_ROW_HEIGHT; diff --git a/app/apps/onboarding/layout-page.ts b/app/apps/onboarding/layout-page.ts index 51aa7c05..0d2eae6c 100644 --- a/app/apps/onboarding/layout-page.ts +++ b/app/apps/onboarding/layout-page.ts @@ -1,8 +1,9 @@ import { G2_LENS_WIDTH, type GrayImage, type UiFont } from "../../graphics/image"; -import { appSwitcherPositionSetting, statusBarPositionSetting, type AppSwitcherPosition } from "../../ui/dashboard-settings"; +import { appSwitcherPositionSetting, type AppSwitcherPosition } from "../../ui/dashboard-settings"; import type { InputEvent } from "../../ui/gestures"; import { MENU_HIGHLIGHT_FILL, MENU_HIGHLIGHT_STROKE } from "../../ui/menu-core"; -import { MIN_WINDOW_HEIGHT, SIDEBAR_WIDTH, SWITCHER_ROW_HEIGHT, TOP_BAR_HEIGHT } from "../../ui/shell/geometry"; +import { MIN_WINDOW_HEIGHT } from "../../ui/shell/geometry"; +import { AREA_OUTLINE, Diagram, drawLayout, LAYOUT_AREA_HEIGHT } from "./layout-diagram"; import { onboardingFont } from "./onboarding-fonts"; import { drawPageHeading, type OnboardingNav, type OnboardingPage } from "./onboarding-page"; @@ -10,8 +11,6 @@ const CONTENT_GAP = 10; const BOTTOM_MARGIN = 8; /** Diagram width as a fraction of the display's: the most a diagram is drawn at. */ const DIAGRAM_SCALE = 0.4; -/** The real-display area a diagram covers: a 288px window band and a bottom switcher row under it. */ -const DIAGRAM_AREA_HEIGHT = MIN_WINDOW_HEIGHT + SWITCHER_ROW_HEIGHT; /** Padding inside a cell's selection box, round the diagram and its caption. */ const CELL_PADDING = 8; const CAPTION_GAP = 4; @@ -32,12 +31,12 @@ export function layoutHasDepth(position: AppSwitcherPosition): boolean { * The app switcher position, as a 2×2 grid of captioned diagrams of each * layout, Bottom (recommended, and selected at first) and Popup on top; * swipes move through them in reading order, a tap saves the selected one. - * The page is fullscreen, so the diagrams get 40% of the display's width + * The page is immersive, so the diagrams get 40% of the display's width * each. Choosing a layout reflows open windows (the dashboard controller * watches the setting). */ export class LayoutPage implements OnboardingPage { - readonly fullscreen = true; + readonly immersive = true; /** Kept across visits, so going back returns to the last choice. */ private selected = LAYOUT_ORDER.indexOf(RECOMMENDED_LAYOUT); @@ -54,11 +53,11 @@ export class LayoutPage implements OnboardingPage { // Short of DIAGRAM_SCALE only where two rows of cells wouldn't fit. const scale = Math.min( DIAGRAM_SCALE, - ((available - ROW_GAP) / 2 - 2 * CELL_PADDING - captionHeight) / DIAGRAM_AREA_HEIGHT, + ((available - ROW_GAP) / 2 - 2 * CELL_PADDING - captionHeight) / LAYOUT_AREA_HEIGHT, ((image.width - COLUMN_GAP) / 2 - 2 * CELL_PADDING) / G2_LENS_WIDTH, ); const diagramWidth = Math.round(G2_LENS_WIDTH * scale); - const diagramHeight = Math.round(DIAGRAM_AREA_HEIGHT * scale); + const diagramHeight = Math.round(LAYOUT_AREA_HEIGHT * scale); const cellWidth = diagramWidth + 2 * CELL_PADDING; const cellHeight = diagramHeight + 2 * CELL_PADDING + captionHeight; const left = Math.round((image.width - 2 * cellWidth - COLUMN_GAP) / 2); @@ -103,157 +102,13 @@ export class LayoutPage implements OnboardingPage { } } -// Diagram brightnesses: brighter than the real chrome's, which the diagrams -// shrink to a few pixels. -const AREA_OUTLINE = 30; -const CHROME_LINE = 100; -const WINDOW_FRAME = 140; -const ICON = 160; -const SELECTED_ICON = 230; -const STATUS = 140; -const CONTENT = 110; -const CONTENT_TITLE = 170; -/** Window content under a popup switcher, which dims it. */ -const DIM = 0.5; - /** - * Draws in real-display pixels, scaled into a cell: the DIAGRAM_AREA_HEIGHT - * rows from the diagram's top, or from `top` rows down (see from). + * A layout's diagram: the 288px band, with the popup switcher open. Only a + * bottom switcher row takes rows under the band; without one, the band sits + * centred in their place, as the band and row share the screen's slack. */ -class Diagram { - constructor( - private readonly image: GrayImage, - private readonly x: number, - private readonly y: number, - private readonly scale: number, - private readonly top = 0, - ) {} - - /** The same diagram with its row 0 `top` rows down. */ - from(top: number): Diagram { - return new Diagram(this.image, this.x, this.y, this.scale, top); - } - - private box(x: number, y: number, width: number, height: number) { - y += this.top; - const left = this.x + Math.round(x * this.scale), top = this.y + Math.round(y * this.scale); - return { - x: left, - y: top, - width: Math.max(1, this.x + Math.round((x + width) * this.scale) - left), - height: Math.max(1, this.y + Math.round((y + height) * this.scale) - top), - }; - } - - fill(x: number, y: number, width: number, height: number, value: number, radius = 0): void { - const box = this.box(x, y, width, height); - if (radius) this.image.fillRoundedRect(box.x, box.y, box.width, box.height, value, Math.max(1, Math.round(radius * this.scale))); - else this.image.fillRect(box.x, box.y, box.width, box.height, value); - } - - outline(x: number, y: number, width: number, height: number, value: number, radius = 0): void { - const box = this.box(x, y, width, height); - this.image.drawRoundedRect(box.x, box.y, box.width, box.height, value, Math.max(0, Math.round(radius * this.scale))); - } - - /** A one-pixel line along a real-pixel row (horizontal) or column. */ - hline(x: number, y: number, width: number, value: number): void { - const box = this.box(x, y, width, 1); - this.image.fillRect(box.x, box.y, box.width, 1, value); - } - - vline(x: number, y: number, height: number, value: number): void { - const box = this.box(x, y, 1, height); - this.image.fillRect(box.x, box.y, 1, box.height, value); - } -} - -/** - * A layout as the real chrome lays it out (geometry.ts, chrome-layer.ts), - * to scale and simplified: the window band with its status bar and frame, - * and the switcher with a few icons, the first selected. Status bar - * placement follows the current setting. Only a bottom switcher row takes - * rows under the band; without one, the band sits centred in their place, - * as the band and row share the screen's slack. - */ -function drawLayoutDiagram(area: Diagram, position: AppSwitcherPosition): void { - area.outline(0, 0, G2_LENS_WIDTH, DIAGRAM_AREA_HEIGHT, AREA_OUTLINE, 12); - const d = position === "bottom" ? area : area.from((DIAGRAM_AREA_HEIGHT - MIN_WINDOW_HEIGHT) / 2); - const statusAtBottom = statusBarPositionSetting.get() === "bottom"; - const windowLeft = SIDEBAR_WIDTH / 2, windowWidth = G2_LENS_WIDTH - SIDEBAR_WIDTH; - switch (position) { - case "left": - case "right": { - const stripLeft = position === "left" ? 0 : G2_LENS_WIDTH - SIDEBAR_WIDTH; - const contentLeft = position === "left" ? SIDEBAR_WIDTH : 0; - drawStatusBar(d, contentLeft, 0, windowWidth, true); - drawContent(d, contentLeft, TOP_BAR_HEIGHT, windowWidth, MIN_WINDOW_HEIGHT - TOP_BAR_HEIGHT, 1); - const separator = position === "left" ? SIDEBAR_WIDTH - 1 : stripLeft; - d.vline(separator, TOP_BAR_HEIGHT, MIN_WINDOW_HEIGHT - TOP_BAR_HEIGHT, CHROME_LINE); - // One column of icons against the separator. - const column = position === "left" ? SIDEBAR_WIDTH - 36 : stripLeft; - for (let slot = 0; slot < 4; slot++) drawIcon(d, column + 2, TOP_BAR_HEIGHT + 10 + slot * 40, slot === 0); - return; - } - case "bottom": { - // With the status bar in the row, the window's header is just the frame's top. - const contentTop = statusAtBottom ? 1 : TOP_BAR_HEIGHT; - if (!statusAtBottom) drawStatusBar(d, windowLeft, 0, windowWidth, false); - drawContent(d, windowLeft, contentTop, windowWidth, MIN_WINDOW_HEIGHT - contentTop, 1); - d.outline(windowLeft - 1, contentTop - 1, windowWidth + 2, MIN_WINDOW_HEIGHT - contentTop + 2, WINDOW_FRAME, 8); - for (let slot = 0; slot < 4; slot++) drawIcon(d, windowLeft + 1 + slot * 40, MIN_WINDOW_HEIGHT + 2, slot === 0); - if (statusAtBottom) drawStatusItems(d, windowLeft + windowWidth, MIN_WINDOW_HEIGHT + 4); - return; - } - case "popup": { - const statusTop = statusAtBottom ? MIN_WINDOW_HEIGHT - TOP_BAR_HEIGHT : 0; - const contentTop = statusAtBottom ? 1 : TOP_BAR_HEIGHT; - const contentHeight = MIN_WINDOW_HEIGHT - TOP_BAR_HEIGHT - 1; - drawStatusBar(d, windowLeft, statusTop, windowWidth, false); - drawContent(d, windowLeft, contentTop, windowWidth, contentHeight, DIM); - d.outline(windowLeft - 1, contentTop - 1, windowWidth + 2, contentHeight + 2, WINDOW_FRAME, 8); - // The popup: a row of icons over the selected window's title, centred on the content. - const box = { width: 272, height: 98 }; - const boxLeft = (G2_LENS_WIDTH - box.width) / 2; - const boxTop = contentTop + (contentHeight - box.height) / 2; - d.fill(boxLeft, boxTop, box.width, box.height, 0); - d.outline(boxLeft, boxTop, box.width, box.height, WINDOW_FRAME); - const iconsLeft = boxLeft + (box.width - (3 * 48 - 4)) / 2; - for (let slot = 0; slot < 3; slot++) drawIcon(d, iconsLeft + slot * 48 + 6, boxTop + 18, slot === 0); - d.fill(G2_LENS_WIDTH / 2 - 50, boxTop + 70, 100, 12, STATUS, 6); - return; - } - } -} - -/** A status bar along a window's top or bottom edge; `divider` draws its line toward the window. */ -function drawStatusBar(d: Diagram, x: number, y: number, width: number, divider: boolean): void { - if (divider) d.hline(x, y + TOP_BAR_HEIGHT - 1, width, CHROME_LINE); - drawStatusItems(d, x + width, y); -} - -/** Notification icons, a battery and the clock, ending at `right`, in a status bar's 28 rows from `top`. */ -function drawStatusItems(d: Diagram, right: number, top: number): void { - d.fill(right - 64, top + 7, 56, 14, STATUS, 4); - d.outline(right - 108, top + 8, 32, 12, STATUS, 2); - d.outline(right - 148, top + 4, 20, 20, CHROME_LINE, 4); - d.outline(right - 176, top + 4, 20, 20, CHROME_LINE, 4); -} - -/** A switcher icon (32px); the selected one filled, as the switcher's selection tab is. */ -function drawIcon(d: Diagram, x: number, y: number, selected: boolean): void { - if (selected) d.fill(x, y, 32, 32, SELECTED_ICON, 6); - else d.outline(x, y, 32, 32, ICON, 6); -} - -/** Stand-in window content: a title and list rows, the first selected. */ -function drawContent(d: Diagram, x: number, y: number, width: number, height: number, brightness: number): void { - const rowWidths = [width - 60, 300, 360, 240]; - d.fill(x + 18, y + 14, 150, 18, CONTENT_TITLE * brightness, 6); - d.outline(x + 8, y + 44, width - 16, 34, CONTENT * brightness, 8); - for (let row = 0; row < rowWidths.length; row++) { - const rowTop = y + 52 + row * 44; - if (rowTop + 18 > y + height) break; - d.fill(x + 18, rowTop, Math.min(rowWidths[row]!, width - 36), 18, CONTENT * brightness, 6); - } +function drawLayoutDiagram(d: Diagram, position: AppSwitcherPosition): void { + d.outline(0, 0, G2_LENS_WIDTH, LAYOUT_AREA_HEIGHT, AREA_OUTLINE, 12); + const top = position === "bottom" ? 0 : (LAYOUT_AREA_HEIGHT - MIN_WINDOW_HEIGHT) / 2; + drawLayout(d, position, { top, height: MIN_WINDOW_HEIGHT, fullWidth: false }, true); } diff --git a/app/apps/onboarding/onboarding-app.ts b/app/apps/onboarding/onboarding-app.ts index 1aa56c96..66a7000d 100644 --- a/app/apps/onboarding/onboarding-app.ts +++ b/app/apps/onboarding/onboarding-app.ts @@ -6,6 +6,7 @@ import { shell } from "../../ui/shell/shell"; import { findSoundEffect, playSoundEffect } from "../../ui/sound-effects"; import { DataCollectionPage } from "./data-collection-page"; import { DepthPage } from "./depth-page"; +import { DisplayModePage } from "./display-mode-page"; import { IosPrivacyPage } from "./ios-privacy-page"; import { LayoutPage } from "./layout-page"; import { markGlassesOnboardingFinished, ONBOARDING_APP_ID } from "./onboarding-progress"; @@ -27,7 +28,7 @@ export function createOnboardingAppWindow(options: InProcessAppOptions): InProce const pages: OnboardingPage[] = [ new WelcomePage(), new TextSizePage(), ...(global.isIOS ? [new IosPrivacyPage()] : []), - new DataCollectionPage(), new LayoutPage(), new DepthPage(), + new DataCollectionPage(), new LayoutPage(), new DepthPage(), new DisplayModePage(), ]; const app = createInProcessWindow({ appId: ONBOARDING_APP_ID, @@ -36,12 +37,12 @@ export function createOnboardingAppWindow(options: InProcessAppOptions): InProce iconLetter: "On", icon: "sparkles", closeable: true, - fullscreen: pages[0]!.fullscreen, + immersive: pages[0]!.immersive, actions: options.actions, baseLayer: new OnboardingLayer( pages, // Only called on page changes, by when `app` is set. - (fullscreen) => app.setFullscreen(fullscreen), + (immersive) => app.setImmersive(immersive), () => { markGlassesOnboardingFinished(); shell.closeWindow(ONBOARDING_WINDOW_ID); @@ -69,7 +70,7 @@ function playWelcomeSound(actions: LayerActions): void { } /** - * Hosts the current page, fullscreen or not as it asks. Double-click steps + * Hosts the current page, immersive or not as it asks. Double-click steps * back a page, or leaves the app from the first one (the standard yield to * the app switcher); every other gesture goes to the page. Pages that don't * apply (Depth beside a side-strip app switcher) are skipped either way. @@ -79,7 +80,7 @@ export class OnboardingLayer implements Layer { constructor( private readonly pages: readonly OnboardingPage[], - private readonly setFullscreen: (fullscreen: boolean) => void, + private readonly setImmersive: (immersive: boolean) => void, private readonly finish: () => void, ) { pages[0]!.enter?.(); @@ -120,6 +121,6 @@ export class OnboardingLayer implements Layer { this.index = index; const page = this.pages[index]!; page.enter?.(); - this.setFullscreen(page.fullscreen ?? false); + this.setImmersive(page.immersive ?? false); } } diff --git a/app/apps/onboarding/onboarding-page.ts b/app/apps/onboarding/onboarding-page.ts index 8f2d1541..5081854d 100644 --- a/app/apps/onboarding/onboarding-page.ts +++ b/app/apps/onboarding/onboarding-page.ts @@ -16,11 +16,11 @@ export type OnboardingNav = { */ export interface OnboardingPage { /** - * Show the page fullscreen: the whole 640×480 panel, with the app switcher - * and status bar hidden. Otherwise it is an ordinary window in the - * chosen layout. + * Show the page immersive (full-screen): the whole 640×480 panel, with + * the app switcher and status bar hidden. Otherwise it is an ordinary + * window in the chosen layout. */ - readonly fullscreen?: boolean; + readonly immersive?: boolean; /** Whether the page belongs in the flow right now; skipped both ways when false. */ applies?(): boolean; /** The page became current, going forward or back. */ diff --git a/app/apps/onboarding/text-size-page.ts b/app/apps/onboarding/text-size-page.ts index 49969c36..4c67627c 100644 --- a/app/apps/onboarding/text-size-page.ts +++ b/app/apps/onboarding/text-size-page.ts @@ -48,7 +48,7 @@ type Face = * while scrolling. */ export class TextSizePage implements OnboardingPage { - readonly fullscreen = true; + readonly immersive = true; private face: Face = { kind: "fixed", label: "Terminus" }; private readonly sizeMenu = new Menu({ wrap: false, diff --git a/app/apps/onboarding/welcome-page.ts b/app/apps/onboarding/welcome-page.ts index 1a96b715..4d9c62b4 100644 --- a/app/apps/onboarding/welcome-page.ts +++ b/app/apps/onboarding/welcome-page.ts @@ -16,7 +16,7 @@ type TextLine = { font: UiFont; text: string; value: number; spaceBefore: number /** The splash: logo beside the name, version and how to go on, centred as one group. */ export class WelcomePage implements OnboardingPage { - readonly fullscreen = true; + readonly immersive = true; paint(image: GrayImage): void { const { width, height } = image; diff --git a/app/apps/pinball/pinball-app.worker.ts b/app/apps/pinball/pinball-app.worker.ts index 9881d602..13d5242e 100644 --- a/app/apps/pinball/pinball-app.worker.ts +++ b/app/apps/pinball/pinball-app.worker.ts @@ -66,7 +66,7 @@ const PANEL_X = 310; /** * Height the table and panel are drawn for: a min-height window's viewport * under the standard top bar. A taller viewport (the status bar folded into - * the switcher row, a full-panel display) centers the layout vertically. + * the switcher row, a Tall or Full Screen display) centers the layout vertically. */ const LAYOUT_HEIGHT = 260; diff --git a/app/apps/terminal/terminal-app.worker.ts b/app/apps/terminal/terminal-app.worker.ts index 6cf44429..87bf9fdc 100644 --- a/app/apps/terminal/terminal-app.worker.ts +++ b/app/apps/terminal/terminal-app.worker.ts @@ -55,10 +55,9 @@ import { clamp } from "../../util/numeric-util"; import { enumSettingMenuItem, terminalAutoReconnectSetting, - terminalDisplayModeSetting, + terminalDisplayLayoutSetting, terminalLaunchPresetsSetting, terminalNewConnectionSetting, - terminalVerticalPositionSetting, terminalWakeOnBellSetting, textSettingMenuItem, toggleSettingMenuItem, @@ -1118,8 +1117,7 @@ function windowMenuItems(window: TerminalWindow): MenuItem[] { */ function settingsMenuItems(): MenuItem[] { return [ - enumSettingMenuItem(terminalDisplayModeSetting), - enumSettingMenuItem(terminalVerticalPositionSetting), + enumSettingMenuItem(terminalDisplayLayoutSetting), terminalFontPickerMenuItem(), // Opens the phone text editor; the settings listener repaints its page. textSettingMenuItem(terminalLaunchPresetsSetting), diff --git a/app/g2/dashboard-controller.ts b/app/g2/dashboard-controller.ts index 3bee2934..53ce6cb8 100644 --- a/app/g2/dashboard-controller.ts +++ b/app/g2/dashboard-controller.ts @@ -72,7 +72,7 @@ import { loadPersistedOpenApps, savePersistedOpenApps } from "../ui/shell/open-a import { appViewportRect, isOnSwitcherEdge, sidebarStripVisible, type WindowHeightMode } from "../ui/shell/geometry"; import { type LayerActions, type TextSettingsEditToggle } from "../ui/layers"; import { type KeyboardInputSession } from "../ui/shell/keyboard-input"; -import { appSwitcherPositionSetting, statusBarPositionSetting, statusBarVisibilitySetting, windowBorderSetting, assistantAllowProactiveSetting, assistantBackendSetting, assistantBridgeHostSetting, assistantBridgePortSetting, assistantBridgeTokenSetting, getBrightnessPreferences, displayModeSetting, navigateDisplayModeSetting, navigateVerticalPositionSetting, terminalDisplayModeSetting, terminalVerticalPositionSetting, elevenLabsApiKeySetting, getStringSettingById, openAiApiKeySetting, nightscoutApiTokenSetting, firmwareDebugFlagsSetting, lockScreenEnabledSetting, nightscoutSiteUrlSetting, onAnySettingChanged, previewColorSetting, ringConnectionModeSetting, saveVoiceRecordingsSetting, sonioxApiKeySetting, screenTimeoutSetting, screenTimeoutSettingToMs, suspendEvenHubWhenScreenOffSetting, verticalPositionSetting, voiceProviderSetting, wakeWordActionSetting, type ConfigSettingString } from "../ui/dashboard-settings"; +import { appSwitcherPositionSetting, statusBarPositionSetting, statusBarVisibilitySetting, windowBorderSetting, assistantAllowProactiveSetting, assistantBackendSetting, assistantBridgeHostSetting, assistantBridgePortSetting, assistantBridgeTokenSetting, getBrightnessPreferences, displayLayoutSetting, navigateDisplayLayoutSetting, terminalDisplayLayoutSetting, elevenLabsApiKeySetting, getStringSettingById, openAiApiKeySetting, nightscoutApiTokenSetting, firmwareDebugFlagsSetting, lockScreenEnabledSetting, nightscoutSiteUrlSetting, onAnySettingChanged, previewColorSetting, ringConnectionModeSetting, saveVoiceRecordingsSetting, sonioxApiKeySetting, screenTimeoutSetting, screenTimeoutSettingToMs, suspendEvenHubWhenScreenOffSetting, voiceProviderSetting, wakeWordActionSetting, type ConfigSettingString } from "../ui/dashboard-settings"; import { isIgnoringBatteryOptimizations, requestIgnoreBatteryOptimizations } from "../native/battery-optimization"; import { getInstalledEvenHubAppById, @@ -184,24 +184,26 @@ const EVEN_APP_DETECTED_MESSAGE = const LAUNCHABLE_APPS = ALL_APPS.filter((app) => app.showInLauncher !== false); /** - * The global settings window viewport sizes depend on: the display mode, - * whether the app switcher takes width beside windows, height below them - * or neither (a popup), and the chrome rows each window loses to it: below - * them, whether the status bar joins the row (dropping the top bar); with a - * popup, whether the status bar keeps rows of its own and the window frame - * (where the status bar goes only moves windows). + * The global settings window viewport sizes depend on: the display mode's + * size (a band's position only moves windows), whether the app switcher + * takes width beside windows, height below them or neither (a popup), and + * the chrome rows each window loses to it: below them, whether the status + * bar joins the row (dropping the top bar); with a popup, whether the + * status bar keeps rows of its own and the window frame (where the status + * bar goes only moves windows). */ function viewportSizesKey(): string { const position = appSwitcherPositionSetting.get(); const switcher = position === "bottom" ? `row|${statusBarPositionSetting.get()}` : position === "popup" ? `popup|${statusBarVisibilitySetting.get()}|${windowBorderSetting.get()}` : "strip"; - return `${displayModeSetting.get()}|${switcher}`; + const layout = displayLayoutSetting.get(); + return `${layout.startsWith("band-") ? "band" : layout}|${switcher}`; } /** The global settings that move window surfaces without resizing them. */ function windowPlacementKey(): string { - return `${verticalPositionSetting.get()}|${appSwitcherPositionSetting.get()}|${statusBarPositionSetting.get()}`; + return `${displayLayoutSetting.get()}|${appSwitcherPositionSetting.get()}|${statusBarPositionSetting.get()}`; } function createInitialDisplayPreview(): ImageSource | null { @@ -449,8 +451,8 @@ class DashboardController { this.pushFirmwareDebugFlags(); this.pushBrightness(); this.syncEvenHubScreenOffSetting(); - // Display mode first: a reflow repositions every surface too, so the - // vertical-position check after it then has nothing left to do. + // Display mode size first: a reflow repositions every surface too, so + // the band-position check after it then has nothing left to do. this.applyDisplayModeIfChanged(); this.applyVerticalPositionIfChanged(); this.applyAppLayoutsIfChanged(); @@ -530,7 +532,7 @@ class DashboardController { }); } - // Vertical-position changes (and moving the app switcher between the left + // Band position changes (and moving the app switcher between the left // and right edges, or a popup switcher's status bar between the top and // bottom) move every window surface and the chrome that aligns with them; // the values are tracked so unrelated setting changes don't trigger a full @@ -540,7 +542,7 @@ class DashboardController { private lastViewportSizes = viewportSizesKey(); /** - * Display mode changed (Settings > Display, or the phone page's picker), + * Display mode size changed (Settings > Display, or the phone page's picker), * or the app switcher or its chrome changed what windows lose to them * (see viewportSizesKey): every window's viewport size changes. In-process windows re-measure in place; workers * that support resizing receive the new viewport. Other worker windows are @@ -586,8 +588,8 @@ class DashboardController { private appLayouts(): Record { return { - navigate: `${navigateDisplayModeSetting.get()}:${navigateVerticalPositionSetting.get()}`, - terminal: `${terminalDisplayModeSetting.get()}:${terminalVerticalPositionSetting.get()}`, + navigate: navigateDisplayLayoutSetting.get(), + terminal: terminalDisplayLayoutSetting.get(), }; } diff --git a/app/g2/ios-preview-controller.ts b/app/g2/ios-preview-controller.ts index feace883..699414e5 100644 --- a/app/g2/ios-preview-controller.ts +++ b/app/g2/ios-preview-controller.ts @@ -44,7 +44,7 @@ import { noopLayerActions, type LayerActions } from '../ui/layers' import { TextViewerLayer } from '../apps/files/text-viewer' import { shell, rawInputEventToInputEvent, type ShellWindow } from '../ui/shell/shell' import { appViewportRect, isOnSwitcherEdge, sidebarStripVisible } from '../ui/shell/geometry' -import { DISPLAY_MODE_VALUES, displayModeLabel, displayModeSetting, onAnySettingChanged, +import { onAnySettingChanged, previewColorSetting, lockScreenEnabledSetting, getBrightnessPreferences, getStringSettingById, nightscoutSiteUrlSetting, nightscoutApiTokenSetting } from '../ui/dashboard-settings' import type { PhoneGesture } from '../phone-ui/phone-gestures' @@ -658,11 +658,6 @@ export class IosPreviewController { this.appHosts.set(appId, host) return host } - cycleDisplayMode(): void { - const values = DISPLAY_MODE_VALUES - displayModeSetting.set(values[(values.indexOf(displayModeSetting.get()) + 1) % values.length]) - } - get displayModeLabel(): string { return displayModeLabel(displayModeSetting.get()) } get connectionState(): SessionState | null { return this.sessionCreated ? this.state : null } get connectionDetails(): string { const state = this.connectionState diff --git a/app/g2/wear-remote.ts b/app/g2/wear-remote.ts index 492fb9d8..9ce66457 100644 --- a/app/g2/wear-remote.ts +++ b/app/g2/wear-remote.ts @@ -28,8 +28,6 @@ import { type AppDefinition } from "../apps/app-definition"; import { getInstalledEvenHubApps, installedEvenHubAppId } from "../apps/evenhub/installed-apps"; import { WEAR_PATHS, wearBridge, type WearMessage } from "../native/wear-bridge"; import { - DISPLAY_MODE_VALUES, - displayModeSetting, onAnySettingChanged, watchCanUnlockSetting, watchCrownClockwiseNextSetting, @@ -88,7 +86,6 @@ const COMMANDS = [ "connect", "disconnect", "close-assistant", - "display-mode", ] as const; type WearCommand = (typeof COMMANDS)[number]; @@ -277,7 +274,6 @@ export class WearRemote { acceptsText: typeof window.receiveTextInput === "function", })), apps: this.listApps(), - displayMode: displayModeSetting.get(), remoteEnabled: watchRemoteEnabledSetting.get(), crownClockwiseNext: watchCrownClockwiseNextSetting.get(), canUnlock: watchCanUnlockSetting.get(), @@ -522,17 +518,6 @@ export class WearRemote { // but tell the watch which of the two happened. ack(true, shell.closeAssistant() ? "" : "The assistant was not open."); return; - case "display-mode": { - const value = String(payload.value ?? ""); - if (!(DISPLAY_MODE_VALUES as readonly string[]).includes(value)) { - ack(false, `Unknown display mode: ${value}`); - return; - } - displayModeSetting.set(value as (typeof DISPLAY_MODE_VALUES)[number]); - this.schedulePublish(); - ack(true, `Display mode: ${value}`); - return; - } default: ack(false, `Unhandled command: ${command}`); } diff --git a/app/phone-ui/remote-controls-view-model.ts b/app/phone-ui/remote-controls-view-model.ts index b846cea9..8efdd3d8 100644 --- a/app/phone-ui/remote-controls-view-model.ts +++ b/app/phone-ui/remote-controls-view-model.ts @@ -1,8 +1,5 @@ import { Dialogs, Observable } from '@nativescript/core'; -import { - brightnessSetting, DISPLAY_MODE_VALUES, displayModeLabel, displayModeSetting, - type BrightnessSetting, type DisplayModeSetting, -} from '../ui/dashboard-settings'; +import { brightnessSetting, displayLayoutSetting, type BrightnessSetting } from '../ui/dashboard-settings'; type ControlsTab = 'settings' | 'watch' | 'ring'; // Remember the tab across navigation on both platforms, without persisting it. @@ -65,17 +62,19 @@ export class RemoteControlsViewModel extends Observable { // ---- display mode and brightness, on the Settings tab ---- get displayModeLabel(): string { - return displayModeLabel(displayModeSetting.get()) + " ▾"; + return displayLayoutSetting.displayValue() + " ▾"; } async onDisplayModeTap(): Promise { - const current = displayModeSetting.get(); - const options = DISPLAY_MODE_VALUES.map((value) => displayModeLabel(value) + (value === current ? " ✓" : "")); + const current = displayLayoutSetting.get(); + // Full Screen is offered only with a bottom or popup app switcher. + const values = displayLayoutSetting.values.filter((value) => !displayLayoutSetting.isDisabled(value)); + const options = values.map((value) => displayLayoutSetting.displayValue(value) + (value === current ? " ✓" : "")); const picked = await Dialogs.action({ title: "Display mode", cancelButtonText: "Cancel", actions: options }); const index = options.indexOf(picked); if (index < 0) return; - const value = DISPLAY_MODE_VALUES[index] as DisplayModeSetting; - if (value !== current) displayModeSetting.set(value); + const value = values[index]!; + if (value !== current) displayLayoutSetting.set(value); this.notifyPropertyChange("displayModeLabel", this.displayModeLabel); } diff --git a/app/phone-ui/remote-controls.xml b/app/phone-ui/remote-controls.xml index 4790537f..943d39e9 100644 --- a/app/phone-ui/remote-controls.xml +++ b/app/phone-ui/remote-controls.xml @@ -38,7 +38,7 @@ -