Blecsd Tui

blECSd Core Library Skill

blECSd is a modern, high-performance terminal UI library built on TypeScript and ECS (Entity Component System) architecture using bitecs. It is a ground-up rewrite of the original blessed node library, NOT backwards-compatible. Version: 0.7.0. Node.js >= 22.0.0.

Hard Rules (Non-Negotiable)

1. Purely Functional, No OOP

BANNED: class, this, new (except Map/Set/Error), prototype manipulation, inheritance.

// WRONG
class MyWidget { private x: number; constructor(x: number) { this.x = x; } }

// CORRECT
interface MyWidget { readonly x: number; }
function createMyWidget(x: number): MyWidget { return { x }; }

2. No Direct bitecs Imports

Only three files may import from 'bitecs': src/core/ecs.ts, src/core/world.ts, src/core/types.ts. Everything else imports from 'blecsd' (external) or '../core/ecs' (internal).

3. Library-First Design

Users control their own world and update loop. All functions take world as a parameter. Never own a global world.

4. Input Priority

INPUT phase is always first in the update loop. Cannot be reordered. All pending input is processed every frame.

5. Early Returns and Guard Clauses

Handle errors first, happy path last. Max nesting 2-3 levels.

6. File Size Limits

• Component files: max 200 lines
• Widget files: max 300 lines per sub-file
• All other source files: max 500 lines

7. Strict TypeScript

• All functions have explicit return types
• No any (use unknown + type guards)
• Prefer readonly arrays and objects
• Branded types for IDs

Architecture

Update Loop Phases (in order)

1. INPUT (always first, immutable position) — keyboard/mouse 2. EARLY_UPDATE — pre-processing, state transitions 3. UPDATE — main game/app logic 4. LATE_UPDATE — post-processing, cleanup 5. ANIMATION — physics, springs, tweens, momentum scrolling 6. LAYOUT — positions, sizes, constraints 7. RENDER — write to screen buffer 8. POST_RENDER — cleanup, telemetry

Where Does Logic Go?

Rule: Components = data only. Systems = logic. Never put business logic in component files.

API Surface (Three Tiers)

Tier 2: Subpath Imports (Recommended)

Full module access — the default for all applications:

import { position, content, scroll } from 'blecsd/components';
import { animationSystem, collisionSystem } from 'blecsd/systems';
import { box, tabs, modal, flexbox } from 'blecsd/widgets';
import { createDoubleBuffer, createProgram } from 'blecsd/terminal';
import { BoxConfigSchema } from 'blecsd/schemas';
import { renderText, wrapText } from 'blecsd/utils';
import { enableDebugOverlay } from 'blecsd/debug';
import { queueKeyEvent } from 'blecsd/input';
import { createViState, processViKey } from 'blecsd/input';

Tier 1: Curated Top-Level ('blecsd')

~80 exports for small scripts and quick prototypes. See API Reference.

Tier 3: Namespace Objects (Preferred for Complex Apps)

Frozen plain objects grouping related functions:

import { position, content, dimensions, border } from 'blecsd/components';

position.set(world, eid, 10, 5);
content.set(world, eid, 'Hello');
dimensions.set(world, eid, 40, 10);
border.set(world, eid, { type: 'line' });

Quick Start with createApp()

The recommended way to bootstrap a blECSd application (added in v0.7.0):

import { createApp } from 'blecsd';
import { createBoxEntity, createTextEntity } from 'blecsd/core';

const app = await createApp({ fullscreen: true, fps: 30 });

// app.world — ECS world
// app.program — terminal input handling
// app.cols, app.rows — terminal dimensions
// app.render() — run one frame
// app.shutdown() — clean exit
// app.start() — start render loop (returns stop fn)

const panel = createBoxEntity(app.world, {
  x: 2, y: 1, width: 40, height: 12,
  border: { type: 1, top: true, bottom: true, left: true, right: true },
});

