@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/builtin-addons/system-status/index.ts

@@ -0,0 +1,16 @@
+import type { AddonRegistry } from "@/addon/registry"
+import { systemStatusManifest } from "./manifest"
+
+export const registerSystemStatusAddon = (registry: AddonRegistry): void => {
+  registry.load(systemStatusManifest)
+}
+
+export {
+  POLL_INTERVAL_MS,
+  SystemStatusConfigSchema,
+  SYSTEM_METRIC_IDS,
+  systemStatusAddon,
+  systemStatusManifest,
+} from "./manifest"
+export type { SystemStatusConfig, SystemMetricId } from "./manifest"
+export default systemStatusManifest

package/src/builtin-addons/system-status/manifest.ts

@@ -0,0 +1,105 @@
+import type { AddonGlobalPoller, AddonManifestV1 } from "@/addon/api"
+
+import systemStatusFrontend from "./buttons/system-status/frontend"
+import {
+  POLL_INTERVAL_MS,
+  SystemStatusConfigSchema,
+  type SystemStatusConfig,
+} from "./buttons/system-status/schemas"
+import { CHART_HISTORY_CHANNEL } from "./domain"
+import {
+  SYSTEM_METRIC_IDS,
+  type SystemMetricId,
+} from "./shared/metrics-catalog"
+
+// ponytail: pollers are server-only; lazy-import live-metrics so the manifest
+// can be loaded by the frontend addon virtual module without dragging
+// node:os / node:fs into the browser bundle.
+function makePoller(metricId: SystemMetricId): AddonGlobalPoller {
+  return {
+    id: `metric:${metricId}`,
+    channel: `runtime:system-status:${metricId}`,
+    // ponytail: one cadence for all metrics. POLL_INTERVAL_MS
+    // is the single source of truth. Per-button overrides would require moving
+    // polling into per-button onMount handlers (multiple buttons on the same
+    // metric would race on one channel); not worth the refactor today.
+    intervalMs: POLL_INTERVAL_MS,
+    poll: async () => {
+      const { probeMetric } = await import("./domain/live-metrics")
+      const result = await probeMetric(metricId)
+      if (result.value !== undefined && result.available) {
+        const { feedSampler } = await import("./domain/chart-sampler")
+        feedSampler(metricId, result.value, Date.now())
+      }
+      return result
+    },
+  }
+}
+
+export const systemStatusManifest: AddonManifestV1 = {
+  apiVersion: 1,
+  name: "system-status",
+  buttonTypes: {
+    "system-status:system-status": {
+      frontend: systemStatusFrontend,
+      service: {
+        configSchema: SystemStatusConfigSchema,
+        internal: false,
+        gestureHandlers: ["tap"] as const,
+      },
+    },
+  },
+  globalService: {
+    pollers: [
+      ...SYSTEM_METRIC_IDS.map(makePoller),
+      {
+        id: "metric:chart-history",
+        channel: CHART_HISTORY_CHANNEL,
+        intervalMs: POLL_INTERVAL_MS,
+        poll: async () => {
+          const { getSamplerState } = await import("./domain/chart-sampler")
+          return getSamplerState()
+        },
+      },
+    ],
+  },
+  checks: [
+    {
+      // ponytail: mirrors the media addon's media-control check. On Apple
+      // Silicon, CPU/GPU temperature and fan RPM have no unprivileged source
+      // from the tools already in use here — powermetrics needs root and the
+      // only readable Temperature in ioreg is the battery's. macmon reads them
+      // through IOReport without sudo. Absent, those three metrics simply stay
+      // unavailable, so this is a hint rather than a hard requirement.
+      name: "macos-sensors",
+      check: async () => {
+        if (process.platform !== "darwin") return { available: true }
+        const { execFile } = await import("node:child_process")
+        const { promisify } = await import("node:util")
+        try {
+          await promisify(execFile)("sh", ["-c", "command -v macmon"], {
+            timeout: 2_000,
+          })
+          return { available: true }
+        } catch {
+          return {
+            available: false,
+            reason:
+              "install macmon (`brew install macmon`) to report CPU/GPU temperature and fan RPM; without it those three metrics stay unavailable on Apple Silicon",
+          }
+        }
+      },
+    },
+  ],
+}
+
+export const systemStatusAddon = systemStatusManifest
+export default systemStatusManifest
+
+export {
+  POLL_INTERVAL_MS,
+  SystemStatusConfigSchema,
+  SYSTEM_METRIC_IDS,
+  type SystemStatusConfig,
+}
+export type { SystemMetricId }

