@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/device/stream-deck.ts

@@ -0,0 +1,155 @@
+import {
+  getStreamDeckModelName,
+  listStreamDecks,
+  openStreamDeck,
+  type StreamDeck as SdkDevice,
+  type StreamDeckDeviceInfo,
+} from "@elgato-stream-deck/node"
+
+export class StreamDeckSelectionError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "StreamDeckSelectionError"
+  }
+}
+
+export type StreamDeckKeyEventType = "down" | "up"
+
+export interface StreamDeckKeyEvent {
+  readonly type: StreamDeckKeyEventType
+  readonly keyIndex: number
+  readonly timestamp: number
+}
+
+export interface StreamDeckDevice {
+  readonly serial: string
+  readonly path: string
+  readonly model: string
+  getKeyCount(): number
+  setBrightness(value: number): Promise<void>
+  fillKeyBuffer(keyIndex: number, buffer: Buffer): Promise<void>
+  onKeyEvent(handler: (event: StreamDeckKeyEvent) => void): () => void
+  /**
+   * Fires when the SDK reports a transport failure — most commonly the USB
+   * device going away (unplugged, or a KVM switching the host).
+   *
+   * ponytail: the SDK declares an `error` event and nothing subscribed to it.
+   * An unhandled `error` on an EventEmitter throws, which the daemon's
+   * uncaughtException guard turned into an immediate exit — so flipping a KVM
+   * killed the service outright instead of it noticing the deck had left.
+   */
+  onError(handler: (err: unknown) => void): () => void
+  close(): Promise<void>
+}
+
+export interface ConnectStreamDeckOptions {
+  readonly serial?: string
+  readonly path?: string
+  readonly model?: string
+}
+
+const buildDescriptor = (
+  info: StreamDeckDeviceInfo,
+  controls: ReadonlyArray<SdkDevice["CONTROLS"][number]>,
+) => ({
+  serial: info.serialNumber ?? "",
+  path: info.path,
+  model: getStreamDeckModelName(info.model),
+  keyCount: controls.filter((c) => c.type === "button").length,
+})
+
+export const connectStreamDeck = async (
+  options: ConnectStreamDeckOptions = {},
+): Promise<StreamDeckDevice> => {
+  const infos = await listStreamDecks()
+  let candidates: StreamDeckDeviceInfo[]
+  if (infos.length === 0) {
+    candidates = []
+  } else if (
+    options.serial !== undefined ||
+    options.path !== undefined ||
+    options.model !== undefined
+  ) {
+    candidates = infos.filter((info) => {
+      if (options.serial !== undefined && info.serialNumber !== options.serial)
+        return false
+      if (options.path !== undefined && info.path !== options.path) return false
+      if (options.model !== undefined && info.model !== options.model)
+        return false
+      return true
+    })
+  } else {
+    candidates = [...infos]
+  }
+
+  if (candidates.length === 0) {
+    throw new StreamDeckSelectionError(
+      options.serial !== undefined || options.path !== undefined
+        ? `No Stream Deck matches selector ${JSON.stringify(options)}`
+        : "No Stream Deck devices found",
+    )
+  }
+  if (
+    candidates.length > 1 &&
+    options.serial === undefined &&
+    options.path === undefined
+  ) {
+    throw new StreamDeckSelectionError(
+      `Multiple Stream Deck devices found (${candidates.length}); pass --serial or --path`,
+    )
+  }
+
+  const targetInfo = candidates[0]!
+  const handle = await openStreamDeck(targetInfo.path, {})
+  const descriptor = buildDescriptor(targetInfo, handle.CONTROLS)
+
+  // Baseline listener so the event always has a subscriber, even when the
+  // caller never registers one. Without it an `error` emitted between open and
+  // the caller's onError() call is still fatal.
+  const errorHandlers = new Set<(err: unknown) => void>()
+  handle.on("error", (err: unknown) => {
+    for (const h of errorHandlers) h(err)
+  })
+
+  return {
+    serial: descriptor.serial,
+    path: descriptor.path,
+    model: descriptor.model,
+    getKeyCount: () => descriptor.keyCount,
+    async setBrightness(value: number): Promise<void> {
+      await handle.setBrightness(value)
+    },
+    async fillKeyBuffer(keyIndex: number, buffer: Buffer): Promise<void> {
+      await handle.fillKeyBuffer(keyIndex, buffer)
+    },
+    onKeyEvent(handler: (event: StreamDeckKeyEvent) => void): () => void {
+      const onDown = (control: { type: string; index: number }): void => {
+        if (control.type !== "button") return
+        handler({
+          type: "down",
+          keyIndex: control.index,
+          timestamp: Date.now(),
+        })
+      }
+      const onUp = (control: { type: string; index: number }): void => {
+        if (control.type !== "button") return
+        handler({ type: "up", keyIndex: control.index, timestamp: Date.now() })
+      }
+      handle.on("down", onDown)
+      handle.on("up", onUp)
+      return () => {
+        handle.off("down", onDown)
+        handle.off("up", onUp)
+      }
+    },
+    onError(handler: (err: unknown) => void): () => void {
+      errorHandlers.add(handler)
+      return () => {
+        errorHandlers.delete(handler)
+      }
+    },
+    async close(): Promise<void> {
+      await handle.close()
+    },
+  }
+}

