@effect-tui/react 0.12.3 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effect-tui/react",
-	"version": "0.12.3",
+	"version": "0.13.0",
 	"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.12.3",
+		"@effect-tui/core": "^0.13.0",
 		"@effect/platform": "^0.94.0",
 		"@effect/platform-bun": "^0.87.0",
 		"@effect/rpc": "^0.73.0",

package/src/dev.tsx

@@ -1,6 +1,8 @@
 /**
  * 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)
@@ -24,7 +26,6 @@ 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 { createRenderer, createRoot, type Root } from "./renderer.js"
 import { useRenderer, useTerminalSize } from "./renderer-context.js"
 import type { RendererOptions, TuiRenderer } from "./renderer-types.js"
 
@@ -37,7 +38,7 @@ import type { RendererOptions, TuiRenderer } from "./renderer-types.js"
  * @example
  * ```tsx
  * import { Atom } from "@effect-atom/atom-react"
- * import { hmr, devRender } from "@effect-tui/react"
+ * import { hmr, render } from "@effect-tui/react"
  *
  * // Just pipe hmr() - that's it!
  * const countAtom = Atom.make(0).pipe(hmr("count"))
@@ -47,6 +48,8 @@ import type { RendererOptions, TuiRenderer } from "./renderer-types.js"
  *   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 {
@@ -76,38 +79,6 @@ 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>()
 
@@ -151,7 +122,7 @@ function extractVarName(source: string, line: number): string | null {
  * @example
  * ```tsx
  * import { Atom } from "@effect-atom/atom-react"
- * import { autoHmr, devRender } from "@effect-tui/react"
+ * import { autoHmr, render } from "@effect-tui/react"
  *
  * // No manual key needed - derived from variable name!
  * const countAtom = Atom.make(0).pipe(autoHmr)
@@ -192,7 +163,7 @@ export function autoHmr<A>(self: A): A {
 	return hmr(key)(self)
 }
 
-export interface DevRenderOptions extends RendererOptions {
+export interface DevOptions {
 	/** Directories to watch (defaults to entry file's directory) */
 	watchDirs?: string[]
 	/** File extensions to watch (defaults to [".ts", ".tsx"]) */
@@ -213,12 +184,12 @@ export interface DevRenderOptions extends RendererOptions {
 	statsTitle?: string
 }
 
-export interface DevRenderResult {
-	renderer: TuiRenderer
-	root: Root
-	/** Manually trigger a reload */
-	rerender: () => Promise<void>
-	/** Stop watching and cleanup */
+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>
 }
 
@@ -262,30 +233,6 @@ async function awaitWriteFinish(path: string, stabilityMs: number): Promise<void
 	}
 }
 
-/**
- * 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
  */
