@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/api/react/registry.ts

@@ -0,0 +1,91 @@
+import type { Unsubscribe } from "@/api/addon"
+
+export type ChannelPayload = unknown
+
+type Listener = (payload: ChannelPayload) => void
+type AnnounceSubscribe = (channels: string[]) => void
+
+export class ChannelRegistry {
+  private static _instance: ChannelRegistry | null = null
+  private static _announceSubscribe: AnnounceSubscribe | null = null
+  private readonly lastPayloads = new Map<string, ChannelPayload>()
+  private readonly listeners = new Map<string, Set<Listener>>()
+  private readonly listenerCounts = new Map<string, number>()
+  private pendingChannels: string[] = []
+  private flushScheduled = false
+
+  static instance(): ChannelRegistry {
+    if (ChannelRegistry._instance === null) {
+      ChannelRegistry._instance = new ChannelRegistry()
+    }
+    return ChannelRegistry._instance
+  }
+
+  static resetForTests(): void {
+    ChannelRegistry._instance = null
+    ChannelRegistry._announceSubscribe = null
+  }
+
+  static setAnnounceSubscribe(cb: AnnounceSubscribe | null): void {
+    ChannelRegistry._announceSubscribe = cb
+  }
+
+  publish<T extends ChannelPayload>(channel: string, payload: T): void {
+    this.lastPayloads.set(channel, payload)
+    const set = this.listeners.get(channel)
+    if (set !== undefined) for (const l of set) l(payload)
+  }
+
+  subscribe<T extends ChannelPayload>(
+    channel: string,
+    cb: (payload: T) => void,
+  ): Unsubscribe {
+    let set = this.listeners.get(channel)
+    if (set === undefined) {
+      set = new Set()
+      this.listeners.set(channel, set)
+    }
+    const listener = cb as Listener
+    set.add(listener)
+
+    const prevCount = this.listenerCounts.get(channel) ?? 0
+    this.listenerCounts.set(channel, prevCount + 1)
+    if (prevCount === 0) {
+      this.pendingChannels.push(channel)
+      if (!this.flushScheduled) {
+        this.flushScheduled = true
+        queueMicrotask(() => this.flushPendingSubscriptions())
+      }
+    }
+
+    return () => {
+      set?.delete(listener)
+      const count = this.listenerCounts.get(channel) ?? 0
+      if (count <= 1) {
+        this.listenerCounts.delete(channel)
+      } else {
+        this.listenerCounts.set(channel, count - 1)
+      }
+    }
+  }
+
+  private flushPendingSubscriptions(): void {
+    this.flushScheduled = false
+    if (this.pendingChannels.length === 0) return
+    const channels = [...new Set(this.pendingChannels)]
+    this.pendingChannels = []
+    ChannelRegistry._announceSubscribe?.(channels)
+  }
+
+  last<T extends ChannelPayload>(channel: string): T | undefined {
+    return this.lastPayloads.get(channel) as T | undefined
+  }
+
+  clear(): void {
+    this.lastPayloads.clear()
+    this.listeners.clear()
+    this.listenerCounts.clear()
+    this.pendingChannels = []
+    this.flushScheduled = false
+  }
+}

package/src/api/react/use-addon-channel.ts

@@ -0,0 +1,26 @@
+import { useEffect, useState } from "react"
+
+import { ChannelRegistry } from "./registry"
+import type { ChannelPayload } from "@/api/addon"
+
+export interface UseAddonChannelReturn<T = unknown> {
+  data: T | undefined
+}
+
+export const useAddonChannel = <T = unknown>(
+  channel: string,
+): UseAddonChannelReturn<T> => {
+  const [data, setData] = useState<T | undefined>(() =>
+    ChannelRegistry.instance().last<T>(channel),
+  )
+
+  useEffect(() => {
+    return ChannelRegistry.instance().subscribe<T>(channel, (payload) => {
+      setData(payload)
+    })
+  }, [channel])
+
+  return { data }
+}
+
+export type { ChannelRegistry, ChannelPayload }

package/src/api/react/use-button-state.tsx