package/src/index.ts

@@ -0,0 +1,74 @@
+export {
+  BUTTON_SIZE_PX,
+  DECK_GAP_PX,
+  DECK_PADDING_PX,
+  DEFAULT_DEVICE_MODEL_ID,
+  DEFAULT_KEY_COUNT,
+  DEVICE_MODELS,
+  deckDimensions,
+  getDeviceModel,
+  gridForKeyCount,
+  isKnownDeviceModel,
+  resolveKeyCount,
+  resolveDeckGap,
+  type DeviceModelSpec,
+} from "./device/models"
+export {
+  PACKAGE_NAME,
+  PROTOCOL_VERSION,
+  SIRENO_ADDON_API_VERSION,
+} from "./version"
+
+export {
+  DOUBLE_TAP_DELAY_MS,
+  HOLD_ACTION_DELAY_MS,
+  SPA_DOUBLE_TAP_DELAY_MS,
+  SPA_HOLD_DELAY_MS,
+  nextGesture,
+  type GestureEvent,
+  type GestureKind,
+  type GestureResult,
+  type GestureType,
+  createGestureDetector,
+  type GestureDetector,
+} from "./core/gesture-state"
+
+export type { AddonGestureEvent } from "./addon/api"
+
+export { ChannelRegistry } from "./api/react/registry"
+export {
+  useAddonChannel,
+  type UseAddonChannelReturn,
+} from "./api/react/use-addon-channel"
+export {
+  ThemeContext,
+  ThemeProvider,
+  useTheme,
+  type ThemeContextValue,
+} from "./themes/use-resolved-theme"
+
+export {
+  AssetCacheProvider,
+  useAssetCache,
+  useAssetCacheMutations,
+  type AssetCache,
+  buildPresentation,
+  ButtonFrame,
+  Chip,
+  Icon,
+  IconLabelSurface,
+  Label,
+  SplitActionSurface,
+  TapIndicator,
+  TemporaryErrorSurface,
+  Text,
+  ThemeUiPresentationProvider,
+  type ButtonFrameProps,
+  type IconLabelSurfaceProps,
+  type SplitActionSurfaceProps,
+  type TapIndicatorProps,
+  type TemporaryErrorSurfaceProps,
+  type ThemeUiPresentation,
+} from "./ui"
+
+export const cliVersion = "0.1.0"

package/src/outputClient/emulator.ts