createTextEntity(app.world, {
  x: 4, y: 2, text: 'My Dashboard', parent: panel,
});

app.program.on('key', (e) => { if (e.name === 'q') app.shutdown(); });
app.start();

createApp Options

Other DX Helpers

Reference Documents

Detailed API surfaces are split into reference files to keep this skill focused:

• [API Surface Reference](./ref/api-surface.md) — Full Tier 1 exports, component namespaces, widget namespaces, systems list
• [Terminal & Server Reference](./ref/terminal-server.md) — Terminal control, server-side (SSH/Telnet/WebSocket), process utils, custom streams, vi mode
• [Graphics & Media Reference](./ref/graphics-media.md) — Graphics manager, braille canvas, vector-to-pixel bridge, image widgets

Common Patterns

Using the Scheduler

import { createWorld, createScheduler, PhaseType } from 'blecsd';

const world = createWorld();
const scheduler = createScheduler();

scheduler.register(inputSystem, PhaseType.INPUT);
scheduler.register(layoutSystem, PhaseType.LAYOUT);
scheduler.register(renderSystem, PhaseType.RENDER);
scheduler.register(outputSystem, PhaseType.POST_RENDER);

function tick() {
  scheduler.run(world);
  requestAnimationFrame(tick);
}
tick();

Custom System

import { defineQuery, defineSystem, hasComponent } from 'blecsd';
import { Position, Velocity } from 'blecsd/components';

const movingQuery = defineQuery([Position, Velocity]);

function createMovementSystem() {
  return defineSystem((world) => {
    for (const eid of movingQuery(world)) {
      Position.x[eid] += Velocity.x[eid];
      Position.y[eid] += Velocity.y[eid];
    }
    return world;
  });
}

Widget API Pattern

import { createBox, setBoxContent, isBox } from 'blecsd/widgets';

const box = createBox(world, {
  position: { x: 0, y: 0 },
  dimensions: { width: '100%', height: '100%' },
  border: { type: 'line', fg: 0x00ff00 },
  padding: { top: 1, left: 2 },
  content: 'Initial content',
});

setBoxContent(world, box, 'Updated content');
if (isBox(world, box)) { /* ... */ }

Keyboard Shortcuts

Global: Tab (focus next), Shift+Tab (focus prev), Escape (blur). Lists: Up/k, Down/j, Home/g, End/G, PageUp/Down, Enter (select), / (search). Text input: Ctrl+A (start), Ctrl+E (end), Ctrl+U (delete to start), Ctrl+K (delete to end), Ctrl+W (delete word).

Error Handling

import { ok, err, isOk, isErr, map } from 'blecsd/errors';

function parseConfig(raw: unknown): Result<Config, ValidationError> {
  const result = ConfigSchema.safeParse(raw);
  if (!result.success) return err(createValidationError(result.error));
  return ok(result.data);
}

Error categories: validation, terminal, system, entity, component, input, render, config, internal.

Testing

import { describe, it, expect } from 'vitest';
import { createWorld, addEntity, addComponent, hasComponent } from 'blecsd';

describe('movement system', () => {
  it('updates position from velocity', () => {
    const world = createWorld();
    const eid = addEntity(world);
    addComponent(world, eid, Position);
    addComponent(world, eid, Velocity);
    Position.x[eid] = 0;
    Velocity.x[eid] = 5;

    movementSystem(world);

    expect(Position.x[eid]).toBe(5);
  });
});

⚠️ Critical: renderSystem Does NOT Render Text Content

The base renderSystem only renders borders and backgrounds. The renderContent() function is a no-op placeholder (see src/systems/renderSystem.ts:341). This means:

• setContent(world, eid, "text") stores data but nothing appears on screen
• createTextEntity(world, { text: "Hello" }) creates an invisible text entity

All official examples use raw ANSI rendering via writeRaw() from blecsd/systems. For TUI apps that need visible text, use:

