Annotation overlay library

@coframe/annotations (packages/coframe-annotations) is a zero-runtime-dependency overlay that lets a human click any element on a live page, leave structured feedback, and have an agent consume — and answer — that feedback. Every interaction emits an AFS v1.1 envelope ({ type, timestamp, sessionId, sequence, payload }) to a webhook, with forensic capture per annotation: selector paths, bounding boxes, nearby text, computed styles, React component stacks and accessibility metadata.

Try it — live playground

The overlay below is the real library running in this frame. Click the toolbar, pick an element, leave a comment, and watch the webhook events stream in:

Quick start

Three ways to install, all ending at the same window.__annotations API:

<!-- 1. Script tag: paste the prebuilt IIFE bundle -->
<script src="/annotations-v1.js"></script>
<script>
  window.__annotations.__init({
    webhookUrl: "https://example.com/webhook",
    sessionId: "session_123",
  });
</script>

// 2. Same-page host (bundler): install into the current document
import {
  ANNOTATIONS_V1_BUNDLE_SOURCE,
  buildAnnotationsInstallSource,
} from "@coframe/annotations";

const script = document.createElement("script");
script.textContent = buildAnnotationsInstallSource({
  webhookUrl: "https://example.com/webhook",
});
document.head.appendChild(script);

// 3. Remote page over CDP (how editor-web injects it)
import { installInCurrentDocument } from "@coframe/annotations";

await installInCurrentDocument(cdpSession, {
  webhookUrl,
  sessionId,
  annotations: pendingAnnotations, // rehydrate the host's durable copy
});

Receiving is one webhook handler — validate envelopes with the helpers in @coframe/annotations/server (or @alphacro/agent-annotations in this repo) and react to annotation.created, thread.message, action.requested, and friends.

What it can do

The features page shows every capability at a glance with animated demos; each one also has a live demo on the capabilities page:

Capability	In one line
Severity + custom composer fields	Always-visible severity (blocking by default, downgradable), host-configurable field set
Re-anchoring resilience	Pins survive SPA remounts/reorders; explicit orphaned state, never a silent decoy
Action slots	Host buttons on toolbar/composer/pin/thread — callbacks or JSON-safe declarative action.requested
Agent round-trip	Thread replies, resolution, focus, and live presence cursors driven by the agent
Parent-owned hydration	Reloads never lose pins — the host re-seeds via __init({ annotations }), dedup by id
Scoped hydration	Seeds carry scope: { url, sessionId, variantId } — variant-A pins never render on variant B
Host-captured screenshots	Opt-in viewport/element capture requests; the host answers via CDP Page.captureScreenshot

How it fits editor-web

ANNOTATIONS_IMPL=coframe selects this library (default in deployed/preview environments); the legacy agentation npm package remains one env var away. Injection, page-watcher rehydration, webhook mapping and the CDP screenshot round-trip are covered in Editor-web integration.

Full API reference: packages/coframe-annotations/README.md.