@rlabs-inc/tui 0.1.0 → 0.2.1

package/src/api/mount.ts

@@ -23,17 +23,19 @@
  */
 
 import { effect } from '@rlabs-inc/signals'
-import type { MountOptions, ResizeEvent } from '../types'
+import type { MountOptions, ResizeEvent, AppendMountResult } from '../types'
 import {
   DiffRenderer,
   InlineRenderer,
 } from '../renderer/output'
+import { AppendRegionRenderer } from '../renderer/append-region'
+import { HistoryWriter, createRenderToHistory } from './history'
 import * as ansi from '../renderer/ansi'
 import { frameBufferDerived } from '../pipeline/frameBuffer'
 import { layoutDerived, terminalWidth, terminalHeight, updateTerminalSize, renderMode } from '../pipeline/layout'
 import { resetRegistry } from '../engine/registry'
-import { hitGrid, clearHitGrid } from '../state/mouse'
-import { keyboard } from '../state/keyboard'
+import { hitGrid, clearHitGrid, mouse } from '../state/mouse'
+import { globalKeys } from '../state/global-keys'
 
 // =============================================================================
 // MOUNT
@@ -49,7 +51,7 @@ import { keyboard } from '../state/keyboard'
 export async function mount(
   root: () => void,
   options: MountOptions = {}
-): Promise<() => Promise<void>> {
+): Promise<(() => Promise<void>) | AppendMountResult> {
   const {
     mode = 'fullscreen',
     mouse = true,
@@ -63,12 +65,21 @@ export async function mount(
   // Create renderer based on mode
   // Fullscreen uses DiffRenderer (absolute positioning)
   // Inline uses InlineRenderer (eraseLines + sequential write)
-  // Append uses DiffRenderer for now (TODO: may need AppendRenderer)
+  // Append uses AppendRegionRenderer (eraseDown + render active)
   const diffRenderer = new DiffRenderer()
   const inlineRenderer = new InlineRenderer()
+  const appendRegionRenderer = new AppendRegionRenderer()
+
+  // For append mode: create history writer and renderToHistory function
+  let historyWriter: HistoryWriter | null = null
+  let renderToHistory: ((componentFn: () => void) => void) | null = null
+
+  if (mode === 'append') {
+    historyWriter = new HistoryWriter()
+    renderToHistory = createRenderToHistory(historyWriter, appendRegionRenderer)
+  }
 
   // Mode-specific state
-  let previousHeight = 0  // For append mode: track last rendered height
   let isFirstRender = true
 
   // Resize handlers (keyboard module handles key/mouse)
@@ -87,9 +98,7 @@ export async function mount(
 
   setupSequence.push(ansi.hideCursor)
 
-  if (mouse) {
-    setupSequence.push(ansi.enableMouse)
-  }
+  // Mouse tracking is handled by globalKeys.initialize() via mouse.enableTracking()
 
   if (kittyKeyboard) {
     setupSequence.push(ansi.enableKittyKeyboard)
@@ -101,9 +110,8 @@ export async function mount(
   // Write setup sequence
   process.stdout.write(setupSequence.join(''))
 
-  // Initialize keyboard module (handles stdin, raw mode, input parsing)
-  // Pass cleanup callback for proper shutdown on Ctrl+C
-  keyboard.initialize()
+  // Initialize global input system (stdin, keyboard, mouse, shortcuts)
+  globalKeys.initialize({ enableMouse: mouse })
 
   // Handle resize
   const handleResize = () => {
@@ -127,20 +135,29 @@ export async function mount(
   // Create the component tree
   root()
 
+  // Global error handlers for debugging
+  process.on('uncaughtException', (err) => {
+    console.error('[TUI] Uncaught exception:', err)
+  })
+  process.on('unhandledRejection', (err) => {
+    console.error('[TUI] Unhandled rejection:', err)
+  })
+
   // THE ONE RENDER EFFECT
   // This is where the magic happens - reactive rendering!
   // Side effects (HitGrid) are applied HERE, not in the derived.
   let stopEffect: (() => void) | null = null
 
   stopEffect = effect(() => {
+    try {
     const start = Bun.nanoseconds()
 
     // Time layout separately (reading .value triggers computation if needed)
-    // const layoutStart = Bun.nanoseconds()
-    // const _layout = layoutDerived.value
-    // const layoutNs = Bun.nanoseconds() - layoutStart
+    const layoutStart = Bun.nanoseconds()
+    const computedLayout = layoutDerived.value
+    const layoutNs = Bun.nanoseconds() - layoutStart
 
-    // Time buffer computation
+    // Time buffer computation (layout is cached, so this is just framebuffer)
     const bufferStart = Bun.nanoseconds()
     const { buffer, hitRegions, terminalSize } = frameBufferDerived.value
     const bufferNs = Bun.nanoseconds() - bufferStart
@@ -161,7 +178,12 @@ export async function mount(
       diffRenderer.render(buffer)
     } else if (mode === 'inline') {
       inlineRenderer.render(buffer)
+    } else if (mode === 'append') {
+      // Append mode: render active content only
+      // History is written via renderToHistory() by the app
+      appendRegionRenderer.render(buffer)
     } else {
+      // Fallback to inline for unknown modes
       inlineRenderer.render(buffer)
     }
     const renderNs = Bun.nanoseconds() - renderStart
@@ -169,24 +191,34 @@ export async function mount(
     const totalNs = Bun.nanoseconds() - start
 
     // Show all timing stats in window title
-    // const layoutMs = layoutNs / 1_000_000
+    const layoutMs = layoutNs / 1_000_000
     const bufferMs = bufferNs / 1_000_000
     const renderMs = renderNs / 1_000_000
     const totalMs = totalNs / 1_000_000
-    // process.stdout.write(`\x1b]0;TUI | ${mode} | layout: ${layoutMs.toFixed(3)}ms | buffer: ${bufferMs.toFixed(3)}ms | render: ${renderMs.toFixed(3)}ms | total: ${totalMs.toFixed(3)}ms\x07`)
-    process.stdout.write(`\x1b]0;TUI | ${mode} | buffer: ${bufferMs.toFixed(3)}ms | render: ${renderMs.toFixed(3)}ms | total: ${totalMs.toFixed(3)}ms\x07`)
+    process.stdout.write(`\x1b]0;TUI | h:${computedLayout.contentHeight} | layout: ${layoutMs.toFixed(3)}ms | buffer: ${bufferMs.toFixed(3)}ms | render: ${renderMs.toFixed(3)}ms | total: ${totalMs.toFixed(3)}ms\x07`)
+    } catch (err) {
+      console.error('[TUI] Render effect error:', err)
+    }
   })
 
   // Cleanup function
-  return async () => {
+  const cleanup = async () => {
     // Stop the render effect
     if (stopEffect) {
       stopEffect()
       stopEffect = null
     }
 
-    // Cleanup keyboard module (removes stdin listener, restores terminal)
-    keyboard.cleanup()
+    // Cleanup global input system
+    globalKeys.cleanup()
+
+    // Cleanup append mode resources
+    if (mode === 'append') {
+      appendRegionRenderer.cleanup()
+      if (historyWriter) {
+        historyWriter.end()
+      }
+    }
 
     // Remove resize listener
     process.stdout.removeListener('resize', handleResize)
@@ -201,11 +233,7 @@ export async function mount(
       restoreSequence.push(ansi.disableKittyKeyboard)
     }
 
-    if (mouse) {
-      restoreSequence.push(ansi.disableMouse)
-    }
-
-    restoreSequence.push(ansi.showCursor)
+    // Mouse disable and cursor show handled by globalKeys.cleanup()
     restoreSequence.push(ansi.reset)
 
     if (mode === 'fullscreen') {
@@ -218,13 +246,20 @@ export async function mount(
 
     process.stdout.write(restoreSequence.join(''))
 
-    // Disable raw mode
-    if (process.stdin.isTTY) {
-      process.stdin.setRawMode(false)
-    }
+    // Raw mode disabled by globalKeys.cleanup() -> input.cleanup()
 
     // Reset registry for clean slate
     resetRegistry()
   }
+
+  // Return based on mode
+  if (mode === 'append' && renderToHistory) {
+    return {
+      cleanup,
+      renderToHistory,
+    }
+  }
+
+  return cleanup
 }
 

package/src/engine/arrays/core.ts

@@ -8,53 +8,45 @@
  *
  * NOTE: Focus state (focusable, tabIndex) is in interaction.ts
  *
- * CRITICAL: Arrays storing Bindings must be regular arrays (NOT state!)
- * state() proxies snapshot getter values, breaking reactivity.
- * componentType is the exception - it stores values directly, not bindings.
+ * Uses slotArray for stable reactive cells that NEVER get replaced.
+ * componentType is the exception - it stores values directly, not reactively.
  */
 
-import { bind, disconnectBinding, type Binding } from '@rlabs-inc/signals'
+import { slotArray, type SlotArray } from '@rlabs-inc/signals'
 import { ComponentType } from '../../types'
 import type { ComponentTypeValue } from '../../types'
 
-/** Component type (box, text, input, etc.) - stores values directly */
+/** Component type (box, text, input, etc.) - stores values directly (not reactive) */
 export const componentType: ComponentTypeValue[] = []
 
 /** Parent component index (-1 for root) */
-export const parentIndex: Binding<number>[] = []
+export const parentIndex: SlotArray<number> = slotArray<number>(-1)
 
 /** Is component visible (0/false = hidden, 1/true = visible) */
-export const visible: Binding<number | boolean>[] = []
+export const visible: SlotArray<number | boolean> = slotArray<number | boolean>(1)
 
 /** Component ID (for debugging and lookups) */
-export const componentId: Binding<string>[] = []
+export const componentId: SlotArray<string> = slotArray<string>('')
 
 /**
  * Ensure array has capacity for the given index.
  * Called by registry when allocating.
- *
- * LAZY BINDING: We push undefined here, not bindings.
- * Primitives create bindings only for props they actually use.
- * This reduces memory from ~70 bindings/component to ~5-10.
  */
 export function ensureCapacity(index: number): void {
   while (componentType.length <= index) {
     componentType.push(ComponentType.NONE)
-    parentIndex.push(undefined as any)
-    visible.push(undefined as any)
-    componentId.push(undefined as any)
   }
+  parentIndex.ensureCapacity(index)
+  visible.ensureCapacity(index)
+  componentId.ensureCapacity(index)
 }
 
 /** Clear values at index (called when releasing) */
 export function clearAtIndex(index: number): void {
   if (index < componentType.length) {
     componentType[index] = ComponentType.NONE
-    disconnectBinding(parentIndex[index])
-    disconnectBinding(visible[index])
-    disconnectBinding(componentId[index])
-    parentIndex[index] = undefined as any
-    visible[index] = undefined as any
-    componentId[index] = undefined as any
   }
+  parentIndex.clear(index)
+  visible.clear(index)
+  componentId.clear(index)
 }

package/src/engine/arrays/dimensions.ts

@@ -5,8 +5,7 @@
  * These are INPUT values that components write.
  * The layout derived READS these and RETURNS computed positions.
  *
- * CRITICAL: Use regular arrays (NOT state!) to preserve binding getters.
- * state() proxies snapshot getter values, breaking reactivity.
+ * Uses slotArray for stable reactive cells that NEVER get replaced.
  *
  * Supports both absolute and percentage dimensions:
  *   - number: Absolute value in cells (e.g., 50)
@@ -17,52 +16,43 @@
  * Note: 0 means "auto" for width/height, "no constraint" for min/max.
  */
 
-import { bind, disconnectBinding, type Binding } from '@rlabs-inc/signals'
+import { slotArray, type SlotArray } from '@rlabs-inc/signals'
 import type { Dimension } from '../../types'
 
 /** Requested width (0 = auto, '100%' = full parent width) */
-export const width: Binding<Dimension>[] = []
+export const width: SlotArray<Dimension> = slotArray<Dimension>(0)
 
 /** Requested height (0 = auto, '100%' = full parent height) */
-export const height: Binding<Dimension>[] = []
+export const height: SlotArray<Dimension> = slotArray<Dimension>(0)
 
 /** Minimum width constraint */
-export const minWidth: Binding<Dimension>[] = []
+export const minWidth: SlotArray<Dimension> = slotArray<Dimension>(0)
 
 /** Minimum height constraint */
-export const minHeight: Binding<Dimension>[] = []
+export const minHeight: SlotArray<Dimension> = slotArray<Dimension>(0)
 
 /** Maximum width constraint (0 = no max) */
-export const maxWidth: Binding<Dimension>[] = []
+export const maxWidth: SlotArray<Dimension> = slotArray<Dimension>(0)
 
 /** Maximum height constraint (0 = no max) */
-export const maxHeight: Binding<Dimension>[] = []
+export const maxHeight: SlotArray<Dimension> = slotArray<Dimension>(0)
 
-/** LAZY BINDING: Push undefined, primitives create bindings for used props only */
+/** Ensure capacity for all dimension arrays */
 export function ensureCapacity(index: number): void {
-  while (width.length <= index) {
-    width.push(undefined as any)
-    height.push(undefined as any)
-    minWidth.push(undefined as any)
-    minHeight.push(undefined as any)
-    maxWidth.push(undefined as any)
-    maxHeight.push(undefined as any)
-  }
+  width.ensureCapacity(index)
+  height.ensureCapacity(index)
+  minWidth.ensureCapacity(index)
+  minHeight.ensureCapacity(index)
+  maxWidth.ensureCapacity(index)
+  maxHeight.ensureCapacity(index)
 }
 
+/** Clear slot at index (reset to default) */
 export function clearAtIndex(index: number): void {
-  if (index < width.length) {
-    disconnectBinding(width[index])
-    disconnectBinding(height[index])
-    disconnectBinding(minWidth[index])
-    disconnectBinding(minHeight[index])
-    disconnectBinding(maxWidth[index])
-    disconnectBinding(maxHeight[index])
-    width[index] = undefined as any
-    height[index] = undefined as any
-    minWidth[index] = undefined as any
-    minHeight[index] = undefined as any
-    maxWidth[index] = undefined as any
-    maxHeight[index] = undefined as any
-  }
+  width.clear(index)
+  height.clear(index)
+  minWidth.clear(index)
+  minHeight.clear(index)
+  maxWidth.clear(index)
+  maxHeight.clear(index)
 }

package/src/engine/arrays/index.ts

@@ -4,8 +4,11 @@
  * All component state lives in these parallel arrays.
  * Each array index corresponds to one component.
  *
- * Components write directly to these arrays.
- * Deriveds read from these arrays and RETURN computed values.
+ * Components write directly to these arrays using setSource().
+ * Deriveds read from these arrays directly (no unwrap needed).
+ *
+ * All arrays use slotArray for stable reactive cells that NEVER get replaced.
+ * This fixes the bind() tracking bug where deriveds miss updates.
  *
  * Array categories:
  * - core: Component type, parent, visibility
@@ -25,7 +28,7 @@ export * as visual from './visual'
 export * as text from './text'
 export * as interaction from './interaction'
 
-import { disconnectBinding } from '@rlabs-inc/signals'
+import { type SlotArray } from '@rlabs-inc/signals'
 import * as core from './core'
 import * as dimensions from './dimensions'
 import * as spacing from './spacing'
@@ -62,12 +65,11 @@ export function clearAllAtIndex(index: number): void {
   interaction.clearAtIndex(index)
 }
 
-/** Disconnect all bindings in an array before truncating */
-function disconnectArray(arr: unknown[]): void {
+/** Clear all slots in a SlotArray (slots are stable, just reset to defaults) */
+function clearSlotArray<T>(arr: SlotArray<T>): void {
   for (let i = 0; i < arr.length; i++) {
-    disconnectBinding(arr[i] as any)
+    arr.clear(i)
   }
-  arr.length = 0
 }
 
 /**
@@ -75,92 +77,92 @@ function disconnectArray(arr: unknown[]): void {
  * Called automatically when all components are destroyed (allocatedIndices.size === 0).
  * This is the "reset on zero" cleanup - no manual API needed!
  *
- * IMPORTANT: Disconnects all bindings before truncating to break circular refs.
+ * SlotArrays are stable - we just clear them to defaults.
  */
 export function resetAllArrays(): void {
-  // Core arrays
+  // Core arrays (componentType is plain array, rest are slotArrays)
   core.componentType.length = 0
-  disconnectArray(core.parentIndex)
-  disconnectArray(core.visible)
-  disconnectArray(core.componentId)
+  clearSlotArray(core.parentIndex)
+  clearSlotArray(core.visible)
+  clearSlotArray(core.componentId)
 
-  // Dimension arrays
-  disconnectArray(dimensions.width)
-  disconnectArray(dimensions.height)
-  disconnectArray(dimensions.minWidth)
-  disconnectArray(dimensions.minHeight)
-  disconnectArray(dimensions.maxWidth)
-  disconnectArray(dimensions.maxHeight)
+  // Dimension arrays (all slotArrays)
+  clearSlotArray(dimensions.width)
+  clearSlotArray(dimensions.height)
+  clearSlotArray(dimensions.minWidth)
+  clearSlotArray(dimensions.minHeight)
+  clearSlotArray(dimensions.maxWidth)
+  clearSlotArray(dimensions.maxHeight)
 
-  // Spacing arrays
-  disconnectArray(spacing.marginTop)
-  disconnectArray(spacing.marginRight)
-  disconnectArray(spacing.marginBottom)
-  disconnectArray(spacing.marginLeft)
-  disconnectArray(spacing.paddingTop)
-  disconnectArray(spacing.paddingRight)
-  disconnectArray(spacing.paddingBottom)
-  disconnectArray(spacing.paddingLeft)
-  disconnectArray(spacing.gap)
-  disconnectArray(spacing.rowGap)
-  disconnectArray(spacing.columnGap)
+  // Spacing arrays (all slotArrays)
+  clearSlotArray(spacing.marginTop)
+  clearSlotArray(spacing.marginRight)
+  clearSlotArray(spacing.marginBottom)
+  clearSlotArray(spacing.marginLeft)
+  clearSlotArray(spacing.paddingTop)
+  clearSlotArray(spacing.paddingRight)
+  clearSlotArray(spacing.paddingBottom)
+  clearSlotArray(spacing.paddingLeft)
+  clearSlotArray(spacing.gap)
+  clearSlotArray(spacing.rowGap)
+  clearSlotArray(spacing.columnGap)
 
-  // Layout arrays
-  disconnectArray(layout.flexDirection)
-  disconnectArray(layout.flexWrap)
-  disconnectArray(layout.justifyContent)
-  disconnectArray(layout.alignItems)
-  disconnectArray(layout.alignContent)
-  disconnectArray(layout.flexGrow)
-  disconnectArray(layout.flexShrink)
-  disconnectArray(layout.flexBasis)
-  disconnectArray(layout.alignSelf)
-  disconnectArray(layout.order)
-  disconnectArray(layout.position)
-  disconnectArray(layout.top)
-  disconnectArray(layout.right)
-  disconnectArray(layout.bottom)
-  disconnectArray(layout.left)
-  disconnectArray(layout.borderTop)
-  disconnectArray(layout.borderRight)
-  disconnectArray(layout.borderBottom)
-  disconnectArray(layout.borderLeft)
-  disconnectArray(layout.zIndex)
-  disconnectArray(layout.overflow)
+  // Layout arrays (all slotArrays)
+  clearSlotArray(layout.flexDirection)
+  clearSlotArray(layout.flexWrap)
+  clearSlotArray(layout.justifyContent)
+  clearSlotArray(layout.alignItems)
+  clearSlotArray(layout.alignContent)
+  clearSlotArray(layout.flexGrow)
+  clearSlotArray(layout.flexShrink)
+  clearSlotArray(layout.flexBasis)
+  clearSlotArray(layout.alignSelf)
+  clearSlotArray(layout.order)
+  clearSlotArray(layout.position)
+  clearSlotArray(layout.top)
+  clearSlotArray(layout.right)
+  clearSlotArray(layout.bottom)
+  clearSlotArray(layout.left)
+  clearSlotArray(layout.borderTop)
+  clearSlotArray(layout.borderRight)
+  clearSlotArray(layout.borderBottom)
+  clearSlotArray(layout.borderLeft)
+  clearSlotArray(layout.zIndex)
+  clearSlotArray(layout.overflow)
 
-  // Visual arrays
-  disconnectArray(visual.fgColor)
-  disconnectArray(visual.bgColor)
-  disconnectArray(visual.opacity)
-  disconnectArray(visual.borderStyle)
-  disconnectArray(visual.borderColor)
-  disconnectArray(visual.borderTop)
-  disconnectArray(visual.borderRight)
-  disconnectArray(visual.borderBottom)
-  disconnectArray(visual.borderLeft)
-  disconnectArray(visual.borderColorTop)
-  disconnectArray(visual.borderColorRight)
-  disconnectArray(visual.borderColorBottom)
-  disconnectArray(visual.borderColorLeft)
-  disconnectArray(visual.showFocusRing)
-  disconnectArray(visual.focusRingColor)
+  // Visual arrays (all slotArrays)
+  clearSlotArray(visual.fgColor)
+  clearSlotArray(visual.bgColor)
+  clearSlotArray(visual.opacity)
+  clearSlotArray(visual.borderStyle)
+  clearSlotArray(visual.borderColor)
+  clearSlotArray(visual.borderTop)
+  clearSlotArray(visual.borderRight)
+  clearSlotArray(visual.borderBottom)
+  clearSlotArray(visual.borderLeft)
+  clearSlotArray(visual.borderColorTop)
+  clearSlotArray(visual.borderColorRight)
+  clearSlotArray(visual.borderColorBottom)
+  clearSlotArray(visual.borderColorLeft)
+  clearSlotArray(visual.showFocusRing)
+  clearSlotArray(visual.focusRingColor)
 
-  // Text arrays
-  disconnectArray(text.textContent)
-  disconnectArray(text.textAttrs)
-  disconnectArray(text.textAlign)
-  disconnectArray(text.textWrap)
-  disconnectArray(text.ellipsis)
+  // Text arrays (all slotArrays)
+  clearSlotArray(text.textContent)
+  clearSlotArray(text.textAttrs)
+  clearSlotArray(text.textAlign)
+  clearSlotArray(text.textWrap)
+  clearSlotArray(text.ellipsis)
 
-  // Interaction arrays
-  disconnectArray(interaction.scrollOffsetX)
-  disconnectArray(interaction.scrollOffsetY)
-  disconnectArray(interaction.focusable)
-  disconnectArray(interaction.tabIndex)
-  disconnectArray(interaction.hovered)
-  disconnectArray(interaction.pressed)
-  disconnectArray(interaction.mouseEnabled)
-  disconnectArray(interaction.cursorPosition)
-  disconnectArray(interaction.selectionStart)
-  disconnectArray(interaction.selectionEnd)
+  // Interaction arrays (all slotArrays)
+  clearSlotArray(interaction.scrollOffsetX)
+  clearSlotArray(interaction.scrollOffsetY)
+  clearSlotArray(interaction.focusable)
+  clearSlotArray(interaction.tabIndex)
+  clearSlotArray(interaction.hovered)
+  clearSlotArray(interaction.pressed)
+  clearSlotArray(interaction.mouseEnabled)
+  clearSlotArray(interaction.cursorPosition)
+  clearSlotArray(interaction.selectionStart)
+  clearSlotArray(interaction.selectionEnd)
 }