@@ -0,0 +1,357 @@
+import { execFile } from "node:child_process"
+import { platform } from "node:os"
+
+import type pino from "pino"
+
+import type {
+  ButtonActionMessage,
+  SelectDeckMessage,
+  SetDeviceMessage,
+  WsMessage,
+} from "@/api/protocol-internal"
+import { resolveKeyCount } from "@/device/models"
+import type { DeviceDescriptor } from "@/device/registry"
+import { writeRuntimeState, type RuntimeState } from "@/util/daemon"
+
+import {
+  DEFAULT_CONFIG_UI_PORT,
+  DEFAULT_FRONTEND_PORT,
+  killChild,
+  resolveConfigUiCwd,
+  resolveFrontendCwd,
+  spawnConfigUiVite,
+  spawnFrontendVite,
+} from "../cli/commands/emulator-mode"
+import {
+  DEFAULT_VITE_RETRY_SCHEDULE_MS,
+  supervise,
+  type SuperviseHandle,
+} from "../cli/commands/subprocess-supervisor"
+
+import type { InitOptions, OutputClient, OutputHandle } from "./types"
+
+const DEFAULT_TIMEOUT_MS = 30_000
+
+const VIRTUAL_MODELS = ["mk2", "mini", "xl"] as const
+
+const isButtonAction = (m: WsMessage): m is ButtonActionMessage =>
+  m.type === "button-action"
+
+const isSetDevice = (m: WsMessage): m is SetDeviceMessage =>
+  m.type === "set-device"
+
+const isSelectDeck = (m: WsMessage): m is SelectDeckMessage =>
+  m.type === "select-deck"
+
+const openBrowser = (
+  url: string,
+  logger: pino.Logger,
+  noOpen = false,
+): void => {
+  if (noOpen) {
+    logger.debug("browser auto-open disabled")
+    return
+  }
+  const os = platform()
+  const cmd = os === "win32" ? "cmd" : os === "darwin" ? "open" : "xdg-open"
+  const args = os === "win32" ? ["/c", "start", "", url] : [url]
+  execFile(cmd, args, (err) => {
+    if (err !== null) {
+      logger.debug(
+        { err: err.message },
+        "browser auto-open unavailable, open the URL manually",
+      )
+    }
+  })
+}
+
+export class EmulatorOutputClient implements OutputClient {
+  readonly kind = "emulator" as const
+
+  private descriptor: DeviceDescriptor | null = null
+
+  async validateReady(): Promise<void> {
+    void this.kind
+  }
+
+  async listDevices(): Promise<ReadonlyArray<DeviceDescriptor>> {
+    return VIRTUAL_MODELS.map((model) => buildVirtualDescriptor(model))
+  }
+
+  async selectDevice(
+    devices: ReadonlyArray<DeviceDescriptor>,
+    savedId: string | null,
+    logger: pino.Logger,
+  ): Promise<DeviceDescriptor> {
+    void logger
+    const match =
+      savedId !== null ? devices.find((d) => d.id === savedId) : undefined
+    if (match !== undefined) {
+      this.descriptor = match
+      return match
+    }
+    const fallback = devices.find((d) => d.model === "mk2") ?? devices[0]
+    if (fallback === undefined) {
+      throw new Error("EmulatorOutputClient: no virtual devices available")
+    }
+    this.descriptor = fallback
+    return fallback
+  }
+
+  async storeSelection(_descriptor: DeviceDescriptor): Promise<void> {
+    void _descriptor
+  }
+
+  async init(opts: InitOptions): Promise<OutputHandle> {
+    if (this.descriptor === null) {
+      throw new Error(
+        "EmulatorOutputClient.init: selectDevice() must run first",
+      )
+    }
+    const descriptor = this.descriptor
+    const logger = opts.logger.child({ component: "emulator" })
+    let shuttingDown = false
+
+    const remote = opts.remote === true
+    const host: "127.0.0.1" | "0.0.0.0" = remote ? "0.0.0.0" : "127.0.0.1"
+    const token = process.env["SIRENO_TOKEN"] ?? ""
+    const requireToken = remote ? token : undefined
+
+    // ponytail: supervise each vite child independently — frontend crash
+    // respawns only the frontend, config UI crash respawns only the config UI.
+    // Both share the same `onChildCrash` so the pipeline exits cleanly when
+    // either exhausts its retry budget. The supervisor spawn closure captures
+    // the resolved URL into a hoisted `frontendUrl`/`configUiUrl` so callers
+    // see it after the initial await; subsequent respawns bind the same port
+    // so the URL stays accurate.
+    let frontendUrl = ""
+    let configUiUrl = ""
+
+    const frontendSupervisor: SuperviseHandle | null =
+      opts.frontendUrl !== undefined
+        ? (() => {
+            frontendUrl = opts.frontendUrl
+            return null
+          })()
+        : await supervise({
+            label: "frontend vite",
+            kill: killChild,
+            delayScheduleMs: DEFAULT_VITE_RETRY_SCHEDULE_MS,
+            spawn: async () => {
+              const r = await spawnFrontendVite({
+                port: DEFAULT_FRONTEND_PORT,
+                cwd: resolveFrontendCwd(),
+                pnpmCommand: "pnpm",
+                readyTimeoutMs: DEFAULT_TIMEOUT_MS,
+                logger,
+                wsUrl: opts.bridge.url,
+                configPath: opts.configPath,
+                emulatorMode: true,
+                host,
+                ...(requireToken !== undefined ? { requireToken } : {}),
+                ...(opts.onChildPid !== undefined
+                  ? { onPid: opts.onChildPid }
+                  : {}),
+              })
+              frontendUrl = r.url
+              return r.process
+            },
+            onGiveUp: () => opts.onChildCrash?.(),
+            isShuttingDown: () => shuttingDown,
+            logger,
+          })
+
+    const emulatorSupervisor = await supervise({
+      label: "config ui vite",
+      kill: killChild,
+      delayScheduleMs: DEFAULT_VITE_RETRY_SCHEDULE_MS,
+      spawn: async () => {
+        const r = await spawnConfigUiVite({
+          port: DEFAULT_CONFIG_UI_PORT,
+          cwd: resolveConfigUiCwd(),
+          pnpmCommand: "pnpm",
+          readyTimeoutMs: DEFAULT_TIMEOUT_MS,
+          logger,
+          wsUrl: opts.bridge.url,
+          configPath: opts.configPath,
+          emulatorMode: true,
+          host,
+          frontendUrl:
+            opts.frontendUrl ?? `http://127.0.0.1:${DEFAULT_FRONTEND_PORT}`,
+          ...(requireToken !== undefined ? { requireToken } : {}),
+          ...(opts.onChildPid !== undefined ? { onPid: opts.onChildPid } : {}),
+        })
+        configUiUrl = r.url
+        return r.process
+      },
+      onGiveUp: () => opts.onChildCrash?.(),
+      isShuttingDown: () => shuttingDown,
+      logger,
+    })
+
+    opts.bridge.setDevice(descriptor)
+
+    opts.bridge.onMessage((message) => {
+      if (isSelectDeck(message)) {
+        if (opts.runtime.deckExists(message.deckId))
+          opts.runtime.navigateToDeck(message.deckId, { addToHistory: false })
+        else
+          logger.warn(
+            { deckId: message.deckId },
+            "emulator: select-deck targets unknown deck",
+          )
+        return
+      }
+      if (isSetDevice(message)) {
+        if (
+          !VIRTUAL_MODELS.includes(
+            message.deviceId as (typeof VIRTUAL_MODELS)[number],
+          )
+        ) {
+          logger.warn(
+            { deviceId: message.deviceId },
+            "emulator: ignoring unsupported virtual device",
+          )
+          return
+        }
+        const descriptor = buildVirtualDescriptor(message.deviceId)
+        this.descriptor = descriptor
+        opts.bridge.setDevice(descriptor)
+        // The runtime was built once at startup with the original device's
+        // keyCount, so system-button injection + pagination baked in the
+        // wrong n-1 / n-2 positions. Rebuild with the new keyCount and
+        // swap the runtime's deck set so the next deck-config broadcast
+        // carries the correct layout. The rebuild path runs
+        // positionButtons(runtimeDeck.config, keyCount) on every deck so
+        // positions always come from the original config snapshot, never
+        // from prior in-memory state.
+        if (opts.rebuildDecksForKeyCount !== undefined) {
+          const rebuilt = opts.rebuildDecksForKeyCount(descriptor.keyCount)
+          opts.runtime.setDecks(rebuilt)
+        }
+        logger.info(
+          { deviceId: message.deviceId },
+          "emulator: virtual device changed",
+        )
+        return
+      }
+      if (!isButtonAction(message)) return
+      logger.debug(
+        {
+          deckId: message.deckId,
+          position: message.position,
+          gesture: message.gesture,
+        },
+        "emulator: button-action received",
+      )
+      // The runtime is the authority on the active deck. The client sends
+      // message.deckId for routing on the frontend (so React knows which
+      // cell fired), but the emulator backend uses runtime.getActiveDeck()
+      // to resolve the actual deck — this avoids relying on the client's
+      // sometimes-stale local view of the active deck.
+      const activeDeck = opts.runtime.getActiveDeck()
+      const button = activeDeck.buttons.find((b) => {
+        if (b.position === message.position) return true
+        const parsed = Number.parseInt(b.id, 10)
+        return Number.isFinite(parsed) && parsed === message.position
+      })
+      logger.debug(
+        {
+          activeDeckId: activeDeck.id,
+          position: message.position,
+          gesture: message.gesture,
+        },
+        "[emulator] button lookup",
+      )
+      if (button === undefined) {
+        logger.warn(
+          { activeDeckId: activeDeck.id, position: message.position },
+          "emulator: button-action targets unknown button",
+        )
+        return
+      }
+      void opts.runtime.dispatchGesture(
+        `${activeDeck.id}:${button.id}`,
+        message.gesture,
+      )
+    })
+
+    const frontendPid = frontendSupervisor?.process.pid ?? 0
+    const emulatorPid = emulatorSupervisor.process.pid ?? 0
+    const childPids = [frontendPid, emulatorPid].filter((p) => p > 0)
+
+    logger.info(
+      {
+        configUiUrl,
+        frontendUrl,
+        wsUrl: opts.bridge.url,
+      },
+      "emulator mode ready",
+    )
+    if (remote) {
+      process.stdout.write(`\n  Config UI:  ${configUiUrl}\n\n`)
+      const lanHost = opts.lanHost ?? "127.0.0.1"
+      const state: RuntimeState = {
+        configUiUrl,
+        wsUrl: opts.bridge.url,
+        frontendUrl,
+        lanHost,
+        addresses: opts.lanAddresses ?? [],
+        emulatorMode: true,
+        remote: true,
+        startedAt: Date.now(),
+        theme: opts.theme.name,
+      }
+      writeRuntimeState(state)
+    } else {
+      const frontendLine =
+        process.env.SIRENO_DEV_MODE === "true"
+          ? `\n  Frontend:  ${frontendUrl}`
+          : ""
+      process.stdout.write(`\n  Config UI:  ${configUiUrl}${frontendLine}\n\n`)
+      openBrowser(configUiUrl, logger, opts.noAutoOpen === true)
+      const lanHost = opts.lanHost ?? "127.0.0.1"
+      const state: RuntimeState = {
+        configUiUrl,
+        wsUrl: opts.bridge.url,
+        frontendUrl,
+        lanHost,
+        addresses: opts.lanAddresses ?? [],
+        emulatorMode: true,
+        remote: false,
+        startedAt: Date.now(),
+        theme: opts.theme.name,
+      }
+      writeRuntimeState(state)
+    }
+
+    opts.runtime.setBrightness(opts.runtime.getBrightness())
+
+    return {
+      descriptor,
+      frontendUrl,
+      configUiUrl,
+      wsUrl: opts.bridge.url,
+      childPids,
+      async stop(): Promise<void> {
+        shuttingDown = true
+        // The supervisor's stop() now SIGTERMs the current mutable child and
+        // falls back to SIGKILL after a grace period. After a respawn the
+        // live vite is the one killed — the previous stale-.process bug
+        // leaked the respawned child and bound the port.
+        await Promise.allSettled([
+          emulatorSupervisor.stop(),
+          frontendSupervisor?.stop() ?? Promise.resolve(),
+        ])
+      },
+    }
+  }
+}
+
+const buildVirtualDescriptor = (model: string): DeviceDescriptor => ({
+  id: `emulator:${model}`,
+  model,
+  keyCount: resolveKeyCount(model),
+  label: `Emulator ${model.toUpperCase()}`,
+  transport: "emulated",
+})

