Merge branch 'master' into master

.eslintrc.json

@@ -23,6 +23,8 @@
       "addons/addon-image/src/tsconfig.json",
       "addons/addon-image/test/tsconfig.json",
       "addons/addon-ligatures/src/tsconfig.json",
+      "addons/addon-progress/src/tsconfig.json",
+      "addons/addon-progress/test/tsconfig.json",
       "addons/addon-search/src/tsconfig.json",
       "addons/addon-search/test/tsconfig.json",
       "addons/addon-serialize/src/tsconfig.json",

.github/workflows/ci.yml

@@ -44,6 +44,9 @@ jobs:
           ./addons/addon-ligatures/lib/* \
           ./addons/addon-ligatures/out/* \
           ./addons/addon-ligatures/out-*/* \
+          ./addons/addon-progress/lib/* \
+          ./addons/addon-progress/out/* \
+          ./addons/addon-progress/out-*/* \
           ./addons/addon-search/lib/* \
           ./addons/addon-search/out/* \
           ./addons/addon-search/out-*/* \
@@ -63,7 +66,7 @@ jobs:
           ./addons/addon-webgl/out/* \
           ./addons/addon-webgl/out-*st/*
     - name: Upload artifacts
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: build-artifacts
         path: compressed-build.zip
@@ -105,7 +108,7 @@ jobs:
       run: |
         yarn --frozen-lockfile
         yarn install-addons
-    - uses: actions/download-artifact@v3
+    - uses: actions/download-artifact@v4
       with:
         name: build-artifacts
     - name: Unzip artifacts
@@ -147,7 +150,7 @@ jobs:
       with:
         token: ${{ secrets.GITHUB_TOKEN }}
         job: build
-    - uses: actions/download-artifact@v3
+    - uses: actions/download-artifact@v4
       with:
         name: build-artifacts
     - name: Unzip artifacts
@@ -167,9 +170,9 @@ jobs:
     strategy:
       matrix:
         node-version: [18] # just one as integration tests are about testing in browser
-        runs-on: [ubuntu] # macos is flaky
+        runs-on: [ubuntu-22.04] # macos is flaky
         browser: [chromium, firefox, webkit]
-    runs-on: ${{ matrix.runs-on }}-latest
+    runs-on: ${{ matrix.runs-on }}
     steps:
     - uses: actions/checkout@v3
     - name: Use Node.js ${{ matrix.node-version }}.x
@@ -188,7 +191,7 @@ jobs:
       with:
         token: ${{ secrets.GITHUB_TOKEN }}
         job: build
-    - uses: actions/download-artifact@v3
+    - uses: actions/download-artifact@v4
       with:
         name: build-artifacts
     - name: Unzip artifacts
@@ -212,6 +215,8 @@ jobs:
       run: yarn test-integration-${{ matrix.browser }} --workers=50% --forbid-only --suite=addon-fit
     - name: Integration tests (addon-image)
       run: yarn test-integration-${{ matrix.browser }} --workers=50% --forbid-only --suite=addon-image
+    - name: Integration tests (addon-progress)
+      run: yarn test-integration-${{ matrix.browser }} --workers=50% --forbid-only --suite=addon-progress
     - name: Integration tests (addon-search)
       run: yarn test-integration-${{ matrix.browser }} --workers=50% --forbid-only --suite=addon-search
     - name: Integration tests (addon-serialize)
@@ -244,7 +249,7 @@ jobs:
         yarn install-addons
     - name: Install playwright
       run: npx playwright install
-    - uses: actions/download-artifact@v3
+    - uses: actions/download-artifact@v4
       with:
         name: build-artifacts
     - name: Unzip artifacts

README.md

@@ -226,6 +226,9 @@ Xterm.js is used in several world-class applications to provide great terminal e
 - [**OpenSFTP**](https://opensftp.com): Super beautiful SSH and SFTP integrated workspace client.
 - [**balena**](https://www.balena.io/): Balena is a full-stack solution for developing, deploying, updating, and troubleshooting IoT Edge devices. We use xterm.js to manage & debug devices on [balenaCloud](https://www.balena.io/cloud).
 - [**Filet Cloud**](https://github.com/fuglaro/filet-cloud): The lean and powerful personal cloud ⛅.
+- [**pyTermTk**](https://github.com/ceccopierangiolieugenio/pyTermTk): Python Terminal Toolkit - a Spiced Up Cross Compatible TUI Library 🌶️, use xterm.js for the [HTML5 exporter](https://ceccopierangiolieugenio.github.io/pyTermTk/sandbox/sandbox.html).
+- [**ecmaOS**](https://ecmaos.sh): A kernel and suite of applications tying modern web technologies into a browser-based operating system.
+- [**LabEx**](https://labex.io): Interactive learning platform with hands-on labs and xterm.js-based online terminals, focused on learn-by-doing approach.
 - [And much more...](https://github.com/xtermjs/xterm.js/network/dependents?package_id=UGFja2FnZS0xNjYzMjc4OQ%3D%3D)
 
 Do you use xterm.js in your application as well? Please [open a Pull Request](https://github.com/sourcelair/xterm.js/pulls) to include it here. We would love to have it on our list. Note: Please add any new contributions to the end of the list only.

addons/addon-fit/typings/addon-fit.d.ts

@@ -39,7 +39,7 @@ declare module '@xterm/addon-fit' {
   }
 
   /**
-   * Reprepresents the dimensions of a terminal.
+   * Represents the dimensions of a terminal.
    */
   export interface ITerminalDimensions {
     /**

addons/addon-ligatures/src/LigaturesAddon.ts

@@ -15,19 +15,22 @@ export interface ITerminalAddon {
 
 export class LigaturesAddon implements ITerminalAddon , ILigaturesApi {
   private readonly _fallbackLigatures: string[];
+  private readonly _fontFeatureSettings?: string;
 
   private _terminal: Terminal | undefined;
   private _characterJoinerId: number | undefined;
 
   constructor(options?: Partial<ILigatureOptions>) {
+    // Source: calt set from https://github.com/be5invis/Iosevka?tab=readme-ov-file#ligations
     this._fallbackLigatures = (options?.fallbackLigatures || [
       '<--', '<---', '<<-', '<-', '->', '->>', '-->', '--->',
       '<==', '<===', '<<=', '<=', '=>', '=>>', '==>', '===>', '>=', '>>=',
-      '<->', '<-->', '<--->', '<---->', '<=>', '<==>', '<===>', '<====>', '-------->',
-      '<~~', '<~', '~>', '~~>', '::', ':::', '==', '!=', '===', '!==',
-      ':=', ':-', ':+', '<*', '<*>', '*>', '<|', '<|>', '|>', '+:', '-:', '=:', ':>',
-      '++', '+++', '<!--', '<!---', '<***>'
+      '<->', '<-->', '<--->', '<---->', '<=>', '<==>', '<===>', '<====>', '::', ':::',
+      '<~~', '</', '</>', '/>', '~~>', '==', '!=', '/=', '~=', '<>', '===', '!==', '!===',
+      '<:', ':=', '*=', '*+', '<*', '<*>', '*>', '<|', '<|>', '|>', '+*', '=*', '=:', ':>',
+      '/*', '*/', '+++', '<!--', '<!---'
     ]).sort((a, b) => b.length - a.length);
