@effect-tui/react 0.15.2 → 0.16.0

package/src/renderer.ts

@@ -1,619 +1 @@
-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 "./renderer/core/index.js"
-import { InputProcessor } from "./renderer/input/index.js"
-import { EventBus, getRenderCache, TerminalSetup } from "./renderer/lifecycle/index.js"
-import { FullscreenRenderer, InlineRenderer, StaticContentRenderer } from "./renderer/modes/index.js"
-import { RendererContext } from "./renderer-context.js"
-import { startDevRuntime, type DevOptions } from "./dev.js"
-import type {
-	Container,
-	FrameStats,
-	PasteMsg,
-	RendererOptions,
-	TuiReadStream,
-	TuiRenderer,
-	TuiRendererInternal,
-	TuiWriteStream,
-} from "./renderer-types.js"
-
-export { RendererContext, useRenderer, useTerminalSize } from "./renderer-context.js"
-// Re-export types and context for backwards compatibility
-export type {
-	FrameStats,
-	PasteMsg,
-	RendererOptions,
-	TuiReadStream,
-	TuiRenderer,
-	TuiWriteStream,
-} from "./renderer-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 debugHook = options?.debug?.onFrame
-
-	// 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)
-		},
-	})
-
-	const handleInlineFullRerender = () => {
-		if (mode !== "inline" || !staticRenderer) return
-		const inlineMode = renderMode as InlineRenderer
-		if (!inlineMode.needsFullRerender()) return
-
-		// Clear screen + scrollback + cursor home
-		stdout.write(ANSI.screen.clear + ANSI.screen.clearScrollback + ANSI.cursor.home)
-		// Replay all cached static content
-		const cachedStatic = staticRenderer.getCachedOutput()
-		if (cachedStatic) {
-			stdout.write(cachedStatic)
-		}
-
-		// Reset state
-		inlineMode.clearFullRerenderFlag()
-		state.invalidateBuffers()
-	}
-
-	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)
-			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 static + dynamic output for atomic write
-			// Wrap in synchronized output mode (DECSET 2026) to prevent tearing
-			// Terminals that don't support it will safely ignore these sequences
-			const output = 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,
-					diffAnsi: 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()
-		}
-	}
-
-	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
-
-	// 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 (onExit) {
-				process.off("exit", onExit)
-				onExit = null
-			}
-			if (onSignal) {
-				process.off("SIGINT", onSignal)
-				process.off("SIGTERM", onSignal)
-				onSignal = null
-			}
-			if (onUncaughtException) {
-				process.off("uncaughtException", onUncaughtException)
-				onUncaughtException = null
-			}
-			if (onUnhandledRejection) {
-				process.off("unhandledRejection", onUnhandledRejection)
-				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
-			}
-			terminal.teardown()
-		},
-		flush() {
-			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) {
-			renderMode.handleResize(width, height, state.lastWidth)
-			state.updateDimensions(width, height)
-			state.invalidateBuffers()
-			state.markDirty()
-			flushSync(() => {
-				events.dispatchResize(width, height)
-			})
-			if (!manualMode) renderFrame()
-		},
-	}
-
-	// Terminal setup
-	terminal.setup()
-
-	// 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
-
-		renderMode.handleResize(newWidth, newHeight, state.lastWidth)
-
-		state.updateDimensions(newWidth, newHeight)
-		state.invalidateBuffers()
-		state.markDirty()
-
-		flushSync(() => {
-			events.dispatchResize(newWidth, newHeight)
-		})
-	}
-	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()
-		process.on("exit", onExit)
-
-		// 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)
-		}
-		process.on("SIGINT", onSignal)
-		process.on("SIGTERM", onSignal)
-
-		// 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)
-		}
-		process.on("uncaughtException", onUncaughtException)
-
-		// 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)
-		}
-		process.on("unhandledRejection", 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.flush(),
-	}
-
-	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
-}
-
-export type RenderOptions = RendererOptions &
-	DevOptions & {
-		/** Enable dev runtime (HMR, console overlay, remote control). */
-		dev?: boolean
-		/** Required when passing options. */
-		importMeta: ImportMetaLike
-	}
-
-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
-	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?.()
-	}
-	process.once("exit", onExit)
-
-	const unmount = () => {
-		process.off("exit", onExit)
-		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 && !options.importMeta) {
-		throw new Error("[effect-tui] render(..., options) requires { importMeta: import.meta }")
-	}
-
-	if (!options?.dev) {
-		const renderer = createRenderer(options)
-		const root = createRoot(renderer)
-		return createRenderInstance(renderer, root, element, () => renderer.stop())
-	}
-
-	const importMeta = options.importMeta
-	if (!importMeta) {
-		throw new Error("[effect-tui] render(..., { dev: true, importMeta }) is required in dev mode")
-	}
-
-	const baseUrl = stripQuery(importMeta.url)
-	const renderCache = getRenderCache<RenderInstance>()
-	const cached = renderCache.get(baseUrl)
-	if (cached) return cached
-
-	const renderer = createRenderer(options)
-	const root = createRoot(renderer)
-	const entryPath = fileURLToPath(new URL(baseUrl))
-
-	const devRuntime = startDevRuntime(entryPath, renderer, root, options)
-
-	const instance = createRenderInstance(
-		renderer,
-		root,
-		element,
-		() => {
-			void devRuntime.stop()
-		},
-		true,
-	)
-
-	renderCache.set(baseUrl, instance)
-	return instance
-}
+export * from "./internal/renderer/index.js"

