@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/builtin-addons/media/backend.ts

@@ -0,0 +1,143 @@
+import {
+  AddonServiceContext,
+  AddonServiceMethod,
+  AddonGlobalService,
+} from "@/addon"
+import { computeProgress } from "./progress"
+import { createMediaProvider, MediaStatusProvider } from "./providers"
+import type { MediaPlayerState } from "./state"
+
+const shellQuote = (arg: string): string => `'${arg.replace(/'/g, "'\\''")}'`
+
+const FALLBACK_STATE: MediaPlayerState = {
+  title: null,
+  artist: null,
+  source: null,
+  status: "notAvailable",
+  isPlaying: false,
+  volume: 0,
+  progress: 0,
+  currentTime: 0,
+  totalTime: 0,
+  muted: false,
+}
+
+let provider: MediaStatusProvider | null = null
+let ctxRef: AddonServiceContext | null = null
+
+const mapStatus = (
+  playStatus: Awaited<
+    ReturnType<MediaStatusProvider["getStatus"]>
+  >["playStatus"],
+): MediaPlayerState["status"] => {
+  if (
+    playStatus === "play" ||
+    playStatus === "pause" ||
+    playStatus === "stop"
+  ) {
+    return playStatus
+  }
+  // 'unavailable' (provider reachable but no data) → 'notAvailable'.
+  return "notAvailable"
+}
+
+const buildState = (
+  status: Awaited<ReturnType<MediaStatusProvider["getStatus"]>>,
+): MediaPlayerState => ({
+  title: status.track?.name ?? null,
+  artist: status.track?.artist ?? null,
+  source: status.track?.album ?? null,
+  status: mapStatus(status.playStatus),
+  isPlaying: status.playStatus === "play",
+  volume: Math.round(status.volume * 100),
+  progress: computeProgress(status.currentTime, status.totalTime),
+  currentTime: status.currentTime,
+  totalTime: status.totalTime,
+  muted: status.muted,
+})
+
+const wrap = (
+  action: (...args: readonly unknown[]) => Promise<void>,
+): AddonServiceMethod => {
+  return async (...args) => {
+    try {
+      await action(...args)
+    } catch (err) {
+      console.error("[media] action failed:", err)
+    }
+    await ctxRef?.poll("state")
+  }
+}
+
+export const globalService: AddonGlobalService = {
+  pollers: [
+    {
+      id: "state",
+      channel: "media:state",
+      intervalMs: 1_000,
+      poll: async (_ctx: AddonServiceContext): Promise<MediaPlayerState> => {
+        if (provider === null) return FALLBACK_STATE
+        try {
+          return buildState(await provider.getStatus())
+        } catch {
+          return FALLBACK_STATE
+        }
+      },
+    },
+  ],
+
+  methods: {
+    play: wrap(async () => {
+      await provider?.play()
+    }),
+    pause: wrap(async () => {
+      await provider?.pause()
+    }),
+    toggle: wrap(async () => {
+      await provider?.toggle()
+    }),
+    next: wrap(async () => {
+      await provider?.next()
+    }),
+    previous: wrap(async () => {
+      await provider?.previous()
+    }),
+    setVolume: wrap(async (...args: readonly unknown[]) => {
+      const value = typeof args[0] === "number" ? args[0] : 1
+      await provider?.setVolume(value)
+    }),
+    volumeUp: wrap(async (...args: readonly unknown[]) => {
+      const step = typeof args[0] === "number" ? args[0] : 0.05
+      await provider?.volumeUp(step)
+    }),
+    volumeDown: wrap(async (...args: readonly unknown[]) => {
+      const step = typeof args[0] === "number" ? args[0] : 0.05
+      await provider?.volumeDown(step)
+    }),
+    toggleMute: wrap(async () => {
+      await provider?.toggleMute()
+    }),
+  },
+
+  onLoad: (ctx: AddonServiceContext) => {
+    ctxRef = ctx
+    provider = createMediaProvider(process.platform, {
+      async run(
+        command: string,
+        args: readonly string[],
+        _options?: { timeoutMs?: number },
+      ) {
+        const shellCmd =
+          args.length === 0
+            ? command
+            : `${command} ${args.map(shellQuote).join(" ")}`
+        return ctx.executor.run(shellCmd)
+      },
+    })
+  },
+
+  onUnload: () => {
+    ctxRef = null
+    provider = null
+  },
+}

package/src/builtin-addons/media/buttons/media-player/backend.ts

