@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/render/browser-renderer.ts

@@ -0,0 +1,240 @@
+import sharp from "sharp"
+
+import { BUTTON_SIZE_PX, gridForKeyCount } from "@/device/models"
+import type { PubSub } from "@/core/pub-sub"
+import { createPubSub } from "@/core/pub-sub"
+import type pino from "pino"
+
+import { BufferChangeTracker } from "./buffer-hash"
+import { CadenceTimer, EventDebouncer } from "./screenshot-cadence"
+
+export interface PlaywrightLike {
+  chromium: {
+    launch(opts?: { headless?: boolean; args?: string[] }): Promise<BrowserLike>
+  }
+}
+export interface BrowserLike {
+  newContext(opts?: {
+    viewport?: { width: number; height: number }
+  }): Promise<ContextLike>
+  close(): Promise<void>
+}
+export interface ContextLike {
+  newPage(): Promise<PageLike>
+  close(): Promise<void>
+}
+export interface PageLike {
+  goto(url: string, opts?: { waitUntil?: string }): Promise<unknown>
+  screenshot(opts: { type: "png" }): Promise<Buffer>
+  close(): Promise<void>
+  route(url: string, handler: (route: RouteLike) => void): void
+}
+
+export interface RouteLike {
+  request(): { url(): string }
+  continue(opts: { url: string }): void
+}
+
+export interface DeviceSink {
+  getKeyCount(): number
+  fillKeyBuffer(keyIndex: number, buffer: Buffer): Promise<void>
+}
+
+export interface BrowserRendererOptions {
+  readonly frontendUrl: string
+  readonly device: DeviceSink
+  readonly logger: pino.Logger
+  readonly pubSub?: PubSub
+  readonly intervalMs?: number
+  readonly eventDebounceMs?: number
+  readonly playwrightFactory?: () => PlaywrightLike | Promise<PlaywrightLike>
+}
+
+const DEFAULT_INTERVAL_MS = 500
+const DEFAULT_EVENT_DEBOUNCE_MS = 50
+
+interface Subscription {
+  unsubscribe: () => void
+}
+
+export class BrowserRenderer {
+  private readonly intervalMs: number
+  private readonly eventDebounceMs: number
+  private readonly pubSub: PubSub | undefined
+  private readonly cadence: CadenceTimer
+  private readonly debouncer: EventDebouncer
+  private readonly tracker = new BufferChangeTracker()
+  private readonly subscriptions: Subscription[] = []
+  /**
+   * Number of consecutive ticks where every key buffer was unchanged.
+   * Once it crosses `BLANK_THRESHOLD`, we suspect the React tree has been
+   * unmounted (typically by an HMR error that escaped the ErrorBoundary)
+   * and warn the user via the logger. The renderer does not abort —
+   * screenshots still flow — but the operator gets a visible signal.
+   */
+  private staticBlankTickCount = 0
+  private browser: BrowserLike | null = null
+  private context: ContextLike | null = null
+  private page: PageLike | null = null
+  private running = false
+  private readonly logger: pino.Logger
+
+  constructor(private readonly options: BrowserRendererOptions) {
+    this.logger = options.logger.child({ component: "browser-renderer" })
+    this.intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS
+    this.eventDebounceMs = options.eventDebounceMs ?? DEFAULT_EVENT_DEBOUNCE_MS
+    this.pubSub = options.pubSub
+    this.cadence = new CadenceTimer({
+      intervalMs: this.intervalMs,
+      onTick: () => this.tick("timer"),
+      logger: this.logger,
+    })
+    this.debouncer = new EventDebouncer({
+      delayMs: this.eventDebounceMs,
+      onFlush: () => this.tick("event"),
+      logger: this.logger,
+    })
+  }
+
+  async start(): Promise<void> {
+    if (this.running) return
+    const factory =
+      this.options.playwrightFactory ??
+      (async (): Promise<PlaywrightLike> =>
+        (await import("playwright")) as PlaywrightLike)
+    const playwright = await factory()
+    try {
+      this.browser = await playwright.chromium.launch({ headless: true })
+    } catch (err) {
+      // ponytail: hardware mode renders every deck frame in headless chromium,
+      // so a missing browser download is fatal — but Playwright's own message
+      // is a box-drawing banner wrapped in a stack trace that never mentions
+      // sirenodeck. Dev builds never auto-install it (ensurePlaywright only
+      // ran for installed trees), so this is the first thing a contributor
+      // hits when they plug in a real deck. Say what to run.
+      const message = (err as Error).message ?? ""
+      if (
+        /Executable doesn't exist|please run the following command/i.test(
+          message,
+        )
+      ) {
+        throw new Error(
+          "Headless chromium is not installed — sirenodeck renders deck images with it.\n" +
+            "  Fix: pnpm --filter @sirenodeck/sirenodeck exec playwright install chromium\n" +
+            `  (original error: ${message.split("\n")[0] ?? ""})`,
+        )
+      }
+      throw err
+    }
+    const { columns, rows } = gridForKeyCount(this.options.device.getKeyCount())
+    const vpWidth = columns * BUTTON_SIZE_PX
+    const vpHeight = rows * BUTTON_SIZE_PX
+    this.context = await this.browser.newContext({
+      viewport: { width: vpWidth, height: vpHeight },
+    })
+    this.page = await this.context.newPage()
+    await this.page.goto(this.options.frontendUrl, { waitUntil: "networkidle" })
+    if (this.pubSub) {
+      this.subscriptions.push(
+        {
+          unsubscribe: this.pubSub.subscribe("runtime:activeDeck", () =>
+            this.debouncer.trigger(),
+          ),
+        },
+        {
+          unsubscribe: this.pubSub.subscribe("runtime:invalidate", () =>
+            this.debouncer.trigger(),
+          ),
+        },
+      )
+    }
+    this.cadence.start()
+    this.running = true
+  }
+
+  /**
+   * Repaints every key on the next tick.
+   *
+   * ponytail: the change tracker skips keys whose bytes have not changed, so
+   * after the hardware goes away and comes back the deck would stay blank —
+   * the tracker still holds the hashes of what the OLD handle was showing.
+   * Nothing reset it before this; `runtime:invalidate` only triggers a tick.
+   */
+  forceRedraw(): void {
+    this.tracker.reset()
+    this.debouncer.trigger()
+  }
+
+  async stop(): Promise<void> {
+    if (!this.running) return
+    this.running = false
+    this.cadence.stop()
+    this.debouncer.dispose()
+    for (const sub of this.subscriptions) sub.unsubscribe()
+    this.subscriptions.length = 0
+    if (this.page) await this.page.close()
+    if (this.context) await this.context.close()
+    if (this.browser) await this.browser.close()
+    this.page = null
+    this.context = null
+    this.browser = null
+  }
+
+  private static readonly BLANK_THRESHOLD = 20
+
+  private async tick(source: "timer" | "event"): Promise<void> {
+    if (!this.page) return
+    try {
+      const png = await this.page.screenshot({ type: "png" })
+      const { columns, rows } = gridForKeyCount(
+        this.options.device.getKeyCount(),
+      )
+      const meta = await sharp(png).metadata()
+      const cellWidth = Math.floor((meta.width ?? 0) / columns)
+      const cellHeight = Math.floor((meta.height ?? 0) / rows)
+      const writes: Array<Promise<void>> = []
+      for (let r = 0; r < rows; r++) {
+        for (let c = 0; c < columns; c++) {
+          const keyIndex = r * columns + c
+          const cropped = await sharp(png)
+            .extract({
+              left: c * cellWidth,
+              top: r * cellHeight,
+              width: cellWidth,
+              height: cellHeight,
+            })
+            .resize(72, 72, { fit: "fill" })
+            .removeAlpha()
+            .raw()
+            .toBuffer()
+          if (!this.tracker.update(keyIndex, cropped)) continue
+          writes.push(this.options.device.fillKeyBuffer(keyIndex, cropped))
+        }
+      }
+      if (writes.length > 0) {
+        await Promise.all(writes)
+        this.staticBlankTickCount = 0
+        this.logger.debug(
+          { source, writes: writes.length },
+          "renderer tick wrote keys",
+        )
+      } else {
+        this.staticBlankTickCount += 1
+        this.logger.debug({ source }, "renderer tick no changes")
+        if (this.staticBlankTickCount === BrowserRenderer.BLANK_THRESHOLD) {
+          this.logger.warn(
+            {
+              consecutiveTicks: this.staticBlankTickCount,
+              source,
+            },
+            "frontend appears blank — React tree may have crashed (check the browser console or HMR errors)",
+          )
+        }
+      }
+    } catch (err) {
+      this.logger.warn({ err, source }, "renderer tick failed")
+    }
+  }
+}
+
+export const _testInternals = { createPubSub }

