@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/deck/runtime-subscriptions.ts

@@ -0,0 +1,45 @@
+import type { PubSub } from "@/core/pub-sub"
+
+import type { Runtime } from "./runtime"
+
+export const subscribeNavigateDeck = (
+  pubSub: PubSub,
+  runtime: Runtime,
+): (() => void) => {
+  return pubSub.subscribe("runtime:navigate-deck", (payload: unknown) => {
+    if (
+      typeof payload !== "object" ||
+      payload === null ||
+      !("deckId" in payload)
+    ) {
+      return
+    }
+    const deckId = String((payload as { deckId: unknown }).deckId)
+    const addToHistory =
+      "addToHistory" in payload
+        ? Boolean((payload as { addToHistory: unknown }).addToHistory)
+        : true
+    // ponytail: position arrives as a real field on the payload — never parse it
+    // from buttonId. The id format `[position]-[deck]-[page]` is opaque; pages
+    // 2+ collide with the page-nav slot's bare-digit prefix if you try.
+    const sourcePosition =
+      "position" in payload &&
+      (payload as { position: unknown }).position !== undefined &&
+      Number.isFinite(Number((payload as { position: unknown }).position))
+        ? Number((payload as { position: unknown }).position)
+        : undefined
+    const sourceDeckId = runtime.getActiveDeckId()
+    // ponytail: check existence BEFORE calling navigateToDeck so we never mutate
+    // nav state for a missing target. deckExists is the runtime's public check.
+    if (!runtime.deckExists(deckId) && sourcePosition !== undefined) {
+      pubSub.publish("runtime:buttonError", {
+        deckId: sourceDeckId,
+        position: sourcePosition,
+        durationMs: 5000,
+        details: `missing-navigation-target: ${deckId}`,
+      })
+      return
+    }
+    runtime.navigateToDeck(deckId, { addToHistory })
+  })
+}

package/src/deck/system-back-injection.ts

@@ -0,0 +1,62 @@
+import type { SystemButtonType } from "./system-buttons/types"
+
+export interface RuntimeDeck {
+  id: string
+  name: string
+  buttons: ReadonlyArray<{
+    id: string
+    type: string
+    position?: number
+    config?: unknown
+  }>
+  isMain?: boolean
+  processNames?: ReadonlyArray<string>
+  windowNames?: ReadonlyArray<string>
+  autoShow?: boolean
+  icon?: string
+}
+
+export interface RuntimeState {
+  navStackDepth: number
+  hasOverlayDeckAvailable: boolean
+  lockActive?: boolean
+  inOverlayMode?: boolean
+}
+
+export const computeSystemButtonForSlotN1 = (
+  deck: RuntimeDeck,
+  state: RuntimeState,
+): SystemButtonType | null => {
+  if (state.lockActive === true) return null
+  if (deck.isMain) return "core:settings-entry"
+  if (state.inOverlayMode === true) return "core:overlay-toggle"
+  return "core:back"
+}
+
+export const injectSystemButtons = <T extends RuntimeDeck>(
+  decks: ReadonlyArray<T>,
+  keyCount: number,
+  options?: { lockActive?: boolean },
+): ReadonlyArray<T> => {
+  const n1Position = keyCount - 1
+  return decks.map((deck) => {
+    const systemButtonType = computeSystemButtonForSlotN1(deck, {
+      navStackDepth: 1,
+      hasOverlayDeckAvailable: false,
+      lockActive: options?.lockActive === true,
+    })
+    if (systemButtonType === null) return deck
+    const filtered = deck.buttons.filter((b) => b.position !== n1Position)
+    return {
+      ...deck,
+      buttons: [
+        ...filtered,
+        {
+          id: `${n1Position}-${deck.id}-0`,
+          type: systemButtonType,
+          position: n1Position,
+        } as T["buttons"][number],
+      ],
+    }
+  })
+}

package/src/deck/system-buttons/registry.tsx

