Could the automatic scrollToBttom() behaviour made to be configurable/togglable?

[vidosits]

In terminal.ts a scrollToBottom() call is made after each write().

ghostty-web/lib/terminal.ts

Lines 573 to 576 in 03ead6e

	// Phase 2: Auto-scroll to bottom on new output (xterm.js behavior)
	if (this.viewportY !== 0) {
	this.scrollToBottom();
	}

Even if the user scrolls up, the terminal just scrolls back to the bottom on the next write. Imagine that there's a log being streamed through a websocket and the user temporarily wants to scroll back for something that was written to the terminal earlier. They have a small window to do that, before the next line gets written and it scrolls to the bottom again.

xterm.js had this same issue and was eventually handled.

[diegosouzapw]

Hi @vidosits! 👋

Just wanted to let you know: this issue is fixed in diegosouzapw/ghostty-web v0.4.0 (see commit).
The preserveScrollOnWrite option is now available — set it to true to lock the viewport position when new output arrives.

If you're looking for a fork with this and many other upstream fixes, feel free to give it a try!

I'm also building OmniRoute, an open project that provides free LLM model access — I plan to use ghostty-web there, so the more reliable it gets, the better. 🙏 Contributions welcome!

[ThomasK33]

Note

This triage report is AI-generated using Mux

1. Classification — feature. No outcome label is recommended: the current behavior was reproduced, so status:could-not-reproduce should not be applied. The existing accepted label can remain.

2. Summary — This issue asks for the automatic scrollToBottom() call after Terminal.write() to be configurable/toggleable. On current origin/main (6a1a50df5b4f6b34d1b1de10fad3a0fc811bfbc0), a user who scrolls up into history is returned to the live bottom on the next write, which makes reading earlier streamed output difficult.

3. Evidence / reproduction — I reproduced the current behavior with a focused Bun/Happy DOM test after installing deps and building the local WASM artifact (bun install, ./scripts/build-wasm.sh, then bun test). The test writes enough rows to create scrollback, scrolls up 3 lines, writes one more line, and observes that viewportY resets to 0.

Observed output on current origin/main:

{
  "scrollbackLength": 9,
  "viewportAfterUserScroll": 3,
  "viewportAfterWrite": 0
}

A second visible-content check showed the jump more directly:

current before: viewportY=3, scrollbackLength=8, topVisible="Line 05"
current after:  viewportY=0, scrollbackLength=9, topVisible="Line 09"

repro-scroll-on-write.test.ts (portable version; save in the repo root)

import { describe, expect, test } from 'bun:test';
import { createIsolatedTerminal } from './lib/test-helpers';

describe('issue #127 scroll-to-bottom-on-write behavior', () => {
  test('write() returns the viewport to the live bottom after a user scrolls up', async () => {
    const container = document.createElement('div');
    document.body.appendChild(container);

    const term = await createIsolatedTerminal({ cols: 20, rows: 5, scrollback: 100 });
    term.open(container);

    for (let i = 0; i < 12; i++) {
      term.write(`Line ${i.toString().padStart(2, '0')}\r\n`);
    }

    expect(term.getScrollbackLength()).toBeGreaterThan(0);

    term.scrollLines(-3);
    const viewportAfterUserScroll = term.getViewportY();
    expect(viewportAfterUserScroll).toBeGreaterThan(0);

    term.write('Line 12\r\n');
    const viewportAfterWrite = term.getViewportY();

    console.log(
      JSON.stringify(
        {
          scrollbackLength: term.getScrollbackLength(),
          viewportAfterUserScroll,
          viewportAfterWrite,
        },
        null,
        2
      )
    );

    expect(viewportAfterWrite).toBe(0);

    term.dispose();
    container.remove();
  });
});

4. Candidate fixes checked — I checked the issue comment, linked timeline entries, and related open/closed PR search results.

