@retrovm/terminal 0.1.3 → 0.2.1

package/dist/node.js

@@ -27,6 +27,11 @@ class Color {
       this._g = g;
       this._b = b;
       this._a = a;
+    } else if (typeof rs === "number" && g === undefined && b === undefined) {
+      this._r = (rs & 255) / 255;
+      this._g = (rs >> 8 & 255) / 255;
+      this._b = (rs >> 16 & 255) / 255;
+      this._a = (rs >> 24 & 255) / 255;
     } else if (typeof rs === "string") {
       const match = rs.match(/^#?([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})?$/i);
       if (match) {
@@ -126,6 +131,9 @@ class Color {
     this._ansiFg = undefined;
     this._ansiBg = undefined;
   }
+  toRGBA() {
+    return (Math.round(this._a * 255) << 24 | Math.round(this._b * 255) << 16 | Math.round(this._g * 255) << 8 | Math.round(this._r * 255)) >>> 0;
+  }
   toString() {
     return `#${Math.round(this._r * 255).toString(16).padStart(2, "0")}${Math.round(this._g * 255).toString(16).padStart(2, "0")}${Math.round(this._b * 255).toString(16).padStart(2, "0")}${Math.round(this._a * 255).toString(16).padStart(2, "0")}`;
   }
@@ -311,15 +319,14 @@ import { format } from "node:util";
 class TerminalCore {
   writer;
   plain;
+  _buffer = null;
+  _syncDepth = 0;
   _altScreen = false;
   constructor(writer, options = {}) {
     this.writer = writer;
     const envNoColor = typeof process !== "undefined" && !!process?.env?.NO_COLOR;
     this.plain = options.plain ?? envNoColor;
   }
-  emit(data) {
-    this.writer.write(data);
-  }
   style(seq, fmt, args) {
     const text = format(fmt, ...args);
     this.emit(this.plain ? text : seq + text);
@@ -417,6 +424,51 @@ class TerminalCore {
     this.emit(`\x1B[${top};${bottom}r`);
     return this;
   }
+  buffer() {
+    if (this._buffer === null)
+      this._buffer = "";
+    return this;
+  }
+  flush() {
+    if (this._buffer !== null) {
+      const data = this._buffer;
+      this._buffer = null;
+      if (data.length > 0)
+        this.writer.write(data);
+    }
+    return this;
+  }
+  raw(data) {
+    this.emit(data);
+    return this;
+  }
+  sync(fn) {
+    const outer = this._syncDepth === 0;
+    const startedBuffer = outer && this._buffer === null;
+    if (outer) {
+      if (startedBuffer)
+        this.buffer();
+      this.emit("\x1B[?2026h");
+    }
+    this._syncDepth++;
+    try {
+      fn();
+    } finally {
+      this._syncDepth--;
+      if (outer) {
+        this.emit("\x1B[?2026l");
+        if (startedBuffer)
+          this.flush();
+      }
+    }
+    return this;
+  }
+  emit(data) {
+    if (this._buffer !== null)
+      this._buffer += data;
+    else
+      this.writer.write(data);
+  }
 }
 function installColorMethods() {
   const proto = TerminalCore.prototype;

package/dist/terminal.d.ts

@@ -14,7 +14,7 @@ export interface ITerminalWriter {
  * appear automatically with full type safety and autocompletion.
  */
 type ColorName = {
-    [K in keyof typeof Color]: typeof Color[K] extends Color ? K : never;
+    [K in keyof typeof Color]: (typeof Color)[K] extends Color ? K : never;
 }[keyof typeof Color];
 type ColorMethod = (fmt?: string, ...args: unknown[]) => ITerminal;
 type InkMethods = {
@@ -37,25 +37,50 @@ export type ITerminal = TerminalCore & InkMethods & BgMethods;
  * and dispatched through an index signature on the class.
  */
 declare class TerminalCore {
-    private readonly writer;
+    protected readonly writer: ITerminalWriter;
     /** ANSI is suppressed when true; styling/cursor methods become no-ops. */
     plain: boolean;
-    private _altScreen;
+    /** Accumulated output when in buffered mode; `null` when unbuffered. */
+    protected _buffer: string | null;
+    /** Nesting depth of active `sync()` calls; only the outermost emits mode 2026. */
+    protected _syncDepth: number;
+    /** Tracks whether the alternate screen buffer is currently active. */
+    protected _altScreen: boolean;
     [key: string]: unknown;
+    /**
+     * @param writer - Any object that implements `write(data: string)`.
+     * @param options.plain - When `true`, all ANSI escape sequences are stripped
+     *   and only plain text is emitted. Defaults to `true` when the `NO_COLOR`
+     *   environment variable is set; `false` otherwise.
+     */
     constructor(writer: ITerminalWriter, options?: {
         plain?: boolean;
     });
-    /** Internal write helper. Single point of contact with the sink. */
-    private emit;
     /** Internal style helper: skips ANSI when `plain` is enabled. */
     private style;
     /** Prints formatted text. Uses `util.format` semantics (`%s`, `%d`, …). */
     print(fmt?: string, ...args: unknown[]): this;
     /** Prints formatted text followed by a newline. */
     println(fmt?: string, ...args: unknown[]): this;
-    /** Sets the foreground color and optionally writes formatted text. */
+    /**
+     * Sets the foreground color and optionally writes formatted text.
+     *
+     * @param c - A `Color` instance or a CSS-compatible color string (`'#f80'`,
+     *   `'#ff8800'`, `'red'`). Strings are parsed by `Color` on every call;
+     *   prefer passing a pre-built `Color` instance in hot loops.
+     * @param fmt - `util.format`-style template string.
+     * @param args - Substitution values for `fmt`.
+     */
     ink(c: string | Color, fmt?: string, ...args: unknown[]): this;
-    /** Sets the background color and optionally writes formatted text. */
+    /**
+     * Sets the background color and optionally writes formatted text.
+     *
+     * @param c - A `Color` instance or a CSS-compatible color string (`'#f80'`,
+     *   `'#ff8800'`, `'red'`). Strings are parsed by `Color` on every call;
+     *   prefer passing a pre-built `Color` instance in hot loops.
+     * @param fmt - `util.format`-style template string.
+     * @param args - Substitution values for `fmt`.
+     */
     paper(c: string | Color, fmt?: string, ...args: unknown[]): this;
     /**
      * Resets all text attributes (color, background, bold, dim, italic,
@@ -84,9 +109,13 @@ declare class TerminalCore {
     cls(): this;
     /** Clears from cursor to end of line. */
     clearLine(): this;
+    /** Moves the cursor up by `n` rows (CUU). */
     up(n?: number): this;
+    /** Moves the cursor down by `n` rows (CUD). */
     down(n?: number): this;
+    /** Moves the cursor right by `n` columns (CUF). */
     right(n?: number): this;
+    /** Moves the cursor left by `n` columns (CUB). */
     left(n?: number): this;
     /** Moves the cursor to the given column (1-based). */
     column(n?: number): this;
@@ -100,20 +129,101 @@ declare class TerminalCore {
     restoreCursor(): this;
     /** Shows or hides the cursor. */
     cursor(visible?: boolean): this;
-    /** Enables or disables the alternate screen buffer. */
+    /**
+     * Switches to (`true`) or exits (`false`) the alternate screen buffer
+     * (DECSET/DECRST 1049). The alternate screen saves the current scrollback
+     * and cursor state on entry, presents a blank canvas for TUI rendering, and
+     * restores the original view on exit — exactly what `vim`, `less`, and
+     * similar programs do. Calls are idempotent: switching to a buffer already
+     * active emits nothing.
+     */
     alt(b?: boolean): this;
     /**
-     * Enables or disables auto-wrap (DECAWM, mode 7).
-     * Note: this is the rename of the old `scroll()` method, which was
-     * misnamed — DEC private mode 7 controls wrapping, not scrolling.
+     * Enables or disables auto-wrap (DECAWM, DEC private mode 7). When enabled
+     * (the default in most terminals), the cursor wraps to the next line when
+     * it reaches the right margin. Disable it to overwrite characters in place,
+     * which is useful for progress bars and fixed-width TUI cells.
      */
     autoWrap(b?: boolean): this;
-    /** Sets the scrolling region (DECSTBM), both rows 1-based and inclusive. */
+    /**
+     * Sets the scrolling region (DECSTBM). Scroll and line-feed operations are
+     * confined to rows `top`–`bottom`, leaving content outside the region
+     * undisturbed. Both values are 1-based and inclusive. Useful for keeping a
+     * status bar or header fixed while the main content area scrolls normally.
+     *
+     * @param top - First row of the scrolling region (1-based).
+     * @param bottom - Last row of the scrolling region (1-based).
+     */
     scrollRegion(top: number, bottom: number): this;
+    /**
+     * Enters buffered mode. Subsequent emissions accumulate in memory until
+     * `flush()` commits them in a single `write()` to the underlying sink.
+     *
+     * Essential for animation loops and full-screen redraws on terminals
+     * that perform poorly with many small writes (macOS Terminal, GNOME
+     * Terminal, Konsole). A 80×24 frame can easily produce thousands of
+     * style transitions; coalescing them into one write turns thousands
+     * of syscalls into one.
+     *
+     * Calling `buffer()` while already buffered is a no-op — buffered
+     * mode is a single state, not a stack.
+     */
+    buffer(): this;
+    /**
+     * Commits the accumulated buffer in a single `write()` and exits
+     * buffered mode. Calling `flush()` when not buffered is a no-op.
+     */
+    flush(): this;
+    /**
+     * Writes a pre-built string directly, bypassing `util.format`. Useful
+     * in hot loops where the caller has already constructed the exact bytes
+     * to emit (e.g. precomputed SGR sequences from a palette LUT) and wants
+     * to avoid the per-call formatting overhead.
+     *
+     * Honors buffered mode like every other emission.
+     */
+    raw(data: string): this;
+    /**
+     * Runs `fn` inside a synchronized-output block (DEC private mode 2026).
+     * The terminal accumulates all changes from the block and presents them
+     * atomically when the block ends, eliminating tearing in TUIs and
+     * animations. Terminals that don't support mode 2026 (e.g. macOS
+     * Terminal.app, plain xterm) ignore the escape silently.
+     *
+     * Automatically enables buffered mode for the duration of the block —
+     * synchronized output without buffering would defeat its purpose, since
+     * each tiny write would still race the terminal's refresh.
+     *
+     * Re-entrant: nested `sync()` calls share the outer block (mode 2026
+     * is not stackable in the protocol).
+     *
+     * The block is guarded by try/finally so the closing escape and flush
+     * always run, even if `fn` throws — important because mode 2026 has a
+     * ~150ms server-side timeout and leaving it open looks like a freeze.
+     *
+     * @example
+     * out.sync(() => {
+     *   for (let row = 0; row < H; row++) {
+     *     for (let col = 0; col < W; col++) {
+     *       out.moveTo(row + 1, col + 1).paper(bg).ink(fg, '▄')
+     *     }
+     *   }
+     * })
+     */
+    sync(fn: () => void): this;
+    private emit;
 }
 /**
- * Public constructor. Accepts any object with a `write(string)` method —
- * an xterm.js `Terminal`, a Node `Writable`, a Bun writer wrapper, or a mock.
+ * Creates a new `Terminal` instance backed by `writer`.
+ *
+ * Accepts any object with a `write(string)` method — an xterm.js `Terminal`,
+ * a Node `Writable`, a Bun writer wrapper, or a test double.
+ *
+ * @param writer - The output sink. Must implement `write(data: string): void`.
+ * @param options.plain - Suppress all ANSI sequences and emit plain text only.
+ *   Defaults to `true` when `NO_COLOR` is set in the environment.
+ * @returns A fully typed `ITerminal` with core methods and auto-generated
+ *   named-color shortcuts (`red`, `bgBlue`, …).
  *
  * @example
  * import { Terminal as XTerm } from '@xterm/xterm'

package/dist/terminal.js

@@ -27,6 +27,11 @@ class Color {
       this._g = g;
       this._b = b;
       this._a = a;
+    } else if (typeof rs === "number" && g === undefined && b === undefined) {
+      this._r = (rs & 255) / 255;
+      this._g = (rs >> 8 & 255) / 255;
+      this._b = (rs >> 16 & 255) / 255;
+      this._a = (rs >> 24 & 255) / 255;
     } else if (typeof rs === "string") {
       const match = rs.match(/^#?([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})?$/i);
       if (match) {
@@ -126,6 +131,9 @@ class Color {
     this._ansiFg = undefined;
     this._ansiBg = undefined;
   }
+  toRGBA() {
+    return (Math.round(this._a * 255) << 24 | Math.round(this._b * 255) << 16 | Math.round(this._g * 255) << 8 | Math.round(this._r * 255)) >>> 0;
+  }
   toString() {
     return `#${Math.round(this._r * 255).toString(16).padStart(2, "0")}${Math.round(this._g * 255).toString(16).padStart(2, "0")}${Math.round(this._b * 255).toString(16).padStart(2, "0")}${Math.round(this._a * 255).toString(16).padStart(2, "0")}`;
   }
@@ -311,15 +319,14 @@ import { format } from "node:util";
 class TerminalCore {
   writer;
   plain;
+  _buffer = null;
+  _syncDepth = 0;
   _altScreen = false;
   constructor(writer, options = {}) {
     this.writer = writer;
     const envNoColor = typeof process !== "undefined" && !!process?.env?.NO_COLOR;
     this.plain = options.plain ?? envNoColor;
   }
-  emit(data) {
-    this.writer.write(data);
-  }
   style(seq, fmt, args) {
     const text = format(fmt, ...args);
     this.emit(this.plain ? text : seq + text);
@@ -417,6 +424,51 @@ class TerminalCore {
     this.emit(`\x1B[${top};${bottom}r`);
     return this;
   }
+  buffer() {
+    if (this._buffer === null)
+      this._buffer = "";
+    return this;
+  }
+  flush() {
+    if (this._buffer !== null) {
+      const data = this._buffer;
+      this._buffer = null;
+      if (data.length > 0)
+        this.writer.write(data);
+    }
+    return this;
+  }
+  raw(data) {
+    this.emit(data);
+    return this;
+  }
+  sync(fn) {
+    const outer = this._syncDepth === 0;
+    const startedBuffer = outer && this._buffer === null;
+    if (outer) {
+      if (startedBuffer)
+        this.buffer();
+      this.emit("\x1B[?2026h");
+    }
+    this._syncDepth++;
+    try {
+      fn();
+    } finally {
+      this._syncDepth--;
+      if (outer) {
+        this.emit("\x1B[?2026l");
+        if (startedBuffer)
+          this.flush();
+      }
+    }
+    return this;
+  }
+  emit(data) {
+    if (this._buffer !== null)
+      this._buffer += data;
+    else
+      this.writer.write(data);
+  }
 }
 function installColorMethods() {
   const proto = TerminalCore.prototype;

package/package.json

@@ -1,28 +1,19 @@
 {
   "name": "@retrovm/terminal",
-  "version": "0.1.3",
-  "description": "Fluent ANSI terminal library — 24-bit color, cursor control and screen management for Bun and Node.js",
+  "version": "0.2.1",
   "author": "Juan Carlos González Amestoy",
-  "license": "MIT",
-  "keywords": [
-    "terminal",
-    "ansi",
-    "color",
-    "cursor",
-    "tui",
-    "cli",
-    "bun",
-    "fluent"
-  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/retrovm/terminal.git"
   },
-  "type": "module",
   "module": "src/terminal.ts",
-  "scripts": {
-    "build": "bun build src/terminal.ts src/node.ts --outdir dist --target node && tsc -p tsconfig.build.json",
-    "prepublishOnly": "bun run build"
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^25.9.1",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
   },
   "exports": {
     ".": {
@@ -35,22 +26,31 @@
       "import": "./dist/terminal.js"
     }
   },
+  "description": "Fluent ANSI terminal library — 24-bit color, cursor control and screen management for Bun and Node.js",
   "files": [
     "src",
     "dist"
   ],
-  "devDependencies": {
-    "@types/bun": "latest",
-    "@types/node": "^25.8.0",
-    "typescript": "^5"
+  "keywords": [
+    "terminal",
+    "ansi",
+    "color",
+    "cursor",
+    "tui",
+    "cli",
+    "bun",
+    "fluent"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
   },
-  "peerDependencies": {
-    "typescript": "^5"
+  "scripts": {
+    "build": "bun build src/terminal.ts src/node.ts --outdir dist --target node && tsc -p tsconfig.build.json",
+    "prepublishOnly": "bun run build"
   },
+  "type": "module",
   "dependencies": {
-    "@retrovm/color": "^0.1.1"
-  },
-  "publishConfig": {
-    "access": "public"
+    "@retrovm/color": "^0.2.2"
   }
 }

package/src/bun.ts

@@ -21,20 +21,13 @@ SOFTWARE.*/
 import { createTerminal } from "./terminal"
 export { createTerminal, type ITerminal, type ITerminalWriter } from "./terminal"
 
-const  _writeOut=(data:string)=>{
-    const w=Bun.stdout.writer()
-    w.write(data)
-    w.flush()
-  }
+const _outWriter = Bun.stdout.writer()
+const _errWriter = Bun.stderr.writer()
 
-const  _writeErr=(data:string)=>{
-    const w=Bun.stderr.writer()
-    w.write(data)
-    w.flush()
-  }
+const _writeOut = (data: string) => { _outWriter.write(data); _outWriter.flush() }
+const _writeErr = (data: string) => { _errWriter.write(data); _errWriter.flush() }
 
-
-export const Terminal={
-  out: createTerminal({ write: _writeOut }) ,
-  err: createTerminal({ write: _writeErr }) ,
+export const Terminal = {
+  out: createTerminal({ write: _writeOut }),
+  err: createTerminal({ write: _writeErr }),
 }

package/src/terminal.ts

@@ -37,7 +37,7 @@ export interface ITerminalWriter {
  * appear automatically with full type safety and autocompletion.
  */
 type ColorName = {
-  [K in keyof typeof Color]: typeof Color[K] extends Color ? K : never
+  [K in keyof typeof Color]: (typeof Color)[K] extends Color ? K : never
 }[keyof typeof Color]
 
 type ColorMethod = (fmt?: string, ...args: unknown[]) => ITerminal
@@ -62,27 +62,32 @@ class TerminalCore {
   /** ANSI is suppressed when true; styling/cursor methods become no-ops. */
   public plain: boolean
 
-  private _altScreen = false;
+  /** Accumulated output when in buffered mode; `null` when unbuffered. */
+  protected _buffer: string | null = null
+  /** Nesting depth of active `sync()` calls; only the outermost emits mode 2026. */
+  protected _syncDepth = 0
+  /** Tracks whether the alternate screen buffer is currently active. */
+  protected _altScreen = false;
 
   // Allows the auto-attached color methods to typecheck on `this`.
   [key: string]: unknown
 
+  /**
+   * @param writer - Any object that implements `write(data: string)`.
+   * @param options.plain - When `true`, all ANSI escape sequences are stripped
+   *   and only plain text is emitted. Defaults to `true` when the `NO_COLOR`
+   *   environment variable is set; `false` otherwise.
+   */
   constructor(
-    private readonly writer: ITerminalWriter,
+    protected readonly writer: ITerminalWriter,
     options: { plain?: boolean } = {},
   ) {
     // Honor NO_COLOR (https://no-color.org/) by default when running under
     // Node/Bun; in browser/xterm contexts `process` may be undefined.
-    const envNoColor =
-      typeof process !== 'undefined' && !!process?.env?.NO_COLOR
+    const envNoColor = typeof process !== 'undefined' && !!process?.env?.NO_COLOR
     this.plain = options.plain ?? envNoColor
   }
 
-  /** Internal write helper. Single point of contact with the sink. */
-  private emit(data: string): void {
-    this.writer.write(data)
-  }
-
   /** Internal style helper: skips ANSI when `plain` is enabled. */
   private style(seq: string, fmt: string, args: unknown[]): this {
     const text = format(fmt, ...args)
@@ -106,13 +111,29 @@ class TerminalCore {
 
   // ─── Color ────────────────────────────────────────────────────────────────
 
-  /** Sets the foreground color and optionally writes formatted text. */
+  /**
+   * Sets the foreground color and optionally writes formatted text.
+   *
+   * @param c - A `Color` instance or a CSS-compatible color string (`'#f80'`,
+   *   `'#ff8800'`, `'red'`). Strings are parsed by `Color` on every call;
+   *   prefer passing a pre-built `Color` instance in hot loops.
+   * @param fmt - `util.format`-style template string.
+   * @param args - Substitution values for `fmt`.
+   */
   ink(c: string | Color, fmt: string = '', ...args: unknown[]): this {
     const color = typeof c === 'string' ? new Color(c) : c
     return this.style(color.toAnsiRGB(), fmt, args)
   }
 
-  /** Sets the background color and optionally writes formatted text. */
+  /**
+   * Sets the background color and optionally writes formatted text.
+   *
+   * @param c - A `Color` instance or a CSS-compatible color string (`'#f80'`,
+   *   `'#ff8800'`, `'red'`). Strings are parsed by `Color` on every call;
+   *   prefer passing a pre-built `Color` instance in hot loops.
+   * @param fmt - `util.format`-style template string.
+   * @param args - Substitution values for `fmt`.
+   */
   paper(c: string | Color, fmt: string = '', ...args: unknown[]): this {
     const color = typeof c === 'string' ? new Color(c) : c
     return this.style(color.toAnsiBackgroundRGB(), fmt, args)
@@ -169,10 +190,29 @@ class TerminalCore {
 
   // ─── Cursor ───────────────────────────────────────────────────────────────
 
-  up(n: number = 1): this    { this.emit(`\x1b[${n}A`); return this }
-  down(n: number = 1): this  { this.emit(`\x1b[${n}B`); return this }
-  right(n: number = 1): this { this.emit(`\x1b[${n}C`); return this }
-  left(n: number = 1): this  { this.emit(`\x1b[${n}D`); return this }
+  /** Moves the cursor up by `n` rows (CUU). */
+  up(n: number = 1): this {
+    this.emit(`\x1b[${n}A`)
+    return this
+  }
+
+  /** Moves the cursor down by `n` rows (CUD). */
+  down(n: number = 1): this {
+    this.emit(`\x1b[${n}B`)
+    return this
+  }
+
+  /** Moves the cursor right by `n` columns (CUF). */
+  right(n: number = 1): this {
+    this.emit(`\x1b[${n}C`)
+    return this
+  }
+
+  /** Moves the cursor left by `n` columns (CUB). */
+  left(n: number = 1): this {
+    this.emit(`\x1b[${n}D`)
+    return this
+  }
 
   /** Moves the cursor to the given column (1-based). */
   column(n: number = 1): this {
@@ -212,7 +252,14 @@ class TerminalCore {
 
   // ─── Modes ────────────────────────────────────────────────────────────────
 
-  /** Enables or disables the alternate screen buffer. */
+  /**
+   * Switches to (`true`) or exits (`false`) the alternate screen buffer
+   * (DECSET/DECRST 1049). The alternate screen saves the current scrollback
+   * and cursor state on entry, presents a blank canvas for TUI rendering, and
+   * restores the original view on exit — exactly what `vim`, `less`, and
+   * similar programs do. Calls are idempotent: switching to a buffer already
+   * active emits nothing.
+   */
   alt(b: boolean = true): this {
     if (b !== this._altScreen) {
       this.emit(`\x1b[?1049${b ? 'h' : 'l'}`)
@@ -222,20 +269,129 @@ class TerminalCore {
   }
 
   /**
-   * Enables or disables auto-wrap (DECAWM, mode 7).
-   * Note: this is the rename of the old `scroll()` method, which was
-   * misnamed — DEC private mode 7 controls wrapping, not scrolling.
+   * Enables or disables auto-wrap (DECAWM, DEC private mode 7). When enabled
+   * (the default in most terminals), the cursor wraps to the next line when
+   * it reaches the right margin. Disable it to overwrite characters in place,
+   * which is useful for progress bars and fixed-width TUI cells.
    */
   autoWrap(b: boolean = true): this {
     this.emit(`\x1b[?7${b ? 'h' : 'l'}`)
     return this
   }
 
-  /** Sets the scrolling region (DECSTBM), both rows 1-based and inclusive. */
+  /**
+   * Sets the scrolling region (DECSTBM). Scroll and line-feed operations are
+   * confined to rows `top`–`bottom`, leaving content outside the region
+   * undisturbed. Both values are 1-based and inclusive. Useful for keeping a
+   * status bar or header fixed while the main content area scrolls normally.
+   *
+   * @param top - First row of the scrolling region (1-based).
+   * @param bottom - Last row of the scrolling region (1-based).
+   */
   scrollRegion(top: number, bottom: number): this {
     this.emit(`\x1b[${top};${bottom}r`)
     return this
   }
+
+  // ─── Buffered output ──────────────────────────────────────────────────────
+
+  /**
+   * Enters buffered mode. Subsequent emissions accumulate in memory until
+   * `flush()` commits them in a single `write()` to the underlying sink.
+   *
+   * Essential for animation loops and full-screen redraws on terminals
+   * that perform poorly with many small writes (macOS Terminal, GNOME
+   * Terminal, Konsole). A 80×24 frame can easily produce thousands of
+   * style transitions; coalescing them into one write turns thousands
+   * of syscalls into one.
+   *
+   * Calling `buffer()` while already buffered is a no-op — buffered
+   * mode is a single state, not a stack.
+   */
+  buffer(): this {
+    if (this._buffer === null) this._buffer = ''
+    return this
+  }
+
+  /**
+   * Commits the accumulated buffer in a single `write()` and exits
+   * buffered mode. Calling `flush()` when not buffered is a no-op.
+   */
+  flush(): this {
+    if (this._buffer !== null) {
+      const data = this._buffer
+      this._buffer = null
+      if (data.length > 0) this.writer.write(data)
+    }
+    return this
+  }
+
+  /**
+   * Writes a pre-built string directly, bypassing `util.format`. Useful
+   * in hot loops where the caller has already constructed the exact bytes
+   * to emit (e.g. precomputed SGR sequences from a palette LUT) and wants
+   * to avoid the per-call formatting overhead.
+   *
+   * Honors buffered mode like every other emission.
+   */
+  raw(data: string): this {
+    this.emit(data)
+    return this
+  }
+
+  // ─── Synchronized output ──────────────────────────────────────────────────
+
+  /**
+   * Runs `fn` inside a synchronized-output block (DEC private mode 2026).
+   * The terminal accumulates all changes from the block and presents them
+   * atomically when the block ends, eliminating tearing in TUIs and
+   * animations. Terminals that don't support mode 2026 (e.g. macOS
+   * Terminal.app, plain xterm) ignore the escape silently.
+   *
+   * Automatically enables buffered mode for the duration of the block —
+   * synchronized output without buffering would defeat its purpose, since
+   * each tiny write would still race the terminal's refresh.
+   *
+   * Re-entrant: nested `sync()` calls share the outer block (mode 2026
+   * is not stackable in the protocol).
+   *
+   * The block is guarded by try/finally so the closing escape and flush
+   * always run, even if `fn` throws — important because mode 2026 has a
+   * ~150ms server-side timeout and leaving it open looks like a freeze.
+   *
+   * @example
+   * out.sync(() => {
+   *   for (let row = 0; row < H; row++) {
+   *     for (let col = 0; col < W; col++) {
+   *       out.moveTo(row + 1, col + 1).paper(bg).ink(fg, '▄')
+   *     }
+   *   }
+   * })
+   */
+  sync(fn: () => void): this {
+    const outer = this._syncDepth === 0
+    const startedBuffer = outer && this._buffer === null
+    if (outer) {
+      if (startedBuffer) this.buffer()
+      this.emit('\x1b[?2026h')
+    }
+    this._syncDepth++
+    try {
+      fn()
+    } finally {
+      this._syncDepth--
+      if (outer) {
+        this.emit('\x1b[?2026l')
+        if (startedBuffer) this.flush()
+      }
+    }
+    return this
+  }
+
+  private emit(data: string): void {
+    if (this._buffer !== null) this._buffer += data
+    else this.writer.write(data)
+  }
 }
 
 /**
@@ -266,8 +422,16 @@ function installColorMethods(): void {
 installColorMethods()
 
 /**
- * Public constructor. Accepts any object with a `write(string)` method —
- * an xterm.js `Terminal`, a Node `Writable`, a Bun writer wrapper, or a mock.
+ * Creates a new `Terminal` instance backed by `writer`.
+ *
+ * Accepts any object with a `write(string)` method — an xterm.js `Terminal`,
+ * a Node `Writable`, a Bun writer wrapper, or a test double.
+ *
+ * @param writer - The output sink. Must implement `write(data: string): void`.
+ * @param options.plain - Suppress all ANSI sequences and emit plain text only.
+ *   Defaults to `true` when `NO_COLOR` is set in the environment.
+ * @returns A fully typed `ITerminal` with core methods and auto-generated
+ *   named-color shortcuts (`red`, `bgBlue`, …).
  *
  * @example
  * import { Terminal as XTerm } from '@xterm/xterm'
@@ -276,13 +440,8 @@ installColorMethods()
  * const term = createTerminal(xterm)
  * term.red('Hello ').bgBlue(' world ').reset().println()
  */
-export function createTerminal(
-  writer: ITerminalWriter,
-  options: { plain?: boolean } = {},
-): ITerminal {
+export function createTerminal(writer: ITerminalWriter, options: { plain?: boolean } = {}): ITerminal {
   return new TerminalCore(writer, options) as unknown as ITerminal
 }
 
 export { TerminalCore }
-
-