electron-live-annotations AGENTS.md

Agent Guide: Implementing electron-live-annotations

You are helping a user add live annotation mode to their Electron product. Do not treat this as a generic package install. The point is to let a human point at the real Electron UI and leave a receipt that future agents can map back to source code and product decisions.

Product Goal

The user should be able to:

1. open the real Electron app;
2. toggle annotation mode;
3. click the exact UI element that needs feedback;
4. write a short note;
5. save a local receipt with element identity and screenshot evidence;
6. hand that receipt to an agent without forcing the agent to reconstruct what was clicked.

The relief sentence is:

"The agent can now see exactly what I meant in the native app."

Discovery Gate Before Editing

Before changing files, inspect the host app and answer these questions in your notes:

• Electron topology: where are the main, preload, and renderer entrypoints?
• Security posture: is contextIsolation enabled, and what preload bridge pattern is already used?
• UI framework: React, Vue, Svelte, Solid, Lit, vanilla, or mixed?
• Build system: electron-vite, Vite, webpack, Forge, Builder, custom, or another runner?
• Selector conventions: does the app already use data-testid, data-test, data-qa, data-cy, or product-specific data-* attributes?
• Review workflow: where should annotation receipts be read later, and who acts on them?
• Storage/privacy posture: is local app.getPath("userData") acceptable, or does the product need a custom path?
• Remote-content posture: can any renderer route load arbitrary web content? If yes, gate or disable capture for those pages before exposing the preload API.
• Product truth boundary: are annotations only local review aids, or should a separate command promote them into issue/review state?

If those answers are unknown, inspect the repo first. Do not paste a generic integration.

Implementation Plan

1. Install the package.

pnpm add electron-live-annotations