getting terminal colors working

2026-02-05 13:46:47 -05:00
parent 9fa52d71ca
commit e239b33042
45 changed files with 1718 additions and 2055 deletions
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -1,4 +1,5 @@
 import { createSignal } from "solid-js";
+import { useRenderer } from "@opentui/solid";
 import { Layout } from "./components/Layout";
 import { Navigation } from "./components/Navigation";
 import { TabNavigation } from "./components/TabNavigation";
@@ -32,31 +33,31 @@ export function App() {
  // Centralized keyboard handler for all tab navigation and shortcuts
  useAppKeyboard({
    get activeTab() {
-      return activeTab()
+      return activeTab();
    },
    onTabChange: setActiveTab,
    inputFocused: inputFocused(),
    navigationEnabled: layerDepth() === 0,
    layerDepth,
    onLayerChange: (newDepth) => {
-      setLayerDepth(newDepth)
+      setLayerDepth(newDepth);
    },
    onAction: (action) => {
      if (action === "escape") {
        if (layerDepth() > 0) {
-          setLayerDepth(0)
-          setInputFocused(false)
+          setLayerDepth(0);
+          setInputFocused(false);
        } else {
-          setShowAuthPanel(false)
-          setInputFocused(false)
+          setShowAuthPanel(false);
+          setInputFocused(false);
        }
      }

      if (action === "enter" && layerDepth() === 0) {
-        setLayerDepth(1)
+        setLayerDepth(1);
      }
    },
-  })
+  });

  const renderContent = () => {
    const tab = activeTab();
--- a/src/components/Layout.tsx
+++ b/src/components/Layout.tsx
@@ -1,5 +1,6 @@
 import type { JSX } from "solid-js"
 import type { RGBA } from "@opentui/core"
+import { Show, createMemo } from "solid-js"
 import { useTheme } from "../context/ThemeContext"
 import { LayerIndicator } from "./LayerIndicator"

@@ -16,52 +17,50 @@ type LayoutProps = {
 }

 export function Layout(props: LayoutProps) {
-  const { theme } = useTheme()
+  const context = useTheme()

-  // Get layer configuration based on depth
-  const getLayerConfig = (depth: number): LayerConfig => {
-    const backgrounds = theme.layerBackgrounds
+  // Get layer configuration based on depth - wrapped in createMemo for reactivity
+  const currentLayer = createMemo((): LayerConfig => {
+    const depth = props.layerDepth || 0
+    const backgrounds = context.theme.layerBackgrounds
    const depthMap: Record<number, LayerConfig> = {
-      0: { depth: 0, background: backgrounds?.layer0 ?? theme.background },
-      1: { depth: 1, background: backgrounds?.layer1 ?? theme.backgroundPanel },
-      2: { depth: 2, background: backgrounds?.layer2 ?? theme.backgroundElement },
-      3: { depth: 3, background: backgrounds?.layer3 ?? theme.backgroundMenu },
+      0: { depth: 0, background: backgrounds?.layer0 ?? context.theme.background },
+      1: { depth: 1, background: backgrounds?.layer1 ?? context.theme.backgroundPanel },
+      2: { depth: 2, background: backgrounds?.layer2 ?? context.theme.backgroundElement },
+      3: { depth: 3, background: backgrounds?.layer3 ?? context.theme.backgroundMenu },
    }

-    return depthMap[depth] || { depth: 0, background: theme.background }
-  }
-
-  // Get current layer background
-  const currentLayer = getLayerConfig(props.layerDepth || 0)
+    return depthMap[depth] || { depth: 0, background: context.theme.background }
+  })

+  // Note: No need for a ready check here - the ThemeProvider uses
+  // createSimpleContext which gates children rendering until ready
  return (
    <box
      flexDirection="column"
      width="100%"
      height="100%"
-      backgroundColor={theme.background}
+      backgroundColor={context.theme.background}
    >
      {/* Header */}
-      {props.header ? (
+      <Show when={props.header} fallback={<box style={{ height: 4 }} />}>
        <box
          style={{
            height: 4,
-            backgroundColor: theme.surface ?? theme.backgroundPanel,
+            backgroundColor: context.theme.surface ?? context.theme.backgroundPanel,
          }}
        >
          <box style={{ padding: 1 }}>
            {props.header}
          </box>
        </box>
-      ) : (
-        <box style={{ height: 4 }} />
-      )}
+      </Show>

      {/* Main content area with layer background */}
      <box
        style={{
          flexGrow: 1,
-          backgroundColor: currentLayer.background,
+          backgroundColor: currentLayer().background,
          paddingLeft: 2,
          paddingRight: 2,
        }}
@@ -72,34 +71,32 @@ export function Layout(props: LayoutProps) {
      </box>

      {/* Footer */}
-      {props.footer ? (
+      <Show when={props.footer} fallback={<box style={{ height: 2 }} />}>
        <box
          style={{
            height: 2,
-            backgroundColor: theme.surface ?? theme.backgroundPanel,
+            backgroundColor: context.theme.surface ?? context.theme.backgroundPanel,
          }}
        >
          <box style={{ padding: 1 }}>
            {props.footer}
          </box>
        </box>
-      ) : (
-        <box style={{ height: 2 }} />
-      )}
+      </Show>

      {/* Layer indicator */}
-      {props.layerDepth !== undefined && (
+      <Show when={props.layerDepth !== undefined}>
        <box
          style={{
            height: 1,
-            backgroundColor: theme.surface ?? theme.backgroundPanel,
+            backgroundColor: context.theme.surface ?? context.theme.backgroundPanel,
          }}
        >
          <box style={{ padding: 1 }}>
-            <LayerIndicator layerDepth={props.layerDepth} />
+            <LayerIndicator layerDepth={props.layerDepth as number} />
          </box>
        </box>
-      )}
+      </Show>
    </box>
  )
 }
--- a/src/context/KeybindContext.tsx
+++ b/src/context/KeybindContext.tsx
@@ -0,0 +1,129 @@
+import { createMemo } from "solid-js"
+import type { ParsedKey, Renderable } from "@opentui/core"
+import { createStore } from "solid-js/store"
+import { useKeyboard, useRenderer } from "@opentui/solid"
+import { createSimpleContext } from "./helper"
+import { Keybind, DEFAULT_KEYBINDS, type KeybindsConfig } from "../utils/keybind"
+
+/**
+ * Keybind context provider for managing keyboard shortcuts.
+ *
+ * Features:
+ * - Leader key support (like vim's leader key)
+ * - Configurable keybindings
+ * - Key parsing and matching
+ * - Display-friendly key representations
+ */
+export const { use: useKeybind, provider: KeybindProvider } = createSimpleContext({
+  name: "Keybind",
+  init: (props: { keybinds?: Partial<KeybindsConfig> }) => {
+    // Merge default keybinds with custom keybinds
+    const customKeybinds = props.keybinds ?? {}
+    const mergedKeybinds = { ...DEFAULT_KEYBINDS, ...customKeybinds }
+
+    const keybinds = createMemo(() => {
+      const result: Record<string, Keybind.Info[]> = {}
+      for (const [key, value] of Object.entries(mergedKeybinds)) {
+        result[key] = Keybind.parse(value)
+      }
+      return result
+    })
+
+    const [store, setStore] = createStore({
+      leader: false,
+    })
+
+    const renderer = useRenderer()
+
+    let focus: Renderable | null = null
+    let timeout: NodeJS.Timeout | undefined
+
+    function leader(active: boolean) {
+      if (active) {
+        setStore("leader", true)
+        focus = renderer.currentFocusedRenderable
+        focus?.blur()
+        if (timeout) clearTimeout(timeout)
+        timeout = setTimeout(() => {
+          if (!store.leader) return
+          leader(false)
+          if (!focus || focus.isDestroyed) return
+          focus.focus()
+        }, 2000) // Leader key timeout
+        return
+      }
+
+      if (!active) {
+        if (focus && !renderer.currentFocusedRenderable) {
+          focus.focus()
+        }
+        setStore("leader", false)
+      }
+    }
+
+    // Handle leader key
+    useKeyboard(async (evt) => {
+      if (!store.leader && result.match("leader", evt)) {
+        leader(true)
+        return
+      }
+
+      if (store.leader && evt.name) {
+        setImmediate(() => {
+          if (focus && renderer.currentFocusedRenderable === focus) {
+            focus.focus()
+          }
+          leader(false)
+        })
+      }
+    })
+
+    const result = {
+      get all() {
+        return keybinds()
+      },
+      get leader() {
+        return store.leader
+      },
+      /**
+       * Parse a keyboard event into a Keybind.Info.
+       */
+      parse(evt: ParsedKey): Keybind.Info {
+        // Handle special case for Ctrl+Underscore (represented as \x1F)
+        if (evt.name === "\x1F") {
+          return Keybind.fromParsedKey({ ...evt, name: "_", ctrl: true }, store.leader)
+        }
+        return Keybind.fromParsedKey(evt, store.leader)
+      },
+      /**
+       * Check if a keyboard event matches a registered keybind.
+       */
+      match(key: keyof KeybindsConfig, evt: ParsedKey): boolean {
+        const keybind = keybinds()[key]
+        if (!keybind) return false
+        const parsed: Keybind.Info = result.parse(evt)
+        for (const kb of keybind) {
+          if (Keybind.match(kb, parsed)) {
+            return true
+          }
+        }
+        return false
+      },
+      /**
+       * Get a display string for a registered keybind.
+       */
+      print(key: keyof KeybindsConfig): string {
+        const first = keybinds()[key]?.at(0)
+        if (!first) return ""
+        const display = Keybind.toString(first)
+        // Replace leader placeholder with actual leader key
+        const leaderKey = keybinds().leader?.[0]
+        if (leaderKey) {
+          return display.replace("<leader>", Keybind.toString(leaderKey))
+        }
+        return display
+      },
+    }
+    return result
+  },
+})
--- a/src/context/ThemeContext.tsx
+++ b/src/context/ThemeContext.tsx
@@ -1,13 +1,14 @@
-import { createContext, createEffect, createMemo, createSignal, Show, useContext } from "solid-js"
+import { createEffect, createMemo, onMount, onCleanup } from "solid-js"
 import { createStore, produce } from "solid-js/store"
 import { useRenderer } from "@opentui/solid"
 import type { ThemeName } from "../types/settings"
 import type { ThemeJson } from "../types/theme-schema"
 import { useAppStore } from "../stores/app"
 import { THEME_JSON } from "../constants/themes"
-import { resolveTheme } from "../utils/theme-resolver"
 import { generateSyntax, generateSubtleSyntax } from "../utils/syntax-highlighter"
 import { resolveTerminalTheme, loadThemes } from "../utils/theme"
+import { createSimpleContext } from "./helper"
+import { setupThemeSignalHandler, emitThemeChanged, emitThemeModeChanged } from "../utils/theme-observer"
 import type { RGBA, TerminalColors } from "@opentui/core"

 type ThemeResolved = {
@@ -75,93 +76,154 @@ type ThemeResolved = {
  thinkingOpacity?: number
 }

-type ThemeContextValue = {
-  theme: ThemeResolved
-  selected: () => string
-  all: () => Record<string, ThemeJson>
-  syntax: () => unknown
-  subtleSyntax: () => unknown
-  mode: () => "dark" | "light"
-  setMode: (mode: "dark" | "light") => void
-  set: (theme: string) => void
-  ready: () => boolean
-}
+/**
+ * Theme context using the createSimpleContext pattern.
+ *
+ * This ensures children are NOT rendered until the theme is ready,
+ * preventing "useTheme must be used within a ThemeProvider" errors.
+ *
+ * The key insight from opencode's implementation is that the provider
+ * uses `<Show when={ready}>` to gate rendering, so components can
+ * safely call useTheme() without checking ready state.
+ */
+export const { use: useTheme, provider: ThemeProvider } = createSimpleContext({
+  name: "Theme",
+  init: (props: { mode: "dark" | "light" }) => {
+    const appStore = useAppStore()
+    const renderer = useRenderer()
+    const [store, setStore] = createStore({
+      themes: THEME_JSON as Record<string, ThemeJson>,
+      mode: props.mode,
+      active: appStore.state().settings.theme as string,
+      system: undefined as undefined | TerminalColors,
+      ready: false,
+    })

-const ThemeContext = createContext<ThemeContextValue>()
+    function init() {
+      resolveSystemTheme()
+      loadThemes()
+        .then((custom) => {
+          setStore(
+            produce((draft) => {
+              Object.assign(draft.themes, custom)
+            })
+          )
+        })
+        .catch(() => {
+          // If custom themes fail to load, fall back to opencode theme
+          setStore("active", "opencode")
+        })
+        .finally(() => {
+          // Only set ready if not waiting for system theme
+          if (store.active !== "system") {
+            setStore("ready", true)
+          }
+        })
+    }

-export function ThemeProvider({ children }: { children: any }) {
-  const appStore = useAppStore()
-  const renderer = useRenderer()
-  const [ready, setReady] = createSignal(false)
-  const [store, setStore] = createStore({
-    themes: {} as Record<string, ThemeJson>,
-    mode: "dark" as "dark" | "light",
-    active: appStore.state().settings.theme as ThemeName,
-    system: undefined as undefined | TerminalColors,
-  })
+    function resolveSystemTheme() {
+      renderer
+        .getPalette({ size: 16 })
+        .then((colors) => {
+          if (!colors.palette[0]) {
+            // No system colors available, fall back to default
+            // This happens when the terminal doesn't support OSC palette queries
+            // (e.g., running inside tmux, or on unsupported terminals)
+            if (store.active === "system") {
+              setStore(
+                produce((draft) => {
+                  draft.active = "opencode"
+                  draft.ready = true
+                })
+              )
+            }
+            return
+          }
+          setStore(
+            produce((draft) => {
+              draft.system = colors
+              if (store.active === "system") {
+                draft.ready = true
+              }
+            })
+          )
+        })
+        .catch(() => {
+          // On error, fall back to default theme if using system
+          if (store.active === "system") {
+            setStore(
+              produce((draft) => {
+                draft.active = "opencode"
+                draft.ready = true
+              })
+            )
+          }
+        })
+    }

-  const init = () => {
-    loadThemes()
-      .then((custom) => {
-        setStore(
-          produce((draft) => {
-            Object.assign(draft.themes, custom)
-          })
-        )
-      })
-      .finally(() => setReady(true))
-  }
+    onMount(init)

-  init()
+    // Setup SIGUSR2 signal handler for dynamic theme reload
+    // This allows external tools to trigger a theme refresh by sending:
+    // `kill -USR2 <pid>`
+    const cleanupSignalHandler = setupThemeSignalHandler(() => {
+      renderer.clearPaletteCache()
+      init()
+    })
+    onCleanup(cleanupSignalHandler)

-  createEffect(() => {
-    setStore("active", appStore.state().settings.theme)
-  })
+    // Sync active theme with app store settings
+    createEffect(() => {
+      const theme = appStore.state().settings.theme
+      if (theme) setStore("active", theme)
+    })

-  createEffect(() => {
-    renderer
-      .getPalette({ size: 16 })
-      .then((colors) => setStore("system", colors))
-      .catch(() => {})
-  })
+    // Emit theme change events for observers
+    createEffect(() => {
+      const theme = store.active
+      const mode = store.mode
+      if (store.ready) {
+        emitThemeChanged(theme, mode)
+      }
+    })

-  const values = createMemo(() => {
-    const themes = Object.keys(store.themes).length ? store.themes : THEME_JSON
-    return resolveTerminalTheme(themes, store.active, store.mode, store.system)
-  })
+    const values = createMemo(() => {
+      return resolveTerminalTheme(store.themes, store.active, store.mode, store.system)
+    })

-  const syntax = createMemo(() => generateSyntax(values() as unknown as Record<string, RGBA>))
-  const subtleSyntax = createMemo(() =>
-    generateSubtleSyntax(values() as unknown as Record<string, RGBA> & { thinkingOpacity?: number })
-  )
+    const syntax = createMemo(() => generateSyntax(values() as unknown as Record<string, RGBA>))
+    const subtleSyntax = createMemo(() =>
+      generateSubtleSyntax(values() as unknown as Record<string, RGBA> & { thinkingOpacity?: number })
+    )

-  const context: ThemeContextValue = {
-  theme: new Proxy(values(), {
-    get(_target, prop) {
-      return values()[prop as keyof typeof values]
-    },
-  }) as ThemeResolved,
-    selected: () => store.active,
-    all: () => store.themes,
-    syntax,
-    subtleSyntax,
-    mode: () => store.mode,
-    setMode: (mode) => setStore("mode", mode),
-    set: (theme) => appStore.setTheme(theme as ThemeName),
-    ready,
-  }
-
-  return (
-    <Show when={ready()}>
-      <ThemeContext.Provider value={context}>{children}</ThemeContext.Provider>
-    </Show>
-  )
-}
-
-export function useTheme() {
-  const context = useContext(ThemeContext)
-  if (!context) {
-    throw new Error("useTheme must be used within a ThemeProvider")
-  }
-  return context
-}
+    return {
+      theme: new Proxy(values(), {
+        get(_target, prop) {
+          // @ts-expect-error - dynamic property access
+          return values()[prop]
+        },
+      }) as ThemeResolved,
+      get selected() {
+        return store.active
+      },
+      all() {
+        return store.themes
+      },
+      syntax,
+      subtleSyntax,
+      mode() {
+        return store.mode
+      },
+      setMode(mode: "dark" | "light") {
+        setStore("mode", mode)
+        emitThemeModeChanged(mode)
+      },
+      set(theme: string) {
+        appStore.setTheme(theme as ThemeName)
+      },
+      get ready() {
+        return store.ready
+      },
+    }
+  },
+})
--- a/src/context/helper.tsx
+++ b/src/context/helper.tsx
@@ -0,0 +1,53 @@
+import { createContext, Show, useContext, type ParentProps } from "solid-js"
+
+/**
+ * Creates a simple context with automatic ready-state handling.
+ *
+ * This pattern ensures that child components are NOT rendered until the
+ * context's `ready` property is true (or undefined, meaning no ready check needed).
+ *
+ * This prevents the "useX must be used within a XProvider" errors that occur
+ * when child components try to use context values before the provider has
+ * finished async initialization.
+ *
+ * Usage:
+ * ```tsx
+ * export const { use: useMyContext, provider: MyProvider } = createSimpleContext({
+ *   name: "MyContext",
+ *   init: (props: { someProp: string }) => {
+ *     const [ready, setReady] = createSignal(false)
+ *     // ... async initialization ...
+ *     return {
+ *       get ready() { return ready() },
+ *       // ... other values
+ *     }
+ *   },
+ * })
+ * ```
+ */
+export function createSimpleContext<T, Props extends Record<string, any>>(input: {
+  name: string
+  init: ((input: Props) => T) | (() => T)
+}) {
+  const ctx = createContext<T>()
+
+  return {
+    provider: (props: ParentProps<Props>) => {
+      const init = input.init(props)
+      // Use an arrow function accessor for the ready check to maintain reactivity.
+      // The getter `init.ready` reads from a store, so wrapping it in an
+      // accessor allows Solid to track changes reactively.
+      return (
+        // @ts-expect-error - ready may not exist on all context types
+        <Show when={init.ready === undefined || init.ready}>
+          <ctx.Provider value={init}>{props.children}</ctx.Provider>
+        </Show>
+      )
+    },
+    use() {
+      const value = useContext(ctx)
+      if (!value) throw new Error(`${input.name} context must be used within a context provider`)
+      return value
+    },
+  }
+}
--- a/src/index.tsx
+++ b/src/index.tsx
@@ -1,10 +1,22 @@
 import { render } from "@opentui/solid"
 import { App } from "./App"
 import { ThemeProvider } from "./context/ThemeContext"
-import "./styles/theme.css"
+import { ToastProvider, Toast } from "./ui/toast"
+import { KeybindProvider } from "./context/KeybindContext"
+import { DialogProvider } from "./ui/dialog"
+import { CommandProvider } from "./ui/command"

 render(() => (
-  <ThemeProvider>
-    <App />
-  </ThemeProvider>
+  <ToastProvider>
+    <ThemeProvider mode="dark">
+      <KeybindProvider>
+        <DialogProvider>
+          <CommandProvider>
+            <App />
+            <Toast />
+          </CommandProvider>
+        </DialogProvider>
+      </KeybindProvider>
+    </ThemeProvider>
+  </ToastProvider>
 ))
--- a/src/types/settings.ts
+++ b/src/types/settings.ts
@@ -1,7 +1,7 @@
 import type { RGBA } from "@opentui/core"
 import type { ColorValue, ThemeJson, Variant } from "./theme-schema"

-export type ThemeName = "system" | "catppuccin" | "gruvbox" | "tokyo" | "nord" | "custom"
+export type ThemeName = "system" | "opencode" | "catppuccin" | "gruvbox" | "tokyo" | "nord" | "custom"

 export type LayerBackgrounds = {
  layer0: ColorValue
--- a/src/ui/command.tsx
+++ b/src/ui/command.tsx
@@ -0,0 +1,307 @@
+import {
+  createContext,
+  createMemo,
+  createSignal,
+  onCleanup,
+  useContext,
+  type Accessor,
+  type ParentProps,
+  For,
+  Show,
+} from "solid-js"
+import { useKeyboard, useTerminalDimensions } from "@opentui/solid"
+import { useKeybind } from "../context/KeybindContext"
+import { useDialog } from "./dialog"
+import { useTheme } from "../context/ThemeContext"
+import type { KeybindsConfig } from "../utils/keybind"
+import { TextAttributes } from "@opentui/core"
+import { emit } from "../utils/event-bus"
+
+/**
+ * Command option for the command palette.
+ */
+export type CommandOption = {
+  /** Display title */
+  title: string
+  /** Unique identifier */
+  value: string
+  /** Description shown below title */
+  description?: string
+  /** Category for grouping */
+  category?: string
+  /** Keybind reference */
+  keybind?: keyof KeybindsConfig
+  /** Whether this command is suggested */
+  suggested?: boolean
+  /** Slash command configuration */
+  slash?: {
+    name: string
+    aliases?: string[]
+  }
+  /** Whether to hide from command list */
+  hidden?: boolean
+  /** Whether command is enabled */
+  enabled?: boolean
+  /** Footer text (usually keybind display) */
+  footer?: string
+  /** Handler when command is selected */
+  onSelect?: (dialog: ReturnType<typeof useDialog>) => void
+}
+
+type CommandContext = ReturnType<typeof init>
+const ctx = createContext<CommandContext>()
+
+function init() {
+  const [registrations, setRegistrations] = createSignal<Accessor<CommandOption[]>[]>([])
+  const [suspendCount, setSuspendCount] = createSignal(0)
+  const dialog = useDialog()
+  const keybind = useKeybind()
+
+  const entries = createMemo(() => {
+    const all = registrations().flatMap((x) => x())
+    return all.map((x) => ({
+      ...x,
+      footer: x.keybind ? keybind.print(x.keybind) : undefined,
+    }))
+  })
+
+  const isEnabled = (option: CommandOption) => option.enabled !== false
+  const isVisible = (option: CommandOption) => isEnabled(option) && !option.hidden
+
+  const visibleOptions = createMemo(() => entries().filter((option) => isVisible(option)))
+  const suggestedOptions = createMemo(() =>
+    visibleOptions()
+      .filter((option) => option.suggested)
+      .map((option) => ({
+        ...option,
+        value: `suggested:${option.value}`,
+        category: "Suggested",
+      })),
+  )
+  const suspended = () => suspendCount() > 0
+
+  // Handle keybind shortcuts
+  useKeyboard((evt) => {
+    if (suspended()) return
+    if (dialog.isOpen) return
+    for (const option of entries()) {
+      if (!isEnabled(option)) continue
+      if (option.keybind && keybind.match(option.keybind, evt)) {
+        evt.preventDefault()
+        option.onSelect?.(dialog)
+        emit("command.execute", { command: option.value })
+        return
+      }
+    }
+  })
+
+  const result = {
+    /**
+     * Trigger a command by its value.
+     */
+    trigger(name: string) {
+      for (const option of entries()) {
+        if (option.value === name) {
+          if (!isEnabled(option)) return
+          option.onSelect?.(dialog)
+          emit("command.execute", { command: name })
+          return
+        }
+      }
+    },
+    /**
+     * Get all slash commands.
+     */
+    slashes() {
+      return visibleOptions().flatMap((option) => {
+        const slash = option.slash
+        if (!slash) return []
+        return {
+          display: "/" + slash.name,
+          description: option.description ?? option.title,
+          aliases: slash.aliases?.map((alias) => "/" + alias),
+          onSelect: () => result.trigger(option.value),
+        }
+      })
+    },
+    /**
+     * Enable/disable keybinds temporarily.
+     */
+    keybinds(enabled: boolean) {
+      setSuspendCount((count) => count + (enabled ? -1 : 1))
+    },
+    suspended,
+    /**
+     * Show the command palette dialog.
+     */
+    show() {
+      dialog.replace(() => <CommandDialog options={visibleOptions()} suggestedOptions={suggestedOptions()} />)
+    },
+    /**
+     * Register commands. Returns cleanup function.
+     */
+    register(cb: () => CommandOption[]) {
+      const results = createMemo(cb)
+      setRegistrations((arr) => [results, ...arr])
+      onCleanup(() => {
+        setRegistrations((arr) => arr.filter((x) => x !== results))
+      })
+    },
+    /**
+     * Get all visible options.
+     */
+    get options() {
+      return visibleOptions()
+    },
+  }
+  return result
+}
+
+export function useCommandDialog() {
+  const value = useContext(ctx)
+  if (!value) {
+    throw new Error("useCommandDialog must be used within a CommandProvider")
+  }
+  return value
+}
+
+export function CommandProvider(props: ParentProps) {
+  const value = init()
+  const dialog = useDialog()
+  const keybind = useKeybind()
+
+  // Open command palette on ctrl+p or command_list keybind
+  useKeyboard((evt) => {
+    if (value.suspended()) return
+    if (dialog.isOpen) return
+    if (evt.defaultPrevented) return
+    if (keybind.match("command_list", evt)) {
+      evt.preventDefault()
+      value.show()
+      return
+    }
+  })
+
+  return <ctx.Provider value={value}>{props.children}</ctx.Provider>
+}
+
+/**
+ * Command palette dialog component.
+ */
+function CommandDialog(props: { options: CommandOption[]; suggestedOptions: CommandOption[] }) {
+  const { theme } = useTheme()
+  const dialog = useDialog()
+  const dimensions = useTerminalDimensions()
+  const [filter, setFilter] = createSignal("")
+  const [selectedIndex, setSelectedIndex] = createSignal(0)
+
+  const filteredOptions = createMemo(() => {
+    const query = filter().toLowerCase()
+    if (!query) {
+      return [...props.suggestedOptions, ...props.options]
+    }
+    return props.options.filter(
+      (option) =>
+        option.title.toLowerCase().includes(query) ||
+        option.description?.toLowerCase().includes(query) ||
+        option.category?.toLowerCase().includes(query)
+    )
+  })
+
+  // Reset selection when filter changes
+  createMemo(() => {
+    filter()
+    setSelectedIndex(0)
+  })
+
+  useKeyboard((evt) => {
+    if (evt.name === "escape") {
+      dialog.clear()
+      evt.preventDefault()
+      return
+    }
+
+    if (evt.name === "return" || evt.name === "enter") {
+      const option = filteredOptions()[selectedIndex()]
+      if (option) {
+        option.onSelect?.(dialog)
+        dialog.clear()
+      }
+      evt.preventDefault()
+      return
+    }
+
+    if (evt.name === "up" || (evt.ctrl && evt.name === "p")) {
+      setSelectedIndex((i) => Math.max(0, i - 1))
+      evt.preventDefault()
+      return
+    }
+
+    if (evt.name === "down" || (evt.ctrl && evt.name === "n")) {
+      setSelectedIndex((i) => Math.min(filteredOptions().length - 1, i + 1))
+      evt.preventDefault()
+      return
+    }
+
+    // Handle text input
+    if (evt.name && evt.name.length === 1 && !evt.ctrl && !evt.meta) {
+      setFilter((f) => f + evt.name)
+      return
+    }
+
+    if (evt.name === "backspace") {
+      setFilter((f) => f.slice(0, -1))
+      return
+    }
+  })
+
+  const maxHeight = Math.floor(dimensions().height * 0.6)
+
+  return (
+    <box flexDirection="column" padding={1}>
+      {/* Search input */}
+      <box marginBottom={1}>
+        <text fg={theme.textMuted}>
+          {"> "}
+        </text>
+        <text fg={theme.text}>
+          {filter() || "Type to search commands..."}
+        </text>
+      </box>
+
+      {/* Command list */}
+      <box flexDirection="column" maxHeight={maxHeight}>
+        <For each={filteredOptions().slice(0, 10)}>
+          {(option, index) => (
+            <box
+              backgroundColor={index() === selectedIndex() ? theme.primary : undefined}
+              padding={1}
+            >
+              <box flexDirection="column" flexGrow={1}>
+                <box flexDirection="row" justifyContent="space-between">
+                  <text
+                    fg={index() === selectedIndex() ? theme.selectedListItemText : theme.text}
+                    attributes={index() === selectedIndex() ? TextAttributes.BOLD : undefined}
+                  >
+                    {option.title}
+                  </text>
+                  <Show when={option.footer}>
+                    <text fg={theme.textMuted}>{option.footer}</text>
+                  </Show>
+                </box>
+                <Show when={option.description}>
+                  <text fg={theme.textMuted}>{option.description}</text>
+                </Show>
+              </box>
+            </box>
+          )}
+        </For>
+        <Show when={filteredOptions().length === 0}>
+          <text fg={theme.textMuted} style={{ padding: 1 }}>
+            No commands found
+          </text>
+        </Show>
+      </box>
+    </box>
+  )
+}
--- a/src/ui/dialog.tsx
+++ b/src/ui/dialog.tsx
@@ -0,0 +1,224 @@
+import { useKeyboard, useRenderer, useTerminalDimensions } from "@opentui/solid"
+import { batch, createContext, Show, useContext, type JSX, type ParentProps } from "solid-js"
+import { useTheme } from "../context/ThemeContext"
+import { RGBA, Renderable } from "@opentui/core"
+import { createStore } from "solid-js/store"
+import { Clipboard } from "../utils/clipboard"
+import { useToast } from "./toast"
+import { emit } from "../utils/event-bus"
+
+export type DialogSize = "medium" | "large"
+
+/**
+ * Dialog component that renders a modal overlay with content.
+ */
+export function Dialog(
+  props: ParentProps<{
+    size?: DialogSize
+    onClose: () => void
+  }>,
+) {
+  const dimensions = useTerminalDimensions()
+  const { theme } = useTheme()
+  const renderer = useRenderer()
+
+  return (
+    <box
+      onMouseUp={async () => {
+        if (renderer.getSelection()) return
+        props.onClose?.()
+      }}
+      width={dimensions().width}
+      height={dimensions().height}
+      alignItems="center"
+      position="absolute"
+      paddingTop={Math.floor(dimensions().height / 4)}
+      left={0}
+      top={0}
+      backgroundColor={RGBA.fromInts(0, 0, 0, 150)}
+    >
+      <box
+        onMouseUp={async (e) => {
+          if (renderer.getSelection()) return
+          e.stopPropagation()
+        }}
+        width={props.size === "large" ? 80 : 60}
+        maxWidth={dimensions().width - 2}
+        backgroundColor={theme.backgroundPanel}
+        paddingTop={1}
+      >
+        {props.children}
+      </box>
+    </box>
+  )
+}
+
+type DialogStackItem = {
+  element: JSX.Element
+  onClose?: () => void
+}
+
+function init() {
+  const [store, setStore] = createStore({
+    stack: [] as DialogStackItem[],
+    size: "medium" as DialogSize,
+  })
+
+  const renderer = useRenderer()
+  let focus: Renderable | null = null
+
+  function refocus() {
+    setTimeout(() => {
+      if (!focus) return
+      if (focus.isDestroyed) return
+      function find(item: Renderable): boolean {
+        for (const child of item.getChildren()) {
+          if (child === focus) return true
+          if (find(child)) return true
+        }
+        return false
+      }
+      const found = find(renderer.root)
+      if (!found) return
+      focus.focus()
+    }, 1)
+  }
+
+  useKeyboard((evt) => {
+    if (evt.name === "escape" && store.stack.length > 0) {
+      const current = store.stack.at(-1)!
+      current.onClose?.()
+      setStore("stack", store.stack.slice(0, -1))
+      evt.preventDefault()
+      evt.stopPropagation()
+      refocus()
+      emit("dialog.close", {})
+    }
+  })
+
+  return {
+    /**
+     * Clear all dialogs from the stack.
+     */
+    clear() {
+      for (const item of store.stack) {
+        if (item.onClose) item.onClose()
+      }
+      batch(() => {
+        setStore("size", "medium")
+        setStore("stack", [])
+      })
+      refocus()
+      emit("dialog.close", {})
+    },
+
+    /**
+     * Replace all dialogs with a new one.
+     */
+    replace(input: JSX.Element | (() => JSX.Element), onClose?: () => void) {
+      if (store.stack.length === 0) {
+        focus = renderer.currentFocusedRenderable
+        focus?.blur()
+      }
+      for (const item of store.stack) {
+        if (item.onClose) item.onClose()
+      }
+      const element = typeof input === "function" ? input() : input
+      setStore("size", "medium")
+      setStore("stack", [{ element, onClose }])
+      emit("dialog.open", { dialogId: "dialog" })
+    },
+
+    /**
+     * Push a new dialog onto the stack.
+     */
+    push(input: JSX.Element | (() => JSX.Element), onClose?: () => void) {
+      if (store.stack.length === 0) {
+        focus = renderer.currentFocusedRenderable
+        focus?.blur()
+      }
+      const element = typeof input === "function" ? input() : input
+      setStore("stack", [...store.stack, { element, onClose }])
+      emit("dialog.open", { dialogId: "dialog" })
+    },
+
+    /**
+     * Pop the top dialog from the stack.
+     */
+    pop() {
+      if (store.stack.length === 0) return
+      const current = store.stack.at(-1)!
+      current.onClose?.()
+      setStore("stack", store.stack.slice(0, -1))
+      if (store.stack.length === 0) {
+        refocus()
+      }
+      emit("dialog.close", {})
+    },
+
+    get stack() {
+      return store.stack
+    },
+
+    get size() {
+      return store.size
+    },
+
+    setSize(size: DialogSize) {
+      setStore("size", size)
+    },
+
+    get isOpen() {
+      return store.stack.length > 0
+    },
+  }
+}
+
+export type DialogContext = ReturnType<typeof init>
+
+const ctx = createContext<DialogContext>()
+
+/**
+ * DialogProvider wraps the application and provides dialog functionality.
+ * Also handles clipboard copy on text selection within dialogs.
+ */
+export function DialogProvider(props: ParentProps) {
+  const value = init()
+  const renderer = useRenderer()
+  const toast = useToast()
+
+  return (
+    <ctx.Provider value={value}>
+      {props.children}
+      <box
+        position="absolute"
+        onMouseUp={async () => {
+          const text = renderer.getSelection()?.getSelectedText()
+          if (text && text.length > 0) {
+            await Clipboard.copy(text)
+              .then(() => toast.show({ message: "Copied to clipboard", variant: "info" }))
+              .catch(toast.error)
+            renderer.clearSelection()
+          }
+        }}
+      >
+        <Show when={value.stack.length > 0}>
+          <Dialog onClose={() => value.clear()} size={value.size}>
+            {value.stack.at(-1)!.element}
+          </Dialog>
+        </Show>
+      </box>
+    </ctx.Provider>
+  )
+}
+
+/**
+ * Hook to access the dialog context.
+ */
+export function useDialog() {
+  const value = useContext(ctx)
+  if (!value) {
+    throw new Error("useDialog must be used within a DialogProvider")
+  }
+  return value
+}
--- a/src/ui/toast.tsx
+++ b/src/ui/toast.tsx
@@ -0,0 +1,153 @@
+import { createContext, useContext, type ParentProps, Show } from "solid-js"
+import { createStore } from "solid-js/store"
+import { useTheme } from "../context/ThemeContext"
+import { useTerminalDimensions } from "@opentui/solid"
+import { TextAttributes } from "@opentui/core"
+import { emit } from "../utils/event-bus"
+
+export type ToastVariant = "info" | "success" | "warning" | "error"
+
+export type ToastOptions = {
+  title?: string
+  message: string
+  variant: ToastVariant
+  duration?: number
+}
+
+const DEFAULT_DURATION = 5000
+
+/**
+ * Toast component that displays at the top-right of the screen.
+ * NOTE: This component must be rendered INSIDE ThemeProvider since it uses useTheme().
+ * The ToastProvider itself can be placed outside ThemeProvider if needed.
+ */
+export function Toast() {
+  const toast = useToast()
+  const { theme } = useTheme()
+  const dimensions = useTerminalDimensions()
+
+  const getVariantColor = (variant: ToastVariant) => {
+    switch (variant) {
+      case "success":
+        return theme.success
+      case "warning":
+        return theme.warning
+      case "error":
+        return theme.error
+      case "info":
+      default:
+        return theme.info
+    }
+  }
+
+  return (
+    <Show when={toast.currentToast}>
+      {(current) => (
+        <box
+          position="absolute"
+          justifyContent="center"
+          alignItems="flex-start"
+          top={2}
+          right={2}
+          maxWidth={Math.min(60, dimensions().width - 6)}
+          paddingLeft={2}
+          paddingRight={2}
+          paddingTop={1}
+          paddingBottom={1}
+          backgroundColor={theme.backgroundPanel}
+          borderColor={getVariantColor(current().variant)}
+          border={["left", "right"]}
+        >
+          <box flexDirection="column">
+            <Show when={current().title}>
+              <text attributes={TextAttributes.BOLD} style={{ marginBottom: 1 }} fg={theme.text}>
+                {current().title}
+              </text>
+            </Show>
+            <text fg={theme.text} wrapMode="word" width="100%">
+              {current().message}
+            </text>
+          </box>
+        </box>
+      )}
+    </Show>
+  )
+}
+
+function init() {
+  const [store, setStore] = createStore({
+    currentToast: null as ToastOptions | null,
+  })
+
+  let timeoutHandle: NodeJS.Timeout | null = null
+
+  const toast = {
+    show(options: ToastOptions) {
+      const duration = options.duration ?? DEFAULT_DURATION
+      setStore("currentToast", {
+        title: options.title,
+        message: options.message,
+        variant: options.variant,
+      })
+
+      // Emit event for other listeners
+      emit("toast.show", options)
+
+      if (timeoutHandle) clearTimeout(timeoutHandle)
+      timeoutHandle = setTimeout(() => {
+        setStore("currentToast", null)
+      }, duration)
+    },
+    error: (err: unknown) => {
+      if (err instanceof Error) {
+        return toast.show({
+          variant: "error",
+          message: err.message,
+        })
+      }
+      toast.show({
+        variant: "error",
+        message: "An unknown error has occurred",
+      })
+    },
+    info: (message: string, title?: string) => {
+      toast.show({ variant: "info", message, title })
+    },
+    success: (message: string, title?: string) => {
+      toast.show({ variant: "success", message, title })
+    },
+    warning: (message: string, title?: string) => {
+      toast.show({ variant: "warning", message, title })
+    },
+    clear: () => {
+      if (timeoutHandle) clearTimeout(timeoutHandle)
+      setStore("currentToast", null)
+    },
+    get currentToast(): ToastOptions | null {
+      return store.currentToast
+    },
+  }
+  return toast
+}
+
+export type ToastContext = ReturnType<typeof init>
+
+const ctx = createContext<ToastContext>()
+
+/**
+ * ToastProvider provides toast functionality.
+ * NOTE: The Toast UI component is NOT rendered here - you must render <Toast /> 
+ * separately inside your component tree, after ThemeProvider.
+ */
+export function ToastProvider(props: ParentProps) {
+  const value = init()
+  return <ctx.Provider value={value}>{props.children}</ctx.Provider>
+}
+
+export function useToast() {
+  const value = useContext(ctx)
+  if (!value) {
+    throw new Error("useToast must be used within a ToastProvider")
+  }
+  return value
+}
--- a/src/utils/clipboard.ts
+++ b/src/utils/clipboard.ts
@@ -0,0 +1,221 @@
+import { $ } from "bun"
+import { platform, release } from "os"
+import { tmpdir } from "os"
+import path from "path"
+
+/**
+ * Writes text to clipboard via OSC 52 escape sequence.
+ * This allows clipboard operations to work over SSH by having
+ * the terminal emulator handle the clipboard locally.
+ */
+function writeOsc52(text: string): void {
+  if (!process.stdout.isTTY) return
+  const base64 = Buffer.from(text).toString("base64")
+  const osc52 = `\x1b]52;c;${base64}\x07`
+  const passthrough = process.env["TMUX"] || process.env["STY"]
+  const sequence = passthrough ? `\x1bPtmux;\x1b${osc52}\x1b\\` : osc52
+  process.stdout.write(sequence)
+}
+
+/**
+ * Lazy initialization for clipboard copy method.
+ * Detects the best clipboard method for the current platform.
+ */
+function createLazy<T>(factory: () => T): () => T {
+  let value: T | undefined
+  return () => {
+    if (value === undefined) {
+      value = factory()
+    }
+    return value
+  }
+}
+
+export namespace Clipboard {
+  export interface Content {
+    data: string
+    mime: string
+  }
+
+  /**
+   * Read content from the clipboard.
+   * Supports text and image (PNG) content on macOS, Windows, and Linux.
+   */
+  export async function read(): Promise<Content | undefined> {
+    const os = platform()
+
+    // macOS: Try to read PNG image first
+    if (os === "darwin") {
+      const tmpfile = path.join(tmpdir(), "podtui-clipboard.png")
+      try {
+        await $`osascript -e 'set imageData to the clipboard as "PNGf"' -e 'set fileRef to open for access POSIX file "${tmpfile}" with write permission' -e 'set eof fileRef to 0' -e 'write imageData to fileRef' -e 'close access fileRef'`
+          .nothrow()
+          .quiet()
+        const file = Bun.file(tmpfile)
+        const buffer = await file.arrayBuffer()
+        if (buffer.byteLength > 0) {
+          return { data: Buffer.from(buffer).toString("base64"), mime: "image/png" }
+        }
+      } catch {
+        // Ignore errors, fall through to text
+      } finally {
+        await $`rm -f "${tmpfile}"`.nothrow().quiet()
+      }
+    }
+
+    // Windows/WSL: Try to read PNG image
+    if (os === "win32" || release().includes("WSL")) {
+      const script =
+        "Add-Type -AssemblyName System.Windows.Forms; $img = [System.Windows.Forms.Clipboard]::GetImage(); if ($img) { $ms = New-Object System.IO.MemoryStream; $img.Save($ms, [System.Drawing.Imaging.ImageFormat]::Png); [System.Convert]::ToBase64String($ms.ToArray()) }"
+      const base64 = await $`powershell.exe -NonInteractive -NoProfile -command "${script}"`.nothrow().text()
+      if (base64) {
+        const imageBuffer = Buffer.from(base64.trim(), "base64")
+        if (imageBuffer.length > 0) {
+          return { data: imageBuffer.toString("base64"), mime: "image/png" }
+        }
+      }
+    }
+
+    // Linux: Try Wayland or X11
+    if (os === "linux") {
+      // Try Wayland first
+      const wayland = await $`wl-paste -t image/png`.nothrow().arrayBuffer()
+      if (wayland && wayland.byteLength > 0) {
+        return { data: Buffer.from(wayland).toString("base64"), mime: "image/png" }
+      }
+      // Try X11
+      const x11 = await $`xclip -selection clipboard -t image/png -o`.nothrow().arrayBuffer()
+      if (x11 && x11.byteLength > 0) {
+        return { data: Buffer.from(x11).toString("base64"), mime: "image/png" }
+      }
+    }
+
+    // Fall back to reading text
+    try {
+      const text = await readText()
+      if (text) {
+        return { data: text, mime: "text/plain" }
+      }
+    } catch {
+      // Ignore errors
+    }
+
+    return undefined
+  }
+
+  /**
+   * Read text from the clipboard.
+   */
+  export async function readText(): Promise<string | undefined> {
+    const os = platform()
+
+    if (os === "darwin") {
+      const result = await $`pbpaste`.nothrow().text()
+      return result || undefined
+    }
+
+    if (os === "linux") {
+      // Try Wayland first
+      if (process.env["WAYLAND_DISPLAY"]) {
+        const result = await $`wl-paste`.nothrow().text()
+        if (result) return result
+      }
+      // Try X11
+      const result = await $`xclip -selection clipboard -o`.nothrow().text()
+      return result || undefined
+    }
+
+    if (os === "win32" || release().includes("WSL")) {
+      const result = await $`powershell.exe -NonInteractive -NoProfile -command "Get-Clipboard"`.nothrow().text()
+      return result?.trim() || undefined
+    }
+
+    return undefined
+  }
+
+  const getCopyMethod = createLazy(() => {
+    const os = platform()
+
+    if (os === "darwin" && Bun.which("osascript")) {
+      return async (text: string) => {
+        const escaped = text.replace(/\\/g, "\\\\").replace(/"/g, '\\"')
+        await $`osascript -e 'set the clipboard to "${escaped}"'`.nothrow().quiet()
+      }
+    }
+
+    if (os === "linux") {
+      if (process.env["WAYLAND_DISPLAY"] && Bun.which("wl-copy")) {
+        return async (text: string) => {
+          const proc = Bun.spawn(["wl-copy"], { stdin: "pipe", stdout: "ignore", stderr: "ignore" })
+          proc.stdin.write(text)
+          proc.stdin.end()
+          await proc.exited.catch(() => {})
+        }
+      }
+      if (Bun.which("xclip")) {
+        return async (text: string) => {
+          const proc = Bun.spawn(["xclip", "-selection", "clipboard"], {
+            stdin: "pipe",
+            stdout: "ignore",
+            stderr: "ignore",
+          })
+          proc.stdin.write(text)
+          proc.stdin.end()
+          await proc.exited.catch(() => {})
+        }
+      }
+      if (Bun.which("xsel")) {
+        return async (text: string) => {
+          const proc = Bun.spawn(["xsel", "--clipboard", "--input"], {
+            stdin: "pipe",
+            stdout: "ignore",
+            stderr: "ignore",
+          })
+          proc.stdin.write(text)
+          proc.stdin.end()
+          await proc.exited.catch(() => {})
+        }
+      }
+    }
+
+    if (os === "win32") {
+      return async (text: string) => {
+        // Pipe via stdin to avoid PowerShell string interpolation ($env:FOO, $(), etc.)
+        const proc = Bun.spawn(
+          [
+            "powershell.exe",
+            "-NonInteractive",
+            "-NoProfile",
+            "-Command",
+            "[Console]::InputEncoding = [System.Text.Encoding]::UTF8; Set-Clipboard -Value ([Console]::In.ReadToEnd())",
+          ],
+          {
+            stdin: "pipe",
+            stdout: "ignore",
+            stderr: "ignore",
+          },
+        )
+
+        proc.stdin.write(text)
+        proc.stdin.end()
+        await proc.exited.catch(() => {})
+      }
+    }
+
+    // Fallback: No native clipboard support
+    return async (_text: string) => {
+      console.warn("No clipboard support available on this platform")
+    }
+  })
+
+  /**
+   * Copy text to the clipboard.
+   * Uses OSC 52 for SSH/tmux support and native clipboard for local.
+   */
+  export async function copy(text: string): Promise<void> {
+    // Always try OSC 52 first for SSH/tmux support
+    writeOsc52(text)
+    // Then use native clipboard
+    await getCopyMethod()(text)
+  }
+}
--- a/src/utils/custom-themes.ts
+++ b/src/utils/custom-themes.ts
@@ -4,6 +4,9 @@ import type { ThemeJson } from "../types/theme-schema"
 import { THEME_JSON } from "../constants/themes"
 import { validateTheme } from "./theme-loader"

+// Files to exclude from theme loading (not actual themes)
+const EXCLUDED_FILES = new Set(["schema", "schema.json"])
+
 export async function getCustomThemes() {
  const home = process.env.HOME ?? ""
  if (!home) return {}
@@ -22,6 +25,10 @@ export async function getCustomThemes() {
  const glob = new Bun.Glob("*.json")
  for await (const item of glob.scan({ absolute: true, followSymlinks: true, cwd: dir })) {
    const name = path.basename(item, ".json")
+    // Skip non-theme files
+    if (EXCLUDED_FILES.has(name) || EXCLUDED_FILES.has(path.basename(item))) {
+      continue
+    }
    const json = (await Bun.file(item).json()) as ThemeJson
    validateTheme(json, item)
    result[name] = json
--- a/src/utils/event-bus.ts
+++ b/src/utils/event-bus.ts
@@ -0,0 +1,136 @@
+/**
+ * Simple event bus for inter-component communication.
+ *
+ * This provides a decoupled way for components to communicate without
+ * direct dependencies. Components can publish events and subscribe to
+ * events they're interested in.
+ *
+ * Usage:
+ * ```tsx
+ * // Subscribe to events
+ * const unsub = EventBus.on("theme.changed", (data) => {
+ *   console.log("Theme changed to:", data.theme)
+ * })
+ *
+ * // Publish events
+ * EventBus.emit("theme.changed", { theme: "dark" })
+ *
+ * // Cleanup
+ * unsub()
+ * ```
+ */
+
+type EventHandler<T = unknown> = (data: T) => void
+
+// Export EventHandler type for external use
+export type { EventHandler }
+
+interface EventBusInstance {
+  on<T = unknown>(event: string, handler: EventHandler<T>): () => void
+  once<T = unknown>(event: string, handler: EventHandler<T>): () => void
+  off<T = unknown>(event: string, handler: EventHandler<T>): void
+  emit<T = unknown>(event: string, data: T): void
+  clear(): void
+}
+
+function createEventBus(): EventBusInstance {
+  const handlers = new Map<string, Set<EventHandler>>()
+
+  return {
+    on<T = unknown>(event: string, handler: EventHandler<T>): () => void {
+      if (!handlers.has(event)) {
+        handlers.set(event, new Set())
+      }
+      handlers.get(event)!.add(handler as EventHandler)
+
+      // Return unsubscribe function
+      return () => {
+        this.off(event, handler)
+      }
+    },
+
+    once<T = unknown>(event: string, handler: EventHandler<T>): () => void {
+      const wrappedHandler: EventHandler<T> = (data) => {
+        this.off(event, wrappedHandler)
+        handler(data)
+      }
+      return this.on(event, wrappedHandler)
+    },
+
+    off<T = unknown>(event: string, handler: EventHandler<T>): void {
+      const eventHandlers = handlers.get(event)
+      if (eventHandlers) {
+        eventHandlers.delete(handler as EventHandler)
+        if (eventHandlers.size === 0) {
+          handlers.delete(event)
+        }
+      }
+    },
+
+    emit<T = unknown>(event: string, data: T): void {
+      const eventHandlers = handlers.get(event)
+      if (eventHandlers) {
+        for (const handler of eventHandlers) {
+          try {
+            handler(data)
+          } catch (error) {
+            console.error(`Error in event handler for "${event}":`, error)
+          }
+        }
+      }
+    },
+
+    clear(): void {
+      handlers.clear()
+    },
+  }
+}
+
+// Singleton event bus instance
+export const EventBus = createEventBus()
+
+// Common event types for the application
+export type AppEvents = {
+  "theme.changed": { theme: string; mode: "dark" | "light" }
+  "theme.mode.changed": { mode: "dark" | "light" }
+  "theme.reload": {}
+  "navigation.tab.changed": { tab: string; previousTab?: string }
+  "navigation.layer.changed": { depth: number; previousDepth: number }
+  "feed.subscribed": { feedId: string; feedUrl: string }
+  "feed.unsubscribed": { feedId: string }
+  "player.play": { episodeId: string }
+  "player.pause": { episodeId: string }
+  "player.stop": {}
+  "auth.login": { userId: string }
+  "auth.logout": {}
+  "toast.show": { message: string; variant: "info" | "success" | "warning" | "error"; title?: string; duration?: number }
+  "dialog.open": { dialogId: string }
+  "dialog.close": { dialogId?: string }
+  "command.execute": { command: string; args?: unknown }
+}
+
+// Type-safe emit and on functions
+export function emit<K extends keyof AppEvents>(event: K, data: AppEvents[K]): void {
+  EventBus.emit(event, data)
+}
+
+export function on<K extends keyof AppEvents>(
+  event: K,
+  handler: EventHandler<AppEvents[K]>
+): () => void {
+  return EventBus.on(event, handler)
+}
+
+export function once<K extends keyof AppEvents>(
+  event: K,
+  handler: EventHandler<AppEvents[K]>
+): () => void {
+  return EventBus.once(event, handler)
+}
+
+export function off<K extends keyof AppEvents>(
+  event: K,
+  handler: EventHandler<AppEvents[K]>
+): void {
+  EventBus.off(event, handler)
+}
--- a/src/utils/keybind.ts
+++ b/src/utils/keybind.ts
@@ -0,0 +1,187 @@
+import type { ParsedKey } from "@opentui/core"
+
+/**
+ * Keyboard shortcut parsing and matching utilities.
+ *
+ * Supports key combinations like:
+ * - "ctrl+c" - Control + c
+ * - "alt+x" - Alt + x
+ * - "shift+enter" - Shift + Enter
+ * - "<leader>n" - Leader key followed by n
+ * - "ctrl+shift+p" - Control + Shift + p
+ */
+
+export namespace Keybind {
+  export interface Info {
+    key: string
+    ctrl: boolean
+    alt: boolean
+    shift: boolean
+    meta: boolean
+    leader: boolean
+  }
+
+  /**
+   * Parse a keybind string into a structured Info object.
+   *
+   * Examples:
+   * - "ctrl+c" -> { key: "c", ctrl: true, ... }
+   * - "<leader>n" -> { key: "n", leader: true, ... }
+   * - "alt+shift+x" -> { key: "x", alt: true, shift: true, ... }
+   */
+  export function parse(input: string): Info[] {
+    if (!input) return []
+
+    // Handle multiple keybinds separated by comma or space
+    const parts = input.split(/[,\s]+/).filter(Boolean)
+
+    return parts.map((part) => {
+      const info: Info = {
+        key: "",
+        ctrl: false,
+        alt: false,
+        shift: false,
+        meta: false,
+        leader: false,
+      }
+
+      // Check for leader key prefix
+      if (part.startsWith("<leader>")) {
+        info.leader = true
+        part = part.substring(8) // Remove "<leader>"
+      }
+
+      // Split by + for modifiers
+      const tokens = part.toLowerCase().split("+")
+
+      for (const token of tokens) {
+        switch (token) {
+          case "ctrl":
+          case "control":
+            info.ctrl = true
+            break
+          case "alt":
+          case "option":
+            info.alt = true
+            break
+          case "shift":
+            info.shift = true
+            break
+          case "meta":
+          case "cmd":
+          case "command":
+          case "win":
+          case "super":
+            info.meta = true
+            break
+          default:
+            // The last non-modifier token is the key
+            info.key = token
+        }
+      }
+
+      return info
+    })
+  }
+
+  /**
+   * Convert a ParsedKey event to a Keybind.Info.
+   */
+  export function fromParsedKey(evt: ParsedKey, leader: boolean = false): Info {
+    // ParsedKey has ctrl, shift, meta but may not have alt directly
+    // We need to check what properties are available
+    const evtAny = evt as unknown as Record<string, unknown>
+    return {
+      key: evt.name?.toLowerCase() ?? "",
+      ctrl: evt.ctrl ?? false,
+      alt: (evtAny.alt as boolean) ?? false,
+      shift: evt.shift ?? false,
+      meta: evt.meta ?? false,
+      leader,
+    }
+  }
+
+  /**
+   * Check if a keybind matches a parsed key event.
+   */
+  export function match(keybind: Info, evt: Info): boolean {
+    return (
+      keybind.key === evt.key &&
+      keybind.ctrl === evt.ctrl &&
+      keybind.alt === evt.alt &&
+      keybind.shift === evt.shift &&
+      keybind.meta === evt.meta &&
+      keybind.leader === evt.leader
+    )
+  }
+
+  /**
+   * Convert a keybind Info to a display string.
+   */
+  export function toString(info: Info): string {
+    const parts: string[] = []
+
+    if (info.leader) parts.push("<leader>")
+    if (info.ctrl) parts.push("Ctrl")
+    if (info.alt) parts.push("Alt")
+    if (info.shift) parts.push("Shift")
+    if (info.meta) parts.push("Cmd")
+
+    if (info.key) {
+      // Capitalize special keys
+      const displayKey = info.key.length === 1 ? info.key.toUpperCase() : capitalize(info.key)
+      parts.push(displayKey)
+    }
+
+    return parts.join("+")
+  }
+
+  function capitalize(str: string): string {
+    return str.charAt(0).toUpperCase() + str.slice(1)
+  }
+}
+
+/**
+ * Default keybindings configuration.
+ */
+export const DEFAULT_KEYBINDS = {
+  // Leader key (space by default)
+  leader: "space",
+
+  // Navigation
+  tab_next: "tab",
+  tab_prev: "shift+tab",
+
+  // App commands
+  command_list: "ctrl+p",
+  help: "?",
+  quit: "ctrl+c",
+
+  // Session/content
+  session_new: "<leader>n",
+  session_list: "<leader>s",
+
+  // Theme
+  theme_list: "<leader>t",
+
+  // Player
+  player_play: "space",
+  player_pause: "space",
+  player_next: "n",
+  player_prev: "p",
+  player_seek_forward: "l",
+  player_seek_backward: "h",
+
+  // List navigation
+  list_up: "k",
+  list_down: "j",
+  list_top: "g",
+  list_bottom: "G",
+  list_select: "enter",
+
+  // Search
+  search_focus: "/",
+  search_clear: "escape",
+}
+
+export type KeybindsConfig = typeof DEFAULT_KEYBINDS
--- a/src/utils/theme-observer.ts
+++ b/src/utils/theme-observer.ts
@@ -0,0 +1,104 @@
+/**
+ * Theme observer utility for detecting and responding to theme changes.
+ *
+ * This module provides utilities for:
+ * - Listening to SIGUSR2 signals for theme reload
+ * - Emitting theme change events via the event bus
+ * - Tracking theme change state
+ */
+
+import { emit, on, off, type EventHandler } from "./event-bus"
+
+/**
+ * Subscribe to theme reload events.
+ * These are triggered by SIGUSR2 signals.
+ */
+export function onThemeReload(handler: EventHandler<{}>): () => void {
+  return on("theme.reload", handler)
+}
+
+/**
+ * Subscribe to theme changed events.
+ * These are triggered when the theme selection changes.
+ */
+export function onThemeChanged(
+  handler: EventHandler<{ theme: string; mode: "dark" | "light" }>
+): () => void {
+  return on("theme.changed", handler)
+}
+
+/**
+ * Subscribe to theme mode changed events.
+ * These are triggered when switching between dark/light mode.
+ */
+export function onThemeModeChanged(
+  handler: EventHandler<{ mode: "dark" | "light" }>
+): () => void {
+  return on("theme.mode.changed", handler)
+}
+
+/**
+ * Emit a theme reload event.
+ */
+export function emitThemeReload(): void {
+  emit("theme.reload", {})
+}
+
+/**
+ * Emit a theme changed event.
+ */
+export function emitThemeChanged(theme: string, mode: "dark" | "light"): void {
+  emit("theme.changed", { theme, mode })
+}
+
+/**
+ * Emit a theme mode changed event.
+ */
+export function emitThemeModeChanged(mode: "dark" | "light"): void {
+  emit("theme.mode.changed", { mode })
+}
+
+/**
+ * Setup SIGUSR2 signal handler for theme reload.
+ * This allows external tools to trigger a theme refresh by sending SIGUSR2 to the process.
+ *
+ * Usage: `kill -USR2 <pid>` to trigger a theme reload
+ *
+ * @param onReload - Callback to execute when SIGUSR2 is received
+ * @returns Cleanup function to remove the handler
+ */
+export function setupThemeSignalHandler(onReload: () => void): () => void {
+  const handler = () => {
+    emitThemeReload()
+    onReload()
+  }
+
+  process.on("SIGUSR2", handler)
+
+  return () => {
+    process.off("SIGUSR2", handler)
+  }
+}
+
+/**
+ * Create a debounced theme change handler to prevent rapid consecutive updates.
+ *
+ * @param handler - The handler to debounce
+ * @param delay - Delay in milliseconds (default: 100ms)
+ */
+export function createDebouncedThemeHandler<T>(
+  handler: (event: T) => void,
+  delay: number = 100
+): (event: T) => void {
+  let timeout: NodeJS.Timeout | null = null
+
+  return (event: T) => {
+    if (timeout) {
+      clearTimeout(timeout)
+    }
+    timeout = setTimeout(() => {
+      handler(event)
+      timeout = null
+    }, delay)
+  }
+}