@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/builtin-addons/emoji-selector/decks/index.ts

@@ -0,0 +1,137 @@
+import type { AddonDeckEntry, AddonGeneratedDeck } from "@/addon/api"
+
+import { categories, type Emoji } from "../data/categories"
+import {
+  DEFAULT_FAVORITES,
+  EmojiSelectorDeckSchema,
+  type EmojiSelectorDeckConfig,
+} from "../support"
+
+// ponytail: build a char→shortcode lookup at module load so favorites
+// get their shortcode filled in without a separate data file.
+const CHAR_TO_SHORTCODE: ReadonlyMap<string, string | undefined> = new Map(
+  categories.flatMap((c) =>
+    c.emojis.map((e) => [e.char, e.shortcode] as const),
+  ),
+)
+
+const lookupShortcode = (char: string): string | undefined =>
+  CHAR_TO_SHORTCODE.get(char)
+
+const EMOJI_PAGE_SIZE = 13
+
+const FAVORITES = {
+  id: "favorites",
+  label: "Favorites",
+  icon: "⭐",
+} as const
+
+const buildCategoryDeckId = (baseDeckId: string, categoryId: string): string =>
+  `${baseDeckId}-${categoryId}`
+
+const buildEmojiDeck = (name: string, emojis: readonly Emoji[]) => {
+  return {
+    name,
+    buttons: emojis.map((emoji, offset) => ({
+      type: "emoji-selector:emoji",
+      emoji: emoji.char,
+      ...(emoji.shortcode !== undefined ? { shortcode: emoji.shortcode } : {}),
+      position: offset,
+      actions: {
+        tap: `type://${emoji.char}`,
+        ...(emoji.shortcode !== undefined
+          ? { dbltap: `type://:${emoji.shortcode}:` }
+          : {}),
+      },
+    })),
+    paginated: true,
+  }
+}
+
+const generateDecks = (
+  deck: { id: string },
+  config: EmojiSelectorDeckConfig,
+): Record<string, AddonGeneratedDeck> => {
+  const decks: Record<string, AddonGeneratedDeck> = {}
+  const favorites = (
+    config.favorites.length > 0 ? config.favorites : [...DEFAULT_FAVORITES]
+  ).map((emoji) => ({
+    char: emoji,
+    shortcode: lookupShortcode(emoji),
+  }))
+
+  const favoritesDeckId = buildCategoryDeckId(deck.id, FAVORITES.id)
+  decks[favoritesDeckId] = buildEmojiDeck(FAVORITES.label, favorites)
+
+  const topButtons: {
+    type: string
+    icon: string
+    label: string
+    position: number
+    target_deck: string
+  }[] = []
+
+  const favTotalPages = Math.max(
+    1,
+    Math.ceil(favorites.length / EMOJI_PAGE_SIZE),
+  )
+  topButtons.push({
+    type: "emoji-selector:category",
+    icon: FAVORITES.icon,
+    label: FAVORITES.label,
+    position: 0,
+    target_deck: favTotalPages > 1 ? `${favoritesDeckId}-p1` : favoritesDeckId,
+  })
+
+  categories.forEach((category, idx) => {
+    const categoryDeckId = buildCategoryDeckId(deck.id, category.id)
+    const totalPages = Math.max(
+      1,
+      Math.ceil(category.emojis.length / EMOJI_PAGE_SIZE),
+    )
+    decks[categoryDeckId] = buildEmojiDeck(category.label, category.emojis)
+    topButtons.push({
+      type: "emoji-selector:category",
+      icon: category.icon,
+      label: category.label,
+      position: idx + 1,
+      target_deck: totalPages > 1 ? `${categoryDeckId}-p1` : categoryDeckId,
+    })
+  })
+
+  decks[deck.id] = {
+    name: "Emoji Selector",
+    buttons: topButtons,
+    paginated: true,
+  }
+
+  return decks
+}
+
+// ponytail: phase 11 array form. The factory takes the addon's
+// runtime config (favorites override) and produces the multi-dynamic
+// record keyed by deck id. Each generated deck id is the run-time
+// identifier — `emoji-selector` is the launcher; `emoji-selector-<category>`
+// are the category drill-downs; the synthetic multi key isn't used
+// here because the factory has a fixed id.
+const emojiSelectorDeckEntry: AddonDeckEntry = {
+  createDecks: ({
+    config,
+  }: {
+    config: unknown
+    deck: { id: string }
+    keyCount: number
+  }): Record<string, AddonGeneratedDeck> => {
+    const cfg =
+      config && typeof config === "object" && "favorites" in config
+        ? (config as EmojiSelectorDeckConfig)
+        : { favorites: [] }
+    return generateDecks({ id: "emoji-selector" }, cfg)
+  },
+}
+
+export default emojiSelectorDeckEntry
+export {
+  emojiSelectorDeckEntry as emojiSelectorDeckFactory,
+  EmojiSelectorDeckSchema,
+}

