winzik/skeleton-chrome/AGENTS.md

36 lines
2.9 KiB
Markdown

# AGENTS.md — {{NAME}} (a Chrome extension)
A Chrome extension, Manifest V3, plain JavaScript (no build step, no bundler, no npm package at run time). Made from
JumPHP's `skeleton-chrome`. The tools run in Docker through JumPHP's `bin/jumphp` (or the JumPHP IDE's Run menu):
never install Node or Chrome on the host.
## Commands
| Command | |
|---|---|
| `bin/jumphp chrome:check <folder> [--json]` | manifest.json: required keys, MV3 rules, every referenced file, icon sizes, permissions (unknown, sensitive, unused, missing), translations in every locale. `var/chrome-check.json`. Exit 1 on errors |
| `bin/jumphp chrome:run <folder> [url]` | headless Chrome with the extension: prints its id and the console errors; `var/screenshots/page.png` (example.com = `tests/fixtures/page.html`), `options.png`, `popup.png`: **open them and look** |
| `bin/jumphp chrome:test <folder>` | `tests/*.test.cjs` (node:test + Puppeteer, `tests/helpers.cjs` loads the extension) |
| `bin/jumphp chrome:pack <folder>` | `dist/<name>-<version>.zip` (check first; tests, scripts, var, *.md left out; `.packignore` for more) |
| `bin/jumphp chrome:bump <folder> [patch\|minor\|major\|x.y.z]` | the version |
| `bin/jumphp chrome:icons <folder> [#bg] [#highlight]` | the icons drawn again |
| `bin/jumphp chrome:lint <folder>` | ESLint (`eslint.config.mjs`) |
## Rules
1. **Manifest V3**: one service worker (`background.js`, `"type": "module"`), no background page, no remote code, no
`eval`, no inline `<script>` or `onclick=""` in pages (the content security policy blocks them).
2. **The service worker sleeps** after ~30 s idle: register every listener at the top level, synchronously; keep state in
`chrome.storage` (`session` for the browser session, `local`, `sync` for settings), never in variables; timers =
`chrome.alarms` (not `setInterval`).
3. **Content scripts** (`content/`) are classic scripts (no `import`): they ask the worker (`chrome.runtime.sendMessage`)
or read `chrome.storage` themselves. Prefix their CSS classes / ids (`xh-`) so the page is untouched.
4. **Messages**: `{type: '...'}` objects; a listener that answers after an `await` returns `true`.
5. **Permissions**: the fewest (README "Permissions"); `chrome:check` warns about sensitive and unused ones. Prefer
`activeTab`; host permissions only for the sites needed.
6. **Texts**: every text the user sees is in `_locales/<lang>/messages.json` (en and fr at least, the same keys);
`data-i18n="key"` / `data-i18n-attr="placeholder:key"` in pages (`lib/i18n.js`), `chrome.i18n.getMessage()` in code.
7. **Tests as you go**: one test per feature in `tests/` (a sentence as its name), then `chrome:test`, `chrome:run`, look
at the screenshots. Before saying it is done: `chrome:check` (no error), `chrome:test`, `chrome:run` (no console
error, screenshots right).
8. **Publishing** (the Chrome Web Store) is the user's: `chrome:pack`, then the README's checklist; never upload for them.