✨ add @clayterm/virtualizer v1 (PRs 1–3)

Implement the virtualizer package for viewport virtualization over
large terminal text output. This covers PRs 1–3 of the implementation
plan:

- PR 1: Export createDisplayWidth from renderer (WASM per-codepoint
  wcwidth, R.WIDTH.* tests)
- PR 2: Virtualizer core — appendLine, resolveViewport, ring buffer,
  ANSI scanner, wrap walker, getLineDisplayWidth (~66 tests)
- PR 3: scrollBy + scrollToFraction with all deferred scroll-dependent
  tests (~92 tests total)

resize() still throws "not implemented" — deferred to PR 4.

Author: taras

mod.ts

@@ -3,3 +3,4 @@ export * from "./term.ts";
 export * from "./input.ts";
 export * from "./settings.ts";
 export * from "./termcodes.ts";
+export { createDisplayWidth } from "./width.ts";

src/clayterm.c

@@ -7,6 +7,7 @@
  *   output         — pointer to output byte buffer
  *   length         — length of output byte buffer
  *   measure        — Clay text measurement callback
+ *   display_width  — per-codepoint wcwidth sum over a UTF-8 string
  */
 
 #include "clayterm.h"
@@ -656,3 +657,32 @@ void measure(int ret, int txt) {
   dims[0] = (float)w;
   dims[1] = 1.0f;
 }
+
+/* ── display_width — per-codepoint wcwidth sum ───────────────────── */
+
+/**
+ * Compute the display width of a UTF-8 string by summing max(0, wcwidth(cp))
+ * for each Unicode codepoint. No ANSI skipping — pure per-codepoint sum.
+ *
+ * @param str  Pointer to a UTF-8 encoded string (not necessarily null-terminated).
+ * @param len  Byte length of the string.
+ * @return     Total display width (non-negative).
+ */
+int display_width(const char *str, int len) {
+  int w = 0;
+  const char *p = str;
+  int rem = len;
+  while (rem > 0) {
+    uint32_t cp;
+    int n = utf8_decode(&cp, p);
+    if (n <= 0) {
+      n = 1;
+    }
+    int cw = wcwidth(cp);
+    if (cw > 0)
+      w += cw;
+    p += n;
+    rem -= n;
+  }
+  return w;
+}

test/width.test.ts

@@ -0,0 +1,47 @@
+import { beforeEach, describe, expect, it } from "./suite.ts";
+import { createDisplayWidth } from "../width.ts";
+
+describe("createDisplayWidth", () => {
+  let displayWidth: (text: string) => number;
+
+  beforeEach(async () => {
+    displayWidth = await createDisplayWidth();
+  });
+
+  it("R.WIDTH.ascii — ASCII characters each have width 1", () => {
+    expect(displayWidth("hello")).toBe(5);
+  });
+
+  it("R.WIDTH.cjk — CJK characters each have width 2", () => {
+    expect(displayWidth("文字")).toBe(4);
+  });
+
+  it("R.WIDTH.combining — combining marks have width 0", () => {
+    expect(displayWidth("e\u0301")).toBe(1);
+  });
+
+  it("R.WIDTH.zwj-emoji — ZWJ emoji sequence uses per-codepoint wcwidth", () => {
+    expect(displayWidth("👨‍👩‍👧‍👦")).toBe(8);
+  });
+
+  it("R.WIDTH.additivity — width of concatenation equals sum of widths", () => {
+    let pairs: [string, string][] = [
+      ["hello", "world"],
+      ["文", "字"],
+      ["abc", "文字"],
+      ["e\u0301", "hello"],
+    ];
+    for (let [a, b] of pairs) {
+      expect(displayWidth(a + b)).toBe(displayWidth(a) + displayWidth(b));
+    }
+  });
+
+  it("R.WIDTH.empty-string — empty string has width 0", () => {
+    expect(displayWidth("")).toBe(0);
+  });
+
+  it("R.WIDTH.zero-width — zero-width characters have width 0", () => {
+    expect(displayWidth("\u200B")).toBe(0);
+    expect(displayWidth("\u200D")).toBe(0);
+  });
+});

