@beamterm/renderer

High-performance WebGL2 terminal renderer achieving sub-millisecond render times through GPU-accelerated instanced rendering. Pure WASM + WebGL2 with zero runtime dependencies.

Features

• Rich text styling — bold, italic, underline, strikethrough with 24-bit color
• Batch updates — all cell changes are collected and uploaded to the GPU in a single pass
• Two font atlas modes — pre-rasterized static atlas or on-demand dynamic atlas with any browser font
• Built-in text selection — linear and block modes with clipboard integration and URL detection
• Responsive — automatic terminal resizing with HiDPI support
• TypeScript definitions included

Requires a browser with WebGL2 and WASM support (any modern browser).

Installation

npm install @beamterm/renderer

Or via CDN:

<script src="https://unpkg.com/@beamterm/renderer@latest/dist/cdn/beamterm.min.js"></script>
<script>
  await Beamterm.init();
  const renderer = new Beamterm.BeamtermRenderer('#terminal');
</script>

Quick Start

import {
  main as init,
  style,
  cell,
  BeamtermRenderer,
} from "@beamterm/renderer";

await init();

// Create renderer — uses the embedded static font atlas by default
const renderer = new BeamtermRenderer("#terminal");

// Or use a dynamic atlas that rasterizes any browser font on demand
// const renderer = BeamtermRenderer.withDynamicAtlas('#terminal', ['JetBrains Mono', 'Fira Code'], 16.0);

const { cols, rows } = renderer.terminalSize();
console.log(`Terminal: ${cols}x${rows} cells`);

const batch = renderer.batch();

batch.clear(0x1a1b26);
batch.text(
  2,
  1,
  "Hello, Beamterm!",
  style().bold().underline().fg(0x7aa2f7).bg(0x1a1b26),
);
batch.cell(0, 0, cell("🚀", style().fg(0xffffff)));
batch.fill(1, 3, 18, 1, cell("─", style().fg(0x565f89).bg(0x1a1b26)));

renderer.render();

API Reference

BeamtermRenderer

The main renderer class. Manages the WebGL2 context and rendering pipeline.

Constructors

Rendering

Font Switching

Swap the font atlas at runtime. Existing cell content is preserved and translated to the new atlas.

Selection & Mouse

Batch

Buffers cell updates for efficient GPU upload. Create one per frame via renderer.batch().

All changes are automatically uploaded when renderer.render() is called.

CellStyle

Fluent builder for text styling. Create one with style().

const heading = style().bold().fg(0x7aa2f7).bg(0x1a1b26);
const warning = style().bold().italic().fg(0xe0af68);

CellQuery

Describes a rectangular or linear region of cells for text extraction.

const query = new CellQuery(SelectionMode.Linear)
  .start(0, 2)
  .end(40, 5)
  .trimTrailingWhitespace(true);

const text = renderer.getText(query);

ModifierKeys

Modifier key flags for enableSelectionWithOptions().

// Require Shift+Click to start selection
renderer.enableSelectionWithOptions(
  SelectionMode.Linear,
  true,
  ModifierKeys.SHIFT,
);

// Require Ctrl+Shift+Click
renderer.enableSelectionWithOptions(
  SelectionMode.Block,
  true,
  ModifierKeys.CONTROL.or(ModifierKeys.SHIFT),
);

Combine with .or(): ModifierKeys.SHIFT.or(ModifierKeys.ALT)

Enums

SelectionMode — Linear (text flow, like a terminal) or Block (rectangular, like a text editor).

MouseEventType — MouseDown, MouseUp, MouseMove, Click, MouseEnter, MouseLeave.

Helper Functions

Color Format

Colors are 24-bit RGB values: 0xRRGGBB.

const white = 0xffffff;
const red = 0xff0000;
const tokyoBg = 0x1a1b26;

Common Patterns

Animation Loop

function animate() {
  const batch = renderer.batch();
  batch.clear(0x1a1b26);
  batch.text(0, 0, `Frame: ${Date.now()}`, style().fg(0xc0caf5));
  renderer.render();
  requestAnimationFrame(animate);
}

Responsive Terminal

window.addEventListener("resize", () => {
  renderer.resize(window.innerWidth, window.innerHeight);
  redrawTerminal();
});

URL Detection

renderer.setMouseHandler((event) => {
  if (event.event_type === MouseEventType.Click) {
    const match = renderer.findUrlAt(event.col, event.row);
    if (match) window.open(match.url, "_blank");
  }
});

Examples

See the examples/ directory:

• Batch API Demo — interactive demonstration of all API methods
• Selection Demo — text selection, URL detection, modifier keys
• Vite + TypeScript — modern dev setup with HMR and runtime font switching
• Webpack — classic bundler setup

Performance Tips

• Prefer batch.text() over multiple batch.cell() calls for strings with uniform styling
• Use batch.fill() for large rectangular regions
• Batch all updates within a single renderer.batch() / renderer.render() cycle
• Reuse CellStyle objects when possible

License

MIT — see LICENSE for details.

Links

• GitHub Repository
• Live Examples
• Issues