import { writeRaw, cursorHome, enterAlternateScreen, hideCursor, setOutputStream } from "blecsd/systems";
import { clearScreen } from "blecsd";

setOutputStream(process.stdout);
enterAlternateScreen();
hideCursor();

// Render with ANSI escape codes
writeRaw(`\x1b[${row};${col}H\x1b[38;2;${r};${g};${b}mHello blECSd!`);

⚠️ Critical: Dev Server Setup for TUI Apps

NEVER use `tsx watch` or `nodemon` for interactive TUI apps. They steal or pipe stdin, breaking process.stdin.setRawMode(true). Symptoms: keypress restarts app, ANSI escape codes echo on screen, arrow keys don't work.

Use this `dev.mjs` pattern instead:

import { spawn } from "node:child_process";
import { watch } from "node:fs";
let child = null, restarting = false;
function start() {
  child = spawn("npx", ["tsx", "src/index.ts"], {
    stdio: "inherit",  // Child gets actual TTY
    env: { ...process.env },
  });
  child.on("exit", (code) => {
    child = null;
    if (restarting) { restarting = false; start(); }
    else process.exit(code || 0);
  });
}
let debounce = null;
watch("src", { recursive: true }, (_, f) => {
  if (!f?.endsWith(".ts") || debounce) return;
  debounce = setTimeout(() => { debounce = null; }, 500);
  if (child) { restarting = true; child.kill("SIGTERM"); } else start();
});
start();

{ "scripts": { "dev": "node dev.mjs" } }

⚠️ Critical: Use Entity Factories, Not addEntity()

addEntity(world) creates a bare entity with zero components — no Renderable, no Position, no Dimensions. It will be completely invisible with no error. Always use createBoxEntity(), createTextEntity(), or other factories from blecsd/core.

Common Anti-Patterns

1. Using classes — All code must be functional. 2. Importing from bitecs directly — Always import from blecsd or ../core/ecs. 3. Putting logic in component files — Components are data only. 4. Deep nesting — Use guard clauses and early returns. 5. Using `any` — Use unknown with type guards. 6. Missing Zod validation at boundaries — All config objects need Zod schemas. 7. Forgetting barrel exports — Update the module's index.ts when adding exports. 8. Processing input outside INPUT phase — All input goes through inputSystem. 9. Using addEntity() for UI elements — Use createBoxEntity() etc. Bare entities lack Renderable and are invisible. 10. Using tsx watch for TUI apps — Use dev.mjs with stdio: "inherit" spawn. See warning above. 11. Expecting renderSystem to show text — It only renders borders/backgrounds. Use writeRaw() for text.

Module Ownership (Ambiguous Names)

Development Commands

pnpm install          # Install dependencies
pnpm dev              # Development mode
pnpm build            # Build (catches issues tests miss)
pnpm test             # Run tests
pnpm test:watch       # Watch mode
pnpm lint             # Biome linter
pnpm lint:fix         # Auto-fix lint
pnpm typecheck        # TypeScript type check

Performance Tips

• Cache queries: const myQuery = defineQuery([Position, Velocity]) once, reuse everywhere.
• Batch component reads in one pass per entity.
• Use dirty tracking: only re-render changed entities.
• Virtualize large lists with createVirtualizedList.
• Use double buffering (createDoubleBuffer) for flicker-free rendering.
• Avoid allocations in hot loops.
• Use frameBudgetSystem to monitor frame times.

Add-on Packages

blECSd API Surface Reference

Tier 1: Top-Level Exports ('blecsd')

ECS Core

• createWorld(), destroyWorld(world)
• addEntity(world), removeEntity(world, eid)
• addComponent(world, eid, Component), hasComponent(world, Component, eid)
• Types: Entity, World, System

App Helpers (DX) — New in v0.7.0