virtualizer/ansi-scanner.ts

@@ -0,0 +1,48 @@
+/**
+ * If text[pos] starts an ESC-initiated CSI or OSC sequence, return the
+ * byte length of the full sequence (inclusive). Otherwise return 0.
+ *
+ * CSI: ESC [ ... <final byte 0x40–0x7E>
+ * OSC: ESC ] ... <BEL (0x07) or ST (ESC \)>
+ */
+export function skipAnsiSequence(text: string, pos: number): number {
+  if (text.charCodeAt(pos) !== 0x1b) return 0;
+  if (pos + 1 >= text.length) return 0;
+
+  let next = text.charCodeAt(pos + 1);
+
+  // CSI: ESC [
+  if (next === 0x5b) {
+    let i = pos + 2;
+    while (i < text.length) {
+      let ch = text.charCodeAt(i);
+      if (ch >= 0x40 && ch <= 0x7e) {
+        return i - pos + 1;
+      }
+      i++;
+    }
+    // Unterminated CSI — consume what we have
+    return i - pos;
+  }
+
+  // OSC: ESC ]
+  if (next === 0x5d) {
+    let i = pos + 2;
+    while (i < text.length) {
+      let ch = text.charCodeAt(i);
+      // BEL terminator
+      if (ch === 0x07) {
+        return i - pos + 1;
+      }
+      // ST terminator: ESC backslash
+      if (ch === 0x1b && i + 1 < text.length && text.charCodeAt(i + 1) === 0x5c) {
+        return i - pos + 2;
+      }
+      i++;
+    }
+    // Unterminated OSC — consume what we have
+    return i - pos;
+  }
+
+  return 0;
+}

virtualizer/deno.json

@@ -0,0 +1,9 @@
+{
+  "name": "@clayterm/virtualizer",
+  "license": "MIT",
+  "exports": { ".": "./mod.ts" },
+  "imports": {
+    "@std/testing": "jsr:@std/testing@1",
+    "@std/expect": "jsr:@std/expect@1"
+  }
+}

virtualizer/deno.lock

@@ -0,0 +1,6 @@
+export { Virtualizer } from "./virtualizer.ts";
+export type {
+  ResolvedViewport,
+  ViewportEntry,
+  VirtualizerOptions,
+} from "./types.ts";

virtualizer/mod.ts

@@ -0,0 +1,68 @@
+export interface LineEntry {
+  text: string;
+  displayWidth: number;
+  lineIndex: number;
+}
+
+export interface AppendResult {
+  lineIndex: number;
+  evicted?: { displayWidth: number; lineIndex: number };
+}
+
+export class RingBuffer {
+  private _items: (LineEntry | undefined)[];
+  private _capacity: number;
+  private _head: number;
+  private _count: number;
+  private _nextIndex: number;
+
+  constructor(capacity: number) {
+    this._capacity = capacity;
+    this._items = new Array(capacity);
+    this._head = 0;
+    this._count = 0;
+    this._nextIndex = 0;
+  }
+
+  get capacity(): number {
+    return this._capacity;
+  }
+
+  get lineCount(): number {
+    return this._count;
+  }
+
+  get baseIndex(): number {
+    if (this._count === 0) return this._nextIndex;
+    return this._items[this._head]!.lineIndex;
+  }
+
+  append(text: string, displayWidth: number): AppendResult {
+    let lineIndex = this._nextIndex++;
+    let evicted: { displayWidth: number; lineIndex: number } | undefined;
+
+    if (this._count === this._capacity) {
+      let evictedEntry = this._items[this._head]!;
+      evicted = {
+        displayWidth: evictedEntry.displayWidth,
+        lineIndex: evictedEntry.lineIndex,
+      };
+      this._head = (this._head + 1) % this._capacity;
+      this._count--;
+    }
+
+    let slot = (this._head + this._count) % this._capacity;
+    this._items[slot] = { text, displayWidth, lineIndex };
+    this._count++;
+
+    return { lineIndex, evicted };
+  }
+
+  get(lineIndex: number): LineEntry | undefined {
+    if (this._count === 0) return undefined;
+    let base = this._items[this._head]!.lineIndex;
+    let offset = lineIndex - base;
+    if (offset < 0 || offset >= this._count) return undefined;
+    return this._items[(this._head + offset) % this._capacity];
+  }
+}

