Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01JkYTqsvYu6AYr9yQ3Q4Nt6
2.9 KiB
2.9 KiB
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
- Manifest V3: one service worker (
background.js,"type": "module"), no background page, no remote code, noeval, no inline<script>oronclick=""in pages (the content security policy blocks them). - The service worker sleeps after ~30 s idle: register every listener at the top level, synchronously; keep state in
chrome.storage(sessionfor the browser session,local,syncfor settings), never in variables; timers =chrome.alarms(notsetInterval). - Content scripts (
content/) are classic scripts (noimport): they ask the worker (chrome.runtime.sendMessage) or readchrome.storagethemselves. Prefix their CSS classes / ids (xh-) so the page is untouched. - Messages:
{type: '...'}objects; a listener that answers after anawaitreturnstrue. - Permissions: the fewest (README "Permissions");
chrome:checkwarns about sensitive and unused ones. PreferactiveTab; host permissions only for the sites needed. - 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. - Tests as you go: one test per feature in
tests/(a sentence as its name), thenchrome: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). - Publishing (the Chrome Web Store) is the user's:
chrome:pack, then the README's checklist; never upload for them.