docs: document ITerminalOptions scrollback default

[ThomasK33]

Summary

Fixes #174.

• Updates ITerminalOptions.scrollback docs to match the actual Terminal default of 10000 lines.
• Adds a focused regression test that verifies default term.options.scrollback is 10000 when no options are provided.
• Leaves runtime scrollback behavior unchanged.

Validation

• bun test lib/terminal.test.ts -t "Public Mutable Options"
• bun run fmt && bun run lint && bun run typecheck && bun test && bun run build

Dogfooding

• Started the Vite dev server with bun run dev -- --host 127.0.0.1.
• Used agent-browser to open http://127.0.0.1:8000/demo/colors-demo.html, verify the color-demo controls rendered, and capture smoke-test evidence.
• Local evidence artifacts captured for this workspace:
  • Screenshot: /tmp/ghostty-web-174-dogfood/colors-demo.png
  • Video: /tmp/ghostty-web-174-dogfood/colors-demo.webm

Verifier summary

The adjacent issue-implementation workflow converged. Its verifier found that the final diff is limited to lib/interfaces.ts and lib/terminal.test.ts, that the public API docs now agree with the existing runtime default, and that the standard validation suite passed after generating the ignored WASM artifact required by tests.

---

📋 Implementation Plan

Implementation Plan — #174

Goal

Resolve GitHub issue coder/ghostty-web#174 by reconciling the public API documentation for ITerminalOptions.scrollback with the actual default used by Terminal.

The live issue is open, labeled documentation, triage:done, and accepted, and asks for the interface comment to document the actual default or for code/docs to be reconciled intentionally. The verified narrow mismatch is:

• lib/interfaces.ts: scrollback?: number; // Default: 1000
• lib/terminal.ts: scrollback: options.scrollback ?? 10000
• lib/ghostty.ts: low-level WASM config fallback also uses config.scrollbackLimit ?? 10000

Scope and non-goals

In scope

• Update the public ITerminalOptions.scrollback documentation to state the actual default: 10000.
• Add one focused regression test asserting that a default Terminal exposes term.options.scrollback === 10000, so the documented API default is tied to executable behavior.
• Run repository validation and collect reviewable evidence.

Out of scope

• Do not change runtime scrollback behavior or the constructor default.
• Do not attempt to make the default xterm.js-compatible 1000; that would be a product behavior change and is not requested by Document actual default for ITerminalOptions.scrollback #174.
• Do not address the byte-vs-line semantics tracked by issue scrollbackLimit is documented as lines but interpreted as bytes by WASM #140 or viewport corruption tracked by issue getViewport() returns corrupted data when viewport spans multiple pages #139.
• Do not touch low-level lib/types.ts docs unless the final diff reveals a direct contradiction created by this task; related PR docs: correct GhosttyTerminalConfig.scrollbackLimit docs #151/docs(types): correct scrollbackLimit field documentation #168 context suggests those are separate from Document actual default for ITerminalOptions.scrollback #174.
• Do not open new issues unless implementation reveals a genuinely separate bug and no matching issue already exists after searching.

Evidence gathered

• Live issue body confirms the requested cleanup and identifies the mismatch between lib/interfaces.ts and lib/terminal.ts.
• Triage comment recommends the smallest safe implementation: update lib/interfaces.ts to document 10000; changing the constructor default would need an intentional behavior decision.
• Explore/code investigation verified:
  • lib/interfaces.ts:13 documents Default: 1000.
  • lib/terminal.ts:147 defaults options.scrollback to 10000.
  • lib/ghostty.ts:296 defaults config.scrollbackLimit to 10000 when writing the WASM terminal config.
  • lib/terminal.test.ts already has a Public Mutable Options section around line 2326 where an adjacent default-options assertion belongs.
• Explore/GitHub investigation verified:
  • No active PR directly resolves the public ITerminalOptions.scrollback comment.
  • Related issues/PRs are adjacent but not duplicates: getViewport() returns corrupted data when viewport spans multiple pages #139, scrollbackLimit is documented as lines but interpreted as bytes by WASM #140, docs: correct GhosttyTerminalConfig.scrollbackLimit docs #151, docs(types): correct scrollbackLimit field documentation #168.

Implementation steps

Phase 1 — Pre-flight verification

1. Confirm the working tree is clean:

   git status --short

2. Re-read the current issue state before editing, in case labels or linked PRs changed:

   gh issue view 174 --repo coder/ghostty-web --comments

3. Confirm the exact mismatch still exists:

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

Quality gate: If lib/interfaces.ts already documents 10000 and no test/default mismatch remains, stop and report that the issue appears already fixed instead of creating a redundant change.

Phase 2 — Documentation correction

