Files
faceclaw/app/apps/app-definition.ts
T
James Babcock fd3c26333f Add bluetooth keyboard support
G2 only: You can pair the glasses with a bluetooth keyboard. It will
relay key events, and you can use it to type in some apps and to
navigate the UI.
2026-11-15 01:54:54 -08:00

216 lines
8.6 KiB
TypeScript

import { type GrayImage } from "../graphics/image";
import { type Plane } from "../graphics/plane";
import { type IconName } from "../graphics/icons";
import { type LayerActions } from "../ui/layers";
import { type InProcessAppOptions, type InProcessWindow } from "../ui/shell/in-process-window";
import { WorkerAppHost } from "../ui/shell/worker-window";
import { shell, type TrayWidget } from "../ui/shell/shell";
/**
* An app, as seen from outside while it isn't running. Each app directory's
* index.ts default-exports one of these, and all-apps.ts collects them; the
* controller and shell reach apps only through this surface. Meant to grow
* into the sole export of an app package (the boundary for sandboxing and
* dynamic loading).
*/
export type AppDefinition = {
appId: string;
/** Launcher-grid and window-title label. */
title: string;
/** Launcher-grid icon. */
icon: IconName;
/** App-supplied launcher icon renderer; icon remains the fallback. */
renderIcon?: (size: number) => GrayImage | null;
/** Open the app's window (or focus it if already open). */
launch: (ctx: AppContext, params?: AppLaunchParams) => Promise<void>;
/**
* Runs once at shell startup, before any launch. For apps that must exist
* from boot (the launcher registers its pinned window here).
*/
boot?: (ctx: AppContext) => void;
/** False for apps that must not appear in the launcher grid (the launcher itself). */
showInLauncher?: boolean;
/**
* False while the paired glasses can't run the app (absent means they can).
* It then leaves the launcher grid and what mirrors it: the watch remote and
* the apps.launch tool. A window restored from before a re-pair still opens,
* so the app needs to say what's wrong rather than assume it never runs.
*/
isSupported?: () => boolean;
/** Present on the app that handles text shared via the Android share intent. */
openSharedText?: (ctx: AppContext, title: string, text: string) => void;
/**
* Present on the app that supplies the Glanceboard: the sleep-time display
* the controller shows on a tap or hold while the shell is asleep (see
* app/g2/glance-host.ts). At most one app provides it.
*/
glanceboard?: GlanceboardProvider;
};
/** A board the glance host can show while the shell sleeps. */
export type GlanceboardProvider = {
/** Board pixel size; the host centres it in the standard 576x288 band. */
size: { width: number; height: number };
/** Whether sleep-time gestures should show the board at all (user setting). */
isEnabled: () => boolean;
/** Whether a single tap shows the board (for tapTimeoutMs). */
showOnTap: () => boolean;
/** How long a tap or head-tilt keeps the board up. */
tapTimeoutMs: () => number;
/** Whether a long-press holds the board up until released. */
showOnLongPress: () => boolean;
/** Whether the head-tilt wake goes to the board rather than the regular UI. */
showOnHeadTilt: () => boolean;
/** Stereo depth (firmware units; positive is nearer) while the board covers the screen. */
depth: () => number;
/** A fresh board; requestRender asks the host to repaint it. */
createBoard: (requestRender: () => void) => GlanceBoardInstance;
};
export type GlanceBoardInstance = {
/** The board is about to show: start widgets (subscriptions, hardware). */
start: () => void;
/** The board was hidden: stop everything start began. */
stop: () => void;
/** Paint the board at its size. */
paint: () => GrayImage;
};
export type AppLaunchParams = {
/** Settings-app section deep-link (window menu -> Settings). */
section?: string;
};
/**
* Shell/controller services available to an app's launch and boot callbacks,
* bound to that app's id. This is deliberately the only channel from app
* definitions back into the controller.
*/
export type AppContext = {
/** The id of the app this context was built for. */
appId: string;
/** Every app, in launcher-grid order. */
apps: readonly AppDefinition[];
/** Shared layer actions (voice capture, text-setting edits, buzzer, ...). */
actions: Omit<LayerActions, "requestRender">;
/** Launch (or focus) any app by id through the shell. */
launchApp: (appId: string, params?: AppLaunchParams) => Promise<void>;
/** Uninstall a dynamically registered app, if the app id supports it. */
uninstallApp: (appId: string) => Promise<void>;
/** Launch-or-focus a main-thread singleton window keyed by windowId. */
launchInProcessApp: (
windowId: string,
surfaceId: string,
create: (options: InProcessAppOptions) => InProcessWindow,
) => Promise<void>;
/**
* Open a main-thread singleton window in the background (neither
* foregrounded nor focused) unless it is open already; `opened` says this
* call opened it. For windows the shell brings forward itself, such as an
* app widget's (see inProcessTrayWidget). Hosts that leave it out can't.
*/
openInProcessAppInBackground?: (
windowId: string,
surfaceId: string,
create: (options: InProcessAppOptions) => InProcessWindow,
) => { window: InProcessWindow; opened: boolean };
/** Get this app's shared worker host, spawning the worker on first use. */
ensureWorkerHost: (createWorker: () => Worker) => WorkerAppHost;
/** Submit a window surface's painted frame, as planes (windows created outside launchInProcessApp). */
submitWindowFrame: (surfaceId: string, planes: Plane[], paintMs: number, frameId: number) => Promise<void>;
setWindowSurfaceVisible: (surfaceId: string, visible: boolean) => void;
requestShellRender: () => void;
appendLog: (message: string) => void;
/**
* Register (or clear, with null) the window hosting the on-glasses
* text-setting editor, so the controller can sync it with the phone-side
* editor field.
*/
setTextEditorHost: (host: TextEditorHost | null) => void;
};
/** See AppContext.setTextEditorHost. */
export type TextEditorHost = {
/** Whether the glasses-side text-setting editor is the top layer. */
isTextEditorOnTop: () => boolean;
/** Pop the text-setting editor if it is on top; returns whether it was. */
closeTextEditor: () => boolean;
requestRender: () => void;
};
/**
* A tray widget (see Shell.setTrayIcon) whose window is a main-thread
* singleton app window, opened in the background while the switcher's
* selection is on it; undefined on hosts that can't do that. `show`, if
* given, runs each time the selection moves onto the widget, once the
* window is open, to bring what the widget stands for on screen in it (the
* shell repaints the window after).
*/
export function inProcessTrayWidget(
ctx: AppContext,
windowId: string,
surfaceId: string,
create: (options: InProcessAppOptions) => InProcessWindow,
show?: () => void,
): TrayWidget | undefined {
const open = ctx.openInProcessAppInBackground;
if (!open) return undefined;
return {
openWindow: () => {
const { window, opened } = open(windowId, surfaceId, create);
show?.();
return { window: window.window, opened };
},
};
}
/**
* Launch-or-focus flow shared by the worker-hosted apps: focus the app's
* existing window if one is open, otherwise open a window in the app's shared
* worker (spawned on first launch).
*/
export async function launchWorkerAppWindow(
ctx: AppContext,
options: {
/** Must construct the worker with a string-literal path (webpack worker loader). */
createWorker: () => Worker;
windowId: string;
title: string;
iconLetter: string;
icon: IconName;
/**
* Which existing window counts as "already launched": any window of this
* app (default), or only options.windowId exactly (multi-window apps like
* the terminal, where launching should reopen the hub even while other
* windows are open).
*/
matchExistingBy?: "appId" | "windowId";
/** Deliver watch swipes raw instead of the fallback (see WorkerWindowSpec). */
acceptsDirectional?: boolean;
/** Deliver hardware-keyboard keys as keys (see WorkerWindowSpec). */
acceptsKeys?: boolean;
},
): Promise<void> {
const existing = shell
.getWindows()
.find((window) =>
options.matchExistingBy === "windowId" ? window.windowId === options.windowId : window.appId === ctx.appId,
);
if (existing) {
shell.focusWindow(existing.windowId);
ctx.requestShellRender();
return;
}
const host = ctx.ensureWorkerHost(options.createWorker);
host.openWindow({
windowId: options.windowId,
title: options.title,
iconLetter: options.iconLetter,
icon: options.icon,
focus: true,
acceptsDirectional: options.acceptsDirectional,
acceptsKeys: options.acceptsKeys,
});
ctx.appendLog(`launched ${options.windowId}`);
}