@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/builtin-addons/core/buttons/toggle/frontend.tsx

@@ -0,0 +1,57 @@
+import { useAddonChannel } from "@/api/react"
+import { IconLabelSurface } from "@/ui/surfaces/IconLabelSurface"
+import { Text } from "@/ui/primitives/Text"
+import type { AddonFrontendButton } from "@/addon/api"
+
+import type { ConfigSchema, StatusToggleConfig } from "./config"
+import { isLegacyToggleConfig, isStatusToggleConfig } from "./config"
+import {
+  TOGGLE_STATES_CHANNEL,
+  type ToggleStatesPayload,
+} from "./global-service"
+
+const fallback = (label: string): React.ReactElement => (
+  <Text tone="muted" text={label} />
+)
+
+const ToggleButtonFrontend: AddonFrontendButton<ConfigSchema> = ({
+  config,
+  buttonId,
+}) => {
+  if (isLegacyToggleConfig(config)) {
+    return fallback("—")
+  }
+  if (!isStatusToggleConfig(config)) {
+    return fallback("—")
+  }
+  return <StatusToggleRenderer config={config} buttonId={buttonId} />
+}
+
+function StatusToggleRenderer({
+  config,
+  buttonId,
+}: {
+  config: StatusToggleConfig
+  buttonId: string
+}) {
+  const { data } = useAddonChannel<ToggleStatesPayload>(TOGGLE_STATES_CHANNEL)
+  const entry = data?.byButton[buttonId] ?? undefined
+  if (entry === undefined || entry === null) {
+    return fallback("…")
+  }
+  if (entry.error !== undefined) {
+    return fallback("err")
+  }
+  const matched =
+    entry.state !== undefined ? config.states[entry.state] : undefined
+  if (matched !== undefined) {
+    const label = matched.label ?? entry.state ?? ""
+    return <IconLabelSurface source={matched.icon} label={label} />
+  }
+  if (entry.raw.length === 0) {
+    return fallback("…")
+  }
+  return fallback(entry.raw)
+}
+
+export default ToggleButtonFrontend

package/src/builtin-addons/core/buttons/toggle/global-service.ts

