diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 99c70f1f..c91fc82e 100644
--- a/.github/copilot-instructions.md
+++ b/.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`:
-
-```sh
-# All unit tests
-yarn test-unit
-
-# Absolute file path
-yarn test-unit out-esbuild/browser/Terminal.test.js
-
-# Filter by wildcard
-yarn test-unit out-esbuild/**/Terminal.test.js
-
-# Specific addon unit tests tests
-yarn test-unit addons/addon-image/out-esbuild/*.test.js
-
-# Multiple files
-yarn test-unit out-esbuild/**/Terminal.test.js out-esbuild/**/InputHandler.test.js
+**Build System**:
+```bash
+npm run build && npm run esbuild # Build all TypeScript and bundle
 ```
 
-These use mocha to run all `.test.js` files within the esbuild output (`out-esbuild/`).
+**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`
 
-## Integration tests
+## Addon Development Pattern
 
-Integration tests are run with `yarn test-integration`:
-
-```sh
-# All integration tests
-yarn test-integration
-
-# Core integration tests
-yarn test-integration --suite=core
-
-# Specific addon integration tests
-yarn test-integration --suite=addon-search
+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
+  }
+}
 ```
 
-These use `@playwright/test` to run all tests within the esbuild test output (`out-esbuild-test/`).
+**Key Examples**:
+- `addons/addon-fit/`: Terminal sizing
+- `addons/addon-webgl/`: GPU-accelerated rendering
+- `addons/addon-search/`: Text search functionality
+
+## Project-Specific Conventions
+
+**TypeScript Project Structure**: Uses TypeScript project references (`tsconfig.all.json`) for incremental builds across browser/headless/addons.
+
+**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
+
+**Testing Utilities**: Use `TestUtils.ts` helpers:
+- `openTerminal(ctx, options)` for setup
+- `pollFor(page, fn, expectedValue)` for async assertions
+- `writeSync(page, data)` for terminal input
+
+## Common Patterns
+
+**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);
+```
+
+**Events**: All terminals emit standard events (onData, onResize, onRender) plus platform-specific ones.
+
+## Critical Implementation Details
+
+- 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
+
+## Writing unit tests
+
+- Unit tests live alongside the source code file of the thing it's testing with a .test.ts suffix.
diff --git a/.github/instructions/unit-test-instructions.instructions.md b/.github/instructions/unit-test-instructions.instructions.md
new file mode 100644
index 00000000..f139e822
--- /dev/null
+++ b/.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.