Merge pull request #5407 from Tyriar/tyriar/bd09_copilot_instructions

Improve Copilot instructions and add test guidelines

Author: Tyriar

.github/copilot-instructions.md

@@ -1,48 +1,90 @@
-This is a TypeScript-based repository with a Ruby client for certain API endpoints. It includes several sub projects called addons which are built separately. It contains a demo application which showcases the functionality of the project.
+# xterm.js Copilot Instructions
 
-Please follow these guidelines when contributing:
+## Architecture Overview
 
-## Development Flow
+**Core Structure**: xterm.js is a multi-target terminal emulator with three main distributions:
+- `src/browser/`: Full-featured browser terminal with DOM rendering
+- `src/headless/`: Server-side terminal for Node.js (no DOM)
+- `src/common/`: Shared core logic (parsing, buffer management, terminal state)
 
-- Install dependencies: `npm install && npm run setup`
-- Build and bundle demo: `npm run build && npm run esbuild`
+**Key Classes**:
+- `Terminal` (browser/headless): Public API wrapper
+- `CoreTerminal` (common): Core terminal logic and state
+- `CoreBrowserTerminal` (browser): Browser-specific terminal implementation
 
-## Unit tests
+## Development Workflow
 
-Unit tests are run with `yarn test-unit`:
+**Build System**:
+```bash
+npm run build && npm run esbuild # Build all TypeScript and bundle
+```
+
+**Testing**:
+- Unit tests: `npm run test-unit` (Mocha)
+- Per-addon unit tests: `npm run test-unit addons/addon-image/out-esbuild/*.test.js`
+- Integration tests: `npm run test-integration` (Playwright across Chrome/Firefox/WebKit)
+- Per-addon integration tests: `npm run test-integration --suite=addon-search`
+
+## Addon Development Pattern
+
+All addons follow this structure:
+```typescript
+export class MyAddon implements ITerminalAddon {
+  activate(terminal: Terminal): void {
+    // Called when loaded via terminal.loadAddon()
+    // Register handlers, access terminal APIs
+  }
+  dispose(): void {
+    // Cleanup when addon is disposed
+  }
+}
+```
 
-```sh
-# All unit tests
-yarn test-unit
+**Key Examples**:
+- `addons/addon-fit/`: Terminal sizing
+- `addons/addon-webgl/`: GPU-accelerated rendering
+- `addons/addon-search/`: Text search functionality
 
-# Absolute file path
-yarn test-unit out-esbuild/browser/Terminal.test.js
+## Project-Specific Conventions
 
-# Filter by wildcard
-yarn test-unit out-esbuild/**/Terminal.test.js
+**TypeScript Project Structure**: Uses TypeScript project references (`tsconfig.all.json`) for incremental builds across browser/headless/addons.
 
-# Specific addon unit tests tests
-yarn test-unit addons/addon-image/out-esbuild/*.test.js
+**API Design**: 
+- Browser and headless terminals share the same public API
+- Proposed APIs require `allowProposedApi: true` option
+- Constructor-only options (cols, rows) cannot be changed after instantiation
 
-# Multiple files
-yarn test-unit out-esbuild/**/Terminal.test.js out-esbuild/**/InputHandler.test.js
-```
+**Testing Utilities**: Use `TestUtils.ts` helpers:
+- `openTerminal(ctx, options)` for setup
+- `pollFor(page, fn, expectedValue)` for async assertions
+- `writeSync(page, data)` for terminal input
 
-These use mocha to run all `.test.js` files within the esbuild output (`out-esbuild/`).
+## Common Patterns
 
-## Integration tests
+**Parser Integration**: Register custom escape sequence handlers:
+```typescript
+terminal.parser.registerCsiHandler('m', params => {
+  // Handle SGR sequences
+  return true; // Handled
+});
+```
+
+**Buffer Access**: Read terminal content via buffer API:
+```typescript
+const line = terminal.buffer.active.getLine(0);
+const cell = line?.getCell(0);
+```
 
-Integration tests are run with `yarn test-integration`:
+**Events**: All terminals emit standard events (onData, onResize, onRender) plus platform-specific ones.
 
-```sh
-# All integration tests
-yarn test-integration
+## Critical Implementation Details
 
-# Core integration tests
-yarn test-integration --suite=core
+- Terminal rendering uses either DOM or WebGL renderers
+- Buffer lines are immutable; create new instances for modifications
+- Character width handling supports Unicode 11+ and grapheme clustering
+- Mouse events translate web events to terminal protocols (X10, VT200, etc.)
+- Color theming supports both palette and true color modes
 
-# Specific addon integration tests
-yarn test-integration --suite=addon-search
-```
+## Writing unit tests
 
-These use `@playwright/test` to run all tests within the esbuild test output (`out-esbuild-test/`).
+- Unit tests live alongside the source code file of the thing it's testing with a .test.ts suffix.

.github/instructions/unit-test-instructions.instructions.md

@@ -0,0 +1,8 @@
+---
+applyTo: '**/*.test.ts'
+---
+When writing unit tests follow these rules:
+
+- When writing unit tests for addons, always create a real xterm.js instance instead of mocking it.
+- Prefer `assert.ok` over `assert.notStrictEqual` when checking something is undefined or not.
+- Avoid comments as most tests should be self-documenting.