package/src/outputClient/index.ts

@@ -0,0 +1,26 @@
+import { EmulatorOutputClient } from "./emulator"
+import { RealOutputClient } from "./real"
+import type { OutputClient } from "./types"
+
+export interface SelectOutputClientOptions {
+  readonly emulator: boolean
+  readonly xdgConfigHome: string
+}
+
+export const selectOutputClient = (
+  options: SelectOutputClientOptions,
+): OutputClient => {
+  if (options.emulator) {
+    return new EmulatorOutputClient()
+  }
+  return new RealOutputClient({ xdgConfigHome: options.xdgConfigHome })
+}
+
+export type {
+  InitOptions,
+  OutputClient,
+  OutputHandle,
+  OutputKind,
+} from "./types"
+export { EmulatorOutputClient } from "./emulator"
+export { RealOutputClient } from "./real"

package/src/outputClient/open-browser.ts

@@ -0,0 +1,26 @@
+import { execFile } from "node:child_process"
+import { platform } from "node:os"
+
+import type pino from "pino"
+
+export const openBrowser = (
+  url: string,
+  logger: pino.Logger,
+  noOpen = false,
+): void => {
+  if (noOpen) {
+    logger.info("browser auto-open disabled")
+    return
+  }
+  const os = platform()
+  const cmd = os === "win32" ? "cmd" : os === "darwin" ? "open" : "xdg-open"
+  const args = os === "win32" ? ["/c", "start", "", url] : [url]
+  execFile(cmd, args, (err) => {
+    if (err !== null) {
+      logger.warn(
+        { err: err.message },
+        "browser auto-open unavailable, open the URL manually",
+      )
+    }
+  })
+}