@rlabs-inc/tui 0.1.0 → 0.2.0

package/src/renderer/append-region.ts

@@ -0,0 +1,303 @@
+/**
+ * TUI Framework - Two-Region Append Renderer
+ *
+ * Implements a hybrid static/reactive rendering mode optimized for chat-like UIs:
+ *
+ * STATIC REGION (Terminal History):
+ * - Completed messages written once via Bun.file(1).writer()
+ * - No re-rendering, pure append-only
+ * - Native terminal scroll, copy/paste, search
+ * - O(1) cost after initial write
+ *
+ * REACTIVE REGION (Active TUI):
+ * - Last N messages + input area
+ * - Full reactive rendering pipeline
+ * - Interactive (focus, scroll, mouse)
+ * - Fixed-size = O(1) render time
+ *
+ * This architecture enables:
+ * - Infinite conversation length with constant performance
+ * - Rich interactive UI for active content
+ * - Graceful degradation to static output
+ * - CLI-like feel with TUI interactivity
+ */
+
+import type { Cell, RGBA, CellAttrs, FrameBuffer } from '../types'
+import { Attr } from '../types'
+import { rgbaEqual } from '../types/color'
+import * as ansi from './ansi'
+
+// =============================================================================
+// FileSink Writer for Static Region
+// =============================================================================
+
+/**
+ * Writer for appending to terminal stdout using Bun's FileSink API.
+ * Buffers writes and flushes efficiently.
+ */
+class StdoutWriter {
+  private writer: any // FileSink type
+  private hasContent = false
+
+  constructor() {
+    // Create writer for stdout (file descriptor 1)
+    const stdoutFile = Bun.file(1)
+    this.writer = stdoutFile.writer({ highWaterMark: 1024 * 1024 }) // 1MB buffer
+  }
+
+  write(content: string): void {
+    if (content.length === 0) return
+    this.writer.write(content)
+    this.hasContent = true
+  }
+
+  flush(): void {
+    if (this.hasContent) {
+      this.writer.flush()
+      this.hasContent = false
+    }
+  }
+
+  end(): void {
+    this.writer.end()
+  }
+}
+
+// =============================================================================
+// Message Tracking
+// =============================================================================
+
+interface MessageMetadata {
+  id: string
+  lineCount: number
+  content: string
+}
+
+// =============================================================================
+// Two-Region Append Renderer
+// =============================================================================
+
+/**
+ * Renders frame buffer in two distinct regions:
+ * 1. Static region: Frozen completed content (terminal history)
+ * 2. Reactive region: Live updating content (last N lines)
+ *
+ * The boundary between regions shifts as content completes.
+ */
+export class AppendRegionRenderer {
+  private staticWriter = new StdoutWriter()
+  private frozenMessages = new Set<string>()
+  private totalStaticLines = 0
+
+  // Cell rendering state (for ANSI optimization)
+  private lastFg: RGBA | null = null
+  private lastBg: RGBA | null = null
+  private lastAttrs: CellAttrs = Attr.NONE
+
+  // Previous reactive output for change detection
+  private previousReactiveOutput = ''
+
+  /**
+   * Render frame buffer with two-region strategy.
+   *
+   * @param buffer - Full frame buffer
+   * @param options.staticHeight - Number of lines to freeze into static region
+   * @param options.messageIds - Optional array of message IDs for tracking
+   */
+  render(
+    buffer: FrameBuffer,
+    options: {
+      staticHeight: number
+      messageIds?: string[]
+    } = { staticHeight: 0 }
+  ): void {
+    const { staticHeight, messageIds = [] } = options
+
+    // Split buffer into two regions
+    const staticBuffer = this.extractRegion(buffer, 0, staticHeight)
+    const reactiveBuffer = this.extractRegion(buffer, staticHeight, buffer.height - staticHeight)
+
+    // STATIC REGION: Freeze new content to terminal history
+    if (staticHeight > this.totalStaticLines) {
+      const newStaticLines = staticHeight - this.totalStaticLines
+      const newStaticBuffer = this.extractRegion(
+        buffer,
+        this.totalStaticLines,
+        newStaticLines
+      )
+
+      const staticOutput = this.buildStaticOutput(newStaticBuffer)
+      this.staticWriter.write(staticOutput)
+      this.staticWriter.flush()
+
+      this.totalStaticLines = staticHeight
+    }
+
+    // REACTIVE REGION: Clear and re-render active content
+    const reactiveOutput = this.buildReactiveOutput(reactiveBuffer)
+
+    // Only update if changed
+    if (reactiveOutput !== this.previousReactiveOutput) {
+      // Clear from current position down
+      process.stdout.write(ansi.eraseDown)
+
+      // Render reactive content
+      process.stdout.write(reactiveOutput)
+
+      this.previousReactiveOutput = reactiveOutput
+    }
+  }
+
+  /**
+   * Extract a region from the frame buffer.
+   */
+  private extractRegion(buffer: FrameBuffer, startY: number, height: number): FrameBuffer {
+    if (height <= 0) {
+      return {
+        width: buffer.width,
+        height: 0,
+        cells: []
+      }
+    }
+
+    const endY = Math.min(startY + height, buffer.height)
+    const actualHeight = endY - startY
+
+    return {
+      width: buffer.width,
+      height: actualHeight,
+      cells: buffer.cells.slice(startY, endY)
+    }
+  }
+
+  /**
+   * Build output for static region (append once, forget).
+   */
+  private buildStaticOutput(buffer: FrameBuffer): string {
+    if (buffer.height === 0) return ''
+
+    const chunks: string[] = []
+
+    // Reset rendering state
+    this.lastFg = null
+    this.lastBg = null
+    this.lastAttrs = Attr.NONE
+
+    for (let y = 0; y < buffer.height; y++) {
+      for (let x = 0; x < buffer.width; x++) {
+        const cell = buffer.cells[y]![x]
+        this.renderCell(chunks, cell!)
+      }
+      chunks.push('\n')
+    }
+
+    chunks.push(ansi.reset)
+
+    return chunks.join('')
+  }
+
+  /**
+   * Build output for reactive region (cleared and re-rendered each frame).
+   */
+  private buildReactiveOutput(buffer: FrameBuffer): string {
+    if (buffer.height === 0) return ''
+
+    const chunks: string[] = []
+
+    // Reset rendering state
+    this.lastFg = null
+    this.lastBg = null
+    this.lastAttrs = Attr.NONE
+
+    for (let y = 0; y < buffer.height; y++) {
+      if (y > 0) {
+        chunks.push('\n')
+      }
+
+      for (let x = 0; x < buffer.width; x++) {
+        const cell = buffer.cells[y]![x]
+        this.renderCell(chunks, cell!)
+      }
+    }
+
+    chunks.push(ansi.reset)
+    chunks.push('\n')
+
+    return chunks.join('')
+  }
+
+  /**
+   * Render a single cell with ANSI optimization.
+   */
+  private renderCell(chunks: string[], cell: Cell): void {
+    // Attributes changed - reset first
+    if (cell.attrs !== this.lastAttrs) {
+      chunks.push(ansi.reset)
+      if (cell.attrs !== Attr.NONE) {
+        chunks.push(ansi.attrs(cell.attrs))
+      }
+      this.lastFg = null
+      this.lastBg = null
+      this.lastAttrs = cell.attrs
+    }
+
+    // Foreground color changed
+    if (!this.lastFg || !rgbaEqual(cell.fg, this.lastFg)) {
+      chunks.push(ansi.fg(cell.fg))
+      this.lastFg = cell.fg
+    }
+
+    // Background color changed
+    if (!this.lastBg || !rgbaEqual(cell.bg, this.lastBg)) {
+      chunks.push(ansi.bg(cell.bg))
+      this.lastBg = cell.bg
+    }
+
+    // Output character
+    if (cell.char === 0) {
+      chunks.push(' ')
+    } else {
+      chunks.push(String.fromCodePoint(cell.char))
+    }
+  }
+
+  /**
+   * Mark a message as frozen (moved to static region).
+   */
+  freezeMessage(messageId: string): void {
+    this.frozenMessages.add(messageId)
+  }
+
+  /**
+   * Check if a message has been frozen.
+   */
+  isFrozen(messageId: string): boolean {
+    return this.frozenMessages.has(messageId)
+  }
+
+  /**
+   * Get total number of static lines rendered.
+   */
+  getStaticLineCount(): number {
+    return this.totalStaticLines
+  }
+
+  /**
+   * Reset the renderer state.
+   */
+  reset(): void {
+    this.frozenMessages.clear()
+    this.totalStaticLines = 0
+    this.previousReactiveOutput = ''
+    this.lastFg = null
+    this.lastBg = null
+    this.lastAttrs = Attr.NONE
+  }
+
+  /**
+   * Cleanup when unmounting.
+   */
+  cleanup(): void {
+    this.staticWriter.end()
+  }
+}

