Files
faceclaw/app/ui/layers.ts
T

359 lines
14 KiB
TypeScript

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, written while Save Recording 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> | void;
startTextSettingEdit: (setting: ConfigSettingString) => Promise<void> | 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> | void;
endTextSettingEdit: () => Promise<void> | 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> | void;
/** Stop push-to-talk; awaits native recognition, or commits a cloud provider for a final result. */
stopVoiceCapture: () => Promise<void> | 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> | void;
stopContinuousVoiceCapture: (client: string) => Promise<void> | void;
/** Play a CFW tone-sequencer payload (see sound-effects.ts). */
playBuzzerSequence: (payload: Uint8Array) => Promise<void> | 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> | 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> | 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<Layer, number>();
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<LayerActions>): 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<void> {
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<boolean> {
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];
}
}