@@ -0,0 +1,19 @@
+import type { AddonButtonTypeService } from "@/addon/api"
+import { configSchema } from "./config"
+
+export default {
+  configSchema,
+  onTap: async ({
+    methods,
+  }: {
+    methods: Record<string, (...args: unknown[]) => unknown>
+  }) => {
+    await methods["media:toggle"]?.()
+  },
+  onDblTap: async ({ methods }) => {
+    await methods["media:previous"]?.()
+  },
+  onHold: async ({ methods }) => {
+    await methods["media:next"]?.()
+  },
+} satisfies AddonButtonTypeService

package/src/builtin-addons/media/buttons/media-player/components/MediaStatus.tsx

@@ -0,0 +1,25 @@
+import { cn, Icon } from "@/ui"
+import { ReactElement } from "react"
+import { MediaButtonStatus, statusesMeta } from "./status-meta"
+
+export function MediaStatusIcon(props: {
+  status: MediaButtonStatus
+}): ReactElement {
+  const currentStatus =
+    statusesMeta[props.status] || statusesMeta["unsupported"]
+
+  const icon = currentStatus.icon
+  const bgColor = currentStatus.bgColor
+  const iconColor = currentStatus.iconColor
+
+  return (
+    <div
+      className={cn(
+        "w-6 h-6 rounded-full flex items-center justify-center overflow-hidden",
+        bgColor,
+      )}
+    >
+      <Icon source={`icon://${icon}`} size={14} fill tone={iconColor} />
+    </div>
+  )
+}

package/src/builtin-addons/media/buttons/media-player/components/MediaSurface.tsx

@@ -0,0 +1,52 @@
+import { formatTime } from "@/builtin-addons/media/progress"
+import { Text } from "@/ui/index"
+import type { ReactElement } from "react"
+import { MediaStatusIcon } from "./MediaStatus"
+import { ProgressBar } from "./ProgressBar"
+import { type MediaButtonStatus } from "./status-meta"
+
+interface MediaSurfaceProps {
+  title: string
+  artist: string
+  source: string
+  progress: number
+  status: MediaButtonStatus
+  currentTime: number
+  totalTime: number
+}
+
+export const MediaSurface = ({
+  title,
+  artist,
+  source: _source,
+  progress,
+  status,
+  currentTime,
+}: MediaSurfaceProps): ReactElement => {
+  return (
+    <div className="flex h-full w-full flex-col relative gap-0.5">
+      <div className="flex items-center justify-between gap-2">
+        <MediaStatusIcon status={status} />
+        <Text
+          align="right"
+          size="lg"
+          tone="primary"
+          weight="bold"
+          text={formatTime(currentTime)}
+        />
+      </div>
+
+      <Text
+        align="left"
+        fit="ellipsis"
+        size="md"
+        tone="fg"
+        weight="bold"
+        text={title}
+      />
+      <Text align="left" fit="ellipsis" size="sm" tone="muted" text={artist} />
+      <div className="flex-1"></div>
+      <ProgressBar status={status} value={progress} className="mb-1" />
+    </div>
+  )
+}

package/src/builtin-addons/media/buttons/media-player/components/ProgressBar.tsx

@@ -0,0 +1,21 @@
+import { cn } from "@/ui"
+import type { ReactElement } from "react"
+import type { MediaButtonStatus } from "./status-meta"
+import { statusesMeta } from "./status-meta"
+
+export const ProgressBar = (props: {
+  className?: string
+  status: MediaButtonStatus
+  value: number
+}): ReactElement => {
+  const bgColor = statusesMeta[props.status]?.bgColor || "bg-gray-500"
+  const bgColorAlt = statusesMeta[props.status]?.bgColorAlt || "bg-gray-300"
+  return (
+    <div className={cn("h-2 w-full rounded-4xl", bgColorAlt, props.className)}>
+      <div
+        className={cn(bgColor, "h-2 rounded-4xl")}
+        style={{ width: `${Math.min(100, Math.max(0, props.value))}%` }}
+      />
+    </div>
+  )
+}

package/src/builtin-addons/media/buttons/media-player/components/status-meta.ts

