@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/builtin-addons/media/providers/types.ts

@@ -0,0 +1,48 @@
+export type PlayStatus = "play" | "pause" | "stop" | "unavailable"
+
+export interface MediaTrack {
+  readonly name: string
+  readonly artist: string
+  readonly album?: string
+}
+
+export interface MediaStatus {
+  readonly track: MediaTrack | null
+  readonly totalTime: number
+  readonly currentTime: number
+  readonly playStatus: PlayStatus
+  readonly volume: number
+  readonly muted: boolean
+}
+
+export interface MediaStatusProvider {
+  getStatus(): Promise<MediaStatus>
+  play(): Promise<void>
+  pause(): Promise<void>
+  toggle(): Promise<void>
+  next(): Promise<void>
+  previous(): Promise<void>
+  setVolume(value: number): Promise<void>
+  volumeUp(step: number): Promise<void>
+  volumeDown(step: number): Promise<void>
+  toggleMute(): Promise<void>
+}
+
+export interface StatusProviderDeps {
+  readonly executor: ProviderExecutor
+}
+
+export interface ProviderExecutor {
+  run(
+    command: string,
+    args: ReadonlyArray<string>,
+    options?: { timeoutMs?: number },
+  ): Promise<{
+    exitCode: number
+    stdout: string
+    stderr: string
+  }>
+}
+
+export const DEFAULT_TIMEOUT_MS = 5_000
+export const ONCHANGE_POLL_MS = 2_000

package/src/builtin-addons/media/providers/windows.ts

