@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/deck/deck-config.ts

@@ -0,0 +1,271 @@
+import { dirname } from "node:path"
+
+import type { DeckConfigMessage } from "@/api/protocol-internal"
+import type { RuntimeDeck } from "@/deck"
+import { isSystemButtonType } from "@/deck/system-buttons/types"
+import { computeSystemButtonForSlotN1 } from "@/deck/system-back-injection"
+import {
+  resolveIconSource,
+  type ResolveIconPathOptions,
+} from "@/render/icon-source-resolver"
+
+export interface AddonFrontendRef {
+  readonly name: string
+  readonly frontendEntry: string | null
+}
+
+export const buildResolverOptions = (
+  addonByType: ReadonlyMap<string, AddonFrontendRef>,
+  baseDirs: ReadonlyArray<string>,
+  // ponytail: external addons (loaded from config's addons: list) need their
+  // dirs registered so `addon://<name>/assets/icon.png` resolves. The basenames
+  // match the addon names in deck triggers.
+  extraAddonDirs?: ReadonlyMap<string, string>,
+): ResolveIconPathOptions => {
+  const addonDirs = new Map<string, string>()
+  for (const ref of addonByType.values()) {
+    if (ref.frontendEntry !== null) {
+      addonDirs.set(ref.name, dirname(ref.frontendEntry))
+    }
+  }
+  for (const [name, dir] of extraAddonDirs ?? []) {
+    addonDirs.set(name, dir)
+  }
+  return { addonDirs, baseDirs }
+}
+
+export type AssetLookup = (fullPath: string) => string | undefined
+
+const resolveOne = (
+  icon: unknown,
+  resolverOptions: ResolveIconPathOptions,
+  assetLookup: AssetLookup,
+): unknown => {
+  if (typeof icon !== "string") return icon
+  if (icon.startsWith("icon://")) return icon
+  if (icon.startsWith("asset://")) return icon
+  let resolved
+  try {
+    resolved = resolveIconSource(icon, resolverOptions)
+  } catch {
+    return icon
+  }
+  if (resolved.kind !== "asset") return icon
+  const id = assetLookup(resolved.fullPath)
+  if (id === undefined) return icon
+  return `asset://${id}`
+}
+
+export const resolveConfigIcons = (
+  cfg: Record<string, unknown>,
+  resolverOptions: ResolveIconPathOptions,
+  assetLookup: AssetLookup,
+): Record<string, unknown> => {
+  const next = { ...cfg }
+  if ("icon" in next)
+    next.icon = resolveOne(next.icon, resolverOptions, assetLookup)
+  if (Array.isArray(next.lines)) {
+    next.lines = (next.lines as ReadonlyArray<unknown>).map((line) => {
+      if (typeof line !== "object" || line === null) return line
+      const lineObj = line as Record<string, unknown>
+      if (!("icon" in lineObj)) return line
+      return {
+        ...lineObj,
+        icon: resolveOne(lineObj.icon, resolverOptions, assetLookup),
+      }
+    })
+  }
+  return next
+}
+
+const deriveLabel = (
+  type: string,
+  config: Record<string, unknown>,
+): string | undefined => {
+  switch (type) {
+    case "core:action": {
+      const cmd = config["command"]
+      if (typeof cmd === "string" && cmd.length > 0) {
+        return cmd.length > 14 ? `${cmd.slice(0, 13)}…` : cmd
+      }
+      // ponytail: fallback to config.label so addon-deck buttons (e.g.
+      // chrome-overlay's {label: 'New Tab'}) render their label when no
+      // command is set. The legacy config-command path stays primary.
+      const label = config["label"]
+      if (typeof label === "string" && label.length > 0) {
+        return label
+      }
+      return undefined
+    }
+    case "core:change-deck": {
+      const deck = config["deck"]
+      if (typeof deck === "string" && deck.length > 0) {
+        return `→ ${deck}`
+      }
+      return undefined
+    }
+    default:
+      return undefined
+  }
+}
+
+export const buildDeckConfigMessage = (
+  deck: RuntimeDeck,
+  addonByType: Map<string, AddonFrontendRef>,
+  resolverOptions: ResolveIconPathOptions = {},
+  navState?: {
+    navStackDepth: number
+    hasOverlayDeckAvailable: boolean
+    inOverlayMode?: boolean
+  },
+  keyCount?: number,
+  isCompact?: boolean,
+  assetLookup: AssetLookup = () => undefined,
+  overlayDeckIcon: string | null = null,
+  overlayDeckName: string | null = null,
+  options?: { lockActive?: boolean },
+): DeckConfigMessage => {
+  const n1Position = keyCount !== undefined ? keyCount - 1 : -1
+  const buttons = deck.buttons
+    .filter((b) => {
+      if (options?.lockActive !== true) return true
+      if (b.position !== n1Position) return true
+      return !isSystemButtonType(b.type)
+    })
+    .map((b) => {
+      const position = b.position
+      const addon = addonByType.get(b.type)
+      const cfg = (b.config ?? {}) as Record<string, unknown>
+      const label = deriveLabel(b.type, cfg)
+      const resolvedConfig = resolveConfigIcons(
+        cfg,
+        resolverOptions,
+        assetLookup,
+      )
+      return {
+        id: b.id,
+        type: b.type,
+        ...(Number.isFinite(position) ? { position } : {}),
+        config: resolvedConfig,
+        ...(label !== undefined ? { label } : {}),
+        ...(addon !== undefined ? { addonName: addon.name } : {}),
+        ...(addon?.frontendEntry !== undefined && addon.frontendEntry !== null
+          ? { frontendEntry: addon.frontendEntry }
+          : {}),
+        ...(b.full === true ? { full: true } : {}),
+        ...(b.variant !== undefined && b.variant.length > 0
+          ? { variant: b.variant }
+          : {}),
+        ...(b.buttonColor !== undefined ? { buttonColor: b.buttonColor } : {}),
+      }
+    })
+
+  let finalButtons = buttons
+  if (n1Position >= 0 && options?.lockActive !== true) {
+    const systemBtn = computeSystemButtonForSlotN1(deck, {
+      navStackDepth: navState?.navStackDepth ?? 1,
+      hasOverlayDeckAvailable: navState?.hasOverlayDeckAvailable ?? false,
+      lockActive: options?.lockActive,
+      inOverlayMode: navState?.inOverlayMode,
+    })
+    if (systemBtn !== null) {
+      const hasN1 = buttons.some(
+        (b) => b.position === n1Position && isSystemButtonType(b.type),
+      )
+      if (hasN1) {
+        finalButtons = buttons.map((b) =>
+          b.position === n1Position && isSystemButtonType(b.type)
+            ? { ...b, type: systemBtn }
+            : b,
+        )
+      } else {
+        finalButtons = [
+          ...buttons,
+          {
+            id: `${n1Position}-${deck.id}-0`,
+            type: systemBtn,
+            position: n1Position,
+            config: {},
+          },
+        ]
+      }
+    }
+  }
+
+  const resolvedOverlayIcon =
+    overlayDeckIcon === null
+      ? null
+      : (resolveOne(overlayDeckIcon, resolverOptions, assetLookup) as
+          | string
+          | null)
+  return {
+    type: "deck-config",
+    deckId: deck.id,
+    surfaces: {
+      [deck.id]: {
+        id: deck.id,
+        name: deck.name ?? deck.id,
+        buttons: finalButtons,
+        ...(deck.buttonColor !== undefined
+          ? { buttonColor: deck.buttonColor }
+          : {}),
+        ...(deck.variant !== undefined && deck.variant.length > 0
+          ? { variant: deck.variant }
+          : {}),
+        ...(deck.buttonErrors !== undefined && deck.buttonErrors.length > 0
+          ? {
+              buttonErrors: deck.buttonErrors.map((e) => ({
+                position: e.position,
+                expiresAt: Number.MAX_SAFE_INTEGER,
+                ...(e.buttonId !== undefined ? { buttonId: e.buttonId } : {}),
+                details: e.details,
+              })),
+            }
+          : {}),
+      },
+    },
+    navMode: "regular",
+    isCompact: isCompact ?? false,
+    hasOverlayDeckAvailable: navState?.hasOverlayDeckAvailable ?? false,
+    overlayDeckIcon: resolvedOverlayIcon,
+    overlayDeckName,
+  }
+}
+
+export type DeckTreeEntry = {
+  readonly id: string
+  readonly name: string
+  readonly isOverlay: boolean
+  readonly links: Array<{
+    readonly target: string
+    readonly label?: string
+  }>
+}
+
+export const buildDeckTree = (
+  decks: ReadonlyArray<RuntimeDeck>,
+  mainDeckId: string,
+): { rootId: string; decks: DeckTreeEntry[] } => {
+  const entries: DeckTreeEntry[] = decks.map((deck) => {
+    const links: { target: string; label?: string }[] = []
+    for (const btn of deck.buttons ?? []) {
+      if (btn.type === "core:change-deck") {
+        const config = btn.config as
+          | { deck?: string; label?: string }
+          | undefined
+        if (config?.deck !== undefined) {
+          links.push({ target: config.deck, label: config.label })
+        }
+      }
+    }
+    return {
+      id: deck.id,
+      name: deck.name ?? deck.id,
+      isOverlay:
+        (deck.processNames?.length ?? 0) > 0 ||
+        (deck.windowNames?.length ?? 0) > 0,
+      links,
+    }
+  })
+  return { rootId: mainDeckId, decks: entries }
+}

