@effect-tui/react 0.1.3 → 0.1.5

package/src/renderer/lifecycle/TerminalSetup.ts

@@ -0,0 +1,105 @@
+import { ANSI, Terminal } from "@effect-tui/core"
+import type { TuiWriteStream, TuiReadStream } from "../../renderer-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
+}
+
+/**
+ * Manages terminal setup and teardown sequences.
+ * Handles fullscreen mode, cursor visibility, paste bracketing, mouse tracking, and raw mode.
+ */
+export class TerminalSetup {
+	constructor(
+		private stdout: TuiWriteStream,
+		private stdin: TuiReadStream,
+		private config: TerminalSetupConfig,
+	) {}
+
+	/**
+	 * Set up terminal for rendering.
+	 * Call this before starting the render loop.
+	 */
+	setup(): void {
+		if (this.config.skipTerminalSetup) return
+
+		if (this.config.mode === "fullscreen") {
+			this.stdout.write(Terminal.enterFullscreen)
+		} else {
+			// Inline mode: try to disable reflow (DEC mode 2028)
+			// Supported by Contour, some others. Ignored by unsupported terminals.
+			this.stdout.write(ANSI.reflow.disable)
+		}
+
+		// Hide cursor during rendering (both modes)
+		this.stdout.write(Terminal.hideCursor)
+
+		if (this.config.enablePaste) {
+			this.stdout.write(ANSI.paste.enable)
+		}
+
+		if (this.config.enableMouse) {
+			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?.()
+		}
+	}
+
+	/**
+	 * Restore terminal to normal state.
+	 * Call this when stopping the renderer.
+	 */
+	teardown(): void {
+		if (this.config.skipTerminalSetup) return
+
+		if (this.config.mode === "fullscreen") {
+			this.stdout.write(Terminal.exitFullscreen)
+		} else {
+			// Re-enable reflow on exit
+			this.stdout.write(ANSI.reflow.enable)
+			this.stdout.write("\r\n")
+		}
+
+		if (this.config.enablePaste) {
+			this.stdout.write(ANSI.paste.disable)
+		}
+
+		if (this.config.enableMouse) {
+			this.stdout.write(ANSI.mouse.disable)
+		}
+
+		// Disable enhanced keyboard protocols
+		if (this.config.enableKittyKeyboard !== false) {
+			this.stdout.write(ANSI.keyboard.disable)
+			this.stdout.write(ANSI.modifyOtherKeys.disable)
+		}
+
+		this.stdout.write(Terminal.showCursor)
+
+		if (this.stdin.isTTY && this.stdin.setRawMode) {
+			this.stdin.setRawMode(false)
+		}
+	}
+}

package/src/renderer/lifecycle/index.ts

@@ -0,0 +1,3 @@
+export { EventBus } from "./EventBus.js"
+export { TerminalSetup, type TerminalSetupConfig } from "./TerminalSetup.js"
+export { ResizeManager, type ResizeState, type ResizeResult } from "./ResizeManager.js"

package/src/renderer/modes/FullscreenRenderer.ts

@@ -0,0 +1,53 @@
+import { ANSI, emitRowWithReset, findChangeWindow } from "@effect-tui/core"
+import type { RendererMode, RenderContext, RenderOutput } from "./RendererMode.js"
+
+/**
+ * Fullscreen rendering mode using alternate buffer.
+ * Supports line-by-line diffing for efficient updates.
+ */
+export class FullscreenRenderer implements RendererMode {
+	private needsFullClear = false
+
+	generateOutput(ctx: RenderContext): RenderOutput {
+		const { nextBuffer, prevBuffer, palette, frameWidth, frameHeight, enableDiff } = ctx
+		let output = ""
+
+		// If a full clear was requested (e.g., on resize), prepend it to output
+		// so clear + content are written atomically (no visible flash)
+		if (this.needsFullClear) {
+			output += ANSI.cursor.to(1, 1)
+			this.needsFullClear = false
+			// After clear, we must redraw everything - can't rely on diff
+			for (let y = 0; y < frameHeight; y++) {
+				if (y > 0) output += ANSI.cursor.to(1, y + 1)
+				output += emitRowWithReset(nextBuffer, palette, y, frameWidth)
+			}
+		} else if (enableDiff && prevBuffer) {
+			// Diff per line for minimal writes
+			for (let y = 0; y < frameHeight; y++) {
+				const change = findChangeWindow(prevBuffer, nextBuffer, y, frameWidth)
+				if (!change) continue
+				output += ANSI.cursor.to(change.left + 1, y + 1)
+				output += emitRowWithReset(nextBuffer, palette, y, frameWidth, change.left, change.right + 1)
+			}
+		} else {
+			// Full redraw (tests/manual mode)
+			output += ANSI.cursor.to(1, 1) + palette.sgr(0)
+			for (let y = 0; y < frameHeight; y++) {
+				output += emitRowWithReset(nextBuffer, palette, y, frameWidth)
+				if (y < frameHeight - 1) output += "\r\n"
+			}
+		}
+
+		return { output, contentHeight: frameHeight }
+	}
+
+	handleResize(_newWidth: number, _newHeight: number, _prevWidth: number): void {
+		// Defer clear to generateOutput so it's written atomically with content
+		this.needsFullClear = true
+	}
+
+	reset(): void {
+		// Nothing to reset for fullscreen mode
+	}
+}

