Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01JkYTqsvYu6AYr9yQ3Q4Nt6
36 lines
2.9 KiB
Markdown
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.
|