@@ -0,0 +1,174 @@
+import type { AddonServiceContext, AddonGlobalService } from "@/addon/api"
+
+import {
+  TOGGLE_DEFAULT_INTERVAL_MS,
+  TOGGLE_DEFAULT_TIMEOUT_MS,
+  type StatusToggleConfig,
+} from "./config"
+
+export const TOGGLE_STATES_CHANNEL = "core:toggle:states"
+export const TOGGLE_POLL_TICK_MS = 1000
+
+export interface ToggleState {
+  readonly raw: string
+  readonly state: string | undefined
+  readonly error?: string
+  readonly at: number
+}
+
+export interface ToggleStatesPayload {
+  readonly byButton: Readonly<Record<string, ToggleState | null>>
+}
+
+interface ButtonEntry {
+  readonly config: StatusToggleConfig
+  lastRaw: string | undefined
+  lastState: string | undefined
+  lastError: string | undefined
+  lastAt: number
+  lastPolledAt: number
+}
+
+const registry = new Map<string, ButtonEntry>()
+let ctxRef: AddonServiceContext | undefined
+
+const trim = (value: string): string => value.replace(/\s+$/, "").trim()
+
+const pollButton = async (
+  entry: ButtonEntry,
+  ctx: AddonServiceContext,
+): Promise<ToggleState> => {
+  // ponytail: defaults are merged here so the global poller can use the
+  // per-button override without the schema forcing an `.default()` (which
+  // would erase the override path inside the union).
+  const timeoutMs = entry.config.timeoutMs ?? TOGGLE_DEFAULT_TIMEOUT_MS
+  try {
+    const res = await ctx.executor.run(entry.config.statusCommand, {
+      timeoutMs,
+    } as Parameters<typeof ctx.executor.run>[1])
+    const raw = trim(res.stdout ?? "")
+    const matchedState =
+      raw.length > 0 && entry.config.states[raw] !== undefined ? raw : undefined
+    return {
+      raw,
+      state: matchedState,
+      at: Date.now(),
+    }
+  } catch (err) {
+    return {
+      raw: "",
+      state: undefined,
+      error: err instanceof Error ? err.message : String(err),
+      at: Date.now(),
+    }
+  }
+}
+
+export const globalService: AddonGlobalService = {
+  methods: {
+    register: (buttonId: unknown, config: unknown): void => {
+      const id = String(buttonId)
+      const cfg = config as StatusToggleConfig
+      const existing = registry.get(id)
+      registry.set(id, {
+        config: cfg,
+        lastRaw: existing?.lastRaw,
+        lastState: existing?.lastState,
+        lastError: existing?.lastError,
+        lastAt: existing?.lastAt ?? 0,
+        lastPolledAt: existing?.lastPolledAt ?? 0,
+      })
+      void ctxRef?.poll("states")
+    },
+    unregister: (buttonId: unknown): void => {
+      registry.delete(String(buttonId))
+    },
+    // ponytail: tap side-channel. The per-button `onTap` calls this so the
+    // next poll happens before the global tick interval — keeps the deck in
+    // sync with the new state immediately after a user action.
+    // When buttonId is provided, resets that specific entry's lastPolledAt so
+    // the next global tick forces a fresh statusCommand run.
+    republish: (buttonId?: unknown): void => {
+      if (buttonId !== undefined) {
+        const entry = registry.get(String(buttonId))
+        if (entry !== undefined) {
+          entry.lastPolledAt = 0
+        }
+      }
+      void ctxRef?.poll("states")
+    },
+    // ponytail: used by the per-button tap to look up the matched state's
+    // `onTap` command without round-tripping through the registry copy. The
+    // poller keeps `lastState` fresh, so a stale read only happens on the
+    // first tap before the first poll completes.
+    lookup: (buttonId: unknown): ToggleState | null => {
+      const entry = registry.get(String(buttonId))
+      if (entry === undefined) return null
+      if (entry.lastAt === 0) return null
+      const out: ToggleState = {
+        raw: entry.lastRaw ?? "",
+        state: entry.lastState,
+        at: entry.lastAt,
+      }
+      return entry.lastError !== undefined
+        ? { ...out, error: entry.lastError }
+        : out
+    },
+  },
+  pollers: [
+    {
+      id: "states",
+      channel: TOGGLE_STATES_CHANNEL,
+      // ponytail: the global tick is bounded at 1s. Per-button cadence lives
+      // in `intervalMs` and is honored by `lastPolledAt`. Adding a longer
+      // global tick would just slow the first poll.
+      intervalMs: TOGGLE_POLL_TICK_MS,
+      poll: async (ctx: AddonServiceContext): Promise<ToggleStatesPayload> => {
+        const byButton: Record<string, ToggleState | null> = {}
+        if (registry.size === 0) return { byButton }
+        const now = Date.now()
+        await Promise.all(
+          [...registry.entries()].map(async ([buttonId, entry]) => {
+            const intervalMs =
+              entry.config.intervalMs ?? TOGGLE_DEFAULT_INTERVAL_MS
+            const due =
+              entry.lastPolledAt === 0 || now - entry.lastPolledAt >= intervalMs
+            if (!due) {
+              byButton[buttonId] =
+                entry.lastAt === 0
+                  ? null
+                  : entry.lastError !== undefined
+                    ? {
+                        raw: entry.lastRaw ?? "",
+                        state: entry.lastState,
+                        error: entry.lastError,
+                        at: entry.lastAt,
+                      }
+                    : {
+                        raw: entry.lastRaw ?? "",
+                        state: entry.lastState,
+                        at: entry.lastAt,
+                      }
+              return
+            }
+            const next = await pollButton(entry, ctx)
+            entry.lastPolledAt = now
+            entry.lastAt = next.at
+            entry.lastRaw = next.raw
+            entry.lastState = next.state
+            entry.lastError = next.error
+            byButton[buttonId] = next
+          }),
+        )
+        return { byButton }
+      },
+    },
+  ],
+  onLoad: (ctx: AddonServiceContext) => {
+    ctxRef = ctx
+  },
+  onUnload: () => {
+    ctxRef = undefined
+    registry.clear()
+  },
+}

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

