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] 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;