package/src/deck/editor-surfaces.ts

@@ -0,0 +1,87 @@
+import type { RuntimeDeck, RuntimeButton } from "./runtime"
+import { paginationReservedPositions } from "@/core/pagination"
+import { computeSystemButtonForSlotN1 } from "./system-back-injection"
+
+export type EditorMutationCapability = "update" | "delete" | "reorder"
+
+export interface EditorSourceTarget {
+  readonly sourcePath: string
+  readonly sourceDeckId: string
+  readonly sourceButtonIndex: number
+  readonly sourceButtonPath: string
+  readonly fingerprint: string
+  readonly capability: EditorMutationCapability
+}
+
+export interface EditorAddonOwner {
+  readonly addonIndex: number
+  readonly addonName: string
+  readonly overrideKey: string
+  readonly capabilities: ReadonlyArray<string>
+}
+
+export interface EditorSurfaceButton {
+  readonly id: string
+  readonly type: string
+  readonly position: number
+  readonly sourceTarget: EditorSourceTarget | null
+}
+
+export interface EditorSurfaceDescriptor {
+  readonly id: string
+  readonly sourceDeckId: string
+  readonly projectionId: string
+  readonly pageIndex: number
+  readonly isOverlay: boolean
+  readonly editable: boolean
+  readonly addonOwner: EditorAddonOwner | null
+  readonly reservedPositions: number[]
+  readonly buttons: EditorSurfaceButton[]
+}
+
+export interface DescribeEditorSurfacesOptions {
+  readonly decks: ReadonlyArray<RuntimeDeck>
+  readonly keyCount: number
+  readonly revision: number
+  readonly systemState?: {
+    navStackDepth: number
+    hasOverlayDeckAvailable: boolean
+    lockActive?: boolean
+    inOverlayMode?: boolean
+  }
+}
+
+export const describeEditorSurfaces = ({
+  decks,
+  keyCount,
+  revision: _revision,
+  systemState,
+}: DescribeEditorSurfacesOptions): EditorSurfaceDescriptor[] =>
+  decks.map((deck) => {
+    const systemType = computeSystemButtonForSlotN1(deck, {
+      navStackDepth: systemState?.navStackDepth ?? 1,
+      hasOverlayDeckAvailable: systemState?.hasOverlayDeckAvailable ?? false,
+      lockActive: systemState?.lockActive,
+      inOverlayMode: systemState?.inOverlayMode,
+    })
+    const reservedPositions = new Set(
+      paginationReservedPositions(keyCount, deck.paginated === true),
+    )
+    if (systemType !== null) reservedPositions.add(keyCount - 1)
+    return {
+      id: deck.id,
+      sourceDeckId: deck.sourceDeckId ?? deck.id,
+      projectionId: deck.projectionId ?? deck.id,
+      pageIndex: deck.pageIndex ?? 0,
+      isOverlay: deck.isOverlay === true || deck.isOverlayDeck === true,
+      editable: deck.editable === true,
+      addonOwner: deck.addonOwner ?? null,
+      reservedPositions: [...reservedPositions].sort((a, b) => a - b),
+      buttons: deck.buttons.map((button: RuntimeButton) => ({
+        id: button.id,
+        type: button.type,
+        position: button.position ?? -1,
+        sourceTarget: button.sourceTarget ?? null,
+      })),
+    }
+  })