+    this._fontFeatureSettings = options?.fontFeatureSettings;
   }
 
   public activate(terminal: Terminal): void {
@@ -36,7 +39,7 @@ export class LigaturesAddon implements ITerminalAddon , ILigaturesApi {
     }
     this._terminal = terminal;
     this._characterJoinerId = enableLigatures(terminal, this._fallbackLigatures);
-    terminal.element.style.fontFeatureSettings = '"liga" on, "calt" on';
+    terminal.element.style.fontFeatureSettings = this._fontFeatureSettings ?? '"calt" on';
   }
 
   public dispose(): void {

addons/addon-ligatures/src/Types.ts

@@ -5,4 +5,5 @@
 
 export interface ILigatureOptions {
   fallbackLigatures: string[];
+  fontFeatureSettings: string;
 }

addons/addon-ligatures/typings/addon-ligatures.d.ts

@@ -23,7 +23,10 @@ declare module '@xterm/addon-ligatures' {
     constructor(options?: Partial<ILigatureOptions>);
 
     /**
-     * Activates the addon
+     * Activates the addon. Note that if webgl is also being used, that addon
+     * should be reactivated after ligatures is activated in order to apply
+     * {@link ILigatureOptions.fontFeatureSettings} to the texture atlas.
+     *
      *
      * @param terminal The terminal the addon is being loaded in.
      */
@@ -40,19 +43,28 @@ declare module '@xterm/addon-ligatures' {
    */
   export interface ILigatureOptions {
     /**
-     * Fallback ligatures to use when the font access API is either not supported by the browser or
-     * access is denied. The default set of ligatures is taken from Iosevka's default "calt"
-     * ligation set: https://typeof.net/Iosevka/
+     * Fallback ligatures to use when the font access API is either not
+     * supported by the browser or access is denied. The default set of
+     * ligatures is taken from Iosevka's default "calt" ligation set:
+     * https://typeof.net/Iosevka/
      *
      * ```
      * <-- <--- <<- <- -> ->> --> --->
      * <== <=== <<= <= => =>> ==> ===> >= >>=
-     * <-> <--> <---> <----> <=> <==> <===> <====> -------->
-     * <~~ <~ ~> ~~> :: ::: == != === !==
-     * := :- :+ <* <*> *> <| <|> |> +: -: =: :>
-     * ++ +++ <!-- <!--- <***>
-     * ```
+     * <-> <--> <---> <----> <=> <==> <===> <====> :: :::
+     * <~~ </ </> /> ~~> == != /= ~= <> === !== !===
+     * <: := *= *+ <* <*> *> <| <|> |> +* =* =: :>
+     * /* <close block comment> +++ <!-- <!---
      */
     fallbackLigatures: string[]
+
+    /**
+     * The CSS `font-feature-settings` value to use for enabling ligatures. This
+     * also supports font variants for example with a value like
+     * `"calt" on, "ss03"`.
+     *
+     * The default value is `"calt" on`.
+     */
+    fontFeatureSettings: string;
   }
 }

addons/addon-progress/.gitignore

@@ -0,0 +1,2 @@
+lib
+node_modules

addons/addon-progress/.npmignore

@@ -0,0 +1,32 @@
+# Blacklist - exclude everything except npm defaults such as LICENSE, etc
+*
+!*/
+
+# Whitelist - lib/
+!lib/**/*.d.ts
+
+!lib/**/*.js
+!lib/**/*.js.map
+
+!lib/**/*.mjs
+!lib/**/*.mjs.map
+
+!lib/**/*.css
+
+# Whitelist - src/
+!src/**/*.ts
+!src/**/*.d.ts
+
+!src/**/*.js
+!src/**/*.js.map
+
+!src/**/*.css
+
+# Blacklist - src/ test files
+src/**/*.test.ts
+src/**/*.test.d.ts
+src/**/*.test.js
+src/**/*.test.js.map
+
+# Whitelist - typings/
+!typings/*.d.ts

addons/addon-progress/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2024, The xterm.js authors (https://github.com/xtermjs/xterm.js)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

addons/addon-progress/README.md

@@ -0,0 +1,69 @@
+## @xterm/addon-progress
+
+An xterm.js addon providing an interface for ConEmu's progress sequence.
+See https://conemu.github.io/en/AnsiEscapeCodes.html#ConEmu_specific_OSC for sequence details.
+
+
+### Install
+
+```bash
+npm install --save @xterm/addon-progress
+```
+
+
+### Usage
+
+```ts
+import { Terminal } from '@xterm/xterm';
+import { ProgressAddon, IProgressState } from '@xterm/addon-progress';
+
+const terminal = new Terminal();
+const progressAddon = new ProgressAddon();
+terminal.loadAddon(progressAddon);
+progressAddon.onChange({state, value}: IProgressState) => {
+  // state: 0-4 integer (see below for meaning)
+  // value: 0-100 integer (percent value)
+  
+  // do your visualisation based on state/value here
+  ...
+});
+```
+
+See the full [API](https://github.com/xtermjs/xterm.js/blob/master/addons/addon-progress/typings/addon-progress.d.ts) for more advanced usage.
+
+### Sequence
+
+The sequence to set progress information has the following format:
+
+```plain
+ESC ] 9 ; 4 ; <state> ; <progress value> BEL
+```
+
+where state is a decimal number in 0 to 4 and progress value is a decimal number in 0 to 100.
+The states have the following meaning:
+
+- 0: Remove any progress indication. Also resets progress value to 0. A given progress value will be ignored.
+- 1: Normal state to set a progress value. The value should be in 0..100, greater values are clamped to 100.
+  If the value is omitted, it will be set to 0.
+- 2: Error state with an optional progress value. An omitted value will be set to 0,
+  which has a special meaning using the last active value.
+- 3: Actual progress is "indeterminate", any progress value will be ignored. Meant to be used to indicate
+  a running task without progress information (e.g. by a spinner). A previously set progress value
+  by any other state sequence will be left untouched.
+- 4: Pause or warning state with an optional progress value. An omitted value will be set to 0,
+  which has a special meaning using the last active value.
+
+The addon resolves most of those semantic nuances and will provide these ready-to-go values:
+- For the remove state (0) any progress value wont be parsed, thus is even allowed to contain garbage.
+  It will always emit `{state: 0, value: 0}`.
+- For the set state (1) an omitted value will be set to 0 emitting `{state: 1, value: 0}`.
+  If a value was given, it must be decimal digits only, any characters outside will mark the whole sequence
+  as faulty (no sloppy integer parsing). The value will be clamped to max 100 giving
+  `{state: 1, value: parsedAndClampedValue}`.
+- For the error and pause state (2 & 4) an omitted or zero value will emit `{state: 2|4, value: lastValue}`.
+  If a value was given, it must be decimal digits only, any characters outside will mark the whole sequence
+  as faulty (no sloppy integer parsing). The value will be clamped to max 100 giving
+  `{state: 2|4, value: parsedAndClampedValue}`.
+- For the indeterminate state (3) a value notion will be ignored.
+  It still emits the value as `{state: 3, value: lastValue}`. Keep in mind not use that value while
+  that state is active, as a task might have entered that state without a proper reset at the beginning.

addons/addon-progress/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@xterm/addon-progress",
+  "version": "0.1.0",
+  "author": {
+    "name": "The xterm.js authors",
+    "url": "https://xtermjs.org/"
+  },
+  "main": "lib/addon-progress.js",
+  "module": "lib/addon-progress.mjs",
+  "types": "typings/addon-progress.d.ts",
+  "repository": "https://github.com/xtermjs/xterm.js/tree/master/addons/addon-progress",
+  "license": "MIT",
+  "keywords": [
+    "terminal",
+    "xterm",
+    "xterm.js"
+  ],
+  "scripts": {
+    "build": "../../node_modules/.bin/tsc -p .",
+    "prepackage": "npm run build",
+    "package": "../../node_modules/.bin/webpack",
+    "prepublishOnly": "npm run package",
+    "start": "node ../../demo/start"
+  },
+  "peerDependencies": {
+    "@xterm/xterm": "^5.0.0"
+  }
+}

addons/addon-progress/src/ProgressAddon.ts

@@ -0,0 +1,102 @@
+/**
+ * Copyright (c) 2024 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import type { Terminal, ITerminalAddon, IDisposable } from '@xterm/xterm';
+import type { ProgressAddon as IProgressApi, IProgressState } from '@xterm/addon-progress';
+import type { Emitter, Event } from 'vs/base/common/event';
+
+
+const enum ProgressType {
+  REMOVE = 0,
+  SET = 1,
+  ERROR = 2,
+  INDETERMINATE = 3,
+  PAUSE = 4
+}
+
+
+/**
+ * Strict integer parsing, only decimal digits allowed.
+ */
+function toInt(s: string): number {
+  let v = 0;
+  for (let i = 0; i < s.length; ++i) {
+    const c = s.charCodeAt(i);
+    if (c < 0x30 || 0x39 < c) {
+      return -1;
+    }
+    v = v * 10 + c - 48;
+  }
+  return v;
+}
+
+
+export class ProgressAddon implements ITerminalAddon, IProgressApi {
+  private _seqHandler: IDisposable | undefined;
+  private _st: ProgressType = ProgressType.REMOVE;
+  private _pr = 0;
+  // HACK: This uses ! to align with the API, this should be fixed when 5283 is resolved
+  private _onChange!: Emitter<IProgressState>;
+  public onChange!: Event<IProgressState>;
+
+  public dispose(): void {
+    this._seqHandler?.dispose();
+    this._onChange?.dispose();
+  }
+
+  public activate(terminal: Terminal): void {
+    this._seqHandler = terminal.parser.registerOscHandler(9, data => {
+      if (!data.startsWith('4;')) {
+        return false;
+      }
+      const parts = data.split(';');
+
+      if (parts.length > 3) {
+        return true;  // faulty sequence, just exit
+      }
+      if (parts.length === 2) {
+        parts.push('');
+      }
+      const st = toInt(parts[1]);
+      const pr = toInt(parts[2]);
+
+      switch (st) {
+        case ProgressType.REMOVE:
+          this.progress = { state: st, value: 0 };
+          break;
+        case ProgressType.SET:
+          if (pr < 0) return true;  // faulty sequence, just exit
+          this.progress = { state: st, value: pr };
+          break;
+        case ProgressType.ERROR:
+        case ProgressType.PAUSE:
+          if (pr < 0) return true;  // faulty sequence, just exit
+          this.progress = { state: st, value: pr || this._pr };
+          break;
+        case ProgressType.INDETERMINATE:
+          this.progress = { state: st, value: this._pr };
+          break;
+      }
+      return true;
+    });
+    // FIXME: borrow emitter ctor from xterm, to be changed once #5283 is resolved
+    this._onChange = new (terminal as any)._core._onData.constructor();
+    this.onChange = this._onChange!.event;
+  }
+
+  public get progress(): IProgressState {
+    return { state: this._st, value: this._pr };
+  }
+
+  public set progress(progress: IProgressState) {
+    if (progress.state < 0 || progress.state > 4) {
+      console.warn(`progress state out of bounds, not applied`);
+      return;
+    }
+    this._st = progress.state;
+    this._pr = Math.min(Math.max(progress.value, 0), 100);
+    this._onChange?.fire({ state: this._st, value: this._pr });
+  }
+}

addons/addon-progress/src/tsconfig.json

@@ -0,0 +1,42 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "target": "es2021",
+    "lib": [
+      "dom",
+      "es2015"
+    ],
+    "rootDir": ".",
+    "outDir": "../out",
+    "sourceMap": true,
+    "removeComments": true,
+    "strict": true,
+    "types": [
+      "../../../node_modules/@types/mocha",
+      "../../../src/vs/typings/thenable"
+    ],
+    "paths": {
+      "browser/*": [
+        "../../../src/browser/*"
+      ],
+      "vs/*": [
+        "../../../src/vs/*"
+      ],
+      "@xterm/addon-progress": [
+        "../typings/addon-progress.d.ts"
+      ]
+    }
+  },
+  "include": [
+    "./**/*",
+    "../../../typings/xterm.d.ts"
+  ],
+  "references": [
+    {
+      "path": "../../../src/browser"
+    },
+    {
+      "path": "../../../src/vs"
+    }
+  ]
+}

