{"owner":"xtermjs","repo":"xterm.js","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# xterm.js Copilot Instructions\n\n## Architecture Overview\n\n**Core Structure**: xterm.js is a multi-target terminal emulator with three main distributions:\n- `src/browser/`: Full-featured browser terminal with DOM rendering\n- `src/headless/`: Server-side terminal for Node.js (no DOM)\n- `src/common/`: Shared core logic (parsing, buffer management, terminal state)\n\n**Key Classes**:\n- `Terminal` (browser/headless): Public API wrapper\n- `CoreTerminal` (common): Core terminal logic and state\n- `CoreBrowserTerminal` (browser): Browser-specific terminal implementation\n\n## Development Workflow\n\n**Build System**:\n```bash\nnpm run build && npm run esbuild # Build all TypeScript and bundle\n```\n\n**Testing**:\n- Unit tests: `npm run test-unit` (Mocha)\n- Unit tests filtering to file: `npm run test-unit -- **/fileName.ts\n- Per-addon unit tests: `npm run test-unit -- addons/addon-image/out-esbuild/*.test.js`\n- Integration tests: `npm run test-integration` (Playwright across Chrome/Firefox/WebKit)\n- Integration tests by file: `npm run test-integration -- test/playwright/InputHandler.test.ts`. Never use grep to filter tests, it doesn't work\n- Integration tests by addon: `npm run test-integration -- --suite=addon-search`. Suites always follow the format `addon-<something>`\n- Lint: `npm run lint` (oxlint with type-aware rules, then ESLint for `naming-convention` only), `npm run lint-api` for `typings/`, `npm run lint-fix` for oxlint auto-fix\n- Lint changes: `npm run lint-changes` to lint only changed files, `npm run lint-changes-fix` to fix them\n\n## Addon Development Pattern\n\nAll addons follow this structure:\n```typescript\nexport class MyAddon implements ITerminalAddon {\n  activate(terminal: Terminal): void {\n    // Called when loaded via terminal.loadAddon()\n    // Register handlers, access terminal APIs\n  }\n  dispose(): void {\n    // Cleanup when addon is disposed\n  }\n}\n```\n\n**Key Examples**:\n- `addons/addon-fit/`: Terminal sizing\n- `addons/addon-webgl/`: GPU-accelerated rendering\n- `addons/addon-search/`: Text search functionality\n\n## Project-Specific Conventions\n\n**TypeScript Project Structure**: Uses TypeScript project references (`tsconfig.all.json`) for incremental builds across browser/headless/addons.\n\n**API Design**: \n- Browser and headless terminals share the same public API\n- Proposed APIs require `allowProposedApi: true` option\n- Constructor-only options (cols, rows) cannot be changed after instantiation\n\n**Disposable Management**:\n- When a disposable object can be replaced over time, prefer a registered `MutableDisposable` over manual dispose/reassign logic.\n- Register it on the owning class (for example, `this._register(new MutableDisposable())`) and assign through `.value`; this automatically disposes the previous value and avoids accidentally leaking resources.\n\n**TypeScript Constants**:\n- Prefer `const enum` over top-level `const` declarations for primitive constants when appropriate, since values are inlined and avoid runtime property lookups.\n\n**Testing Utilities**: Use `TestUtils.ts` helpers:\n- `openTerminal(ctx, options)` for setup\n- `pollFor(page, fn, expectedValue)` for async assertions\n- `writeSync(page, data)` for terminal input\n\n## Common Patterns\n\n**Parser Integration**: Register custom escape sequence handlers:\n```typescript\nterminal.parser.registerCsiHandler('m', params => {\n  // Handle SGR sequences\n  return true; // Handled\n});\n```\n\n**Buffer Access**: Read terminal content via buffer API:\n```typescript\nconst line = terminal.buffer.active.getLine(0);\nconst cell = line?.getCell(0);\n```\n\n**Events**: All terminals emit standard events (onData, onResize, onRender) plus platform-specific ones.\n\n## Critical Implementation Details\n\n- Terminal rendering uses either DOM or WebGL renderers\n- Buffer lines are immutable; create new instances for modifications\n- Character width handling supports Unicode 11+ and grapheme clustering\n- Mouse events translate web events to terminal protocols (X10, VT200, etc.)\n- Color theming supports both palette and true color modes\n\n## Writing unit tests\n\n- Unit tests live alongside the source code file of the thing it's testing with a .test.ts suffix.\n\n## Cursor Cloud specific instructions\n\n**Demo server**: Start with `npm start` (port 3000). The demo server uses node-pty to spawn real shell sessions over WebSocket. Integration tests auto-start it via Playwright's `webServer` config, so you don't need to start it manually for `npm run test-integration`.\n\n**Build before testing**: Always run `npm run build && npm run esbuild` before `npm run test-unit`. Integration tests also need `npm run esbuild-demo-client` and `npm run esbuild-demo-server`. The update script handles this automatically on session start.\n\n**No external services**: This project has zero external dependencies (no databases, Docker, or APIs). Everything runs locally with Node.js.\n\n**TypeScript compiler**: The project uses `tsgo` (native TypeScript compiler preview) rather than standard `tsc`. It's installed via the `@typescript/native-preview` package.\n\n**Lint only changed files**: Prefer `npm run lint-changes` over `npm run lint` when iterating on code changes — it's significantly faster.\n"},"files":{"AGENTS.md":"# xterm.js Copilot Instructions\n\n## Architecture Overview\n\n**Core Structure**: xterm.js is a multi-target terminal emulator with three main distributions:\n- `src/browser/`: Full-featured browser terminal with DOM rendering\n- `src/headless/`: Server-side terminal for Node.js (no DOM)\n- `src/common/`: Shared core logic (parsing, buffer management, terminal state)\n\n**Key Classes**:\n- `Terminal` (browser/headless): Public API wrapper\n- `CoreTerminal` (common): Core terminal logic and state\n- `CoreBrowserTerminal` (browser): Browser-specific terminal implementation\n\n## Development Workflow\n\n**Build System**:\n```bash\nnpm run build && npm run esbuild # Build all TypeScript and bundle\n```\n\n**Testing**:\n- Unit tests: `npm run test-unit` (Mocha)\n- Unit tests filtering to file: `npm run test-unit -- **/fileName.ts\n- Per-addon unit tests: `npm run test-unit -- addons/addon-image/out-esbuild/*.test.js`\n- Integration tests: `npm run test-integration` (Playwright across Chrome/Firefox/WebKit)\n- Integration tests by file: `npm run test-integration -- test/playwright/InputHandler.test.ts`. Never use grep to filter tests, it doesn't work\n- Integration tests by addon: `npm run test-integration -- --suite=addon-search`. Suites always follow the format `addon-<something>`\n- Lint: `npm run lint` (oxlint with type-aware rules, then ESLint for `naming-convention` only), `npm run lint-api` for `typings/`, `npm run lint-fix` for oxlint auto-fix\n- Lint changes: `npm run lint-changes` to lint only changed files, `npm run lint-changes-fix` to fix them\n\n## Addon Development Pattern\n\nAll addons follow this structure:\n```typescript\nexport class MyAddon implements ITerminalAddon {\n  activate(terminal: Terminal): void {\n    // Called when loaded via terminal.loadAddon()\n    // Register handlers, access terminal APIs\n  }\n  dispose(): void {\n    // Cleanup when addon is disposed\n  }\n}\n```\n\n**Key Examples**:\n- `addons/addon-fit/`: Terminal sizing\n- `addons/addon-webgl/`: GPU-accelerated rendering\n- `addons/addon-search/`: Text search functionality\n\n## Project-Specific Conventions\n\n**TypeScript Project Structure**: Uses TypeScript project references (`tsconfig.all.json`) for incremental builds across browser/headless/addons.\n\n**API Design**: \n- Browser and headless terminals share the same public API\n- Proposed APIs require `allowProposedApi: true` option\n- Constructor-only options (cols, rows) cannot be changed after instantiation\n\n**Disposable Management**:\n- When a disposable object can be replaced over time, prefer a registered `MutableDisposable` over manual dispose/reassign logic.\n- Register it on the owning class (for example, `this._register(new MutableDisposable())`) and assign through `.value`; this automatically disposes the previous value and avoids accidentally leaking resources.\n\n**TypeScript Constants**:\n- Prefer `const enum` over top-level `const` declarations for primitive constants when appropriate, since values are inlined and avoid runtime property lookups.\n\n**Testing Utilities**: Use `TestUtils.ts` helpers:\n- `openTerminal(ctx, options)` for setup\n- `pollFor(page, fn, expectedValue)` for async assertions\n- `writeSync(page, data)` for terminal input\n\n## Common Patterns\n\n**Parser Integration**: Register custom escape sequence handlers:\n```typescript\nterminal.parser.registerCsiHandler('m', params => {\n  // Handle SGR sequences\n  return true; // Handled\n});\n```\n\n**Buffer Access**: Read terminal content via buffer API:\n```typescript\nconst line = terminal.buffer.active.getLine(0);\nconst cell = line?.getCell(0);\n```\n\n**Events**: All terminals emit standard events (onData, onResize, onRender) plus platform-specific ones.\n\n## Critical Implementation Details\n\n- Terminal rendering uses either DOM or WebGL renderers\n- Buffer lines are immutable; create new instances for modifications\n- Character width handling supports Unicode 11+ and grapheme clustering\n- Mouse events translate web events to terminal protocols (X10, VT200, etc.)\n- Color theming supports both palette and true color modes\n\n## Writing unit tests\n\n- Unit tests live alongside the source code file of the thing it's testing with a .test.ts suffix.\n\n## Cursor Cloud specific instructions\n\n**Demo server**: Start with `npm start` (port 3000). The demo server uses node-pty to spawn real shell sessions over WebSocket. Integration tests auto-start it via Playwright's `webServer` config, so you don't need to start it manually for `npm run test-integration`.\n\n**Build before testing**: Always run `npm run build && npm run esbuild` before `npm run test-unit`. Integration tests also need `npm run esbuild-demo-client` and `npm run esbuild-demo-server`. The update script handles this automatically on session start.\n\n**No external services**: This project has zero external dependencies (no databases, Docker, or APIs). Everything runs locally with Node.js.\n\n**TypeScript compiler**: The project uses `tsgo` (native TypeScript compiler preview) rather than standard `tsc`. It's installed via the `@typescript/native-preview` package.\n\n**Lint only changed files**: Prefer `npm run lint-changes` over `npm run lint` when iterating on code changes — it's significantly faster.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# xterm.js Copilot Instructions\n\n## Architecture Overview\n\n**Core Structure**: xterm.js is a multi-target terminal emulator with three main distributions:\n- `src/browser/`: Full-featured browser terminal with DOM rendering\n- `src/headless/`: Server-side terminal for Node.js (no DOM)\n- `src/common/`: Shared core logic (parsing, buffer management, terminal state)\n\n**Key Classes**:\n- `Terminal` (browser/headless): Public API wrapper\n- `CoreTerminal` (common): Core terminal logic and state\n- `CoreBrowserTerminal` (browser): Browser-specific terminal implementation\n\n## Development Workflow\n\n**Build System**:\n```bash\nnpm run build && npm run esbuild # Build all TypeScript and bundle\n```\n\n**Testing**:\n- Unit tests: `npm run test-unit` (Mocha)\n- Unit tests filtering to file: `npm run test-unit -- **/fileName.ts\n- Per-addon unit tests: `npm run test-unit -- addons/addon-image/out-esbuild/*.test.js`\n- Integration tests: `npm run test-integration` (Playwright across Chrome/Firefox/WebKit)\n- Integration tests by file: `npm run test-integration -- test/playwright/InputHandler.test.ts`. Never use grep to filter tests, it doesn't work\n- Integration tests by addon: `npm run test-integration -- --suite=addon-search`. Suites always follow the format `addon-<something>`\n- Lint: `npm run lint` (oxlint with type-aware rules, then ESLint for `naming-convention` only), `npm run lint-api` for `typings/`, `npm run lint-fix` for oxlint auto-fix\n- Lint changes: `npm run lint-changes` to lint only changed files, `npm run lint-changes-fix` to fix them\n\n## Addon Development Pattern\n\nAll addons follow this structure:\n```typescript\nexport class MyAddon implements ITerminalAddon {\n  activate(terminal: Terminal): void {\n    // Called when loaded via terminal.loadAddon()\n    // Register handlers, access terminal APIs\n  }\n  dispose(): void {\n    // Cleanup when addon is disposed\n  }\n}\n```\n\n**Key Examples**:\n- `addons/addon-fit/`: Terminal sizing\n- `addons/addon-webgl/`: GPU-accelerated rendering\n- `addons/addon-search/`: Text search functionality\n\n## Project-Specific Conventions\n\n**TypeScript Project Structure**: Uses TypeScript project references (`tsconfig.all.json`) for incremental builds across browser/headless/addons.\n\n**API Design**: \n- Browser and headless terminals share the same public API\n- Proposed APIs require `allowProposedApi: true` option\n- Constructor-only options (cols, rows) cannot be changed after instantiation\n\n**Disposable Management**:\n- When a disposable object can be replaced over time, prefer a registered `MutableDisposable` over manual dispose/reassign logic.\n- Register it on the owning class (for example, `this._register(new MutableDisposable())`) and assign through `.value`; this automatically disposes the previous value and avoids accidentally leaking resources.\n\n**TypeScript Constants**:\n- Prefer `const enum` over top-level `const` declarations for primitive constants when appropriate, since values are inlined and avoid runtime property lookups.\n\n**Testing Utilities**: Use `TestUtils.ts` helpers:\n- `openTerminal(ctx, options)` for setup\n- `pollFor(page, fn, expectedValue)` for async assertions\n- `writeSync(page, data)` for terminal input\n\n## Common Patterns\n\n**Parser Integration**: Register custom escape sequence handlers:\n```typescript\nterminal.parser.registerCsiHandler('m', params => {\n  // Handle SGR sequences\n  return true; // Handled\n});\n```\n\n**Buffer Access**: Read terminal content via buffer API:\n```typescript\nconst line = terminal.buffer.active.getLine(0);\nconst cell = line?.getCell(0);\n```\n\n**Events**: All terminals emit standard events (onData, onResize, onRender) plus platform-specific ones.\n\n## Critical Implementation Details\n\n- Terminal rendering uses either DOM or WebGL renderers\n- Buffer lines are immutable; create new instances for modifications\n- Character width handling supports Unicode 11+ and grapheme clustering\n- Mouse events translate web events to terminal protocols (X10, VT200, etc.)\n- Color theming supports both palette and true color modes\n\n## Writing unit tests\n\n- Unit tests live alongside the source code file of the thing it's testing with a .test.ts suffix.\n\n## Cursor Cloud specific instructions\n\n**Demo server**: Start with `npm start` (port 3000). The demo server uses node-pty to spawn real shell sessions over WebSocket. Integration tests auto-start it via Playwright's `webServer` config, so you don't need to start it manually for `npm run test-integration`.\n\n**Build before testing**: Always run `npm run build && npm run esbuild` before `npm run test-unit`. Integration tests also need `npm run esbuild-demo-client` and `npm run esbuild-demo-server`. The update script handles this automatically on session start.\n\n**No external services**: This project has zero external dependencies (no databases, Docker, or APIs). Everything runs locally with Node.js.\n\n**TypeScript compiler**: The project uses `tsgo` (native TypeScript compiler preview) rather than standard `tsc`. It's installed via the `@typescript/native-preview` package.\n\n**Lint only changed files**: Prefer `npm run lint-changes` over `npm run lint` when iterating on code changes — it's significantly faster.\n","category":"root","tokens":1295}]}