@coframe-gtm/annotations 1.0.1

package/src/bundle.ts

@@ -0,0 +1,69 @@
+/**
+ * IIFE bundle entry. esbuild emits a single minified IIFE that:
+ *
+ *   1. Sets `window.__annotations` to the AFS-compatible API.
+ *   2. Mounts the closed Shadow DOM overlay + installs the picker.
+ *   3. Auto-initialises with no webhook so a bare paste works.
+ *
+ * The CDP install helper (`./inject/install.ts`) appends an
+ * `__init({ webhookUrl, sessionId, author, mode })` call after the
+ * bundle source when the host wants outbound events or a specific
+ * starting state.
+ */
+
+import { render, h } from "preact";
+
+import { api, initSession } from "./api.js";
+import { installPicker, setPickerHost } from "./picker.js";
+import { mountShadow } from "./shadow.js";
+import { author, mode, ready, theme, viewportTick } from "./store.js";
+import { App } from "./ui/App.js";
+
+import type { AnnotationsApi } from "./api.js";
+import type { Mode, Theme } from "./types.js";
+
+interface InitOptions {
+  webhookUrl?: string;
+  sessionId?: string;
+  author?: { kind: "human" | "agent"; id?: string; displayName?: string };
+  mode?: Mode;
+  theme?: Theme;
+}
+
+declare global {
+  interface Window {
+    __annotations?: AnnotationsApi & { __init: (opts?: InitOptions) => void };
+  }
+}
+
+let mounted = false;
+
+function init(opts: InitOptions = {}): void {
+  initSession(opts);
+  if (opts.author) author.value = opts.author;
+  if (opts.mode) mode.value = opts.mode;
+  if (opts.theme) theme.value = opts.theme;
+
+  if (!mounted) {
+    mounted = true;
+    const { host, appRoot } = mountShadow();
+    setPickerHost(host);
+    installPicker();
+    render(h(App, {}), appRoot);
+
+    const bump = (): void => {
+      viewportTick.value++;
+    };
+    window.addEventListener("scroll", bump, { passive: true, capture: true });
+    window.addEventListener("resize", bump, { passive: true });
+  }
+
+  ready.value = true;
+  // eslint-disable-next-line no-console
+  console.info("[annotations v1] ready on", location.href);
+}
+
+const surface = Object.assign({ __init: init }, api);
+(window as Window).__annotations = surface;
+
+init();

package/src/capture.test.ts