• createApp(options?) — Full application bootstrap (world + pipeline + input + shutdown)
• createRenderPipeline(stream, options?) — Wire render pipeline manually
• onShutdown(world, options?) — Register SIGINT/SIGTERM handlers
• renderToString(world, cols, rows) — Render frame to string
• Types: App, AppOptions, RenderPipeline, RenderPipelineOptions, ShutdownOptions

Entity Factories

• createScreenEntity(world, config) — Root screen entity
• createBoxEntity(world, config) — Box/container (supports title option as of v0.7.0)
• createTextEntity(world, config) — Text display
• createButtonEntity(world, config) — Button
• createCheckboxEntity(world, config) — Checkbox
• createInputEntity(world, config) — Text input
• createSelectEntity(world, config) — Dropdown select
• createListEntity(world, config) — List

Systems

• inputSystem(world) — Process keyboard/mouse
• layoutSystem(world) — Calculate layout
• renderSystem(world) — Render to buffer
• outputSystem(world) — Write buffer to terminal
• animationSystem(world) — Update animations
• focusSystem(world) — Manage focus
• cleanup(), clearScreen()

Component Helpers

• getText(world, eid), setText(world, eid, text)
• getPosition(world, eid), setPosition(world, eid, x, y)
• getDimensions(world, eid), setDimensions(world, eid, w, h)
• setZIndex(world, eid, z), getZIndex(world, eid), normalizeZIndices(world)
• toggle(world, eid) — Toggle visibility
• scrollByLines(world, eid, delta), scrollToTop/Bottom/Line(world, eid, ...)
• focusNext(world), focusPrev(world)
• prepend(world, parentEid, childEid)
• hitTest(world, x, y)
• Position, Velocity, getVelocity(world, eid), setVelocity(world, eid, vx, vy)

Terminal I/O

• enableInput/disableInput(world), enableKeys/disableKeys(world), enableMouse/disableMouse(world)
• stripAnsi(str), createDoubleBuffer(w, h), getBackBuffer(db)
• getCell(buf, x, y), setCell(buf, x, y, cell), clearBuffer(buf), fillRect(...)
• createDirtyTracker(cols, rows) — Dirty tracking for render pipeline
• LogLevel, parseKeyBuffer(buf), isMouseBuffer(buf), parseMouseSequence(buf)
• Types: KeyEvent, CellBuffer, Cell, KeyHandler, MouseHandler, TerminalCapabilities, CursorShape

Schemas

• BoxConfigSchema, PositionValueSchema, TextConfigSchema

Utilities

• renderText(text, options), wrapText(text, width)
• getLine(rope, n), getLines(rope), getStats(rope)
• createCellBuffer(w, h)

Types

• DimensionValue, BoxConfig, CleanupCallback, HitTestResult, PositionValue, TextConfig, Unsubscribe, DirtyRect

---

Component Namespaces (blecsd/components)

Each is a frozen object of pure functions. 44 namespaces total:

---

Widget Namespaces (blecsd/widgets)

63 widget namespaces. All follow createXxx(world, config) → entity ID pattern:

---

Systems (blecsd/systems)

---

Other Subpath Modules

Graphics & Media Reference

Unified Graphics Backend (v0.5.0+)

Auto-detect and use the best terminal graphics protocol:

import {
  createAutoGraphicsManager,
  createGraphicsManager,
  registerBackend,
  detectGraphicsSupport,
  selectBackend,
  refreshBackend,
} from 'blecsd/terminal';  // or 'blecsd/systems' depending on module

Auto-Detection

const gm = createAutoGraphicsManager();
// Detects: Kitty > iTerm2 > Sixel > ANSI > Braille > ASCII

Manual Backend Management

const gm = createGraphicsManager();
registerBackend(gm, kittyBackend);
registerBackend(gm, sixelBackend);
registerBackend(gm, brailleBackend);
selectBackend(gm, 'kitty'); // or let it auto-select

Backend Constants

• KITTY_BACKEND_NAME, ITERM2_BACKEND_NAME, SIXEL_BACKEND_NAME, ANSI_BACKEND_NAME, BRAILLE_BACKEND_NAME

