feat: add native ghostty alternate screen and line wrapping (#29)

sreya · web-flow · commit b1cc03e24b9c · 2025-11-16T12:18:30.000-05:00
- Add ghostty_terminal_is_alternate_screen() to detect alternate buffer mode
- Add ghostty_terminal_is_row_wrapped() to detect soft-wrapped lines
diff --git a/demo/index.html b/demo/index.html
@@ -301,6 +301,23 @@ <h3>📜 Scrolling Features</h3>
         </div>
       </div>
 
+      <div class="feature-panel">
+        <h3>🔍 Buffer Access API (NEW!)</h3>
+        <div class="button-grid">
+          <button class="test-button" id="btn-testAlternateScreen">🔄 Test Alternate Screen</button>
+          <button class="test-button" id="btn-testWrapping">📏 Test Line Wrapping</button>
+          <button class="test-button" id="btn-testEdgeCases">⚠️ Test Edge Cases</button>
+          <button class="test-button" id="btn-showBufferInfo">ℹ️ Show Buffer Info</button>
+        </div>
+        <div>
+          <strong style="display: block; margin-bottom: 8px">API Test Results:</strong>
+          <div class="event-log" id="buffer-api-log">
+            <div style="opacity: 0.5; text-align: center">Test results will appear here...</div>
+          </div>
+          <button class="clear-log" id="btn-clear-buffer-log">Clear Results</button>
+        </div>
+      </div>
+
       <div class="warning">
         <strong>⚠️ Warning: Full Filesystem Access</strong>
         This demo has unrestricted access to your entire filesystem. It's meant for local
@@ -692,6 +709,167 @@ <h3>📜 Scrolling Features</h3>
           }, 100);
         });
 
