@effect-tui/react 0.1.3 → 0.1.4

package/src/console/useConsole.ts

@@ -0,0 +1,129 @@
+// useConsole hook - manages console visibility and toggle keybinding
+// Uses ` (backtick) for toggle, ~ (tilde) for screenshot
+// Auto-show on error
+
+import { useState, useEffect, useCallback, useMemo } from "react"
+import { getConsoleCapture, type LogEntry } from "./ConsoleCapture.js"
+import { useKeyboard } from "../hooks/use-keyboard.js"
+
+// ─────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────
+
+export interface UseConsoleOptions {
+	/** Auto-show console on console.error (default: true) */
+	autoShowOnError?: boolean
+	/** Start with console visible (default: false) */
+	initiallyVisible?: boolean
+}
+
+export interface UseConsoleReturn {
+	/** Whether the console is currently visible */
+	visible: boolean
+	/** Set visibility directly */
+	setVisible: (visible: boolean) => void
+	/** Toggle visibility */
+	toggle: () => void
+	/** Current log entries */
+	entries: LogEntry[]
+	/** Clear all log entries */
+	clear: () => void
+}
+
+// ─────────────────────────────────────────────────────────────
+// Hook
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Hook for managing the debug console.
+ *
+ * Features:
+ * - ` (backtick) to toggle visibility
+ * - ~ (tilde) to take screenshot
+ * - Auto-show on console.error (configurable)
+ * - Access to log entries and clear function
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const { visible } = useConsole({ autoShowOnError: true })
+ *
+ *   return (
+ *     <zstack>
+ *       <MainContent />
+ *       {visible && <ConsolePopover position="bottom" />}
+ *     </zstack>
+ *   )
+ * }
+ * ```
+ */
+export function useConsole(options: UseConsoleOptions = {}): UseConsoleReturn {
+	const { autoShowOnError = true, initiallyVisible = false } = options
+
+	const capture = useMemo(() => getConsoleCapture(), [])
+
+	const [visible, setVisible] = useState(initiallyVisible)
+	const [entries, setEntries] = useState<LogEntry[]>(() => capture.getEntries())
+
+	// Activate capture on mount
+	useEffect(() => {
+		if (!capture.isActive) {
+			capture.activate()
+		}
+
+		return () => {
+			// Don't deactivate on unmount - other components may still use it
+			// The singleton handles cleanup on process exit
+		}
+	}, [capture])
+
+	// Subscribe to entries and errors
+	useEffect(() => {
+		const handleEntry = (_entry: LogEntry) => {
+			setEntries(capture.getEntries())
+		}
+
+		const handleError = (_entry: LogEntry) => {
+			if (autoShowOnError) {
+				setVisible(true)
+			}
+		}
+
+		capture.on("entry", handleEntry)
+		capture.on("error", handleError)
+
+		return () => {
+			capture.off("entry", handleEntry)
+			capture.off("error", handleError)
+		}
+	}, [capture, autoShowOnError])
+
+	// Toggle function
+	const toggle = useCallback(() => {
+		setVisible((v) => !v)
+	}, [])
+
+	// Clear function
+	const clear = useCallback(() => {
+		capture.clear()
+		setEntries([])
+	}, [capture])
+
+	// Keyboard handler for ` toggle
+	// No useCallback needed - useKeyboard uses refs internally
+	useKeyboard((key) => {
+		// ` (backtick) - toggle console
+		if (key.name === "char" && key.text === "`") {
+			toggle()
+			key.preventDefault?.()
+		}
+	})
+
+	return {
+		visible,
+		setVisible,
+		toggle,
+		entries,
+		clear,
+	}
+}

package/src/debug/DebugOverlay.ts

