@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/addon/api.ts

@@ -0,0 +1,461 @@
+import type { ComponentType } from "react"
+
+import type { z } from "zod"
+
+import type { ActionExecutor } from "@/action/executor"
+import type { Store } from "@/core/store"
+import type { GestureKind } from "@/core/gesture-state"
+
+export type { GestureKind }
+import type { Methods } from "@/deck/methods"
+
+/** The runtime manifest API version (`AddonManifestV1`). */
+export const SIRENO_ADDON_API_VERSION = 1 as const
+
+export type AddonKind = "runtime" | "theme"
+export type AddonManifestKind = "addon" | "theme"
+
+/**
+ * Per-button gesture stream delivered to addon renderers. `null` when no
+ * gesture has fired since the last handoff. See `AddonFrontendButtonProps.gesture`.
+ */
+export interface AddonGestureEvent {
+  readonly gesture: GestureKind
+  readonly at: number
+}
+
+export interface AddonButtonTypeRenderContext {
+  config: unknown
+  pressed: boolean
+  addonName: string
+  frameState: unknown
+}
+
+export interface AddonButtonTypeActionContext {
+  config: unknown
+  pressed: boolean
+  addonName: string
+  hostContext: Record<string, unknown>
+  methods: Record<string, (...args: unknown[]) => unknown>
+}
+
+export interface AddonAssets {
+  styles?: string[]
+}
+
+export interface AddonFrontend {
+  main: string
+  styles?: string[]
+}
+
+export interface AddonManifest {
+  apiVersion: number
+  kind?: AddonKind
+  main?: string
+  frontend?: AddonFrontend
+  css?: string
+  name?: string
+  version?: string
+  description?: string
+  publishIntervalMs?: number
+}
+
+export interface LoadedTheme {
+  name: string
+  apiVersion: number
+  source: {
+    kind: "builtin" | "sibling" | "local" | "npm"
+    resolvedPath: string
+  }
+  manifestPath: string
+  uiOverridesPath: string | null
+  cssPath: string
+}
+
+export interface AddonLoadIssue {
+  level: "error" | "warning" | "info"
+  source: string
+  message: string
+}
+
+export interface AddonFrontendButtonProps<Config> {
+  readonly config: Config
+  readonly state: unknown
+  readonly addonName: string
+  readonly buttonType: string
+  readonly buttonId: string
+  /**
+   * Latest gesture delivered to this specific button since the previous
+   * commit. `null` when no gesture is pending. The renderer is expected to
+   * react in a `useEffect([gesture])` and the parent (Deck) will clear the
+   * value in a post-commit pass so unrelated re-renders do not re-fire it.
+   *
+   * Source: hardware + emulator only — never emitted for frontend-emulated
+   * clicks (those arrive via the WS `button-action` path which calls
+   * `runtime.invokeAction`, bypassing the gesture listener).
+   */
+  readonly gesture: AddonGestureEvent | null
+}
+
+export type AddonFrontendButton<Config> = ComponentType<
+  AddonFrontendButtonProps<Config>
+>
+
+export interface AddonButtonTypeService<Config = unknown> {
+  readonly configSchema?: unknown
+  readonly defaultRenderIntervalMs?: number
+  readonly internal?: boolean
+  readonly full?: boolean
+  /**
+   * Opt-in gesture allowlist. If the service declares onTap/onDblTap/onHold
+   * but this field is missing, the runtime logs a warning and strips the
+   * undeclared handlers (default-deny). If present, only listed gestures fire.
+   */
+  readonly gestureHandlers?: ReadonlyArray<GestureKind>
+  readonly onMount?: (
+    ctx: AddonButtonServiceContext<Config>,
+  ) => void | Promise<void>
+  readonly onTap?: (
+    ctx: AddonButtonServiceContext<Config>,
+  ) => void | Promise<void>
+  readonly onDblTap?: (
+    ctx: AddonButtonServiceContext<Config>,
+  ) => void | Promise<void>
+  readonly onHold?: (
+    ctx: AddonButtonServiceContext<Config>,
+  ) => void | Promise<void>
+  readonly dispose?: (
+    ctx: AddonButtonServiceContext<Config>,
+  ) => void | Promise<void>
+}
+
+export interface AddonButtonTypeDef<Config = unknown> {
+  readonly frontend: AddonFrontendButton<Config>
+  readonly service: AddonButtonTypeService<Config>
+}
+
+export interface AddonButtonTypeDefAny {
+  readonly frontend: AddonFrontendButton<any>
+  readonly service: AddonButtonTypeService<any>
+  readonly name?: string
+  readonly internal?: boolean
+}
+
+export type AddonDeckFactory = (page: number) => AddonGeneratedDeck
+
+export interface AddonDeckDefinition {
+  type: string
+  configSchema?: unknown
+  createDecks: (ctx: {
+    config: unknown
+    deck: { id: string }
+    keyCount: number
+  }) => Record<string, AddonGeneratedDeck>
+  internal?: boolean
+}
+
+export interface AddonGeneratedDeck {
+  name?: string
+  icon?: string
+  background?: string
+  /**
+   * Variant token name. Themes declare which variants they support in
+   * their manifest; addon authors pick from the active theme's set.
+   * Unknown names fall back to "default" with a console.warn at render.
+   *
+   * `variant` is the *semantic* axis: highlighted / warning / success / error.
+   * Use it when the colour carries meaning (recording, paused, errored).
+   */
+  variant?: string
+  /**
+   * Per-button hue customisation — closed enum, distinct from `variant`.
+   * Themes declare a variant entry for each enum value they want to
+   * expose (e.g. `blue`, `cyan`); unknown names fall back to `default`
+   * with a console.warn at render. Use it to distinguish buttons
+   * inside a deck by colour (e.g. six app-shortcuts, each a different
+   * hue) without claiming semantic meaning.
+   */
+  buttonColor?:
+    | "blue"
+    | "green"
+    | "purple"
+    | "cyan"
+    | "magenta"
+    | "amber"
+    | "lime"
+  buttons?: unknown[]
+  paginated?: boolean
+  trigger?: unknown
+  autoShow?: boolean
+  isOverlay?: boolean
+}
+
+/**
+ * Phase 11: addon manifest deck entries. Three shapes, each an item in
+ * the manifest's `decks: ReadonlyArray<AddonDeckEntry>`:
+ *
+ * - Static: the entry itself IS the generated deck (id + AddonGeneratedDeck fields).
+ * - Single-dynamic: `createDeck(ctx)` returns ONE AddonGeneratedDeck under `id`.
+ * - Multi-dynamic: `createDecks(ctx)` returns a record keyed by `<addon>:<deck>`.
+ *
+ * The `type` field is gone — `id` (or the keys returned from createDecks) is the
+ * canonical deck-type key. Hard cutover from the legacy Record<key, AddonDeckDefinition>
+ * shape; AddonRegistry.load() rejects that at runtime.
+ */
+export type AddonDeckEntryCtx = {
+  config: unknown
+  deck: { id: string }
+  keyCount: number
+}
+
+export type AddonDeckEntry =
+  | (AddonGeneratedDeck & {
+      id: string
+      createDeck?: never
+      createDecks?: never
+      internal?: boolean
+    })
+  | {
+      id: string
+      createDeck: (ctx: AddonDeckEntryCtx) => AddonGeneratedDeck
+      createDecks?: never
+      internal?: boolean
+    }
+  | {
+      id?: undefined
+      createDeck?: never
+      createDecks: (
+        ctx: AddonDeckEntryCtx,
+      ) => Record<string, AddonGeneratedDeck>
+      internal?: boolean
+    }
+
+/**
+ * Runtime addon manifest. Both builtin and third-party addons export this from
+ * their entry file (`index.ts` in dev, `index.js` in prod).
+ *
+ * The `entry` field on `AddonJsonManifest` points at the file that exports this;
+ * the runtime loads it via dynamic `import()` and passes it to `AddonRegistry.load()`.
+ *
+ * `defaultButton` declares one of this addon's button types as the default. When
+ * set, users may write `type: <addonName>` in `config.yml` as a shorthand for
+ * `<defaultButton>` (e.g. `type: emoji-selector` resolves to
+ * `emoji-selector:launcher`). The value must be a key of `buttonTypes`.
+ */
+/**
+ * Result of a single addon requirement check. Probes external dependencies
+ * (e.g. `playerctl` for media on Linux); failures are expected when the
+ * tool isn't installed and are surfaced as warnings, not exceptions.
+ */
+export interface AddonCheckResult {
+  readonly available: boolean
+  readonly reason?: string
+}
+
+/**
+ * A named requirement check contributed by an addon. The check function
+ * probes external state and returns a structured result; it should not
+ * throw — unexpected errors are caught by the runner and reported as
+ * failures.
+ */
+export interface AddonCheck {
+  readonly name: string
+  readonly check: () => Promise<AddonCheckResult>
+}
+
+export interface AddonManifestV1 {
+  readonly apiVersion: 1
+  readonly name: string
+  readonly kind?: AddonKind
+  readonly buttonTypes: Readonly<Record<string, AddonButtonTypeDefAny>>
+  readonly defaultButton?: string
+  readonly decks?: ReadonlyArray<AddonDeckEntry>
+  readonly frontend?: AddonFrontend
+  readonly poller?: {
+    readonly channels: ReadonlyArray<{
+      readonly channel: string
+      readonly intervalMs: number
+      readonly poll: () => unknown | Promise<unknown>
+    }>
+  }
+  readonly publishIntervalMs?: number
+  readonly globalService?: AddonGlobalService
+  /**
+   * Optional list of OS-specific requirement checks. Core runs these
+   * for enabled addons on start/restart and displays pass/fail in the
+   * startup banner. Checks never block startup — they only surface
+   * configuration gaps so the operator can act on them.
+   */
+  readonly checks?: ReadonlyArray<AddonCheck>
+}
+
+/**
+ * Addon-global service. Runs for the lifetime of the addon (while the addon
+ * is loaded). Multiple instances of the same button type share this state.
+ *
+ * - `pollers` are started when the addon activates and stopped when it
+ *   deactivates; each publishes on a named channel that frontends consume
+ *   via the bridge.
+ * - `subscriptions` are push-based sources (file watchers, sockets); they
+ *   publish on the same channels.
+ * - `methods` is the namespaced API surface available to per-button
+ *   services via `ctx.methods.<name>`.
+ * - `onLoad`/`onUnload` are the explicit lifecycle hooks; the runtime
+ *   passes an `AbortSignal` so cleanup is automatic.
+ */
+export interface AddonGlobalService {
+  readonly pollers?: ReadonlyArray<AddonGlobalPoller>
+  readonly subscriptions?: ReadonlyArray<AddonGlobalSubscription>
+  readonly methods?: Readonly<Record<string, AddonServiceMethod>>
+  // onLoad/onUnload accept an optional addon-specific config (typed as
+  // `unknown` since the runtime doesn't know the addon's config shape).
+  // Built-in addons ignore it; third-party / builtin addons that need
+  // hydrated state can read it. The runtime calls these once per process.
+  readonly onLoad?: (
+    ctx: AddonServiceContext,
+    config?: unknown,
+  ) => void | Promise<void>
+  readonly onUnload?: (
+    ctx: AddonServiceContext,
+    config?: unknown,
+  ) => void | Promise<void>
+}
+
+export type AddonServiceMethod = (
+  ...args: readonly unknown[]
+) => unknown | Promise<unknown>
+
+export interface AddonGlobalPoller {
+  readonly id: string
+  readonly channel: string
+  readonly intervalMs: number
+  readonly poll: (ctx: AddonServiceContext) => unknown | Promise<unknown>
+}
+
+export interface AddonGlobalSubscription {
+  readonly channel: string
+  readonly subscribe: (ctx: AddonServiceContext) => { unsubscribe: () => void }
+}
+
+export interface AddonServiceContext {
+  /** Push data to the channel this poller/subscription is bound to. */
+  publish: (data: unknown) => void
+  /**
+   * Trigger the poller with the given id (within this addon) immediately and
+   * broadcast its result. Useful after a `methods` call to reflect the new
+   * state without waiting for the next polling tick. Unknown ids are no-ops;
+   * poller errors are logged and swallowed.
+   */
+  poll: (id: string) => Promise<void>
+  /** Aborted when the addon unloads. */
+  signal: AbortSignal
+  /** Run host commands (e.g. `brightness set 80`). */
+  executor: ActionExecutor
+  /** Fire an OS notification. */
+  notify(args: { title: string; body: string; sound?: boolean }): Promise<void>
+  /**
+   * Ask the host to re-materialize addon decks (dynamic deck shape). No-op
+   * when the host hasn't wired a rebuilder.
+   */
+  requestDeckRebuild?: () => void
+}
+
+/**
+ * Per-button service. One instance is created per rendered button of this
+ * type; the instance is disposed when the last instance unmounts.
+ *
+ * The runtime merges the addon-global service's `methods` into the action
+ * context so per-button services can call shared APIs without importing
+ * the addon's internals.
+ */
+export interface AddonButtonService<Config = unknown> {
+  readonly onMount?: (
+    ctx: AddonButtonServiceContext<Config>,
+  ) => void | Promise<void>
+  readonly onUnmount?: (
+    ctx: AddonButtonServiceContext<Config>,
+  ) => void | Promise<void>
+  readonly onTap?: (
+    ctx: AddonButtonServiceContext<Config>,
+  ) => void | Promise<void>
+  readonly onDblTap?: (
+    ctx: AddonButtonServiceContext<Config>,
+  ) => void | Promise<void>
+  readonly onHold?: (
+    ctx: AddonButtonServiceContext<Config>,
+  ) => void | Promise<void>
+  readonly dispose?: (
+    ctx: AddonButtonServiceContext<Config>,
+  ) => void | Promise<void>
+}
+
+export interface AddonButtonServiceContext<Config = unknown> {
+  readonly config: Config
+  readonly buttonId: string
+  /** Declared button position within its deck, when the deck defines one. */
+  readonly position?: number
+  readonly addonName: string
+  /** Namespaced addon-global methods (`<addonName>:<methodName>` keys). */
+  readonly methods: Readonly<Record<string, AddonServiceMethod>>
+  /**
+   * Core runtime methods exposed to addons (e.g. `adjustBrightness`,
+   * `dispatch`, `runCommand`, `keyMacro`, `typeText`, `navigateToDeck`,
+   * `goBack`, `showTemporaryError`, `getActiveDeckId`). Setter functions
+   * like `setKeyMacroProvider` are intentionally not exposed — they belong
+   * to host setup, not addon backends.
+   */
+  readonly coreMethods: Methods
+  /** Publish on a channel. */
+  readonly publish: (channel: string, data: unknown) => void
+  /** Run host commands. */
+  readonly executor: ActionExecutor
+  /** Aborted when the button instance unmounts. */
+  readonly signal: AbortSignal
+  /**
+   * Per-addon persisted state. Use `store.buttonScope(addonName, key)` to
+   * scope reads/writes to this addon.
+   */
+  readonly store: Store
+}
+
+/**
+ * JSON metadata manifest. Both builtin and third-party addons ship this file
+ * for discovery. Runtime metadata (button types, decks, etc.) lives in the
+ * entry file (see `entry`) which exports an `AddonManifestV1` at runtime.
+ *
+ * Convention:
+ * - `name`: unique addon identifier (e.g. `date-time`).
+ * - `kind`: `"addon"` selects runtime registration; `"theme"` selects the theme loader.
+ * - `apiVersion`: the JSON manifest schema version (currently 1).
+ * - `entry`: path (relative to the JSON file) to the runtime entry that exports
+ *   an `AddonManifestV1`. In dev this is `index.ts`; in prod this is `index.js`.
+ *   The CLI dynamically imports it at startup.
+ */
+export interface AddonJsonManifest {
+  readonly kind: AddonManifestKind
+  readonly apiVersion: 1
+  readonly name: string
+  readonly entry: string
+  /**
+   * Optional path (relative to the JSON file) to a SEPARATE browser bundle.
+   *
+   * ponytail: `entry` is imported by Node, which cannot resolve the host's
+   * `@sirenodeck/sirenodeck/ui/*` specifiers — they point at .tsx sources. A
+   * prebuilt addon therefore has to inline stubs for them at build time, and
+   * when that same bundle is also handed to the browser those stubs are what
+   * renders. The pomodoro addon shipped `Label = () => null` exactly this way,
+   * so its buttons drew no text at all.
+   *
+   * When set, the browser loads THIS file instead, built with the host UI
+   * specifiers left external so vite resolves them to the real components.
+   * Omitted, the loader falls back to `entry` and behaviour is unchanged, so
+   * existing addons keep working untouched.
+   */
+  readonly frontendEntry?: string
+}
+
+/** Validation schema for `AddonJsonManifest`; usable at scan time. */
+export type AddonJsonManifestSchema = z.ZodType<AddonJsonManifest>
+
+/** The current JSON manifest schema version. */
+export const SIRENO_ADDON_JSON_API_VERSION = 1 as const