@@ -0,0 +1,120 @@
+import type { AddonManifestV1 } from "@/addon/api"
+import { positionButtons } from "@/deck/position-buttons"
+
+import actionBackend from "./buttons/action/backend"
+import actionFrontend from "./buttons/action/frontend"
+import changeDeckBackend from "./buttons/change-deck/backend"
+import changeDeckFrontend from "./buttons/change-deck/frontend"
+import mediaSampleBackend from "./buttons/media-sample/backend"
+import mediaSampleFrontend from "./buttons/media-sample/frontend"
+import pageNavBackend from "./buttons/page-nav/backend"
+import pageNavFrontend from "./buttons/page-nav/frontend"
+import toggleBackend from "./buttons/toggle/backend"
+import toggleFrontend from "./buttons/toggle/frontend"
+import { globalService as toggleGlobalService } from "./buttons/toggle/global-service"
+
+export const manifest: AddonManifestV1 = {
+  apiVersion: 1,
+  name: "core",
+  buttonTypes: {
+    "core:action": {
+      frontend: actionFrontend,
+      // ponytail: gestureHandlers: ['tap'] is REQUIRED for type:// macros and any
+      // addon-deck button that uses actions.tap. The addon registry's default-deny
+      // policy strips undeclared handlers — without this, taps silently no-op.
+      service: { ...actionBackend, gestureHandlers: ["tap"] as const },
+    },
+    "core:change-deck": {
+      frontend: changeDeckFrontend,
+      service: { ...changeDeckBackend, gestureHandlers: ["tap"] as const },
+    },
+    "core:toggle": {
+      frontend: toggleFrontend,
+      service: { ...toggleBackend, gestureHandlers: ["tap"] as const },
+    },
+    "core:page-nav": {
+      frontend: pageNavFrontend,
+      service: { ...pageNavBackend, gestureHandlers: ["tap", "hold"] as const },
+    },
+    "core:media-sample": {
+      frontend: mediaSampleFrontend,
+      service: { ...mediaSampleBackend, gestureHandlers: ["tap"] as const },
+    },
+  },
+  globalService: toggleGlobalService,
+  decks: [
+    {
+      createDecks: ({ config, keyCount }) => {
+        const userButtons = (
+          config as { lockButtons?: ReadonlyArray<Record<string, unknown>> }
+        ).lockButtons
+
+        const centerButton = Math.floor(keyCount / 2)
+
+        // ponytail: default buttons omit `id` — the schema is `.strict()` and
+        // rejects unknown keys, and the runtime re-assigns `id` from `position`
+        // via `positionButtons` in run.ts. Spelling `id` here just emits
+        // "Unrecognized key: 'id'" warnings at startup (3 of them per daemon).
+        const defaultButtons = [
+          {
+            type: "date-time:date-time",
+            config: { format: "<strong><5xl>HH</5xl></strong>" },
+            position: centerButton - 1,
+            full: true,
+          },
+          {
+            type: "date-time:date-time",
+            config: { format: "<strong><5xl><blink>:</blink></5xl></strong>" },
+            position: centerButton,
+            full: true,
+          },
+          {
+            type: "date-time:date-time",
+            config: { format: "<strong><5xl>mm</5xl></strong>" },
+            position: centerButton + 1,
+            full: true,
+          },
+        ]
+
+        return {
+          "core:lock": {
+            name: "Lock",
+            buttons:
+              userButtons !== undefined && userButtons.length > 0
+                ? positionButtons(
+                    userButtons as Array<{ position?: number; id?: string }>,
+                    keyCount,
+                  ).map((b, i) => {
+                    // ponytail: strip the user-supplied `id` (if any) before
+                    // spreading. The button schema is `.strict()` and rejects
+                    // unknown keys; without this, the runtime emits
+                    // "Unrecognized key: 'id'" warnings for each user button.
+                    const { id: _userId, ...rest } = b
+                    return {
+                      id:
+                        b.position !== undefined ? String(b.position) : `b${i}`,
+                      ...rest,
+                    }
+                  })
+                : defaultButtons,
+          },
+        }
+      },
+    },
+  ],
+}
+
+export const coreAddon = manifest
+export default manifest
+export {
+  actionBackend as actionButtonBackend,
+  actionFrontend as ActionButtonFrontend,
+  changeDeckBackend as changeDeckButtonBackend,
+  changeDeckFrontend as ChangeDeckFrontend,
+  mediaSampleBackend as mediaSampleButtonBackend,
+  mediaSampleFrontend as MediaSampleButtonFrontend,
+  pageNavBackend as pageNavButtonBackend,
+  pageNavFrontend as PageNavFrontend,
+  toggleBackend as toggleButtonBackend,
+  toggleFrontend as ToggleButtonFrontend,
+}

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

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

package/src/builtin-addons/date-time/README.md