addons/addon-progress/test/ProgressAddon.test.ts

@@ -0,0 +1,129 @@
+/**
+ * Copyright (c) 2024 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import test from '@playwright/test';
+import { deepStrictEqual } from 'assert';
+import { ITestContext, createTestContext, openTerminal } from '../../../test/playwright/TestUtils';
+
+
+let ctx: ITestContext;
+test.beforeAll(async ({ browser }) => {
+  ctx = await createTestContext(browser);
+  ctx.page.setViewportSize({ width: 1024, height: 768 });
+  await openTerminal(ctx);
+});
+test.afterAll(async () => await ctx.page.close());
+
+
+test.describe('ProgressAddon', () => {
+  test.beforeEach(async function(): Promise<any> {
+    await ctx.page.evaluate(`
+      window.progressStack = [];
+      window.term.reset();
+      window.progressAddon?.dispose();
+      window.progressAddon = new ProgressAddon();
+      window.term.loadAddon(window.progressAddon);
+      window.progressAddon.onChange(progress => window.progressStack.push(progress));
+    `);
+  });
+
+  test('initial values should be 0;0', async () => {
+    deepStrictEqual(await ctx.page.evaluate('window.progressAddon.progress'), {state: 0, value: 0});
+  });
+  test('state 0: remove', async () => {
+    // no value
+    await ctx.proxy.write('\x1b]9;4;0\x1b\\');
+    deepStrictEqual(await ctx.page.evaluate('window.progressStack'), [{state: 0, value: 0}]);
+    // value ignored
+    await ctx.proxy.write('\x1b]9;4;0;12\x1b\\');
+    deepStrictEqual(await ctx.page.evaluate('window.progressStack'), [{state: 0, value: 0}, {state: 0, value: 0}]);
+  });
+  test('state 1: set', async () => {
+    // set 10%
+    await ctx.proxy.write('\x1b]9;4;1;10\x1b\\');
+    deepStrictEqual(await ctx.page.evaluate('window.progressStack'), [{state: 1, value: 10}]);
+    // set 50%
+    await ctx.proxy.write('\x1b]9;4;1;50\x1b\\');
+    deepStrictEqual(await ctx.page.evaluate('window.progressStack'), [{state: 1, value: 10}, {state: 1, value: 50}]);
+    // set 23%
+    await ctx.proxy.write('\x1b]9;4;1;23\x1b\\');
+    deepStrictEqual(await ctx.page.evaluate('window.progressStack'), [{state: 1, value: 10}, {state: 1, value: 50}, {state: 1, value: 23}]);
+  });
+  test('state 1: set - special sequence handling', async () => {
+    // missing progress value defaults to 0
+    await ctx.proxy.write('\x1b]9;4;1\x1b\\');
+    deepStrictEqual(await ctx.page.evaluate('window.progressStack'), [{state: 1, value: 0}]);
+    // malformed progress value get ignored
+    await ctx.proxy.write('\x1b]9;4;1;12x\x1b\\');
+    deepStrictEqual(await ctx.page.evaluate('window.progressStack'), [{state: 1, value: 0}]);
+    // out of bounds gets clamped to 100
+    await ctx.proxy.write('\x1b]9;4;1;123\x1b\\');
+    deepStrictEqual(await ctx.page.evaluate('window.progressStack'), [{state: 1, value: 0}, {state: 1, value: 100}]);
+  });
+  test('state 2: error - preserve previous value on empty/0', async () => {
+    // set value to 12
+    await ctx.proxy.write('\x1b]9;4;1;12\x1b\\');
+    // omitted/empty/0 value emits previous value
+    await ctx.proxy.write('\x1b]9;4;2\x1b\\');
+    await ctx.proxy.write('\x1b]9;4;2;\x1b\\');
+    await ctx.proxy.write('\x1b]9;4;2;0\x1b\\');
+    deepStrictEqual(
+      await ctx.page.evaluate('window.progressStack'),
+      [{state: 1, value: 12}, {state: 2, value: 12}, {state: 2, value: 12}, {state: 2, value: 12}]
+    );
+  });
+  test('state 2: error - with new value', async () => {
+    // set value to 12
+    await ctx.proxy.write('\x1b]9;4;1;12\x1b\\');
+    // new value updates clamped
+    await ctx.proxy.write('\x1b]9;4;2;25\x1b\\');
+    await ctx.proxy.write('\x1b]9;4;2;123\x1b\\');
+    deepStrictEqual(
+      await ctx.page.evaluate('window.progressStack'),
+      [{state: 1, value: 12}, {state: 2, value: 25}, {state: 2, value: 100}]
+    );
+  });
+  test('state 3: indeterminate - keeps value untouched', async () => {
+    // set value to 12
+    await ctx.proxy.write('\x1b]9;4;1;12\x1b\\');
+    // new value updates clamped
+    await ctx.proxy.write('\x1b]9;4;3\x1b\\');
+    await ctx.proxy.write('\x1b]9;4;3;123\x1b\\');
+    deepStrictEqual(
+      await ctx.page.evaluate('window.progressStack'),
+      [{state: 1, value: 12}, {state: 3, value: 12}, {state: 3, value: 12}]
+    );
+  });
+  test('state 4: pause - preserve previous value on empty/0', async () => {
+    // set value to 12
+    await ctx.proxy.write('\x1b]9;4;1;12\x1b\\');
+    // omitted/empty/0 value emits previous value
+    await ctx.proxy.write('\x1b]9;4;4\x1b\\');
+    await ctx.proxy.write('\x1b]9;4;4;\x1b\\');
+    await ctx.proxy.write('\x1b]9;4;4;0\x1b\\');
+    deepStrictEqual(
+      await ctx.page.evaluate('window.progressStack'),
+      [{state: 1, value: 12}, {state: 4, value: 12}, {state: 4, value: 12}, {state: 4, value: 12}]
+    );
+  });
+  test('state 4: pause - with new value', async () => {
+    // set value to 12
+    await ctx.proxy.write('\x1b]9;4;1;12\x1b\\');
+    // new value updates clamped
+    await ctx.proxy.write('\x1b]9;4;4;25\x1b\\');
+    await ctx.proxy.write('\x1b]9;4;4;123\x1b\\');
+    deepStrictEqual(
+      await ctx.page.evaluate('window.progressStack'),
+      [{state: 1, value: 12}, {state: 4, value: 25}, {state: 4, value: 100}]
+    );
+  });
+  test('invalid sequences should not emit anything', async () => {
+    // illegal state
+    await ctx.proxy.write('\x1b]9;4;5;12\x1b\\');
+    // illegal chars in value
+    await ctx.proxy.write('\x1b]9;4;1; 123xxxx\x1b\\');
+    deepStrictEqual(await ctx.page.evaluate('window.progressStack'), []);
+  });
+});

addons/addon-progress/test/playwright.config.ts

@@ -0,0 +1,35 @@
+import { PlaywrightTestConfig } from '@playwright/test';
+
+const config: PlaywrightTestConfig = {
+  testDir: '.',
+  timeout: 10000,
+  projects: [
+    {
+      name: 'ChromeStable',
+      use: {
+        browserName: 'chromium',
+        channel: 'chrome'
+      }
+    },
+    {
+      name: 'FirefoxStable',
+      use: {
+        browserName: 'firefox'
+      }
+    },
+    {
+      name: 'WebKit',
+      use: {
+        browserName: 'webkit'
+      }
+    }
+  ],
+  reporter: 'list',
+  webServer: {
+    command: 'npm run start',
+    port: 3000,
+    timeout: 120000,
+    reuseExistingServer: !process.env.CI
+  }
+};
+export default config;

addons/addon-progress/test/tsconfig.json

@@ -0,0 +1,41 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "target": "ESNext",
+    "lib": [
+      "es2021",
+    ],
+    "rootDir": ".",
+    "outDir": "../out-test",
+    "sourceMap": true,
+    "removeComments": true,
+    "baseUrl": ".",
+    "paths": {
+      "common/*": [
+        "../../../src/common/*"
+      ],
+      "browser/*": [
+        "../../../src/browser/*"
+      ]
+    },
+    "strict": true,
+    "types": [
+      "../../../node_modules/@types/node"
+    ]
+  },
+  "include": [
+    "./**/*",
+    "../../../typings/xterm.d.ts"
+  ],
+  "references": [
+    {
+      "path": "../../../src/common"
+    },
+    {
+      "path": "../../../src/browser"
+    },
+    {
+      "path": "../../../test/playwright"
+    }
+  ]
+}