@@ -0,0 +1,88 @@
+/**
+ * @vitest-environment jsdom
+ *
+ * Selector + forensic-extraction tests. Layout-dependent fields
+ * (bounding box, computed styles) are exercised in the browser;
+ * here we pin the deterministic selector / extraction logic.
+ */
+
+import { beforeEach, describe, expect, it } from "vitest";
+
+import { captureElement, cssPath, requery, shortSelector } from "./capture.js";
+
+beforeEach(() => {
+  document.body.innerHTML = "";
+});
+
+describe("shortSelector", () => {
+  it("prefers a stable id", () => {
+    document.body.innerHTML = `<button id="cta" class="x y">Go</button>`;
+    expect(shortSelector(document.querySelector("button")!)).toBe("#cta");
+  });
+
+  it("prefers data-testid over class", () => {
+    document.body.innerHTML = `<div data-testid="hero" class="a b">x</div>`;
+    expect(shortSelector(document.querySelector("div")!)).toBe(
+      '[data-testid="hero"]',
+    );
+  });
+
+  it("falls back to tag + first stable class", () => {
+    document.body.innerHTML = `<a class="link primary">x</a>`;
+    expect(shortSelector(document.querySelector("a")!)).toBe("a.link");
+  });
+
+  it("ignores framework-generated ids", () => {
+    document.body.innerHTML = `<div id=":r1:" class="card">x</div>`;
+    expect(shortSelector(document.querySelector("div")!)).toBe("div.card");
+  });
+});
+
+describe("cssPath", () => {
+  it("builds a unique nth-of-type path", () => {
+    document.body.innerHTML = `
+      <main><ul><li>a</li><li class="target">b</li><li>c</li></ul></main>`;
+    const target = document.querySelector(".target")!;
+    const path = cssPath(target);
+    expect(path).toContain("li:nth-of-type(2)");
+    expect(document.querySelector(path)).toBe(target);
+  });
+
+  it("anchors on the nearest stable id", () => {
+    document.body.innerHTML = `<section id="feat"><p><span>x</span></p></section>`;
+    const span = document.querySelector("span")!;
+    const path = cssPath(span);
+    expect(path.startsWith("#feat")).toBe(true);
+    expect(document.querySelector(path)).toBe(span);
+  });
+});
+
+describe("requery", () => {
+  it("re-finds an element by its captured path", () => {
+    document.body.innerHTML = `<div class="box"><button class="go">Go</button></div>`;
+    const btn = document.querySelector("button")!;
+    expect(requery(cssPath(btn))).toBe(btn);
+  });
+
+  it("returns null for an invalid selector instead of throwing", () => {
+    expect(requery(">>bad")).toBeNull();
+  });
+});
+
+describe("captureElement", () => {
+  it("captures AFS context fields for an element", () => {
+    document.body.innerHTML = `
+      <article class="post"><h2 id="title" role="heading" aria-label="Hi">Hello world</h2></article>`;
+    const h2 = document.querySelector("h2")!;
+    const cap = captureElement(h2);
+
+    expect(cap.element).toBe("h2");
+    expect(cap.elementPath).toBe("#title");
+    expect(cap.url).toBe(location.href);
+    expect(cap.accessibility).toContain('role="heading"');
+    expect(cap.accessibility).toContain('aria-label="Hi"');
+    expect(cap.nearbyText).toContain("Hello world");
+    expect(cap.nearbyElements).toContain("parent: article.post");
+    expect(cap.boundingBox).toBeDefined();
+  });
+});

package/src/capture.ts

