fix: stabilize WASM viewport row reads

[ThomasK33]

Summary

Fixes #139.

• Convert the JavaScript scrollback line-count budget to Ghostty's byte-based max_scrollback inside the WASM wrapper.
• Read viewport cells from RenderState cached row data instead of resolving each viewport row independently, keeping rows coherent across Ghostty page boundaries.
• Add a focused regression test using the issue's 130x39, ANSI-heavy append-only output pattern to catch scrollback drops and viewport row merging.

Validation

• bun run build:wasm — passed; patch applies and rebuilt ghostty-vt.wasm locally for tests/build.
• bun test lib/terminal.test.ts -t "keeps viewport coherent" — passed.
• bun run fmt && bun run lint && bun run typecheck && bun test && bun run build — passed.
• git -C ghostty apply --check ../patches/ghostty-wasm-api.patch — passed.
• git diff --check origin/main...HEAD — passed.

Verifier findings

The issue implementation workflow converged after one verifier run with no P1-P3 findings and no non-blocking findings reported.

Dogfooding

The workflow verifier also dogfooded the browser demo with controlled 130x39 terminal output, scrolling through ANSI-heavy rep= / line= rows. It reported coherent bottom/history/back-to-bottom views and scrollbackLength=913.

---

📋 Implementation Plan

Implementation Plan — #139

Goal

Fix GitHub issue #139: getViewport() / getLine() can return corrupted rows when the visible viewport crosses Ghostty's internal page boundaries, and the JS scrollback line-count option is currently handed to Ghostty as a byte budget. Keep the change minimal, reviewable, and limited to #139.

Verified context

• Live issue getViewport() returns corrupted data when viewport spans multiple pages #139 is open, labeled triage:done, bug, and accepted. The issue describes two coupled problems:
  1. renderStateGetViewport in the WASM API patch resolves every viewport row independently with pages.pin(.active), which can become inconsistent across internal page boundaries.
  2. JS scrollback/scrollbackLimit represents lines, but Ghostty Terminal.init(.max_scrollback) expects bytes.
• Related PR fix: use cached row pins for WASM viewport rendering #133 is open and demonstrates a plausible fix: use cached RenderState.row_data row pins and convert scrollback lines to bytes. Its implementation direction is useful, but its two added repro test files are large/exploratory; prefer a smaller targeted regression test footprint.
• Current repo evidence:
  • lib/terminal.ts defaults scrollback to 10000 and passes it through buildWasmConfig() as GhosttyTerminalConfig.scrollbackLimit.
  • lib/ghostty.ts writes config.scrollbackLimit ?? 10000 directly into the WASM config struct as scrollback_limit.
  • patches/ghostty-wasm-api.patch defines newWithConfig() and passes scrollback_limit directly to Terminal.init(... .max_scrollback = scrollback_limit ...).
  • ghostty/src/terminal/Screen.zig documents max_scrollback as bytes.
  • Native ghostty/src/terminal/render.zig builds RenderState.row_data.items(.pin) using a viewport rowIterator and stores each row pin during RenderState.update().
  • patches/ghostty-wasm-api.patch currently has renderStateGetViewport() bypassing that row-pin cache and calling pages.pin(.{ .active = .{ .y = ... } }) per row.
• Out-of-scope follow-up discovered during planning: lib/interfaces.ts documents scrollback default as 1000 while Terminal uses 10000. I searched existing issues and opened Document actual default for ITerminalOptions.scrollback #174 with needs-triage. Do not fold that docs cleanup into getViewport() returns corrupted data when viewport spans multiple pages #139 unless a maintainer explicitly asks.

Scope boundaries

In scope:

• Correct renderStateGetViewport() row resolution in patches/ghostty-wasm-api.patch.
• Convert line-count scrollback config to the byte budget Ghostty expects before calling Terminal.init().
• Rebuild and commit the generated ghostty-vt.wasm after patch changes.
• Add concise regression coverage for page-boundary viewport stability and scrollback retention/monotonicity.
• Validate with automated tests, build checks, and browser dogfooding evidence.

Out of scope:

