@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/deck/runtime/runtime.ts

@@ -0,0 +1,1060 @@
+import type pino from "pino"
+
+import type { PubSub } from "@/core/pub-sub"
+import type { Store } from "@/core/store"
+import type { GestureKind } from "@/core/gesture-state"
+import type { ActiveAppProvider } from "@/system/providers/active-app"
+import type { SessionProvider, SessionState } from "@/system/providers/session"
+import { getRequiredCapability } from "@/system/requirements"
+import { compileDeckMatcher } from "@/system/glob-match"
+import type { Methods } from "../methods"
+import { describeEditorSurfaces } from "../editor-surfaces"
+import type {
+  EditorAddonOwner,
+  EditorSourceTarget,
+  EditorSurfaceDescriptor,
+} from "../editor-surfaces"
+
+type ActiveAppProviderLike = Pick<ActiveAppProvider, "getActive" | "stop">
+
+export interface RuntimeButton {
+  id: string
+  type: string
+  position?: number
+  config?: unknown
+  actions?: {
+    tap?: string
+    dbltap?: string
+    hold?: string
+  }
+  full?: boolean
+  variant?: string
+  buttonColor?:
+    | "blue"
+    | "green"
+    | "purple"
+    | "cyan"
+    | "magenta"
+    | "amber"
+    | "lime"
+  sourceTarget?: EditorSourceTarget
+}
+
+export interface RuntimeDeck {
+  id: string
+  name: string
+  buttons: ReadonlyArray<RuntimeButton>
+  isMain?: boolean
+  processNames?: ReadonlyArray<string>
+  windowNames?: ReadonlyArray<string>
+  autoShow?: boolean
+  isOverlayDeck?: boolean
+  icon?: string
+  background?: string
+  paginated?: boolean
+  // ponytail: addon-generated decks inherit the parent's window/process trigger
+  // so the runtime can switch to them automatically when the watched window
+  // comes to the foreground. Preserved through materialization.
+  trigger?: unknown
+  isOverlay?: boolean
+  config?: Record<string, unknown>
+  buttonColor?:
+    | "blue"
+    | "green"
+    | "purple"
+    | "cyan"
+    | "magenta"
+    | "amber"
+    | "lime"
+  /**
+   * Variant token name resolved from the active theme. Falls back to
+   * "default" when the theme doesn't declare the requested variant.
+   */
+  variant?: string
+  buttonErrors?: ReadonlyArray<{
+    position: number
+    buttonId?: string
+    details: string
+  }>
+  sourceDeckId?: string
+  projectionId?: string
+  pageIndex?: number
+  editable?: boolean
+  addonOwner?: EditorAddonOwner
+}
+
+export interface RuntimeButtonHandler {
+  onTap?: (ctx: ButtonActionContext) => void | Promise<void>
+  onDblTap?: (ctx: ButtonActionContext) => void | Promise<void>
+  onHold?: (ctx: ButtonActionContext) => void | Promise<void>
+  dispose?: () => void | Promise<void>
+}
+
+export interface ButtonActionContext {
+  buttonId: string
+  deckId: string
+  config: unknown
+  gesture: GestureKind
+  position: number | undefined
+}
+
+export interface GestureEvent {
+  readonly gesture: GestureKind
+  readonly at: number
+  readonly position: number | undefined
+}
+
+export type GestureListener = (buttonId: string, event: GestureEvent) => void
+
+export interface MountedButton {
+  addonName: string
+  buttonId: string
+  type: string
+  config: unknown
+}
+
+export interface CreateRuntimeOptions {
+  decks: ReadonlyArray<RuntimeDeck>
+  pubSub: PubSub
+  store: Store
+  logger: pino.Logger
+  getMethods: () => Methods
+}
+
+export interface Runtime {
+  getActiveDeck(): RuntimeDeck
+  getActiveDeckId(): string
+  deckExists(id: string): boolean
+  setDecks(decks: ReadonlyArray<RuntimeDeck>): void
+  navigateToDeck(id: string, options?: { addToHistory?: boolean }): void
+  goBack(): void
+  setOverlay(
+    deckId: string | null,
+    opts?: { source?: "autoShow" | "manual" },
+  ): void
+  getOverlay(): RuntimeDeck | null
+  registerButtonHandler(buttonId: string, handler: RuntimeButtonHandler): void
+  unregisterButtonHandler(buttonId: string): void
+  mountAddonButtons(
+    addonName: string,
+    buttons: ReadonlyArray<MountedButton>,
+  ): void
+  dispatchGesture(buttonId: string, gesture: GestureKind): Promise<void>
+  invokeAction(buttonId: string, gesture: GestureKind): Promise<void>
+  setGestureListener(listener: GestureListener | null): void
+  invalidate(): void
+  setActiveAppProvider(provider: ActiveAppProviderLike): void
+  setSessionProvider(provider: SessionProvider): void
+  isLockActive(): boolean
+  stopActiveAppPolling(): Promise<void>
+  navStackDepth(): number
+  hasOverlayDeckAvailable(): boolean
+  getAvailableOverlayDeckIcon(): string | null
+  getAvailableOverlayDeckName(): string | null
+  getBrightness(): number
+  setBrightness(value: number): void
+  getEditorSurfaces(options?: {
+    keyCount?: number
+    revision?: number
+  }): EditorSurfaceDescriptor[]
+}
+
+export const createRuntime = (options: CreateRuntimeOptions): Runtime => {
+  const { pubSub, store, getMethods } = options
+  const logger = options.logger.child({ component: "runtime" })
+  let { decks } = options
+  let gestureListener: GestureListener | null = null
+  const mainDeck = decks.find((d) => d.isMain) ?? decks[0]
+  if (mainDeck === undefined) {
+    throw new Error("createRuntime: at least one deck is required")
+  }
+
+  const handlers = new Map<string, RuntimeButtonHandler>()
+  const navStack: string[] = [mainDeck.id]
+  let transientDeckId: string | null = null
+  let overlayDeckId: string | null = null
+  let availableOverlayDeckId: string | null = null
+  let overlayPreviousActiveId: string | null = null
+  const overlayNavStacks = new Map<string, string[]>()
+  const buttonIndex = new Map<
+    string,
+    { deckId: string; button: RuntimeDeck["buttons"][number] }
+  >()
+  for (const deck of decks) {
+    for (const button of deck.buttons) {
+      if (!buttonIndex.has(button.id)) {
+        buttonIndex.set(button.id, { deckId: deck.id, button })
+      }
+      // ponytail: also index the composite "{deckId}:{button.id}" so callers
+      // can dispatch by either form. findButton consults both maps.
+      const composite = `${deck.id}:${button.id}`
+      if (!buttonIndex.has(composite)) {
+        buttonIndex.set(composite, { deckId: deck.id, button })
+      }
+    }
+  }
+  let brightness = 50
+  let lockActive = false
+  let preLockActiveDeckId: string | null = null
+  let preLockOverlayDeckId: string | null = null
+  let sessionUnsubscribe: (() => void) | null = null
+
+  const deckById = (id: string): RuntimeDeck | undefined =>
+    decks.find((d) => d.id === id)
+
+  const setDecks = (next: ReadonlyArray<RuntimeDeck>): void => {
+    decks = next
+    // ponytail: rebuild a global button-id → ref map so bare-id lookups in
+    // findButton are O(1) instead of scanning all decks in deck order. Set
+    // first-wins (not last-wins) to preserve the legacy scan behavior.
+    buttonIndex.clear()
+    for (const deck of decks) {
+      if (!Array.isArray(deck.buttons)) continue
+      for (const button of deck.buttons) {
+        if (!buttonIndex.has(button.id)) {
+          buttonIndex.set(button.id, { deckId: deck.id, button })
+        }
+        const composite = `${deck.id}:${button.id}`
+        if (!buttonIndex.has(composite)) {
+          buttonIndex.set(composite, { deckId: deck.id, button })
+        }
+      }
+    }
+    // Clear any navigation/overlay state that pointed at decks we no longer have.
+    const currentActive = transientDeckId ?? navStack[navStack.length - 1]
+    if (currentActive !== undefined && deckById(currentActive) === undefined) {
+      navStack.length = 0
+      const fallback = decks.find((d) => d.isMain) ?? decks[0]
+      if (fallback !== undefined) navStack.push(fallback.id)
+      transientDeckId = null
+    }
+    if (overlayDeckId !== null && deckById(overlayDeckId) === undefined) {
+      // ponytail: clear both bits so a later setOverlay(null) doesn't restore
+      // a deck id that no longer exists in the registry.
+      overlayDeckId = null
+      overlayPreviousActiveId = null
+    }
+    pubSub.publish("runtime:activeDeck", { deckId: getActiveDeckId() })
+  }
+
+  const findButton = (
+    id: string,
+  ): { deckId: string; button: RuntimeDeck["buttons"][number] } | null => {
+    // ponytail: build a global button-id index in setDecks so bare-id
+    // lookups don't depend on deck order.
+    return buttonIndex.get(id) ?? null
+  }
+
+  // ponytail: lock-mode escape hatch — only these button types can navigate out of lock mode
+  const LOCK_FOLDER_NAV_TYPES: ReadonlySet<string> = new Set([
+    "core:change-deck",
+    "core:page-nav",
+  ])
+
+  const getActiveDeck = (): RuntimeDeck => {
+    const id = getActiveDeckId()
+    const deck = deckById(id)
+    if (deck === undefined) throw new Error(`Active deck '${id}' not found`)
+    return deck
+  }
+
+  const getActiveDeckId = (): string => {
+    if (lockActive) return "core:lock"
+    // ponytail: while overlay mode is on, transientDeckId (used by page-nav)
+    // must take precedence — otherwise paginated overlay pages are invisible
+    // to the runtime, and dismissing overlay after paginating restores the
+    // overlay root instead of the page the user was on.
+    if (overlayDeckId !== null) {
+      if (transientDeckId !== null) return transientDeckId
+      const stack = overlayNavStacks.get(overlayDeckId)
+      if (stack !== undefined && stack.length > 0) {
+        return stack[stack.length - 1] ?? overlayDeckId
+      }
+      return overlayDeckId
+    }
+    return transientDeckId ?? navStack[navStack.length - 1] ?? mainDeck.id
+  }
+
+  const snapshotRegularActiveDeckId = (): string =>
+    overlayPreviousActiveId ??
+    transientDeckId ??
+    navStack[navStack.length - 1] ??
+    mainDeck.id
+
+  const enterLockMode = (): void => {
+    if (lockActive) return
+    preLockActiveDeckId = snapshotRegularActiveDeckId()
+    preLockOverlayDeckId = overlayDeckId
+    lockActive = true
+    logger.info(
+      { preLockActiveDeckId, preLockOverlayDeckId },
+      "runtime: lock active",
+    )
+    pubSub.publish("runtime:lock-mode", {
+      active: true,
+      reason: "session-locked",
+    })
+    pubSub.publish("runtime:activeDeck", { deckId: "core:lock" })
+    pubSub.publish("runtime:invalidate", undefined)
+  }
+
+  const navigateToDeck = (
+    id: string,
+    navOptions?: { addToHistory?: boolean },
+  ): void => {
+    if (id === getActiveDeckId()) return
+    let resolvedId = id
+    let target = deckById(id)
+    // ponytail: paginated decks drop the base id (e.g. `demo-media` becomes
+    // `demo-media-p1`/`demo-media-p2`). Fall back to the first paginated page
+    // when the base id no longer exists, so `core:change-deck` targets keep
+    // working without callers knowing about pagination.
+    if (target === undefined) {
+      const firstPage = deckById(`${id}-p1`)
+      if (firstPage !== undefined) {
+        target = firstPage
+        resolvedId = firstPage.id
+      }
+    }
+    if (target === undefined) {
+      logger.warn({ deckId: id }, "navigateToDeck: deck not found")
+      return
+    }
+    const previousActiveId = getActiveDeckId()
+    if (overlayDeckId !== null) {
+      // ponytail: while overlay mode is on, both change-deck (addToHistory:true)
+      // and page-nav (addToHistory:false) push onto the overlay's nav stack so
+      // re-toggling the overlay restores the user's last position. Page-nav
+      // used to set transientDeckId which the runtime dropped on every
+      // getActiveDeckId query — see https://example.invalid/quick-009.
+      const stack = overlayNavStacks.get(overlayDeckId)
+      if (stack === undefined) {
+        overlayNavStacks.set(overlayDeckId, [overlayDeckId])
+      }
+      const current = overlayNavStacks.get(overlayDeckId)!
+      if (current[current.length - 1] !== resolvedId) {
+        current.push(resolvedId)
+      }
+      transientDeckId = null
+    } else if (navOptions?.addToHistory === false) {
+      transientDeckId = resolvedId
+    } else {
+      navStack.push(resolvedId)
+      transientDeckId = null
+    }
+    pubSub.publish("runtime:deck-inactive", { deckId: previousActiveId })
+    pubSub.publish("runtime:activeDeck", { deckId: resolvedId })
+  }
+
+  const goBack = (): void => {
+    if (overlayDeckId !== null) {
+      const stack = overlayNavStacks.get(overlayDeckId)
+      if (stack !== undefined && stack.length > 1) {
+        stack.pop()
+        const prev = stack[stack.length - 1]!
+        pubSub.publish("runtime:deck-inactive", { deckId: prev })
+        pubSub.publish("runtime:activeDeck", { deckId: prev })
+      } else {
+        setOverlay(null)
+      }
+      return
+    }
+    if (transientDeckId !== null) {
+      pubSub.publish("runtime:deck-inactive", { deckId: transientDeckId })
+      const pageMatch = /^(.*)-p\d+$/.exec(transientDeckId)
+      if (pageMatch !== null) {
+        const basePageId = `${pageMatch[1]}-p1`
+        if (navStack[navStack.length - 1] === basePageId) {
+          navStack.pop()
+          pubSub.publish("runtime:deck-inactive", { deckId: basePageId })
+        }
+      }
+      transientDeckId = null
+      const prev = navStack[navStack.length - 1] ?? mainDeck.id
+      pubSub.publish("runtime:activeDeck", { deckId: prev })
+      return
+    }
+    if (navStack.length <= 1) {
+      logger.warn("goBack: at root deck; nothing to pop")
+      return
+    }
+    const popped = navStack[navStack.length - 1]
+    navStack.pop()
+    const prev = navStack[navStack.length - 1]
+    if (prev === undefined) return
+    if (popped !== undefined) {
+      pubSub.publish("runtime:deck-inactive", { deckId: popped })
+    }
+    pubSub.publish("runtime:activeDeck", { deckId: prev })
+  }
+
+  const setOverlay = (
+    deckId: string | null,
+    opts?: { source?: "autoShow" | "manual" },
+  ): void => {
+    if (deckId !== null && deckById(deckId) === undefined) {
+      logger.warn({ deckId }, "setOverlay: deck not found")
+      return
+    }
+    if (deckId !== null && !overlayNavStacks.has(deckId)) {
+      overlayNavStacks.set(deckId, [deckId])
+    }
+    const previousActiveId = getActiveDeckId()
+    const previousOverlayId = overlayDeckId
+    if (previousOverlayId === null && deckId !== null) {
+      overlayPreviousActiveId = previousActiveId
+    }
+    overlayDeckId = deckId
+    pubSub.publish(
+      "runtime:overlay",
+      opts?.source !== undefined ? { deckId, source: opts.source } : { deckId },
+    )
+    if (deckId !== null) {
+      if (previousOverlayId !== null) {
+        pubSub.publish("runtime:deck-inactive", { deckId: previousOverlayId })
+      } else {
+        pubSub.publish("runtime:deck-inactive", { deckId: previousActiveId })
+      }
+      // ponytail: if the overlay has nav history (stack top != deckId), the
+      // user was already navigating within this overlay. Publish the stack
+      // top so the broadcast matches what getActiveDeckId will report, and
+      // re-toggling restores the page the user was on.
+      const stack = overlayNavStacks.get(deckId)
+      const targetDeck =
+        stack !== undefined && stack.length > 0
+          ? (stack[stack.length - 1] ?? deckId)
+          : deckId
+      pubSub.publish("runtime:activeDeck", { deckId: targetDeck })
+    } else {
+      // ponytail: previousActiveId (e.g. a paginated page like -p2) is the
+      // deck actually being deactivated; previousOverlayId is the overlay
+      // root. Publish the page so subscribers see the right deck going dark.
+      if (previousActiveId !== previousOverlayId) {
+        pubSub.publish("runtime:deck-inactive", { deckId: previousActiveId })
+      }
+      // ponytail: clear transientDeckId so the dismissed overlay's paginated
+      // page doesn't bleed into the regular nav state. Without this,
+      // getActiveDeckId keeps returning the page even after overlayDeckId
+      // is null.
+      transientDeckId = null
+      const restoreId = overlayPreviousActiveId ?? mainDeck.id
+      overlayPreviousActiveId = null
+      pubSub.publish("runtime:activeDeck", { deckId: restoreId })
+    }
+  }
+
+  const getOverlay = (): RuntimeDeck | null => {
+    if (overlayDeckId === null) return null
+    return deckById(overlayDeckId) ?? null
+  }
+
+  const registerButtonHandler = (
+    buttonId: string,
+    handler: RuntimeButtonHandler,
+  ): void => {
+    handlers.set(buttonId, handler)
+  }
+
+  const unregisterButtonHandler = (buttonId: string): void => {
+    handlers.delete(buttonId)
+  }
+
+  const mountAddonButtons = (
+    addonName: string,
+    buttons: ReadonlyArray<MountedButton>,
+  ): void => {
+    for (const btn of buttons) {
+      logger.debug(
+        { addonName, buttonId: btn.buttonId, type: btn.type },
+        "mounted addon button",
+      )
+    }
+  }
+
+  const handleSystemButton = (type: string, gesture: GestureKind): boolean => {
+    if (type === "core:back") {
+      if (gesture === "tap") {
+        goBack()
+        return true
+      }
+      if (gesture === "hold") {
+        // ponytail: hold always goes to main, never toggles overlay
+        if (overlayDeckId !== null) setOverlay(null)
+        navStack.length = 0
+        navStack.push(mainDeck.id)
+        const prevTransient = transientDeckId
+        transientDeckId = null
+        if (prevTransient !== null) {
+          pubSub.publish("runtime:deck-inactive", { deckId: prevTransient })
+        }
+        pubSub.publish("runtime:activeDeck", { deckId: mainDeck.id })
+        return true
+      }
+      if (gesture === "dbl-tap") {
+        if (overlayDeckId !== null) {
+          setOverlay(null)
+        } else if (availableOverlayDeckId !== null) {
+          setOverlay(availableOverlayDeckId)
+        }
+        return true
+      }
+      return true
+    }
+    // ponytail: gesture table — see ARCHITECTURE §5.
+    // core:settings-entry tap = open settings overlay; dbl-tap = toggle overlay.
+    // core:overlay-toggle tap/dbl-tap = toggle overlay (legacy fallback).
+    if (type === "core:settings-entry") {
+      if (gesture === "tap") {
+        navigateToDeck("internal-settings:settings", { addToHistory: true })
+        return true
+      }
+      if (gesture === "dbl-tap") {
+        if (overlayDeckId !== null) {
+          setOverlay(null)
+        } else if (availableOverlayDeckId !== null) {
+          setOverlay(availableOverlayDeckId)
+        }
+        return true
+      }
+      return false
+    }
+    if (type === "core:overlay-toggle") {
+      // ponytail: tap = step back within overlay path; dbl-tap = toggle
+      // overlay on/off; hold is left unhandled so it can fall through if the
+      // user assigns a hold action elsewhere.
+      if (gesture === "tap") {
+        goBack()
+        return true
+      }
+      if (gesture === "dbl-tap") {
+        if (overlayDeckId !== null) {
+          setOverlay(null)
+        } else if (availableOverlayDeckId !== null) {
+          setOverlay(availableOverlayDeckId)
+        }
+        return true
+      }
+      return false
+    }
+    return false
+  }
+
+  const invokeAction = async (
+    buttonId: string,
+    gesture: GestureKind,
+  ): Promise<void> => {
+    let found: { deckId: string; button: RuntimeDeck["buttons"][number] } | null
+    try {
+      found = findButton(buttonId)
+    } catch (err) {
+      // ponytail: findButton indexes into a Map — should never throw, but
+      // a corrupted deck entry would otherwise crash the daemon on every
+      // gesture. Log + bail; let the next gesture try again.
+      logger.error({ err, buttonId }, "runtime: findButton threw")
+      return
+    }
+    if (found === null) {
+      logger.warn({ buttonId }, "invokeAction: button not found")
+      return
+    }
+
+    try {
+      if (handleSystemButton(found.button.type, gesture)) {
+        return
+      }
+
+      if (lockActive && found.deckId === "core:lock") {
+        if (LOCK_FOLDER_NAV_TYPES.has(found.button.type)) {
+          lockActive = false
+          preLockActiveDeckId = null
+          preLockOverlayDeckId = null
+          if (overlayDeckId !== null) setOverlay(null)
+          pubSub.publish("runtime:lock-mode", {
+            active: false,
+            reason: "escape",
+          })
+          logger.info(
+            { buttonId, gesture, buttonType: found.button.type },
+            "runtime: lock escaped via folder-nav button",
+          )
+        } else {
+          logger.debug(
+            { buttonId, gesture, buttonType: found.button.type },
+            "runtime: lock-mode gesture suppressed",
+          )
+          return
+        }
+      }
+
+      if (found.deckId !== getActiveDeckId() && found.deckId !== "core:lock") {
+        logger.debug(
+          { buttonId, deckId: found.deckId, activeDeckId: getActiveDeckId() },
+          "invokeAction: gesture on inactive deck, dropping",
+        )
+        return
+      }
+
+      const userAction =
+        gesture === "tap"
+          ? found.button.actions?.tap
+          : gesture === "dbl-tap"
+            ? found.button.actions?.dbltap
+            : found.button.actions?.hold
+
+      const deck = deckById(found.deckId)
+      // ponytail: Array.isArray is tighter than  — rejects
+      // , , and non-array values uniformly. Defends
+      // against any RuntimeDeck that ends up with  missing
+      // (corrupted state, future refactor, runtime injection).
+      const position =
+        found.button.position ??
+        (Array.isArray(deck?.buttons)
+          ? deck.buttons.findIndex((b) => b.id === found.button.id)
+          : -1)
+
+      logger.info(
+        {
+          buttonId,
+          deckId: found.deckId,
+          position,
+          gesture,
+          buttonType: found.button.type,
+          buttonActions: found.button.actions,
+          userAction,
+        },
+        "[runtime] invokeAction resolved",
+      )
+
+      if (userAction !== undefined) {
+        logger.info(
+          { buttonId, gesture, action: userAction },
+          "[addon:sirenodeck] user action",
+        )
+        const capability = getRequiredCapability(userAction)
+        if (capability !== null && !getMethods().checkRequirement(capability)) {
+          logger.warn(
+            { buttonId, gesture, action: userAction, capability },
+            "[runtime] action skipped: missing system requirement",
+          )
+          if (position >= 0) {
+            getMethods().showTemporaryError(
+              found.deckId,
+              position,
+              undefined,
+              found.button.id,
+              `missing-requirement: ${capability}`,
+            )
+          }
+          return
+        }
+        try {
+          await getMethods().dispatch(userAction)
+        } catch (err) {
+          logger.error(
+            { buttonId, gesture, err },
+            "[addon:sirenodeck] user action failed",
+          )
+          if (position >= 0) {
+            getMethods().showTemporaryError(
+              found.deckId,
+              position,
+              undefined,
+              found.button.id,
+              `action-failed: ${userAction}`,
+            )
+          }
+        }
+        return
+      }
+
+      const handlerKey = `${found.deckId}:${found.button.id}`
+      const handler = handlers.get(handlerKey)
+      if (handler === undefined) {
+        // Dynamic decks can be rebuilt after addon services mount. Pagination
+        // is declarative, so keep its navigation working for those new buttons.
+        if (found.button.type === "core:page-nav") {
+          const config = found.button.config
+          if (typeof config === "object" && config !== null) {
+            const target =
+              gesture === "tap"
+                ? (config as { nextDeckId?: unknown }).nextDeckId
+                : gesture === "hold"
+                  ? (config as { prevDeckId?: unknown }).prevDeckId
+                  : undefined
+            if (typeof target === "string") {
+              navigateToDeck(target, { addToHistory: false })
+            }
+          }
+        }
+        return
+      }
+      const ctx: ButtonActionContext = {
+        buttonId,
+        deckId: found.deckId,
+        config: found.button.config,
+        gesture,
+        position: found.button.position,
+      }
+      const fn =
+        gesture === "tap"
+          ? handler.onTap
+          : gesture === "dbl-tap"
+            ? handler.onDblTap
+            : handler.onHold
+      if (fn === undefined) {
+        return
+      }
+      await fn(ctx)
+    } catch (err) {
+      // ponytail: a single bad button-press must not crash the entire
+      // daemon. Log the failure with full context so operators see it in
+      // service.log and can file a bug — but keep serving subsequent
+      // gestures instead of exiting via killChildrenAndExit.
+      logger.error(
+        {
+          err,
+          buttonId,
+          gesture,
+          deckId: found.deckId,
+          buttonType: found.button.type,
+        },
+        "invokeAction: uncaught error in handler",
+      )
+    }
+  }
+
+  const dispatchGesture = async (
+    buttonId: string,
+    gesture: GestureKind,
+  ): Promise<void> => {
+    const found = findButton(buttonId)
+    if (found === null) {
+      logger.warn({ buttonId }, "dispatchGesture: button not found")
+      return
+    }
+    gestureListener?.(found.button.id, {
+      gesture,
+      at: Date.now(),
+      position: found.button.position,
+    })
+    await invokeAction(buttonId, gesture)
+  }
+
+  const setGestureListener = (listener: GestureListener | null): void => {
+    gestureListener = listener
+  }
+
+  const invalidate = (): void => {
+    pubSub.publish("runtime:invalidate", { activeDeckId: getActiveDeckId() })
+  }
+
+  void store
+
+  const overlayDecks = (): Array<{
+    deck: RuntimeDeck
+    matcher: ReturnType<typeof compileDeckMatcher>
+    specificity: number
+  }> => {
+    const result: Array<{
+      deck: RuntimeDeck
+      matcher: ReturnType<typeof compileDeckMatcher>
+      specificity: number
+    }> = []
+    for (const deck of decks) {
+      const hasProcess =
+        deck.processNames !== undefined && deck.processNames.length > 0
+      const hasWindow =
+        deck.windowNames !== undefined && deck.windowNames.length > 0
+      if (!hasProcess && !hasWindow) continue
+      result.push({
+        deck,
+        matcher: compileDeckMatcher({
+          processNames: deck.processNames,
+          windowNames: deck.windowNames,
+        }),
+        specificity: (hasProcess ? 1 : 0) + (hasWindow ? 1 : 0),
+      })
+    }
+    return result
+  }
+
+  let activeAppPoll: ReturnType<typeof setInterval> | null = null
+  let activeAppProvider: ActiveAppProviderLike | null = null
+  let lastOverlayDeckId: string | null = overlayDeckId
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null
+  let pendingOverlayDeckId: string | null = null
+  let latestActiveAppSnapshot: {
+    name: string
+    windowTitle: string | null
+    processId: number | null
+  } | null = null
+
+  const applyOverlay = (deckId: string | null): void => {
+    if (deckId !== null && deckById(deckId) === undefined) {
+      logger.warn({ deckId }, "active-app: overlay deck not found")
+      return
+    }
+    if (deckId === null) {
+      // ponytail: no overlay matches anymore. If we had one active, dismiss it.
+      if (overlayDeckId !== null) {
+        logger.info(
+          { prevOverlayId: overlayDeckId },
+          "active-app: dismissing previous overlay (no match)",
+        )
+        setOverlay(null, { source: "autoShow" })
+      }
+      lastOverlayDeckId = null
+      return
+    }
+    if (overlayDeckId !== null && deckId !== overlayDeckId) {
+      // ponytail: overlay mode is a routing branch. If the new match is
+      // auto-show it replaces the current overlay; if it's not auto-show the
+      // current overlay dismisses and the new match stays as available-only
+      // (manual toggle required). In both cases the previous overlay's
+      // overlayNavStacks entry is preserved for re-activation.
+      const newDeck = deckById(deckId)
+      if (newDeck === undefined) return
+      if (newDeck.autoShow === true) {
+        logger.info(
+          { prevOverlayId: overlayDeckId, newMatch: deckId },
+          "active-app: switching overlay (match moved, autoShow)",
+        )
+        setOverlay(deckId, { source: "autoShow" })
+      } else {
+        logger.info(
+          { prevOverlayId: overlayDeckId, newMatch: deckId },
+          "active-app: dismissing current overlay (new match is not autoShow)",
+        )
+        setOverlay(null, { source: "autoShow" })
+      }
+      lastOverlayDeckId = deckId
+      return
+    }
+    if (deckId === lastOverlayDeckId) return
+    const deck = deckById(deckId)
+    if (deck === undefined) return
+    logger.info(
+      { deckId, autoShow: deck.autoShow === true },
+      "active-app: applying overlay",
+    )
+    if (deck.autoShow !== true) {
+      lastOverlayDeckId = deckId
+      return
+    }
+    lastOverlayDeckId = deckId
+    setOverlay(deckId, { source: "autoShow" })
+  }
+
+  const computeOverlayFor = (snapshot: {
+    name: string
+    windowTitle: string | null
+    processId: number | null
+  }): string | null => {
+    let bestId: string | null = null
+    let bestSpecificity = -1
+    for (const { deck, matcher, specificity } of overlayDecks()) {
+      if (!matcher(snapshot)) continue
+      if (specificity > bestSpecificity) {
+        bestId = deck.id
+        bestSpecificity = specificity
+      }
+    }
+    if (availableOverlayDeckId !== bestId) {
+      const prev = availableOverlayDeckId
+      availableOverlayDeckId = bestId
+      if (bestId !== null) {
+        logger.info(
+          {
+            from: prev,
+            to: bestId,
+            snapshot: {
+              name: snapshot.name,
+              windowTitle: snapshot.windowTitle,
+            },
+          },
+          "active-app: overlay deck available",
+        )
+      } else if (prev !== null) {
+        logger.info({ from: prev }, "active-app: no overlay deck matches")
+      }
+      pubSub.publish("runtime:overlay-available", { deckId: bestId })
+    }
+    return bestId
+  }
+
+  const scheduleOverlay = (deckId: string | null): void => {
+    pendingOverlayDeckId = deckId
+    if (debounceTimer !== null) clearTimeout(debounceTimer)
+    debounceTimer = setTimeout(() => {
+      debounceTimer = null
+      const next = pendingOverlayDeckId
+      pendingOverlayDeckId = null
+      applyOverlay(next)
+    }, 200)
+  }
+
+  const startActiveAppLoop = (provider: ActiveAppProviderLike): void => {
+    if (activeAppPoll !== null) return
+    logger.info("active-app: poll loop started")
+    activeAppPoll = setInterval(() => {
+      void provider.getActive().then((snapshot) => {
+        if (snapshot === null) {
+          latestActiveAppSnapshot = null
+          scheduleOverlay(null)
+          return
+        }
+        latestActiveAppSnapshot = snapshot
+        logger.debug(
+          {
+            snapshot: {
+              name: snapshot.name,
+              windowTitle: snapshot.windowTitle,
+            },
+          },
+          "active-app: snapshot",
+        )
+        scheduleOverlay(computeOverlayFor(snapshot))
+      })
+    }, 1000)
+  }
+
+  const stopActiveAppLoop = (): void => {
+    if (debounceTimer !== null) {
+      clearTimeout(debounceTimer)
+      debounceTimer = null
+    }
+    pendingOverlayDeckId = null
+    if (activeAppPoll !== null) {
+      clearInterval(activeAppPoll)
+      activeAppPoll = null
+    }
+  }
+
+  const setActiveAppProvider = (provider: ActiveAppProviderLike): void => {
+    activeAppProvider = provider
+    startActiveAppLoop(provider)
+  }
+
+  const setSessionProvider = (provider: SessionProvider): void => {
+    if (sessionUnsubscribe !== null) {
+      sessionUnsubscribe()
+      sessionUnsubscribe = null
+    }
+    const handle = (state: SessionState): void => {
+      if (state === "locked" && !lockActive) {
+        enterLockMode()
+        return
+      }
+      if (state === "locked" && lockActive) {
+        preLockActiveDeckId = snapshotRegularActiveDeckId()
+        preLockOverlayDeckId = overlayDeckId
+        logger.info("runtime: lock snapshot refreshed on re-lock")
+        return
+      }
+      if (state === "unlocked" && lockActive) {
+        lockActive = false
+        const overlaySnapshot = preLockOverlayDeckId
+        const activeSnapshot = preLockActiveDeckId
+        preLockActiveDeckId = null
+        preLockOverlayDeckId = null
+        if (
+          overlaySnapshot !== null &&
+          latestActiveAppSnapshot !== null &&
+          computeOverlayFor(latestActiveAppSnapshot) === overlaySnapshot
+        ) {
+          logger.info(
+            { overlayId: overlaySnapshot },
+            "runtime: overlay auto-resumed on unlock (trigger still matches)",
+          )
+          setOverlay(overlaySnapshot, { source: "autoShow" })
+        } else {
+          if (overlayDeckId !== null) setOverlay(null)
+          const restoreId = activeSnapshot ?? mainDeck.id
+          logger.info(
+            { restoreId, overlayWas: overlaySnapshot, triggerMatches: false },
+            "runtime: lock cleared, restoring previous deck",
+          )
+          navigateToDeck(restoreId, { addToHistory: false })
+        }
+        pubSub.publish("runtime:lock-mode", {
+          active: false,
+          reason: "session-unlocked",
+        })
+        pubSub.publish("runtime:invalidate", undefined)
+      }
+    }
+    sessionUnsubscribe = provider.subscribe(handle)
+  }
+
+  const stopActiveAppPolling = async (): Promise<void> => {
+    stopActiveAppLoop()
+    if (activeAppProvider !== null) {
+      try {
+        await activeAppProvider.stop()
+      } catch (err) {
+        logger.warn({ err }, "active-app: provider stop() failed")
+      }
+      activeAppProvider = null
+    }
+  }
+
+  const runtime: Runtime = {
+    getActiveDeck,
+    getActiveDeckId,
+    deckExists: (id: string) =>
+      deckById(id) !== undefined || deckById(`${id}-p1`) !== undefined,
+    setDecks,
+    navigateToDeck,
+    goBack,
+    setOverlay,
+    getOverlay,
+    registerButtonHandler,
+    unregisterButtonHandler,
+    mountAddonButtons,
+    dispatchGesture,
+    invokeAction,
+    setGestureListener,
+    invalidate,
+    setActiveAppProvider,
+    setSessionProvider,
+    isLockActive: () => lockActive,
+    stopActiveAppPolling,
+    navStackDepth: () => navStack.length,
+    hasOverlayDeckAvailable: () =>
+      availableOverlayDeckId !== null || pendingOverlayDeckId !== null,
+    getAvailableOverlayDeckIcon: (): string | null => {
+      const id = availableOverlayDeckId ?? pendingOverlayDeckId
+      if (id === null) return null
+      const deck = deckById(id)
+      return deck?.icon ?? null
+    },
+    getAvailableOverlayDeckName: (): string | null => {
+      const id = availableOverlayDeckId ?? pendingOverlayDeckId
+      if (id === null) return null
+      const deck = deckById(id)
+      return deck?.name ?? null
+    },
+    getBrightness: () => brightness,
+    setBrightness: (value: number) => {
+      const clamped = Math.max(10, Math.min(100, Math.round(value)))
+      if (clamped === brightness) return
+      brightness = clamped
+      pubSub.publish("sireno:settings:brightness", { value: clamped })
+    },
+    getEditorSurfaces: ({ keyCount = 15, revision = 0 } = {}) => {
+      return describeEditorSurfaces({
+        decks,
+        keyCount,
+        revision,
+        systemState: {
+          navStackDepth: navStack.length,
+          hasOverlayDeckAvailable: availableOverlayDeckId !== null,
+          lockActive,
+          inOverlayMode: overlayDeckId !== null,
+        },
+      })
+    },
+  }
+
+  return runtime
+}