Add @clayterm/virtualizer v1

[taras]

Demo

Summary

• Add createDisplayWidth() async WASM factory to @clayterm/clayterm — returns a synchronous per-codepoint wcwidth string-width function
• Add @clayterm/virtualizer package — viewport virtualization over large terminal text output with ring buffer storage, ANSI-aware line wrapping, scroll position tracking, and viewport resolution
• Add current-state specification document for the Clayterm rendering contract

Virtualizer API

class Virtualizer {
  constructor(options: { measureWidth, columns, rows, maxLines? })
  appendLine(text: string): number
  resize(columns: number, rows: number): void
  scrollBy(deltaVisualRows: number): void
  scrollToFraction(fraction: number): void
  resolveViewport(): ResolvedViewport
}

Key design decisions:

• ANSI handling is internal — the virtualizer owns CSI/OSC skipping; the injected measureWidth only sees visible codepoints
• Exact wrapping for visible lines, approximate estimation for scrollbar — resolveViewport() computes exact wrap points for viewport entries while totalEstimatedVisualRows uses ceil(displayWidth/columns) for O(1) append
• Stable monotonic line identity — lineIndex values are never reused, even after FIFO eviction
• Anchor-based scroll position — scroll state is (anchorLineIndex, anchorSubRow) with bottom-follow behavior

Test coverage

125 test steps across 18 suites:

• Core invariants, ANSI handling, wrapping golden fixtures
• Scroll, resize, eviction conformance tests
• Exactness vs approximation structural tests
• Property-based tests with deterministic PRNG
• 7 validation-gate benchmarks (informational)

Test plan

• deno test in virtualizer/ — 125 steps pass
• deno test in root — renderer width tests pass
• Verify CI passes

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/clayterm@11

commit: 80324f4