@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/builtin-addons/system-status/buttons/system-status/frontend.tsx

@@ -0,0 +1,224 @@
+import type { AddonFrontendButton } from "@/addon/api"
+import { useAddonChannel } from "@/api/react"
+import {
+  BarsSurface,
+  LabelValueListSurface,
+  PaginatedSurface,
+  ValueChart,
+  type BarsItem,
+  type LabelValueListLine,
+  type PaginatedPage,
+  type ValueChartPoint,
+  type ValueChartSeries,
+} from "@/ui/index"
+import type { ReactElement } from "react"
+
+import {
+  CHART_HISTORY_CHANNEL,
+  resolveThresholdColor,
+  thresholdColorHex,
+  toDisplayMetric,
+  type ChartSamplerState,
+} from "../../domain"
+import { MetricColor, METRICS_CATALOG } from "../../shared/metrics-catalog"
+import {
+  pickLabel,
+  readSnapshot,
+  resolveMetricId,
+  useAllMetricChannels,
+} from "../_shared"
+import type { SystemPageConfig, SystemStatusConfig } from "./schemas"
+
+function pctFromDisplay(
+  value: number | undefined,
+  percentage: number | undefined,
+  maxValue: number,
+): number {
+  if (percentage !== undefined) return Math.min(100, Math.max(0, percentage))
+  if (value === undefined || maxValue <= 0) return 0
+  return Math.min(100, Math.max(0, Math.round((value / maxValue) * 100)))
+}
+
+function BarsPage({ metrics }: Extract<SystemPageConfig, { type: "bars" }>) {
+  const channels = useAllMetricChannels()
+  const useIconInsteadOfTitle = metrics.length === 3
+
+  const items: BarsItem[] = []
+  for (const entry of metrics) {
+    const id = resolveMetricId(entry)
+    if (id === null) continue
+    const def = METRICS_CATALOG[id]
+    if (!def) continue
+    if (!def.views.includes("bars")) continue
+    const maxValue = def.maxValue ?? 100
+    const display = toDisplayMetric(readSnapshot(channels[id], id))
+    const color = thresholdColorHex(
+      resolveThresholdColor(display.value ?? 0, def.thresholds) as MetricColor,
+    )
+    const pct = pctFromDisplay(display.value, display.percentage, maxValue)
+    items.push({
+      title: useIconInsteadOfTitle ? "" : pickLabel(entry, def.defaultLabel),
+      ...(def.icon ? { titleIcon: def.icon } : {}),
+      value: pct,
+      maxValue,
+      displayValue: display.formattedValue,
+      ...(display.unit ? { units: display.unit } : {}),
+      color,
+    })
+  }
+
+  type BarsTuple =
+    | readonly [BarsItem]
+    | readonly [BarsItem, BarsItem]
+    | readonly [BarsItem, BarsItem, BarsItem]
+
+  if (items.length === 0) return <div className="h-full w-full" />
+  const tuple: BarsTuple =
+    items.length === 1
+      ? [items[0]!]
+      : items.length === 2
+        ? [items[0]!, items[1]!]
+        : [items[0]!, items[1]!, items[2]!]
+
+  return (
+    <div className="h-full w-full p-1">
+      <BarsSurface items={tuple} barMaxWidthClass="max-w-[40px]" />
+    </div>
+  )
+}
+
+function KpisPage({ metrics }: Extract<SystemPageConfig, { type: "kpis" }>) {
+  const channels = useAllMetricChannels()
+
+  const lines: LabelValueListLine[] = []
+  for (const entry of metrics) {
+    const id = resolveMetricId(entry)
+    if (id === null) continue
+    const def = METRICS_CATALOG[id]
+    if (!def) continue
+    const display = toDisplayMetric(readSnapshot(channels[id], id))
+    const color = thresholdColorHex(
+      resolveThresholdColor(display.value ?? 0, def.thresholds) as MetricColor,
+    )
+    lines.push({
+      ...(def.icon ? { icon: def.icon } : {}),
+      label: pickLabel(entry, def.defaultLabel),
+      value: display.formattedValue,
+      ...(display.unit ? { units: display.unit } : {}),
+      ...(display.unitLong ? { unitLong: display.unitLong } : {}),
+      ...(color ? { color } : {}),
+    })
+  }
+
+  type LinesTuple =
+    | readonly [LabelValueListLine]
+    | readonly [LabelValueListLine, LabelValueListLine]
+    | readonly [LabelValueListLine, LabelValueListLine, LabelValueListLine]
+
+  if (lines.length === 0) return <div className="h-full w-full" />
+  const tuple: LinesTuple =
+    lines.length === 1
+      ? [lines[0]!]
+      : lines.length === 2
+        ? [lines[0]!, lines[1]!]
+        : [lines[0]!, lines[1]!, lines[2]!]
+
+  return <LabelValueListSurface lines={tuple} />
+}
+
+function ChartPage({
+  metrics,
+  windowSeconds,
+}: Extract<SystemPageConfig, { type: "chart" }>) {
+  const { data: history } = useAddonChannel<ChartSamplerState>(
+    CHART_HISTORY_CHANNEL,
+  )
+  const channels = useAllMetricChannels()
+
+  const series: ValueChartSeries[] = metrics.flatMap((entry) => {
+    const id = resolveMetricId(entry)
+    if (id === null) return []
+    const def = METRICS_CATALOG[id]
+    if (!def) return []
+    if (!def.views.includes("chart")) return []
+
+    const rawSamples = history?.samples[id] ?? []
+    const now = Date.now()
+    const windowMs = windowSeconds * 1000
+    const clipped: ValueChartPoint[] = []
+    for (const s of rawSamples) {
+      if (s.at >= now - windowMs) clipped.push(s)
+    }
+
+    const latest = toDisplayMetric(readSnapshot(channels[id], id))
+    const yMax = Math.max(def.maxValue ?? 0, ...clipped.map((p) => p.value), 1)
+
+    return [
+      {
+        id,
+        color:
+          thresholdColorHex(
+            resolveThresholdColor(
+              latest.value ?? 0,
+              def.thresholds,
+            ) as MetricColor,
+          ) ?? "var(--sireno-color-primary)",
+        icon: def.icon ?? "icon://activity",
+        ...(typeof entry === "object" && entry.label
+          ? { label: entry.label }
+          : {}),
+        ...(latest.unit ? { unit: latest.unit } : {}),
+        points: clipped,
+        yMax,
+      },
+    ]
+  })
+
+  type ChartTuple =
+    | readonly [ValueChartSeries]
+    | readonly [ValueChartSeries, ValueChartSeries]
+
+  if (series.length === 0) return <div className="h-full w-full" />
+  const tuple: ChartTuple =
+    series.length === 1 ? [series[0]!] : [series[0]!, series[1]!]
+
+  return (
+    <div className="h-full -mx-1">
+      <ValueChart series={tuple} windowSeconds={windowSeconds} />
+    </div>
+  )
+}
+
+const PAGE_COMPONENTS: {
+  [K in SystemPageConfig["type"]]: (
+    props: Extract<SystemPageConfig, { type: K }>,
+  ) => ReactElement
+} = {
+  bars: BarsPage,
+  kpis: KpisPage,
+  chart: ChartPage,
+}
+
+const SystemStatusFrontend: AddonFrontendButton<SystemStatusConfig> = ({
+  config,
+  gesture,
+}) => {
+  const rawPages = (
+    Array.isArray(config.pages)
+      ? config.pages
+      : config.pages != null
+        ? [config.pages]
+        : [config as unknown as SystemPageConfig]
+  ) as SystemPageConfig[]
+
+  const pages: PaginatedPage<SystemPageConfig>[] = rawPages.map((page) => ({
+    render: PAGE_COMPONENTS[page.type] as (
+      props: SystemPageConfig,
+    ) => ReactElement,
+    config: page,
+  }))
+
+  return <PaginatedSurface pages={pages} gesture={gesture} />
+}
+
+export default SystemStatusFrontend

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

