From 052398d401f1d64b5c35187d6cb3113a97a8c378 Mon Sep 17 00:00:00 2001 From: James Babcock Date: Mon, 31 Aug 2026 23:42:22 -0700 Subject: [PATCH] Update EvenHub compatibility layer to support new functionality (context menus and some other things) from 0.0.14 --- app/apps/evenhub/compositor.ts | 16 +++++- app/apps/evenhub/containers.ts | 80 +++++++++++++++++++++++++- app/apps/evenhub/evenhub-window.ts | 34 +++++++++-- app/apps/evenhub/session.ts | 67 ++++++++++++++++++++-- tests/evenhub-containers.test.cjs | 91 ++++++++++++++++++++++++++++++ tests/tsconfig.json | 3 +- 6 files changed, 279 insertions(+), 12 deletions(-) create mode 100644 tests/evenhub-containers.test.cjs diff --git a/app/apps/evenhub/compositor.ts b/app/apps/evenhub/compositor.ts index 60d2c706..56ab1d5e 100644 --- a/app/apps/evenhub/compositor.ts +++ b/app/apps/evenhub/compositor.ts @@ -26,9 +26,23 @@ export const EVENHUB_SCREEN_HEIGHT = 288; const TEXT_WHITE = 255; const LIST_ROW_PADDING = 4; +/** + * SDK 0.0.14 textColor levels 0..4 as grey values. Level 4 is the default and + * the only one apps got before 0.0.14, so it must stay exactly TEXT_WHITE. + * Level 0 is the firmware's "fully dim" step, which over the black page + * background means the text is effectively not shown. + */ +const TEXT_BRIGHTNESS_GREYS = [0, 64, 128, 191, 255]; + +function textGrey(level: number | undefined): number { + return level === undefined ? TEXT_WHITE : (TEXT_BRIGHTNESS_GREYS[level] ?? TEXT_WHITE); +} + /** Chars the font lacks are skipped silently on stock (no tofu); EvenHubFont * skips unknown glyphs, matching that. */ function paintTextContainer(image: GrayImage, container: EvenHubTextContainer): void { + // Only the text dims: textColor is a text-brightness level, and stock draws + // the container's border at full brightness regardless. paintBorder(image, container); const inset = container.borderWidth + container.paddingLength; EvenHubFont.get().drawTextWrapped( @@ -37,7 +51,7 @@ function paintTextContainer(image: GrayImage, container: EvenHubTextContainer): container.y + inset, Math.max(1, container.width - 2 * inset), container.content, - TEXT_WHITE, + textGrey(container.textColor), ); } diff --git a/app/apps/evenhub/containers.ts b/app/apps/evenhub/containers.ts index 95954fa6..c529290e 100644 --- a/app/apps/evenhub/containers.ts +++ b/app/apps/evenhub/containers.ts @@ -22,6 +22,8 @@ export type EvenHubTextContainer = { /** Extended-layout: inherit content from a same-named container on replace. */ preserve: boolean; content: string; + /** SDK 0.0.14 textColor: brightness level 0..4; undefined means the device default (4). */ + textColor: number | undefined; }; export type EvenHubImageContainer = { @@ -63,11 +65,31 @@ export type EvenHubListContainer = { export type EvenHubContainer = EvenHubTextContainer | EvenHubImageContainer | EvenHubListContainer; +/** One entry of the OS contextual menu an app registers via `menuObject`. */ +export type EvenHubMenuItem = { + itemName: string; + /** Non-zero uint32, unique within the menu; echoed back in menuItemClickEvent. */ + itemID: number; +}; + export type EvenHubPage = { /** In declaration order (lists, images, texts); z-sorted at paint time. */ containers: EvenHubContainer[]; + /** + * The page's contextual-menu entries (SDK 0.0.14 `menuObject`). Empty when + * the app declared none, which on rebuild is how a menu is cleared. + */ + menuItems: EvenHubMenuItem[]; }; +/** Firmware brightness levels for text; 4 is the device default. */ +const MIN_TEXT_BRIGHTNESS = 0; +const MAX_TEXT_BRIGHTNESS = 4; + +/** Firmware limits on a contextual menu, enforced app-side by the SDK too. */ +const MENU_MAX_ITEMS = 10; +const MENU_NAME_MAX_BYTES = 32; + function normalizeKey(key: string): string { return key.replace(/_/g, "").toLowerCase(); } @@ -123,9 +145,62 @@ function parseTextContainer(json: Record): EvenHubTextContainer zOrderIndex: readOptionalNumber(json, "zOrderIndex"), preserve: readNumber(json, "preserve", 0) !== 0, content: readString(json, "content", ""), + textColor: readTextBrightness(json), }; } +/** + * A text container's brightness level, or undefined for the device default. + * Out-of-range values are dropped rather than clamped: the SDK rejects the + * whole call for them, so an app that sends one is already misbehaving and + * the default level is the least surprising thing to draw. + */ +export function readTextBrightness(json: Record): number | undefined { + const value = readOptionalNumber(json, "textColor"); + if (value === undefined || !Number.isInteger(value)) return undefined; + if (value < MIN_TEXT_BRIGHTNESS || value > MAX_TEXT_BRIGHTNESS) return undefined; + return value; +} + +/** The raw `menuObject.menuItems` array as sent, before any rule is applied. */ +export function declaredMenuItems(data: Record): unknown[] { + const raw = pickLoose(asRecord(pickLoose(data, "menuObject")), "menuItems"); + return Array.isArray(raw) ? raw : []; +} + +function utf8ByteLength(value: string): number { + let bytes = 0; + for (const char of value) { + const code = char.codePointAt(0) ?? 0; + bytes += code < 0x80 ? 1 : code < 0x800 ? 2 : code < 0x10000 ? 3 : 4; + } + return bytes; +} + +/** + * Parse `menuObject.menuItems`. The SDK validates these app-side and refuses + * to call the host at all on a violation, so anything invalid arriving here + * came from an app bypassing the SDK; drop the offending entries (and any + * past the tenth) rather than rejecting the whole page, which would leave the + * app with no UI at all. + */ +export function parseMenuItems(data: Record): EvenHubMenuItem[] { + const items: EvenHubMenuItem[] = []; + const seen = new Set(); + for (const entry of declaredMenuItems(data)) { + if (items.length >= MENU_MAX_ITEMS) break; + const json = asRecord(entry); + const itemID = readNumber(json, "itemID", 0); + if (!Number.isInteger(itemID) || itemID <= 0 || itemID > 0xffffffff) continue; + if (seen.has(itemID)) continue; + const itemName = readString(json, "itemName", ""); + if (utf8ByteLength(itemName) > MENU_NAME_MAX_BYTES) continue; + seen.add(itemID); + items.push({ itemName, itemID }); + } + return items; +} + function parseImageContainer(json: Record): EvenHubImageContainer { return { kind: "image", @@ -173,6 +248,9 @@ function parseListContainer(json: Record): EvenHubListContainer * page. Containers keep declaration order within and across the three arrays * (lists, then images, then texts — texts last so info panels and capture * containers sit above image tiles when no zOrderIndex is given). + * + * The whole page is replaced on rebuild, which is also what gives an omitted + * menuObject its documented meaning: the previous contextual menu goes away. */ export function parsePage(data: Record): EvenHubPage { const containers: EvenHubContainer[] = []; @@ -188,7 +266,7 @@ export function parsePage(data: Record): EvenHubPage { if (Array.isArray(texts)) { for (const item of texts) containers.push(parseTextContainer(asRecord(item))); } - return { containers }; + return { containers, menuItems: parseMenuItems(data) }; } /** The container that owns gesture events (exactly one per valid page). */ diff --git a/app/apps/evenhub/evenhub-window.ts b/app/apps/evenhub/evenhub-window.ts index 8ca31823..23a9e669 100644 --- a/app/apps/evenhub/evenhub-window.ts +++ b/app/apps/evenhub/evenhub-window.ts @@ -37,7 +37,8 @@ class EvenHubAppLayer implements Layer { handleInput(event: InputEvent): void { // Everything goes to the app; long-press never reaches here (the window // menu intercepts it), which is the guaranteed way out since EvenHub - // apps own double-click. + // apps own double-click. The press is still reported to the app as + // LONG_PRESS_EVENT — see the handleInput wrapper below. this.session.handleGesture(event); } } @@ -61,9 +62,22 @@ export function createEvenHubWindow( fallbackIcon, ), heightMode: "medium", - // Glasses-first: the app runs without the phone showing it; this reveals - // its phone UI (config pages, etc.) over the dashboard on demand. - menuItems: () => [{ label: "Show phone UI", onSelect: (ctx) => { ctx.stack.pop(); onShowPhone(); } }], + // The window's long-press 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 + // changes or clears the menu is reflected on the next press. + menuItems: () => [ + ...session.contextMenuItems().map((item) => ({ + label: item.itemName, + onSelect: (ctx: LayerContext) => { + ctx.stack.pop(); + session.selectContextMenuItem(item.itemID); + }, + })), + // Glasses-first: the app runs without the phone showing it; this reveals + // its phone UI (config pages, etc.) over the dashboard on demand. + { label: "Show phone UI", onSelect: (ctx: LayerContext) => { ctx.stack.pop(); onShowPhone(); } }, + ], actions: options.actions, baseLayer: new EvenHubAppLayer(session), submitFrame: options.submitFrame, @@ -87,6 +101,18 @@ export function createEvenHubWindow( windowId, }); + // LONG_PRESS_EVENT / LONG_PRESS_RELEASE_EVENT (SDK 0.0.14). Wrapped at the + // window rather than handled in the base layer because the press opens the + // window menu and so never reaches a layer, and because the release lands on + // that menu once it is up. + const baseHandleInput = created.window.handleInput; + created.window.handleInput = async (event, frameId) => { + if (event.type === "long-press" || event.type === "long-press-release") { + session.handleGesture(event); + } + await baseHandleInput(event, frameId); + }; + // FOREGROUND_ENTER/EXIT for the app on shell focus changes. const baseSetForeground = created.window.setForeground; created.window.setForeground = (foreground) => { diff --git a/app/apps/evenhub/session.ts b/app/apps/evenhub/session.ts index 739a920f..2297d3c8 100644 --- a/app/apps/evenhub/session.ts +++ b/app/apps/evenhub/session.ts @@ -38,14 +38,17 @@ import { import { EvenHubApiKeyDialogLayer } from "./api-key-dialog"; import { asRecord, + declaredMenuItems, eventCaptureContainer, parsePage, readNumber, readOptionalNumber, readString, + readTextBrightness, type EvenHubImageContainer, type EvenHubListContainer, type EvenHubContainer, + type EvenHubMenuItem, type EvenHubPage, } from "./containers"; import { compositePage } from "./compositor"; @@ -73,6 +76,9 @@ const FOREGROUND_ENTER_EVENT = 4; const FOREGROUND_EXIT_EVENT = 5; const SYSTEM_EXIT_EVENT = 7; const IMU_DATA_REPORT_EVENT = 8; +/** SDK 0.0.14: the press gesture, delivered like any other list/text/sys event. */ +const LONG_PRESS_EVENT = 9; +const LONG_PRESS_RELEASE_EVENT = 10; /** * Injected into every served HTML document at document start (before any app @@ -440,6 +446,21 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenH case "double-click": this.emitSysEvent(DOUBLE_CLICK_EVENT, gestureSource(event.source)); break; + case "long-press": + case "long-press-release": { + // SDK 0.0.14 exposes press and release as ordinary events. The window + // still opens its menu on the same gesture (that menu is where the + // app's contextual-menu items live, and it is the way out of an app + // that owns double-click), so an app hears the press as well as + // seeing the menu — it cannot be given exclusive use of the gesture. + const eventType = event.type === "long-press" ? LONG_PRESS_EVENT : LONG_PRESS_RELEASE_EVENT; + if (capture?.kind === "list") { + this.emitListEvent(capture, eventType); + } else { + this.emitSysEvent(eventType, gestureSource(event.source)); + } + break; + } case "scroll-up": case "scroll-down": { const eventType = event.type === "scroll-up" ? SCROLL_TOP_EVENT : SCROLL_BOTTOM_EVENT; @@ -455,6 +476,20 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenH } } + /** + * The contextual-menu entries the running page registered (SDK 0.0.14 + * `menuObject`), for the window to merge into its own menu. Empty when the + * app declared none. + */ + contextMenuItems(): EvenHubMenuItem[] { + return this.page?.menuItems ?? []; + } + + /** The user picked one of the app's contextual-menu entries. */ + selectContextMenuItem(itemID: number): void { + this.pushMessage("evenHubEvent", { type: "menuItemClickEvent", jsonData: { itemID } }); + } + private scrollList(list: EvenHubListContainer, eventType: number): void { // Swipe up selects the previous item, swipe down the next (stock direction). const delta = eventType === SCROLL_TOP_EVENT ? -1 : 1; @@ -542,10 +577,21 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenH return this.screenOn; } - /** A decoded mic frame from the router: hand it to the app as an audioEvent. */ + /** + * A decoded mic frame from the router: hand it to the app as an audioEvent. + * + * SDK 0.0.14 added per-frame `direction` and `speakerRole`. Neither is + * available here — the router hands over plain PCM with no beamforming tag, + * and speakerRole is an app-level diarization result the stock host computes + * — so both are sent as the fallbacks the SDK documents for a phone mic and + * for older hosts. + */ deliverAudioPcm(pcm: Uint8Array): void { const audioPcm = Array.from(pcm); - this.pushMessage("evenHubEvent", { type: "audioEvent", jsonData: { audioPcm } }); + this.pushMessage("evenHubEvent", { + type: "audioEvent", + jsonData: { audioPcm, direction: null, speakerRole: "unknown" }, + }); } /** @@ -757,7 +803,7 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenH return 1; } const page = parsePage(data); - this.warnOnInvalidPage(page); + this.warnOnInvalidPage(page, data); this.page = page; this.pageCreated = true; // The launch focus arrived before the page existed; deliver the ENTER now. @@ -772,14 +818,21 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenH private rebuildPage(data: Record): boolean { // Also serves as create for apps that fall back to rebuild-on-error. const page = parsePage(data); - this.warnOnInvalidPage(page); + this.warnOnInvalidPage(page, data); this.page = page; this.pageCreated = true; this.windowHooks?.requestRender(); return true; } - private warnOnInvalidPage(page: EvenHubPage): void { + private warnOnInvalidPage(page: EvenHubPage, data: Record): void { + const declaredMenuCount = declaredMenuItems(data).length; + if (declaredMenuCount > page.menuItems.length) { + this.log( + `evenhub: dropped ${declaredMenuCount - page.menuItems.length} of ${declaredMenuCount} contextual menu ` + + "items (max 10, itemID must be non-zero and unique, itemName at most 32 UTF-8 bytes)", + ); + } // Stock rejects these outright; we accept-and-log until rejection is // proven necessary for compatibility. const captures = page.containers.filter((c) => c.kind !== "image" && c.isEventCapture).length; @@ -813,6 +866,10 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenH } else { container.content = content; } + // SDK 0.0.14: textColor on an incremental update sets the container's + // brightness; omitting it keeps whatever level the container has. + const brightness = readTextBrightness(data); + if (brightness !== undefined) container.textColor = brightness; this.windowHooks?.requestRender(); return true; } diff --git a/tests/evenhub-containers.test.cjs b/tests/evenhub-containers.test.cjs new file mode 100644 index 00000000..366ee7f1 --- /dev/null +++ b/tests/evenhub-containers.test.cjs @@ -0,0 +1,91 @@ +// The SDK 0.0.14 additions to the page-container payload: the contextual menu +// (`menuObject`) and text brightness (`textColor`). +// +// The payloads here were captured by running the real @evenrealities/ +// even_hub_sdk 0.0.14 against a stub `flutter_inappwebview.callHandler` and +// recording what it sent, so they are the literal wire shapes, not a reading +// of the docs. The rules the parser enforces are the ones the SDK enforces +// app-side before it will call the host at all. +const test = require("node:test"); +const assert = require("node:assert/strict"); + +const { parsePage, declaredMenuItems } = require("../.test-build/app/apps/evenhub/containers.js"); + +const menuItem = (itemID, itemName) => ({ itemName, itemID }); + +test("a menuObject becomes the page's contextual menu", () => { + const page = parsePage({ + containerTotalNum: 1, + textObject: [{ containerID: 1, containerName: "main", content: "hi" }], + menuObject: { menuItems: [menuItem(1, "Pause"), menuItem(2, "Resume")] }, + }); + assert.deepEqual(page.menuItems, [ + { itemName: "Pause", itemID: 1 }, + { itemName: "Resume", itemID: 2 }, + ]); +}); + +test("a page with no menuObject has no menu, which is how rebuild clears one", () => { + const page = parsePage({ textObject: [{ containerID: 1, containerName: "main" }] }); + assert.deepEqual(page.menuItems, []); +}); + +test("protobuf-style menu keys parse the same as camelCase", () => { + const page = parsePage({ Menu_Object: { Menu_Items: [{ Item_Name: "Go", Item_ID: 3 }] } }); + assert.deepEqual(page.menuItems, [{ itemName: "Go", itemID: 3 }]); +}); + +test("menu entries the firmware cannot represent are dropped, not the whole page", () => { + const page = parsePage({ + textObject: [{ containerID: 1, containerName: "main", content: "kept" }], + menuObject: { + menuItems: [ + menuItem(0, "zero id"), + menuItem(1, "ok"), + menuItem(1, "duplicate id"), + menuItem(2, "x".repeat(33)), + menuItem(3, "x".repeat(32)), + ], + }, + }); + assert.deepEqual(page.menuItems, [ + { itemName: "ok", itemID: 1 }, + { itemName: "x".repeat(32), itemID: 3 }, + ]); + assert.equal(page.containers.length, 1, "an invalid menu must not cost the app its containers"); +}); + +test("itemName is measured in UTF-8 bytes, not characters", () => { + // 11 three-byte characters is 33 bytes: over the limit despite being short. + const overLimit = "あ".repeat(11); + const atLimit = "あ".repeat(10); // 30 bytes + const page = parsePage({ menuObject: { menuItems: [menuItem(1, overLimit), menuItem(2, atLimit)] } }); + assert.deepEqual(page.menuItems, [{ itemName: atLimit, itemID: 2 }]); +}); + +test("a menu is capped at the firmware's ten entries", () => { + const menuItems = Array.from({ length: 12 }, (_, i) => menuItem(i + 1, `item ${i + 1}`)); + const page = parsePage({ menuObject: { menuItems } }); + assert.equal(page.menuItems.length, 10); + assert.equal(page.menuItems[9].itemID, 10); + assert.equal(declaredMenuItems({ menuObject: { menuItems } }).length, 12, "the raw count drives the dropped-items log"); +}); + +test("textColor carries brightness levels 0 through 4", () => { + for (const level of [0, 1, 2, 3, 4]) { + const page = parsePage({ textObject: [{ containerID: 1, containerName: "t", textColor: level }] }); + assert.equal(page.containers[0].textColor, level); + } +}); + +test("an omitted or out-of-range textColor falls back to the device default", () => { + for (const textObject of [ + [{ containerID: 1, containerName: "t" }], + [{ containerID: 1, containerName: "t", textColor: 5 }], + [{ containerID: 1, containerName: "t", textColor: -1 }], + [{ containerID: 1, containerName: "t", textColor: 2.5 }], + ]) { + const page = parsePage({ textObject }); + assert.equal(page.containers[0].textColor, undefined); + } +}); diff --git a/tests/tsconfig.json b/tests/tsconfig.json index e554b339..e4afb253 100644 --- a/tests/tsconfig.json +++ b/tests/tsconfig.json @@ -23,6 +23,7 @@ "../app/apps/microphones/sentiment.ts", "../app/apps/microphones/dsp.ts", "../app/apps/microphones/radar-dots.ts", - "../app/apps/microphones/name-guess.ts" + "../app/apps/microphones/name-guess.ts", + "../app/apps/evenhub/containers.ts" ] }