Fix webpack aliases for target-* module paths and out/primitives+runtime

Co-authored-by: Daniel Imms <Tyriar@users.noreply.github.com>

AGENTS.md

@@ -2,10 +2,13 @@
 
 ## Architecture Overview
 
-**Core Structure**: xterm.js is a multi-target terminal emulator with three main distributions:
+**Core Structure**: xterm.js is a multi-target terminal emulator with these main source areas:
-- `src/browser/`: Full-featured browser terminal with DOM rendering
+- `src/primitives/`: Building blocks (buffer, parser, input, data, utilities); TypeScript project `src/primitives/tsconfig.json`
-- `src/headless/`: Server-side terminal for Node.js (no DOM)
+- `src/runtime/`: Services, `CoreTerminal`, `InputHandler`, public API adapters; TypeScript project `src/runtime/tsconfig.json`
-- `src/common/`: Shared core logic (parsing, buffer management, terminal state)
+- `src/target-browser/`: Browser terminal with DOM rendering
+- `src/target-headless/`: Node terminal without DOM
+
+See `src/ARCHITECTURE.md` for the dependency graph and import-path conventions (`common/*`, `target-browser/*`, `target-headless/*`).
 
 **Key Classes**:
 - `Terminal` (browser/headless): Public API wrapper

addons/addon-attach/test/tsconfig.json

