Merge pull request #536 from nwparker/cloud/reg13-wake-scroll-anchor

fix(cloud): REG-13 a scroll during a wake keeps its line after attach
This commit is contained in:
Neil
2026-11-12 05:59:56 -08:00
committed by GitHub
4 changed files with 118 additions and 8 deletions
@@ -0,0 +1,36 @@
import { Terminal } from '@xterm/headless'
import { describe, expect, it } from 'vitest'
import { wakeAnchoredRow, wakeAnchorText } from './cloud-wake-scroll-anchor'
/** A real terminal holding `rows`, one per line, with room for all of them. */
async function terminalWith(rows: string[]): Promise<Terminal> {
const terminal = new Terminal({ cols: 20, rows: 4, scrollback: 100, allowProposedApi: true })
await new Promise<void>((resolve) => terminal.write(rows.join('\r\n'), resolve))
return terminal
}
// REG-13: the line a person scrolled to during a wake is found again by its text, nearest its old row.
describe('wake scroll anchor', () => {
it('reads a row without trailing blanks, and null for an empty or unreadable one', async () => {
const terminal = await terminalWith(['ok ', '', 'next'])
const active = terminal.buffer.active
expect(wakeAnchorText(active, 0)).toBe('ok')
expect(wakeAnchorText(active, 1)).toBeNull()
expect(wakeAnchorText({}, 0)).toBeNull()
})
it('picks the occurrence nearest the old row when the line repeats (repeated log lines)', async () => {
const terminal = await terminalWith(['tick', 'a', 'b', 'tick', 'c', 'd', 'e', 'f', 'tick', 'g'])
const active = terminal.buffer.active
expect(wakeAnchoredRow(active, 'tick', 6)).toBe(8)
expect(wakeAnchoredRow(active, 'tick', 4)).toBe(3)
expect(wakeAnchoredRow(active, 'tick', 1)).toBe(0)
})
it('keeps the old row when the line is gone, or when nothing was anchored', async () => {
const terminal = await terminalWith(['a', 'b', 'c'])
const active = terminal.buffer.active
expect(wakeAnchoredRow(active, 'missing', 1)).toBe(1)
expect(wakeAnchoredRow(active, null, 2)).toBe(2)
})
})
@@ -0,0 +1,40 @@
// REG-13: a scroll made while a cloud pane wakes is kept by the top row's text, not its index. The
// restore rewrites the pane (history, divider, woken screen) and the rows above that line can
// differ in count from the preview the person scrolled, so the same index can land lines away.
import type { RestoreBuffer } from './cloud-wake-scrollback-render'
/** The text of row `y` with trailing blanks dropped, or null when it has none. */
export function wakeAnchorText(
buffer: Partial<Pick<RestoreBuffer, 'getLine'>>,
y: number
): string | null {
const line = buffer.getLine?.(y)
if (!line) {
return null
}
let text = ''
for (let x = 0; x < line.length; x++) {
text += line.getCell(x)?.getChars() || ' '
}
text = text.trimEnd()
return text === '' ? null : text
}
/** The row holding `anchor` nearest to `near`, or `near` when no row holds it. */
export function wakeAnchoredRow(
buffer: RestoreBuffer,
anchor: string | null,
near: number
): number {
if (anchor === null) {
return near
}
for (let distance = 0; distance < buffer.length; distance++) {
for (const y of distance === 0 ? [near] : [near - distance, near + distance]) {
if (y >= 0 && y < buffer.length && wakeAnchorText(buffer, y) === anchor) {
return y
}
}
}
return near
}
@@ -340,6 +340,25 @@ describe('WAKE-SCROLLBACK', () => {
expect(active.getLine(active.viewportY)!.translateToString(true).trimEnd()).toBe('row 12')
})
// REG-13: the preview the person scrolled had 33 more rows above their line than the restore
// writes back (1922 came back as 1955); the line they read is found again by its text.
it('a scroll made while waking stays on the same line when the restore shifts rows', async () => {
const lines = Array.from({ length: 2000 }, (_, index) => String(index + 1))
const slept = pane(10)
await write(slept, `${lines.join('\r\n')}\r\n`)
capture(slept, 'leaf-1')
armWakeScrollback(['leaf-1'])
const preview = pane(10)
const extra = Array.from({ length: 33 }, (_, index) => `preview ${index}`)
await write(preview, `${[...extra, ...lines].join('\r\n')}\r\n`)
const top = 33 + 1921
preview.scrollToLine(top)
expect(preview.buffer.active.getLine(top)!.translateToString(true).trimEnd()).toBe('1922')
expect(await wake(preview, 'leaf-1', '$ ')).toBe(true)
const active = preview.buffer.active
expect(active.getLine(active.viewportY)!.translateToString(true).trimEnd()).toBe('1922')
})
it('a person who had scrolled up keeps their place instead of jumping', async () => {
const terminal = pane(5)
await write(terminal, Array.from({ length: 50 }, (_, index) => `row ${index}`).join('\r\n'))
@@ -2,6 +2,7 @@
// VM and the woken pane attaches to a new terminal whose snapshot replay erases scrollback; the
// output the pane showed before the sleep is written back above a "Slept 14:02–14:31 · processes
// stopped" divider, client-side only (nothing reaches the PTY), as rendered text + SGR.
import { wakeAnchoredRow, wakeAnchorText } from './cloud-wake-scroll-anchor'
import { translate } from '@/i18n/i18n'
import { parseRemoteRuntimePtyId } from '../../../../shared/remote-runtime/remote-runtime-pty-id'
import { isOrcaCloudEnvironmentId } from './orca-cloud-environment-id'
@@ -27,6 +28,8 @@ type PendingHistory = {
ptyId: string | null
/** The line the person had scrolled up to (kept across the wake's remount), or null at the bottom. */
scrolledTo: number | null
/** That line's text (REG-13: the restore can shift rows, so its text finds it again). */
scrolledText: string | null
}
/**
@@ -48,7 +51,7 @@ export type ScrollbackSource = {
rows: number
buffer: {
normal: RestoreBuffer & { baseY: number }
active?: { viewportY: number; baseY: number }
active?: { viewportY: number; baseY: number } & Partial<Pick<RestoreBuffer, 'getLine'>>
}
}
@@ -117,7 +120,9 @@ export function captureWakeScrollback(
armed: false,
ptyId: options.ptyId ?? null,
text: text.replace(SGR, '').trim() === '' ? null : text,
scrolledTo: active && active.viewportY < active.baseY ? active.viewportY : null
scrolledTo: active && active.viewportY < active.baseY ? active.viewportY : null,
scrolledText:
active && active.viewportY < active.baseY ? wakeAnchorText(active, active.viewportY) : null
}
pending.set(leafId, entry)
if (entry.text !== null || !options.readOnlyCopy) {
@@ -241,12 +246,18 @@ export function forgetPreReplayCopy(leafId: string): void {
/** The person scrolled the waking pane: where to put them back after the restore. */
export function noteWakeViewport(
leafId: string,
terminal: { buffer: { active: { viewportY: number; baseY: number } } }
terminal: {
buffer: {
active: { viewportY: number; baseY: number } & Partial<Pick<RestoreBuffer, 'getLine'>>
}
}
): void {
const entry = pending.get(leafId)
if (entry) {
const { viewportY, baseY } = terminal.buffer.active
entry.scrolledTo = viewportY < baseY ? viewportY : null
const active = terminal.buffer.active
const scrolled = active.viewportY < active.baseY
entry.scrolledTo = scrolled ? active.viewportY : null
entry.scrolledText = scrolled ? wakeAnchorText(active, active.viewportY) : null
}
}
@@ -274,6 +285,8 @@ export type WakeScrollbackRestore = {
block: string
/** Where a person who had scrolled up was, or null when pinned to the bottom. */
scrolledTo: number | null
/** That line's text, so the rewrite (which can shift rows) finds it again (REG-13). */
anchor: string | null
}
/**
@@ -298,10 +311,12 @@ export function beginWakeScrollbackRestore(
if (entry.text === null) {
return null
}
const { viewportY, baseY } = terminal.buffer.active
const active = terminal.buffer.active
const scrolledHere = active.viewportY < active.baseY
return {
// A remount on wake starts at the bottom: the person's scroll is the one noted before it.
scrolledTo: viewportY < baseY ? viewportY : entry.scrolledTo,
scrolledTo: scrolledHere ? active.viewportY : entry.scrolledTo,
anchor: scrolledHere ? wakeAnchorText(active, active.viewportY) : entry.scrolledText,
block: `\x1b[0m${sanitizeRestoredText(entry.text)}\x1b[0m\r\n${wakeDividerLine(entry.sleptAt, wokeAt, terminal.cols)}`
}
}
@@ -369,7 +384,7 @@ export async function finishWakeScrollbackRestore(
return false
}
if (restore.scrolledTo !== null) {
scrollTo(restore.scrolledTo)
scrollTo(wakeAnchoredRow(terminal.buffer.active, restore.anchor, restore.scrolledTo))
}
return true
}