@effect-tui/react 0.15.2 → 2.0.0

package/src/dev.tsx

@@ -1,463 +1,10 @@
 /**
  * Development utilities for hot module replacement (HMR).
- *
  * Use render(..., { dev: true, importMeta: import.meta }) to enable HMR.
- *
- * Enables hot reload during development:
- * - File changes trigger re-render without process restart
- * - Terminal stays stable (no screen flash)
- * - State preserved when using Effect's globalValue with effect-atom
- * - Debug console panel (` to toggle, ~ for screenshot)
- * - Remote control when EFFECT_TUI_REMOTE=1
  */
 
-import { readFileSync } from "node:fs"
-import { stat } from "node:fs/promises"
-import { dirname } from "node:path"
-import { Colors } from "@effect-tui/core"
-import * as watcher from "@parcel/watcher"
-import { globalValue } from "effect/GlobalValue"
-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 { DiagnosticsPanel } from "./debug/DiagnosticsPanel.js"
-import { ToastContainer, ToastProvider, useToast } from "./dev/Toast.js"
-import { useKeyboard } from "./hooks/use-keyboard.js"
-import { enableRemote } from "./remote/index.js"
-import { useRenderer, useTerminalSize } from "./renderer-context.js"
-import type { RendererOptions, TuiRenderer } from "./renderer-types.js"
-
-/**
- * Pipeable combinator that makes an atom persist across hot reloads.
- *
- * This is the cleanest way to define HMR-persistent atoms - just pipe it!
- * Combines globalValue (for persistence) + keepAlive (prevents registry cleanup).
- *
- * @example
- * ```tsx
- * import { Atom } from "@effect-atom/atom-react"
- * import { hmr, render } from "@effect-tui/react"
- *
- * // Just pipe hmr() - that's it!
- * const countAtom = Atom.make(0).pipe(hmr("count"))
- * const userAtom = Atom.make<User | null>(null).pipe(hmr("user"))
- *
- * export default function App() {
- *   const count = useAtomValue(countAtom)
- *   // Edit this file - count persists!
- * }
- *
- * render(<App />, { dev: true, importMeta: import.meta })
- * ```
- */
-export function hmr(key: string): <A,>(self: A) => A {
-	return <A,>(self: A): A => {
-		return globalValue(Symbol.for(`hmr/${key}`), () => {
-			// Apply keepAlive if it's an atom (just sets keepAlive: true)
-			if (typeof self === "object" && self !== null && "keepAlive" in self) {
-				return Object.assign(Object.create(Object.getPrototypeOf(self)), {
-					...self,
-					keepAlive: true,
-				})
-			}
-			return self
-		}) as A
-	}
-}
-
-/**
- * Wrap any value creation in HMR persistence.
- *
- * @example
- * ```tsx
- * const countAtom = hmrState("count", () => Atom.make(0).pipe(Atom.keepAlive))
- * ```
- */
-export function hmrState<T>(key: string, create: () => T): T {
-	return globalValue(Symbol.for(`hmr/${key}`), create)
-}
-
-// Cache for runtime key extraction
-const keyCache = new Map<string, string>()
-
-/**
- * Parse stack trace to get file path and line number.
- * Returns null if parsing fails.
- */
-function parseStack(stack: string): { file: string; line: number; col: number } | null {
-	// Bun stack format: "    at functionName (file:line:col)" or "    at file:line:col"
-	const lines = stack.split("\n")
-	// Skip first line (Error message) and find caller (skip autoHmr itself)
-	for (let i = 2; i < lines.length; i++) {
-		const match = lines[i].match(/\((.+?):(\d+):(\d+)\)/) || lines[i].match(/at\s+(.+?):(\d+):(\d+)/)
-		if (match) {
-			return { file: match[1], line: parseInt(match[2], 10), col: parseInt(match[3], 10) }
-		}
-	}
-	return null
-}
-
-/**
- * Extract variable name from source line using regex.
- * Returns null if extraction fails.
- */
-function extractVarName(source: string, line: number): string | null {
-	const lines = source.split("\n")
-	if (line < 1 || line > lines.length) return null
-
-	const sourceLine = lines[line - 1]
-	const match = sourceLine.match(/(?:export\s+)?(?:const|let|var)\s+(\w+)\s*=/)
-	return match?.[1] ?? null
-}
-
-/**
- * Auto-keyed HMR persistence for atoms.
- *
- * When used with the HMR plugin (recommended), keys are injected at load time
- * based on the variable name. Without the plugin, falls back to runtime
- * stack trace parsing.
- *
- * @example
- * ```tsx
- * import { Atom } from "@effect-atom/atom-react"
- * import { autoHmr, render } from "@effect-tui/react"
- *
- * // No manual key needed - derived from variable name!
- * const countAtom = Atom.make(0).pipe(autoHmr)
- * const userAtom = Atom.make<User | null>(null).pipe(autoHmr)
- *
- * // To enable compile-time transform (faster, more reliable):
- * // bun --preload @effect-tui/react/hmr-plugin run src/app.tsx
- * ```
- */
-export function autoHmr<A>(self: A): A {
-	// Get stack trace for caller location
-	const stack = new Error().stack ?? ""
-	const location = parseStack(stack)
-
-	if (!location) {
-		// Fallback: use a hash of the stack trace
-		const fallbackKey = `unknown:${stack.slice(0, 100)}`
-		return hmr(fallbackKey)(self)
-	}
-
-	const cacheKey = `${location.file}:${location.line}:${location.col}`
-
-	// Check cache first
-	let key = keyCache.get(cacheKey)
-	if (!key) {
-		try {
-			// Read source file and extract variable name
-			const source = readFileSync(location.file, "utf-8")
-			const varName = extractVarName(source, location.line)
-			key = `${location.file}:${varName ?? `line${location.line}`}`
-		} catch {
-			// File read failed, use line-based key
-			key = `${location.file}:line${location.line}`
-		}
-		keyCache.set(cacheKey, key)
-	}
-
-	return hmr(key)(self)
-}
-
-export interface DevOptions {
-	/** Directories to watch (defaults to entry file's directory) */
-	watchDirs?: string[]
-	/** File extensions to watch (defaults to [".ts", ".tsx"]) */
-	watchExtensions?: string[]
-	/** Debounce delay in ms (defaults to 150) */
-	debounce?: number
-	/** Wait for file writes to stabilize (defaults to 50ms) */
-	awaitWriteFinish?: number
-	/** Called before each hot reload */
-	onReload?: () => void
-	/** Called on errors */
-	onError?: (error: Error) => void
-	/** Show renderer diagnostics overlay. */
-	showStats?: boolean
-	/** Sampling window for renderer stats (ms). */
-	statsSampleMs?: number
-	/** Override diagnostics panel title. */
-	statsTitle?: string
-}
-
-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>
-}
-
-/**
- * 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))
-	}
-}
-
-/**
- * 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
-}
-
-/**
- * Overlay for renderer diagnostics stats.
- */
-function StatsOverlay({ sampleMs, title }: { sampleMs?: number; title?: string }) {
-	const { width, height } = useTerminalSize()
-
-	return (
-		<vstack width={width} height={height}>
-			<hstack width={width}>
-				<spacer />
-				<box padding={1} border="rounded" borderColor={Colors.ansi.gray(8)} bg={Colors.ansi.gray(2)}>
-					<DiagnosticsPanel sampleMs={sampleMs} title={title ?? "Renderer Stats"} />
-				</box>
-			</hstack>
-			<spacer />
-		</vstack>
-	)
-}
-
-export interface DevWrapperProps {
-	children?: React.ReactNode
-	showStats?: boolean
-	statsSampleMs?: number
-	statsTitle?: string
-	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
- * - Optional renderer stats overlay (showStats)
- *
- * Use this to wrap your app when you need dev UI features without the dev runtime
- * (e.g., when you need to pass props or load the app manually).
- */
-export function DevWrapper({
-	children,
-	showStats,
-	statsSampleMs,
-	statsTitle,
-	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" />}
-				</vstack>
-			</ToastProvider>
-		)
-	}
-
-	// Fullscreen mode: Overlay with toast/console positioned by alignment
-	return (
-		<ToastProvider>
-			<Overlay>
-				{/* Base - determines container size */}
-
-				<ScreenshotHandler />
-				{children}
-
-				{/* Overlays */}
-				{visible && (
-					<Overlay.Item alignment={{ v: "bottom" }}>
-						<ConsolePopover fixedHeight={12} />
-					</Overlay.Item>
-				)}
-				{showStats && (
-					<Overlay.Item alignment={{ v: "top", h: "right" }}>
-						<StatsOverlay sampleMs={statsSampleMs} title={statsTitle} />
-					</Overlay.Item>
-				)}
-				<Overlay.Item alignment={{ v: "top" }}>
-					<ToastContainer />
-				</Overlay.Item>
-			</Overlay>
-		</ToastProvider>
-	)
-}
-
-type DevRoot = {
-	render(element: React.ReactNode, sync?: boolean): void
-}
-
-export function startDevRuntime(
-	entryPath: string,
-	renderer: TuiRenderer,
-	root: DevRoot,
-	options?: DevOptions & { mode?: RendererOptions["mode"] },
-): DevRuntime {
-	const watchExtensions = options?.watchExtensions ?? [".ts", ".tsx"]
-	const debounceMs = options?.debounce ?? 150
-	const stabilityMs = options?.awaitWriteFinish ?? 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 = options?.watchDirs?.[0] ?? 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 panel
-			const appElement = typeof App === "function" ? React.createElement(App) : App
-			const wrapped = React.createElement(
-				DevWrapper,
-				{
-					showStats: options?.showStats,
-					statsSampleMs: options?.statsSampleMs,
-					statsTitle: options?.statsTitle,
-					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 }
-}
+export { hmr, hmrState, autoHmr } from "./internal/dev/hmr.js"
+export { DevWrapper } from "./internal/dev/ui.js"
+export type { DevWrapperProps } from "./internal/dev/ui.js"
+export { startDevRuntime } from "./internal/dev/runtime.js"
+export type { DevOptions, DevRuntime } from "./internal/dev/runtime.js"