@effect-tui/react 0.15.2 → 0.16.0

package/src/internal/renderer/lifecycle/ProcessLifecycle.ts

@@ -0,0 +1,125 @@
+type ExitHandler = () => void
+type SignalHandler = (signal: NodeJS.Signals) => void
+type UncaughtHandler = (err: Error) => void
+type RejectionHandler = (reason: unknown) => void
+
+export interface ProcessHandlers {
+	onExit?: ExitHandler
+	onSignal?: SignalHandler
+	onUncaughtException?: UncaughtHandler
+	onUnhandledRejection?: RejectionHandler
+}
+
+const exitHandlers = new Set<ExitHandler>()
+const signalHandlers = new Set<SignalHandler>()
+const uncaughtHandlers = new Set<UncaughtHandler>()
+const rejectionHandlers = new Set<RejectionHandler>()
+
+let exitListenerAttached = false
+let signalListenersAttached = false
+let uncaughtListenerAttached = false
+let rejectionListenerAttached = false
+
+const dispatchExit = () => {
+	for (const handler of exitHandlers) handler()
+}
+
+const dispatchSignal = (signal: NodeJS.Signals) => {
+	for (const handler of signalHandlers) handler(signal)
+}
+
+const dispatchUncaught = (err: Error) => {
+	for (const handler of uncaughtHandlers) handler(err)
+}
+
+const dispatchRejection = (reason: unknown) => {
+	for (const handler of rejectionHandlers) handler(reason)
+}
+
+const ensureExitListener = () => {
+	if (exitListenerAttached) return
+	process.on("exit", dispatchExit)
+	exitListenerAttached = true
+}
+
+const ensureSignalListeners = () => {
+	if (signalListenersAttached) return
+	process.on("SIGINT", dispatchSignal)
+	process.on("SIGTERM", dispatchSignal)
+	signalListenersAttached = true
+}
+
+const ensureUncaughtListener = () => {
+	if (uncaughtListenerAttached) return
+	process.on("uncaughtException", dispatchUncaught)
+	uncaughtListenerAttached = true
+}
+
+const ensureRejectionListener = () => {
+	if (rejectionListenerAttached) return
+	process.on("unhandledRejection", dispatchRejection)
+	rejectionListenerAttached = true
+}
+
+const maybeDetachExitListener = () => {
+	if (!exitListenerAttached || exitHandlers.size > 0) return
+	process.off("exit", dispatchExit)
+	exitListenerAttached = false
+}
+
+const maybeDetachSignalListeners = () => {
+	if (!signalListenersAttached || signalHandlers.size > 0) return
+	process.off("SIGINT", dispatchSignal)
+	process.off("SIGTERM", dispatchSignal)
+	signalListenersAttached = false
+}
+
+const maybeDetachUncaughtListener = () => {
+	if (!uncaughtListenerAttached || uncaughtHandlers.size > 0) return
+	process.off("uncaughtException", dispatchUncaught)
+	uncaughtListenerAttached = false
+}
+
+const maybeDetachRejectionListener = () => {
+	if (!rejectionListenerAttached || rejectionHandlers.size > 0) return
+	process.off("unhandledRejection", dispatchRejection)
+	rejectionListenerAttached = false
+}
+
+export const registerProcessHandlers = (handlers: ProcessHandlers): (() => void) => {
+	if (handlers.onExit) {
+		exitHandlers.add(handlers.onExit)
+		ensureExitListener()
+	}
+	if (handlers.onSignal) {
+		signalHandlers.add(handlers.onSignal)
+		ensureSignalListeners()
+	}
+	if (handlers.onUncaughtException) {
+		uncaughtHandlers.add(handlers.onUncaughtException)
+		ensureUncaughtListener()
+	}
+	if (handlers.onUnhandledRejection) {
+		rejectionHandlers.add(handlers.onUnhandledRejection)
+		ensureRejectionListener()
+	}
+
+	return () => {
+		if (handlers.onExit) {
+			exitHandlers.delete(handlers.onExit)
+			maybeDetachExitListener()
+		}
+		if (handlers.onSignal) {
+			signalHandlers.delete(handlers.onSignal)
+			maybeDetachSignalListeners()
+		}
+		if (handlers.onUncaughtException) {
+			uncaughtHandlers.delete(handlers.onUncaughtException)
+			maybeDetachUncaughtListener()
+		}
+		if (handlers.onUnhandledRejection) {
+			rejectionHandlers.delete(handlers.onUnhandledRejection)
+			maybeDetachRejectionListener()
+		}
+	}
+}

