@coframe-gtm/annotations 1.0.1

package/src/picker.ts

@@ -0,0 +1,203 @@
+/**
+ * Interaction controller — the human side of annotation capture.
+ *
+ * Lifecycle is driven by the `mode` / `feedbackTool` signals:
+ *
+ *   - mode === "feedback" + tool "element" → hover-highlight, click
+ *     pins a single element and opens the composer.
+ *   - tool "text" → native text selection; mouseup with a non-empty
+ *     selection captures the anchor element + selectedText.
+ *   - tool "multi" → click toggles elements into a set; the composer
+ *     "add" affordance commits the set with `isMultiSelect`.
+ *
+ * The library's Shadow DOM host is `pointer-events: none` over empty
+ * space, so page elements receive pointer events normally and
+ * `event.target` is the real page element. Events whose composedPath
+ * includes our host are our own UI — ignored for picking.
+ */
+
+import { captureElement, type CapturedTarget } from "./capture.js";
+import {
+  author,
+  draft,
+  feedbackTool,
+  hoverBox,
+  mode,
+  multiSelection,
+} from "./store.js";
+import { emit } from "./webhook.js";
+
+let host: HTMLElement | null = null;
+let installed = false;
+
+// Throttle local-cursor presence so we emit at most ~8/s (multi-cursor).
+let lastPresenceAt = 0;
+function emitPresence(event: MouseEvent): void {
+  const now = Date.now();
+  if (now - lastPresenceAt < 120) return;
+  lastPresenceAt = now;
+  emit("presence.cursor", {
+    id: author.value.id ?? "human",
+    label: author.value.displayName ?? "You",
+    kind: author.value.kind,
+    x: (event.clientX / window.innerWidth) * 100,
+    y: event.clientY + window.scrollY,
+  });
+}
+
+/** Register the Shadow host so we can exclude our own UI from picks. */
+export function setPickerHost(el: HTMLElement): void {
+  host = el;
+}
+
+function isOwnUi(event: Event): boolean {
+  if (!host) return false;
+  const path = event.composedPath();
+  return path.includes(host);
+}
+
+function pickable(target: EventTarget | null): Element | null {
+  if (!(target instanceof Element)) return null;
+  if (target.tagName === "HTML" || target.tagName === "BODY") return null;
+  return target;
+}
+
+function onMouseMove(event: MouseEvent): void {
+  // Always broadcast the local cursor (presence) — independent of mode —
+  // so the host can mirror it to other actors for multi-cursor.
+  if (!isOwnUi(event)) emitPresence(event);
+  if (mode.value !== "feedback" || draft.value) {
+    hoverBox.value = null;
+    return;
+  }
+  if (isOwnUi(event)) {
+    hoverBox.value = null;
+    return;
+  }
+  if (feedbackTool.value === "text") {
+    hoverBox.value = null;
+    return;
+  }
+  const el = pickable(event.target);
+  if (!el) {
+    hoverBox.value = null;
+    return;
+  }
+  const rect = el.getBoundingClientRect();
+  hoverBox.value = {
+    top: rect.top,
+    left: rect.left,
+    width: rect.width,
+    height: rect.height,
+  };
+}
+
+function onClick(event: MouseEvent): void {
+  if (mode.value !== "feedback") return;
+  if (isOwnUi(event)) return;
+  if (feedbackTool.value === "text") return; // handled on mouseup
+  if (draft.value) return; // composer open — ignore page clicks
+
+  const el = pickable(event.target);
+  if (!el) return;
+
+  // Suppress the page's own click handling while annotating.
+  event.preventDefault();
+  event.stopPropagation();
+
+  if (feedbackTool.value === "multi") {
+    toggleMulti(el);
+    return;
+  }
+
+  // Single element → open composer immediately.
+  openComposer(captureElement(el));
+}
+
+function onMouseUp(): void {
+  if (mode.value !== "feedback" || feedbackTool.value !== "text") return;
+  if (draft.value) return;
+  const selection = window.getSelection();
+  const text = selection?.toString().trim();
+  if (!text || !selection || selection.rangeCount === 0) return;
+  const range = selection.getRangeAt(0);
+  const anchor =
+    range.commonAncestorContainer.nodeType === 1
+      ? (range.commonAncestorContainer as Element)
+      : range.commonAncestorContainer.parentElement;
+  if (!anchor) return;
+  const captured = captureElement(anchor);
+  openComposer({ ...captured, selectedText: text });
+}
+
+function onKeyDown(event: KeyboardEvent): void {
+  if (event.key !== "Escape") return;
+  if (draft.value) {
+    draft.value = null;
+    return;
+  }
+  if (multiSelection.value.length) {
+    multiSelection.value = [];
+    hoverBox.value = null;
+    return;
+  }
+  if (mode.value === "feedback") {
+    mode.value = "view";
+    hoverBox.value = null;
+  }
+}
+
+function toggleMulti(el: Element): void {
+  const current = multiSelection.value;
+  multiSelection.value = current.includes(el)
+    ? current.filter((e) => e !== el)
+    : [...current, el];
+}
+
+/** Commit the current multi-element set into a single draft. */
+export function commitMultiSelection(): void {
+  const els = multiSelection.value;
+  if (!els.length) return;
+  const primary = captureElement(els[0]!);
+  const boxes = els.map((el) => {
+    const rect = el.getBoundingClientRect();
+    return {
+      x: rect.left + window.scrollX,
+      y: rect.top + window.scrollY,
+      width: rect.width,
+      height: rect.height,
+    };
+  });
+  const labels = els.map((el) => el.tagName.toLowerCase()).join(", ");
+  openComposer({
+    ...primary,
+    isMultiSelect: true,
+    elementBoundingBoxes: boxes,
+    nearbyElements: `${els.length} elements: ${labels}`,
+  });
+}
+
+function openComposer(target: CapturedTarget): void {
+  multiSelection.value = [];
+  hoverBox.value = null;
+  draft.value = target;
+}
+
+/** Attach document listeners once. Idempotent. */
+export function installPicker(): void {
+  if (installed) return;
+  installed = true;
+  document.addEventListener("mousemove", onMouseMove, true);
+  document.addEventListener("click", onClick, true);
+  document.addEventListener("mouseup", onMouseUp, true);
+  document.addEventListener("keydown", onKeyDown, true);
+}
+
+export function uninstallPicker(): void {
+  if (!installed) return;
+  installed = false;
+  document.removeEventListener("mousemove", onMouseMove, true);
+  document.removeEventListener("click", onClick, true);
+  document.removeEventListener("mouseup", onMouseUp, true);
+  document.removeEventListener("keydown", onKeyDown, true);
+}

