termvision

Semantic reconstruction and reflow for rendered terminal grids.

termvision takes a terminal screen that has already been rendered into cells, detects common semantic structures, and produces a new grid for a different viewport size without re-running the original TUI process.

Status: early 0.1.x package. The public API is intentionally small while the detection heuristics are still being validated.

Why

Terminal sharing and multiplexing tools often fall back to the smallest connected viewport. Re-rendering a full-screen TUI at a different size is hard because the byte stream has already been baked for the source PTY. termvision works from the rendered grid instead: it treats borders, prompts, status bars, progress bars, tree output, and columnar output as layout signals.

Install

pnpm add termvision

termvision is ESM-only and targets Node.js 20 or newer.

Usage

import { gridFromText, gridToText, reflow } from "termvision";

const source = gridFromText(`
┌──────────────────────┐
│ hello world          │
│ from termvision      │
└──────────────────────┘
`);

const result = reflow({
  source,
  target: { cols: 40, rows: 8 },
  confidenceThreshold: 0.6,
});

console.log(result.fallback);   // "none" | "viewport-pan"
console.log(result.confidence); // 0..1
console.log(gridToText(result.grid));

ANSI-colored text can be parsed and rendered back to HTML:

import { gridFromAnsi, gridToHtml } from "termvision";

const grid = gridFromAnsi("\x1b[32mready\x1b[0m");
console.log(gridToHtml(grid));

Current Scope

Implemented:

• Box-drawing rectangle detection for single, double, rounded, and heavy borders.
• Text-grid reflow with top and bottom anchoring.
• Heuristic classification for prompts, status bars, separators, progress bars, tree output, and columnar output.
• Basic ANSI SGR parsing for foreground/background colors and bold text.
• viewport-pan fallback for dense table-like screens where semantic reflow is risky.
• Optional classified-line wide block preservation for code and diff content that should be panned on narrow viewports instead of hard-wrapped.
• Horizontal fill-line projection for separators and rule-filled footer rows, while leaving box/table borders untouched.

Not implemented yet:

• Cursor-aware input field reconstruction.
• Nested layout tree solving beyond simple stacked border regions.
• Full terminal escape sequence emulation in the public API.
• Stable table schema inference.

API Surface

The package exports:

• Grid helpers: createGrid, gridFromText, gridFromAnsi, gridToText, gridToHtml, getCell, setCell, copyRect.
• Reflow: reflow, ReflowOptions, ReflowResult, FallbackMode.
• Detection and rendering internals that are useful for experiments: detectBorders, buildWidgetTree, renderWidgetTree, classifyLines, reflowClassifiedLines, reflowClassifiedLineRecords, resizeHorizontalFillLineCells.
• Types: Grid, Cell, DetectedRect, Widget, WidgetTree, BorderStyle, ClassifiedLine, LineKind, Anchor, ReflowClassifiedLinesOptions, ReflowedLine, ReflowedLineWideBlockKind, WideBlockStrategy, AnsiAttrs.

See docs/API.md for contract details.

Development

pnpm install
pnpm typecheck
pnpm test
pnpm build
pnpm pack:dry

Tooling is centralized through Vite+: pnpm test uses vp test, pnpm demo uses vp dev, and pnpm build uses vp pack backed by tsdown to create the publishable ESM bundle and declarations.

Run the demo:

pnpm demo

Inspect a fixture:

pnpm inspect test/fixtures/asciinema/vim-editor.json 100 30

Documentation

• docs/ARCHITECTURE.md: implementation model and module responsibilities.
• docs/PROJECT_STRUCTURE.md: repository layout and publish/include decisions.
• docs/PUBLISHING.md: release checklist and npm package gates.
• docs/DECISIONS.md: explicit decisions behind gitignore, docs, package contents, and scope.
• docs/API.md: current public API contract.
• CONTRIBUTING.md: local development workflow.
• SECURITY.md: vulnerability reporting policy.

Recording and replay utilities use @aitty/wterm-core for terminal capture; termvision itself does not ship or depend on a local wasm binary.

License

Apache-2.0.