Document actual default for ITerminalOptions.scrollback

[ThomasK33]

Description

While planning the fix for #139, I noticed a small API documentation mismatch around the scrollback option:

• lib/terminal.ts currently defaults options.scrollback to 10000 lines.
• lib/interfaces.ts documents scrollback?: number; // Default: 1000.

This can confuse API users and reviewers when reasoning about scrollback-related behavior.

Expected behavior

The ITerminalOptions.scrollback comment should document the actual default used by Terminal, or the code and docs should be reconciled intentionally.

Actual behavior

The interface comment says the default is 1000, while the constructor uses 10000.

Reproduction / evidence

rg -n "scrollback" lib/interfaces.ts lib/terminal.ts

Relevant current lines:

// lib/interfaces.ts
scrollback?: number; // Default: 1000

// lib/terminal.ts
scrollback: options.scrollback ?? 10000,

Why this is out of scope for #139

Issue #139 is about runtime corruption caused by WASM viewport row pin resolution and scrollback line-count-to-byte conversion. This is a documentation/default consistency cleanup and should not expand the #139 implementation scope.

Related planning context: #139

---

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

[ThomasK33]

Note

This triage report is AI-generated using Mux

1. Classification — documentation; no outcome label. The reported mismatch is reproducible by static inspection, so status:could-not-reproduce is not applicable.

2. Summary — The issue reports that the public ITerminalOptions.scrollback comment documents Default: 1000, while the Terminal constructor currently defaults options.scrollback to 10000. That is a small API documentation/default consistency problem, separate from the runtime scrollback byte/line issue tracked elsewhere.

3. Evidence / reproduction — I read the full issue thread for Document actual default for ITerminalOptions.scrollback #174 (no comments at triage time), the related getViewport() returns corrupted data when viewport spans multiple pages #139 discussion, adjacent scrollbackLimit is documented as lines but interpreted as bytes by WASM #140, and the scrollback-related PRs called out below. The mismatch reproduces on the current checkout (6a1a50d) with a targeted grep:

   rg -n "scrollback\?: number|scrollback: options\.scrollback \?\? 10000|scrollbackLimit\?: number|scrollback_limit: number" lib/interfaces.ts lib/terminal.ts lib/types.ts

   lib/types.ts:535:  scrollbackLimit?: number;
   lib/types.ts:607:  scrollback_limit: number; // Number of scrollback lines (default: 10,000)
   lib/interfaces.ts:13:  scrollback?: number; // Default: 1000
   lib/terminal.ts:147:      scrollback: options.scrollback ?? 10000,
   

   The lines directly relevant to this issue are:

   // lib/interfaces.ts
   scrollback?: number; // Default: 1000
   
   // lib/terminal.ts
   scrollback: options.scrollback ?? 10000,

4. Candidate fixes checked — No PR directly references Document actual default for ITerminalOptions.scrollback #174 yet.

   • docs: correct GhosttyTerminalConfig.scrollbackLimit docs #151 (docs: correct GhosttyTerminalConfig.scrollbackLimit docs) is open and only changes low-level lib/types.ts documentation for GhosttyTerminalConfig.scrollbackLimit / TerminalConfig.scrollback_limit. Its body explicitly notes that ITerminalOptions.scrollback remains misleading, so it does not resolve this issue.
   • docs(types): correct scrollbackLimit field documentation #168 (docs(types): correct scrollbackLimit field documentation) is closed and makes the same low-level docs change plus unrelated ignore-file changes; it does not touch lib/interfaces.ts or lib/terminal.ts.
   • fix: use cached row pins for WASM viewport rendering #133 (fix: use cached row pins for WASM viewport rendering) is the candidate fix for getViewport() returns corrupted data when viewport spans multiple pages #139. Its diff touches lib/ghostty.ts, WASM patch code, and regression tests; it converts scrollback line counts to bytes in the WASM path but does not update the ITerminalOptions.scrollback default comment, so it is not a direct fix for this documentation mismatch.

5. Relevant code / likely cause — lib/interfaces.ts appears to have kept an xterm.js-shaped scrollback default comment (1000), while lib/terminal.ts intentionally constructs baseOptions.scrollback with options.scrollback ?? 10000. The neighboring low-level comments in lib/types.ts are also under active discussion in scrollbackLimit is documented as lines but interpreted as bytes by WASM #140/docs: correct GhosttyTerminalConfig.scrollbackLimit docs #151, but the exact mismatch reported here is the public ITerminalOptions comment versus the constructor default.

6. Recommendation — Keep this open as a documentation cleanup. The smallest safe implementation is to update lib/interfaces.ts so ITerminalOptions.scrollback documents the actual 10000 default. If maintainers instead want xterm.js-compatible 1000 behavior, the constructor default and tests should be changed intentionally rather than only editing the comment. When scrollbackLimit is documented as lines but interpreted as bytes by WASM #140/fix: use cached row pins for WASM viewport rendering #133 is resolved, consider wording the scrollback docs so both the default and unit semantics remain clear.

7. Adjacent issues — Existing scrollbackLimit is documented as lines but interpreted as bytes by WASM #140 tracks the larger scrollbackLimit line-count-vs-byte mismatch, and getViewport() returns corrupted data when viewport spans multiple pages #139 tracks viewport corruption that can be exacerbated by that runtime mismatch. I did not find another open or closed issue specifically for the ITerminalOptions.scrollback default comment, and no new adjacent issue was created.