package/src/render/buffer-hash.ts

@@ -0,0 +1,20 @@
+import { createHash } from "node:crypto"
+
+export const hashBuffer = (buf: Buffer): string =>
+  createHash("sha1").update(buf).digest("hex").slice(0, 16)
+
+export class BufferChangeTracker {
+  private readonly last = new Map<number, string>()
+
+  update(keyIndex: number, buf: Buffer): boolean {
+    const hash = hashBuffer(buf)
+    const previous = this.last.get(keyIndex)
+    if (previous === hash) return false
+    this.last.set(keyIndex, hash)
+    return true
+  }
+
+  reset(): void {
+    this.last.clear()
+  }
+}

package/src/render/editor-handler.ts

@@ -0,0 +1,197 @@
+import type { WebSocket } from "ws"
+
+import type { ConfigMutationService } from "@/config/mutation"
+import {
+  editorMutationResultMessageSchema,
+  editorStateMessageSchema,
+  type EditorMutationMessage,
+  type EditorUndoMessage,
+  type EditorStateMessage,
+  editorValidationResultMessageSchema,
+  editorSourceValidationResultMessageSchema,
+  type EditorSourceValidationRequestMessage,
+  type EditorValidationRequestMessage,
+  type WsMessage,
+} from "./protocol"
+
+export interface EditorMessageHandlerOptions {
+  readonly mutationService: ConfigMutationService
+  readonly getState: () => Omit<
+    EditorStateMessage,
+    "type" | "revision" | "canUndo" | "buttonSchemas" | "surfaces"
+  > & {
+    buttonSchemas?: EditorStateMessage["buttonSchemas"]
+    surfaces?: EditorStateMessage["surfaces"]
+    revision?: number
+  }
+  readonly onChanged?: () => void | Promise<void>
+  readonly broadcast: (message: WsMessage) => void
+  readonly validateConfig?: (buttonType: string, config: unknown) => string[]
+}
+
+export interface EditorMessageHandler {
+  readonly onMessage: (message: WsMessage, socket: WebSocket) => void
+  readonly onConnection: (socket: WebSocket) => void
+  readonly invalidate: () => void
+}
+
+export const createEditorMessageHandler = (
+  options: EditorMessageHandlerOptions,
+): EditorMessageHandler => {
+  let revision = options.getState().revision ?? 0
+  let applyQueue = Promise.resolve()
+
+  const state = (): EditorStateMessage =>
+    editorStateMessageSchema.parse({
+      type: "editor-state",
+      ...options.getState(),
+      revision,
+      canUndo: options.mutationService.canUndo(),
+    })
+
+  const send = (socket: WebSocket, message: WsMessage): void => {
+    if (socket.readyState === socket.OPEN) socket.send(JSON.stringify(message))
+  }
+
+  const result = (
+    socket: WebSocket,
+    requestId: string,
+    ok: boolean,
+    error?: string,
+  ): void => {
+    send(
+      socket,
+      editorMutationResultMessageSchema.parse({
+        type: "editor-mutation-result",
+        requestId,
+        ok,
+        revision,
+        ...(error !== undefined ? { error } : {}),
+      }),
+    )
+  }
+
+  const validationResult = (
+    socket: WebSocket,
+    request: EditorValidationRequestMessage,
+  ): void => {
+    const errors =
+      options.validateConfig?.(request.buttonType, request.config) ?? []
+    send(
+      socket,
+      editorValidationResultMessageSchema.parse({
+        type: "editor-validation-result",
+        requestId: request.requestId,
+        valid: errors.length === 0,
+        errors,
+      }),
+    )
+  }
+
+  const sourceValidationResult = (
+    socket: WebSocket,
+    request: EditorSourceValidationRequestMessage,
+  ): void => {
+    const errors = options.mutationService.validateSource(
+      request.path,
+      request.content,
+    )
+    send(
+      socket,
+      editorSourceValidationResultMessageSchema.parse({
+        type: "editor-source-validation-result",
+        requestId: request.requestId,
+        valid: errors.length === 0,
+        errors,
+      }),
+    )
+  }
+
+  const apply = async (
+    socket: WebSocket,
+    requestId: string,
+    requestRevision: number,
+    operation: () => Promise<boolean | void>,
+  ): Promise<void> => {
+    const task = async (): Promise<void> => {
+      if (requestRevision !== revision) {
+        result(socket, requestId, false, "stale editor revision")
+        send(socket, state())
+        return
+      }
+      try {
+        const changed = await operation()
+        if (changed === false) {
+          result(socket, requestId, false, "nothing to undo")
+          return
+        }
+        revision += 1
+        await options.onChanged?.()
+        result(socket, requestId, true)
+        options.broadcast(state())
+      } catch (error) {
+        result(
+          socket,
+          requestId,
+          false,
+          error instanceof Error ? error.message : String(error),
+        )
+      }
+    }
+    const queued = applyQueue.then(task, task)
+    applyQueue = queued.then(
+      () => undefined,
+      () => undefined,
+    )
+    await queued
+  }
+
+  return {
+    onMessage: (message, socket) => {
+      if (message.type === "editor-state-request") {
+        send(socket, state())
+        return
+      }
+      if (message.type === "editor-validation-request") {
+        validationResult(socket, message)
+        return
+      }
+      if (message.type === "editor-source-validation-request") {
+        sourceValidationResult(socket, message)
+        return
+      }
+      if (message.type === "editor-asset-write") {
+        void options.mutationService
+          .writeAsset(message.filename, message.data)
+          .then(() => result(socket, message.requestId, true))
+          .catch((error: unknown) =>
+            result(
+              socket,
+              message.requestId,
+              false,
+              error instanceof Error ? error.message : String(error),
+            ),
+          )
+        return
+      }
+      if (message.type === "editor-mutate") {
+        void apply(socket, message.requestId, message.revision, () =>
+          options.mutationService.apply(message.mutation),
+        )
+        return
+      }
+      if (message.type === "editor-undo") {
+        void apply(socket, message.requestId, message.revision, () =>
+          options.mutationService.undo(),
+        )
+      }
+    },
+    onConnection: (socket) => send(socket, state()),
+    invalidate: () => {
+      revision += 1
+      options.broadcast(state())
+    },
+  }
+}
+
+export type { EditorMutationMessage, EditorUndoMessage }