Protocol Constants

• APC_PREFIX, KITTY_ST, OSC_1337_PREFIX, DCS_START, SIXEL_ST

Schemas (Zod)

• GraphicsCapabilitiesSchema, GraphicsManagerConfigSchema, ImageDataSchema, GraphicsRenderOptionsSchema, GraphicsDetectionResultSchema

---

Braille Canvas (Vector Graphics Primitives)

Create a braille dot-coordinate drawing surface (2x4 dots per cell):

import {
  createBrailleCanvas,
  drawBrailleLine, drawBrailleRect, fillBrailleRect,
  drawBrailleCircle, fillBrailleCircle,
  drawBrailleArc, drawBrailleBezier, drawBrailleEllipse,
  setDot, clearDot, getDot, setCellColor, dotToCell, cellToDot,
  brailleCanvasToString, brailleCanvasToCells,
} from 'blecsd/terminal';  // exact subpath may vary

const canvas = createBrailleCanvas(80, 48); // width x height in dot coordinates
drawBrailleLine(canvas, 0, 0, 79, 47);
drawBrailleCircle(canvas, 40, 24, 15);
fillBrailleRect(canvas, 10, 10, 30, 20);
const output = brailleCanvasToString(canvas);

---

Vector-to-Pixel Bridge

Render braille canvas through the best available graphics backend:

import { renderVector, canvasToPixelBitmap, hasPixelBackend } from 'blecsd/terminal';

// Renders BrailleCanvas through best backend (pixel or braille fallback)
renderVector(graphicsManager, brailleCanvas, { x: 0, y: 0 });

// Convert vector drawings to RGBA pixel bitmap for Kitty/iTerm2/Sixel
const bitmap = canvasToPixelBitmap(brailleCanvas, width, height);

// Check if a pixel-capable backend is active
if (hasPixelBackend(graphicsManager)) { /* use pixel rendering */ }

---

Image Widget Enhancements

Overlay Mode with GraphicsManager

import { createImage, setGraphicsManager } from 'blecsd/widgets';

const img = createImage(world, {
  type: 'overlay',           // Use graphics protocol overlay
  graphicsManager: gm,       // Auto-detected manager
});

// Dynamically assign graphics manager
setGraphicsManager(img, gm);

ANSIImage and OverlayImage Widgets (v0.7.0)

import { ansiImage, overlayImage } from 'blecsd/widgets';

// ANSI-rendered image (works in all terminals)
const ai = ansiImage.createANSIImage(world, config);

// Overlay image (uses Kitty/iTerm2/Sixel protocol)
const oi = overlayImage.createOverlayImage(world, config);

Aspect Ratio & Animation

import { calculateAspectRatioDimensions, setAnimatedImage, startAnimation, stopAnimation, setFrame } from 'blecsd/widgets';

const { width, height } = calculateAspectRatioDimensions(srcW, srcH, targetW, targetH);

setAnimatedImage(eid, gifFrames);
startAnimation(eid);
stopAnimation(eid);
setFrame(eid, 3);

Cache Management

import { clearImageCache, clearAllImageCaches } from 'blecsd/widgets';

clearImageCache(eid);
clearAllImageCaches();

---

Chart Rendering

Braille Gauge Mode

import { gauge } from 'blecsd/widgets';

const g = gauge.createGauge(world, {
  renderMode: 'braille',  // 4x vertical resolution
  gradientStart: '#00ff00',
  gradientEnd: '#ff0000',
});

Chart Utilities

• brailleFillPattern() — Fill pattern for braille charts
• renderBrailleBar() — Single braille bar
• renderBrailleGradientBar() — Gradient-colored braille bar

---

Spring Physics Animation System

import { springSystem } from 'blecsd/systems';

// Presets: bouncy, smooth, snappy
// Config: stiffness, damping, precision

Smooth spring-based animations for UI transitions.

---

