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 busy fraction 0..1: the busiest engine (3D, copy, video, compute)
   *  of ONE adapter, the figure Task Manager shows. The host measures the
   *  hardware adapter with the most dedicated video memory unless the user
   *  picked another in Settings > General. App 0.3.8+; earlier apps summed
   *  the 3D engines of every adapter. */
  gpu: number | null;
  /** Disk busy fraction 0..1 (physical disks total). */
  disk: number | null;
  /** Fixed drives (letters), resampled about every 30s inside the 1Hz
   *  stream. `percent` is used/total 0..1; `label` is the volume name or
   *  null; null when enumeration fails, empty when no fixed drives exist. */
  drives:
    | { mount: string; label: string | null; usedMb: number; totalMb: number; percent: 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. drives lists fixed volumes only and refreshes about every 30 seconds inside the stream (app 0.2.5+); sizes are MiB, like ram. net sums the up hardware interfaces only, so a VPN tunnel or a virtual switch port never counts the same bytes again; a machine with no hardware interface up (a VM guest) sums every up interface, and the first tick after that rule flips is null (app 0.3.7 or newer; earlier apps summed every up interface). gpu is the busiest engine of one graphics adapter, the figure Task Manager shows for that card: the hardware adapter with the most dedicated video memory, or the one the user picked in Settings > General (app 0.3.8 or newer; earlier apps summed the 3D engines of every adapter, integrated graphics included).

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" | "restartAdvanced" | "sleep" | "lock" | "signOut"): Promise<{ ran: boolean }>

Ends or suspends the Windows session. Only these six 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. From a bar, the test is the bar window or its pane (app 0.3.7 or newer; older apps refuse bars outright).

restartAdvanced restarts into the advanced startup menu (recovery, firmware settings, safe mode), what shutdown /r /o does. App 0.3.7 or newer; an older app rejects it INVALID_PARAMS with "unknown power action", so catch that to feature-detect.

shutdown, restart, restartAdvanced 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.