@@ -0,0 +1,23 @@
+import {
+  useAddonChannel,
+  type ChannelRegistry,
+  type ChannelPayload,
+} from "./use-addon-channel"
+
+export { useAddonChannel, type ChannelRegistry, type ChannelPayload }
+
+export interface UseButtonStateReturn<T = unknown> {
+  readonly state: T | undefined
+}
+
+export const useButtonState = <T = unknown,>(
+  addonName: string,
+  buttonType: string,
+  buttonId: string,
+): UseButtonStateReturn<T> => {
+  const channel = `${addonName}:${buttonType}:${buttonId}`
+  const { data } = useAddonChannel<T>(channel)
+  return { state: data }
+}
+
+export const NullButton = (): null => null

package/src/api/react/use-deck.ts

@@ -0,0 +1,24 @@
+import { useEffect, useState } from "react"
+
+import { ChannelRegistry } from "./registry"
+
+export interface UseDeckReturn {
+  activeDeckId: string | null
+}
+
+export const useDeck = (): UseDeckReturn => {
+  const [activeDeckId, setActiveDeckId] = useState<string | null>(
+    () => ChannelRegistry.instance().last<string>("runtime:activeDeck") ?? null,
+  )
+
+  useEffect(() => {
+    return ChannelRegistry.instance().subscribe<{ deckId: string }>(
+      "runtime:activeDeck",
+      (payload) => {
+        setActiveDeckId(payload.deckId)
+      },
+    )
+  }, [])
+
+  return { activeDeckId }
+}

package/src/builtin-addons/brightness/README.md

@@ -0,0 +1,51 @@
+# brightness
+
+Single button that adjusts screen brightness. Tap = action (up/down/set). The button shows the current brightness as a bar.
+
+Uses the OS provider from `packages/cli/src/system/providers/`:
+
+- Linux: `xrandr` / `brightnessctl` (whichever is available)
+- macOS: `osascript`
+- Windows: PowerShell + WMI
+
+## Buttons
+
+| Type                    | Description                                      |
+| ----------------------- | ------------------------------------------------ |
+| `brightness:brightness` | Single button: shows + adjusts screen brightness |
+
+## Config
+
+```yaml
+- position: 5
+  type: brightness:brightness
+  config:
+    action: up # "up" (default), "down", or "set"
+    value: 75 # required for "set" (0-100); ignored for up/down
+```
+
+### Gesture semantics
+
+- **Tap** on a `brightness:brightness` button → executes the configured `action`.
+- **Hold** on a `brightness:brightness` button → toggles between `up` and `down` for fine-grained adjustment.
+
+## Example
+
+In your `settings` deck (auto-generated by `internal-settings`):
+
+```yaml
+decks:
+  settings:
+    name: Settings
+    buttons:
+      - position: 0
+        type: brightness:brightness
+        config: { action: up }
+```
+
+Run `xrandr --output eDP-1 --brightness 0.75` (Linux) to verify the action works on your system.
+
+## See also
+
+- [system-status](../system-status/README.md) — same polling pattern; brightness is just a one-button metric
+- [OS providers](../../../../system/providers/README.md) — brightness provider per OS

package/src/builtin-addons/brightness/buttons/brightness/backend.ts

@@ -0,0 +1,13 @@
+import type { AddonButtonTypeService } from "@/addon/api"
+
+import { buildMacOSCommand, formatCommand, isMacOS } from "../../domain/macos"
+import { configSchema, type ConfigSchema } from "./config"
+
+export default {
+  configSchema,
+  defaultRenderIntervalMs: 2000,
+  onTap: ({ config, executor }) => {
+    if (!isMacOS(process.platform)) return
+    void executor.run(formatCommand(buildMacOSCommand(config))).catch(() => {})
+  },
+} satisfies AddonButtonTypeService<ConfigSchema>

package/src/builtin-addons/brightness/buttons/brightness/config.ts

