JS API — window.__annotations #
The vendor-neutral global bridge. Available the moment the library is injected.
| Member | Returns | Description |
|---|---|---|
version | string | Library version. |
schema | "afs-1.1" | Schema identifier. |
addAnnotation(input) | string | Create an annotation; returns its id. |
replyToAnnotation(id, msg) | string | null | Append a thread message ({ role, content }). |
updateAnnotation(id, patch) | boolean | Patch any annotation fields. |
acknowledgeAnnotation(id) | boolean | Mark acknowledged. |
resolveAnnotation(id, by?) | boolean | Mark resolved (by = human / agent). |
dismissAnnotation(id) | boolean | Mark dismissed. |
removeAnnotation(id) | boolean | Delete one annotation. |
clearAnnotations() | number | Erase the board; returns count removed. |
focusAnnotation(id) | boolean | Open that annotation's thread panel. |
closeThread() | void | Close any open thread panel. |
setCursor(cursor) | void | Upsert one actor's presence cursor by id. |
setCursors(list) | void | Replace all presence cursors. |
removeCursor(id) | boolean | Remove one actor's cursor. |
clearCursors() | void | Remove all cursors. |
setMode(mode) | void | Set view / feedback / layout. |
getMode() | Mode | Read the current mode (for a headless parent frame). |
subscribeMode(fn) | () => void | Subscribe to mode changes; returns an unsubscribe. |
setTheme(theme) | void | dark / light / auto. |
getAnnotations() | Annotation[] | Snapshot of the current board. |
Session init
initSession({ webhookUrl?: string; sessionId?: string }): void;Webhook events #
Each state change emits one envelope to webhookUrl. sequence is monotonic
per session, so the host can detect a gap and request replay.
interface AgentationEvent<P> {
type: AgentationEventType;
timestamp: string; // ISO 8601
sessionId: string;
sequence: number; // monotonic per session
payload: P;
}| Event | Fires when |
|---|---|
session.created / session.updated / session.closed | Session lifecycle. |
annotation.created / annotation.updated / annotation.deleted | An annotation changes. |
thread.message | A reply is appended to a thread. |
action.requested | The UI requests a host action. |
presence.cursor | An actor's cursor moves (throttled). |
Versioning #
SemVer on the package; the schema carries its own version so consumers can branch on it.
| Value | |
|---|---|
| Package | @coframe-gtm/annotations |
| Version | 1.1.0 |
| Schema | afs-1.1 |
| Entry | /v1, /v1/inject, /v1/server |
1.2.0 — overlay polish: liquid-glass popups (composer / thread / preview),
multi-element markers now outline every selected element and stay pinned through scroll,
one popup open at a time, and the comment box auto-focuses on open.
The
/v1 path is the stability contract. A breaking schema change ships as
/v2 alongside /v1, so injected pages never break under your feet.