1. Edit lib/interfaces.ts only at ITerminalOptions.scrollback:

   scrollback?: number; // Default: 10000

2. Do not change neighboring options or formatting beyond formatter output.

Quality gate: Re-run the targeted grep and verify all public/API default references for this issue now agree on 10000.

Phase 3 — Focused regression test

Add one test in lib/terminal.test.ts inside the existing describe('Public Mutable Options', ...) block, next to the current test that checks custom option values.

Recommended test shape:

test('options expose default values when none are provided', async () => {
  const term = await createIsolatedTerminal();
  try {
    expect(term.options).toBeDefined();
    expect(term.options.cols).toBe(80);
    expect(term.options.rows).toBe(24);
    expect(term.options.scrollback).toBe(10000);
  } finally {
    term.dispose();
  }
});

Notes:

• Keep the test narrow. The issue is about scrollback; checking cols/rows only provides cheap context that this is a default-options test.
• Use try/finally so the new test does not add another undisposed Terminal instance.
• Do not assert low-level WASM byte/line semantics here; that belongs to scrollbackLimit is documented as lines but interpreted as bytes by WASM #140.

Quality gate: Run the targeted test before broader validation:

bun test lib/terminal.test.ts -t "Public Mutable Options"

Phase 4 — Full validation

Run the repository's standard checks before claiming success:

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

If dependencies are missing, run bun install first. If any command hangs, fails, or is blocked by environment or unrelated existing behavior, capture the exact output and document it instead of hiding it.

Phase 5 — Dogfooding and reviewable evidence

This issue has no intentional UI/runtime behavior change, so dogfooding should focus on proving the public API default and demonstrating that the demo still loads.

1. Produce command-line evidence:

   script -q /tmp/ghostty-web-174-validation.typescript -c '
     set -e
     rg -n "scrollback\?: number|scrollback: options\.scrollback \?\? 10000" lib/interfaces.ts lib/terminal.ts
     bun test lib/terminal.test.ts -t "Public Mutable Options"
     bun run fmt && bun run lint && bun run typecheck && bun test && bun run build
   '

   Attach or summarize the resulting transcript in the PR/implementation report.

2. Optional browser smoke evidence for reviewer confidence:

   • Start the dev server:

     bun run dev

   • Use agent-browser (load its current instructions with agent-browser skills get core first) or a normal browser to open http://localhost:8000/demo/colors-demo.html.

   • Verify the demo renders the terminal color showcase without console errors.

   • Capture a screenshot of the loaded demo and, if available, a short recording of page load/interaction.

   • Make clear in the evidence that this is a no-regression UI smoke check; the demos configure scrollback: 10000 explicitly, so this browser smoke does not prove the default behavior. The targeted unit test is the default-behavior evidence.

Acceptance criteria

• lib/interfaces.ts documents ITerminalOptions.scrollback as defaulting to 10000.
• lib/terminal.ts continues to default options.scrollback to 10000; no runtime behavior changes are introduced.
• A focused test in lib/terminal.test.ts asserts the default public option value for scrollback is 10000.
• Targeted and full validation commands pass, or any environmental blocker is documented with exact command output.
• The final diff stays minimal and reviewable, limited to lib/interfaces.ts and the focused test addition in lib/terminal.test.ts unless formatter output requires otherwise.
• No out-of-scope issues are fixed in this PR.

Out-of-scope issue handling during implementation

If implementation discovers another bug, flaky test, missing feature, or nice-to-have improvement:

1. Do not expand the Document actual default for ITerminalOptions.scrollback #174 PR to fix it.

2. Search existing issues first, including recent issues that another agent/workspace may have opened:

   gh issue list --repo coder/ghostty-web --state all --search "<root problem keywords>"

3. If a matching issue exists, comment there with new evidence/reproduction details and link back to Document actual default for ITerminalOptions.scrollback #174 or the PR.

4. If no matching issue exists, create a new issue with evidence, reproduction steps, expected behavior, actual behavior, why it is out of scope for Document actual default for ITerminalOptions.scrollback #174, and label it needs-triage.

5. Return to the Document actual default for ITerminalOptions.scrollback #174 scope immediately after recording the out-of-scope finding.

PR notes for implementer

• Keep the PR title/documentation-oriented, for example: docs: document ITerminalOptions scrollback default.
• PR body should link Fixes #174, summarize the comment/test changes, list validation commands, and include dogfooding evidence.
• Include the required mux-generated footer with $MUX_MODEL_STRING and $MUX_THINKING_LEVEL if creating a PR from this workspace.

---

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

[ThomasK33]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. What shall we delve into next?

Reviewed commit: c94b6c9b57

ℹ️ 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".