@@ -0,0 +1,10 @@
+import { z } from "zod"
+
+export const configSchema = z
+  .object({
+    action: z.enum(["up", "down", "set"]).optional().default("up"),
+    value: z.number().int().min(0).max(100).optional(),
+  })
+  .strict()
+
+export type ConfigSchema = z.infer<typeof configSchema>

package/src/builtin-addons/brightness/buttons/brightness/frontend.tsx

@@ -0,0 +1,50 @@
+import { Text } from "@/ui/index"
+import { useAddonChannel } from "@/api/react"
+import type { AddonFrontendButton } from "@/addon/api"
+
+import type { ConfigSchema } from "./config"
+
+interface BrightnessState {
+  readonly value: number
+  readonly max: number
+}
+
+const BrightnessButtonFrontend: AddonFrontendButton<ConfigSchema> = ({
+  config,
+}) => {
+  const { action } = config ?? {}
+  const { data } = useAddonChannel<BrightnessState>("brightness:current")
+  if (data === undefined) {
+    return (
+      <Text
+        size="xs"
+        tone="muted"
+        typography="mono"
+        className="flex h-full w-full items-center justify-center"
+        text="—"
+      />
+    )
+  }
+  const pct = Math.max(0, Math.min(100, (data.value / (data.max || 100)) * 100))
+  return (
+    <span className="flex h-full w-full flex-col items-stretch justify-center gap-1 p-2">
+      <span className="flex items-baseline justify-between">
+        <Text size="xs" tone="muted" fit="ellipsis" text="Brightness" />
+        <Text size="xs" tone="fg" text={`${pct.toFixed(0)}%`} />
+      </span>
+      <span className="block h-1.5 w-full overflow-hidden rounded bg-bar">
+        <span className="block h-full bg-accent" style={{ width: `${pct}%` }} />
+      </span>
+      <Text
+        size="xs"
+        tone="muted"
+        className="text-center"
+        typography="aux"
+        text={`Tap: ${action ?? "up"}`}
+      />
+    </span>
+  )
+}
+
+export default BrightnessButtonFrontend
+export { BrightnessButtonFrontend }

package/src/builtin-addons/brightness/domain/macos.ts

@@ -0,0 +1,46 @@
+import type { ConfigSchema as BrightnessButtonConfig } from "../buttons/brightness/config"
+
+const escape = (s: string): string => `'${s.replaceAll("'", "'\\''")}'`
+
+export const isMacOS = (platform: NodeJS.Platform): boolean =>
+  platform === "darwin"
+
+export const setBrightnessMacOS = async (
+  config: BrightnessButtonConfig,
+  exec: (
+    cmd: string,
+    args: string[],
+  ) => Promise<{ exitCode: number; stderr: string }>,
+): Promise<void> => {
+  if (config.action === "set" && config.value !== undefined) {
+    const script = `tell application "System Events" to set brightness of (first item of (get displays)) to ${config.value / 100}`
+    await exec("osascript", ["-e", script])
+    return
+  }
+  if (config.action === "down") {
+    await exec("osascript", [
+      "-e",
+      `tell application "System Events" to key code 145`,
+    ])
+    return
+  }
+  await exec("osascript", [
+    "-e",
+    `tell application "System Events" to key code 144`,
+  ])
+}
+
+export const buildMacOSCommand = (
+  config: BrightnessButtonConfig,
+): readonly string[] => {
+  if (config.action === "set" && config.value !== undefined) {
+    return ["osascript", "-e", `set brightness to ${config.value / 100}`]
+  }
+  if (config.action === "down") {
+    return ["osascript", "-e", `key code 145`]
+  }
+  return ["osascript", "-e", `key code 144`]
+}
+
+export const formatCommand = (cmd: readonly string[]): string =>
+  cmd.map(escape).join(" ")

package/src/builtin-addons/brightness/index.d.ts

@@ -0,0 +1,5 @@
+import type { NewAddonManifest } from "@/addon/api"
+
+declare const manifest: NewAddonManifest
+export default manifest
+export { manifest }

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

