annotate-loop

Dev-only visual annotation loop as a standalone reusable package: point at any localhost preview page, click an element, type the change — the bundle lands as a durable annotation job.

• Pi extension opens a dedicated Chrome preview with /annotate <localhost-url> and delivers visual feedback into the same conversation. Includes temporary property previews, batches, live target inspection, and a browser review loop.
• Bookmarklet arms an element picker on any localhost page on any port — no dev-server dependency.
• Picker captures redundant location evidence: page URL, component hint, CSS path, XPath, element summary, viewport, plus a screenshot and a typed instruction (fix/copy/layout/style/other).
• Receiver (annotate-loop-receiver) listens loopback-only (127.0.0.1:8787 by default) and files jobs to an intake dir. Clipboard-paste fallback keeps bundles durable when the receiver is down.
• Reverify (annotate-loop/reverify) lets the worker re-check the spot against the live page before cutting code — never trust a stale path blind.
• Dev-only gating: visible badge behind import.meta.env.DEV, and annotate-loop-guard fails CI if any dev marker reaches the publish dir.

Install

npm install annotate-loop

Pilot status: 0.2.x — API may shift. Framework adapters start with Astro (annotate-loop/adapters/astro/AnnotateBadge.astro).

Pi-native quick start

From this checkout, run npm ci, then start Pi in the project you want to edit:

pi -e /absolute/path/to/annotate-loop/extensions/annotate.ts \
   --skill /absolute/path/to/annotate-loop/skills/annotate

Start that project's dev server, select a vision-capable model, then enter /annotate http://localhost:4321/ in Pi. Click an element, describe the change, and Send. Pi receives the request and screenshot in this conversation; Looks good / Revise close the review loop. No receiver or consumer code changes needed. /annotate stop closes the owned browser, not submitted work.

Requires Chrome and Node ^20.19.0 || >=22.12.0. Use trusted local previews only; screenshots/page evidence go to Pi history and your model provider. See Pi setup, lifecycle, and limitations.

Bookmarklet quick start

1. Start your site's dev server (any localhost port).
2. Start the receiver (separate terminal):

   npx annotate-loop-receiver
   # listens on http://127.0.0.1:8787 → data/annotations/<id>.json
   # options: --port=8787 --out-dir=data/annotations
   

3. Build the bookmarklet once, add it as a bookmark, click it on any localhost tab:

   npx annotate-loop-bookmarklet --out=dist/bookmarklet.txt
   

   Or mount the badge on pilot pages (Astro):

   import AnnotateBadge from 'annotate-loop/adapters/astro/AnnotateBadge.astro';
   <AnnotateBadge pilot="home" />
   

4. Hover to highlight, click to freeze, pick an instruction type, describe the change, hit Send.
5. Triage intake jobs, re-verify each spot on the live page (reverification guide), implement, then archive/delete the job file.

Full workflow: docs/usage.md. Astro wiring: examples/astro-usage.md.

Dev-only gating (do not break)

• The badge/picker render only in dev (import.meta.env.DEV); production prerender emits nothing. Never put picker/bookmarklet copies under the site's public/ dir (it ships verbatim to dist/).
• annotate-loop-guard scans the static publish dir for picker/badge markers and fails on any hit. Run it in CI right after the build:

  npx annotate-loop-guard --dir=dist/client --public-dir=public
  

Job lifecycle

Filed jobs are intake, not instructions: triage, re-verify each spot on the live page, implement, then archive/delete the job file. Do not commit screenshots or jobs to long-lived branches — extract the change and drop the bundle.

Development

npm ci
npm test
npm run test:browser  # real Chrome via chrome-devtools-axi; no model billed

The core picker/receiver remains dependency-free. The Pi browser bridge has runtime Chrome-tooling dependencies; test dependencies include jsdom and tsx.

License

MIT — see LICENSE.