virtualizer/ring-buffer.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "./suite.ts";
+import { Virtualizer } from "../mod.ts";
+
+function charMeasure(text: string): number {
+  let cp = text.codePointAt(0)!;
+  if (cp >= 0x4e00 && cp <= 0x9fff) return 2;
+  if (cp < 0x20) return 0;
+  return 1;
+}
+
+describe("G.ANSI — ANSI golden fixtures", () => {
+  it("G.ANSI.simple-sgr — SGR sequence does not add sub-rows", () => {
+    let v = new Virtualizer({ measureWidth: charMeasure, columns: 80, rows: 24 });
+    let idx = v.appendLine("\x1b[31mred\x1b[0m");
+    let vp = v.resolveViewport();
+    expect(vp.entries[0].totalSubRows).toBe(1);
+    expect(v.getLineDisplayWidth(idx)).toBe(3);
+  });
+
+  it("G.ANSI.sgr-at-wrap-boundary — wrap occurs at visible char boundary, not inside SGR", () => {
+    let v = new Virtualizer({ measureWidth: charMeasure, columns: 5, rows: 24 });
+    v.appendLine("abcde\x1b[31mfghij");
+    let vp = v.resolveViewport();
+    let entry = vp.entries[0];
+    // Visible: "abcde" (5) then "fghij" (5). CSI "\x1b[31m" at indices 5–9 (5 chars).
+    // Wrap after 5 visible chars → wrap point at index 10 (start of 'f', after CSI)
+    expect(entry.wrapPoints).toEqual([10]);
+    let slices = [entry.text.slice(0, 10), entry.text.slice(10)];
+    expect(slices[0]).toBe("abcde\x1b[31m");
+    expect(slices[1]).toBe("fghij");
+  });
+
+  it("G.ANSI.osc-with-bel — OSC with BEL terminator", () => {
+    let v = new Virtualizer({ measureWidth: charMeasure, columns: 80, rows: 24 });
+    let idx = v.appendLine("\x1b]0;title\x07visible");
+    let vp = v.resolveViewport();
+    expect(vp.entries[0].totalSubRows).toBe(1);
+    expect(v.getLineDisplayWidth(idx)).toBe(7);
+  });
+
+  it("G.ANSI.osc-with-st — OSC with ST terminator", () => {
+    let v = new Virtualizer({ measureWidth: charMeasure, columns: 80, rows: 24 });
+    let idx = v.appendLine("\x1b]0;title\x1b\\visible");
+    let vp = v.resolveViewport();
+    expect(vp.entries[0].totalSubRows).toBe(1);
+    expect(v.getLineDisplayWidth(idx)).toBe(7);
+  });
+
+  it("G.ANSI.nested-csi-in-wrapped-line — multiple CSI in wrapping line, no wrap inside CSI", () => {
+    let v = new Virtualizer({ measureWidth: charMeasure, columns: 3, rows: 24 });
+    // "a\x1b[1mb\x1b[0mc\x1b[32md\x1b[0me" — 5 visible chars: a, b, c, d, e
+    v.appendLine("a\x1b[1mb\x1b[0mc\x1b[32md\x1b[0me");
+    let vp = v.resolveViewport();
+    let entry = vp.entries[0];
+    // 5 visible chars at columns 3 → 2 sub-rows
+    expect(entry.totalSubRows).toBe(2);
+    // No wrap point should fall inside any CSI sequence
+    let text = entry.text;
+    for (let wp of entry.wrapPoints) {
+      expect(text.charCodeAt(wp)).not.toBe(0x5b); // not '['
+      // wp should not be between ESC and final byte
+      if (wp > 0 && text.charCodeAt(wp - 1) === 0x1b) {
+        // wp right after ESC — that's inside the sequence
+        expect(true).toBe(false);
+      }
+    }
+  });
+});