package/src/builtin-addons/system-status/shared/metrics-catalog.ts

@@ -0,0 +1,316 @@
+export type MetricFormatter =
+  | "bytes"
+  | "bool"
+  | "count"
+  | "frequency-ghz"
+  | "percent"
+  | "rate-bytes"
+  | "uptime"
+
+// ponytail: formatters emit value-only; the unit lives in `DisplayMetric.unit`
+// so the renderer can style the value and the unit independently (e.g. bigger
+// digits + smaller "%" suffix). When the unit is magnitude-dependent (bytes,
+// rate-bytes, uptime) the formatter picks the right scale and returns both halves.
+export interface FormattedValue {
+  value: string
+  unit?: string
+  unitLong?: string
+}
+
+export type MetricView = "bars" | "chart" | "kpis"
+export type MetricColor = "default" | "success" | "warning" | "danger"
+
+export interface MetricThreshold {
+  /** Lower bound, inclusive. Omit for -Infinity. */
+  minValue?: number
+  /** Upper bound, inclusive. Omit for +Infinity. */
+  maxValue?: number
+  color: MetricColor
+}
+
+export interface DisplayMetric {
+  id: SystemMetricId
+  label: string
+  available: boolean
+  // ponytail: numeric/digit portion only — units live in `unit` so the
+  // renderer can style them independently. Magnitude-dependent formatters
+  // (bytes, rate-bytes, uptime) emit a scale-aware unit; static formatters
+  // (percent) emit "%"; magnitude-independent formatters (count,
+  // frequency-ghz, bool) emit no unit and let the probe/catalog supply it.
+  formattedValue: string
+  unit?: string
+  unitLong?: string
+  value?: number
+  max?: number
+  percentage?: number
+}
+
+export interface MetricDef {
+  readonly id: SystemMetricId
+  readonly defaultLabel: string
+  readonly defaultShortLabel?: string
+  readonly icon?: string
+  readonly unit?: string
+  readonly formatter: MetricFormatter
+  readonly views: ReadonlyArray<MetricView>
+  /** Upper bound for bar rendering. Omit when bars aren't supported. */
+  readonly maxValue?: number
+  readonly thresholds?: ReadonlyArray<MetricThreshold>
+}
+
+export interface SystemMetricSnapshot {
+  available: boolean
+  id: SystemMetricId
+  label: string
+  max?: number
+  percentage?: number
+  unit?: string
+  value?: number
+}
+
+export interface MetricConfig {
+  id: SystemMetricId
+  label?: string
+}
+
+export type SystemMetricId =
+  | "battery"
+  | "cpu"
+  | "cpu-boost"
+  | "cpu-voltages"
+  | "disk"
+  | "disk-io"
+  | "fan-rpm"
+  | "frequency"
+  | "gpu-temp"
+  | "gpu-usage"
+  | "load"
+  | "network"
+  | "network-read"
+  | "network-write"
+  | "processes"
+  | "ram"
+  | "swap"
+  | "temperature"
+  | "uptime"
+
+export const METRICS_CATALOG: Readonly<Record<SystemMetricId, MetricDef>> = {
+  cpu: {
+    id: "cpu",
+    defaultLabel: "CPU",
+    defaultShortLabel: "CPU",
+    icon: "icon://cpu",
+    unit: "%",
+    formatter: "percent",
+    views: ["bars", "chart", "kpis"],
+    maxValue: 100,
+    thresholds: [
+      { maxValue: 70, color: "default" },
+      { minValue: 70, maxValue: 90, color: "warning" },
+      { minValue: 90, color: "danger" },
+    ],
+  },
+  ram: {
+    id: "ram",
+    defaultLabel: "RAM",
+    icon: "icon://memory-stick",
+    unit: "%",
+    formatter: "percent",
+    views: ["bars", "chart", "kpis"],
+    maxValue: 100,
+    thresholds: [
+      { maxValue: 70, color: "default" },
+      { minValue: 70, maxValue: 90, color: "warning" },
+      { minValue: 90, color: "danger" },
+    ],
+  },
+  swap: {
+    id: "swap",
+    defaultLabel: "Swap",
+    defaultShortLabel: "SWP",
+    icon: "icon://repeat",
+    unit: "%",
+    formatter: "percent",
+    views: ["bars", "chart", "kpis"],
+    maxValue: 100,
+    thresholds: [
+      { maxValue: 50, color: "default" },
+      { minValue: 50, maxValue: 80, color: "warning" },
+      { minValue: 80, color: "danger" },
+    ],
+  },
+  disk: {
+    id: "disk",
+    defaultLabel: "Disk",
+    defaultShortLabel: "DSK",
+    icon: "icon://hard-drive",
+    unit: "%",
+    formatter: "percent",
+    views: ["bars", "chart", "kpis"],
+    maxValue: 100,
+    thresholds: [
+      { maxValue: 70, color: "default" },
+      { minValue: 70, maxValue: 90, color: "warning" },
+      { minValue: 90, color: "danger" },
+    ],
+  },
+  battery: {
+    id: "battery",
+    defaultLabel: "Battery",
+    defaultShortLabel: "BAT",
+    icon: "icon://battery",
+    unit: "%",
+    formatter: "percent",
+    views: ["bars", "chart", "kpis"],
+    maxValue: 100,
+    thresholds: [
+      { minValue: 40, color: "default" },
+      { minValue: 20, maxValue: 40, color: "warning" },
+      { maxValue: 20, color: "danger" },
+    ],
+  },
+  temperature: {
+    id: "temperature",
+    defaultLabel: "Temp",
+    defaultShortLabel: "TMP",
+    icon: "icon://thermometer",
+    unit: "°C",
+    formatter: "count",
+    views: ["bars", "chart", "kpis"],
+    maxValue: 100,
+    thresholds: [
+      { maxValue: 70, color: "default" },
+      { minValue: 70, maxValue: 85, color: "warning" },
+      { minValue: 85, color: "danger" },
+    ],
+  },
+  frequency: {
+    id: "frequency",
+    defaultLabel: "Freq",
+    defaultShortLabel: "FRQ",
+    icon: "icon://activity",
+    unit: "GHz",
+    formatter: "frequency-ghz",
+    views: ["bars", "chart", "kpis"],
+    maxValue: 5,
+    thresholds: [{ minValue: 4, color: "success" }],
+  },
+  load: {
+    id: "load",
+    defaultLabel: "Load",
+    defaultShortLabel: "LD",
+    icon: "icon://gauge",
+    formatter: "count",
+    views: ["bars", "chart", "kpis"],
+    maxValue: 100,
+    thresholds: [
+      { maxValue: 50, color: "default" },
+      { minValue: 50, maxValue: 80, color: "warning" },
+      { minValue: 80, color: "danger" },
+    ],
+  },
+  // ponytail: these three have no meaningful `maxValue` — bars would lie.
+  // Catalog pins them to kpis-only; the bars frontend renders nothing for
+  // them if a config sneaks them in.
+  processes: {
+    id: "processes",
+    defaultLabel: "Procs",
+    icon: "icon://boxes",
+    formatter: "count",
+    views: ["kpis"],
+  },
+  network: {
+    id: "network",
+    defaultLabel: "Net",
+    icon: "icon://network",
+    formatter: "count",
+    views: ["kpis"],
+  },
+  uptime: {
+    id: "uptime",
+    defaultLabel: "Uptime",
+    icon: "icon://clock",
+    formatter: "uptime",
+    unit: "m",
+    views: ["kpis"],
+  },
+  "cpu-boost": {
+    id: "cpu-boost",
+    defaultLabel: "Boost",
+    icon: "icon://zap",
+    formatter: "bool",
+    views: ["kpis"],
+    thresholds: [{ minValue: 1, maxValue: 1, color: "success" }],
+  },
+  "cpu-voltages": {
+    id: "cpu-voltages",
+    defaultLabel: "Vcore",
+    icon: "icon://bolt",
+    formatter: "count",
+    unit: "V",
+    views: ["kpis"],
+  },
+  "disk-io": {
+    id: "disk-io",
+    defaultLabel: "Disk I/O",
+    icon: "icon://arrow-down-up",
+    formatter: "rate-bytes",
+    views: ["kpis"],
+  },
+  "fan-rpm": {
+    id: "fan-rpm",
+    defaultLabel: "Fan",
+    icon: "icon://fan",
+    formatter: "count",
+    unit: "RPM",
+    views: ["kpis"],
+  },
+  "gpu-temp": {
+    id: "gpu-temp",
+    defaultLabel: "GPU Temp",
+    defaultShortLabel: "GTT",
+    icon: "icon://thermometer-sun",
+    formatter: "count",
+    unit: "°C",
+    views: ["bars", "chart", "kpis"],
+    maxValue: 100,
+    thresholds: [
+      { maxValue: 70, color: "default" },
+      { minValue: 70, maxValue: 85, color: "warning" },
+      { minValue: 85, color: "danger" },
+    ],
+  },
+  "gpu-usage": {
+    id: "gpu-usage",
+    defaultLabel: "GPU",
+    defaultShortLabel: "GPU",
+    icon: "icon://microchip",
+    formatter: "percent",
+    unit: "%",
+    views: ["bars", "chart", "kpis"],
+    maxValue: 100,
+    thresholds: [
+      { maxValue: 70, color: "default" },
+      { minValue: 70, maxValue: 90, color: "warning" },
+      { minValue: 90, color: "danger" },
+    ],
+  },
+  "network-read": {
+    id: "network-read",
+    defaultLabel: "Net RX",
+    icon: "icon://arrow-down",
+    formatter: "rate-bytes",
+    views: ["kpis"],
+  },
+  "network-write": {
+    id: "network-write",
+    defaultLabel: "Net TX",
+    icon: "icon://arrow-up",
+    formatter: "rate-bytes",
+    views: ["kpis"],
+  },
+} as const satisfies Readonly<Record<string, MetricDef>>
+
+export const SYSTEM_METRIC_IDS = Object.keys(
+  METRICS_CATALOG,
+) as SystemMetricId[]