@@ -0,0 +1,73 @@
+# date-time
+
+Time + date buttons. All refresh on a 1-second interval.
+
+## Buttons
+
+| Type                     | Description                                 |
+| ------------------------ | ------------------------------------------- |
+| `date-time:time`         | Digital time (HH:mm or big variant)         |
+| `date-time:date`         | Day + month + weekday                       |
+| `date-time:date-time`    | Combined date + time (custom format string) |
+| `date-time:analog-clock` | SVG analog clock face                       |
+
+## Config
+
+### `date-time:time`
+
+```yaml
+- position: 2
+  type: date-time:time
+  config:
+    variant: big # "default" (HH:mm) or "big" (HH.mm)
+```
+
+### `date-time:date`
+
+```yaml
+- position: 3
+  type: date-time:date
+  config:
+    locale: en-US # optional, defaults to "en-US"
+    time_zone: Europe/Madrid # optional, defaults to local
+```
+
+### `date-time:date-time`
+
+```yaml
+- position: 5
+  type: date-time:date-time
+  config:
+    format: "DD/MM/YYYY HH:mm:ss" # default; supports <markup> tags
+```
+
+### `date-time:analog-clock`
+
+```yaml
+- position: 4
+  type: date-time:analog-clock # no config
+```
+
+## Example
+
+```yaml
+decks:
+  main:
+    name: Main
+    buttons:
+      - position: 2
+        type: date-time:time
+        config: { variant: big }
+      - position: 3
+        type: date-time:date
+      - position: 4
+        type: date-time:analog-clock
+      - position: 5
+        type: date-time:date-time
+        config:
+          format: "YYYY-MM-DD HH:mm"
+```
+
+## See also
+
+- [system-status](../system-status/README.md) — uptime in the status button

package/src/builtin-addons/date-time/buttons/analog-clock/backend.ts

@@ -0,0 +1,10 @@
+import type { AddonButtonTypeService } from "@/addon/api"
+
+import { configSchema } from "./config"
+
+export const ANALOG_CLOCK_INTERVAL_MS = 1000
+
+export default {
+  configSchema,
+  defaultRenderIntervalMs: ANALOG_CLOCK_INTERVAL_MS,
+} satisfies AddonButtonTypeService

package/src/builtin-addons/date-time/buttons/analog-clock/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/date-time/buttons/analog-clock/frontend.tsx

@@ -0,0 +1,88 @@
+import type { AddonFrontendButton } from "@/addon/api"
+
+import { useNow } from "../../shared/use-now"
+import { ConfigSchema } from "./config"
+
+const polar = (
+  cx: number,
+  cy: number,
+  r: number,
+  deg: number,
+): { x: number; y: number } => {
+  const rad = ((deg - 90) * Math.PI) / 180
+  return { x: cx + r * Math.cos(rad), y: cy + r * Math.sin(rad) }
+}
+
+const INTERVAL_MS = 1000
+
+const AnalogClockButtonFrontend: AddonFrontendButton<ConfigSchema> = () => {
+  const now = useNow(INTERVAL_MS)
+  const h = now.getHours() % 12
+  const m = now.getMinutes()
+  const s = now.getSeconds()
+  const hourAngle = (h + m / 60) * 30
+  const minuteAngle = (m + s / 60) * 6
+  const secondAngle = s * 6
+  const hourEnd = polar(50, 50, 22, hourAngle)
+  const minEnd = polar(50, 50, 32, minuteAngle)
+  const secEnd = polar(50, 50, 36, secondAngle)
+  const ticks = Array.from({ length: 12 }, (_, i) => {
+    const angle = i * 30
+    const outer = polar(50, 50, 40, angle)
+    const inner = polar(50, 50, i % 3 === 0 ? 34 : 37, angle)
+    return (
+      <line
+        key={i}
+        x1={outer.x}
+        y1={outer.y}
+        x2={inner.x}
+        y2={inner.y}
+        stroke="var(--sireno-color-muted)"
+        strokeWidth={i % 3 === 0 ? 1.5 : 0.75}
+      />
+    )
+  })
+  return (
+    <svg viewBox="0 0 100 100" className="h-full w-full">
+      <circle
+        cx="50"
+        cy="50"
+        r="42"
+        fill="none"
+        stroke="var(--sireno-color-primary)"
+        strokeWidth={1}
+      />
+      {ticks}
+      <line
+        x1="50"
+        y1="50"
+        x2={hourEnd.x}
+        y2={hourEnd.y}
+        stroke="var(--sireno-color-fg)"
+        strokeWidth={3}
+        strokeLinecap="round"
+      />
+      <line
+        x1="50"
+        y1="50"
+        x2={minEnd.x}
+        y2={minEnd.y}
+        stroke="var(--sireno-color-fg)"
+        strokeWidth={2}
+        strokeLinecap="round"
+      />
+      <line
+        x1="50"
+        y1="50"
+        x2={secEnd.x}
+        y2={secEnd.y}
+        stroke="var(--sireno-color-accent)"
+        strokeWidth={1}
+        strokeLinecap="round"
+      />
+      <circle cx="50" cy="50" r="2" fill="var(--sireno-color-fg)" />
+    </svg>
+  )
+}
+
+export default AnalogClockButtonFrontend

