simplify stack save in parser

src/common/InputHandler.ts

@@ -460,7 +460,9 @@ export class InputHandler extends Disposable implements IInputHandler {
     super.dispose();
   }
 
-  // FIXME: cleanup async handling
+  /**
+   * Async parse support.
+   */
   private _parseStack = {
     paused: false,
     cursorStartX: 0,
@@ -468,7 +470,6 @@ export class InputHandler extends Disposable implements IInputHandler {
     decodedLength: 0,
     position: 0
   };
-
   private _preserveStack(cursorStartX: number, cursorStartY: number, decodedLength: number, position: number): void {
     this._parseStack.paused = true;
     this._parseStack.cursorStartX = cursorStartX;
@@ -477,6 +478,19 @@ export class InputHandler extends Disposable implements IInputHandler {
     this._parseStack.position = position;
   }
 
+  /**
+   * Parse call with async handler support.
+   *
+   * Whether the stack state got preserved for the next call, is indicated by the return value:
+   * - undefined (void):
+   *   all handlers were sync, no stack save, continue normally with next chunk
+   * - Promise\<boolean\>:
+   *   execution stopped at async handler, stack saved, continue with
+   *   same chunk and the promise resolve value as `promiseResult` until the method returns `undefined`
+   *
+   * Note: Never call this directly for a running terminal instance in production.
+   * Always use `Terminal.write`, which provides in-band blocking and correct exection order.
+   */
   public parse(data: string | Uint8Array, promiseResult?: boolean): void | Promise<boolean> {
     let result: void | Promise<boolean>;
     let buffer = this._bufferService.buffer;