System and power

dd.system

Reads need the system permission; the write surface (setVolume, setMuted, the Wi-Fi verbs, openSettings) additionally needs systemControls.

dd.system.status()

dd.system.status(): Promise<SystemVitals | null>

The latest vitals snapshot, a cheap cache read (null until the sampler's first pass). Seed your UI with this, then follow onVitals.

dd.system.onVitals()

dd.system.onVitals(cb: (vitals: SystemVitals) => void): () => void

interface SystemVitals {
  /** CPU busy fraction 0..1 (null on the very first sample). */
  cpu: number | null;
  ram: { usedMb: number; totalMb: number; percent: number } | null;
  /** GPU 3D-engine utilization 0..1. */
  gpu: number | null;
  /** Disk busy fraction 0..1 (physical disks total). */
  disk: number | null;
  net: { rxBps: number; txBps: number } | null;
  battery: { percent: number | null; charging: boolean } | null;
  wifi: { ssid: string; signal: number } | null;
  volume: { level: number; muted: boolean } | null;
}

A 1 Hz stream. Every field fails independently: a machine with no GPU counters, no Wi-Fi adapter, no battery, or no audio device reports null for that field while the rest keep flowing. Render nulls as absent, not as zero. cpu, gpu, disk, volume.level and ram.percent are 0..1 fractions; wifi.signal is 0..100.

dd.system.setVolume()

dd.system.setVolume(level: number): Promise<void>  // 0..1

Master volume. 120 calls per rolling 10 seconds; throttle slider drags client-side to roughly one call per 100 ms.

dd.system.setMuted()

dd.system.setMuted(muted: boolean): Promise<void>

20 calls per rolling 10 seconds.

dd.system.wifiNetworks()

dd.system.wifiNetworks(): Promise<{ networks: WifiNetwork[] }>

interface WifiNetwork {
  ssid: string;
  /** Signal quality 0..100. */
  signal: number;
  secured: boolean;
  connected: boolean;
  /** Windows has a saved profile: wifiConnect only works for these. */
  known: boolean;
}

Available networks, deduped by SSID (strongest kept), connected first. The host triggers a background scan at most every 30 seconds. 6 calls per rolling 10 seconds.

dd.system.wifiConnect()

dd.system.wifiConnect(ssid: string): Promise<void>

Connects only to networks with a saved Windows profile (known: true); passwords never cross the bridge. No profile rejects NOT_FOUND; send users to openSettings("wifi") for new networks. 3 calls per rolling 10 seconds.

dd.system.wifiDisconnect()

dd.system.wifiDisconnect(): Promise<void>

3 calls per rolling 10 seconds.

dd.system.openSettings()

dd.system.openSettings(panel: "sound" | "power" | "wifi" | "battery"): Promise<void>

Opens a Windows settings page. panel is a whitelist key mapped host-side; widgets can never launch arbitrary settings targets. 3 calls per rolling 10 seconds.

dd.power

Needs the power permission, which is deliberately separate from systemControls: granting a volume slider is not granting the power to turn the machine off.

dd.power.capabilities()

dd.power.capabilities(): Promise<{ sleep: boolean; hibernate: boolean }>

What this machine can actually do, read from its firmware. Check it before drawing a Sleep button: many desktops have no sleep state at all, and a button that fails every press reads as a broken widget. An unreadable answer reports true for both, so a machine that would have worked never loses its button. No gesture gate (a widget needs this before any interaction). 30 calls per rolling 10 seconds.

dd.power.run()

dd.power.run(action: "shutdown" | "restart" | "sleep" | "lock" | "signOut"): Promise<{ ran: boolean }>

Ends or suspends the Windows session. Only these five actions exist; nothing else (no flags, no timeouts, no targets) reaches the OS. Refused unless the real cursor is inside the widget, and refused in edit mode, so a background timer can never trigger it.

shutdown, restart and signOut first raise a host-drawn confirmation the widget cannot draw, style, or auto-answer; Cancel holds the initial focus, and Escape, closing the window, or a timeout all answer no. ran: false means the user declined, which is the moment to re-enable your button:

const { ran } = await dd.power.run("shutdown");
if (!ran) button.disabled = false;

sleep and lock skip the confirmation, being instantly reversible. Nothing here forces applications to close: an app with unsaved work still gets Windows' own "this app is preventing shutdown" screen. On actions that proceed, the session usually ends before the promise settles. 6 calls per rolling 10 seconds.