@@ -0,0 +1,67 @@
+import { z } from "zod"
+
+import { pagesSchema } from "@/ui/index"
+
+import {
+  SYSTEM_METRIC_IDS,
+  type SystemMetricId,
+} from "../../shared/metrics-catalog"
+
+export const MetricEntrySchema = z
+  .union([
+    z.enum(SYSTEM_METRIC_IDS),
+    z
+      .object({
+        id: z.enum(SYSTEM_METRIC_IDS),
+        label: z.string().min(1).optional(),
+        shortLabel: z.string().min(1).max(3).optional(),
+      })
+      .strict(),
+  ])
+  .transform(
+    (entry): { id: SystemMetricId; label?: string; shortLabel?: string } =>
+      typeof entry === "string"
+        ? { id: entry }
+        : {
+            id: entry.id,
+            ...(entry.label !== undefined ? { label: entry.label } : {}),
+            ...(entry.shortLabel !== undefined
+              ? { shortLabel: entry.shortLabel }
+              : {}),
+          },
+  )
+
+export const BarPageSchema = z
+  .object({
+    type: z.literal("bars"),
+    metrics: z.array(MetricEntrySchema).min(1).max(3),
+  })
+  .strict()
+
+export const KpiPageSchema = z
+  .object({
+    type: z.literal("kpis"),
+    metrics: z.array(MetricEntrySchema).min(1).max(3),
+  })
+  .strict()
+
+export const ChartPageSchema = z
+  .object({
+    type: z.literal("chart"),
+    metrics: z.array(MetricEntrySchema).min(1).max(2),
+    windowSeconds: z.number().int().positive().max(60).default(60),
+  })
+  .strict()
+
+export const PageSchema = z.discriminatedUnion("type", [
+  BarPageSchema,
+  KpiPageSchema,
+  ChartPageSchema,
+])
+
+export const SystemStatusConfigSchema = pagesSchema(PageSchema)
+
+export type SystemStatusConfig = z.infer<typeof SystemStatusConfigSchema>
+export type SystemPageConfig = z.infer<typeof PageSchema>
+
+export const POLL_INTERVAL_MS = 1000 as const

