@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/render/protocol.ts

@@ -0,0 +1,61 @@
+export {
+  helloMessageSchema,
+  helloMessageStrictSchema,
+  helloAckMessageSchema,
+  deckConfigMessageSchema,
+  stateMessageSchema,
+  decksListMessageSchema,
+  showOverlayMessageSchema,
+  buttonErrorMessageSchema,
+  buttonActionMessageSchema,
+  methodCallMessageSchema,
+  methodCallResultMessageSchema,
+  selectDeckMessageSchema,
+  setDeviceMessageSchema,
+  deckActiveMessageSchema,
+  dismissOverlayMessageSchema,
+  assetsMessageSchema,
+  subscribeChannelsMessageSchema,
+  editorStateRequestMessageSchema,
+  editorStateMessageSchema,
+  editorValidationRequestMessageSchema,
+  editorValidationResultMessageSchema,
+  editorSourceValidationRequestMessageSchema,
+  editorSourceValidationResultMessageSchema,
+  editorMutationMessageSchema,
+  editorAssetWriteMessageSchema,
+  editorUndoMessageSchema,
+  editorMutationResultMessageSchema,
+  wsMessageSchema,
+  PROTOCOL_VERSION,
+} from "../api/protocol-internal"
+
+export type {
+  HelloMessage,
+  HelloAckMessage,
+  DeckConfigMessage,
+  StateMessage,
+  DecksListMessage,
+  ShowOverlayMessage,
+  ButtonErrorMessage,
+  ButtonActionMessage,
+  MethodCallMessage,
+  MethodCallResultMessage,
+  SelectDeckMessage,
+  SetDeviceMessage,
+  DeckActiveMessage,
+  DismissOverlayMessage,
+  AssetsMessage,
+  SubscribeChannelsMessage,
+  RootButtonMutation,
+  EditorStateMessage,
+  EditorValidationRequestMessage,
+  EditorValidationResultMessage,
+  EditorSourceValidationRequestMessage,
+  EditorSourceValidationResultMessage,
+  EditorMutationMessage,
+  EditorAssetWriteMessage,
+  EditorUndoMessage,
+  EditorMutationResultMessage,
+  WsMessage,
+} from "../api/protocol-internal"

package/src/render/push-raw-image.ts

@@ -0,0 +1,100 @@
+import { readFileSync } from "node:fs"
+
+import sharp from "sharp"
+
+import { gridForKeyCount } from "@/device/models"
+
+export interface PushRawImageDevice {
+  readonly getKeyCount: () => number
+  readonly fillKeyBuffer: (keyIndex: number, buffer: Buffer) => Promise<void>
+}
+
+export interface PushRawImageOptions {
+  readonly imagePath: string
+  readonly device: PushRawImageDevice
+  readonly logger: {
+    warn: (obj: unknown, msg?: string) => void
+    info: (obj: unknown, msg?: string) => void
+  }
+  readonly background?: string
+}
+
+const KEY_SIZE = 72
+
+export async function pushRawImage(opts: PushRawImageOptions): Promise<void> {
+  const background = opts.background ?? "#000000"
+  let sourceBuffer: Buffer
+  try {
+    sourceBuffer = readFileSync(opts.imagePath)
+  } catch (err) {
+    opts.logger.warn(
+      { err: (err as Error).message, imagePath: opts.imagePath },
+      "pushRawImage: cannot read image — skipping splash",
+    )
+    return
+  }
+
+  const keyCount = opts.device.getKeyCount()
+  const { columns, rows } = gridForKeyCount(keyCount)
+  const deckWidth = columns * KEY_SIZE
+  const deckHeight = rows * KEY_SIZE
+
+  let composed: Buffer
+  try {
+    const resized = await sharp(sourceBuffer)
+      .resize({
+        fit: "contain",
+        width: deckWidth,
+        height: deckHeight,
+      })
+      .toBuffer()
+
+    const resizedMeta = await sharp(resized).metadata()
+    const resizedWidth = resizedMeta.width ?? deckWidth
+    const resizedHeight = resizedMeta.height ?? deckHeight
+    const left = Math.max(0, Math.round((deckWidth - resizedWidth) / 2))
+    const top = Math.max(0, Math.round((deckHeight - resizedHeight) / 2))
+
+    composed = await sharp({
+      create: {
+        background,
+        channels: 4,
+        width: deckWidth,
+        height: deckHeight,
+      },
+    })
+      .composite([{ input: resized, left, top }])
+      .removeAlpha()
+      .raw()
+      .toBuffer()
+  } catch (err) {
+    opts.logger.warn(
+      { err: (err as Error).message, imagePath: opts.imagePath },
+      "pushRawImage: sharp pipeline failed — skipping splash",
+    )
+    return
+  }
+
+  const writes: Array<Promise<void>> = []
+  for (let keyIndex = 0; keyIndex < keyCount; keyIndex += 1) {
+    const row = Math.floor(keyIndex / columns)
+    const column = keyIndex % columns
+    const cell = await sharp(composed, {
+      raw: { channels: 3, width: deckWidth, height: deckHeight },
+    })
+      .extract({
+        left: column * KEY_SIZE,
+        top: row * KEY_SIZE,
+        width: KEY_SIZE,
+        height: KEY_SIZE,
+      })
+      .raw()
+      .toBuffer()
+    writes.push(opts.device.fillKeyBuffer(keyIndex, cell))
+  }
+  await Promise.all(writes)
+  opts.logger.info(
+    { imagePath: opts.imagePath, keyCount },
+    "pushRawImage: pushed raw image",
+  )
+}