package/src/builtin-addons/system-status/sirenodeck.json

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

package/src/builtin-addons/test-buildin/decks/action-buttons-test.ts

@@ -0,0 +1,56 @@
+import type { AddonDeckEntry } from "@/addon/api"
+
+/**
+ * Action Buttons Test deck — one `core:action` button per icon-source
+ * shape, so a single deck exercises every accepted (and a few rejected)
+ * icon configuration in the validator and runtime.
+ *
+ * The buttons are intentionally simple (no `actions.tap` — they're
+ * static, no-op displays) so tapping them is harmless. Each one's only
+ * job is to render a different icon shape, so the test deck reads as
+ * a visual matrix of "what each icon source renders as".
+ */
+
+const ICON_CASES: ReadonlyArray<{ label: string; icon: string }> = [
+  // Lucide / icon:// — the most common shape
+  { label: "icon://play", icon: "icon://play" },
+  { label: "icon://settings", icon: "icon://settings" },
+  { label: "icon://volume-x", icon: "icon://volume-x" },
+  // Addon asset refs
+  {
+    label: "addon://emoji-selector/assets/smileys.svg",
+    icon: "addon://emoji-selector/assets/smileys.svg",
+  },
+  {
+    label: "addon://emoji-selector/assets/launcher.svg",
+    icon: "addon://emoji-selector/assets/launcher.svg",
+  },
+  // Single emoji
+  { label: "🔥", icon: "🔥" },
+  { label: "✈️", icon: "✈️" },
+  // Edge: empty name in scheme
+  { label: "icon:// (invalid)", icon: "icon://" },
+  // No icon at all (just label) — exercises the label-only path
+  { label: "(no icon)", icon: "" },
+  // Inline data URL (rejected by runtime — must be pre-resolved)
+  { label: "data: (invalid)", icon: "data:image/svg+xml;base64,PHN2Zy8+" },
+]
+
+// ponytail: phase 11 array form. The deck is now a static AddonDeckEntry
+// whose inline shape is the deck itself. No factory needed since the
+// icon cases are baked in.
+const ICON_BUTTONS = ICON_CASES.map(({ label, icon }, i) => ({
+  type: "core:action",
+  position: i,
+  ...(icon !== "" ? { config: { icon, label } } : { config: { label } }),
+}))
+
+const actionButtonsTestDeck: AddonDeckEntry = {
+  id: "test-buildin:action-buttons-test",
+  name: "Action Buttons Test",
+  icon: "🧪",
+  buttons: ICON_BUTTONS,
+}
+
+export default actionButtonsTestDeck
+export { actionButtonsTestDeck }