package/src/renderer/modes/InlineRenderer.ts

@@ -0,0 +1,186 @@
+import { ANSI, emitRowWithReset, rowContentWidth, findChangeWindow } from "@effect-tui/core"
+import type { RendererMode, RenderContext, RenderOutput } from "./RendererMode.js"
+
+/**
+ * Inline rendering mode that renders in-place without alternate buffer.
+ * When content exceeds terminal height, shows the bottom portion (bottom-aligned truncation).
+ */
+export class InlineRenderer implements RendererMode {
+	private previousHeight = 0
+	private previousStartRow = 0 // Track which row we started from (for truncation)
+	private _needsFullRerender = false
+	private printedWidths: number[] = []
+	private _forceFullOutput = false
+
+	generateOutput(ctx: RenderContext): RenderOutput {
+		const { prevBuffer, frameHeight, contentHeight } = ctx
+		let output = ""
+
+		// Calculate visible region (bottom-aligned when overflowing)
+		const isOverflowing = contentHeight > frameHeight
+		const visibleHeight = Math.min(contentHeight, frameHeight)
+		const startRow = isOverflowing ? contentHeight - frameHeight : 0
+
+		// Detect if viewport shifted (content grew/shrank affecting visible region)
+		const startRowChanged = startRow !== this.previousStartRow
+		const needsFullRedraw = this.previousHeight >= frameHeight || startRowChanged
+
+		// Need full redraw if: at terminal limit, or viewport shifted
+		if (needsFullRedraw) {
+			// Clear visible area and redraw (prepend to output for atomic write)
+			if (this.previousHeight > 0) {
+				output += ANSI.cursor.up(this.previousHeight)
+			}
+			output += ANSI.cursor.startOfLine
+			this.previousStartRow = startRow
+			this.printedWidths = []
+		} else if (this.previousHeight > 0) {
+			// Normal case: move cursor up to start of previous output
+			output += ANSI.cursor.up(this.previousHeight)
+			output += ANSI.cursor.startOfLine
+		}
+
+		// Generate output for visible region
+		// Force full output after static content handling (diff mode cursor tracking gets desynchronized)
+		if (prevBuffer && !needsFullRedraw && !this._forceFullOutput) {
+			output += this.generateDiffOutput(ctx, visibleHeight, startRow)
+		} else {
+			output += this.generateFullOutput(ctx, visibleHeight, startRow, startRow + visibleHeight)
+			this._forceFullOutput = false
+		}
+
+		this.previousHeight = visibleHeight
+		this.previousStartRow = startRow
+		return { output, contentHeight: visibleHeight }
+	}
+
+	private generateDiffOutput(ctx: RenderContext, visibleHeight: number, startRow: number): string {
+		const { nextBuffer, prevBuffer, palette, frameWidth } = ctx
+		if (!prevBuffer) return ""
+
+		let output = ""
+		const rowsToProcess = Math.max(visibleHeight, this.previousHeight)
+		let cursorRow = 0
+
+		const moveToRow = (targetRow: number) => {
+			const delta = targetRow - cursorRow
+			if (delta > 0) {
+				output += ANSI.cursor.down(delta)
+			} else if (delta < 0) {
+				output += ANSI.cursor.up(-delta)
+			}
+			cursorRow = targetRow
+		}
+
+		for (let screenY = 0; screenY < rowsToProcess; screenY++) {
+			const bufferY = startRow + screenY
+
+			// Rows beyond visible height: clear if previously printed
+			if (screenY >= visibleHeight) {
+				const prevW = this.printedWidths[screenY] ?? 0
+				if (prevW > 0) {
+					moveToRow(screenY)
+					output += ANSI.cursor.toCol(1) + palette.sgr(0) + " ".repeat(prevW)
+					this.printedWidths[screenY] = 0
+				}
+				continue
+			}
+
+			const change = findChangeWindow(prevBuffer, nextBuffer, bufferY, frameWidth)
+			const newW = rowContentWidth(nextBuffer, bufferY, frameWidth)
+			const prevW = this.printedWidths[screenY] ?? 0
+
+			if (!change) {
+				// No change; maybe need to clear tail if content shrunk
+				if (prevW > newW) {
+					moveToRow(screenY)
+					output += ANSI.cursor.toCol(newW + 1) + palette.sgr(0) + " ".repeat(prevW - newW)
+					this.printedWidths[screenY] = newW
+				}
+				continue
+			}
+
+			// Emit changed region [left..right]
+			moveToRow(screenY)
+			output += ANSI.cursor.toCol(change.left + 1)
+			output += emitRowWithReset(nextBuffer, palette, bufferY, frameWidth, change.left, change.right + 1)
+
+			// Clear tail if shrunk
+			const effectiveW = Math.max(newW, change.right + 1)
+			if (prevW > effectiveW) {
+				output += ANSI.cursor.toCol(effectiveW + 1) + palette.sgr(0) + " ".repeat(prevW - effectiveW)
+			}
+			this.printedWidths[screenY] = newW
+		}
+
+		// Ensure cursor ends just after the dynamic block for next frame positioning
+		moveToRow(visibleHeight)
+		output += ANSI.cursor.toCol(1)
+
+		return output
+	}
+
+	private generateFullOutput(ctx: RenderContext, rowCount: number, startRow: number, endRow: number): string {
+		const { nextBuffer, palette, frameWidth } = ctx
+		let output = ""
+
+		// Full redraw inline: clear each line first, then emit content
+		for (let bufferY = startRow; bufferY < endRow; bufferY++) {
+			const screenY = bufferY - startRow
+			const trimmedWidth = rowContentWidth(nextBuffer, bufferY, frameWidth)
+			// Full-width emit avoids reliance on line clears.
+			output += emitRowWithReset(nextBuffer, palette, bufferY, frameWidth, 0, frameWidth)
+			output += "\r\n"
+			// Track line widths for resize reflow calculation
+			this.printedWidths[screenY] = trimmedWidth
+		}
+
+		// Clear any extra lines if content shrank
+		for (let screenY = rowCount; screenY < this.previousHeight; screenY++) {
+			output += palette.sgr(0) + " ".repeat(frameWidth) + "\r\n"
+			this.printedWidths[screenY] = 0
+		}
+
+		// Move cursor back up to end of content
+		if (this.previousHeight > rowCount) {
+			output += ANSI.cursor.up(this.previousHeight - rowCount)
+		}
+
+		return output
+	}
+
+	handleResize(newWidth: number, _newHeight: number, prevWidth: number): void {
+		// Any width change triggers full rerender (Ink-style: clear + replay static)
+		if (newWidth !== prevWidth) {
+			this._needsFullRerender = true
+		}
+	}
+
+	/** Check if full rerender is needed (clear screen + replay static) */
+	needsFullRerender(): boolean {
+		return this._needsFullRerender
+	}
+
+	/** Clear the full rerender flag after handling */
+	clearFullRerenderFlag(): void {
+		this._needsFullRerender = false
+		this.previousHeight = 0
+		this.previousStartRow = 0
+		this.printedWidths = []
+	}
+
+	reset(): void {
+		this.previousHeight = 0
+		this.previousStartRow = 0
+		this.printedWidths = []
+	}
+
+	/** Force full output on the next frame (needed after static content to resync cursor tracking) */
+	forceFullOutputOnce(): void {
+		this._forceFullOutput = true
+	}
+
+	getPreviousHeight(): number {
+		return this.previousHeight
+	}
+}

