feat(solid): expose terminal focus events via hooks (#811)

Closes #766

The renderer already emits `"focus"` and `"blur"` events when the
terminal window gains/loses focus (via DECSET 1004), but there's no way
to consume them from the SolidJS layer.

This adds three hooks following existing patterns:

- `onFocus(callback)` / `onBlur(callback)` — callback style, mirrors
`onResize`
- `useTerminalFocus()` → `Accessor<boolean>` — signal style, mirrors
`useTerminalDimensions`

Use case: opencode plugins need to know if the user is looking at the
terminal to decide whether to send OS notifications. Currently done via
osascript polling — this replaces it with the event-driven signal the
terminal already provides.

---------

Co-authored-by: Simon Klee <hello@simonklee.dk>

Author: nybble73

packages/core/src/renderer.ts

@@ -473,6 +473,7 @@ export class CliRenderer extends EventEmitter implements RenderContext {
   private _paletteDetectionPromise: Promise<TerminalColors> | null = null
   private _onDestroy?: () => void
   private _themeMode: ThemeMode | null = null
+  private _terminalFocusState: boolean | null = null
 
   private sequenceHandlers: ((sequence: string) => boolean)[] = []
   private prependedInputHandlers: ((sequence: string) => boolean)[] = []
@@ -1180,12 +1181,18 @@ export class CliRenderer extends EventEmitter implements RenderContext {
         this.lib.restoreTerminalModes(this.rendererPtr)
         this.shouldRestoreModesOnNextFocus = false
       }
-      this.emit(CliRenderEvents.FOCUS)
+      if (this._terminalFocusState !== true) {
+        this._terminalFocusState = true
+        this.emit(CliRenderEvents.FOCUS)
+      }
       return true
     }
     if (sequence === "\x1b[O") {
       this.shouldRestoreModesOnNextFocus = true
-      this.emit(CliRenderEvents.BLUR)
+      if (this._terminalFocusState !== false) {
+        this._terminalFocusState = false
+        this.emit(CliRenderEvents.BLUR)
+      }
       return true
     }
     return false

packages/core/src/tests/renderer.focus-restore.test.ts

@@ -130,6 +130,35 @@ describe("focus restore - terminal mode re-enable on focus-in", () => {
     expect(events).toEqual(["focus", "blur"])
   })
 
+  test("duplicate focus and blur sequences only emit transitions once", async () => {
+    const events: string[] = []
+
+    renderer.on("focus", () => {
+      events.push("focus")
+    })
+
+    renderer.on("blur", () => {
+      events.push("blur")
+    })
+
+    renderer.stdin.emit("data", Buffer.from("\x1b[O"))
+    clock.advance(15)
+    renderer.stdin.emit("data", Buffer.from("\x1b[O"))
+    clock.advance(15)
+
+    renderer.stdin.emit("data", Buffer.from("\x1b[I"))
+    clock.advance(15)
+    renderer.stdin.emit("data", Buffer.from("\x1b[I"))
+    clock.advance(15)
+
+    renderer.stdin.emit("data", Buffer.from("\x1b[O"))
+    clock.advance(15)
+    renderer.stdin.emit("data", Buffer.from("\x1b[O"))
+    clock.advance(15)
+
+    expect(events).toEqual(["blur", "focus", "blur"])
+  })
+
   test("focus events do not trigger keypress events", async () => {
     const keypresses: any[] = []
 

packages/solid/README.md

@@ -128,6 +128,8 @@ Returns the current component catalogue that powers JSX tag lookup.
 
 - `useRenderer()`
 - `onResize(callback)`
+- `onFocus(callback)`
+- `onBlur(callback)`
 - `useTerminalDimensions()`
 - `useKeyboard(handler, options?)`
 - `usePaste(handler)`

packages/solid/src/elements/hooks.ts

@@ -105,6 +105,30 @@ export const usePaste = (callback: (event: PasteEvent) => void) => {
  */
 export const useKeyHandler = useKeyboard
 
+export const onFocus = (callback: () => void) => {
+  const renderer = useRenderer()
+
+  onMount(() => {
+    renderer.on("focus", callback)
+  })
+
+  onCleanup(() => {
+    renderer.off("focus", callback)
+  })
+}
+
+export const onBlur = (callback: () => void) => {
+  const renderer = useRenderer()
+
+  onMount(() => {
+    renderer.on("blur", callback)
+  })
+
+  onCleanup(() => {
+    renderer.off("blur", callback)
+  })
+}
+
 export const useSelectionHandler = (callback: (selection: Selection) => void) => {
   const renderer = useRenderer()
 

packages/solid/tests/events.test.tsx

@@ -3,7 +3,7 @@ import { testRender } from "../index.js"
 import { createSignal } from "solid-js"
 import { decodePasteBytes } from "@opentui/core"
 import { createSpy } from "@opentui/core/testing"
-import { usePaste, useKeyboard } from "../src/elements/hooks.js"
+import { onBlur, onFocus, usePaste, useKeyboard } from "../src/elements/hooks.js"
 import type { PasteEvent } from "@opentui/core"
 
 let testSetup: Awaited<ReturnType<typeof testRender>>
@@ -348,6 +348,46 @@ describe("SolidJS Renderer Integration Tests", () => {
       expect(pastedText()).toBe("pasted content")
     })
 
+    it("should handle terminal focus hooks", async () => {
+      const focusSpy = createSpy()
+      const blurSpy = createSpy()
+      const [status, setStatus] = createSignal("idle")
+
+      const TestComponent = () => {
+        onFocus(() => {
+          focusSpy()
+          setStatus("focused")
+        })
+
+        onBlur(() => {
+          blurSpy()
+          setStatus("blurred")
+        })
+
+        return (
+          <box>
+            <text>Status: {status()}</text>
+          </box>
+        )
+      }
+
+      testSetup = await testRender(() => <TestComponent />, { width: 30, height: 5 })
+
+      testSetup.renderer.stdin.emit("data", Buffer.from("\x1b[I"))
+      await new Promise((resolve) => setTimeout(resolve, 10))
+
+      expect(focusSpy.callCount()).toBe(1)
+      expect(blurSpy.callCount()).toBe(0)
+      expect(status()).toBe("focused")
+
+      testSetup.renderer.stdin.emit("data", Buffer.from("\x1b[O"))
+      await new Promise((resolve) => setTimeout(resolve, 10))
+
+      expect(focusSpy.callCount()).toBe(1)
+      expect(blurSpy.callCount()).toBe(1)
+      expect(status()).toBe("blurred")
+    })
+
     it("should handle global preventDefault for keyboard events", async () => {
       const inputSpy = createSpy()
       const globalHandlerSpy = createSpy()

packages/web/src/content/docs/bindings/solid.mdx

@@ -228,6 +228,40 @@ const App = () => {
 }
 ```
 
+### `onFocus(callback)`
+
+Run side effects when the terminal window gains focus.
+
+```tsx
+import { onFocus } from "@opentui/solid"
+
+const App = () => {
+  onFocus(() => {
+    console.log("Terminal focused")
+  })
+
+  return <text>Switch away and back to trigger focus events</text>
+}
+```
+
+### `onBlur(callback)`
+
+Run side effects when the terminal window loses focus.
+
+```tsx
+import { onBlur } from "@opentui/solid"
+
+const App = () => {
+  onBlur(() => {
+    console.log("Terminal blurred")
+  })
+
+  return <text>Switch away and back to trigger blur events</text>
+}
+```
+
+These hooks listen for terminal focus-in/focus-out events when the terminal emulator supports them.
+
 ### `useTerminalDimensions()`
 
 Get reactive terminal dimensions (returns a Solid signal).
@@ -410,13 +444,13 @@ render(App)
 
 ## Differences from React bindings
 
-| Aspect             | Solid                                | React                                  |
-| ------------------ | ------------------------------------ | -------------------------------------- |
-| Render function    | `render(() => <App />)`              | `createRoot(renderer).render(<App />)` |
-| Component naming   | snake_case (`ascii_font`)            | kebab-case (`ascii-font`)              |
-| State              | `createSignal`                       | `useState`                             |
-| Effects            | `onMount`, `onCleanup`               | `useEffect`                            |
-| Resize hook        | `onResize(callback)`                 | `useOnResize(callback)`                |
-| Dimensions         | Returns signal: `dimensions().width` | Returns object: `dimensions.width`     |
-| Extra hooks        | `usePaste`, `useSelectionHandler`    | -                                      |
-| Special components | `Portal`, `Dynamic`                  | -                                      |
+| Aspect             | Solid                                                  | React                                  |
+| ------------------ | ------------------------------------------------------ | -------------------------------------- |
+| Render function    | `render(() => <App />)`                                | `createRoot(renderer).render(<App />)` |
+| Component naming   | snake_case (`ascii_font`)                              | kebab-case (`ascii-font`)              |
+| State              | `createSignal`                                         | `useState`                             |
+| Effects            | `onMount`, `onCleanup`                                 | `useEffect`                            |
+| Resize hook        | `onResize(callback)`                                   | `useOnResize(callback)`                |
+| Dimensions         | Returns signal: `dimensions().width`                   | Returns object: `dimensions.width`     |
+| Extra hooks        | `onFocus`, `onBlur`, `usePaste`, `useSelectionHandler` | -                                      |
+| Special components | `Portal`, `Dynamic`                                    | -                                      |