@@ -0,0 +1,36 @@
+import { IconTone } from "@/ui"
+import type { MediaButtonStatus } from "../../../state"
+
+export const statusesMeta: Record<
+  MediaButtonStatus,
+  { icon: string; bgColor: string; bgColorAlt: string; iconColor?: IconTone }
+> = {
+  pause: {
+    icon: "pause",
+    bgColor: "bg-muted/30",
+    bgColorAlt: "bg-muted/10",
+  },
+  play: {
+    icon: "play",
+    bgColor: "bg-primary",
+    bgColorAlt: "bg-primary/30",
+    iconColor: "foreground-contrast",
+  },
+  stop: {
+    icon: "square",
+    bgColor: "bg-danger/30",
+    bgColorAlt: "bg-danger/10",
+  },
+  unsupported: {
+    icon: "slash",
+    bgColor: "bg-danger/30",
+    bgColorAlt: "bg-danger/10",
+  },
+  notAvailable: {
+    icon: "slash",
+    bgColor: "bg-background/30",
+    bgColorAlt: "bg-background/10",
+  },
+}
+
+export type { MediaButtonStatus }

package/src/builtin-addons/media/buttons/media-player/config.ts

@@ -0,0 +1,4 @@
+import { z } from "zod"
+
+export const configSchema = z.object({})
+export type ConfigSchema = z.infer<typeof configSchema>

package/src/builtin-addons/media/buttons/media-player/frontend.tsx

@@ -0,0 +1,29 @@
+import type { AddonFrontendButton } from "@/addon/api"
+import { useAddonChannel } from "@/api/react"
+
+import { Icon } from "@/ui"
+import type { MediaPlayerState } from "../../state"
+import { MediaSurface } from "./components/MediaSurface"
+import { ConfigSchema } from "./config"
+
+const MediaPlayerButtonFrontend: AddonFrontendButton<ConfigSchema> = () => {
+  const { data } = useAddonChannel<MediaPlayerState>("media:state")
+
+  if (!data) {
+    return <Icon source="icon://hourglass" />
+  }
+
+  return (
+    <MediaSurface
+      title={data?.title ?? ""}
+      artist={data?.artist ?? ""}
+      source={data?.source ?? ""}
+      progress={data?.progress ?? 0}
+      currentTime={data?.currentTime ?? 0}
+      totalTime={data?.totalTime ?? 0}
+      status={data?.status ?? "notAvailable"}
+    />
+  )
+}
+
+export default MediaPlayerButtonFrontend

package/src/builtin-addons/media/buttons/volume/common/frontend.tsx

@@ -0,0 +1,52 @@
+import type { AddonGestureEvent } from "@/addon/api"
+import { useAddonChannel } from "@/api/react"
+import { IconLabelProgressSurface } from "@/ui/index"
+import { useEffect, useRef, useState } from "react"
+import type { MediaPlayerState } from "../../../state"
+
+const PROGRESS_VISIBLE_MS = 2000
+
+export type VolumeVariant = "down" | "up"
+
+interface VolumeButtonFrontendProps {
+  readonly variant: VolumeVariant
+  readonly gesture?: AddonGestureEvent | null
+}
+
+const VolumeButtonFrontend = ({
+  variant,
+  gesture,
+}: VolumeButtonFrontendProps) => {
+  const { data } = useAddonChannel<MediaPlayerState>("media:state")
+  const volume = data?.volume ?? 0
+  const [showProgress, setShowProgress] = useState(false)
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  useEffect(() => {
+    if (gesture?.gesture !== "tap") return
+    setShowProgress(true)
+    if (timerRef.current) clearTimeout(timerRef.current)
+    timerRef.current = setTimeout(
+      () => setShowProgress(false),
+      PROGRESS_VISIBLE_MS,
+    )
+  }, [gesture?.at])
+
+  useEffect(
+    () => () => {
+      if (timerRef.current) clearTimeout(timerRef.current)
+    },
+    [],
+  )
+
+  return (
+    <IconLabelProgressSurface
+      source={`icon://${variant === "down" ? "volume" : "volume-2"}`}
+      label={variant === "down" ? "Vol -" : "Vol +"}
+      progress={volume}
+      visible={showProgress}
+    />
+  )
+}
+
+export default VolumeButtonFrontend

package/src/builtin-addons/media/buttons/volume/mute/backend.ts

@@ -0,0 +1,13 @@
+import type { AddonButtonTypeService } from "@/addon/api"
+import { configSchema } from "./config"
+
+export default {
+  configSchema,
+  onTap: async ({
+    methods,
+  }: {
+    methods: Record<string, (...args: unknown[]) => unknown>
+  }) => {
+    await methods["media:toggleMute"]?.()
+  },
+} satisfies AddonButtonTypeService

package/src/builtin-addons/media/buttons/volume/mute/config.ts