Constraint Layout System

import { constraintLayout } from 'blecsd/systems';

// Constraint types: fixed, percentage, min, max, ratio
// Functions: layoutHorizontal, layoutVertical

---

Accessibility Foundation

import { accessibility } from 'blecsd/components';

// ARIA-like roles: button, checkbox, list, textbox, dialog, menu, tree
accessibility.setRole(world, eid, 'button');
accessibility.setLabel(world, eid, 'Submit');
accessibility.announce('Item selected'); // screen reader notification

---

CSS-like Stylesheet System (blecsd/style)

Declarative style rules with selectors by widget tag, class, and entity ID:

import { ... } from 'blecsd/style';

// CSS-like specificity cascading with Zod validation

---

Plugin/Module System

Extensible architecture for bundling components, systems, and lifecycle hooks into reusable modules with dependency resolution and priority ordering.

---

Render Backend Abstraction

Pluggable RenderBackend interface with auto-detection:

• AnsiBackend — Standard ANSI escape sequences with optimized cursor movement
• KittyBackend — Kitty graphics protocol with synchronized output and image encoding

Terminal & Server Reference

Terminal Control Functions

All available from blecsd/terminal or blecsd:

Cursor & Screen

• cursorHome() — Move cursor to 0,0
• clearScreen() — Clear terminal
• enterAlternateScreen() / leaveAlternateScreen() — Alternate buffer
• hideCursor() / showCursor() — Cursor visibility
• moveTo(x, y) — Move cursor to absolute position (0-indexed)
• saveCursorPosition() / restoreCursorPosition() — DEC cursor save/restore
• setCursorShape(shape) — Set cursor to 'block', 'underline', or 'bar'
• bell() — Ring terminal bell
• setWindowTitle(title) — Set terminal window title via OSC 2
• writeRaw(data) — Write raw data to output

Mouse Tracking

• enableMouseTracking(mode) — Enable with 'normal', 'button', or 'any' modes
• disableMouseTracking() — Disable all mouse tracking

Output Modes

• beginSyncOutput() / endSyncOutput() — Synchronized output (DEC 2026) for flicker-free rendering
• enableBracketedPasteMode() / disableBracketedPasteMode() — Bracketed paste
• enableFocusReporting() / disableFocusReporting() — Terminal focus events
• setOutputStream(stream) — Set output target
• setOutputBuffer(db) — Set output double buffer
• setRenderBuffer(tracker, backBuffer) — Set render buffer

Input Parsing

• createProgram(config?) — Create terminal program for input handling
• parseKeyBuffer(buf) — Parse raw key buffer to KeyEvent
• isMouseBuffer(buf) / parseMouseSequence(buf) — Mouse input parsing
• createInputHandler(config) — Input stream handler

Screen Buffers

• createDoubleBuffer(w, h) — Create double buffer for flicker-free output
• getBackBuffer(db) — Get back buffer reference
• clearDirtyRegions(db) — Clear tracked dirty regions
• getCell(buf, x, y) / setCell(buf, x, y, cell) — Cell operations
• clearBuffer(buf) / fillRect(buf, x, y, w, h, cell) — Buffer operations

Colors

• CSS_COLORS — Named CSS colors map
• matchColor(r, g, b) / matchColorCached(r, g, b) — Find nearest 256-color
• nameToColor(name) — CSS color name to RGB

Detection

• Terminal capability detection, color support probing

---

Vi Mode (blecsd/input)

Vi-style navigation for scrollable elements:

import { createViState, createViConfig, processViKey } from 'blecsd/input';

const state = createViState();
const config = createViConfig({ enabled: true, viewportHeight: 40 });

const [action, newState] = processViKey(keyEvent, state, config);
// action.type: 'scroll' | 'jump' | 'page' | 'search' | 'searchNext' | 'enterSearch' | 'exitSearch' | 'searchInput' | 'none'

Modes: 'normal' | 'search' | 'command'