package/src/test/render-tui.ts

@@ -21,7 +21,7 @@ export interface RenderTUIResult {
 	/** Send a key event */
 	sendKey(key: KeyMsg): void
 	/** Trigger a render cycle and process React updates */
-	flush(): void
+	renderNow(): void
 	/** Unmount the component and stop the renderer */
 	unmount(): void
 	/** Access mock stdout for advanced assertions */
@@ -40,12 +40,12 @@ export interface RenderTUIResult {
  *
  * @example
  * ```ts
- * const { lastFrame, sendKey, flush, unmount } = renderTUI(<Counter />)
+ * const { lastFrame, sendKey, renderNow, unmount } = renderTUI(<Counter />)
  *
  * expect(lastFrame()).toContain("Count: 0")
  *
  * sendKey({ key: "up" })
- * flush()
+ * renderNow()
  *
  * expect(lastFrame()).toContain("Count: 1")
  *
@@ -84,9 +84,9 @@ export function renderTUI(element: ReactElement, options?: RenderTUIOptions): Re
 	flushPassiveEffects()
 
 	// Initial render
-	renderer.flush()
+	renderer.renderNow()
 
-	const flush = () => {
+	const renderNow = () => {
 		// Flush React updates synchronously
 		flushSync(() => {
 			bump?.()
@@ -95,7 +95,7 @@ export function renderTUI(element: ReactElement, options?: RenderTUIOptions): Re
 		// Clear buffer before re-render to get clean frame
 		stdout.clear()
 		renderer.requestRender()
-		renderer.flush()
+		renderer.renderNow()
 		// Flush updates scheduled during layout (e.g., viewport/content size callbacks)
 		flushSync(() => {
 			bump?.()
@@ -103,7 +103,7 @@ export function renderTUI(element: ReactElement, options?: RenderTUIOptions): Re
 		flushPassiveEffects()
 		stdout.clear()
 		renderer.requestRender()
-		renderer.flush()
+		renderer.renderNow()
 	}
 
 	return {
@@ -123,7 +123,7 @@ export function renderTUI(element: ReactElement, options?: RenderTUIOptions): Re
 			stdin.sendKey(key)
 		},
 
-		flush,
+		renderNow,
 
 		unmount() {
 			root.unmount()
@@ -134,8 +134,14 @@ export function renderTUI(element: ReactElement, options?: RenderTUIOptions): Re
 		renderer,
 
 		resize(w: number, h: number) {
-			stdout.resize(w, h)
-			flush()
+			stdout.columns = w
+			stdout.rows = h
+			if (renderer.dispatchResize) {
+				renderer.dispatchResize(w, h)
+			} else {
+				stdout.resize(w, h)
+			}
+			renderNow()
 		},
 	}
 }