@effect-tui/react 0.15.2 → 0.16.0

package/src/internal/dev/runtime.ts

@@ -0,0 +1,170 @@
+import { stat } from "node:fs/promises"
+import { dirname } from "node:path"
+import * as watcher from "@parcel/watcher"
+import React from "react"
+import { enableRemote } from "../../remote/index.js"
+import { DevWrapper } from "./ui.js"
+import type { RendererOptions, TuiRenderer } from "../renderer/types.js"
+
+export interface DevOptions {
+	/** Called before each hot reload */
+	onReload?: () => void
+	/** Called on errors */
+	onError?: (error: Error) => void
+}
+
+export interface DevRuntime {
+	/** Promise that resolves after the first render + watcher setup. */
+	ready: Promise<void>
+	/** Manually trigger a reload. */
+	reload: () => Promise<void>
+	/** Stop watching and cleanup. */
+	stop: () => Promise<void>
+}
+
+type DevRoot = {
+	render(element: React.ReactNode, sync?: boolean): void
+}
+
+/**
+ * Clear require.cache for project files to ensure fresh imports.
+ * Bun uses require.cache internally even for ESM modules.
+ * This is necessary because query-string cache-busting only affects
+ * the entry point, not transitive dependencies.
+ */
+function clearProjectCache(projectRoot: string): void {
+	for (const file of Object.keys(require.cache)) {
+		if (file.startsWith(projectRoot) && !file.includes("node_modules")) {
+			delete require.cache[file]
+		}
+	}
+}
+
+/**
+ * Wait for a file to stabilize (no size changes) before proceeding.
+ * This avoids importing partially-written files.
+ */
+async function awaitWriteFinish(path: string, stabilityMs: number): Promise<void> {
+	let lastSize = -1
+	let stableCount = 0
+	const checkInterval = 10
+
+	while (stableCount < stabilityMs / checkInterval) {
+		try {
+			const stats = await stat(path)
+			if (stats.size === lastSize) {
+				stableCount++
+			} else {
+				lastSize = stats.size
+				stableCount = 0
+			}
+		} catch {
+			// File might be temporarily unavailable during write
+			stableCount = 0
+		}
+		await new Promise((r) => setTimeout(r, checkInterval))
+	}
+}
+
+export function startDevRuntime(
+	entryPath: string,
+	renderer: TuiRenderer,
+	root: DevRoot,
+	options?: DevOptions & { mode?: RendererOptions["mode"] },
+): DevRuntime {
+	const watchExtensions = [".ts", ".tsx"]
+	const debounceMs = 150
+	const stabilityMs = 50
+
+	// Dev mode always enables remote control with entry path for identification
+	const stopRemote = enableRemote(renderer, { entryPath })
+
+	let debounceTimer: ReturnType<typeof setTimeout> | null = null
+	let version = 0
+	let subscription: watcher.AsyncSubscription | null = null
+
+	// Determine project root for cache clearing
+	const projectRoot = dirname(entryPath)
+
+	const reload = async () => {
+		const thisVersion = ++version
+
+		try {
+			// Clear module cache for project files before re-importing
+			clearProjectCache(projectRoot)
+
+			// Cache-bust by adding query string with version
+			const mod = await import(`${entryPath}?v=${thisVersion}`)
+
+			// Skip if a newer render was triggered
+			if (thisVersion !== version) return
+
+			const App = mod.default
+
+			if (!App) {
+				const err = new Error(`No default export found in ${entryPath}`)
+				options?.onError?.(err)
+				console.error("[effect-tui] Dev render failed:", err.message)
+				return
+			}
+
+			// Render the component wrapped in DevWrapper for console + stats
+			const appElement = typeof App === "function" ? React.createElement(App) : App
+			const wrapped = React.createElement(
+				DevWrapper,
+				{
+					mode: options?.mode,
+				},
+				appElement,
+			)
+			root.render(wrapped)
+		} catch (err) {
+			const error = err instanceof Error ? err : new Error(String(err))
+			options?.onError?.(error)
+			console.error("[effect-tui] Dev render error:", error.message)
+		}
+	}
+
+	const ready = (async () => {
+		await reload()
+
+		try {
+			subscription = await watcher.subscribe(projectRoot, async (err, events) => {
+				if (err) {
+					options?.onError?.(err)
+					console.error("[effect-tui] Dev watcher error:", err)
+					return
+				}
+
+				// Filter to relevant file extensions
+				const relevantEvents = events.filter((event) => watchExtensions.some((ext) => event.path.endsWith(ext)))
+
+				if (relevantEvents.length === 0) return
+
+				// Debounce rapid changes
+				if (debounceTimer) clearTimeout(debounceTimer)
+				debounceTimer = setTimeout(async () => {
+					// Wait for file writes to stabilize
+					const changedPath = relevantEvents[0].path
+					await awaitWriteFinish(changedPath, stabilityMs)
+
+					options?.onReload?.()
+					await reload()
+				}, debounceMs)
+			})
+		} catch (err) {
+			console.error(`[effect-tui] Failed to watch ${projectRoot}:`, err)
+		}
+	})()
+
+	const stop = async () => {
+		if (debounceTimer) clearTimeout(debounceTimer)
+		if (subscription) {
+			await subscription.unsubscribe()
+		}
+		stopRemote()
+		renderer.stop()
+	}
+
+	return { ready, reload, stop }
+}

