Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
fix(watch-link): a viewer joining a running session starts its filter mid-stream
reviewbc4b73f91ee2
diff --git a/src/core/watch-link/__fixtures__/xterm-vt500.ts b/src/core/watch-link/__fixtures__/xterm-vt500.tsnew file mode 100644index 000000000..fb77d47a7--- /dev/null+++ b/src/core/watch-link/__fixtures__/xterm-vt500.ts@@ -0,0 +1,268 @@+// xterm.js 5.5.0's VT500 parser table, for the stream filter's differential test (test-only).+//+// The six blocks between the BEGIN/END markers are copied VERBATIM from the installed package:+// node_modules/@xterm/xterm/src/common/parser/Constants.ts ParserState, ParserAction+// node_modules/@xterm/xterm/src/common/parser/EscapeSequenceParser.ts TableAccess, TransitionTable,+// NON_ASCII_PRINTABLE,+// VT500_TRANSITION_TABLE+// `stream-filter.xterm.test.ts` compares each block with that source, so an xterm upgrade that+// changes the table fails there instead of silently testing the filter against an old model.+// Only the code after the END marker is ours.+//+// The copied blocks: Copyright (c) 2017-2018 The xterm.js authors. MIT license.++// ---- BEGIN verbatim xterm 5.5.0 ----+export const enum ParserState {+ GROUND = 0,+ ESCAPE = 1,+ ESCAPE_INTERMEDIATE = 2,+ CSI_ENTRY = 3,+ CSI_PARAM = 4,+ CSI_INTERMEDIATE = 5,+ CSI_IGNORE = 6,+ SOS_PM_APC_STRING = 7,+ OSC_STRING = 8,+ DCS_ENTRY = 9,+ DCS_PARAM = 10,+ DCS_IGNORE = 11,+ DCS_INTERMEDIATE = 12,+ DCS_PASSTHROUGH = 13+}++export const enum ParserAction {+ IGNORE = 0,+ ERROR = 1,+ PRINT = 2,+ EXECUTE = 3,+ OSC_START = 4,+ OSC_PUT = 5,+ OSC_END = 6,+ CSI_DISPATCH = 7,+ PARAM = 8,+ COLLECT = 9,+ ESC_DISPATCH = 10,+ CLEAR = 11,+ DCS_HOOK = 12,+ DCS_PUT = 13,+ DCS_UNHOOK = 14+}++const enum TableAccess {+ TRANSITION_ACTION_SHIFT = 4,+ TRANSITION_STATE_MASK = 15,+ INDEX_STATE_SHIFT = 8+}++export class TransitionTable {+ public table: Uint8Array;++ constructor(length: number) {+ this.table = new Uint8Array(length);+ }++ /**+ * Set default transition.+ * @param action default action+ * @param next default next state+ */+ public setDefault(action: ParserAction, next: ParserState): void {+ this.table.fill(action << TableAccess.TRANSITION_ACTION_SHIFT | next);+ }++ /**+ * Add a transition to the transition table.+ * @param code input character code+ * @param state current parser state+ * @param action parser action to be done+ * @param next next parser state+ */+ public add(code: number, state: ParserState, action: ParserAction, next: ParserState): void {+ this.table[state << TableAccess.INDEX_STATE_SHIFT | code] = action << TableAccess.TRANSITION_ACTION_SHIFT | next;+ }++ /**+ * Add transitions for multiple input character codes.+ * @param codes input character code array+ * @param state current parser state+ * @param action parser action to be done+ * @param next next parser state+ */+ public addMany(codes: number[], state: ParserState, action: ParserAction, next: ParserState): void {+ for (let i = 0; i < codes.length; i++) {+ this.table[state << TableAccess.INDEX_STATE_SHIFT | codes[i]] = action << TableAccess.TRANSITION_ACTION_SHIFT | next;+ }+ }+}++const NON_ASCII_PRINTABLE = 0xA0;++export const VT500_TRANSITION_TABLE = (function (): TransitionTable {+ const table: TransitionTable = new TransitionTable(4095);++ // range macro for byte+ const BYTE_VALUES = 256;+ const blueprint = Array.apply(null, Array(BYTE_VALUES)).map((unused: any, i: number) => i);+ const r = (start: number, end: number): number[] => blueprint.slice(start, end);++ // Default definitions.+ const PRINTABLES = r(0x20, 0x7f); // 0x20 (SP) included, 0x7F (DEL) excluded+ const EXECUTABLES = r(0x00, 0x18);+ EXECUTABLES.push(0x19);+ EXECUTABLES.push.apply(EXECUTABLES, r(0x1c, 0x20));++ const states: number[] = r(ParserState.GROUND, ParserState.DCS_PASSTHROUGH + 1);+ let state: any;++ // set default transition+ table.setDefault(ParserAction.ERROR, ParserState.GROUND);+ // printables+ table.addMany(PRINTABLES, ParserState.GROUND, ParserAction.PRINT, ParserState.GROUND);+ // global anywhere rules+ for (state in states) {+ table.addMany([0x18, 0x1a, 0x99, 0x9a], state, ParserAction.EXECUTE, ParserState.GROUND);+ table.addMany(r(0x80, 0x90), state, ParserAction.EXECUTE, ParserState.GROUND);+ table.addMany(r(0x90, 0x98), state, ParserAction.EXECUTE, ParserState.GROUND);+ table.add(0x9c, state, ParserAction.IGNORE, ParserState.GROUND); // ST as terminator+ table.add(0x1b, state, ParserAction.CLEAR, ParserState.ESCAPE); // ESC+ table.add(0x9d, state, ParserAction.OSC_START, ParserState.OSC_STRING); // OSC+ table.addMany([0x98, 0x9e, 0x9f], state, ParserAction.IGNORE, ParserState.SOS_PM_APC_STRING);+ table.add(0x9b, state, ParserAction.CLEAR, ParserState.CSI_ENTRY); // CSI+ table.add(0x90, state, ParserAction.CLEAR, ParserState.DCS_ENTRY); // DCS+ }+ // rules for executables and 7f+ table.addMany(EXECUTABLES, ParserState.GROUND, ParserAction.EXECUTE, ParserState.GROUND);+ table.addMany(EXECUTABLES, ParserState.ESCAPE, ParserAction.EXECUTE, ParserState.ESCAPE);+ table.add(0x7f, ParserState.ESCAPE, ParserAction.IGNORE, ParserState.ESCAPE);+ table.addMany(EXECUTABLES, ParserState.OSC_STRING, ParserAction.IGNORE, ParserState.OSC_STRING);+ table.addMany(EXECUTABLES, ParserState.CSI_ENTRY, ParserAction.EXECUTE, ParserState.CSI_ENTRY);+ table.add(0x7f, ParserState.CSI_ENTRY, ParserAction.IGNORE, ParserState.CSI_ENTRY);+ table.addMany(EXECUTABLES, ParserState.CSI_PARAM, ParserAction.EXECUTE, ParserState.CSI_PARAM);+ table.add(0x7f, ParserState.CSI_PARAM, ParserAction.IGNORE, ParserState.CSI_PARAM);+ table.addMany(EXECUTABLES, ParserState.CSI_IGNORE, ParserAction.EXECUTE, ParserState.CSI_IGNORE);+ table.addMany(EXECUTABLES, ParserState.CSI_INTERMEDIATE, ParserAction.EXECUTE, ParserState.CSI_INTERMEDIATE);+ table.add(0x7f, ParserState.CSI_INTERMEDIATE, ParserAction.IGNORE, ParserState.CSI_INTERMEDIATE);+ table.addMany(EXECUTABLES, ParserState.ESCAPE_INTERMEDIATE, ParserAction.EXECUTE, ParserState.ESCAPE_INTERMEDIATE);+ table.add(0x7f, ParserState.ESCAPE_INTERMEDIATE, ParserAction.IGNORE, ParserState.ESCAPE_INTERMEDIATE);+ // osc+ table.add(0x5d, ParserState.ESCAPE, ParserAction.OSC_START, ParserState.OSC_STRING);+ table.addMany(PRINTABLES, ParserState.OSC_STRING, ParserAction.OSC_PUT, ParserState.OSC_STRING);+ table.add(0x7f, ParserState.OSC_STRING, ParserAction.OSC_PUT, ParserState.OSC_STRING);+ table.addMany([0x9c, 0x1b, 0x18, 0x1a, 0x07], ParserState.OSC_STRING, ParserAction.OSC_END, ParserState.GROUND);+ table.addMany(r(0x1c, 0x20), ParserState.OSC_STRING, ParserAction.IGNORE, ParserState.OSC_STRING);+ // sos/pm/apc does nothing+ table.addMany([0x58, 0x5e, 0x5f], ParserState.ESCAPE, ParserAction.IGNORE, ParserState.SOS_PM_APC_STRING);+ table.addMany(PRINTABLES, ParserState.SOS_PM_APC_STRING, ParserAction.IGNORE, ParserState.SOS_PM_APC_STRING);+ table.addMany(EXECUTABLES, ParserState.SOS_PM_APC_STRING, ParserAction.IGNORE, ParserState.SOS_PM_APC_STRING);+ table.add(0x9c, ParserState.SOS_PM_APC_STRING, ParserAction.IGNORE, ParserState.GROUND);+ table.add(0x7f, ParserState.SOS_PM_APC_STRING, ParserAction.IGNORE, ParserState.SOS_PM_APC_STRING);+ // csi entries+ table.add(0x5b, ParserState.ESCAPE, ParserAction.CLEAR, ParserState.CSI_ENTRY);+ table.addMany(r(0x40, 0x7f), ParserState.CSI_ENTRY, ParserAction.CSI_DISPATCH, ParserState.GROUND);+ table.addMany(r(0x30, 0x3c), ParserState.CSI_ENTRY, ParserAction.PARAM, ParserState.CSI_PARAM);+ table.addMany([0x3c, 0x3d, 0x3e, 0x3f], ParserState.CSI_ENTRY, ParserAction.COLLECT, ParserState.CSI_PARAM);+ table.addMany(r(0x30, 0x3c), ParserState.CSI_PARAM, ParserAction.PARAM, ParserState.CSI_PARAM);+ table.addMany(r(0x40, 0x7f), ParserState.CSI_PARAM, ParserAction.CSI_DISPATCH, ParserState.GROUND);+ table.addMany([0x3c, 0x3d, 0x3e, 0x3f], ParserState.CSI_PARAM, ParserAction.IGNORE, ParserState.CSI_IGNORE);+ table.addMany(r(0x20, 0x40), ParserState.CSI_IGNORE, ParserAction.IGNORE, ParserState.CSI_IGNORE);+ table.add(0x7f, ParserState.CSI_IGNORE, ParserAction.IGNORE, ParserState.CSI_IGNORE);+ table.addMany(r(0x40, 0x7f), ParserState.CSI_IGNORE, ParserAction.IGNORE, ParserState.GROUND);+ table.addMany(r(0x20, 0x30), ParserState.CSI_ENTRY, ParserAction.COLLECT, ParserState.CSI_INTERMEDIATE);+ table.addMany(r(0x20, 0x30), ParserState.CSI_INTERMEDIATE, ParserAction.COLLECT, ParserState.CSI_INTERMEDIATE);+ table.addMany(r(0x30, 0x40), ParserState.CSI_INTERMEDIATE, ParserAction.IGNORE, ParserState.CSI_IGNORE);+ table.addMany(r(0x40, 0x7f), ParserState.CSI_INTERMEDIATE, ParserAction.CSI_DISPATCH, ParserState.GROUND);+ table.addMany(r(0x20, 0x30), ParserState.CSI_PARAM, ParserAction.COLLECT, ParserState.CSI_INTERMEDIATE);+ // esc_intermediate+ table.addMany(r(0x20, 0x30), ParserState.ESCAPE, ParserAction.COLLECT, ParserState.ESCAPE_INTERMEDIATE);+ table.addMany(r(0x20, 0x30), ParserState.ESCAPE_INTERMEDIATE, ParserAction.COLLECT, ParserState.ESCAPE_INTERMEDIATE);+ table.addMany(r(0x30, 0x7f), ParserState.ESCAPE_INTERMEDIATE, ParserAction.ESC_DISPATCH, ParserState.GROUND);+ table.addMany(r(0x30, 0x50), ParserState.ESCAPE, ParserAction.ESC_DISPATCH, ParserState.GROUND);+ table.addMany(r(0x51, 0x58), ParserState.ESCAPE, ParserAction.ESC_DISPATCH, ParserState.GROUND);+ table.addMany([0x59, 0x5a, 0x5c], ParserState.ESCAPE, ParserAction.ESC_DISPATCH, ParserState.GROUND);+ table.addMany(r(0x60, 0x7f), ParserState.ESCAPE, ParserAction.ESC_DISPATCH, ParserState.GROUND);+ // dcs entry+ table.add(0x50, ParserState.ESCAPE, ParserAction.CLEAR, ParserState.DCS_ENTRY);+ table.addMany(EXECUTABLES, ParserState.DCS_ENTRY, ParserAction.IGNORE, ParserState.DCS_ENTRY);+ table.add(0x7f, ParserState.DCS_ENTRY, ParserAction.IGNORE, ParserState.DCS_ENTRY);+ table.addMany(r(0x1c, 0x20), ParserState.DCS_ENTRY, ParserAction.IGNORE, ParserState.DCS_ENTRY);+ table.addMany(r(0x20, 0x30), ParserState.DCS_ENTRY, ParserAction.COLLECT, ParserState.DCS_INTERMEDIATE);+ table.addMany(r(0x30, 0x3c), ParserState.DCS_ENTRY, ParserAction.PARAM, ParserState.DCS_PARAM);+ table.addMany([0x3c, 0x3d, 0x3e, 0x3f], ParserState.DCS_ENTRY, ParserAction.COLLECT, ParserState.DCS_PARAM);+ table.addMany(EXECUTABLES, ParserState.DCS_IGNORE, ParserAction.IGNORE, ParserState.DCS_IGNORE);+ table.addMany(r(0x20, 0x80), ParserState.DCS_IGNORE, ParserAction.IGNORE, ParserState.DCS_IGNORE);+ table.addMany(r(0x1c, 0x20), ParserState.DCS_IGNORE, ParserAction.IGNORE, ParserState.DCS_IGNORE);+ table.addMany(EXECUTABLES, ParserState.DCS_PARAM, ParserAction.IGNORE, ParserState.DCS_PARAM);+ table.add(0x7f, ParserState.DCS_PARAM, ParserAction.IGNORE, ParserState.DCS_PARAM);+ table.addMany(r(0x1c, 0x20), ParserState.DCS_PARAM, ParserAction.IGNORE, ParserState.DCS_PARAM);+ table.addMany(r(0x30, 0x3c), ParserState.DCS_PARAM, ParserAction.PARAM, ParserState.DCS_PARAM);+ table.addMany([0x3c, 0x3d, 0x3e, 0x3f], ParserState.DCS_PARAM, ParserAction.IGNORE, ParserState.DCS_IGNORE);+ table.addMany(r(0x20, 0x30), ParserState.DCS_PARAM, ParserAction.COLLECT, ParserState.DCS_INTERMEDIATE);+ table.addMany(EXECUTABLES, ParserState.DCS_INTERMEDIATE, ParserAction.IGNORE, ParserState.DCS_INTERMEDIATE);+ table.add(0x7f, ParserState.DCS_INTERMEDIATE, ParserAction.IGNORE, ParserState.DCS_INTERMEDIATE);+ table.addMany(r(0x1c, 0x20), ParserState.DCS_INTERMEDIATE, ParserAction.IGNORE, ParserState.DCS_INTERMEDIATE);+ table.addMany(r(0x20, 0x30), ParserState.DCS_INTERMEDIATE, ParserAction.COLLECT, ParserState.DCS_INTERMEDIATE);+ table.addMany(r(0x30, 0x40), ParserState.DCS_INTERMEDIATE, ParserAction.IGNORE, ParserState.DCS_IGNORE);+ table.addMany(r(0x40, 0x7f), ParserState.DCS_INTERMEDIATE, ParserAction.DCS_HOOK, ParserState.DCS_PASSTHROUGH);+ table.addMany(r(0x40, 0x7f), ParserState.DCS_PARAM, ParserAction.DCS_HOOK, ParserState.DCS_PASSTHROUGH);+ table.addMany(r(0x40, 0x7f), ParserState.DCS_ENTRY, ParserAction.DCS_HOOK, ParserState.DCS_PASSTHROUGH);+ table.addMany(EXECUTABLES, ParserState.DCS_PASSTHROUGH, ParserAction.DCS_PUT, ParserState.DCS_PASSTHROUGH);+ table.addMany(PRINTABLES, ParserState.DCS_PASSTHROUGH, ParserAction.DCS_PUT, ParserState.DCS_PASSTHROUGH);+ table.add(0x7f, ParserState.DCS_PASSTHROUGH, ParserAction.IGNORE, ParserState.DCS_PASSTHROUGH);+ table.addMany([0x1b, 0x9c, 0x18, 0x1a], ParserState.DCS_PASSTHROUGH, ParserAction.DCS_UNHOOK, ParserState.GROUND);+ // special handling of unicode chars+ table.add(NON_ASCII_PRINTABLE, ParserState.GROUND, ParserAction.PRINT, ParserState.GROUND);+ table.add(NON_ASCII_PRINTABLE, ParserState.OSC_STRING, ParserAction.OSC_PUT, ParserState.OSC_STRING);+ table.add(NON_ASCII_PRINTABLE, ParserState.CSI_IGNORE, ParserAction.IGNORE, ParserState.CSI_IGNORE);+ table.add(NON_ASCII_PRINTABLE, ParserState.DCS_IGNORE, ParserAction.IGNORE, ParserState.DCS_IGNORE);+ table.add(NON_ASCII_PRINTABLE, ParserState.DCS_PASSTHROUGH, ParserAction.DCS_PUT, ParserState.DCS_PASSTHROUGH);+ return table;+})();+// ---- END verbatim xterm 5.5.0 ----++const STRING_STATES = new Set<number>([+ ParserState.SOS_PM_APC_STRING,+ ParserState.OSC_STRING,+ ParserState.DCS_ENTRY,+ ParserState.DCS_PARAM,+ ParserState.DCS_IGNORE,+ ParserState.DCS_INTERMEDIATE,+ ParserState.DCS_PASSTHROUGH+])++// One code through `EscapeSequenceParser.parse()`'s state walk, without its handlers. Two facts+// about `parse()` make a one-code-at-a-time walk of the table exact: its read-ahead loops (PRINT,+// PARAM, OSC_PUT, DCS_PUT) only take codes whose table entry keeps the state they are in, and an+// OSC or DCS ended by ESC goes to ESCAPE although the table says GROUND+// (`transition |= ParserState.ESCAPE`). An ERROR (a non-ASCII code in SOS/PM/APC or a DCS header)+// goes to GROUND with the default error handler, as the table says.+function step(state: number, code: number): number {+ let transition = VT500_TRANSITION_TABLE.table[state << TableAccess.INDEX_STATE_SHIFT | (code < 0xa0 ? code : NON_ASCII_PRINTABLE)]+ const action = transition >> TableAccess.TRANSITION_ACTION_SHIFT+ if ((action === ParserAction.OSC_END || action === ParserAction.DCS_UNHOOK) && code === 0x1b) {+ transition |= ParserState.ESCAPE+ }+ return transition & TableAccess.TRANSITION_STATE_MASK+}++/**+ * For each code point of a stream read from GROUND, whether xterm consumes it INSIDE a string+ * sequence (OSC, DCS, SOS, PM, APC): in a string state before it and still in one after it.+ */+export function xtermStringPayload(codePoints: readonly number[]): boolean[] {+ let state: number = ParserState.GROUND+ return codePoints.map((code) => {+ const next = step(state, code)+ const inside = STRING_STATES.has(state) && STRING_STATES.has(next)+ state = next+ return inside+ })+}++/** Whether xterm, reading these code points from GROUND, ever enters a string sequence. */+export function xtermEntersString(codePoints: readonly number[]): boolean {+ let state: number = ParserState.GROUND+ for (const code of codePoints) {+ state = step(state, code)+ if (STRING_STATES.has(state)) return true+ }+ return false+}diff --git a/src/core/watch-link/stream-filter.test.ts b/src/core/watch-link/stream-filter.test.tsindex 5f2d1eecc..1b7178508 100644--- a/src/core/watch-link/stream-filter.test.ts+++ b/src/core/watch-link/stream-filter.test.ts@@ -10,8 +10,9 @@ const run = (chunks: string[], max?: number): string => {// The filter's rules, one UTF-16 unit at a time and without a fast path: the oracle the fuzz test// holds the production parser to.-function oneCharAtATime(input: string, max: number): string {- let mode: 'text' | 'esc' | 'string' | 'stringEsc' = 'text'+function oneCharAtATime(input: string, max: number, midStream: boolean): string {+ // midStream: as if an 8-bit DCS introducer had just been read.+ let mode: 'text' | 'esc' | 'string' | 'stringEsc' = midStream ? 'string' : 'text'let osc = falselet len = 0let out = ''@@ -170,7 +171,7 @@ describe('createStreamFilter', () => {expect(f.push(']visible')).toBe(']visible')})- it('output never carries a string introducer, whatever the input and however it is chunked', () => {+ it('output never carries a string introducer, whatever the input, start and chunking', () => {// Why this is enough: in xterm.js a string state (OSC/DCS/SOS/PM/APC) is entered only from// ESCAPE on ] P X ^ _, or anywhere on an 8-bit introducer; ESCAPE is entered only by ESC and is// left by any char except C0 executables, DEL and ESC. So if no push emits an 8-bit introducer@@ -200,16 +201,17 @@ describe('createStreamFilter', () => {let input = ''for (let i = rand(60); i > 0; i--) input += ALPHABET[rand(ALPHABET.length)]const cap = [2, 5, 1_048_576][rand(3)]+ const midStream = rand(2) === 1// Cut anywhere, a surrogate pair included: the cap counts UTF-16 units, so nothing depends on it.const cuts = [0, input.length]for (let k = rand(5); k > 0; k--) cuts.push(rand(input.length + 1))cuts.sort((x, y) => x - y)const chunks = cuts.slice(1).map((end, i) => input.slice(cuts[i], end))- const f = createStreamFilter(cap)+ const f = createStreamFilter(cap, { midStream })const outs = chunks.map((c) => f.push(c))for (const out of outs) {- const ctx = JSON.stringify({ input, chunks, cap, out })+ const ctx = JSON.stringify({ input, chunks, cap, midStream, out })expect(INTRO_8.test(out), ctx).toBe(false)expect(out.endsWith(ESC), ctx).toBe(false)for (let i = out.indexOf(ESC); i !== -1; i = out.indexOf(ESC, i + 1)) {@@ -218,7 +220,82 @@ describe('createStreamFilter', () => {}// However it is chunked, the result is the char-by-char statement of the same rules: the// parser's slicing and fast path neither drop, reorder nor add a char.- expect(outs.join(''), JSON.stringify({ chunks, cap })).toBe(oneCharAtATime(input, cap))+ expect(outs.join(''), JSON.stringify({ chunks, cap, midStream })).toBe(oneCharAtATime(input, cap, midStream))}})})++describe('createStreamFilter, joined mid-stream', () => {+ // A watcher co-attaches to a RUNNING session, so its first byte can land anywhere: inside an OSC 52,+ // or right after an ESC that the previous read ended on. A filter that starts in text would print+ // the rest of that string, or read `]52;…` as text.+ const mid = (chunks: string[], max?: number): string => {+ const f = createStreamFilter(max, { midStream: true })+ return chunks.map((c) => f.push(c)).join('')+ }++ it('a join at any offset never prints a byte of a string, and resyncs at the next escape', () => {+ // Text is lowercase, spaces and `ESC [ m`; every string's payload is from a disjoint alphabet+ // (uppercase, digits, `=;]\`), so any payload byte in the output is visible as such.+ const STREAM = [+ 'pre ', `${ESC}[m`, 'one ',+ `${ESC}]52;C;U0VDUkVUQQ==${BEL}`, 'mid ',+ `${ESC}]52;C;U0VDUkVUQg==${ESC}\\`, 'two ',+ `${ESC}PQDATA${BEL}MORE${ESC}\\`, 'three ',+ `${ESC}_GAPC${BEL}HIDDEN${ESC}\\`, 'four ',+ `\x9d52;C;U0VDUkVUQw==\x9c`, 'five ',+ `\x90QDATA${BEL}MORE\x9c`,+ `${ESC}[m`, 'tail'+ ].join('')+ const resync = STREAM.lastIndexOf(ESC)+ for (let k = 0; k <= STREAM.length; k++) {+ const rest = STREAM.slice(k)+ for (const out of [mid([rest]), mid([rest.slice(0, 3), rest.slice(3)])]) {+ expect(out, `join at ${k}`).toMatch(/^[a-z \x1b[]*$/)+ if (k <= resync) expect(out.endsWith(`${ESC}[mtail`), `join at ${k}: ${JSON.stringify(out)}`).toBe(true)+ }+ }+ })++ it('a join right after a lone trailing ESC does not print the OSC 52 that ESC started', () => {+ const rest = `]52;c;c2VjcmV0${BEL}rest${ESC}[mtail`+ expect(mid([rest])).toBe(`${ESC}[mtail`)+ // What a filter starting in text would have sent: the whole clipboard.+ expect(run([rest])).toContain('c2VjcmV0')+ })++ it('a join into plain text loses only the text up to the first ESC', () => {+ expect(mid(['hello world', ` ${ESC}[1mbold${ESC}[m after`])).toBe(`${ESC}[1mbold${ESC}[m after`)+ })++ it('starts as an unknown string: ST, ESC-ST and 8-bit introducers end it, BEL does not', () => {+ expect(mid([`DATA${ESC}\\after`])).toBe('after')+ expect(mid([`DATA${ESC}`, `\\after`])).toBe('after')+ expect(mid(['DATA\x9cafter'])).toBe('after')+ // It may be a DCS or APC, where BEL is data.+ expect(mid([`DATA${BEL}more${ESC}[mafter`])).toBe(`${ESC}[mafter`)+ // An 8-bit introducer starts a string of ITS kind: this one is an OSC, which BEL ends.+ expect(mid([`DATA\x9d52;c;x${BEL}after`])).toBe('after')+ })++ it('the cap counts from the join, on creation and on reset', () => {+ const f = createStreamFilter(5, { midStream: true })+ expect(f.push('12345')).toBe('')+ expect(f.push('6789')).toBe('789')++ const g = createStreamFilter(10)+ expect(g.push(`a${ESC}]12345678`)).toBe('a')+ g.reset({ midStream: true })+ expect(g.push('1234567890')).toBe('')+ expect(g.push('Xab')).toBe('ab')+ })++ it('reset({ midStream }) drops what was being read and starts as a join', () => {+ const f = createStreamFilter()+ expect(f.push('a')).toBe('a')+ f.reset({ midStream: true })+ expect(f.push(`b${ESC}[mc`)).toBe(`${ESC}[mc`)+ f.reset()+ expect(f.push('d')).toBe('d')+ })+})diff --git a/src/core/watch-link/stream-filter.ts b/src/core/watch-link/stream-filter.tsindex 76d7da280..c208746d9 100644--- a/src/core/watch-link/stream-filter.ts+++ b/src/core/watch-link/stream-filter.ts@@ -19,8 +19,16 @@// ESC, and takes an 8-bit introducer as a string start: `ESC \n ]52;…` is still an OSC 52.// - An 8-bit introducer inside a string starts a new string of ITS kind (an OSC turned DCS no longer// ends at BEL), with a fresh count toward the cap.-// Where xterm ENDS a string on something this parser does not (CAN, SUB, other C1 controls), the-// viewer misses a little text until the next terminator; it never sees more than the owner.+// Where xterm ENDS a string on something this parser does not (CAN, SUB, other C1 controls, and a+// non-ASCII char, U+00A0 and up, inside SOS/PM/APC or a DCS before its final byte: ERROR → GROUND),+// the viewer misses a little text until the next terminator; it never sees more than the owner.+//+// A viewer that joins a RUNNING session (`midStream`) cannot know where in the stream its first byte+// falls: inside an OSC 52, or right after an ESC the previous read ended on (`]52;c;…` would then+// read as text, the whole clipboard). So it starts as if an unknown string had just begun: nothing+// is shown until the next ESC, ST or 8-bit introducer, where xterm's state is known again whatever+// it was (ESCAPE, GROUND, a new string). The cost is the text between the join and the first+// escape: the viewer misses it until those cells are painted again.//// The output guarantee the caller relies on: no push emits an 8-bit introducer or ends on ESC, and// every ESC it emits is followed by a char that leaves ESCAPE without starting a string. So the@@ -49,12 +57,25 @@ function isC0Executable(c: number): boolean {return c <= 0x17 || c === 0x19 || (c >= 0x1c && c <= 0x1f)}+export interface StreamFilterOptions {+ /**+ * The first byte may fall anywhere in the stream. Every viewer that co-attaches to a running+ * session must set it, and so must every `reset()` onto a session that is already running;+ * without it a join inside a string, or right after an ESC, sends the string's payload as text.+ * Starts exactly as if an 8-bit DCS introducer had just been read: nothing is shown until the+ * next ESC (an `ESC \` ST is dropped), ST or 8-bit introducer; BEL does not end it (the unknown+ * string may be a DCS or APC, where BEL is data); the cap counts from the join.+ */+ midStream?: boolean+}+export interface StreamFilter {push(chunk: string): string- reset(): void+ /** Forget the current sequence, for a new pty session; `midStream` as for `createStreamFilter`. */+ reset(opts?: StreamFilterOptions): void}-export function createStreamFilter(maxStringChars = 1_048_576): StreamFilter {+export function createStreamFilter(maxStringChars = 1_048_576, opts?: StreamFilterOptions): StreamFilter {// 'esc' is ESCAPE after a plain ESC; 'stringEsc' is ESCAPE after the ESC that ended a string,// where `ESC \` is that string's ST and is dropped with it.let mode: 'text' | 'esc' | 'string' | 'stringEsc' = 'text'@@ -65,11 +86,18 @@ export function createStreamFilter(maxStringChars = 1_048_576): StreamFilter {osc = introducer === 0x5d || introducer === 0x9dlen = 0}- return {- reset() {+ const start = (o: StreamFilterOptions | undefined): void => {+ if (o?.midStream) enterString(0x90)+ else {mode = 'text'osc = falselen = 0+ }+ }+ start(opts)+ return {+ reset(o) {+ start(o)},push(chunk) {if (mode === 'text' && !TEXT_SPECIAL.test(chunk)) return chunkdiff --git a/src/core/watch-link/stream-filter.xterm.test.ts b/src/core/watch-link/stream-filter.xterm.test.tsnew file mode 100644index 000000000..46fea3a9b--- /dev/null+++ b/src/core/watch-link/stream-filter.xterm.test.ts@@ -0,0 +1,144 @@+// The stream filter held to xterm.js itself, through xterm 5.5's own VT500 table (copied verbatim in+// __fixtures__/xterm-vt500.ts). Two ways a viewer could get what is not on the owner's screen, one+// check each, on random streams:+// - payload: every letter xterm consumes INSIDE a string sequence is changed; if the filter's+// output changes with it, a byte of string payload reached the viewer;+// - synthesis: xterm reading the filter's OUTPUT must never enter a string sequence (a lone ESC+// glued to the text after a removed string would be one, without any payload byte leaking).+// This is what the hand-written cases cannot do: it asks xterm, not the filter's own reading of+// xterm, where each string starts and ends.+import { describe, it, expect } from 'vitest'+import { readFileSync } from 'node:fs'+import { join } from 'node:path'+import { createStreamFilter } from './stream-filter'+import { xtermEntersString, xtermStringPayload } from './__fixtures__/xterm-vt500'++const ESC = '\x1b'+const BEL = '\x07'+const XTERM_PARSER = join(__dirname, '..', '..', '..', 'node_modules', '@xterm', 'xterm', 'src', 'common', 'parser')++const read = (file: string): string => readFileSync(file, 'utf8').replace(/\r\n/g, '\n')+function block(src: string, start: string, end: string): string {+ const i = src.indexOf(start)+ if (i === -1) return `<missing: ${start}>`+ return src.slice(i, src.indexOf(end, i) + end.length)+}++// mulberry32, seeded: reproducible.+function rng(seed: number): (n: number) => number {+ return (n) => {+ seed = (seed + 0x6d2b79f5) >>> 0+ let z = seed+ z = Math.imul(z ^ (z >>> 15), z | 1)+ z ^= z + Math.imul(z ^ (z >>> 7), z | 61)+ return ((z ^ (z >>> 14)) >>> 0) % n+ }+}++const LETTERS = 'abcdefghijklmnopqrstuvwxyz'+const IS_LETTER = new Set(LETTERS)+// Changing one lowercase letter to another moves neither parser: both take them as the same class+// in every state (printable, OSC/DCS data, an ESC or DCS final byte).+const flipLetter = (c: string): string => LETTERS[(LETTERS.indexOf(c) + 1) % LETTERS.length]++// Text, C0 (BEL, CAN, SUB and others), DEL, ESC, the 7-bit introducer letters, 8-bit introducers and+// other C1, and non-ASCII (U+00A0 is where xterm's NON_ASCII_PRINTABLE starts).+const SINGLES = [+ '\x00', '\t', '\n', '\r', BEL, '\x18', '\x1a', '\x19', '\x1c', '\x7f', ESC, ']', 'P', 'X', '^', '_', '[',+ '\\', ';', '0', '9', ' ', '(', 'é', ' ', '🙂', '\x85', '\x99', '\x9b', '\x9c', '\x9d', '\x90', '\x98',+ '\x9e', '\x9f'+]+const SNIPPETS = [+ [ESC, ']'], [ESC, 'P'], [ESC, 'X'], [ESC, '^'], [ESC, '_'], [ESC, '\\'], [ESC, '['], [ESC, ESC], [ESC, '\n'],+ [ESC, '\x7f'], [ESC, '('], [ESC, '\x9d'], ['\x9d'], ['\x90'], ['\x9c'], [BEL],+ [ESC, ']', '5', '2', ';', 'c', ';'], [ESC, ']', '8', ';', ';'], [ESC, 'P', 'q'], [ESC, 'P', '1', ';', '2', '$', 'q'],+ ['\x90', 'q'], [ESC, '_', 'G']+]++/** A random stream as code points, so a join lands between code points like a decoded pty read. */+function randomStream(rand: (n: number) => number): string[] {+ const cps: string[] = []+ for (let parts = 1 + rand(40); parts > 0; parts--) {+ const kind = rand(10)+ if (kind < 4) for (let i = 1 + rand(6); i > 0; i--) cps.push(LETTERS[rand(LETTERS.length)])+ else if (kind < 8) cps.push(...SNIPPETS[rand(SNIPPETS.length)])+ else cps.push(SINGLES[rand(SINGLES.length)])+ }+ return cps+}++function filterInChunks(text: string, cuts: number[], midStream: boolean): string[] {+ const f = createStreamFilter(undefined, { midStream })+ const outs: string[] = []+ let from = 0+ for (const to of [...cuts, text.length]) {+ outs.push(f.push(text.slice(from, to)))+ from = to+ }+ return outs+}++const codePoints = (s: string): number[] => Array.from(s, (c) => c.codePointAt(0) ?? 0)++/**+ * Feeds the stream from code point `join` on (xterm itself read it from the start), once as it is+ * and once with every string-payload letter after the join changed, cut into the same random+ * chunks; the two outputs must be equal, and xterm must not enter a string reading the output, as a+ * whole or any one push of it (the caller may drop pushes). Returns how many letters were changed.+ */+function checkNothingHiddenReachesOutput(cps: string[], join: number, midStream: boolean, rand: (n: number) => number): number {+ const payload = xtermStringPayload(cps.map((c) => c.codePointAt(0) ?? 0))+ let flips = 0+ const changed = cps.map((c, i) => {+ if (i < join || !payload[i] || !IS_LETTER.has(c)) return c+ flips+++ return flipLetter(c)+ })+ const text = cps.slice(join).join('')+ const cuts: number[] = []+ for (let k = rand(4); k > 0; k--) cuts.push(rand(text.length + 1))+ cuts.sort((a, b) => a - b)+ const outs = filterInChunks(text, cuts, midStream)+ const out = outs.join('')+ const ctx = JSON.stringify({ stream: cps.join(''), join, midStream, cuts, out })+ expect(filterInChunks(changed.slice(join).join(''), cuts, midStream).join(''), ctx).toBe(out)+ for (const piece of [out, ...outs]) expect(xtermEntersString(codePoints(piece)), ctx).toBe(false)+ return flips+}++describe('createStreamFilter against xterm 5.5', () => {+ it('the model is the installed xterm parser table, verbatim', () => {+ const fixture = read(join(__dirname, '__fixtures__', 'xterm-vt500.ts'))+ const constants = read(join(XTERM_PARSER, 'Constants.ts'))+ const parser = read(join(XTERM_PARSER, 'EscapeSequenceParser.ts'))+ const blocks: [string, string, string][] = [+ [constants, 'export const enum ParserState {', '\n}'],+ [constants, 'export const enum ParserAction {', '\n}'],+ [parser, 'const enum TableAccess {', '\n}'],+ [parser, 'export class TransitionTable {', '\n}'],+ [parser, 'const NON_ASCII_PRINTABLE = 0xA0;', ';'],+ [parser, 'export const VT500_TRANSITION_TABLE = (function (): TransitionTable {', '\n})();']+ ]+ for (const [src, start, end] of blocks) {+ expect(block(fixture, start, end), `re-copy ${start} from the installed xterm`).toBe(block(src, start, end))+ }+ })++ it('nothing xterm hides reaches the output, from the start of a stream', () => {+ const rand = rng(0xc0ffee)+ let flips = 0+ for (let n = 0; n < 3000; n++) flips += checkNothingHiddenReachesOutput(randomStream(rand), 0, false, rand)+ // Not vacuous: the seeded run changes ~51k payload letters here, ~28k in the midStream run.+ expect(flips).toBeGreaterThan(20_000)+ })++ it('nothing xterm hides reaches the output, joined at a random offset (midStream)', () => {+ const rand = rng(0x10ad)+ let flips = 0+ for (let n = 0; n < 3000; n++) {+ const cps = randomStream(rand)+ flips += checkNothingHiddenReachesOutput(cps, rand(cps.length + 1), true, rand)+ }+ expect(flips).toBeGreaterThan(10_000)+ })+})