@@ -0,0 +1,4 @@
+import { z } from "zod"
+
+export const configSchema = z.object({})
+export type ConfigSchema = z.infer<typeof configSchema>

package/src/builtin-addons/media/buttons/volume/mute/frontend.tsx

@@ -0,0 +1,26 @@
+import type { AddonFrontendButton } from "@/addon/api"
+import { useAddonChannel } from "@/api/react"
+import { IconLabelSurface } from "@/ui/index"
+import type { MediaPlayerState } from "../../../state"
+
+const MuteButtonFrontend: AddonFrontendButton<Record<string, never>> = () => {
+  const { data } = useAddonChannel<MediaPlayerState>("media:state")
+  const volume = data?.volume ?? 0
+  const muted = data?.muted ?? false
+
+  const isMuted = muted || volume === 0
+
+  const iconName = isMuted ? "volume-off" : "volume-2"
+
+  return (
+    <div className="flex h-full w-full flex-col items-center justify-center gap-1 relative">
+      <IconLabelSurface
+        key={iconName}
+        label="Mute"
+        source={`icon://${iconName}`}
+      />
+    </div>
+  )
+}
+
+export default MuteButtonFrontend

package/src/builtin-addons/media/buttons/volume/volume-down/backend.ts

@@ -0,0 +1,14 @@
+import { z } from "zod"
+import type { AddonButtonTypeService } from "@/addon/api"
+
+import { configSchema } from "./config"
+
+type Config = z.infer<typeof configSchema>
+
+export default {
+  configSchema,
+  onTap: async ({ config, methods }) => {
+    const step = (config.step ?? 5) / 100
+    await (methods["media:volumeDown"] as (s: number) => Promise<void>)?.(step)
+  },
+} satisfies AddonButtonTypeService<Config>

package/src/builtin-addons/media/buttons/volume/volume-down/config.ts

@@ -0,0 +1,6 @@
+import { z } from "zod"
+
+export const configSchema = z.object({
+  step: z.number().positive().default(5),
+})
+export type ConfigSchema = z.infer<typeof configSchema>

package/src/builtin-addons/media/buttons/volume/volume-down/frontend.tsx

@@ -0,0 +1,10 @@
+import type { AddonFrontendButton } from "@/addon/api"
+import VolumeButtonFrontend from "../common/frontend"
+
+const VolumeDownButtonFrontend: AddonFrontendButton<unknown> = ({
+  gesture,
+}) => {
+  return <VolumeButtonFrontend variant="down" gesture={gesture ?? null} />
+}
+
+export default VolumeDownButtonFrontend

package/src/builtin-addons/media/buttons/volume/volume-up/backend.ts

@@ -0,0 +1,14 @@
+import { z } from "zod"
+import type { AddonButtonTypeService } from "@/addon/api"
+
+import { configSchema } from "./config"
+
+type Config = z.infer<typeof configSchema>
+
+export default {
+  configSchema,
+  onTap: async ({ config, methods }) => {
+    const step = (config.step ?? 5) / 100
+    await (methods["media:volumeUp"] as (s: number) => Promise<void>)?.(step)
+  },
+} satisfies AddonButtonTypeService<Config>

package/src/builtin-addons/media/buttons/volume/volume-up/config.ts

@@ -0,0 +1,6 @@
+import { z } from "zod"
+
+export const configSchema = z.object({
+  step: z.number().positive().default(5),
+})
+export type ConfigSchema = z.infer<typeof configSchema>

package/src/builtin-addons/media/buttons/volume/volume-up/frontend.tsx

@@ -0,0 +1,8 @@
+import type { AddonFrontendButton } from "@/addon/api"
+import VolumeButtonFrontend from "../common/frontend"
+
+const VolumeUpButtonFrontend: AddonFrontendButton<unknown> = ({ gesture }) => {
+  return <VolumeButtonFrontend variant="up" gesture={gesture ?? null} />
+}
+
+export default VolumeUpButtonFrontend

package/src/builtin-addons/media/checks.ts