+        // =========================================================================
+        // Buffer Access API Handlers (NEW!)
+        // =========================================================================
+
+        function logBufferEvent(message, isSuccess = true) {
+          const bufferLog = document.getElementById('buffer-api-log');
+          const eventDiv = document.createElement('div');
+          eventDiv.className = 'event';
+          eventDiv.innerHTML = `
+            <span class="event-type" style="color: ${isSuccess ? '#4caf50' : '#ff9800'}">${isSuccess ? '✓' : '→'}</span>
+            <span class="event-data">${message}</span>
+          `;
+          bufferLog.appendChild(eventDiv);
+          bufferLog.scrollTop = bufferLog.scrollHeight;
+        }
+
+        document.getElementById('btn-clear-buffer-log').addEventListener('click', () => {
+          const bufferLog = document.getElementById('buffer-api-log');
+          bufferLog.innerHTML =
+            '<div style="opacity: 0.5; text-align: center">Test results will appear here...</div>';
+        });
+
+        document.getElementById('btn-testAlternateScreen').addEventListener('click', async () => {
+          const bufferLog = document.getElementById('buffer-api-log');
+          bufferLog.innerHTML = ''; // Clear log
+
+          logBufferEvent('Testing alternate screen detection...', false);
+
+          // Check initial state
+          const initial = term.wasmTerm?.isAlternateScreen();
+          logBufferEvent(
+            `Initial (normal mode): ${initial === false ? '✓ PASS' : '✗ FAIL'} (${initial})`
+          );
+
+          // Enter alternate screen
+          term.write('\x1b[?1049h');
+          term.write('\x1b[2J\x1b[H'); // Clear and home
+          term.write('\x1b[1;32m╔════════════════════════════════════════╗\r\n');
+          term.write('║     ALTERNATE SCREEN MODE ACTIVE       ║\r\n');
+          term.write('║     (Like vim/less/htop)               ║\r\n');
+          term.write('║                                        ║\r\n');
+          term.write('║     Normal buffer is preserved!        ║\r\n');
+          term.write('║     Exiting in 3 seconds...            ║\r\n');
+          term.write('╚════════════════════════════════════════╝\x1b[0m\r\n');
+
+          const inAlt = term.wasmTerm?.isAlternateScreen();
+          logBufferEvent(`In alternate mode: ${inAlt === true ? '✓ PASS' : '✗ FAIL'} (${inAlt})`);
+
+          // Exit after delay
+          await new Promise((r) => setTimeout(r, 3000));
+          term.write('\x1b[?1049l');
+
+          const afterExit = term.wasmTerm?.isAlternateScreen();
+          logBufferEvent(
+            `After exit (normal mode): ${afterExit === false ? '✓ PASS' : '✗ FAIL'} (${afterExit})`
+          );
+
+          if (initial === false && inAlt === true && afterExit === false) {
+            logBufferEvent('🎉 All alternate screen tests PASSED!', true);
+          }
+        });
+
+        document.getElementById('btn-testWrapping').addEventListener('click', () => {
+          const bufferLog = document.getElementById('buffer-api-log');
+          bufferLog.innerHTML = ''; // Clear log
+
+          logBufferEvent('Testing line wrapping detection...', false);
+
+          term.write('\x1b[2J\x1b[H'); // Clear screen
+
+          // Write short lines (no wrap)
+          term.write('Short line 1\r\n');
+          term.write('Short line 2\r\n');
+
+          const row0 = term.wasmTerm?.isRowWrapped(0);
+          const row1 = term.wasmTerm?.isRowWrapped(1);
+          logBufferEvent(
+            `Row 0 (short line): ${row0 === false ? '✓ PASS' : '✗ FAIL'} (wrapped=${row0})`
+          );
+          logBufferEvent(
+            `Row 1 (short line): ${row1 === false ? '✓ PASS' : '✗ FAIL'} (wrapped=${row1})`
+          );
+
+          // Write long line that wraps
+          term.write(
+            '\x1b[33mThis is a very long line that will definitely wrap to the next line because it is much longer than the terminal width allows for a single line of text!\x1b[0m\r\n'
+          );
+
+          // Check wrapping (row 2 starts long line, row 3+ are continuations)
+          const results = [];
+          for (let i = 2; i < 6; i++) {
+            const wrapped = term.wasmTerm?.isRowWrapped(i);
+            results.push({ row: i, wrapped });
+            logBufferEvent(
+              `Row ${i}: ${wrapped ? 'WRAPPED ↪' : 'NEW LINE ↓'} (wrapped=${wrapped})`
+            );
+          }
+
+          const row2correct = results[0].wrapped === false; // Start of line
+          const row3correct = results[1].wrapped === true; // Continuation
+
+          if (row0 === false && row1 === false && row2correct && row3correct) {
+            logBufferEvent('🎉 Line wrapping tests PASSED!', true);
+          }
+        });
+
+        document.getElementById('btn-testEdgeCases').addEventListener('click', () => {
+          const bufferLog = document.getElementById('buffer-api-log');
+          bufferLog.innerHTML = ''; // Clear log
+
+          logBufferEvent('Testing edge cases...', false);
+
+          // Row 0 can never be wrapped
+          const row0 = term.wasmTerm?.isRowWrapped(0);
+          logBufferEvent(`Row 0 (never wraps): ${row0 === false ? '✓ PASS' : '✗ FAIL'} (${row0})`);
+
+          // Negative row
+          const negRow = term.wasmTerm?.isRowWrapped(-1);
+          logBufferEvent(`Row -1 (invalid): ${negRow === false ? '✓ PASS' : '✗ FAIL'} (${negRow})`);
+
+          // Out of bounds
+          const largeRow = term.wasmTerm?.isRowWrapped(9999);
+          logBufferEvent(
+            `Row 9999 (out of bounds): ${largeRow === false ? '✓ PASS' : '✗ FAIL'} (${largeRow})`
+          );
+
+          if (row0 === false && negRow === false && largeRow === false) {
+            logBufferEvent('🎉 All edge case tests PASSED!', true);
+          }
+        });
+
+        document.getElementById('btn-showBufferInfo').addEventListener('click', () => {
+          const bufferLog = document.getElementById('buffer-api-log');
+          bufferLog.innerHTML = ''; // Clear log
+
+          logBufferEvent('📊 Current Buffer Information:', false);
+
+          const isAlt = term.wasmTerm?.isAlternateScreen();
+          const mode = isAlt
+            ? 'Alternate Screen (vim/less/htop mode)'
+            : 'Normal Screen (shell mode)';
+          logBufferEvent(`Screen Mode: ${mode}`, true);
+
+          logBufferEvent(`Terminal Size: ${term.cols}x${term.rows}`, true);
+
+          // Check wrapping for visible rows
+          let wrappedCount = 0;
+          for (let i = 0; i < term.rows; i++) {
+            if (term.wasmTerm?.isRowWrapped(i)) {
+              wrappedCount++;
+            }
+          }
+          logBufferEvent(`Wrapped Rows: ${wrappedCount}/${term.rows} visible rows`, true);
+
+          // Show first 10 rows wrap status
+          logBufferEvent('First 10 rows wrap status:', false);
+          for (let i = 0; i < Math.min(10, term.rows); i++) {
+            const wrapped = term.wasmTerm?.isRowWrapped(i);
+            logBufferEvent(`  Row ${i}: ${wrapped ? '↪ wrapped' : '↓ new line'}`, true);
+          }
+        });
         // Expose terminal to console for debugging
         window.term = term;
       }
diff --git a/lib/ghostty.ts b/lib/ghostty.ts
@@ -394,6 +394,55 @@ export class GhosttyTerminal {
     return this.exports.ghostty_terminal_get_scrollback_length(this.handle);
   }
 