package/src/builtin-addons/system-status/domain/catalog.ts

@@ -0,0 +1,53 @@
+import {
+  METRICS_CATALOG,
+  SYSTEM_METRIC_IDS,
+  type MetricColor,
+  type MetricThreshold,
+} from "../shared/metrics-catalog"
+
+export { SYSTEM_METRIC_IDS }
+
+if (
+  Object.keys(METRICS_CATALOG).sort().join(",") !==
+  [...SYSTEM_METRIC_IDS].sort().join(",")
+) {
+  throw new Error(
+    "METRICS_CATALOG drift: every SystemMetricId must have a MetricDef",
+  )
+}
+
+/**
+ * Resolve the threshold color for a given value. Both bounds are inclusive.
+ * When multiple thresholds match, the **last defined** one wins — let users
+ * stack thresholds from broad to narrow without surprise overrides.
+ */
+export function resolveThresholdColor(
+  value: number,
+  thresholds?: ReadonlyArray<MetricThreshold>,
+): MetricColor {
+  if (thresholds === undefined || thresholds.length === 0) return "default"
+  let result: MetricColor = "default"
+  for (const t of thresholds) {
+    const min = t.minValue ?? -Infinity
+    const max = t.maxValue ?? Infinity
+    if (value >= min && value <= max) result = t.color
+  }
+  return result
+}
+
+/**
+ * Convert a MetricColor to a CSS-color string for the UI surfaces.
+ * `default` returns undefined — the surface keeps its own primary color.
+ */
+export function thresholdColorHex(color: MetricColor): string | undefined {
+  switch (color) {
+    case "danger":
+      return "#ef4444"
+    case "warning":
+      return "#f59e0b"
+    case "success":
+      return "#22c55e"
+    case "default":
+      return undefined
+  }
+}