@@ -0,0 +1,121 @@
+import type {
+  MediaStatus,
+  MediaStatusProvider,
+  ProviderExecutor,
+} from "./types"
+
+interface WindowsDeps {
+  readonly executor: ProviderExecutor
+}
+
+const runPowerShell = async (
+  deps: WindowsDeps,
+  script: string,
+): Promise<void> => {
+  const result = await deps.executor.run(
+    "powershell",
+    ["-NoProfile", "-Command", script],
+    {
+      timeoutMs: 5_000,
+    },
+  )
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `powershell failed: ${result.stderr.trim() || "exit " + result.exitCode}`,
+    )
+  }
+}
+
+const PS_GET_STATE = `(Get-Process | Where-Object { $_.MainWindowTitle -ne '' } | Select-Object -First 1 -ExpandProperty ProcessName) 2>$null`
+const PS_GET_TRACK = `try { $m = [Windows.Media.Control.GlobalSystemMediaTransportControlsSessionManager,Windows.Media.Content,Windows,ContentType=WindowsRuntime]::RequestAsync().GetAwaiter().GetResult().GetCurrentSession().GetMediaPropertiesAsync().GetAwaiter().GetResult(); "{0}|{1}|{2}" -f $m.Title, $m.Artist, $m.AlbumTitle } catch { "" }`
+const PS_PLAY = `Add-Type -AssemblyName System.Runtime.WindowsRuntime; $null = [Windows.System.User, Windows.System, ContentType=WindowsRuntime]; $smtc = [Windows.Media.Control.GlobalSystemMediaTransportControlsSessionManager,Windows.Media.Content,Windows,ContentType=WindowsRuntime]::RequestAsync().GetAwaiter().GetResult(); $null = $smtc.GetCurrentSession().TryPlayAsync().GetAwaiter().GetResult()`
+const PS_PAUSE = `$smtc = [Windows.Media.Control.GlobalSystemMediaTransportControlsSessionManager,Windows.Media.Content,Windows,ContentType=WindowsRuntime]::RequestAsync().GetAwaiter().GetResult(); $null = $smtc.GetCurrentSession().TryPauseAsync().GetAwaiter().GetResult()`
+const PS_TOGGLE = `$smtc = [Windows.Media.Control.GlobalSystemMediaTransportControlsSessionManager,Windows.Media.Content,Windows,ContentType=WindowsRuntime]::RequestAsync().GetAwaiter().GetResult(); $null = $smtc.GetCurrentSession().TryTogglePlayPauseAsync().GetAwaiter().GetResult()`
+
+const readStatus = async (deps: WindowsDeps): Promise<MediaStatus> => {
+  const [stateResult, trackResult] = await Promise.all([
+    deps.executor.run("powershell", ["-NoProfile", "-Command", PS_GET_STATE], {
+      timeoutMs: 2_000,
+    }),
+    deps.executor.run("powershell", ["-NoProfile", "-Command", PS_GET_TRACK], {
+      timeoutMs: 2_000,
+    }),
+  ])
+
+  // SMTC does not expose a distinct play/pause/stop status. We use the
+  // presence of a foreground media process as a proxy for "playing"; a real
+  // session manager would expose PlaybackStatus but the underlying Windows
+  // Media Control API does not surface it through PowerShell here.
+  const playStatus: MediaStatus["playStatus"] =
+    stateResult.exitCode === 0 && stateResult.stdout.trim().length > 0
+      ? "play"
+      : "stop"
+
+  const track =
+    trackResult.exitCode === 0 && trackResult.stdout.trim().length > 0
+      ? (() => {
+          const parts = trackResult.stdout.trim().split("|")
+          const name = (parts[0] ?? "").trim()
+          if (name.length === 0) return null
+          return {
+            name,
+            artist:
+              parts[1] !== undefined && parts[1].trim().length > 0
+                ? parts[1].trim()
+                : "",
+            album:
+              parts[2] !== undefined && parts[2].trim().length > 0
+                ? parts[2].trim()
+                : undefined,
+          }
+        })()
+      : null
+
+  return {
+    track,
+    totalTime: 0,
+    currentTime: 0,
+    playStatus,
+    volume: 1,
+    muted: false,
+  }
+}
+
+export const createWindowsProvider = (
+  deps: WindowsDeps,
+): MediaStatusProvider => {
+  return {
+    async getStatus() {
+      return readStatus(deps)
+    },
+
+    async play() {
+      await runPowerShell(deps, PS_PLAY)
+    },
+    async pause() {
+      await runPowerShell(deps, PS_PAUSE)
+    },
+    async toggle() {
+      await runPowerShell(deps, PS_TOGGLE)
+    },
+    async next() {
+      // SMTC doesn't expose next/previous directly.
+    },
+    async previous() {
+      // SMTC doesn't expose next/previous directly.
+    },
+
+    async setVolume(_value) {
+      // SMTC doesn't support volume control.
+    },
+    async volumeUp(_step) {
+      // SMTC doesn't support volume control.
+    },
+    async volumeDown(_step) {
+      // SMTC doesn't support volume control.
+    },
+    async toggleMute() {
+      // SMTC doesn't support mute.
+    },
+  }
+}

package/src/builtin-addons/media/sirenodeck.json

@@ -0,0 +1,6 @@
+{
+  "kind": "addon",
+  "apiVersion": 1,
+  "name": "media",
+  "entry": "index.ts"
+}

package/src/builtin-addons/media/state.ts

@@ -0,0 +1,19 @@
+export type MediaButtonStatus =
+  | "play"
+  | "pause"
+  | "stop"
+  | "unsupported"
+  | "notAvailable"
+
+export interface MediaPlayerState {
+  title: string | null
+  artist: string | null
+  source: string | null
+  status: MediaButtonStatus | null
+  isPlaying: boolean
+  progress: number
+  currentTime: number
+  totalTime: number
+  volume: number
+  muted: boolean
+}

package/src/builtin-addons/register-builtins.ts

