@rlabs-inc/tui 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rlabs-inc/tui",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "The Terminal UI Framework for TypeScript/Bun - Blazing-fast, fine-grained reactive terminal UI with complete flexbox layout",
   "module": "index.ts",
   "main": "index.ts",

package/src/api/history.ts

@@ -0,0 +1,451 @@
+/**
+ * TUI Framework - History Rendering for Append Mode
+ *
+ * Provides utilities for rendering content to terminal history (scrollback).
+ * Used in append mode where completed content is frozen to history while
+ * active content remains reactive.
+ *
+ * Key concepts:
+ * - History content is written once via FileSink (Bun's efficient stdout writer)
+ * - Uses the same component API as active rendering
+ * - Isolated rendering: creates temporary components, renders, cleans up
+ */
+
+import { batch } from '@rlabs-inc/signals'
+import type { FrameBuffer, RGBA } from '../types'
+import { ComponentType } from '../types'
+import { Colors, TERMINAL_DEFAULT } from '../types/color'
+import {
+  createBuffer,
+  fillRect,
+  drawBorder,
+  drawText,
+  drawTextCentered,
+  drawTextRight,
+  createClipRect,
+  intersectClipRects,
+  type ClipRect,
+  type BorderConfig,
+} from '../renderer/buffer'
+import {
+  getAllocatedIndices,
+  getCapacity,
+  releaseIndex,
+} from '../engine/registry'
+import { wrapText, truncateText } from '../utils/text'
+import {
+  getInheritedFg,
+  getInheritedBg,
+  getBorderColors,
+  getBorderStyles,
+  hasBorder,
+  getEffectiveOpacity,
+} from '../engine/inheritance'
+import { computeLayoutTitan } from '../pipeline/layout/titan-engine'
+import { terminalWidth, terminalHeight } from '../pipeline/layout'
+import * as ansi from '../renderer/ansi'
+
+// Import arrays
+import * as core from '../engine/arrays/core'
+import * as visual from '../engine/arrays/visual'
+import * as text from '../engine/arrays/text'
+import * as spacing from '../engine/arrays/spacing'
+import * as layout from '../engine/arrays/layout'
+import * as interaction from '../engine/arrays/interaction'
+import { Attr } from '../types'
+import { rgbaEqual } from '../types/color'
+
+// =============================================================================
+// FILESINK WRITER
+// =============================================================================
+
+/**
+ * Writer for appending to terminal stdout using Bun's FileSink API.
+ * Buffers writes and flushes efficiently.
+ */
+export class HistoryWriter {
+  private writer: ReturnType<ReturnType<typeof Bun.file>['writer']>
+  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()
+  }
+}
+
+// =============================================================================
+// BUFFER TO ANSI CONVERSION
+// =============================================================================
+
+/**
+ * Convert a FrameBuffer to ANSI escape sequence string.
+ */
+function bufferToAnsi(buffer: FrameBuffer): string {
+  if (buffer.height === 0) return ''
+
+  const chunks: string[] = []
+
+  // Track last colors/attrs for optimization
+  let lastFg: RGBA | null = null
+  let lastBg: RGBA | null = null
+  let lastAttrs: number = Attr.NONE
+
+  for (let y = 0; y < buffer.height; y++) {
+    for (let x = 0; x < buffer.width; x++) {
+      const cell = buffer.cells[y]![x]!
+
+      // Attributes changed - reset first
+      if (cell.attrs !== lastAttrs) {
+        chunks.push(ansi.reset)
+        if (cell.attrs !== Attr.NONE) {
+          chunks.push(ansi.attrs(cell.attrs))
+        }
+        lastFg = null
+        lastBg = null
+        lastAttrs = cell.attrs
+      }
+
+      // Foreground color changed
+      if (!lastFg || !rgbaEqual(cell.fg, lastFg)) {
+        chunks.push(ansi.fg(cell.fg))
+        lastFg = cell.fg
+      }
+
+      // Background color changed
+      if (!lastBg || !rgbaEqual(cell.bg, lastBg)) {
+        chunks.push(ansi.bg(cell.bg))
+        lastBg = cell.bg
+      }
+
+      // Output character
+      if (cell.char === 0) {
+        chunks.push(' ')
+      } else {
+        chunks.push(String.fromCodePoint(cell.char))
+      }
+    }
+    chunks.push('\n')
+  }
+
+  chunks.push(ansi.reset)
+
+  return chunks.join('')
+}
+
+// =============================================================================
+// ISOLATED FRAME BUFFER COMPUTATION
+// =============================================================================
+
+/**
+ * Compute a frame buffer for a specific set of component indices.
+ * Used for isolated history rendering.
+ */
+function computeBufferForIndices(
+  indices: Set<number>,
+  layoutResult: ReturnType<typeof computeLayoutTitan>,
+  tw: number
+): FrameBuffer {
+  const bufferWidth = tw
+  const bufferHeight = Math.max(1, layoutResult.contentHeight)
+
+  // Create fresh buffer
+  const buffer = createBuffer(bufferWidth, bufferHeight, TERMINAL_DEFAULT)
+
+  if (indices.size === 0) {
+    return buffer
+  }
+
+  // Find root components and build child index map (only for our indices)
+  const rootIndices: number[] = []
+  const childMap = new Map<number, number[]>()
+
+  for (const i of indices) {
+    if (core.componentType[i] === ComponentType.NONE) continue
+    const vis = core.visible[i]
+    if (vis === 0 || vis === false) continue
+
+    const parent = core.parentIndex[i] ?? -1
+    if (parent === -1 || !indices.has(parent)) {
+      // Root if no parent or parent not in our set
+      rootIndices.push(i)
+    } else {
+      const children = childMap.get(parent)
+      if (children) {
+        children.push(i)
+      } else {
+        childMap.set(parent, [i])
+      }
+    }
+  }
+
+  // Sort by zIndex
+  rootIndices.sort((a, b) => (layout.zIndex[a] || 0) - (layout.zIndex[b] || 0))
+  for (const children of childMap.values()) {
+    children.sort((a, b) => (layout.zIndex[a] || 0) - (layout.zIndex[b] || 0))
+  }
+
+  // Render tree recursively
+  for (const rootIdx of rootIndices) {
+    renderComponentToBuffer(
+      buffer,
+      rootIdx,
+      layoutResult,
+      childMap,
+      undefined,
+      0,
+      0
+    )
+  }
+
+  return buffer
+}
+
+/**
+ * Render a component and its children to a buffer.
+ */
+function renderComponentToBuffer(
+  buffer: FrameBuffer,
+  index: number,
+  computedLayout: { x: number[]; y: number[]; width: number[]; height: number[]; scrollable: number[] },
+  childMap: Map<number, number[]>,
+  parentClip: ClipRect | undefined,
+  parentScrollY: number,
+  parentScrollX: number
+): void {
+  const vis = core.visible[index]
+  if (vis === 0 || vis === false) return
+  if (core.componentType[index] === ComponentType.NONE) return
+
+  const x = Math.floor((computedLayout.x[index] || 0) - parentScrollX)
+  const y = Math.floor((computedLayout.y[index] || 0) - parentScrollY)
+  const w = Math.floor(computedLayout.width[index] || 0)
+  const h = Math.floor(computedLayout.height[index] || 0)
+
+  if (w <= 0 || h <= 0) return
+
+  const componentBounds = createClipRect(x, y, w, h)
+
+  if (parentClip) {
+    const intersection = intersectClipRects(componentBounds, parentClip)
+    if (!intersection) return
+  }
+
+  // Get colors
+  const fg = getInheritedFg(index)
+  const bg = getInheritedBg(index)
+  const opacity = getEffectiveOpacity(index)
+
+  const effectiveFg = opacity < 1 ? { ...fg, a: Math.round(fg.a * opacity) } : fg
+  const effectiveBg = opacity < 1 ? { ...bg, a: Math.round(bg.a * opacity) } : bg
+
+  // Fill background
+  if (effectiveBg.a > 0 && effectiveBg.r !== -1) {
+    fillRect(buffer, x, y, w, h, effectiveBg, parentClip)
+  }
+
+  // Borders
+  const borderStyles = getBorderStyles(index)
+  const borderColors = getBorderColors(index)
+  const hasAnyBorder = hasBorder(index)
+
+  if (hasAnyBorder && w >= 2 && h >= 2) {
+    const config: BorderConfig = {
+      styles: borderStyles,
+      colors: {
+        top: opacity < 1 ? { ...borderColors.top, a: Math.round(borderColors.top.a * opacity) } : borderColors.top,
+        right: opacity < 1 ? { ...borderColors.right, a: Math.round(borderColors.right.a * opacity) } : borderColors.right,
+        bottom: opacity < 1 ? { ...borderColors.bottom, a: Math.round(borderColors.bottom.a * opacity) } : borderColors.bottom,
+        left: opacity < 1 ? { ...borderColors.left, a: Math.round(borderColors.left.a * opacity) } : borderColors.left,
+      },
+    }
+    drawBorder(buffer, x, y, w, h, config, undefined, parentClip)
+  }
+
+  // Content area
+  const padTop = (spacing.paddingTop[index] || 0) + (hasAnyBorder && borderStyles.top > 0 ? 1 : 0)
+  const padRight = (spacing.paddingRight[index] || 0) + (hasAnyBorder && borderStyles.right > 0 ? 1 : 0)
+  const padBottom = (spacing.paddingBottom[index] || 0) + (hasAnyBorder && borderStyles.bottom > 0 ? 1 : 0)
+  const padLeft = (spacing.paddingLeft[index] || 0) + (hasAnyBorder && borderStyles.left > 0 ? 1 : 0)
+
+  const contentX = x + padLeft
+  const contentY = y + padTop
+  const contentW = w - padLeft - padRight
+  const contentH = h - padTop - padBottom
+
+  const contentBounds = createClipRect(contentX, contentY, contentW, contentH)
+  const contentClip = parentClip
+    ? intersectClipRects(contentBounds, parentClip)
+    : contentBounds
+
+  if (!contentClip || contentW <= 0 || contentH <= 0) {
+    return
+  }
+
+  // Render by type
+  switch (core.componentType[index]) {
+    case ComponentType.BOX:
+      break
+
+    case ComponentType.TEXT:
+      renderTextToBuffer(buffer, index, contentX, contentY, contentW, contentH, effectiveFg, contentClip)
+      break
+
+    // Other types can be added as needed
+  }
+
+  // Render children
+  if (core.componentType[index] === ComponentType.BOX) {
+    const children = childMap.get(index) || []
+    const isScrollable = (computedLayout.scrollable[index] ?? 0) === 1
+    const scrollY = isScrollable ? (interaction.scrollOffsetY[index] || 0) : 0
+    const scrollX = isScrollable ? (interaction.scrollOffsetX[index] || 0) : 0
+
+    for (const childIdx of children) {
+      renderComponentToBuffer(
+        buffer,
+        childIdx,
+        computedLayout,
+        childMap,
+        contentClip,
+        parentScrollY + scrollY,
+        parentScrollX + scrollX
+      )
+    }
+  }
+}
+
+/**
+ * Render text component to buffer.
+ */
+function renderTextToBuffer(
+  buffer: FrameBuffer,
+  index: number,
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+  fg: RGBA,
+  clip: ClipRect
+): void {
+  const rawValue = text.textContent[index]
+  const content = rawValue == null ? '' : String(rawValue)
+  if (!content) return
+
+  const attrs = text.textAttrs[index] || 0
+  const align = text.textAlign[index] || 0
+
+  const lines = wrapText(content, w)
+
+  for (let lineIdx = 0; lineIdx < lines.length && lineIdx < h; lineIdx++) {
+    const line = lines[lineIdx] ?? ''
+    const lineY = y + lineIdx
+
+    if (lineY < clip.y || lineY >= clip.y + clip.height) continue
+
+    switch (align) {
+      case 0:
+        drawText(buffer, x, lineY, line, fg, undefined, attrs, clip)
+        break
+      case 1:
+        drawTextCentered(buffer, x, lineY, w, line, fg, undefined, attrs, clip)
+        break
+      case 2:
+        drawTextRight(buffer, x, lineY, w, line, fg, undefined, attrs, clip)
+        break
+    }
+  }
+}
+
+// =============================================================================
+// RENDER TO HISTORY
+// =============================================================================
+
+/**
+ * Create a renderToHistory function bound to a HistoryWriter and AppendRegionRenderer.
+ *
+ * The renderer is needed to coordinate:
+ * 1. Erase the active area BEFORE writing history
+ * 2. History is written (becomes permanent scrollback)
+ * 3. Next render will start fresh below the history
+ *
+ * Usage:
+ * ```ts
+ * const renderToHistory = createRenderToHistory(historyWriter, appendRegionRenderer)
+ *
+ * // When freezing content:
+ * renderToHistory(() => {
+ *   Message({ content: 'Hello!' })
+ * })
+ * ```
+ */
+export function createRenderToHistory(
+  historyWriter: HistoryWriter,
+  appendRegionRenderer: { eraseActive: () => void }
+) {
+  return function renderToHistory(componentFn: () => void): void {
+    // CRITICAL: Wrap in batch() to prevent reactive updates during this operation.
+    // Without batch, the ReactiveSet triggers updates when we allocate/release indices,
+    // causing the render effect to run mid-operation and duplicate content.
+    batch(() => {
+      // Save current allocated indices BEFORE creating history components
+      const beforeIndices = new Set(getAllocatedIndices())
+
+      // Run component function - creates new components
+      componentFn()
+
+      // Find NEW indices (ones that didn't exist before)
+      const historyIndices = new Set<number>()
+      for (const idx of getAllocatedIndices()) {
+        if (!beforeIndices.has(idx)) {
+          historyIndices.add(idx)
+        }
+      }
+
+      if (historyIndices.size === 0) {
+        return
+      }
+
+      // Get terminal width for layout
+      const tw = terminalWidth.value
+      const th = terminalHeight.value
+
+      // Compute layout for just history components
+      const layoutResult = computeLayoutTitan(tw, th, historyIndices, false)
+
+      // Build frame buffer for history components
+      const buffer = computeBufferForIndices(historyIndices, layoutResult, tw)
+
+      // STEP 2: Convert to ANSI and write to history
+      // This becomes permanent terminal scrollback
+      const output = bufferToAnsi(buffer)
+      historyWriter.write(output)
+      historyWriter.flush()
+
+      // Cleanup: release all history components
+      // Batched, so render effect won't run until after release completes.
+      // The renderer's previousHeight is already 0 from eraseActive(), so next render
+      // will simply render the active area fresh below our history output
+      for (const idx of historyIndices) {
+        releaseIndex(idx)
+      }
+    })
+  }
+}

