@effect-tui/react 0.1.3 → 0.1.4

package/src/remote/Router.ts

@@ -0,0 +1,58 @@
+// RPC handlers for remote session control
+import type { Rpc } from "@effect/rpc"
+import { Effect, Layer, Context } from "effect"
+import type { KeyMsg } from "@effect-tui/core"
+import { TuiRpcs } from "./Procedures.js"
+
+// Service interface for the TUI session
+export interface TuiSessionImpl {
+	readonly getScreenshot: () => string
+	readonly dispatchKey: (key: KeyMsg) => void
+	readonly dispatchPaste: (text: string) => void
+	readonly dispatchResize: (width: number, height: number) => void
+	readonly getInfo: () => { pid: number; width: number; height: number }
+}
+
+export class TuiSession extends Context.Tag("TuiSession")<
+	TuiSession,
+	TuiSessionImpl
+>() {}
+
+// Create the RPC handlers layer
+export const HandlersLive: Layer.Layer<
+	| Rpc.Handler<"Screenshot">
+	| Rpc.Handler<"SendKey">
+	| Rpc.Handler<"Paste">
+	| Rpc.Handler<"Resize">
+	| Rpc.Handler<"Info">,
+	never,
+	TuiSession
+> = TuiRpcs.toLayer(
+	Effect.gen(function* () {
+		const session = yield* TuiSession
+
+		return {
+			Screenshot: () => Effect.sync(() => session.getScreenshot()),
+
+			SendKey: ({ name, text, ctrl, shift, meta }) =>
+				Effect.sync(() => {
+					const key: KeyMsg = {
+						type: "key",
+						name: name as KeyMsg["name"],
+						text,
+						ctrl: ctrl ?? false,
+						shift: shift ?? false,
+						meta: meta ?? false,
+					}
+					session.dispatchKey(key)
+				}),
+
+			Paste: ({ text }) => Effect.sync(() => session.dispatchPaste(text)),
+
+			Resize: ({ width, height }) =>
+				Effect.sync(() => session.dispatchResize(width, height)),
+
+			Info: () => Effect.sync(() => session.getInfo()),
+		}
+	}),
+)

package/src/remote/Server.ts

@@ -0,0 +1,76 @@
+// Remote server that exposes TUI session via Unix socket
+import { Effect, Layer } from "effect"
+import { RpcSerialization, RpcServer } from "@effect/rpc"
+import { BunSocketServer } from "@effect/platform-bun"
+import * as fs from "node:fs"
+import * as path from "node:path"
+import { TuiRpcs } from "./Procedures.js"
+import { HandlersLive, TuiSession, type TuiSessionImpl } from "./Router.js"
+
+// Default socket directory
+const SOCKET_DIR = "/tmp/effect-tui-sessions"
+
+// Ensure socket directory exists
+const ensureSocketDir = Effect.sync(() => {
+	if (!fs.existsSync(SOCKET_DIR)) {
+		fs.mkdirSync(SOCKET_DIR, { recursive: true })
+	}
+})
+
+// Get socket path for current process
+export const getSocketPath = (pid?: number) =>
+	path.join(SOCKET_DIR, `${pid ?? process.pid}.sock`)
+
+// Clean up socket file
+const cleanupSocket = (socketPath: string) =>
+	Effect.sync(() => {
+		try {
+			if (fs.existsSync(socketPath)) {
+				fs.unlinkSync(socketPath)
+			}
+		} catch {
+			// Ignore cleanup errors
+		}
+	})
+
+// Create the server layer
+export const makeServerLayer = (
+	sessionImpl: TuiSessionImpl,
+	socketPath?: string,
+) => {
+	const actualPath = socketPath ?? getSocketPath()
+
+	// Setup layer - creates directory, cleans stale socket
+	const SetupLive = Layer.scopedDiscard(
+		Effect.gen(function* () {
+			yield* ensureSocketDir
+			yield* cleanupSocket(actualPath)
+			yield* Effect.addFinalizer(() => cleanupSocket(actualPath))
+			// Use console.log so it gets captured by the debug console panel
+			console.log(`[remote] Listening on ${actualPath}`)
+		}),
+	)
+
+	// RPC handlers layer (needs TuiSession)
+	const HandlersLayer = HandlersLive.pipe(
+		Layer.provide(Layer.succeed(TuiSession, sessionImpl)),
+	)
+
+	// Full RPC server stack:
+	// 1. RpcServer.layer creates the RPC server, needs handlers
+	// 2. Handlers provide the implementation
+	// 3. Protocol layer provides socket protocol
+	// 4. Socket server provides the actual socket
+	const RpcLive = RpcServer.layer(TuiRpcs).pipe(
+		Layer.provide(HandlersLayer),
+		Layer.provideMerge(RpcServer.layerProtocolSocketServer),
+		Layer.provide(RpcSerialization.layerNdjson),
+		Layer.provide(
+			BunSocketServer.layer({
+				path: actualPath,
+			}),
+		),
+	)
+
+	return Layer.merge(SetupLive, RpcLive)
+}