@@ -0,0 +1,97 @@
+import { type ReactElement } from "react"
+
+import { Icon } from "@/ui/primitives/Icon"
+import { Label } from "@/ui/primitives/Label"
+import { IconLabelSurface } from "@/ui/surfaces/IconLabelSurface"
+import { TemporaryErrorSurface } from "@/ui/surfaces/TemporaryErrorSurface"
+
+import {
+  SYSTEM_BUTTON_TYPES,
+  isSystemButtonType,
+  type SystemButtonType,
+} from "./types"
+
+const SYSTEM_BUTTON_LAYOUT: Record<
+  SystemButtonType,
+  { source: string; label: string; details?: string }
+> = {
+  "core:back": { source: "icon://arrow-left", label: "Back" },
+  "core:settings-entry": { source: "icon://settings", label: "Settings" },
+  "core:overlay-toggle": { source: "icon://layers", label: "Overlay" },
+  "core:temporary-error": {
+    source: "icon://triangle-alert",
+    label: "Error",
+  },
+}
+
+export const SYSTEM_BUTTON_LABELS: ReadonlyArray<string> = SYSTEM_BUTTON_TYPES
+
+export const isSystemButton = (type: string): type is SystemButtonType =>
+  isSystemButtonType(type)
+
+const FALLBACK_ERROR_DETAILS = "check logs"
+
+export const renderSystemButton = (
+  type: string,
+  iconOverride?: string,
+  details?: string,
+  labelOverride?: string,
+): ReactElement | null => {
+  if (!isSystemButtonType(type)) {
+    return null
+  }
+  const layout = SYSTEM_BUTTON_LAYOUT[type]
+
+  if (type === "core:temporary-error") {
+    return (
+      <TemporaryErrorSurface
+        source={iconOverride ?? layout.source}
+        label={layout.label}
+        details={details ?? layout.details ?? FALLBACK_ERROR_DETAILS}
+      />
+    )
+  }
+
+  return (
+    <IconLabelSurface
+      source={iconOverride ?? layout.source}
+      label={labelOverride ?? layout.label}
+      {...(details !== undefined
+        ? { details }
+        : layout.details !== undefined
+          ? { details: layout.details }
+          : {})}
+    />
+  )
+}
+
+interface OverlayToggleSurfaceProps {
+  deckIcon: string
+  overlayDeckName?: string
+}
+
+const OverlayToggleSurface = ({
+  deckIcon,
+  overlayDeckName,
+}: OverlayToggleSurfaceProps): ReactElement => {
+  return (
+    <div
+      className="flex flex-col items-center justify-center gap-1"
+      data-sireno-overlay-toggle="true"
+    >
+      <div className="flex items-center gap-1">
+        <Icon source={deckIcon} size={26} />
+        <Icon source="icon://slash" size={14} />
+        <Icon source="icon://layers" size={26} />
+      </div>
+      <Label text={overlayDeckName ?? "Overlay"} lines={2} />
+    </div>
+  )
+}
+
+export const renderOverlayToggleButton = (
+  deckIcon: string,
+  overlayDeckName?: string,
+): ReactElement => (
+  <OverlayToggleSurface deckIcon={deckIcon} overlayDeckName={overlayDeckName} />
+)

package/src/deck/system-buttons/types.ts

@@ -0,0 +1,14 @@
+// ponytail: pagination is handled by the `core:page-nav` addon button
+// (tap=next, hold=prev) in builtin-addons/core/buttons/page-nav/, not by a
+// system button. Keeping the system-button surface small and deliberate.
+export const SYSTEM_BUTTON_TYPES = [
+  "core:back",
+  "core:settings-entry",
+  "core:overlay-toggle",
+  "core:temporary-error",
+] as const
+
+export type SystemButtonType = (typeof SYSTEM_BUTTON_TYPES)[number]
+
+export const isSystemButtonType = (value: string): value is SystemButtonType =>
+  (SYSTEM_BUTTON_TYPES as ReadonlyArray<string>).includes(value)

package/src/device/black-frame.ts