package/src/builtin-addons/test-buildin/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/test-buildin/index.ts

@@ -0,0 +1,16 @@
+import type { AddonManifestV1 } from "@/addon/api"
+
+import actionButtonsTestDeck from "./decks/action-buttons-test"
+
+export const manifest: AddonManifestV1 = {
+  apiVersion: 1,
+  name: "test-buildin",
+  // No custom buttonTypes — the test deck uses the existing core:action
+  // button type so we can exercise the runtime's icon pipeline without
+  // introducing new backend code.
+  buttonTypes: {},
+  decks: [actionButtonsTestDeck],
+}
+
+export const testBuildinAddon = manifest
+export default manifest

package/src/builtin-addons/value-display/README.md

@@ -0,0 +1,59 @@
+# value-display
+
+Run shell commands and show their output. Useful for showing disk usage, git status, weather (without Open-Meteo), battery percentage (Linux), etc.
+
+Each button has up to 4 `values` entries; each entry runs a command via the action executor and shows its output.
+
+## Buttons
+
+| Type                    | Description                                            |
+| ----------------------- | ------------------------------------------------------ |
+| `value-display:display` | Single button: shows N values (label + command output) |
+
+## Config
+
+```yaml
+- position: 6
+  type: value-display:display
+  config:
+    poll_interval_ms: 5000 # optional, default 5000
+    timeout_ms: 5000 # optional, default 5000 (per command)
+    values:
+      - label: Disk
+        command: "df -h / | tail -1 | awk '{print $5}'"
+        formatter: strip # "raw" (default), "strip", or "line"
+        units: "%"
+      - label: Uptime
+        command: "uptime -p"
+        formatter: strip
+      - label: CPU Temp
+        command: "sensors | grep 'Core 0' | awk '{print $3}'"
+        timeout_ms: 2000
+```
+
+### Formatters
+
+| Formatter | Behavior                                            |
+| --------- | --------------------------------------------------- |
+| `raw`     | Output the command's stdout verbatim                |
+| `strip`   | Trim leading/trailing whitespace                    |
+| `line`    | Take only the first non-empty line, trim whitespace |
+
+## Example
+
+```yaml
+- position: 6
+  type: value-display:display
+  config:
+    values:
+      - label: Disk
+        command: "df -h / | tail -1 | awk '{print $5}'"
+        units: "%"
+      - label: CPU Temp
+        command: "sensors | grep 'Core 0' | awk '{print $3}'"
+```
+
+## See also
+
+- [weather](../weather/README.md) — `weather:weather` is a wrapper around Open-Meteo; `value-display:display` is the manual version
+- [system-status](../system-status/README.md) — same polling pattern, but for built-in OS metrics