Key bindings (normal mode):

• j/k — Scroll down/up
• h/l — Scroll left/right
• gg/G — Jump to top/bottom
• H/M/L — Jump to high/middle/low of viewport
• Ctrl+d/Ctrl+u — Half page down/up
• Ctrl+f/Ctrl+b — Full page down/up
• / — Enter search mode (forward)
• ? — Enter search mode (backward)
• n/N — Next/prev search match

---

Process Utilities (blecsd/terminal)

Spawn processes with automatic terminal state management:

import { spawn, exec, execSync, readEditor, getDefaultEditor } from 'blecsd/terminal';

// Spawn child process (saves/restores terminal state)
spawn('vim', ['file.txt'], { stdio: 'inherit' });

// Execute command
const result = await exec('ls -la');

// Sync execution
const output = execSync('echo hello');

// Open external editor (respects $EDITOR)
const content = await readEditor({ initialContent: 'Edit me', suffix: '.md' });

// Get default editor
const editor = getDefaultEditor(); // $EDITOR or 'vi'

The processUtils namespace groups these:

import { process as proc } from 'blecsd/terminal';
proc.spawn('ls', ['-la']);

---

Server-Side (SSH, Telnet, WebSocket, TCP)

Unified Server App

import { createServerApp } from 'blecsd/terminal';

const app = createServerApp({
  mode: 'telnet',  // 'tcp' | 'telnet' | 'ssh'
  port: 2323,
  onSession: (session) => {
    writeToSession(session, 'Welcome!\r\n');
  },
});

SSH Server

import { createSSHServer, startSSHServer, stopSSHServer, getSSHClientCount } from 'blecsd/terminal';

const server = createSSHServer({
  port: 2222,
  hostKey: fs.readFileSync('/path/to/host_key'),
  authorizedKeys: [{ key: publicKeyData, username: 'admin' }],
  onSession: (session) => { /* StreamSession */ },
});

startSSHServer(server);

Features: public key auth, password auth, PTY support with window resize, multi-client. Peer dependency: ssh2.

Telnet Server

import { createTelnetServer, startTelnetServer, stopTelnetServer } from 'blecsd/terminal';

const server = createTelnetServer({
  port: 2323,
  onSession: (session) => {
    writeToSession(session, 'Welcome!\r\n');
    session.onData((data) => console.log('Input:', data));
  },
});

startTelnetServer(server);

Protocol support: NAWS, TTYPE, SGA, ECHO.

WebSocket Server (Browser Rendering)

import { createWebServer, startWebServer, stopWebServer, webBroadcast } from 'blecsd/terminal';

const server = createWebServer({
  port: 8080,
  title: 'My Terminal App',
  authToken: 'secret',
});

startWebServer(server);
webBroadcast(server, '\x1b[2J\x1b[HHello from blECSd!');

High-Level serveWeb

import { serveWeb } from 'blecsd/terminal';

const { server, stop } = await serveWeb(world, {
  port: 8080,
  title: 'My Terminal App',
});
// Open http://localhost:8080 in browser

Custom Streams

import { createStreamSession, writeToSession, endSession } from 'blecsd/terminal';

const session = createStreamSession({
  input: readableStream,
  output: writableStream,
  cols: 80,
  rows: 24,
  onData: (data) => { /* handle input */ },
  onResize: (cols, rows) => { /* handle resize */ },
  onClose: () => { /* cleanup */ },
});

writeToSession(session, 'Hello!\r\n');
endSession(session);

---

Terminal Cleanup

import { cleanup, restoreTerminal } from 'blecsd';

// cleanup() disables ALL terminal modes on exit:
// - Mouse tracking
// - Bracketed paste
// - Focus reporting
// - Synchronized output
// - Kitty keyboard protocol
// - Alternate screen
// - Cursor visibility
// - Style reset

OutputState tracks: mouseTracking, mouseMode, syncOutput, bracketedPaste, focusReporting.