@@ -351,8 +298,8 @@ export interface DevWrapperProps {
  * - Auto-show console on errors
  * - Optional renderer stats overlay (showStats)
  *
- * Use this to wrap your app when you need dev features but can't use devRender
- * (e.g., when you need to pass props to your App component).
+ * 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,
@@ -405,14 +352,20 @@ export function DevWrapper({
 	)
 }
 
-export async function devRender(entryPath: string, options?: DevRenderOptions): Promise<DevRenderResult> {
+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
 
-	const renderer = createRenderer(options)
-	const root = createRoot(renderer)
-
 	// Dev mode always enables remote control with entry path for identification
 	const stopRemote = enableRemote(renderer, { entryPath })
 
@@ -423,8 +376,7 @@ export async function devRender(entryPath: string, options?: DevRenderOptions):
 	// Determine project root for cache clearing
 	const projectRoot = options?.watchDirs?.[0] ?? dirname(entryPath)
 
-	// Import and render the module
-	const render = async () => {
+	const reload = async () => {
 		const thisVersion = ++version
 
 		try {
@@ -442,7 +394,7 @@ export async function devRender(entryPath: string, options?: DevRenderOptions):
 			if (!App) {
 				const err = new Error(`No default export found in ${entryPath}`)
 				options?.onError?.(err)
-				console.error("[devRender]", err.message)
+				console.error("[effect-tui] Dev render failed:", err.message)
 				return
 			}
 
@@ -462,41 +414,41 @@ export async function devRender(entryPath: string, options?: DevRenderOptions):
 		} catch (err) {
 			const error = err instanceof Error ? err : new Error(String(err))
 			options?.onError?.(error)
-			console.error("[devRender] Error loading module:", error.message)
+			console.error("[effect-tui] Dev render error:", error.message)
 		}
 	}
 
-	// Initial render
-	await render()
+	const ready = (async () => {
+		await reload()
 
-	// Watch for changes using @parcel/watcher
-	try {
-		subscription = await watcher.subscribe(projectRoot, 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 ${projectRoot}:`, err)
-	}
+		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)
@@ -507,5 +459,5 @@ export async function devRender(entryPath: string, options?: DevRenderOptions):
 		renderer.stop()
 	}
 
-	return { renderer, root, rerender: render, stop }
+	return { ready, reload, stop }
 }

package/src/hooks/index.ts

@@ -2,7 +2,10 @@ export type { UseKeyboardOptions } from "./use-keyboard.js"
 export { useKeyboard } from "./use-keyboard.js"
 export type { UseMouseOptions } from "./use-mouse.js"
 export { useMouse } from "./use-mouse.js"
+export type { UsePasteOptions } from "./use-paste.js"
 export { usePaste } from "./use-paste.js"
+export type { ShortcutHandler, ShortcutMap, UseShortcutOptions } from "./use-shortcut.js"
+export { useShortcut } from "./use-shortcut.js"
 export { useQuit } from "./use-quit.js"
 export type { ScrollState, UseScrollOptions, UseScrollReturn } from "./use-scroll.js"
 export { useScroll } from "./use-scroll.js"

package/src/hooks/use-mouse.ts

@@ -3,10 +3,19 @@ import { useEffect, useRef } from "react"
 import { useRenderer } from "../renderer.js"
 
 export type UseMouseOptions = {
-	/** Filter by action type */
+	/** Filter by action type (alias: phase) */
 	action?: "press" | "release" | "drag" | "move" | "any"
+	/** Filter by action type */
+	phase?: "press" | "release" | "drag" | "move" | "any"
 	/** Filter by button */
 	button?: MouseButton | MouseButton[]
+	/** Optional predicate to drop events before they reach the handler. */
+	filter?: (mouse: MouseMsg) => boolean
+	/**
+	 * If true, call preventDefault when available before invoking handler.
+	 * This stops further renderer-level handlers.
+	 */
+	stopPropagation?: boolean
 }
 
 /**
@@ -26,12 +35,16 @@ export type UseMouseOptions = {
  */
 export function useMouse(handler: (mouse: MouseMsg) => void, opts?: UseMouseOptions): void {
 	const renderer = useRenderer()
-	const action = opts?.action ?? "any"
+	const action = opts?.phase ?? opts?.action ?? "any"
 	const button = opts?.button
+	const filter = opts?.filter
+	const stopPropagation = opts?.stopPropagation ?? false
 
 	// Store handler in ref so we always call the latest version
 	const handlerRef = useRef(handler)
 	handlerRef.current = handler
+	const filterRef = useRef(filter)
+	filterRef.current = filter
 
 	useEffect(() => {
 		const wrapped = (mouse: MouseMsg) => {
@@ -44,8 +57,11 @@ export function useMouse(handler: (mouse: MouseMsg) => void, opts?: UseMouseOpti
 				if (!buttons.includes(mouse.button)) return
 			}
 
+			if (filterRef.current && !filterRef.current(mouse)) return
+			if (stopPropagation && mouse.preventDefault) mouse.preventDefault()
+
 			handlerRef.current(mouse)
 		}
 		return renderer.onMouse(wrapped)
-	}, [renderer, action, button])
+	}, [renderer, action, button, stopPropagation])
 }

package/src/hooks/use-paste.ts

@@ -1,6 +1,17 @@
 import { useEffect, useRef } from "react"
+import type { PasteMsg } from "../renderer-types.js"
 import { useRenderer } from "../renderer.js"
 
+export type UsePasteOptions = {
+	/** Optional predicate to drop events before they reach the handler. */
+	filter?: (paste: PasteMsg) => boolean
+	/**
+	 * If true, call preventDefault when available before invoking handler.
+	 * This stops further renderer-level handlers.
+	 */
+	stopPropagation?: boolean
+}
+
 /**
  * Subscribe to bracketed paste events (if supported by renderer/terminal).
  *
@@ -10,20 +21,28 @@ import { useRenderer } from "../renderer.js"
  * @example
  * ```tsx
  * // No useCallback needed - just pass your handler directly
- * usePaste((text) => {
- *   insertText(text, cursorPosition)
+ * usePaste((paste) => {
+ *   insertText(paste.text, cursorPosition)
  * })
  * ```
  */
-export function usePaste(handler: (text: string) => void): void {
+export function usePaste(handler: (paste: PasteMsg) => void, opts?: UsePasteOptions): void {
 	const renderer = useRenderer()
+	const filter = opts?.filter
+	const stopPropagation = opts?.stopPropagation ?? false
 
 	// Store handler in ref so we always call the latest version
 	const handlerRef = useRef(handler)
 	handlerRef.current = handler
+	const filterRef = useRef(filter)
+	filterRef.current = filter
 
 	useEffect(() => {
 		if (!renderer.onPaste) return
-		return renderer.onPaste((text) => handlerRef.current(text))
-	}, [renderer])
+		return renderer.onPaste((paste) => {
+			if (filterRef.current && !filterRef.current(paste)) return
+			if (stopPropagation && paste.preventDefault) paste.preventDefault()
+			handlerRef.current(paste)
+		})
+	}, [renderer, stopPropagation])
 }