Restructure common into layered folders (issue #5963)

Reorganize src/common into platform (base, encoding, data, buffer,
parser, input), integration (services, terminal), and public API layers.

- Move core utilities to common/base/
- Move TextDecoder to common/encoding/
- Move Types, CircularList, Color, TaskQueue, SortedList to common/services/
- Move CoreTerminal, InputHandler, WindowsMode to common/terminal/
- Define ICharset in common/data/Charsets.ts (re-exported from Types)
- Update imports across src/, addons/, and test/
- Add per-layer tsconfig.json files and REARCHITECTURE.md
- Root common/tsconfig.json remains the composite build entry

Co-authored-by: Daniel Imms <Tyriar@users.noreply.github.com>
This commit is contained in:
Cursor Agent
2026-05-30 16:12:18 +00:00
co-authored by Daniel Imms
parent 43e8365f0e
commit 1d125ac715
207 changed files with 2505 additions and 288 deletions
+60
View File
@@ -0,0 +1,60 @@
# Common folder rearchitecture
Layered layout for `src/common/` as proposed in [issue #5963](https://github.com/xtermjs/xterm.js/issues/5963).
## Dependency graph (target)
```mermaid
flowchart BT
subgraph platform["Platform layer"]
direction LR
base["common/base"]
encoding["common/encoding"]
data["common/data"]
buffer["common/buffer"]
parser["common/parser"]
input["common/input"]
encoding --> base
data --> base
buffer --> encoding
buffer --> data
parser --> buffer
input --> parser
end
subgraph integration["Integration layer"]
direction LR
services["common/services"]
terminal["common/terminal"]
terminal --> services
end
subgraph api_layer["API layer"]
public["common/public"]
end
integration --> platform
api_layer --> integration
```
## Package contents
| Project | Role | Notable sources |
| --- | --- | --- |
| `common/base` | Core utilities (lifecycle, events, platform) | `Async`, `Event`, `Lifecycle`, `Platform`, `StringBuilder`, `Version` |
| `common/encoding` | UTF conversion | `TextDecoder` (moved from `input/`) |
| `common/data` | Static terminal data | `Charsets`, `EscapeSequences` |
| `common/buffer` | Screen buffer | `Buffer`, `BufferLine`, … |
| `common/parser` | Escape sequence parser | `EscapeSequenceParser`, … |
| `common/input` | Keyboard / write path helpers | `Keyboard`, `WriteBuffer`, … |
| `common/services` | DI services and shared types | `Services`, `Types`, `CircularList`, … |
| `common/terminal` | Core terminal + input handler | `CoreTerminal`, `InputHandler`, `WindowsMode` |
| `common/public` | Public API adapters | `AddonManager`, buffer API views |
## TypeScript projects
- **`common/tsconfig.json`** — composite build for all layers (resolves existing `buffer` ↔ `services` imports).
- **`common/<layer>/tsconfig.json`** — per-layer config extending the root (`noEmit`) for tooling and future split into referenced composite projects.
Enforcing one-way project references at compile time (separate `out` per layer) is follow-up work once `Types` and buffer service interfaces are decoupled.