Move primitives and runtime out of src/common/

Relocate src/common/primitives and src/common/runtime to src/primitives
and src/runtime. Add src/tsconfig.json as the primitives+runtime solution.
Update tsconfigs, esbuild, webpack aliases, publish path, and docs.

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

AGENTS.md

@@ -3,8 +3,8 @@
 ## Architecture Overview
 
 **Core Structure**: xterm.js is a multi-target terminal emulator with these main source areas:
-- `src/common/primitives/`: Building blocks (buffer, parser, input, data, utilities); TypeScript project `src/common/primitives/tsconfig.json`
-- `src/common/runtime/`: Services, `CoreTerminal`, `InputHandler`, public API adapters; TypeScript project `src/common/runtime/tsconfig.json`
+- `src/primitives/`: Building blocks (buffer, parser, input, data, utilities); TypeScript project `src/primitives/tsconfig.json`
+- `src/runtime/`: Services, `CoreTerminal`, `InputHandler`, public API adapters; TypeScript project `src/runtime/tsconfig.json`
 - `src/target-browser/`: Browser terminal with DOM rendering
 - `src/target-headless/`: Node terminal without DOM
 

addons/addon-attach/test/tsconfig.json

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

addons/addon-clipboard/test/tsconfig.json

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

addons/addon-fit/test/tsconfig.json

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

addons/addon-image/src/tsconfig.json

@@ -14,9 +14,8 @@
     "paths": {
       "target-browser/*": [ "../../../src/target-browser/*" ],
       "common/*": [
-        "../../../src/common/primitives/*",
-        "../../../src/common/runtime/*",
-        "../../../src/common/*"
+        "../../../src/primitives/*",
+        "../../../src/runtime/*",
       ],
       "@xterm/addon-image": [ "../typings/addon-image.d.ts" ],
       "*": [ "./*" ]
@@ -28,6 +27,6 @@
   ],
   "references": [
     { "path": "../../../src/target-browser" },
-    { "path": "../../../src/common" }
+    { "path": "../../../src" }
   ]
 }

addons/addon-image/test/tsconfig.json

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

addons/addon-image/webpack.config.js

@@ -25,7 +25,10 @@ const addon = {
     modules: ['./node_modules'],
     extensions: [ '.js' ],
     alias: {
-      common: path.resolve('../../out/common'),
+      common: [
+      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,9 +16,8 @@
     ],
     "paths": {
       "common/*": [
-        "../../../src/common/primitives/*",
-        "../../../src/common/runtime/*",
-        "../../../src/common/*"
+        "../../../src/primitives/*",
+        "../../../src/runtime/*",
       ],
       "target-browser/*": [
         "../../../src/target-browser/*"
@@ -37,7 +36,7 @@
       "path": "../../../src/target-browser"
     },
     {
-      "path": "../../../src/common"
+      "path": "../../../src"
     }
   ]
 }

addons/addon-progress/test/tsconfig.json

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

addons/addon-progress/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'),
+    ],
       browser: path.resolve('../../out/target-browser'),
       vs: path.resolve('../../out/vs')
     }

addons/addon-search/src/tsconfig.json

