From 84baee9c7668c84bdc848a15ca2d3c2d6e8960a5 Mon Sep 17 00:00:00 2001 From: James Babcock Date: Wed, 7 Oct 2026 01:22:42 -0700 Subject: [PATCH] EvenHub extensions: Fonts, window icons, touch-start events --- app/apps/evenhub/compositor.ts | 20 +- app/apps/evenhub/containers.ts | 22 +- app/apps/evenhub/device-status-source.ts | 28 ++ app/apps/evenhub/device-status.ts | 63 +++ app/apps/evenhub/evenhub-window.ts | 25 +- app/apps/evenhub/font-spec.ts | 171 ++++++++ app/apps/evenhub/fonts.ts | 139 +++++++ app/apps/evenhub/manager.ts | 5 +- app/apps/evenhub/session.ts | 255 +++++++++--- app/apps/evenhub/window-icon.ts | 119 ++++++ app/g2/ios-preview-controller.ts | 7 + app/graphics/bdffont.ts | 23 ++ app/ui/shell/shell.ts | 27 +- evenhub-extensions/README.md | 129 +++++- evenhub-extensions/docs/api/README.md | 414 +++++++++++++++++--- evenhub-extensions/src/index.ts | 270 ++++++++++++- evenhub-extensions/test/stock-sdk-compat.ts | 12 + evenhub-extensions/typedoc.json | 7 +- tests/evenhub-containers.test.cjs | 23 ++ tests/evenhub-device-status.test.cjs | 45 +++ tests/evenhub-extensions-shim.test.cjs | 63 +++ tests/evenhub-font-spec.test.cjs | 84 ++++ tests/evenhub-window-icon.test.cjs | 56 +++ tests/ios-glanceboard.test.cjs | 1 + tests/tsconfig.json | 3 + 25 files changed, 1884 insertions(+), 127 deletions(-) create mode 100644 app/apps/evenhub/device-status-source.ts create mode 100644 app/apps/evenhub/device-status.ts create mode 100644 app/apps/evenhub/font-spec.ts create mode 100644 app/apps/evenhub/fonts.ts create mode 100644 app/apps/evenhub/window-icon.ts create mode 100644 tests/evenhub-device-status.test.cjs create mode 100644 tests/evenhub-font-spec.test.cjs create mode 100644 tests/evenhub-window-icon.test.cjs diff --git a/app/apps/evenhub/compositor.ts b/app/apps/evenhub/compositor.ts index e154ed41..8518facf 100644 --- a/app/apps/evenhub/compositor.ts +++ b/app/apps/evenhub/compositor.ts @@ -4,7 +4,8 @@ * * Text uses Even's extracted 20px firmware font (via EvenHubFont), measured * and wrapped with @evenrealities/pretext, so glyph widths and line breaks - * match what apps expect. + * match what apps expect. Extended layouts may pick other fonts per container + * (fonts.ts), which wrap with Faceclaw's own text wrapping. * * Known deviations from stock, acceptable for now: * - List rendering is a plain vertical list. A non-zero itemWidth sets the @@ -13,7 +14,7 @@ * - Lists scroll with our menus' animation and bounce (see list-menu.ts). */ import { GrayImage } from "../../graphics/image"; -import { EvenHubFont } from "../../graphics/evenhub-font"; +import { containerFace } from "./fonts"; import { type EvenHubContainer, type EvenHubImageContainer, @@ -47,14 +48,11 @@ function paintTextContainer(image: GrayImage, container: EvenHubTextContainer): // the container's border at full brightness regardless. paintBorder(image, container); const inset = container.borderWidth + container.paddingLength; - EvenHubFont.get().drawTextWrapped( - image, - container.x + inset, - container.y + inset, - Math.max(1, container.width - 2 * inset), - container.content, - textGrey(container.textColor), - ); + const face = containerFace(container.font); + const lines = face.wrap(container.content, Math.max(1, container.width - 2 * inset)); + for (let i = 0; i < lines.length; i++) { + face.drawText(image, container.x + inset, container.y + inset + i * face.lineHeight, lines[i]!, textGrey(container.textColor)); + } } function paintBorder( @@ -94,7 +92,7 @@ function paintImageContainer(image: GrayImage, container: EvenHubImageContainer) function paintListContainer(image: GrayImage, container: EvenHubListContainer, focused: boolean): void { paintBorder(image, container); - paintListItems(image, container, EvenHubFont.get(), focused); + paintListItems(image, container, containerFace(container.font), focused); } /** Bottom-to-top paint order for a page's containers. */ diff --git a/app/apps/evenhub/containers.ts b/app/apps/evenhub/containers.ts index b62f631b..6cb7f629 100644 --- a/app/apps/evenhub/containers.ts +++ b/app/apps/evenhub/containers.ts @@ -5,6 +5,7 @@ * (Container_ID), and numbers sometimes arrive as strings, so all field * reads go through loose key matching (the SDK's pickLoose behavior). */ +import { mergeFontSpecs, parseFontSpec, type EvenHubFontSpec } from "./font-spec"; export type EvenHubTextContainer = { kind: "text"; @@ -24,6 +25,8 @@ export type EvenHubTextContainer = { content: string; /** SDK 0.0.14 textColor: brightness level 0..4; undefined means the device default (4). */ textColor: number | undefined; + /** Extended-layout font (merged with the layout's default); undefined is the stock font. */ + font: EvenHubFontSpec | undefined; }; export type EvenHubImageContainer = { @@ -63,6 +66,8 @@ export type EvenHubListContainer = { selectBorder: boolean; /** Selection is host-local: scroll moves it with no app round-trip. */ selectedIndex: number; + /** Extended-layout font (merged with the layout's default); undefined is the stock font. */ + font: EvenHubFontSpec | undefined; }; export type EvenHubContainer = EvenHubTextContainer | EvenHubImageContainer | EvenHubListContainer; @@ -149,7 +154,12 @@ function readBorderWidth(json: Record): number { return Math.max(0, Math.min(MAX_BORDER_WIDTH, readNumber(json, "borderWidth", 0))); } -function parseTextContainer(json: Record): EvenHubTextContainer { +/** A container's font: its own `font` over the layout-wide default. */ +function readFont(json: Record, layoutFont: EvenHubFontSpec | undefined): EvenHubFontSpec | undefined { + return mergeFontSpecs(layoutFont, parseFontSpec(pickLoose(json, "font"))); +} + +function parseTextContainer(json: Record, layoutFont: EvenHubFontSpec | undefined): EvenHubTextContainer { return { kind: "text", id: readNumber(json, "containerID", 0), @@ -166,6 +176,7 @@ function parseTextContainer(json: Record): EvenHubTextContainer preserve: readFlag(json, "preserve"), content: readString(json, "content", ""), textColor: readTextBrightness(json), + font: readFont(json, layoutFont), }; } @@ -238,7 +249,7 @@ function parseImageContainer(json: Record): EvenHubImageContain }; } -function parseListContainer(json: Record): EvenHubListContainer { +function parseListContainer(json: Record, layoutFont: EvenHubFontSpec | undefined): EvenHubListContainer { const itemContainer = asRecord(pickLoose(json, "itemContainer")); const itemNamesRaw = pickLoose(itemContainer, "itemName"); const itemNames = Array.isArray(itemNamesRaw) ? itemNamesRaw.map(String) : []; @@ -260,6 +271,7 @@ function parseListContainer(json: Record): EvenHubListContainer itemWidth: readNumber(itemContainer, "itemWidth", 0), selectBorder: readFlag(itemContainer, "isItemSelectBorderEn"), selectedIndex: 0, + font: readFont(json, layoutFont), }; } @@ -274,9 +286,11 @@ function parseListContainer(json: Record): EvenHubListContainer */ export function parsePage(data: Record): EvenHubPage { const containers: EvenHubContainer[] = []; + // Extended layouts may set a default font for every text and list container. + const layoutFont = parseFontSpec(pickLoose(data, "font")); const lists = pickLoose(data, "listObject"); if (Array.isArray(lists)) { - for (const item of lists) containers.push(parseListContainer(asRecord(item))); + for (const item of lists) containers.push(parseListContainer(asRecord(item), layoutFont)); } const images = pickLoose(data, "imageObject"); if (Array.isArray(images)) { @@ -284,7 +298,7 @@ export function parsePage(data: Record): EvenHubPage { } const texts = pickLoose(data, "textObject"); if (Array.isArray(texts)) { - for (const item of texts) containers.push(parseTextContainer(asRecord(item))); + for (const item of texts) containers.push(parseTextContainer(asRecord(item), layoutFont)); } return { containers, menuItems: parseMenuItems(data) }; } diff --git a/app/apps/evenhub/device-status-source.ts b/app/apps/evenhub/device-status-source.ts new file mode 100644 index 00000000..82423308 --- /dev/null +++ b/app/apps/evenhub/device-status-source.ts @@ -0,0 +1,28 @@ +/** + * The live data behind an EvenHub app's device status: glasses presence (fed + * by the connection controller), the headset battery (from the shell's top + * bar state), and the paired glasses' serial. + */ +import { shell } from "../../ui/shell/shell"; +import { getGlassesPresence, onGlassesPresenceChanged } from "../../g2/glasses-presence"; +import { loadPairedGlassesIdentity } from "../../g2/device-addresses"; +import { type EvenHubDeviceStatusSource } from "./device-status"; + +export const liveDeviceStatusSource: EvenHubDeviceStatusSource = { + read: () => { + const presence = getGlassesPresence(); + return { + serial: loadPairedGlassesIdentity()?.serial ?? null, + connected: presence.connected, + worn: presence.worn, + battery: shell.getBatteryLevels().headset, + charging: presence.charging, + }; + }, + subscribe: (listener) => { + const offs = [onGlassesPresenceChanged(listener), shell.onBatteryLevelsChanged(listener)]; + return () => { + for (const off of offs) off(); + }; + }, +}; diff --git a/app/apps/evenhub/device-status.ts b/app/apps/evenhub/device-status.ts new file mode 100644 index 00000000..e281733c --- /dev/null +++ b/app/apps/evenhub/device-status.ts @@ -0,0 +1,63 @@ +/** + * The stock SDK's DeviceStatus (getGlassesInfo().status and the + * deviceStatusChanged push), built from what Faceclaw actually knows about + * the glasses. Pure, so it can be tested without NativeScript. + */ + +/** Used when no glasses have been paired (preview-only mode). */ +export const PLACEHOLDER_SERIAL = "FACECLAW-G2"; + +/** Wire shape of the SDK's DeviceStatus. Unknown fields are omitted rather than guessed. */ +export type EvenHubDeviceStatus = { + sn: string; + connectType: "connected" | "disconnected"; + isWearing?: boolean; + batteryLevel?: number; + isCharging?: boolean; + isInCase?: boolean; +}; + +export type EvenHubDeviceStatusInput = { + /** The paired glasses' serial number, or null when none are paired. */ + serial: string | null; + connected: boolean; + /** null until the firmware reports a wear state this session. */ + worn: boolean | null; + /** Last known headset battery percentage, or null if never reported. */ + battery: number | null; + charging: boolean; +}; + +/** Where a session reads the device status from (live in the app; fixed in tests). */ +export type EvenHubDeviceStatusSource = { + read(): EvenHubDeviceStatusInput; + /** Call `listener` after anything read() reports may have changed. Returns an unsubscribe function. */ + subscribe(listener: () => void): () => void; +}; + +/** No glasses: what a session reports when it isn't given a live source. */ +export const OFFLINE_DEVICE_STATUS_SOURCE: EvenHubDeviceStatusSource = { + read: () => ({ serial: null, connected: false, worn: null, battery: null, charging: false }), + subscribe: () => () => {}, +}; + +export function buildEvenHubDeviceStatus(input: EvenHubDeviceStatusInput): EvenHubDeviceStatus { + const status: EvenHubDeviceStatus = { + // The SDK only applies a status push whose sn matches getGlassesInfo's, + // so both must come from here. + sn: input.serial?.trim() || PLACEHOLDER_SERIAL, + connectType: input.connected ? "connected" : "disconnected", + isCharging: input.charging, + // The G2 only charges in its case, and Faceclaw has no separate + // in-case report. + isInCase: input.charging, + }; + if (input.worn !== null) status.isWearing = input.worn; + if (input.battery !== null) status.batteryLevel = input.battery; + return status; +} + +export function sameDeviceStatus(a: EvenHubDeviceStatus, b: EvenHubDeviceStatus): boolean { + return a.sn === b.sn && a.connectType === b.connectType && a.isWearing === b.isWearing && + a.batteryLevel === b.batteryLevel && a.isCharging === b.isCharging && a.isInCase === b.isInCase; +} diff --git a/app/apps/evenhub/evenhub-window.ts b/app/apps/evenhub/evenhub-window.ts index 09d399d1..d359b2ee 100644 --- a/app/apps/evenhub/evenhub-window.ts +++ b/app/apps/evenhub/evenhub-window.ts @@ -5,7 +5,7 @@ */ import { GrayImage } from "../../graphics/image"; import { EVENHUB_SCREEN_WIDTH } from "./compositor"; -import { type InputEvent } from "../../ui/gestures"; +import { directionalFallback, isDirectionalInput, type InputEvent } from "../../ui/gestures"; import { type Layer, type LayerContext } from "../../ui/layers"; import { createInProcessWindow, @@ -18,6 +18,13 @@ import { EvenHubSession } from "./session"; import { renderInstalledEvenHubIcon } from "./installed-apps"; class EvenHubAppLayer implements Layer { + /** + * Watch swipes become the usual stock gestures here rather than in the + * stack's fallback, which labels them as ring input: an app reading the + * extension's source field should see that they came from the watch. + */ + readonly acceptsDirectional = true; + constructor(private readonly session: EvenHubSession) {} paint(ctx: LayerContext): GrayImage { @@ -40,7 +47,7 @@ class EvenHubAppLayer implements Layer { // menu intercepts tap-then-hold), which is the guaranteed way out since // EvenHub apps own double-click. Tap-then-hold is still reported to the // app as LONG_PRESS_EVENT — see the handleInput wrapper below. - this.session.handleGesture(event); + this.session.handleGesture(isDirectionalInput(event) ? ({ ...directionalFallback(event), source: "watch" } as InputEvent) : event); } } @@ -50,6 +57,7 @@ export function createEvenHubWindow( session: EvenHubSession, options: InProcessAppOptions, onShowPhone: () => void, + requestShellRender: () => void, ): InProcessWindow { const fallbackIcon = windowIcon("package", session.manifest.name.charAt(0).toUpperCase() || "E"); const created = createInProcessWindow({ @@ -58,11 +66,14 @@ export function createEvenHubWindow( title: session.manifest.name, iconLetter: session.manifest.name.charAt(0).toUpperCase() || "E", closeable: true, + // An icon the app set at runtime (extension setWindowIcon) wins over the + // package's. drawIcon: makeImageWindowIcon( - (size) => renderInstalledEvenHubIcon(session.manifest.packageId, size), + (size) => session.renderWindowIcon(size) ?? renderInstalledEvenHubIcon(session.manifest.packageId, size), fallbackIcon, ), heightMode: "medium", + keepsScreenOn: () => session.keepsScreenOn(), // The window's context menu doubles as the OS contextual menu EvenHub // apps register with `menuObject` (SDK 0.0.14): the app's own entries come // first, then the host entries. Evaluated at open time, so a rebuild that @@ -99,6 +110,14 @@ export function createEvenHubWindow( // The extended layout uses the full 576x452 app area ("max"); stock apps // stay in the 576x288 band ("medium"). setTallCanvas: (tall) => created.setHeightMode(tall ? "max" : "medium"), + setAttention: (attention) => shell.setWindowAttention(windowId, attention), + // Only while the app listens for text: otherwise the shell's Type Into App + // destinations (voice dialog, phone keyboard, watch) would send into a void. + setAcceptsTextInput: (accept) => { + created.window.receiveTextInput = accept ? (text, textOptions) => session.deliverTextInput(text, textOptions) : undefined; + }, + startVoiceInput: () => shell.foregroundWindow()?.windowId === windowId && shell.startVoiceInput(), + iconChanged: requestShellRender, windowId, }); diff --git a/app/apps/evenhub/font-spec.ts b/app/apps/evenhub/font-spec.ts new file mode 100644 index 00000000..a16318b1 --- /dev/null +++ b/app/apps/evenhub/font-spec.ts @@ -0,0 +1,171 @@ +/** + * Font options for EvenHub text and list containers (the extension layout's + * `font: { family, size, weight }`): parsing, inheritance from the layout's + * default, and choosing a face from what is installed. Pure, so it can be + * tested without NativeScript; app/apps/evenhub/fonts.ts loads the result. + * + * A container with no font anywhere keeps the stock firmware font, exactly as + * on stock. Naming any font option switches to Faceclaw's fonts, with the + * defaults below filling the options left out. + */ + +/** A container's font request, after parsing. Absent fields take the defaults. */ +export type EvenHubFontSpec = { + family?: string; + size?: number; + weight?: number; +}; + +export const DEFAULT_FONT_FAMILY = "Roboto"; +/** The stock firmware font's size, so switching family alone keeps text about the same size. */ +export const DEFAULT_FONT_SIZE = 20; +export const DEFAULT_FONT_WEIGHT = 400; +export const MIN_FONT_SIZE = 6; +/** Larger glyphs leave the glyph-cache path (255px limit), so text stops being cheap to send. */ +export const MAX_FONT_SIZE = 128; + +/** + * Parse a `font` object from a layout or container. Undefined when there is + * none; unusable fields are dropped, so `{}` means "Faceclaw's default font". + */ +export function parseFontSpec(raw: unknown): EvenHubFontSpec | undefined { + if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined; + const record = raw as Record; + const spec: EvenHubFontSpec = {}; + if (typeof record.family === "string" && record.family.trim()) spec.family = record.family.trim(); + const size = typeof record.size === "string" ? Number(record.size) : record.size; + if (typeof size === "number" && Number.isFinite(size)) { + spec.size = Math.min(MAX_FONT_SIZE, Math.max(MIN_FONT_SIZE, Math.round(size))); + } + const weight = parseWeight(record.weight); + if (weight !== undefined) spec.weight = weight; + return spec; +} + +function parseWeight(raw: unknown): number | undefined { + if (typeof raw === "string") { + const keyword = raw.trim().toLowerCase(); + if (keyword === "normal") return 400; + if (keyword === "bold") return 700; + raw = Number(keyword); + } + if (typeof raw !== "number" || !Number.isFinite(raw)) return undefined; + return Math.min(1000, Math.max(1, Math.round(raw))); +} + +/** A container's font: its own options over the layout default's, field by field. */ +export function mergeFontSpecs( + layoutDefault: EvenHubFontSpec | undefined, + own: EvenHubFontSpec | undefined, +): EvenHubFontSpec | undefined { + if (!layoutDefault) return own; + if (!own) return layoutDefault; + return { ...layoutDefault, ...own }; +} + +/** One loadable face: a TTF file, a Terminus weight, or the stock font. */ +export type FontFaceCandidate = { + /** Family as the font names itself (e.g. "Inter 18pt"). */ + family: string; + /** 100..900. */ + weight: number; + /** The sizes a bitmap face comes in; null for a scalable face. */ + sizes: readonly number[] | null; + monospace: boolean; + /** Identifies the face to the loader. */ + key: string; +}; + +/** + * The family name apps use: an optical-size suffix ("Inter 18pt") is dropped, + * since the bundled Inter is its 18pt cut and apps would ask for "Inter". + */ +export function displayFamily(family: string): string { + return family.replace(/\s+\d+\s*pt$/i, "").trim() || family; +} + +function normalizeFamily(name: string): string { + return name.toLowerCase().replace(/[^a-z0-9]/g, ""); +} + +export function familyMatches(candidate: string, requested: string): boolean { + const wanted = normalizeFamily(requested); + return normalizeFamily(candidate) === wanted || normalizeFamily(displayFamily(candidate)) === wanted; +} + +/** + * Pick the face and pixel size for a spec. An unknown family falls back to + * DEFAULT_FONT_FAMILY; null when even that is missing (the caller then uses + * the stock font). Weight follows CSS's font matching: 400–500 look up to + * 500 first, lighter requests look lighter first, heavier ones heavier + * first. A bitmap face takes its nearest size (the smaller on a tie). + */ +export function selectFontFace( + spec: EvenHubFontSpec, + candidates: readonly FontFaceCandidate[], +): { face: FontFaceCandidate; size: number } | null { + const family = spec.family ?? DEFAULT_FONT_FAMILY; + let faces = candidates.filter((candidate) => familyMatches(candidate.family, family)); + if (faces.length === 0) faces = candidates.filter((candidate) => familyMatches(candidate.family, DEFAULT_FONT_FAMILY)); + if (faces.length === 0) return null; + const desired = spec.weight ?? DEFAULT_FONT_WEIGHT; + const face = [...faces].sort((a, b) => weightRank(a.weight, desired) - weightRank(b.weight, desired))[0]!; + const requestedSize = spec.size ?? DEFAULT_FONT_SIZE; + return { face, size: face.sizes ? nearestSize(face.sizes, requestedSize) : requestedSize }; +} + +/** Lower is better: CSS font-weight matching as a sort key. */ +function weightRank(weight: number, desired: number): number { + const distance = Math.abs(weight - desired); + if (weight === desired) return 0; + if (desired >= 400 && desired <= 500) { + if (weight > desired && weight <= 500) return distance; + if (weight < desired) return 1000 + distance; + return 2000 + distance; + } + const preferLighter = desired < 400; + return (weight < desired) === preferLighter ? distance : 1000 + distance; +} + +function nearestSize(sizes: readonly number[], requested: number): number { + let best = sizes[0]!; + for (const size of sizes) { + const better = Math.abs(size - requested) < Math.abs(best - requested) || + (Math.abs(size - requested) === Math.abs(best - requested) && size < best); + if (better) best = size; + } + return best; +} + +/** A family as the extension's getFonts() reports it. */ +export type FontFamilyInfo = { + family: string; + weights: number[]; + /** Bitmap families' sizes; absent for scalable families. */ + sizes?: number[]; + monospace: boolean; +}; + +/** Group faces into families for getFonts(), sorted by name. */ +export function describeFontFamilies(candidates: readonly FontFaceCandidate[]): FontFamilyInfo[] { + const families = new Map(); + for (const candidate of candidates) { + const name = displayFamily(candidate.family); + const key = normalizeFamily(name); + let info = families.get(key); + if (!info) { + info = { family: name, weights: [], monospace: candidate.monospace }; + families.set(key, info); + } + if (!info.weights.includes(candidate.weight)) info.weights.push(candidate.weight); + if (candidate.sizes) info.sizes = Array.from(new Set([...(info.sizes ?? []), ...candidate.sizes])); + info.monospace = info.monospace && candidate.monospace; + } + return Array.from(families.values()) + .map((info) => ({ + ...info, + weights: [...info.weights].sort((a, b) => a - b), + ...(info.sizes ? { sizes: [...info.sizes].sort((a, b) => a - b) } : {}), + })) + .sort((a, b) => a.family.localeCompare(b.family)); +} diff --git a/app/apps/evenhub/fonts.ts b/app/apps/evenhub/fonts.ts new file mode 100644 index 00000000..52b4236f --- /dev/null +++ b/app/apps/evenhub/fonts.ts @@ -0,0 +1,139 @@ +/** + * Loads the fonts EvenHub text and list containers ask for (see font-spec.ts + * for the matching rules): the stock firmware font, Terminus at its bitmap + * sizes, and every installed TTF/OTF — the bundled Roboto, Inter, Montserrat + * and Roboto Mono, plus any the user installed from the Files app. + */ +import { EvenHubFont } from "../../graphics/evenhub-font"; +import { getTerminusFont, TERMINUS_SIZES } from "../../graphics/bdffont"; +import { TtfFont } from "../../graphics/ttf-font"; +import { listInstalledFonts } from "../../graphics/installed-fonts"; +import { wrapText } from "../../graphics/textwrap"; +import type { GrayImage, UiFont } from "../../graphics/image"; +import { + describeFontFamilies, + familyMatches, + selectFontFace, + type EvenHubFontSpec, + type FontFaceCandidate, + type FontFamilyInfo, +} from "./font-spec"; + +/** What containers draw text with: the stock font's interface, which UiFonts are adapted to. */ +export type EvenHubTextFace = { + readonly lineHeight: number; + measureLine(text: string): number; + wrap(text: string, maxWidth: number): string[]; + drawText(image: GrayImage, x: number, y: number, text: string, value?: number): void; +}; + +class UiFontFace implements EvenHubTextFace { + constructor(private readonly font: UiFont) {} + + get lineHeight(): number { + return this.font.lineHeight; + } + + measureLine(text: string): number { + return this.font.measureText(text); + } + + wrap(text: string, maxWidth: number): string[] { + return wrapText(this.font, text, maxWidth); + } + + drawText(image: GrayImage, x: number, y: number, text: string, value = 255): void { + this.font.drawText(image, x, y, text, value); + } +} + +const STOCK_KEY = "stock"; +const TERMINUS_KEY_PREFIX = "terminus:"; +const TTF_KEY_PREFIX = "ttf:"; + +const BUILT_IN_FACES: readonly FontFaceCandidate[] = [ + // The firmware font: one size, one weight. + { family: "EvenHub", weight: 400, sizes: [20], monospace: false, key: STOCK_KEY }, + { family: "Terminus", weight: 400, sizes: TERMINUS_SIZES, monospace: true, key: `${TERMINUS_KEY_PREFIX}400` }, + { family: "Terminus", weight: 700, sizes: TERMINUS_SIZES, monospace: true, key: `${TERMINUS_KEY_PREFIX}700` }, +]; + +/** A family the listing lacks is re-listed at most this often (the user may have just installed it). */ +const RELIST_INTERVAL_MS = 30_000; + +let faces: FontFaceCandidate[] | null = null; +let listedAtMs = 0; + +function listFaces(): FontFaceCandidate[] { + const installed = listInstalledFonts() + // Upright faces only: there is no italic option yet. + .filter((font) => font.weightOrder < 1000) + .map((font): FontFaceCandidate => ({ + family: font.family, + weight: font.weightOrder, + sizes: null, + monospace: font.monospace, + key: `${TTF_KEY_PREFIX}${font.path}`, + })); + faces = [...BUILT_IN_FACES, ...installed]; + listedAtMs = Date.now(); + return faces; +} + +/** Whether some listed face has the family (no family asks for the default, which is bundled). */ +function hasFamily(available: readonly FontFaceCandidate[], family: string | undefined): boolean { + return !family || available.some((face) => familyMatches(face.family, family)); +} + +/** Resolved faces by spec; null means the stock font (asked for, or nothing loadable). */ +const resolved = new Map(); + +/** The face for a spec, and whether it is in the family asked for (rather than the fallback). */ +function loadFace(spec: EvenHubFontSpec): { face: EvenHubTextFace | null; exact: boolean } { + let available = faces ?? listFaces(); + if (!hasFamily(available, spec.family) && Date.now() - listedAtMs > RELIST_INTERVAL_MS) available = listFaces(); + const exact = hasFamily(available, spec.family); + return { face: openFace(selectFontFace(spec, available)), exact }; +} + +function openFace(choice: { face: FontFaceCandidate; size: number } | null): EvenHubTextFace | null { + if (!choice || choice.face.key === STOCK_KEY) return null; + const { face, size } = choice; + if (face.key.startsWith(TERMINUS_KEY_PREFIX)) { + const font = getTerminusFont(size, face.weight >= 600); + return font ? new UiFontFace(font) : null; + } + const font = TtfFont.load(face.key.slice(TTF_KEY_PREFIX.length), size); + return font ? new UiFontFace(font) : null; +} + +/** + * The face a container draws with: the stock font when it names no font, + * otherwise the closest match to its spec. + */ +export function containerFace(spec: EvenHubFontSpec | undefined): EvenHubTextFace { + if (!spec) return EvenHubFont.get(); + const key = `${spec.family ?? ""}|${spec.size ?? ""}|${spec.weight ?? ""}`; + let face = resolved.get(key); + if (face === undefined) { + const loaded = loadFace(spec); + face = loaded.face; + // A fallback isn't kept, so a family the user installs later gets picked up. + if (loaded.exact) resolved.set(key, face); + } + // Not cached as an object: EvenHubFont.get() changes once firmware fonts are extracted. + return face ?? EvenHubFont.get(); +} + +/** The font families apps can ask for (extension getFonts). Re-lists installed fonts. */ +export function availableFontFamilies(): FontFamilyInfo[] { + return describeFontFamilies(listFaces()); +} + +/** Width of the widest line of `text` and the line height, in the font a container would use. */ +export function measureContainerText(text: string, spec: EvenHubFontSpec | undefined): { width: number; lineHeight: number } { + const face = containerFace(spec); + let width = 0; + for (const line of text.split("\n")) width = Math.max(width, face.measureLine(line)); + return { width: Math.ceil(width), lineHeight: face.lineHeight }; +} diff --git a/app/apps/evenhub/manager.ts b/app/apps/evenhub/manager.ts index 0b12dabe..14b9382f 100644 --- a/app/apps/evenhub/manager.ts +++ b/app/apps/evenhub/manager.ts @@ -22,6 +22,7 @@ import { unpackRuntime } from "./unpack-runtime"; import { type EvenHubPermission } from "./permissions"; import { EvenHubSession } from "./session"; import { createEvenHubWindow } from "./evenhub-window"; +import { liveDeviceStatusSource } from "./device-status-source"; import { createEvenHubWebView, type EvenHubWebView } from "./webview"; import { shell } from "../../ui/shell/shell"; import { GrayImage } from "../../graphics/image"; @@ -126,7 +127,7 @@ async function startApp( ): Promise { const windowId = `evenhub:app:${nextSerial++}`; const session = new EvenHubSession(manifest, distDir, ctx.appendLog, remoteUrl, - payload => ctx.actions.playBuzzerSequence(payload)); + payload => ctx.actions.playBuzzerSequence(payload), liveDeviceStatusSource); const webView = createEvenHubWebView(session); session.attachWebView({ evaluateJs: webView.evaluateJs, @@ -147,7 +148,7 @@ async function startApp( try { await ctx.launchInProcessApp(windowId, `window:${windowId}`, (options) => - createEvenHubWindow(windowId, appId, session, options, () => showOnPhone(windowId)), + createEvenHubWindow(windowId, appId, session, options, () => showOnPhone(windowId), () => ctx.requestShellRender()), ); } catch (error) { session.close(); throw error; } } diff --git a/app/apps/evenhub/session.ts b/app/apps/evenhub/session.ts index 5fe23a25..90d9034e 100644 --- a/app/apps/evenhub/session.ts +++ b/app/apps/evenhub/session.ts @@ -63,6 +63,16 @@ import { toolRegistry, type ToolResult, type ToolSpec } from "../../assistant/to import { getCurrentLocation } from "../../native/location"; import { LocationTracker, type TrackedLocation } from "../../native/location-tracker"; import { ensureFineLocationPermission } from "../../native/location-permissions"; +import { + buildEvenHubDeviceStatus, + OFFLINE_DEVICE_STATUS_SOURCE, + sameDeviceStatus, + type EvenHubDeviceStatus, + type EvenHubDeviceStatusSource, +} from "./device-status"; +import { parseWindowIcon, WindowIconRenderer } from "./window-icon"; +import { availableFontFamilies, containerFace, measureContainerText } from "./fonts"; +import { parseFontSpec } from "./font-spec"; const UPNG = require("upng-js"); @@ -284,19 +294,29 @@ export function buildFaceclawExtensionsScript(versionString: string): string { if (i >= 0) arr.splice(i, 1); }; } - // Compass: enable on first listener, disable when the last one leaves. - var compassListeners = []; - function addCompass(cb) { - compassListeners.push(cb); - if (compassListeners.length === 1) send("setCompass", [true]); - var off = on("compass", cb); - return function () { - off(); - var i = compassListeners.indexOf(cb); - if (i >= 0) compassListeners.splice(i, 1); - if (compassListeners.length === 0) send("setCompass", [false]); + // Events the host only produces on request (compass, touch-down, text + // input): it is told to start on the first listener and to stop when the + // last one leaves. Each unsubscribe function works once. + function counted(name, setMethod) { + var count = 0; + return function (cb) { + var off = on(name, cb); + if (++count === 1) send(setMethod, [true]); + var active = true; + return function () { + if (!active) return; + active = false; + off(); + if (--count === 0) send(setMethod, [false]); + }; }; } + function setWindowIcon(icon) { + if (!icon) return call("setWindowIcon", [null]); + // Typed arrays (ImageData.data) don't survive JSON; send a plain array. + var data = Array.prototype.slice.call(icon.data || []); + return call("setWindowIcon", [{ width: icon.width, height: icon.height, data: data }]); + } // Voice-assistant tools: specs go to the host; handlers stay here and run when // the host invokes a tool via __fcExtInvokeTool. var toolHandlers = {}; @@ -335,10 +355,18 @@ export function buildFaceclawExtensionsScript(versionString: string): string { getConfiguredApiKeys: function () { return call("getConfiguredApiKeys"); }, requestApiKeyAccess: function (services) { return call("requestApiKeyAccess", [services || []]); }, playBuzzer: function (steps) { return call("playBuzzer", [steps || []]); }, - addCompassListener: addCompass, + addCompassListener: counted("compass", "setCompass"), createLayout: function (layout) { return call("createLayout", [layout || {}]); }, replaceLayout: function (layout) { return call("replaceLayout", [layout || {}]); }, - setAssistantTools: setAssistantTools + setAssistantTools: setAssistantTools, + addTouchDownListener: counted("touchDown", "setTouchDown"), + addTextInputListener: counted("textInput", "setTextInput"), + startVoiceInput: function () { return call("startVoiceInput"); }, + setWindowIcon: setWindowIcon, + setAttention: function (attention) { send("setAttention", [!!attention]); }, + setKeepScreenOn: function (keepOn) { send("setKeepScreenOn", [!!keepOn]); }, + getFonts: function () { return call("getFonts"); }, + measureText: function (text, font) { return call("measureText", [String(text), font || null]); } }; window.getFaceclawExtensions = function () { return extensions; }; })(); @@ -364,6 +392,14 @@ export type EvenHubWindowHooks = { pushOverlay: (layer: Layer) => void; /** Switch the window between the stock 576x288 band and the full 576x452 canvas. */ setTallCanvas: (tall: boolean) => void; + /** Show or clear the attention dot on the window's switcher icon. */ + setAttention: (attention: boolean) => void; + /** Offer (or stop offering) the window as the shell's "Type Into App" destination. */ + setAcceptsTextInput: (accept: boolean) => void; + /** Open the shell's voice dialog aimed at the window; false if it can't open now. */ + startVoiceInput: () => boolean; + /** The app changed its window icon: repaint the switcher. */ + iconChanged: () => void; /** The shell window id (unique per running instance; used for tool registration). */ windowId: string; }; @@ -414,6 +450,21 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenH private shellFocused = true; /** API-key services the user has granted this app this session. */ private readonly grantedApiKeys = new Set(); + /** The app listens for touch-down (extension addTouchDownListener). */ + private touchDownRequested = false; + /** The app listens for text input, so the shell offers it as a Type Into App destination. */ + private textInputRequested = false; + /** The app asked for the attention dot on its switcher icon. */ + private attention = false; + /** The app asked the idle screen timeout to wait while it is in the foreground. */ + private keepScreenOnRequested = false; + /** The app's own switcher icon; null draws the package icon. */ + private windowIcon: WindowIconRenderer | null = null; + /** The paired glasses' serial, read once so getGlassesInfo and every status push agree. */ + private glassesSerial: string | null | undefined = undefined; + /** The last deviceStatusChanged sent, and the subscriptions that refresh it. */ + private lastDeviceStatus: EvenHubDeviceStatus | null = null; + private readonly deviceStatusOffs: (() => void)[] = []; private log: (message: string) => void; constructor( @@ -422,6 +473,7 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenH log: (message: string) => void, remoteUrl = "", private readonly sendBuzzerSequence: (payload: Uint8Array) => Promise | void = () => {}, + private readonly deviceStatusSource: EvenHubDeviceStatusSource = OFFLINE_DEVICE_STATUS_SOURCE, ) { this.manifest = manifest; this.distDir = distDir; @@ -447,14 +499,8 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenH // Launched to drive the glasses (from the on-glasses file browser), so // apps that branch on this should take their glasses path. this.pushMessage("evenAppLaunchSource", { launchSource: "glassesMenu" }); - this.pushMessage("deviceStatusChanged", { - sn: "FACECLAW-G2", - connectType: "connected", - isWearing: true, - batteryLevel: 100, - isCharging: false, - isInCase: false, - }); + this.pushDeviceStatus(); + this.deviceStatusOffs.push(this.deviceStatusSource.subscribe(() => this.pushDeviceStatus())); } // ----- glasses window wiring ----- @@ -462,6 +508,10 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenH attachWindow(hooks: EvenHubWindowHooks): void { this.windowHooks = hooks; this.shellWindowId = hooks.windowId; + // Requests the app made before the window existed. + if (this.textInputRequested) hooks.setAcceptsTextInput(true); + if (this.attention) hooks.setAttention(true); + if (this.windowIcon) hooks.iconChanged(); } windowClosed(): void { @@ -491,18 +541,29 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenH * locally with events only for clicks and boundary scrolls. */ handleGesture(event: InputEvent): void { + // Touch-down has no stock event (an unknown eventType would parse as a + // click), so it goes only to apps that subscribed through the extension. + if (event.type === "ring-press") { + if (this.touchDownRequested) { + this.pushExtEvent("touchDown", { source: extensionInputSource(event.source), timestampMs: event.timestampMs }); + } + return; + } if (!this.page) return; - const capture = this.page ? eventCaptureContainer(this.page) : undefined; + const capture = eventCaptureContainer(this.page); + // The stock eventSource can't tell the watch from the ring, and scrolls + // carry none; the extension field names the device when it is known. + const inputSource = "source" in event && event.source ? extensionInputSource(event.source) : undefined; switch (event.type) { case "click": if (capture?.kind === "list") { - this.emitListEvent(capture, CLICK_EVENT); + this.emitListEvent(capture, CLICK_EVENT, inputSource); } else { - this.emitSysEvent(CLICK_EVENT, gestureSource(event.source)); + this.emitSysEvent(CLICK_EVENT, gestureSource(event.source), inputSource); } break; case "double-click": - this.emitSysEvent(DOUBLE_CLICK_EVENT, gestureSource(event.source)); + this.emitSysEvent(DOUBLE_CLICK_EVENT, gestureSource(event.source), inputSource); break; case "long-press": case "short-then-long-press": @@ -516,9 +577,9 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenH // given exclusive use of the gesture. const eventType = event.type === "long-press-release" ? LONG_PRESS_RELEASE_EVENT : LONG_PRESS_EVENT; if (capture?.kind === "list") { - this.emitListEvent(capture, eventType); + this.emitListEvent(capture, eventType, inputSource); } else { - this.emitSysEvent(eventType, gestureSource(event.source)); + this.emitSysEvent(eventType, gestureSource(event.source), inputSource); } break; } @@ -526,9 +587,9 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenH case "scroll-down": { const eventType = event.type === "scroll-up" ? SCROLL_TOP_EVENT : SCROLL_BOTTOM_EVENT; if (capture?.kind === "list") { - this.scrollList(capture, eventType); + this.scrollList(capture, eventType, inputSource); } else { - this.emitSysEvent(eventType, 0); + this.emitSysEvent(eventType, 0, inputSource); } break; } @@ -551,11 +612,11 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenH this.pushMessage("evenHubEvent", { type: "menuItemClickEvent", jsonData: { itemID } }); } - private scrollList(list: EvenHubListContainer, eventType: number): void { + private scrollList(list: EvenHubListContainer, eventType: number, inputSource?: ExtensionInputSource): void { // Swipe up selects the previous item, swipe down the next (stock direction). const delta = eventType === SCROLL_TOP_EVENT ? -1 : 1; // At a boundary the selection stays put (the list bounces) and the app hears about it. - if (!stepListSelection(list, EvenHubFont.get(), delta)) this.emitListEvent(list, eventType); + if (!stepListSelection(list, containerFace(list.font), delta)) this.emitListEvent(list, eventType, inputSource); this.windowHooks?.requestRender(); } @@ -820,19 +881,10 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenH return ApplicationSettings.getString(this.storageKey(readString(data, "key", "")), ""); case "getUserInfo": return { uid: 0, name: "Faceclaw", avatar: "", country: "" }; - case "getGlassesInfo": - return { - model: "g2", - sn: "FACECLAW-G2", - status: { - sn: "FACECLAW-G2", - connectType: "connected", - isWearing: true, - batteryLevel: 100, - isCharging: false, - isInCase: false, - }, - }; + case "getGlassesInfo": { + const status = this.deviceStatus(); + return { model: "g2", sn: status.sn, status }; + } case "audioControl": return this.audioControl(data); case "getAppLocation": @@ -1001,17 +1053,18 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenH this.pushMessage("evenHubEvent", { type: payloadType, jsonData: elideZeroFields(jsonData) }); } - private emitSysEvent(eventType: number, eventSource: number): void { - this.pushEvenHubEvent("sysEvent", { eventType, eventSource }); + private emitSysEvent(eventType: number, eventSource: number, inputSource?: ExtensionInputSource): void { + this.pushEvenHubEvent("sysEvent", { eventType, eventSource, [INPUT_SOURCE_FIELD]: inputSource }); } - private emitListEvent(list: EvenHubListContainer, eventType: number): void { + private emitListEvent(list: EvenHubListContainer, eventType: number, inputSource?: ExtensionInputSource): void { this.pushEvenHubEvent("listEvent", { containerID: list.id, containerName: list.name, currentSelectItemIndex: list.selectedIndex, currentSelectItemName: list.itemNames[list.selectedIndex] ?? "", eventType, + [INPUT_SOURCE_FIELD]: inputSource, }); } @@ -1027,7 +1080,7 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenH result = await this.dispatchExtension(method, args.slice(1)); } catch (error) { ok = false; - result = String(error); + result = error instanceof Error ? error.message : String(error); this.log(`evenhub: extension call failed: ${error}`); } // id 0 is a fire-and-forget send; nothing is awaiting it. @@ -1060,12 +1113,96 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenH case "setAssistantTools": this.setAssistantTools(Array.isArray(params[0]) ? params[0] : []); return null; + case "setTouchDown": + this.touchDownRequested = params[0] === true; + return null; + case "setTextInput": + this.setTextInputRequested(params[0] === true); + return null; + case "startVoiceInput": + // Without a text listener the dialog would have nowhere in the app to send to. + return this.textInputRequested && (this.windowHooks?.startVoiceInput() ?? false); + case "setWindowIcon": + this.setWindowIcon(params[0]); + return null; + case "setAttention": + this.attention = params[0] === true; + this.windowHooks?.setAttention(this.attention); + return null; + case "setKeepScreenOn": + this.keepScreenOnRequested = params[0] === true; + return null; + case "getFonts": + return availableFontFamilies(); + case "measureText": + // No font measures in the stock font, as a container without one draws. + return measureContainerText(String(params[0] ?? ""), parseFontSpec(params[1])); default: this.log(`evenhub: unknown extension method ${method}`); return null; } } + // ----- device status (stock getGlassesInfo / deviceStatusChanged) ----- + + private deviceStatus(): EvenHubDeviceStatus { + const input = this.deviceStatusSource.read(); + if (this.glassesSerial === undefined) this.glassesSerial = input.serial; + return buildEvenHubDeviceStatus({ ...input, serial: this.glassesSerial }); + } + + /** Push deviceStatusChanged if the status differs from the last one sent. */ + private pushDeviceStatus(): void { + if (this.closed) return; + const status = this.deviceStatus(); + if (this.lastDeviceStatus && sameDeviceStatus(status, this.lastDeviceStatus)) return; + this.lastDeviceStatus = status; + this.pushMessage("deviceStatusChanged", status); + } + + // ----- window controls and text input (extensions) ----- + + /** Whether the idle screen timeout should wait while this window is in the foreground. */ + keepsScreenOn(): boolean { + return this.keepScreenOnRequested; + } + + /** The app's own switcher icon at `size`, or null to draw the package icon. */ + renderWindowIcon(size: number): GrayImage | null { + return this.windowIcon?.render(size) ?? null; + } + + private setWindowIcon(raw: unknown): void { + if (raw == null) { + this.windowIcon = null; + } else { + const image = parseWindowIcon(raw); + if (!image) { + throw new Error( + "setWindowIcon: expected {width, height, data} of at most 256x256, with data holding " + + "width*height grayscale or width*height*4 RGBA bytes", + ); + } + this.windowIcon = new WindowIconRenderer(image); + } + this.windowHooks?.iconChanged(); + } + + private setTextInputRequested(accept: boolean): void { + if (this.textInputRequested === accept) return; + this.textInputRequested = accept; + this.windowHooks?.setAcceptsTextInput(accept); + } + + /** + * Text the shell routed to this window: the voice dialog's Type Into App, + * the phone keyboard, the watch, or remote input. Only arrives while the + * app listens (setAcceptsTextInput). + */ + deliverTextInput(text: string, options?: { submit?: boolean }): void { + this.pushExtEvent("textInput", options?.submit === undefined ? { text } : { text, submit: options.submit }); + } + // ----- compass (EvenHubCompassClient) ----- deliverCompass(reading: EvenHubCompassReading): void { @@ -1249,6 +1386,7 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenH this.pendingToolCalls.clear(); this.locationTracker?.stop(); this.locationTracker = null; + for (const off of this.deviceStatusOffs.splice(0)) off(); if (!this.systemExitSent) { // Best effort: lets the app's teardown handlers run before the webview dies. this.emitSysEvent(SYSTEM_EXIT_EVENT, 0); @@ -1451,6 +1589,27 @@ function luminance(r: number, g: number, b: number): number { return Math.round(0.2126 * r + 0.7152 * g + 0.0722 * b); } +/** + * Input-device names in the extension API: the touchDown event's source, and + * the `faceclawInputSource` field added to stock gesture events. + */ +type ExtensionInputSource = "ring" | "left-touchpad" | "right-touchpad" | "watch"; + +const INPUT_SOURCE_FIELD = "faceclawInputSource"; + +function extensionInputSource(source: InputSource): ExtensionInputSource { + switch (source) { + case "ring": + return "ring"; + case "left-arm": + return "left-touchpad"; + case "right-arm": + return "right-touchpad"; + case "watch": + return "watch"; + } +} + /** * ring/left-arm/right-arm -> PB EventSourceType. The watch is reported to * EvenHub apps as the ring: they only know stock hardware, and the watch's diff --git a/app/apps/evenhub/window-icon.ts b/app/apps/evenhub/window-icon.ts new file mode 100644 index 00000000..87ff6f5e --- /dev/null +++ b/app/apps/evenhub/window-icon.ts @@ -0,0 +1,119 @@ +/** + * App-supplied window icons (the extension setWindowIcon): parse the pixel + * buffer an app sends and scale it to the sizes the app switcher draws at. + * Pure, so it can be tested without NativeScript. + */ +import { GrayImage } from "../../graphics/image"; + +/** Larger icons are refused: they only cost bridge traffic, since switcher icons are ~32px. */ +export const MAX_WINDOW_ICON_DIMENSION = 256; + +/** + * Parse `{width, height, data}` from the bridge into a grayscale image. + * `data` is width*height brightness bytes, or width*height*4 RGBA bytes (an + * ImageData), which are reduced to luminance times alpha. Arrays arrive as + * plain arrays or as JSON-ified typed arrays ({"0": n, ...}). Returns null for + * anything malformed. + */ +export function parseWindowIcon(raw: unknown): GrayImage | null { + if (!raw || typeof raw !== "object") return null; + const record = raw as Record; + const width = Number(record.width); + const height = Number(record.height); + if (!Number.isInteger(width) || !Number.isInteger(height)) return null; + if (width < 1 || height < 1 || width > MAX_WINDOW_ICON_DIMENSION || height > MAX_WINDOW_ICON_DIMENSION) return null; + const data = toNumberArray(record.data); + if (!data) return null; + const area = width * height; + const image = new GrayImage(width, height, 0); + if (data.length === area) { + for (let i = 0; i < area; i++) image.pixels[i] = clampByte(data[i]!); + } else if (data.length === area * 4) { + for (let i = 0; i < area; i++) { + const o = i * 4; + const luminance = 0.2126 * data[o]! + 0.7152 * data[o + 1]! + 0.0722 * data[o + 2]!; + image.pixels[i] = clampByte((luminance * data[o + 3]!) / 255); + } + } else { + return null; + } + return image; +} + +/** + * Scale an icon to fit a size x size box, keeping its aspect ratio, with an + * area-averaging filter. Results are cached per size, since the switcher + * repaints often. + */ +export class WindowIconRenderer { + private readonly scaled = new Map(); + + constructor(private readonly source: GrayImage) {} + + render(size: number): GrayImage { + const box = Math.max(1, Math.round(size)); + let image = this.scaled.get(box); + if (!image) { + image = scaleToFit(this.source, box); + this.scaled.set(box, image); + } + return image; + } +} + +function scaleToFit(source: GrayImage, box: number): GrayImage { + const scale = Math.min(box / source.width, box / source.height); + const width = Math.max(1, Math.round(source.width * scale)); + const height = Math.max(1, Math.round(source.height * scale)); + if (width === source.width && height === source.height) return source; + const out = new GrayImage(width, height, 0); + for (let y = 0; y < height; y++) { + const y0 = (y * source.height) / height; + const y1 = ((y + 1) * source.height) / height; + for (let x = 0; x < width; x++) { + const x0 = (x * source.width) / width; + const x1 = ((x + 1) * source.width) / width; + out.pixels[y * width + x] = clampByte(areaAverage(source, x0, y0, x1, y1)); + } + } + return out; +} + +/** Mean of the source over the rectangle [x0,x1) x [y0,y1), weighting partly covered pixels. */ +function areaAverage(source: GrayImage, x0: number, y0: number, x1: number, y1: number): number { + let sum = 0; + let weight = 0; + for (let sy = Math.floor(y0); sy < Math.min(source.height, Math.ceil(y1)); sy++) { + const wy = Math.min(y1, sy + 1) - Math.max(y0, sy); + for (let sx = Math.floor(x0); sx < Math.min(source.width, Math.ceil(x1)); sx++) { + const w = wy * (Math.min(x1, sx + 1) - Math.max(x0, sx)); + sum += source.pixels[sy * source.width + sx]! * w; + weight += w; + } + } + return weight > 0 ? sum / weight : 0; +} + +function toNumberArray(raw: unknown): number[] | null { + let values: unknown[]; + if (Array.isArray(raw)) { + values = raw; + } else if (raw && typeof raw === "object") { + const record = raw as Record; + values = []; + for (let i = 0; String(i) in record; i++) values.push(record[String(i)]); + } else { + return null; + } + const out: number[] = []; + for (const entry of values) { + const value = Number(entry); + if (!Number.isFinite(value)) return null; + out.push(value); + } + return out; +} + +function clampByte(value: number): number { + return Math.max(0, Math.min(255, Math.round(value))); +} diff --git a/app/g2/ios-preview-controller.ts b/app/g2/ios-preview-controller.ts index 12c1574e..ac4e4971 100644 --- a/app/g2/ios-preview-controller.ts +++ b/app/g2/ios-preview-controller.ts @@ -25,6 +25,7 @@ import { GlanceHost, type GlanceDisplay } from './glance-host' import { createLockScreenImage, LOCK_SCREEN_SURFACE_ID } from './lock-screen' import { OsEventTypeList } from './events' import { loadDeviceAddresses } from './device-addresses' +import { updateGlassesPresence } from './glasses-presence' import { firmwareIncompatibilityMessage, hasCompatibleFirmware } from './firmware-compat' import { isHaltedSessionPhase, suppressAutoReconnect } from './reconnect-policy' import { deviceAddressError } from './ios-peripheral-identity' @@ -373,6 +374,7 @@ export class IosPreviewController { // a session's first snapshot) wakes the screen, to the lock notice if locked. const putOn = wearing && this.glassesWorn === false this.glassesWorn = wearing + this.syncPresence() this.logBluetooth(`Glasses wear state: ${wearing ? 'ON_HEAD' : 'OFF_HEAD'}`) if (!wearing && this.phoneLocked && this.lockEnabled) this.setGlassesLocked(true) if (putOn && this.runtimeRunning && !shell.isScreenOn()) shell.wake('sidebar') @@ -672,6 +674,10 @@ export class IosPreviewController { this.logBluetooth(status) this.emitState() } + /** Mirror the session into glasses-presence (read by EvenHub's device status and Timers). */ + private syncPresence(): void { + updateGlassesPresence({ connected: this.state.phase === 'connected', worn: this.glassesWorn, charging: this.state.charging ?? false }) + } private emitState(): void { if (this.state.phase !== 'connected') resetRingInputFilter() this.pushBrightness() @@ -679,6 +685,7 @@ export class IosPreviewController { if (this.state.phase !== 'connected' && this.state.phase !== 'connecting') this.glassesWorn = null if (this.state.phase !== 'connected') iosVoiceInput.handleSessionEnded() shell.setBatteryLevels({ headset: this.state.battery, headsetCharging: this.state.charging }) + this.syncPresence() this.syncRuntime() if (this.active) this.onConnectionState({ ...this.state }) this.requestShellRender() diff --git a/app/graphics/bdffont.ts b/app/graphics/bdffont.ts index 8bf9dfec..1d43ad05 100644 --- a/app/graphics/bdffont.ts +++ b/app/graphics/bdffont.ts @@ -248,6 +248,29 @@ export function getFont(font: EmbeddedFontName): BdfFont { return loadEmbeddedFont(font); } +/** Every Terminus size bundled under fonts/terminus, each in normal and bold. */ +export const TERMINUS_SIZES = [12, 14, 16, 18, 20, 22, 24, 28, 32] as const; + +const terminusFonts = new Map(); + +/** + * Terminus at any bundled size, normal or bold (EvenHub apps pick fonts by + * size and weight). Null for a size that isn't bundled. The sizes the UI + * already uses come back as the same objects getFont returns. + */ +export function getTerminusFont(size: number, bold: boolean): BdfFont | null { + if (!(TERMINUS_SIZES as readonly number[]).includes(size)) return null; + const name = `terminus${size}${bold ? "b" : ""}`; + if (name in embeddedFonts) return loadEmbeddedFont(name as EmbeddedFontName); + let font = terminusFonts.get(name); + if (!font) { + const text = knownFolders.currentApp().getFile(`fonts/terminus/ter-u${size}${bold ? "b" : "n"}.bdf`).readTextSync(); + font = BdfFont.parse(text, { atlasKey: name }); + terminusFonts.set(name, font); + } + return font; +} + // NOTE: the default UI font getters (getDefaultSmallFont & co.) live in // ./ui-fonts, which resolves the user's font settings to a BdfFont or // TtfFont. This module stays a pure BDF loader. diff --git a/app/ui/shell/shell.ts b/app/ui/shell/shell.ts index 1ad07d0b..632b444f 100644 --- a/app/ui/shell/shell.ts +++ b/app/ui/shell/shell.ts @@ -394,6 +394,7 @@ class Shell { private battery: ShellChromeState["battery"] = { headset: null, headsetCharging: null, ring: null, ringCharging: null, watch: null, watchCharging: null, }; + private readonly batteryListeners = new Set<() => void>(); private attention = new Map(); /** Set while the switcher's selection is on a notification (see NotificationSelection). */ private selectedNotification: NotificationSelection | null = null; @@ -584,7 +585,19 @@ class Shell { } setBatteryLevels(levels: Partial): void { - this.battery = { ...this.battery, ...levels }; + const next = { ...this.battery, ...levels }; + const keys = Object.keys(next) as (keyof ShellChromeState["battery"])[]; + if (keys.every((key) => next[key] === this.battery[key])) return; + this.battery = next; + for (const listener of Array.from(this.batteryListeners)) listener(); + } + + /** Called after any battery level or charging state changes. Returns an unsubscribe function. */ + onBatteryLevelsChanged(listener: () => void): () => void { + this.batteryListeners.add(listener); + return () => { + this.batteryListeners.delete(listener); + }; } /** @@ -1397,16 +1410,20 @@ class Shell { * Open the voice dialog aimed at the foreground window. Called when the * user picks Voice input from the system menu (or an app asks via a * start-voice-input message). The menu click already ended the press, so - * the dialog finishes on click instead of long-press-release. + * the dialog finishes on click instead of long-press-release. Returns + * false when the dialog can't open now (voice input disabled, screen off, + * another dialog or overlay up); true means it is opening, though a + * microphone-permission prompt can still stop it. */ - startVoiceInput(): void { - if (this.config.voiceInputEnabled === false) return; - if (!this.screenOn || this.activeVoiceLayer || !this.stack.isAtBase()) return; + startVoiceInput(): boolean { + if (this.config.voiceInputEnabled === false || this.voiceDialogPending) return false; + if (!this.screenOn || this.activeVoiceLayer || !this.stack.isAtBase()) return false; // The transcript is aimed at the window whose menu requested it; the menu // entry point defaults the highlight to Type Into App. this.focus = "window"; this.openVoiceDialog({ finishOnClick: true, defaultTarget: "app" }); this.config.requestShellRender(); + return true; } /** diff --git a/evenhub-extensions/README.md b/evenhub-extensions/README.md index 0e056c09..56a3d613 100644 --- a/evenhub-extensions/README.md +++ b/evenhub-extensions/README.md @@ -7,10 +7,12 @@ Faceclaw is an alternative host for EvenHub apps on the Even Realities G2 glasses. An app built against the standard [`@evenrealities/even_hub_sdk`](https://www.npmjs.com/package/@evenrealities/even_hub_sdk) runs in Faceclaw unchanged. This package lets the app detect that it is -running in Faceclaw and use some extra capabilities there: a taller canvas, the -glasses' compass and buzzer, window lifecycle events, voice-assistant tools, and -the user's API keys (with their consent). In the stock Even app the extensions -are absent, and the app runs as usual. +running in Faceclaw and use some extra capabilities there: a taller canvas, +choice of fonts, the glasses' compass and buzzer, touch-down events and which device an input came +from, dictated or typed text, control of the app's switcher icon and the screen +timeout, window lifecycle events, voice-assistant tools, and the user's API keys +(with their consent). In the stock Even app the extensions are absent, and the +app runs as usual. - [API reference](docs/api/README.md) @@ -57,11 +59,15 @@ startup. You don't need to wait for the bridge first. ## How it works Faceclaw injects one global function, `window.getFaceclawExtensions`, into the -app's webview. Every extension lives behind it. Faceclaw doesn't modify the -standard SDK, other globals, or any built-in prototype, so an app that uses +app's webview. Every extension method lives behind it. Faceclaw doesn't modify +the standard SDK, other globals, or any built-in prototype, so an app that uses the extensions keeps working in any other host. `getFaceclawExtensions()` in this package checks whether that global exists and calls it. +The one addition outside that global is data: Faceclaw adds a +`faceclawInputSource` field to the raw JSON of stock gesture events, which +`getInputSource()` reads. Stock apps ignore it. + ## Checking for features New members will be added over time, and an app may run in a Faceclaw build @@ -107,6 +113,18 @@ The [API reference](docs/api/README.md) documents every member in full. | `addCompassListener(fn)` | Turn on the magnetometer and receive headings. | | `createLayout(layout)` / `replaceLayout(layout)` | Build the page on the full 576×452 canvas, with no container limit, and optionally keep content across layouts. | | `setAssistantTools(tools)` | Offer tools to Faceclaw's voice assistant. | +| `addTouchDownListener(fn)` | Hear the moment a finger touches the ring or watch, before the gesture is known. | +| `addTextInputListener(fn)` | Receive dictated or typed text: the app becomes a "Type Into App" destination. | +| `startVoiceInput()` | Open the voice dialog for the app. | +| `setWindowIcon(icon)` | Replace the app's switcher icon with a pixel buffer. | +| `setAttention(on)` | Show or clear the attention dot on the app's switcher icon. | +| `setKeepScreenOn(on)` | Stop the display from sleeping for inactivity while the app is in front. | +| `getFonts()` | List the font families available to text and list containers. | +| `measureText(text, font)` | Measure text in a font, to size or centre it. | + +The package also exports `getInputSource(event)`, which tells you which device +(`ring`, `left-touchpad`, `right-touchpad` or `watch`) produced a stock gesture +event. ### Extended layout @@ -121,6 +139,7 @@ classes. The differences: - A container with `preserve: true` keeps the content (text, pixels, or list items and selection) of the same-named container in the previous layout. Without it, the container starts blank. +- Text and list containers can use other fonts (see [Fonts](#fonts)). ```ts import { ImageContainerProperty, TextContainerProperty } from "@evenrealities/even_hub_sdk"; @@ -141,6 +160,92 @@ Keep using the stock `updateImageRawData` and `textContainerUpgrade` to update content; they address containers by `containerID`. Once an app has used an extended layout, its window stays at 576×452 for the rest of the session. +### Fonts + +In an extended layout, text and list containers can set a `font` with a +`family`, `size` (in pixels) and `weight`. A `font` on the layout is the +default for all of them, and a container's own `font` overrides it field by +field. Without either, text is in the stock firmware font, as before. + +```ts +await fc.createLayout({ + font: { family: "Inter", size: 22 }, + textObject: [ + { containerID: 1, containerName: "title", xPosition: 16, yPosition: 12, width: 544, height: 50, content: "Today", font: { size: 40, weight: "bold" } }, + { containerID: 2, containerName: "body", xPosition: 16, yPosition: 70, width: 544, height: 360, content: "...", isEventCapture: 1 }, + ], +}); +``` + +Faceclaw bundles Roboto, Inter, Montserrat and Roboto Mono (weights 300, 400 +and 700, any size from 6 to 128) and the bitmap font Terminus (sizes 12 to +32, weights 400 and 700). `EvenHub` is the stock font, at 20px only. Users +can install more fonts, and `getFonts()` lists everything available. An +unknown family falls back to Roboto, and the nearest available weight and +(for bitmap fonts) size are used. + +`measureText(text, font)` returns the text's width and line height in a +font, so you can size containers or centre text. A list row is the font's +line height plus 12 pixels. + +### Input sources and touch-down + +The stock `eventSource` field can't tell the watch from the ring, and scrolls +don't carry it at all. Pass the event your `onEvenHubEvent` handler receives +to `getInputSource()` to find out which device it came from: + +```ts +import { getFaceclawExtensions, getInputSource } from "@faceclaw/evenhub-extensions"; + +bridge.onEvenHubEvent((event) => { + const source = getInputSource(event); // "ring", "left-touchpad", "right-touchpad", "watch" or null +}); +``` + +It returns `null` when the source is unknown (some scrolls), for non-gesture +events, and outside Faceclaw. + +A touch-down is the moment a finger lands on the ring or the watch's +touchpad, before Faceclaw knows whether it will become a tap, a scroll or a +hold. The interpreted gesture still arrives afterwards as the usual stock +event. Touch-downs suit games and other latency-sensitive input: + +```ts +fc.addTouchDownListener(({ source, timestampMs }) => flap()); +``` + +The glasses' own touchpads don't report touch-down. + +### Text input + +While the app has a text-input listener, Faceclaw offers it as the "Type Into +App" destination for its voice dialog, the phone keyboard and the watch. The +app can also open the voice dialog itself: + +```ts +fc.addTextInputListener(({ text }) => addNote(text)); + +// For example, from a "Dictate" item in the app's menu: +const opened = await fc.startVoiceInput(); +``` + +### Window icon, attention dot, and screen timeout + +```ts +// Draw a 32x32 icon on a canvas, light on black, and use it in the app switcher. +fc.setWindowIcon(ctx.getImageData(0, 0, 32, 32)); + +// Flag new activity while the app is in the background; clear it when seen. +fc.setAttention(true); + +// Keep the display awake while the app is in front (e.g. a teleprompter). +fc.setKeepScreenOn(true); +``` + +`setWindowIcon` takes `{ width, height, data }` with grayscale or RGBA pixels, +up to 256×256, so an `ImageData` works as is. Pass `null` to restore the +package's icon. + ### Compass Each `CompassReading` has several headings, all in degrees clockwise from north: @@ -191,6 +296,18 @@ keys. `requestApiKeyAccess(services)` shows a consent prompt on the glasses and resolves with the keys the user agreed to share. If the user declines, it resolves to `{}`. A grant lasts until the app closes. +## Stock APIs in Faceclaw + +Faceclaw implements the stock SDK too. Some differences worth knowing: + +- `getDeviceInfo()` and `onDeviceStatusChanged` report the real glasses: + their serial number, whether they are connected and worn, the battery level, + and whether they are charging. `isInCase` is the same as `isCharging`, since + the G2 only charges in its case. Fields Faceclaw doesn't know yet (wear state + before the glasses first report it) are left out. +- `shutDownPageContainer(1)` returns to the app switcher instead of asking to + quit. Use `quit()` to really quit. + ## Stability This package is pre-1.0. Until 1.0 the API may still change. After that, changes diff --git a/evenhub-extensions/docs/api/README.md b/evenhub-extensions/docs/api/README.md index 62b3bfdf..6d1b113e 100644 --- a/evenhub-extensions/docs/api/README.md +++ b/evenhub-extensions/docs/api/README.md @@ -261,6 +261,168 @@ tool's `handler` runs in the app when the assistant calls it. `void` +##### addTouchDownListener() + +```ts +addTouchDownListener(listener): () => void; +``` + +Receive touch-downs: the moment a finger touches the ring or the watch's +touchpad, before Faceclaw knows whether it will become a tap, a scroll or +a hold. The interpreted gesture still arrives afterwards as the usual +stock event. Use it where latency matters, as in games. + +Touch-downs arrive only while the app's window has input focus. The +glasses' own touchpads don't report them. + +###### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `listener` | (`event`) => `void` | Called on each touch-down. | + +###### Returns + +A function that unsubscribes `listener`. + +() => `void` + +##### addTextInputListener() + +```ts +addTextInputListener(listener): () => void; +``` + +Receive text the user sends to the app. While at least one listener is +registered and the app is in the foreground, Faceclaw offers the app as +the "Type Into App" destination of its voice dialog, the phone keyboard +and the watch. + +###### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `listener` | (`event`) => `void` | Called with each piece of text. | + +###### Returns + +A function that unsubscribes `listener`. + +() => `void` + +##### startVoiceInput() + +```ts +startVoiceInput(): Promise; +``` + +Open Faceclaw's voice dialog for this app. When the user sends the +dictation with Type Into App, it arrives at the text-input listeners. + +###### Returns + +`Promise`\<`boolean`\> + +A promise that resolves to true if the dialog is opening, or + false if it can't open: there is no text-input listener, the app isn't + in the foreground, voice input is unavailable, or another dialog is up. + +##### setWindowIcon() + +```ts +setWindowIcon(icon): Promise; +``` + +Replace the app's icon in the app switcher, or pass `null` to go back to +the package's icon. See [WindowIconImage](#windowiconimage) for the format. + +###### Parameters + +| Parameter | Type | +| ------ | ------ | +| `icon` | [`WindowIconImage`](#windowiconimage) \| `null` | + +###### Returns + +`Promise`\<`void`\> + +A promise that resolves once the icon is set, and rejects if the + image is malformed or larger than 256×256. + +##### setAttention() + +```ts +setAttention(attention): void; +``` + +Show or clear the attention dot on the app's switcher icon, for example +when something new arrives while the app is in the background. The dot +stays until the app clears it or closes. + +###### Parameters + +| Parameter | Type | +| ------ | ------ | +| `attention` | `boolean` | + +###### Returns + +`void` + +##### setKeepScreenOn() + +```ts +setKeepScreenOn(keepOn): void; +``` + +Stop the glasses display from turning off for inactivity while the app is +in the foreground, as a teleprompter or navigation app needs. It has no +effect while another window is in front, and the user can still turn the +display off. Pass `false` to restore the normal timeout. + +###### Parameters + +| Parameter | Type | +| ------ | ------ | +| `keepOn` | `boolean` | + +###### Returns + +`void` + +##### getFonts() + +```ts +getFonts(): Promise; +``` + +List the font families available for [FaceclawFont.family](#property-family), +including any the user has installed. + +###### Returns + +`Promise`\<[`FaceclawFontFamily`](#faceclawfontfamily)[]\> + +##### measureText() + +```ts +measureText(text, font?): Promise; +``` + +Measure text as a container with this font would draw it, for example to +size a text container or centre a label. + +###### Parameters + +| Parameter | Type | Description | +| ------ | ------ | ------ | +| `text` | `string` | The text. Lines split at `\n` are measured separately. | +| `font?` | [`FaceclawFont`](#faceclawfont) | The font to measure in. Unlike a container's font, it isn't combined with a layout default. Omit it to measure in the stock font. | + +###### Returns + +`Promise`\<[`TextMeasurement`](#textmeasurement)\> + *** ### getFaceclawExtensions() @@ -278,7 +440,7 @@ script runs. [`FaceclawExtensions`](#faceclawextensions) \| `null` -## Window lifecycle +## Window ### WindowLifecycleEventType @@ -312,51 +474,107 @@ Payload of a [FaceclawExtensions.addWindowLifecycleListener](#addwindowlifecycle | ------ | ------ | ------ | | `type` | [`WindowLifecycleEventType`](#windowlifecycleeventtype) | Which transition happened. | -## API keys +*** -### ApiKeyService +### WindowIconImage -```ts -type ApiKeyService = "openai" | "anthropic" | "soniox" | "elevenlabs" | "mapbox"; -``` +An image for [FaceclawExtensions.setWindowIcon](#setwindowicon). An `ImageData` (from +a canvas's `getImageData`) fits this shape and can be passed directly. -Third-party services whose API keys the user may have configured in Faceclaw. - -## Buzzer - -### BuzzerStep - -One step of a piezo-buzzer tone sequence. The G2 has a single monophonic PWM -buzzer, and the firmware plays a sequence's steps back to back on its own timer. - -#### Properties - -| Property | Type | Default value | Description | -| ------ | ------ | ------ | ------ | -| `freq` | `number` | `undefined` | Tone frequency in Hz. The piezo is loudest around 1–4 kHz and faint below about 150 Hz. | -| `ms` | `number` | `undefined` | Step duration in milliseconds (1–65535). | -| `duty?` | `number` | `50` | PWM duty cycle, 0–100. Use `duty: 0` for a rest (silence) lasting `ms`. | - -## Compass - -### CompassReading - -A magnetometer heading sample from [FaceclawExtensions.addCompassListener](#addcompasslistener). -All headings are in degrees clockwise, in the range [0, 360). - -Prefer `trueHeadingDegrees` when it is present, then `magneticHeadingDegrees`. -If `wearerCalibrated` is false, treat both as relative headings, or let the -user zero them. +Draw it like Faceclaw's own icons: light strokes on black. Brightness is +coverage, so black is transparent, and Faceclaw inverts the icon for the +selected window. The switcher draws icons at about 32×32; larger images are +scaled down to fit, keeping their aspect ratio. #### Properties | Property | Type | Description | | ------ | ------ | ------ | -| `headingDegrees` | `number` | Raw magnetic heading as reported by the glasses, with no correction for how they sit on the wearer's head. It is kept for apps that zero it themselves. | -| `magneticHeadingDegrees` | `number` | Magnetic heading corrected by the wearer's calibration offset from Faceclaw's Compass app. Equal to `headingDegrees` until the wearer calibrates. | -| `wearerCalibrated` | `boolean` | Whether the wearer has calibrated the compass in Faceclaw's Compass app. Only trust `magneticHeadingDegrees` and `trueHeadingDegrees` as absolute headings when this is true. | -| `declinationDegrees?` | `number` | Local magnetic declination in degrees (east positive), computed from the phone's location and the World Magnetic Model. Absent when Faceclaw has no location fix or no location permission. | -| `trueHeadingDegrees?` | `number` | `magneticHeadingDegrees` plus declination. Absent when `declinationDegrees` is. | +| `width` | `number` | Width in pixels, 1–256. | +| `height` | `number` | Height in pixels, 1–256. | +| `data` | `ArrayLike`\<`number`\> | Pixels in rows from the top left: either `width * height` grayscale values (0–255), or `width * height * 4` RGBA values, which Faceclaw converts to grayscale (luminance times alpha). | + +## Input + +### InputSource + +```ts +type InputSource = "ring" | "left-touchpad" | "right-touchpad" | "watch"; +``` + +The device an input came from: + +- `ring`: the Even R1 ring (or the ring pad in Faceclaw's phone app). +- `left-touchpad` / `right-touchpad`: the touch areas on the glasses' arms. +- `watch`: Faceclaw's Wear OS watch remote (or the watch pad in Faceclaw's + phone app). + +*** + +### TouchDownEvent + +A touch-down, from [FaceclawExtensions.addTouchDownListener](#addtouchdownlistener). + +#### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `source` | [`InputSource`](#inputsource) | Which device was touched. Currently always `ring` or `watch`: the glasses' touchpads don't report touch-down. | +| `timestampMs` | `number` | When Faceclaw received the touch, in milliseconds since the epoch (comparable with `Date.now()`). | + +*** + +### getInputSource() + +```ts +function getInputSource(event): InputSource | null; +``` + +Which device produced a stock EvenHub gesture event, or `null` if Faceclaw +didn't say. + +The stock `eventSource` field only knows the stock devices, so Faceclaw +reports the watch there as the ring. Faceclaw adds the real device to the +event's raw JSON as `faceclawInputSource`, and this function reads it. Pass +the event object your `onEvenHubEvent` handler receives. + +Faceclaw adds the field to clicks, double-clicks, long-presses and their +releases, and scrolls, in both `sysEvent` and `listEvent`. It is missing when +the glasses don't report a scroll's source, on non-gesture events, and in +every other host. + +#### Parameters + +| Parameter | Type | +| ------ | ------ | +| `event` | \| \{ `jsonData?`: `Record`\<`string`, `unknown`\>; \} \| `null` \| `undefined` | + +#### Returns + +[`InputSource`](#inputsource) \| `null` + +#### Example + +```ts +bridge.onEvenHubEvent((event) => { + if (event.sysEvent && getInputSource(event) === "watch") { + // ... + } +}); +``` + +## Text input + +### TextInputEvent + +Text sent to the app, from [FaceclawExtensions.addTextInputListener](#addtextinputlistener). + +#### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `text` | `string` | The finished text: a whole dictation, or a typed entry. | +| `submit?` | `boolean` | Present when the sender said whether to submit the text (`true`, like pressing Enter after it) or only insert it (`false`). Faceclaw's remote-input tool sets it; dictation and the phone keyboard leave it out. | ## Extended layout @@ -383,8 +601,8 @@ classes can be passed directly. In practice you should set `containerID`, | `containerName?` | `string` | Container name. `preserve` matches containers across layouts by name. | | `xPosition?` | `number` | Left edge in pixels on the 576×452 canvas. | | `yPosition?` | `number` | Top edge in pixels on the 576×452 canvas. | -| `width?` | `number` | Width in pixels. | -| `height?` | `number` | Height in pixels. | +| `width?` | `number` | Width in pixels. | +| `height?` | `number` | Height in pixels. | | `zOrderIndex?` | `number` | Stacking order: higher values draw on top. | | `isEventCapture?` | `number` \| `boolean` | When set to `1`/`true`, this container receives the app's tap and scroll events. Exactly one text or list container per layout should capture events. | | `preserve?` | `boolean` | When true, inherit content (text, image pixels, or list items and selection) from the container of the same kind and `containerName` in the previous layout. Otherwise the container starts blank. | @@ -407,8 +625,8 @@ A text container. The fields match the stock SDK's `TextContainerProperty`, plus | `containerName?` | `string` | `undefined` | Container name. `preserve` matches containers across layouts by name. | | `xPosition?` | `number` | `undefined` | Left edge in pixels on the 576×452 canvas. | | `yPosition?` | `number` | `undefined` | Top edge in pixels on the 576×452 canvas. | -| `width?` | `number` | `undefined` | Width in pixels. | -| `height?` | `number` | `undefined` | Height in pixels. | +| `width?` | `number` | `undefined` | Width in pixels. | +| `height?` | `number` | `undefined` | Height in pixels. | | `zOrderIndex?` | `number` | `undefined` | Stacking order: higher values draw on top. | | `isEventCapture?` | `number` \| `boolean` | `undefined` | When set to `1`/`true`, this container receives the app's tap and scroll events. Exactly one text or list container per layout should capture events. | | `preserve?` | `boolean` | `undefined` | When true, inherit content (text, image pixels, or list items and selection) from the container of the same kind and `containerName` in the previous layout. Otherwise the container starts blank. | @@ -418,6 +636,7 @@ A text container. The fields match the stock SDK's `TextContainerProperty`, plus | `borderColor?` | `number` | `undefined` | Accepted for compatibility with stock payloads. Faceclaw currently ignores it. | | `borderRadius?` | `number` | `undefined` | Border corner radius in pixels. | | `paddingLength?` | `number` | `undefined` | Padding between the border and the text, in pixels. | +| `font?` | [`FaceclawFont`](#faceclawfont) | `undefined` | The text's font. Its fields override the layout's [FaceclawLayout.font](#property-font-2) one by one. With neither, the text is in the stock firmware font. | *** @@ -469,8 +688,8 @@ A list container. The fields match the stock SDK's `ListContainerProperty`, plus | `containerName?` | `string` | Container name. `preserve` matches containers across layouts by name. | | `xPosition?` | `number` | Left edge in pixels on the 576×452 canvas. | | `yPosition?` | `number` | Top edge in pixels on the 576×452 canvas. | -| `width?` | `number` | Width in pixels. | -| `height?` | `number` | Height in pixels. | +| `width?` | `number` | Width in pixels. | +| `height?` | `number` | Height in pixels. | | `zOrderIndex?` | `number` | Stacking order: higher values draw on top. | | `isEventCapture?` | `number` \| `boolean` | When set to `1`/`true`, this container receives the app's tap and scroll events. Exactly one text or list container per layout should capture events. | | `preserve?` | `boolean` | When true, inherit content (text, image pixels, or list items and selection) from the container of the same kind and `containerName` in the previous layout. Otherwise the container starts blank. | @@ -479,6 +698,7 @@ A list container. The fields match the stock SDK's `ListContainerProperty`, plus | `borderColor?` | `number` | Accepted for compatibility with stock payloads. Faceclaw currently ignores it. | | `borderRadius?` | `number` | Border corner radius in pixels. | | `paddingLength?` | `number` | Padding between the border and the items, in pixels. | +| `font?` | [`FaceclawFont`](#faceclawfont) | The items' font. Its fields override the layout's [FaceclawLayout.font](#property-font-2) one by one. With neither, the items are in the stock firmware font. Each row is the font's line height plus 12 pixels. | *** @@ -512,6 +732,8 @@ classes, with three differences: - Each container may set `preserve: true` to inherit its content from the same-named container in the previous layout. +Text and list containers can also use other fonts (see [FaceclawFont](#faceclawfont)). + #### Properties | Property | Type | Description | @@ -521,6 +743,110 @@ classes, with three differences: | `listObject?` | [`FaceclawListContainer`](#faceclawlistcontainer)[] | List containers. | | `menuObject?` | [`FaceclawMenu`](#faceclawmenu) | The page's contextual menu. Omit it to clear any previous menu. | | `containerTotalNum?` | `number` | Accepted for compatibility with stock payloads and ignored: there is no container limit. | +| `font?` | [`FaceclawFont`](#faceclawfont) | The default font for every text and list container in the layout. | + +## Fonts + +### FaceclawFont + +A font for text and list containers in an extended layout, from +[FaceclawLayout.font](#property-font-2) and the containers' own `font`. A container +that has no font, and whose layout has none, uses the stock firmware font. + +Available families (see [FaceclawExtensions.getFonts](#getfonts)): + +- `Roboto`, `Inter`, `Montserrat` and `Roboto Mono`: bundled TrueType + fonts in weights 300, 400 and 700, at any size. +- `Terminus`: a monospace bitmap font, in sizes 12, 14, 16, 18, 20, 22, 24, + 28 and 32, and weights 400 and 700. +- `EvenHub`: the stock firmware font, 20px only. Use it to bring back the + stock font for one container when the layout sets another. +- Any font the user has installed in Faceclaw. + +Text in the stock font wraps exactly as on the stock firmware. Text in +other fonts wraps with Faceclaw's own line breaking. + +#### Properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `family?` | `string` | `"Roboto"` | Font family, matched without regard to case, spaces or punctuation. An unknown family falls back to Roboto. | +| `size?` | `number` | `20` | Size in pixels: the em size, as in CSS `font-size`. A line is somewhat taller; [FaceclawExtensions.measureText](#measuretext) reports its height. 6–128. Bitmap families use their nearest size. | +| `weight?` | `number` \| `"normal"` \| `"bold"` | `400` | Weight, 100–900, where `"normal"` is 400 and `"bold"` is 700. The nearest weight the family has is used, as CSS chooses it. | + +*** + +### FaceclawFontFamily + +A font family Faceclaw can draw, from [FaceclawExtensions.getFonts](#getfonts). + +#### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `family` | `string` | The name to use as [FaceclawFont.family](#property-family). | +| `weights` | `number`[] | The weights the family has, lightest first. | +| `sizes?` | `number`[] | For a bitmap family, the sizes it has. Absent for a scalable family, which takes any size. | +| `monospace` | `boolean` | Whether every character has the same width. | + +*** + +### TextMeasurement + +The size of some text, from [FaceclawExtensions.measureText](#measuretext). + +#### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `width` | `number` | Width in pixels of the widest line (lines are split at `\n`). | +| `lineHeight` | `number` | Height in pixels of one line. A text container advances by this much per line. | + +## API keys + +### ApiKeyService + +```ts +type ApiKeyService = "openai" | "anthropic" | "soniox" | "elevenlabs" | "mapbox"; +``` + +Third-party services whose API keys the user may have configured in Faceclaw. + +## Buzzer + +### BuzzerStep + +One step of a piezo-buzzer tone sequence. The G2 has a single monophonic PWM +buzzer, and the firmware plays a sequence's steps back to back on its own timer. + +#### Properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `freq` | `number` | `undefined` | Tone frequency in Hz. The piezo is loudest around 1–4 kHz and faint below about 150 Hz. | +| `ms` | `number` | `undefined` | Step duration in milliseconds (1–65535). | +| `duty?` | `number` | `50` | PWM duty cycle, 0–100. Use `duty: 0` for a rest (silence) lasting `ms`. | + +## Compass + +### CompassReading + +A magnetometer heading sample from [FaceclawExtensions.addCompassListener](#addcompasslistener). +All headings are in degrees clockwise, in the range [0, 360). + +Prefer `trueHeadingDegrees` when it is present, then `magneticHeadingDegrees`. +If `wearerCalibrated` is false, treat both as relative headings, or let the +user zero them. + +#### Properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `headingDegrees` | `number` | Raw magnetic heading as reported by the glasses, with no correction for how they sit on the wearer's head. It is kept for apps that zero it themselves. | +| `magneticHeadingDegrees` | `number` | Magnetic heading corrected by the wearer's calibration offset from Faceclaw's Compass app. Equal to `headingDegrees` until the wearer calibrates. | +| `wearerCalibrated` | `boolean` | Whether the wearer has calibrated the compass in Faceclaw's Compass app. Only trust `magneticHeadingDegrees` and `trueHeadingDegrees` as absolute headings when this is true. | +| `declinationDegrees?` | `number` | Local magnetic declination in degrees (east positive), computed from the phone's location and the World Magnetic Model. Absent when Faceclaw has no location fix or no location permission. | +| `trueHeadingDegrees?` | `number` | `magneticHeadingDegrees` plus declination. Absent when `declinationDegrees` is. | ## Assistant tools diff --git a/evenhub-extensions/src/index.ts b/evenhub-extensions/src/index.ts index b0b0bccd..4fbebd07 100644 --- a/evenhub-extensions/src/index.ts +++ b/evenhub-extensions/src/index.ts @@ -69,20 +69,121 @@ export interface BuzzerStep { * An app can assume it starts `visible` and `focused` at launch. Events report * changes from there. * - * @group Window lifecycle + * @group Window */ export type WindowLifecycleEventType = "visible" | "hidden" | "focused" | "blurred"; /** * Payload of a {@link FaceclawExtensions.addWindowLifecycleListener} callback. * - * @group Window lifecycle + * @group Window */ export interface WindowLifecycleEvent { /** Which transition happened. */ type: WindowLifecycleEventType; } +/** + * An image for {@link FaceclawExtensions.setWindowIcon}. An `ImageData` (from + * a canvas's `getImageData`) fits this shape and can be passed directly. + * + * Draw it like Faceclaw's own icons: light strokes on black. Brightness is + * coverage, so black is transparent, and Faceclaw inverts the icon for the + * selected window. The switcher draws icons at about 32×32; larger images are + * scaled down to fit, keeping their aspect ratio. + * + * @group Window + */ +export interface WindowIconImage { + /** Width in pixels, 1–256. */ + width: number; + /** Height in pixels, 1–256. */ + height: number; + /** + * Pixels in rows from the top left: either `width * height` grayscale + * values (0–255), or `width * height * 4` RGBA values, which Faceclaw + * converts to grayscale (luminance times alpha). + */ + data: ArrayLike; +} + +// ---- Input ---- + +/** + * The device an input came from: + * + * - `ring`: the Even R1 ring (or the ring pad in Faceclaw's phone app). + * - `left-touchpad` / `right-touchpad`: the touch areas on the glasses' arms. + * - `watch`: Faceclaw's Wear OS watch remote (or the watch pad in Faceclaw's + * phone app). + * + * @group Input + */ +export type InputSource = "ring" | "left-touchpad" | "right-touchpad" | "watch"; + +/** + * A touch-down, from {@link FaceclawExtensions.addTouchDownListener}. + * + * @group Input + */ +export interface TouchDownEvent { + /** + * Which device was touched. Currently always `ring` or `watch`: the + * glasses' touchpads don't report touch-down. + */ + source: InputSource; + /** When Faceclaw received the touch, in milliseconds since the epoch (comparable with `Date.now()`). */ + timestampMs: number; +} + +/** + * Which device produced a stock EvenHub gesture event, or `null` if Faceclaw + * didn't say. + * + * The stock `eventSource` field only knows the stock devices, so Faceclaw + * reports the watch there as the ring. Faceclaw adds the real device to the + * event's raw JSON as `faceclawInputSource`, and this function reads it. Pass + * the event object your `onEvenHubEvent` handler receives. + * + * Faceclaw adds the field to clicks, double-clicks, long-presses and their + * releases, and scrolls, in both `sysEvent` and `listEvent`. It is missing when + * the glasses don't report a scroll's source, on non-gesture events, and in + * every other host. + * + * @example + * ```ts + * bridge.onEvenHubEvent((event) => { + * if (event.sysEvent && getInputSource(event) === "watch") { + * // ... + * } + * }); + * ``` + * + * @group Input + */ +export function getInputSource(event: { jsonData?: Record } | null | undefined): InputSource | null { + const value = event?.jsonData?.faceclawInputSource; + return value === "ring" || value === "left-touchpad" || value === "right-touchpad" || value === "watch" ? value : null; +} + +// ---- Text input ---- + +/** + * Text sent to the app, from {@link FaceclawExtensions.addTextInputListener}. + * + * @group Text input + */ +export interface TextInputEvent { + /** The finished text: a whole dictation, or a typed entry. */ + text: string; + /** + * Present when the sender said whether to submit the text (`true`, like + * pressing Enter after it) or only insert it (`false`). Faceclaw's + * remote-input tool sets it; dictation and the phone keyboard leave it out. + */ + submit?: boolean; +} + /** * A magnetometer heading sample from {@link FaceclawExtensions.addCompassListener}. * All headings are in degrees clockwise, in the range [0, 360). @@ -120,6 +221,78 @@ export interface CompassReading { trueHeadingDegrees?: number; } +// ---- Fonts ---- + +/** + * A font for text and list containers in an extended layout, from + * {@link FaceclawLayout.font} and the containers' own `font`. A container + * that has no font, and whose layout has none, uses the stock firmware font. + * + * Available families (see {@link FaceclawExtensions.getFonts}): + * + * - `Roboto`, `Inter`, `Montserrat` and `Roboto Mono`: bundled TrueType + * fonts in weights 300, 400 and 700, at any size. + * - `Terminus`: a monospace bitmap font, in sizes 12, 14, 16, 18, 20, 22, 24, + * 28 and 32, and weights 400 and 700. + * - `EvenHub`: the stock firmware font, 20px only. Use it to bring back the + * stock font for one container when the layout sets another. + * - Any font the user has installed in Faceclaw. + * + * Text in the stock font wraps exactly as on the stock firmware. Text in + * other fonts wraps with Faceclaw's own line breaking. + * + * @group Fonts + */ +export interface FaceclawFont { + /** + * Font family, matched without regard to case, spaces or punctuation. An + * unknown family falls back to Roboto. + * @defaultValue "Roboto" + */ + family?: string; + /** + * Size in pixels: the em size, as in CSS `font-size`. A line is somewhat + * taller; {@link FaceclawExtensions.measureText} reports its height. 6–128. + * Bitmap families use their nearest size. + * @defaultValue 20 + */ + size?: number; + /** + * Weight, 100–900, where `"normal"` is 400 and `"bold"` is 700. The nearest + * weight the family has is used, as CSS chooses it. + * @defaultValue 400 + */ + weight?: number | "normal" | "bold"; +} + +/** + * A font family Faceclaw can draw, from {@link FaceclawExtensions.getFonts}. + * + * @group Fonts + */ +export interface FaceclawFontFamily { + /** The name to use as {@link FaceclawFont.family}. */ + family: string; + /** The weights the family has, lightest first. */ + weights: number[]; + /** For a bitmap family, the sizes it has. Absent for a scalable family, which takes any size. */ + sizes?: number[]; + /** Whether every character has the same width. */ + monospace: boolean; +} + +/** + * The size of some text, from {@link FaceclawExtensions.measureText}. + * + * @group Fonts + */ +export interface TextMeasurement { + /** Width in pixels of the widest line (lines are split at `\n`). */ + width: number; + /** Height in pixels of one line. A text container advances by this much per line. */ + lineHeight: number; +} + // ---- Extended layout (a superset of the stock EvenHub page containers) ---- /** @@ -185,6 +358,12 @@ export interface FaceclawTextContainer extends FaceclawContainerCommon { borderRadius?: number; /** Padding between the border and the text, in pixels. */ paddingLength?: number; + /** + * The text's font. Its fields override the layout's + * {@link FaceclawLayout.font} one by one. With neither, the text is in the + * stock firmware font. + */ + font?: FaceclawFont; } /** @@ -233,6 +412,13 @@ export interface FaceclawListContainer extends FaceclawContainerCommon { borderRadius?: number; /** Padding between the border and the items, in pixels. */ paddingLength?: number; + /** + * The items' font. Its fields override the layout's + * {@link FaceclawLayout.font} one by one. With neither, the items are in + * the stock firmware font. Each row is the font's line height plus 12 + * pixels. + */ + font?: FaceclawFont; } /** @@ -262,6 +448,8 @@ export interface FaceclawMenu { * - Each container may set `preserve: true` to inherit its content from the * same-named container in the previous layout. * + * Text and list containers can also use other fonts (see {@link FaceclawFont}). + * * @group Extended layout */ export interface FaceclawLayout { @@ -275,6 +463,8 @@ export interface FaceclawLayout { menuObject?: FaceclawMenu; /** Accepted for compatibility with stock payloads and ignored: there is no container limit. */ containerTotalNum?: number; + /** The default font for every text and list container in the layout. */ + font?: FaceclawFont; } // ---- Voice-assistant tools ---- @@ -445,6 +635,82 @@ export interface FaceclawExtensions { * @param tools - The tools to offer. Pass `[]` to remove them all. */ setAssistantTools(tools: AssistantTool[]): void; + + /** + * Receive touch-downs: the moment a finger touches the ring or the watch's + * touchpad, before Faceclaw knows whether it will become a tap, a scroll or + * a hold. The interpreted gesture still arrives afterwards as the usual + * stock event. Use it where latency matters, as in games. + * + * Touch-downs arrive only while the app's window has input focus. The + * glasses' own touchpads don't report them. + * + * @param listener - Called on each touch-down. + * @returns A function that unsubscribes `listener`. + */ + addTouchDownListener(listener: (event: TouchDownEvent) => void): () => void; + + /** + * Receive text the user sends to the app. While at least one listener is + * registered and the app is in the foreground, Faceclaw offers the app as + * the "Type Into App" destination of its voice dialog, the phone keyboard + * and the watch. + * + * @param listener - Called with each piece of text. + * @returns A function that unsubscribes `listener`. + */ + addTextInputListener(listener: (event: TextInputEvent) => void): () => void; + + /** + * Open Faceclaw's voice dialog for this app. When the user sends the + * dictation with Type Into App, it arrives at the text-input listeners. + * + * @returns A promise that resolves to true if the dialog is opening, or + * false if it can't open: there is no text-input listener, the app isn't + * in the foreground, voice input is unavailable, or another dialog is up. + */ + startVoiceInput(): Promise; + + /** + * Replace the app's icon in the app switcher, or pass `null` to go back to + * the package's icon. See {@link WindowIconImage} for the format. + * + * @returns A promise that resolves once the icon is set, and rejects if the + * image is malformed or larger than 256×256. + */ + setWindowIcon(icon: WindowIconImage | null): Promise; + + /** + * Show or clear the attention dot on the app's switcher icon, for example + * when something new arrives while the app is in the background. The dot + * stays until the app clears it or closes. + */ + setAttention(attention: boolean): void; + + /** + * Stop the glasses display from turning off for inactivity while the app is + * in the foreground, as a teleprompter or navigation app needs. It has no + * effect while another window is in front, and the user can still turn the + * display off. Pass `false` to restore the normal timeout. + */ + setKeepScreenOn(keepOn: boolean): void; + + /** + * List the font families available for {@link FaceclawFont.family}, + * including any the user has installed. + */ + getFonts(): Promise; + + /** + * Measure text as a container with this font would draw it, for example to + * size a text container or centre a label. + * + * @param text - The text. Lines split at `\n` are measured separately. + * @param font - The font to measure in. Unlike a container's font, it + * isn't combined with a layout default. Omit it to measure in the stock + * font. + */ + measureText(text: string, font?: FaceclawFont): Promise; } declare global { diff --git a/evenhub-extensions/test/stock-sdk-compat.ts b/evenhub-extensions/test/stock-sdk-compat.ts index e3d09263..554dbc77 100644 --- a/evenhub-extensions/test/stock-sdk-compat.ts +++ b/evenhub-extensions/test/stock-sdk-compat.ts @@ -10,9 +10,12 @@ import { MenuItemProperty, RebuildPageContainer, TextContainerProperty, + type EvenHubEvent, } from "@evenrealities/even_hub_sdk"; +import { getInputSource } from "../src/index"; import type { FaceclawExtensions, + InputSource, FaceclawImageContainer, FaceclawLayout, FaceclawListContainer, @@ -62,3 +65,12 @@ void fc.createLayout(fromCreate); void fc.replaceLayout(fromRebuild); void fc.replaceLayout(mixed); void fc.replaceLayout(new RebuildPageContainer({ textObject: [new TextContainerProperty({ containerID: 1 })] })); + +// The stock event the SDK hands onEvenHubEvent carries the source field. +declare const stockEvent: EvenHubEvent; +const source: InputSource | null = getInputSource(stockEvent); +void source; + +// A canvas ImageData is accepted as a window icon. +declare const imageData: ImageData; +void fc.setWindowIcon(imageData); diff --git a/evenhub-extensions/typedoc.json b/evenhub-extensions/typedoc.json index 7133f76a..5faa1991 100644 --- a/evenhub-extensions/typedoc.json +++ b/evenhub-extensions/typedoc.json @@ -18,11 +18,14 @@ "treatWarningsAsErrors": true, "groupOrder": [ "Entry point", - "Window lifecycle", + "Window", + "Input", + "Text input", + "Extended layout", + "Fonts", "API keys", "Buzzer", "Compass", - "Extended layout", "Assistant tools", "Properties", "Methods", diff --git a/tests/evenhub-containers.test.cjs b/tests/evenhub-containers.test.cjs index 2af839ae..7527df66 100644 --- a/tests/evenhub-containers.test.cjs +++ b/tests/evenhub-containers.test.cjs @@ -118,3 +118,26 @@ test("flags accept booleans (extension layouts) as well as 0/1 (stock)", () => { ); assert.equal(page.containers[0].selectBorder, true); }); + +test("a layout font is the default for text and list containers, which override it field by field", () => { + const page = parsePage({ + font: { family: "Inter", size: 24 }, + listObject: [{ containerID: 1, containerName: "l", font: { weight: "bold" } }], + textObject: [{ containerID: 2, containerName: "t" }, { containerID: 3, containerName: "u", font: { family: "Terminus" } }], + imageObject: [{ containerID: 4, containerName: "i" }], + }); + assert.deepEqual( + page.containers.map((c) => [c.name, c.font]), + [ + ["l", { family: "Inter", size: 24, weight: 700 }], + ["i", undefined], + ["t", { family: "Inter", size: 24 }], + ["u", { family: "Terminus", size: 24 }], + ], + ); +}); + +test("containers without a font anywhere keep the stock font", () => { + const page = parsePage({ textObject: [{ containerID: 1, containerName: "t", content: "x" }] }); + assert.equal(page.containers[0].font, undefined); +}); diff --git a/tests/evenhub-device-status.test.cjs b/tests/evenhub-device-status.test.cjs new file mode 100644 index 00000000..3092997f --- /dev/null +++ b/tests/evenhub-device-status.test.cjs @@ -0,0 +1,45 @@ +// The stock DeviceStatus an EvenHub app sees (getGlassesInfo().status and the +// deviceStatusChanged push), built from Faceclaw's view of the glasses. +const test = require("node:test"); +const assert = require("node:assert/strict"); + +const { buildEvenHubDeviceStatus, sameDeviceStatus, PLACEHOLDER_SERIAL } = require("../.test-build/app/apps/evenhub/device-status.js"); + +const worn = { serial: "S200LAAJ0123", connected: true, worn: true, battery: 73, charging: false }; + +test("connected, worn glasses report their real values", () => { + assert.deepEqual(buildEvenHubDeviceStatus(worn), { + sn: "S200LAAJ0123", + connectType: "connected", + isWearing: true, + batteryLevel: 73, + isCharging: false, + isInCase: false, + }); +}); + +test("charging means in the case, since the G2 only charges there", () => { + const status = buildEvenHubDeviceStatus({ ...worn, worn: false, charging: true }); + assert.equal(status.isCharging, true); + assert.equal(status.isInCase, true); + assert.equal(status.isWearing, false); +}); + +test("unknown wear state and battery are omitted, not guessed", () => { + const status = buildEvenHubDeviceStatus({ serial: null, connected: false, worn: null, battery: null, charging: false }); + assert.deepEqual(status, { sn: PLACEHOLDER_SERIAL, connectType: "disconnected", isCharging: false, isInCase: false }); + assert.equal("isWearing" in status, false); + assert.equal("batteryLevel" in status, false); +}); + +test("a blank serial falls back to the placeholder", () => { + assert.equal(buildEvenHubDeviceStatus({ ...worn, serial: " " }).sn, PLACEHOLDER_SERIAL); +}); + +test("sameDeviceStatus compares every field", () => { + const a = buildEvenHubDeviceStatus(worn); + assert.equal(sameDeviceStatus(a, buildEvenHubDeviceStatus(worn)), true); + assert.equal(sameDeviceStatus(a, buildEvenHubDeviceStatus({ ...worn, battery: 72 })), false); + assert.equal(sameDeviceStatus(a, buildEvenHubDeviceStatus({ ...worn, worn: null })), false); + assert.equal(sameDeviceStatus(a, buildEvenHubDeviceStatus({ ...worn, connected: false })), false); +}); diff --git a/tests/evenhub-extensions-shim.test.cjs b/tests/evenhub-extensions-shim.test.cjs index 1ad5e5f5..bb43d0bb 100644 --- a/tests/evenhub-extensions-shim.test.cjs +++ b/tests/evenhub-extensions-shim.test.cjs @@ -99,3 +99,66 @@ test('assistant tools send specs to the host and run handlers on invoke', async const results = posted.filter((p) => p.name === 'faceclawExtToolResult').map((p) => p.args).sort((a, b) => a[0] - b[0]); assert.deepEqual(results, [[7, true, 42], [8, false, 'nope'], [9, false, 'unknown tool missing']]); }); + +test('touch-down and text input are requested while someone listens, and unsubscribing twice is harmless', () => { + const { win, fc, posted } = page(); + const seen = []; + const offTouch = fc.addTouchDownListener((e) => seen.push(`touch:${e.source}`)); + const offText1 = fc.addTextInputListener((e) => seen.push(`text1:${e.text}`)); + const offText2 = fc.addTextInputListener((e) => seen.push(`text2:${e.text}`)); + win.__fcExtEvent('touchDown', { source: 'watch', timestampMs: 5 }); + win.__fcExtEvent('textInput', { text: 'hi' }); + offText1(); + offText1(); + win.__fcExtEvent('textInput', { text: 'again' }); + offText2(); + offTouch(); + assert.deepEqual(seen, ['touch:watch', 'text1:hi', 'text2:hi', 'text2:again']); + assert.deepEqual(posted.map((p) => p.args), [ + ['setTouchDown', true], + ['setTextInput', true], + ['setTextInput', false], + ['setTouchDown', false], + ]); +}); + +test('window icons are sent as plain arrays, and clearing sends null', async () => { + const { win, fc, posted } = page(); + const set = fc.setWindowIcon({ width: 1, height: 2, data: new Uint8ClampedArray([7, 9]) }); + const clear = fc.setWindowIcon(null); + assert.deepEqual(posted.map((p) => p.args), [ + ['setWindowIcon', { width: 1, height: 2, data: [7, 9] }], + ['setWindowIcon', null], + ]); + win.__fcExtResolve(posted[0].id, true, null); + win.__fcExtResolve(posted[1].id, false, 'setWindowIcon: bad'); + await set; + await assert.rejects(clear, /setWindowIcon: bad/); +}); + +test('window controls are fire-and-forget; startVoiceInput resolves the host answer', async () => { + const { win, fc, posted } = page(); + fc.setAttention(1); + fc.setKeepScreenOn(false); + const voice = fc.startVoiceInput(); + assert.deepEqual(posted.map((p) => [p.args, p.id === 0]), [ + [['setAttention', true], true], + [['setKeepScreenOn', false], true], + [['startVoiceInput'], false], + ]); + win.__fcExtResolve(posted[2].id, true, false); + assert.equal(await voice, false); +}); + +test('font queries are calls; measureText sends null for no font', () => { + const { fc, posted } = page(); + void fc.getFonts(); + void fc.measureText('hi'); + void fc.measureText(42, { family: 'Inter', size: 30 }); + assert.deepEqual(posted.map((p) => p.args), [ + ['getFonts'], + ['measureText', 'hi', null], + ['measureText', '42', { family: 'Inter', size: 30 }], + ]); + assert.ok(posted.every((p) => p.id > 0)); +}); diff --git a/tests/evenhub-font-spec.test.cjs b/tests/evenhub-font-spec.test.cjs new file mode 100644 index 00000000..ef4fcb39 --- /dev/null +++ b/tests/evenhub-font-spec.test.cjs @@ -0,0 +1,84 @@ +// Font options for EvenHub text and list containers (extension layouts): +// parsing, layout-default inheritance, and choosing a face. +const test = require("node:test"); +const assert = require("node:assert/strict"); + +const { + parseFontSpec, + mergeFontSpecs, + selectFontFace, + describeFontFamilies, + MAX_FONT_SIZE, +} = require("../.test-build/app/apps/evenhub/font-spec.js"); + +const TERMINUS_SIZES = [12, 14, 16, 18, 20, 22, 24, 28, 32]; +const ttf = (family, weight, monospace = false) => ({ family, weight, sizes: null, monospace, key: `ttf:${family}:${weight}` }); +const FACES = [ + { family: "EvenHub", weight: 400, sizes: [20], monospace: false, key: "stock" }, + { family: "Terminus", weight: 400, sizes: TERMINUS_SIZES, monospace: true, key: "terminus:400" }, + { family: "Terminus", weight: 700, sizes: TERMINUS_SIZES, monospace: true, key: "terminus:700" }, + ttf("Inter 18pt", 300), ttf("Inter 18pt", 400), ttf("Inter 18pt", 700), + ttf("Roboto", 300), ttf("Roboto", 400), ttf("Roboto", 700), + ttf("Roboto Mono", 300, true), ttf("Roboto Mono", 400, true), ttf("Roboto Mono", 700, true), +]; +const pick = (spec, faces = FACES) => { + const choice = selectFontFace(spec, faces); + return choice && `${choice.face.key}@${choice.size}`; +}; + +test("no font object means no spec (the stock font); an empty one means the defaults", () => { + assert.equal(parseFontSpec(undefined), undefined); + assert.equal(parseFontSpec("Roboto"), undefined); + assert.deepEqual(parseFontSpec({}), {}); + assert.equal(pick({}), "ttf:Roboto:400@20"); +}); + +test("sizes are rounded and clamped, weights take keywords and numeric strings", () => { + assert.deepEqual(parseFontSpec({ family: " Inter ", size: 17.6, weight: "bold" }), { family: "Inter", size: 18, weight: 700 }); + assert.deepEqual(parseFontSpec({ size: 1000, weight: "normal" }), { size: MAX_FONT_SIZE, weight: 400 }); + assert.deepEqual(parseFontSpec({ size: 2, weight: "300" }), { size: 6, weight: 300 }); + assert.deepEqual(parseFontSpec({ family: "", size: "x", weight: "heavy" }), {}); +}); + +test("a container's font overrides the layout default field by field", () => { + assert.deepEqual(mergeFontSpecs({ family: "Inter", size: 24 }, { size: 30 }), { family: "Inter", size: 30 }); + assert.deepEqual(mergeFontSpecs(undefined, { size: 30 }), { size: 30 }); + assert.deepEqual(mergeFontSpecs({ family: "Inter" }, undefined), { family: "Inter" }); + assert.equal(mergeFontSpecs(undefined, undefined), undefined); +}); + +test("families match loosely, including without an optical-size suffix", () => { + assert.equal(pick({ family: "inter" }), "ttf:Inter 18pt:400@20"); + assert.equal(pick({ family: "Inter 18pt" }), "ttf:Inter 18pt:400@20"); + assert.equal(pick({ family: "robotomono", size: 14 }), "ttf:Roboto Mono:400@14"); + assert.equal(pick({ family: "ROBOTO" }), "ttf:Roboto:400@20", "Roboto doesn't pick up Roboto Mono"); +}); + +test("an unknown family falls back to Roboto, and with no Roboto there is no choice", () => { + assert.equal(pick({ family: "Comic Sans", weight: 700 }), "ttf:Roboto:700@20"); + assert.equal(pick({ family: "Comic Sans" }, FACES.slice(0, 3)), null); +}); + +test("weights follow CSS matching", () => { + assert.equal(pick({ family: "Inter", weight: 500 }), "ttf:Inter 18pt:400@20", "400-500 look lighter before heavier"); + assert.equal(pick({ family: "Inter", weight: 600 }), "ttf:Inter 18pt:700@20", "heavier requests look heavier first"); + assert.equal(pick({ family: "Inter", weight: 350 }), "ttf:Inter 18pt:300@20", "lighter requests look lighter first"); + assert.equal(pick({ family: "Inter", weight: 100 }), "ttf:Inter 18pt:300@20"); + assert.equal(pick({ family: "Inter", weight: 900 }), "ttf:Inter 18pt:700@20"); +}); + +test("bitmap families snap to their nearest size", () => { + assert.equal(pick({ family: "Terminus", size: 25 }), "terminus:400@24"); + assert.equal(pick({ family: "Terminus", size: 26, weight: 700 }), "terminus:700@24", "a tie takes the smaller size"); + assert.equal(pick({ family: "Terminus", size: 100 }), "terminus:400@32"); + assert.equal(pick({ family: "EvenHub", size: 40, weight: 700 }), "stock@20"); +}); + +test("families are listed once each, by their app-facing name", () => { + const families = describeFontFamilies(FACES); + assert.deepEqual(families.map((f) => f.family), ["EvenHub", "Inter", "Roboto", "Roboto Mono", "Terminus"]); + const terminus = families.find((f) => f.family === "Terminus"); + assert.deepEqual(terminus, { family: "Terminus", weights: [400, 700], sizes: TERMINUS_SIZES, monospace: true }); + const inter = families.find((f) => f.family === "Inter"); + assert.deepEqual(inter, { family: "Inter", weights: [300, 400, 700], monospace: false }); +}); diff --git a/tests/evenhub-window-icon.test.cjs b/tests/evenhub-window-icon.test.cjs new file mode 100644 index 00000000..3559cfe6 --- /dev/null +++ b/tests/evenhub-window-icon.test.cjs @@ -0,0 +1,56 @@ +// App-supplied switcher icons (extension setWindowIcon): parsing the pixel +// buffer from the bridge, and scaling it to the switcher's icon size. +const test = require("node:test"); +const assert = require("node:assert/strict"); + +const { parseWindowIcon, WindowIconRenderer, MAX_WINDOW_ICON_DIMENSION } = require("../.test-build/app/apps/evenhub/window-icon.js"); + +test("grayscale data is taken as-is", () => { + const icon = parseWindowIcon({ width: 2, height: 2, data: [0, 64, 128, 255] }); + assert.deepEqual([...icon.pixels], [0, 64, 128, 255]); +}); + +test("RGBA data (an ImageData) becomes luminance times alpha", () => { + const icon = parseWindowIcon({ + width: 3, + height: 1, + data: [255, 255, 255, 255, 255, 255, 255, 0, 0, 255, 0, 255], + }); + assert.deepEqual([...icon.pixels], [255, 0, 182]); +}); + +test("a JSON-ified typed array parses like a plain array", () => { + const icon = parseWindowIcon({ width: 2, height: 1, data: { 0: 10, 1: 20 } }); + assert.deepEqual([...icon.pixels], [10, 20]); +}); + +test("malformed icons are refused", () => { + assert.equal(parseWindowIcon(null), null); + assert.equal(parseWindowIcon({ width: 2, height: 2, data: [1, 2, 3] }), null, "wrong length"); + assert.equal(parseWindowIcon({ width: 0, height: 2, data: [] }), null, "empty"); + assert.equal(parseWindowIcon({ width: 1.5, height: 2, data: [1, 2, 3] }), null, "fractional size"); + assert.equal(parseWindowIcon({ width: 1, height: 1, data: ["x"] }), null, "non-numeric data"); + const big = MAX_WINDOW_ICON_DIMENSION + 1; + assert.equal(parseWindowIcon({ width: big, height: 1, data: new Array(big).fill(0) }), null, "too wide"); +}); + +test("icons shrink to fit the box, keeping their aspect ratio and averaging pixels", () => { + const data = []; + for (let y = 0; y < 4; y++) for (let x = 0; x < 8; x++) data.push(x < 4 ? 0 : 200); + const renderer = new WindowIconRenderer(parseWindowIcon({ width: 8, height: 4, data })); + const small = renderer.render(4); + assert.equal(small.width, 4); + assert.equal(small.height, 2); + assert.deepEqual([...small.pixels], [0, 0, 200, 200, 0, 0, 200, 200]); + const odd = renderer.render(3); + assert.equal(odd.width, 3); + // The middle column straddles the edge between the halves. + assert.equal(odd.pixels[1], 100); +}); + +test("renders are cached per size, and a fitting icon is used unscaled", () => { + const source = parseWindowIcon({ width: 4, height: 4, data: new Array(16).fill(9) }); + const renderer = new WindowIconRenderer(source); + assert.equal(renderer.render(32), renderer.render(32)); + assert.equal(renderer.render(4), source); +}); diff --git a/tests/ios-glanceboard.test.cjs b/tests/ios-glanceboard.test.cjs index 30c1155a..e86366d8 100644 --- a/tests/ios-glanceboard.test.cjs +++ b/tests/ios-glanceboard.test.cjs @@ -146,6 +146,7 @@ function fixture() { '../native/weather': { weatherBridge: { setSessionActive() {} } }, './glance-host': { GlanceHost }, './events': events, './lock-screen': { LOCK_SCREEN_SURFACE_ID: 'lock-screen', createLockScreenImage: () => new images.GrayImage(640, 480, 123) }, + './glasses-presence': load('app/g2/glasses-presence.ts', {}), './device-addresses': { loadDeviceAddresses: () => ({ right: 'AA', left: 'BB', ring: '' }) }, './ios-peripheral-identity': { deviceAddressError: () => null }, './firmware-compat': load('app/g2/firmware-compat.ts', {}), './reconnect-policy': load('app/g2/reconnect-policy.ts', {}), '../apps/launcher': { launcherEntries: () => [] }, diff --git a/tests/tsconfig.json b/tests/tsconfig.json index cc9c2fc3..a1c2e944 100644 --- a/tests/tsconfig.json +++ b/tests/tsconfig.json @@ -47,6 +47,9 @@ "../app/apps/microphones/name-guess.ts", "../app/apps/evenhub/containers.ts", "../app/apps/evenhub/list-menu.ts", + "../app/apps/evenhub/device-status.ts", + "../app/apps/evenhub/font-spec.ts", + "../app/apps/evenhub/window-icon.ts", "../app/apps/timer/timer-model.ts", "../app/apps/teleprompter/script-tracker.ts", "../app/apps/nightscout/nightscout-alerts.ts",