Repository navigation
fix(web): manual Reload history action for the tmux repaint gap above live output (#814) - #815
HadrienKerlero wants to merge 12 commits into
Conversation
…irst scroll-up (Ark0N#814) A tmux repaint burst overwrites rows that never reach xterm scrollback, leaving a hole just above the live screen. The Ark0N#205 re-pull only fired at viewportY 0, so the user had to scroll past the hole first. Mark a non-shell session dirty on each live write; the first upward scroll from the bottom of a dirty session runs the existing full-history re-pull anchored to the bottom, keeping the viewport's distance from live output and replaying travel made during the replay. Cooldown, downgrade guard and the top-of-buffer path are unchanged.
…ve (Ark0N#814) Review follow-up. The early re-pull sampled the live-output generation after its fetch, but nothing gates live output while the capture downloads, so output newer than the capture was overwritten and the session marked clean. Sample before the fetch. Travel made during the replay was one signed sum clamped once, so scrolling to the bottom and back up cancelled out. Record moves in order and clamp after each, as live scrolling does.
|
Thanks for this, Hadrien, and for the careful write-up. The PR repairs the tmux repaint gap from #814 by re-pulling the full tmux history on the first scroll-up from the live screen, instead of waiting until the scroll reaches the top of the buffer. The open design questionOne decision on #814 is still open, and this PR makes it: whether the history repair may fire before the top of the buffer, and on which signal. That has to be settled before more work goes into the code. The signal here is any live output. There are narrower options, and picking one is the open part: keep the top-only behaviour, use a stream signal that only fires on a burst (the reproduction on #814 found that tmux sends a full-screen Code points, if the any-output trigger is kept
Typecheck, lint, format, the frontend syntax and dead-code checks, and the full test suite (17134 tests) pass on this branch, and 9 of the new tests fail on master as intended. The trigger question is open, so the PR stays as it is for now. The code points above only apply if the any-output trigger is kept. |
…utput, add a phone reload control (Ark0N#814) Review follow-up on Ark0N#815, and the phone case from Ark0N#814: the gap opens below a reader who stays scrolled up while output arrives, and the bottom-only trigger never fired there. - Open the buffer load before the capture fetch so output arriving during the download is queued and replayed, not wiped by the reset. Every non-replay exit flushes the queue. A drop at the 128 KiB cap during an open load is deferred and resumed when the load ends instead of spending its retries against it. - Clear the live-output mark only when the response is source 'mux-full-history', on the scroll and tab-switch paths. - Repair on any upward scroll in a marked non-shell session, not only from the bottom. A content anchor (3-row signature, searched at most 2000 rows either side) keeps the row being read in place; no match falls back to distance from the bottom. - Tie replay travel to its session so a tab switch does not swallow moves on the new tab. - Reveal the partial-history notice when the initiating gesture reached the top, even if the anchor moved the viewport off row 0. - Touch-only Reload history button (#historyReloadBtn), styled in styles.css so wide touch viewports get it too. Non-touch pages skip its work entirely. - Docs, JSDoc and a changeset. Unit tests, and a Playwright browser test with trusted touch events and real xterm. Fixes Ark0N#814
|
@Ark0N I've updated the PR with your recommandations + ported the fix for mobile |
|
Thanks for the update, Hadrien, and for writing out the upside and downside of each change. This revision repairs the tmux repaint gap from #814 on any upward wheel or touch scroll in a non-shell session that has had live output since its last full capture. It holds the line being read in place with a content anchor and adds a touch-only "Reload history" button. All six code points from the earlier review are addressed. The load opens before the fetch and every exit flushes the queue, the mark is cleared only on The open design questionThe question from the earlier review is still open, and this commit widens it: whether the history repair may run before the top of the buffer, and on which signal. With this commit, once the 4 s cooldown has passed, any upward scroll anywhere in a session that has had live output since its last full pull runs an unbounded Code pointsThe first two come from the Reload history button. Both were confirmed in a real Chromium page.
Smaller ones:
NextThe trigger question is open, so the PR stays as it is for now. Points 1 to 5 apply as long as the Reload history button and this recovery path are part of it. |
Ark0N#814) - Scrolling pulls tmux history only at the top of the buffer again (Ark0N#205); the automatic pull on any upward scroll is removed. - Reload history lives in the existing #historyTruncationBar on desktop and touch, shown for a marked non-shell session scrolled away from live output. It never duplicates Load full history; one × dismisses what the bar carried. - New per-device setting historyReloadAction (Terminal & Input > Scrolling & rendering), default on, kept out of SettingsUpdateSchema. - Eligibility sync is transition-only and onScroll is coalesced per frame. - Remove the floating #historyReloadBtn and its z-index 20 layer. - Deferred dropped-output recovery resumes at its saved attempt. - zh-CN entries for the new strings; docs and changeset updated.
|
@Ark0N, thanks for the second review. Here is my answer to the design question, and the PR is reworked to match ( Decision: no automatic early pull. The early repair is a manual action.Before answering I measured the tmux side: tmux 3.4 on a private socket, attached through node-pty the way Codeman does (
Cost on 100k lines of 120 characters:
Writing the 12 MB capture into headless xterm took another 0.56 s. What I take from it:
So the PR now does this:
Your second review, points 1 to 5
On
The PR description has the details; the earlier versions are folded underneath. Possible follow-ups, your call and not in this PR: a bounded capture with a client-side splice would make an automatic early repair affordable. A |
|
Thanks for the third round, Hadrien, and for the tmux measurements in the thread. This revision keeps scrolling top-only as on master and adds a manual Reload history action to the existing history banner, together with the content anchor, the load opened before the fetch, the mux-only clear and a per-device setting. You addressed every point from both earlier reviews. Typecheck, lint, format, the frontend checks, the full test suite (17183 tests) and both browser files pass here, and 52 of the new unit tests fail against master's frontend code as intended. Needs a fix
Smaller ones
Open questionOne design point is still open, and it is not something to change in this round. The action ships ON by default and keys on any live output, so in a working session the bar appears on nearly every scroll-up, covers the top rows being read and is announced by Once 1 to 4 are in, the PR is ready for another review. If you can try the #814 recipe (40 slow lines, then 500 at once) in a real non-shell session, please post the before and after in the thread. |
…0N#814) - Reload history requires pane history and no buffer load in flight; a downgrade-refused pull hides it until the next mux-full-history replay, and a stale tap re-checks eligibility before fetching. - x during Loading... hides the bar at once; the pull continues. - The content anchor scores up to 64 visible rows, so repeated TUI borders cannot outvote the row being read; ambiguous matches keep the viewport. - Live flushes track the reading row with an xterm marker across scrollback trimming at the cap. - Docs: Settings-Reference row, Dashboard notice text, ~1 s capture cost, byte-history replays rely on the top-of-buffer pull.
|
@Ark0N, thanks for the third review. The PR is updated ( Points 1 to 6
Two other fixes found while testing
Tests
On
I haven't yet run the #814 recipe in a real non-shell session; I'll post the before and after in the thread when I have. Open question: on by defaultI'd keep it on by default. Without this action, the only way to see output that has fallen outside the screen is to scroll all the way up to the top of the buffer, every time, to trigger the full-history pull. That is the #814 symptom itself: the history looks broken until you find that workaround. A default-off action would leave most users with that, and they wouldn't know there is a setting to change. The bar only appears while you are scrolled up in a session that has had output since its last full capture, and anyone who finds it in the way can turn it off per device in Settings > Terminal & Input > History Reload Button. |
Ark0N#814) - _historyReloadActionEligible() no longer reads _paneHistoryLines: it is recorded at the last load, so a session first opened empty kept 0 after the burst that opens the gap, and the action never appeared (found by the live Ark0N#814 recipe). - A pane with no tmux history is still retired by the downgrade refusal, which dismisses the action until the next mux-full-history replay.
|
Thanks for the fourth round, Hadrien, and for answering the default question directly. This revision keeps the manual Reload history action in the history banner and closes the points from the third review. It also makes the content anchor hold up against repeated TUI borders, and an xterm marker now keeps the reading row in place at the scrollback cap. Every point from the third review is in. Typecheck, lint, format, the frontend syntax, dead-code and browser-excludes checks, the full test suite (17,192 tests) and both browser files (13 tests) pass here. 13 of the new unit tests and the new browser case at the 50k cap fail against Needs a fix
Smaller ones
Open questionThe default is still undecided: Reload history could ship ON keyed on any live output, ship OFF, or be offered only after a burst signal such as a full-screen NextPoint 1 is the only code fix this round needs, and points 2 and 3 are small. The default question above is still open. |
|
@Ark0N, here is the #814 recipe run live, before and after, as you asked. Setup
for i in $(seq 1 40); do echo slow-$i; sleep 0.1; done; seq -f burst-%g 1 500
Results
The gap size differs from run to run, since it depends on how tmux samples the burst. Either way the browser kept a fraction of the 540 lines while tmux held all of them, and a mid-history wheel scroll on master shows rows jumping from A bug the run found, now fixedOn
The reading position on that runThe top visible row was After the reload, scrolling to the bottom and back up with no new output did not bring the button back, since the mark had been cleared. Checks on
|
…#814) - _historyReloadActionEligible() also requires no terminal load state: selectSession sets it before switching activeSessionId, so the sync right after the switch no longer offers Reload for the loading tab. - _clearTerminalLoadState() re-syncs the action, so a marked tab offers Reload once its load ends. - Changeset: note the reading-position fix for live flushes at the scrollback cap.
|
@Ark0N, thanks for the fourth review. The PR is updated ( Point 1: Reload history during the incoming tab's loadFixed as you suggested:
Tests:
Point 2: release note
Point 3: the #814 recipePosted just after your review, in this comment. It has the live before and after: real isolated Codeman servers, real tmux captures through Reload history, no stubbed Checks on
|
- A content-anchored reload answered by anything but mux-full-history (an empty response, or the byte-history fallback for a blank or failed pane capture) adds the session to _historyReloadDismissed until the next mux replay; only a mux replay clears the mark, so each tap repeated a forced, unbounded capture. An error envelope leaves it available. - Only the request still current (active session and select generation) may dismiss: a slow answer from before an A -> B -> A switch must not retire the action a newer capture already cleared.
|
@Ark0N, one follow-up on top of When
Tests in On |
|
Thanks for the fifth round, Hadrien, and for running the #814 recipe live with real captures. This revision keeps Reload history off while the incoming tab loads, adds the reading-position fix to the release note, and retires the action when a manual reload comes back with anything but a full mux capture. Every point from the fourth review is in. Typecheck, lint, format, the frontend syntax, dead-code and browser-excludes checks, the full test suite (17,199 tests) and both history browser files (14 tests) pass here. Two of the new tests from Small ones
Open questionThe default is still undecided: Reload history can ship ON keyed on any live output, ship OFF, or be offered only after a burst signal such as a full-screen NextPoints 1 to 3 are the only changes this round needs. |
) - _onSessionNeedsRefresh samples the live-output generation before its fetch and, after replaying a mux-full-history capture, clears _liveOutputSinceFullPull and _historyReloadDismissed while it still owns the active session and the generation is unchanged; the ?tail= fallback never clears them. - test/terminal-viewport-marker.test.ts: gated test driving the real flushPendingWrites over @xterm/headless at a full scrollback; the reading row holds with the marker and drifts without it. - Docs: the anchor sentence matches minimumScore, and the refresh rule is in the Repair while reading paragraph.
|
@Ark0N, thanks for the fifth review. The PR is updated ( Point 1: a gated test for the scrollback-cap fixNew
Point 2: the drop-recovery refresh clears the mark
The Tests in
The first one fails with the clear removed. Point 3: the anchor sentence
Checks on
|
|
Thanks for the sixth round, Hadrien, and for the gated marker test. This revision clears the Reload mark after a drop-recovery capture, adds All three points from the fifth review are in. Typecheck, lint, format, the frontend syntax, dead-code and browser-excludes checks, the full test suite (757 files, 17,207 tests) and both history browser files (14 tests) pass here. The new drop-recovery test fails against Small onesThese don't depend on the open question below.
Open questionThe default for Reload history is still open. The options are to ship it ON keyed on any live output, ship it OFF, or offer it only after a burst signal such as a full-screen NextEvery code point from the earlier reviews is addressed, and the three small ones above are the only code changes needed this round. The default is the one open item left. |
…rk0N#814) - _onSessionNeedsRefresh adds the session to _historyReloadDismissed when the full capture would shrink the buffer and it falls back to ?tail=, past the ownership guard, so a no-history pane is not re-captured by the next tap. - Changeset: scope the note to agent sessions (seen with OMP). - CLAUDE.md: one warning sentence on the Reload history rules. - terminal-resilience test reads each whole method instead of a 4,000-character window.
|
@Ark0N, thanks for the sixth review. The PR is updated ( Point 1: the drop-recovery fallback retires Reload historyWhen Two rows in the drop-recovery tests in
The first one fails with the new branch disabled. The invariants paragraph mentions the rule next to the clear. Point 2: changeset wording
Point 3:
|
|
Thanks for the seventh round, Hadrien. This PR repairs the tmux repaint gap from #814 with a manual Reload history action in the history banner, which re-pulls the full tmux history and keeps the line you are reading where it was. The three points from the sixth review are all in:
Typecheck, lint, format, and the frontend syntax, dead-code and browser-excludes checks pass here, and so do the full test suite (757 files, 17,208 tests) and both history browser files (14 tests). With the One small one
The notice stays revealed until a downward scroll reaches live output. Someone who reached the top, scrolled partway back down and then got new output is shown this button, where Reload history would have kept their place. Please make two changes:
Open questionThe default for Reload history hasn't been decided. The options are:
That is a product decision, and it has not been made yet. The anchor point above doesn't depend on it. NextThe default is the one open item. The anchor fix is the only code change this round asks for. |
… Reload (Ark0N#814) - The notice's Load full history button pulls with anchor 'content' when Reload history is eligible (read at click time, since the bar only re-renders on eligibility transitions) and keeps 'top' otherwise. - Tests: the single load control asserts the content anchor; an ineligible session keeps the top anchor.
|
@Ark0N, thanks for the seventh review. The PR is updated ( Load full history keeps the reader's line when Reload is eligible
I read eligibility at click time ( Tests in
The invariants paragraph describes the rule. Open questionNoted that the default is still your decision. Checks on
|
|
Thanks for the eighth round, Hadrien. This PR repairs the tmux repaint gap from #814 with a manual Reload history action in the history banner, which re-pulls the full tmux history and keeps the line you are reading in place. The point from the seventh review is in: Load full history now pulls with the content anchor when Reload history is eligible (read at click time), and the new test pins both anchors. Typecheck, lint, format, and the frontend syntax, dead-code, browser-excludes and public-asset checks pass here. So do the full test suite (757 files, 17,209 tests) and both history browser files (14 tests). Two small ones
Open questionThe default for Reload history is still open. The options are:
That is a product decision, and it has not been made yet. Points 1 and 2 above do not depend on it. NextPoints 1 and 2 are the only code changes this round asks for. The default is the one open item. |
…coveries (Ark0N#814) - _restoreViewportAnchor searches expected - 4000 + rows .. expected + rows (same 4,001 candidates / 4,064 reads): filled rows only move the reader up, so gaps up to 4000 - rows land exactly, also at the scrollback cap. - _resetAllAppState and _cleanupPreviousSession clear _pendingDroppedOutputRecovery next to the recovery timer, so a reconnect load does not resume a stale recovery and run a second full capture. - Tests: capped 2,500- and 3,900-row gaps; both real cleanup methods drop the pending recovery. Docs: the window and the beyond-window fallback.
|
@Ark0N, thanks for the eighth review. The PR is updated ( Point 1: the anchor window leans up
Tests in
The "Repair while reading" paragraph describes the window. It also says what happens to a wider gap: the match falls outside, the restore keeps the old absolute index, and at the cap that lands the reader the whole gap below their line. Point 2: a deferred recovery no longer survives a reset
New test in Open questionNoted that the default is still your decision. Checks on
|
Fixes #814.
Current version (
21582a77): eighth review addressed, #814 recipe run liveSame design as
b052d686(folded below): scrolling pulls history only at the top, and the early repair is a manual Reload history action in the existing history banner, on by default and toggleable per device.73364f8daddresses the third review and fixes two reading-position problems found while testing.ebba82e5fixes a regression the live #814 run found in73364f8d(see point 1 and the thread).408894a3addresses the fourth review,0e5170e8retires Reload history after an answer that is not a full mux capture,afab324baddresses the fifth review,982a11e3the sixth,9f5c6683the seventh and21582a77the eighth (see the thread).Eighth review, points 1 and 2
_restoreViewportAnchorsearchesexpected - 4000 + rowstoexpected + rows(same 4,001 candidates, at most 4,064 line reads), so gaps up to4000 - rowsfilled below the reader land exactly, including at the scrollback cap._resetAllAppStateand_cleanupPreviousSessionclear_pendingDroppedOutputRecoverynext to the recovery timer, so a reconnect's own load does not resume it.Seventh review
anchor: 'content'(eligibility read at click time), so the reader keeps their line; otherwise it keepsanchor: 'top'.Sixth review, points 1 to 3
_onSessionNeedsRefreshfalls back to?tail=because the full capture would shrink the buffer, it adds the session to_historyReloadDismissedpast the ownership guard, so a no-history pane is not re-captured by the next tap.CLAUDE.md. OneAlso: the
terminal-resilience"every replay path clears through that helper" test reads each whole method instead of a 4,000-character window, which point 1's comment had pushed the reset call past.Fifth review, points 1 to 3
test/terminal-viewport-marker.test.ts(innpm test) drives the realflushPendingWritesand_restoreTerminalViewportover@xterm/headless6.0.0 at a full scrollback: the reading row stays online 140with the marker and ends online 160without it._onSessionNeedsRefreshclears_liveOutputSinceFullPulland_historyReloadDismissedafter replaying amux-full-historycapture, while it still owns the active session and the live-output generation sampled before its fetch is unchanged. The?tail=fallback never clears them.minimumScore: a viewport with one distinct row matches on that row alone.Fourth review, points 1 to 3
_historyReloadActionEligible()also requires!this.terminalLoadStates?.has(sessionId);selectSessionsets that state before it switchesactiveSessionId._clearTerminalLoadState()re-syncs the action, so a marked tab offers Reload once its load ends.flushPendingWritesreading-position change, which applies in every mode with the setting on or off.Third review, points 1 to 6
_replayWouldShrinkBufferadds the session to_historyReloadDismisseduntil the next successfulmux-full-historyreplay, so a pane with no tmux history (fullscreen Claude in the alternate screen) stops offering Reload after one refused tap. A tap on a stale button re-checks eligibility before fetching.73364f8dalso required_paneHistoryLinesnot to be 0; the live run showed that this value is recorded at the last load, so a session first opened empty kept 0 after the burst and never offered Reload.ebba82e5removes that check._isLoadingBuffer. Part of eligibility;_finishBufferLoadre-syncs the action, so a marked tab offers Reload after its own load, not during it.?tail=replay never marks the session, so that gap relies on the top-of-buffer pull.docs/wiki/Settings-Reference.md;docs/wiki/The-Dashboard.mddescribes Reload history in the same bar and says it is withdrawn after a reload that finds nothing more, as for fullscreen Claude.docs/architecture-invariants.mdand the_maybeRefetchFullHistoryJSDoc.Also fixed
viewportYmoved the reader up on every flush.flushPendingWritesnow tracks the row with an xterm marker.Tests
test/shell-scroll-history-pull.test.ts:_isLoadingBufferand a terminal load state in the eligibility table, and a stalepaneHistoryLines: 0that must not hide the action; clearing the matching load state shows the action; a refused pull retires the action and a stale second tap does not fetch; the action appears when a marked session's load finishes; × during Loading… keeps the bar hidden after the pull; anchor cases for repeated borders, ambiguous copies, a lone distinctive row among blanks and the 50k-row bound.test/history-gap-repair.browser.test.ts: real xterm with OMP-like repaint history (CSI Splus cursor-addressed redraws) at a 50,000-row scrollback cap; the reading row keeps its offset through the replay and a later live flush. A tab switch to a marked session with its capture held open shows no Reload history until the load finishes.strip-mux-onlysession runningbash): on master the browser kept a fraction of the 540 lines and only a scroll to the top repaired them; onebba82e5Reload history appeared mid-history and one click restored all 540 in order. Numbers in the thread.Checks run on
21582a77npm run build,typecheck,lint,format:check,check:frontend-syntax,check:frontend-dead,check:browser-excludes: pass.npm test: 757 files passed, 1 skipped; 17213 tests passed, 13 skipped, 0 failed.npx vitest run --config config/vitest.browser.config.ts test/history-gap-repair.browser.test.ts test/capture-load-window.browser.test.ts: 14/14.Not done
Third version (
b052d686): manual Reload history action, no automatic early pullThe design question from the review is answered in the comment on this PR: I drop the automatic early pull. Below is what the current version does. The two earlier versions are folded underneath.
What it does
Scrolling is top-only again.
_maybeLoadMoreHistoryOnScrollpulls only when the viewport reaches row 0, as on master (Scrollback in terminal not working #205). The repair branch on any upward scroll is gone, and so is its notice-reveal change. A pull still starts only at the top. After a pull that grows the buffer and puts the reader back below row 0, the notice is now still revealed."Reload history" in the existing
#historyTruncationBar, on desktop and touch. It is offered when all of these hold:mux-full-historyreplay);A tap runs
_maybeRefetchFullHistory({ force: true, anchor: 'content' }), the same explicit-choice path as "Load full history". If the revealed notice already offers "Load full history", no second load control is added. Otherwise "Reload history" is added to the notice, or shown alone with "Recent output may be missing from this view." One × dismisses what the bar carried: the notice for the page, as before, and the reload action until the next successfulmux-full-historyreplay clears the mark.Setting. "History Reload Button" in Settings > Terminal & Input > Scrolling & rendering (
historyReloadAction). It is per device, on by default, wired liketerminalWheelLocalScrollback(load, save, stripped from the PUT, in_displaySettingKeySet()), and not inSettingsUpdateSchema.Kept from
0f890a97:mux-full-history;_earlyReplayTravel, which still records travel during a tapped replay.Second review, points 1 to 5
#historyReloadBtnis removed. The action lives inside the banner, so nothing overlaps it._syncHistoryReloadAction()re-renders the banner only when eligibility, the active session or the loading state changes;terminal.onScrollis registered on all devices and coalesced to onerequestAnimationFrameper frame;isTerminalAtBottom()._pendingDroppedOutputRecoveryis now{ sessionId, attempt }, and_finishBufferLoadresumes at that attempt.Tests
test/shell-scroll-history-pull.test.ts:mux-full-historyreplay;test/history-notice-reveal.test.ts: the notice is revealed only from a top pull, including when the replay grows the buffer.test/settings-admin-only-ui.test.ts: the setting loads, saves, stays per device and is never sent to the server.test/history-gap-repair.browser.test.ts(Playwright, real xterm, touch and desktop contexts):elementFromPointon each banner button returns that button;Checks run on
b052d686npm run build,typecheck,lint,format:check,check:frontend-syntax,check:frontend-dead,check:browser-excludes: pass.npm test: 756 files passed, 1 skipped; 17183 tests passed, 13 skipped, 0 failed.npx vitest run --config config/vitest.browser.config.ts test/history-gap-repair.browser.test.ts test/capture-load-window.browser.test.ts: 12/12.Not done
_pullHistoryinterminal-tile.js) are unchanged and keep the top-only pull.Second version (
0f890a97): automatic pull on any upward scroll, touch-only floating buttonUpdate: the phone case and the review on this PR
The first version of this PR only repaired the gap when a scroll-up started at the live bottom. On a phone that's not how it's used: you scroll up, keep reading while OMP keeps writing, and a new gap opens below where you are (the case confirmed on #814). The bottom-only trigger never fires there, so on a smartphone the fix did nothing in practice.
The new commit,
0f890a97, changes the trigger to any upward scroll and adds a touch-only reload button. It also addresses the six points of the review on this PR. Each change is described below with what it does, the upside, the downside and what's missing.What I measured before changing the trigger
These are measurements with plain tmux 3.4 and
@xterm/headless6.0.0 (the version Codeman ships), outside Codeman:status off, 40 lines printed slowly then 500 at once. The attached client's stream had manyCSI n S(including the full-screenCSI 24 S) and only carried 94 to 268 of the 540 lines. After feeding that stream into xterm with the alt-screen switches stripped (whatstrip-mux-onlydoes), the browser heldbaseY20 to 25. tmux heldhistory_size517. Only a re-pull from tmux brings those rows back.CSI Sand lost nothing.I did not switch the trigger to a
CSI Sburst signal. I only checked that slow output sends none, not that every gap comes with one, so it's not proven as a gap detector. The trigger stays "any live output since the last full pull", the same signal as before.The changes
1. The buffer load opens before the capture fetch (review point 1)
What it does.
_maybeRefetchFullHistorycalls_beginBufferLoad()before_fetchTerminalCaptureand passes that owner token tochunkedTerminalWrite. Before, the third argument was the session id. Live output arriving while the capture downloads now goes into_loadBufferQueueinstead of the old buffer. A replay keeps the existing header-time cutoff (_bufferLoadFinishOpts). Every other exit flushes the whole queue into the untouched buffer through a singlefinally(_finishBufferLoad(owner, { flushQueued: true, since: 0 })): no buffer, tab switch, bounded-shell skip, downgrade refusal, orcatch. A stale owner (a tab switch took over) is a no-op there.Holding the queue for the whole download has a side effect: in a busy session it can now hit the 128 KiB cap in
_onSessionTerminal. A dropped frame calls_scheduleDroppedOutputRecovery, and_onSessionNeedsRefreshrefuses to run while_isLoadingBufferis set. So the recovery could burn its five attempts (2 s apart) against our own open load, and the dropped frames would never come back. It now remembers a pending recovery for the active session without spending an attempt (_pendingDroppedOutputRecovery), and_finishBufferLoadresumes it when the load ends.Upside. Your scratch test confirmed that rows written during the download used to be wiped by
_resetTerminalForReplay(). They're kept now, and appear exactly once. This is the same patternselectSessionalready used.Downside. For the length of the download, live output is held back from the screen instead of written right away. On a slow link and a large capture that's visible as the terminal pausing, then catching up. Drop recovery now has a deferred state, which is one more piece of state in a path that has already had bugs (#464).
Missing. The duplicate window described in
_bufferLoadFinishOpts(a batch already pending when the capture ran comes after the headers and is replayed) is unchanged. Its fix belongs on the server.2. The mark is cleared based on what came back (review point 3)
What it does. Both clears of
_liveOutputSinceFullPullnow also requiresource === 'mux-full-history': the scroll re-pull and the tab-switch?full=1load. Afull=1that fell back to the byte history (source: 'history') carries the same hole, so it keeps the session marked. The generation check stays, so output newer than the capture also keeps the mark.Upside. A capture failure no longer passes for a repair.
Downside. If captures keep failing for a session, each later upward scroll asks again (at most every 4 s). Nothing loops on its own; every attempt needs a gesture.
Missing. Nothing known.
3. The repair runs on any upward scroll, not only from the bottom
What it does.
_maybeLoadMoreHistoryOnScrolldrops theviewportY >= baseY - 2 - |lines|condition. A marked non-shell session now repairs on any upward scroll: mid-history, near the bottom, or at the top, with one pull per gesture. The guards inside_maybeRefetchFullHistoryare unchanged: 4 s cooldown, 60 s useless-pull latch,_replayWouldShrinkBuffer, select generation, detached sessions and tiles. An unmarked session still pulls only at the top, as in #205. Shell is unchanged.anchor: 'bottom'is replaced byanchor: 'content'. Before the reset,_captureViewportAnchor()records the first non-empty row in the viewport, the two rows after it, its offset in the viewport and the distance from the bottom. After the replay,_restoreViewportAnchor()looks outward from the expected row for the nearest 3-row match and puts that row back at the same offset. If none matches it uses the nearest first-row match, and failing that the distance from the bottom. The search is bounded: at most 2,000 rows either side of the expected row, so 4,001 candidates and 12,003 line reads at most.The partial-history notice: a marked pull started from mid-history doesn't reveal it. A pull whose gesture had reached row 0 does, even if the anchor then moves the viewport off row 0.
Upside. This is the case that was broken on phones: a gap opening below the reader is repaired on the next upward scroll, without going back to the bottom first. The line being read stays where it was, even when recovered rows land below it (keeping the distance from the bottom can't do that, because the bottom moves).
Downside. This widens the cost you raised in the review. In an active session, nearly every upward scroll more than 4 s after the last pull runs an unbounded
?full=1:capturePaneBufferthroughexecSyncover up to 100k lines, about 0.3 s on the event loop for every client and session (docs/architecture-invariants.md). The browser then resets and replays while the user reads. That's now true from anywhere in history, not just from the bottom. The anchor is a text heuristic: on very repetitive TUI output (borders, separator rows, identical status lines) the nearest match can be the wrong copy, and it falls back to the distance from the bottom. The pull can still flicker during the replay.Missing.
lines=capture could only work if the replay could splice rather than reset, and_replayWouldShrinkBufferrefuses a short capture today._pullHistoryinterminal-tile.js) are untouched and keep the top-only behaviour.4. Replay travel is tied to its session (review point 6)
What it does.
_earlyReplayTravelis now{ sessionId, moves: [] }. Moves are recorded only while that session is active; on another tab they go through the normal path. Thefinallyalways resets it.Upside. After a tab switch takes over an in-flight repair, scrolling on the new tab is no longer swallowed until the old replay settles.
Downside. It's still a single app-level field. That works because one pull at a time is guaranteed by
_fullHistoryRepullInFlight.Missing. Nothing known.
5. "Reload history" button for touch devices
What it does.
#historyReloadBtninindex.html: a floating button at the top right of the terminal, at least 44×44 px,aria-label="Reload history", styled instyles.css. It isn't inmobile.css, because that sheet is only loaded below 1024 px and a landscape tablet would get an unstyled button that takes room from the terminal._syncHistoryReloadButton()alone decides whether it shows. It shows when all of these hold: touch device, non-shell session, viewport not at the bottom, session marked, no tiles, no pull in flight. Tapping it runs_maybeRefetchFullHistory({ force: true, anchor: 'content' }), showing "Loading…" while it runs. The button is updated on terminal scroll (listener registered only on touch devices), when a session is first marked influshPendingWrites, at the end of a pull, and on tab switch. On a non-touch page the method returns at its first line.Upside. It gives a phone user a direct way to repair, independent of how they scroll and of the 4 s cooldown (
force). It's only shown when there is probably something to recover.Downside. One more piece of UI over the terminal: it covers part of the top-right rows while it's visible. It shows whenever the session is marked, even if the gap may not exist (same proxy as change 3).
forceskips the cooldown, so repeated taps each run a full capture on the server; each tap waits for the previous one to finish (disabled, plus the in-flight guard).Missing. No translation; the label is in English like the rest of the UI. It doesn't hide while the user is actively swiping. Nothing on desktop, by design.
6. Docs and changeset (review point 4)
What it does.
docs/architecture-invariants.md(Full-scrollback replay) gets a "Repair while reading (#814)" paragraph covering:mux-full-history-only clear;The JSDoc of
_maybeRefetchFullHistoryand_maybeLoadMoreHistoryOnScrollno longer says "only at the top" or "on demand rather than automatic"..changeset/814-history-repair-while-reading.mdis a patch.Missing.
npx prettier --check docs/architecture-invariants.mdflags about twenty spots that were already in the file; I only fixed the one I added.format:checkonly coverssrc/**.Tests (review points 2 and 5)
test/shell-scroll-history-pull.test.ts(VM, mocked xterm). The #814 block is rewritten for the new contract:_isLoadingBufferfalse afterwards;source: 'history'and cleared onmux-full-history, for both the scroll pull and the realselectSession;getLinecalls stays within it;test/history-notice-reveal.test.ts: the notice for a marked pull started from the top versus from mid-history.test/history-gap-repair.browser.test.ts(new, Playwright, real xterm, listed inBROWSER_TEST_GLOBS). It uses ahasTouch/isMobile390×640 context and trusted CDP touch events (Input.dispatchTouchEvent). Live output goes through the real_onSessionTerminal→batchTerminalWrite→flushPendingWritespath. The burst is shaped like tmux's:CSI 24 S, then a repaint of the last 24 rows, with the middle lines never sent./terminalis stubbed with amux-full-historycapture. Five scenarios:json()): present exactly once.This test was flaky at first. The cause was the test setup, not the app: its forced
terminal.resize(80, 24)disagreed with the fitted 62×36 container, so the existing resize path (terminal-ui.js,\x1b[3J\x1b[H\x1b[2Jon a real size change) cleared the seed rows. The setup now waits for startup, font and render readiness, and a size that holds across frames before it seeds anything. On failure it dumps the state (baseY, queues, load owner, generations). It passed 3 full runs in a row.Checks run
On this branch, commit
0f890a97:npm run typecheck,lint,format:check,check:frontend-syntax,check:frontend-dead,check:browser-excludes: pass. The pre-push hook passed.npm run build: pass.npm test:file-browser-searchchecks that_activateFileBrowserSessionis called right afterthis.activeSessionId = sessionId; I moved my call one line down, and it passes now.tab-layout-editing,webhook-push-glue,webview-sse) and pass on rerun.spreadsheet-preview-worker("2,000,001 empty runs") also times out ona9a3c6f3without this commit. The machine was at load 11 to 25 on 4 cores.terminal-flush-budget,mobile-ime-preview-structureandfile-browser-search), and both browser files (7 tests).npx vitest run --config config/vitest.browser.config.ts test/history-gap-repair.browser.test.ts test/capture-load-window.browser.test.ts: 7/7.Manual check
The same change, ported onto a local 1.51.0 install (with this PR's first two commits under it), passes the same targeted tests and both browser files. It's built into that install. I haven't watched it on a real phone yet. The phone-only behaviour (swipe, button, on-screen keyboard) is covered only by the emulated touch test above. I'll report back after using it.
What's left to decide
The design question from your review is still open, and this commit makes it harder to avoid: is "any live output → unbounded full capture on any upward scroll" an acceptable cost? If not, the cheapest path I see is on the server: serve
?full=1from an asynchronouscapture-pane, or a bounded one with a client-side splice. That would make this trigger much cheaper without changing the client contract. I didn't do it here because it changes the server's hot path.Original description (first two commits, ede2d9f and a9a3c6f)
Problem
In a non-shell session (seen with OMP), scrolling up from the live screen shows a hole: recent output just above the screen is missing and the rows jump to older history. tmux still holds those rows. When output outpaces tmux's flush interval, tmux repaints the pane rectangle instead of emitting linefeeds, so rows that were on screen get overwritten and never reach xterm's scrollback. The repair for this (#205,
_maybeRefetchFullHistory) only runs when the viewport reachesviewportY === 0. The gap sits near the bottom of the buffer, so the user has to scroll past it to the top before the history is fixed.What this changes
Frontend only:
src/web/public/app.jsandsrc/web/public/terminal-ui.js.flushPendingWritessets_liveOutputSinceFullPulland increments_liveOutputGen[sessionId]for every live chunk it writes, but not while_isLoadingBufferis set, because a replay cannot open a new gap. A full-history replay clears the flag only if the generation has not changed since its capture could have been taken. The scroll re-pull samples the generation before its fetch, because nothing gates live output while the capture downloads. The tab-switch?full=1load samples it at the replay, because it already queues live output during its fetch, and it clears the flag only if itcompletedwithout falling back to the tail. Live output newer than the capture therefore keeps the session marked, and the next scroll-up pulls again._maybeLoadMoreHistoryOnScroll. If the gesture is upward, started at the live bottom (viewportY >= baseY - 2 - |lines|, which allows for the travelscrollLinesalready applied), the session is notshelland is marked, and no pull or load is running, it calls_maybeRefetchFullHistory({ anchor: 'bottom' }). This hook is only reached from Codeman's own wheel, touch and smooth-scroll routes. Scrollbar drags and keyboard scrolling do not get the early repair, and still depend on the unchanged top-of-buffer path, as before.anchor: 'bottom'in_maybeRefetchFullHistory. The existing restore keeps the position measured from the top, which is right when the user is at row 0. Here the user is a few rows above the live screen, so the restore keeps the distance from the bottom instead. While the replay runs, the reset buffer cannot scroll. Wheel and touch moves are recorded in order in_earlyReplayTraveland replayed once the replay ends, each clamped to[0, baseY]as it would have been live, so scrolling down to the bottom and back up does not cancel out. That way the gesture is neither lost nor fed into the top-of-buffer path partway through. If that travel reaches the top, the partial-history notice is still shown.The existing guards still apply unchanged: the 4 s cooldown, the 60 s latch after a useless pull,
_replayWouldShrinkBuffer, the select-generation check, detached sessions, and tiles.Why this shape, and what I rejected
baseYwith_paneHistoryLines. I did not do that._paneHistoryLinesis recorded at tab switch, so it is stale exactly when it matters, after a burst. A fresh#{history_size}would need a probe round trip, and probably a new server route, for every scroll-up. The dirty flag is free and always current. The cost is that it is a coarser proxy (see below).Downsides and risks
?full=1capture: tmuxcapture-paneover up tohistory-limitlines on the server, plus a full reset and chunked replay in the browser. The cooldown limits this to one pull every 4 s, and the flag limits it to once per batch of output. On a long session this is still far more capture traffic than before, when it happened only at the top of the buffer. On mobile data it also costs bandwidth. I think this is the main thing to review._replayWouldShrinkBufferand latched for 60 s. That is correct, but it still costs one wasted capture per minute per session on scroll-up. The test for this case checks that the buffer is not reset and the flag stays set._earlyReplayTravelis one app-level field, not per session. It works because only one pull can run at a time (_fullHistoryRepullInFlight) and thefinallyalways resets it. It is still shared state that a future concurrent path could break.Tests
New
describeblock intest/shell-scroll-history-pull.test.ts("early full-history recovery above live output (#814)"). It covers:The shared
makeAppfixture now setsviewportY: 0, because the scroll path reads it. The reversal and download-time tests fail on the previous version of this branch and pass now.These are VM-loaded unit tests with a mocked xterm. They pin the logic but not real xterm behavior during a reset and replay, nor the real buffer-load queue. They do not cover an early replay cancelled by a tab switch, or the tab-switch path clearing the flag. No browser test covers this path. I did not run
npm run test:browser.Run on this branch (based on
master@e99b42c3):npm test(on the first commit): 757 files, 17130 passed, 13 skipped, 1 failed. The failure isfrontend-public-tooling.test.ts > runs the public asset check script. It failed because my worktree lacked the gitignoredsrc/web/public/vendor/*bundles thatpostinstallbuilds. With those copied in, the file passes 4/4. It is unrelated to this change.npm run lint,format:check,typecheck,check:frontend-syntax,check:frontend-dead,check:browser-excludes: pass on both commits. The pre-push hook passed on the second push.npm run build: passes.Manual verification: not done
The first commit was built into a local 1.51.0 install (Linux, tmux 3.4, OMP 18.20.0, Zen Browser), but I have no recorded before/after observation that it removes the gap. The follow-up commit has not been run in a browser at all. Please treat the behavior as unverified until someone reproduces #814 and checks that the first scroll-up after an OMP burst shows the recent rows without a jump.