@@ -0,0 +1,65 @@
+import type { AddonRegistry } from "@/addon/registry"
+
+import { registerBuiltInThemes, registerSiblingThemes } from "@/themes/loader"
+
+import { manifest as codingAgentsManifest } from "./coding-agents"
+import { registerCodingAgentsAddon } from "./coding-agents"
+import brightnessAddon from "./brightness/index"
+import { coreAddon } from "./core/index"
+import dateTimeAddon from "./date-time/index"
+import emojiSelectorAddon from "./emoji-selector/index"
+import { internalSettingsAddon } from "./internal-settings/index"
+import mediaPlayerAddon from "./media/index"
+import { sessionAddon } from "./session/index"
+import { systemStatusAddon } from "./system-status/index"
+import valueDisplayAddon from "./value-display/index"
+import weatherAddon from "./weather/index"
+
+export const registerBuiltins = (registry: AddonRegistry): void => {
+  registerBuiltInThemes(registry)
+  registerSiblingThemes(registry)
+  registry.load(coreAddon)
+  registry.load(internalSettingsAddon)
+  registry.load(sessionAddon)
+  registry.load(dateTimeAddon)
+  registry.load(emojiSelectorAddon)
+  registry.load(mediaPlayerAddon)
+  registry.load(systemStatusAddon)
+  registry.load(valueDisplayAddon)
+  registry.load(weatherAddon)
+  registry.load(brightnessAddon)
+  registerCodingAgentsAddon(registry)
+}
+
+/**
+ * The builtin manifests, by addon name, as objects rather than file paths.
+ *
+ * ponytail: the addon bridge used to reach a builtin's handlers by
+ * `await import(<path to its index.ts>)`. That works under tsx and fails under
+ * the published bundle, where plain node meets TypeScript source and a `@/`
+ * path alias and gives up — "Cannot find package '@/deck'". The buttons then
+ * rendered but never received data: system metrics sat at "—%", the weather
+ * read "---", and the media player showed an empty face, with the failure
+ * confined to one error line in the daemon log.
+ *
+ * These modules are statically imported above, so they are already inside the
+ * bundle and inside the dev process alike. Handing the bridge the object it
+ * would have imported removes the file-path round trip entirely, which is both
+ * faster and immune to how the process was started.
+ */
+export const BUILTIN_MANIFESTS: ReadonlyMap<string, unknown> = new Map<
+  string,
+  unknown
+>([
+  ["core", coreAddon],
+  ["internal-settings", internalSettingsAddon],
+  ["session", sessionAddon],
+  ["date-time", dateTimeAddon],
+  ["emoji-selector", emojiSelectorAddon],
+  ["media", mediaPlayerAddon],
+  ["system-status", systemStatusAddon],
+  ["value-display", valueDisplayAddon],
+  ["weather", weatherAddon],
+  ["brightness", brightnessAddon],
+  ["coding-agents", codingAgentsManifest],
+])

package/src/builtin-addons/session/README.md

@@ -0,0 +1,14 @@
+# session
+
+**Internal-only addon.** Provides session-related info buttons. The locked deck itself is runtime-synthesized (see `packages/cli/src/deck/runtime.ts` → `buildDefaultLockDeck`); this addon does not register a deck factory.
+
+## Buttons
+
+| Button id      | Purpose                                          |
+| -------------- | ------------------------------------------------ |
+| `session:info` | Shows current OS session state (locked/unlocked) |
+
+## See also
+
+- [Internal settings](../internal-settings/README.md) — settings overlay
+- `packages/cli/src/deck/runtime.ts` — runtime-synthesized lock deck

package/src/builtin-addons/session/buttons/session-info/backend.ts

@@ -0,0 +1,8 @@
+import type { AddonButtonTypeService } from "@/addon/api"
+
+import { configSchema } from "./config"
+
+export default {
+  configSchema,
+  onTap: async () => {},
+} satisfies AddonButtonTypeService

package/src/builtin-addons/session/buttons/session-info/config.ts

@@ -0,0 +1,4 @@
+import { z } from "zod"
+
+export const configSchema = z.object({})
+export type ConfigSchema = z.infer<typeof configSchema>

