mirror of
https://git.undefined-dev.fr/Blendman974/faceclaw.git
synced 2026-11-19 21:03:09 +00:00
1830 lines
72 KiB
TypeScript
1830 lines
72 KiB
TypeScript
/**
|
|
* One running EvenHub app: the host side of the SDK's
|
|
* flutter_inappwebview.callHandler('evenAppMessage', ...) contract, the page
|
|
* container state, and the glue between the phone WebView and the glasses
|
|
* window. Wire shapes were captured empirically from even_hub_sdk 0.0.12
|
|
* (see notes/evenhub_compatibility.txt).
|
|
*
|
|
* Wire contract summary:
|
|
* - Web -> host: callHandler('evenAppMessage', '<json>') where the JSON is
|
|
* {type: "call_even_app_method", method, data?}. The handler's return
|
|
* value resolves the app-side promise (no response postMessage).
|
|
* - Host -> web: call window._listenEvenAppMessage({type:
|
|
* "listen_even_app_data", method, data}); for method "evenHubEvent", data
|
|
* is {type: "sysEvent"|"textEvent"|"listEvent", jsonData: {...}}.
|
|
* - Return values: createStartUpPageContainer -> int 0..3;
|
|
* updateImageRawData -> int 0..3 or enum string; rebuild/textUpgrade/
|
|
* shutDown/setLocalStorage -> boolean; getLocalStorage -> string;
|
|
* getUserInfo/getGlassesInfo -> plain JSON objects (not strings).
|
|
*/
|
|
import { ApplicationSettings } from "@nativescript/core";
|
|
import { GrayImage } from "../../graphics/image";
|
|
import { EvenHubFont } from "../../graphics/evenhub-font";
|
|
import { type InputEvent, type InputSource } from "../../ui/gestures";
|
|
import { type Layer } from "../../ui/layers";
|
|
import {
|
|
anthropicApiKeySetting,
|
|
elevenLabsApiKeySetting,
|
|
mapboxApiKeySetting,
|
|
openAiApiKeySetting,
|
|
sonioxApiKeySetting,
|
|
} from "../../ui/dashboard-settings";
|
|
import {
|
|
buildSoundSequencePayload,
|
|
phraseDurationMs,
|
|
CFW_SEQ_MAX,
|
|
type Step,
|
|
} from "../../ui/sound-effects";
|
|
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";
|
|
import { describeImageUpdate, describePage, describeTextUpgrade } from "./layout-debug";
|
|
import { stepListSelection } from "./list-menu";
|
|
import { type EvenHubManifest } from "./ehpk";
|
|
import { permissionsIncludeMicrophone, permissionsInclude } from "./permissions";
|
|
import { evenHubMicRouter, type EvenHubMicClient } from "./mic-router";
|
|
import { evenHubImuRouter, type EvenHubImuClient } from "./imu-router";
|
|
import { evenHubCompassRouter, type EvenHubCompassClient, type EvenHubCompassReading } from "./compass-router";
|
|
import { type ImuReading } from "../../native/imu";
|
|
import { toolRegistry, type ToolResult, type ToolSpec } from "../../assistant/tool-registry";
|
|
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");
|
|
|
|
/**
|
|
* Page layouts and container updates go to logcat at debug level (see
|
|
* layout-debug.ts): `adb logcat -s FaceclawEvenHubLayout:D`. Android only.
|
|
*/
|
|
const LAYOUT_LOG_TAG = "FaceclawEvenHubLayout";
|
|
const LAYOUT_LOG_ENABLED = !!global.isAndroid;
|
|
/** Logcat truncates entries around 4 KB; split longer lines below that. */
|
|
const LOGCAT_CHUNK_CHARS = 3000;
|
|
|
|
/** OsEventTypeList values (PB ordinals). */
|
|
const CLICK_EVENT = 0;
|
|
const SCROLL_TOP_EVENT = 1;
|
|
const SCROLL_BOTTOM_EVENT = 2;
|
|
const DOUBLE_CLICK_EVENT = 3;
|
|
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
|
|
* JS): (1) the promise-returning flutter_inappwebview.callHandler the EvenHub
|
|
* SDK expects, backed by the FaceclawEvenHubJsBridge Java object; and (2) a
|
|
* host-driven setTimeout/setInterval/requestAnimationFrame replacement that
|
|
* survives the screen-off throttle (fired by the native ticker in
|
|
* FaceclawEvenHubWebViewHost). Kept in ES5 so it runs on any webview.
|
|
*/
|
|
export const EVENHUB_BRIDGE_INJECT_SCRIPT = `
|
|
(function () {
|
|
if (window.flutter_inappwebview && window.flutter_inappwebview.callHandler) return;
|
|
var pending = {};
|
|
var nextId = 1;
|
|
window.__fcResolve = function (id, ok, value) {
|
|
var entry = pending[id];
|
|
if (!entry) return;
|
|
delete pending[id];
|
|
(ok ? entry[0] : entry[1])(value);
|
|
};
|
|
window.flutter_inappwebview = {
|
|
callHandler: function (name) {
|
|
var args = Array.prototype.slice.call(arguments, 1);
|
|
return new Promise(function (resolve, reject) {
|
|
var id = nextId++;
|
|
pending[id] = [resolve, reject];
|
|
window.__faceclawEvenHub.postMessage(String(name), JSON.stringify(args), id);
|
|
});
|
|
}
|
|
};
|
|
})();
|
|
(function () {
|
|
// Host-driven timers and requestAnimationFrame. Chromium heavily throttles a
|
|
// page's own setTimeout/setInterval when the phone screen is off, and pauses
|
|
// or throttles a hidden page's rAF, which slows timer-driven apps to a crawl
|
|
// and stalls canvas apps that render on a rAF loop. Replace them with queues
|
|
// fired by window.__fcTick(), which the native host calls regardless of
|
|
// screen state (host-initiated evaluateJavascript escapes the throttle).
|
|
// (The glasses render via BLE, not the phone's display, so vsync alignment
|
|
// doesn't matter — a steady frame rate does.)
|
|
//
|
|
// __fcTick returns how many ms until it next has work (-1: none), and the
|
|
// host sleeps until then instead of evaluating JS at 60Hz for an idle page.
|
|
// Work added outside a tick that is due before the host's next tick wakes it
|
|
// through the bridge.
|
|
if (window.__fcTick) return;
|
|
var FRAME_MS = 16;
|
|
var timers = new Map();
|
|
var nextId = 1;
|
|
var rafs = new Map();
|
|
var nextRafId = 1;
|
|
var inTick = false;
|
|
// When the host will next call __fcTick; Infinity while it is idle.
|
|
var hostNextTickAt = Infinity;
|
|
function needTickBy(due) {
|
|
if (inTick || due >= hostNextTickAt) return;
|
|
hostNextTickAt = Date.now();
|
|
var bridge = window.__faceclawEvenHub;
|
|
if (bridge && bridge.wakeTimers) bridge.wakeTimers();
|
|
}
|
|
window.setTimeout = function (cb, delay) {
|
|
var args = Array.prototype.slice.call(arguments, 2);
|
|
var id = nextId++;
|
|
var due = Date.now() + (+delay || 0);
|
|
timers.set(id, { cb: cb, args: args, due: due, interval: 0 });
|
|
needTickBy(due);
|
|
return id;
|
|
};
|
|
window.setInterval = function (cb, delay) {
|
|
var args = Array.prototype.slice.call(arguments, 2);
|
|
var id = nextId++;
|
|
var d = +delay || 0;
|
|
var due = Date.now() + d;
|
|
timers.set(id, { cb: cb, args: args, due: due, interval: d });
|
|
needTickBy(due);
|
|
return id;
|
|
};
|
|
window.clearTimeout = function (id) { timers.delete(id); };
|
|
window.clearInterval = function (id) { timers.delete(id); };
|
|
window.requestAnimationFrame = function (cb) {
|
|
var id = nextRafId++;
|
|
rafs.set(id, cb);
|
|
needTickBy(Date.now() + FRAME_MS);
|
|
return id;
|
|
};
|
|
window.cancelAnimationFrame = function (id) { rafs.delete(id); };
|
|
function runTimers() {
|
|
var now = Date.now();
|
|
var dueIds = [];
|
|
timers.forEach(function (entry, id) { if (entry.due <= now) dueIds.push(id); });
|
|
dueIds.sort(function (a, b) { return timers.get(a).due - timers.get(b).due; });
|
|
for (var i = 0; i < dueIds.length; i++) {
|
|
var entry = timers.get(dueIds[i]);
|
|
if (!entry) continue; // cleared by an earlier callback this tick
|
|
if (entry.interval > 0) {
|
|
// Advance one period (keeps cadence); if we've fallen behind, skip the
|
|
// missed periods rather than fast-forwarding a burst of catch-up fires.
|
|
entry.due += entry.interval;
|
|
if (entry.due <= now) entry.due = now + entry.interval;
|
|
} else {
|
|
timers.delete(dueIds[i]);
|
|
}
|
|
try { entry.cb.apply(null, entry.args); } catch (e) { if (window.console) console.error(e); }
|
|
}
|
|
}
|
|
function runRafs() {
|
|
if (rafs.size === 0) return;
|
|
var ts = window.performance && performance.now ? performance.now() : Date.now();
|
|
// Snapshot and clear: callbacks that re-request during this frame run on
|
|
// the NEXT frame, matching rAF semantics (so a loop doesn't spin forever).
|
|
var current = rafs;
|
|
rafs = new Map();
|
|
current.forEach(function (cb) {
|
|
try { cb(ts); } catch (e) { if (window.console) console.error(e); }
|
|
});
|
|
}
|
|
function inTickDo(fn) {
|
|
inTick = true;
|
|
try { fn(); } finally { inTick = false; }
|
|
}
|
|
// Fixed-rate entry points for hosts that don't use __fcTick's schedule (the
|
|
// iOS host calls both every frame).
|
|
window.__fcTimerTick = function () { inTickDo(runTimers); };
|
|
window.__fcRafTick = function () { inTickDo(runRafs); };
|
|
window.__fcTick = function () {
|
|
inTick = true;
|
|
try {
|
|
runTimers();
|
|
runRafs();
|
|
} finally {
|
|
inTick = false;
|
|
}
|
|
var now = Date.now();
|
|
var delay = rafs.size ? FRAME_MS : -1;
|
|
timers.forEach(function (entry) {
|
|
var d = entry.due - now;
|
|
if (delay < 0 || d < delay) delay = d;
|
|
});
|
|
if (delay >= 0) delay = Math.max(FRAME_MS, Math.ceil(delay));
|
|
hostNextTickAt = delay < 0 ? Infinity : now + delay;
|
|
return delay;
|
|
};
|
|
})();
|
|
`;
|
|
|
|
/**
|
|
* Injected at document-start (after the stock bridge shim): defines
|
|
* `window.getFaceclawExtensions`, the single entry point for Faceclaw-only
|
|
* capabilities. Its public contract (the `FaceclawExtensions` interface) is
|
|
* the @faceclaw/evenhub-extensions package in evenhub-extensions/. Keep the
|
|
* two in step (tests/evenhub-extensions-shim.test.cjs checks the member list).
|
|
* When adding members, bump API_VERSION and tag them `@since apiVersion N` in
|
|
* the package.
|
|
*
|
|
* It never touches the standard SDK or any prototype — everything lives behind
|
|
* this one global, so apps stay compatible with the stock Even app (where the
|
|
* global is absent).
|
|
*
|
|
* RPC uses its own id-keyed promise map and `__fcExtResolve`, kept separate
|
|
* from the stock `__fcResolve` channel. Events arrive via `__fcExtEvent`.
|
|
* `<VERSION>` is interpolated by buildFaceclawExtensionsScript at load.
|
|
*/
|
|
export function buildFaceclawExtensionsScript(versionString: string): string {
|
|
return `
|
|
(function () {
|
|
if (window.getFaceclawExtensions) return;
|
|
var VERSION = ${JSON.stringify(versionString)};
|
|
var API_VERSION = 1;
|
|
var pending = {};
|
|
var nextId = 1;
|
|
window.__fcExtResolve = function (id, ok, value) {
|
|
var entry = pending[id];
|
|
if (!entry) return;
|
|
delete pending[id];
|
|
if (ok) entry[0](value);
|
|
else entry[1](new Error(String(value)));
|
|
};
|
|
function call(method, params) {
|
|
return new Promise(function (resolve, reject) {
|
|
var id = nextId++;
|
|
pending[id] = [resolve, reject];
|
|
window.__faceclawEvenHub.postMessage("faceclawExt", JSON.stringify([method].concat(params || [])), id);
|
|
});
|
|
}
|
|
function send(method, params) {
|
|
// Fire-and-forget: id 0 tells the host no response is expected.
|
|
window.__faceclawEvenHub.postMessage("faceclawExt", JSON.stringify([method].concat(params || [])), 0);
|
|
}
|
|
var listeners = {};
|
|
window.__fcExtEvent = function (name, data) {
|
|
// Iterate a snapshot, so a listener that unsubscribes mid-dispatch
|
|
// doesn't make the next one get skipped.
|
|
var arr = (listeners[name] || []).slice();
|
|
for (var i = 0; i < arr.length; i++) {
|
|
try { arr[i](data); } catch (e) { if (window.console) console.error(e); }
|
|
}
|
|
};
|
|
function on(name, cb) {
|
|
(listeners[name] || (listeners[name] = [])).push(cb);
|
|
return function () {
|
|
var arr = listeners[name];
|
|
if (!arr) return;
|
|
var i = arr.indexOf(cb);
|
|
if (i >= 0) arr.splice(i, 1);
|
|
};
|
|
}
|
|
// 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 = {};
|
|
window.__fcExtInvokeTool = function (id, name, args) {
|
|
var handler = toolHandlers[name];
|
|
function reply(ok, value) {
|
|
window.__faceclawEvenHub.postMessage("faceclawExtToolResult", JSON.stringify([id, ok, value]), 0);
|
|
}
|
|
if (!handler) { reply(false, "unknown tool " + name); return; }
|
|
Promise.resolve().then(function () { return handler(args); }).then(
|
|
function (res) { reply(true, res == null ? "" : res); },
|
|
function (err) { reply(false, String((err && err.message) || err)); }
|
|
);
|
|
};
|
|
function setAssistantTools(tools) {
|
|
toolHandlers = {};
|
|
var specs = [];
|
|
(tools || []).forEach(function (t) {
|
|
if (!t || !t.name || typeof t.handler !== "function") return;
|
|
toolHandlers[t.name] = t.handler;
|
|
specs.push({
|
|
name: t.name,
|
|
description: t.description || "",
|
|
parameters: t.parameters || { type: "object", properties: {} },
|
|
availability: t.availability === "open" ? "open" : "foreground"
|
|
});
|
|
});
|
|
send("setAssistantTools", [specs]);
|
|
}
|
|
var extensions = {
|
|
apiVersion: API_VERSION,
|
|
getVersion: function () { return VERSION; },
|
|
returnToAppSwitcher: function () { send("returnToAppSwitcher"); },
|
|
quit: function () { send("quit"); },
|
|
addWindowLifecycleListener: function (cb) { return on("windowLifecycle", cb); },
|
|
getConfiguredApiKeys: function () { return call("getConfiguredApiKeys"); },
|
|
requestApiKeyAccess: function (services) { return call("requestApiKeyAccess", [services || []]); },
|
|
playBuzzer: function (steps) { return call("playBuzzer", [steps || []]); },
|
|
addCompassListener: counted("compass", "setCompass"),
|
|
createLayout: function (layout) { return call("createLayout", [layout || {}]); },
|
|
replaceLayout: function (layout) { return call("replaceLayout", [layout || {}]); },
|
|
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; };
|
|
})();
|
|
`;
|
|
}
|
|
|
|
/** Stock blocks a repeated createStartUpPageContainer ~2s before failing it. */
|
|
const DUPLICATE_CREATE_DELAY_MS = 2000;
|
|
|
|
export type EvenHubWebViewHandle = {
|
|
/** Run JS inside the app's WebView (must be called on the main thread). */
|
|
evaluateJs: (js: string) => void;
|
|
/** Detach and destroy the WebView (the app is closing). */
|
|
destroy: () => void;
|
|
};
|
|
|
|
export type EvenHubWindowHooks = {
|
|
requestRender: () => void;
|
|
closeWindow: () => void;
|
|
/** Hand focus to the app switcher (used to decline an app's quit request). */
|
|
focusSwitcher: () => void;
|
|
/** Push a modal overlay layer onto the app window (e.g. a consent prompt). */
|
|
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;
|
|
};
|
|
|
|
export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenHubCompassClient {
|
|
readonly manifest: EvenHubManifest;
|
|
readonly distDir: string;
|
|
/**
|
|
* For a developer-loaded app served from a live web server: the absolute
|
|
* URL to open. Empty for a packaged app, which is served offline out of
|
|
* distDir instead (see webview.ts).
|
|
*/
|
|
readonly remoteUrl: string;
|
|
|
|
private page: EvenHubPage | null = null;
|
|
private pageCreated = false;
|
|
private webViewHandle: EvenHubWebViewHandle | null = null;
|
|
private windowHooks: EvenHubWindowHooks | null = null;
|
|
private closed = false;
|
|
private launchContextPushed = false;
|
|
private loadError = '';
|
|
private systemExitSent = false;
|
|
/** The one-shot launch FOREGROUND_ENTER has been delivered (page exists). */
|
|
private launchEnterSent = false;
|
|
/** Shell focus state; true from launch (apps open focused). */
|
|
private foreground = true;
|
|
/** Phone screen state; the mic goes silent while the screen is off. */
|
|
private screenOn = true;
|
|
/** The app has enabled its microphone via audioControl(true). */
|
|
private micRequested = false;
|
|
/** The app has enabled the accelerometer via imuControl(true). */
|
|
private imuRequested = false;
|
|
/** The app has activated the compass (extension addCompassListener). */
|
|
private compassRequested = false;
|
|
/** Non-null while the app has an active location subscription. */
|
|
private locationTracker: LocationTracker | null = null;
|
|
/** The shell window id, for tool registration (falls back to packageId). */
|
|
private shellWindowId = "";
|
|
/** Whether this app has contributed assistant tools (for cleanup). */
|
|
private hasAppTools = false;
|
|
/** Pending host→app tool invocations, keyed by call id. */
|
|
private readonly pendingToolCalls = new Map<number, (result: ToolResult) => void>();
|
|
private nextToolCallId = 1;
|
|
// Window-lifecycle tracking for the extension API (apps launch visible+focused).
|
|
private lastVisible = true;
|
|
private lastFocused = true;
|
|
/** Shell input focus on this window, sampled during paint. */
|
|
private shellFocused = true;
|
|
/** API-key services the user has granted this app this session. */
|
|
private readonly grantedApiKeys = new Set<string>();
|
|
/** The app listens for touch-down (extension addTouchDownListener). */
|
|
private touchDownRequested = false;
|
|
/** The app listens for text input, so the shell offers it as a Type Into App destination. */
|
|
private textInputRequested = false;
|
|
/** The app asked for the attention dot on its switcher icon. */
|
|
private attention = false;
|
|
/** The app asked the idle screen timeout to wait while it is in the foreground. */
|
|
private keepScreenOnRequested = false;
|
|
/** The app's own switcher icon; null draws the package icon. */
|
|
private windowIcon: WindowIconRenderer | null = null;
|
|
/** The paired glasses' serial, read once so getGlassesInfo and every status push agree. */
|
|
private glassesSerial: string | null | undefined = undefined;
|
|
/** The last deviceStatusChanged sent, and the subscriptions that refresh it. */
|
|
private lastDeviceStatus: EvenHubDeviceStatus | null = null;
|
|
private readonly deviceStatusOffs: (() => void)[] = [];
|
|
private log: (message: string) => void;
|
|
|
|
constructor(
|
|
manifest: EvenHubManifest,
|
|
distDir: string,
|
|
log: (message: string) => void,
|
|
remoteUrl = "",
|
|
private readonly sendBuzzerSequence: (payload: Uint8Array) => Promise<void> | void = () => {},
|
|
private readonly deviceStatusSource: EvenHubDeviceStatusSource = OFFLINE_DEVICE_STATUS_SOURCE,
|
|
) {
|
|
this.manifest = manifest;
|
|
this.distDir = distDir;
|
|
this.remoteUrl = remoteUrl;
|
|
this.log = log;
|
|
}
|
|
|
|
// ----- webview wiring -----
|
|
|
|
attachWebView(handle: EvenHubWebViewHandle): void {
|
|
this.webViewHandle = handle;
|
|
}
|
|
|
|
/**
|
|
* A WebView load failed. Once the app has loaded, a failed or blocked
|
|
* navigation leaves its page running, so only a failure before then (or one
|
|
* the host marks `fatal`) replaces the glasses window with the error.
|
|
*/
|
|
webViewFailed(message: string, fatal = false): void {
|
|
if (this.closed) return;
|
|
this.log(`evenhub: ${message}`);
|
|
if (this.launchContextPushed && !fatal) return;
|
|
this.loadError = message; this.windowHooks?.requestRender();
|
|
}
|
|
|
|
/** The WebView finished loading the app: push the one-shot launch context. */
|
|
webViewLoaded(): void {
|
|
if (this.loadError) { this.loadError = ''; this.windowHooks?.requestRender(); }
|
|
if (this.launchContextPushed) return;
|
|
this.launchContextPushed = true;
|
|
// 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.pushDeviceStatus();
|
|
this.deviceStatusOffs.push(this.deviceStatusSource.subscribe(() => this.pushDeviceStatus()));
|
|
}
|
|
|
|
// ----- glasses window wiring -----
|
|
|
|
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 {
|
|
this.windowHooks = null;
|
|
this.close();
|
|
}
|
|
|
|
paint(size: { width: number; height: number }, focused: boolean): GrayImage {
|
|
// Focus changes always trigger a repaint of the foreground window, so paint
|
|
// is a reliable place to sample shell input-focus for lifecycle events.
|
|
this.updateShellFocus(focused);
|
|
if (this.loadError || !this.pageCreated || !this.page) {
|
|
const image = new GrayImage(size.width, size.height, 0);
|
|
const font = EvenHubFont.get();
|
|
font.drawText(image, 16, 16, `${this.loadError ? 'Could not run' : 'Loading'} ${this.manifest.name}...`, 255);
|
|
font.drawTextWrapped(image, 16, 16 + 2 * font.lineHeight, Math.max(1, size.width - 32),
|
|
this.loadError || "(waiting for the app to build its page)", 120);
|
|
return image;
|
|
}
|
|
return compositePage(this.page, size, focused);
|
|
}
|
|
|
|
/**
|
|
* Route a gesture to the app, emulating stock hardware: clicks and
|
|
* double-clicks arrive as sysEvent (never textEvent) with zero-valued
|
|
* fields elided the way protobuf JSON elides them; list selection moves
|
|
* 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 = 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, inputSource);
|
|
} else {
|
|
this.emitSysEvent(CLICK_EVENT, gestureSource(event.source), inputSource);
|
|
}
|
|
break;
|
|
case "double-click":
|
|
this.emitSysEvent(DOUBLE_CLICK_EVENT, gestureSource(event.source), inputSource);
|
|
break;
|
|
case "long-press":
|
|
case "short-then-long-press":
|
|
case "long-press-release": {
|
|
// SDK 0.0.14 exposes press and release as ordinary events. The app's
|
|
// press is the context-menu gesture (tap-then-hold; the shell keeps
|
|
// the plain long-press for its system menu): the window still opens
|
|
// its menu on it (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-release" ? LONG_PRESS_RELEASE_EVENT : LONG_PRESS_EVENT;
|
|
if (capture?.kind === "list") {
|
|
this.emitListEvent(capture, eventType, inputSource);
|
|
} else {
|
|
this.emitSysEvent(eventType, gestureSource(event.source), inputSource);
|
|
}
|
|
break;
|
|
}
|
|
case "scroll-up":
|
|
case "scroll-down": {
|
|
const eventType = event.type === "scroll-up" ? SCROLL_TOP_EVENT : SCROLL_BOTTOM_EVENT;
|
|
if (capture?.kind === "list") {
|
|
this.scrollList(capture, eventType, inputSource);
|
|
} else {
|
|
this.emitSysEvent(eventType, 0, inputSource);
|
|
}
|
|
break;
|
|
}
|
|
default:
|
|
break;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* 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, 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, containerFace(list.font), delta)) this.emitListEvent(list, eventType, inputSource);
|
|
this.windowHooks?.requestRender();
|
|
}
|
|
|
|
/**
|
|
* Shell focus changes drive foreground/background. The initial ENTER is
|
|
* deferred until the page exists (a just-launched app is focused before it
|
|
* has built its page); createStartUpPage emits it then.
|
|
*/
|
|
setForeground(foreground: boolean): void {
|
|
if (this.foreground === foreground) return;
|
|
this.foreground = foreground;
|
|
// Foreground gates mic + IMU eligibility (only the visible app hears audio /
|
|
// reads the accelerometer).
|
|
if (this.micRequested) evenHubMicRouter.notifyEligibilityChanged();
|
|
if (this.imuRequested) evenHubImuRouter.notifyEligibilityChanged();
|
|
if (this.compassRequested) evenHubCompassRouter.notifyEligibilityChanged();
|
|
// Foreground gates which app tools are live; re-list on change.
|
|
if (this.hasAppTools) toolRegistry.fireToolsChanged();
|
|
// Focus is unknown until the next paint (a re-shown window repaints and
|
|
// re-asserts it; a hidden one won't, so treat it as unfocused meanwhile).
|
|
this.shellFocused = false;
|
|
this.recomputeLifecycle();
|
|
if (!this.pageCreated) return;
|
|
this.emitSysEvent(foreground ? FOREGROUND_ENTER_EVENT : FOREGROUND_EXIT_EVENT, 0);
|
|
}
|
|
|
|
/** Screen turned on/off (forwarded from the shell); mutes the mic when off. */
|
|
setScreenOn(on: boolean): void {
|
|
if (this.screenOn === on) return;
|
|
this.screenOn = on;
|
|
if (this.micRequested) evenHubMicRouter.notifyEligibilityChanged();
|
|
// As in setForeground: let the next paint re-assert focus.
|
|
this.shellFocused = false;
|
|
this.recomputeLifecycle();
|
|
}
|
|
|
|
// ----- extension window lifecycle -----
|
|
|
|
/** Sample shell input-focus (from paint) and emit focused/blurred on change. */
|
|
private updateShellFocus(focused: boolean): void {
|
|
if (this.shellFocused === focused) return;
|
|
this.shellFocused = focused;
|
|
this.recomputeLifecycle();
|
|
}
|
|
|
|
/**
|
|
* Emit visible/hidden and focused/blurred extension events on transition.
|
|
* visible = foreground && screen on; focused additionally needs shell input
|
|
* focus on this window.
|
|
*/
|
|
private recomputeLifecycle(): void {
|
|
const visible = this.foreground && this.screenOn;
|
|
const focused = visible && this.shellFocused;
|
|
if (visible !== this.lastVisible) {
|
|
this.lastVisible = visible;
|
|
this.pushExtEvent("windowLifecycle", { type: visible ? "visible" : "hidden" });
|
|
}
|
|
if (focused !== this.lastFocused) {
|
|
this.lastFocused = focused;
|
|
this.pushExtEvent("windowLifecycle", { type: focused ? "focused" : "blurred" });
|
|
}
|
|
}
|
|
|
|
// ----- microphone (EvenHubMicClient) -----
|
|
|
|
get windowId(): string {
|
|
return this.shellWindowId || this.manifest.packageId;
|
|
}
|
|
|
|
isForeground(): boolean {
|
|
return this.foreground;
|
|
}
|
|
|
|
isScreenOn(): boolean {
|
|
return this.screenOn;
|
|
}
|
|
|
|
/**
|
|
* 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, direction: null, speakerRole: "unknown" },
|
|
});
|
|
}
|
|
|
|
/**
|
|
* audioControl(enable, source?): open or close the microphone for this app.
|
|
* Gated on a declared microphone permission (confirmed at install/first run).
|
|
* Enabling only registers intent — the router decides when audio actually
|
|
* flows (foreground + screen on + no assistant modal).
|
|
*/
|
|
private audioControl(data: Record<string, unknown>): boolean {
|
|
if (!permissionsIncludeMicrophone(this.manifest.permissions)) {
|
|
this.log("evenhub: audioControl denied (app declares no microphone permission)");
|
|
return false;
|
|
}
|
|
const enable = readEnableFlag(data);
|
|
// The 0.0.12 payload shape isn't captured; log it once per toggle so the
|
|
// real field names can be confirmed from hardware.
|
|
this.log(`evenhub: audioControl enable=${enable} data=${JSON.stringify(data)}`);
|
|
if (enable) {
|
|
if (!this.micRequested) {
|
|
this.micRequested = true;
|
|
evenHubMicRouter.requestMic(this);
|
|
}
|
|
} else if (this.micRequested) {
|
|
this.micRequested = false;
|
|
evenHubMicRouter.releaseMic(this);
|
|
}
|
|
return true;
|
|
}
|
|
|
|
// ----- location -----
|
|
|
|
private declaresLocation(): boolean {
|
|
if (permissionsInclude(this.manifest.permissions, "location")) return true;
|
|
this.log("evenhub: location denied (app declares no location permission)");
|
|
return false;
|
|
}
|
|
|
|
/** getAppLocation(): one-shot fix, or null on denial/error (SDK contract). */
|
|
private async getAppLocation(): Promise<AppLocation | null> {
|
|
if (!this.declaresLocation()) return null;
|
|
if (!(await ensureFineLocationPermission())) return null;
|
|
try {
|
|
const location = await getCurrentLocation();
|
|
return {
|
|
latitude: location.latitude,
|
|
longitude: location.longitude,
|
|
...(location.accuracyMeters != null ? { accuracy: location.accuracyMeters } : {}),
|
|
timestamp: location.timestampMs,
|
|
};
|
|
} catch (error) {
|
|
this.log(`evenhub: getAppLocation failed: ${error}`);
|
|
return null;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* startAppLocationUpdates(options?): begin a location subscription. Fixes are
|
|
* pushed to the app as `appLocationChanged`. Continues in the background (the
|
|
* subscription ends only on stopAppLocationUpdates or app close), matching the
|
|
* Navigate app's foreground-service-backed tracking.
|
|
*/
|
|
private async startLocationUpdates(data: Record<string, unknown>): Promise<boolean> {
|
|
if (!this.declaresLocation()) return false;
|
|
if (!(await ensureFineLocationPermission())) return false;
|
|
if (this.closed) return false;
|
|
if (this.locationTracker) return true;
|
|
const intervalMs = readOptionalNumber(data, "intervalMs") ?? 1000;
|
|
const tracker = new LocationTracker({
|
|
onLocation: (location) => {
|
|
if (this.closed) return;
|
|
this.pushMessage("appLocationChanged", toAppLocation(location));
|
|
},
|
|
onError: (message) => this.log(`evenhub: location update error: ${message}`),
|
|
});
|
|
this.locationTracker = tracker;
|
|
tracker.start(Math.max(200, Math.round(intervalMs)));
|
|
return true;
|
|
}
|
|
|
|
private stopLocationUpdates(): boolean {
|
|
this.locationTracker?.stop();
|
|
this.locationTracker = null;
|
|
return true;
|
|
}
|
|
|
|
// ----- accelerometer / IMU (EvenHubImuClient) -----
|
|
|
|
/** A shared IMU reading from the router: hand it to the app as a sysEvent. */
|
|
deliverImu(reading: ImuReading): void {
|
|
this.pushEvenHubEvent("sysEvent", {
|
|
eventType: IMU_DATA_REPORT_EVENT,
|
|
imuData: { x: reading.x, y: reading.y, z: reading.z },
|
|
});
|
|
}
|
|
|
|
/**
|
|
* imuControl(isOpen, reportFrq): enable/disable the accelerometer report
|
|
* stream. There is no EvenHub IMU permission (nor an Android one), so no
|
|
* consent gate. Enabling registers intent; the router only actually streams
|
|
* to the foreground app. reportFrq is one of 100..1000 (step 100).
|
|
*/
|
|
private imuControl(data: Record<string, unknown>): boolean {
|
|
if (global.isIOS) return false;
|
|
const enable = readEnableFlag(data);
|
|
const freq = clampImuFreq(readOptionalNumber(data, "reportFrq") ?? readOptionalNumber(data, "reportFreq") ?? 100);
|
|
// Payload field spelling isn't fully captured; log once per toggle.
|
|
this.log(`evenhub: imuControl enable=${enable} freq=${freq} data=${JSON.stringify(data)}`);
|
|
if (enable) {
|
|
this.imuRequested = true;
|
|
evenHubImuRouter.requestImu(this, freq);
|
|
} else if (this.imuRequested) {
|
|
this.imuRequested = false;
|
|
evenHubImuRouter.releaseImu(this);
|
|
}
|
|
return true;
|
|
}
|
|
|
|
// ----- bridge calls (web -> host) -----
|
|
|
|
/**
|
|
* Handle one callHandler('evenAppMessage', ...) invocation. argsJson is the
|
|
* JSON array of handler arguments; args[0] is the SDK's message JSON string
|
|
* (kept lenient: a bare object works too).
|
|
*/
|
|
handleBridgeCall(handlerName: string, argsJson: string, callId: number): void {
|
|
if (handlerName === "faceclawExt") {
|
|
this.handleExtensionCall(argsJson, callId);
|
|
return;
|
|
}
|
|
if (handlerName === "faceclawExtToolResult") {
|
|
this.handleToolResult(argsJson);
|
|
return;
|
|
}
|
|
void (async () => {
|
|
let result: unknown = null;
|
|
try {
|
|
if (handlerName !== "evenAppMessage") throw new Error(`unknown handler ${handlerName}`);
|
|
const args = JSON.parse(argsJson) as unknown[];
|
|
const first = args[0];
|
|
const message = asRecord(typeof first === "string" ? JSON.parse(first) : first);
|
|
const method = readString(message, "method", "");
|
|
const data = asRecord(message.data);
|
|
result = await this.dispatch(method, data);
|
|
} catch (error) {
|
|
this.log(`evenhub bridge call failed: ${error}`);
|
|
this.resolveCall(callId, false, String(error));
|
|
return;
|
|
}
|
|
this.resolveCall(callId, true, result);
|
|
})();
|
|
}
|
|
|
|
private async dispatch(method: string, data: Record<string, unknown>): Promise<unknown> {
|
|
switch (method) {
|
|
case "createStartUpPageContainer":
|
|
return this.createStartUpPage(data);
|
|
case "rebuildPageContainer":
|
|
return this.rebuildPage(data);
|
|
case "textContainerUpgrade":
|
|
return this.textUpgrade(data);
|
|
case "updateImageRawData":
|
|
return this.updateImage(data);
|
|
case "shutDownPageContainer":
|
|
return this.shutDown(readNumber(data, "exitMode", 0));
|
|
case "setLocalStorage":
|
|
ApplicationSettings.setString(this.storageKey(readString(data, "key", "")), readString(data, "value", ""));
|
|
return true;
|
|
case "getLocalStorage":
|
|
return ApplicationSettings.getString(this.storageKey(readString(data, "key", "")), "");
|
|
case "getUserInfo":
|
|
return { uid: 0, name: "Faceclaw", avatar: "", country: "" };
|
|
case "getGlassesInfo": {
|
|
const status = this.deviceStatus();
|
|
return { model: "g2", sn: status.sn, status };
|
|
}
|
|
case "audioControl":
|
|
return this.audioControl(data);
|
|
case "getAppLocation":
|
|
return this.getAppLocation();
|
|
case "startAppLocationUpdates":
|
|
return this.startLocationUpdates(data);
|
|
case "stopAppLocationUpdates":
|
|
return this.stopLocationUpdates();
|
|
case "imuControl":
|
|
return this.imuControl(data);
|
|
// Unsupported surface (album/camera pickers): fail politely.
|
|
case "pickImageFromAlbum":
|
|
case "captureImageFromCamera":
|
|
return null;
|
|
default:
|
|
this.log(`evenhub: unhandled method ${method}`);
|
|
return null;
|
|
}
|
|
}
|
|
|
|
/** EhStartUpPageCreateResult: 0 success, 1 invalid, 2 oversize, 3 outOfMemory. */
|
|
private async createStartUpPage(data: Record<string, unknown>): Promise<number> {
|
|
if (this.pageCreated) {
|
|
// One-shot per session on stock: a second call blocks ~2s, then fails.
|
|
this.layoutLog(() => ["createStartUpPageContainer: repeated call, rejected as stock does"]);
|
|
await delay(DUPLICATE_CREATE_DELAY_MS);
|
|
return 1;
|
|
}
|
|
const page = parsePage(data);
|
|
this.warnOnInvalidPage(page, data);
|
|
this.layoutLog(() => describePage("createStartUpPageContainer", page, data));
|
|
this.page = page;
|
|
this.pageCreated = true;
|
|
// The launch focus arrived before the page existed; deliver the ENTER now.
|
|
if (this.foreground && !this.launchEnterSent) {
|
|
this.launchEnterSent = true;
|
|
this.emitSysEvent(FOREGROUND_ENTER_EVENT, 0);
|
|
}
|
|
this.windowHooks?.requestRender();
|
|
return 0;
|
|
}
|
|
|
|
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, data);
|
|
this.layoutLog(() => describePage("rebuildPageContainer", page, data));
|
|
this.page = page;
|
|
this.pageCreated = true;
|
|
this.windowHooks?.requestRender();
|
|
return true;
|
|
}
|
|
|
|
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;
|
|
if (captures !== 1) this.log(`evenhub: page has ${captures} event-capture containers (stock requires exactly 1)`);
|
|
const texts = page.containers.filter((c) => c.kind === "text").length;
|
|
const images = page.containers.filter((c) => c.kind === "image").length;
|
|
if (texts > 8 || images > 4) this.log(`evenhub: page exceeds stock limits (${texts} text, ${images} image)`);
|
|
}
|
|
|
|
private textUpgrade(data: Record<string, unknown>): boolean {
|
|
const id = readNumber(data, "containerID", -1);
|
|
// containerID is the identity; containerName is optional in the wild (e.g.
|
|
// level-even-g2 omits it). Match by id, enforcing the name only when the app
|
|
// actually supplies a non-empty one. (updateImage already matches by id.)
|
|
const name = readString(data, "containerName", "");
|
|
const container = this.page?.containers.find(
|
|
(c) => c.kind === "text" && c.id === id && (name === "" || c.name === name),
|
|
);
|
|
const content = readString(data, "content", "");
|
|
const offset = readOptionalNumber(data, "contentOffset");
|
|
if (!container || container.kind !== "text") {
|
|
this.layoutLog(() => [describeTextUpgrade(id, name, null, offset, content.length)]);
|
|
return false;
|
|
}
|
|
// (contentLength is intentionally ignored — see below.)
|
|
// Stock semantics are "write `content` at contentOffset and truncate the
|
|
// rest" (a null-terminating strcpy(buf+offset, content)), NOT a splice that
|
|
// keeps the old tail after offset+contentLength. Keeping the tail left stray
|
|
// trailing text when an app (e.g. g2oom) shrank a string with an
|
|
// under-sized contentLength; dropping it matches stock and still supports
|
|
// suffix rewrites (offset>0) and full replaces (offset 0 / omitted).
|
|
if (offset !== undefined && offset > 0) {
|
|
container.content = container.content.slice(0, offset) + content;
|
|
} 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.layoutLog(() => [describeTextUpgrade(id, name, container, offset, content.length)]);
|
|
this.windowHooks?.requestRender();
|
|
return true;
|
|
}
|
|
|
|
/** BleEhSendImageResult: 0 success, 1 imageException, 2 sizeInvalid, 3 sendFailed. */
|
|
private updateImage(data: Record<string, unknown>): number {
|
|
const id = readNumber(data, "containerID", -1);
|
|
const found = this.page?.containers.find((c) => c.kind === "image" && c.id === id);
|
|
const container = found?.kind === "image" ? found : null;
|
|
const raw = data.imageData ?? data.rawData ?? data.mapRawData;
|
|
const bytes = container ? imagePayloadBytes(raw) : null;
|
|
const decoded = container && bytes && bytes.length > 0 ? decodeImageBytes(bytes, container) : null;
|
|
const result = !container ? 3 : !decoded ? 1 : 0;
|
|
this.layoutLog(() =>
|
|
describeImageUpdate({
|
|
page: this.page,
|
|
sentId: id,
|
|
sentName: readString(data, "containerName", ""),
|
|
container,
|
|
raw,
|
|
bytes,
|
|
decoded,
|
|
result,
|
|
}),
|
|
);
|
|
if (!container || !decoded) return result;
|
|
container.pixels = decoded.pixels;
|
|
container.pixelsWidth = decoded.width;
|
|
container.pixelsHeight = decoded.height;
|
|
this.windowHooks?.requestRender();
|
|
return result;
|
|
}
|
|
|
|
/** Debug-level logcat for layouts and updates; `describe` runs only when logging is on. */
|
|
private layoutLog(describe: () => string[]): void {
|
|
if (!LAYOUT_LOG_ENABLED) return;
|
|
try {
|
|
const prefix = `[${this.manifest.packageId}] `;
|
|
for (const line of describe()) {
|
|
for (let i = 0; i < line.length; i += LOGCAT_CHUNK_CHARS) {
|
|
android.util.Log.d(LAYOUT_LOG_TAG, prefix + line.slice(i, i + LOGCAT_CHUNK_CHARS));
|
|
}
|
|
}
|
|
} catch (error) {
|
|
console.warn(`evenhub: layout log failed: ${error}`);
|
|
}
|
|
}
|
|
|
|
private shutDown(exitMode: number): boolean {
|
|
this.layoutLog(() => [`shutDownPageContainer exitMode=${exitMode}`]);
|
|
if (exitMode === 1) {
|
|
// The app asked to quit (stock would pop an on-glasses confirm). We
|
|
// decline and hand focus to the app switcher instead, leaving the app
|
|
// running — so an app's double-tap-to-quit becomes double-tap-to-defocus.
|
|
// No FOREGROUND_EXIT: focusing the sidebar doesn't background the app
|
|
// (native Faceclaw apps behave the same), and refocusing the same window
|
|
// wouldn't re-fire ENTER, which would leave a pause-on-exit app stuck.
|
|
this.windowHooks?.focusSwitcher();
|
|
return true;
|
|
}
|
|
// Immediate exit. Resolve first (the return travels via evaluateJs, and
|
|
// close() only tears the webview down after its own delay).
|
|
setTimeout(() => this.close(), 200);
|
|
return true;
|
|
}
|
|
|
|
private storageKey(key: string): string {
|
|
// The package ID must end at the first ':' so that no other package can
|
|
// reach this one's keys (manifest IDs are unvalidated: package "a" asking
|
|
// for key "b:ls:c" must not read package "a:ls:b"'s "c"). IDs containing
|
|
// ':' or '%' are encoded, so they can't collide with the plain IDs either.
|
|
const id = this.manifest.packageId;
|
|
return `evenhub:${/[:%]/.test(id) ? encodeURIComponent(id) : id}:ls:${key}`;
|
|
}
|
|
|
|
// ----- pushes (host -> web) -----
|
|
|
|
private resolveCall(callId: number, ok: boolean, value: unknown): void {
|
|
this.webViewHandle?.evaluateJs(
|
|
`window.__fcResolve && window.__fcResolve(${callId}, ${ok ? "true" : "false"}, ${JSON.stringify(value ?? null)})`,
|
|
);
|
|
}
|
|
|
|
private pushMessage(method: string, data: unknown): void {
|
|
const message = { type: "listen_even_app_data", method, data };
|
|
this.webViewHandle?.evaluateJs(
|
|
`window._listenEvenAppMessage && window._listenEvenAppMessage(${JSON.stringify(message)})`,
|
|
);
|
|
}
|
|
|
|
private resolveExtCall(callId: number, ok: boolean, value: unknown): void {
|
|
this.webViewHandle?.evaluateJs(
|
|
`window.__fcExtResolve && window.__fcExtResolve(${callId}, ${ok ? "true" : "false"}, ${JSON.stringify(value ?? null)})`,
|
|
);
|
|
}
|
|
|
|
/** Log a problem with the app's own calls where its developer will see it: the app's console. */
|
|
private warnApp(message: string): void {
|
|
this.log(`evenhub: ${message}`);
|
|
this.webViewHandle?.evaluateJs(`window.console && console.warn(${JSON.stringify(`Faceclaw: ${message}`)})`);
|
|
}
|
|
|
|
/** Deliver an extension event to the app (e.g. windowLifecycle). */
|
|
private pushExtEvent(name: string, data: unknown): void {
|
|
this.webViewHandle?.evaluateJs(
|
|
`window.__fcExtEvent && window.__fcExtEvent(${JSON.stringify(name)}, ${JSON.stringify(data)})`,
|
|
);
|
|
}
|
|
|
|
private pushEvenHubEvent(payloadType: "sysEvent" | "textEvent" | "listEvent", jsonData: Record<string, unknown>): void {
|
|
this.pushMessage("evenHubEvent", { type: payloadType, jsonData: elideZeroFields(jsonData) });
|
|
}
|
|
|
|
private emitSysEvent(eventType: number, eventSource: number, inputSource?: ExtensionInputSource): void {
|
|
this.pushEvenHubEvent("sysEvent", { eventType, eventSource, [INPUT_SOURCE_FIELD]: inputSource });
|
|
}
|
|
|
|
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,
|
|
});
|
|
}
|
|
|
|
// ----- Faceclaw extensions (faceclawExt channel) -----
|
|
|
|
private handleExtensionCall(argsJson: string, callId: number): void {
|
|
void (async () => {
|
|
let ok = true;
|
|
let result: unknown = null;
|
|
try {
|
|
const args = JSON.parse(argsJson) as unknown[];
|
|
const method = String(args[0]);
|
|
result = await this.dispatchExtension(method, args.slice(1));
|
|
} catch (error) {
|
|
ok = false;
|
|
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.
|
|
if (callId !== 0) this.resolveExtCall(callId, ok, result);
|
|
})();
|
|
}
|
|
|
|
private async dispatchExtension(method: string, params: unknown[]): Promise<unknown> {
|
|
switch (method) {
|
|
case "returnToAppSwitcher":
|
|
this.windowHooks?.focusSwitcher();
|
|
return null;
|
|
case "quit":
|
|
// A real quit — bypasses the shutDown(1) → return-to-switcher behavior.
|
|
setTimeout(() => this.close(), 0);
|
|
return null;
|
|
case "getConfiguredApiKeys":
|
|
return configuredApiKeyServices();
|
|
case "requestApiKeyAccess":
|
|
return this.requestApiKeyAccess(Array.isArray(params[0]) ? params[0].map(String) : []);
|
|
case "playBuzzer":
|
|
await this.playBuzzer(Array.isArray(params[0]) ? params[0] : []);
|
|
return null;
|
|
case "setCompass":
|
|
this.setCompass(params[0] === true);
|
|
return null;
|
|
case "createLayout":
|
|
case "replaceLayout":
|
|
return this.applyExtensionLayout(asRecord(params[0]));
|
|
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 {
|
|
this.pushExtEvent("compass", reading);
|
|
}
|
|
|
|
private setCompass(enable: boolean): void {
|
|
if (enable) {
|
|
if (!this.compassRequested) {
|
|
this.compassRequested = true;
|
|
evenHubCompassRouter.requestCompass(this);
|
|
}
|
|
} else if (this.compassRequested) {
|
|
this.compassRequested = false;
|
|
evenHubCompassRouter.releaseCompass(this);
|
|
}
|
|
}
|
|
|
|
// ----- extended layout -----
|
|
|
|
/**
|
|
* Build/replace the page from an extended layout: full 576x452 canvas, no
|
|
* container-count limit, and per-container `preserve` (inherit content from a
|
|
* same-named container in the outgoing layout). Returns true on success.
|
|
*/
|
|
private applyExtensionLayout(data: Record<string, unknown>): boolean {
|
|
const previous = this.page;
|
|
const page = parsePage(data);
|
|
for (const container of page.containers) {
|
|
if (container.preserve) preserveContent(container, previous);
|
|
}
|
|
this.layoutLog(() => describePage("extension layout", page, data));
|
|
this.page = page;
|
|
this.pageCreated = true;
|
|
// The extended layout uses the taller app area.
|
|
this.windowHooks?.setTallCanvas(true);
|
|
if (this.foreground && !this.launchEnterSent) {
|
|
this.launchEnterSent = true;
|
|
this.emitSysEvent(FOREGROUND_ENTER_EVENT, 0);
|
|
}
|
|
this.windowHooks?.requestRender();
|
|
return true;
|
|
}
|
|
|
|
// ----- assistant tools -----
|
|
|
|
private setAssistantTools(rawSpecs: unknown[]): void {
|
|
const specs: ToolSpec[] = [];
|
|
for (const raw of rawSpecs) {
|
|
const record = asRecord(raw);
|
|
const name = readString(record, "name", "");
|
|
const problem = appToolProblem(name, record.parameters);
|
|
if (problem) {
|
|
this.warnApp(`setAssistantTools: skipped tool ${JSON.stringify(name)}: ${problem}`);
|
|
continue;
|
|
}
|
|
const availability = record.availability === "open" ? "open" : "foreground";
|
|
specs.push({
|
|
name,
|
|
description: readString(record, "description", ""),
|
|
inputSchema: record.parameters == null ? { type: "object", properties: {} } : asRecord(record.parameters),
|
|
availability,
|
|
});
|
|
}
|
|
if (specs.length === 0 && !this.hasAppTools) return;
|
|
toolRegistry.setAppTools({
|
|
windowId: this.windowId,
|
|
// Prefix tools with the app's package name, per the extension contract.
|
|
appId: this.manifest.packageId,
|
|
specs,
|
|
invoke: (toolName, args) => this.invokeAppTool(toolName, args),
|
|
isForeground: () => this.foreground,
|
|
});
|
|
this.hasAppTools = specs.length > 0;
|
|
}
|
|
|
|
/** Invoke one of the app's tools by dispatching into the webview and awaiting its reply. */
|
|
private invokeAppTool(toolName: string, args: unknown): Promise<ToolResult> {
|
|
return new Promise((resolve) => {
|
|
if (!this.webViewHandle || this.closed) {
|
|
resolve({ ok: false, error: "app not available" });
|
|
return;
|
|
}
|
|
const id = this.nextToolCallId++;
|
|
this.pendingToolCalls.set(id, resolve);
|
|
this.webViewHandle.evaluateJs(
|
|
`window.__fcExtInvokeTool && window.__fcExtInvokeTool(${id}, ${JSON.stringify(toolName)}, ${JSON.stringify(args ?? {})})`,
|
|
);
|
|
});
|
|
}
|
|
|
|
private handleToolResult(argsJson: string): void {
|
|
try {
|
|
const args = JSON.parse(argsJson) as unknown[];
|
|
const id = Number(args[0]);
|
|
const ok = args[1] === true;
|
|
const value = args[2];
|
|
const resolve = this.pendingToolCalls.get(id);
|
|
if (!resolve) return;
|
|
this.pendingToolCalls.delete(id);
|
|
if (ok) {
|
|
resolve({ ok: true, content: typeof value === "string" ? value : JSON.stringify(value ?? null) });
|
|
} else {
|
|
resolve({ ok: false, error: typeof value === "string" ? value : "tool failed" });
|
|
}
|
|
} catch (error) {
|
|
this.log(`evenhub: bad tool result: ${error}`);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Prompt the user (on the glasses) to share configured API keys with the app,
|
|
* resolving with the granted values. Services already granted this session
|
|
* skip the prompt; declining resolves with an empty map.
|
|
*/
|
|
private requestApiKeyAccess(services: string[]): Promise<Record<string, string>> {
|
|
const requested = services.filter(isKnownApiKeyService);
|
|
const buildGrant = (): Record<string, string> => {
|
|
const out: Record<string, string> = {};
|
|
for (const id of requested) {
|
|
if (!this.grantedApiKeys.has(id)) continue;
|
|
const value = apiKeyValue(id);
|
|
if (value) out[id] = value;
|
|
}
|
|
return out;
|
|
};
|
|
if (requested.every((id) => this.grantedApiKeys.has(id))) {
|
|
return Promise.resolve(buildGrant());
|
|
}
|
|
if (!this.windowHooks) return Promise.resolve({});
|
|
return new Promise((resolve) => {
|
|
const dialog = new EvenHubApiKeyDialogLayer(
|
|
this.manifest.name,
|
|
requested.map((id) => ({ id, configured: apiKeyValue(id).length > 0 })),
|
|
() => {
|
|
for (const id of requested) this.grantedApiKeys.add(id);
|
|
resolve(buildGrant());
|
|
},
|
|
() => resolve({}),
|
|
);
|
|
this.windowHooks?.pushOverlay(dialog);
|
|
this.windowHooks?.requestRender();
|
|
});
|
|
}
|
|
|
|
/** Play a piezo tone sequence, chunking/pacing past the firmware's 48-step cap. */
|
|
private async playBuzzer(rawSteps: unknown[]): Promise<void> {
|
|
const steps = normalizeBuzzerSteps(rawSteps);
|
|
if (steps.length === 0) return;
|
|
for (let i = 0; i < steps.length; i += CFW_SEQ_MAX) {
|
|
const chunk = steps.slice(i, i + CFW_SEQ_MAX);
|
|
// A send failure rejects the app's promise (handleExtensionCall logs it).
|
|
await this.sendBuzzerSequence(buildSoundSequencePayload(chunk));
|
|
if (i + CFW_SEQ_MAX < steps.length) await delay(phraseDurationMs(chunk));
|
|
}
|
|
}
|
|
|
|
// ----- teardown -----
|
|
|
|
/** Close everything: glasses window, WebView, session. Idempotent. */
|
|
close(): void {
|
|
if (this.closed) return;
|
|
this.closed = true;
|
|
if (this.micRequested) {
|
|
this.micRequested = false;
|
|
evenHubMicRouter.releaseMic(this);
|
|
}
|
|
if (this.imuRequested) {
|
|
this.imuRequested = false;
|
|
evenHubImuRouter.releaseImu(this);
|
|
}
|
|
if (this.compassRequested) {
|
|
this.compassRequested = false;
|
|
evenHubCompassRouter.releaseCompass(this);
|
|
}
|
|
if (this.hasAppTools) {
|
|
this.hasAppTools = false;
|
|
toolRegistry.removeAppTools(this.windowId);
|
|
}
|
|
for (const resolve of this.pendingToolCalls.values()) resolve({ ok: false, error: "app closed" });
|
|
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);
|
|
this.systemExitSent = true;
|
|
}
|
|
const hooks = this.windowHooks;
|
|
this.windowHooks = null;
|
|
hooks?.closeWindow();
|
|
const webView = this.webViewHandle;
|
|
this.webViewHandle = null;
|
|
if (webView) {
|
|
// Give in-flight resolves/pushes a beat to reach the webview first.
|
|
setTimeout(() => webView.destroy(), 100);
|
|
}
|
|
}
|
|
|
|
isClosed(): boolean {
|
|
return this.closed;
|
|
}
|
|
}
|
|
|
|
function delay(ms: number): Promise<void> {
|
|
return new Promise((resolve) => setTimeout(resolve, ms));
|
|
}
|
|
|
|
/** The SDK's AppLocation shape (even_hub_sdk 0.0.12+), all fields camelCase. */
|
|
type AppLocation = {
|
|
latitude: number;
|
|
longitude: number;
|
|
accuracy?: number;
|
|
altitude?: number;
|
|
speed?: number;
|
|
heading?: number;
|
|
timestamp?: number;
|
|
};
|
|
|
|
/** Map a continuous GPS fix to the SDK's AppLocation (omitting absent fields). */
|
|
function toAppLocation(location: TrackedLocation): AppLocation {
|
|
const out: AppLocation = { latitude: location.latitude, longitude: location.longitude };
|
|
if (location.accuracyMeters != null) out.accuracy = location.accuracyMeters;
|
|
if (location.speedMps != null) out.speed = location.speedMps;
|
|
if (location.bearingDeg != null) out.heading = location.bearingDeg;
|
|
out.timestamp = location.timestampMs;
|
|
return out;
|
|
}
|
|
|
|
/**
|
|
* Read the enable flag from an audioControl / imuControl payload. The exact
|
|
* wire field name for SDK 0.0.12 isn't captured, so accept the plausible
|
|
* spellings (the mock bridge reads `isOpen`; IMU's PB field is `iMUReportEn`);
|
|
* default to enabling (the common intent) when the payload is opaque, and log
|
|
* it so the real shape can be pinned from hardware.
|
|
*/
|
|
function readEnableFlag(data: Record<string, unknown>): boolean {
|
|
for (const key of ["enable", "open", "isOpen", "on", "status", "value", "start", "iMUReportEn", "IMU_ReportEn"]) {
|
|
const value = data[key];
|
|
if (typeof value === "boolean") return value;
|
|
if (typeof value === "number") return value !== 0;
|
|
if (typeof value === "string") return value === "true" || value === "1" || value === "on" || value === "open";
|
|
}
|
|
return true;
|
|
}
|
|
|
|
/** Snap a requested IMU report rate to the SDK's 100..1000 (step 100) grid. */
|
|
function clampImuFreq(freq: number): number {
|
|
const snapped = Math.round(freq / 100) * 100;
|
|
return Math.min(1000, Math.max(100, snapped));
|
|
}
|
|
|
|
/**
|
|
* Copy content into a `preserve` container from the same-named, same-kind
|
|
* container in the previous page (if any), so a replaceLayout keeps its pixels /
|
|
* text / list state instead of blanking.
|
|
*/
|
|
function preserveContent(target: EvenHubContainer, previous: EvenHubPage | null): void {
|
|
const source = previous?.containers.find((c) => c.kind === target.kind && c.name === target.name);
|
|
if (!source) return;
|
|
if (target.kind === "text" && source.kind === "text") {
|
|
target.content = source.content;
|
|
} else if (target.kind === "image" && source.kind === "image") {
|
|
target.pixels = source.pixels;
|
|
target.pixelsWidth = source.pixelsWidth;
|
|
target.pixelsHeight = source.pixelsHeight;
|
|
} else if (target.kind === "list" && source.kind === "list") {
|
|
target.itemNames = source.itemNames;
|
|
target.selectedIndex = Math.min(source.selectedIndex, Math.max(0, target.itemNames.length - 1));
|
|
}
|
|
}
|
|
|
|
/** The API-key services the extension API can surface, and their settings. */
|
|
const API_KEY_SERVICES = [
|
|
{ id: "openai", setting: openAiApiKeySetting },
|
|
{ id: "anthropic", setting: anthropicApiKeySetting },
|
|
{ id: "soniox", setting: sonioxApiKeySetting },
|
|
{ id: "elevenlabs", setting: elevenLabsApiKeySetting },
|
|
{ id: "mapbox", setting: mapboxApiKeySetting },
|
|
] as const;
|
|
|
|
function isKnownApiKeyService(id: string): boolean {
|
|
return API_KEY_SERVICES.some((service) => service.id === id);
|
|
}
|
|
|
|
function apiKeyValue(id: string): string {
|
|
return API_KEY_SERVICES.find((service) => service.id === id)?.setting.get().trim() ?? "";
|
|
}
|
|
|
|
/** Service ids the user has actually configured (non-empty key), names only. */
|
|
function configuredApiKeyServices(): string[] {
|
|
return API_KEY_SERVICES.filter((service) => service.setting.get().trim()).map((service) => service.id);
|
|
}
|
|
|
|
/** App assistant-tool names: what every model provider accepts in a tool name. */
|
|
const APP_TOOL_NAME = /^[A-Za-z0-9_-]{1,64}$/;
|
|
|
|
/**
|
|
* Why an app's assistant tool can't be offered, or null if it can. Provider
|
|
* APIs reject a whole request over one bad tool definition, so offering it
|
|
* would break every assistant turn while the app runs.
|
|
*/
|
|
function appToolProblem(name: string, parameters: unknown): string | null {
|
|
if (!APP_TOOL_NAME.test(name)) return "name must be 1-64 letters, digits, underscores or hyphens";
|
|
if (parameters == null) return null;
|
|
const schema = parameters as Record<string, unknown>;
|
|
if (typeof parameters !== "object" || Array.isArray(parameters) || schema.type !== "object") {
|
|
return 'parameters must be a JSON Schema with type "object"';
|
|
}
|
|
if ("oneOf" in schema || "anyOf" in schema || "allOf" in schema) {
|
|
return "parameters can't use oneOf, anyOf or allOf at the top level";
|
|
}
|
|
const properties = schema.properties;
|
|
if (properties !== undefined && (!properties || typeof properties !== "object" || Array.isArray(properties))) {
|
|
return "parameters.properties must be an object";
|
|
}
|
|
const required = schema.required;
|
|
if (required !== undefined && !(Array.isArray(required) && required.every((key) => typeof key === "string"))) {
|
|
return "parameters.required must be an array of property names";
|
|
}
|
|
return null;
|
|
}
|
|
|
|
/** Coerce an app-supplied buzzer step list into validated {freq, ms, duty?}. */
|
|
function normalizeBuzzerSteps(raw: unknown[]): Step[] {
|
|
const out: Step[] = [];
|
|
for (const item of raw) {
|
|
if (!item || typeof item !== "object") continue;
|
|
const record = item as Record<string, unknown>;
|
|
const freq = Number(record.freq);
|
|
const ms = Number(record.ms);
|
|
if (!Number.isFinite(freq) || !Number.isFinite(ms)) continue;
|
|
const duty = record.duty === undefined ? undefined : Number(record.duty);
|
|
out.push({ freq, ms, duty: duty !== undefined && Number.isFinite(duty) ? duty : undefined });
|
|
}
|
|
return out;
|
|
}
|
|
|
|
/**
|
|
* Decode an uncompressed Windows BMP ('BM', BI_RGB) to 8bpp grayscale. Handles
|
|
* 1/4/8-bit paletted and 24/32-bit BGR(A), top-down or bottom-up. Returns null
|
|
* for compressed or unsupported variants. Apps like EvenChess send 1-bit BMPs
|
|
* (black/white palette) for full-board refreshes.
|
|
*/
|
|
function decodeBmp(bytes: Uint8Array): { pixels: Uint8Array; width: number; height: number } | null {
|
|
if (bytes.length < 54 || bytes[0] !== 0x42 || bytes[1] !== 0x4d) return null;
|
|
const u16 = (o: number) => bytes[o]! | (bytes[o + 1]! << 8);
|
|
const u32 = (o: number) => (bytes[o]! | (bytes[o + 1]! << 8) | (bytes[o + 2]! << 16) | (bytes[o + 3]! << 24)) >>> 0;
|
|
const i32 = (o: number) => bytes[o]! | (bytes[o + 1]! << 8) | (bytes[o + 2]! << 16) | (bytes[o + 3]! << 24);
|
|
|
|
const pixelOffset = u32(10);
|
|
const dibSize = u32(14);
|
|
const width = i32(18);
|
|
const heightRaw = i32(22);
|
|
const bitCount = u16(28);
|
|
const compression = u32(30);
|
|
if (compression !== 0) return null; // only BI_RGB (uncompressed)
|
|
if (width <= 0 || width > 4096) return null;
|
|
const topDown = heightRaw < 0;
|
|
const height = Math.abs(heightRaw);
|
|
if (height === 0 || height > 4096) return null;
|
|
|
|
// Palette (grayscale per index) for <=8bpp; each entry is 4 bytes BGRA.
|
|
let palette: Uint8Array | null = null;
|
|
if (bitCount <= 8) {
|
|
let numColors = u32(46);
|
|
if (numColors === 0 || numColors > (1 << bitCount)) numColors = 1 << bitCount;
|
|
const palOffset = 14 + dibSize;
|
|
palette = new Uint8Array(numColors);
|
|
for (let i = 0; i < numColors; i++) {
|
|
const o = palOffset + i * 4;
|
|
if (o + 2 >= bytes.length) break;
|
|
palette[i] = luminance(bytes[o + 2]!, bytes[o + 1]!, bytes[o]!);
|
|
}
|
|
}
|
|
|
|
const stride = (((width * bitCount + 31) >> 5) << 2); // rows are 4-byte aligned
|
|
const pixels = new Uint8Array(width * height);
|
|
for (let y = 0; y < height; y++) {
|
|
const srcY = topDown ? y : height - 1 - y;
|
|
const rowStart = pixelOffset + srcY * stride;
|
|
if (rowStart >= bytes.length) break;
|
|
const dstRow = y * width;
|
|
for (let x = 0; x < width; x++) {
|
|
let gray: number;
|
|
if (bitCount === 1) {
|
|
const bit = ((bytes[rowStart + (x >> 3)] ?? 0) >> (7 - (x & 7))) & 1;
|
|
gray = palette?.[bit] ?? (bit ? 255 : 0);
|
|
} else if (bitCount === 4) {
|
|
const byte = bytes[rowStart + (x >> 1)] ?? 0;
|
|
const nib = (x & 1) === 0 ? byte >> 4 : byte & 0x0f;
|
|
gray = palette?.[nib] ?? nib * 17;
|
|
} else if (bitCount === 8) {
|
|
const idx = bytes[rowStart + x] ?? 0;
|
|
gray = palette?.[idx] ?? idx;
|
|
} else if (bitCount === 24) {
|
|
const o = rowStart + x * 3;
|
|
gray = luminance(bytes[o + 2] ?? 0, bytes[o + 1] ?? 0, bytes[o] ?? 0);
|
|
} else if (bitCount === 32) {
|
|
const o = rowStart + x * 4;
|
|
gray = luminance(bytes[o + 2] ?? 0, bytes[o + 1] ?? 0, bytes[o] ?? 0);
|
|
} else {
|
|
return null;
|
|
}
|
|
pixels[dstRow + x] = gray;
|
|
}
|
|
}
|
|
return { pixels, width, height };
|
|
}
|
|
|
|
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
|
|
* ring-vocabulary gestures mean the same thing.
|
|
*/
|
|
function gestureSource(source: InputSource): number {
|
|
switch (source) {
|
|
case "right-arm":
|
|
return 1;
|
|
case "ring":
|
|
case "watch":
|
|
return 2;
|
|
case "left-arm":
|
|
return 3;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Protobuf JSON elides zero-valued fields, and apps depend on it (they test
|
|
* eventType === 0 || eventType === undefined). Emit the same shape.
|
|
*/
|
|
function elideZeroFields(obj: Record<string, unknown>): Record<string, unknown> {
|
|
const out: Record<string, unknown> = {};
|
|
for (const [key, value] of Object.entries(obj)) {
|
|
if (value === undefined || value === 0 || value === "") continue;
|
|
out[key] = value;
|
|
}
|
|
return out;
|
|
}
|
|
|
|
/** Accept the payload forms seen on the wire: number[], JSON-ified typed
|
|
* array ({"0": 1, ...}), or base64 string. */
|
|
function imagePayloadBytes(raw: unknown): Uint8Array | null {
|
|
if (Array.isArray(raw)) {
|
|
const out = new Uint8Array(raw.length);
|
|
for (let i = 0; i < raw.length; i++) out[i] = Number(raw[i]) & 0xff;
|
|
return out;
|
|
}
|
|
if (typeof raw === "string") return base64Decode(raw);
|
|
if (raw && typeof raw === "object") {
|
|
const record = raw as Record<string, unknown>;
|
|
const keys = Object.keys(record);
|
|
const out = new Uint8Array(keys.length);
|
|
for (let i = 0; i < keys.length; i++) {
|
|
const value = record[String(i)];
|
|
if (typeof value !== "number") return null;
|
|
out[i] = value & 0xff;
|
|
}
|
|
return out;
|
|
}
|
|
return null;
|
|
}
|
|
|
|
const BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
|
|
|
|
function base64Decode(text: string): Uint8Array | null {
|
|
const clean = text.replace(/[\s=]+$/g, "").replace(/\s+/g, "");
|
|
const out = new Uint8Array(Math.floor((clean.length * 3) / 4));
|
|
let bits = 0;
|
|
let bitCount = 0;
|
|
let outIndex = 0;
|
|
for (const char of clean) {
|
|
const value = BASE64_ALPHABET.indexOf(char);
|
|
if (value < 0) return null;
|
|
bits = (bits << 6) | value;
|
|
bitCount += 6;
|
|
if (bitCount >= 8) {
|
|
bitCount -= 8;
|
|
out[outIndex++] = (bits >> bitCount) & 0xff;
|
|
}
|
|
}
|
|
return out.subarray(0, outIndex);
|
|
}
|
|
|
|
/**
|
|
* Decode an image payload: PNG or BMP (both are sent by real apps — EvenChess
|
|
* force-refreshes as 1-bit BMP but streams live moves as PNG, so a host that
|
|
* only did PNG dropped the initial board), or raw grayscale sized to the
|
|
* container (8bpp, or 4bpp packed two pixels per byte, high nibble first).
|
|
*/
|
|
function decodeImageBytes(
|
|
bytes: Uint8Array,
|
|
container: EvenHubImageContainer,
|
|
): { pixels: Uint8Array; width: number; height: number } | null {
|
|
if (bytes.length > 2 && bytes[0] === 0x42 && bytes[1] === 0x4d) {
|
|
const bmp = decodeBmp(bytes);
|
|
if (bmp) return bmp;
|
|
}
|
|
if (bytes.length > 4 && bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47) {
|
|
try {
|
|
const buffer = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
|
|
const decoded = UPNG.decode(buffer);
|
|
const frames = UPNG.toRGBA8(decoded) as ArrayBuffer[];
|
|
if (!frames.length) return null;
|
|
const rgba = new Uint8Array(frames[0]!);
|
|
const pixels = new Uint8Array(decoded.width * decoded.height);
|
|
for (let i = 0; i < pixels.length; i++) {
|
|
const offset = i * 4;
|
|
const alpha = (rgba[offset + 3] ?? 0) / 255;
|
|
pixels[i] = Math.round(
|
|
(0.2126 * (rgba[offset] ?? 0) + 0.7152 * (rgba[offset + 1] ?? 0) + 0.0722 * (rgba[offset + 2] ?? 0)) * alpha,
|
|
);
|
|
}
|
|
return { pixels, width: decoded.width, height: decoded.height };
|
|
} catch (error) {
|
|
console.warn(`evenhub: PNG decode failed: ${error}`);
|
|
return null;
|
|
}
|
|
}
|
|
const area = container.width * container.height;
|
|
if (bytes.length === area) {
|
|
return { pixels: Uint8Array.from(bytes), width: container.width, height: container.height };
|
|
}
|
|
if (bytes.length === Math.ceil(area / 2)) {
|
|
const pixels = new Uint8Array(area);
|
|
for (let i = 0; i < area; i++) {
|
|
const byte = bytes[i >> 1]!;
|
|
const nibble = i % 2 === 0 ? byte >> 4 : byte & 0x0f;
|
|
pixels[i] = nibble * 17;
|
|
}
|
|
return { pixels, width: container.width, height: container.height };
|
|
}
|
|
return null;
|
|
}
|