package/src/builtin-addons/emoji-selector/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/emoji-selector/index.ts

@@ -0,0 +1,29 @@
+import type { AddonManifestV1 } from "@/addon/api"
+
+import categoryBackend from "./buttons/category/backend"
+import categoryFrontend from "./buttons/category/frontend"
+import emojiBackend from "./buttons/emoji/backend"
+import emojiFrontend from "./buttons/emoji/frontend"
+import launcherBackend from "./buttons/launcher/backend"
+import launcherFrontend from "./buttons/launcher/frontend"
+import emojiSelectorDeckEntry from "./decks"
+
+export const manifest: AddonManifestV1 = {
+  apiVersion: 1,
+  name: "emoji-selector",
+  buttonTypes: {
+    "emoji-selector:category": {
+      frontend: categoryFrontend,
+      service: categoryBackend,
+    },
+    "emoji-selector:emoji": { frontend: emojiFrontend, service: emojiBackend },
+    "emoji-selector:launcher": {
+      frontend: launcherFrontend,
+      service: { ...launcherBackend, gestureHandlers: ["tap"] as const },
+    },
+  },
+  decks: [emojiSelectorDeckEntry],
+}
+
+export const emojiSelectorAddon = manifest
+export default manifest

package/src/builtin-addons/emoji-selector/sirenodeck.json

@@ -0,0 +1,6 @@
+{
+  "kind": "addon",
+  "apiVersion": 1,
+  "name": "emoji-selector",
+  "entry": "index.ts"
+}

package/src/builtin-addons/emoji-selector/support.ts

@@ -0,0 +1,49 @@
+import { z } from "zod"
+
+export const EMOJI_LAUNCHER_GRID: readonly string[] = [
+  "\u{1F602}",
+  "\u{1F525}",
+  "\u2764\uFE0F",
+  "\u2B50",
+  "\u{1F355}",
+  "\u{1F3B5}",
+]
+
+export const EMOJI_FONT_STACK =
+  "'Apple Color Emoji', 'Segoe UI Emoji', 'Noto Color Emoji', 'Twemoji Mozilla', system-ui, sans-serif"
+
+export const DEFAULT_FAVORITES: readonly string[] = [
+  "❤️",
+  "🔥",
+  "⭐",
+  "😂",
+  "👍",
+  "🎉",
+  "💯",
+  "✨",
+  "🙏",
+  "👑",
+] as const
+
+export const EmojiLauncherButtonSchema = z
+  .object({
+    label: z.string().min(1).default("Emojis"),
+    // Curated favorites shown first in the emoji deck. Valid on the launcher
+    // button (this schema) AND on the per-deck override record
+    // (decks["emoji-selector:__multi__"].config.favorites); the launcher
+    // wins when both are set. Falls back to DEFAULT_FAVORITES.
+    favorites: z.array(z.string().min(1)).optional(),
+  })
+  .strict()
+
+export type EmojiLauncherButtonConfig = z.infer<
+  typeof EmojiLauncherButtonSchema
+>
+
+export const EmojiSelectorDeckSchema = z
+  .object({
+    favorites: z.array(z.string().min(1)).default([...DEFAULT_FAVORITES]),
+  })
+  .strict()
+
+export type EmojiSelectorDeckConfig = z.infer<typeof EmojiSelectorDeckSchema>

package/src/builtin-addons/index.ts