package/src/server/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Portable backend surface — the transport-agnostic ingest core.
+ *
+ * Wrap these in a platform adapter:
+ *   - Cloudflare Worker route, or
+ *   - AWS Lambda / Function URL.
+ *
+ * Nothing here imports a platform SDK or any vendor-internal package, so the
+ * folder copies cleanly into another repo alongside `../types.ts`.
+ */
+
+export {
+  annotationQueueReducer,
+  applyAnnotationEvent,
+  corsHeaders,
+  emptyAnnotationsState,
+  parseEnvelope,
+} from "./ingest.js";
+
+export type { AnnotationsState } from "./ingest.js";
+
+export {
+  InMemoryRunStore,
+  makeRunRecord,
+  recordAnnotationEventRun,
+} from "./run-store.js";
+
+export type { RunStore, RunRecord, RunKind } from "./run-store.js";

package/src/server/ingest.test.ts

@@ -0,0 +1,144 @@
+/**
+ * Ingest core tests. Pure logic, no DOM/platform — runs in the default
+ * node env. This core is the portable "backend" shared by the the host app
+ * Cloudflare route and a future GTM-repo AWS Lambda.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import {
+  annotationQueueReducer,
+  applyAnnotationEvent,
+  corsHeaders,
+  emptyAnnotationsState,
+  parseEnvelope,
+  type AnnotationsState,
+} from "./ingest.js";
+import type { AgentationEvent, Annotation } from "../types.js";
+
+function ann(id: string, over: Partial<Annotation> = {}): Annotation {
+  return {
+    id,
+    comment: "c",
+    elementPath: "button.cta",
+    element: "button",
+    x: 10,
+    y: 20,
+    timestamp: 0,
+    status: "pending",
+    thread: [],
+    ...over,
+  };
+}
+
+function envelope(
+  type: AgentationEvent["type"],
+  payload: unknown,
+  seq = 1,
+): AgentationEvent {
+  return {
+    type,
+    timestamp: "2026-05-29T00:00:00.000Z",
+    sessionId: "cf_sid",
+    sequence: seq,
+    payload,
+  };
+}
+
+describe("parseEnvelope", () => {
+  it("accepts a well-formed envelope", () => {
+    const e = parseEnvelope({
+      type: "annotation.created",
+      timestamp: "2026-05-29T00:00:00.000Z",
+      sessionId: "s",
+      sequence: 1,
+      payload: ann("a1"),
+    });
+    expect(e.type).toBe("annotation.created");
+  });
+
+  it.each([
+    ["not an object", 42],
+    ["bad type", { type: "nope", timestamp: "t", sessionId: "s", sequence: 1, payload: {} }],
+    ["missing payload", { type: "annotation.created", timestamp: "t", sessionId: "s", sequence: 1 }],
+    ["bad sequence", { type: "session.updated", timestamp: "t", sessionId: "s", sequence: "x", payload: {} }],
+  ])("rejects %s", (_label, body) => {
+    expect(() => parseEnvelope(body)).toThrow();
+  });
+});
+
+describe("annotationQueueReducer", () => {
+  it("created pushes; duplicate id replaces", () => {
+    let s = emptyAnnotationsState();
+    s = annotationQueueReducer(s, envelope("annotation.created", ann("a1", { comment: "first" })));
+    s = annotationQueueReducer(s, envelope("annotation.created", ann("a1", { comment: "second" }), 2));
+    expect(s.items).toHaveLength(1);
+    expect(s.items[0]!.comment).toBe("second");
+    expect(s.lastSequence).toBe(2);
+  });
+
+  it("updated patches by id, no-op when absent", () => {
+    let s: AnnotationsState = { items: [ann("a1")] };
+    s = annotationQueueReducer(s, envelope("annotation.updated", { id: "a1", patch: { status: "resolved" } }));
+    expect(s.items[0]!.status).toBe("resolved");
+    const before = s;
+    s = annotationQueueReducer(s, envelope("annotation.updated", { id: "ghost", patch: { status: "dismissed" } }));
+    expect(s.items).toEqual(before.items);
+  });
+
+  it("deleted removes by id", () => {
+    let s: AnnotationsState = { items: [ann("a1"), ann("a2")] };
+    s = annotationQueueReducer(s, envelope("annotation.deleted", { id: "a1" }));
+    expect(s.items.map((a) => a.id)).toEqual(["a2"]);
+  });
+
+  it("thread.message appends to the right annotation", () => {
+    let s: AnnotationsState = { items: [ann("a1")] };
+    s = annotationQueueReducer(
+      s,
+      envelope("thread.message", {
+        annotationId: "a1",
+        message: { id: "m1", role: "agent", content: "hi", timestamp: 1 },
+      }),
+    );
+    expect(s.items[0]!.thread).toHaveLength(1);
+    expect(s.items[0]!.thread![0]!.content).toBe("hi");
+  });
+
+  it("session.* only bumps metadata", () => {
+    const s = annotationQueueReducer(
+      { items: [ann("a1")] },
+      envelope("session.updated", { mode: "feedback" }, 7),
+    );
+    expect(s.items).toHaveLength(1);
+    expect(s.lastSequence).toBe(7);
+  });
+});
+
+describe("applyAnnotationEvent", () => {
+  it("reads, reduces, and writes back via the io adapter", async () => {
+    let state = emptyAnnotationsState();
+    const next = await applyAnnotationEvent(
+      {
+        getState: () => state,
+        setState: (n) => {
+          state = n;
+        },
+      },
+      envelope("annotation.created", ann("a1")),
+    );
+    expect(next.items).toHaveLength(1);
+    expect(state.items).toHaveLength(1);
+  });
+});
+
+describe("corsHeaders", () => {
+  it("reflects the origin and allows POST/OPTIONS", () => {
+    const h = corsHeaders("https://stripe.com");
+    expect(h["access-control-allow-origin"]).toBe("https://stripe.com");
+    expect(h["access-control-allow-methods"]).toContain("POST");
+  });
+  it("falls back to * when origin is null", () => {
+    expect(corsHeaders(null)["access-control-allow-origin"]).toBe("*");
+  });
+});

package/src/server/ingest.ts

@@ -0,0 +1,175 @@
+/**
+ * Transport-agnostic annotation ingest core (the "backend" layer).
+ *
+ * Zero platform dependencies — no Cloudflare, no AWS, no vendor-internal packages.
+ * Pure functions over the AFS event envelope so the SAME logic wraps a
+ * Cloudflare Worker route and an AWS Lambda (another
+ * engine repo). Host adapters supply `getState` / `setState`; this core
+ * owns parsing, the queue reducer, and CORS.
+ *
+ * Keep this file portable: it may be copied verbatim into another repo
+ * alongside `../types.ts`.
+ */
+
+import type {
+  AgentationEvent,
+  AgentationEventType,
+  Annotation,
+  ThreadMessage,
+} from "../types.js";
+
+/** The host-held annotation queue. Broadcast to viewers + fed to the agent. */
+export interface AnnotationsState {
+  readonly items: ReadonlyArray<Annotation>;
+  readonly lastEventAt?: number;
+  readonly lastSequence?: number;
+}
+
+export function emptyAnnotationsState(): AnnotationsState {
+  return { items: [] };
+}
+
+const EVENT_TYPES: ReadonlySet<string> = new Set<AgentationEventType>([
+  "annotation.created",
+  "annotation.updated",
+  "annotation.deleted",
+  "session.created",
+  "session.updated",
+  "session.closed",
+  "thread.message",
+  "action.requested",
+  "presence.cursor",
+]);
+
+/**
+ * Validate + narrow an untrusted request body into an AFS event
+ * envelope. Throws `Error` with a readable message on malformed input
+ * so the adapter can return 400.
+ */
+export function parseEnvelope(body: unknown): AgentationEvent {
+  if (typeof body !== "object" || body === null) {
+    throw new Error("envelope must be a JSON object");
+  }
+  const e = body as Record<string, unknown>;
+  if (typeof e.type !== "string" || !EVENT_TYPES.has(e.type)) {
+    throw new Error(`unknown or missing event type: ${String(e.type)}`);
+  }
+  if (typeof e.timestamp !== "string") {
+    throw new Error("envelope.timestamp must be an ISO string");
+  }
+  if (typeof e.sessionId !== "string") {
+    throw new Error("envelope.sessionId must be a string");
+  }
+  if (typeof e.sequence !== "number") {
+    throw new Error("envelope.sequence must be a number");
+  }
+  if (!("payload" in e)) {
+    throw new Error("envelope.payload is required");
+  }
+  return {
+    type: e.type as AgentationEventType,
+    timestamp: e.timestamp,
+    sessionId: e.sessionId,
+    sequence: e.sequence,
+    payload: e.payload,
+  };
+}
+
+/**
+ * Apply one AFS event to the queue. Pure — returns a new state, never
+ * mutates. Out-of-order / duplicate events are tolerated: `created`
+ * replaces by id, `updated`/`deleted`/`thread.message` no-op when the
+ * target is absent.
+ */
+export function annotationQueueReducer(
+  state: AnnotationsState,
+  envelope: AgentationEvent,
+): AnnotationsState {
+  const base: AnnotationsState = {
+    ...state,
+    lastEventAt: Date.parse(envelope.timestamp) || state.lastEventAt,
+    lastSequence: envelope.sequence,
+  };
+
+  switch (envelope.type) {
+    case "annotation.created": {
+      const ann = envelope.payload as Annotation;
+      if (!ann || typeof ann.id !== "string") return base;
+      const without = base.items.filter((a) => a.id !== ann.id);
+      return { ...base, items: [...without, ann] };
+    }
+
+    case "annotation.updated": {
+      const { id, patch } = (envelope.payload ?? {}) as {
+        id?: string;
+        patch?: Partial<Annotation>;
+      };
+      if (!id || !patch) return base;
+      return {
+        ...base,
+        items: base.items.map((a) => (a.id === id ? { ...a, ...patch } : a)),
+      };
+    }
+
+    case "annotation.deleted": {
+      const { id } = (envelope.payload ?? {}) as { id?: string };
+      if (!id) return base;
+      return { ...base, items: base.items.filter((a) => a.id !== id) };
+    }
+
+    case "thread.message": {
+      const { annotationId, message } = (envelope.payload ?? {}) as {
+        annotationId?: string;
+        message?: ThreadMessage;
+      };
+      if (!annotationId || !message) return base;
+      return {
+        ...base,
+        items: base.items.map((a) =>
+          a.id === annotationId
+            ? { ...a, thread: [...(a.thread ?? []), message] }
+            : a,
+        ),
+      };
+    }
+
+    // session.* and action.requested carry no queue mutation; the
+    // metadata bump above (lastEventAt/lastSequence) is the whole effect.
+    default:
+      return base;
+  }
+}
+
+/**
+ * CORS headers for the webhook response. The overlay runs on the target
+ * page origin and POSTs cross-origin to the host, so preflight + ACAO
+ * are mandatory. Reflects the request origin when present (credentials
+ * are not used, so `*` is also safe; reflecting is friendlier to future
+ * cookie-bearing setups).
+ */
+export function corsHeaders(origin: string | null): Record<string, string> {
+  return {
+    "access-control-allow-origin": origin ?? "*",
+    "access-control-allow-methods": "POST, OPTIONS",
+    "access-control-allow-headers": "content-type",
+    "access-control-max-age": "86400",
+  };
+}
+
+/**
+ * Orchestration helper an adapter can call once it has parsed the
+ * envelope: read current state, reduce, write back. Adapters provide
+ * the platform-specific state access.
+ */
+export async function applyAnnotationEvent(
+  io: {
+    getState: () => AnnotationsState | Promise<AnnotationsState>;
+    setState: (next: AnnotationsState) => void | Promise<void>;
+  },
+  envelope: AgentationEvent,
+): Promise<AnnotationsState> {
+  const current = await io.getState();
+  const next = annotationQueueReducer(current, envelope);
+  await io.setState(next);
+  return next;
+}

