Copilot instructions

1# Copilot Instructions for Electron
2 
3## Build System
4 
5Electron uses `@electron/build-tools` (`e` CLI). Install with `npm i -g @electron/build-tools`.
6 
7```bash
8e sync              # Fetch sources and apply patches
9e build             # Build Electron (GN + Ninja)
10e build -k 999      # Build, continuing through errors
11e start             # Run built Electron
12e start --version   # Verify Electron launches
13e test              # Run full test suite
14e debug             # Run in debugger (lldb on macOS, gdb on Linux)
15```
16 
17### Linting
18 
19```bash
20npm run lint              # Run all linters (JS, C++, Python, GN, docs)
21npm run lint:js           # JavaScript/TypeScript only
22npm run lint:clang-format # C++ formatting only
23npm run lint:cpp          # C++ linting only
24npm run lint:docs         # Documentation only
25```
26 
27### Running a Single Test
28 
29```bash
30npm run test -- -g "pattern"   # Run tests matching a regex pattern
31# Example: npm run test -- -g "ipc"
32```
33 
34### Running a Single Node.js Test
35 
36```bash
37node script/node-spec-runner.js parallel/test-crypto-keygen
38```
39 
40## Architecture
41 
42Electron embeds Chromium (rendering) and Node.js (backend) to enable desktop apps with web technologies. The parent directory (`../`) is the Chromium source tree.
43 
44### Process Model
45 
46Electron has two primary process types, mirroring Chromium:
47 
48- **Main process** (`shell/browser/` + `lib/browser/`): Controls app lifecycle, creates windows, system APIs
49- **Renderer process** (`shell/renderer/` + `lib/renderer/`): Runs web content in BrowserWindows
50 
51### Native ↔ JavaScript Bridge
52 
53Each API is implemented as a C++/JS pair:
54 
55- C++ side: `shell/browser/api/electron_api_{name}.cc/.h` — uses `gin::Wrappable` and `ObjectTemplateBuilder`
56- JS side: `lib/browser/api/{name}.ts` — exports the module, registered in `lib/browser/api/module-list.ts`
57- Binding: `NODE_LINKED_BINDING_CONTEXT_AWARE(electron_browser_{name}, Initialize)` in C++ and registered in `shell/common/node_bindings.cc`
58- Type declaration: `typings/internal-ambient.d.ts` maps `process._linkedBinding('electron_browser_{name}')`
59 
60### Patches System
61 
62Electron patches upstream dependencies (Chromium, Node.js, V8, etc.) rather than forking them. Patches live in `patches/` organized by target, with `patches/config.json` mapping directories to repos.
63 
64```text
65patches/{target}/*.patch  →  [e sync]   →  target repo commits
66                          ←  [e patches] ←
67```
68 
69Key rules:
70 
71- Fix existing patches rather than creating new ones
72- Preserve original authorship in TODO comments — never change `TODO(name)` assignees
73- Each patch commit message must explain why the patch exists
74- After modifying patches, run `e patches {target}` to export
75 
76When working on the `roller/chromium/main` branch for Chromium upgrades, use `e sync --3` for 3-way merge conflict resolution.
77 
78## Conventions
79 
80### File Naming
81 
82- JS/TS files: kebab-case (`file-name.ts`)
83- C++ files: snake_case with `electron_api_` prefix (`electron_api_safe_storage.cc`)
84- Test files: `api-{module-name}-spec.ts` in `spec/`
85- Source file lists are maintained in `filenames.gni` (with platform-specific sections)
86 
87### JavaScript/TypeScript
88 
89- Semicolons required (`"semi": ["error", "always"]`)
90- `const` and `let` only (no `var`)
91- Arrow functions preferred
92- Import order enforced: `@electron/internal` → `@electron` → `electron` → external → builtin → relative
93- API naming: `PascalCase` for classes (`BrowserWindow`), `camelCase` for module APIs (`globalShortcut`)
94- Prefer getters/setters over jQuery-style `.text([text])` patterns
95 
96### C++
97 
98- Follows Chromium coding style, enforced by `clang-format` and `clang-tidy`
99- Uses Chromium abstractions (`base::`, `content::`, etc.)
100- Header guards: `#ifndef ELECTRON_SHELL_BROWSER_API_ELECTRON_API_{NAME}_H_`
101- Platform-specific files: `_mac.mm`, `_win.cc`, `_linux.cc`
102 
103### Testing
104 
105- Framework: Mocha + Chai + Sinon
106- Test helpers in `spec/lib/` (e.g., `spec-helpers.ts`, `window-helpers.ts`)
107- Use `defer()` from spec-helpers for cleanup, `closeAllWindows()` for window teardown
108- Tests import from `electron/main` or `electron/renderer`
109 
110### Documentation
111 
112- API docs in `docs/api/` as Markdown, parsed by `@electron/docs-parser` to generate `electron.d.ts`
113- API history tracked via YAML blocks in HTML comments within doc files
114- Docs must pass `npm run lint:docs`
115 
116### Build Configuration
117 
118- `BUILD.gn`: Main GN build config
119- `buildflags/buildflags.gni`: Feature flags (PDF viewer, extensions, spellchecker)
120- `build/args/`: Build argument profiles (`testing.gn`, `release.gn`, `all.gn`)
121- `DEPS`: Dependency versions and checkout paths
122- `chromium_src/`: Chromium source file overrides (compiled instead of originals)
123