package/src/remote/index.ts

@@ -0,0 +1,90 @@
+// Remote session control for effect-tui
+//
+// Allows external tools (like Claude Code) to connect to a running TUI session
+// to send keypresses and get screenshots.
+//
+// Usage:
+// 1. Run app with EFFECT_TUI_REMOTE=1 to enable remote control
+// 2. Connect using etui CLI or raw socket at /tmp/effect-tui-sessions/<pid>.sock
+
+export { TuiRpcs } from "./Procedures.js"
+export { TuiSession, HandlersLive } from "./Router.js"
+export { makeServerLayer, getSocketPath } from "./Server.js"
+
+import { Effect, Exit, Layer, Scope } from "effect"
+import * as fs from "node:fs"
+import type { TuiRenderer } from "../renderer-types.js"
+import type { TuiSessionImpl } from "./Router.js"
+import { makeServerLayer, getSocketPath } from "./Server.js"
+
+/**
+ * Enable remote control for a TUI renderer.
+ * Starts an RPC server on a Unix socket at /tmp/effect-tui-sessions/<pid>.sock
+ *
+ * @param renderer - The TUI renderer to control
+ * @param socketPath - Optional custom socket path
+ * @returns A cleanup function to stop the server
+ */
+export function enableRemote(
+	renderer: TuiRenderer,
+	socketPath?: string,
+): () => void {
+	const actualPath = socketPath ?? getSocketPath()
+
+	// Create session implementation from renderer
+	const session: TuiSessionImpl = {
+		getScreenshot: () => renderer.getScreenshot(),
+		dispatchKey: (key) => renderer.dispatchKey?.(key),
+		dispatchPaste: (text) => renderer.dispatchPaste?.(text),
+		dispatchResize: (width, height) => renderer.dispatchResize?.(width, height),
+		getInfo: () => ({
+			pid: process.pid,
+			width: renderer.width,
+			height: renderer.height,
+		}),
+	}
+
+	// Build and run the server layer
+	const serverLayer = makeServerLayer(session, actualPath)
+
+	// Use Effect runtime to manage the server lifecycle
+	let scope: Scope.CloseableScope | null = null
+
+	Effect.runPromise(
+		Effect.gen(function* () {
+			scope = yield* Scope.make()
+			yield* Layer.buildWithScope(serverLayer, scope)
+		}),
+	).catch((err) => {
+		console.error("[effect-tui] Remote server error:", err)
+	})
+
+	// Ensure socket cleanup on process exit (Effect finalizers may not run on abrupt exit)
+	const cleanupSocket = () => {
+		try {
+			if (fs.existsSync(actualPath)) {
+				fs.unlinkSync(actualPath)
+			}
+		} catch {
+			// Ignore cleanup errors
+		}
+	}
+
+	// "exit" event fires synchronously on any exit (normal, SIGINT, SIGTERM, etc.)
+	process.on("exit", cleanupSocket)
+
+	return () => {
+		process.off("exit", cleanupSocket)
+		cleanupSocket()
+		if (scope) {
+			Effect.runPromise(Scope.close(scope, Exit.void))
+		}
+	}
+}
+
+/**
+ * Check if remote control should be enabled (via EFFECT_TUI_REMOTE=1 env var)
+ */
+export function shouldEnableRemote(): boolean {
+	return process.env.EFFECT_TUI_REMOTE === "1"
+}