addons/addon-progress/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "files": [],
+  "include": [],
+  "references": [
+    { "path": "./src" },
+    { "path": "./test" }
+  ]
+}

addons/addon-progress/typings/addon-progress.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Copyright (c) 2024 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import { Terminal, ITerminalAddon, IDisposable, IEvent } from '@xterm/xterm';
+
+declare module '@xterm/addon-progress' {
+  /**
+   * An xterm.js addon that provides an interface for ConEmu's progress
+   * sequence.
+   */
+  export class ProgressAddon implements ITerminalAddon, IDisposable {
+
+    /**
+     * Creates a new progress addon
+     */
+    constructor();
+
+    /**
+     * Activates the addon
+     * @param terminal The terminal the addon is being loaded in.
+     */
+    public activate(terminal: Terminal): void;
+
+    /**
+     * Disposes the addon.
+     */
+    public dispose(): void;
+
+    /**
+     * An event that fires when the tracked progress changes.
+     */
+    public readonly onChange: IEvent<IProgressState>;
+
+    /**
+     * Gets or sets the current progress tracked by the addon. This can be used
+     * to reset a stuck progress indicator back to initial with
+     * `{ state: 0, value: 0 }` or to restore an indicator.
+     */
+    public progress: IProgressState;
+  }
+
+  /**
+   * Progress state tracked by the addon.
+   */
+  export interface IProgressState {
+    /**
+     * The progress state.
+     *
+     * - `0`: No progress. Setting this will resets progress value to 0
+     *   regardless of the {@link value} used.
+     * - `1`: Normal percentage-based from 0 to 100.
+     * - `2`: Error with an optional progress value from 0 to 100.
+     * - `3`: Indeterminate progress, any progress value will be ignored. This
+     *   is used to indicate work is happening but a percentage value cannot be
+     *   determined.
+     * - `4`: Pause or warning state with an optional progress value.
+     */
+    state: 0 | 1 | 2 | 3 | 4;
+
+    /**
+     * The percentage value of progress from 0 to 100. See {@link state} for
+     * whether this is relevant.
+     */
+    value: number;
+  }
+}

addons/addon-progress/webpack.config.js

@@ -0,0 +1,42 @@
+/**
+ * Copyright (c) 2024 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+const path = require('path');
+
+const addonName = 'ProgressAddon';
+const mainFile = 'addon-progress.js';
+
+module.exports = {
+  entry: `./out/${addonName}.js`,
+  devtool: 'source-map',
+  module: {
+    rules: [
+      {
+        test: /\.js$/,
+        use: ["source-map-loader"],
+        enforce: "pre",
+        exclude: /node_modules/
+      }
+    ]
+  },
+  resolve: {
+    modules: ['./node_modules'],
+    extensions: [ '.js' ],
+    alias: {
+      common: path.resolve('../../out/common'),
+      browser: path.resolve('../../out/browser'),
+      vs: path.resolve('../../out/vs')
+    }
+  },
+  output: {
+    filename: mainFile,
+    path: path.resolve('./lib'),
+    library: addonName,
+    libraryTarget: 'umd',
+    // Force usage of globalThis instead of global / self. (This is cross-env compatible)
+    globalObject: 'globalThis',
+  },
+  mode: 'production'
+};