@@ -0,0 +1,73 @@
+import { connectStreamDeck, type StreamDeckDevice } from "@/device/stream-deck"
+
+import type pino from "pino"
+
+// ponytail: extracted from RealOutputClient.pushBlackFrame so any caller
+// (current or future) can push a black frame WITHOUT going through the full
+// daemon init. Today the daemon pushes a black frame on its own teardown in
+// runPipeline's finally block; the helper is preserved for that single use
+// site and stays best-effort because the device may be unplugged at the
+// moment of exit.
+const buildBlackBuffer = (keyCount: number): Buffer => {
+  const stride = 3 * 8
+  const total = keyCount * stride * 8
+  return Buffer.alloc(total)
+}
+
+export const pushBlackFrame = async (
+  device: StreamDeckDevice,
+  logger: pino.Logger,
+): Promise<void> => {
+  try {
+    const buf = buildBlackBuffer(device.getKeyCount())
+    for (let i = 0; i < device.getKeyCount(); i++) {
+      await device.fillKeyBuffer(i, buf.subarray(0, 3 * 8 * 8))
+    }
+    // ponytail: brightness is a feature report processed synchronously by the
+    // device firmware, so dimming to 0 is a guaranteed "off" signal even if the
+    // queued image writes above are dropped at USB disconnect.
+    await device.setBrightness(0)
+    // ponytail: give the queued USB writes a moment to drain before the caller
+    // closes the device; otherwise node-hid may flush to a closed handle and
+    // the panel keeps the last fully-rendered frame.
+    await new Promise<void>((r) => setTimeout(r, 200))
+    logger.info("black-frame: pushed")
+  } catch (err) {
+    logger.warn(
+      { err: (err as Error).message },
+      "black-frame: push failed (non-fatal)",
+    )
+  }
+}
+
+export interface BlackFrameConfig {
+  readonly serial: string
+}
+
+// ponytail: parent-process entry point. Opens a fresh device, pushes the
+// black frame, closes. All errors are non-fatal — the device may be gone,
+// the daemon may be mid-shutdown, the operator may have unplugged the cable.
+export const pushBlackFrameToDevice = async (
+  config: BlackFrameConfig,
+  logger: pino.Logger,
+): Promise<void> => {
+  let device: StreamDeckDevice | null = null
+  try {
+    device = await connectStreamDeck({ serial: config.serial })
+  } catch (err) {
+    logger.warn(
+      { err: (err as Error).message, serial: config.serial },
+      "black-frame: failed to connect to device (non-fatal)",
+    )
+    return
+  }
+  try {
+    await pushBlackFrame(device, logger)
+  } finally {
+    try {
+      await device.close()
+    } catch {
+      void 0
+    }
+  }
+}

package/src/device/index.ts

@@ -0,0 +1,13 @@
+export {
+  connectStreamDeck,
+  StreamDeckSelectionError,
+  type ConnectStreamDeckOptions,
+  type StreamDeckDevice,
+} from "./stream-deck"
+export { listDevices, type DeviceDescriptor } from "./registry"
+export {
+  UDEV_RULES,
+  UdevPermissionError,
+  formatInstallInstructions,
+  installUdevRules,
+} from "./linux-udev"

package/src/device/linux-udev.ts

@@ -0,0 +1,36 @@
+export const UDEV_RULES = `# sirenodeck — Elgato Stream Deck udev rules
+# Grants current user access to Elgato USB devices without sudo.
+
+SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="0060", TAG+="uaccess"
+SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="006c", TAG+="uaccess"
+SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="006d", TAG+="uaccess"
+SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="006e", TAG+="uaccess"
+SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="0080", TAG+="uaccess"
+SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="0084", TAG+="uaccess"
+SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="0086", TAG+="uaccess"
+SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="0090", TAG+="uaccess"
+`
+
+export class UdevPermissionError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "UdevPermissionError"
+  }
+}
+
+export const formatInstallInstructions = (): string =>
+  `Stream Deck udev rules not installed. To install:
+
+  sudo tee /etc/udev/rules.d/70-sirenodeck.rules > /dev/null <<'EOF'
+${UDEV_RULES.trimEnd()}
+EOF
+  sudo udevadm control --reload-rules && sudo udevadm trigger
+
+Then unplug and replug your Stream Deck.
+`
+
+export const installUdevRules = async (): Promise<void> => {
+  throw new UdevPermissionError(
+    "installUdevRules() requires running with elevated privileges; use the manual instructions from formatInstallInstructions()",
+  )
+}

