@effect-tui/react 0.1.3 → 0.1.5

package/src/debug/DiagnosticsPanel.tsx

@@ -3,36 +3,36 @@ import { useFrameStats } from "../hooks/useFrameStats.js"
 import "../jsx.js"
 
 export interface DiagnosticsPanelProps {
-  sampleMs?: number
-  title?: string
+	sampleMs?: number
+	title?: string
 }
 
 export function DiagnosticsPanel({ sampleMs = 200, title = "Diagnostics" }: DiagnosticsPanelProps) {
-  const stats = useFrameStats(sampleMs)
+	const stats = useFrameStats(sampleMs)
 
-  const fps = stats ? (stats.frameMs > 0 ? (1000 / stats.frameMs).toFixed(1) : "∞") : "—"
-  const bytes = stats ? stats.bytes : 0
-  const h = stats ? stats.contentHeight : 0
-  const phases = stats?.phases
+	const fps = stats ? (stats.frameMs > 0 ? (1000 / stats.frameMs).toFixed(1) : "∞") : "—"
+	const bytes = stats ? stats.bytes : 0
+	const h = stats ? stats.contentHeight : 0
+	const phases = stats?.phases
 
-  return (
-    <vstack spacing={1}>
-      <text fg={Colors.cyan} bold>
-        {title} ({stats?.mode ?? "?"})
-      </text>
-      {stats ? (
-        <>
-          <text fg={Colors.gray(12)}>
-            size {stats.width}×{stats.height} content {h} rows — {bytes} bytes/frame — {fps} fps
-          </text>
-          <text fg={Colors.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>
-      )}
-    </vstack>
-  )
+	return (
+		<vstack spacing={1}>
+			<text fg={Colors.cyan} bold>
+				{title} ({stats?.mode ?? "?"})
+			</text>
+			{stats ? (
+				<>
+					<text fg={Colors.gray(12)}>
+						size {stats.width}×{stats.height} content {h} rows — {bytes} bytes/frame — {fps} fps
+					</text>
+					<text fg={Colors.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>
+			)}
+		</vstack>
+	)
 }

package/src/dev/Toast.tsx

@@ -0,0 +1,117 @@
+// Toast notification system for dev mode
+// Beautiful, minimal notifications that appear at the top of the screen
+
+import { useState, useCallback, createContext, useContext, type ReactNode } from "react"
+import { Colors } from "@effect-tui/core"
+import { useTerminalSize } from "../renderer-context.js"
+
+// ─────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────
+
+export type ToastType = "success" | "info" | "warning" | "error"
+
+export interface Toast {
+	id: number
+	message: string
+	type: ToastType
+}
+
+export interface ToastContextValue {
+	toasts: Toast[]
+	show: (message: string, type?: ToastType, durationMs?: number) => void
+	dismiss: (id: number) => void
+}
+
+// ─────────────────────────────────────────────────────────────
+// Context
+// ─────────────────────────────────────────────────────────────
+
+const ToastContext = createContext<ToastContextValue | null>(null)
+
+export function useToast(): ToastContextValue {
+	const ctx = useContext(ToastContext)
+	if (!ctx) {
+		throw new Error("useToast must be used within a ToastProvider")
+	}
+	return ctx
+}
+
+// ─────────────────────────────────────────────────────────────
+// Styling
+// ─────────────────────────────────────────────────────────────
+
+const TOAST_STYLES: Record<ToastType, { bg: ReturnType<typeof Colors.rgb>; fg: ReturnType<typeof Colors.rgb>; icon: string }> = {
+	success: { bg: Colors.rgb(30, 70, 40), fg: Colors.rgb(140, 230, 140), icon: "✓" },
+	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: "✗" },
+}
+
+// ─────────────────────────────────────────────────────────────
+// Provider
+// ─────────────────────────────────────────────────────────────
+
+let toastId = 0
+
+export function ToastProvider({ children }: { children: ReactNode }) {
+	const [toasts, setToasts] = useState<Toast[]>([])
+
+	const show = useCallback((message: string, type: ToastType = "info", durationMs = 2000) => {
+		const id = ++toastId
+		setToasts((prev) => [...prev, { id, message, type }])
+
+		setTimeout(() => {
+			setToasts((prev) => prev.filter((t) => t.id !== id))
+		}, durationMs)
+	}, [])
+
+	const dismiss = useCallback((id: number) => {
+		setToasts((prev) => prev.filter((t) => t.id !== id))
+	}, [])
+
+	return (
+		<ToastContext.Provider value={{ toasts, show, dismiss }}>
+			{children}
+		</ToastContext.Provider>
+	)
+}
+
+// ─────────────────────────────────────────────────────────────
+// 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]
+	const style = TOAST_STYLES[toast.type]
+
+	// Center the message with padding
+	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
+	return (
+		<text bg={style.bg} fg={style.fg}>
+			{paddedContent}
+		</text>
+	)
+}
+
+// ─────────────────────────────────────────────────────────────
+// Convenience hook for screenshot toast
+// ─────────────────────────────────────────────────────────────
+
+export function useScreenshotToast() {
+	const { show } = useToast()
+
+	return useCallback((path: string) => {
+		show(`Screenshot saved: ${path}`, "success", 2500)
+	}, [show])
+}

package/src/dev/index.ts

@@ -0,0 +1,2 @@
+// Dev mode utilities
+export { ToastProvider, ToastContainer, useToast, useScreenshotToast, type Toast, type ToastType } from "./Toast.js"

package/src/dev.tsx

