@heinrichb/console-toolkit 1.0.5 → 1.0.6

package/dist/components/progress.d.ts

@@ -1,4 +1,4 @@
-import { StyledLine, Style } from "../core/types";
+import { PrintLine, PrintStyle } from "../core/types";
 export interface ProgressBarOptions {
     /**
      * Progress value between 0.0 and 1.0.
@@ -12,38 +12,38 @@ export interface ProgressBarOptions {
     /**
      * Base style for the entire progress bar.
      */
-    style?: Style | Style[];
+    style?: PrintStyle;
     /**
      * Style for the brackets (start and end characters).
-     * Defaults to `style` or gray.
+     * Defaults to `style`.
      */
-    bracketStyle?: Style | Style[];
+    bracketStyle?: PrintStyle;
     /**
      * Specific style for the start bracket. Overrides `bracketStyle`.
      */
-    startStyle?: Style | Style[];
+    startStyle?: PrintStyle;
     /**
      * Specific style for the end bracket. Overrides `bracketStyle`.
      */
-    endStyle?: Style | Style[];
+    endStyle?: PrintStyle;
     /**
      * Style for the bar (filled and empty parts).
      * Defaults to `style`.
      */
-    barStyle?: Style | Style[];
+    barStyle?: PrintStyle;
     /**
      * Specific style for the filled part. Overrides `barStyle`.
      */
-    fillStyle?: Style | Style[];
+    fillStyle?: PrintStyle;
     /**
      * Specific style for the empty part. Overrides `barStyle`.
      */
-    emptyStyle?: Style | Style[];
+    emptyStyle?: PrintStyle;
     /**
      * Style for the percentage text.
      * Defaults to `style`.
      */
-    percentageStyle?: Style | Style[];
+    percentageStyle?: PrintStyle;
     /**
      * Character to use for the start bracket. Defaults to `[`.
      */
@@ -70,6 +70,6 @@ export interface ProgressBarOptions {
     formatPercentage?: (progress: number) => string;
 }
 /**
- * Creates a StyledLine representing a progress bar.
+ * Creates a PrintLine representing a progress bar.
  */
-export declare function createProgressBar(options: ProgressBarOptions): StyledLine;
+export declare function createProgressBar(options: ProgressBarOptions): PrintLine;

package/dist/components/progress.js

@@ -1,5 +1,5 @@
 /**
- * Creates a StyledLine representing a progress bar.
+ * Creates a PrintLine representing a progress bar.
  */
 export function createProgressBar(options) {
     const { progress, width = 20, style, bracketStyle, startStyle, endStyle, barStyle, fillStyle, emptyStyle, percentageStyle, startChar = "[", endChar = "]", fillChar = "█", emptyChar = "░", showPercentage = true, formatPercentage } = options;
@@ -8,15 +8,14 @@ export function createProgressBar(options) {
     // Calculate filled width
     const filledWidth = Math.round(p * width);
     const emptyWidth = width - filledWidth;
-    // Resolve styles
-    const baseStyle = style ?? [];
-    const resolvedBracketStyle = bracketStyle ?? baseStyle;
+    // Resolve styles (Defaults)
+    const resolvedBracketStyle = bracketStyle ?? style;
     const resolvedStartStyle = startStyle ?? resolvedBracketStyle;
     const resolvedEndStyle = endStyle ?? resolvedBracketStyle;
-    const resolvedBarStyle = barStyle ?? baseStyle;
+    const resolvedBarStyle = barStyle ?? style;
     const resolvedFillStyle = fillStyle ?? resolvedBarStyle;
     const resolvedEmptyStyle = emptyStyle ?? resolvedBarStyle;
-    const resolvedPercentageStyle = percentageStyle ?? baseStyle;
+    const resolvedPercentageStyle = percentageStyle ?? style;
     const segments = [];
     // Start Bracket
     if (startChar) {

package/dist/components/progress.test.js

@@ -7,6 +7,7 @@ describe("createProgressBar", () => {
     test("generates a default progress bar at 0%", () => {
         const line = createProgressBar({ progress: 0 });
         const text = getText(line);
+        // Default format: [░░░░░░░░░░░░░░░░░░░░] 0%
         expect(text).toContain("[");
         expect(text).toContain("]");
         expect(text).toContain("0%");
@@ -23,6 +24,8 @@ describe("createProgressBar", () => {
         const line = createProgressBar({ progress: 1.0 });
         const text = getText(line);
         expect(text).toContain("100%");
+        // Should not contain empty char
+        // But wait, width default 20. 100% means 20 filled. 0 empty.
         expect(text).not.toContain("░");
     });
     test("allows custom width", () => {
@@ -31,34 +34,35 @@ describe("createProgressBar", () => {
         const segments = line.segments;
         const filled = segments.find((s) => s.text.includes("█"));
         const empty = segments.find((s) => s.text.includes("░"));
+        // 50% of 10 is 5.
         expect(filled?.text.length).toBe(5);
         expect(empty?.text.length).toBe(5);
     });
     test("applies styles correctly", () => {
         const line = createProgressBar({
             progress: 0.5,
-            style: "blue",
-            bracketStyle: "red",
-            barStyle: "green",
-            percentageStyle: "yellow"
+            style: { color: "blue" },
+            bracketStyle: { color: "red" },
+            barStyle: { color: "green" },
+            percentageStyle: { color: "yellow" }
         });
         const start = line.segments.find((s) => s.text === "[");
         const filled = line.segments.find((s) => s.text.includes("█"));
         const end = line.segments.find((s) => s.text === "]");
         const percentage = line.segments.find((s) => s.text.includes("%"));
-        expect(start?.style).toBe("red");
-        expect(filled?.style).toBe("green");
-        expect(end?.style).toBe("red");
-        expect(percentage?.style).toBe("yellow");
+        expect(start?.style).toEqual({ color: "red" });
+        expect(filled?.style).toEqual({ color: "green" });
+        expect(end?.style).toEqual({ color: "red" });
+        expect(percentage?.style).toEqual({ color: "yellow" });
     });
     test("cascades styles (general style -> specific)", () => {
         const line = createProgressBar({
             progress: 0.5,
-            style: "blue"
+            style: { color: "blue" }
         });
         line.segments.forEach((s) => {
             if (s.text.trim().length > 0) {
-                expect(s.style).toBe("blue");
+                expect(s.style).toEqual({ color: "blue" });
             }
         });
     });

package/dist/core/layout.d.ts

@@ -1,16 +1,16 @@
-import { Style, StyledLine } from "./types";
+import { PrintLine, PrintStyle } from "./types";
 import { Printer } from "./printer";
 /**
- * Merges multiple columns of StyledLines into a single layout.
+ * Merges multiple columns of PrintLines into a single layout.
  * Ensures proper alignment by padding shorter lines.
  *
- * @param columns - Array of columns, where each column is an array of StyledLines.
+ * @param columns - Array of columns, where each column is an array of PrintLines.
  * @param separator - String used to separate columns.
  * @param defaultStyle - Style to apply to the separator and padding.
  * @param widths - Optional fixed widths for each column.
- * @returns A single array of StyledLines representing the merged output.
+ * @returns A single array of PrintLines representing the merged output.
  */
-export declare function mergeMultipleColumns(columns: StyledLine[][], separator: string, defaultStyle: Style | Style[], widths?: number[]): StyledLine[];
+export declare function mergeMultipleColumns(columns: PrintLine[][], separator?: string, defaultStyle?: PrintStyle, widths?: number[]): PrintLine[];
 /**
  * Prints multiple columns of styled content to the console.
  * A convenience wrapper around `mergeMultipleColumns` and `Printer.print`.
@@ -18,7 +18,7 @@ export declare function mergeMultipleColumns(columns: StyledLine[][], separator:
  * @param columns - Array of columns to print.
  * @param options - Layout options (widths, separator, custom printer).
  */
-export declare function printColumns(columns: StyledLine[][], options?: {
+export declare function printColumns(columns: PrintLine[][], options?: {
     widths?: number[];
     separator?: string;
     printer?: Printer;

package/dist/core/layout.js

@@ -1,21 +1,19 @@
 import { computeMaxWidth, padLine } from "./utils";
 import { Printer } from "./printer";
-import { RESET } from "./style";
 // -----------------
 // Core Layout & Printing
 // -----------------
-const defaultPrinter = new Printer();
 /**
- * Merges multiple columns of StyledLines into a single layout.
+ * Merges multiple columns of PrintLines into a single layout.
  * Ensures proper alignment by padding shorter lines.
  *
- * @param columns - Array of columns, where each column is an array of StyledLines.
+ * @param columns - Array of columns, where each column is an array of PrintLines.
  * @param separator - String used to separate columns.
  * @param defaultStyle - Style to apply to the separator and padding.
  * @param widths - Optional fixed widths for each column.
- * @returns A single array of StyledLines representing the merged output.
+ * @returns A single array of PrintLines representing the merged output.
  */
-export function mergeMultipleColumns(columns, separator, defaultStyle, widths) {
+export function mergeMultipleColumns(columns, separator = "     ", defaultStyle, widths) {
     if (columns.length === 0)
         return [];
     const maxLines = Math.max(...columns.map((c) => c.length));
@@ -29,12 +27,13 @@ export function mergeMultipleColumns(columns, separator, defaultStyle, widths) {
         let segments = [];
         for (let j = 0; j < columns.length; j++) {
             const line = columns[j][i] || { segments: [] };
-            // Pad if not the last column
+            // If not the last column, pad it
             if (j < columns.length - 1) {
                 const padded = padLine(line, colWidths[j], defaultStyle);
                 segments = [...segments, ...padded.segments, { text: separator, style: defaultStyle }];
             }
             else {
+                // Last column, just add segments
                 segments = [...segments, ...line.segments];
             }
         }
@@ -50,8 +49,7 @@ export function mergeMultipleColumns(columns, separator, defaultStyle, widths) {
  * @param options - Layout options (widths, separator, custom printer).
  */
 export function printColumns(columns, options = {}) {
-    const { widths, separator = "     ", printer = defaultPrinter } = options;
-    const defaultStyle = RESET;
-    const mergedLines = mergeMultipleColumns(columns, separator, defaultStyle, widths);
-    printer.print(mergedLines);
+    const { widths, separator = "     ", printer = new Printer() } = options;
+    const mergedLines = mergeMultipleColumns(columns, separator, undefined, widths);
+    printer.print({ lines: mergedLines });
 }

package/dist/core/layout.test.js

@@ -1,17 +1,25 @@
 import { expect, test, describe, spyOn, afterEach } from "bun:test";
 import { mergeMultipleColumns, printColumns } from "./layout";
 import { getLineLength } from "./utils";
-const lineA = { segments: [{ text: "Hello", style: [] }] };
-const lineB = { segments: [{ text: "World!!", style: [] }] };
+const lineA = { segments: [{ text: "Hello" }] };
+const lineB = { segments: [{ text: "World!!" }] };
 describe("Layout Utilities", () => {
     const stdoutSpy = spyOn(process.stdout, "write").mockImplementation(() => true);
     afterEach(() => {
         stdoutSpy.mockClear();
     });
     test("mergeMultipleColumns handles asymmetric column lengths", () => {
-        const merged = mergeMultipleColumns([[lineA], [lineB, lineB]], " | ", "", [10]);
+        // Column 1: [lineA]
+        // Column 2: [lineB, lineB]
+        // Separator: " | "
+        // Default Style: undefined
+        // Widths: [10] (first col width 10)
+        const merged = mergeMultipleColumns([[lineA], [lineB, lineB]], " | ", undefined, [10]);
         expect(merged.length).toBe(2);
-        expect(getLineLength(merged[1])).toBe(10 + 3 + 7);
+        // Second merged line:
+        // Col 1 is empty (pad to 10) + " | " + Col 2 (lineB, length 7)
+        // 10 + 3 + 7 = 20
+        expect(getLineLength(merged[1])).toBe(20);
     });
     test("printColumns executes correctly", () => {
         printColumns([[lineA], [lineB]]);
@@ -29,7 +37,10 @@ describe("Layout Utilities", () => {
     });
     test("printColumns handles empty columns", () => {
         printColumns([]);
-        expect(stdoutSpy).toHaveBeenCalled(); // Should clear lines if interactive, or do nothing.
+        // Should just print nothing or minimal output (if logic handles empty array gracefully)
+        // mergeMultipleColumns returns []
+        // printer.print({ lines: [] }) -> might output clear sequence or empty string
+        expect(stdoutSpy).toHaveBeenCalled();
     });
     test("printColumns handles 3 columns", () => {
         printColumns([[lineA], [lineA], [lineB]]);

package/dist/core/printer.d.ts

@@ -1,20 +1,33 @@
-import { PrinterOptions, StyledLine } from "./types";
+import { PrintBlock, PrinterOptions } from "./types";
 /**
- * Handles rendering StyledLines to the terminal with support for interactive overwriting.
+ * Handles rendering PrintBlocks to the terminal with support for interactive/live overwriting.
  */
 export declare class Printer {
     private linesRendered;
-    private isInteractive;
+    private isLive;
+    private data?;
     constructor(options?: PrinterOptions);
     /**
      * Generates the clear sequence to move cursor and clear previously rendered lines.
      */
     private getClearSequence;
     /**
-     * Renders an array of StyledLines to the standard output.
-     * If interactive mode is enabled, it clears the previously printed lines first.
+     * Clears the console using the stored line count.
+     */
+    clear(): void;
+    /**
+     * Renders the PrintBlock to the standard output.
+     * If data is provided, updates the internal state.
      *
-     * @param lines - The lines to print.
+     * @param data - Optional data to update the printer with.
+     */
+    print(data?: PrintBlock): void;
+    /**
+     * Resolves the block's vertical gradient (if any) to a solid color for the specific line.
+     */
+    private resolveBlockColorForLine;
+    /**
+     * Renders a single line.
      */
-    print(lines: StyledLine[]): void;
+    private renderLine;
 }

package/dist/core/printer.js

@@ -1,41 +1,129 @@
-import { resolveStyle, RESET } from "./style";
+import { getGradientColor, mergeStyles, resolveStyle, RESET, interpolateColor, resolveModifiersToAnsi } from "./style";
 const ESC = "\x1b";
-// -----------------
-// Printer Class
-// -----------------
 /**
- * Handles rendering StyledLines to the terminal with support for interactive overwriting.
+ * Handles rendering PrintBlocks to the terminal with support for interactive/live overwriting.
  */
 export class Printer {
     linesRendered = 0;
-    isInteractive;
+    isLive;
+    data;
     constructor(options = {}) {
-        this.isInteractive = options.interactive ?? false;
+        this.isLive = options.live ?? false;
+        this.data = options.data;
     }
     /**
      * Generates the clear sequence to move cursor and clear previously rendered lines.
      */
     getClearSequence() {
-        if (!this.isInteractive || this.linesRendered === 0)
+        if (!this.isLive || this.linesRendered === 0)
             return "";
         return `${ESC}[1A${ESC}[2K\r`.repeat(this.linesRendered);
     }
     /**
-     * Renders an array of StyledLines to the standard output.
-     * If interactive mode is enabled, it clears the previously printed lines first.
+     * Clears the console using the stored line count.
+     */
+    clear() {
+        if (this.linesRendered > 0) {
+            process.stdout.write(this.getClearSequence());
+            this.linesRendered = 0;
+        }
+    }
+    /**
+     * Renders the PrintBlock to the standard output.
+     * If data is provided, updates the internal state.
      *
-     * @param lines - The lines to print.
+     * @param data - Optional data to update the printer with.
      */
-    print(lines) {
+    print(data) {
+        if (data) {
+            this.data = data;
+        }
+        if (!this.data) {
+            return; // Nothing to print
+        }
         let output = this.getClearSequence();
-        lines.forEach((line) => {
-            line.segments.forEach((seg) => {
-                const ansiStyle = resolveStyle(seg.style);
-                output += `${ansiStyle}${seg.text}${RESET}`;
-            });
+        const lines = this.data.lines;
+        const blockStyle = this.data.style ?? {};
+        lines.forEach((line, lineIndex) => {
+            output += this.renderLine(line, lineIndex, lines.length, blockStyle);
             output += "\n";
         });
         process.stdout.write(output);
         this.linesRendered = lines.length;
     }
+    /**
+     * Resolves the block's vertical gradient (if any) to a solid color for the specific line.
+     */
+    resolveBlockColorForLine(blockStyle, lineIndex, totalLines) {
+        if (!blockStyle.color)
+            return undefined;
+        if (Array.isArray(blockStyle.color)) {
+            // Vertical Gradient
+            if (totalLines <= 1)
+                return blockStyle.color[0]; // Single line, use first color
+            const colors = blockStyle.color;
+            const factor = lineIndex / (totalLines - 1);
+            // Interpolate manually to obtain Hex Color
+            const f = Math.max(0, Math.min(1, factor));
+            const segmentLength = 1 / (colors.length - 1);
+            const segmentIndex = Math.min(Math.floor(f / segmentLength), colors.length - 2);
+            const segmentFactor = (f - segmentIndex * segmentLength) / segmentLength;
+            const c1 = colors[segmentIndex];
+            const c2 = colors[segmentIndex + 1];
+            return interpolateColor(c1, c2, segmentFactor);
+        }
+        return blockStyle.color;
+    }
+    /**
+     * Renders a single line.
+     */
+    renderLine(line, lineIndex, totalLines, parentBlockStyle) {
+        // 1. Resolve Block Gradient to Solid Color for this line
+        const blockColorForLine = this.resolveBlockColorForLine(parentBlockStyle, lineIndex, totalLines);
+        // 2. Create Base Line Style (Block Modifiers + Resolved Block Color)
+        const baseLineStyle = {
+            modifiers: parentBlockStyle.modifiers,
+            color: blockColorForLine
+        };
+        // 3. Merge with Line's own style
+        // If line.style has color, it overrides baseLineStyle.color
+        const effectiveLineStyle = mergeStyles(baseLineStyle, line.style);
+        // 4. Pre-calculate total chars for horizontal gradients
+        const totalChars = line.segments.reduce((acc, seg) => acc + seg.text.length, 0);
+        let currentCharIndex = 0;
+        let lineOutput = "";
+        line.segments.forEach((seg) => {
+            const effectiveSegmentStyle = mergeStyles(effectiveLineStyle, seg.style);
+            if (Array.isArray(effectiveSegmentStyle.color)) {
+                // Gradient Handling (Horizontal)
+                const colors = effectiveSegmentStyle.color;
+                const text = seg.text;
+                // Determine if we are using the Line's gradient (Global) or Segment's gradient (Local)
+                // If effectiveSegmentStyle.color === effectiveLineStyle.color, it's inherited (Global)
+                // Otherwise it's the segment's own gradient (Local)
+                const isGlobalGradient = effectiveSegmentStyle.color === effectiveLineStyle.color;
+                // Iterate characters to apply gradient
+                const modifiersAnsi = resolveModifiersToAnsi(effectiveSegmentStyle.modifiers);
+                for (let i = 0; i < text.length; i++) {
+                    let factor = 0;
+                    if (isGlobalGradient && totalChars > 1) {
+                        factor = (currentCharIndex + i) / (totalChars - 1);
+                    }
+                    else if (!isGlobalGradient && text.length > 1) {
+                        factor = i / (text.length - 1);
+                    }
+                    const colorAnsi = getGradientColor(colors, factor); // Returns ANSI Color Code
+                    lineOutput += `${modifiersAnsi}${colorAnsi}${text[i]}`;
+                }
+                lineOutput += RESET;
+            }
+            else {
+                // Solid Color Handling
+                const ansi = resolveStyle(effectiveSegmentStyle);
+                lineOutput += `${ansi}${seg.text}${RESET}`;
+            }
+            currentCharIndex += seg.text.length;
+        });
+        return lineOutput;
+    }
 }

package/dist/core/printer.test.js

@@ -1,36 +1,124 @@
 import { expect, test, describe, spyOn, afterEach } from "bun:test";
 import { Printer } from "./printer";
+import { resolveColorToAnsi } from "./style";
+const ESC = "\x1b";
 describe("Printer", () => {
+    // Mock process.stdout.write to prevent actual output during tests
     const stdoutSpy = spyOn(process.stdout, "write").mockImplementation(() => true);
     afterEach(() => {
         stdoutSpy.mockClear();
     });
-    test("Printer.print outputs to console with resolved styles", () => {
+    test("Printer.print outputs basic text with solid styles", () => {
         const printer = new Printer();
-        printer.print([{ segments: [{ text: "Test", style: "red" }] }]);
-        expect(stdoutSpy).toHaveBeenCalled();
+        const block = {
+            lines: [{ segments: [{ text: "Hello", style: { color: "red" } }] }]
+        };
+        printer.print(block);
+        expect(stdoutSpy).toHaveBeenCalledTimes(1);
         const output = stdoutSpy.mock.calls[0][0];
-        expect(output).toContain("\x1b[31mTest");
-    });
-    test("Printer handles interactive clearing", () => {
-        const printer = new Printer({ interactive: true });
-        printer.print([{ segments: [{ text: "L1", style: "" }] }]);
-        printer.print([{ segments: [{ text: "L2", style: "" }] }]);
-        expect(stdoutSpy).toHaveBeenCalledWith(expect.stringContaining("\x1b[1A\x1b[2K\r"));
-    });
-    test("Printer optimizes clearing of multiple lines", () => {
-        const printer = new Printer({ interactive: true });
-        printer.print([
-            { segments: [{ text: "L1", style: "" }] },
-            { segments: [{ text: "L2", style: "" }] },
-            { segments: [{ text: "L3", style: "" }] }
-        ]);
-        stdoutSpy.mockClear();
-        printer.print([{ segments: [{ text: "New", style: "" }] }]);
-        const clearSeq = "\x1b[1A\x1b[2K\r";
-        const expectedClear = clearSeq.repeat(3);
+        // Check for Red ANSI + Text + Reset
+        expect(output).toContain(`${ESC}[38;2;239;68;68mHello${ESC}[0m`);
+    });
+    test("Printer.print applies Block style to lines (inheritance)", () => {
+        const printer = new Printer();
+        const block = {
+            style: { color: "blue", modifiers: ["bold"] },
+            lines: [{ segments: [{ text: "Line 1" }] }, { segments: [{ text: "Line 2" }] }]
+        };
+        printer.print(block);
+        const output = stdoutSpy.mock.calls[0][0];
+        const blueAnsi = resolveColorToAnsi("blue");
+        const boldAnsi = `${ESC}[1m`;
+        // Both lines should be Blue + Bold
+        // Matches: Bold + Blue + Text + Reset
+        expect(output).toContain(`${boldAnsi}${blueAnsi}Line 1${ESC}[0m`);
+        expect(output).toContain(`${boldAnsi}${blueAnsi}Line 2${ESC}[0m`);
+    });
+    test("Printer handles Block Vertical Gradient (Lines inherit solid colors)", () => {
+        const printer = new Printer();
+        const block = {
+            style: { color: ["#000000", "#FFFFFF"] }, // Black to White
+            lines: [
+                { segments: [{ text: "Start" }] }, // Should be Black
+                { segments: [{ text: "Middle" }] }, // Should be Gray
+                { segments: [{ text: "End" }] } // Should be White
+            ]
+        };
+        printer.print(block);
+        const output = stdoutSpy.mock.calls[0][0];
+        const blackAnsi = resolveColorToAnsi("#000000");
+        const whiteAnsi = resolveColorToAnsi("#FFFFFF");
+        const grayAnsi = resolveColorToAnsi("#808080");
+        expect(output).toContain(`${blackAnsi}Start${ESC}[0m`);
+        expect(output).toContain(`${grayAnsi}Middle${ESC}[0m`);
+        expect(output).toContain(`${whiteAnsi}End${ESC}[0m`);
+    });
+    test("Printer handles Line Override (Horizontal Gradient)", () => {
+        const printer = new Printer();
+        const block = {
+            lines: [
+                {
+                    style: { color: ["#FF0000", "#0000FF"] }, // Red to Blue
+                    segments: [{ text: "GB" }] // Gradient applies to these 2 chars
+                }
+            ]
+        };
+        printer.print(block);
+        const output = stdoutSpy.mock.calls[0][0];
+        // First char 'G' should be Red (start)
+        // Second char 'B' should be Blue (end) - wait, factor logic?
+        // Length 2. index 0 -> factor 0. index 1 -> factor 1.
+        const redAnsi = resolveColorToAnsi("#FF0000");
+        const blueAnsi = resolveColorToAnsi("#0000FF");
+        expect(output).toContain(`${redAnsi}G`);
+        expect(output).toContain(`${blueAnsi}B`);
+    });
+    test("Printer handles Segment Override (Solid overrides Line Gradient)", () => {
+        const printer = new Printer();
+        const block = {
+            lines: [
+                {
+                    style: { color: ["#FF0000", "#0000FF"] }, // Line Gradient
+                    segments: [
+                        { text: "A" }, // Inherits Gradient (Red)
+                        { text: "B", style: { color: "green" } } // Override Solid (Green)
+                    ]
+                }
+            ]
+        };
+        printer.print(block);
+        const output = stdoutSpy.mock.calls[0][0];
+        const redAnsi = resolveColorToAnsi("#FF0000");
+        const greenAnsi = resolveColorToAnsi("green");
+        expect(output).toContain(`${redAnsi}A`);
+        expect(output).toContain(`${greenAnsi}B`);
+    });
+    test("Printer handles live clearing", () => {
+        const printer = new Printer({ live: true });
+        // Print 2 lines
+        printer.print({
+            lines: [{ segments: [{ text: "1" }] }, { segments: [{ text: "2" }] }]
+        });
+        // Print again (should clear 2 lines)
+        printer.print({
+            lines: [{ segments: [{ text: "New" }] }]
+        });
+        const clearSeq = `${ESC}[1A${ESC}[2K\r`;
+        const expectedClear = clearSeq.repeat(2);
+        const secondCallOutput = stdoutSpy.mock.calls[1][0];
+        expect(secondCallOutput.startsWith(expectedClear)).toBe(true);
+    });
+    test("Printer.clear() manually clears the output", () => {
+        const printer = new Printer({ live: true });
+        printer.print({
+            lines: [{ segments: [{ text: "Line 1" }] }]
+        });
         expect(stdoutSpy).toHaveBeenCalledTimes(1);
-        const callArg = stdoutSpy.mock.calls[0][0];
-        expect(callArg.startsWith(expectedClear)).toBe(true);
+        printer.clear();
+        expect(stdoutSpy).toHaveBeenCalledTimes(2);
+        const clearSeq = `${ESC}[1A${ESC}[2K\r`;
+        const expectedClear = clearSeq.repeat(1);
+        const clearOutput = stdoutSpy.mock.calls[1][0];
+        expect(clearOutput).toBe(expectedClear);
     });
 });