• coder/ghostty-web PR fix: preserve scroll position when new output arrives #150 (fix: preserve scroll position when new output arrives) is open. I fetched its current head (a1c4f2f8dbb405c7d0507b1ba02ccc93e032f98d) into a scratch worktree and ran the same repro. It preserves the same visible top line after the write (Line 05) by changing viewportY from 3 to 4, so it fixes the viewport-locking behavior. It does not make the behavior configurable; the PR body describes an unconditional behavior change. Its discussion previously called out missing onScroll/scrollbar updates; the current PR head includes scrollEmitter.fire(...) and showScrollbar() in the preserve branch.
• coder/ghostty-web PR fix: respect scroll position when new output arrives #170 (fix: respect scroll position when new output arrives) is closed/unmerged. I fetched its head (c1a18b837c0bfaab2a7cc22f988e4e6b0993d47e) and ran the same repro. It avoids jumping all the way to bottom (viewportY stays 3), but the top visible line changes from Line 05 to Line 06 because it does not compensate for scrollback growth. It also does not add configurability.
• The fork PR diegosouzapw/ghostty-web implement screen buffer #5 is merged and was linked from the issue timeline. I read its body/discussion and verified commit 84a64fb1f20882e39f6cecf4b88f17f7be6e03fc in a scratch worktree. Its default mode preserves current behavior (viewportY returns to 0), while preserveScrollOnWrite: true keeps the same visible top line (Line 05) and moves viewportY from 3 to 4. This matches the requested “configurable/toggleable” behavior.
• PR fix(renderer): correct scrollback/screen row mapping during smooth scroll #171 was also checked because it mentions viewportY, but its body is about renderer row mapping during fractional smooth scroll. It appears adjacent, not a candidate fix for this issue’s write-time auto-scroll policy.

Candidate comparison from the same visible-content harness:

current:       before top="Line 05" viewportY=3 -> after top="Line 09" viewportY=0
PR #150:       before top="Line 05" viewportY=3 -> after top="Line 05" viewportY=4
PR #170:       before top="Line 05" viewportY=3 -> after top="Line 06" viewportY=3
fork default:  before top="Line 05" viewportY=3 -> after top="Line 09" viewportY=0
fork opt-in:   before top="Line 05" viewportY=3 -> after top="Line 05" viewportY=4

5. Relevant code / likely cause — Current lib/terminal.ts writes to WASM, processes responses, invalidates links, then unconditionally calls scrollToBottom() whenever viewportY !== 0:

// Phase 2: Auto-scroll to bottom on new output (xterm.js behavior)
if (this.viewportY !== 0) {
  this.scrollToBottom();
}

scrollToBottom() sets viewportY = 0 and fires onScroll, so any write yanks a scrolled viewport back to the live edge. ITerminalOptions currently has scrolling-related smoothScrollDuration, but no option for preserving the viewport on writes.

The likely implementation shape is the same as the verified candidates that fully preserve content: when an opt-in flag is enabled and savedViewportY > 0, record the previous scrollback length before writing, write the data, compute delta = newScrollback - savedScrollback, then set viewportY = min(savedViewportY + delta, newScrollback) so the same scrollback content remains under the viewport. The branch should continue to fire onScroll and keep the scrollbar affordance visible when it mutates viewportY.

6. Recommendation — Keep this issue open/accepted and implement as an opt-in feature. The fork PR implement screen buffer #5 behavior is the closest fit for this issue because it preserves backwards-compatible auto-scroll by default while adding a preserveScrollOnWrite?: boolean option for embedders that need the viewport locked during streaming output. If PR fix: preserve scroll position when new output arrives #150 is used as the base, it should be adjusted to make the behavior configurable (or the breaking default behavior should be explicitly accepted/documented). Add regression coverage for: default auto-scroll, opt-in preserved viewport, onScroll/scrollbar updates when preserved, and the scrollback-limit clamp path.

7. Adjacent issues — No duplicate issue was found in open/closed issue search for preserve scroll or scrollToBottom; only this issue matched. No new adjacent issue was created.

---

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