package/src/builtin-addons/date-time/buttons/custom/backend.ts

@@ -0,0 +1,10 @@
+import type { AddonButtonTypeService } from "@/addon/api"
+
+import { configSchema } from "./config"
+
+export const DIGITAL_DATE_TIME_INTERVAL_MS = 1000
+
+export default {
+  configSchema,
+  defaultRenderIntervalMs: DIGITAL_DATE_TIME_INTERVAL_MS,
+} satisfies AddonButtonTypeService

package/src/builtin-addons/date-time/buttons/custom/config.ts

@@ -0,0 +1,9 @@
+import { z } from "zod"
+
+export const configSchema = z
+  .object({
+    format: z.string().min(1).optional().default("DD/MM/YYYY HH:mm:ss"),
+  })
+  .strict()
+
+export type ConfigSchema = z.infer<typeof configSchema>

package/src/builtin-addons/date-time/buttons/custom/frontend.tsx

@@ -0,0 +1,26 @@
+import type { AddonFrontendButton } from "@/addon/api"
+import { Text } from "@/ui/index"
+
+import { formatDigitalDateTimeLabel } from "../../shared/format"
+import { useNow } from "../../shared/use-now"
+import { ConfigSchema } from "./config"
+
+const INTERVAL_MS = 1000
+
+const DateTimeButtonFrontend: AddonFrontendButton<ConfigSchema> = ({
+  config,
+}) => {
+  const now = useNow(INTERVAL_MS)
+  const format = (config as { format?: string }).format ?? "DD/MM/YYYY HH:mm:ss"
+  return (
+    <span className="flex h-full w-full items-center justify-center">
+      <Text
+        size="lg"
+        tone="fg"
+        text={formatDigitalDateTimeLabel(format, now)}
+      />
+    </span>
+  )
+}
+
+export default DateTimeButtonFrontend

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

@@ -0,0 +1,10 @@
+import type { AddonButtonTypeService } from "@/addon/api"
+
+import { configSchema } from "./config"
+
+export const DATE_BUTTON_INTERVAL_MS = 60000
+
+export default {
+  configSchema,
+  defaultRenderIntervalMs: DATE_BUTTON_INTERVAL_MS,
+} satisfies AddonButtonTypeService

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

@@ -0,0 +1,10 @@
+import { z } from "zod"
+
+export const configSchema = z
+  .object({
+    locale: z.string().min(2).max(35).optional(),
+    time_zone: z.string().min(1).optional(),
+  })
+  .strict()
+
+export type ConfigSchema = z.infer<typeof configSchema>

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

@@ -0,0 +1,42 @@
+import type { AddonFrontendButton } from "@/addon/api"
+
+import { Chip, Text } from "@/ui"
+import { formatDateParts } from "../../shared/format-date"
+import { useNow } from "../../shared/use-now"
+import { ConfigSchema } from "./config"
+
+const INTERVAL_MS = 60000
+
+const DateButtonFrontend: AddonFrontendButton<ConfigSchema> = ({ config }) => {
+  const now = useNow(INTERVAL_MS)
+  const { day, month, weekday, year } = formatDateParts(
+    {
+      ...config,
+      weekDayFormat: "short",
+      yearFormat: "2-digit",
+    },
+    now,
+  )
+  return (
+    <span className="flex h-full w-full flex-col items-center justify-center gap-0.5">
+      <Chip tone="primary" size="md" text={month} />
+      <Text
+        size="4xl"
+        lineHeight="1em"
+        tone="fg"
+        typography="main"
+        weight="bold"
+        text={day}
+      />
+      <Text
+        tone="muted"
+        size="md"
+        typography="main"
+        weight="semibold"
+        text={weekday}
+      />
+    </span>
+  )
+}
+
+export default DateButtonFrontend

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

@@ -0,0 +1,10 @@
+import type { AddonButtonTypeService } from "@/addon/api"
+
+import { configSchema } from "./config"
+
+export const TIME_BUTTON_INTERVAL_MS = 1000
+
+export default {
+  configSchema,
+  defaultRenderIntervalMs: TIME_BUTTON_INTERVAL_MS,
+} satisfies AddonButtonTypeService

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

@@ -0,0 +1,9 @@
+import { z } from "zod"
+
+export const configSchema = z
+  .object({
+    variant: z.enum(["default", "big"]).optional().default("default"),
+  })
+  .strict()
+
+export type ConfigSchema = z.infer<typeof configSchema>