package/src/renderer/core/FrameBuilder.ts

@@ -0,0 +1,49 @@
+import { performance } from "node:perf_hooks"
+import type { CellBuffer, Palette } from "@effect-tui/core"
+import type { HostInstance } from "../../reconciler/types.js"
+import * as Prof from "../../profiler.js"
+
+export interface FrameTimings {
+	clear: number
+	layout: number
+	render: number
+}
+
+/**
+ * Handles the measure → layout → render pipeline for a single frame.
+ */
+export class FrameBuilder {
+	/**
+	 * Execute the frame pipeline: clear buffer, measure, layout, and render.
+	 * Returns timing information for each phase.
+	 */
+	build(root: HostInstance, buffer: CellBuffer, palette: Palette, width: number, height: number): FrameTimings {
+		// Clear buffer
+		let t = Prof.startPhase()
+		const clearStart = performance.now()
+		buffer.clear(0)
+		const clearMs = performance.now() - clearStart
+		Prof.endPhase("clear", t)
+
+		// Layout (measure + position)
+		t = Prof.startPhase()
+		const layoutStart = performance.now()
+		root.measure(width, height)
+		root.layout({ x: 0, y: 0, w: width, h: height })
+		const layoutMs = performance.now() - layoutStart
+		Prof.endPhase("layout", t)
+
+		// Render
+		t = Prof.startPhase()
+		const renderStart = performance.now()
+		root.render(buffer, palette)
+		const renderMs = performance.now() - renderStart
+		Prof.endPhase("render", t)
+
+		return {
+			clear: clearMs,
+			layout: layoutMs,
+			render: renderMs,
+		}
+	}
+}

package/src/renderer/core/RendererState.ts

@@ -0,0 +1,80 @@
+import { CellBuffer, Palette } from "@effect-tui/core"
+
+/**
+ * Mutable state for the renderer.
+ * Centralized to make state management explicit and easier to track.
+ */
+export class RendererState {
+	// Dimensions
+	width: number
+	height: number
+	lastWidth: number
+
+	// Rendering flags
+	dirty = true
+	running = true
+
+	// Buffers (double-buffered for diffing)
+	prevBuffer: CellBuffer | null = null
+	nextBuffer: CellBuffer | null = null
+	readonly palette = new Palette()
+
+	// Loop handle
+	loop: ReturnType<typeof setInterval> | null = null
+
+	// Event handler references for cleanup
+	inputHandler: ((data: Buffer) => void) | null = null
+	resizeHandler: (() => void) | null = null
+
+	constructor(width: number, height: number) {
+		this.width = width
+		this.height = height
+		this.lastWidth = width
+	}
+
+	/**
+	 * Ensure buffers exist and are correctly sized.
+	 * Call this at the start of each frame.
+	 */
+	ensureBuffers(width: number, height: number): void {
+		if (!this.prevBuffer || !this.nextBuffer || this.prevBuffer.w !== width || this.prevBuffer.h !== height) {
+			this.prevBuffer = new CellBuffer(width, height)
+			this.nextBuffer = new CellBuffer(width, height)
+			this.prevBuffer.clear(0)
+			this.nextBuffer.clear(0)
+		}
+	}
+
+	/**
+	 * Swap prev and next buffers after rendering.
+	 */
+	swapBuffers(): void {
+		const tmp = this.prevBuffer
+		this.prevBuffer = this.nextBuffer
+		this.nextBuffer = tmp
+	}
+
+	/**
+	 * Invalidate buffers (e.g., on resize).
+	 */
+	invalidateBuffers(): void {
+		this.prevBuffer = null
+		this.nextBuffer = null
+	}
+
+	/**
+	 * Mark as needing render.
+	 */
+	markDirty(): void {
+		this.dirty = true
+	}
+
+	/**
+	 * Update dimensions.
+	 */
+	updateDimensions(width: number, height: number): void {
+		this.width = width
+		this.height = height
+		this.lastWidth = width
+	}
+}

package/src/renderer/core/index.ts

@@ -0,0 +1,2 @@
+export { FrameBuilder, type FrameTimings } from "./FrameBuilder.js"
+export { RendererState } from "./RendererState.js"