package/src/renderer/modes/RendererMode.ts

@@ -0,0 +1,46 @@
+import type { CellBuffer, Palette } from "@effect-tui/core"
+import type { TuiWriteStream } from "../../renderer-types.js"
+
+/**
+ * Context passed to render mode output generation.
+ */
+export interface RenderContext {
+	nextBuffer: CellBuffer
+	prevBuffer: CellBuffer | null
+	palette: Palette
+	frameWidth: number
+	/** Terminal height (viewport) */
+	frameHeight: number
+	/** Actual content height (may exceed frameHeight in inline mode) */
+	contentHeight: number
+	enableDiff: boolean
+	stdout: TuiWriteStream
+}
+
+/**
+ * Result of generating output for a frame.
+ */
+export interface RenderOutput {
+	output: string
+	contentHeight: number
+}
+
+/**
+ * Interface for render mode implementations.
+ */
+export interface RendererMode {
+	/**
+	 * Generate ANSI output for the current frame.
+	 */
+	generateOutput(ctx: RenderContext): RenderOutput
+
+	/**
+	 * Handle a resize event. Returns true if a full clear is needed.
+	 */
+	handleResize(newWidth: number, newHeight: number, prevWidth: number): void
+
+	/**
+	 * Reset any mode-specific state (e.g., after static content flush).
+	 */
+	reset(): void
+}