package/src/addon/check-runner.ts

@@ -0,0 +1,84 @@
+import type { AddonCheck, AddonCheckResult } from "./api"
+import mediaAddonManifest from "@/builtin-addons/media/index"
+import { buildMediaAddonChecks } from "@/builtin-addons/media/checks"
+import { createChildProcessExecutor } from "@/builtin-addons/media/executor"
+
+export interface AddonCheckInput {
+  readonly name: string
+  readonly checks?: ReadonlyArray<AddonCheck>
+}
+
+export interface AddonCheckOutcome {
+  readonly addonName: string
+  readonly checkName: string
+  readonly available: boolean
+  readonly reason?: string
+}
+
+// ponytail: probe errors are expected (tool not installed). Catching here
+// keeps callers from having to wrap each check in try/catch and keeps the
+// display layer uniform.
+const runCheck = async (
+  addonName: string,
+  check: AddonCheck,
+): Promise<AddonCheckOutcome> => {
+  try {
+    const result: AddonCheckResult = await check.check()
+    return result.reason !== undefined
+      ? {
+          addonName,
+          checkName: check.name,
+          available: result.available,
+          reason: result.reason,
+        }
+      : {
+          addonName,
+          checkName: check.name,
+          available: result.available,
+        }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    return {
+      addonName,
+      checkName: check.name,
+      available: false,
+      reason: `check error: ${message}`,
+    }
+  }
+}
+
+export const runAddonChecks = async (
+  addons: ReadonlyArray<AddonCheckInput>,
+): Promise<ReadonlyArray<AddonCheckOutcome>> => {
+  const all = addons.flatMap((addon) =>
+    (addon.checks ?? []).map((check) => runCheck(addon.name, check)),
+  )
+  return Promise.all(all)
+}
+
+// ponytail: the CLI process doesn't share state with the daemon process,
+// so it can't introspect a live `AddonRegistry`. Builtin addons ship as
+// statically-known TS modules; importing their manifests here is enough
+// to enumerate their `checks` for the start banner. External addons are
+// out of scope — the registry is built inside the daemon process and the
+// CLI doesn't have a way to safely re-resolve their entry files.
+//
+// We import the manifest only for the addon NAME (used in banner output),
+// then build the checks at the Node edge here — the addon manifest itself
+// is bundled into the frontend vite graph, so importing node-only modules
+// (playerctl/wpctl probing) there would externalize them for the browser
+// and break the SPA on load. Keeping the executor + check-builder import
+// at the CLI edge keeps the manifest Node-pure.
+export const collectBuiltinAddonChecks = (): ReadonlyArray<AddonCheckInput> => {
+  const checks = buildMediaAddonChecks({
+    platform: process.platform,
+    executor: createChildProcessExecutor(),
+  })
+  return checks.length > 0 ? [{ name: mediaAddonManifest.name, checks }] : []
+}
+
+// ponytail: probe errors are expected when external tools are missing —
+// run checks in parallel so a slow `command -v` doesn't gate the banner.
+export const runBuiltinAddonChecks = (): Promise<
+  ReadonlyArray<AddonCheckOutcome>
+> => runAddonChecks(collectBuiltinAddonChecks())

package/src/addon/index.ts

@@ -0,0 +1,5 @@
+export * from "./api"
+export { SIRENO_ADDON_API_VERSION } from "./api-types"
+export * from "./loader"
+export * from "./registry"
+export * from "./spec"