From abfec1b372bee51e5141b988f87e224ba5fbe00c Mon Sep 17 00:00:00 2001 From: James Babcock Date: Mon, 13 Jul 2026 01:58:31 -0700 Subject: [PATCH] Terminal supports g2mirror scrollback --- app/native/g2mirror-client.ts | 84 ++++++++++++++++++- app/ui/apps/terminal-emulator.ts | 30 ++++--- app/workers/terminal-app.worker.ts | 130 +++++++++++++++++++++++++++-- 3 files changed, 223 insertions(+), 21 deletions(-) diff --git a/app/native/g2mirror-client.ts b/app/native/g2mirror-client.ts index 05e79999..5b7745e6 100644 --- a/app/native/g2mirror-client.ts +++ b/app/native/g2mirror-client.ts @@ -38,6 +38,18 @@ export type G2MirrorState = { attachedCommand: string; }; +/** A page of archived scrollback lines (see PROTOCOL.md "Scrollback history"). */ +export type G2MirrorHistoryReply = { + /** Absolute index of lines[0]; the page covers [start, start + lines.length). */ + start: number; + /** Oldest index still retained by the wrapper (older requests return nothing). */ + oldest: number; + /** Current splice point (next line to be archived). */ + next: number; + /** Plain text, ANSI-stripped, oldest-to-newest. */ + lines: string[]; +}; + export type G2MirrorClientOptions = { host: string; port: number; @@ -56,10 +68,16 @@ export class G2MirrorClient { private status = "Not connected."; private sessions: G2MirrorSession[] = []; private attachedCommand = ""; + // Scrollback archive extent: `historyNext` is the splice point (index of the + // next line to be archived), `historyOldest` the oldest retained index. + private historyNext = 0; + private historyOldest = 0; private listRefreshTimer: ReturnType | null = null; private stopped = false; private readonly stateListeners = new Set<(state: G2MirrorState) => void>(); private readonly terminalDataListeners = new Set<(data: Uint8Array, kind: TerminalDataKind) => void>(); + private readonly snapshotListeners = new Set<(historyNext: number, historyOldest: number) => void>(); + private readonly historyLinesListeners = new Set<(reply: G2MirrorHistoryReply) => void>(); private readonly sessionAttachedListeners = new Set<(command: string) => void>(); private readonly sessionDetachedListeners = new Set<(reason: string) => void>(); private readonly bellListeners = new Set<(socket: string, lastBellAtMs: number) => void>(); @@ -191,6 +209,27 @@ export class G2MirrorClient { this.send({ type: "view" }); } + /** + * A snapshot arrived, carrying its scrollback splice point (`history_next`) + * and the oldest retained index. Fired after the snapshot's terminal data. + */ + onSnapshot(listener: (historyNext: number, historyOldest: number) => void): () => void { + this.snapshotListeners.add(listener); + return () => this.snapshotListeners.delete(listener); + } + + /** A page of archived scrollback (reply to requestHistory). */ + onHistoryLines(listener: (reply: G2MirrorHistoryReply) => void): () => void { + this.historyLinesListeners.add(listener); + return () => this.historyLinesListeners.delete(listener); + } + + /** Request archived lines ending just before `before`, paging backwards. */ + requestHistory(before: number, limit = 200): void { + if (this.phase !== "attached") return; + this.send({ type: "history", before, limit }); + } + /** * Write bytes to the attached app's terminal, as a terminal emulator would * for keystrokes. `text` is sent as UTF-8; include a trailing "\r" to submit @@ -272,17 +311,46 @@ export class G2MirrorClient { // Session accepted us (relayed from the wrapper). this.clearListRefreshTimer(); this.attachedCommand = String(message.command ?? ""); + const history = message.history; + if (history && typeof history.next === "number") { + this.historyNext = Number(history.next) || 0; + this.historyOldest = Number(history.oldest) || 0; + } this.setState("attached", `Attached: ${this.attachedCommand || "session"}`); for (const listener of Array.from(this.sessionAttachedListeners)) { listener(this.attachedCommand); } return; } - case "snapshot": + case "snapshot": { + const data = decodeBase64(String(message.data ?? "")); + if (typeof message.history_next === "number") { + this.historyNext = Number(message.history_next) || 0; + } + for (const listener of Array.from(this.terminalDataListeners)) { + listener(data, "snapshot"); + } + for (const listener of Array.from(this.snapshotListeners)) { + listener(this.historyNext, this.historyOldest); + } + return; + } case "output": { const data = decodeBase64(String(message.data ?? "")); for (const listener of Array.from(this.terminalDataListeners)) { - listener(data, message.type as TerminalDataKind); + listener(data, "output"); + } + return; + } + case "history_lines": { + const start = Number(message.start) || 0; + const oldest = Number(message.oldest) || 0; + const next = Number(message.next) || 0; + const rawLines = Array.isArray(message.lines) ? message.lines : []; + const lines = rawLines.map((line: any) => stripAnsi(decodeBase64Utf8(String(line?.data ?? "")))); + this.historyOldest = oldest; + for (const listener of Array.from(this.historyLinesListeners)) { + listener({ start, oldest, next, lines }); } return; } @@ -368,6 +436,18 @@ function decodeBase64(data: string): Uint8Array { return toUint8Array(android.util.Base64.decode(data, android.util.Base64.DEFAULT)); } +function decodeBase64Utf8(data: string): string { + if (!data) return ""; + const bytes = android.util.Base64.decode(data, android.util.Base64.DEFAULT); + return String(new java.lang.String(bytes, "UTF-8")); +} + +/** Strip escape sequences (SGR colors, other CSI) so archived lines render as plain text. */ +function stripAnsi(text: string): string { + // eslint-disable-next-line no-control-regex + return text.replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "").replace(/[\x00-\x08\x0b-\x1f]/g, ""); +} + function encodeBase64Utf8(text: string): string { const bytes = new java.lang.String(text).getBytes("UTF-8"); return String(android.util.Base64.encodeToString(bytes, android.util.Base64.NO_WRAP)); diff --git a/app/ui/apps/terminal-emulator.ts b/app/ui/apps/terminal-emulator.ts index b08a3f63..c4610b96 100644 --- a/app/ui/apps/terminal-emulator.ts +++ b/app/ui/apps/terminal-emulator.ts @@ -38,7 +38,9 @@ export class TerminalEmulator { this.term = new Terminal({ cols, rows, - scrollback: 0, + // Retain witnessed lines that scroll off the top; the archive covers + // everything before this. Matches the wrapper's default history cap. + scrollback: 10000, allowProposedApi: true, }); } @@ -56,18 +58,24 @@ export class TerminalEmulator { this.term.reset(); } - visibleLines(): string[] { - const buffer = this.term.buffer.active; - const lines: string[] = []; - for (let row = 0; row < this.rows; row++) { - const line = buffer.getLine(buffer.viewportY + row); - lines.push(line ? line.translateToString(true) : ""); - } - return lines; + /** Total lines held (witnessed scrollback + the live screen). */ + bufferLength(): number { + return this.term.buffer.active.length; } - cursor(): { x: number; y: number } { + /** Text of buffer line `index` (0 = oldest retained), trailing space trimmed. */ + lineAt(index: number): string { + const line = this.term.buffer.active.getLine(index); + return line ? line.translateToString(true) : ""; + } + + /** Cursor row as an absolute buffer index (baseY + cursorY). */ + cursorRow(): number { const buffer = this.term.buffer.active; - return { x: buffer.cursorX, y: buffer.cursorY }; + return buffer.baseY + buffer.cursorY; + } + + cursorCol(): number { + return this.term.buffer.active.cursorX; } } diff --git a/app/workers/terminal-app.worker.ts b/app/workers/terminal-app.worker.ts index f57230b7..d035df01 100644 --- a/app/workers/terminal-app.worker.ts +++ b/app/workers/terminal-app.worker.ts @@ -23,6 +23,7 @@ import { type G2MirrorState, } from "../native/g2mirror-client"; import { onSettingsStoreChanged } from "../native/settings-store"; +import { clamp } from "../util/numeric-util"; import { terminalAuthTokenSetting, terminalHostSetting, @@ -43,6 +44,7 @@ const CELL_HEIGHT = 12; const DEVICE_NAME = "Faceclaw G2"; const HUB_ROW_HEIGHT = 20; const RENDER_COALESCE_MS = 33; +const HISTORY_PAGE = 200; type BaseWindow = { windowId: string; @@ -67,6 +69,17 @@ type ViewWindow = BaseWindow & { attachRequested: boolean; status: string; unsubscribers: Array<() => void>; + // Scrollback model. Absolute line indices span the archive and the emulator: + // indices < historyNext are archived lines; >= historyNext are emulator buffer + // line (index - historyNext). `archive` holds fetched lines [archiveStart, + // historyNext). `scrollTop` is the absolute index of the top visible line, or + // null to follow the live bottom. + historyNext: number; + historyOldest: number; + archive: string[]; + archiveStart: number; + scrollTop: number | null; + historyFetchInFlight: boolean; }; type TerminalWindow = HubWindow | ViewWindow; @@ -262,8 +275,30 @@ function createViewWindow(windowId: string, surfaceId: string, socket: string, l attachRequested: false, status: "Connecting...", unsubscribers: [], + historyNext: 0, + historyOldest: 0, + archive: [], + archiveStart: 0, + scrollTop: null, + historyFetchInFlight: false, }; window.unsubscribers.push( + client.onSnapshot((historyNext, historyOldest) => { + // A (re)snapshot resets the emulator, so reset the scroll model too: + // follow the bottom and drop any fetched archive (its splice may move). + window.historyNext = historyNext; + window.historyOldest = historyOldest; + window.archive = []; + window.archiveStart = historyNext; + window.scrollTop = null; + window.historyFetchInFlight = false; + maybePrefetchHistory(window); + scheduleRender(window); + }), + client.onHistoryLines((reply) => { + applyHistoryReply(window, reply); + scheduleRender(window); + }), client.onStateChange((state) => { if (state.phase === "connected" && !window.attachRequested) { window.attachRequested = true; @@ -302,10 +337,58 @@ function handleInput(window: TerminalWindow, event: DashboardInputEvent, frameId handleHubInput(window, event, frameId); return; } - // View windows are readonly (protocol v1 has no keyboard input). + // View windows: scroll gestures page through scrollback; text input arrives + // via the separate "text-input" message. + if (event.type === "scroll-up" || event.type === "scroll-down") { + handleViewScroll(window, event.type === "scroll-up" ? -1 : 1, frameId); + return; + } frameTimings.finishFrame(frameId, "discarded: terminal view ignored input"); } +/** Top visible absolute line index when following the live bottom. */ +function followTop(window: ViewWindow): number { + return window.historyNext + window.emulator.bufferLength() - gridRows; +} + +function handleViewScroll(window: ViewWindow, direction: -1 | 1, frameId: number): void { + const page = Math.max(1, gridRows - 1); + const bottomTop = followTop(window); + const minTop = window.archiveStart; + const currentTop = window.scrollTop ?? bottomTop; + const newTop = clamp(currentTop + direction * page, Math.min(minTop, bottomTop), bottomTop); + // Snapping to (or below) the live bottom re-locks to follow mode. + window.scrollTop = newTop >= bottomTop ? null : newTop; + maybePrefetchHistory(window); + renderAndSubmit(window, frameId); +} + +/** Fetch an older page of archive when the view nears the top of what's loaded. */ +function maybePrefetchHistory(window: ViewWindow): void { + if (window.historyFetchInFlight) return; + if (window.archiveStart <= window.historyOldest) return; // nothing older retained + const top = window.scrollTop ?? followTop(window); + if (window.archive.length === 0 || top - window.archiveStart <= gridRows) { + window.historyFetchInFlight = true; + window.client.requestHistory(window.archiveStart, HISTORY_PAGE); + } +} + +function applyHistoryReply(window: ViewWindow, reply: { start: number; oldest: number; lines: string[] }): void { + window.historyFetchInFlight = false; + window.historyOldest = reply.oldest; + if (!reply.lines.length) { + // Nothing older was returned; stop asking below what we already have. + window.historyOldest = window.archiveStart; + return; + } + // The page ends just before our request (archiveStart); prepend it. + if (reply.start < window.archiveStart) { + window.archive = reply.lines.concat(window.archive); + window.archiveStart = reply.start; + } +} + type HubItem = { label: string; onSelect?: () => void; @@ -417,17 +500,48 @@ function paintView(window: ViewWindow): GrayImage { image.drawText(terminalFont, 24, 130, `${GESTURE_DOUBLE_CLICK} back`, 110); return image; } - const cursor = window.emulator.cursor(); - image.fillRect(cursor.x * CELL_WIDTH, cursor.y * CELL_HEIGHT, CELL_WIDTH, CELL_HEIGHT, 70); - const lines = window.emulator.visibleLines(); - for (let row = 0; row < lines.length; row++) { - const line = lines[row]!; - if (line.length === 0) continue; - image.drawText(terminalFont, 0, row * CELL_HEIGHT, line, 200); + + const rows = gridRows; + const historyNext = window.historyNext; + const bufferLength = window.emulator.bufferLength(); + const bottomTop = historyNext + bufferLength - rows; + const following = window.scrollTop === null; + const top = following ? bottomTop : clamp(window.scrollTop!, window.archiveStart, bottomTop); + + // Draw the cursor only if its line is within the visible window. + const cursorScreenRow = historyNext + window.emulator.cursorRow() - top; + if (cursorScreenRow >= 0 && cursorScreenRow < rows) { + image.fillRect(window.emulator.cursorCol() * CELL_WIDTH, cursorScreenRow * CELL_HEIGHT, CELL_WIDTH, CELL_HEIGHT, 70); + } + + for (let row = 0; row < rows; row++) { + const absolute = top + row; + let text = ""; + if (absolute >= historyNext) { + const bufferIndex = absolute - historyNext; + if (bufferIndex >= 0 && bufferIndex < bufferLength) text = window.emulator.lineAt(bufferIndex); + } else if (absolute >= window.archiveStart) { + text = window.archive[absolute - window.archiveStart] ?? ""; + } + if (text.length) image.drawText(terminalFont, 0, row * CELL_HEIGHT, text, 200); + } + + if (!following) { + drawScrollIndicator(image, top, window.archiveStart, bottomTop); } return image; } +/** Right-edge scrollbar showing the view position within the scrollback. */ +function drawScrollIndicator(image: GrayImage, top: number, minTop: number, maxTop: number): void { + const trackX = viewportWidth - 3; + image.fillRect(trackX, 0, 3, viewportHeight, 30); + const fraction = clamp((top - minTop) / Math.max(1, maxTop - minTop), 0, 1); + const thumbHeight = 24; + const thumbY = Math.round((viewportHeight - thumbHeight) * fraction); + image.fillRect(trackX, thumbY, 3, thumbHeight, 150); +} + /** Coalesce bursty repaint triggers (terminal output) into ~30fps renders. */ function scheduleRender(window: TerminalWindow): void { if (window.renderScheduled) return;