import { GrayImage } from "../graphics/image"; import { screenHeight, screenWidth } from "../graphics/screen-size"; import { dimPlanes, type Plane } from "../graphics/plane"; import { spanCurrent } from "../native/frame-timings"; import { type ConfigSettingBoolean, type ConfigSettingString, type VoiceProvider } from "./dashboard-settings"; import { directionalFallback, isDirectionalInput, type InputEvent } from "./gestures"; import { toViewport, type Viewport, type ViewportSize } from "./viewport"; export type TextSettingsEditToggle = { setting: ConfigSettingBoolean; label: string; }; /** A continuous-capture client's needs (see LayerActions.startContinuousVoiceCapture). */ export type ContinuousCaptureOptions = { /** Names a WAV of the captured audio in Downloads (iOS, when Save Transcribe audio is on). */ recordAs?: string; /** * Transcribe with this provider, expecting this spoken language (ISO 639-1, * or "" for the provider to detect it), instead of the Transcription * Provider setting (Translate). While any client asks for one, every * capture uses it, and a shared capture running another restarts on it. */ transcription?: TranscriptionChoice; }; export type TranscriptionChoice = { provider: VoiceProvider; language: string }; export type LayerActions = { /** Ask for a dashboard repaint+transmit, e.g. when async data arrives. */ requestRender: () => void; disconnect: () => Promise | void; startTextSettingEdit: (setting: ConfigSettingString) => Promise | void; /** Open one phone form for multiple related settings (for example email + password). */ startTextSettingsEdit: ( settings: readonly ConfigSettingString[], title: string, onFinish?: () => void, toggle?: TextSettingsEditToggle, onCancel?: () => void, ) => Promise | void; endTextSettingEdit: () => Promise | void; /** * Start push-to-talk voice capture with the provider chosen in settings. * With `endpointing`, the capture also ends itself when the speaker stops * (hands-free); otherwise it runs until stopVoiceCapture. */ startVoiceCapture: (endpointing?: boolean) => Promise | void; /** Stop push-to-talk; awaits native recognition, or commits a cloud provider for a final result. */ stopVoiceCapture: () => Promise | void; /** * Start continuous capture on behalf of `client` (one id per window); shares * the mic with push-to-talk, and runs while any client wants it. Calling it * again for the same client replaces its options. */ startContinuousVoiceCapture: (client: string, options?: ContinuousCaptureOptions) => Promise | void; stopContinuousVoiceCapture: (client: string) => Promise | void; /** Play a CFW tone-sequencer payload (see sound-effects.ts). */ playBuzzerSequence: (payload: Uint8Array) => Promise | void; }; /** Do-nothing actions, for stacks whose layers never use them (or as a base to spread over). */ export const noopLayerActions: LayerActions = { requestRender: () => {}, disconnect: () => {}, startTextSettingEdit: () => {}, startTextSettingsEdit: () => {}, endTextSettingEdit: () => {}, startVoiceCapture: () => {}, stopVoiceCapture: () => {}, startContinuousVoiceCapture: () => {}, stopContinuousVoiceCapture: () => {}, playBuzzerSequence: () => {}, }; /** * Hands a layer its paint canvas: a fresh transparent (0-filled) image the * size of the stack. Calling it also declares that the layers below should * stay visible beneath this layer — each layer becomes its own plane, so a * layer that never calls paintBelow fully replaces what is under it (its * plane is submitted alone), while one that does gets composited above the * planes below. Repeat calls return the same canvas. * * Note the plane model's occlusion rule: raster painted onto the canvas * covers lower planes entirely (including their text), but glyphs drawn into * the *same* image always render above that image's own raster. */ export type PaintBelow = () => GrayImage; function notifyRemoved(layer: Layer | undefined): void { try { layer?.onRemoved?.(); } catch (error) { console.warn("layer onRemoved failed", error); } } export interface LayerContext { readonly stack: LayerStack; readonly actions: LayerActions; } export interface Layer { readonly depth?: number; paintParts?(): Plane[]; readonly paintOverBase?: boolean; /** * True when this layer stands in for `below`, a stacked layer directly * beneath it (or beneath another layer it stands in for): when this layer * calls paintBelow, the stack skips `below` and paints what is under it * instead. A submenu replacing the menu it opened from uses this, so the * hidden menu costs no plane and its dimUnderneath doesn't dim the content * a second time; popping the submenu still returns to it. */ replacesLayerBelow?(below: Layer): boolean; /** * Dim everything painted beneath this layer: a 0..1 brightness factor * applied to the pixels and glyphs of every plane below it in the stack * (only meaningful for layers that call paintBelow). false, the default, * leaves the planes below as painted. For the shell's stack the factor also * reaches the window surfaces beneath the shell surface (see * LayerStack.baseDim). */ readonly dimUnderneath?: false | number; paint(ctx: LayerContext, paintBelow: PaintBelow): GrayImage; handleInput(event: InputEvent, ctx: LayerContext): Promise | void; /** * True when handleInput gives swipe-left / swipe-right a meaning of its own. * Otherwise the stack hands the layer directionalFallback(event) instead. */ readonly acceptsDirectional?: boolean; /** * A touch at (x, y) in this layer's own canvas coordinates, from the phone's * mirror view. Return true if the layer acted on it (selected / opened what * is there); false sends a plain select (click) instead. */ hitTest?(x: number, y: number, ctx: LayerContext): Promise | boolean; /** Called when the layer leaves the stack by any path (pop or clearToBase). */ onRemoved?(): void; /** * Accept a finished text string aimed at this window (voice input, and * anything else the shell routes through sendTextToForegroundWindow). * Layers that have somewhere to put text implement it; the rest don't, and * the shell then has no app destination to offer. */ receiveTextInput?(text: string, ctx: LayerContext): void; } export class LayerStack { private readonly layers: Layer[]; private static nextShellKey = 3; static allocateShellKey(): number { if (this.nextShellKey > 65535) this.nextShellKey = 3; return this.nextShellKey++; } private readonly shellKeys = new WeakMap(); private readonly ctx: LayerContext; /** * The base viewport, or null to follow the paired glasses' screen as it * is now: the shell's own stack lives for the whole process, and * re-pairing with the other glasses type changes the screen under it. */ private baseSize: Viewport | null; private readonly focusedFn: () => boolean; private lastBaseDim: number | false = 1; constructor( baseLayer: Layer, actions: LayerActions, // A bare size is a viewport nothing borders (see toViewport). baseSize?: ViewportSize | Viewport, // Whether this stack is the current input target; drives the strength of // selection highlights (a visible-but-unfocused window dims its selection). // Defaults to always-focused for shell overlays and standalone stacks. isFocused: () => boolean = () => true, ) { this.layers = [baseLayer]; this.ctx = { stack: this, actions, }; this.baseSize = baseSize ? toViewport(baseSize) : null; this.focusedFn = isFocused; } isFocused(): boolean { return this.focusedFn(); } push(layer: Layer): void { this.layers.push(layer); } pop(): void { if (this.layers.length > 1) { notifyRemoved(this.layers.pop()); } } /** Whether the top layer matches (without popping it). */ topMatches(predicate: (layer: Layer) => boolean): boolean { return this.layers.length > 1 && predicate(this.layers[this.layers.length - 1]!); } /** Pop the top layer only if it matches; returns whether a layer was popped. */ popIfTop(predicate: (layer: Layer) => boolean): boolean { if (this.layers.length > 1 && predicate(this.layers[this.layers.length - 1]!)) { notifyRemoved(this.layers.pop()); return true; } return false; } clearToBase(): void { for (const layer of this.layers.splice(1)) { notifyRemoved(layer); } } /** * Pop layers down to and including the given one, wherever it sits in the * stack (e.g. dismissing the assistant while a follow-up voice dialog is * open above it). Returns false if the layer isn't stacked (the base layer * can never be popped). Removal callbacks fire top-down. */ popThrough(layer: Layer): boolean { const index = this.layers.indexOf(layer); if (index <= 0) return false; for (const removed of this.layers.splice(index).reverse()) { notifyRemoved(removed); } return true; } /** * Remove one stacked layer wherever it sits, leaving the layers above it in * place (e.g. a notification modal that closes under a menu opened over it). * Returns false if the layer isn't stacked (the base layer can never be removed). */ remove(layer: Layer): boolean { const index = this.layers.indexOf(layer); if (index <= 0) return false; this.layers.splice(index, 1); notifyRemoved(layer); return true; } isAtBase(): boolean { return this.layers.length === 1; } /** * The viewport layers lay out in: its size, what each of its edges * touches, and the padding suggested for them (see viewport.ts). A host * that gave only a size, and the shell's own screen-sized stack, have * edges nothing borders and no padding. */ getBaseSize(): Viewport { return toViewport(this.baseSize ?? { width: screenWidth(), height: screenHeight() }); } /** * Resize the base viewport (e.g. an EvenHub window switching to the tall * canvas), or change what its edges touch. */ setBaseSize(size: ViewportSize | Viewport): void { this.baseSize = toViewport(size); } setActions(actions: Partial): void { Object.assign(this.ctx.actions, actions); } /** * Paint the stack as planes, bottom to top: the top layer's plane last, * preceded by the planes of the layers it asked to remain visible (see * PaintBelow). All planes share the stack's base size at offset (0, 0). */ paint(): Plane[] { this.lastBaseDim = false; return this.paintLayer(this.layers.length - 1, 1); } /** * The brightness factor the last paint applied to the base plane: 1 when * nothing dims it, a smaller factor under a layer with dimUnderneath, and * false when the base was not painted at all (a stacked layer replaced it). * A stack whose base is transparent over something else (the shell chrome * over the window surfaces) forwards this to what lies beneath. */ paintUndimmed(): Plane[] { return this.paintLayer(this.layers.length - 1, 1, true); } baseDim(): number | false { return this.lastBaseDim; } async handleInput(event: InputEvent): Promise { const top = this.layers[this.layers.length - 1]!; const delivered = isDirectionalInput(event) && !top.acceptsDirectional ? directionalFallback(event) : event; await top.handleInput(delivered, this.ctx); } /** * Pass a mirror touch to the base layer when nothing is stacked on it. * With a layer stacked (a menu, a dialog) the touch is consumed without * acting: positions mean nothing to the overlay, and falling back to a * blind synthetic click would activate whatever happens to be highlighted * rather than what was tapped. */ async hitTest(x: number, y: number): Promise { if (this.layers.length !== 1) return true; const base = this.layers[0]!; if (!base.hitTest) return false; return await base.hitTest(x, y, this.ctx); } /** Hand text to the top layer; false if it doesn't take text input. */ receiveTextInput(text: string): boolean { const layer = this.layers[this.layers.length - 1]!; if (!layer.receiveTextInput) return false; layer.receiveTextInput(text, this.ctx); return true; } /** Paint layer `index`; `dimSoFar` is the factor the layers above apply to it. */ private paintLayer(index: number, dimSoFar: number, raw = false): Plane[] { const layer = this.layers[index]!; if (raw && index === 0 && layer.paintParts) return layer.paintParts(); let key = this.shellKeys.get(layer); if (key === undefined) { key = LayerStack.allocateShellKey(); this.shellKeys.set(layer, key); } let canvas: GrayImage | null = null; let belowRequested = false; const image = spanCurrent(`paint[${index}]:${layer.constructor.name}`, () => layer.paint(this.ctx, () => { belowRequested = true; if (!canvas) { const { width, height } = this.getBaseSize(); canvas = new GrayImage(width, height, 0); } return canvas; }), ); const ownPlane: Plane = { image, x: 0, y: 0, shellKey: key, depth: layer.depth, dimUnderneath: layer.dimUnderneath === false ? 1 : layer.dimUnderneath }; if (index <= 0) { this.lastBaseDim = dimSoFar; return [ownPlane]; } if (!belowRequested) { return [ownPlane]; } const dim = layer.dimUnderneath || 1; let belowIndex = layer.paintOverBase ? 0 : index - 1; while (belowIndex > 0 && layer.replacesLayerBelow?.(this.layers[belowIndex]!)) belowIndex--; const below = this.paintLayer(belowIndex, dimSoFar * dim, raw); return [...(!raw && dim < 1 ? dimPlanes(below, dim) : below), ownPlane]; } }