@@ -0,0 +1,13 @@
+export { SYSTEM_BUTTON_TYPES } from "@/deck/system-buttons/types"
+export { default as brightnessAddon } from "./brightness/index"
+export { coreAddon } from "./core/index"
+export { default as dateTimeAddon } from "./date-time/index"
+export { default as emojiSelectorAddon } from "./emoji-selector/index"
+export { internalSettingsAddon } from "./internal-settings/index"
+export { default as mediaPlayerAddon } from "./media/index"
+export { registerBuiltins } from "./register-builtins"
+export { sessionAddon } from "./session/index"
+export { systemStatusAddon } from "./system-status/index"
+export { default as testBuildinAddon } from "./test-buildin/index"
+export { default as valueDisplayAddon } from "./value-display/index"
+export { default as weatherAddon } from "./weather/index"

package/src/builtin-addons/internal-settings/README.md

@@ -0,0 +1,26 @@
+# internal-settings
+
+**Internal-only addon.** Provides the `settings` overlay deck (brightness up/down, app info). The runtime injects `settings` automatically when the `internal-settings:settings` deck is opened from the reserved `n-1` slot.
+
+You don't reference this addon directly in `config.yml`. The settings overlay is always available via the back/settings entry button on every deck.
+
+## Buttons
+
+| Type                                | Description                      |
+| ----------------------------------- | -------------------------------- |
+| `internal-settings:brightness-up`   | Increase screen brightness       |
+| `internal-settings:brightness-down` | Decrease screen brightness       |
+| `internal-settings:app-info`        | Shows the about / app info panel |
+
+## Decks
+
+| Deck id                      | Buttons                                              |
+| ---------------------------- | ---------------------------------------------------- |
+| `internal-settings:settings` | brightness-up (0), brightness-down (1), app-info (2) |
+
+The `settings` deck is auto-generated. The brightness buttons delegate to the OS provider's brightness control (see [brightness](../brightness/README.md)).
+
+## See also
+
+- [brightness](../brightness/README.md) — brightness OS provider
+- [Session](../session/README.md) — provides the `session:locked` overlay

package/src/builtin-addons/internal-settings/backend.ts