package/src/builtin-addons/session/buttons/session-info/frontend.tsx

@@ -0,0 +1,2 @@
+import { NullButton } from "@/api/react"
+export default NullButton

package/src/builtin-addons/session/buttons/time/backend.ts

@@ -0,0 +1,7 @@
+import type { AddonButtonTypeService } from "@/addon/api"
+
+import { configSchema } from "./config"
+
+export default {
+  configSchema,
+} satisfies AddonButtonTypeService

package/src/builtin-addons/session/buttons/time/config.ts

@@ -0,0 +1,6 @@
+import { z } from "zod"
+
+export const configSchema = z.object({
+  format: z.string().default("HH:mm"),
+})
+export type ConfigSchema = z.infer<typeof configSchema>

package/src/builtin-addons/session/buttons/time/frontend.tsx

@@ -0,0 +1,2 @@
+import { NullButton } from "@/api/react"
+export default NullButton

package/src/builtin-addons/session/index.d.ts

@@ -0,0 +1,5 @@
+import type { NewAddonManifest } from "@/addon/api"
+
+declare const manifest: NewAddonManifest
+export default manifest
+export { manifest }

package/src/builtin-addons/session/index.ts

@@ -0,0 +1,18 @@
+import type { AddonManifestV1 } from "@/addon/api"
+
+import sessionInfoBackend from "./buttons/session-info/backend"
+import sessionInfoFrontend from "./buttons/session-info/frontend"
+
+export const manifest: AddonManifestV1 = {
+  apiVersion: 1,
+  name: "session",
+  buttonTypes: {
+    "session:info": {
+      frontend: sessionInfoFrontend,
+      service: { ...sessionInfoBackend, gestureHandlers: ["tap"] as const },
+    },
+  },
+}
+
+export const sessionAddon = manifest
+export default manifest

package/src/builtin-addons/session/sirenodeck.json

@@ -0,0 +1,6 @@
+{
+  "kind": "addon",
+  "apiVersion": 1,
+  "name": "session",
+  "entry": "index.ts"
+}

package/src/builtin-addons/system-status/README.md