+  /**
+   * Check if terminal is in alternate screen buffer mode.
+   *
+   * The alternate screen is used by vim, less, htop, etc.
+   * When active, normal buffer is preserved and restored when the app exits.
+   *
+   * @returns true if in alternate screen, false if in normal screen
+   *
+   * @example
+   * ```typescript
+   * // Detect if vim is running
+   * if (term.isAlternateScreen()) {
+   *   console.log('Full-screen app is active');
+   * }
+   * ```
+   */
+  isAlternateScreen(): boolean {
+    return Boolean(this.exports.ghostty_terminal_is_alternate_screen(this.handle));
+  }
+
+  /**
+   * Check if a row is wrapped from the previous row.
+   *
+   * Wrapped rows are continuations of long lines that exceeded terminal width.
+   * Used for text selection to treat wrapped lines as single logical lines.
+   *
+   * @param row Row index (0 = top visible line)
+   * @returns true if row continues from previous line, false otherwise
+   *
+   * @example
+   * ```typescript
+   * // Get full logical line including wraps
+   * let text = '';
+   * for (let row = 0; row < term.rows; row++) {
+   *   const line = term.getLine(row);
+   *   text += lineToString(line);
+   *
+   *   // Only add newline if NOT wrapped
+   *   if (!term.isRowWrapped(row + 1)) {
+   *     text += '\n';
+   *   }
+   * }
+   * ```
+   */
+  isRowWrapped(row: number): boolean {
+    if (row < 0 || row >= this._rows) return false;
+    return Boolean(this.exports.ghostty_terminal_is_row_wrapped(this.handle, row));
+  }
+
   /**
    * Get a line of cells from the visible screen.
    *
diff --git a/lib/terminal.test.ts b/lib/terminal.test.ts
@@ -1093,3 +1093,89 @@ describe('Terminal Options', () => {
     });
   });
 });
+
+describe('Buffer Access API', () => {
+  let term: Terminal;
+  let container: HTMLElement;
+
+  beforeEach(() => {
+    term = new Terminal();
+    if (typeof document !== 'undefined') {
+      container = document.createElement('div');
+      document.body.appendChild(container);
+    }
+  });
+
+  afterEach(() => {
+    term.dispose();
+    if (container && container.parentNode) {
+      container.parentNode.removeChild(container);
+    }
+  });
+
+  test('isAlternateScreen() starts false', async () => {
+    if (!container) return; // Skip if no DOM
+
+    await term.open(container);
+    expect(term.wasmTerm?.isAlternateScreen()).toBe(false);
+  });
+
+  test('isAlternateScreen() detects alternate screen mode', async () => {
+    if (!container) return; // Skip if no DOM
+
+    await term.open(container);
+
+    // Enter alternate screen (DEC Private Mode 1049 - like vim does)
+    term.write('\x1b[?1049h');
+    expect(term.wasmTerm?.isAlternateScreen()).toBe(true);
+
+    // Exit alternate screen
+    term.write('\x1b[?1049l');
+    expect(term.wasmTerm?.isAlternateScreen()).toBe(false);
+  });
+
+  test('isRowWrapped() returns false for normal line breaks', async () => {
+    if (!container) return; // Skip if no DOM
+
+    await term.open(container);
+    term.write('Line 1\r\nLine 2\r\n');
+
+    expect(term.wasmTerm?.isRowWrapped(0)).toBe(false);
+    expect(term.wasmTerm?.isRowWrapped(1)).toBe(false);
+  });
+
+  test('isRowWrapped() detects wrapped lines', async () => {
+    if (typeof document === 'undefined') return; // Skip if no DOM
+
+    // Create narrow terminal to force wrapping
+    const narrowTerm = new Terminal({ cols: 20, rows: 10 });
+    const narrowContainer = document.createElement('div');
+    await narrowTerm.open(narrowContainer);
+
+    try {
+      // Write text longer than terminal width (no newline)
+      narrowTerm.write('This is a very long line that will definitely wrap');
+
+      // First line should not be wrapped (start of line)
+      expect(narrowTerm.wasmTerm?.isRowWrapped(0)).toBe(false);
+
+      // Second line should be wrapped (continuation)
+      expect(narrowTerm.wasmTerm?.isRowWrapped(1)).toBe(true);
+    } finally {
+      narrowTerm.dispose();
+    }
+  });
+
+  test('isRowWrapped() handles edge cases', async () => {
+    if (!container) return; // Skip if no DOM
+
+    await term.open(container);
+
+    // Row 0 can never be wrapped (nothing to wrap from)
+    expect(term.wasmTerm?.isRowWrapped(0)).toBe(false);
+
+    // Out of bounds returns false
+    expect(term.wasmTerm?.isRowWrapped(-1)).toBe(false);
+    expect(term.wasmTerm?.isRowWrapped(999)).toBe(false);
+  });
+});
diff --git a/lib/types.ts b/lib/types.ts
@@ -353,6 +353,8 @@ export interface GhosttyWasmExports extends WebAssembly.Exports {
   ghostty_terminal_get_cursor_x(terminal: TerminalHandle): number;
   ghostty_terminal_get_cursor_y(terminal: TerminalHandle): number;
   ghostty_terminal_get_cursor_visible(terminal: TerminalHandle): boolean;
+  ghostty_terminal_is_alternate_screen(terminal: TerminalHandle): boolean;
+  ghostty_terminal_is_row_wrapped(terminal: TerminalHandle, row: number): boolean;
   ghostty_terminal_is_dirty(terminal: TerminalHandle): boolean;
   ghostty_terminal_is_row_dirty(terminal: TerminalHandle, row: number): boolean;
   ghostty_terminal_clear_dirty(terminal: TerminalHandle): void;
diff --git a/patches/ghostty-wasm-api.patch b/patches/ghostty-wasm-api.patch