@@ -0,0 +1,58 @@
+import type pino from "pino"
+
+import { AddonServiceContext, AddonGlobalService } from "@/addon/api"
+import {
+  createBrightnessProvider,
+  type BrightnessProvider,
+} from "@/builtin-addons/brightness/providers"
+
+let brightnessProvider: BrightnessProvider | null = null
+
+const clampStep = (step: unknown, fallback: number): number => {
+  if (typeof step !== "number" || !Number.isFinite(step)) return fallback
+  return Math.max(0, Math.min(100, step))
+}
+
+const noOpLogger = {
+  info: () => undefined,
+  warn: () => undefined,
+} as unknown as pino.Logger
+
+export const globalService: AddonGlobalService = {
+  methods: {
+    brightnessUp: async (...args: readonly unknown[]) => {
+      if (brightnessProvider === null) return
+      const step = clampStep(args[0], 5)
+      const current = await brightnessProvider.getCurrent()
+      await brightnessProvider.setBrightness(
+        Math.min(100, current.value + step),
+      )
+    },
+    brightnessDown: async (...args: readonly unknown[]) => {
+      if (brightnessProvider === null) return
+      const step = clampStep(args[0], 5)
+      const current = await brightnessProvider.getCurrent()
+      await brightnessProvider.setBrightness(Math.max(0, current.value - step))
+    },
+  },
+  onLoad: (ctx: AddonServiceContext) => {
+    // ponytail: brightness providers speak the system-provider CommandExecutor
+    // dialect (command + args array); the addon executor runs a single shell
+    // string. Quote args and bridge the two — per-command timeouts are not
+    // needed for these one-shot probes.
+    const shellQuote = (value: string): string =>
+      `'${value.replaceAll("'", `'\\''`)}'`
+    const executor = {
+      run: async (command: string, args: ReadonlyArray<string>) =>
+        ctx.executor.run([command, ...args].map(shellQuote).join(" ")),
+    }
+    brightnessProvider = createBrightnessProvider({
+      executor,
+      platform: process.platform,
+      logger: noOpLogger,
+    })
+  },
+  onUnload: () => {
+    brightnessProvider = null
+  },
+}

package/src/builtin-addons/internal-settings/buttons/app-info/backend.ts

@@ -0,0 +1,7 @@
+import type { AddonButtonService } from "@/addon/api"
+
+export default {
+  onTap: async () => {
+    // no-op — display-only button
+  },
+} satisfies AddonButtonService

package/src/builtin-addons/internal-settings/buttons/app-info/config.ts

@@ -0,0 +1,13 @@
+import { z } from "zod"
+
+export const configSchema = z
+  .object({
+    icon: z
+      .string()
+      .min(1)
+      .optional()
+      .default("addon://internal-settings/logo72x72.png"),
+  })
+  .strict()
+
+export type ConfigSchema = z.infer<typeof configSchema>

package/src/builtin-addons/internal-settings/buttons/app-info/frontend.tsx

@@ -0,0 +1,18 @@
+import type { AddonFrontendButton } from "@/addon/api"
+import { Icon, Text } from "@/ui/index"
+
+import pkg from "../../../../../package.json" with { type: "json" }
+import type { ConfigSchema } from "./config"
+
+const version: string = typeof pkg.version === "string" ? pkg.version : "0.0.0"
+
+const AppInfoButtonFrontend: AddonFrontendButton<ConfigSchema> = ({
+  config,
+}) => (
+  <div className="flex h-full w-full items-center justify-center gap-1 flex-col">
+    <Icon source={config.icon} size={40} />
+    <Text text={version} />
+  </div>
+)
+
+export default AppInfoButtonFrontend

package/src/builtin-addons/internal-settings/buttons/brightness/common/frontend.tsx

@@ -0,0 +1,50 @@
+import type { AddonGestureEvent } from "@/addon/api"
+import { useAddonChannel } from "@/api/react"
+import { IconLabelProgressSurface } from "@/ui/index"
+import { useEffect, useRef, useState } from "react"
+
+const BRIGHTNESS_CHANNEL = "sireno:settings:brightness"
+const PROGRESS_VISIBLE_MS = 2000
+
+export type BrightnessVariant = "down" | "up"
+
+interface BrightnessButtonFrontendProps {
+  readonly variant: BrightnessVariant
+  readonly gesture?: AddonGestureEvent | null
+}
+
+export const BrightnessButtonFrontend = ({
+  variant,
+  gesture,
+}: BrightnessButtonFrontendProps) => {
+  const { data } = useAddonChannel<{ value: number }>(BRIGHTNESS_CHANNEL)
+  const progress = typeof data?.value === "number" ? data.value : 0
+  const [showProgress, setShowProgress] = useState(false)
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  useEffect(() => {
+    if (gesture?.gesture !== "tap" && gesture?.gesture !== "dbl-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" ? "sun-dim" : "sun"}`}
+      label={variant === "down" ? "Darker" : "Lighter"}
+      progress={progress}
+      visible={showProgress}
+    />
+  )
+}

package/src/builtin-addons/internal-settings/buttons/brightness-down/backend.ts

@@ -0,0 +1,16 @@
+import { z } from "zod"
+import type { AddonButtonTypeService } from "@/addon/api"
+
+import { configSchema } from "./config"
+
+type Config = z.infer<typeof configSchema>
+
+export default {
+  configSchema,
+  onTap: ({ coreMethods }) => {
+    coreMethods.adjustBrightness({ direction: "down" })
+  },
+  onDblTap: ({ coreMethods }) => {
+    coreMethods.adjustBrightness({ direction: "down" })
+  },
+} satisfies AddonButtonTypeService<Config>

package/src/builtin-addons/internal-settings/buttons/brightness-down/config.ts

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

package/src/builtin-addons/internal-settings/buttons/brightness-down/frontend.tsx

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

package/src/builtin-addons/internal-settings/buttons/brightness-up/backend.ts

@@ -0,0 +1,16 @@
+import { z } from "zod"
+import type { AddonButtonTypeService } from "@/addon/api"
+
+import { configSchema } from "./config"
+
+type Config = z.infer<typeof configSchema>
+
+export default {
+  configSchema,
+  onTap: ({ coreMethods }) => {
+    coreMethods.adjustBrightness({ direction: "up" })
+  },
+  onDblTap: ({ coreMethods }) => {
+    coreMethods.adjustBrightness({ direction: "up" })
+  },
+} satisfies AddonButtonTypeService<Config>

package/src/builtin-addons/internal-settings/buttons/brightness-up/config.ts

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

package/src/builtin-addons/internal-settings/buttons/brightness-up/frontend.tsx

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

