Arciform

Arciform is a browser extension for giving visual feedback to a coding agent. You open the page you want changed, click an element or drag a rectangle over the part that looks wrong, and write what should change. Arciform collects the requests, attaches evidence from the rendered page (selectors, visible text, computed styles, a DOM excerpt, a screenshot crop), and exports everything as a prompt that an agent with access to the repository can act on. You point at the problem instead of describing where it is.

Status: proof of concept, version 0.5.0. Chromium only, Manifest V3, plain JavaScript, no build step. Expect rough edges and breaking changes.

More screenshots and a walkthrough are on the landing page. The product concept is in PRODUCT.md.

Install

Install it from the Chrome Web Store.

To run it from source, load the folder unpacked (Chrome refuses .crx files that come from outside the Web Store):

1. Get the source: clone this repository or download it as a zip and unpack it.
2. Open chrome://extensions and turn on Developer mode.
3. Click Load unpacked and pick the extension/ folder.

Try it

1. Run npm run demo and open http://localhost:4173. The demo page has seven deliberate design flaws, listed in a comment at the top of demo/index.html.
2. Click the Arciform toolbar icon (or press Alt+Shift+A).
3. Click an element or drag a rectangle, write what should change, save. Repeat.
4. Click Export, then Copy prompt, and paste it into a coding agent. If you ticked Screenshot on a request, copy its picture from the same dialog and paste it after the prompt.

It works on any http(s) page. For file:// pages, enable Allow access to file URLs on the extension's details page. Browser pages such as chrome:// and the Web Store cannot be annotated.

What is implemented

Area	Behavior
Selection	Element click with parent/child stepping. Rectangle drag that proposes two scopes: the elements inside it, or the container around it.
Scope	"This instance only" versus "All N matching" is an explicit choice, never inferred.
Comments	Five presets that fill in editable text, a Preserve field, and a reference picker for "Match another element". The editor opens next to the target and can be dragged by its head; it then stays where it was put until review mode ends.
Review	Numbered pins, a collapsible request list, edit, delete, mark resolved.
Evidence	Taken from the DOM and stylesheets: selector, DOM path, position among siblings, parent layout, computed styles, the CSS rules that apply and where they come from, and a short HTML excerpt.
Screenshots	Optional, one checkbox per request, off by default. The export dialog shows each crop with a Copy image button.
Persistence	Requests are stored per page in chrome.storage.local and survive reloads.
After a code change	Targets reattach only on a confident match. Otherwise the card says so and offers manual reattach.
Export	A Markdown prompt that separates user intent, observed evidence, and what is left to the agent. Copy it to the clipboard; there are no files to download.
Interact mode	Lets the page respond normally so you can open a menu or reach a state before marking it.
Element state	Leaving Interact mode freezes whatever is hovered, focused or active: the element keeps its styles, and menus or tooltips opened by the page stay open. The editor's State row (Default, Hover, Focus, Active) is preset from the freeze. Picking another state shows it on the page while the request is edited, applied from the page's own :hover, :focus and :active rules. Press I to release. Form controls and widgets get an Element row with the flags that apply to the target (checked, indeterminate, disabled, readonly, required, open, selected, and any aria-expanded, aria-selected, aria-pressed, aria-checked, aria-disabled, aria-current, aria-invalid the element carries); toggling one sets it on the page. The prompt lists these flags, plus placeholder-shown and valid/invalid, as the element's state on the page.

Shortcuts: E element, R region, I interact, Ctrl/⌘+Enter save, Esc cancel.

Known limitations

• Chromium only. Other browsers are not supported.
• Top frame only. An <iframe> is selectable as one element, and nothing inside it can be marked.
• CSS rules in stylesheets served from another origin cannot be read, so they are missing from the evidence.
• A frozen state keeps computed styles, not pseudo-elements: a ::before or ::after that changes on hover reverts. Pages that close a menu on a timer or by tracking the pointer still close it. A state that does not end when the overlay appears, such as :active while the mouse button is held, cannot be captured and is released. A state picked by hand applies the page's stylesheet rules to the element, so JavaScript-driven behaviour (a menu opened on mouseenter) does not follow, and rules from cross-origin stylesheets cannot be applied.
• Screenshots capture only the visible viewport. A marked area that extends past it is cropped to what was on screen, and a target that is fully off screen gets no crop.
• No before/after comparison. After the agent changes the code you can reattach and resolve requests, but the extension does not compare the old and new rendering.
• Review mode ends when the tab navigates to a different site. Click the icon again to resume; saved requests are still there.
• Screenshot crops are capped at 960 × 720 pixels and about 20 kB. Fine detail in large areas is lost.
• Requests are keyed by origin and path. Two URLs that differ only in their query string share one request list.

Privacy

Arciform makes no network requests and has no server, account, analytics, or telemetry. Requests and screenshot crops are stored on your machine in chrome.storage.local. Data leaves the extension only when you click Copy prompt or copy a screenshot in the Export dialog. The export contains the page URL, page text, DOM excerpts, and CSS rules, so read it before you share it.

The extension asks for activeTab, scripting, and storage. It has no access to any page until you click its icon there, and that access covers only that tab. PRIVACY.md lists exactly what is stored, and SECURITY.md explains each permission and how to report a vulnerability.

Decisions this prototype makes

PRODUCT.md left these open. Each is a default, easy to change.

• First prototype: region and comment flow, without live style previews.
• Browser: Chromium only. Top frame only; an <iframe> is selectable as one element.
• Handoff: copied text. Screenshots are copied as images and pasted separately.
• Screenshots: opt-in per request, captured at save time with the overlay hidden.
• Review after edit: reattach, resolve, and manual reattach are in. Before/after comparison is not.

Layout

extension/
  manifest.json
  background.js        active tabs, screenshot capture
  content/
    core.js            presets, DOM helper, icons
    dom.js             selectors, evidence, region scope, reattachment
    capture.js         screenshot crop
    exporter.js        prompt
    styles.js          overlay CSS (shadow DOM)
    app.js             selection, editor, pins, tray, export dialog
demo/index.html        practice page with deliberate flaws
scripts/smoke.mjs      end-to-end test in headless Chromium
scripts/package.mjs    builds a zip of extension/ in dist/
docs/                  design notes, landing page

The files in docs/*.md and PRODUCT.md are design notes written before and during the prototype. Where they disagree with this README, the README describes what the code does.

Test

npm install
npm run check
npm run smoke

check runs node --check on every script. smoke loads the extension in headless Chromium, marks the demo page, exports, reloads, and removes a target. Screenshots and the exported prompt land in scripts/out/. Set CHROMIUM=/path/to/chromium to choose the browser. See CONTRIBUTING.md for how the browser is located.

npm run package writes dist/arciform-<version>.zip with manifest.json at the zip root. It needs python3.

Contributing

See CONTRIBUTING.md. Changes are listed in CHANGELOG.md.

License

MIT. See LICENSE.