package/src/renderer/input/InputProcessor.ts

@@ -0,0 +1,94 @@
+import { decodeInput, ANSI, type KeyMsg, type MouseMsg } from "@effect-tui/core"
+
+export interface InputProcessorConfig {
+	exitOnCtrlC: boolean
+	dispatchKey: (key: KeyMsg) => boolean // Returns true if event was handled (preventDefault called)
+	dispatchMouse: (mouse: MouseMsg) => void
+	dispatchPaste: (text: string) => void
+	flushSync: <T>(fn: () => T) => T
+	onInputProcessed: () => void
+}
+
+/**
+ * Processes raw terminal input, handling keyboard, mouse, and bracketed paste.
+ */
+export class InputProcessor {
+	private pasteActive = false
+	private pasteBuffer = ""
+
+	constructor(private config: InputProcessorConfig) {}
+
+	/**
+	 * Process incoming data from stdin.
+	 * Handles bracketed paste detection, key/mouse event decoding, and dispatch.
+	 */
+	process(data: Buffer): void {
+		let chunk = data.toString("utf8")
+
+		while (chunk.length > 0) {
+			if (this.pasteActive) {
+				const endIdx = chunk.indexOf(ANSI.paste.endMarker)
+				if (endIdx >= 0) {
+					this.pasteBuffer += chunk.slice(0, endIdx)
+					this.config.dispatchPaste(this.pasteBuffer)
+					this.pasteBuffer = ""
+					this.pasteActive = false
+					chunk = chunk.slice(endIdx + ANSI.paste.endMarker.length)
+					continue
+				} else {
+					this.pasteBuffer += chunk
+					chunk = ""
+					break
+				}
+			}
+
+			const startIdx = chunk.indexOf(ANSI.paste.startMarker)
+			if (startIdx >= 0) {
+				// Emit any input before the paste start
+				this.emitInput(chunk.slice(0, startIdx))
+				this.pasteActive = true
+				this.pasteBuffer = ""
+				chunk = chunk.slice(startIdx + ANSI.paste.startMarker.length)
+				continue
+			}
+
+			// No paste markers; treat as normal input
+			this.emitInput(chunk)
+			chunk = ""
+		}
+
+		// Notify that input processing is complete
+		this.config.onInputProcessed()
+	}
+
+	private emitInput(str: string): void {
+		if (!str) return
+		const events = decodeInput(Buffer.from(str, "utf8"))
+
+		for (const event of events) {
+			if (event.type === "mouse") {
+				this.config.flushSync(() => {
+					this.config.dispatchMouse(event)
+				})
+			} else {
+				const wrapped: KeyMsg = {
+					...event,
+					defaultPrevented: false,
+					preventDefault() {
+						wrapped.defaultPrevented = true
+					},
+				}
+
+				this.config.flushSync(() => {
+					this.config.dispatchKey(wrapped)
+				})
+
+				// Default Ctrl+C handling - exit unless user called preventDefault()
+				// Only match Ctrl+C (not Ctrl+Shift+C which should be available for copy)
+				if (this.config.exitOnCtrlC && !wrapped.defaultPrevented && event.ctrl && !event.shift && event.text === "c") {
+					process.exit(0)
+				}
+			}
+		}
+	}
+}

package/src/renderer/input/index.ts

@@ -0,0 +1 @@
+export { InputProcessor, type InputProcessorConfig } from "./InputProcessor.js"

package/src/renderer/lifecycle/EventBus.ts

