@coframe-gtm/annotations 1.0.1

package/src/server/run-store.ts

@@ -0,0 +1,155 @@
+/**
+ * Run store — a durable, verifiable audit trail of "runs".
+ *
+ * A *run* is any event worth keeping forever for later verification:
+ *   - `annotation-session`  — a human/agent annotation session + its events
+ *   - `annotation-event`    — a single AFS event (created/updated/thread/…)
+ *   - `test-run`            — a validation/test execution + its outcome
+ *
+ * Transport-agnostic (the "backend" layer): this file defines the
+ * `RunStore` port + a deterministic in-memory implementation and a
+ * record-builder. Concrete adapters live in *infra*:
+ *   - DynamoDB (structured record) + S3 (full artifact/log blob), or
+ *   - any KV/object pair.
+ * Keeping the AWS SDK out of this package preserves portability into any
+ * host repo — infra picks the adapter.
+ */
+
+export type RunKind =
+  | "annotation-session"
+  | "annotation-event"
+  | "test-run";
+
+/**
+ * One immutable run record. `id` + `kind` + `at` are the DynamoDB
+ * primary/sort key material; `artifactKey` points at an S3 object
+ * holding the heavy payload (full event JSON, test log, screenshots).
+ */
+export interface RunRecord {
+  /** Unique id (ULID/uuid). Adapter may assign if omitted upstream. */
+  readonly id: string;
+  readonly kind: RunKind;
+  /** ISO timestamp. */
+  readonly at: string;
+  /** Session this run belongs to, when applicable. */
+  readonly sessionId?: string;
+  /** Monotonic sequence within a session, when applicable. */
+  readonly sequence?: number;
+  /** "pass" | "fail" | "ok" | a domain status. */
+  readonly status?: string;
+  /** Small structured summary (counts, command, git sha, …). */
+  readonly summary?: Readonly<Record<string, unknown>>;
+  /** S3 key (or any object-store key) for the full artifact blob. */
+  readonly artifactKey?: string;
+}
+
+/** The port infra adapters implement. */
+export interface RunStore {
+  /** Persist one run record (DynamoDB put). Idempotent on `id`. */
+  putRun(record: RunRecord): Promise<void>;
+  /**
+   * Persist a heavy artifact blob (S3 put) and return its key. The key
+   * is what goes on `RunRecord.artifactKey`.
+   */
+  putArtifact?(
+    key: string,
+    body: string,
+    contentType?: string,
+  ): Promise<string>;
+  /** List runs (for verification dashboards / `verify` tooling). */
+  listRuns(filter?: {
+    kind?: RunKind;
+    sessionId?: string;
+    limit?: number;
+  }): Promise<ReadonlyArray<RunRecord>>;
+}
+
+/** Deterministic in-memory store for tests + local dev. */
+export class InMemoryRunStore implements RunStore {
+  private readonly runs: RunRecord[] = [];
+  private readonly artifacts = new Map<string, string>();
+
+  async putRun(record: RunRecord): Promise<void> {
+    const idx = this.runs.findIndex((r) => r.id === record.id);
+    if (idx >= 0) this.runs[idx] = record;
+    else this.runs.push(record);
+  }
+
+  async putArtifact(key: string, body: string): Promise<string> {
+    this.artifacts.set(key, body);
+    return key;
+  }
+
+  async listRuns(filter?: {
+    kind?: RunKind;
+    sessionId?: string;
+    limit?: number;
+  }): Promise<ReadonlyArray<RunRecord>> {
+    let out = this.runs.slice();
+    if (filter?.kind) out = out.filter((r) => r.kind === filter.kind);
+    if (filter?.sessionId) out = out.filter((r) => r.sessionId === filter.sessionId);
+    out.sort((a, b) => (a.at < b.at ? 1 : -1)); // newest first
+    if (filter?.limit !== undefined) out = out.slice(0, filter.limit);
+    return out;
+  }
+
+  /** Test helper: read back an artifact body. */
+  readArtifact(key: string): string | undefined {
+    return this.artifacts.get(key);
+  }
+}
+
+/** Build a well-formed RunRecord, filling `at` from an injected clock. */
+export function makeRunRecord(input: {
+  id: string;
+  kind: RunKind;
+  at: string;
+  sessionId?: string;
+  sequence?: number;
+  status?: string;
+  summary?: Record<string, unknown>;
+  artifactKey?: string;
+}): RunRecord {
+  return {
+    id: input.id,
+    kind: input.kind,
+    at: input.at,
+    ...(input.sessionId ? { sessionId: input.sessionId } : {}),
+    ...(input.sequence !== undefined ? { sequence: input.sequence } : {}),
+    ...(input.status ? { status: input.status } : {}),
+    ...(input.summary ? { summary: input.summary } : {}),
+    ...(input.artifactKey ? { artifactKey: input.artifactKey } : {}),
+  };
+}
+
+/**
+ * Convenience: record an AFS event as both a queue mutation (caller's
+ * concern) and a durable `annotation-event` run with the full envelope
+ * stashed as an S3 artifact. Adapters that lack `putArtifact` just skip
+ * the blob and keep the structured record.
+ */
+export async function recordAnnotationEventRun(
+  store: RunStore,
+  envelope: { type: string; sessionId: string; sequence: number; timestamp: string; payload: unknown },
+): Promise<void> {
+  const id = `${envelope.sessionId}:${envelope.sequence}`;
+  let artifactKey: string | undefined;
+  if (store.putArtifact) {
+    artifactKey = await store.putArtifact(
+      `annotations/${envelope.sessionId}/${envelope.sequence}.json`,
+      JSON.stringify(envelope),
+      "application/json",
+    );
+  }
+  await store.putRun(
+    makeRunRecord({
+      id,
+      kind: "annotation-event",
+      at: envelope.timestamp,
+      sessionId: envelope.sessionId,
+      sequence: envelope.sequence,
+      status: envelope.type,
+      ...(artifactKey ? { artifactKey } : {}),
+    }),
+  );
+}

