Update EvenHub compatibility layer to support new functionality (context menus and some other things) from 0.0.14

This commit is contained in:
James Babcock committed 2026-08-31 23:42:22 -07:00
1 parent 216dc59255
commit 052398d401
6 files changed
+279 -12

No files matched your search

+15 -1
View File
@@ -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),
);
}
+79 -1
View File
@@ -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<string, unknown>): 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<string, unknown>): 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<string, unknown>): 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<string, unknown>): EvenHubMenuItem[] {
const items: EvenHubMenuItem[] = [];
const seen = new Set<number>();
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<string, unknown>): EvenHubImageContainer {
return {
kind: "image",
@@ -173,6 +248,9 @@ function parseListContainer(json: Record<string, unknown>): 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<string, unknown>): EvenHubPage {
const containers: EvenHubContainer[] = [];
@@ -188,7 +266,7 @@ export function parsePage(data: Record<string, unknown>): 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). */
+30 -4
View File
@@ -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) => {
+62 -5
View File
@@ -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<string, unknown>): 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<string, unknown>): 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;
}
+91
View File
@@ -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);
}
});
+2 -1
View File
@@ -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"
]
}