@coframe-gtm/annotations 1.0.1

package/README.md

@@ -0,0 +1,48 @@
+# @coframe-gtm/annotations
+
+Clean-room **AFS v1.1** annotation overlay + transport-agnostic ingest core.
+Injects into any web page; humans and agents annotate the same page
+bidirectionally. No platform deps — `preact` + `@preact/signals` only — so it
+ports anywhere.
+
+## Layout
+
+- `src/` — **frontend**: closed Shadow DOM overlay (element / text / multi
+  picker, pins, composer, discussion threads), forensic capture, 4-tier
+  Markdown output, and the `window.__annotations` JS bridge.
+- `src/server/` — **backend (portable)**: `parseEnvelope`, `annotationQueueReducer`,
+  `corsHeaders`, and a `RunStore` port. Wrap in a Cloudflare Worker route or an
+  AWS Lambda — same logic, no platform import.
+- `src/inject/` — CDP install helpers + the esbuild bundler that emits the IIFE
+  and regenerates `bundle-source.generated.ts`.
+
+## Use
+
+```bash
+pnpm install
+pnpm test        # vitest (node + jsdom)
+pnpm typecheck
+pnpm build       # → dist/annotations-v1.iife.js + regenerated bundle-source
+```
+
+Inject the built IIFE into a page (via CDP `Page.addScriptToEvaluateOnNewDocument`
+or a `<script>`), then control it:
+
+```js
+window.__annotations.__init({
+  webhookUrl: "https://your-host/annotations/webhook",
+  sessionId: "sess_123",
+  author: { kind: "human", displayName: "You" },
+});
+window.__annotations.addAnnotation({ comment: "tighten this", elementPath: "button.cta", element: "button", x: 50, y: 100 });
+```
+
+The overlay POSTs AFS event envelopes (`{type, timestamp, sessionId, sequence, payload}`)
+to `webhookUrl`. Your backend feeds them through `src/server` into whatever
+store/queue you want.
+
+## Two layers, one package
+
+- **Engine** (this package) — the reusable overlay + portable ingest core.
+- **Backend** — wire `src/server` into a Cloudflare Worker or AWS Lambda over
+  any S3 / DynamoDB / queue store you own. Nothing here pins you to a platform.

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@coframe-gtm/annotations",
+  "version": "1.0.1",
+  "type": "module",
+  "description": "Clean-room AFS v1.1 annotation overlay (frontend) + transport-agnostic ingest core (backend). Injects into any page; humans + agents annotate bidirectionally.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Coframe/GTM-growth-engine.git",
+    "directory": "coframe-agentation/frontend"
+  },
+  "main": "./src/index.ts",
+  "files": ["src", "README.md"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./server": "./src/server/index.ts",
+    "./inject": "./src/inject/install.ts",
+    "./v1": "./src/index.ts",
+    "./v1/server": "./src/server/index.ts",
+    "./v1/inject": "./src/inject/install.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "build": "node --experimental-strip-types src/inject/build.ts"
+  },
+  "dependencies": {
+    "preact": "^10.24.0",
+    "@preact/signals": "^2.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "esbuild": "^0.28.0",
+    "jsdom": "^25.0.0",
+    "typescript": "^5.9.2",
+    "vitest": "^4.1.5"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": ["esbuild"]
+  }
+}

package/src/README.md