package/src/shadow.ts

@@ -0,0 +1,84 @@
+/**
+ * Closed Shadow DOM host for the v1 library.
+ *
+ * Closed mode: `host.shadowRoot` returns null to the host page,
+ * and `document.querySelector` can't reach into the tree. We hold
+ * the only reference internally so our UI is fully insulated from
+ * the host's JS.
+ *
+ * Reset stylesheet at the top of the tree neutralises any
+ * inheritable host styles (font sizes, colors, link decoration).
+ * Inside the shadow, our own theme.css applies cleanly.
+ *
+ * Idempotency: re-mounting on the same page is a no-op that
+ * returns the existing handles. CDP re-injection happens; we
+ * shouldn't double-mount.
+ */
+
+const HOST_ID = "annotations-v1-host";
+
+export interface ShadowMount {
+  /** The light-DOM host element appended to documentElement. */
+  host: HTMLElement;
+  /** The closed shadow root. We hold the only reference. */
+  shadow: ShadowRoot;
+  /** The element the Preact tree mounts into. */
+  appRoot: HTMLDivElement;
+}
+
+const RESET_CSS = `
+:host {
+  all: initial;
+  contain: layout style;
+  font-family: -apple-system, "SF Pro Text", system-ui, sans-serif;
+  font-size: 14px;
+  line-height: 1.45;
+  color: #f4f4f4;
+}
+*, *::before, *::after { box-sizing: border-box; }
+button { font: inherit; cursor: pointer; }
+[hidden] { display: none !important; }
+`;
+
+let cachedMount: ShadowMount | null = null;
+
+export function mountShadow(): ShadowMount {
+  if (cachedMount && document.contains(cachedMount.host)) return cachedMount;
+
+  // The host page may have torn down the host element (SPA route
+  // changes that wipe documentElement.children). If our cached
+  // reference is stale, fall through and re-mount cleanly.
+  const existingByDom = document.getElementById(HOST_ID);
+  if (existingByDom) existingByDom.remove();
+
+  const host = document.createElement("div");
+  host.id = HOST_ID;
+  host.style.cssText = [
+    "all: initial",
+    "position: fixed",
+    "inset: 0",
+    "pointer-events: none",
+    "z-index: 2147483647",
+  ].join(";");
+
+  const shadow = host.attachShadow({ mode: "closed" });
+  const reset = document.createElement("style");
+  reset.textContent = RESET_CSS;
+  shadow.appendChild(reset);
+
+  const appRoot = document.createElement("div");
+  appRoot.id = "cf-app";
+  appRoot.style.cssText = "pointer-events: auto;";
+  shadow.appendChild(appRoot);
+
+  document.documentElement.appendChild(host);
+
+  cachedMount = { host, shadow, appRoot };
+  return cachedMount;
+}
+
+export function unmountShadow(): void {
+  if (!cachedMount) return;
+  cachedMount.host.remove();
+  cachedMount = null;
+}