package/src/render/emulator-server.ts

@@ -0,0 +1,128 @@
+import { spawn, type ChildProcess } from "node:child_process"
+import { existsSync } from "node:fs"
+import { dirname, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+export interface EmulatorServerOptions {
+  readonly port: number
+  readonly frontendEmulatorDir: string
+  readonly env?: Readonly<Record<string, string>>
+  readonly logger?: (msg: string) => void
+}
+
+export interface EmulatorServerHandle {
+  readonly child: ChildProcess
+  readonly port: number
+  readonly url: string
+  close(): Promise<void>
+}
+
+const READY_PREFIX = "READY "
+
+export const parseReadyLine = (line: string): number | null => {
+  const trimmed = line.trim()
+  if (!trimmed.startsWith(READY_PREFIX)) return null
+  const portStr = trimmed.slice(READY_PREFIX.length).trim()
+  const port = Number.parseInt(portStr, 10)
+  return Number.isFinite(port) ? port : null
+}
+
+export const startEmulatorServer = async (
+  options: EmulatorServerOptions,
+): Promise<EmulatorServerHandle> => {
+  const { port, frontendEmulatorDir } = options
+  const log = options.logger ?? ((): void => {})
+  const viteBin = resolve(frontendEmulatorDir, "node_modules", ".bin", "vite")
+  const cliEntry = resolve(frontendEmulatorDir, "src", "main")
+
+  const env: Record<string, string> = {
+    ...(process.env as Record<string, string>),
+    ...options.env,
+    SIRENO_EMULATOR_PORT: String(port),
+  }
+
+  const child = spawn(
+    "node",
+    ["--import", "tsx/esm", viteBin, "--port", String(port), cliEntry],
+    {
+      cwd: frontendEmulatorDir,
+      env,
+      stdio: ["ignore", "pipe", "pipe"],
+    },
+  )
+
+  return await new Promise<EmulatorServerHandle>((resolvePromise, reject) => {
+    let settled = false
+    const onData = (chunk: Buffer): void => {
+      const text = chunk.toString("utf8")
+      log(text)
+      for (const line of text.split("\n")) {
+        if (line.startsWith(READY_PREFIX)) {
+          const actualPort = Number.parseInt(
+            line.slice(READY_PREFIX.length).trim(),
+            10,
+          )
+          if (!Number.isFinite(actualPort)) {
+            return
+          }
+          if (settled) return
+          settled = true
+          child.stdout?.off("data", onData)
+          child.stderr?.off("data", onErr)
+          resolvePromise({
+            child,
+            port: actualPort,
+            url: `http://127.0.0.1:${actualPort}`,
+            close: () => closeEmulator(child),
+          })
+        }
+      }
+    }
+    const onErr = (chunk: Buffer): void => {
+      log(`[emulator stderr] ${chunk.toString("utf8")}`)
+    }
+    child.stdout?.on("data", onData)
+    child.stderr?.on("data", onErr)
+    child.once("error", (err) => {
+      if (!settled) {
+        settled = true
+        reject(err)
+      }
+    })
+    child.once("exit", (code) => {
+      if (!settled) {
+        settled = true
+        reject(new Error(`emulator child exited early with code ${code}`))
+      }
+    })
+  })
+}
+
+const closeEmulator = (child: ChildProcess): Promise<void> =>
+  new Promise<void>((resolveClose) => {
+    if (child.exitCode !== null) {
+      resolveClose()
+      return
+    }
+    child.once("exit", () => resolveClose())
+    child.kill("SIGTERM")
+    setTimeout(() => {
+      if (child.exitCode === null) child.kill("SIGKILL")
+    }, 2000).unref()
+  })
+
+export const emulatorServerEntryExists = (
+  frontendEmulatorDir: string,
+): boolean => {
+  const main = resolve(frontendEmulatorDir, "src", "main")
+  const pkg = resolve(frontendEmulatorDir, "package.json")
+  return existsSync(main) && existsSync(pkg)
+}
+
+export const __test_internals = {
+  resolveEntry: (frontendEmulatorDir: string): string =>
+    resolve(frontendEmulatorDir, "src", "main"),
+}
+
+const _internalDirname = dirname(fileURLToPath(import.meta.url))
+void _internalDirname

package/src/render/icon-source-resolver.ts

@@ -0,0 +1,69 @@
+import { isAbsolute, join } from "node:path"
+
+import { EMOJI_RE } from "../core/icon-source"
+
+export interface ResolveIconPathOptions {
+  readonly addonDirs?: ReadonlyMap<string, string>
+  readonly baseDirs?: ReadonlyArray<string>
+}
+
+export type ResolvedIconSource =
+  | { kind: "generic"; name: string }
+  | { kind: "asset"; fullPath: string }
+  | { kind: "emoji"; emoji: string }
+
+export const resolveIconSource = (
+  source: string,
+  options: ResolveIconPathOptions = {},
+): ResolvedIconSource => {
+  if (EMOJI_RE.test(source)) {
+    // Emojis don't need any path resolution — the frontend renders them
+    // directly as a span. Returning a "generic" kind would be misleading
+    // (no icon name), so we have a dedicated "emoji" kind that callers
+    // can recognize and skip path/asset bookkeeping.
+    return { kind: "emoji", emoji: source }
+  }
+  if (source.startsWith("icon://")) {
+    return { kind: "generic", name: source.slice("icon://".length) }
+  }
+  if (source.startsWith("addon://")) {
+    const match = /^addon:\/\/([^/]+)\/(.*)$/.exec(source)
+    const [, addonName, assetPath] = match ?? []
+    if (addonName !== undefined && assetPath !== undefined) {
+      const addonDir = options.addonDirs?.get(addonName)
+      if (addonDir) {
+        return { kind: "asset", fullPath: join(addonDir, assetPath) }
+      }
+    }
+    throw new Error(`Cannot resolve addon icon "${source}": unknown addon dir`)
+  }
+  if (source.startsWith("builtin://")) {
+    const assetPath = source.slice("builtin://".length)
+    const builtinDir = options.addonDirs?.get("builtin")
+    if (builtinDir) {
+      return { kind: "asset", fullPath: join(builtinDir, assetPath) }
+    }
+    throw new Error(
+      `Cannot resolve builtin icon "${source}": builtin dir not registered`,
+    )
+  }
+  if (
+    source.startsWith("data:") ||
+    source.startsWith("http://") ||
+    source.startsWith("https://") ||
+    source.startsWith("file://")
+  ) {
+    throw new Error(
+      `Inline icon "${source.slice(0, 32)}…" must be pre-resolved to asset:// before reaching the Icon component`,
+    )
+  }
+  if (isAbsolute(source)) {
+    return { kind: "asset", fullPath: source }
+  }
+  // ponytail: returns on first baseDir; baseDirs is always 1 entry today (config dir).
+  // If multiple baseDirs ever get added, this needs a statSync existence check + iteration.
+  for (const baseDir of options.baseDirs ?? []) {
+    return { kind: "asset", fullPath: join(baseDir, source) }
+  }
+  throw new Error(`Cannot resolve icon "${source}": no base dirs configured`)
+}

package/src/render/index.ts

@@ -0,0 +1,16 @@
+export {
+  BrowserRenderer,
+  type BrowserRendererOptions,
+  type DeviceSink,
+  type PlaywrightLike,
+  type BrowserLike,
+  type ContextLike,
+  type PageLike,
+} from "./browser-renderer"
+export {
+  CadenceTimer,
+  EventDebouncer,
+  type CadenceTimerOptions,
+  type EventDebouncerOptions,
+} from "./screenshot-cadence"
+export { BufferChangeTracker, hashBuffer } from "./buffer-hash"