package/src/server/run-store.test.ts

@@ -0,0 +1,51 @@
+/**
+ * Run-store tests. Pure/in-memory — validates the audit-trail contract
+ * the AWS (DynamoDB + S3) adapter must satisfy.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import {
+  InMemoryRunStore,
+  makeRunRecord,
+  recordAnnotationEventRun,
+} from "./run-store.js";
+
+describe("InMemoryRunStore", () => {
+  it("puts and lists runs newest-first, filtered by kind/session", async () => {
+    const s = new InMemoryRunStore();
+    await s.putRun(makeRunRecord({ id: "1", kind: "test-run", at: "2026-05-29T00:00:01Z", status: "pass" }));
+    await s.putRun(makeRunRecord({ id: "2", kind: "annotation-event", at: "2026-05-29T00:00:02Z", sessionId: "cf" }));
+    await s.putRun(makeRunRecord({ id: "3", kind: "test-run", at: "2026-05-29T00:00:03Z", status: "fail" }));
+
+    const tests = await s.listRuns({ kind: "test-run" });
+    expect(tests.map((r) => r.id)).toEqual(["3", "1"]); // newest first
+    const byList = await s.listRuns({ sessionId: "cf" });
+    expect(byList).toHaveLength(1);
+    expect((await s.listRuns({ limit: 1 }))).toHaveLength(1);
+  });
+
+  it("is idempotent on id", async () => {
+    const s = new InMemoryRunStore();
+    await s.putRun(makeRunRecord({ id: "x", kind: "test-run", at: "t", status: "pass" }));
+    await s.putRun(makeRunRecord({ id: "x", kind: "test-run", at: "t", status: "fail" }));
+    const all = await s.listRuns();
+    expect(all).toHaveLength(1);
+    expect(all[0]!.status).toBe("fail");
+  });
+
+  it("stores artifacts and links them from records", async () => {
+    const s = new InMemoryRunStore();
+    await recordAnnotationEventRun(s, {
+      type: "annotation.created",
+      sessionId: "cf",
+      sequence: 7,
+      timestamp: "2026-05-29T00:00:00Z",
+      payload: { id: "ann_1" },
+    });
+    const [rec] = await s.listRuns({ kind: "annotation-event" });
+    expect(rec!.id).toBe("cf:7");
+    expect(rec!.artifactKey).toBe("annotations/cf/7.json");
+    expect(s.readArtifact(rec!.artifactKey!)).toContain("ann_1");
+  });
+});