package/src/internal/dev/ui.tsx

@@ -0,0 +1,87 @@
+import React from "react"
+import { Overlay } from "../../components/Overlay.js"
+import { ConsolePopover } from "../../console/ConsolePopover.js"
+import { copyToClipboard, copyToClipboardSync } from "../../console/clipboard.js"
+import { useConsole } from "../../console/useConsole.js"
+import { ToastContainer, ToastProvider, useToast } from "../../dev/Toast.js"
+import { useKeyboard } from "../../hooks/use-keyboard.js"
+import { useRenderer } from "../renderer/context.js"
+
+/**
+ * Internal component that handles screenshot with toast notification
+ */
+function ScreenshotHandler() {
+	const renderer = useRenderer()
+	const { show } = useToast()
+
+	useKeyboard((key) => {
+		// ~ (tilde) - screenshot
+		if (key.name === "char" && key.text === "~") {
+			const ansiOutput = renderer.getScreenshot()
+			if (!ansiOutput) return
+
+			// Copy actual content to clipboard
+			const copied = copyToClipboardSync(ansiOutput)
+			if (!copied) {
+				copyToClipboard(ansiOutput)
+			}
+
+			// Also save to file as backup
+			const tmpPath = `/tmp/tui-screenshot-${Date.now()}.txt`
+			Bun.write(tmpPath, ansiOutput)
+
+			show("Screenshot copied!", "screenshot", 2500)
+			key.preventDefault?.()
+		}
+	})
+
+	return null
+}
+
+export interface DevWrapperProps {
+	children?: React.ReactNode
+	mode?: "fullscreen" | "inline"
+}
+
+/**
+ * Wrapper component that provides dev mode features:
+ * - Debug console panel (` backtick to toggle)
+ * - Screenshot support (~ tilde) with toast notification
+ * - Auto-show console on errors
+ */
+export function DevWrapper({ children, mode }: DevWrapperProps) {
+	const { visible } = useConsole({ autoShowOnError: true, initiallyVisible: false })
+
+	// Inline mode: content flows naturally in vstack
+	if (mode === "inline") {
+		return (
+			<ToastProvider>
+				<vstack>
+					<ScreenshotHandler />
+					<ToastContainer />
+					{children}
+					{visible && <ConsolePopover fixedHeight={5} mode="inline" showStatsTab />}
+				</vstack>
+			</ToastProvider>
+		)
+	}
+
+	// Fullscreen mode: Overlay with toast/console positioned by alignment
+	return (
+		<ToastProvider>
+			<Overlay>
+				<ScreenshotHandler />
+				{children}
+
+				{visible && (
+					<Overlay.Item alignment={{ v: "bottom" }}>
+						<ConsolePopover fixedHeight={12} showStatsTab />
+					</Overlay.Item>
+				)}
+				<Overlay.Item alignment={{ v: "top" }}>
+					<ToastContainer />
+				</Overlay.Item>
+			</Overlay>
+		</ToastProvider>
+	)
+}

package/src/internal/renderer/context.ts

@@ -0,0 +1,27 @@
+import { createContext, useContext, useEffect, useState } from "react"
+import type { TuiRenderer } from "./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 → internal/renderer}/core/FrameBuilder.ts

@@ -1,7 +1,7 @@
 import { performance } from "node:perf_hooks"
 import type { CellBuffer, Palette } from "@effect-tui/core"
-import * as Prof from "../../profiler.js"
-import type { HostInstance } from "../../reconciler/types.js"
+import * as Prof from "../../../profiler.js"
+import type { HostInstance } from "../../../reconciler/types.js"
 
 export interface FrameTimings {
 	clear: number