EvenHub extensions: Fonts, window icons, touch-start events

This commit is contained in:
James Babcock committed 2026-10-07 01:22:42 -07:00
1 parent 4ee0af86cc
commit 84baee9c76
25 files changed
+1884 -127

No files matched your search

+9 -11
View File
@@ -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. */
+18 -4
View File
@@ -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<string, unknown>): number {
return Math.max(0, Math.min(MAX_BORDER_WIDTH, readNumber(json, "borderWidth", 0)));
}
function parseTextContainer(json: Record<string, unknown>): EvenHubTextContainer {
/** A container's font: its own `font` over the layout-wide default. */
function readFont(json: Record<string, unknown>, layoutFont: EvenHubFontSpec | undefined): EvenHubFontSpec | undefined {
return mergeFontSpecs(layoutFont, parseFontSpec(pickLoose(json, "font")));
}
function parseTextContainer(json: Record<string, unknown>, layoutFont: EvenHubFontSpec | undefined): EvenHubTextContainer {
return {
kind: "text",
id: readNumber(json, "containerID", 0),
@@ -166,6 +176,7 @@ function parseTextContainer(json: Record<string, unknown>): EvenHubTextContainer
preserve: readFlag(json, "preserve"),
content: readString(json, "content", ""),
textColor: readTextBrightness(json),
font: readFont(json, layoutFont),
};
}
@@ -238,7 +249,7 @@ function parseImageContainer(json: Record<string, unknown>): EvenHubImageContain
};
}
function parseListContainer(json: Record<string, unknown>): EvenHubListContainer {
function parseListContainer(json: Record<string, unknown>, 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<string, unknown>): EvenHubListContainer
itemWidth: readNumber(itemContainer, "itemWidth", 0),
selectBorder: readFlag(itemContainer, "isItemSelectBorderEn"),
selectedIndex: 0,
font: readFont(json, layoutFont),
};
}
@@ -274,9 +286,11 @@ function parseListContainer(json: Record<string, unknown>): EvenHubListContainer
*/
export function parsePage(data: Record<string, unknown>): 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<string, unknown>): 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) };
}
+28
View File
@@ -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();
};
},
};
+63
View File
@@ -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;
}
+22 -3
View File
@@ -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,
});
+171
View File
@@ -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<string, unknown>;
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<string, FontFamilyInfo>();
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));
}
+139
View File
@@ -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<string, EvenHubTextFace | null>();
/** 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 };
}
+3 -2
View File
@@ -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<void> {
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; }
}
+207 -48
View File
@@ -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<string>();
/** 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> | 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
+119
View File
@@ -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<string, unknown>;
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<number, GrayImage>();
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<string, unknown>;
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)));
}
+7
View File
@@ -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()
+23
View File
@@ -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<string, BdfFont>();
/**
* 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.
+22 -5
View File
@@ -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<string, boolean>();
/** 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<ShellChromeState["battery"]>): 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;
}
/**
+123 -6
View File
@@ -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
+370 -44
View File
@@ -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<boolean>;
```
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<void>;
```
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<FaceclawFontFamily[]>;
```
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<TextMeasurement>;
```
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
| ------ | ------ | ------ |
| <a id="property-type"></a> `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 |
| ------ | ------ | ------ | ------ |
| <a id="property-freq"></a> `freq` | `number` | `undefined` | Tone frequency in Hz. The piezo is loudest around 1–4 kHz and faint below about 150 Hz. |
| <a id="property-ms"></a> `ms` | `number` | `undefined` | Step duration in milliseconds (1–65535). |
| <a id="property-duty"></a> `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 |
| ------ | ------ | ------ |
| <a id="property-headingdegrees"></a> `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. |
| <a id="property-magneticheadingdegrees"></a> `magneticHeadingDegrees` | `number` | Magnetic heading corrected by the wearer's calibration offset from Faceclaw's Compass app. Equal to `headingDegrees` until the wearer calibrates. |
| <a id="property-wearercalibrated"></a> `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. |
| <a id="property-declinationdegrees"></a> `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. |
| <a id="property-trueheadingdegrees"></a> `trueHeadingDegrees?` | `number` | `magneticHeadingDegrees` plus declination. Absent when `declinationDegrees` is. |
| <a id="property-width"></a> `width` | `number` | Width in pixels, 1–256. |
| <a id="property-height"></a> `height` | `number` | Height in pixels, 1–256. |
| <a id="property-data"></a> `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 |
| ------ | ------ | ------ |
| <a id="property-source"></a> `source` | [`InputSource`](#inputsource) | Which device was touched. Currently always `ring` or `watch`: the glasses' touchpads don't report touch-down. |
| <a id="property-timestampms"></a> `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 |
| ------ | ------ | ------ |
| <a id="property-text"></a> `text` | `string` | The finished text: a whole dictation, or a typed entry. |
| <a id="property-submit"></a> `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`,
| <a id="property-containername"></a> `containerName?` | `string` | Container name. `preserve` matches containers across layouts by name. |
| <a id="property-xposition"></a> `xPosition?` | `number` | Left edge in pixels on the 576×452 canvas. |
| <a id="property-yposition"></a> `yPosition?` | `number` | Top edge in pixels on the 576×452 canvas. |
| <a id="property-width"></a> `width?` | `number` | Width in pixels. |
| <a id="property-height"></a> `height?` | `number` | Height in pixels. |
| <a id="property-width-2"></a> `width?` | `number` | Width in pixels. |
| <a id="property-height-1"></a> `height?` | `number` | Height in pixels. |
| <a id="property-zorderindex"></a> `zOrderIndex?` | `number` | Stacking order: higher values draw on top. |
| <a id="property-iseventcapture"></a> `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. |
| <a id="property-preserve"></a> `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
| <a id="property-containername-1"></a> `containerName?` | `string` | `undefined` | Container name. `preserve` matches containers across layouts by name. |
| <a id="property-xposition-1"></a> `xPosition?` | `number` | `undefined` | Left edge in pixels on the 576×452 canvas. |
| <a id="property-yposition-1"></a> `yPosition?` | `number` | `undefined` | Top edge in pixels on the 576×452 canvas. |
| <a id="property-width-1"></a> `width?` | `number` | `undefined` | Width in pixels. |
| <a id="property-height-1"></a> `height?` | `number` | `undefined` | Height in pixels. |
| <a id="property-width-3"></a> `width?` | `number` | `undefined` | Width in pixels. |
| <a id="property-height-2"></a> `height?` | `number` | `undefined` | Height in pixels. |
| <a id="property-zorderindex-1"></a> `zOrderIndex?` | `number` | `undefined` | Stacking order: higher values draw on top. |
| <a id="property-iseventcapture-1"></a> `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. |
| <a id="property-preserve-1"></a> `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
| <a id="property-bordercolor"></a> `borderColor?` | `number` | `undefined` | Accepted for compatibility with stock payloads. Faceclaw currently ignores it. |
| <a id="property-borderradius"></a> `borderRadius?` | `number` | `undefined` | Border corner radius in pixels. |
| <a id="property-paddinglength"></a> `paddingLength?` | `number` | `undefined` | Padding between the border and the text, in pixels. |
| <a id="property-font"></a> `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
| <a id="property-containername-2"></a> `containerName?` | `string` | Container name. `preserve` matches containers across layouts by name. |
| <a id="property-xposition-2"></a> `xPosition?` | `number` | Left edge in pixels on the 576×452 canvas. |
| <a id="property-yposition-2"></a> `yPosition?` | `number` | Top edge in pixels on the 576×452 canvas. |
| <a id="property-width-2"></a> `width?` | `number` | Width in pixels. |
| <a id="property-height-2"></a> `height?` | `number` | Height in pixels. |
| <a id="property-width-4"></a> `width?` | `number` | Width in pixels. |
| <a id="property-height-3"></a> `height?` | `number` | Height in pixels. |
| <a id="property-zorderindex-2"></a> `zOrderIndex?` | `number` | Stacking order: higher values draw on top. |
| <a id="property-iseventcapture-2"></a> `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. |
| <a id="property-preserve-2"></a> `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
| <a id="property-bordercolor-1"></a> `borderColor?` | `number` | Accepted for compatibility with stock payloads. Faceclaw currently ignores it. |
| <a id="property-borderradius-1"></a> `borderRadius?` | `number` | Border corner radius in pixels. |
| <a id="property-paddinglength-1"></a> `paddingLength?` | `number` | Padding between the border and the items, in pixels. |
| <a id="property-font-1"></a> `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:
| <a id="property-listobject"></a> `listObject?` | [`FaceclawListContainer`](#faceclawlistcontainer)[] | List containers. |
| <a id="property-menuobject"></a> `menuObject?` | [`FaceclawMenu`](#faceclawmenu) | The page's contextual menu. Omit it to clear any previous menu. |
| <a id="property-containertotalnum"></a> `containerTotalNum?` | `number` | Accepted for compatibility with stock payloads and ignored: there is no container limit. |
| <a id="property-font-2"></a> `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 |
| ------ | ------ | ------ | ------ |
| <a id="property-family"></a> `family?` | `string` | `"Roboto"` | Font family, matched without regard to case, spaces or punctuation. An unknown family falls back to Roboto. |
| <a id="property-size"></a> `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. |
| <a id="property-weight"></a> `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 |
| ------ | ------ | ------ |
| <a id="property-family-1"></a> `family` | `string` | The name to use as [FaceclawFont.family](#property-family). |
| <a id="property-weights"></a> `weights` | `number`[] | The weights the family has, lightest first. |
| <a id="property-sizes"></a> `sizes?` | `number`[] | For a bitmap family, the sizes it has. Absent for a scalable family, which takes any size. |
| <a id="property-monospace"></a> `monospace` | `boolean` | Whether every character has the same width. |
***
### TextMeasurement
The size of some text, from [FaceclawExtensions.measureText](#measuretext).
#### Properties
| Property | Type | Description |
| ------ | ------ | ------ |
| <a id="property-width-1"></a> `width` | `number` | Width in pixels of the widest line (lines are split at `\n`). |
| <a id="property-lineheight"></a> `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 |
| ------ | ------ | ------ | ------ |
| <a id="property-freq"></a> `freq` | `number` | `undefined` | Tone frequency in Hz. The piezo is loudest around 1–4 kHz and faint below about 150 Hz. |
| <a id="property-ms"></a> `ms` | `number` | `undefined` | Step duration in milliseconds (1–65535). |
| <a id="property-duty"></a> `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 |
| ------ | ------ | ------ |
| <a id="property-headingdegrees"></a> `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. |
| <a id="property-magneticheadingdegrees"></a> `magneticHeadingDegrees` | `number` | Magnetic heading corrected by the wearer's calibration offset from Faceclaw's Compass app. Equal to `headingDegrees` until the wearer calibrates. |
| <a id="property-wearercalibrated"></a> `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. |
| <a id="property-declinationdegrees"></a> `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. |
| <a id="property-trueheadingdegrees"></a> `trueHeadingDegrees?` | `number` | `magneticHeadingDegrees` plus declination. Absent when `declinationDegrees` is. |
## Assistant tools
+268 -2
View File
@@ -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<number>;
}
// ---- 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<string, unknown> } | 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<boolean>;
/**
* 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<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.
*/
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<FaceclawFontFamily[]>;
/**
* 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<TextMeasurement>;
}
declare global {
@@ -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);
+5 -2
View File
@@ -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",
+23
View File
@@ -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);
});
+45
View File
@@ -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);
});
+63
View File
@@ -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));
});
+84
View File
@@ -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 });
});
+56
View File
@@ -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);
});
+1
View File
@@ -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: () => [] },
+3
View File
@@ -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",