charmbracelet / charmbracelet/x

vt: notify consumers when terminal output clears scrollback

Open
#938 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Go
Stars
314
Forks
94
Avg merge
3d 22h
Merged PRs (30d)
2

Description

## Problem

The emulator correctly clears its internal scrollback for `CSI 3 J`, but a consumer cannot reliably tell that the clear happened.

Reading `ScrollbackLen()` before and after `Emulator.Write` is not enough. One call can contain both the clear command and enough following output to create new scrollback. The final length may equal or exceed the old length, so the clear is invisible to the consumer.

## Reproduction shape

1. Fill an emulator with several rows of scrollback.
2. Record `ScrollbackLen()`.
3. In one call to `Write`, send `\x1b[3J` followed by enough lines to scroll several new rows.
4. Read `ScrollbackLen()` again.

The final length can be as large as the starting length even though all of the old history was cleared and replaced with new history.

## Expected

A consumer should have an observable signal that scrollback was cleared. For example, this could be:

- a scrollback-cleared callback; or
- a history change result that distinguishes cleared rows from newly pushed rows.

## Actual

Only the final scrollback contents and length are observable. That final state cannot tell a downstream incremental model whether the old history survived.

## Why this matters

Consumers that maintain absolute history positions for lazy loading, selection, or search can keep coordinates that refer to history the terminal application explicitly erased. Asking each consumer to parse escape sequences separately would duplicate the emulator's parser and can disagree with it.

The important case is a clear and subsequent scrolling within one `Write` call. A simple before-and-after length comparison cannot solve that case.

Contributor guide

Open the contributing guide

Research direction

Start by tracing Emulator.Write and the CSI 3 J handling, then inspect how ScrollbackLen exposes state to consumers. Define and implement an observable signal that distinguishes cleared history from subsequent scrolling within one Write call, and verify that consumers can detect the clear even when new scrollback is created.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
cli
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.