• Refactoring unrelated renderer/input/selection code.
• Changing or documenting public scrollback: 0 semantics. The current wrapper has special handling for 0, while Ghostty's byte-level docs have their own meaning; do not characterize, test, or change that behavior in getViewport() returns corrupted data when viewport spans multiple pages #139 unless it becomes a direct blocker, and file a separate issue if a semantic mismatch is confirmed.
• Replacing PR fix: use cached row pins for WASM viewport rendering #133 wholesale, especially its large exploratory test files.
• Fixing unrelated docs/default mismatches such as Document actual default for ITerminalOptions.scrollback #174.

Recommended implementation phases

Phase 1 — Add focused regression tests first

Add minimal regression coverage in existing test files, preferably lib/terminal.test.ts near the existing Terminal Config / render-state tests. Reuse createIsolatedTerminal() from lib/test-helpers.ts; always dispose terminals in finally blocks.

Target tests:

1. Viewport page-boundary stability

   • Create an isolated terminal with the reported dimensions: cols: 130, rows: 39, scrollback: 10000.
   • Write deterministic, distinct, SGR-heavy lines in repeated batches, enough to cross Ghostty page boundaries. Keep the generator small; use unique row markers like rep=03 line=041 plus color/style escape sequences rather than copying PR fix: use cached row pins for WASM viewport rendering #133's large repro fixture.
   • Call term.wasmTerm!.update() before reading viewport data.
   • Keep visible text under 130 columns; ANSI escape bytes can be long, but printable row markers must not wrap unless the assertion explicitly accounts for wrapping.
   • Avoid a trailing final \r\n, or explicitly account for the final blank row when computing expected viewport rows.
   • Assert:
     • Primary oracle: getViewport() rows decode to the expected final visible line markers, with no horizontal merging from unrelated lines.
     • getScrollbackLength() never decreases during append-only output before the configured scrollback limit should be reached.
     • Secondary consistency check only: getLine(row) and the corresponding getViewport() slice agree for sampled rows. Do not treat this as an independent correctness oracle because getLine() slices getViewport().

2. Scrollback line-count budget is not treated as raw bytes

   • Use a small but clear configuration such as cols: 130, rows: 39, scrollback: 10000 with repeated output, or a second faster case with a lower custom limit if it reliably fails before the fix.
   • Assert retained scrollback is consistent with a line-count budget and does not unexpectedly drop under the issue's reproduction pattern.
   • Avoid overfitting to exact Ghostty internals; prefer monotonicity and lower-bound assertions that distinguish "line count converted to bytes" from "line count passed as tiny byte budget".

Quality gate before implementation:

bun test lib/terminal.test.ts -t "viewport|scrollback"

Expected result before the fix: at least one new regression assertion should fail against the current ghostty-vt.wasm. If it does not fail, tighten only the generator/threshold within #139's described reproduction dimensions before changing production code.

Implementation workflow for the Zig patch phases:

• Prefer applying patches/ghostty-wasm-api.patch to the ghostty/ submodule, editing ghostty/src/terminal/c/terminal.zig, then regenerating or refreshing the patch from that submodule diff. This avoids hand-editing large patch hunks incorrectly.
• Before rebuilding, verify the final patch still applies cleanly with git -C ghostty apply --check ../patches/ghostty-wasm-api.patch (or rely on scripts/build-wasm.sh, which performs this check and fails early).
• After generating the final patch, ensure the ghostty/ submodule is returned to a clean state.

Phase 2 — Fix scrollback unit conversion in the WASM API patch

Update patches/ghostty-wasm-api.patch in the generated Zig wrapper (src/terminal/c/terminal.zig inside the patch):

1. Add the page-layout imports needed to compute Ghostty's byte budget from rows/columns:

const pagepkg = @import("../page.zig");
const Page = pagepkg.Page;

2. In newWithConfig(), treat cfg.scrollback_limit as a JS line count and convert finite values to bytes before passing .max_scrollback to Terminal.init().

Preferred shape:

const scrollback_lines: usize = if (config_) |cfg|
    if (cfg.scrollback_limit == 0) std.math.maxInt(usize) else cfg.scrollback_limit
else
    10_000;

const scrollback_limit: usize = if (scrollback_lines == std.math.maxInt(usize))
    std.math.maxInt(usize)
