@effect-tui/react 0.15.2 → 0.16.0

package/src/internal/renderer/index.ts

@@ -0,0 +1,656 @@
+import { performance } from "node:perf_hooks"
+import { fileURLToPath } from "node:url"
+import { ANSI, bufferToString, type KeyMsg, type MouseMsg } from "@effect-tui/core"
+import React, { type ReactNode } from "react"
+import { createTerminalWriter, writeToTerminal } from "../../console/ConsoleCapture.js"
+import { DEFAULT_FPS } from "../../constants.js"
+import { requestExit } from "../../exit.js"
+import * as Prof from "../../profiler.js"
+import { flushSync, reconciler } from "../../reconciler/host-config.js"
+import type { HostContext } from "../../reconciler/types.js"
+// Extracted modules
+import { FrameBuilder, RendererState } from "./core/index.js"
+import { InputProcessor } from "./input/index.js"
+import { EventBus, getRenderCache, registerProcessHandlers } from "./lifecycle/index.js"
+import { createKeyboardCapabilityProbe, TerminalSetup } from "./terminal/index.js"
+import { FullscreenRenderer, InlineRenderer, StaticContentRenderer } from "./modes/index.js"
+import { RendererContext } from "./context.js"
+import { startDevRuntime } from "../dev/runtime.js"
+import type {
+	Container,
+	FrameStats,
+	PasteMsg,
+	RendererOptions,
+	TuiReadStream,
+	TuiRenderer,
+	TuiRendererInternal,
+	TuiWriteStream,
+} from "./types.js"
+
+export { RendererContext, useRenderer, useTerminalSize } from "./context.js"
+// Re-export types and context for backwards compatibility
+export type {
+	FrameStats,
+	PasteMsg,
+	RendererOptions,
+	TuiReadStream,
+	TuiRenderer,
+	TuiWriteStream,
+} from "./types.js"
+
+type HandledSignal = "SIGINT" | "SIGTERM"
+
+export function createRenderer(options?: RendererOptions): TuiRenderer {
+	const fps = options?.fps ?? DEFAULT_FPS
+	// Use custom stdout if provided, otherwise use process.stdout with bypassed capture
+	let stdout: TuiWriteStream
+	if (options?.stdout) {
+		// Use custom stdout as-is (e.g., for testing with MockStdout)
+		stdout = options.stdout
+	} else {
+		// Create a proxy that bypasses console capture for writes
+		// This ensures Effect.log etc. don't corrupt the TUI
+		const terminalWrite = createTerminalWriter()
+		stdout = new Proxy(process.stdout as TuiWriteStream, {
+			get(target, prop) {
+				if (prop === "write") {
+					return terminalWrite
+				}
+				const value = (target as unknown as Record<string | symbol, unknown>)[prop]
+				// Bind methods to preserve `this` context (critical for .on(), .removeListener(), etc.)
+				if (typeof value === "function") {
+					return value.bind(target)
+				}
+				return value
+			},
+		})
+	}
+	const stdin: TuiReadStream = options?.stdin ?? process.stdin
+	const mode = options?.mode ?? "fullscreen"
+	const exitOnCtrlC = options?.exitOnCtrlC ?? true
+	const handleSignals = options?.handleSignals ?? true
+	const exitOnSignal = options?.exitOnSignal ?? true
+	const signalExitCodes: Record<HandledSignal, number> = {
+		SIGINT: 130,
+		SIGTERM: 143,
+		...options?.signalExitCodes,
+	}
+	const manualMode = options?.manualMode ?? false
+	const enableDiff = options?.diff ?? !manualMode
+	const skipTerminalSetup = options?.skipTerminalSetup ?? false
+	const enablePaste = options?.enablePaste ?? true
+	const enableMouse = options?.enableMouse ?? mode === "fullscreen"
+	const enableKittyKeyboard = options?.enableKittyKeyboard
+	const debugHook = options?.debug?.onFrame
+
+	const keyboardProbe =
+		!skipTerminalSetup && enableKittyKeyboard !== false
+			? createKeyboardCapabilityProbe({
+					stdout,
+					onResolved: (supportsKitty) => {
+						if (supportsKitty) {
+							stdout.write(ANSI.modifyOtherKeys.disable)
+							stdout.write(ANSI.keyboard.enable(1))
+						} else {
+							stdout.write(ANSI.modifyOtherKeys.enable)
+						}
+					},
+				})
+			: null
+
+	// Initialize state
+	const state = new RendererState(stdout.columns || 80, stdout.rows || 24)
+	const events = new EventBus()
+	const frameBuilder = new FrameBuilder()
+
+	// Terminal setup/teardown
+	const terminal = new TerminalSetup(stdout, stdin, {
+		mode,
+		enablePaste,
+		enableMouse,
+		skipTerminalSetup,
+	})
+
+	// Render mode (fullscreen or inline)
+	const renderMode = mode === "fullscreen" ? new FullscreenRenderer() : new InlineRenderer()
+
+	// Static content renderer (inline mode only)
+	const staticRenderer = mode === "inline" ? new StaticContentRenderer(stdout, state.palette) : null
+
+	// Input processing
+	const inputProcessor = new InputProcessor({
+		exitOnCtrlC,
+		dispatchKey: (key) => {
+			events.dispatchKey(key)
+			return key.defaultPrevented ?? false
+		},
+		dispatchMouse: (mouse) => events.dispatchMouse(mouse),
+		dispatchPaste: (text) => events.dispatchPaste(text),
+		flushSync: (fn) => flushSync(fn) ?? (undefined as never),
+		onInputProcessed: () => {
+			if (!manualMode) renderFrame()
+		},
+		onQuit: () => {
+			// Clean up terminal state before exiting
+			renderer.stop()
+			requestExit(0)
+		},
+		filterInput: keyboardProbe ? (input) => keyboardProbe.handleInput(input) : undefined,
+	})
+
+	const handleInlineFullRerender = (): string => {
+		if (mode !== "inline" || !staticRenderer) return ""
+		const inlineMode = renderMode as InlineRenderer
+		if (!inlineMode.needsFullRerender()) return ""
+
+		let output = ""
+
+		// Clear screen + scrollback + cursor home
+		output += ANSI.screen.clear + ANSI.screen.clearScrollback + ANSI.cursor.home
+
+		// Replay all cached static content
+		const cachedStatic = staticRenderer.getCachedOutput()
+		if (cachedStatic) {
+			output += cachedStatic
+		}
+
+		// Reset state
+		inlineMode.clearFullRerenderFlag()
+		state.invalidateBuffers()
+
+		return output
+	}
+
+	const flushInlineStatic = (container: Container | null, frameWidth: number) => {
+		if (mode !== "inline" || !container?.staticDirty || !container.staticRoot || !staticRenderer) {
+			return ""
+		}
+
+		const inlineMode = renderMode as InlineRenderer
+		const prevHeight = inlineMode.getPreviousHeight()
+		let output = ""
+
+		// Step 1: Clear the dynamic area (move up + clear to end of screen)
+		if (prevHeight > 0) {
+			output += ANSI.cursor.up(prevHeight) + ANSI.cursor.startOfLine + ANSI.screen.clearToEnd
+		}
+
+		// Step 2: Append static content (cursor ends at bottom of static)
+		output += staticRenderer.render(container.staticRoot, frameWidth)
+
+		// Step 3: Reset previousHeight to 0 (we cleared dynamic, starting fresh)
+		inlineMode.reset()
+		inlineMode.forceFullOutputOnce() // Force full output to resync cursor tracking after static
+		state.invalidateBuffers()
+		container.staticDirty = false
+
+		return output
+	}
+
+	// The render frame logic
+	const renderFrame = () => {
+		const frameStart = Prof.startFrame()
+		const frameStartMs = performance.now()
+		// Flush any pending React updates before measuring/layout.
+		// Ensures resize-driven state (useTerminalSize) is reflected in the host tree.
+		flushSync(() => {})
+		const frameWidth = state.width
+		const frameHeight = state.height
+		let contentH = frameHeight
+
+		const container = (renderer as TuiRendererInternal)._container
+		const root = container?.root ?? null
+
+		// Must render if dirty OR if static content needs flushing
+		if ((!state.dirty && !container?.staticDirty) || !root) return
+		state.dirty = false
+
+		try {
+			// Handle full rerender on resize (Ink-style: clear everything + replay static)
+			const fullRerenderOutput = handleInlineFullRerender()
+
+			// Handle static content: clear dynamic area, append static, then fresh dynamic render
+			// Note: IL (insert lines) won't work here because inline mode uses relative positioning
+			// and IL would desync the screen state from our buffer tracking.
+			const staticOutput = flushInlineStatic(container ?? null, frameWidth)
+
+			// For inline mode, measure content unconstrained to handle overflow
+			let actualContentHeight = frameHeight
+			if (mode === "inline") {
+				const size = root.measure(frameWidth, Number.MAX_SAFE_INTEGER)
+				actualContentHeight = size.h
+			}
+
+			// Buffer height: content height for inline (to capture all content), terminal height for fullscreen
+			const bufferHeight = mode === "inline" ? Math.max(actualContentHeight, frameHeight) : frameHeight
+
+			// Ensure buffers exist
+			state.ensureBuffers(frameWidth, bufferHeight)
+			if (!state.nextBuffer) return
+
+			// Build frame (clear, layout, render)
+			const timings = frameBuilder.build(root, state.nextBuffer, state.palette, frameWidth, bufferHeight)
+
+			// Generate output
+			const t = Prof.startPhase()
+			const diffStartMs = performance.now()
+
+			const { output: modeOutput, contentHeight } = renderMode.generateOutput({
+				nextBuffer: state.nextBuffer,
+				prevBuffer: state.prevBuffer,
+				palette: state.palette,
+				frameWidth,
+				frameHeight,
+				contentHeight: actualContentHeight,
+				enableDiff,
+				stdout,
+			})
+
+			// Combine all output for single atomic write
+			// fullRerenderOutput (clear + replay static) goes BEFORE sync block
+			// Sync block wraps only the dynamic content to prevent tearing
+			const output =
+				fullRerenderOutput +
+				ANSI.sync.begin +
+				staticOutput +
+				modeOutput +
+				state.palette.sgr(0) +
+				ANSI.sync.end
+			contentH = contentHeight
+			const diffAnsiMs = performance.now() - diffStartMs
+			Prof.endPhase("diff+ansi", t)
+
+			// Write output (single atomic write prevents visual glitches)
+			const writeT = Prof.startPhase()
+			const writeStart = performance.now()
+			stdout.write(output)
+			const writeMs = performance.now() - writeStart
+			Prof.endPhase("write", writeT)
+
+			Prof.endFrame(frameStart)
+			const frameMs = performance.now() - frameStartMs
+
+			// Swap buffers
+			state.swapBuffers()
+
+			// Build stats
+			const stats: FrameStats = {
+				mode,
+				width: state.width,
+				height: state.height,
+				contentHeight: contentH,
+				bytes: Buffer.byteLength(output, "utf8"),
+				frameMs,
+				phases: {
+					clear: timings.clear,
+					layout: timings.layout,
+					render: timings.render,
+					diffMs: diffAnsiMs,
+					write: writeMs,
+				},
+				timestamp: performance.now(),
+			}
+
+			if (debugHook) debugHook(stats)
+			if (events.hasFrameHandlers) events.dispatchFrame(stats)
+		} catch (err) {
+			console.error("[effect-tui] Render error:", err)
+			state.markDirty()
+		}
+	}
+
+	const applyResize = (width: number, height: number, renderNow: boolean) => {
+		const prevWidth = state.lastWidth
+		renderMode.handleResize(width, height, prevWidth)
+		state.updateDimensions(width, height)
+		state.invalidateBuffers()
+		state.markDirty()
+		flushSync(() => {
+			events.dispatchResize(width, height)
+		})
+		if (renderNow) renderFrame()
+	}
+
+	let onExit: (() => void) | null = null
+	let onSignal: ((signal: NodeJS.Signals) => void) | null = null
+	let onUncaughtException: ((err: Error) => void) | null = null
+	let onUnhandledRejection: ((reason: unknown) => void) | null = null
+	let unregisterProcessHandlers: (() => void) | null = null
+
+	// Build renderer object
+	const renderer: TuiRenderer = {
+		get width() {
+			return state.width
+		},
+		get height() {
+			return state.height
+		},
+		requestRender() {
+			state.markDirty()
+		},
+		onKey: (handler: (key: KeyMsg) => void) => events.onKey(handler),
+		onMouse: (handler: (mouse: MouseMsg) => void) => events.onMouse(handler),
+		onPaste: (handler: (paste: PasteMsg) => void) => events.onPaste(handler),
+		onResize: (handler: (width: number, height: number) => void) => events.onResize(handler),
+		onFrameStats: (handler: (stats: FrameStats) => void) => events.onFrameStats(handler),
+		stop() {
+			state.running = false
+			if (unregisterProcessHandlers) {
+				unregisterProcessHandlers()
+				unregisterProcessHandlers = null
+				onExit = null
+				onSignal = null
+				onUncaughtException = null
+				onUnhandledRejection = null
+			}
+			if (state.loop) {
+				clearInterval(state.loop)
+				state.loop = null
+			}
+			if (state.inputHandler) {
+				stdin.removeListener("data", state.inputHandler)
+				state.inputHandler = null
+			}
+			if (state.resizeHandler) {
+				stdout.removeListener("resize", state.resizeHandler)
+				state.resizeHandler = null
+			}
+			events.clear()
+			terminal.teardown()
+		},
+		renderNow() {
+			renderFrame()
+		},
+		getScreenshot() {
+			// Return the previous buffer as ANSI string (it has the last rendered frame)
+			if (state.prevBuffer) {
+				return bufferToString(state.prevBuffer, state.palette, state.width, state.height)
+			}
+			return ""
+		},
+		dispatchKey(key: KeyMsg) {
+			events.dispatchKey(key)
+			if (!manualMode) renderFrame()
+		},
+		dispatchPaste(text: string) {
+			events.dispatchPaste(text)
+			if (!manualMode) renderFrame()
+		},
+		dispatchResize(width: number, height: number) {
+			applyResize(width, height, !manualMode)
+		},
+	}
+
+	// Terminal setup
+	terminal.setup()
+	keyboardProbe?.start()
+	if (!keyboardProbe && !skipTerminalSetup) {
+		stdout.write(ANSI.modifyOtherKeys.enable)
+	}
+
+	// Input handling
+	state.inputHandler = (data: Buffer) => inputProcessor.process(data)
+	stdin.on("data", state.inputHandler)
+
+	// Resize handling
+	state.resizeHandler = () => {
+		const newWidth = stdout.columns || 80
+		const newHeight = stdout.rows || 24
+		applyResize(newWidth, newHeight, false)
+	}
+	stdout.on("resize", state.resizeHandler)
+
+	// Render loop
+	if (!manualMode) {
+		const frameMs = 1000 / fps
+		state.loop = setInterval(() => {
+			if (!state.running) {
+				if (state.loop) clearInterval(state.loop)
+				terminal.teardown()
+				return
+			}
+			renderFrame()
+		}, frameMs)
+	}
+
+	// Process exit handlers - ensure terminal is restored on any exit
+	// These handlers are critical for proper cleanup when process.exit() is called
+	let cleanedUp = false
+	const cleanup = () => {
+		if (cleanedUp) return
+		cleanedUp = true
+		renderer.stop()
+	}
+
+	if (handleSignals) {
+		// Handle normal process exit (synchronous - runs before exit completes)
+		onExit = () => cleanup()
+
+		// Handle SIGINT (Ctrl+C from shell, not from TUI input) and SIGTERM
+		onSignal = (signal: NodeJS.Signals) => {
+			cleanup()
+			if (!exitOnSignal) return
+			const code = signalExitCodes[signal as HandledSignal] ?? 0
+			requestExit(code)
+		}
+
+		// Handle uncaught exceptions - ensure error is visible before exit
+		onUncaughtException = (err: Error) => {
+			cleanup()
+			// Write directly to terminal, bypassing console capture
+			writeToTerminal(`\n[effect-tui] Uncaught exception:\n${err.stack || err.message}\n`)
+			process.exit(1)
+		}
+
+		// Handle unhandled promise rejections
+		onUnhandledRejection = (reason: unknown) => {
+			cleanup()
+			const message = reason instanceof Error ? reason.stack || reason.message : String(reason)
+			writeToTerminal(`\n[effect-tui] Unhandled rejection:\n${message}\n`)
+			process.exit(1)
+		}
+
+		unregisterProcessHandlers = registerProcessHandlers({
+			onExit,
+			onSignal,
+			onUncaughtException,
+			onUnhandledRejection,
+		})
+	}
+
+	;(renderer as TuiRendererInternal)._container = null
+	return renderer
+}
+
+export interface Root {
+	render(element: ReactNode, sync?: boolean): void
+	unmount(): void
+}
+
+export function createRoot(renderer: TuiRenderer): Root {
+	const hostContext: HostContext = {
+		requestRender: () => renderer.requestRender(),
+		requestImmediateRender: () => renderer.renderNow(),
+	}
+
+	const container: Container = {
+		root: null,
+		ctx: hostContext,
+	}
+
+	const fiberRoot = reconciler.createContainer(
+		container,
+		0,
+		null,
+		false,
+		null,
+		"",
+		(err: Error) => console.error(err),
+		(err: Error) => console.error(err),
+		(err: Error) => console.error(err),
+		() => {},
+		null,
+	)
+
+	;(renderer as TuiRendererInternal)._container = container
+
+	return {
+		render(element: ReactNode, sync = false) {
+			const wrapped = React.createElement(RendererContext.Provider, { value: renderer }, element)
+			if (sync) {
+				flushSync(() => {
+					reconciler.updateContainer(wrapped, fiberRoot, null, null)
+				})
+				renderer.requestRender()
+			} else {
+				reconciler.updateContainer(wrapped, fiberRoot, null, () => {
+					renderer.requestRender()
+				})
+			}
+		},
+		unmount() {
+			reconciler.updateContainer(null, fiberRoot, null, () => {
+				renderer.stop()
+			})
+		},
+	}
+}
+
+// High-level convenience API (Ink-style)
+export interface RenderInstance {
+	renderer: TuiRenderer
+	root: Root
+	rerender(element: ReactNode): void
+	unmount(): void
+	waitUntilExit(): Promise<void>
+	/** Cleanly exit the application, restoring terminal state before process.exit() */
+	quit(code?: number): void
+}
+
+export type ImportMetaLike = {
+	url: string
+	main?: boolean
+}
+
+type RenderBaseOptions = {
+	/** Render mode: fullscreen (default) or inline. */
+	mode?: RendererOptions["mode"]
+}
+
+type RenderDevOptions = RenderBaseOptions & {
+	/** Enable dev runtime (HMR, console overlay, remote control). */
+	dev: true
+	/** Required in dev mode. */
+	importMeta: ImportMetaLike
+}
+
+type RenderRuntimeOptions = RenderBaseOptions & {
+	/** Dev mode disabled (default). */
+	dev?: false | undefined
+}
+
+export type RenderOptions = RenderDevOptions | RenderRuntimeOptions
+
+const stripQuery = (url: string): string => url.split("?")[0]
+
+const createRenderInstance = (
+	renderer: TuiRenderer,
+	root: Root,
+	element: ReactNode,
+	stop: () => void,
+	skipInitialRender = false,
+): RenderInstance => {
+	if (!skipInitialRender) {
+		root.render(element, true)
+	}
+
+	let resolved = false
+	let resolveExit: (() => void) | null = null
+	let unregisterExitHandler: (() => void) | null = null
+	const exitPromise = new Promise<void>((resolve) => {
+		resolveExit = () => {
+			if (resolved) return
+			resolved = true
+			resolve()
+		}
+	})
+
+	// Resolve the exit promise on process exit
+	// Note: Terminal cleanup is handled by createRenderer's exit handlers
+	const onExit = () => {
+		resolveExit?.()
+	}
+	unregisterExitHandler = registerProcessHandlers({ onExit })
+
+	const unmount = () => {
+		if (unregisterExitHandler) {
+			unregisterExitHandler()
+			unregisterExitHandler = null
+		}
+		if (!resolved) {
+			resolved = true
+			stop()
+			resolveExit?.()
+		}
+	}
+
+	const rerender = (next: ReactNode) => {
+		if (resolved) return
+		root.render(next)
+	}
+
+	// Clean quit function - stop() + process.exit()
+	// The createRenderer exit handler will also run, but it's idempotent
+	const quit = (code = 0) => {
+		stop()
+		requestExit(code)
+	}
+
+	return {
+		renderer,
+		root,
+		rerender,
+		unmount,
+		waitUntilExit: () => exitPromise,
+		quit,
+	}
+}
+
+export function render(element: ReactNode, options?: RenderOptions): RenderInstance {
+	if (options?.dev && !options.importMeta) {
+		throw new Error("[effect-tui] render(..., { dev: true, importMeta }) is required in dev mode")
+	}
+
+	if (!options?.dev) {
+		const renderer = createRenderer({ mode: options?.mode })
+		const root = createRoot(renderer)
+		return createRenderInstance(renderer, root, element, () => renderer.stop())
+	}
+
+	const importMeta = options.importMeta
+
+	const baseUrl = stripQuery(importMeta.url)
+	const cacheKey = `${baseUrl}::${options.mode ?? "fullscreen"}`
+	const renderCache = getRenderCache<RenderInstance>()
+	const cached = renderCache.get(cacheKey)
+	if (cached) return cached
+
+	const renderer = createRenderer({ mode: options.mode })
+	const root = createRoot(renderer)
+	const entryPath = fileURLToPath(new URL(baseUrl))
+
+	const devRuntime = startDevRuntime(entryPath, renderer, root, { mode: options.mode })
+
+	const instance = createRenderInstance(
+		renderer,
+		root,
+		element,
+		() => {
+			void devRuntime.stop()
+		},
+		true,
+	)
+
+	renderCache.set(cacheKey, instance)
+	return instance
+}

