From 8576581574673282d0e71a9d925180139d37bdb5 Mon Sep 17 00:00:00 2001 From: tabarra <1808295+tabarra@users.noreply.github.com> Date: Sun, 2 Mar 2025 09:28:50 -0300 Subject: [PATCH 1/3] docs: added usage tip for registerMarker() --- typings/xterm.d.ts | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/typings/xterm.d.ts b/typings/xterm.d.ts index 15a03327..0b3b3977 100644 --- a/typings/xterm.d.ts +++ b/typings/xterm.d.ts @@ -1159,7 +1159,18 @@ declare module '@xterm/xterm' { deregisterCharacterJoiner(joinerId: number): void; /** - * Adds a marker to the normal buffer and returns it. + * Adds a marker to the normal buffer and returns it. + * NOTE: If you are synchronously writing data line-by-line (as in, doing + * multiple `term.writeln()`before the terminal re-rendering), the cursorY + * position will not be updated until after all pending terminal writes, + * which will result in the markers offset being calculated from the + * position cursorY was when your batch of writes started. + * Dealing with this issue by setting `cursorYOffset` to be index of this + * line in your batch will fail if you have any line wraps prior to it. + * Instead, consider registering a marker inside a write callback, eg.: + * ```ts + * term.writeln(data, () => term.registerMarker(...)) + * ``` * @param cursorYOffset The y position offset of the marker from the cursor. * @returns The new marker or undefined. */ From a8ead811bfea4521ee4f77ed8a26a9cc5a81e9c3 Mon Sep 17 00:00:00 2001 From: Daniel Imms <2193314+Tyriar@users.noreply.github.com> Date: Tue, 22 Apr 2025 02:47:21 -0700 Subject: [PATCH 2/3] Move clarification into write apis --- typings/xterm-headless.d.ts | 6 ++++-- typings/xterm.d.ts | 19 +++++-------------- 2 files changed, 9 insertions(+), 16 deletions(-) diff --git a/typings/xterm-headless.d.ts b/typings/xterm-headless.d.ts index 8d1facc7..9397dfe4 100644 --- a/typings/xterm-headless.d.ts +++ b/typings/xterm-headless.d.ts @@ -837,7 +837,8 @@ declare module '@xterm/headless' { * bytes given as Uint8Array from the pty or a string. Raw bytes will always * be treated as UTF-8 encoded, string data as UTF-16. * @param callback Optional callback that fires when the data was processed - * by the parser. + * by the parser. This callback must be provided and awaited in order for + * {@link buffer} to reflect the change in the write. */ write(data: string | Uint8Array, callback?: () => void): void; @@ -847,7 +848,8 @@ declare module '@xterm/headless' { * bytes given as Uint8Array from the pty or a string. Raw bytes will always * be treated as UTF-8 encoded, string data as UTF-16. * @param callback Optional callback that fires when the data was processed - * by the parser. + * by the parser. This callback must be provided and awaited in order for + * {@link buffer} to reflect the change in the write. */ writeln(data: string | Uint8Array, callback?: () => void): void; diff --git a/typings/xterm.d.ts b/typings/xterm.d.ts index 154ea57f..b4ba20fe 100644 --- a/typings/xterm.d.ts +++ b/typings/xterm.d.ts @@ -1166,18 +1166,7 @@ declare module '@xterm/xterm' { deregisterCharacterJoiner(joinerId: number): void; /** - * Adds a marker to the normal buffer and returns it. - * NOTE: If you are synchronously writing data line-by-line (as in, doing - * multiple `term.writeln()`before the terminal re-rendering), the cursorY - * position will not be updated until after all pending terminal writes, - * which will result in the markers offset being calculated from the - * position cursorY was when your batch of writes started. - * Dealing with this issue by setting `cursorYOffset` to be index of this - * line in your batch will fail if you have any line wraps prior to it. - * Instead, consider registering a marker inside a write callback, eg.: - * ```ts - * term.writeln(data, () => term.registerMarker(...)) - * ``` + * Adds a marker to the normal buffer and returns it. * @param cursorYOffset The y position offset of the marker from the cursor. * @returns The new marker or undefined. */ @@ -1280,7 +1269,8 @@ declare module '@xterm/xterm' { * bytes given as Uint8Array from the pty or a string. Raw bytes will always * be treated as UTF-8 encoded, string data as UTF-16. * @param callback Optional callback that fires when the data was processed - * by the parser. + * by the parser. This callback must be provided and awaited in order for + * {@link buffer} to reflect the change in the write. */ write(data: string | Uint8Array, callback?: () => void): void; @@ -1290,7 +1280,8 @@ declare module '@xterm/xterm' { * bytes given as Uint8Array from the pty or a string. Raw bytes will always * be treated as UTF-8 encoded, string data as UTF-16. * @param callback Optional callback that fires when the data was processed - * by the parser. + * by the parser. This callback must be provided and awaited in order for + * {@link buffer} to reflect the change in the write. */ writeln(data: string | Uint8Array, callback?: () => void): void; From 78fbae3293e8c79f746b939cec42d275148bce4a Mon Sep 17 00:00:00 2001 From: Daniel Imms <2193314+Tyriar@users.noreply.github.com> Date: Tue, 22 Apr 2025 02:53:35 -0700 Subject: [PATCH 3/3] Add additional note to main doc --- typings/xterm-headless.d.ts | 8 ++++++++ typings/xterm.d.ts | 8 ++++++++ 2 files changed, 16 insertions(+) diff --git a/typings/xterm-headless.d.ts b/typings/xterm-headless.d.ts index 9397dfe4..11d97947 100644 --- a/typings/xterm-headless.d.ts +++ b/typings/xterm-headless.d.ts @@ -833,6 +833,10 @@ declare module '@xterm/headless' { /** * Write data to the terminal. + * + * Note that the change will not be reflected in the {@link buffer} + * immediately as the data is processed asynchronously. Provide a + * {@link callback} to know when the data was processed. * @param data The data to write to the terminal. This can either be raw * bytes given as Uint8Array from the pty or a string. Raw bytes will always * be treated as UTF-8 encoded, string data as UTF-16. @@ -844,6 +848,10 @@ declare module '@xterm/headless' { /** * Writes data to the terminal, followed by a break line character (\n). + * + * Note that the change will not be reflected in the {@link buffer} + * immediately as the data is processed asynchronously. Provide a + * {@link callback} to know when the data was processed. * @param data The data to write to the terminal. This can either be raw * bytes given as Uint8Array from the pty or a string. Raw bytes will always * be treated as UTF-8 encoded, string data as UTF-16. diff --git a/typings/xterm.d.ts b/typings/xterm.d.ts index b4ba20fe..d1c2667d 100644 --- a/typings/xterm.d.ts +++ b/typings/xterm.d.ts @@ -1265,6 +1265,10 @@ declare module '@xterm/xterm' { /** * Write data to the terminal. + * + * Note that the change will not be reflected in the {@link buffer} + * immediately as the data is processed asynchronously. Provide a + * {@link callback} to know when the data was processed. * @param data The data to write to the terminal. This can either be raw * bytes given as Uint8Array from the pty or a string. Raw bytes will always * be treated as UTF-8 encoded, string data as UTF-16. @@ -1276,6 +1280,10 @@ declare module '@xterm/xterm' { /** * Writes data to the terminal, followed by a break line character (\n). + * + * Note that the change will not be reflected in the {@link buffer} + * immediately as the data is processed asynchronously. Provide a + * {@link callback} to know when the data was processed. * @param data The data to write to the terminal. This can either be raw * bytes given as Uint8Array from the pty or a string. Raw bytes will always * be treated as UTF-8 encoded, string data as UTF-16.