@@ -0,0 +1,20 @@
+import type { AddonManifestV1 } from "@/addon/api"
+
+import brightnessBackend from "./buttons/brightness/backend"
+import brightnessFrontend from "./buttons/brightness/frontend"
+
+export const manifest: AddonManifestV1 = {
+  apiVersion: 1,
+  name: "brightness",
+  buttonTypes: {
+    "brightness:brightness": {
+      frontend: brightnessFrontend,
+      service: { ...brightnessBackend, gestureHandlers: ["tap"] as const },
+    },
+  },
+  publishIntervalMs: 2000,
+}
+
+export const brightnessAddon = manifest
+export default manifest
+export { brightnessBackend, brightnessFrontend }

package/src/builtin-addons/brightness/poller.ts

@@ -0,0 +1,27 @@
+import type { AddonPoller } from "@/addon/api-types"
+
+import type { BrightnessProvider } from "./providers"
+
+export interface BrightnessPollerDeps {
+  readonly brightnessProvider: BrightnessProvider | null
+}
+
+export const createPoller = (deps: BrightnessPollerDeps): AddonPoller => ({
+  channels: [
+    {
+      channel: "brightness:current",
+      intervalMs: 2_000,
+      poll: async () => {
+        if (deps.brightnessProvider === null) {
+          return { value: 0, max: 100 }
+        }
+        try {
+          const reading = await deps.brightnessProvider.getCurrent()
+          return { value: reading.value, max: reading.max }
+        } catch {
+          return { value: 0, max: 100 }
+        }
+      },
+    },
+  ],
+})

package/src/builtin-addons/brightness/providers/darwin.ts

@@ -0,0 +1,107 @@
+import type pino from "pino"
+
+import { type CommandExecutor } from "@/system/providers/shared"
+
+import {
+  createNullBrightnessProvider,
+  type BrightnessProvider,
+  type BrightnessReading,
+} from "./index"
+
+export interface CreateDarwinBrightnessProviderOptions {
+  readonly executor: CommandExecutor
+  readonly logger: pino.Logger
+}
+
+// ponytail: this provider used to shell out to
+// `tell application "System Events" to get brightness of (every item of
+// displays)`. System Events has no `displays` element, so every call failed
+// with "The variable displays is not defined (-2753)" and brightness has never
+// worked on macOS. There is no public CLI or ioreg node for display brightness
+// on Apple Silicon (it moved into the private DisplayServices framework), so
+// the honest options are the `brightness` Homebrew binary or nothing.
+//
+// `brightness -l` prints one "display N: brightness 0.550000" line per display;
+// `brightness <0..1>` sets every display. Values are 0..1 on the wire and
+// 0..100 across the BrightnessProvider interface.
+const BRIGHTNESS_BIN = "brightness"
+const INSTALL_HINT = "install it with `brew install brightness`"
+
+const BRIGHTNESS_LINE = /display\s+\d+:\s+brightness\s+([0-9]*\.?[0-9]+)/i
+
+export const parseBrightnessList = (
+  stdout: string,
+): BrightnessReading | null => {
+  const match = BRIGHTNESS_LINE.exec(stdout)
+  if (match?.[1] === undefined) return null
+  const fraction = Number.parseFloat(match[1])
+  if (!Number.isFinite(fraction)) return null
+  const clamped = Math.max(0, Math.min(1, fraction))
+  return { value: Math.round(clamped * 100), max: 100 }
+}
+
+export const createDarwinBrightnessProvider = (
+  options: CreateDarwinBrightnessProviderOptions,
+): BrightnessProvider => {
+  const { executor, logger } = options
+  const nullProvider = createNullBrightnessProvider(logger)
+  let disposed = false
+  // Warn once, not on every poll tick.
+  let warnedMissing = false
+
+  const warnMissing = (detail: string): void => {
+    if (warnedMissing) return
+    warnedMissing = true
+    logger.warn(
+      { bin: BRIGHTNESS_BIN, detail },
+      `brightness: '${BRIGHTNESS_BIN}' unavailable — ${INSTALL_HINT}`,
+    )
+  }
+
+  const stop = async (): Promise<void> => {
+    disposed = true
+  }
+
+  const getCurrent = async (): Promise<BrightnessReading> => {
+    if (disposed) throw new Error("Brightness provider is disposed")
+    let result
+    try {
+      result = await executor.run(BRIGHTNESS_BIN, ["-l"], { timeoutMs: 2_000 })
+    } catch (err) {
+      warnMissing((err as Error).message)
+      return nullProvider.getCurrent()
+    }
+    if (result.exitCode !== 0) {
+      warnMissing(result.stderr.trim() || `exit ${result.exitCode}`)
+      return nullProvider.getCurrent()
+    }
+    const parsed = parseBrightnessList(result.stdout)
+    if (parsed === null) {
+      logger.warn(
+        { stdout: result.stdout.slice(0, 200) },
+        "brightness: could not parse `brightness -l` output",
+      )
+      return nullProvider.getCurrent()
+    }
+    return parsed
+  }
+
+  const setBrightness = async (value: number): Promise<void> => {
+    if (disposed) throw new Error("Brightness provider is disposed")
+    const fraction = Math.max(0, Math.min(100, Math.round(value))) / 100
+    let result
+    try {
+      result = await executor.run(BRIGHTNESS_BIN, [fraction.toFixed(3)], {
+        timeoutMs: 2_000,
+      })
+    } catch (err) {
+      warnMissing((err as Error).message)
+      return
+    }
+    if (result.exitCode !== 0) {
+      warnMissing(result.stderr.trim() || `exit ${result.exitCode}`)
+    }
+  }
+
+  return { getCurrent, setBrightness, stop }
+}