package/src/{renderer → internal/renderer}/input/InputProcessor.ts

@@ -1,5 +1,5 @@
 import { ANSI, decodeInput, type KeyMsg, type MouseMsg } from "@effect-tui/core"
-import { requestExit } from "../../exit.js"
+import { requestExit } from "../../../exit.js"
 
 export interface InputProcessorConfig {
 	exitOnCtrlC: boolean
@@ -9,6 +9,8 @@ export interface InputProcessorConfig {
 	flushSync: <T>(fn: () => T) => T
 	onInputProcessed: () => void
 	onQuit?: () => void // Called instead of process.exit() for proper cleanup
+	/** Optional filter to strip capability responses from raw input */
+	filterInput?: (input: string) => string
 }
 
 /**
@@ -28,6 +30,13 @@ export class InputProcessor {
 	process(data: Buffer): void {
 		let chunk = this.pendingInput + data.toString("utf8")
 		this.pendingInput = ""
+		if (this.config.filterInput) {
+			chunk = this.config.filterInput(chunk)
+		}
+		if (chunk.length === 0) {
+			this.config.onInputProcessed()
+			return
+		}
 
 		while (chunk.length > 0) {
 			if (this.pasteActive) {

package/src/{renderer → internal/renderer}/lifecycle/EventBus.ts

@@ -1,5 +1,5 @@
 import type { KeyMsg, MouseMsg } from "@effect-tui/core"
-import type { FrameStats, PasteMsg } from "../../renderer-types.js"
+import type { FrameStats, PasteMsg } from "../types.js"
 
 /**
  * Centralized event subscription management for the renderer.
@@ -97,4 +97,12 @@ export class EventBus {
 	get hasFrameHandlers(): boolean {
 		return this.frameHandlers.size > 0
 	}
+
+	clear(): void {
+		this.keyHandlers.clear()
+		this.mouseHandlers.clear()
+		this.pasteHandlers.clear()
+		this.resizeHandlers.clear()
+		this.frameHandlers.clear()
+	}
 }