@@ -0,0 +1,557 @@
+// Integrated debug overlay for all TUI apps
+// Provides console log viewer with Ctrl+Shift+D toggle and Ctrl+Shift+S screenshot
+
+import type { CellBuffer, Palette, KeyMsg, MouseMsg } from "@effect-tui/core"
+import { getConsoleCapture, type LogLevel } from "../console/ConsoleCapture.js"
+import { copyToClipboardSync, copyToClipboard } from "../console/clipboard.js"
+
+// ─────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────
+
+export interface DebugOverlayOptions {
+	/** Initial height as percentage of terminal (default: 30) */
+	heightPercent?: number
+	/** Minimum height percent (default: 10) */
+	minHeightPercent?: number
+	/** Maximum height percent (default: 80) */
+	maxHeightPercent?: number
+	/** Show file locations in log entries (default: true) */
+	showLocations?: boolean
+}
+
+interface SelectionPoint {
+	line: number
+	col: number
+}
+
+// ─────────────────────────────────────────────────────────────
+// Color constants (8-bit palette indices for performance)
+// ─────────────────────────────────────────────────────────────
+
+const TITLE_BG = 236 // gray(4)
+const TITLE_FG = 15 // white
+const CONTENT_BG = 234 // gray(2)
+const SELECTION_BG_R = 60
+const SELECTION_BG_G = 90
+const SELECTION_BG_B = 140
+
+const LOG_COLORS: Record<LogLevel, number> = {
+	LOG: 15, // white
+	INFO: 14, // cyan
+	WARN: 11, // yellow
+	ERROR: 9, // red
+	DEBUG: 250, // gray(12)
+}
+
+// ─────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────
+
+function formatTimestamp(date: Date): string {
+	const h = date.getHours().toString().padStart(2, "0")
+	const m = date.getMinutes().toString().padStart(2, "0")
+	const s = date.getSeconds().toString().padStart(2, "0")
+	return `${h}:${m}:${s}`
+}
+
+function formatLocation(loc?: { file: string; line: number }): string {
+	if (!loc) return ""
+	const parts = loc.file.split("/")
+	const filename = parts[parts.length - 1]
+	return `${filename}:${loc.line}`
+}
+
+function wrapLine(text: string, maxWidth: number): string[] {
+	if (text.length <= maxWidth) return [text]
+
+	const lines: string[] = []
+	let remaining = text
+
+	while (remaining.length > 0) {
+		if (remaining.length <= maxWidth) {
+			lines.push(remaining)
+			break
+		}
+
+		let breakAt = maxWidth
+		const lastSpace = remaining.lastIndexOf(" ", maxWidth)
+		if (lastSpace > maxWidth * 0.5) {
+			breakAt = lastSpace
+		}
+
+		lines.push(remaining.slice(0, breakAt))
+		remaining = remaining.slice(breakAt).trimStart()
+	}
+
+	return lines
+}
+
+function normalizeSelection(anchor: SelectionPoint, head: SelectionPoint): [SelectionPoint, SelectionPoint] {
+	if (anchor.line < head.line || (anchor.line === head.line && anchor.col <= head.col)) {
+		return [anchor, head]
+	}
+	return [head, anchor]
+}
+
+// ─────────────────────────────────────────────────────────────
+// Debug Overlay Class
+// ─────────────────────────────────────────────────────────────
+
+interface DisplayLine {
+	text: string
+	level: LogLevel
+}
+
+export class DebugOverlay {
+	private _visible = false
+	private sizePercent: number
+	private minSizePercent: number
+	private maxSizePercent: number
+	private showLocations: boolean
+
+	// Scroll state
+	private scrollOffset = 0
+	private wasAtEnd = true
+
+	// Selection state
+	private selectionAnchor: SelectionPoint | null = null
+	private selectionHead: SelectionPoint | null = null
+	private isSelecting = false
+
+	// Feedback message
+	private feedback: string | null = null
+	private feedbackTimeout: ReturnType<typeof setTimeout> | null = null
+
+	// Cached display lines
+	private displayLines: DisplayLine[] = []
+	private lastEntriesLength = 0
+	private lastWidth = 0
+
+	// Screenshot callback
+	private getScreenshot: (() => string) | null = null
+
+	constructor(options: DebugOverlayOptions = {}) {
+		this.sizePercent = options.heightPercent ?? 30
+		this.minSizePercent = options.minHeightPercent ?? 10
+		this.maxSizePercent = options.maxHeightPercent ?? 80
+		this.showLocations = options.showLocations ?? true
+	}
+
+	get visible(): boolean {
+		return this._visible
+	}
+
+	show(): void {
+		this._visible = true
+	}
+
+	hide(): void {
+		this._visible = false
+	}
+
+	toggle(): void {
+		this._visible = !this._visible
+	}
+
+	setScreenshotFn(fn: () => string): void {
+		this.getScreenshot = fn
+	}
+
+	// ─────────────────────────────────────────────────────────────
+	// Key handling - returns true if event was consumed
+	// ─────────────────────────────────────────────────────────────
+
+	handleKey(key: KeyMsg, width: number, height: number): boolean {
+		// Ctrl+Shift+D - toggle overlay (handled even when hidden)
+		if (key.ctrl && key.shift && key.name === "char" && key.text === "d") {
+			this.toggle()
+			return true
+		}
+
+		// Ctrl+Shift+S - screenshot (handled even when hidden)
+		if (key.ctrl && key.shift && key.name === "char" && key.text === "s") {
+			this.takeScreenshot()
+			return true
+		}
+
+		// Rest only applies when visible
+		if (!this._visible) return false
+
+		// Ctrl+Y or Ctrl+C - copy selection
+		if (key.ctrl && !key.shift && key.name === "char" && (key.text === "y" || key.text === "c")) {
+			this.copySelection()
+			return true
+		}
+
+		// Ctrl+S - save logs
+		if (key.ctrl && !key.shift && key.name === "char" && key.text === "s") {
+			this.saveLogs()
+			return true
+		}
+
+		// Size controls
+		if (key.name === "char" && (key.text === "+" || key.text === "=")) {
+			this.sizePercent = Math.min(this.maxSizePercent, this.sizePercent + 5)
+			return true
+		}
+		if (key.name === "char" && key.text === "-") {
+			this.sizePercent = Math.max(this.minSizePercent, this.sizePercent - 5)
+			return true
+		}
+
+		const viewportHeight = this.getViewportHeight(height)
+		const maxScroll = Math.max(0, this.displayLines.length - viewportHeight)
+
+		// Shift+up/down - jump to top/bottom
+		if (key.shift && key.name === "up") {
+			this.scrollOffset = 0
+			this.wasAtEnd = false
+			return true
+		}
+		if (key.shift && key.name === "down") {
+			this.scrollOffset = maxScroll
+			this.wasAtEnd = true
+			return true
+		}
+
+		// Regular up/down - scroll
+		if (key.name === "up") {
+			this.scrollOffset = Math.max(0, this.scrollOffset - 1)
+			this.wasAtEnd = this.scrollOffset >= maxScroll
+			return true
+		}
+		if (key.name === "down") {
+			this.scrollOffset = Math.min(maxScroll, this.scrollOffset + 1)
+			this.wasAtEnd = this.scrollOffset >= maxScroll
+			return true
+		}
+
+		// Home/End
+		if (key.name === "home") {
+			this.scrollOffset = 0
+			this.wasAtEnd = false
+			return true
+		}
+		if (key.name === "end") {
+			this.scrollOffset = maxScroll
+			this.wasAtEnd = true
+			return true
+		}
+
+		return false
+	}
+
+	// ─────────────────────────────────────────────────────────────
+	// Mouse handling - returns true if event was consumed
+	// ─────────────────────────────────────────────────────────────
+
+	handleMouse(mouse: MouseMsg, width: number, height: number): boolean {
+		if (!this._visible) return false
+
+		const popoverHeight = this.getPopoverHeight(height)
+		const contentStartY = height - popoverHeight + 1
+
+		// Check if mouse is in overlay area
+		if (mouse.y < height - popoverHeight || mouse.y >= height) return false
+
+		// Mouse wheel scroll
+		if (mouse.button === "scroll-up" || mouse.button === "scroll-down") {
+			const viewportHeight = this.getViewportHeight(height)
+			const maxScroll = Math.max(0, this.displayLines.length - viewportHeight)
+			const delta = mouse.button === "scroll-up" ? -3 : 3
+			this.scrollOffset = Math.max(0, Math.min(maxScroll, this.scrollOffset + delta))
+			this.wasAtEnd = this.scrollOffset >= maxScroll
+			return true
+		}
+
+		// Text selection
+		if (mouse.button === "left") {
+			const relativeY = mouse.y - contentStartY
+			const lineIndex = Math.floor(relativeY + this.scrollOffset)
+			const col = Math.max(0, mouse.x)
+
+			if (lineIndex < 0 || lineIndex >= this.displayLines.length) return true
+
+			if (mouse.action === "press") {
+				this.selectionAnchor = { line: lineIndex, col }
+				this.selectionHead = { line: lineIndex, col }
+				this.isSelecting = true
+			} else if (mouse.action === "drag" && this.isSelecting) {
+				this.selectionHead = { line: lineIndex, col }
+
+				// Auto-scroll at edges
+				const viewportHeight = this.getViewportHeight(height)
+				if (relativeY <= 1) {
+					this.scrollOffset = Math.max(0, this.scrollOffset - 1)
+				} else if (relativeY >= viewportHeight - 2) {
+					const maxScroll = Math.max(0, this.displayLines.length - viewportHeight)
+					this.scrollOffset = Math.min(maxScroll, this.scrollOffset + 1)
+				}
+			} else if (mouse.action === "release") {
+				this.isSelecting = false
+			}
+			return true
+		}
+
+		return true // Consume all mouse events in overlay area
+	}
+
+	// ─────────────────────────────────────────────────────────────
+	// Rendering
+	// ─────────────────────────────────────────────────────────────
+
+	render(buffer: CellBuffer, palette: Palette, width: number, height: number): void {
+		if (!this._visible) return
+
+		const popoverHeight = this.getPopoverHeight(height)
+		const viewportHeight = this.getViewportHeight(height)
+		const startY = height - popoverHeight
+
+		// Update display lines if needed
+		this.updateDisplayLines(width)
+
+		// Auto-scroll to end if sticky
+		if (this.wasAtEnd) {
+			this.scrollOffset = Math.max(0, this.displayLines.length - viewportHeight)
+		}
+
+		// Title bar styles
+		const titleStyle = palette.id({ fg: TITLE_FG, bg: TITLE_BG })
+		const hintStyle = palette.id({ fg: this.feedback ? 10 : 250, bg: TITLE_BG })
+
+		// Draw title bar
+		const titleText = this.feedback ?? "Console"
+		const hints = `[^Y copy] [^S save] [^⇧S screenshot] [+/- ${this.sizePercent}%]`
+
+		buffer.fillRect(0, startY, width, 1, 32, titleStyle)
+		buffer.drawText(1, startY, ` ${titleText}`, titleStyle)
+		buffer.drawText(width - hints.length - 1, startY, hints, hintStyle)
+
+		// Content area
+		const contentStyle = palette.id({ bg: CONTENT_BG })
+		buffer.fillRect(0, startY + 1, width, viewportHeight, 32, contentStyle)
+
+		// Draw log lines
+		const contentStartY = startY + 1
+		for (let i = 0; i < viewportHeight; i++) {
+			const lineIdx = this.scrollOffset + i
+			if (lineIdx >= this.displayLines.length) break
+
+			const line = this.displayLines[lineIdx]
+			const y = contentStartY + i
+			const paddedText = line.text.padEnd(width - 1, " ")
+
+			// Check for selection
+			const sel = this.getLineSelection(lineIdx, paddedText.length)
+
+			if (sel) {
+				// Render with selection highlight
+				const before = paddedText.slice(0, sel.startCol)
+				const selected = paddedText.slice(sel.startCol, sel.endCol)
+				const after = paddedText.slice(sel.endCol)
+
+				const normalStyle = palette.id({ fg: LOG_COLORS[line.level], bg: CONTENT_BG })
+				const selStyle = palette.id({ fg: 15, bg: { r: SELECTION_BG_R, g: SELECTION_BG_G, b: SELECTION_BG_B } })
+
+				let x = 0
+				if (before.length > 0) {
+					buffer.drawText(x, y, before, normalStyle)
+					x += before.length
+				}
+				buffer.drawText(x, y, selected, selStyle)
+				x += selected.length
+				if (after.length > 0) {
+					buffer.drawText(x, y, after, normalStyle)
+				}
+			} else {
+				const style = palette.id({ fg: LOG_COLORS[line.level], bg: CONTENT_BG })
+				buffer.drawText(0, y, paddedText, style)
+			}
+		}
+
+		// Draw scrollbar if needed
+		if (this.displayLines.length > viewportHeight) {
+			this.drawScrollbar(buffer, palette, width, contentStartY, viewportHeight)
+		}
+	}
+
+	// ─────────────────────────────────────────────────────────────
+	// Private helpers
+	// ─────────────────────────────────────────────────────────────
+
+	private getPopoverHeight(termHeight: number): number {
+		return Math.max(5, Math.floor(termHeight * (this.sizePercent / 100)))
+	}
+
+	private getViewportHeight(termHeight: number): number {
+		return this.getPopoverHeight(termHeight) - 1 // -1 for title bar
+	}
+
+	private updateDisplayLines(width: number): void {
+		const capture = getConsoleCapture()
+		const entries = capture.getEntries()
+
+		// Only rebuild if entries changed or width changed
+		if (entries.length === this.lastEntriesLength && width === this.lastWidth) {
+			return
+		}
+
+		this.lastEntriesLength = entries.length
+		this.lastWidth = width
+		this.displayLines = []
+
+		const availableWidth = width - 1 // Leave room for scrollbar
+
+		for (const entry of entries) {
+			const timestamp = formatTimestamp(entry.timestamp)
+			const location = this.showLocations ? formatLocation(entry.location) : ""
+
+			const prefix = `[${timestamp}] [${entry.level}] `
+			const suffix = location ? ` (${location})` : ""
+
+			const messageLines = entry.message.split("\n")
+
+			for (let j = 0; j < messageLines.length; j++) {
+				const msgLine = messageLines[j]
+				const isFirstLine = j === 0
+				const isLastLine = j === messageLines.length - 1
+
+				const linePrefix = isFirstLine ? prefix : "    "
+				const lineSuffix = isLastLine ? suffix : ""
+
+				const fullLine = linePrefix + msgLine + lineSuffix
+				const wrappedLines = wrapLine(fullLine, availableWidth)
+
+				for (const wrappedLine of wrappedLines) {
+					this.displayLines.push({
+						text: wrappedLine,
+						level: entry.level,
+					})
+				}
+			}
+		}
+	}
+
+	private getLineSelection(
+		lineIndex: number,
+		lineLength: number,
+	): { startCol: number; endCol: number } | null {
+		if (!this.selectionAnchor || !this.selectionHead) return null
+
+		const [start, end] = normalizeSelection(this.selectionAnchor, this.selectionHead)
+
+		if (lineIndex < start.line || lineIndex > end.line) return null
+
+		const startCol = lineIndex === start.line ? Math.min(start.col, lineLength) : 0
+		const endCol = lineIndex === end.line ? Math.min(end.col, lineLength) : lineLength
+
+		if (startCol >= endCol && lineIndex === start.line && lineIndex === end.line) return null
+
+		return { startCol, endCol }
+	}
+
+	private drawScrollbar(
+		buffer: CellBuffer,
+		palette: Palette,
+		width: number,
+		contentStartY: number,
+		viewportHeight: number,
+	): void {
+		const maxScroll = this.displayLines.length - viewportHeight
+		const scrollRatio = maxScroll > 0 ? this.scrollOffset / maxScroll : 0
+		const thumbRatio = viewportHeight / this.displayLines.length
+		const thumbHeight = Math.max(1, Math.floor(viewportHeight * thumbRatio))
+		const thumbY = Math.floor((viewportHeight - thumbHeight) * scrollRatio)
+
+		const trackStyle = palette.id({ fg: 8 })
+		const thumbStyle = palette.id({ fg: 7 })
+
+		for (let i = 0; i < viewportHeight; i++) {
+			const isThumb = i >= thumbY && i < thumbY + thumbHeight
+			const char = isThumb ? "┃" : "│"
+			const style = isThumb ? thumbStyle : trackStyle
+			buffer.drawText(width - 1, contentStartY + i, char, style)
+		}
+	}
+
+	private getSelectedText(): string {
+		if (!this.selectionAnchor || !this.selectionHead) return ""
+
+		const [start, end] = normalizeSelection(this.selectionAnchor, this.selectionHead)
+		const lines: string[] = []
+
+		for (let i = start.line; i <= end.line && i < this.displayLines.length; i++) {
+			const lineText = this.displayLines[i]?.text ?? ""
+			const startCol = i === start.line ? Math.min(start.col, lineText.length) : 0
+			const endCol = i === end.line ? Math.min(end.col, lineText.length) : lineText.length
+			lines.push(lineText.slice(startCol, endCol))
+		}
+
+		return lines.join("\n")
+	}
+
+	private copySelection(): void {
+		const text = this.getSelectedText()
+		if (!text) return
+
+		const copied = copyToClipboardSync(text)
+		if (!copied) {
+			copyToClipboard(text)
+		}
+
+		this.showFeedback("Copied!")
+	}
+
+	private async saveLogs(): Promise<void> {
+		const allText = this.displayLines.map((l) => l.text).join("\n")
+		const tmpPath = `/tmp/console-logs-${Date.now()}.txt`
+
+		try {
+			await Bun.write(tmpPath, allText)
+			const copied = copyToClipboardSync(tmpPath)
+			if (!copied) {
+				await copyToClipboard(tmpPath)
+			}
+			this.showFeedback(`Saved: ${tmpPath}`)
+		} catch {
+			this.showFeedback("Save failed")
+		}
+	}
+
+	private async takeScreenshot(): Promise<void> {
+		if (!this.getScreenshot) {
+			this.showFeedback("Screenshot not available")
+			return
+		}
+
+		const screenshot = this.getScreenshot()
+		const tmpPath = `/tmp/tui-screenshot-${Date.now()}.txt`
+
+		try {
+			await Bun.write(tmpPath, screenshot)
+			const copied = copyToClipboardSync(tmpPath)
+			if (!copied) {
+				await copyToClipboard(tmpPath)
+			}
+			this.showFeedback(`Screenshot: ${tmpPath}`)
+			// Also show the console so user sees the feedback
+			if (!this._visible) {
+				this._visible = true
+			}
+		} catch {
+			this.showFeedback("Screenshot failed")
+		}
+	}
+
+	private showFeedback(message: string, durationMs = 2000): void {
+		if (this.feedbackTimeout) {
+			clearTimeout(this.feedbackTimeout)
+		}
+		this.feedback = message
+		this.feedbackTimeout = setTimeout(() => {
+			this.feedback = null
+			this.feedbackTimeout = null
+		}, durationMs)
+	}
+}