package/src/builtin-addons/system-status/domain/chart-sampler.ts

@@ -0,0 +1,58 @@
+import { SystemMetricId } from "../shared/metrics-catalog"
+
+export interface ChartSample {
+  at: number
+  value: number
+}
+
+export type ChartSamplerState = {
+  samples: Partial<Record<SystemMetricId, ReadonlyArray<ChartSample>>>
+}
+
+export const RING_CAPACITY = 60
+export const CHART_HISTORY_CHANNEL = "runtime:system-status:chart-history"
+
+function createRingBuffer(): {
+  feed: (id: SystemMetricId, value: number, at: number) => void
+  state: () => ChartSamplerState
+} {
+  const buffers = new Map<SystemMetricId, ChartSample[]>()
+
+  const feed = (id: SystemMetricId, value: number, at: number): void => {
+    let buf = buffers.get(id)
+    if (buf === undefined) {
+      buf = []
+      buffers.set(id, buf)
+    }
+    buf.push({ at, value })
+    if (buf.length > RING_CAPACITY) buf.shift()
+  }
+
+  const state = (): ChartSamplerState => {
+    const samples: Record<string, ReadonlyArray<ChartSample>> = {}
+    for (const [id, buf] of buffers) samples[id] = buf
+    return { samples }
+  }
+
+  return { feed, state }
+}
+
+let sampler: ReturnType<typeof createRingBuffer> | null = null
+
+export function feedSampler(
+  id: SystemMetricId,
+  value: number,
+  at: number,
+): void {
+  if (sampler === null) sampler = createRingBuffer()
+  sampler.feed(id, value, at)
+}
+
+export function getSamplerState(): ChartSamplerState {
+  if (sampler === null) return { samples: {} }
+  return sampler.state()
+}
+
+export function resetSampler(): void {
+  sampler = null
+}

package/src/builtin-addons/system-status/domain/display-metrics.ts