package/src/deck/host-context.ts

@@ -0,0 +1,18 @@
+import { hostname, platform, arch, userInfo } from "node:os"
+
+export interface HostContext {
+  hostname: string
+  platform: NodeJS.Platform
+  userInfo: { username: string; homedir: string }
+  arch: string
+}
+
+export const getHostContext = (): HostContext => {
+  const info = userInfo()
+  return {
+    hostname: hostname(),
+    platform: platform(),
+    userInfo: { username: info.username, homedir: info.homedir },
+    arch: arch(),
+  }
+}

package/src/deck/index.ts

@@ -0,0 +1,102 @@
+import type pino from "pino"
+
+import { createPubSub } from "@/core/pub-sub"
+import { createStore } from "@/core/store"
+import { NotImplementedError } from "@/util/errors"
+import { createLogger } from "@/util/logger"
+import type { KeyMacroProvider } from "@/system/providers/key-macro"
+
+import { createActionExecutor } from "@/action/executor"
+import { getHostContext } from "./host-context"
+import { createMethods } from "./methods"
+import { createRuntime, type Runtime, type RuntimeDeck } from "./runtime"
+
+export { createActionExecutor, type ActionExecutor } from "@/action/executor"
+export type { PubSub } from "@/core/pub-sub"
+export type { Store } from "@/core/store"
+export {
+  createMethods,
+  type Methods,
+  type MethodsContext,
+  type KeyMacroAction,
+} from "./methods"
+export {
+  createRuntime,
+  type Runtime,
+  type RuntimeDeck,
+  type RuntimeButton,
+  type RuntimeButtonHandler,
+  type ButtonActionContext,
+  type GestureEvent,
+  type GestureListener,
+  type MountedButton,
+} from "./runtime"
+export { getHostContext, type HostContext } from "./host-context"
+export {
+  computeSystemButtonForSlotN1,
+  injectSystemButtons,
+} from "./system-back-injection"
+export { parseMacro } from "./macro-parse"
+export {
+  describeEditorSurfaces,
+  type EditorAddonOwner,
+  type EditorMutationCapability,
+  type EditorSourceTarget,
+  type EditorSurfaceButton,
+  type EditorSurfaceDescriptor,
+} from "./editor-surfaces"
+export {
+  isSystemButtonType,
+  SYSTEM_BUTTON_TYPES,
+  type SystemButtonType,
+} from "./system-buttons/types"
+
+export interface CreateDeckRuntimeOptions {
+  decks: ReadonlyArray<RuntimeDeck>
+  logger?: pino.Logger
+  keyMacroProvider?: KeyMacroProvider
+}
+
+export const createDeckRuntime = (
+  options: CreateDeckRuntimeOptions,
+): {
+  runtime: Runtime
+  methods: ReturnType<typeof createMethods>
+  pubSub: ReturnType<typeof createPubSub>
+  store: ReturnType<typeof createStore>
+} => {
+  const logger = options.logger ?? createLogger({ level: "silent" })
+  const pubSub = createPubSub()
+  const store = createStore()
+  const executor = createActionExecutor({ host: getHostContext() })
+
+  const methodsRef: { current: ReturnType<typeof createMethods> | undefined } =
+    {
+      current: undefined,
+    }
+
+  const runtime = createRuntime({
+    decks: options.decks,
+    pubSub,
+    store,
+    logger,
+    getMethods: () => methodsRef.current!,
+  })
+
+  const methods = createMethods({
+    runtime,
+    pubSub,
+    store,
+    executor,
+    logger,
+    ...(options.keyMacroProvider !== undefined
+      ? { keyMacroProvider: options.keyMacroProvider }
+      : {}),
+  })
+
+  methodsRef.current = methods
+
+  return { runtime, methods, pubSub, store }
+}
+
+export { NotImplementedError }