@@ -0,0 +1,489 @@
+/**
+ * Development utilities for hot module replacement (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 { globalValue } from "effect/GlobalValue"
+import * as watcher from "@parcel/watcher"
+import { dirname } from "path"
+import { stat } from "fs/promises"
+import { readFileSync } from "fs"
+import React from "react"
+import { Colors } from "@effect-tui/core"
+import { createRenderer, createRoot, type Root } from "./renderer.js"
+import type { RendererOptions } from "./renderer-types.js"
+import type { TuiRenderer } from "./renderer-types.js"
+import { ConsolePopover } from "./console/ConsolePopover.js"
+import { useConsole } from "./console/useConsole.js"
+import { enableRemote } from "./remote/index.js"
+import { ToastProvider, ToastContainer, useToast } from "./dev/Toast.js"
+import { useKeyboard } from "./hooks/use-keyboard.js"
+import { useRenderer, useTerminalSize } from "./renderer-context.js"
+import { copyToClipboardSync, copyToClipboard } from "./console/clipboard.js"
+import { DiagnosticsPanel } from "./debug/DiagnosticsPanel.js"
+import { Overlay } from "./components/Overlay.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, devRender } 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!
+ * }
+ * ```
+ */
+export function hmr<A>(key: string): (self: A) => A {
+	return (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)
+}
+
+/**
+ * Simple self-running dev mode. Just add this at the bottom of your file:
+ *
+ * @example
+ * ```tsx
+ * export default function App() { ... }
+ *
+ * devMain(import.meta)
+ * ```
+ *
+ * That's it! Handles:
+ * - Only runs when file is the entry point (import.meta.main)
+ * - Only initializes once across HMR reloads
+ * - Automatically finds the file path
+ */
+export function devMain(importMeta: { main?: boolean; url: string }, options?: Omit<DevRenderOptions, never>): void {
+	// Skip if not main entry point
+	if (!importMeta.main) return
+
+	// Skip if this is a HMR re-import (has cache-busting query string)
+	if (importMeta.url.includes("?")) return
+
+	const key = `devMain/${importMeta.url}`
+	const initialized = hmrState(key, () => ({ done: false }))
+
+	if (!initialized.done) {
+		initialized.done = true
+		const filePath = new URL(importMeta.url).pathname
+		devRender(filePath, options)
+	}
+}
+
+// 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, devRender } 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<A>(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<A>(key)(self)
+}
+
+export interface DevRenderOptions extends RendererOptions {
+	/** 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 DevRenderResult {
+	renderer: TuiRenderer
+	root: Root
+	/** Manually trigger a reload */
+	rerender: () => Promise<void>
+	/** Stop watching and cleanup */
+	stop: () => Promise<void>
+}
+
+/**
+ * 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))
+	}
+}
+
+/**
+ * Render a TUI app with hot module replacement support.
+ *
+ * Uses @parcel/watcher for reliable, cross-platform file watching.
+ * When files change, the module is re-imported and the app re-renders
+ * without restarting the process or tearing down the terminal.
+ *
+ * For state preservation, use effect-atom with the hmr() combinator:
+ *
+ * @example
+ * ```tsx
+ * import { Atom, useAtomValue } from "@effect-atom/atom-react"
+ * import { hmr, devRender } from "@effect-tui/react"
+ *
+ * const countAtom = Atom.make(0).pipe(hmr("count"))
+ *
+ * export default function App() {
+ *   const count = useAtomValue(countAtom)
+ *   return <text>Count: {count}</text>
+ * }
+ *
+ * devRender(import.meta.path, { mode: "inline" })
+ * ```
+ */
+/**
+ * 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!", "success", 1500)
+			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.gray(8)} bg={Colors.gray(2)}>
+					<DiagnosticsPanel sampleMs={sampleMs} title={title ?? "Renderer Stats"} />
+				</box>
+			</hstack>
+			<spacer />
+		</vstack>
+	)
+}
+
+/**
+ * Internal 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)
+ */
+function DevWrapper({
+	children,
+	showStats,
+	statsSampleMs,
+	statsTitle,
+	mode,
+}: {
+	children?: React.ReactNode
+	showStats?: boolean
+	statsSampleMs?: number
+	statsTitle?: string
+	mode?: "fullscreen" | "inline"
+}) {
+	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>
+	)
+}
+
+export async function devRender(entryPath: string, options?: DevRenderOptions): Promise<DevRenderResult> {
+	const watchExtensions = options?.watchExtensions ?? [".ts", ".tsx"]
+	const debounceMs = options?.debounce ?? 150
+	const stabilityMs = options?.awaitWriteFinish ?? 50
+
+	const renderer = createRenderer(options)
+	const root = createRoot(renderer)
+
+	// Dev mode always enables remote control
+	const stopRemote = enableRemote(renderer)
+
+	let debounceTimer: ReturnType<typeof setTimeout> | null = null
+	let version = 0
+	let subscription: watcher.AsyncSubscription | null = null
+
+	// Import and render the module
+	const render = async () => {
+		const thisVersion = ++version
+
+		try {
+			// 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("[devRender]", 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("[devRender] Error loading module:", error.message)
+		}
+	}
+
+	// Initial render
+	await render()
+
+	// Watch for changes using @parcel/watcher
+	const watchDir = options?.watchDirs?.[0] ?? dirname(entryPath)
+
+	try {
+		subscription = await watcher.subscribe(watchDir, async (err, events) => {
+			if (err) {
+				options?.onError?.(err)
+				console.error("[devRender] 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 render()
+			}, debounceMs)
+		})
+	} catch (err) {
+		console.error(`[devRender] Failed to watch ${watchDir}:`, err)
+	}
+
+	const stop = async () => {
+		if (debounceTimer) clearTimeout(debounceTimer)
+		if (subscription) {
+			await subscription.unsubscribe()
+		}
+		stopRemote()
+		renderer.stop()
+	}
+
+	return { renderer, root, rerender: render, stop }
+}