@effect-tui/react 0.8.0 → 0.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effect-tui/react",
-	"version": "0.8.0",
+	"version": "0.9.1",
 	"description": "React bindings for @effect-tui/core",
 	"type": "module",
 	"files": [
@@ -83,7 +83,7 @@
 		"prepublishOnly": "bun run typecheck && bun run build"
 	},
 	"dependencies": {
-		"@effect-tui/core": "^0.8.0",
+		"@effect-tui/core": "^0.9.1",
 		"@effect/platform": "^0.94.0",
 		"@effect/platform-bun": "^0.87.0",
 		"@effect/rpc": "^0.73.0",

package/src/components/Divider.tsx

@@ -17,7 +17,7 @@ export interface DividerProps {
  * <Divider char="═" fg={Colors.brightBlue} />
  * ```
  */
-export function Divider({ char = "─", fg = Colors.gray(12) }: DividerProps) {
+export function Divider({ char = "─", fg = Colors.ansi.gray(12) }: DividerProps) {
 	const { width } = useTerminalSize()
 	return <text fg={fg}>{char.repeat(width)}</text>
 }

package/src/components/Markdown.tsx

@@ -31,19 +31,19 @@ export interface MarkdownTheme {
 }
 
 const defaultTheme: Required<MarkdownTheme> = {
-	h1: Colors.brightCyan,
-	h2: Colors.cyan,
-	h3: Colors.brightBlue,
-	bold: Colors.brightWhite,
-	italic: Colors.brightYellow,
-	code: Colors.brightGreen,
-	codeBg: Colors.gray(2),
-	link: Colors.brightBlue,
-	linkUrl: Colors.gray(10),
-	quote: Colors.gray(14),
-	quoteBorder: Colors.gray(8),
-	listMarker: Colors.gray(12),
-	text: Colors.gray(18),
+	h1: Colors.ansi.brightCyan,
+	h2: Colors.cyan(500),
+	h3: Colors.ansi.brightBlue,
+	bold: Colors.ansi.brightWhite,
+	italic: Colors.ansi.brightYellow,
+	code: Colors.ansi.brightGreen,
+	codeBg: Colors.ansi.gray(2),
+	link: Colors.ansi.brightBlue,
+	linkUrl: Colors.ansi.gray(10),
+	quote: Colors.ansi.gray(14),
+	quoteBorder: Colors.ansi.gray(8),
+	listMarker: Colors.ansi.gray(12),
+	text: Colors.ansi.gray(18),
 }
 
 export interface MarkdownProps {

package/src/components/MultilineTextInput.tsx

@@ -262,12 +262,12 @@ export function MultilineTextInput({
 	placeholder = "",
 	width,
 	height = 5,
-	fg = Colors.brightWhite,
+	fg = Colors.ansi.brightWhite,
 	bg,
-	cursorFg = Colors.black,
-	cursorBg = Colors.brightWhite,
-	placeholderFg = Colors.gray(10),
-	lineNumberFg = Colors.gray(12),
+	cursorFg = Colors.ansi.black,
+	cursorBg = Colors.ansi.brightWhite,
+	placeholderFg = Colors.ansi.gray(10),
+	lineNumberFg = Colors.ansi.gray(12),
 	onCancel,
 	onSubmit,
 	focused = true,

package/src/components/Table.tsx

@@ -175,8 +175,8 @@ function TableRoot<T>({
 	headerSeparator = false,
 	rowSeparator = false,
 	padding = 1,
-	borderColor = Colors.gray(12),
-	headerColor = Colors.gray(12),
+	borderColor = Colors.ansi.gray(12),
+	headerColor = Colors.ansi.gray(12),
 	children,
 }: TableProps<T>) {
 	const columns = extractColumns<T>(children, data)

package/src/components/TextInput.tsx

@@ -73,11 +73,11 @@ export function TextInput({
 	onChange,
 	placeholder = "",
 	width,
-	fg = Colors.brightWhite,
+	fg = Colors.ansi.brightWhite,
 	bg,
-	cursorFg = Colors.black,
-	cursorBg = Colors.brightWhite,
-	placeholderFg = Colors.gray(10),
+	cursorFg = Colors.ansi.black,
+	cursorBg = Colors.ansi.brightWhite,
+	placeholderFg = Colors.ansi.gray(10),
 	onSubmit,
 	onCancel,
 	focused = true,

package/src/console/ConsoleCapture.ts

@@ -120,12 +120,23 @@ export class ConsoleCapture extends EventEmitter {
 	private inConsoleMethod = false
 	// Track if current write is from the TUI renderer (should bypass capture)
 	private inRendererWrite = false
+	// Block stdout/stderr writes only after renderer is ready
+	// Until then, pass through to avoid swallowing startup errors
+	private blockingEnabled = false
 
 	constructor(options?: { maxEntries?: number }) {
 		super()
 		this.maxEntries = options?.maxEntries ?? 1000
 	}
 
+	/**
+	 * Enable blocking of stdout/stderr writes.
+	 * Call this after the renderer is fully set up and rendering.
+	 */
+	enableBlocking(): void {
+		this.blockingEnabled = true
+	}
+
 	/**
 	 * Write directly to stdout, bypassing capture.
 	 * Used by the TUI renderer to output to terminal.
@@ -157,13 +168,17 @@ export class ConsoleCapture extends EventEmitter {
 		// Store original console
 		this.originalConsole = globalThis.console
 
+		// Enable blocking immediately - TUI owns the terminal
+		// Any output will be captured in the console panel, not displayed
+		this.blockingEnabled = true
+
 		// Intercept stdout.write - captures Effect.log, printf, etc.
 		process.stdout.write = ((
 			chunk: Uint8Array | string,
 			encodingOrCallback?: BufferEncoding | ((err?: Error | null) => void),
 			callback?: (err?: Error | null) => void,
 		): boolean => {
-			// If this write is from renderer or console methods, pass through
+			// If this write is from renderer, pass through
 			if (this.inRendererWrite) {
 				return originalStdoutWrite(chunk, encodingOrCallback as BufferEncoding, callback)
 			}
@@ -172,7 +187,11 @@ export class ConsoleCapture extends EventEmitter {
 				const text = typeof chunk === "string" ? chunk : chunk.toString()
 				this.captureRawOutput(text, "stdout")
 			}
-			// Don't write to real stdout - TUI owns the terminal
+			// If blocking not enabled yet, pass through (allows startup errors to show)
+			if (!this.blockingEnabled) {
+				return originalStdoutWrite(chunk, encodingOrCallback as BufferEncoding, callback)
+			}
+			// Block write - TUI owns the terminal
 			const cb = typeof encodingOrCallback === "function" ? encodingOrCallback : callback
 			if (cb) cb()
 			return true
@@ -191,6 +210,10 @@ export class ConsoleCapture extends EventEmitter {
 				const text = typeof chunk === "string" ? chunk : chunk.toString()
 				this.captureRawOutput(text, "stderr")
 			}
+			// If blocking not enabled yet, pass through (allows startup errors to show)
+			if (!this.blockingEnabled) {
+				return originalStderrWrite(chunk, encodingOrCallback as BufferEncoding, callback)
+			}
 			const cb = typeof encodingOrCallback === "function" ? encodingOrCallback : callback
 			if (cb) cb()
 			return true

package/src/console/ConsolePopover.tsx

@@ -41,16 +41,16 @@ interface SelectionPoint {
 // ─────────────────────────────────────────────────────────────
 
 const LOG_COLORS: Record<LogLevel, ColorValue> = {
-	LOG: Colors.white,
-	INFO: Colors.cyan,
-	WARN: Colors.yellow,
-	ERROR: Colors.red,
-	DEBUG: Colors.gray(12),
+	LOG: Colors.ansi.white,
+	INFO: Colors.cyan(500),
+	WARN: Colors.yellow(500),
+	ERROR: Colors.red(500),
+	DEBUG: Colors.ansi.gray(12),
 }
 
-const TITLE_BG = Colors.gray(4)
-const TITLE_FG = Colors.white
-const CONTENT_BG = Colors.gray(2)
+const TITLE_BG = Colors.ansi.gray(4)
+const TITLE_FG = Colors.ansi.white
+const CONTENT_BG = Colors.ansi.gray(2)
 const SELECTION_BG = Colors.rgb(60, 90, 140)
 
 // ─────────────────────────────────────────────────────────────
@@ -421,7 +421,7 @@ export function ConsolePopover({
 								{before}
 							</text>
 						)}
-						<text fg={Colors.white} bg={SELECTION_BG}>
+						<text fg={Colors.ansi.white} bg={SELECTION_BG}>
 							{selected}
 						</text>
 						{after.length > 0 && (
@@ -450,11 +450,11 @@ export function ConsolePopover({
 			<vstack width={termWidth} height={popoverHeight}>
 				{/* Title bar */}
 				<hstack height={1} bg={TITLE_BG}>
-					<text fg={feedback ? Colors.green : TITLE_FG} bg={TITLE_BG}>
+					<text fg={feedback ? Colors.green(500) : TITLE_FG} bg={TITLE_BG}>
 						{` ${titleText}`}
 					</text>
 					<spacer />
-					<text fg={Colors.gray(14)} bg={TITLE_BG}>
+					<text fg={Colors.ansi.gray(14)} bg={TITLE_BG}>
 						{`${mode === "inline" ? inlineHints : hints} `}
 					</text>
 				</hstack>
@@ -463,7 +463,7 @@ export function ConsolePopover({
 				<scroll {...scrollProps} sticky>
 					<vstack>
 						{displayLines.length === 0 ? (
-							<text fg={Colors.gray(10)} bg={CONTENT_BG}>
+							<text fg={Colors.ansi.gray(10)} bg={CONTENT_BG}>
 								No console output yet
 							</text>
 						) : (

package/src/console/useConsole.ts

@@ -65,16 +65,13 @@ export function useConsole(options: UseConsoleOptions = {}): UseConsoleReturn {
 	const [visible, setVisible] = useState(initiallyVisible)
 	const [entries, setEntries] = useState<LogEntry[]>(() => capture.getEntries())
 
-	// Activate capture on mount
+	// Activate capture on mount (blocking is enabled immediately in activate())
 	useEffect(() => {
 		if (!capture.isActive) {
 			capture.activate()
 		}
-
-		return () => {
-			// Don't deactivate on unmount - other components may still use it
-			// The singleton handles cleanup on process exit
-		}
+		// Don't deactivate on unmount - other components may still use it
+		// The singleton handles cleanup on process exit
 	}, [capture])
 
 	// Subscribe to entries and errors

package/src/debug/DiagnosticsPanel.tsx

@@ -17,21 +17,21 @@ export function DiagnosticsPanel({ sampleMs = 200, title = "Diagnostics" }: Diag
 
 	return (
 		<vstack spacing={1}>
-			<text fg={Colors.cyan} bold>
+			<text fg={Colors.cyan(500)} bold>
 				{title} ({stats?.mode ?? "?"})
 			</text>
 			{stats ? (
 				<>
-					<text fg={Colors.gray(12)}>
+					<text fg={Colors.ansi.gray(12)}>
 						size {stats.width}×{stats.height} content {h} rows — {bytes} bytes/frame — {fps} fps
 					</text>
-					<text fg={Colors.gray(12)}>
+					<text fg={Colors.ansi.gray(12)}>
 						clear {phases?.clear.toFixed(2)}ms · layout {phases?.layout.toFixed(2)}ms · render{" "}
 						{phases?.render.toFixed(2)}ms · diff {phases?.diffAnsi.toFixed(2)}ms · write {phases?.write.toFixed(2)}ms
 					</text>
 				</>
 			) : (
-				<text fg={Colors.gray(10)}>Waiting for first frame…</text>
+				<text fg={Colors.ansi.gray(10)}>Waiting for first frame…</text>
 			)}
 		</vstack>
 	)

package/src/dev/Toast.tsx

@@ -2,19 +2,20 @@
 // Beautiful, minimal notifications that appear at the top of the screen
 
 import { Colors } from "@effect-tui/core"
-import { createContext, type ReactNode, useCallback, useContext, useState } from "react"
-import { useTerminalSize } from "../renderer-context.js"
+import { createContext, type ReactNode, useCallback, useContext, useEffect, useState } from "react"
 
 // ─────────────────────────────────────────────────────────────
 // Types
 // ─────────────────────────────────────────────────────────────
 
-export type ToastType = "success" | "info" | "warning" | "error"
+export type ToastType = "success" | "info" | "warning" | "error" | "screenshot"
 
 export interface Toast {
 	id: number
 	message: string
 	type: ToastType
+	/** Timestamp when the toast was created (for animations) */
+	createdAt: number
 }
 
 export interface ToastContextValue {
@@ -49,6 +50,7 @@ const TOAST_STYLES: Record<
 	info: { bg: Colors.rgb(30, 50, 80), fg: Colors.rgb(140, 180, 230), icon: "ℹ" },
 	warning: { bg: Colors.rgb(80, 60, 20), fg: Colors.rgb(230, 200, 100), icon: "⚠" },
 	error: { bg: Colors.rgb(80, 30, 30), fg: Colors.rgb(230, 140, 140), icon: "✗" },
+	screenshot: { bg: Colors.rgb(30, 70, 40), fg: Colors.rgb(140, 230, 140), icon: "📷" },
 }
 
 // ─────────────────────────────────────────────────────────────
@@ -62,7 +64,7 @@ export function ToastProvider({ children }: { children: ReactNode }) {
 
 	const show = useCallback((message: string, type: ToastType = "info", durationMs = 2000) => {
 		const id = ++toastId
-		setToasts((prev) => [...prev, { id, message, type }])
+		setToasts((prev) => [...prev, { id, message, type, createdAt: Date.now() }])
 
 		setTimeout(() => {
 			setToasts((prev) => prev.filter((t) => t.id !== id))
@@ -76,30 +78,95 @@ export function ToastProvider({ children }: { children: ReactNode }) {
 	return <ToastContext.Provider value={{ toasts, show, dismiss }}>{children}</ToastContext.Provider>
 }
 
+// ─────────────────────────────────────────────────────────────
+// Screenshot Toast Animation
+// ─────────────────────────────────────────────────────────────
+
+// Animation phases: camera → flash → success
+type ScreenshotPhase = "camera" | "flash" | "success"
+
+const SCREENSHOT_PHASES: Record<
+	ScreenshotPhase,
+	{ icon: string; bg: ReturnType<typeof Colors.rgb>; fg: ReturnType<typeof Colors.rgb> }
+> = {
+	camera: {
+		icon: "📷",
+		bg: Colors.rgb(40, 50, 60),
+		fg: Colors.rgb(180, 200, 220),
+	},
+	flash: {
+		icon: "⚡",
+		bg: Colors.rgb(255, 255, 200), // Bright flash!
+		fg: Colors.rgb(60, 60, 40),
+	},
+	success: {
+		icon: "✓",
+		bg: Colors.rgb(30, 70, 40),
+		fg: Colors.rgb(140, 230, 140),
+	},
+}
+
+function ScreenshotToast({ message, createdAt }: { message: string; createdAt: number }) {
+	const [phase, setPhase] = useState<ScreenshotPhase>("camera")
+
+	useEffect(() => {
+		// Phase timing: camera (0-120ms) → flash (120-280ms) → success (280ms+)
+		const elapsed = Date.now() - createdAt
+		const cameraDelay = Math.max(0, 120 - elapsed)
+		const flashDelay = Math.max(0, 280 - elapsed)
+
+		const flashTimer = setTimeout(() => setPhase("flash"), cameraDelay)
+		const successTimer = setTimeout(() => setPhase("success"), flashDelay)
+
+		return () => {
+			clearTimeout(flashTimer)
+			clearTimeout(successTimer)
+		}
+	}, [createdAt])
+
+	const style = SCREENSHOT_PHASES[phase]
+	const content = ` ${style.icon} ${message} `
+
+	return (
+		<hstack>
+			<spacer />
+			<box bg={style.bg} padding={{ x: 1 }}>
+				<text fg={style.fg}>{content}</text>
+			</box>
+		</hstack>
+	)
+}
+
 // ─────────────────────────────────────────────────────────────
 // Toast Display Component
 // ─────────────────────────────────────────────────────────────
 
 export function ToastContainer() {
 	const { toasts } = useToast()
-	const { width } = useTerminalSize()
 
 	if (toasts.length === 0) return null
 
 	// Show only the most recent toast
 	const toast = toasts[toasts.length - 1]
+
+	// Special animated toast for screenshots
+	if (toast.type === "screenshot") {
+		return <ScreenshotToast message={toast.message} createdAt={toast.createdAt} />
+	}
+
 	const style = TOAST_STYLES[toast.type]
 
-	// Center the message with padding
+	// Compact pill in upper right
 	const content = ` ${style.icon} ${toast.message} `
-	const padding = Math.max(0, Math.floor((width - content.length) / 2))
-	const paddedContent = " ".repeat(padding) + content + " ".repeat(width - padding - content.length)
 
-	// Just render the toast line - parent zstack handles positioning
+	// Position in upper right corner
 	return (
-		<text bg={style.bg} fg={style.fg}>
-			{paddedContent}
-		</text>
+		<hstack>
+			<spacer />
+			<box bg={style.bg} padding={{ x: 1 }}>
+				<text fg={style.fg}>{content}</text>
+			</box>
+		</hstack>
 	)
 }
 

package/src/dev.tsx

@@ -327,7 +327,7 @@ function StatsOverlay({ sampleMs, title }: { sampleMs?: number; title?: string }
 		<vstack width={width} height={height}>
 			<hstack width={width}>
 				<spacer />
-				<box padding={1} border="rounded" borderColor={Colors.gray(8)} bg={Colors.gray(2)}>
+				<box padding={1} border="rounded" borderColor={Colors.ansi.gray(8)} bg={Colors.ansi.gray(2)}>
 					<DiagnosticsPanel sampleMs={sampleMs} title={title ?? "Renderer Stats"} />
 				</box>
 			</hstack>

package/src/hooks/use-scroll.ts

@@ -218,28 +218,37 @@ export function useScroll(options: UseScrollOptions = {}): UseScrollReturn {
 	const atStart = offset <= 0
 	const atEnd = offset >= maxOffset
 
+	const clampOffset = useCallback(
+		(value: number) => {
+			const clamped = Math.max(0, Math.min(maxOffset, value))
+			// Keep refs in sync so rapid events don't use stale state
+			offsetRef.current = clamped
+			wasAtEndRef.current = clamped >= maxOffset - 1
+			return clamped
+		},
+		[maxOffset],
+	)
+
 	// Clamp and set offset
 	const setOffset = useCallback(
 		(newOffset: number) => {
-			const clamped = Math.max(0, Math.min(maxOffset, newOffset))
-			setOffsetRaw(clamped)
-			// Track if we're at end for sticky behavior
-			wasAtEndRef.current = clamped >= maxOffset - 1
+			setOffsetRaw(() => clampOffset(newOffset))
 		},
-		[maxOffset],
+		[clampOffset],
 	)
 
 	// Scroll by delta with accumulator for fractional scrolling
+	// Uses functional state updates to avoid stale closures during rapid scrolling
 	const scrollBy = useCallback(
 		(delta: number) => {
 			accumulatorRef.current += delta
 			const integerDelta = Math.trunc(accumulatorRef.current)
 			if (integerDelta !== 0) {
-				setOffset(offset + integerDelta)
+				setOffsetRaw((prev) => clampOffset(prev + integerDelta))
 				accumulatorRef.current -= integerDelta
 			}
 		},
-		[offset, setOffset],
+		[clampOffset],
 	)
 
 	const scrollToStart = useCallback(() => {
@@ -270,9 +279,9 @@ export function useScroll(options: UseScrollOptions = {}): UseScrollReturn {
 		if (!sticky) return
 		const newMaxOffset = Math.max(0, contentSize - viewportSize)
 		if (wasAtEndRef.current && contentSize > 0) {
-			setOffsetRaw(newMaxOffset)
+			setOffsetRaw(() => clampOffset(newMaxOffset))
 		}
-	}, [sticky, contentSize, viewportSize])
+	}, [sticky, contentSize, viewportSize, clampOffset])
 
 	// Handle viewport size changes (reported by scroll component)
 	const handleViewportSize = useCallback(

package/src/hosts/box.ts

@@ -20,6 +20,10 @@ export interface BoxProps extends CommonProps {
 	border?: BorderKind
 	borderColor?: Color
 	bg?: Color
+	/** Title displayed on the top border */
+	title?: string
+	/** Title text color (defaults to borderColor) */
+	titleColor?: Color
 }
 
 export class BoxHost extends SingleChildHost {
@@ -27,6 +31,8 @@ export class BoxHost extends SingleChildHost {
 	border: BorderKind = "none"
 	borderColor?: Color
 	bg?: Color
+	title?: string
+	titleColor?: Color
 
 	constructor(props: BoxProps, ctx: HostContext) {
 		super("box", props, ctx)
@@ -101,9 +107,21 @@ export class BoxHost extends SingleChildHost {
 		// Draw border
 		if (this.border !== "none" && w >= 2 && h >= 2) {
 			const chars = borderChars(this.border)
-			const borderFg = toColorValue(this.borderColor) ?? Colors.gray(8)
+			const borderFg = toColorValue(this.borderColor) ?? Colors.ansi.gray(8)
 			const borderStyle = palette.id({ fg: borderFg })
 			drawBorder(buffer, x, y, w, h, chars, borderStyle)
+
+			// Draw title on top border if present
+			if (this.title && w >= 5) {
+				const titleFg = toColorValue(this.titleColor) ?? borderFg
+				const titleStyle = palette.id({ fg: titleFg })
+				const maxTitleLen = w - 4 // Leave room for "─ " and " ─"
+				const displayTitle =
+					this.title.length > maxTitleLen ? this.title.slice(0, maxTitleLen - 1) + "…" : this.title
+				// Draw " Title " starting at x+2
+				const titleX = x + 2
+				buffer.drawText(titleX, y, ` ${displayTitle} `, titleStyle)
+			}
 		}
 
 		// Render single child
@@ -119,5 +137,7 @@ export class BoxHost extends SingleChildHost {
 		this.border = (props.border as BorderKind | undefined) ?? "none"
 		this.borderColor = props.borderColor as Color | undefined
 		this.bg = props.bg as Color | undefined
+		this.title = props.title as string | undefined
+		this.titleColor = props.titleColor as Color | undefined
 	}
 }

package/src/hosts/canvas.ts

@@ -168,7 +168,7 @@ export class CanvasHost extends BaseHost {
 				// Draw border (with clipping)
 				if (border !== "none" && bw >= 2 && bh >= 2) {
 					const chars = borderChars(border)
-					const borderFg = toColorValue(opts?.borderColor) ?? toColorValue(opts?.fg) ?? Colors.gray(8)
+					const borderFg = toColorValue(opts?.borderColor) ?? toColorValue(opts?.fg) ?? Colors.ansi.gray(8)
 					const borderStyle = palette.id({ fg: borderFg })
 					drawBorder(buffer, px, py, bw, bh, chars, borderStyle, { ox, oy, w, h })
 				}

package/src/hosts/codeblock.ts

@@ -88,7 +88,7 @@ export class CodeBlockHost extends BaseHost {
 
 			if (this.lineNumbers) {
 				const gutterStyle = styleIdFromProps(palette, {
-					fg: this.lineNumberColor ?? Colors.gray(11),
+					fg: this.lineNumberColor ?? Colors.ansi.gray(11),
 					bg: this.lineNumberBackground ?? this.background,
 				})
 				const digits = String(i + 1).padStart(this.gutterWidth - 1, " ")

package/src/inline/index.tsx

@@ -41,19 +41,19 @@ function TaskList({ tasks, spinnerIndex }: TaskListProps) {
 
 				const color =
 					task.status === "running"
-						? Colors.brightYellow
+						? Colors.ansi.brightYellow
 						: task.status === "success"
-							? Colors.brightGreen
+							? Colors.ansi.brightGreen
 							: task.status === "failure"
-								? Colors.brightRed
-								: Colors.gray(10)
+								? Colors.ansi.brightRed
+								: Colors.ansi.gray(10)
 
 				return (
 					<hstack key={i} spacing={1}>
 						<text bold fg={color}>
 							{icon}
 						</text>
-						<text fg={task.status === "pending" ? Colors.gray(10) : undefined}>{task.label}</text>
+						<text fg={task.status === "pending" ? Colors.ansi.gray(10) : undefined}>{task.label}</text>
 					</hstack>
 				)
 			})}

package/src/renderer.ts

@@ -32,13 +32,28 @@ 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
-	const baseStdout: TuiWriteStream = options?.stdout ?? process.stdout
-	// Wrap write method to bypass console capture (so Effect.log etc. don't corrupt TUI)
-	const terminalWrite = createTerminalWriter()
-	const stdout: TuiWriteStream = {
-		...baseStdout,
-		write: terminalWrite,
-	} as TuiWriteStream
+	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