package/src/store.ts

@@ -0,0 +1,79 @@
+/**
+ * Preact signals for the v1 library state.
+ *
+ * Single in-memory source of truth — there's no persistence inside
+ * the library; the host's webhook handler is the durable log. On
+ * re-injection the store resets, then the host's `__init` call can
+ * re-hydrate via `addAnnotation` if it wants to.
+ */
+
+import { signal } from "@preact/signals";
+import type { CapturedTarget } from "./capture.js";
+import type { Annotation, Mode, Theme } from "./types.js";
+
+export const annotations = signal<Annotation[]>([]);
+export const mode = signal<Mode>("view");
+export const theme = signal<Theme>("dark");
+export const webhookUrl = signal<string | null>(null);
+export const sessionId = signal<string>("");
+export const sequence = signal<number>(0);
+export const ready = signal<boolean>(false);
+
+/**
+ * Identity stamped on annotations + thread replies authored through
+ * the in-page UI. The host can override via `__init({ author })`.
+ */
+export const author = signal<{
+  kind: "human" | "agent";
+  id?: string;
+  displayName?: string;
+}>({ kind: "human", id: "human", displayName: "You" });
+
+// ── Picker / UI interaction state (browser-only) ───────────────────
+
+/** Sub-mode within "feedback" mode: what a click captures. */
+export type FeedbackTool = "element" | "text" | "multi";
+
+export const feedbackTool = signal<FeedbackTool>("element");
+
+/** Live highlight box (viewport coords) drawn under the cursor. */
+export const hoverBox = signal<{
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+} | null>(null);
+
+/**
+ * A captured target awaiting a comment. When non-null the composer
+ * popup is open. Cleared on submit or cancel.
+ */
+export const draft = signal<CapturedTarget | null>(null);
+
+/** Multi-element selection accumulator (feedbackTool === "multi"). */
+export const multiSelection = signal<Element[]>([]);
+
+/** Annotation id whose thread panel is open, or null. */
+export const activeThreadId = signal<string | null>(null);
+
+/** Bump on scroll/resize to force pins to recompute screen positions. */
+export const viewportTick = signal<number>(0);
+
+/**
+ * Live presence cursors — one per actor (human reviewers + spun-off
+ * agents) collaborating on the same page. The host pushes positions via
+ * `setCursors`/`setCursor` (over the JS bridge); the overlay renders a
+ * labeled cursor for each. `x` is % of viewport width, `y` is px from
+ * document top — same coordinate space as annotations, so cursors and
+ * pins line up.
+ */
+export interface PresenceCursor {
+  id: string;
+  label: string;
+  kind: "human" | "agent";
+  x: number;
+  y: number;
+  color?: string;
+}
+
+export const cursors = signal<PresenceCursor[]>([]);

package/src/types.ts