@@ -0,0 +1,169 @@
+# system-status
+
+OS metrics as Stream Deck buttons. Three visual modes — horizontal bars, a
+KPIs list, and a mini-chart — and 19 built-in metrics. Polls every second via
+addon-global pollers per metric, publishes on `runtime:system-status:<id>`,
+and chart history on `runtime:system-status:chart-history`.
+
+## Buttons
+
+| Type                          | Description                                           |
+| ----------------------------- | ----------------------------------------------------- |
+| `system-status:system-status` | 1–3 metrics rendered as horizontal bars + value chips |
+
+> The `bars`, `kpis`, and `chart` layouts are pages within this single button
+> type, not separate button types.
+
+## Config
+
+```yaml
+- position: 5
+  type: "system-status:system-status"
+  config:
+    pages:
+      - type: bars
+        metrics:
+          - id: cpu
+            label: CPU
+          - id: ram
+            label: MEM
+          - swap
+      - type: kpis
+        metrics: [temperature, uptime]
+```
+
+`metrics` accepts either a string id (`"cpu"`) or an object
+(`{id: "cpu", label: "CPU"}`). At least one, at most three.
+
+### Page layouts
+
+The single registered button type accepts up to five `pages`. Each page has one
+of three layouts:
+
+| Layout  | Metric count | Notes                                      |
+| ------- | ------------ | ------------------------------------------ |
+| `bars`  | 1–3          | Horizontal bars + value chips              |
+| `kpis`  | 1–3          | Label/value list                           |
+| `chart` | 1–2          | Metrics plotted over a sliding time window |
+
+```yaml
+- position: 6
+     type: "system-status:system-status"
+     config:
+     pages:
+       - type: kpis
+         metrics: [cpu, ram]
+```
+
+`chart` supports an optional `windowSeconds` (default 60); the per-metric
+history is published on a dedicated
+`runtime:system-status:chart-history` channel, separate from the live
+metric channels.
+
+## Metrics
+
+| Id              | Label (default) | Formatter     | Unit | Views             | Source                                                                            |
+| --------------- | --------------- | ------------- | ---- | ----------------- | --------------------------------------------------------------------------------- |
+| `cpu`           | CPU             | percent       | %    | bars, chart, kpis | `/proc` jiffies delta over poll interval                                          |
+| `ram`           | RAM             | percent       | %    | bars, chart, kpis | `os.totalmem/freemem`                                                             |
+| `swap`          | Swap            | percent       | %    | bars, chart, kpis | `/proc/meminfo` SwapTotal/SwapFree (Linux)                                        |
+| `disk`          | Disk            | percent       | %    | bars, chart, kpis | `statfs("/")` used/total                                                          |
+| `disk-io`       | Disk I/O        | rate-bytes    | B/s  | kpis              | `/proc/diskstats` sector delta × 512 (Linux)                                      |
+| `network`       | Net             | count         | —    | kpis              | Interface count (placeholder — see `network-read` / `network-write`)              |
+| `network-read`  | Net RX          | rate-bytes    | B/s  | kpis              | `/sys/class/net/*/statistics/rx_bytes` delta, non-loopback (Linux)                |
+| `network-write` | Net TX          | rate-bytes    | B/s  | kpis              | `/sys/class/net/*/statistics/tx_bytes` delta, non-loopback (Linux)                |
+| `battery`       | Battery         | percent       | %    | bars, chart, kpis | `/sys/class/power_supply/BAT0/capacity` (Linux)                                   |
+| `temperature`   | Temp            | count         | °C   | bars, chart, kpis | hwmon / `thermal_zone0` (Linux); `macmon` `temp.cpu_temp_avg` (macOS)             |
+| `gpu-temp`      | GPU Temp        | count         | °C   | bars, chart, kpis | amdgpu sysfs / `nvidia-smi` (Linux); `macmon` `temp.gpu_temp_avg` (macOS)         |
+| `gpu-usage`     | GPU             | percent       | %    | bars, chart, kpis | amdgpu `gpu_busy_percent`, fallback `nvidia-smi --query-gpu=utilization.gpu`      |
+| `uptime`        | Uptime          | uptime        | —    | kpis              | `os.uptime()`                                                                     |
+| `frequency`     | Freq            | frequency-ghz | GHz  | bars, chart, kpis | `os.cpus()[].speed`, fallback `/proc/cpuinfo` MHz                                 |
+| `load`          | Load            | count         | —    | bars, chart, kpis | `os.loadavg()[0]`                                                                 |
+| `processes`     | Procs           | count         | —    | kpis              | `/proc` numeric-dir count (Linux)                                                 |
+| `cpu-boost`     | Boost           | bool          | —    | kpis              | `/sys/devices/system/cpu/cpufreq/boost`, fallback `intel_pstate/no_turbo` (Linux) |
+| `cpu-voltages`  | Vcore           | count         | V    | kpis              | hwmon `in0_input` on k10temp/zenpower/coretemp/acpitz (Linux)                     |
+| `fan-rpm`       | Fan             | count         | RPM  | kpis              | hwmon `fan*_input` first non-zero reading (Linux); `macmon` fastest fan (macOS)   |
+
+Metrics that aren't available on the current platform report
+`available: false` and the button renders a `—` for that slot. No silent
+zeros, no crashes.
+
+#### Platform coverage
+
+Most probes read Linux sysfs. macOS has no `/proc` or `/sys`, so the darwin
+paths go through documented CLIs instead — `sysctl` for swap, `pmset` for
+battery, `ps` for processes, `netstat` for network, and `ioreg` for GPU
+utilisation and disk I/O.
+
+Three metrics need a helper. CPU temperature, GPU temperature and fan RPM have
+no unprivileged source on Apple Silicon from those tools: `powermetrics`
+requires root, and the only `Temperature` key `ioreg` will hand a normal user
+belongs to `AppleSmartBattery` — the battery's, not the SoC's, so reporting it
+would be wrong rather than merely absent. [`macmon`](https://github.com/vladkens/macmon)
+reads all three through IOReport without sudo:
+
+```sh
+brew install macmon
+```
+
+It is optional and follows the same pattern as the media addon preferring
+`media-control` and brightness preferring `brightness`: present, the metrics
+report live values; absent, they stay unavailable and `system-requirements`
+names the install command.
+
+`cpu-boost` and `cpu-voltages` stay unavailable on macOS whatever is
+installed. Apple Silicon has no turbo toggle to report and no exposed voltage
+rail, so there is nothing to read — this is not a gap waiting to be filled.
+
+### Formatters
+
+| Formatter       | Output                                    |
+| --------------- | ----------------------------------------- |
+| `percent`       | `5.4%` (<10) / `42%` (≥10)                |
+| `count`         | `42` (≥100) / `5.4` (<100)                |
+| `bytes`         | `5.2 MB`                                  |
+| `rate-bytes`    | `5.2 MB/s` (uses KiB/MiB/GiB/TiB scaling) |
+| `frequency-ghz` | `3.40`                                    |
+| `uptime`        | `2h`                                      |
+| `bool`          | `ON` (≥0.5) / `OFF`                       |
+
+## Example
+
+```yaml
+decks:
+  sys:
+    name: Sys Stats
+    buttons:
+      - position: 0
+        type: "system-status:system-status"
+         config:
+           pages:
+             - type: bars
+               metrics:
+                 - id: cpu
+                   label: CPU
+                 - id: ram
+                   label: MEM
+                 - swap
+       - position: 1
+         type: "system-status:system-status"
+         config:
+           pages:
+             - type: kpis
+               metrics: [disk-io, network-read, network-write]
+       - position: 2
+         type: "system-status:system-status"
+         config:
+           pages:
+             - type: kpis
+               metrics: [cpu-boost, cpu-voltages, fan-rpm]
+```
+
+## See also
+
+- [media](../media/README.md) — same addon pattern (no config, polls OS)
+- [brightness](../brightness/README.md) — same polling pattern; brightness is
+  just a one-button metric
+- [value-display](../value-display/README.md) — same polling pattern, but
+  for built-in OS metrics via shell commands
+- [date-time](../date-time/README.md) — sibling addon for time/date buttons

package/src/builtin-addons/system-status/buttons/_shared.ts

@@ -0,0 +1,131 @@
+import { useAddonChannel } from "@/api/react"
+
+import {
+  METRICS_CATALOG,
+  SYSTEM_METRIC_IDS,
+  type SystemMetricId,
+  type SystemMetricSnapshot,
+} from "../shared/metrics-catalog"
+
+export interface MetricPayload {
+  available: boolean
+  value?: number
+  percentage?: number
+  max?: number
+  unit?: string
+}
+
+export function readSnapshot(
+  payload: MetricPayload | undefined,
+  id: SystemMetricId,
+): SystemMetricSnapshot {
+  if (!payload)
+    return { available: false, id, label: METRICS_CATALOG[id].defaultLabel }
+  return {
+    available: payload.available,
+    id,
+    label: METRICS_CATALOG[id].defaultLabel,
+    ...(payload.max !== undefined ? { max: payload.max } : {}),
+    ...(payload.percentage !== undefined
+      ? { percentage: payload.percentage }
+      : {}),
+    ...(payload.unit !== undefined ? { unit: payload.unit } : {}),
+    ...(payload.value !== undefined ? { value: payload.value } : {}),
+  }
+}
+
+export function useAllMetricChannels(): Record<
+  SystemMetricId,
+  MetricPayload | undefined
+> {
+  const cpu = useAddonChannel<MetricPayload>("runtime:system-status:cpu")
+  const ram = useAddonChannel<MetricPayload>("runtime:system-status:ram")
+  const swap = useAddonChannel<MetricPayload>("runtime:system-status:swap")
+  const disk = useAddonChannel<MetricPayload>("runtime:system-status:disk")
+  const network = useAddonChannel<MetricPayload>(
+    "runtime:system-status:network",
+  )
+  const battery = useAddonChannel<MetricPayload>(
+    "runtime:system-status:battery",
+  )
+  const temperature = useAddonChannel<MetricPayload>(
+    "runtime:system-status:temperature",
+  )
+  const uptime = useAddonChannel<MetricPayload>("runtime:system-status:uptime")
+  const frequency = useAddonChannel<MetricPayload>(
+    "runtime:system-status:frequency",
+  )
+  const load = useAddonChannel<MetricPayload>("runtime:system-status:load")
+  const processes = useAddonChannel<MetricPayload>(
+    "runtime:system-status:processes",
+  )
+  const cpuBoost = useAddonChannel<MetricPayload>(
+    "runtime:system-status:cpu-boost",
+  )
+  const cpuVoltages = useAddonChannel<MetricPayload>(
+    "runtime:system-status:cpu-voltages",
+  )
+  const diskIo = useAddonChannel<MetricPayload>("runtime:system-status:disk-io")
+  const fanRpm = useAddonChannel<MetricPayload>("runtime:system-status:fan-rpm")
+  const gpuTemp = useAddonChannel<MetricPayload>(
+    "runtime:system-status:gpu-temp",
+  )
+  const gpuUsage = useAddonChannel<MetricPayload>(
+    "runtime:system-status:gpu-usage",
+  )
+  const networkRead = useAddonChannel<MetricPayload>(
+    "runtime:system-status:network-read",
+  )
+  const networkWrite = useAddonChannel<MetricPayload>(
+    "runtime:system-status:network-write",
+  )
+  return {
+    cpu: cpu.data,
+    ram: ram.data,
+    swap: swap.data,
+    disk: disk.data,
+    network: network.data,
+    battery: battery.data,
+    temperature: temperature.data,
+    uptime: uptime.data,
+    frequency: frequency.data,
+    load: load.data,
+    processes: processes.data,
+    "cpu-boost": cpuBoost.data,
+    "cpu-voltages": cpuVoltages.data,
+    "disk-io": diskIo.data,
+    "fan-rpm": fanRpm.data,
+    "gpu-temp": gpuTemp.data,
+    "gpu-usage": gpuUsage.data,
+    "network-read": networkRead.data,
+    "network-write": networkWrite.data,
+  }
+}
+
+const isMetricId = (id: string): id is SystemMetricId =>
+  (SYSTEM_METRIC_IDS as readonly string[]).includes(id)
+
+export function resolveMetricId(entry: unknown): SystemMetricId | null {
+  if (typeof entry === "string") return isMetricId(entry) ? entry : null
+  if (entry && typeof entry === "object" && "id" in entry) {
+    const id = (entry as { id: unknown }).id
+    if (typeof id === "string" && isMetricId(id)) return id
+  }
+  return null
+}
+
+export function pickLabel(entry: unknown, fallback: string): string {
+  if (entry && typeof entry === "object" && "label" in entry) {
+    const value = (entry as { label?: unknown }).label
+    if (typeof value === "string" && value.length > 0) return value
+  }
+  return fallback
+}
+
+export function pickShortLabel(entry: unknown, fallback: string): string {
+  if (entry && typeof entry === "object" && "shortLabel" in entry) {
+    const value = (entry as { shortLabel?: unknown }).shortLabel
+    if (typeof value === "string" && value.length > 0) return value
+  }
+  return fallback
+}