@@ -11,10 +11,11 @@
     "removeComments": true,
     "paths": {
       "common/*": [
-        "../../../src/common/*"
+        "../../../src/primitives/*",
+        "../../../src/runtime/*",
       ],
-      "browser/*": [
+      "target-browser/*": [
-        "../../../src/browser/*"
+        "../../../src/target-browser/*"
       ],
       "*": [
         "./*"
@@ -31,10 +32,10 @@
   ],
   "references": [
     {
-      "path": "../../../src/common"
+      "path": "../../../src"
     },
     {
-      "path": "../../../src/browser"
+      "path": "../../../src/target-browser"
     },
     {
       "path": "../../../test/playwright"

addons/addon-clipboard/src/tsconfig.json

@@ -15,8 +15,8 @@
       "../../../node_modules/@types/mocha"
     ],
     "paths": {
-      "browser/*": [
+      "target-browser/*": [
-        "../../../src/browser/*"
+        "../../../src/target-browser/*"
       ],
       "@xterm/addon-clipboard": [
         "../typings/addon-clipboard.d.ts"
@@ -29,7 +29,7 @@
   ],
   "references": [
     {
-      "path": "../../../src/browser"
+      "path": "../../../src/target-browser"
     }
   ]
 }

addons/addon-clipboard/test/tsconfig.json

@@ -11,10 +11,11 @@
     "removeComments": true,
     "paths": {
       "common/*": [
-        "../../../src/common/*"
+        "../../../src/primitives/*",
+        "../../../src/runtime/*",
       ],
-      "browser/*": [
+      "target-browser/*": [
-        "../../../src/browser/*"
+        "../../../src/target-browser/*"
       ],
       "*": [
         "./*"
@@ -31,10 +32,10 @@
   ],
   "references": [
     {
-      "path": "../../../src/common"
+      "path": "../../../src"
     },
     {
-      "path": "../../../src/browser"
+      "path": "../../../src/target-browser"
     },
     {
       "path": "../../../test/playwright"

addons/addon-fit/src/FitAddon.ts

@@ -5,7 +5,7 @@
 
 import type { Terminal, ITerminalAddon, IRenderDimensions } from '@xterm/xterm';
 import type { FitAddon as IFitApi } from '@xterm/addon-fit';
-import { ViewportConstants } from 'browser/shared/Constants';
+import { ViewportConstants } from 'target-browser/shared/Constants';
 
 interface ITerminalDimensions {
   /**

addons/addon-fit/src/tsconfig.json

@@ -15,8 +15,8 @@
       "../../../node_modules/@types/mocha"
     ],
     "paths": {
-      "browser/*": [
+      "target-browser/*": [
-        "../../../src/browser/*"
+        "../../../src/target-browser/*"
       ],
       "@xterm/addon-fit": [
         "../typings/addon-fit.d.ts"
@@ -29,7 +29,7 @@
   ],
   "references": [
     {
-      "path": "../../../src/browser"
+      "path": "../../../src/target-browser"
     }
   ]
 }

addons/addon-fit/test/tsconfig.json

@@ -11,10 +11,11 @@
     "removeComments": true,
     "paths": {
       "common/*": [
-        "../../../src/common/*"
+        "../../../src/primitives/*",
+        "../../../src/runtime/*",
       ],
-      "browser/*": [
+      "target-browser/*": [
-        "../../../src/browser/*"
+        "../../../src/target-browser/*"
       ],
       "*": [
         "./*"
@@ -31,10 +32,10 @@
   ],
   "references": [
     {
-      "path": "../../../src/common"
+      "path": "../../../src"
     },
     {
-      "path": "../../../src/browser"
+      "path": "../../../src/target-browser"
     },
     {
       "path": "../../../test/playwright"

addons/addon-image/src/Types.ts

@@ -10,9 +10,9 @@ import { Attributes, BgFlags, Content, ExtFlags, UnderlineStyle } from 'common/b
 import type { AttributeData } from 'common/buffer/AttributeData';
 import type { IParams, IDcsHandler, IOscHandler, IApcHandler, IEscapeSequenceParser } from 'common/parser/Types';
 import type { IBufferLine, IExtendedAttrs, IInputHandler } from 'common/Types';
-import type { ITerminal, ReadonlyColorSet } from 'browser/Types';
+import type { ITerminal, ReadonlyColorSet } from 'target-browser/Types';
-import type { IRenderDimensions } from 'browser/renderer/shared/Types';
+import type { IRenderDimensions } from 'target-browser/renderer/shared/Types';
-import type { ICoreBrowserService, IRenderService, IThemeService } from 'browser/services/Services';
+import type { ICoreBrowserService, IRenderService, IThemeService } from 'target-browser/services/Services';
 
 export const enum Cell {
   CONTENT = 0,  // codepoint and wcwidth information (enum Content)

addons/addon-image/src/tsconfig.json

@@ -12,8 +12,11 @@
       "../../../node_modules/@types/mocha"
     ],
     "paths": {
-      "browser/*": [ "../../../src/browser/*" ],
+      "target-browser/*": [ "../../../src/target-browser/*" ],
-      "common/*": [ "../../../src/common/*" ],
+      "common/*": [
+        "../../../src/primitives/*",
+        "../../../src/runtime/*",
+      ],
       "@xterm/addon-image": [ "../typings/addon-image.d.ts" ],
       "*": [ "./*" ]
     }
@@ -23,7 +26,7 @@
     "../../../typings/xterm.d.ts"
   ],
   "references": [
-    { "path": "../../../src/browser" },
+    { "path": "../../../src/target-browser" },
-    { "path": "../../../src/common" }
+    { "path": "../../../src" }
   ]
 }

addons/addon-image/test/tsconfig.json

@@ -11,10 +11,11 @@
     "removeComments": true,
     "paths": {
       "common/*": [
-        "../../../src/common/*"
+        "../../../src/primitives/*",
+        "../../../src/runtime/*",
       ],
-      "browser/*": [
+      "target-browser/*": [
-        "../../../src/browser/*"
+        "../../../src/target-browser/*"
       ],
       "*": [
         "./*"
@@ -31,10 +32,10 @@
   ],
   "references": [
     {
-      "path": "../../../src/common"
+      "path": "../../../src"
     },
     {
-      "path": "../../../src/browser"
+      "path": "../../../src/target-browser"
     },
     {
       "path": "../../../test/playwright"

addons/addon-image/webpack.config.js

@@ -25,8 +25,11 @@ const addon = {
     modules: ['./node_modules'],
     extensions: [ '.js' ],
     alias: {
-      common: path.resolve('../../out/common'),
+      common: [
-      browser: path.resolve('../../out/browser'),
+      path.resolve('../../out/runtime'),
+      path.resolve('../../out/primitives'),
+    ],
+      browser: path.resolve('../../out/target-browser'),
       vs: path.resolve('../../out/vs')
     }
   },

addons/addon-progress/src/tsconfig.json

@@ -16,10 +16,11 @@
     ],
     "paths": {
       "common/*": [
-        "../../../src/common/*"
+        "../../../src/primitives/*",
+        "../../../src/runtime/*",
       ],
-      "browser/*": [
+      "target-browser/*": [
-        "../../../src/browser/*"
+        "../../../src/target-browser/*"
       ],
       "@xterm/addon-progress": [
         "../typings/addon-progress.d.ts"
@@ -32,10 +33,10 @@
   ],
   "references": [
     {
-      "path": "../../../src/browser"
+      "path": "../../../src/target-browser"
     },
     {
-      "path": "../../../src/common"
+      "path": "../../../src"
     }
   ]
 }

addons/addon-progress/test/tsconfig.json

@@ -11,10 +11,11 @@
     "removeComments": true,
     "paths": {
       "common/*": [
-        "../../../src/common/*"
+        "../../../src/primitives/*",
+        "../../../src/runtime/*",
       ],
-      "browser/*": [
+      "target-browser/*": [
-        "../../../src/browser/*"
+        "../../../src/target-browser/*"
       ],
       "*": [
         "./*"
@@ -31,10 +32,10 @@
   ],
   "references": [
     {
-      "path": "../../../src/common"
+      "path": "../../../src"
     },
     {
-      "path": "../../../src/browser"
+      "path": "../../../src/target-browser"
     },
     {
       "path": "../../../test/playwright"

addons/addon-progress/webpack.config.js

@@ -25,8 +25,11 @@ module.exports = {
     modules: ['./node_modules'],
     extensions: [ '.js' ],
     alias: {
-      common: path.resolve('../../out/common'),
+      common: [
-      browser: path.resolve('../../out/browser'),
+      path.resolve('../../out/runtime'),
+      path.resolve('../../out/primitives'),
+    ],
+      browser: path.resolve('../../out/target-browser'),
       vs: path.resolve('../../out/vs')
     }
   },

addons/addon-search/src/SearchEngine.test.ts

@@ -5,7 +5,7 @@
 import { assert } from 'chai';
 import { SearchEngine } from './SearchEngine';
 import { SearchLineCache } from './SearchLineCache';
-import { Terminal } from 'browser/public/Terminal';
+import { Terminal } from 'target-browser/public/Terminal';
 import type { ISearchOptions } from '@xterm/addon-search';
 import { DisposableStore } from 'common/Lifecycle';
 

addons/addon-search/src/SearchLineCache.test.ts

@@ -4,7 +4,7 @@
  */
 import { assert } from 'chai';
 import { SearchLineCache, LineCacheEntry } from './SearchLineCache';
-import { Terminal } from 'browser/public/Terminal';
+import { Terminal } from 'target-browser/public/Terminal';
 import { timeout } from 'common/Async';
 
 function writeP(terminal: Terminal, data: string): Promise<void> {

addons/addon-search/src/tsconfig.json

@@ -16,10 +16,11 @@
     ],
     "paths": {
       "common/*": [
-        "../../../src/common/*"
+        "../../../src/primitives/*",
+        "../../../src/runtime/*",
       ],
-      "browser/*": [
+      "target-browser/*": [
-        "../../../src/browser/*"
+        "../../../src/target-browser/*"
       ],
       "@xterm/addon-search" : [
         "../typings/addon-search.d.ts"
@@ -32,10 +33,10 @@
   ],
   "references": [
     {
-      "path": "../../../src/common"
+      "path": "../../../src"
     },
     {
-      "path": "../../../src/browser"
+      "path": "../../../src/target-browser"
     }
   ]
 }

addons/addon-search/test/tsconfig.json

@@ -11,10 +11,11 @@
     "removeComments": true,
     "paths": {
       "common/*": [
-        "../../../src/common/*"
+        "../../../src/primitives/*",
+        "../../../src/runtime/*",
       ],
-      "browser/*": [
+      "target-browser/*": [
-        "../../../src/browser/*"
+        "../../../src/target-browser/*"
       ],
       "*": [
         "./*"
@@ -31,10 +32,10 @@
   ],
   "references": [
     {
-      "path": "../../../src/common"
+      "path": "../../../src"
     },
     {
-      "path": "../../../src/browser"
+      "path": "../../../src/target-browser"
     },
     {
       "path": "../../../test/playwright"

addons/addon-search/webpack.config.js

@@ -25,7 +25,10 @@ module.exports = {
     modules: ['./node_modules'],
     extensions: [ '.js' ],
     alias: {
-      common: path.resolve('../../out/common'),
+      common: [
+      path.resolve('../../out/runtime'),
+      path.resolve('../../out/primitives'),
+    ],
       vs: path.resolve('../../out/vs')
     }
   },

addons/addon-serialize/benchmark/SerializeAddon.benchmark.ts

@@ -7,7 +7,7 @@ import { perfContext, before, ThroughputRuntimeCase } from 'xterm-benchmark';
 
 import { spawn } from 'node-pty';
 import { Utf8ToUtf32, stringFromCodePoint } from 'common/input/TextDecoder';
-import { Terminal } from 'browser/public/Terminal';
+import { Terminal } from 'target-browser/public/Terminal';
 import { SerializeAddon } from 'SerializeAddon';
 
 class TestTerminal extends Terminal {

addons/addon-serialize/benchmark/tsconfig.json

@@ -12,8 +12,11 @@
     "target": "es2021",
     "module": "nodenext",
     "paths": {
-      "common/*": ["../../../src/common/*"],
+      "common/*": [
-      "browser/*": ["../../../src/browser/*"],
+        "../../../src/primitives/*",
+        "../../../src/runtime/*",
+      ],
+      "target-browser/*": ["../../../src/target-browser/*"],
       "SerializeAddon": ["../src/SerializeAddon"],
       "@xterm/addon-serialize": [
         "../typings/addon-serialize.d.ts"
@@ -23,7 +26,7 @@
   "include": ["../**/*", "../../../typings/xterm.d.ts"],
   "exclude": ["../../../**/*test.ts", "../../**/*api.ts"],
   "references": [
-    { "path": "../../../src/common" },
+    { "path": "../../../src" },
-    { "path": "../../../src/browser" }
+    { "path": "../../../src/target-browser" }
   ]
 }

addons/addon-serialize/src/SerializeAddon.test.ts

@@ -6,10 +6,10 @@
 import jsdom = require('jsdom');
 import { assert } from 'chai';
 import { SerializeAddon } from './SerializeAddon';
-import { Terminal } from 'browser/public/Terminal';
+import { Terminal } from 'target-browser/public/Terminal';
-import { SelectionModel } from 'browser/selection/SelectionModel';
+import { SelectionModel } from 'target-browser/selection/SelectionModel';
 import { IBufferService } from 'common/services/Services';
-import { ThemeService } from 'browser/services/ThemeService';
+import { ThemeService } from 'target-browser/services/ThemeService';
 
 function sgr(...seq: string[]): string {
   return `\x1b[${seq.join(';')}m`;

addons/addon-serialize/src/SerializeAddon.ts

@@ -8,7 +8,7 @@
 import type { IBuffer, IBufferCell, IBufferRange, ITerminalAddon, Terminal } from '@xterm/xterm';
 import type { IHTMLSerializeOptions, SerializeAddon as ISerializeApi, ISerializeOptions, ISerializeRange } from '@xterm/addon-serialize';
 import { IAttributeData, IColor } from 'common/Types';
-import { DEFAULT_ANSI_COLORS } from 'browser/Types';
+import { DEFAULT_ANSI_COLORS } from 'target-browser/Types';
 import { UnderlineStyle } from 'common/buffer/Constants';
 
 function constrain(value: number, low: number, high: number): number {

addons/addon-serialize/src/tsconfig.json

@@ -12,10 +12,11 @@
     "removeComments": true,
     "paths": {
       "common/*": [
-        "../../../src/common/*"
+        "../../../src/primitives/*",
+        "../../../src/runtime/*",
       ],
-      "browser/*": [
+      "target-browser/*": [
-        "../../../src/browser/*"
+        "../../../src/target-browser/*"
       ],
       "@xterm/addon-serialize": [
         "../typings/addon-serialize.d.ts"
@@ -33,10 +34,10 @@
   ],
   "references": [
     {
-      "path": "../../../src/common"
+      "path": "../../../src"
     },
     {
-      "path": "../../../src/browser"
+      "path": "../../../src/target-browser"
     }
   ]
 }

addons/addon-serialize/test/tsconfig.json

@@ -11,10 +11,11 @@
     "removeComments": true,
     "paths": {
       "common/*": [
-        "../../../src/common/*"
+        "../../../src/primitives/*",
+        "../../../src/runtime/*",
       ],
-      "browser/*": [
+      "target-browser/*": [
-        "../../../src/browser/*"
+        "../../../src/target-browser/*"
       ]
     },
     "strict": true,
@@ -28,10 +29,10 @@
   ],
   "references": [
     {
-      "path": "../../../src/common"
+      "path": "../../../src"
     },
     {
-      "path": "../../../src/browser"
+      "path": "../../../src/target-browser"
     },
     {
       "path": "../../../test/playwright"

addons/addon-serialize/webpack.config.js

@@ -25,8 +25,11 @@ module.exports = {
     modules: ['./node_modules'],
     extensions: [ '.js' ],
     alias: {
-      common: path.resolve('../../out/common'),
+      common: [
-      browser: path.resolve('../../out/browser')
+      path.resolve('../../out/runtime'),
+      path.resolve('../../out/primitives'),
+    ],
+      browser: path.resolve('../../out/target-browser')
     }
   },
   output: {

addons/addon-unicode-graphemes/benchmark/UnicodeGraphemeAddon.benchmark.ts

@@ -7,7 +7,7 @@ import { perfContext, before, ThroughputRuntimeCase } from 'xterm-benchmark';
 
 import { spawn } from 'node-pty';
 import { Utf8ToUtf32, stringFromCodePoint } from 'common/input/TextDecoder';
-import { CoreBrowserTerminal } from 'browser/CoreBrowserTerminal';
+import { CoreBrowserTerminal } from 'target-browser/CoreBrowserTerminal';
 import { UnicodeGraphemeProvider } from 'UnicodeGraphemeProvider';
 
 

addons/addon-unicode-graphemes/benchmark/tsconfig.json

@@ -9,8 +9,11 @@
     "target": "es2015",
     "module": "nodenext",
     "paths": {
-      "common/*": ["../../../src/common/*"],
+      "common/*": [
-      "browser/*": ["../../../src/browser/*"],
+        "../../../src/primitives/*",
+        "../../../src/runtime/*",
+      ],
+      "target-browser/*": ["../../../src/target-browser/*"],
       "UnicodeGraphemeProvider": ["../src/UnicodeGraphemeProvider"],
       "@xterm/addon-unicode-graphemes": [
         "../typings/addon-unicode-graphemes.d.ts"
@@ -20,7 +23,7 @@
   "include": ["../**/*", "../../../typings/xterm.d.ts"],
   "exclude": ["../../../**/*test.ts", "../../**/*api.ts"],
   "references": [
-    { "path": "../../../src/common" },
+    { "path": "../../../src" },
-    { "path": "../../../src/browser" }
+    { "path": "../../../src/target-browser" }
   ]
 }

addons/addon-unicode-graphemes/src/UnicodeGraphemeProvider.ts

@@ -4,8 +4,8 @@
  */
 
 import { IUnicodeVersionProvider } from '@xterm/xterm';
-import { UnicodeCharProperties, UnicodeCharWidth } from 'common/services/Services';
+import { createPropertyValue, extractCharKind, extractWidth } from 'common/input/UnicodeProperties';
-import { UnicodeService } from 'common/services/UnicodeService';
+import { UnicodeCharProperties, UnicodeCharWidth } from 'common/input/UnicodeTypes';
 import * as UC from './third-party/UnicodeProperties';
 
 export class UnicodeGraphemeProvider implements IUnicodeVersionProvider {
@@ -19,7 +19,7 @@ export class UnicodeGraphemeProvider implements IUnicodeVersionProvider {
   }
 
   private static readonly _plainNarrowProperties: UnicodeCharProperties
-    = UnicodeService.createPropertyValue(UC.GRAPHEME_BREAK_Other, 1, false);
+    = createPropertyValue(UC.GRAPHEME_BREAK_Other, 1, false);
 
   public charProperties(codepoint: number, preceding: UnicodeCharProperties): UnicodeCharProperties {
     // Optimize the simple ASCII case, under the condition that
@@ -39,9 +39,9 @@ export class UnicodeGraphemeProvider implements IUnicodeVersionProvider {
       w = 1;
     }
     if (preceding !== 0) {
-      const oldWidth = UnicodeService.extractWidth(preceding);
+      const oldWidth = extractWidth(preceding);
       if (this.handleGraphemes) {
-        charInfo = UC.shouldJoin(UnicodeService.extractCharKind(preceding), charInfo);
+        charInfo = UC.shouldJoin(extractCharKind(preceding), charInfo);
       } else {
         charInfo = w === 0 ? 1 : 0;
       }
@@ -54,7 +54,7 @@ export class UnicodeGraphemeProvider implements IUnicodeVersionProvider {
         }
       }
     }
-    return UnicodeService.createPropertyValue(charInfo, w, shouldJoin);
+    return createPropertyValue(charInfo, w, shouldJoin);
   }
 
   public wcwidth(codepoint: number): UnicodeCharWidth {

addons/addon-unicode-graphemes/src/tsconfig.json

@@ -13,7 +13,8 @@
     "strict": true,
     "paths": {
       "common/*": [
-        "../../../src/common/*"
+        "../../../src/primitives/*",
+        "../../../src/runtime/*",
       ],
       "@xterm/addon-unicode-graphemes": [
         "../typings/addon-unicode-graphemes.d.ts"
@@ -29,7 +30,7 @@
   ],
   "references": [
     {
-      "path": "../../../src/common"
+      "path": "../../../src"
     }
   ]
 }

addons/addon-unicode-graphemes/test/tsconfig.json

@@ -11,10 +11,11 @@
     "removeComments": true,
     "paths": {
       "common/*": [
-        "../../../src/common/*"
+        "../../../src/primitives/*",
+        "../../../src/runtime/*",
       ],
-      "browser/*": [
+      "target-browser/*": [
-        "../../../src/browser/*"
+        "../../../src/target-browser/*"
       ]
     },
     "strict": true,
@@ -28,10 +29,10 @@
   ],
   "references": [
     {
-      "path": "../../../src/common"
+      "path": "../../../src"
     },
     {
-      "path": "../../../src/browser"
+      "path": "../../../src/target-browser"
     },
     {
       "path": "../../../test/playwright"

addons/addon-unicode-graphemes/webpack.config.js

@@ -25,7 +25,10 @@ module.exports = {
     modules: ['./node_modules'],
     extensions: [ '.js' ],
     alias: {
-      common: path.resolve('../../out/common'),
+      common: [
+      path.resolve('../../out/runtime'),
+      path.resolve('../../out/primitives'),
+    ],
       vs: path.resolve('../../out/vs')
     }
   },

addons/addon-unicode11/src/UnicodeV11.ts

@@ -4,8 +4,8 @@
  */
 
 import { IUnicodeVersionProvider } from '@xterm/xterm';
-import { UnicodeCharProperties, UnicodeCharWidth } from 'common/services/Services';
+import { createPropertyValue, extractWidth } from 'common/input/UnicodeProperties';
-import { UnicodeService } from 'common/services/UnicodeService';
+import { UnicodeCharProperties, UnicodeCharWidth } from 'common/input/UnicodeTypes';
 
 const BMP_COMBINING = [
   [0x0300, 0x036F], [0x0483, 0x0489], [0x0591, 0x05BD],
@@ -223,13 +223,13 @@ export class UnicodeV11 implements IUnicodeVersionProvider {
     let width = this.wcwidth(codepoint);
     let shouldJoin = width === 0 && preceding !== 0;
     if (shouldJoin) {
-      const oldWidth = UnicodeService.extractWidth(preceding);
+      const oldWidth = extractWidth(preceding);
       if (oldWidth === 0) {
         shouldJoin = false;
       } else if (oldWidth > width) {
         width = oldWidth;
       }
     }
-    return UnicodeService.createPropertyValue(0, width, shouldJoin);
+    return createPropertyValue(0, width, shouldJoin);
   }
 }

addons/addon-unicode11/src/tsconfig.json

@@ -13,7 +13,8 @@
     "strict": true,
     "paths": {
       "common/*": [
-        "../../../src/common/*"
+        "../../../src/primitives/*",
+        "../../../src/runtime/*",
       ],
       "@xterm/addon-unicode11": [
         "../typings/addon-unicode11.d.ts"
@@ -32,7 +33,7 @@
   ],
   "references": [
     {
-      "path": "../../../src/common"
+      "path": "../../../src"
     }
   ]
 }

addons/addon-unicode11/test/tsconfig.json

@@ -11,10 +11,11 @@
     "removeComments": true,
     "paths": {
       "common/*": [
-        "../../../src/common/*"
+        "../../../src/primitives/*",
+        "../../../src/runtime/*",
       ],
-      "browser/*": [
+      "target-browser/*": [
-        "../../../src/browser/*"
+        "../../../src/target-browser/*"
       ],
       "*": [
         "./*"
@@ -31,10 +32,10 @@
   ],
   "references": [
     {
-      "path": "../../../src/common"
+      "path": "../../../src"
     },
     {
-      "path": "../../../src/browser"
+      "path": "../../../src/target-browser"
     },
     {
       "path": "../../../test/playwright"

addons/addon-unicode11/webpack.config.js

@@ -25,7 +25,10 @@ module.exports = {
     modules: ['./node_modules'],
     extensions: [ '.js' ],
     alias: {
-      common: path.resolve('../../out/common'),
+      common: [
+      path.resolve('../../out/runtime'),
+      path.resolve('../../out/primitives'),
+    ],
       vs: path.resolve('../../out/vs')
     }
   },

addons/addon-web-fonts/test/tsconfig.json

@@ -11,10 +11,11 @@
     "removeComments": true,
     "paths": {
       "common/*": [
-        "../../../src/common/*"
+        "../../../src/primitives/*",
+        "../../../src/runtime/*",
       ],
-      "browser/*": [
+      "target-browser/*": [
-        "../../../src/browser/*"
+        "../../../src/target-browser/*"
       ],
       "*": [
         "./*"
@@ -31,10 +32,10 @@
   ],
   "references": [
     {
-      "path": "../../../src/common"
+      "path": "../../../src"
     },
     {
-      "path": "../../../src/browser"
+      "path": "../../../src/target-browser"
     },
     {
       "path": "../../../test/playwright"

addons/addon-web-links/test/tsconfig.json

@@ -11,10 +11,11 @@
     "removeComments": true,
     "paths": {
       "common/*": [
-        "../../../src/common/*"
+        "../../../src/primitives/*",
+        "../../../src/runtime/*",
       ],
-      "browser/*": [
+      "target-browser/*": [
-        "../../../src/browser/*"
+        "../../../src/target-browser/*"
       ],
       "*": [
         "./*"
@@ -31,10 +32,10 @@
   ],
   "references": [
     {
-      "path": "../../../src/common"
+      "path": "../../../src"
     },
     {
-      "path": "../../../src/browser"
+      "path": "../../../src/target-browser"
     },
     {
       "path": "../../../test/playwright"

addons/addon-webgl/src/CellColorResolver.ts

@@ -1,12 +1,12 @@
-import { ISelectionRenderModel } from 'browser/renderer/shared/Types';
+import { ISelectionRenderModel } from 'target-browser/renderer/shared/Types';
-import { ICoreBrowserService, IThemeService } from 'browser/services/Services';
+import { ICoreBrowserService, IThemeService } from 'target-browser/services/Services';
-import { ReadonlyColorSet } from 'browser/Types';
+import { ReadonlyColorSet } from 'target-browser/Types';
 import { Attributes, BgFlags, ExtFlags, FgFlags, NULL_CELL_CODE, UnderlineStyle } from 'common/buffer/Constants';
 import { IDecorationService, IOptionsService } from 'common/services/Services';
 import { ICellData } from 'common/Types';
 import { Terminal } from '@xterm/xterm';
 import { rgba } from 'common/Color';
-import { treatGlyphAsBackgroundColor } from 'browser/renderer/shared/RendererUtils';
+import { treatGlyphAsBackgroundColor } from 'target-browser/renderer/shared/RendererUtils';
 import { blockPatternCodepoints } from './customGlyphs/CustomGlyphDefinitions';
 
 // Work variables to avoid garbage collection

addons/addon-webgl/src/CharAtlasCache.ts

@@ -5,7 +5,7 @@
 
 import { TextureAtlas } from './TextureAtlas';
 import { ITerminalOptions, Terminal } from '@xterm/xterm';
-import { ITerminal, ReadonlyColorSet } from 'browser/Types';
+import { ITerminal, ReadonlyColorSet } from 'target-browser/Types';
 import { ICharAtlasConfig, ITextureAtlas } from './Types';
 import { generateConfig, configEquals } from './CharAtlasUtils';
 import type { ILogService } from 'common/services/Services';

addons/addon-webgl/src/CharAtlasUtils.ts

@@ -6,7 +6,7 @@
 import { ICharAtlasConfig } from './Types';
 import { Attributes } from 'common/buffer/Constants';
 import { ITerminalOptions } from '@xterm/xterm';
-import { IColorSet, ReadonlyColorSet } from 'browser/Types';
+import { IColorSet, ReadonlyColorSet } from 'target-browser/Types';
 import { NULL_COLOR } from 'common/Color';
 
 export function generateConfig(deviceCellWidth: number, deviceCellHeight: number, deviceCharWidth: number, deviceCharHeight: number, options: Required<ITerminalOptions>, colors: ReadonlyColorSet, devicePixelRatio: number, deviceMaxTextureSize: number, customGlyphs: boolean = true): ICharAtlasConfig {

addons/addon-webgl/src/CursorBlinkStateManager.ts

@@ -3,8 +3,8 @@
  * @license MIT
  */
 
-import { RendererConstants } from 'browser/renderer/shared/Constants';
+import { RendererConstants } from 'target-browser/renderer/shared/Constants';
-import { ICoreBrowserService } from 'browser/services/Services';
+import { ICoreBrowserService } from 'target-browser/services/Services';
 
 const enum Constants {
   /**

addons/addon-webgl/src/GlyphRenderer.ts

@@ -3,14 +3,14 @@
  * @license MIT
  */
 import { TextureAtlas } from './TextureAtlas';
-import { IRenderDimensions } from 'browser/renderer/shared/Types';
+import { IRenderDimensions } from 'target-browser/renderer/shared/Types';
 import { NULL_CELL_CODE } from 'common/buffer/Constants';
 import { Disposable, toDisposable } from 'common/Lifecycle';
 import { Terminal } from '@xterm/xterm';
 import { IRenderModel, IWebGL2RenderingContext, IWebGLVertexArrayObject, type IRasterizedGlyph, type ITextureAtlas } from './Types';
 import { createProgram, GLTexture, PROJECTION_MATRIX } from './WebglUtils';
 import type { ILogService, IOptionsService } from 'common/services/Services';
-import { allowRescaling, throwIfFalsy } from 'browser/renderer/shared/RendererUtils';
+import { allowRescaling, throwIfFalsy } from 'target-browser/renderer/shared/RendererUtils';
 
 interface IVertices {
   attributes: Float32Array;

addons/addon-webgl/src/RectangleRenderer.ts

@@ -3,9 +3,9 @@
  * @license MIT
  */
 
-import { IRenderDimensions } from 'browser/renderer/shared/Types';
+import { IRenderDimensions } from 'target-browser/renderer/shared/Types';
-import { IThemeService } from 'browser/services/Services';
+import { IThemeService } from 'target-browser/services/Services';
-import { ReadonlyColorSet } from 'browser/Types';
+import { ReadonlyColorSet } from 'target-browser/Types';
 import { Attributes, FgFlags } from 'common/buffer/Constants';
 import { Disposable, toDisposable } from 'common/Lifecycle';
 import { IColor } from 'common/Types';
@@ -13,7 +13,7 @@ import { Terminal } from '@xterm/xterm';
 import { RenderModelConstants } from './RenderModel';
 import { IRenderModel, IWebGL2RenderingContext, IWebGLVertexArrayObject } from './Types';
 import { createProgram, expandFloat32Array, PROJECTION_MATRIX } from './WebglUtils';
-import { throwIfFalsy } from 'browser/renderer/shared/RendererUtils';
+import { throwIfFalsy } from 'target-browser/renderer/shared/RendererUtils';
 import type { ILogService } from 'common/services/Services';
 
 const enum VertexAttribLocations {

addons/addon-webgl/src/RenderModel.ts

@@ -4,8 +4,8 @@
  */
 
 import { ICursorRenderModel, IRenderModel } from './Types';
-import { ISelectionRenderModel } from 'browser/renderer/shared/Types';
+import { ISelectionRenderModel } from 'target-browser/renderer/shared/Types';
-import { createSelectionRenderModel } from 'browser/renderer/shared/SelectionRenderModel';
+import { createSelectionRenderModel } from 'target-browser/renderer/shared/SelectionRenderModel';
 
 export const enum RenderModelConstants {
   INDICIES_PER_CELL = 4,

addons/addon-webgl/src/TextureAtlas.ts

@@ -3,10 +3,10 @@
  * @license MIT
  */
 
-import { IColorContrastCache } from 'browser/Types';
+import { IColorContrastCache } from 'target-browser/Types';
 import { DIM_OPACITY, TEXT_BASELINE } from './Constants';
 import { tryDrawCustomGlyph } from './customGlyphs/CustomGlyphRasterizer';
-import { computeNextVariantOffset, treatGlyphAsBackgroundColor, isPowerlineGlyph, isRestrictedPowerlineGlyph, throwIfFalsy } from 'browser/renderer/shared/RendererUtils';
+import { computeNextVariantOffset, treatGlyphAsBackgroundColor, isPowerlineGlyph, isRestrictedPowerlineGlyph, throwIfFalsy } from 'target-browser/renderer/shared/RendererUtils';
 import { IBoundingBox, ICharAtlasConfig, IRasterizedGlyph, ITextureAtlas } from './Types';
 import { NULL_COLOR, channels, color, rgba } from 'common/Color';
 import { FourKeyMap } from 'common/MultiKeyMap';

addons/addon-webgl/src/Types.ts

@@ -4,8 +4,8 @@
  */
 
 import { FontWeight } from '@xterm/xterm';
-import { IColorSet } from 'browser/Types';
+import { IColorSet } from 'target-browser/Types';
-import { ISelectionRenderModel } from 'browser/renderer/shared/Types';
+import { ISelectionRenderModel } from 'target-browser/renderer/shared/Types';
 import { CursorInactiveStyle, CursorStyle, type IDisposable } from 'common/Types';
 import type { IEvent } from 'common/Event';
 

addons/addon-webgl/src/WebglAddon.ts

@@ -5,8 +5,8 @@
 
 import type { ITerminalAddon, Terminal } from '@xterm/xterm';
 import type { IWebglAddonOptions, WebglAddon as IWebglApi } from '@xterm/addon-webgl';
-import { ICharacterJoinerService, ICharSizeService, ICoreBrowserService, IRenderService, IThemeService } from 'browser/services/Services';
+import { ICharacterJoinerService, ICharSizeService, ICoreBrowserService, IRenderService, IThemeService } from 'target-browser/services/Services';
-import { ITerminal } from 'browser/Types';
+import { ITerminal } from 'target-browser/Types';
 import { Disposable, toDisposable } from 'common/Lifecycle';
 import { getSafariVersion, isSafari } from 'common/Platform';
 import { ICoreService, IDecorationService, ILogService, IOptionsService } from 'common/services/Services';

addons/addon-webgl/src/WebglRenderer.ts

@@ -3,18 +3,18 @@
  * @license MIT
  */
 
-import { ITerminal } from 'browser/Types';
+import { ITerminal } from 'target-browser/Types';
 import { CellColorResolver } from './CellColorResolver';
 import { acquireTextureAtlas, removeTerminalFromCache } from './CharAtlasCache';
 import { CursorBlinkStateManager } from './CursorBlinkStateManager';
 import { observeDevicePixelDimensions } from './DevicePixelObserver';
-import { IRenderDimensions, IRenderer, IRequestRedrawEvent } from 'browser/renderer/shared/Types';
+import { IRenderDimensions, IRenderer, IRequestRedrawEvent } from 'target-browser/renderer/shared/Types';
-import { ICharSizeService, ICharacterJoinerService, ICoreBrowserService, IThemeService } from 'browser/services/Services';
+import { ICharSizeService, ICharacterJoinerService, ICoreBrowserService, IThemeService } from 'target-browser/services/Services';
 import { CharData, IBufferLine, ICellData } from 'common/Types';
 import { AttributeData } from 'common/buffer/AttributeData';
 import { CellData } from 'common/buffer/CellData';
 import { Attributes, Content, FgFlags, NULL_CELL_CHAR, NULL_CELL_CODE } from 'common/buffer/Constants';
-import { TextBlinkStateManager } from 'browser/renderer/shared/TextBlinkStateManager';
+import { TextBlinkStateManager } from 'target-browser/renderer/shared/TextBlinkStateManager';
 import { ICoreService, IDecorationService, ILogService, IOptionsService } from 'common/services/Services';
 import { Terminal } from '@xterm/xterm';
 import { GlyphRenderer } from './GlyphRenderer';
@@ -24,9 +24,9 @@ import { IWebGL2RenderingContext, type ITextureAtlas } from './Types';
 import { LinkRenderLayer } from './renderLayer/LinkRenderLayer';
 import { IRenderLayer } from './renderLayer/Types';
 import { Emitter, EventUtils } from 'common/Event';
-import { addDisposableListener } from 'browser/Dom';
+import { addDisposableListener } from 'target-browser/Dom';
 import { combinedDisposable, Disposable, MutableDisposable, toDisposable } from 'common/Lifecycle';
-import { createRenderDimensions } from 'browser/renderer/shared/RendererUtils';
+import { createRenderDimensions } from 'target-browser/renderer/shared/RendererUtils';
 
 const enum Constants {
   MERGE_RETRY_LIMIT = 32

addons/addon-webgl/src/WebglUtils.ts

@@ -3,7 +3,7 @@
  * @license MIT
  */
 
-import { throwIfFalsy } from 'browser/renderer/shared/RendererUtils';
+import { throwIfFalsy } from 'target-browser/renderer/shared/RendererUtils';
 import type { ILogService } from 'common/services/Services';
 
 /**

addons/addon-webgl/src/customGlyphs/CustomGlyphRasterizer.ts

@@ -3,7 +3,7 @@
  * @license MIT
  */
 
-import { throwIfFalsy } from 'browser/renderer/shared/RendererUtils';
+import { throwIfFalsy } from 'target-browser/renderer/shared/RendererUtils';
 import type { ILogService } from 'common/services/Services';
 import { customGlyphDefinitions } from './CustomGlyphDefinitions';
 import { CustomGlyphDefinitionType, CustomGlyphScaleType, CustomGlyphVectorType, type CustomGlyphDefinitionPart, type CustomGlyphPathDrawFunctionDefinition, type CustomGlyphPatternDefinition, type ICustomGlyphSolidOctantBlockVector, type ICustomGlyphVectorShape } from './Types';

addons/addon-webgl/src/renderLayer/BaseRenderLayer.ts

@@ -3,16 +3,16 @@
  * @license MIT
  */
 
-import { ReadonlyColorSet } from 'browser/Types';
+import { ReadonlyColorSet } from 'target-browser/Types';
 import { acquireTextureAtlas } from '../CharAtlasCache';
-import { IRenderDimensions } from 'browser/renderer/shared/Types';
+import { IRenderDimensions } from 'target-browser/renderer/shared/Types';
-import { ICoreBrowserService, IThemeService } from 'browser/services/Services';
+import { ICoreBrowserService, IThemeService } from 'target-browser/services/Services';
 import { Disposable, toDisposable } from 'common/Lifecycle';
 import { CellData } from 'common/buffer/CellData';
 import { IOptionsService } from 'common/services/Services';
 import { Terminal } from '@xterm/xterm';
 import { IRenderLayer } from './Types';
-import { throwIfFalsy } from 'browser/renderer/shared/RendererUtils';
+import { throwIfFalsy } from 'target-browser/renderer/shared/RendererUtils';
 import { TEXT_BASELINE } from '../Constants';
 import type { ITextureAtlas } from '../Types';
 

addons/addon-webgl/src/renderLayer/LinkRenderLayer.ts

@@ -4,10 +4,10 @@
  */
 
 import { is256Color } from '../CharAtlasUtils';
-import { INVERTED_DEFAULT_COLOR } from 'browser/renderer/shared/Constants';
+import { INVERTED_DEFAULT_COLOR } from 'target-browser/renderer/shared/Constants';
-import { IRenderDimensions } from 'browser/renderer/shared/Types';
+import { IRenderDimensions } from 'target-browser/renderer/shared/Types';
-import { ICoreBrowserService, IThemeService } from 'browser/services/Services';
+import { ICoreBrowserService, IThemeService } from 'target-browser/services/Services';
-import { ILinkifier2, ILinkifierEvent } from 'browser/Types';
+import { ILinkifier2, ILinkifierEvent } from 'target-browser/Types';
 import { IOptionsService } from 'common/services/Services';
 import { Terminal } from '@xterm/xterm';
 import { BaseRenderLayer } from './BaseRenderLayer';

addons/addon-webgl/src/renderLayer/Types.ts

@@ -4,7 +4,7 @@
  */
 
 import { IDisposable, Terminal } from '@xterm/xterm';
-import { IRenderDimensions } from 'browser/renderer/shared/Types';
+import { IRenderDimensions } from 'target-browser/renderer/shared/Types';
 
 export interface IRenderLayer extends IDisposable {
   /**

addons/addon-webgl/src/tsconfig.json

@@ -12,10 +12,11 @@
     "removeComments": true,
     "paths": {
       "common/*": [
-        "../../../src/common/*"
+        "../../../src/primitives/*",
+        "../../../src/runtime/*",
       ],
-      "browser/*": [
+      "target-browser/*": [
-        "../../../src/browser/*"
+        "../../../src/target-browser/*"
       ],
       "@xterm/addon-webgl": [
         "../typings/addon-webgl.d.ts"
@@ -36,10 +37,10 @@
   ],
   "references": [
     {
-      "path": "../../../src/common"
+      "path": "../../../src"
     },
     {
-      "path": "../../../src/browser"
+      "path": "../../../src/target-browser"
     }
   ]
 }

addons/addon-webgl/test/tsconfig.json

@@ -11,10 +11,11 @@
     "removeComments": true,
     "paths": {
       "common/*": [
-        "../../../src/common/*"
+        "../../../src/primitives/*",
+        "../../../src/runtime/*",
       ],
-      "browser/*": [
+      "target-browser/*": [
-        "../../../src/browser/*"
+        "../../../src/target-browser/*"
       ],
       "*": [
         "./*"
@@ -32,10 +33,10 @@
   ],
   "references": [
     {
-      "path": "../../../src/common"
+      "path": "../../../src"
     },
     {
-      "path": "../../../src/browser"
+      "path": "../../../src/target-browser"
     },
     {
       "path": "../../../test/playwright"

addons/addon-webgl/webpack.config.js

@@ -25,8 +25,11 @@ module.exports = {
     modules: ['./node_modules'],
     extensions: [ '.js' ],
     alias: {
-      common: path.resolve('../../out/common'),
+      common: [
-      browser: path.resolve('../../out/browser'),
+      path.resolve('../../out/runtime'),
+      path.resolve('../../out/primitives'),
+    ],
+      browser: path.resolve('../../out/target-browser'),
       vs: path.resolve('../../out/vs')
     }
   },

bin/esbuild.mjs

@@ -92,6 +92,9 @@ let outConfig = {
 }
 let skipOut = false;
 
+/** @type {esbuild.BuildOptions[] | undefined} */
+let outBuilds;
+
 /** @type {esbuild.BuildOptions} */
 let outTestConfig = {
   format: 'cjs',
@@ -171,7 +174,7 @@ if (config.addon) {
 } else if (config.isHeadless) {
   bundleConfig = {
     ...bundleConfig,
-    entryPoints: [`src/headless/public/Terminal.ts`],
+    entryPoints: [`src/target-headless/public/Terminal.ts`],
     outfile: `headless/lib-headless/xterm-headless.mjs`
   };
   outConfig = {
@@ -183,18 +186,35 @@ if (config.addon) {
 } else {
   bundleConfig = {
     ...bundleConfig,
-    entryPoints: [`src/browser/public/Terminal.ts`],
+    entryPoints: [`src/target-browser/public/Terminal.ts`],
     outfile: `lib/xterm.mjs`
   };
-  outConfig = {
+  outBuilds = [
+    {
       ...outConfig,
-    entryPoints: [
+      entryPoints: ['src/primitives/**/*.ts'],
-      'src/browser/**/*.ts',
+      outbase: 'src/primitives',
-      'src/common/**/*.ts',
+      outdir: 'out-esbuild/common',
-      'src/headless/**/*.ts'
+    },
-    ],
+    {
-    outdir: 'out-esbuild/'
+      ...outConfig,
-  };
+      entryPoints: ['src/runtime/**/*.ts'],
+      outbase: 'src/runtime',
+      outdir: 'out-esbuild/common',
+    },
+    {
+      ...outConfig,
+      entryPoints: ['src/target-browser/**/*.ts'],
+      outbase: 'src',
+      outdir: 'out-esbuild',
+    },
+    {
+      ...outConfig,
+      entryPoints: ['src/target-headless/**/*.ts'],
+      outbase: 'src',
+      outdir: 'out-esbuild',
+    },
+  ];
   outTestConfig = {
     ...outConfig,
     entryPoints: ['test/**/*.ts'],
@@ -205,7 +225,9 @@ if (config.addon) {
 if (config.isWatch) {
   context(bundleConfig).then(e => e.watch());
   if (!skipOut) {
-    context(outConfig).then(e => e.watch());
+    for (const buildConfig of outBuilds ?? [outConfig]) {
+      context(buildConfig).then(e => e.watch());
+    }
   }
   if (!skipOutTest) {
     context(outTestConfig).then(e => e.watch());
@@ -213,7 +235,9 @@ if (config.isWatch) {
 } else {
   await build(bundleConfig);
   if (!skipOut) {
-    await build(outConfig);
+    for (const buildConfig of outBuilds ?? [outConfig]) {
+      await build(buildConfig);
+    }
   }
   if (!skipOutTest) {
     await build(outTestConfig);

bin/publish.js

@@ -81,7 +81,7 @@ function checkAndPublishPackage(packageDir, repoCommit, peerDependencies, update
 
   // Update Version.ts with the new version
   if (updateVersionTs) {
-    const versionTsPath = path.join(packageDir, 'src/common/Version.ts');
+    const versionTsPath = path.join(packageDir, 'src/primitives/Version.ts');
     const versionTsContent = fs.readFileSync(versionTsPath, 'utf8');
     const updatedVersionTs = versionTsContent.replace(
       /export const XTERM_VERSION = '[^']+';/,

bin/vs_base_find_unused.js

@@ -38,4 +38,4 @@ function findUnusedSymbols(
 }
 
 // Example usage
-findUnusedSymbols("./src/browser/tsconfig.json");
+findUnusedSymbols("./src/target-browser/tsconfig.json");

src/ARCHITECTURE.md

@@ -0,0 +1,70 @@
+# xterm.js source architecture
+
+This document describes how `src/` is organized. The layout follows [issue #5963](https://github.com/xtermjs/xterm.js/issues/5963): **primitives** and **runtime** as separate TypeScript composite projects, with **target-browser** and **target-headless** as platform entry points.
+
+## Dependency graph
+
+```mermaid
+flowchart BT
+  primitives["primitives<br/>building blocks"]
+  runtime["runtime<br/>services, integration"]
+  targetBrowser["target-browser<br/>DOM terminal"]
+  targetHeadless["target-headless<br/>Node terminal"]
+
+  runtime --> primitives
+  targetBrowser --> runtime
+  targetHeadless --> runtime
+```
+
+## TypeScript projects
+
+| Project | `tsconfig` | Output | Role |
+| --- | --- | --- | --- |
+| Primitives | `src/primitives/tsconfig.json` | `out/primitives/` | Buffer, parser, input helpers, static data, shared utilities. Must not import from `runtime/`. |
+| Runtime | `src/runtime/tsconfig.json` | `out/runtime/` | Services (DI), `CoreTerminal`, `InputHandler`, public API adapters, `Types.ts`. References primitives. |
+| Source (solution) | `src/tsconfig.json` | — | Solution root; references primitives + runtime only. |
+| Target browser | `src/target-browser/tsconfig.json` | `out/target-browser/` | Browser rendering, input, public `Terminal`. References `src/`. |
+| Target headless | `src/target-headless/tsconfig.json` | `out/target-headless/` | Headless terminal. References `src/`. |
+
+Unit test files (`**/*.test.ts`) are excluded from composite library builds; they are compiled via esbuild for `npm run test-unit`.
+
+## `primitives/`
+
+| Area | Contents |
+| --- | --- |
+| Root utilities | `Async`, `CircularList`, `Color`, `ColorTypes`, `Event`, `KeyboardTypes`, `Lifecycle`, `MultiKeyMap`, `Platform`, `SortedList`, `StringBuilder`, `TaskQueue`, `TerminalOptions`, `Version` |
+| `buffer/` | Screen buffer, `CellTypes`, `BufferService` / `BufferOptions` / `BufferLog` interfaces (buffer-layer contracts) |
+| `data/` | `Charsets`, `EscapeSequences` |
+| `input/` | UTF decoding, keyboard helpers, `UnicodeTypes`, `UnicodeProperties` |
+| `parser/` | Escape-sequence parser |
+
+Primitives depend only on other primitives (and `@xterm/xterm` typings where needed). Buffer code uses `IBufferService` from `common/buffer/BufferService`, not `common/services/Services`.
+
+## `runtime/`
+
+| Area | Contents |
+| --- | --- |
+| `services/` | DI implementations (`BufferService`, `OptionsService`, …) |
+| `public/` | Public API adapters (`AddonManager`, buffer/parser views) |
+| Root | `CoreTerminal`, `InputHandler`, `WindowsMode`, `Types.ts`, `TestUtils.test.ts` |
+
+`Types.ts` re-exports primitive types and adds integration types (`IInputHandler`, `ICoreTerminal`, mouse/color helpers, etc.).
+
+## Import paths
+
+Source keeps the `common/...` prefix (logical module name, not a physical `common/` folder). Each project's `paths` in `tsconfig.json` map that prefix to `primitives/` and/or `runtime/`.
+
+Platform code uses:
+
+- `target-browser/...` — browser terminal
+- `target-headless/...` — Node terminal
+
+## Published packages vs source folders
+
+The npm package directory `headless/` (e.g. `headless/lib-headless/`) is unchanged; only the **source** tree uses `src/target-headless/`.
+
+## Related issues
+
+- [#5963](https://github.com/xtermjs/xterm.js/issues/5963) — module split
+- [#5896](https://github.com/xtermjs/xterm.js/issues/5896) — relative imports
+- [#5897](https://github.com/xtermjs/xterm.js/issues/5897) — `import/no-cycle` lint

src/browser/tsconfig.json

@@ -1,25 +0,0 @@
-{
-  "extends": "../tsconfig-library-base",
-  "compilerOptions": {
-    "lib": [
-      "dom",
-      "es2021"
-    ],
-    "outDir": "../../out",
-    "types": [
-      "../../node_modules/@types/mocha"
-    ],
-    "skipLibCheck": true,
-    "paths": {
-      "common/*": [ "./../common/*" ],
-      "*": [ "./../*" ]
-    }
-  },
-  "include": [
-    "./**/*",
-    "../../typings/xterm.d.ts"
-  ],
-  "references": [
-    { "path": "../common" }
-  ]
-}

src/common/tsconfig.json

@@ -1,23 +0,0 @@
-{
-  "extends": "../tsconfig-library-base",
-  "compilerOptions": {
-    "lib": [
-      "es2015",
-      "es2016.Array.Include",
-      "es2019.string",
-      "es2021.weakref"
-    ],
-    "outDir": "../../out",
-    "types": [
-      "../../node_modules/@types/mocha"
-    ],
-    "paths": {
-      "common/*": [ "./../common/*" ],
-      "*": [ "./../*" ]
-    }
-  },
-  "include": [
-    "./**/*",
-    "../../typings/xterm.d.ts"
-  ]
-}

src/primitives/CircularList.ts

@@ -3,9 +3,30 @@
  * @license MIT
  */
 
-import { ICircularList } from 'common/Types';
 import { Disposable } from 'common/Lifecycle';
-import { Emitter } from 'common/Event';
+import { Emitter, type IEvent } from 'common/Event';
+
+export interface ICircularList<T> {
+  length: number;
+  maxLength: number;
+  isFull: boolean;
+
+  onDeleteEmitter: Emitter<IDeleteEvent>;
+  onDelete: IEvent<IDeleteEvent>;
+  onInsertEmitter: Emitter<IInsertEvent>;
+  onInsert: IEvent<IInsertEvent>;
+  onTrimEmitter: Emitter<number>;
+  onTrim: IEvent<number>;
+
+  get(index: number): T | undefined;
+  set(index: number, value: T): void;
+  push(value: T): void;
+  recycle(): T;
+  pop(): T | undefined;
+  splice(start: number, deleteCount: number, ...items: T[]): void;
+  trimStart(count: number): void;
+  shiftElements(start: number, count: number, offset: number): void;
+}
 
 export interface IInsertEvent {
   index: number;

src/primitives/Color.ts

@@ -3,7 +3,7 @@
  * @license MIT
  */
 
-import { IColor, IColorRGB } from 'common/Types';
+import { IColor, IColorRGB } from 'common/ColorTypes';
 
 let $r = 0;
 let $g = 0;

src/primitives/ColorTypes.ts

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) 2018 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+export interface IColor {
+  readonly css: string;
+  readonly rgba: number; // 32-bit int with rgba in each byte
+}
+
+export type IColorRGB = [red: number, green: number, blue: number];

src/primitives/KeyboardTypes.ts

@@ -0,0 +1,29 @@
+/**
+ * Copyright (c) 2018 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+export interface IKeyboardEvent {
+  altKey: boolean;
+  ctrlKey: boolean;
+  shiftKey: boolean;
+  metaKey: boolean;
+  /** @deprecated See KeyboardEvent.keyCode */
+  keyCode: number;
+  key: string;
+  type: string;
+  code: string;
+}
+
+export const enum KeyboardResultType {
+  SEND_KEY,
+  SELECT_ALL,
+  PAGE_UP,
+  PAGE_DOWN
+}
+
+export interface IKeyboardResult {
+  type: KeyboardResultType;
+  cancel: boolean;
+  key: string | undefined;
+}

src/primitives/SortedList.ts

@@ -4,7 +4,7 @@
  */
 
 import { IdleTaskQueue } from 'common/TaskQueue';
-import type { ILogService } from 'common/services/Services';
+import type { IBufferLogService } from 'common/buffer/BufferLog';
 
 // Work variables to avoid garbage collection.
 let i = 0;
@@ -28,7 +28,7 @@ export class SortedList<T> {
 
   constructor(
     private readonly _getKey: (value: T) => number,
-    logService: ILogService
+    logService: IBufferLogService
   ) {
     this._flushInsertedTask = new IdleTaskQueue(logService);
     this._flushDeletedTask = new IdleTaskQueue(logService);

src/primitives/TaskQueue.ts

@@ -3,7 +3,7 @@
  * @license MIT
  */
 
-import type { ILogService } from 'common/services/Services';
+import type { IBufferLogService } from 'common/buffer/BufferLog';
 
 interface ITaskQueue {
   /**
@@ -34,9 +34,9 @@ abstract class TaskQueue implements ITaskQueue {
   private _tasks: (() => boolean | void)[] = [];
   private _idleCallback?: number;
   private _i = 0;
-  protected readonly _logService: ILogService;
+  protected readonly _logService: IBufferLogService;
 
-  constructor(logService: ILogService) {
+  constructor(logService: IBufferLogService) {
     this._logService = logService;
   }
 
@@ -156,7 +156,7 @@ export const IdleTaskQueue = ('requestIdleCallback' in globalThis) ? IdleTaskQue
 export class DebouncedIdleTask {
   private _queue: ITaskQueue;
 
-  constructor(logService: ILogService) {
+  constructor(logService: IBufferLogService) {
     this._queue = new IdleTaskQueue(logService);
   }
 

src/primitives/TerminalOptions.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) 2018 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import { ITerminalOptions as IPublicTerminalOptions } from '@xterm/xterm';
+
+// TODO: The options that are not in the public API should be reviewed
+export interface ITerminalOptions extends IPublicTerminalOptions {
+  [key: string]: any;
+  convertEol?: boolean;
+  termName?: string;
+}

src/primitives/buffer/AttributeData.ts

@@ -3,7 +3,7 @@
  * @license MIT
  */
 
-import { IAttributeData, IColorRGB, IExtendedAttrs } from 'common/Types';
+import { IAttributeData, IColorRGB, IExtendedAttrs } from 'common/buffer/CellTypes';
 import { Attributes, FgFlags, BgFlags, UnderlineStyle, ExtFlags } from 'common/buffer/Constants';
 
 export class AttributeData implements IAttributeData {

src/primitives/buffer/Buffer.ts

@@ -6,7 +6,10 @@
 import { CircularList, IInsertEvent } from 'common/CircularList';
 import { Disposable, toDisposable } from 'common/Lifecycle';
 import { IdleTaskQueue } from 'common/TaskQueue';
-import { IAttributeData, IBufferLine, ICellData, ICharset } from 'common/Types';
+import { IAttributeData, IBufferLine, ICellData } from 'common/buffer/CellTypes';
+import { IBufferLogService } from 'common/buffer/BufferLog';
+import { IBufferOptionsService } from 'common/buffer/BufferOptions';
+import { IBufferService } from 'common/buffer/BufferService';
 import { ExtendedAttrs } from 'common/buffer/AttributeData';
 import { BufferLine, DEFAULT_ATTR_DATA } from 'common/buffer/BufferLine';
 import { BufferLineStringCache } from 'common/buffer/BufferLineStringCache';
@@ -15,8 +18,7 @@ import { CellData } from 'common/buffer/CellData';
 import { NULL_CELL_CHAR, NULL_CELL_CODE, NULL_CELL_WIDTH, WHITESPACE_CELL_CHAR, WHITESPACE_CELL_CODE, WHITESPACE_CELL_WIDTH } from 'common/buffer/Constants';
 import { Marker } from 'common/buffer/Marker';
 import { IBuffer } from 'common/buffer/Types';
-import { DEFAULT_CHARSET } from 'common/data/Charsets';
+import { DEFAULT_CHARSET, ICharset } from 'common/data/Charsets';
-import { IBufferService, ILogService, IOptionsService } from 'common/services/Services';
 
 export const MAX_BUFFER_SIZE = 4294967295; // 2^32 - 1
 
@@ -56,9 +58,9 @@ export class Buffer extends Disposable implements IBuffer {
 
   constructor(
     private _hasScrollback: boolean,
-    private _optionsService: IOptionsService,
+    private _optionsService: IBufferOptionsService,
     private _bufferService: IBufferService,
-    private readonly _logService: ILogService
+    private readonly _logService: IBufferLogService
   ) {
     super();
     this._cols = this._bufferService.cols;

src/primitives/buffer/BufferLine.test.ts

@@ -3,10 +3,10 @@
  * @license MIT
  */
 import { NULL_CELL_CHAR, NULL_CELL_WIDTH, NULL_CELL_CODE, DEFAULT_ATTR, Content, UnderlineStyle, BgFlags, Attributes, FgFlags } from 'common/buffer/Constants';
-import { BufferLine } from 'common/buffer//BufferLine';
+import { BufferLine } from 'common/buffer/BufferLine';
 import { BufferLineStringCache } from 'common/buffer/BufferLineStringCache';
 import { CellData } from 'common/buffer/CellData';
-import { CharData, IBufferLine, ICellData } from '../Types';
+import { CharData, IBufferLine, ICellData } from 'common/buffer/CellTypes';
 import { assert } from 'chai';
 import { AttributeData } from 'common/buffer/AttributeData';
 import { createCellData, NULL_CELL_DATA, extendedAttributes } from 'common/TestUtils.test';

src/primitives/buffer/BufferLine.ts

@@ -3,7 +3,7 @@
  * @license MIT
  */
 
-import { CharData, IAttributeData, IBufferLine, ICellData, IExtendedAttrs } from 'common/Types';
+import { CharData, IAttributeData, IBufferLine, ICellData, IExtendedAttrs } from 'common/buffer/CellTypes';
 import { AttributeData } from 'common/buffer/AttributeData';
 import { CellData } from 'common/buffer/CellData';
 import { Attributes, BgFlags, CHAR_DATA_ATTR_INDEX, CHAR_DATA_CHAR_INDEX, CHAR_DATA_WIDTH_INDEX, Content, NULL_CELL_CHAR, NULL_CELL_CODE, NULL_CELL_WIDTH, WHITESPACE_CELL_CHAR } from 'common/buffer/Constants';

src/primitives/buffer/BufferLog.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) 2022 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+export interface IBufferLogService {
+  warn(message: any, ...optionalParams: any[]): void;
+}

src/primitives/buffer/BufferOptions.ts

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) 2019 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import type { IDisposable } from 'common/Lifecycle';
+import type { ITerminalOptions } from 'common/TerminalOptions';
+
+/**
+ * Options surface used by the buffer layer.
+ */
+export interface IBufferOptionsService {
+  readonly rawOptions: Required<ITerminalOptions>;
+  onSpecificOptionChange<K extends keyof ITerminalOptions>(key: K, callback: (value: ITerminalOptions[K]) => void): IDisposable;
+}

src/primitives/buffer/BufferReflow.ts

@@ -5,7 +5,7 @@
 
 import { BufferLine } from 'common/buffer/BufferLine';
 import { CircularList } from 'common/CircularList';
-import { IBufferLine, ICellData } from 'common/Types';
+import { IBufferLine, ICellData } from 'common/buffer/CellTypes';
 
 export interface INewLayoutResult {
   layout: number[];

src/primitives/buffer/BufferService.ts

@@ -0,0 +1,31 @@
+/**
+ * Copyright (c) 2019 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import type { IEvent } from 'common/Event';
+import type { IAttributeData } from 'common/buffer/CellTypes';
+import type { IBuffer, IBufferSet } from 'common/buffer/Types';
+
+export interface IBufferResizeEvent {
+  cols: number;
+  rows: number;
+  colsChanged: boolean;
+  rowsChanged: boolean;
+}
+
+export interface IBufferService {
+  serviceBrand: undefined;
+
+  readonly cols: number;
+  readonly rows: number;
+  readonly buffer: IBuffer;
+  readonly buffers: IBufferSet;
+  isUserScrolling: boolean;
+  onResize: IEvent<IBufferResizeEvent>;
+  onScroll: IEvent<number>;
+  scroll(eraseAttr: IAttributeData, isWrapped?: boolean): void;
+  scrollLines(disp: number, suppressScrollEvent?: boolean): void;
+  resize(cols: number, rows: number): void;
+  reset(): void;
+}

src/primitives/buffer/BufferSet.ts

@@ -4,10 +4,12 @@
  */
 
 import { Disposable, MutableDisposable } from 'common/Lifecycle';
-import { IAttributeData } from 'common/Types';
+import { IAttributeData } from 'common/buffer/CellTypes';
 import { Buffer } from 'common/buffer/Buffer';
 import { IBuffer, IBufferSet } from 'common/buffer/Types';
-import { IBufferService, ILogService, IOptionsService } from 'common/services/Services';
+import { IBufferLogService } from 'common/buffer/BufferLog';
+import { IBufferOptionsService } from 'common/buffer/BufferOptions';
+import { IBufferService } from 'common/buffer/BufferService';
 import { Emitter } from 'common/Event';
 
 /**
@@ -28,9 +30,9 @@ export class BufferSet extends Disposable implements IBufferSet {
    * Create a new BufferSet for the given terminal.
    */
   constructor(
-    private readonly _optionsService: IOptionsService,
+    private readonly _optionsService: IBufferOptionsService,
     private readonly _bufferService: IBufferService,
-    private readonly _logService: ILogService
+    private readonly _logService: IBufferLogService
   ) {
     super();
     this.reset();

src/primitives/buffer/CellData.ts

@@ -3,7 +3,7 @@
  * @license MIT
  */
 
-import { CharData, ICellData, IExtendedAttrs } from 'common/Types';
+import { CharData, ICellData, IExtendedAttrs } from 'common/buffer/CellTypes';
 import { stringFromCodePoint } from 'common/input/TextDecoder';
 import { CHAR_DATA_CHAR_INDEX, CHAR_DATA_WIDTH_INDEX, CHAR_DATA_ATTR_INDEX, Content } from 'common/buffer/Constants';
 import { AttributeData, ExtendedAttrs } from 'common/buffer/AttributeData';