package/src/deck/macro-parse.ts

@@ -0,0 +1,182 @@
+import { parseCombo } from "@/system/providers/key-macro/parser"
+
+export type MacroStep =
+  | { kind: "combo"; value: string }
+  | { kind: "key"; value: string }
+  | { kind: "text"; value: string }
+  | { kind: "delay"; ms: number }
+
+const DELAY_RE = /^(\d+)(ms|s|m|h)$/
+
+const parseDelay = (raw: string): number | null => {
+  const m = raw.match(DELAY_RE)
+  if (m === null) return null
+  const n = Number(m[1])
+  const unit = m[2]
+  if (unit === "ms") return n
+  if (unit === "s") return n * 1000
+  if (unit === "m") return n * 60_000
+  if (unit === "h") return n * 3_600_000
+  return null
+}
+
+export const parseMacro = (value: string): MacroStep[] => {
+  const segments = value
+    .split(";")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0)
+  const steps: MacroStep[] = []
+  for (const seg of segments) {
+    const lc = seg.toLowerCase()
+    if (lc.startsWith("delay(") && lc.endsWith(")")) {
+      const inner = lc.slice(6, -1)
+      const ms = parseDelay(inner)
+      if (ms !== null) {
+        steps.push({ kind: "delay", ms })
+        continue
+      }
+    }
+    const parsed = parseCombo(seg)
+    if (parsed !== null) {
+      const combo =
+        parsed.mods.length > 0
+          ? `${parsed.mods.join("+")}+${parsed.key}`
+          : parsed.key
+      steps.push({ kind: "combo", value: combo })
+      continue
+    }
+    steps.push({ kind: "text", value: seg })
+  }
+  return steps
+}
+
+export type MacroPlatform = "macos" | "linux" | "windows"
+
+/**
+ * Spellings accepted for a platform override. `osx` and `darwin` are here
+ * because the older JSON macro form and `process.platform` use them
+ * respectively — a user should not have to know which layer they are talking
+ * to in order to name their own operating system.
+ */
+const PLATFORM_ALIASES: ReadonlyMap<string, MacroPlatform> = new Map([
+  ["macos", "macos"],
+  ["mac", "macos"],
+  ["osx", "macos"],
+  ["darwin", "macos"],
+  ["linux", "linux"],
+  ["windows", "windows"],
+  ["win", "windows"],
+  ["win32", "windows"],
+])
+
+export const currentMacroPlatform = (
+  platform: string = process.platform,
+): MacroPlatform => {
+  if (platform === "darwin") return "macos"
+  if (platform === "win32") return "windows"
+  return "linux"
+}
+
+export interface PlatformMacro {
+  readonly overrides: ReadonlyMap<MacroPlatform, string>
+  /** The macro used by any platform without an override. Always present. */
+  readonly fallback: string
+}
+
+export class MacroSyntaxError extends Error {}
+
+/**
+ * Parses `[os:override][os2:override2]default` into its parts.
+ *
+ * Overrides are a prefix run: parsing stops at the first character that is not
+ * the start of a well-formed `[<known-os>:` block, and everything from there on
+ * is the default verbatim. That keeps every macro that does not use the syntax
+ * working untouched, including ones containing `]` — `macro://ctrl+]` never
+ * enters bracket parsing because it does not begin with `[`.
+ *
+ * The consequence is that a literal `]` INSIDE an override would close it
+ * early, so it must be written with its key name, `bracketright`. The default
+ * segment has no such restriction.
+ */
+export const parsePlatformMacro = (value: string): PlatformMacro => {
+  const overrides = new Map<MacroPlatform, string>()
+  let rest = value
+
+  while (rest.startsWith("[")) {
+    const colon = rest.indexOf(":")
+    if (colon === -1) break
+    const rawName = rest.slice(1, colon).trim().toLowerCase()
+    const platform = PLATFORM_ALIASES.get(rawName)
+    // Not a platform override — e.g. a macro that genuinely starts with "[".
+    // Leave it, and everything after it, as the default.
+    if (platform === undefined) break
+    const close = rest.indexOf("]", colon)
+    if (close === -1) {
+      throw new MacroSyntaxError(
+        `macro: unterminated '[${rawName}:' override — add the closing ']'`,
+      )
+    }
+    if (overrides.has(platform)) {
+      throw new MacroSyntaxError(`macro: duplicate override for '${platform}'`)
+    }
+    const override = rest.slice(colon + 1, close).trim()
+    if (override.length === 0) {
+      throw new MacroSyntaxError(`macro: override for '${platform}' is empty`)
+    }
+    overrides.set(platform, override)
+    rest = rest.slice(close + 1)
+  }
+
+  const fallback = rest.trim()
+  if (fallback.length === 0) {
+    // Deliberately mandatory: without it a macro would silently do nothing on
+    // any platform the author did not think to list.
+    throw new MacroSyntaxError(
+      overrides.size > 0
+        ? "macro: a default is required after the per-OS overrides, e.g. macro://[macos:cmd+c]ctrl+c"
+        : "macro: requires a value, e.g. macro://ctrl+c",
+    )
+  }
+  return { overrides, fallback }
+}
+
+/**
+ * Picks the macro this platform should run. Platforms without an override get
+ * the default, which is what makes `[windows:X]Y` mean "X on Windows, Y on
+ * macOS and Linux".
+ */
+export const resolvePlatformMacro = (
+  value: string,
+  platform: string = process.platform,
+): string => {
+  const parsed = parsePlatformMacro(value)
+  return parsed.overrides.get(currentMacroPlatform(platform)) ?? parsed.fallback
+}
+
+export const dispatchMacro = async (
+  value: string,
+  handlers: {
+    runCommand: (cmd: string) => Promise<unknown>
+    keyMacro: (action: {
+      kind: "combo" | "key" | "text"
+      value: string
+    }) => Promise<void>
+  },
+): Promise<void> => {
+  const steps = parseMacro(value)
+  for (const step of steps) {
+    if (step.kind === "delay") {
+      await new Promise<void>((resolve) => setTimeout(resolve, step.ms))
+      continue
+    }
+    if (step.kind === "combo") {
+      await handlers.keyMacro({ kind: "combo", value: step.value })
+      continue
+    }
+    if (step.kind === "key") {
+      await handlers.keyMacro({ kind: "key", value: step.value })
+      continue
+    }
+    await handlers.keyMacro({ kind: "text", value: step.value })
+  }
+}