@@ -16,9 +16,8 @@
     ],
     "paths": {
       "common/*": [
-        "../../../src/common/primitives/*",
-        "../../../src/common/runtime/*",
-        "../../../src/common/*"
+        "../../../src/primitives/*",
+        "../../../src/runtime/*",
       ],
       "target-browser/*": [
         "../../../src/target-browser/*"
@@ -34,7 +33,7 @@
   ],
   "references": [
     {
-      "path": "../../../src/common"
+      "path": "../../../src"
     },
     {
       "path": "../../../src/target-browser"

addons/addon-search/test/tsconfig.json

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

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/tsconfig.json

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

addons/addon-serialize/src/tsconfig.json

@@ -12,9 +12,8 @@
     "removeComments": true,
     "paths": {
       "common/*": [
-        "../../../src/common/primitives/*",
-        "../../../src/common/runtime/*",
-        "../../../src/common/*"
+        "../../../src/primitives/*",
+        "../../../src/runtime/*",
       ],
       "target-browser/*": [
         "../../../src/target-browser/*"
@@ -35,7 +34,7 @@
   ],
   "references": [
     {
-      "path": "../../../src/common"
+      "path": "../../../src"
     },
     {
       "path": "../../../src/target-browser"

addons/addon-serialize/test/tsconfig.json

@@ -11,9 +11,8 @@
     "removeComments": true,
     "paths": {
       "common/*": [
-        "../../../src/common/primitives/*",
-        "../../../src/common/runtime/*",
-        "../../../src/common/*"
+        "../../../src/primitives/*",
+        "../../../src/runtime/*",
       ],
       "target-browser/*": [
         "../../../src/target-browser/*"
@@ -30,7 +29,7 @@
   ],
   "references": [
     {
-      "path": "../../../src/common"
+      "path": "../../../src"
     },
     {
       "path": "../../../src/target-browser"

addons/addon-serialize/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'),
+    ],
       browser: path.resolve('../../out/target-browser')
     }
   },

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

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

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

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

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

@@ -11,9 +11,8 @@
     "removeComments": true,
     "paths": {
       "common/*": [
-        "../../../src/common/primitives/*",
-        "../../../src/common/runtime/*",
-        "../../../src/common/*"
+        "../../../src/primitives/*",
+        "../../../src/runtime/*",
       ],
       "target-browser/*": [
         "../../../src/target-browser/*"
@@ -30,7 +29,7 @@
   ],
   "references": [
     {
-      "path": "../../../src/common"
+      "path": "../../../src"
     },
     {
       "path": "../../../src/target-browser"

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/tsconfig.json

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

addons/addon-unicode11/test/tsconfig.json

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

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,9 +11,8 @@
     "removeComments": true,
     "paths": {
       "common/*": [
-        "../../../src/common/primitives/*",
-        "../../../src/common/runtime/*",
-        "../../../src/common/*"
+        "../../../src/primitives/*",
+        "../../../src/runtime/*",
       ],
       "target-browser/*": [
         "../../../src/target-browser/*"
@@ -33,7 +32,7 @@
   ],
   "references": [
     {
-      "path": "../../../src/common"
+      "path": "../../../src"
     },
     {
       "path": "../../../src/target-browser"

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

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

addons/addon-webgl/src/tsconfig.json

@@ -12,9 +12,8 @@
     "removeComments": true,
     "paths": {
       "common/*": [
-        "../../../src/common/primitives/*",
-        "../../../src/common/runtime/*",
-        "../../../src/common/*"
+        "../../../src/primitives/*",
+        "../../../src/runtime/*",
       ],
       "target-browser/*": [
         "../../../src/target-browser/*"
@@ -38,7 +37,7 @@
   ],
   "references": [
     {
-      "path": "../../../src/common"
+      "path": "../../../src"
     },
     {
       "path": "../../../src/target-browser"

addons/addon-webgl/test/tsconfig.json

@@ -11,9 +11,8 @@
     "removeComments": true,
     "paths": {
       "common/*": [
-        "../../../src/common/primitives/*",
-        "../../../src/common/runtime/*",
-        "../../../src/common/*"
+        "../../../src/primitives/*",
+        "../../../src/runtime/*",
       ],
       "target-browser/*": [
         "../../../src/target-browser/*"
@@ -34,7 +33,7 @@
   ],
   "references": [
     {
-      "path": "../../../src/common"
+      "path": "../../../src"
     },
     {
       "path": "../../../src/target-browser"

addons/addon-webgl/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'),
+    ],
       browser: path.resolve('../../out/target-browser'),
       vs: path.resolve('../../out/vs')
     }

bin/esbuild.mjs

@@ -192,14 +192,14 @@ if (config.addon) {
   outBuilds = [
     {
       ...outConfig,
-      entryPoints: ['src/common/primitives/**/*.ts'],
-      outbase: 'src/common/primitives',
+      entryPoints: ['src/primitives/**/*.ts'],
+      outbase: 'src/primitives',
       outdir: 'out-esbuild/common',
     },
     {
       ...outConfig,
-      entryPoints: ['src/common/runtime/**/*.ts'],
-      outbase: 'src/common/runtime',
+      entryPoints: ['src/runtime/**/*.ts'],
+      outbase: 'src/runtime',
       outdir: 'out-esbuild/common',
     },
     {

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/primitives/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 = '[^']+';/,

src/ARCHITECTURE.md

@@ -6,8 +6,8 @@ This document describes how `src/` is organized. The layout follows [issue #5963
 
 ```mermaid
 flowchart BT
-  primitives["common/primitives<br/>building blocks"]
-  runtime["common/runtime<br/>services, integration"]
+  primitives["primitives<br/>building blocks"]
+  runtime["runtime<br/>services, integration"]
   targetBrowser["target-browser<br/>DOM terminal"]
   targetHeadless["target-headless<br/>Node terminal"]
 
@@ -20,15 +20,15 @@ flowchart BT
 
 | Project | `tsconfig` | Output | Role |
 | --- | --- | --- | --- |
-| Primitives | `src/common/primitives/tsconfig.json` | `out/common/primitives/` | Buffer, parser, input helpers, static data, shared utilities. Must not import from `runtime/`. |
-| Runtime | `src/common/runtime/tsconfig.json` | `out/common/runtime/` | Services (DI), `CoreTerminal`, `InputHandler`, public API adapters, `Types.ts`. References primitives. |
-| Common (solution) | `src/common/tsconfig.json` | — | Solution root; references primitives + runtime only. |
-| Target browser | `src/target-browser/tsconfig.json` | `out/target-browser/` | Browser rendering, input, public `Terminal`. References common. |
-| Target headless | `src/target-headless/tsconfig.json` | `out/target-headless/` | Headless terminal. References common. |
+| 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`.
 
-## `common/primitives/`
+## `primitives/`
 
 | Area | Contents |
 | --- | --- |
@@ -40,7 +40,7 @@ Unit test files (`**/*.test.ts`) are excluded from composite library builds; the
 
 Primitives depend only on other primitives (and `@xterm/xterm` typings where needed). Buffer code uses `IBufferService` from `common/buffer/BufferService`, not `common/services/Services`.
 
-## `common/runtime/`
+## `runtime/`
 
 | Area | Contents |
 | --- | --- |
@@ -52,12 +52,12 @@ Primitives depend only on other primitives (and `@xterm/xterm` typings where nee
 
 ## Import paths
 
-Source keeps the `common/...` prefix. Each project's `paths` in `tsconfig.json` map that prefix to the correct layer (primitives first, then runtime, for targets).
+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/...` — was `browser/...`
-- `target-headless/...` — was `headless/...`
+- `target-browser/...` — browser terminal
+- `target-headless/...` — Node terminal
 
 ## Published packages vs source folders