package/src/renderer/index.ts

@@ -36,5 +36,7 @@ export {
   finalizeAppendMode,
 } from './output'
 
-// Input parsing
-export { InputBuffer, type ParsedInput } from './input'
+// Two-region append renderer
+export { AppendRegionRenderer } from './append-region'
+
+// Input parsing moved to src/state/input.ts

package/src/renderer/output.ts

@@ -312,12 +312,11 @@ export function finalizeAppendMode(output: OutputBuffer, height: number): void {
 // =============================================================================
 
 /**
- * Inline renderer matching Ink's log-update approach.
- * Uses our own ansi.ts (zero dependencies).
+ * Inline renderer for non-fullscreen mode.
+ * Uses clearTerminal for reliable rendering without ghost lines.
  */
 export class InlineRenderer {
   private output = new OutputBuffer()
-  private previousLineCount = 0
   private previousOutput = ''
 
   // Cell rendering state (for ANSI optimization)
@@ -327,18 +326,14 @@ export class InlineRenderer {
 
   /**
    * Render a frame buffer for inline mode.
-   * Follows log-update's algorithm:
-   * 1. Build output with trailing newline
-   * 2. eraseLines(previousLineCount) + output
-   * 3. Track new line count
    *
-   * KEY INSIGHT FROM INK:
-   * When content height >= terminal rows, eraseLines can't reach content
-   * that scrolled off the top into scrollback. In this case, use clearTerminal
-   * to wipe everything including scrollback, then redraw.
+   * Uses clearTerminal (clears screen + scrollback) before each render.
+   * This is simpler and more reliable than tracking line counts:
+   * - No ghost lines from eraseLines edge cases
+   * - Once content exceeds terminal height, scrollback is cleared anyway
+   * - The slight overhead of clearing is negligible with fast renders
    */
   render(buffer: FrameBuffer): void {
-    // Build the output string
     const output = this.buildOutput(buffer)
 
     // Skip if output unchanged
@@ -346,26 +341,11 @@ export class InlineRenderer {
       return
     }
 
-    // Get terminal viewport height
-    const terminalRows = process.stdout.rows || 24
-
-    // When content height >= terminal rows, eraseLines can't reach content
-    // that scrolled off into scrollback. Use clearTerminal instead.
-    if (this.previousLineCount >= terminalRows) {
-      this.output.write(ansi.clearTerminal + output)
-    } else {
-      this.output.write(ansi.eraseLines(this.previousLineCount) + output)
-    }
+    // Clear everything and render fresh
+    this.output.write(ansi.clearTerminal + output)
     this.output.flushSync()
 
-    // Track for next render
     this.previousOutput = output
-    // buffer.height + 1 because:
-    // - We output buffer.height lines of content
-    // - Plus a trailing newline that puts cursor on the next line
-    // - eraseLines works from cursor position upward, so we need to erase
-    //   buffer.height lines PLUS the empty line we're currently on
-    this.previousLineCount = buffer.height + 1
   }
 
   /**
@@ -431,10 +411,8 @@ export class InlineRenderer {
    * Clear all rendered content and reset state.
    */
   clear(): void {
-    if (this.previousLineCount > 0) {
-      this.output.write(ansi.eraseLines(this.previousLineCount))
-      this.output.flushSync()
-    }
+    this.output.write(ansi.clearTerminal)
+    this.output.flushSync()
     this.reset()
   }
 
@@ -442,7 +420,6 @@ export class InlineRenderer {
    * Reset the renderer state.
    */
   reset(): void {
-    this.previousLineCount = 0
     this.previousOutput = ''
     this.lastFg = null
     this.lastBg = null

package/src/state/focus.ts

@@ -65,7 +65,10 @@ export function restoreFocusFromHistory(): boolean {
   while (focusHistory.length > 0) {
     const index = focusHistory.pop()!
     // Check if component is still valid and focusable
-    if (unwrap(focusable[index]) && unwrap(visible[index])) {
+    // Match TITAN's logic: undefined means visible, only 0/false means hidden
+    const isVisible = unwrap(visible[index])
+    const isActuallyVisible = isVisible !== 0 && isVisible !== false
+    if (unwrap(focusable[index]) && isActuallyVisible) {
       focusedIndex.value = index
       return true
     }
@@ -83,7 +86,11 @@ export function getFocusableIndices(): number[] {
   const result: number[] = []
 
   for (const i of indices) {
-    if (unwrap(focusable[i]) && unwrap(visible[i])) {
+    const isFocusable = unwrap(focusable[i])
+    const isVisible = unwrap(visible[i])
+    // Match TITAN's logic: undefined means visible, only 0/false means hidden
+    const isActuallyVisible = isVisible !== 0 && isVisible !== false
+    if (isFocusable && isActuallyVisible) {
       result.push(i)
     }
   }
@@ -141,8 +148,9 @@ function findNextFocusable(fromIndex: number, direction: 1 | -1): number {
 
 /** Move focus to next focusable component */
 export function focusNext(): boolean {
-  const next = findNextFocusable(focusedIndex.value, 1)
-  if (next !== -1 && next !== focusedIndex.value) {
+  const current = focusedIndex.value
+  const next = findNextFocusable(current, 1)
+  if (next !== -1 && next !== current) {
     saveFocusToHistory()
     focusedIndex.value = next
     return true
@@ -163,7 +171,10 @@ export function focusPrevious(): boolean {
 
 /** Focus a specific component by index */
 export function focus(index: number): boolean {
-  if (unwrap(focusable[index]) && unwrap(visible[index])) {
+  // Match TITAN's logic: undefined means visible, only 0/false means hidden
+  const isVisible = unwrap(visible[index])
+  const isActuallyVisible = isVisible !== 0 && isVisible !== false
+  if (unwrap(focusable[index]) && isActuallyVisible) {
     if (focusedIndex.value !== index) {
       saveFocusToHistory()
       focusedIndex.value = index

package/src/state/global-keys.ts

@@ -0,0 +1,184 @@
+/**
+ * TUI Framework - Global Keys Module
+ *
+ * Central location for ALL global keyboard and mouse shortcuts.
+ * This is the ONLY place where global input behaviors are defined.
+ *
+ * Wires together: input, keyboard, mouse, focus, scroll
+ *
+ * Global behaviors:
+ * - Ctrl+C: Exit application
+ * - Tab/Shift+Tab: Focus navigation
+ * - Arrow keys: Scroll focused scrollable
+ * - Page Up/Down: Large scroll jumps
+ * - Home/End: Scroll to start/end
+ * - Mouse wheel: Scroll hovered or focused
+ */
+
+import { input } from './input'
+import { keyboard, dispatch as dispatchKeyboard, dispatchFocused } from './keyboard'
+import { mouse, dispatch as dispatchMouse } from './mouse'
+import { focusNext, focusPrevious, focusedIndex } from './focus'
+import { handleArrowScroll, handlePageScroll, handleHomeEnd, handleWheelScroll } from './scroll'
+import type { KeyboardEvent } from './keyboard'
+import type { MouseEvent } from './mouse'
+
+// =============================================================================
+// STATE
+// =============================================================================
+
+let initialized = false
+let cleanupCallback: (() => void) | null = null
+let exitOnCtrlC = true
+
+// =============================================================================
+// EVENT HANDLERS
+// =============================================================================
+
+function handleKeyboardEvent(event: KeyboardEvent): void {
+  try {
+    // Only process press events for most shortcuts
+    const isPress = event.state === 'press'
+
+    // Ctrl+C - exit (always, even on release for safety)
+    if (exitOnCtrlC && event.key === 'c' && event.modifiers.ctrl) {
+      cleanup()
+      process.exit(0)
+    }
+
+    // Skip non-press events for other shortcuts
+    if (!isPress) {
+      // Still dispatch to handlers (they may want release events)
+      dispatchFocused(focusedIndex.value, event)
+      dispatchKeyboard(event)
+      return
+    }
+
+    // Tab - focus navigation
+    if (event.key === 'Tab' && !event.modifiers.ctrl && !event.modifiers.alt) {
+      if (event.modifiers.shift) {
+        focusPrevious()
+      } else {
+        focusNext()
+      }
+      return // Tab is always consumed
+    }
+
+    // Dispatch to focused component handlers first
+    if (dispatchFocused(focusedIndex.value, event)) {
+      return // Consumed by focused handler
+    }
+
+    // Dispatch to user handlers (keyboard.onKey)
+    // If user returns true, they handled it - skip framework defaults
+    if (dispatchKeyboard(event)) {
+      return // User handled it
+    }
+
+    // =========================================================================
+    // FRAMEWORK DEFAULTS - only run if user didn't handle
+    // =========================================================================
+
+    // Arrow keys - scroll focused scrollable
+    if (event.key === 'ArrowUp' && handleArrowScroll('up')) return
+    if (event.key === 'ArrowDown' && handleArrowScroll('down')) return
+    if (event.key === 'ArrowLeft' && handleArrowScroll('left')) return
+    if (event.key === 'ArrowRight' && handleArrowScroll('right')) return
+
+    // Page Up/Down
+    if (event.key === 'PageUp' && handlePageScroll('up')) return
+    if (event.key === 'PageDown' && handlePageScroll('down')) return
+
+    // Home/End (without Ctrl - Ctrl+Home/End could be used for something else)
+    if (event.key === 'Home' && !event.modifiers.ctrl && handleHomeEnd('home')) return
+    if (event.key === 'End' && !event.modifiers.ctrl && handleHomeEnd('end')) return
+  } catch (err) {
+    console.error('[TUI] Keyboard handler error:', err)
+  }
+}
+
+function handleMouseEvent(event: MouseEvent): void {
+  // Mouse wheel - scroll hovered or focused
+  if (event.action === 'scroll' && event.scroll) {
+    handleWheelScroll(event.x, event.y, event.scroll.direction)
+  }
+
+  // Dispatch to mouse module for hover/click handling
+  dispatchMouse(event)
+}
+
+// =============================================================================
+// PUBLIC API
+// =============================================================================
+
+/**
+ * Initialize the global input system.
+ * Sets up stdin handling and wires all global shortcuts.
+ */
+export function initialize(options?: {
+  onCleanup?: () => void
+  exitOnCtrlC?: boolean
+  enableMouse?: boolean
+}): void {
+  if (initialized) return
+
+  initialized = true
+  cleanupCallback = options?.onCleanup ?? null
+  exitOnCtrlC = options?.exitOnCtrlC ?? true
+
+  // Initialize input system with our handlers
+  input.initialize(handleKeyboardEvent, handleMouseEvent)
+
+  // Enable mouse tracking if requested
+  if (options?.enableMouse !== false) {
+    mouse.enableTracking()
+  }
+}
+
+/**
+ * Clean up the global input system.
+ */
+export function cleanup(): void {
+  if (!initialized) return
+
+  initialized = false
+
+  // Clean up all modules
+  mouse.cleanup()
+  keyboard.cleanup()
+  input.cleanup()
+
+  // Show cursor
+  process.stdout.write('\x1b[?25h')
+
+  // Call user cleanup
+  if (cleanupCallback) {
+    cleanupCallback()
+    cleanupCallback = null
+  }
+}
+
+/**
+ * Set whether Ctrl+C exits the application.
+ */
+export function setExitOnCtrlC(enabled: boolean): void {
+  exitOnCtrlC = enabled
+}
+
+/**
+ * Check if global keys system is initialized.
+ */
+export function isInitialized(): boolean {
+  return initialized
+}
+
+// =============================================================================
+// EXPORT
+// =============================================================================
+
+export const globalKeys = {
+  initialize,
+  cleanup,
+  setExitOnCtrlC,
+  isInitialized,
+}

package/src/state/index.ts

@@ -11,9 +11,45 @@
  * - cursor: Cursor visibility, shape, position
  */
 
-// Keyboard is primary for focus navigation
-export * from './keyboard'
-export * from './mouse'
+// Keyboard - explicit exports to avoid conflicts
+export {
+  keyboard,
+  lastKey,
+  lastEvent,
+  on,
+  onKey,
+  onFocused,
+  cleanupIndex,
+  dispatch as dispatchKeyboard,
+  dispatchFocused,
+  cleanup as cleanupKeyboard,
+} from './keyboard'
+export type { Modifiers, KeyState, KeyboardEvent, KeyHandler } from './keyboard'
+
+// Mouse - explicit exports to avoid conflicts
+export {
+  mouse,
+  hitGrid,
+  lastMouseEvent,
+  mouseX,
+  mouseY,
+  isMouseDown,
+  HitGrid,
+  MouseButton,
+  onMouseDown,
+  onMouseUp,
+  onClick,
+  onScroll,
+  onComponent,
+  resize,
+  clearHitGrid,
+  enableTracking,
+  disableTracking,
+  isTrackingEnabled,
+  dispatch as dispatchMouse,
+  cleanup as cleanupMouse,
+} from './mouse'
+export type { MouseAction, ScrollInfo, MouseEvent, MouseHandlers, MouseHandler } from './mouse'
 // Focus exports - exclude duplicates that are in keyboard
 export {
   focusedIndex,
@@ -36,8 +72,8 @@ export {
 export * from './scroll'
 export * from './cursor'
 
-// Convenient namespace exports
-export { keyboard } from './keyboard'
-export { mouse } from './mouse'
-export { scroll } from './scroll'
-export { cursor } from './cursor'
+// Global keys - all shortcuts wired together
+export { globalKeys } from './global-keys'
+
+// Input - stdin ownership
+export { input } from './input'