Surfaces ↓

Hardware

client.hardware

Daemon -> webapp hardware surface: ambient-light and backlight change events, plus the reply to hardware.stateGet.

Requests

you ask, the daemon answers; await the tagged result and check .ok

stateGet(): Promise<TypedRequestResult<HardwareStateReply, never>>

push form: onStateReply (subscribe instead of awaiting)

Webapp asks for the current HardwareState snapshot (backlight mode / level, ambient light reading).

const res = await client.hardware.stateGet();
if (res.ok) {
  console.log(res.response.state);
}

type Result =
  | { ok: true; response: HardwareStateReply }
  | { ok: false; kind: 'domain'; error: never }
  | { ok: false; kind: 'protocol'; error: WireError };

Commands

fire-and-forget; the promise resolves once the daemon has taken the message

displaySetMode(DisplaySetMode): Promise<void>

await client.hardware.displaySetMode({ mode: 'auto' });

displaySetLevel(DisplaySetLevel): Promise<void>

await client.hardware.displaySetLevel({ level: 0 });

Events

the daemon pushes these unprompted; subscribing returns an unsubscribe function

onAmbientLightUpdate(handler: (AmbientLightUpdate) => void): () => void

const off = client.hardware.onAmbientLightUpdate((update) => {
  console.log(update.ambientLevel);
});
// call off() to unsubscribe

onBrightnessChanged(handler: (BrightnessState) => void): () => void

const off = client.hardware.onBrightnessChanged((state) => {
  console.log(state.mode);
});
// call off() to unsubscribe

Types

shapes referenced above, as the SDK types them

0..=100 ambient-brightness indicator derived from the on-board ALS + backlight curve. Low = dark room, high = bright room.

type AmbientLightUpdate = {
  ambientLevel: number;
};

Backlight state. level is the user-set value (only respected in Manual); effective_level is what's actually on the panel - equal to level in Manual, ALS-derived in Auto.

type BrightnessState = {
  mode: BrightnessMode;
  level: number;
  effectiveLevel: number;
};

Response to hardware.stateGet.

type HardwareStateReply = {
  state: HardwareState;
};

Payload for hardware.displaySetMode: switch backlight control between daemon-driven (Auto, following the ALS) and webapp-driven (Manual, via displaySetLevel).

type DisplaySetMode = {
  mode: BrightnessMode;
};

Set the manual backlight level. Ignored unless mode == Manual; callers should pair with setMode({ Manual }) when forcing a level.

type DisplaySetLevel = {
  level: number; // Backlight level in `[0.0, 1.0]`.
};

type BrightnessMode =
  | 'auto' // Daemon drives backlight from the on-board ALS.
  | 'manual' // Webapp drives backlight directly via `setLevel`.;

Snapshot of the device's hardware-controlled surfaces. Sent on hardware.state.get and re-broadcast on any change. ambient_level is the 0-255 ambient light reading.

type HardwareState = {
  brightness: BrightnessState;
  ambientLevel: number;
};