@retrovm/terminal 0.2.0 → 0.3.0

package/README.md

@@ -11,6 +11,9 @@ Depends on [`@retrovm/color`](https://www.npmjs.com/package/@retrovm/color) (bun
 - **Named color shortcuts** — `term.red(...)`, `term.bgBlue(...)` etc., generated automatically from the `Color` registry
 - **Full cursor control** — move, save/restore, show/hide
 - **Screen management** — clear, alternate buffer, scroll region, auto-wrap
+- **Buffered output** — coalesce thousands of small writes into a single `write()` call with `buffer()` / `flush()`
+- **Synchronized output** — wrap redraws in `sync()` for tear-free animation via DEC mode 2026
+- **Pixel framebuffer** — render a `Uint32Array` pixel buffer directly to the terminal using the half-block trick (`framebuffer()`)
 - **Sink-agnostic** — works with Bun's stdout/stderr writers, Node.js `Writable`s, xterm.js terminals, or any test double
 - **`NO_COLOR` support** — respects the [no-color.org](https://no-color.org/) convention out of the box
 - **TypeScript-first** — strict types with full autocompletion for all color methods
@@ -104,8 +107,15 @@ term.ink(new Color('#3399ff'), 'Color instance')
 term.ink('#aaaaaa')   // set color only, write nothing
 ```
 
+#### `resetText(fmt?, ...args)`
+Resets all text attributes (color, background, bold, dim, italic, underline, …) without touching the cursor or alternate screen.
+
+```typescript
+term.red('colored').resetText(' — plain again')
+```
+
 #### `reset(fmt?, ...args)`
-Resets **all** attributes (color, background, bold, etc.) and optionally writes text.
+Full teardown: shows the cursor, exits the alternate screen buffer, and resets all text attributes. Use this as the last call in a TUI lifecycle.
 
 ```typescript
 term.red('warning').reset(' — back to normal')
@@ -225,6 +235,98 @@ term.scrollRegion(1, process.stdout.rows)   // reset to full screen
 
 ---
 
+### Buffered output
+
+#### `buffer()`
+Enters buffered mode. All subsequent emissions accumulate in memory instead of being written immediately. Calling `buffer()` while already buffered is a no-op.
+
+#### `flush()`
+Commits the buffer in a single `write()` call and exits buffered mode. Calling `flush()` when not buffered is a no-op.
+
+```typescript
+term.buffer()
+for (let i = 0; i < 1000; i++) term.moveTo(i % 24 + 1, 1).print('row %d', i)
+term.flush()   // one syscall instead of thousands
+```
+
+#### `raw(data)`
+Writes a pre-built string directly, bypassing `util.format`. Useful in hot loops where the caller has already constructed the exact bytes to emit.
+
+```typescript
+const seq = '\x1b[38;2;255;128;0m'   // precomputed orange
+term.raw(seq).raw('hot loop text').resetText()
+```
+
+---
+
+### Synchronized output
+
+#### `sync(fn)`
+Runs `fn` inside a synchronized-output block (DEC private mode 2026). The terminal accumulates all changes and presents them atomically when the block ends, eliminating tearing in TUIs and animations. Terminals that don't support mode 2026 ignore the escape silently.
+
+Automatically enables buffered mode for the duration of the block. Re-entrant: nested `sync()` calls share the outermost block.
+
+```typescript
+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).raw('▄')
+    }
+  }
+})
+```
+
+---
+
+### Pixel graphics
+
+#### `framebuffer(fb, w, h)`
+Renders a raw pixel buffer to the terminal using the half-block trick. Each pair of vertically adjacent pixels is encoded as a single `▄` character: the upper pixel becomes the background color and the lower pixel the foreground color, doubling the effective vertical resolution.
+
+- **`fb`** — `Uint32Array` of packed pixels. Format: little-endian RGBA (`0xAABBGGRR`), alpha ignored. Matches `Canvas.getImageData` output on little-endian systems.
+- **`w`** — Width in pixels (terminal columns).
+- **`h`** — Height in pixels. Must be even.
+
+The entire frame is assembled into one string before writing; the write is wrapped in `sync()`.
+
+```typescript
+const W = out.width ?? 80
+const H = (out.height ?? 24) * 2   // 2 pixel rows per character row
+const fb = new Uint32Array(W * H)
+
+// fill fb with 0xAABBGGRR pixels...
+fb[0] = 0xFF0000FF   // red pixel at (0, 0)
+
+out.framebuffer(fb, W, H)
+```
+
+---
+
+### Dimensions
+
+#### `width` *(getter)*
+Current width of the terminal in columns, as reported by the writer. Returns `-1` if the writer does not implement `width()`. Always reflects the current size — read on every access, so it stays correct after a resize.
+
+#### `height` *(getter)*
+Current height of the terminal in rows, as reported by the writer. Returns `-1` if the writer does not implement `height()`. Same live semantics as `width`.
+
+The built-in `Terminal.out` and `Terminal.err` instances always provide both — wired to `process.stdout.columns` / `process.stdout.rows` in both Bun and Node.
+
+Custom sinks can opt in by implementing the optional `width` and `height` functions on `ITerminalWriter`:
+
+```typescript
+const term = createTerminal({
+  write: s => myCanvas.write(s),
+  width:  () => myCanvas.cols,
+  height: () => myCanvas.rows,
+})
+
+term.width   // myCanvas.cols, live
+term.height  // myCanvas.rows, live
+```
+
+---
+
 ### Options
 
 #### `plain`
@@ -346,6 +448,20 @@ Procedural fire simulation using the **half-block trick**: the `▄` character h
 bun run sample/fire.ts
 ```
 
+### `snake.ts`
+Fully playable Snake game running in the alternate buffer. Uses `sync()` for tear-free rendering and updates only the cells that actually changed each tick. The snake body carries a smooth cyan-to-teal gradient; food pulses with an orange-yellow glow. Controls: WASD or arrow keys, Q to quit.
+
+```sh
+bun run sample/snake.ts
+```
+
+### `rotozoom.ts`
+Real-time rotating and zooming texture effect. Each frame the CPU computes a rotated/scaled UV map over the terminal dimensions and calls `out.framebuffer()` to push the result as a pixel buffer — demonstrating that `framebuffer()` is fast enough for 60 fps animation. Exit with any key.
+
+```sh
+bun run sample/rotozoom.ts
+```
+
 ### `sysmon.ts`
 Live system monitor that refreshes every second inside the alternate buffer. Two-panel layout drawn with box-drawing characters (`┌┬┐│├┤└┴┘─`). Left panel shows overall CPU average and per-core usage bars; right panel shows system RAM and process heap. All bars are color-coded: green below 70%, orange 70–90%, red above 90%.
 

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")}`;
   }
@@ -461,6 +469,48 @@ class TerminalCore {
     else
       this.writer.write(data);
   }
+  framebuffer(fb, w, h) {
+    const ch = [];
+    for (let y = 0;y < h; y += 2) {
+      for (let x = 0;x < w; x++) {
+        const i = y * w + x;
+        const c1 = fb[i];
+        const c2 = fb[i + w];
+        const b1 = c1 >> 16 & 255;
+        const g1 = c1 >> 8 & 255;
+        const r1 = c1 & 255;
+        const b2 = c2 >> 16 & 255;
+        const g2 = c2 >> 8 & 255;
+        const r2 = c2 & 255;
+        ch.push("\x1B[48;2;");
+        ch.push(r1.toString());
+        ch.push(";");
+        ch.push(g1.toString());
+        ch.push(";");
+        ch.push(b1.toString());
+        ch.push("m\x1B[38;2;");
+        ch.push(r2.toString());
+        ch.push(";");
+        ch.push(g2.toString());
+        ch.push(";");
+        ch.push(b2.toString());
+        ch.push("m▄");
+      }
+    }
+    this.sync(() => {
+      this.raw(ch.join(""));
+    });
+  }
+  get width() {
+    if (this.writer.width)
+      return this.writer.width();
+    return -1;
+  }
+  get height() {
+    if (this.writer.height)
+      return this.writer.height();
+    return -1;
+  }
 }
 function installColorMethods() {
   const proto = TerminalCore.prototype;
@@ -484,8 +534,8 @@ function createTerminal(writer, options = {}) {
 }
 // src/node.ts
 var Terminal = {
-  out: createTerminal(process.stdout),
-  err: createTerminal(process.stderr)
+  out: createTerminal({ write: (data) => process.stdout.write(data), width: () => process.stdout.columns ?? 80, height: () => process.stdout.rows ?? 24 }),
+  err: createTerminal({ write: (data) => process.stderr.write(data), width: () => process.stderr.columns ?? 80, height: () => process.stderr.rows ?? 24 })
 };
 export {
   createTerminal,

package/dist/terminal.d.ts

@@ -6,6 +6,8 @@ import { Color } from '@retrovm/color';
  */
 export interface ITerminalWriter {
     write(data: string): void;
+    width?: () => number;
+    height?: () => number;
 }
 /**
  * Extracts from `Color` only the keys whose value is an instance of `Color`,
@@ -212,6 +214,47 @@ declare class TerminalCore {
      */
     sync(fn: () => void): this;
     private emit;
+    /**
+     * Renders a raw pixel buffer to the terminal using the half-block trick.
+     *
+     * Each pair of vertically adjacent pixels is encoded as a single `▄`
+     * character: the upper pixel becomes the background color and the lower
+     * pixel becomes the foreground color, effectively doubling the vertical
+     * resolution — one character row covers two pixel rows.
+     *
+     * Pixel format: little-endian RGBA packed into a `Uint32Array`. Each
+     * element is `0xAABBGGRR` — R in the low byte, G in the next, B in the
+     * next, alpha ignored. This matches the layout produced by
+     * `Canvas.getImageData` and most image-decoding libraries when read as a
+     * `Uint32Array` on a little-endian system.
+     *
+     * The entire frame is assembled into one string before writing, which is
+     * far cheaper than calling `ink`/`paper`/`raw` per pixel. The write is
+     * wrapped in `sync()` to reduce tearing on capable terminals.
+     *
+     * @param fb - Pixel buffer. Length must be at least `w * h`.
+     * @param w  - Width in pixels (equals the number of terminal columns used).
+     * @param h  - Height in pixels. Must be even; an odd last row is ignored.
+     */
+    framebuffer(fb: Uint32Array, w: number, h: number): void;
+    /**
+     * Current width of the terminal in columns, as reported by the writer.
+     * Returns `-1` if the writer does not implement `width()`.
+     *
+     * Called on every access so it always reflects the current size, even after
+     * a resize event. The built-in Bun and Node writers read
+     * `process.stdout.columns` each time.
+     */
+    get width(): number;
+    /**
+     * Current height of the terminal in rows, as reported by the writer.
+     * Returns `-1` if the writer does not implement `height()`.
+     *
+     * Called on every access so it always reflects the current size, even after
+     * a resize event. The built-in Bun and Node writers read
+     * `process.stdout.rows` each time.
+     */
+    get height(): number;
 }
 /**
  * Creates a new `Terminal` instance backed by `writer`.

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")}`;
   }
@@ -461,6 +469,48 @@ class TerminalCore {
     else
       this.writer.write(data);
   }
+  framebuffer(fb, w, h) {
+    const ch = [];
+    for (let y = 0;y < h; y += 2) {
+      for (let x = 0;x < w; x++) {
+        const i = y * w + x;
+        const c1 = fb[i];
+        const c2 = fb[i + w];
+        const b1 = c1 >> 16 & 255;
+        const g1 = c1 >> 8 & 255;
+        const r1 = c1 & 255;
+        const b2 = c2 >> 16 & 255;
+        const g2 = c2 >> 8 & 255;
+        const r2 = c2 & 255;
+        ch.push("\x1B[48;2;");
+        ch.push(r1.toString());
+        ch.push(";");
+        ch.push(g1.toString());
+        ch.push(";");
+        ch.push(b1.toString());
+        ch.push("m\x1B[38;2;");
+        ch.push(r2.toString());
+        ch.push(";");
+        ch.push(g2.toString());
+        ch.push(";");
+        ch.push(b2.toString());
+        ch.push("m▄");
+      }
+    }
+    this.sync(() => {
+      this.raw(ch.join(""));
+    });
+  }
+  get width() {
+    if (this.writer.width)
+      return this.writer.width();
+    return -1;
+  }
+  get height() {
+    if (this.writer.height)
+      return this.writer.height();
+    return -1;
+  }
 }
 function installColorMethods() {
   const proto = TerminalCore.prototype;

package/package.json

@@ -1,28 +1,19 @@
 {
   "name": "@retrovm/terminal",
-  "version": "0.2.0",
-  "description": "Fluent ANSI terminal library — 24-bit color, cursor control and screen management for Bun and Node.js",
+  "version": "0.3.0",
   "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

@@ -1,33 +1,33 @@
-/*Copyright (c) 2026 Juan Carlos González Amestoy
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.*/
-
-import { createTerminal } from "./terminal"
-export { createTerminal, type ITerminal, type ITerminalWriter } from "./terminal"
-
-const _outWriter = Bun.stdout.writer()
-const _errWriter = Bun.stderr.writer()
-
-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 }),
+/*Copyright (c) 2026 Juan Carlos González Amestoy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.*/
+
+import { createTerminal } from "./terminal"
+export { createTerminal, type ITerminal, type ITerminalWriter } from "./terminal"
+
+const _outWriter = Bun.stdout.writer()
+const _errWriter = Bun.stderr.writer()
+
+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, width: () => process.stdout.columns ?? 80, height: () => process.stdout.rows ?? 24 }),
+  err: createTerminal({ write: _writeErr, width: () => process.stderr.columns ?? 80, height: () => process.stderr.rows ?? 24 }),
 }

package/src/node.ts

@@ -2,6 +2,6 @@ import { createTerminal } from "./terminal"
 export { createTerminal, type ITerminal, type ITerminalWriter } from "./terminal"
 
 export const Terminal = {
-  out: createTerminal(process.stdout),
-  err: createTerminal(process.stderr),
+  out: createTerminal({ write: (data: string) => process.stdout.write(data), width: () => process.stdout.columns ?? 80, height: () => process.stdout.rows ?? 24 }),
+  err: createTerminal({ write: (data: string) => process.stderr.write(data), width: () => process.stderr.columns ?? 80, height: () => process.stderr.rows ?? 24 }),
 }