@@ -0,0 +1,104 @@
+import type { AddonCheck, AddonCheckResult } from "@/addon/api"
+import type { CommandExecutor } from "@/system/providers/shared"
+
+interface MediaChecksDeps {
+  readonly platform: NodeJS.Platform
+  readonly executor: CommandExecutor
+}
+
+const commandExists = async (
+  executor: CommandExecutor,
+  command: string,
+): Promise<boolean> => {
+  // `command` is a shell builtin, not an executable that execFile can spawn.
+  const quoted = `'${command.replaceAll(`'`, `'\\''`)}'`
+  const result = await executor.run("sh", ["-c", `command -v ${quoted}`])
+  return result.exitCode === 0 && result.stdout.trim().length > 0
+}
+
+// ponytail: each OS exposes a different media control surface. The
+// check should match the binary the provider actually invokes — if the
+// provider shells out to `playerctl`, the check looks for `playerctl`.
+// No need to instantiate the full provider; that would spawn real
+// subprocesses during preflight.
+const checkLinux = async ({
+  executor,
+}: MediaChecksDeps): Promise<AddonCheckResult> => {
+  const found: string[] = []
+  const missing: string[] = []
+  if (await commandExists(executor, "playerctl")) found.push("playerctl")
+  else missing.push("playerctl")
+  if (await commandExists(executor, "wpctl")) found.push("wpctl")
+  else missing.push("wpctl")
+  if (missing.length === 0) return { available: true }
+  return {
+    available: false,
+    reason: `install ${missing.join(", ")} (volume control needs wpctl on PipeWire/WirePlumber; transport needs playerctl)`,
+  }
+}
+
+const checkDarwin = async ({
+  executor,
+}: MediaChecksDeps): Promise<AddonCheckResult> => {
+  // ponytail: mirrors the Linux check's shape — there, playerctl is the
+  // system-wide MPRIS bridge and its absence is worth reporting. On macOS the
+  // equivalent is `media-control`: without it the provider can only talk to
+  // scriptable desktop players (Spotify, Music, TV) via AppleScript and will
+  // never see a browser, which is where most people actually play audio.
+  if (!(await commandExists(executor, "osascript"))) {
+    return {
+      available: false,
+      reason:
+        "install osascript (ships with macOS; needed for system volume control)",
+    }
+  }
+  if (await commandExists(executor, "media-control")) {
+    return { available: true }
+  }
+  return {
+    available: false,
+    reason:
+      "install media-control (`brew install media-control`) to detect playback from any app, browsers included; without it only Spotify/Music/TV are visible",
+  }
+}
+
+const checkWindows = async ({
+  executor,
+}: MediaChecksDeps): Promise<AddonCheckResult> => {
+  if (await commandExists(executor, "powershell")) {
+    return { available: true }
+  }
+  return {
+    available: false,
+    reason:
+      "install powershell (ships with Windows; needed for SMTC media control)",
+  }
+}
+
+const checkUnknown = async (): Promise<AddonCheckResult> => ({
+  available: false,
+  reason: "unsupported platform; media controls unavailable",
+})
+
+export const buildMediaAddonChecks = (
+  deps: MediaChecksDeps,
+): ReadonlyArray<AddonCheck> => {
+  const check = async (): Promise<AddonCheckResult> => {
+    switch (deps.platform) {
+      case "linux":
+        return checkLinux(deps)
+      case "darwin":
+        return checkDarwin(deps)
+      case "win32":
+        return checkWindows(deps)
+      default:
+        return checkUnknown()
+    }
+  }
+  return [
+    {
+      name: "media-control",
+      check,
+    },
+  ]
+}

package/src/builtin-addons/media/executor.ts

@@ -0,0 +1,36 @@
+import { execFile } from "node:child_process"
+
+import type { CommandExecutor } from "@/system/providers/shared"
+
+const execFileAsync = (
+  command: string,
+  args: ReadonlyArray<string>,
+  timeoutMs: number,
+): Promise<{ exitCode: number; stdout: string; stderr: string }> =>
+  new Promise((resolve) => {
+    execFile(
+      command,
+      [...args],
+      { timeout: timeoutMs },
+      (err, stdout, stderr) => {
+        const stdoutStr = typeof stdout === "string" ? stdout : ""
+        const stderrStr = typeof stderr === "string" ? stderr : ""
+        if (err !== null) {
+          const code = (err as NodeJS.ErrnoException).code
+          resolve({
+            exitCode: code === "ENOENT" ? 127 : 1,
+            stdout: stdoutStr,
+            stderr: stderrStr || err.message,
+          })
+          return
+        }
+        resolve({ exitCode: 0, stdout: stdoutStr, stderr: stderrStr })
+      },
+    )
+  })
+
+export const createChildProcessExecutor = (): CommandExecutor => ({
+  async run(command, args, options) {
+    return execFileAsync(command, args, options?.timeoutMs ?? 2_000)
+  },
+})

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

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