package/src/render/screenshot-cadence.ts

@@ -0,0 +1,87 @@
+import type pino from "pino"
+
+export interface CadenceTimerOptions {
+  readonly intervalMs: number
+  readonly onTick: () => void | Promise<void>
+  readonly logger: pino.Logger
+}
+
+export class CadenceTimer {
+  private timer: ReturnType<typeof setTimeout> | null = null
+  private running = false
+
+  constructor(private readonly options: CadenceTimerOptions) {}
+
+  start(): void {
+    if (this.running) return
+    this.running = true
+    this.schedule()
+  }
+
+  stop(): void {
+    this.running = false
+    if (this.timer !== null) {
+      clearTimeout(this.timer)
+      this.timer = null
+    }
+  }
+
+  private schedule(): void {
+    if (!this.running) return
+    this.timer = setTimeout(() => {
+      this.timer = null
+      if (!this.running) return
+      const start = Date.now()
+      const result = this.options.onTick()
+      const follow = () => {
+        const elapsed = Date.now() - start
+        if (elapsed > this.options.intervalMs) {
+          this.options.logger.warn(
+            { intervalMs: this.options.intervalMs, elapsedMs: elapsed },
+            "cadence timer tick exceeded interval",
+          )
+        }
+        this.schedule()
+      }
+      if (result instanceof Promise) {
+        result.then(follow, (err: unknown) => {
+          this.options.logger.error({ err }, "cadence timer tick failed")
+          this.schedule()
+        })
+      } else {
+        follow()
+      }
+    }, this.options.intervalMs)
+  }
+}
+
+export interface EventDebouncerOptions {
+  readonly delayMs: number
+  readonly onFlush: () => void
+  readonly logger: pino.Logger
+}
+
+export class EventDebouncer {
+  private timer: ReturnType<typeof setTimeout> | null = null
+  private disposed = false
+
+  constructor(private readonly options: EventDebouncerOptions) {}
+
+  trigger(): void {
+    if (this.disposed) return
+    if (this.timer !== null) clearTimeout(this.timer)
+    this.timer = setTimeout(() => {
+      this.timer = null
+      if (this.disposed) return
+      this.options.onFlush()
+    }, this.options.delayMs)
+  }
+
+  dispose(): void {
+    this.disposed = true
+    if (this.timer !== null) {
+      clearTimeout(this.timer)
+      this.timer = null
+    }
+  }
+}

package/src/render/state-publisher.ts

@@ -0,0 +1,110 @@
+import type pino from "pino"
+
+import type { WsBridge } from "./ws-bridge"
+
+export interface StatePublisherChannel {
+  readonly channel: string
+  readonly addonName: string
+  readonly intervalMs: number
+  readonly poll: () => Promise<unknown> | unknown
+}
+
+export interface StatePublisherOptions {
+  readonly bridge: Pick<WsBridge, "broadcast">
+  readonly logger: pino.Logger
+  readonly onPublish?: () => void
+}
+
+export interface DeckSnapshot {
+  readonly addonNames: ReadonlyArray<string>
+}
+
+export class StatePublisher {
+  private readonly bridge: Pick<WsBridge, "broadcast">
+  private readonly logger: pino.Logger
+  private readonly onPublish: (() => void) | undefined
+  private readonly channels = new Map<string, StatePublisherChannel>()
+  private readonly timers = new Map<string, NodeJS.Timeout>()
+  private activeAddonNames: ReadonlyArray<string> = []
+
+  constructor(options: StatePublisherOptions) {
+    this.bridge = options.bridge
+    this.logger = options.logger.child({ component: "state-publisher" })
+    this.onPublish = options.onPublish
+  }
+
+  registerChannel(channel: StatePublisherChannel): void {
+    this.channels.set(channel.channel, channel)
+    if (this.activeAddonNames.includes(channel.addonName)) {
+      this.startChannel(channel)
+    }
+  }
+
+  unregisterChannel(channelName: string): void {
+    this.stopChannel(channelName)
+    this.channels.delete(channelName)
+  }
+
+  setActiveDeck(snapshot: DeckSnapshot): void {
+    const previous = new Set(this.activeAddonNames)
+    const next = new Set(snapshot.addonNames)
+    this.activeAddonNames = snapshot.addonNames
+    for (const ch of this.channels.values()) {
+      const wasActive = previous.has(ch.addonName)
+      const isActive = next.has(ch.addonName)
+      if (!wasActive && isActive) this.startChannel(ch)
+      else if (wasActive && !isActive) this.stopChannel(ch.channel)
+    }
+  }
+
+  stopAll(): void {
+    for (const name of this.timers.keys()) this.stopChannel(name)
+  }
+
+  private startChannel(channel: StatePublisherChannel): void {
+    if (this.timers.has(channel.channel)) return
+    const fire = (): void => {
+      try {
+        const payload = channel.poll()
+        if (payload instanceof Promise) {
+          payload
+            .then((value) => {
+              this.bridge.broadcast({
+                type: "state",
+                channels: { [channel.channel]: value },
+              })
+              this.onPublish?.()
+            })
+            .catch((err: unknown) => {
+              this.logger.warn(
+                { err, channel: channel.channel },
+                "state-publisher: poll failed",
+              )
+            })
+        } else {
+          this.bridge.broadcast({
+            type: "state",
+            channels: { [channel.channel]: payload },
+          })
+          this.onPublish?.()
+        }
+      } catch (err) {
+        this.logger.warn(
+          { err, channel: channel.channel },
+          "state-publisher: poll threw",
+        )
+      }
+    }
+    fire()
+    const timer = setInterval(fire, channel.intervalMs)
+    this.timers.set(channel.channel, timer)
+  }
+
+  private stopChannel(channelName: string): void {
+    const t = this.timers.get(channelName)
+    if (t !== undefined) {
+      clearInterval(t)
+      this.timers.delete(channelName)
+    }
+  }
+}