package/src/builtin-addons/internal-settings/decks/settings.ts

@@ -0,0 +1,25 @@
+import type { AddonDeckFactory } from "@/addon/api"
+
+const settingsDeck: AddonDeckFactory = () => ({
+  name: "Settings",
+  buttons: [
+    {
+      id: "brightness-down",
+      type: "internal-settings:brightness-down",
+      position: 0,
+    },
+    {
+      id: "brightness-up",
+      type: "internal-settings:brightness-up",
+      position: 1,
+    },
+    {
+      id: "app-info",
+      type: "internal-settings:app-info",
+      position: 2,
+      config: { icon: "addon://internal-settings/logo72x72.png" },
+    },
+  ],
+})
+
+export default settingsDeck

package/src/builtin-addons/internal-settings/index.d.ts

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

package/src/builtin-addons/internal-settings/index.ts

@@ -0,0 +1,53 @@
+import type { AddonManifestV1 } from "@/addon/api"
+
+import appInfoBackend from "./buttons/app-info/backend"
+import appInfoFrontend from "./buttons/app-info/frontend"
+import brightnessDownBackend from "./buttons/brightness-down/backend"
+import brightnessDownFrontend from "./buttons/brightness-down/frontend"
+import brightnessUpBackend from "./buttons/brightness-up/backend"
+import brightnessUpFrontend from "./buttons/brightness-up/frontend"
+import settingsDeck from "./decks/settings"
+
+const withInternal = <T extends object>(impl: T): T & { internal: true } => ({
+  ...impl,
+  internal: true,
+})
+
+export const manifest: AddonManifestV1 = {
+  apiVersion: 1,
+  name: "internal-settings",
+  buttonTypes: {
+    "internal-settings:brightness-down": {
+      frontend: brightnessDownFrontend,
+      service: {
+        ...withInternal(brightnessDownBackend),
+        gestureHandlers: ["tap", "dbl-tap"] as const,
+      },
+    },
+    "internal-settings:brightness-up": {
+      frontend: brightnessUpFrontend,
+      service: {
+        ...withInternal(brightnessUpBackend),
+        gestureHandlers: ["tap", "dbl-tap"] as const,
+      },
+    },
+    "internal-settings:app-info": {
+      frontend: appInfoFrontend,
+      service: {
+        ...withInternal(appInfoBackend),
+        gestureHandlers: ["tap"] as const,
+        full: true,
+      },
+    },
+  },
+  decks: [
+    {
+      id: "internal-settings:settings",
+      createDeck: () => settingsDeck(0),
+      internal: true,
+    },
+  ],
+}
+
+export const internalSettingsAddon = manifest
+export default manifest

package/src/builtin-addons/internal-settings/sirenodeck.json

@@ -0,0 +1,6 @@
+{
+  "kind": "addon",
+  "apiVersion": 1,
+  "name": "internal-settings",
+  "entry": "index.ts"
+}

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

@@ -0,0 +1,45 @@
+# media
+
+Single button that shows the current track + play/pause state. Tap = play/pause. Hold = next track. The left half of the button is prev/play/pause, the right half is next/volume (split button).
+
+Uses the OS media provider from `packages/cli/src/system/providers/`:
+
+- Linux: `playerctl` (MPRIS)
+- macOS: `osascript`
+- Windows: PowerShell + UIA
+
+## Buttons
+
+| Type                | Description                                                     |
+| ------------------- | --------------------------------------------------------------- |
+| `media:player`      | Single button: prev / play-pause / next + volume (split action) |
+| `media:mute`        | Toggle mute                                                     |
+| `media:volume:up`   | Volume up by step                                               |
+| `media:volume:down` | Volume down by step                                             |
+
+## Config
+
+The `media:player` button has no config — it auto-discovers the OS media provider.
+
+```yaml
+- position: 12
+  type: media:player
+```
+
+## Example
+
+```yaml
+decks:
+  main:
+    name: Main
+    buttons:
+      - position: 12
+        type: media:player
+```
+
+Run `playerctl status` (Linux) or open Music (macOS) / Windows Media Player to see the state reflected on the button.
+
+## See also
+
+- [OS providers](../../../../system/providers/README.md) — media player integration per OS
+- [system-status](../system-status/README.md) — same addon pattern (no config, polls OS)