@@ -0,0 +1,79 @@
+# `@coframe-gtm/annotations/v1` — P1 scaffold
+
+The clean-room injection bundle described in
+[`../../PLAN.md`](../../PLAN.md). P1 (phase one) of that plan ships
+this scaffold:
+
+- Closed Shadow DOM mount (`shadow.ts`)
+- Preact-rendered debug shell (`ui/App.ts`)
+- `window.__annotations` API surface (`api.ts`)
+- Outbound webhook emitter (`webhook.ts`)
+- CDP install helpers (`inject/install.ts`)
+- esbuild build pipeline (`inject/build.ts`)
+
+What it does today: inject the bundle into any page, see a small
+floating "Annotations · 0 · view mode" badge in the bottom
+left. Call `window.__annotations.addAnnotation({…})` from the
+console to add a row; the badge updates live.
+
+What it doesn't do yet: pin rendering on the target element, the
+element picker, threading UI, settings panel, forensic extraction.
+Those land in P2 → P7.
+
+## Build
+
+```sh
+pnpm build
+```
+
+Outputs `dist/annotations-v1.iife.js` and regenerates
+`src/v1/inject/bundle-source.generated.ts` with the bundle as a
+TypeScript string constant.
+
+## Manual smoke test
+
+```js
+// 1. Build the bundle.
+// 2. Open any page (e.g. https://linear.app) in Chrome.
+// 3. Open DevTools → Sources → paste the contents of
+//    dist/annotations-v1.iife.js, run it.
+// 4. Verify the floating annotations badge appears.
+// 5. Drop an annotation:
+window.__annotations.addAnnotation({
+  kind: "feedback",
+  target: { type: "element", path: "h1" },
+  body: [{ kind: "markdown", text: "Headline test" }],
+});
+// 6. Badge shows "1 annotation"; the row lists "feedback · Agent".
+// 7. Set the webhook URL and watch events POST:
+window.__annotations.__init({ webhookUrl: "https://webhook.site/your-id" });
+window.__annotations.addAnnotation({
+  kind: "bug",
+  target: { type: "element", path: "button" },
+  body: [{ kind: "markdown", text: "Broken on mobile" }],
+});
+```
+
+## Layout
+
+```
+src/v1/
+├── README.md           # this file
+├── index.ts            # public Node surface (install helpers, types)
+├── types.ts            # data model
+├── store.ts            # Preact signals
+├── ulid.ts             # tiny inlined ULID
+├── shadow.ts           # closed Shadow DOM mount
+├── webhook.ts          # outbound POST emitter
+├── api.ts              # window.__annotations
+├── bundle.ts           # IIFE entry
+├── ui/
+│   └── App.ts          # root Preact tree (debug shell for P1)
+└── inject/
+    ├── install.ts      # CDP install helpers
+    └── build.ts        # esbuild build script
+```
+
+Phases P2 → P7 fill in `ui/Pin.ts`, `ui/ElementPicker.ts`,
+`ui/CommentPopup.ts`, `ui/SettingsPanel.ts`, plus the
+`extract.ts` / `selectors.ts` / `react.ts` modules.

package/src/api.test.ts