package/src/device/models.ts

@@ -0,0 +1,89 @@
+export interface DeviceModelSpec {
+  readonly id: string
+  readonly name: string
+  readonly keyCount: number
+  readonly columns: number
+  readonly rows: number
+}
+
+export const DEVICE_MODELS: ReadonlyArray<DeviceModelSpec> = [
+  {
+    id: "original",
+    name: "Stream Deck Original",
+    keyCount: 15,
+    columns: 5,
+    rows: 3,
+  },
+  {
+    id: "originalv2",
+    name: "Stream Deck Original V2",
+    keyCount: 15,
+    columns: 5,
+    rows: 3,
+  },
+  { id: "mk2", name: "Stream Deck MK.2", keyCount: 15, columns: 5, rows: 3 },
+  { id: "plus", name: "Stream Deck +", keyCount: 32, columns: 8, rows: 4 },
+  { id: "mini", name: "Stream Deck Mini", keyCount: 6, columns: 3, rows: 2 },
+  { id: "xl", name: "Stream Deck XL", keyCount: 32, columns: 8, rows: 4 },
+]
+
+export const DEFAULT_DEVICE_MODEL_ID = "mk2"
+
+export const DEFAULT_KEY_COUNT = 15
+
+export const BUTTON_SIZE_PX = 96
+export const DECK_PADDING_PX = 16
+export const DECK_GAP_PX = 8
+
+export const resolveDeckGap = (
+  value: string | null | undefined,
+  compact = false,
+): number => {
+  if (value === "false" || value === "0") return 0
+  if (value === "true" || value === "8") return DECK_GAP_PX
+  return compact ? 0 : DECK_GAP_PX
+}
+
+export const deckDimensions = (
+  model: Pick<DeviceModelSpec, "columns" | "rows">,
+  gap: number,
+  padding = DECK_PADDING_PX,
+) => ({
+  width:
+    model.columns * BUTTON_SIZE_PX + (model.columns - 1) * gap + padding * 2,
+  height: model.rows * BUTTON_SIZE_PX + (model.rows - 1) * gap + padding * 2,
+})
+
+export const isKnownDeviceModel = (id: string): id is DeviceModelSpec["id"] =>
+  DEVICE_MODELS.some((m) => m.id === id)
+
+export const getDeviceModel = (id: string): DeviceModelSpec => {
+  const found = DEVICE_MODELS.find((m) => m.id === id)
+  if (found === undefined) {
+    throw new Error(`Unknown device model: ${id}`)
+  }
+  return found
+}
+
+export const resolveKeyCount = (id: string | undefined): number => {
+  if (id === undefined) return DEFAULT_KEY_COUNT
+  if (!isKnownDeviceModel(id)) {
+    throw new Error(`Unknown device model: ${id}`)
+  }
+  return getDeviceModel(id).keyCount
+}
+
+export const gridForKeyCount = (
+  keyCount: number,
+): { columns: number; rows: number } => {
+  if (keyCount === 15) return { columns: 5, rows: 3 }
+  if (keyCount === 32) return { columns: 8, rows: 4 }
+  if (keyCount === 6) return { columns: 3, rows: 2 }
+  if (keyCount === 8) return { columns: 4, rows: 2 }
+  if (keyCount === 3) return { columns: 3, rows: 1 }
+  if (keyCount === 2) return { columns: 2, rows: 1 }
+  if (keyCount === 1) return { columns: 1, rows: 1 }
+  const columns = Math.ceil(Math.sqrt(keyCount))
+  const rows = Math.ceil(keyCount / columns)
+  return { columns, rows }
+}

package/src/device/reconnecting.ts