package/src/internal/renderer/lifecycle/index.ts

@@ -0,0 +1,3 @@
+export { EventBus } from "./EventBus.js"
+export { registerProcessHandlers, type ProcessHandlers } from "./ProcessLifecycle.js"
+export { getRenderCache, type RenderCache } from "./RenderCache.js"

package/src/{renderer → internal/renderer}/modes/InlineRenderer.ts

@@ -163,12 +163,15 @@ export class InlineRenderer implements RendererMode {
 		return this._needsFullRerender
 	}
 
-	/** Clear the full rerender flag after handling */
+	/** Clear the full rerender flag after handling (keeps previousHeight for cursor tracking) */
 	clearFullRerenderFlag(): void {
 		this._needsFullRerender = false
-		this.previousHeight = 0
+		// DON'T reset previousHeight - we need it for cursor positioning in generateOutput.
+		// After clear+replay static, the cursor is at end of static content.
+		// generateOutput will use previousHeight to know where dynamic content should go.
 		this.previousStartRow = 0
 		this.printedWidths = []
+		this._forceFullOutput = true // Force full output to resync rendering
 	}
 
 	reset(): void {

package/src/{renderer → internal/renderer}/modes/RendererMode.ts

@@ -1,5 +1,5 @@
 import type { CellBuffer, Palette } from "@effect-tui/core"
-import type { TuiWriteStream } from "../../renderer-types.js"
+import type { TuiWriteStream } from "../types.js"
 
 /**
  * Context passed to render mode output generation.

package/src/{renderer → internal/renderer}/modes/StaticContentRenderer.ts

@@ -1,6 +1,6 @@
 import { CellBuffer, emitRowWithReset, type Palette, rowContentWidth } from "@effect-tui/core"
-import type { HostInstance } from "../../reconciler/types.js"
-import type { TuiWriteStream } from "../../renderer-types.js"
+import type { HostInstance } from "../../../reconciler/types.js"
+import type { TuiWriteStream } from "../types.js"
 
 /**
  * Renders static content to scrollback (inline mode only).
@@ -31,6 +31,9 @@ export class StaticContentRenderer {
 	 * Caller clears dynamic area first, then appends this output.
 	 */
 	render(staticNode: HostInstance, frameWidth: number): string {
+		// Pre-frame cache prep (optional)
+		staticNode.prepareFrame?.()
+
 		// Measure and layout static content
 		const staticSize = staticNode.measure(frameWidth, Number.MAX_SAFE_INTEGER)
 		staticNode.layout({ x: 0, y: 0, w: frameWidth, h: staticSize.h })

package/src/internal/renderer/terminal/KeyboardCapabilityProbe.ts

@@ -0,0 +1,91 @@
+import { ANSI } from "@effect-tui/core"
+import type { TuiWriteStream } from "../types.js"
+
+type ProbeOptions = {
+	stdout: TuiWriteStream
+	timeoutMs?: number
+	onResolved: (supportsKitty: boolean) => void
+}
+
+export type KeyboardCapabilityProbe = {
+	start(): void
+	handleInput(input: string): string
+}
+
+const kittyResponseRe = /^\x1b\[\?\d+(?:;\d+)?u$/
+
+export function createKeyboardCapabilityProbe(options: ProbeOptions): KeyboardCapabilityProbe {
+	const timeoutMs = options.timeoutMs ?? 150
+	let active = false
+	let resolved = false
+	let buffer = ""
+	let timer: ReturnType<typeof setTimeout> | null = null
+
+	const resolve = (supportsKitty: boolean) => {
+		if (resolved) return
+		resolved = true
+		active = false
+		buffer = ""
+		if (timer) {
+			clearTimeout(timer)
+			timer = null
+		}
+		options.onResolved(supportsKitty)
+	}
+
+	const handleCapabilitySequence = (sequence: string) => {
+		if (kittyResponseRe.test(sequence)) {
+			resolve(true)
+		} else if (sequence.includes("kitty")) {
+			resolve(true)
+		}
+	}
+
+	const handleInput = (input: string): string => {
+		if (!active) return input
+		let data = buffer + input
+		buffer = ""
+		let output = ""
+		let i = 0
+
+		while (i < data.length) {
+			if (data.startsWith("\x1b[?", i)) {
+				const end = data.indexOf("u", i + 3)
+				if (end === -1) {
+					buffer = data.slice(i)
+					break
+				}
+				const seq = data.slice(i, end + 1)
+				handleCapabilitySequence(seq)
+				i = end + 1
+				continue
+			}
+			if (data.startsWith("\x1bP>|", i)) {
+				const end = data.indexOf("\x1b\\", i + 4)
+				if (end === -1) {
+					buffer = data.slice(i)
+					break
+				}
+				const seq = data.slice(i, end + 2)
+				handleCapabilitySequence(seq)
+				i = end + 2
+				continue
+			}
+
+			output += data[i] as string
+			i += 1
+		}
+
+		return output
+	}
+
+	return {
+		start() {
+			if (resolved || active) return
+			active = true
+			options.stdout.write(ANSI.keyboard.query)
+			timer = setTimeout(() => resolve(false), timeoutMs)
+		},
+		handleInput,
+	}
+}

package/src/{renderer/lifecycle → internal/renderer/terminal}/TerminalSetup.ts

@@ -1,19 +1,11 @@
 import { ANSI, Terminal } from "@effect-tui/core"
-import type { TuiReadStream, TuiWriteStream } from "../../renderer-types.js"
+import type { TuiReadStream, TuiWriteStream } from "../types.js"
 
 export interface TerminalSetupConfig {
 	mode: "fullscreen" | "inline"
 	enablePaste: boolean
 	enableMouse: boolean
 	skipTerminalSetup: boolean
-	/**
-	 * Enable Kitty keyboard protocol for enhanced modifier detection.
-	 * When enabled, Ctrl+Shift+C can be distinguished from Ctrl+C.
-	 * Supported by: Kitty, iTerm2 3.5+, WezTerm, Ghostty, foot, Contour, rio.
-	 * Gracefully ignored by terminals that don't support it.
-	 * @default true
-	 */
-	enableKittyKeyboard?: boolean
 }
 
 /**
@@ -53,14 +45,6 @@ export class TerminalSetup {
 			this.stdout.write(ANSI.mouse.enable)
 		}
 
-		// Enable enhanced keyboard protocols for modifier detection
-		// This allows distinguishing Ctrl+Shift+C from Ctrl+C on supported terminals
-		// NOTE: Many terminals intercept Ctrl+Shift+C for their own copy function!
-		if (this.config.enableKittyKeyboard !== false) {
-			this.stdout.write(ANSI.keyboard.enable(1)) // Kitty protocol (flag 1 = disambiguate)
-			this.stdout.write(ANSI.modifyOtherKeys.enable) // xterm protocol (mode 2)
-		}
-
 		if (this.stdin.isTTY && this.stdin.setRawMode) {
 			this.stdin.setRawMode(true)
 			this.stdin.resume?.()
@@ -85,11 +69,9 @@ export class TerminalSetup {
 		// This ensures all sequences are flushed together before process exit
 		let output = ""
 
-		// Disable enhanced keyboard protocols first
-		if (this.config.enableKittyKeyboard !== false) {
-			output += ANSI.keyboard.disable
-			output += ANSI.modifyOtherKeys.disable
-		}
+		// Disable enhanced keyboard protocols first (safe to send regardless of support)
+		output += ANSI.keyboard.disable
+		output += ANSI.modifyOtherKeys.disable
 
 		if (this.config.enableMouse) {
 			output += ANSI.mouse.disable

package/src/internal/renderer/terminal/index.ts

@@ -0,0 +1,2 @@
+export { createKeyboardCapabilityProbe, type KeyboardCapabilityProbe } from "./KeyboardCapabilityProbe.js"
+export { TerminalSetup, type TerminalSetupConfig } from "./TerminalSetup.js"

package/src/internal/renderer/types.ts

@@ -0,0 +1,125 @@
+import type { KeyMsg, MouseMsg } from "@effect-tui/core"
+import type { HostContext, HostInstance } from "../../reconciler/types.js"
+
+export type PasteMsg = {
+	type: "paste"
+	text: string
+	/** Set by renderer to allow handlers to stop further propagation. */
+	defaultPrevented?: boolean
+	preventDefault?: () => void
+}
+
+/** Minimal write stream interface for renderer output */
+export interface TuiWriteStream {
+	write(s: string): void
+	columns: number
+	rows: number
+	on(event: string, cb: () => void): void
+	removeListener(event: string, cb: () => void): void
+}
+
+/** Minimal read stream interface for renderer input */
+export interface TuiReadStream {
+	isTTY?: boolean
+	setRawMode?(mode: boolean): void
+	resume?(): void
+	on(event: string, cb: (data: Buffer) => void): void
+	removeListener(event: string, cb: (data: Buffer) => void): void
+}
+
+export interface TuiRenderer {
+	/** Terminal width */
+	width: number
+	/** Terminal height */
+	height: number
+	/** Request a re-render */
+	requestRender(): void
+	/** Subscribe to per-frame stats (if enabled). */
+	onFrameStats?(handler: (stats: FrameStats) => void): () => void
+	/** Subscribe to keyboard events */
+	onKey(handler: (key: KeyMsg) => void): () => void
+	/** Subscribe to mouse events (clicks, scroll, etc.) */
+	onMouse(handler: (mouse: MouseMsg) => void): () => void
+	/** Subscribe to paste events (bracketed paste mode). */
+	onPaste?(handler: (paste: PasteMsg) => void): () => void
+	/** Subscribe to resize events */
+	onResize(handler: (width: number, height: number) => void): () => void
+	/** Stop the renderer */
+	stop(): void
+	/** Manually trigger one render frame (only in manualMode) */
+	renderNow(): void
+	/**
+	 * Get the current screen as ANSI string (for screenshots/debugging).
+	 * Returns the last rendered frame with all ANSI color codes intact.
+	 */
+	getScreenshot(): string
+	/** Dispatch a key event (for remote control) */
+	dispatchKey?(key: KeyMsg): void
+	/** Dispatch a paste event (for remote control) */
+	dispatchPaste?(text: string): void
+	/** Dispatch a resize event (for remote control) */
+	dispatchResize?(width: number, height: number): void
+}
+
+/** Internal renderer type with container reference */
+export interface TuiRendererInternal extends TuiRenderer {
+	_container: Container | null
+}
+
+export interface Container {
+	root: HostInstance | null
+	ctx: HostContext
+	/** @internal Static content root node (for Static component) */
+	staticRoot?: HostInstance | null
+	/** @internal Flag indicating static content needs flushing */
+	staticDirty?: boolean
+}
+
+export interface RendererOptions {
+	fps?: number
+	stdout?: NodeJS.WriteStream | TuiWriteStream
+	stdin?: NodeJS.ReadStream | TuiReadStream
+	/** Render mode: "fullscreen" uses alternate buffer, "inline" renders in-place */
+	mode?: "fullscreen" | "inline"
+	/** Exit the process on Ctrl+C unless preventDefault was called. Defaults to true. */
+	exitOnCtrlC?: boolean
+	/** Handle SIGINT/SIGTERM and process exit cleanup. Defaults to true. */
+	handleSignals?: boolean
+	/** Exit the process after handling SIGINT/SIGTERM. Defaults to true. */
+	exitOnSignal?: boolean
+	/** Override exit codes for signals. Defaults: SIGINT=130, SIGTERM=143. */
+	signalExitCodes?: Partial<Record<"SIGINT" | "SIGTERM", number>>
+	/** Enable diffed rendering (per-line). Defaults to true in runtime, false in manualMode (tests). */
+	diff?: boolean
+	/** Skip automatic render loop. Call renderNow() manually to render frames. */
+	manualMode?: boolean
+	/** Skip fullscreen/raw mode setup (for testing) */
+	skipTerminalSetup?: boolean
+	/** Enable bracketed paste (default true). */
+	enablePaste?: boolean
+	/** Enable mouse mode for scroll wheel events (default true in fullscreen). */
+	enableMouse?: boolean
+	/** Enable Kitty/xterm keyboard protocols for enhanced modifier detection (default true). */
+	enableKittyKeyboard?: boolean
+	/** Optional per-frame diagnostics hook. Called after each frame is written. */
+	debug?: {
+		onFrame?: (stats: FrameStats) => void
+	}
+}
+
+export interface FrameStats {
+	mode: "fullscreen" | "inline"
+	width: number
+	height: number
+	contentHeight: number
+	bytes: number
+	frameMs: number
+	phases: {
+		clear: number
+		layout: number
+		render: number
+		diffMs: number
+		write: number
+	}
+	timestamp: number
+}

package/src/renderer-context.ts

@@ -1,27 +1 @@
-import { createContext, useContext, useEffect, useState } from "react"
-import type { TuiRenderer } from "./renderer-types.js"
-
-// Context for accessing renderer in components
-export const RendererContext = createContext<TuiRenderer | null>(null)
-
-export function useRenderer(): TuiRenderer {
-	const renderer = useContext(RendererContext)
-	if (!renderer) {
-		throw new Error("useRenderer must be used within a TUI renderer")
-	}
-	return renderer
-}
-
-/** Hook that returns terminal size and re-renders on resize */
-export function useTerminalSize(): { width: number; height: number } {
-	const renderer = useRenderer()
-	const [size, setSize] = useState({ width: renderer.width, height: renderer.height })
-
-	useEffect(() => {
-		return renderer.onResize((width, height) => {
-			setSize({ width, height })
-		})
-	}, [renderer])
-
-	return size
-}
+export { RendererContext, useRenderer, useTerminalSize } from "./internal/renderer/context.js"

package/src/renderer-types.ts

@@ -1,123 +1,10 @@
-import type { KeyMsg, MouseMsg } from "@effect-tui/core"
-import type { HostContext, HostInstance } from "./reconciler/types.js"
-
-export type PasteMsg = {
-	type: "paste"
-	text: string
-	/** Set by renderer to allow handlers to stop further propagation. */
-	defaultPrevented?: boolean
-	preventDefault?: () => void
-}
-
-/** Minimal write stream interface for renderer output */
-export interface TuiWriteStream {
-	write(s: string): void
-	columns: number
-	rows: number
-	on(event: string, cb: () => void): void
-	removeListener(event: string, cb: () => void): void
-}
-
-/** Minimal read stream interface for renderer input */
-export interface TuiReadStream {
-	isTTY?: boolean
-	setRawMode?(mode: boolean): void
-	resume?(): void
-	on(event: string, cb: (data: Buffer) => void): void
-	removeListener(event: string, cb: (data: Buffer) => void): void
-}
-
-export interface TuiRenderer {
-	/** Terminal width */
-	width: number
-	/** Terminal height */
-	height: number
-	/** Request a re-render */
-	requestRender(): void
-	/** Subscribe to per-frame stats (if enabled). */
-	onFrameStats?(handler: (stats: FrameStats) => void): () => void
-	/** Subscribe to keyboard events */
-	onKey(handler: (key: KeyMsg) => void): () => void
-	/** Subscribe to mouse events (clicks, scroll, etc.) */
-	onMouse(handler: (mouse: MouseMsg) => void): () => void
-	/** Subscribe to paste events (bracketed paste mode). */
-	onPaste?(handler: (paste: PasteMsg) => void): () => void
-	/** Subscribe to resize events */
-	onResize(handler: (width: number, height: number) => void): () => void
-	/** Stop the renderer */
-	stop(): void
-	/** Manually trigger one render frame (only in manualMode) */
-	flush(): void
-	/**
-	 * Get the current screen as ANSI string (for screenshots/debugging).
-	 * Returns the last rendered frame with all ANSI color codes intact.
-	 */
-	getScreenshot(): string
-	/** Dispatch a key event (for remote control) */
-	dispatchKey?(key: KeyMsg): void
-	/** Dispatch a paste event (for remote control) */
-	dispatchPaste?(text: string): void
-	/** Dispatch a resize event (for remote control) */
-	dispatchResize?(width: number, height: number): void
-}
-
-/** Internal renderer type with container reference */
-export interface TuiRendererInternal extends TuiRenderer {
-	_container: Container | null
-}
-
-export interface Container {
-	root: HostInstance | null
-	ctx: HostContext
-	/** @internal Static content root node (for Static component) */
-	staticRoot?: HostInstance | null
-	/** @internal Flag indicating static content needs flushing */
-	staticDirty?: boolean
-}
-
-export interface RendererOptions {
-	fps?: number
-	stdout?: NodeJS.WriteStream | TuiWriteStream
-	stdin?: NodeJS.ReadStream | TuiReadStream
-	/** Render mode: "fullscreen" uses alternate buffer, "inline" renders in-place */
-	mode?: "fullscreen" | "inline"
-	/** Exit the process on Ctrl+C unless preventDefault was called. Defaults to true. */
-	exitOnCtrlC?: boolean
-	/** Handle SIGINT/SIGTERM and process exit cleanup. Defaults to true. */
-	handleSignals?: boolean
-	/** Exit the process after handling SIGINT/SIGTERM. Defaults to true. */
-	exitOnSignal?: boolean
-	/** Override exit codes for signals. Defaults: SIGINT=130, SIGTERM=143. */
-	signalExitCodes?: Partial<Record<"SIGINT" | "SIGTERM", number>>
-	/** Enable diffed rendering (per-line). Defaults to true in runtime, false in manualMode (tests). */
-	diff?: boolean
-	/** Skip automatic render loop. Call flush() manually to render frames. */
-	manualMode?: boolean
-	/** Skip fullscreen/raw mode setup (for testing) */
-	skipTerminalSetup?: boolean
-	/** Enable bracketed paste (default true). */
-	enablePaste?: boolean
-	/** Enable mouse mode for scroll wheel events (default true in fullscreen). */
-	enableMouse?: boolean
-	/** Optional per-frame diagnostics hook. Called after each frame is written. */
-	debug?: {
-		onFrame?: (stats: FrameStats) => void
-	}
-}
-
-export interface FrameStats {
-	mode: "fullscreen" | "inline"
-	width: number
-	height: number
-	contentHeight: number
-	bytes: number
-	frameMs: number
-	phases: {
-		clear: number
-		layout: number
-		render: number
-		diffAnsi: number
-		write: number
-	}
-	timestamp: number
-}
+export type {
+	Container,
+	FrameStats,
+	PasteMsg,
+	RendererOptions,
+	TuiReadStream,
+	TuiRenderer,
+	TuiRendererInternal,
+	TuiWriteStream,
+} from "./internal/renderer/types.js"