package/src/builtin-addons/value-display/backend.ts

@@ -0,0 +1,86 @@
+import type { AddonServiceContext, AddonGlobalService } from "@/addon/api"
+
+import type { ConfigSchema } from "./buttons/value-display/config"
+
+const DEFAULT_POLL_MS = 5000
+
+const buttonRegistry = new Map<string, ConfigSchema>()
+let ctxRef: AddonServiceContext | undefined
+
+export const globalService: AddonGlobalService = {
+  methods: {
+    registerValues: (buttonId: unknown, config: unknown): void => {
+      buttonRegistry.set(String(buttonId), config as ConfigSchema)
+      ctxRef?.poll("values")
+    },
+    unregisterValues: (buttonId: unknown): void => {
+      buttonRegistry.delete(String(buttonId))
+    },
+  },
+  pollers: [
+    {
+      id: "values",
+      channel: "value-display:values",
+      intervalMs: DEFAULT_POLL_MS,
+      poll: async (ctx: AddonServiceContext) => {
+        const byButton: Record<
+          string,
+          Array<{
+            label: string
+            value: string
+            units?: string
+          }>
+        > = {}
+        if (buttonRegistry.size === 0) return { byButton }
+
+        await Promise.all(
+          [...buttonRegistry.entries()].map(async ([buttonId, config]) => {
+            const results = await Promise.all(
+              config.values.map(async (entry) => {
+                try {
+                  const res = await ctx.executor.run(entry.command, {
+                    timeoutMs: entry.timeout_ms ?? config.timeout_ms,
+                  })
+                  const raw = res.stdout ?? ""
+                  let value: string
+                  switch (entry.formatter) {
+                    case "strip":
+                      value = raw.replace(/\s+$/, "")
+                      break
+                    case "line":
+                      value = (
+                        raw.indexOf("\n") === -1
+                          ? raw
+                          : raw.slice(0, raw.indexOf("\n"))
+                      ).trim()
+                      break
+                    case "raw":
+                    default:
+                      value = raw.trim()
+                      break
+                  }
+                  return { label: entry.label, value, units: entry.units }
+                } catch {
+                  return {
+                    label: entry.label,
+                    value: "err",
+                    units: entry.units,
+                  }
+                }
+              }),
+            )
+            byButton[buttonId] = results
+          }),
+        )
+        return { byButton }
+      },
+    },
+  ],
+  onLoad: async (ctx: AddonServiceContext) => {
+    ctxRef = ctx
+  },
+  onUnload: () => {
+    ctxRef = undefined
+    buttonRegistry.clear()
+  },
+}

package/src/builtin-addons/value-display/buttons/value-display/backend.ts

@@ -0,0 +1,17 @@
+import type {
+  AddonButtonServiceContext,
+  AddonButtonTypeService,
+} from "@/addon/api"
+
+import { configSchema, type ConfigSchema } from "./config"
+
+export default {
+  configSchema,
+  onMount: (ctx: AddonButtonServiceContext<ConfigSchema>) => {
+    ctx.methods["value-display:registerValues"]?.(ctx.buttonId, ctx.config)
+  },
+  dispose: (ctx: AddonButtonServiceContext<ConfigSchema>) => {
+    ctx.methods["value-display:unregisterValues"]?.(ctx.buttonId)
+  },
+  defaultRenderIntervalMs: 5000,
+} satisfies AddonButtonTypeService<ConfigSchema>