@@ -0,0 +1,345 @@
+/**
+ * Forensic DOM extraction.
+ *
+ * Given a target element (and optionally a selected-text range or a
+ * multi-element set), produce the AFS 1.1 context fields the
+ * Forensic output formatter wants: a stable selector path, a
+ * canonical `fullPath`, curated computed styles, classes,
+ * accessibility attributes, nearby text/elements, the React
+ * component (when the page is React), bounding box, and fixed
+ * positioning.
+ *
+ * Everything here is browser-only and called at capture time, so
+ * `document` / `window` are assumed present. Pure string helpers are
+ * unit-testable; the DOM walkers are exercised in the browser.
+ */
+
+import type { AddAnnotationInput } from "./api.js";
+import type { BoundingBox } from "./types.js";
+
+/** Computed-style properties worth capturing for layout reasoning. */
+const FORENSIC_STYLE_PROPS = [
+  "display",
+  "position",
+  "width",
+  "height",
+  "margin",
+  "padding",
+  "color",
+  "background-color",
+  "background",
+  "font-family",
+  "font-size",
+  "font-weight",
+  "line-height",
+  "border",
+  "border-radius",
+  "box-shadow",
+  "flex-direction",
+  "justify-content",
+  "align-items",
+  "gap",
+  "grid-template-columns",
+  "z-index",
+  "opacity",
+  "text-align",
+] as const;
+
+/** Accessibility-relevant attributes. */
+const A11Y_ATTRS = [
+  "role",
+  "aria-label",
+  "aria-labelledby",
+  "aria-describedby",
+  "aria-hidden",
+  "aria-expanded",
+  "aria-checked",
+  "aria-selected",
+  "alt",
+  "title",
+  "tabindex",
+  "type",
+  "name",
+  "for",
+  "href",
+] as const;
+
+export interface CapturedTarget
+  extends Pick<
+    AddAnnotationInput,
+    | "elementPath"
+    | "element"
+    | "x"
+    | "y"
+    | "url"
+    | "boundingBox"
+    | "reactComponents"
+    | "cssClasses"
+    | "computedStyles"
+    | "accessibility"
+    | "nearbyText"
+    | "selectedText"
+    | "isFixed"
+    | "isMultiSelect"
+    | "fullPath"
+    | "nearbyElements"
+    | "elementBoundingBoxes"
+  > {}
+
+/**
+ * Capture the full forensic context for an element. `selectedText`
+ * and the multi-element set are layered in by the callers in
+ * `picker.ts`.
+ */
+export function captureElement(el: Element): CapturedTarget {
+  const rect = el.getBoundingClientRect();
+  const isFixed = isFixedPositioned(el);
+  const scrollX = window.scrollX;
+  const scrollY = window.scrollY;
+
+  const box: BoundingBox = {
+    x: rect.left + (isFixed ? 0 : scrollX),
+    y: rect.top + (isFixed ? 0 : scrollY),
+    width: rect.width,
+    height: rect.height,
+  };
+
+  return {
+    element: el.tagName.toLowerCase(),
+    elementPath: shortSelector(el),
+    fullPath: cssPath(el),
+    x: clampPercent(((rect.left + rect.width / 2) / window.innerWidth) * 100),
+    y: isFixed ? rect.top : rect.top + scrollY,
+    url: location.href,
+    boundingBox: box,
+    isFixed,
+    cssClasses: classList(el),
+    computedStyles: computedStyles(el),
+    accessibility: accessibility(el),
+    nearbyText: nearbyText(el),
+    nearbyElements: nearbyElements(el),
+    reactComponents: reactComponent(el),
+  };
+}
+
+// ── Selector heuristics ────────────────────────────────────────────
+
+/**
+ * Short, human-readable selector for display + as the re-query key
+ * used to re-anchor pins. id > data-testid > tag + first class.
+ */
+export function shortSelector(el: Element): string {
+  if (el.id && isStableId(el.id)) return `#${cssEscape(el.id)}`;
+  const testid = el.getAttribute("data-testid");
+  if (testid) return `[data-testid="${testid}"]`;
+  const tag = el.tagName.toLowerCase();
+  const cls = firstStableClass(el);
+  return cls ? `${tag}.${cssEscape(cls)}` : tag;
+}
+
+/**
+ * Canonical, document-unique CSS path from `<body>` to the element,
+ * using `:nth-of-type` where needed for stability.
+ */
+export function cssPath(el: Element): string {
+  const segments: string[] = [];
+  let node: Element | null = el;
+  while (node && node.nodeType === 1 && node.tagName.toLowerCase() !== "html") {
+    if (node.id && isStableId(node.id)) {
+      segments.unshift(`#${cssEscape(node.id)}`);
+      break;
+    }
+    let seg = node.tagName.toLowerCase();
+    const parent: Element | null = node.parentElement;
+    if (parent) {
+      const sameTag = Array.from(parent.children).filter(
+        (c) => c.tagName === node!.tagName,
+      );
+      if (sameTag.length > 1) {
+        seg += `:nth-of-type(${sameTag.indexOf(node) + 1})`;
+      }
+    }
+    segments.unshift(seg);
+    node = parent;
+  }
+  return segments.join(" > ");
+}
+
+/** Re-find an element by the selector captured earlier. Best-effort. */
+export function requery(selector: string): Element | null {
+  if (!selector) return null;
+  try {
+    return document.querySelector(selector);
+  } catch {
+    return null;
+  }
+}
+
+function isStableId(id: string): boolean {
+  // Skip framework-generated ids (long hashes, `:r1:`, `radix-…`).
+  if (id.length > 40) return false;
+  if (/^[:]?r[a-z0-9]+[:]?$/i.test(id)) return false;
+  if (/^(radix|headlessui|mui|react-aria)[-:]/i.test(id)) return false;
+  return true;
+}
+
+function firstStableClass(el: Element): string | null {
+  for (const c of Array.from(el.classList)) {
+    // Skip hashed CSS-module / styled-components classes.
+    if (/^[a-z0-9_-]*[a-f0-9]{6,}$/i.test(c) && /\d/.test(c)) continue;
+    if (c.startsWith("cf-")) continue;
+    return c;
+  }
+  return el.classList[0] ?? null;
+}
+
+function cssEscape(value: string): string {
+  if (typeof CSS !== "undefined" && typeof CSS.escape === "function") {
+    return CSS.escape(value);
+  }
+  return value.replace(/([^\w-])/g, "\\$1");
+}
+
+// ── Field extractors ───────────────────────────────────────────────
+
+function classList(el: Element): string | undefined {
+  const classes = Array.from(el.classList).filter((c) => !c.startsWith("cf-"));
+  return classes.length ? classes.join(" ") : undefined;
+}
+
+function computedStyles(el: Element): string | undefined {
+  const cs = window.getComputedStyle(el);
+  const lines: string[] = [];
+  for (const prop of FORENSIC_STYLE_PROPS) {
+    const value = cs.getPropertyValue(prop);
+    if (value && value !== "none" && value !== "normal" && value !== "auto") {
+      lines.push(`${prop}: ${value};`);
+    }
+  }
+  return lines.length ? lines.join("\n") : undefined;
+}
+
+function accessibility(el: Element): string | undefined {
+  const parts: string[] = [];
+  for (const attr of A11Y_ATTRS) {
+    const value = el.getAttribute(attr);
+    if (value !== null && value !== "") parts.push(`${attr}="${value}"`);
+  }
+  const text = directText(el);
+  if (text) parts.push(`text="${truncate(text, 60)}"`);
+  return parts.length ? parts.join(" ") : undefined;
+}
+
+/** Text the user can see inside the element, collapsed + truncated. */
+function nearbyText(el: Element): string | undefined {
+  const text = (el.textContent ?? "").replace(/\s+/g, " ").trim();
+  if (!text) return undefined;
+  return truncate(text, 200);
+}
+
+/** A compact description of the element's siblings + parent. */
+function nearbyElements(el: Element): string | undefined {
+  const parts: string[] = [];
+  if (el.parentElement) {
+    parts.push(`parent: ${describe(el.parentElement)}`);
+  }
+  const prev = el.previousElementSibling;
+  if (prev) parts.push(`prev: ${describe(prev)}`);
+  const next = el.nextElementSibling;
+  if (next) parts.push(`next: ${describe(next)}`);
+  return parts.length ? parts.join(" | ") : undefined;
+}
+
+function describe(el: Element): string {
+  const tag = el.tagName.toLowerCase();
+  const cls = firstStableClass(el);
+  const label = (el.textContent ?? "").replace(/\s+/g, " ").trim().slice(0, 30);
+  return `${tag}${cls ? `.${cls}` : ""}${label ? ` "${label}"` : ""}`;
+}
+
+function directText(el: Element): string {
+  let out = "";
+  for (const node of Array.from(el.childNodes)) {
+    if (node.nodeType === 3) out += node.textContent ?? "";
+  }
+  return out.replace(/\s+/g, " ").trim();
+}
+
+// ── React detection ────────────────────────────────────────────────
+
+/**
+ * Walk `__reactFiber$` keys to surface the nearest named component.
+ * The only entry React offers; sanitisation/format below is ours.
+ */
+export function reactComponent(el: Element): string | undefined {
+  const fiberKey = Object.keys(el).find(
+    (k) => k.startsWith("__reactFiber$") || k.startsWith("__reactInternalInstance$"),
+  );
+  if (!fiberKey) return undefined;
+
+  let fiber = (el as unknown as Record<string, unknown>)[fiberKey] as
+    | ReactFiber
+    | undefined;
+  const names: string[] = [];
+  let props: Record<string, unknown> | undefined;
+  let depth = 0;
+
+  while (fiber && depth < 30) {
+    const type = fiber.type;
+    const name =
+      typeof type === "function"
+        ? (type as { displayName?: string; name?: string }).displayName ??
+          (type as { name?: string }).name
+        : undefined;
+    if (name && /^[A-Z]/.test(name) && !names.includes(name)) {
+      names.push(name);
+      if (!props && fiber.memoizedProps) props = fiber.memoizedProps;
+      if (names.length >= 3) break;
+    }
+    fiber = fiber.return;
+    depth++;
+  }
+
+  if (!names.length) return undefined;
+  const head = names[0];
+  const propStr = props ? sanitizeProps(props) : "";
+  return propStr ? `${head} (${propStr})` : head;
+}
+
+interface ReactFiber {
+  type?: unknown;
+  return?: ReactFiber;
+  memoizedProps?: Record<string, unknown>;
+}
+
+function sanitizeProps(props: Record<string, unknown>): string {
+  const pairs: string[] = [];
+  for (const [key, value] of Object.entries(props)) {
+    if (key === "children") continue;
+    if (typeof value === "string") pairs.push(`${key}=${JSON.stringify(truncate(value, 40))}`);
+    else if (typeof value === "number" || typeof value === "boolean") pairs.push(`${key}=${value}`);
+    if (pairs.length >= 5) break;
+  }
+  return pairs.join(", ");
+}
+
+// ── misc ───────────────────────────────────────────────────────────
+
+function isFixedPositioned(el: Element): boolean {
+  let node: Element | null = el;
+  let depth = 0;
+  while (node && depth < 20) {
+    if (window.getComputedStyle(node).position === "fixed") return true;
+    node = node.parentElement;
+    depth++;
+  }
+  return false;
+}
+
+function truncate(text: string, max: number): string {
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+
+function clampPercent(n: number): number {
+  return Math.max(0, Math.min(100, Math.round(n * 10) / 10));
+}

package/src/index.ts

@@ -0,0 +1,45 @@
+/**
+ * Public v1 surface — for Node callers (server workers, scripts,
+ * tests) that need types, install helpers, the bundle source, or
+ * the Forensic output formatter.
+ *
+ * Browser consumers don't import from here — they inject the IIFE
+ * bundle and use `window.__annotations`.
+ */
+
+export type {
+  AgentationEvent,
+  AgentationEventType,
+  Annotation,
+  AnnotationIntent,
+  AnnotationKind,
+  AnnotationSeverity,
+  AnnotationStatus,
+  BoundingBox,
+  Mode,
+  PlacementData,
+  RearrangeData,
+  Theme,
+  ThreadMessage,
+} from "./types.js";
+
+export type { AnnotationsApi, AddAnnotationInput, ReplyInput } from "./api.js";
+
+export {
+  installInCurrentDocument,
+  installOnNewDocument,
+  installAnnotationsOverlay,
+  buildAnnotationsInstallSource,
+  buildInitCall,
+  ANNOTATIONS_V1_BUNDLE_SOURCE,
+} from "./inject/install.js";
+
+export type { CdpSession, InstallOptions } from "./inject/install.js";
+
+export {
+  formatAnnotation,
+  formatAnnotationBundle,
+  type FormatOptions,
+  type BundleOptions,
+  type OutputDetail,
+} from "./output.js";

package/src/inject/build.ts

@@ -0,0 +1,52 @@
+/**
+ * Build the v1 IIFE bundle with esbuild.
+ *
+ * Invocation: `pnpm build`
+ *
+ * Output: `dist/annotations-v1.iife.js`. The build also re-emits
+ * `src/v1/inject/bundle-source.generated.ts` exporting the bundle
+ * source as a TypeScript string constant so the worker (or any Node
+ * caller) can import it without reading the file at runtime.
+ */
+
+import { build } from "esbuild";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = resolve(here, "..", "..", "..");
+const entryPoint = resolve(here, "..", "bundle.ts");
+const outFile = resolve(pkgRoot, "dist", "annotations-v1.iife.js");
+const generatedSrc = resolve(here, "bundle-source.generated.ts");
+
+await mkdir(dirname(outFile), { recursive: true });
+
+await build({
+  entryPoints: [entryPoint],
+  outfile: outFile,
+  bundle: true,
+  format: "iife",
+  minify: true,
+  target: "es2020",
+  jsx: "automatic",
+  jsxImportSource: "preact",
+  legalComments: "none",
+  logLevel: "info",
+});
+
+const bundleSource = await readFile(outFile, "utf8");
+
+const generated = [
+  "/* eslint-disable */",
+  "// This file is generated by `pnpm build`.",
+  "// Do not edit by hand. Regenerate by running the build script.",
+  "export const ANNOTATIONS_V1_BUNDLE_SOURCE: string =",
+  JSON.stringify(bundleSource) + ";",
+  "",
+].join("\n");
+
+await writeFile(generatedSrc, generated, "utf8");
+
+const kb = (bundleSource.length / 1024).toFixed(1);
+console.log(`annotations-v1.iife.js  ${kb} kB`);