@@ -0,0 +1,154 @@
+/**
+ * v1 annotation data model — Annotation Format Schema (AFS) v1.1.
+ *
+ * Wire-compatible with agentation.com/schema except:
+ *
+ *   - `comment` is treated as **Markdown** (not plain text) so we
+ *     can embed inline images, code blocks, and links inside a
+ *     single annotation. Tools that consume AFS as plaintext still
+ *     work since Markdown degrades cleanly when not rendered.
+ *
+ * The shape is intentionally flat — no discriminated `target` union
+ * — so existing AFS consumers (agents, MCP clients, etc.) can
+ * read our annotations without a translation shim. Variant
+ * dimensions (text selection, multi-element, area, layout mode)
+ * are encoded as optional fields on the same object.
+ */
+
+export type AnnotationKind = "feedback" | "placement" | "rearrange";
+
+export type AnnotationIntent = "fix" | "change" | "question" | "approve";
+
+export type AnnotationSeverity = "blocking" | "important" | "suggestion";
+
+export type AnnotationStatus =
+  | "pending"
+  | "acknowledged"
+  | "resolved"
+  | "dismissed";
+
+export type Mode = "view" | "feedback" | "layout";
+
+export type Theme = "dark" | "light" | "auto";
+
+export interface BoundingBox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface PlacementData {
+  componentType: string;
+  width: number;
+  height: number;
+  scrollY: number;
+  text?: string;
+}
+
+export interface RearrangeData {
+  selector: string;
+  label: string;
+  tagName: string;
+  originalRect: BoundingBox;
+  currentRect: BoundingBox;
+}
+
+export interface ThreadMessage {
+  id: string;
+  role: "human" | "agent";
+  /** Markdown content. Renderers should treat as Markdown. */
+  content: string;
+  timestamp: number;
+}
+
+/**
+ * AFS v1.1 annotation. Field ordering mirrors the canonical spec
+ * so JSON diffs against agentation output stay readable.
+ */
+export interface Annotation {
+  // Required
+  id: string;
+  /** Markdown — can include inline images, code blocks, links. */
+  comment: string;
+  elementPath: string;
+  timestamp: number;
+  /** Percentage of viewport width (0-100). */
+  x: number;
+  /** Pixels from document top, or viewport if `isFixed`. */
+  y: number;
+  element: string;
+
+  // Recommended
+  url?: string;
+  boundingBox?: BoundingBox;
+
+  // Optional context
+  reactComponents?: string;
+  cssClasses?: string;
+  computedStyles?: string;
+  accessibility?: string;
+  nearbyText?: string;
+  selectedText?: string;
+
+  // Browser-component fields (set by the injected library at capture time)
+  isFixed?: boolean;
+  isMultiSelect?: boolean;
+  fullPath?: string;
+  nearbyElements?: string;
+  /**
+   * For multi-element annotations: the per-element bounding boxes
+   * of the selected set. Always document-relative.
+   */
+  elementBoundingBoxes?: BoundingBox[];
+
+  // Feedback classification
+  intent?: AnnotationIntent;
+  severity?: AnnotationSeverity;
+
+  // Annotation kind — defaults to "feedback"
+  kind?: AnnotationKind;
+
+  // Layout-mode data (kind === "placement" | "rearrange")
+  placement?: PlacementData;
+  rearrange?: RearrangeData;
+
+  // Lifecycle
+  status?: AnnotationStatus;
+  resolvedAt?: string;
+  resolvedBy?: "human" | "agent";
+  thread?: ThreadMessage[];
+
+  // Authoring metadata (extension to AFS; safe additions)
+  author?: { kind: "human" | "agent"; id?: string; displayName?: string };
+  /** ISO timestamp set by the library on first emit. */
+  createdAt?: string;
+  /** ISO timestamp updated on any mutation. */
+  updatedAt?: string;
+}
+
+/**
+ * AFS event envelope. The library emits one of these per state
+ * change to the webhook URL. The `sequence` field is monotonic per
+ * session so the host can detect missed events and request replay.
+ */
+export type AgentationEventType =
+  | "annotation.created"
+  | "annotation.updated"
+  | "annotation.deleted"
+  | "session.created"
+  | "session.updated"
+  | "session.closed"
+  | "thread.message"
+  | "action.requested"
+  | "presence.cursor";
+
+export interface AgentationEvent<P = unknown> {
+  type: AgentationEventType;
+  /** ISO 8601 timestamp. */
+  timestamp: string;
+  sessionId: string;
+  /** Monotonic per session for ordering and replay. */
+  sequence: number;
+  payload: P;
+}