else blk: {
    const cap = pagepkg.std_capacity.adjust(.{ .cols = @intCast(cols) }) catch
        break :blk scrollback_lines * 1024;
    const page_size = Page.layout(cap).total_size;
    const bytes_per_line = page_size / cap.rows;
    break :blk scrollback_lines * bytes_per_line;
};

Implementation notes:

• Prefer Zig checked/defensive arithmetic where practical (mul overflow fallback to std.math.maxInt(usize) or a documented equivalent). The goal is fail-fast in tests without introducing user-visible crashes for valid inputs.
• Preserve the wrapper's existing cfg.scrollback_limit == 0 branch as an implementation detail; do not add tests or documentation for 0 semantics in getViewport() returns corrupted data when viewport spans multiple pages #139.
• Keep the TypeScript config field as a line count. At most, update the nearby comment in lib/ghostty.ts to say the WASM wrapper converts lines to bytes internally.
• Do not duplicate Ghostty page-size assumptions in TypeScript; the Zig wrapper has direct access to Ghostty's page layout helpers.

Phase 3 — Fix viewport row resolution in renderStateGetViewport()

Update only renderStateGetViewport() unless tests prove another row-coordinate API must change for #139.

Minimal intended behavior:

• Stop reading rows with independent pages.pin(.active) calls.
• Read const row_pins = rs.row_data.items(.pin);, which is populated by renderStateUpdate() / native RenderState.update().
• For each viewport row y, use row_pins[y] to obtain cells and page style/hyperlink/grapheme metadata.
• Preserve the current cell serialization fields and behavior: codepoint, fg/bg RGB, style flags, width, hyperlink ID, and grapheme length.
• Add defensive checks for impossible/stale-cache states:
  • Return -1 if buf_size < rows * cols as today.
  • If row_pins.len < rows, fill missing rows with default cells and add a debug assertion if practical. Avoid returning -1 here unless the TypeScript side is also changed to prevent stale cell-pool reuse, which would broaden the fix.
  • Keep default-cell fill behavior for columns beyond a row's cell span.

Important update-order assumption:

• lib/ghostty.ts#getLine() already calls update() before getViewport().
• Direct tests that call getViewport() should call term.wasmTerm!.update() first.
• Do not add extra update() calls to getViewport() unless required; that would change a hot-path performance contract outside the issue's root cause.

Phase 4 — Rebuild committed WASM artifact

Because ghostty-vt.wasm is committed, patch changes are not complete until the binary is rebuilt.

Commands:

bun install
bun run build:wasm

If Zig is unavailable, use the repo-documented/mise path used by triage:

PATH="$(mise where zig@0.15.2):$PATH" ./scripts/build-wasm.sh

After rebuilding:

git status --short
git -C ghostty status --short

Acceptance for this phase:

• Tracked changes should include the patch, generated ghostty-vt.wasm, and the targeted test edit(s).
• The ghostty/ submodule worktree should be clean after scripts/build-wasm.sh reverts the patch.

Phase 5 — Automated validation

Run targeted checks while iterating, then the full project gate before declaring done.

Targeted checks:

bun test lib/terminal.test.ts -t "viewport|scrollback"
bun test lib/scrolling.test.ts

Full validation gate:

bun run fmt && bun run lint && bun run typecheck && bun test && bun run build

Notes:

• bun run build invokes build:wasm, so it may rebuild the WASM artifact again; verify no unexpected binary churn afterward.
• If bun test hangs after reporting completion, capture the pass/fail summary and note the known hang behavior rather than claiming a clean exit that did not occur.
• If any validation failure is unrelated to getViewport() returns corrupted data when viewport spans multiple pages #139, follow the out-of-scope issue policy instead of broadening this fix.

Dogfooding / reviewable evidence

Because this bug affects the browser-visible terminal viewport and scrollback behavior, dogfooding should produce both automated logs and visual evidence.

