ccmanager 0.1.0 → 0.1.1

package/dist/components/Session.js

@@ -1,6 +1,7 @@
 import { useEffect, useState } from 'react';
 import { useStdout } from 'ink';
 import { shortcutManager } from '../services/shortcutManager.js';
+import { TerminalSerializer } from '../utils/terminalSerializer.js';
 const Session = ({ session, sessionManager, onReturnToMenu, }) => {
     const { stdout } = useStdout();
     const [isExiting, setIsExiting] = useState(false);
@@ -12,24 +13,24 @@ const Session = ({ session, sessionManager, onReturnToMenu, }) => {
         // Handle session restoration
         const handleSessionRestore = (restoredSession) => {
             if (restoredSession.id === session.id) {
-                // Replay all buffered output, but skip the initial clear if present
-                for (let i = 0; i < restoredSession.outputHistory.length; i++) {
-                    const buffer = restoredSession.outputHistory[i];
-                    if (!buffer)
-                        continue;
-                    const str = buffer.toString('utf8');
-                    // Skip clear screen sequences at the beginning
-                    if (i === 0 && (str.includes('\x1B[2J') || str.includes('\x1B[H'))) {
-                        // Skip this buffer or remove the clear sequence
-                        const cleaned = str
-                            .replace(/\x1B\[2J/g, '')
-                            .replace(/\x1B\[H/g, '');
-                        if (cleaned.length > 0) {
-                            stdout.write(Buffer.from(cleaned, 'utf8'));
-                        }
-                    }
-                    else {
-                        stdout.write(buffer);
+                // Instead of replaying all history, use the virtual terminal's current buffer
+                // This avoids duplicate content issues
+                const terminal = restoredSession.terminal;
+                if (terminal) {
+                    // Use the TerminalSerializer to preserve ANSI escape sequences (colors, styles)
+                    const serializedOutput = TerminalSerializer.serialize(terminal, {
+                        trimRight: true,
+                        includeEmptyLines: true,
+                    });
+                    // Write the serialized terminal state with preserved formatting
+                    if (serializedOutput) {
+                        stdout.write(serializedOutput);
+                        // Position cursor at the correct location
+                        const buffer = terminal.buffer.active;
+                        const cursorY = buffer.cursorY;
+                        const cursorX = buffer.cursorX;
+                        // Move cursor to the saved position
+                        stdout.write(`\x1B[${cursorY + 1};${cursorX + 1}H`);
                     }
                 }
             }

package/dist/services/sessionManager.colorRestore.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/sessionManager.colorRestore.test.js

@@ -0,0 +1,142 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { SessionManager } from './sessionManager.js';
+import { spawn } from 'node-pty';
+// Create mock pty process
+const createMockPtyProcess = () => {
+    const handlers = {
+        data: [],
+        exit: [],
+    };
+    return {
+        write: vi.fn(),
+        resize: vi.fn(),
+        onData: vi.fn((handler) => {
+            handlers.data.push(handler);
+        }),
+        onExit: vi.fn((handler) => {
+            handlers.exit.push(handler);
+        }),
+        kill: vi.fn(),
+        _emit: (event, ...args) => {
+            if (event === 'data' && handlers.data.length > 0) {
+                handlers.data.forEach(h => h(args[0]));
+            }
+            else if (event === 'exit' && handlers.exit.length > 0) {
+                handlers.exit.forEach(h => h(args[0]));
+            }
+        },
+    };
+};
+// Mock node-pty
+vi.mock('node-pty', () => ({
+    spawn: vi.fn(),
+}));
+// Don't mock @xterm/headless - let it use the real implementation
+// since we need actual terminal functionality for color testing
+describe('SessionManager - Color Restoration', () => {
+    let sessionManager;
+    const mockWorktreePath = '/test/worktree';
+    beforeEach(() => {
+        sessionManager = new SessionManager();
+        vi.clearAllMocks();
+    });
+    it('should preserve ANSI colors when switching between sessions', async () => {
+        // Create a mock PTY process
+        const mockProcess = createMockPtyProcess();
+        vi.mocked(spawn).mockReturnValue(mockProcess);
+        sessionManager.createSession(mockWorktreePath);
+        const session = sessionManager.sessions.get(mockWorktreePath);
+        expect(session).toBeDefined();
+        // Simulate colorful output from Claude Code
+        const colorfulData = [
+            '\x1b[32m✓\x1b[0m File created successfully\n',
+            '\x1b[1;34mRunning tests...\x1b[0m\n',
+            '\x1b[38;5;196mError:\x1b[0m Test failed\n',
+            '\x1b[38;2;255;165;0mWarning:\x1b[0m Deprecated API\n',
+        ];
+        // Activate session first
+        sessionManager.setSessionActive(mockWorktreePath, true);
+        // Send colored data to the terminal
+        for (const data of colorfulData) {
+            mockProcess._emit('data', data);
+            // Wait for terminal to process the data
+            await new Promise(resolve => setTimeout(resolve, 10));
+        }
+        // Deactivate session
+        sessionManager.setSessionActive(mockWorktreePath, false);
+        // Set up listener to capture restore event
+        let restoredContent = null;
+        sessionManager.on('sessionRestore', restoredSession => {
+            // In real usage, the Session component would use TerminalSerializer here
+            // For this test, we'll verify the terminal buffer contains the data
+            const terminal = restoredSession.terminal;
+            if (terminal) {
+                // Access the terminal buffer to verify colors are preserved
+                const buffer = terminal.buffer.active;
+                restoredContent = '';
+                // Simple check: verify buffer has content
+                for (let i = 0; i < buffer.length; i++) {
+                    const line = buffer.getLine(i);
+                    if (line) {
+                        // Check if line has colored cells
+                        for (let x = 0; x < terminal.cols; x++) {
+                            const cell = line.getCell(x);
+                            if (cell && cell.getChars()) {
+                                const fgColorMode = cell.getFgColorMode();
+                                const bgColorMode = cell.getBgColorMode();
+                                // If any cell has non-default color, we know colors are preserved
+                                if (fgColorMode !== 0 || bgColorMode !== 0) {
+                                    restoredContent = 'has-colors';
+                                    break;
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        });
+        // Reactivate session (simulating switching back)
+        sessionManager.setSessionActive(mockWorktreePath, true);
+        // Verify that colors were preserved in the terminal buffer
+        expect(restoredContent).toBe('has-colors');
+    });
+    it('should handle complex color sequences during restoration', async () => {
+        // Create a mock PTY process
+        const mockProcess = createMockPtyProcess();
+        vi.mocked(spawn).mockReturnValue(mockProcess);
+        sessionManager.createSession(mockWorktreePath);
+        const session = sessionManager.sessions.get(mockWorktreePath);
+        // Activate session
+        sessionManager.setSessionActive(mockWorktreePath, true);
+        // Send a complex sequence with cursor movements and color changes
+        const complexSequence = [
+            'Line 1: Normal text\n',
+            '\x1b[32mLine 2: Green text\x1b[0m\n',
+            '\x1b[1A\x1b[K\x1b[31mLine 2: Now red text\x1b[0m\n', // Move up, clear line, write red
+            '\x1b[1;33mLine 3: Bold yellow\x1b[0m\n',
+            '\x1b[48;5;17m\x1b[38;5;231mWhite on dark blue background\x1b[0m\n',
+        ];
+        for (const data of complexSequence) {
+            mockProcess._emit('data', data);
+            await new Promise(resolve => setTimeout(resolve, 10));
+        }
+        // Check terminal has processed the sequences correctly
+        const terminal = session.terminal;
+        expect(terminal).toBeDefined();
+        // Verify buffer contains content (actual color verification would require
+        // checking individual cells, which is done in terminalSerializer.test.ts)
+        const buffer = terminal.buffer.active;
+        let hasContent = false;
+        for (let i = 0; i < buffer.length; i++) {
+            const line = buffer.getLine(i);
+            if (line) {
+                const text = line.translateToString(true);
+                if (text.trim()) {
+                    hasContent = true;
+                    break;
+                }
+            }
+        }
+        expect(hasContent).toBe(true);
+    });
+});

package/dist/services/sessionManager.integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/sessionManager.integration.test.js

@@ -0,0 +1,178 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { SessionManager } from './sessionManager.js';
+import { spawn } from 'node-pty';
+// Create mock pty process
+const createMockPtyProcess = () => {
+    const handlers = {
+        data: [],
+        exit: [],
+    };
+    return {
+        write: vi.fn(),
+        resize: vi.fn(),
+        onData: vi.fn((handler) => {
+            handlers.data.push(handler);
+        }),
+        onExit: vi.fn((handler) => {
+            handlers.exit.push(handler);
+        }),
+        kill: vi.fn(),
+        _emit: (event, ...args) => {
+            if (event === 'data' && handlers.data.length > 0) {
+                handlers.data.forEach(h => h(args[0]));
+            }
+            else if (event === 'exit' && handlers.exit.length > 0) {
+                handlers.exit.forEach(h => h(args[0]));
+            }
+        },
+    };
+};
+// Mock node-pty
+vi.mock('node-pty', () => ({
+    spawn: vi.fn(),
+}));
+// Mock @xterm/headless
+vi.mock('@xterm/headless', () => ({
+    default: {
+        Terminal: vi.fn().mockImplementation(() => ({
+            buffer: {
+                active: {
+                    length: 10,
+                    cursorY: 0,
+                    cursorX: 0,
+                    getLine: vi.fn(),
+                },
+            },
+            write: vi.fn(),
+            resize: vi.fn(),
+            clear: vi.fn(),
+            onData: vi.fn(),
+        })),
+    },
+}));
+describe('SessionManager - Partial TUI Update Integration', () => {
+    let sessionManager;
+    const mockWorktreePath = '/test/worktree';
+    beforeEach(() => {
+        sessionManager = new SessionManager();
+        vi.clearAllMocks();
+    });
+    it('should not accumulate duplicate content in output history', () => {
+        // Create a mock PTY process
+        const mockProcess = createMockPtyProcess();
+        vi.mocked(spawn).mockReturnValue(mockProcess);
+        // Create a session
+        sessionManager.createSession(mockWorktreePath);
+        const session = sessionManager.sessions.get(mockWorktreePath);
+        expect(session).toBeDefined();
+        // Simulate multiple partial updates from Claude Code
+        const updates = [
+            '+ Exploring... (10s ・ 53 tokens ・ esc to interrupt)\r',
+            '\x1B[1A\x1B[K+ Exploring... (10s ・ 57 tokens ・ esc to interrupt)\r',
+            '\x1B[1A\x1B[K+ Exploring... (10s ・ 76 tokens ・ esc to interrupt)\r',
+            '\x1B[1A\x1B[K+ Exploring... (10s ・ 89 tokens ・ esc to interrupt)\r',
+            '\x1B[1A\x1B[K+ Exploring... (10s ・ 102 tokens ・ esc to interrupt)\r',
+        ];
+        // Process each update
+        updates.forEach(update => {
+            // Simulate PTY data event
+            mockProcess._emit('data', update);
+        });
+        // Check that the virtual terminal received all updates
+        expect(session.terminal.write).toHaveBeenCalledTimes(5);
+        // The outputHistory should be empty since we removed that functionality
+        expect(session.outputHistory).toEqual([]);
+    });
+    it('should use virtual terminal buffer for session restoration', () => {
+        // Create a mock PTY process
+        const mockProcess = createMockPtyProcess();
+        vi.mocked(spawn).mockReturnValue(mockProcess);
+        sessionManager.createSession(mockWorktreePath);
+        const session = sessionManager.sessions.get(mockWorktreePath);
+        // Mock the terminal buffer to contain the final state
+        // Type cast is acceptable for test mocks
+        const mockTerminal = session.terminal;
+        mockTerminal.buffer.active.getLine = vi.fn((index) => {
+            const lines = [
+                'Welcome to Claude Code',
+                '+ Exploring... (10s ・ 218 tokens ・ esc to interrupt)',
+                '',
+                'Task completed successfully',
+                '> ',
+            ];
+            if (index < lines.length) {
+                return {
+                    translateToString: () => lines[index],
+                };
+            }
+            return null;
+        });
+        mockTerminal.buffer.active.length = 5;
+        mockTerminal.buffer.active.cursorY = 4;
+        mockTerminal.buffer.active.cursorX = 2;
+        // Emit restore event
+        sessionManager.emit('sessionRestore', session);
+        // The terminal buffer should be used for restoration, not output history
+        // This prevents duplicate content issues
+        expect(session.outputHistory).toEqual([]);
+    });
+    it('should handle ANSI escape sequences correctly in virtual terminal', () => {
+        // Create a mock PTY process
+        const mockProcess = createMockPtyProcess();
+        vi.mocked(spawn).mockReturnValue(mockProcess);
+        sessionManager.createSession(mockWorktreePath);
+        const session = sessionManager.sessions.get(mockWorktreePath);
+        // Simulate data with ANSI escape sequences
+        const dataWithEscapes = [
+            'Line 1\n',
+            'Line 2\n',
+            '\x1B[1A\x1B[KReplaced Line 2\n', // Move up one line, clear line, write new text
+            '\x1B[2J\x1B[H', // Clear screen and move to home
+            'Fresh start\n',
+        ];
+        dataWithEscapes.forEach(data => {
+            mockProcess._emit('data', data);
+        });
+        // Virtual terminal should handle all the escape sequences
+        expect(session.terminal.write).toHaveBeenCalledTimes(5);
+        // No raw output should be stored
+        expect(session.outputHistory).toEqual([]);
+    });
+    it('should emit sessionData events for active sessions only', () => {
+        // Create a mock PTY process
+        const mockProcess = createMockPtyProcess();
+        vi.mocked(spawn).mockReturnValue(mockProcess);
+        const dataHandler = vi.fn();
+        sessionManager.on('sessionData', dataHandler);
+        sessionManager.createSession(mockWorktreePath);
+        const session = sessionManager.sessions.get(mockWorktreePath);
+        // Session is not active by default
+        mockProcess._emit('data', 'Test data 1');
+        // Should not emit data when inactive
+        expect(dataHandler).not.toHaveBeenCalled();
+        // Activate session
+        sessionManager.setSessionActive(mockWorktreePath, true);
+        // Now data should be emitted
+        mockProcess._emit('data', 'Test data 2');
+        expect(dataHandler).toHaveBeenCalledWith(session, 'Test data 2');
+    });
+    it('should restore session without replaying output history', () => {
+        // Create a mock PTY process
+        const mockProcess = createMockPtyProcess();
+        vi.mocked(spawn).mockReturnValue(mockProcess);
+        const restoreHandler = vi.fn();
+        sessionManager.on('sessionRestore', restoreHandler);
+        sessionManager.createSession(mockWorktreePath);
+        const session = sessionManager.sessions.get(mockWorktreePath);
+        // Add some data to the session
+        mockProcess._emit('data', 'Old output that should not be replayed\n');
+        mockProcess._emit('data', 'More old output\n');
+        // Deactivate then reactivate session
+        sessionManager.setSessionActive(mockWorktreePath, false);
+        sessionManager.setSessionActive(mockWorktreePath, true);
+        // Should emit restore event
+        expect(restoreHandler).toHaveBeenCalledWith(session);
+        // But should not have any output history to replay
+        expect(session.outputHistory).toEqual([]);
+    });
+});

package/dist/services/sessionManager.js

@@ -101,7 +101,7 @@ export class SessionManager extends EventEmitter {
             process: ptyProcess,
             state: 'busy', // Session starts as busy when created
             output: [],
-            outputHistory: [],
+            outputHistory: [], // Kept for backward compatibility but no longer used
             lastActivity: new Date(),
             isActive: false,
             terminal,
@@ -115,20 +115,10 @@ export class SessionManager extends EventEmitter {
     setupBackgroundHandler(session) {
         // This handler always runs for all data
         session.process.onData((data) => {
-            // Write data to virtual terminal
+            // Write data to virtual terminal - this maintains the proper rendered state
             session.terminal.write(data);
-            // Store in output history as Buffer
-            const buffer = Buffer.from(data, 'utf8');
-            session.outputHistory.push(buffer);
-            // Limit memory usage - keep max 10MB of output history
-            const MAX_HISTORY_SIZE = 10 * 1024 * 1024; // 10MB
-            let totalSize = session.outputHistory.reduce((sum, buf) => sum + buf.length, 0);
-            while (totalSize > MAX_HISTORY_SIZE && session.outputHistory.length > 0) {
-                const removed = session.outputHistory.shift();
-                if (removed) {
-                    totalSize -= removed.length;
-                }
-            }
+            // We no longer need to maintain outputHistory since we use the virtual terminal buffer
+            // This prevents duplicate content issues and reduces memory usage
             session.lastActivity = new Date();
             // Only emit data events when session is active
             if (session.isActive) {
@@ -163,8 +153,9 @@ export class SessionManager extends EventEmitter {
         const session = this.sessions.get(worktreePath);
         if (session) {
             session.isActive = active;
-            // If becoming active, emit a restore event with the output history
-            if (active && session.outputHistory.length > 0) {
+            // If becoming active, emit a restore event
+            // The Session component will use the virtual terminal buffer instead of outputHistory
+            if (active) {
                 this.emit('sessionRestore', session);
             }
         }

package/dist/types/index.d.ts

@@ -1,4 +1,6 @@
 import { IPty } from 'node-pty';
+import type pkg from '@xterm/headless';
+export type Terminal = InstanceType<typeof pkg.Terminal>;
 export type SessionState = 'idle' | 'busy' | 'waiting_input';
 export interface Worktree {
     path: string;
@@ -15,7 +17,7 @@ export interface Session {
     outputHistory: Buffer[];
     lastActivity: Date;
     isActive: boolean;
-    terminal: any;
+    terminal: Terminal;
     stateCheckInterval?: NodeJS.Timeout;
 }
 export interface SessionManager {

package/dist/utils/terminalSerializer.d.ts

@@ -0,0 +1,119 @@
+import type { Terminal } from '../types/index.js';
+/**
+ * TerminalSerializer: Converts terminal screen content to text while preserving colors and formatting.
+ *
+ * Imagine taking a screenshot of your terminal, but instead of an image, you get text that
+ * can recreate the exact same appearance with all colors and styles when displayed again.
+ */
+export declare class TerminalSerializer {
+    /**
+     * ESC: The "magic" prefix that tells the terminal "the next characters are instructions, not text"
+     * '\x1b[' is like saying "Hey terminal, listen up for special commands!"
+     */
+    private static readonly ESC;
+    /**
+     * RESET: The command that tells terminal "go back to normal text" (no colors, no bold, etc.)
+     * Like clicking "clear formatting" in a word processor
+     */
+    private static readonly RESET;
+    /**
+     * Determines which color system is being used for a given color value.
+     *
+     * Terminal supports different color systems:
+     * - Mode 0 (DEFAULT): Basic terminal colors (like white text on black background)
+     * - Mode 1 (P16): 16 basic colors (8 normal + 8 bright versions)
+     * - Mode 2 (P256): 256 colors (used for more variety)
+     * - Mode 3 (RGB): True color with Red, Green, Blue values (16.7 million colors)
+     *
+     * @param colorValue - The packed color information from the terminal
+     * @returns 0, 1, 2, or 3 indicating which color system to use
+     */
+    private static getColorMode;
+    /**
+     * Extracts the actual color value from the packed color information.
+     *
+     * The extraction method depends on the color mode:
+     * - For RGB mode: Extracts all three color components (R, G, B)
+     * - For palette modes: Extracts just the color index number
+     *
+     * Think of it like unpacking a suitcase - different items are packed differently
+     *
+     * @param colorValue - The packed color information from the terminal
+     * @returns The actual color value (either RGB values or palette index)
+     */
+    private static extractColor;
+    /**
+     * Converts a color value into the special text codes that terminals understand.
+     *
+     * Terminals use "ANSI escape sequences" - special character combinations that control
+     * how text appears. It's like HTML tags, but for terminals.
+     *
+     * Examples of what this function produces:
+     * - Red text: "\x1b[31m" (tells terminal "make the following text red")
+     * - Blue background: "\x1b[44m" (tells terminal "make the background blue")
+     * - RGB color: "\x1b[38;2;255;128;0m" (orange text using RGB values)
+     *
+     * @param colorValue - The color to convert (packed number with mode and color data)
+     * @param isBackground - true for background color, false for text color
+     * @returns ANSI escape sequence string that terminals can interpret
+     */
+    private static colorToAnsi;
+    /**
+     * Converts a single line of terminal content into text with color/style codes.
+     *
+     * This function processes each character in a line and:
+     * 1. Extracts the character itself
+     * 2. Checks its color (text and background)
+     * 3. Checks its style (bold, italic, underline, etc.)
+     * 4. Adds the necessary codes to recreate that appearance
+     *
+     * It's like going through a line character by character and noting:
+     * "This letter is red, this one is bold, this one has blue background..."
+     *
+     * @param line - One line from the terminal screen
+     * @param cols - Number of columns (width) of the terminal
+     * @param trimRight - Whether to remove trailing spaces (like right-trim in text editors)
+     * @returns The line as text with embedded color/style codes
+     */
+    private static serializeLine;
+    /**
+     * Converts the entire terminal screen (or part of it) into text with colors preserved.
+     *
+     * This is the main function that processes multiple lines of terminal content.
+     * It's like taking a "text screenshot" of your terminal that can be replayed later
+     * with all the colors and formatting intact.
+     *
+     * @param terminal - The terminal object containing the screen buffer
+     * @param options - Configuration options:
+     *   - startLine: First line to include (default: 0, the top)
+     *   - endLine: Last line to include (default: bottom of screen)
+     *   - trimRight: Remove trailing spaces from each line (default: true)
+     *   - includeEmptyLines: Keep blank lines in output (default: true)
+     * @returns Multi-line string with embedded ANSI codes for colors/styles
+     */
+    static serialize(terminal: Terminal, options?: {
+        startLine?: number;
+        endLine?: number;
+        trimRight?: boolean;
+        includeEmptyLines?: boolean;
+    }): string;
+    /**
+     * Convenience function to get just the last few lines from the terminal.
+     *
+     * Useful when you only need recent output, like:
+     * - Getting the last error message
+     * - Showing recent command output
+     * - Displaying the current prompt
+     *
+     * Example: getLastLines(terminal, 10) gets the last 10 lines
+     *
+     * @param terminal - The terminal object containing the screen buffer
+     * @param lineCount - How many lines from the bottom to include
+     * @param options - Same options as serialize() for controlling output format
+     * @returns The requested lines as text with color/style codes
+     */
+    static getLastLines(terminal: Terminal, lineCount: number, options?: {
+        trimRight?: boolean;
+        includeEmptyLines?: boolean;
+    }): string;
+}

package/dist/utils/terminalSerializer.js

@@ -0,0 +1,376 @@
+/**
+ * Constants for decoding color information stored in terminal cells.
+ * Terminal colors are packed into a single number where different bits represent different information.
+ * Think of it like a compressed file - multiple pieces of data stored in one number.
+ *
+ * These constants are based on xterm.js internal implementation:
+ * Source: https://github.com/xtermjs/xterm.js/blob/master/src/common/buffer/Constants.ts
+ *
+ * The color storage format uses bit packing where:
+ * - Bits 1-8: Blue component (also used for palette color indices)
+ * - Bits 9-16: Green component (RGB mode only)
+ * - Bits 17-24: Red component (RGB mode only)
+ * - Bits 25-26: Color mode indicator
+ *
+ * Reference implementation:
+ * https://github.com/xtermjs/xterm.js/blob/master/src/common/buffer/AttributeData.ts
+ */
+const Attributes = {
+    /**
+     * BLUE_MASK: Used to extract blue color value (bits 1-8)
+     * In 256-color and 16-color modes, the entire color number is stored here
+     * Example: 0x0000FF masks out everything except the last 8 bits
+     */
+    BLUE_MASK: 0xff,
+    BLUE_SHIFT: 0,
+    /**
+     * GREEN_MASK: Used to extract green color value (bits 9-16)
+     * Only used in RGB (true color) mode
+     * Example: 0x00FF00 masks out everything except bits 9-16
+     */
+    GREEN_MASK: 0xff00,
+    GREEN_SHIFT: 8,
+    /**
+     * RED_MASK: Used to extract red color value (bits 17-24)
+     * Only used in RGB (true color) mode
+     * Example: 0xFF0000 masks out everything except bits 17-24
+     */
+    RED_MASK: 0xff0000,
+    RED_SHIFT: 16,
+    /**
+     * CM_MASK: Used to determine which color system is being used (bits 25-26)
+     * Like a label that says "this is 16-color" or "this is RGB"
+     *
+     * Color modes from xterm.js:
+     * https://github.com/xtermjs/xterm.js/blob/master/src/common/Types.d.ts#L33
+     */
+    CM_MASK: 0x3000000,
+    CM_DEFAULT: 0, // Default terminal colors (usually white text on black background)
+    CM_P16: 0x1000000, // 16-color palette (basic colors like red, blue, green)
+    CM_P256: 0x2000000, // 256-color palette (more shades and colors)
+    CM_RGB: 0x3000000, // RGB/true color (millions of colors, like in photos)
+};
+/**
+ * TerminalSerializer: Converts terminal screen content to text while preserving colors and formatting.
+ *
+ * Imagine taking a screenshot of your terminal, but instead of an image, you get text that
+ * can recreate the exact same appearance with all colors and styles when displayed again.
+ */
+export class TerminalSerializer {
+    /**
+     * Determines which color system is being used for a given color value.
+     *
+     * Terminal supports different color systems:
+     * - Mode 0 (DEFAULT): Basic terminal colors (like white text on black background)
+     * - Mode 1 (P16): 16 basic colors (8 normal + 8 bright versions)
+     * - Mode 2 (P256): 256 colors (used for more variety)
+     * - Mode 3 (RGB): True color with Red, Green, Blue values (16.7 million colors)
+     *
+     * @param colorValue - The packed color information from the terminal
+     * @returns 0, 1, 2, or 3 indicating which color system to use
+     */
+    static getColorMode(colorValue) {
+        const mode = colorValue & Attributes.CM_MASK;
+        if (mode === Attributes.CM_P16)
+            return 1; // P16
+        if (mode === Attributes.CM_P256)
+            return 2; // P256
+        if (mode === Attributes.CM_RGB)
+            return 3; // RGB
+        return 0; // DEFAULT
+    }
+    /**
+     * Extracts the actual color value from the packed color information.
+     *
+     * The extraction method depends on the color mode:
+     * - For RGB mode: Extracts all three color components (R, G, B)
+     * - For palette modes: Extracts just the color index number
+     *
+     * Think of it like unpacking a suitcase - different items are packed differently
+     *
+     * @param colorValue - The packed color information from the terminal
+     * @returns The actual color value (either RGB values or palette index)
+     */
+    static extractColor(colorValue) {
+        const mode = colorValue & Attributes.CM_MASK;
+        if (mode === Attributes.CM_RGB) {
+            // For RGB, extract R, G, B components (all 24 bits of color data)
+            return colorValue & 0xffffff;
+        }
+        // For palette colors, it's stored in the blue channel (just 8 bits)
+        return colorValue & Attributes.BLUE_MASK;
+    }
+    /**
+     * Converts a color value into the special text codes that terminals understand.
+     *
+     * Terminals use "ANSI escape sequences" - special character combinations that control
+     * how text appears. It's like HTML tags, but for terminals.
+     *
+     * Examples of what this function produces:
+     * - Red text: "\x1b[31m" (tells terminal "make the following text red")
+     * - Blue background: "\x1b[44m" (tells terminal "make the background blue")
+     * - RGB color: "\x1b[38;2;255;128;0m" (orange text using RGB values)
+     *
+     * @param colorValue - The color to convert (packed number with mode and color data)
+     * @param isBackground - true for background color, false for text color
+     * @returns ANSI escape sequence string that terminals can interpret
+     */
+    static colorToAnsi(colorValue, isBackground) {
+        // -1 is a special value meaning "use the terminal's default color"
+        if (colorValue === -1) {
+            return isBackground ? `${this.ESC}49m` : `${this.ESC}39m`;
+        }
+        // Different prefixes for text color (38) vs background color (48)
+        const prefix = isBackground ? '48' : '38';
+        const mode = this.getColorMode(colorValue);
+        const color = this.extractColor(colorValue);
+        switch (mode) {
+            case 0: // DEFAULT
+                // Reset to terminal's default colors
+                return isBackground ? `${this.ESC}49m` : `${this.ESC}39m`;
+            case 1: // P16 - Basic 16 colors
+                // Colors 0-7 are normal intensity (black, red, green, yellow, blue, magenta, cyan, white)
+                // Colors 8-15 are bright/bold versions of the same colors
+                if (color < 8) {
+                    // Standard colors: 30-37 for text, 40-47 for background
+                    return `${this.ESC}${(isBackground ? 40 : 30) + color}m`;
+                }
+                else {
+                    // Bright colors: 90-97 for text, 100-107 for background
+                    return `${this.ESC}${(isBackground ? 100 : 90) + (color - 8)}m`;
+                }
+            case 2: // P256 - Extended 256 color palette
+                // Format: ESC[38;5;{color}m for foreground, ESC[48;5;{color}m for background
+                // The ;5; tells terminal "the next number is a color from the 256-color palette"
+                return `${this.ESC}${prefix};5;${color}m`;
+            case 3: {
+                // RGB - True color (24-bit, millions of colors)
+                // Extract individual Red, Green, Blue components from the packed color
+                const r = (color >> 16) & 0xff; // Red: bits 17-24
+                const g = (color >> 8) & 0xff; // Green: bits 9-16
+                const b = color & 0xff; // Blue: bits 1-8
+                // Format: ESC[38;2;{r};{g};{b}m for foreground
+                // The ;2; tells terminal "the next three numbers are RGB values"
+                return `${this.ESC}${prefix};2;${r};${g};${b}m`;
+            }
+            default:
+                return '';
+        }
+    }
+    /**
+     * Converts a single line of terminal content into text with color/style codes.
+     *
+     * This function processes each character in a line and:
+     * 1. Extracts the character itself
+     * 2. Checks its color (text and background)
+     * 3. Checks its style (bold, italic, underline, etc.)
+     * 4. Adds the necessary codes to recreate that appearance
+     *
+     * It's like going through a line character by character and noting:
+     * "This letter is red, this one is bold, this one has blue background..."
+     *
+     * @param line - One line from the terminal screen
+     * @param cols - Number of columns (width) of the terminal
+     * @param trimRight - Whether to remove trailing spaces (like right-trim in text editors)
+     * @returns The line as text with embedded color/style codes
+     */
+    static serializeLine(line, cols, trimRight = true) {
+        if (!line)
+            return '';
+        let result = '';
+        // Keep track of the current colors/styles to avoid repeating the same codes
+        let lastFgColor = null;
+        let lastBgColor = null;
+        let lastStyles = {
+            bold: false,
+            italic: false,
+            underline: false,
+            strikethrough: false,
+        };
+        // Find the last character that isn't a space (for trimming)
+        // Start from the right and work backwards to find content
+        let lastNonEmptyIndex = -1;
+        if (trimRight) {
+            for (let x = cols - 1; x >= 0; x--) {
+                const cell = line.getCell(x);
+                if (cell) {
+                    const chars = cell.getChars();
+                    if (chars && chars.trim() !== '') {
+                        lastNonEmptyIndex = x;
+                        break;
+                    }
+                }
+            }
+        }
+        // If the line is completely empty and we're trimming, return empty string
+        if (trimRight && lastNonEmptyIndex === -1) {
+            return '';
+        }
+        const endCol = trimRight ? lastNonEmptyIndex + 1 : cols;
+        // Process each character position in the line
+        for (let x = 0; x < endCol; x++) {
+            const cell = line.getCell(x);
+            if (!cell) {
+                // No cell data at this position, just add a space
+                result += ' ';
+                continue;
+            }
+            // Get the actual character at this position
+            const chars = cell.getChars();
+            const cellChar = chars || ' ';
+            // Build up any necessary escape sequences for this character
+            let escapeSequence = '';
+            // STEP 1: Check text color
+            // Get both the color value and the color mode (which type of color it is)
+            const fgColor = cell.getFgColor();
+            const fgColorMode = cell.getFgColorMode();
+            // Combine them into a single value that includes both color and mode information
+            const fgColorValue = fgColorMode === 0 ? fgColor : fgColorMode | fgColor;
+            // Only add color code if it's different from the previous character
+            if (fgColorValue !== lastFgColor) {
+                escapeSequence += this.colorToAnsi(fgColorValue, false);
+                lastFgColor = fgColorValue;
+            }
+            // STEP 2: Check background color (same process as text color)
+            const bgColor = cell.getBgColor();
+            const bgColorMode = cell.getBgColorMode();
+            const bgColorValue = bgColorMode === 0 ? bgColor : bgColorMode | bgColor;
+            if (bgColorValue !== lastBgColor) {
+                escapeSequence += this.colorToAnsi(bgColorValue, true);
+                lastBgColor = bgColorValue;
+            }
+            // STEP 3: Check text styles (bold, italic, etc.)
+            const currentStyles = {
+                bold: !!cell.isBold(), // Is this character bold?
+                italic: !!cell.isItalic(), // Is it italicized?
+                underline: !!cell.isUnderline(), // Is it underlined?
+                strikethrough: !!cell.isStrikethrough(), // Is it crossed out?
+            };
+            // If any style changed from the previous character, update them
+            if (currentStyles.bold !== lastStyles.bold ||
+                currentStyles.italic !== lastStyles.italic ||
+                currentStyles.underline !== lastStyles.underline ||
+                currentStyles.strikethrough !== lastStyles.strikethrough) {
+                // First, turn off all styles with reset codes
+                // 22m = not bold, 23m = not italic, 24m = not underline, 29m = not strikethrough
+                escapeSequence += `${this.ESC}22m${this.ESC}23m${this.ESC}24m${this.ESC}29m`;
+                // Then turn on only the styles we need
+                // 1m = bold, 3m = italic, 4m = underline, 9m = strikethrough
+                if (currentStyles.bold)
+                    escapeSequence += `${this.ESC}1m`;
+                if (currentStyles.italic)
+                    escapeSequence += `${this.ESC}3m`;
+                if (currentStyles.underline)
+                    escapeSequence += `${this.ESC}4m`;
+                if (currentStyles.strikethrough)
+                    escapeSequence += `${this.ESC}9m`;
+                lastStyles = { ...currentStyles };
+            }
+            // Add the escape sequences (if any) followed by the actual character
+            result += escapeSequence + cellChar;
+        }
+        return result;
+    }
+    /**
+     * Converts the entire terminal screen (or part of it) into text with colors preserved.
+     *
+     * This is the main function that processes multiple lines of terminal content.
+     * It's like taking a "text screenshot" of your terminal that can be replayed later
+     * with all the colors and formatting intact.
+     *
+     * @param terminal - The terminal object containing the screen buffer
+     * @param options - Configuration options:
+     *   - startLine: First line to include (default: 0, the top)
+     *   - endLine: Last line to include (default: bottom of screen)
+     *   - trimRight: Remove trailing spaces from each line (default: true)
+     *   - includeEmptyLines: Keep blank lines in output (default: true)
+     * @returns Multi-line string with embedded ANSI codes for colors/styles
+     */
+    static serialize(terminal, options = {}) {
+        // Get the current screen content and dimensions
+        const buffer = terminal.buffer.active;
+        const cols = terminal.cols;
+        // Apply default options
+        const { startLine = 0, endLine = buffer.length, trimRight = true, includeEmptyLines = true, } = options;
+        const lines = [];
+        // Process each line in the specified range
+        for (let y = startLine; y < Math.min(endLine, buffer.length); y++) {
+            const line = buffer.getLine(y);
+            if (line) {
+                // Convert this line to text with color codes
+                const serializedLine = this.serializeLine(line, cols, trimRight);
+                // Skip empty lines if user doesn't want them
+                if (!includeEmptyLines && serializedLine.trim() === '') {
+                    continue;
+                }
+                lines.push(serializedLine);
+            }
+            else if (includeEmptyLines) {
+                // Line doesn't exist but we want to preserve empty lines
+                lines.push('');
+            }
+        }
+        // Remove trailing empty lines if trimming is enabled
+        // This is like removing blank lines at the end of a document
+        if (trimRight && lines.length > 0) {
+            let lastNonEmptyIndex = lines.length - 1;
+            while (lastNonEmptyIndex >= 0) {
+                const line = lines[lastNonEmptyIndex];
+                if (line && line.trim() !== '') {
+                    break;
+                }
+                lastNonEmptyIndex--;
+            }
+            // Join all lines and add a reset code at the end to clear any formatting
+            return lines.slice(0, lastNonEmptyIndex + 1).join('\n') + this.RESET;
+        }
+        // Join all lines and add a reset code at the end
+        return lines.join('\n') + this.RESET;
+    }
+    /**
+     * Convenience function to get just the last few lines from the terminal.
+     *
+     * Useful when you only need recent output, like:
+     * - Getting the last error message
+     * - Showing recent command output
+     * - Displaying the current prompt
+     *
+     * Example: getLastLines(terminal, 10) gets the last 10 lines
+     *
+     * @param terminal - The terminal object containing the screen buffer
+     * @param lineCount - How many lines from the bottom to include
+     * @param options - Same options as serialize() for controlling output format
+     * @returns The requested lines as text with color/style codes
+     */
+    static getLastLines(terminal, lineCount, options = {}) {
+        const buffer = terminal.buffer.active;
+        // Calculate where to start (can't go below 0)
+        const startLine = Math.max(0, buffer.length - lineCount);
+        // Use the main serialize function but with a specific range
+        return this.serialize(terminal, {
+            startLine,
+            endLine: buffer.length,
+            ...options,
+        });
+    }
+}
+/**
+ * ESC: The "magic" prefix that tells the terminal "the next characters are instructions, not text"
+ * '\x1b[' is like saying "Hey terminal, listen up for special commands!"
+ */
+Object.defineProperty(TerminalSerializer, "ESC", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: '\x1b['
+});
+/**
+ * RESET: The command that tells terminal "go back to normal text" (no colors, no bold, etc.)
+ * Like clicking "clear formatting" in a word processor
+ */
+Object.defineProperty(TerminalSerializer, "RESET", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: '\x1b[0m'
+});

package/dist/utils/terminalSerializer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/terminalSerializer.test.js

@@ -0,0 +1,137 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import pkg from '@xterm/headless';
+import { TerminalSerializer } from './terminalSerializer.js';
+const { Terminal } = pkg;
+describe('TerminalSerializer', () => {
+    let terminal;
+    beforeEach(() => {
+        terminal = new Terminal({
+            cols: 80,
+            rows: 24,
+            allowProposedApi: true,
+        });
+    });
+    // Helper to write to terminal and wait for processing
+    const writeAsync = (data) => {
+        return new Promise(resolve => {
+            terminal.write(data, () => resolve());
+        });
+    };
+    it('should serialize plain text without escape sequences', async () => {
+        await writeAsync('Hello, World!');
+        const serialized = TerminalSerializer.serialize(terminal);
+        expect(serialized).toContain('Hello, World!');
+    });
+    it('should preserve foreground colors', async () => {
+        // Write red text
+        await writeAsync('\x1b[31mRed Text\x1b[0m');
+        const serialized = TerminalSerializer.serialize(terminal);
+        expect(serialized).toContain('\x1b[31m');
+        expect(serialized).toContain('Red Text');
+    });
+    it('should preserve background colors', async () => {
+        // Write text with blue background
+        await writeAsync('\x1b[44mBlue Background\x1b[0m');
+        const serialized = TerminalSerializer.serialize(terminal);
+        expect(serialized).toContain('\x1b[44m');
+        expect(serialized).toContain('Blue Background');
+    });
+    it('should preserve 256 colors', async () => {
+        // Write text with extended color (color 196 = bright red)
+        await writeAsync('\x1b[38;5;196mExtended Color\x1b[0m');
+        const serialized = TerminalSerializer.serialize(terminal);
+        expect(serialized).toContain('\x1b[38;5;196m');
+        expect(serialized).toContain('Extended Color');
+    });
+    it('should preserve RGB colors', async () => {
+        // Write text with true color RGB
+        await writeAsync('\x1b[38;2;255;128;0mOrange RGB\x1b[0m');
+        const serialized = TerminalSerializer.serialize(terminal);
+        expect(serialized).toContain('\x1b[38;2;255;128;0m');
+        expect(serialized).toContain('Orange RGB');
+    });
+    it('should preserve text styles', async () => {
+        // Write bold text
+        await writeAsync('\x1b[1mBold Text\x1b[0m');
+        const serialized = TerminalSerializer.serialize(terminal);
+        expect(serialized).toContain('\x1b[1m');
+        expect(serialized).toContain('Bold Text');
+        // Clear and write italic text
+        terminal.reset();
+        await writeAsync('\x1b[3mItalic Text\x1b[0m');
+        const serializedItalic = TerminalSerializer.serialize(terminal);
+        expect(serializedItalic).toContain('\x1b[3m');
+        expect(serializedItalic).toContain('Italic Text');
+    });
+    it('should handle multiple lines correctly', async () => {
+        await writeAsync('Line 1\r\n');
+        await writeAsync('\x1b[32mLine 2 (green)\x1b[0m\r\n');
+        await writeAsync('Line 3');
+        const serialized = TerminalSerializer.serialize(terminal);
+        const lines = serialized.split('\n');
+        expect(lines.length).toBeGreaterThanOrEqual(3);
+        expect(lines[0]).toContain('Line 1');
+        expect(lines[1]).toContain('\x1b[32m');
+        expect(lines[1]).toContain('Line 2 (green)');
+        expect(lines[2]).toContain('Line 3');
+    });
+    it('should trim trailing empty lines when trimRight is true', async () => {
+        await writeAsync('Content\r\n\r\n\r\n\r\n');
+        const serialized = TerminalSerializer.serialize(terminal, {
+            trimRight: true,
+        });
+        const lines = serialized.split('\n');
+        // Should only have the content line, not the trailing empty lines
+        expect(lines[0]).toContain('Content');
+        expect(lines.length).toBe(1); // Plus reset code
+    });
+    it('should preserve empty lines when includeEmptyLines is true', async () => {
+        await writeAsync('Line 1\r\n\r\nLine 3');
+        const serialized = TerminalSerializer.serialize(terminal, {
+            includeEmptyLines: true,
+        });
+        const lines = serialized.split('\n');
+        expect(lines.length).toBe(3); // 3 lines including the empty one
+        expect(lines[1]).toBe(''); // Empty line
+    });
+    it('should handle getLastLines correctly', async () => {
+        // Create a small terminal so we can see the scrolling
+        const smallTerminal = new Terminal({
+            cols: 80,
+            rows: 10,
+            allowProposedApi: true,
+        });
+        // Helper for this specific terminal
+        const writeToSmall = (data) => {
+            return new Promise(resolve => {
+                smallTerminal.write(data, () => resolve());
+            });
+        };
+        // Write enough lines to fill and scroll the buffer
+        for (let i = 1; i <= 15; i++) {
+            await writeToSmall(`Line ${i}\r\n`);
+        }
+        const lastLines = TerminalSerializer.getLastLines(smallTerminal, 3);
+        // Should contain the last few lines
+        expect(lastLines).toContain('Line 14');
+        expect(lastLines).toContain('Line 15');
+        // Should not contain much older lines
+        expect(lastLines).not.toContain('Line 10');
+    });
+    it('should handle complex mixed formatting', async () => {
+        // Complex formatting with multiple attributes
+        await writeAsync('\x1b[1;31;44mBold Red on Blue\x1b[0m Normal \x1b[3;38;5;226mItalic Yellow\x1b[0m');
+        const serialized = TerminalSerializer.serialize(terminal);
+        // Should contain various escape sequences
+        expect(serialized).toContain('Bold Red on Blue');
+        expect(serialized).toContain('Normal');
+        expect(serialized).toContain('Italic Yellow');
+        // Should have some escape sequences (exact sequences may vary based on implementation)
+        expect(serialized).toMatch(/\x1b\[\d+(;\d+)*m/);
+    });
+    it('should add reset at the end', async () => {
+        await writeAsync('Some text');
+        const serialized = TerminalSerializer.serialize(terminal);
+        expect(serialized).toMatch(/\x1b\[0m$/);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "ccmanager",
-	"version": "0.1.0",
+	"version": "0.1.1",
 	"description": "TUI application for managing multiple Claude Code sessions across Git worktrees",
 	"license": "MIT",
 	"author": "Kodai Kabasawa",