Long log viewers
Reuse sparse row anchors and page caches while jumping through fixed-column buffers.
Terminal text layout for serious buffers
Long terminal text should not rewrap from scratch just to draw one viewport.
`pretext-tui` is a host-neutral TypeScript kernel for TUI, CLI, log, transcript, editor-pane, and dashboard hosts. Prepare text once, reflow by terminal columns, and materialize only the rows your host needs.
- Current release
- 0.1.0
- Runtime target
- Terminal cells
- Public package
- pretext-tui
The pressure point
Modern terminal apps are text-heavy again.
Agents, build logs, patches, transcripts, markdown notes, stack traces, CJK, emoji, tabs, ANSI style, and links all end up in terminal panes. The naive path wraps the whole string on resize or scroll. `pretext-tui` gives hosts a stable `prepare -> layout -> range -> materialize` contract instead.
Pipeline
Ranges first. Strings last.
Store width-independent prepared data, keep fixed-column caches separate, and turn only requested ranges into display text.
-
01
Prepare
Normalize visible terminal source, analyze Unicode boundaries, and keep prepared state independent from the current viewport width.
-
02
Layout
Measure in exact integer terminal cells. Tabs stay structural and width-dependent caches stay fixed-column.
-
03
Range
Walk line ranges, source offsets, search hits, selections, and generic sidecar ranges without eagerly rendering strings.
-
04
Materialize
Convert only visible rows or extracted ranges into text, leaving rendering, focus, input, and clipboard behavior to the host.
Where it fits
A text kernel under your terminal UI.
Agent transcripts
Keep sessions, patches, markdown-ish prose, tables, and command output in one source-aware wrapping path.
Editor panes
Map source offsets to terminal rows and columns for host-owned search, diagnostics, and selection UI.
Rich ANSI views
Use the opt-in sidecar for SGR style spans and OSC8 link metadata while keeping unsafe controls out of layout.
Install
Published on npm. The core seven APIs are stable as of 0.1.0.
The root package exports the terminal API. `pretext-tui/terminal` is the explicit alias, and `pretext-tui/terminal-rich-inline` is the opt-in rich metadata sidecar.
npm install pretext-tuiCore API
A small contract for large terminal text.
`prepareTerminal()` performs the reusable analysis pass. Layout APIs operate in terminal columns. Materializers turn only requested ranges into renderable text.
- Terminal cells instead of browser pixels
- UTF-16 source offsets over sanitized visible source
- Opaque runtime handles for indexes and caches
- Host-owned rendering, input, panes, scrolling, and clipboard
import {
layoutTerminal,
materializeTerminalLineRange,
prepareTerminal,
walkTerminalLineRanges,
} from 'pretext-tui'
const prepared = prepareTerminal('hello world\nstatus ok', {
whiteSpace: 'pre-wrap',
tabSize: 4,
})
const stats = layoutTerminal(prepared, { columns: 40 })
walkTerminalLineRanges(prepared, { columns: 40 }, line => {
const row = materializeTerminalLineRange(prepared, line)
console.log(row.text)
})Interactive feel
Try the layout contract in an embedded TUI.
This is a small host-side playground for the website: change columns, page through a transcript, search source text, and click a rendered row to inspect the source range behind it. The package remains terminal-first; browser rendering is only this site's demo host.
- Prepared once
- 0 code units
- Total rows
- 0
- Materialized
- 0 rows
- Search hits
- 0
Selected row
Click a terminal row to inspect its source range.
Evidence-safe claims
Performance language stays reproducible.
The repository keeps dynamic benchmark numbers in JSON evidence reports, not in marketing prose. Public copy can cite report ids and workload ids, while raw samples, runtime metadata, comparator caveats, and source hashes stay in the report.
Read evidence docsBoundary
What the package owns.
- Text preparation
- Terminal-cell wrapping
- Line ranges and source offsets
- Selection and extraction data
- Rich inline metadata sidecar
- Fixed-column paging primitives
Host-owned
What stays above it.
- Rendering and styling
- Input and keybindings
- Panes, focus, and scrolling
- Clipboard and copy formatting
- Persistence and file operations
- Command execution and product behavior
FAQ
Quick answers.
What is pretext-tui?
pretext-tui is a host-neutral terminal-cell text layout core for long terminal text, written in TypeScript. It prepares text once, lays out rows as ranges over integer terminal cells, and materializes only the rows a host viewport needs.
Is pretext-tui a TUI framework, renderer, or terminal emulator?
No. It is the text layout engine you put under one. Host applications own rendering, input, panes, scrolling, clipboard, and product behavior; the package owns layout data such as rows, ranges, source offsets, and rich inline metadata.
How does pretext-tui handle very long terminal buffers?
Prepared text is analyzed once and reused across relayouts. Fixed-column sparse row anchors and page caches let a viewport jump deep into a long transcript and fetch only the requested rows instead of rewrapping the whole buffer. Performance language stays tied to reproducible evidence reports in the repository.
Does pretext-tui support ANSI colors, styles, and hyperlinks?
Plain core input rejects raw terminal controls. An opt-in rich sidecar extracts inline SGR style spans and OSC8 links with conservative policy-bound defaults: unsupported control sequences are rejected or sanitized, diagnostics are redacted by default, and ANSI reconstruction is explicit opt-in.
How does pretext-tui handle CJK, emoji, and Unicode width?
Width is integer terminal cells computed through deterministic terminal width profiles covering CJK, emoji, combining marks, tabs, zero-width breaks, and soft hyphens. Source offsets are UTF-16 over sanitized visible text, and ranges are grapheme-safe.
Website deployment
Ready for Cloudflare Pages.
The site is static HTML, CSS, and JavaScript. Use the `website` directory as the Pages output directory. No build command is required.