@@ -0,0 +1,193 @@
+import type pino from "pino"
+
+import type { StreamDeckDevice, StreamDeckKeyEvent } from "./stream-deck"
+
+/**
+ * Wraps a Stream Deck so losing the hardware is a pause, not a crash.
+ *
+ * ponytail: a KVM switching to another computer removes the USB device. The
+ * SDK then emits `error`, which nothing subscribed to — an unhandled `error`
+ * on an EventEmitter throws, the daemon's uncaughtException guard fired, and
+ * the service exited with no recovery. Writes could fail the same way.
+ *
+ * This keeps the daemon alive instead: the surrounding pipeline (vite,
+ * Playwright, the bridge, the runtime) is untouched by USB coming and going,
+ * so only the device handle is swapped. While the deck is away, writes are
+ * dropped silently and a watcher retries for as long as it takes; when it
+ * returns, brightness and key listeners are reattached and the caller is asked
+ * to repaint.
+ */
+export interface ReconnectingDeviceDeps {
+  readonly serial: string
+  readonly connect: (opts: {
+    readonly serial: string
+  }) => Promise<StreamDeckDevice>
+  readonly logger: pino.Logger
+  /** Gap between reconnect attempts. */
+  readonly retryDelayMs?: number
+  /** Called after a fresh handle is attached, to restore brightness/repaint. */
+  readonly onReconnect?: (device: StreamDeckDevice) => void | Promise<void>
+  /** Called when the hardware goes away. */
+  readonly onDisconnect?: (err: unknown) => void
+  readonly sleep?: (ms: number) => Promise<void>
+}
+
+export interface ReconnectingDevice extends StreamDeckDevice {
+  /** Whether hardware is attached right now. */
+  isConnected(): boolean
+}
+
+const DEFAULT_RETRY_DELAY_MS = 2_000
+
+export const createReconnectingDevice = (
+  initial: StreamDeckDevice,
+  deps: ReconnectingDeviceDeps,
+): ReconnectingDevice => {
+  const retryDelayMs = deps.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS
+  const sleep =
+    deps.sleep ?? ((ms: number) => new Promise((r) => setTimeout(r, ms)))
+
+  let current: StreamDeckDevice | null = initial
+  let stopped = false
+  let watching = false
+  let detachCurrent: (() => void) | null = null
+
+  const keyHandlers = new Set<(event: StreamDeckKeyEvent) => void>()
+  const errorHandlers = new Set<(err: unknown) => void>()
+
+  const attach = (device: StreamDeckDevice): void => {
+    const offKeys = device.onKeyEvent((event) => {
+      for (const h of keyHandlers) h(event)
+    })
+    const offError = device.onError((err) => {
+      lose(err)
+    })
+    detachCurrent = () => {
+      offKeys()
+      offError()
+    }
+  }
+
+  const lose = (err: unknown): void => {
+    if (current === null || stopped) return
+    const gone = current
+    current = null
+    detachCurrent?.()
+    detachCurrent = null
+    deps.logger.warn(
+      { err: err instanceof Error ? err.message : String(err) },
+      "device: Stream Deck disconnected — holding the deck and watching for it to come back",
+    )
+    for (const h of errorHandlers) h(err)
+    deps.onDisconnect?.(err)
+    // Best effort: the handle is already dead, and close() on a vanished HID
+    // device commonly throws.
+    void Promise.resolve()
+      .then(() => gone.close())
+      .catch(() => undefined)
+    void watch()
+  }
+
+  const watch = async (): Promise<void> => {
+    if (watching || stopped) return
+    watching = true
+    let attempts = 0
+    // Deliberately unbounded: the user asked for the deck to be picked up
+    // whenever it returns, which on a KVM can be hours later. Nothing here
+    // accumulates, and the daemon is otherwise idle without a device.
+    while (!stopped && current === null) {
+      attempts += 1
+      try {
+        const device = await deps.connect({ serial: deps.serial })
+        if (stopped) {
+          void device.close().catch(() => undefined)
+          break
+        }
+        current = device
+        attach(device)
+        deps.logger.info(
+          { attempts, serial: deps.serial },
+          "device: Stream Deck reconnected",
+        )
+        try {
+          await deps.onReconnect?.(device)
+        } catch (err) {
+          deps.logger.warn({ err }, "device: post-reconnect restore failed")
+        }
+        break
+      } catch {
+        // Not back yet. Logged sparsely so an overnight absence does not
+        // produce thousands of identical lines.
+        if (attempts === 1 || attempts % 30 === 0) {
+          deps.logger.info(
+            { attempts, serial: deps.serial, retryDelayMs },
+            "device: still waiting for the Stream Deck",
+          )
+        }
+        await sleep(retryDelayMs)
+      }
+    }
+    watching = false
+  }
+
+  /** Runs a hardware call, treating transport failure as a disconnect. */
+  const guard = async (
+    action: (device: StreamDeckDevice) => Promise<void>,
+  ): Promise<void> => {
+    const device = current
+    // No hardware: drop the write. The renderer keeps ticking against a device
+    // that is not there, and its change tracker is reset on reconnect so the
+    // dropped frames are repainted then.
+    if (device === null) return
+    try {
+      await action(device)
+    } catch (err) {
+      lose(err)
+    }
+  }
+
+  // Wire the device we were handed, not just the ones we reconnect to —
+  // otherwise the first disconnect is never noticed and key events from the
+  // initial handle never reach the caller.
+  attach(initial)
+
+  return {
+    // Identity stays that of the device we were asked to track, so callers
+    // that captured the descriptor keep working across a swap.
+    serial: initial.serial,
+    path: initial.path,
+    model: initial.model,
+    getKeyCount: () => (current ?? initial).getKeyCount(),
+    isConnected: () => current !== null,
+    async setBrightness(value: number): Promise<void> {
+      await guard((d) => d.setBrightness(value))
+    },
+    async fillKeyBuffer(keyIndex: number, buffer: Buffer): Promise<void> {
+      await guard((d) => d.fillKeyBuffer(keyIndex, buffer))
+    },
+    onKeyEvent(handler: (event: StreamDeckKeyEvent) => void): () => void {
+      keyHandlers.add(handler)
+      return () => {
+        keyHandlers.delete(handler)
+      }
+    },
+    onError(handler: (err: unknown) => void): () => void {
+      errorHandlers.add(handler)
+      return () => {
+        errorHandlers.delete(handler)
+      }
+    },
+    async close(): Promise<void> {
+      stopped = true
+      const device = current
+      current = null
+      detachCurrent?.()
+      detachCurrent = null
+      keyHandlers.clear()
+      errorHandlers.clear()
+      if (device !== null) await device.close()
+    },
+  }
+}
+
+export { DEFAULT_RETRY_DELAY_MS }