@@ -0,0 +1,90 @@
+import type { KeyMsg, MouseMsg } from "@effect-tui/core"
+import type { FrameStats } from "../../renderer-types.js"
+
+/**
+ * Centralized event subscription management for the renderer.
+ * Provides type-safe subscription methods with automatic cleanup.
+ */
+export class EventBus {
+	private keyHandlers = new Set<(key: KeyMsg) => void>()
+	private mouseHandlers = new Set<(mouse: MouseMsg) => void>()
+	private pasteHandlers = new Set<(text: string) => void>()
+	private resizeHandlers = new Set<(width: number, height: number) => void>()
+	private frameHandlers = new Set<(stats: FrameStats) => void>()
+
+	onKey(handler: (key: KeyMsg) => void): () => void {
+		this.keyHandlers.add(handler)
+		return () => this.keyHandlers.delete(handler)
+	}
+
+	onMouse(handler: (mouse: MouseMsg) => void): () => void {
+		this.mouseHandlers.add(handler)
+		return () => this.mouseHandlers.delete(handler)
+	}
+
+	onPaste(handler: (text: string) => void): () => void {
+		this.pasteHandlers.add(handler)
+		return () => this.pasteHandlers.delete(handler)
+	}
+
+	onResize(handler: (width: number, height: number) => void): () => void {
+		this.resizeHandlers.add(handler)
+		return () => this.resizeHandlers.delete(handler)
+	}
+
+	onFrameStats(handler: (stats: FrameStats) => void): () => void {
+		this.frameHandlers.add(handler)
+		return () => this.frameHandlers.delete(handler)
+	}
+
+	/**
+	 * Dispatch a key event to all handlers.
+	 * Stops early if preventDefault is called.
+	 */
+	dispatchKey(key: KeyMsg): void {
+		for (const handler of this.keyHandlers) {
+			if (key.defaultPrevented) break
+			handler(key)
+		}
+	}
+
+	/**
+	 * Dispatch a mouse event to all handlers.
+	 */
+	dispatchMouse(mouse: MouseMsg): void {
+		for (const handler of this.mouseHandlers) {
+			handler(mouse)
+		}
+	}
+
+	/**
+	 * Dispatch a paste event to all handlers.
+	 */
+	dispatchPaste(text: string): void {
+		for (const handler of this.pasteHandlers) {
+			handler(text)
+		}
+	}
+
+	/**
+	 * Dispatch a resize event to all handlers.
+	 */
+	dispatchResize(width: number, height: number): void {
+		for (const handler of this.resizeHandlers) {
+			handler(width, height)
+		}
+	}
+
+	/**
+	 * Dispatch frame stats to all handlers.
+	 */
+	dispatchFrame(stats: FrameStats): void {
+		for (const handler of this.frameHandlers) {
+			handler(stats)
+		}
+	}
+
+	get hasFrameHandlers(): boolean {
+		return this.frameHandlers.size > 0
+	}
+}

package/src/renderer/lifecycle/ResizeManager.ts

@@ -0,0 +1,65 @@
+import type { TuiWriteStream } from "../../renderer-types.js"
+
+export interface ResizeState {
+	width: number
+	height: number
+	lastWidth: number
+	previousHeight: number // For inline mode
+	inlineClearHeight: number
+}
+
+export interface ResizeResult {
+	newWidth: number
+	newHeight: number
+	needsFullClear: boolean // Fullscreen mode
+	inlineClearHeight: number // Inline mode
+}
+
+/**
+ * Handles terminal resize events and calculates necessary clear/redraw actions.
+ */
+export class ResizeManager {
+	constructor(
+		private stdout: TuiWriteStream,
+		private mode: "fullscreen" | "inline",
+	) {}
+
+	/**
+	 * Process a resize event and determine what actions are needed.
+	 */
+	handleResize(currentState: ResizeState): ResizeResult {
+		const newWidth = this.stdout.columns || 80
+		const newHeight = this.stdout.rows || 24
+
+		let needsFullClear = false
+		let inlineClearHeight = currentState.inlineClearHeight
+
+		if (this.mode === "fullscreen") {
+			// Fullscreen: defer clear to renderFrame so it's written atomically with content
+			needsFullClear = true
+		} else if (newWidth !== currentState.lastWidth || newHeight !== currentState.height) {
+			// Inline: on dimension change, request clear on next render
+			const clearHeight = Math.max(currentState.previousHeight, currentState.height, newHeight)
+			if (clearHeight > inlineClearHeight) {
+				inlineClearHeight = clearHeight
+			}
+		}
+
+		return {
+			newWidth,
+			newHeight,
+			needsFullClear,
+			inlineClearHeight,
+		}
+	}
+
+	/**
+	 * Get current terminal dimensions.
+	 */
+	getDimensions(): { width: number; height: number } {
+		return {
+			width: this.stdout.columns || 80,
+			height: this.stdout.rows || 24,
+		}
+	}
+}