forked from Blendman974/faceclaw
Update EvenHub compatibility layer to support new functionality (context menus and some other things) from 0.0.14
This commit is contained in:
1 parent
216dc59255
commit
052398d401
6 files changed
+279
-12
No files matched your search
@@ -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),
|
||||
);
|
||||
}
|
||||
|
||||
|
||||
@@ -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). */
|
||||
|
||||
@@ -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) => {
|
||||
|
||||
@@ -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;
|
||||
}
|
||||
|
||||
@@ -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
@@ -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"
|
||||
]
|
||||
}
|
||||
Reference in new issue
Block a user