winzik/skeleton-chrome/AGENTS.md

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

  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.