package/src/render/vite-server.ts

@@ -0,0 +1,138 @@
+import { spawn, type ChildProcess } from "node:child_process"
+import { EventEmitter } from "node:events"
+
+export interface ViteServerOptions {
+  command: string
+  args: ReadonlyArray<string>
+  cwd: string
+  env?: Readonly<Record<string, string>>
+  readyMatcher?: RegExp
+  maxRestarts?: number
+  restartBackoffMs?: ReadonlyArray<number>
+  onPid?: (pid: number) => void
+}
+
+export interface ViteServerHandle {
+  readonly emitter: EventEmitter
+  readonly port: number | null
+  readonly pid: number | null
+  stop(): Promise<void>
+}
+
+export const spawnViteServer = (
+  options: ViteServerOptions,
+): Promise<ViteServerHandle> => {
+  const {
+    command,
+    args,
+    cwd,
+    env,
+    readyMatcher = /READY\s+(\d+)/,
+    maxRestarts = 3,
+    restartBackoffMs = [500, 1000, 2000],
+    onPid,
+  } = options
+
+  return new Promise((resolve, reject) => {
+    const emitter = new EventEmitter()
+    let current: ChildProcess | null = null
+    let port: number | null = null
+    let pid: number | null = null
+    let restartCount = 0
+    let stopped = false
+
+    const killCurrent = (): Promise<void> =>
+      new Promise<void>((res) => {
+        if (current === null) {
+          res()
+          return
+        }
+        const proc = current
+        proc.once("exit", () => res())
+        proc.kill("SIGTERM")
+        setTimeout(() => {
+          if (!proc.killed) proc.kill("SIGKILL")
+        }, 2000)
+      })
+
+    const start = (): void => {
+      if (stopped) return
+      // ponytail: detached:true puts vite in its own process group — kill
+      // -pgid (terminateChildren) takes the whole group down at once so a
+      // crashed or SIGKILL'd daemon doesn't leave vite holding :5180/:52938.
+      current = spawn(command, [...args], {
+        cwd,
+        env: env !== undefined ? { ...process.env, ...env } : process.env,
+        detached: true,
+      })
+      current.unref()
+      const newPid = current.pid ?? null
+      pid = newPid
+      if (newPid !== null) {
+        emitter.emit("pid", newPid)
+        onPid?.(newPid)
+      }
+
+      const onReady = (matchedPort: number): void => {
+        port = matchedPort
+        emitter.emit("ready", matchedPort)
+        resolve(handle)
+      }
+
+      const buffer: string[] = []
+      current.stdout?.on("data", (chunk: Buffer) => {
+        const text = chunk.toString()
+        buffer.push(text)
+        if (port === null) {
+          const match =
+            text.match(readyMatcher) ?? buffer.join("").match(readyMatcher)
+          if (match && match[1]) onReady(Number.parseInt(match[1], 10))
+        }
+        emitter.emit("stdout", text)
+      })
+
+      current.stderr?.on("data", (chunk: Buffer) => {
+        emitter.emit("stderr", chunk.toString())
+      })
+
+      current.on("exit", (code) => {
+        if (stopped) return
+        if (port === null) {
+          reject(
+            new Error(
+              `vite spawn: process exited with code ${code} before READY`,
+            ),
+          )
+          return
+        }
+        if (restartCount >= maxRestarts) {
+          emitter.emit("crash", code)
+          return
+        }
+        const backoff =
+          restartBackoffMs[
+            Math.min(restartCount, restartBackoffMs.length - 1)
+          ] ?? 1000
+        restartCount += 1
+        emitter.emit("restart", restartCount, backoff)
+        setTimeout(start, backoff)
+      })
+    }
+
+    const handle: ViteServerHandle = {
+      emitter,
+      get port() {
+        return port
+      },
+      get pid() {
+        return pid
+      },
+      stop: async () => {
+        stopped = true
+        await killCurrent()
+      },
+    }
+
+    start()
+  })
+}