package/src/api/mount.ts

@@ -23,12 +23,13 @@
  */
 
 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'
@@ -50,12 +51,11 @@ import { globalKeys } from '../state/global-keys'
 export async function mount(
   root: () => void,
   options: MountOptions = {}
-): Promise<() => Promise<void>> {
+): Promise<(() => Promise<void>) | AppendMountResult> {
   const {
     mode = 'fullscreen',
     mouse = true,
     kittyKeyboard = true,
-    getStaticHeight,
   } = options
 
   // Set render mode signal BEFORE creating components
@@ -65,13 +65,21 @@ export async function mount(
   // Create renderer based on mode
   // Fullscreen uses DiffRenderer (absolute positioning)
   // Inline uses InlineRenderer (eraseLines + sequential write)
-  // Append uses AppendRegionRenderer (two-region: static + reactive)
+  // 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)
@@ -171,10 +179,9 @@ export async function mount(
     } else if (mode === 'inline') {
       inlineRenderer.render(buffer)
     } else if (mode === 'append') {
-      // Append mode: use two-region renderer
-      // staticHeight determined by getStaticHeight callback or defaults to 0
-      const staticHeight = getStaticHeight ? getStaticHeight() : 0
-      appendRegionRenderer.render(buffer, { staticHeight })
+      // 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)
@@ -195,7 +202,7 @@ export async function mount(
   })
 
   // Cleanup function
-  return async () => {
+  const cleanup = async () => {
     // Stop the render effect
     if (stopEffect) {
       stopEffect()
@@ -205,9 +212,12 @@ export async function mount(
     // Cleanup global input system
     globalKeys.cleanup()
 
-    // Cleanup append region renderer if used
+    // Cleanup append mode resources
     if (mode === 'append') {
       appendRegionRenderer.cleanup()
+      if (historyWriter) {
+        historyWriter.end()
+      }
     }
 
     // Remove resize listener
@@ -241,5 +251,15 @@ export async function mount(
     // Reset registry for clean slate
     resetRegistry()
   }
+
+  // Return based on mode
+  if (mode === 'append' && renderToHistory) {
+    return {
+      cleanup,
+      renderToHistory,
+    }
+  }
+
+  return cleanup
 }
 

package/src/renderer/append-region.ts

@@ -1,205 +1,84 @@
 /**
- * TUI Framework - Two-Region Append Renderer
+ * TUI Framework - Append Mode Renderer
  *
- * Implements a hybrid static/reactive rendering mode optimized for chat-like UIs:
+ * Simple renderer for append mode:
+ * - Clears active region (eraseDown from cursor)
+ * - Renders active content
  *
- * 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
+ * History content is handled separately via renderToHistory().
+ * The app controls what goes to history vs active area.
  *
- * 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
+ * This renderer is essentially inline mode with cursor at the
+ * boundary between frozen history and active content.
  */
 
-import type { Cell, RGBA, CellAttrs, FrameBuffer } from '../types'
+import type { FrameBuffer, RGBA, CellAttrs } 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
+// APPEND MODE 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)
+ * Simple append mode renderer.
+ * Erases previous active content and renders fresh.
  *
- * The boundary between regions shifts as content completes.
+ * Like InlineRenderer but only erases the active area (preserves history).
  */
 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 = ''
+  // Track previous height to know how many lines to erase
+  private previousHeight = 0
 
   /**
-   * 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 frame buffer as active content.
+   * Erases exactly the previous content, then writes fresh.
    */
-  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)
+  render(buffer: FrameBuffer): void {
+    const output = this.buildOutput(buffer)
 
-    // 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
+    // Erase previous active content (move up and clear each line)
+    if (this.previousHeight > 0) {
+      process.stdout.write(ansi.eraseLines(this.previousHeight))
     }
 
-    // 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)
+    // Render active content
+    process.stdout.write(output)
 
-      this.previousReactiveOutput = reactiveOutput
-    }
+    // Track height for next render
+    // +1 because buildOutput adds trailing newline which moves cursor down one line
+    this.previousHeight = buffer.height + 1
   }
 
   /**
-   * Extract a region from the frame buffer.
+   * Erase the current active area.
+   * Call this BEFORE writing to history so we clear the screen first.
    */
-  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)
+  eraseActive(): void {
+    if (this.previousHeight > 0) {
+      process.stdout.write(ansi.eraseLines(this.previousHeight))
+      this.previousHeight = 0
     }
   }
 
   /**
-   * Build output for static region (append once, forget).
+   * Call this after writing to history.
+   * Resets height tracking so next render doesn't try to erase history.
    */
-  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('')
+  invalidate(): void {
+    this.previousHeight = 0
   }
 
   /**
-   * Build output for reactive region (cleared and re-rendered each frame).
+   * Build output string for the buffer.
    */
-  private buildReactiveOutput(buffer: FrameBuffer): string {
+  private buildOutput(buffer: FrameBuffer): string {
     if (buffer.height === 0) return ''
 
     const chunks: string[] = []
@@ -229,7 +108,7 @@ export class AppendRegionRenderer {
   /**
    * Render a single cell with ANSI optimization.
    */
-  private renderCell(chunks: string[], cell: Cell): void {
+  private renderCell(chunks: string[], cell: { char: number; fg: RGBA; bg: RGBA; attrs: CellAttrs }): void {
     // Attributes changed - reset first
     if (cell.attrs !== this.lastAttrs) {
       chunks.push(ansi.reset)
@@ -262,42 +141,19 @@ export class AppendRegionRenderer {
   }
 
   /**
-   * 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 renderer state.
    */
   reset(): void {
-    this.frozenMessages.clear()
-    this.totalStaticLines = 0
-    this.previousReactiveOutput = ''
+    this.previousHeight = 0
     this.lastFg = null
     this.lastBg = null
     this.lastAttrs = Attr.NONE
   }
 
   /**
-   * Cleanup when unmounting.
+   * Cleanup (no-op for simplified renderer).
    */
   cleanup(): void {
-    this.staticWriter.end()
+    // Nothing to cleanup - we don't own the FileSink
   }
 }

package/src/types/index.ts

@@ -272,8 +272,8 @@ export interface MountOptions {
   /**
    * Render mode:
    * - 'fullscreen': Alternate screen buffer, full terminal control
-   * - 'inline': Renders inline, save/restore cursor, updates in place
-   * - 'append': Content flows down, still reactive (can update previous content)
+   * - 'inline': Renders inline, updates in place
+   * - 'append': Active content at bottom, history via renderToHistory()
    */
   mode?: RenderMode
   /** Enable mouse tracking (default: true) */
@@ -282,12 +282,27 @@ export interface MountOptions {
   kittyKeyboard?: boolean
   /** Initial cursor configuration */
   cursor?: Partial<Cursor>
+}
+
+/**
+ * Result of mount() for append mode.
+ * Includes renderToHistory for writing content to terminal history.
+ */
+export interface AppendMountResult {
+  /** Cleanup function to unmount */
+  cleanup: () => Promise<void>
   /**
-   * For append mode: Function to determine static region height.
-   * Called on each render to decide where to split static/reactive regions.
-   * Return number of lines to freeze into terminal history.
+   * Render components to terminal history (frozen scrollback).
+   * Use the same component API - components are rendered once and forgotten.
+   *
+   * @example
+   * ```ts
+   * renderToHistory(() => {
+   *   Message({ content: 'Frozen message' })
+   * })
+   * ```
    */
-  getStaticHeight?: () => number
+  renderToHistory: (componentFn: () => void) => void
 }
 
 // =============================================================================