package/src/renderer/modes/StaticContentRenderer.ts

@@ -0,0 +1,56 @@
+import { CellBuffer, emitRowWithReset, rowContentWidth, type Palette } from "@effect-tui/core"
+import type { HostInstance } from "../../reconciler/types.js"
+import type { TuiWriteStream } from "../../renderer-types.js"
+
+/**
+ * Renders static content to scrollback (inline mode only).
+ * Static content is rendered once and doesn't update with the dynamic section.
+ * Caches all output for replay on resize (Ink-style).
+ */
+export class StaticContentRenderer {
+	private cachedOutput = "" // Accumulates all static content for replay
+
+	constructor(
+		_stdout: TuiWriteStream, // Kept for API compatibility, not used (writes are atomic in renderer.ts)
+		private palette: Palette,
+	) {}
+
+	/** Get all cached static output for replay on resize */
+	getCachedOutput(): string {
+		return this.cachedOutput
+	}
+
+	/** Clear the cache (call after full terminal clear + replay) */
+	clearCache(): void {
+		this.cachedOutput = ""
+	}
+
+	/**
+	 * Render a static node and return the output string.
+	 * Static content is append-only - no cursor positioning needed.
+	 * Caller clears dynamic area first, then appends this output.
+	 */
+	render(staticNode: HostInstance, frameWidth: number): string {
+		// 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 })
+
+		// Render to a temporary buffer
+		const staticBuffer = new CellBuffer(frameWidth, staticSize.h)
+		staticBuffer.clear(0)
+		staticNode.render(staticBuffer, this.palette)
+
+		// Build content lines - append-only, no cursor movement
+		let contentLines = ""
+		for (let y = 0; y < staticSize.h; y++) {
+			const trimmedWidth = rowContentWidth(staticBuffer, y, frameWidth)
+			const line = emitRowWithReset(staticBuffer, this.palette, y, frameWidth, 0, trimmedWidth)
+			contentLines += line + "\n"
+		}
+
+		// Cache the content for replay on resize
+		this.cachedOutput += contentLines
+
+		return contentLines
+	}
+}

package/src/renderer/modes/index.ts

@@ -0,0 +1,4 @@
+export type { RendererMode, RenderContext, RenderOutput } from "./RendererMode.js"
+export { FullscreenRenderer } from "./FullscreenRenderer.js"
+export { InlineRenderer } from "./InlineRenderer.js"
+export { StaticContentRenderer } from "./StaticContentRenderer.js"

package/src/renderer-context.ts

@@ -0,0 +1,27 @@
+import { createContext, useContext, useState, useEffect } 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
+}

package/src/renderer-types.ts

@@ -0,0 +1,109 @@
+import type { KeyMsg, MouseMsg } from "@effect-tui/core"
+import type { HostInstance, HostContext } from "./reconciler/types.js"
+
+/** 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: (text: string) => 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
+	/** 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
+}