package/src/device/registry.ts

@@ -0,0 +1,38 @@
+import {
+  listStreamDecks,
+  type StreamDeckDeviceInfo,
+} from "@elgato-stream-deck/node"
+import { resolveKeyCount } from "@/device/models"
+
+export type DeviceTransport = "real" | "emulated"
+
+export interface DeviceDescriptor {
+  readonly id: string
+  readonly model: string
+  readonly keyCount: number
+  readonly label: string
+  readonly transport: DeviceTransport
+}
+
+const toDescriptor = (info: StreamDeckDeviceInfo): DeviceDescriptor => {
+  const model = info.model
+  const id = info.serialNumber ?? info.path
+  return {
+    id,
+    model,
+    keyCount: resolveKeyCount(model),
+    label: `${model.toUpperCase()} (${id})`,
+    transport: "real",
+  }
+}
+
+export const listDevices = async (): Promise<DeviceDescriptor[]> => {
+  try {
+    const infos = await listStreamDecks()
+    return infos.map(toDescriptor).sort((a, b) => a.id.localeCompare(b.id))
+  } catch (err) {
+    // ponytail: log so real errors (missing model entry, HID I/O failure) aren't hidden as "no devices"
+    console.warn({ err }, "device enumeration failed")
+    return []
+  }
+}