@@ -0,0 +1,128 @@
+import {
+  type DisplayMetric,
+  FormattedValue,
+  MetricFormatter,
+  METRICS_CATALOG,
+  type SystemMetricSnapshot,
+} from "../shared/metrics-catalog"
+
+function formatBytes(value: number): FormattedValue {
+  if (value < 1024) return { value: String(value), unit: "B" }
+  if (value < 1024 ** 2) return { value: (value / 1024).toFixed(1), unit: "KB" }
+  if (value < 1024 ** 3)
+    return { value: (value / 1024 ** 2).toFixed(1), unit: "MB" }
+  if (value < 1024 ** 4)
+    return { value: (value / 1024 ** 3).toFixed(1), unit: "GB" }
+  return { value: (value / 1024 ** 4).toFixed(1), unit: "TB" }
+}
+
+function formatRateBytes(value: number): FormattedValue {
+  const v = Math.max(0, value)
+  if (v < 1024) return { value: String(Math.round(v)), unit: "B/s" }
+  if (v < 1024 ** 2) return { value: (v / 1024).toFixed(1), unit: "KB/s" }
+  if (v < 1024 ** 3) return { value: (v / 1024 ** 2).toFixed(1), unit: "MB/s" }
+  if (v < 1024 ** 4) return { value: (v / 1024 ** 3).toFixed(1), unit: "GB/s" }
+  return { value: (v / 1024 ** 4).toFixed(1), unit: "TB/s" }
+}
+
+function formatBool(value: number): FormattedValue {
+  return { value: value >= 0.5 ? "ON" : "OFF" }
+}
+
+function formatUptime(totalSeconds: number): FormattedValue {
+  const s = Math.max(0, Math.round(totalSeconds))
+  const days = Math.floor(s / (24 * 60 * 60))
+  const hours = Math.floor(s / (60 * 60))
+  const minutes = Math.floor((s % 3600) / 60)
+
+  if (days > 0) return { value: String(days), unit: "d", unitLong: "days" }
+  if (hours > 0) return { value: String(hours), unit: "h", unitLong: "hours" }
+  return { value: String(minutes), unit: "m", unitLong: "minutes" }
+}
+
+function formatValue(
+  value: number,
+  formatter: MetricFormatter | undefined,
+): FormattedValue {
+  switch (formatter) {
+    case "bytes":
+      return formatBytes(value)
+    case "bool":
+      return formatBool(value)
+    case "count":
+      return {
+        value: value.toFixed(0),
+      }
+    case "frequency-ghz":
+      return { value: value.toFixed(2) }
+    case "percent":
+      // ponytail: integers when stable, one decimal when low. High values
+      // (10%+) hide <1% swing behind integer rounding; low values benefit
+      // from precision so a 0.4% idle actually shows as movement.
+      return value < 10
+        ? { value: value.toFixed(1), unit: "%" }
+        : { value: String(Math.round(value)), unit: "%" }
+    case "rate-bytes":
+      return formatRateBytes(value)
+    case "uptime":
+      return formatUptime(value)
+    default:
+      return { value: String(value) }
+  }
+}
+
+export function resolveFormatter(
+  name: string | undefined,
+): MetricFormatter | undefined {
+  if (!name) return undefined
+  const allowed: MetricFormatter[] = [
+    "bytes",
+    "bool",
+    "count",
+    "frequency-ghz",
+    "percent",
+    "rate-bytes",
+    "uptime",
+  ]
+  return (allowed as string[]).includes(name)
+    ? (name as MetricFormatter)
+    : undefined
+}
+
+export function toDisplayMetric(
+  snapshot: SystemMetricSnapshot,
+  formatterName?: string,
+): DisplayMetric {
+  const def = METRICS_CATALOG[snapshot.id]!
+  const formatter = resolveFormatter(formatterName) ?? def.formatter
+  if (!snapshot.available || snapshot.value === undefined) {
+    // ponytail: the comment that used to sit here claimed the unit is dropped
+    // so the renderer shows "—" alone, never "— °C". The code has always done
+    // the opposite, and display-rate-bytes-formatter.test.ts explicitly pins
+    // the unit being KEPT ("— B/s"). Two contradictory intents; the test wins,
+    // so the behaviour stands and the misleading comment is gone. If the
+    // intent really is a bare "—", that is a deliberate UI change with a test
+    // to update, not a silent fix.
+    return {
+      id: snapshot.id,
+      label: def.defaultLabel,
+      available: false,
+      formattedValue: "—",
+      unit: def.unit ?? snapshot.unit,
+    }
+  }
+  const formatted = formatValue(snapshot.value, formatter)
+  return {
+    id: snapshot.id,
+    label: def.defaultLabel,
+    available: true,
+    formattedValue: formatted.value,
+    unit: formatted.unit ?? def.unit ?? snapshot.unit,
+    ...(formatted.unitLong ? { unitLong: formatted.unitLong } : {}),
+    value: snapshot.value,
+    ...(snapshot.max !== undefined ? { max: snapshot.max } : {}),
+    ...(snapshot.percentage !== undefined
+      ? { percentage: snapshot.percentage }
+      : {}),
+  }
+}

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

@@ -0,0 +1,10 @@
+export { resolveThresholdColor, thresholdColorHex } from "./catalog"
+export {
+  CHART_HISTORY_CHANNEL,
+  feedSampler,
+  getSamplerState,
+  resetSampler,
+  RING_CAPACITY,
+} from "./chart-sampler"
+export type { ChartSample, ChartSamplerState } from "./chart-sampler"
+export { resolveFormatter, toDisplayMetric } from "./display-metrics"