@@ -0,0 +1,253 @@
+/**
+ * Smoke tests for the v1 API surface — AFS 1.1 shape.
+ *
+ * Confirms store mutations, event payloads, and ordering match the
+ * contract in PLAN.md. Does not exercise the shadow / Preact render
+ * path (that needs jsdom + a separate setup).
+ */
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { api, initSession } from "./api.js";
+import {
+  annotations,
+  cursors,
+  mode,
+  sequence,
+  sessionId,
+  theme,
+  webhookUrl,
+} from "./store.js";
+import { formatAnnotation, formatAnnotationBundle } from "./output.js";
+import type { AgentationEvent, Annotation } from "./types.js";
+
+beforeEach(() => {
+  annotations.value = [];
+  mode.value = "view";
+  theme.value = "dark";
+  webhookUrl.value = null;
+  sessionId.value = "test-session";
+  sequence.value = 0;
+});
+
+describe("api.addAnnotation (AFS shape)", () => {
+  it("emits AFS 1.1-shaped annotations", () => {
+    const id = api.addAnnotation({
+      comment: "**Headline** is buried",
+      elementPath: "body > main > h1",
+      element: "h1",
+      x: 50,
+      y: 200,
+    });
+    expect(id).toMatch(/^ann_/);
+    const a = annotations.value[0]!;
+    expect(a.element).toBe("h1");
+    expect(a.elementPath).toBe("body > main > h1");
+    expect(a.kind).toBe("feedback");
+    expect(a.status).toBe("pending");
+    expect(a.x).toBe(50);
+    expect(a.y).toBe(200);
+    expect(a.thread).toEqual([]);
+    expect(a.timestamp).toBeGreaterThan(0);
+    expect(typeof a.createdAt).toBe("string");
+  });
+
+  it("respects custom kind / intent / severity / author", () => {
+    api.addAnnotation({
+      comment: "broken on mobile",
+      elementPath: "button.cta",
+      element: "button",
+      x: 25,
+      y: 480,
+      kind: "feedback",
+      intent: "fix",
+      severity: "blocking",
+      author: { kind: "human", id: "ari", displayName: "Ari" },
+    });
+    const a = annotations.value[0]!;
+    expect(a.intent).toBe("fix");
+    expect(a.severity).toBe("blocking");
+    expect(a.author?.kind).toBe("human");
+  });
+});
+
+describe("threading and lifecycle", () => {
+  it("acknowledge → resolve flow", () => {
+    const id = api.addAnnotation({
+      comment: "fix nav density",
+      elementPath: "nav",
+      element: "nav",
+      x: 50,
+      y: 80,
+    });
+    expect(api.acknowledgeAnnotation(id)).toBe(true);
+    expect(annotations.value[0]!.status).toBe("acknowledged");
+    expect(api.resolveAnnotation(id, "agent")).toBe(true);
+    expect(annotations.value[0]!.status).toBe("resolved");
+    expect(annotations.value[0]!.resolvedBy).toBe("agent");
+    expect(typeof annotations.value[0]!.resolvedAt).toBe("string");
+  });
+
+  it("dismiss sets dismissed status", () => {
+    const id = api.addAnnotation({
+      comment: "ok skip",
+      elementPath: "footer",
+      element: "footer",
+      x: 50,
+      y: 1200,
+    });
+    expect(api.dismissAnnotation(id)).toBe(true);
+    expect(annotations.value[0]!.status).toBe("dismissed");
+  });
+
+  it("replyToAnnotation appends thread message", () => {
+    const id = api.addAnnotation({
+      comment: "ok",
+      elementPath: "h1",
+      element: "h1",
+      x: 50,
+      y: 100,
+    });
+    const msgId = api.replyToAnnotation(id, {
+      role: "agent",
+      content: "Try `Start free →`",
+    });
+    expect(msgId).toMatch(/^msg_/);
+    const a = annotations.value[0]!;
+    expect(a.thread).toHaveLength(1);
+    expect(a.thread![0]!.role).toBe("agent");
+  });
+
+  it("replyToAnnotation returns null for unknown ids", () => {
+    expect(api.replyToAnnotation("missing", { role: "human", content: "x" })).toBeNull();
+  });
+});
+
+describe("clearAnnotations / removeAnnotation", () => {
+  it("clear returns count and empties", () => {
+    api.addAnnotation({ comment: "a", elementPath: "h1", element: "h1", x: 0, y: 0 });
+    api.addAnnotation({ comment: "b", elementPath: "h2", element: "h2", x: 0, y: 0 });
+    expect(api.clearAnnotations()).toBe(2);
+    expect(annotations.value).toEqual([]);
+  });
+});
+
+describe("webhook emission", () => {
+  it("emits AFS event envelope on addAnnotation", async () => {
+    const fetchSpy = vi.fn().mockResolvedValue({ ok: true });
+    vi.stubGlobal("fetch", fetchSpy);
+    initSession({ webhookUrl: "https://example.com/webhook", sessionId: "s1" });
+
+    api.addAnnotation({
+      comment: "test",
+      elementPath: "h1",
+      element: "h1",
+      x: 50,
+      y: 100,
+    });
+
+    await Promise.resolve();
+    // 2 emits: session.created (initSession) + annotation.created.
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+    const lastCall = fetchSpy.mock.calls[1]!;
+    const body = JSON.parse((lastCall[1] as { body: string }).body) as AgentationEvent;
+    expect(body.type).toBe("annotation.created");
+    expect(body.sessionId).toBe("s1");
+    expect(body.sequence).toBeGreaterThan(0);
+    expect(typeof body.timestamp).toBe("string");
+    vi.unstubAllGlobals();
+  });
+
+  it("monotonic sequence per session", () => {
+    initSession({ webhookUrl: null as unknown as string, sessionId: "s2" });
+    const seqStart = sequence.value;
+    api.addAnnotation({ comment: "a", elementPath: "h1", element: "h1", x: 0, y: 0 });
+    const id = annotations.value[0]!.id;
+    api.replyToAnnotation(id, { role: "agent", content: "ack" });
+    api.acknowledgeAnnotation(id);
+    expect(sequence.value).toBeGreaterThan(seqStart);
+  });
+});
+
+describe("formatAnnotation (Forensic output)", () => {
+  const sample: Annotation = {
+    id: "ann_k8x2m",
+    comment: "Button is cut off on mobile viewport",
+    elementPath: "body > main > .hero-section > button.cta",
+    timestamp: 1705694400000,
+    x: 45.5,
+    y: 480,
+    element: "button",
+    url: "http://localhost:3000/landing",
+    boundingBox: { x: 120, y: 480, width: 200, height: 48 },
+    reactComponents: "App > LandingPage > HeroSection > CTAButton",
+    cssClasses: "cta btn-primary",
+    nearbyText: "Get Started Free",
+    intent: "fix",
+    severity: "blocking",
+    status: "pending",
+    thread: [
+      { id: "msg_1", role: "human", content: "blocks 50% of users", timestamp: 1 },
+      { id: "msg_2", role: "agent", content: "fixing in next variant", timestamp: 2 },
+    ],
+  };
+
+  it("forensic includes the full field set", () => {
+    const md = formatAnnotation(sample, { detail: "forensic", index: 1 });
+    expect(md).toContain("# Annotation");
+    expect(md).toContain("Annotation #1");
+    expect(md).toContain("**Element:** button");
+    expect(md).toContain("**Path:**");
+    expect(md).toContain("**React:** App > LandingPage");
+    expect(md).toContain("**Severity:**");
+    expect(md).toContain("Intent");
+    expect(md).toContain("**Nearby text:**");
+    expect(md).toContain("**Thread:**");
+    expect(md).toContain("agent");
+    expect(md).toContain("Button is cut off on mobile viewport");
+  });
+
+  it("compact strips contextual fields", () => {
+    const md = formatAnnotation(sample, { detail: "compact" });
+    expect(md).not.toContain("**React:**");
+    expect(md).not.toContain("**Nearby text:**");
+    expect(md).toContain("**Element:**");
+  });
+
+  it("bundle formats N annotations with a header", () => {
+    const md = formatAnnotationBundle([sample, sample], {
+      pageUrl: "https://stripe.com",
+      sessionId: "s1",
+    });
+    expect(md.startsWith("# Annotations")).toBe(true);
+    expect(md).toContain("URL: https://stripe.com");
+    expect(md).toContain("Count: 2");
+    expect(md.match(/^## Annotation/gm) ?? []).toHaveLength(2);
+  });
+});
+
+describe("presence cursors (multi-cursor)", () => {
+  beforeEach(() => api.clearCursors());
+
+  it("setCursors replaces all; setCursor upserts by id; removeCursor drops one", () => {
+    api.setCursors([
+      { id: "you", label: "You", kind: "human", x: 30, y: 100 },
+      { id: "agent", label: "Agent", kind: "agent", x: 50, y: 200 },
+    ]);
+    expect(cursors.value.map((c) => c.id)).toEqual(["you", "agent"]);
+
+    api.setCursor({ id: "agent", label: "Agent", kind: "agent", x: 55, y: 210 });
+    expect(cursors.value).toHaveLength(2);
+    expect(cursors.value.find((c) => c.id === "agent")?.x).toBe(55);
+
+    api.setCursor({ id: "scout", label: "Scout", kind: "agent", x: 70, y: 150 });
+    expect(cursors.value).toHaveLength(3);
+
+    expect(api.removeCursor("you")).toBe(true);
+    expect(api.removeCursor("ghost")).toBe(false);
+    expect(cursors.value).toHaveLength(2);
+
+    api.clearCursors();
+    expect(cursors.value).toHaveLength(0);
+  });
+});

package/src/api.ts

@@ -0,0 +1,264 @@
+/**
+ * `window.__annotations` — the inbound JS bridge.
+ *
+ * AFS 1.1 compatible: every annotation is the flat shape from
+ * `./types.ts`. Callers (CDP injectors, in-page UI, agents) hit
+ * these methods to mutate the store; the store emits the
+ * corresponding `annotation.created / updated / deleted` event.
+ */
+
+import { ulid } from "./ulid.js";
+import {
+  activeThreadId,
+  annotations,
+  cursors,
+  mode,
+  sessionId,
+  theme,
+  webhookUrl,
+  type PresenceCursor,
+} from "./store.js";
+import { emit } from "./webhook.js";
+import type {
+  Annotation,
+  AnnotationKind,
+  AnnotationStatus,
+  Mode,
+  Theme,
+  ThreadMessage,
+} from "./types.js";
+
+export interface AddAnnotationInput {
+  /** Generated if omitted. */
+  id?: string;
+  /** Markdown. */
+  comment: string;
+  elementPath: string;
+  element: string;
+  x: number;
+  y: number;
+  timestamp?: number;
+  url?: string;
+  boundingBox?: Annotation["boundingBox"];
+  reactComponents?: string;
+  cssClasses?: string;
+  computedStyles?: string;
+  accessibility?: string;
+  nearbyText?: string;
+  selectedText?: string;
+  isFixed?: boolean;
+  isMultiSelect?: boolean;
+  fullPath?: string;
+  nearbyElements?: string;
+  elementBoundingBoxes?: Annotation["elementBoundingBoxes"];
+  intent?: Annotation["intent"];
+  severity?: Annotation["severity"];
+  kind?: AnnotationKind;
+  placement?: Annotation["placement"];
+  rearrange?: Annotation["rearrange"];
+  status?: AnnotationStatus;
+  author?: Annotation["author"];
+}
+
+export interface ReplyInput {
+  role: "human" | "agent";
+  /** Markdown. */
+  content: string;
+}
+
+export interface AnnotationsApi {
+  readonly version: string;
+  readonly schema: "afs-1.1";
+  addAnnotation(input: AddAnnotationInput): string;
+  replyToAnnotation(annotationId: string, message: ReplyInput): string | null;
+  updateAnnotation(annotationId: string, patch: Partial<Annotation>): boolean;
+  acknowledgeAnnotation(annotationId: string): boolean;
+  resolveAnnotation(annotationId: string, by?: "human" | "agent"): boolean;
+  dismissAnnotation(annotationId: string): boolean;
+  removeAnnotation(annotationId: string): boolean;
+  clearAnnotations(): number;
+  /** Open an annotation's thread panel in the UI. Returns false if not found. */
+  focusAnnotation(annotationId: string): boolean;
+  /** Close any open thread panel. */
+  closeThread(): void;
+  /** Replace all live presence cursors (multi-cursor collaboration). */
+  setCursors(next: PresenceCursor[]): void;
+  /** Upsert a single actor's cursor by id. */
+  setCursor(cursor: PresenceCursor): void;
+  /** Remove one actor's cursor (e.g. an agent finished / a human left). */
+  removeCursor(id: string): boolean;
+  /** Remove all cursors. */
+  clearCursors(): void;
+  setMode(next: Mode): void;
+  setTheme(next: Theme): void;
+  getAnnotations(): Annotation[];
+}
+
+export const api: AnnotationsApi = {
+  version: "0.1.0",
+  schema: "afs-1.1",
+
+  addAnnotation(input) {
+    const id = input.id ?? `ann_${ulid().slice(-12).toLowerCase()}`;
+    const now = Date.now();
+    const annotation: Annotation = {
+      id,
+      comment: input.comment,
+      elementPath: input.elementPath,
+      element: input.element,
+      x: input.x,
+      y: input.y,
+      timestamp: input.timestamp ?? now,
+      url: input.url,
+      boundingBox: input.boundingBox,
+      reactComponents: input.reactComponents,
+      cssClasses: input.cssClasses,
+      computedStyles: input.computedStyles,
+      accessibility: input.accessibility,
+      nearbyText: input.nearbyText,
+      selectedText: input.selectedText,
+      isFixed: input.isFixed,
+      isMultiSelect: input.isMultiSelect,
+      fullPath: input.fullPath,
+      nearbyElements: input.nearbyElements,
+      elementBoundingBoxes: input.elementBoundingBoxes,
+      intent: input.intent,
+      severity: input.severity,
+      kind: input.kind ?? "feedback",
+      placement: input.placement,
+      rearrange: input.rearrange,
+      status: input.status ?? "pending",
+      thread: [],
+      author: input.author ?? {
+        kind: "agent",
+        id: "agent",
+        displayName: "Agent",
+      },
+      createdAt: new Date(now).toISOString(),
+      updatedAt: new Date(now).toISOString(),
+    };
+    annotations.value = [...annotations.value, annotation];
+    emit("annotation.created", annotation);
+    return id;
+  },
+
+  replyToAnnotation(annotationId, message) {
+    const existing = annotations.value.find((a) => a.id === annotationId);
+    if (!existing) return null;
+    const msg: ThreadMessage = {
+      id: `msg_${ulid().slice(-10).toLowerCase()}`,
+      role: message.role,
+      content: message.content,
+      timestamp: Date.now(),
+    };
+    annotations.value = annotations.value.map((a) =>
+      a.id === annotationId
+        ? {
+            ...a,
+            thread: [...(a.thread ?? []), msg],
+            updatedAt: new Date().toISOString(),
+          }
+        : a,
+    );
+    emit("thread.message", { annotationId, message: msg });
+    return msg.id;
+  },
+
+  updateAnnotation(annotationId, patch) {
+    let found = false;
+    annotations.value = annotations.value.map((a) => {
+      if (a.id !== annotationId) return a;
+      found = true;
+      return { ...a, ...patch, updatedAt: new Date().toISOString() } as Annotation;
+    });
+    if (found) emit("annotation.updated", { id: annotationId, patch });
+    return found;
+  },
+
+  acknowledgeAnnotation(annotationId) {
+    return this.updateAnnotation(annotationId, { status: "acknowledged" });
+  },
+
+  resolveAnnotation(annotationId, by = "agent") {
+    return this.updateAnnotation(annotationId, {
+      status: "resolved",
+      resolvedAt: new Date().toISOString(),
+      resolvedBy: by,
+    });
+  },
+
+  dismissAnnotation(annotationId) {
+    return this.updateAnnotation(annotationId, { status: "dismissed" });
+  },
+
+  removeAnnotation(annotationId) {
+    const before = annotations.value.length;
+    annotations.value = annotations.value.filter((a) => a.id !== annotationId);
+    const removed = annotations.value.length < before;
+    if (removed) emit("annotation.deleted", { id: annotationId });
+    return removed;
+  },
+
+  clearAnnotations() {
+    const n = annotations.value.length;
+    annotations.value = [];
+    activeThreadId.value = null;
+    emit("session.updated", { cleared: n });
+    return n;
+  },
+
+  focusAnnotation(annotationId) {
+    const exists = annotations.value.some((a) => a.id === annotationId);
+    if (exists) activeThreadId.value = annotationId;
+    return exists;
+  },
+
+  closeThread() {
+    activeThreadId.value = null;
+  },
+
+  setCursors(next) {
+    cursors.value = next;
+  },
+
+  setCursor(cursor) {
+    const others = cursors.value.filter((c) => c.id !== cursor.id);
+    cursors.value = [...others, cursor];
+  },
+
+  removeCursor(id) {
+    const before = cursors.value.length;
+    cursors.value = cursors.value.filter((c) => c.id !== id);
+    return cursors.value.length < before;
+  },
+
+  clearCursors() {
+    cursors.value = [];
+  },
+
+  setMode(next) {
+    if (mode.value === next) return;
+    mode.value = next;
+    emit("session.updated", { mode: next });
+  },
+
+  setTheme(next) {
+    theme.value = next;
+  },
+
+  getAnnotations() {
+    return annotations.value;
+  },
+};
+
+export function initSession(opts: {
+  webhookUrl?: string;
+  sessionId?: string;
+}): void {
+  if (opts.webhookUrl !== undefined) webhookUrl.value = opts.webhookUrl;
+  sessionId.value = opts.sessionId ?? `cf_${ulid().slice(-12).toLowerCase()}`;
+  emit("session.created", {
+    sessionId: sessionId.value,
+    pageUrl: typeof location !== "undefined" ? location.href : "",
+  });
+}