Setup (follow the repo's demo/PTY instructions if they change; current repo instructions use this shape):

# Terminal 1: PTY server for the interactive demo
cd demo/server
bun install
bun run start

# Terminal 2: Vite dev server from repo root
bun run dev

Browser exercise:

1. Open http://localhost:8000/demo/ using agent-browser or a normal browser.
2. Resize the browser/demo terminal so the terminal is near the issue reproduction shape (cols ~= 130, rows ~= 39) if feasible.
3. Paste/run an ANSI-heavy append-only output command, for example:

for rep in $(seq 1 14); do
  for i in $(seq 1 68); do
    color=$(( (rep * 17 + i) % 256 ))
    printf '\033[1;38;5;%smrep=%02d line=%02d %s\033[0m\n' "$color" "$rep" "$i" "████████████████████████████████"
  done
done

4. Scroll to the bottom, then into history, then back down. Look for merged rows, missing blocks, garbage characters, or scrollbar jumps.
5. Capture reviewer evidence:
   • Screenshot at the bottom after the output completes.
   • Screenshot while scrolled into history where distinct rep= / line= markers remain coherent.
   • A short video recording of scrolling through the generated output without row corruption.
6. Attach screenshots/recording artifacts to the final report or PR using attach_file so reviewers can inspect the exact dogfood state.

If the environment cannot provide browser screenshots/video, document the blocker explicitly and include the automated regression logs plus any terminal output snapshots that demonstrate the same invariants.

Acceptance criteria

• The new regression test(s) fail on the current implementation or are otherwise demonstrated to reproduce getViewport() returns corrupted data when viewport spans multiple pages #139 before the fix.
• renderStateGetViewport() uses cached RenderState.row_data row pins instead of independent pages.pin(.active) row resolution.
• The JS scrollback line count is converted to a Ghostty byte budget before being passed as .max_scrollback.
• getScrollbackLength() does not unexpectedly decrease under the issue's append-only reproduction before the configured line budget is reached.
• getViewport() and getLine() return coherent, matching visible rows across page-boundary scenarios at the reported dimensions.
• The generated ghostty-vt.wasm is rebuilt and included with the patch changes.
• No unrelated API/default/doc cleanup is included in the getViewport() returns corrupted data when viewport spans multiple pages #139 diff.
• Targeted tests, full validation, and dogfooding evidence are completed or any environmental blockers are clearly reported.

Risks and mitigations

• Repro brittleness: The corruption depends on page layout and column width. Start from the issue dimensions (cols=130, rows=39, scrollback=10000) and the triage repro pattern. Keep assertions invariant-based rather than exact-byte-layout-based.
• RenderState cache freshness: Cached row pins are only valid after update(). Tests and hot paths should maintain the current update-before-read ordering; add defensive checks in Zig for stale cache rather than silently reading undefined pins.
• Scrollback memory increase: Correctly converting 10,000 lines to bytes will allocate more scrollback than the buggy behavior. This is expected and required by the API contract; avoid adding new memory knobs in this issue.
• WASM build tooling: Rebuilding requires Zig 0.15.2+. If unavailable, this is a hard blocker for implementation completion because the committed binary must match the patch.
• Adjacent row APIs: renderStateGetGrapheme(), isRowWrapped(), and getHyperlinkUri() also resolve rows, but PR fix: use cached row pins for WASM viewport rendering #133 and getViewport() returns corrupted data when viewport spans multiple pages #139 specifically target renderStateGetViewport(). Do not expand to them unless a getViewport() returns corrupted data when viewport spans multiple pages #139 regression test proves viewport correctness still depends on them; otherwise file/follow a separate issue.

Advisor review status

Approved after two advisor review rounds. Round 1 requested refinements around test oracles, deterministic non-wrapping output, patch-edit workflow, scrollback: 0 scope, stale row-pin fallback behavior, and dogfood setup wording. The plan was updated accordingly, and round 2 approved it as implementation-ready.

---

Generated with mux • Model: openai:gpt-5.5 • Thinking: xhigh

[ThomasK33]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0b3e85ff1e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[ThomasK33]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f2cb4c1156

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[ThomasK33]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d117e5938e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[ThomasK33]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d6c359c2ed

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[ThomasK33]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Bravo.

Reviewed commit: 9940237221

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[ThomasK33]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. You're on a roll.

Reviewed commit: f2e4a9f27b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".