package/src/builtin-addons/brightness/providers/index.ts

@@ -0,0 +1,81 @@
+import type pino from "pino"
+
+import { ProviderError } from "@/system/providers/error"
+
+import { createDarwinBrightnessProvider } from "./darwin"
+import { createLinuxBrightnessProvider } from "./linux"
+import { type CommandExecutor } from "@/system/providers/shared"
+import { createWindowsBrightnessProvider } from "./windows"
+
+export interface BrightnessReading {
+  readonly value: number
+  readonly max: number
+}
+
+export interface BrightnessProvider {
+  getCurrent(): Promise<BrightnessReading>
+  setBrightness(value: number): Promise<void>
+  stop(): Promise<void>
+}
+
+export const createNullBrightnessProvider = (
+  logger?: pino.Logger,
+): BrightnessProvider => {
+  if (logger) {
+    logger.warn(
+      { provider: "brightness" },
+      "OS brightness provider unavailable, using null provider",
+    )
+  }
+  return {
+    async getCurrent(): Promise<BrightnessReading> {
+      return { value: 0, max: 100 }
+    },
+    async setBrightness(_value: number): Promise<void> {
+      throw new ProviderError(
+        "NOT_AVAILABLE",
+        "Brightness provider not available on this platform",
+      )
+    },
+    async stop() {
+      return
+    },
+  }
+}
+
+export interface CreateBrightnessProviderOptions {
+  readonly executor: CommandExecutor
+  readonly platform?: NodeJS.Platform
+  readonly env?: Readonly<Record<string, string>>
+  readonly logger: pino.Logger
+}
+
+export const createBrightnessProvider = (
+  options: CreateBrightnessProviderOptions,
+): BrightnessProvider => {
+  const platform = options.platform ?? process.platform
+  if (platform === "linux") {
+    return createLinuxBrightnessProvider({
+      executor: options.executor,
+      env: options.env,
+      logger: options.logger,
+    })
+  }
+  if (platform === "darwin") {
+    return createDarwinBrightnessProvider({
+      executor: options.executor,
+      logger: options.logger,
+    })
+  }
+  if (platform === "win32") {
+    return createWindowsBrightnessProvider({
+      executor: options.executor,
+      logger: options.logger,
+    })
+  }
+  void createNullBrightnessProvider(options.logger)
+  throw new ProviderError(
+    "UNSUPPORTED_PLATFORM",
+    `Brightness provider not implemented for platform '${platform}' in this build`,
+  )
+}