@coframe-gtm/annotations 1.0.4 → 1.2.0

package/src/ui/Composer.ts

@@ -0,0 +1,206 @@
+/**
+ * Composer popup — the comment + intent/severity form shown when a
+ * target is captured. Vanilla DOM.
+ *
+ * Local form state (comment/intent/severity) lives in plain closure
+ * variables, NOT in a re-rendering hook. The comment is read from the
+ * textarea's `.value` at submit time. Selecting an intent/severity chip
+ * toggles the `.on` class on the chips in place — the composer is never
+ * rebuilt on a chip click, so the textarea keeps its focus + value.
+ */
+
+import { api } from "../api.js";
+import type { CapturedTarget } from "../capture.js";
+import { author, draft } from "../store.js";
+import type {
+  AnnotationIntent,
+  AnnotationKind,
+  AnnotationSeverity,
+} from "../types.js";
+import {
+  INTENTS,
+  SEVERITIES,
+  SEVERITY_COLOR,
+  SEVERITY_NEUTRAL,
+} from "./constants.js";
+import { placeNear, truncate } from "./helpers.js";
+import { brandGlyph } from "./brand.js";
+import { el } from "./dom.js";
+
+export function renderComposer(target: CapturedTarget): HTMLElement {
+  // Local form state — closure vars, not hooks. Chip selections update
+  // these + toggle classes in place; the comment is read from the DOM.
+  let intent: AnnotationIntent = "change";
+  let severity: AnnotationSeverity = "important";
+
+  const textarea = el("textarea", {
+    class: "cf-textarea",
+    placeholder: "Describe the change… (Markdown supported)",
+    autofocus: true,
+    onKeyDown: (e: KeyboardEvent) => {
+      if ((e.metaKey || e.ctrlKey) && e.key === "Enter") submit();
+    },
+    onInput: () => syncSubmitState(),
+  }) as HTMLTextAreaElement;
+
+  const submit = (): void => {
+    const text = textarea.value.trim();
+    if (!text) return;
+    api.addAnnotation({
+      ...target,
+      comment: text,
+      intent,
+      severity,
+      kind: "feedback" satisfies AnnotationKind,
+      author: author.value,
+    });
+    draft.value = null;
+  };
+
+  const cancel = (): void => {
+    draft.value = null;
+  };
+
+  // Build a chip group whose selection toggles `.on` in place. `onSelect`
+  // updates the closure state; we never rebuild the composer.
+  function chipGroup(
+    labels: readonly string[],
+    color: (label: string) => string,
+    isOn: (label: string) => boolean,
+    onSelect: (label: string) => void,
+  ): { group: HTMLElement; refresh: () => void } {
+    const chips = labels.map((label) => {
+      const on = isOn(label);
+      return el(
+        "button",
+        {
+          class: `cf-chip${on ? " on" : ""}`,
+          style: on ? `--cf-chip:${color(label)};` : undefined,
+          onClick: () => {
+            onSelect(label);
+            refresh();
+          },
+        },
+        label,
+      );
+    });
+    const group = el("div", { class: "cf-chipset" }, ...chips);
+    function refresh(): void {
+      labels.forEach((label, i) => {
+        const chip = chips[i]!;
+        const on = isOn(label);
+        chip.className = `cf-chip${on ? " on" : ""}`;
+        if (on) chip.setAttribute("style", `--cf-chip:${color(label)};`);
+        else chip.removeAttribute("style");
+      });
+    }
+    return { group, refresh };
+  }
+
+  const intentGroup = chipGroup(
+    INTENTS,
+    () => SEVERITY_NEUTRAL,
+    (label) => intent === label,
+    (label) => {
+      intent = label as AnnotationIntent;
+    },
+  );
+
+  const severityGroup = chipGroup(
+    SEVERITIES,
+    (label) => SEVERITY_COLOR[label as AnnotationSeverity],
+    (label) => severity === label,
+    (label) => {
+      severity = label as AnnotationSeverity;
+    },
+  );
+
+  const label = target.isMultiSelect
+    ? `${target.elementBoundingBoxes?.length ?? 0} elements`
+    : target.selectedText
+      ? `"${truncate(target.selectedText, 40)}"`
+      : `<${target.element}>`;
+
+  const submitBtn = el(
+    "button",
+    {
+      class: "cf-btn cf-btn-primary",
+      disabled: true,
+      onClick: submit,
+    },
+    "Comment",
+  ) as HTMLButtonElement;
+
+  function syncSubmitState(): void {
+    submitBtn.disabled = !textarea.value.trim();
+  }
+
+  // Intent + severity are power-user controls — keep them out of the way
+  // behind a single disclosure so the default surface is just type + send.
+  const details = el(
+    "div",
+    { class: "cf-details", hidden: true },
+    el(
+      "div",
+      { class: "cf-field" },
+      el("span", { class: "cf-field-label" }, "Intent"),
+      intentGroup.group,
+    ),
+    el(
+      "div",
+      { class: "cf-field" },
+      el("span", { class: "cf-field-label" }, "Severity"),
+      severityGroup.group,
+    ),
+  ) as HTMLElement;
+
+  const detailsBtn = el(
+    "button",
+    {
+      class: "cf-disclose",
+      onClick: () => {
+        const open = details.hidden;
+        details.hidden = !open;
+        detailsBtn.classList.toggle("on", open);
+        detailsBtn.textContent = open ? "Details ▴" : "Details ▾";
+      },
+    },
+    "Details ▾",
+  );
+
+  const popup = el(
+    "div",
+    { class: "cf-popup cf-composer" },
+    el(
+      "div",
+      { class: "cf-popup-head" },
+      brandGlyph("cf-popup-brand"),
+      el("span", { class: "cf-popup-target" }, label),
+      el("button", { class: "cf-icon-btn", onClick: cancel, title: "Close (Esc)" }, "✕"),
+    ),
+    textarea,
+    details,
+    el(
+      "div",
+      { class: "cf-popup-actions" },
+      detailsBtn,
+      submitBtn,
+    ),
+  );
+
+  // Anchor the composer next to the element being annotated.
+  const bb = target.boundingBox;
+  if (bb) {
+    placeNear(popup, {
+      left: bb.x - window.scrollX,
+      top: bb.y - window.scrollY,
+      width: bb.width,
+      height: bb.height,
+    });
+  }
+  // Focus the comment field right away — the `autofocus` attribute doesn't
+  // fire on nodes created + inserted dynamically into the shadow root, so
+  // without this the user has to click into the box before typing.
+  requestAnimationFrame(() => textarea.focus({ preventScroll: true }));
+  return popup;
+}

package/src/ui/Cursors.ts

@@ -0,0 +1,48 @@
+/**
+ * Live presence cursors — one labeled arrow per remote actor (human
+ * reviewers + spun-off agents) collaborating on the same page. Vanilla
+ * DOM; the cursors layer renders one of these per entry in
+ * `cursors.value` (multi-cursor).
+ */
+
+import type { PresenceCursor } from "../store.js";
+import { CURSOR_PALETTE } from "./constants.js";
+import { hashId } from "./helpers.js";
+import { el, svg } from "./dom.js";
+
+export function renderCursor(c: PresenceCursor): HTMLElement {
+  // x is % of viewport width; y is px from document top.
+  const left = (c.x / 100) * window.innerWidth;
+  const top = c.y - window.scrollY;
+  const color =
+    c.color ??
+    (c.kind === "agent"
+      ? CURSOR_PALETTE[Math.abs(hashId(c.id)) % CURSOR_PALETTE.length]!
+      : "#ffffff");
+
+  const arrow = svg(
+    "svg",
+    {
+      width: "18",
+      height: "18",
+      viewBox: "0 0 18 18",
+      class: "cf-cursor-arrow",
+    },
+    svg("path", {
+      d: "M2 2 L2 14 L6 10 L9 16 L11 15 L8 9 L14 9 Z",
+      fill: color,
+      stroke: "rgba(0,0,0,0.35)",
+      "stroke-width": "0.75",
+    }),
+  );
+
+  return el(
+    "div",
+    {
+      class: `cf-cursor cf-cursor-${c.kind}`,
+      style: `top:${top}px;left:${left}px;--cf-cursor:${color};`,
+    },
+    arrow,
+    el("span", { class: "cf-cursor-label" }, c.label),
+  );
+}

package/src/ui/Pins.ts

@@ -0,0 +1,138 @@
+/**
+ * Pins + multi-select boxes (vanilla DOM).
+ *
+ *   - `renderPin(a, index)` — one numbered marker per annotation,
+ *     re-anchored to its live element. Click toggles the thread panel;
+ *     hover shows a small floating preview card with the comment.
+ *   - `MultiBox(el)` — a pulsing outline around an element in the
+ *     current multi-selection set.
+ */
+
+import { activeThreadId, draft } from "../store.js";
+import type { Annotation, BoundingBox } from "../types.js";
+import { DEFAULT_DOT, SEVERITY_COLOR } from "./constants.js";
+import { colorForIdentity } from "./Avatar.js";
+import { annotationBox, boxStyle, firstLine } from "./helpers.js";
+import { el } from "./dom.js";
+
+/**
+ * Annotations whose entrance animation has already played. The pins layer
+ * re-renders on EVERY scroll/resize tick, so without this gate the
+ * `cf-rise`/`cf-pin-pop` keyframes would replay on each tick and the
+ * markers would flicker instead of tracking their element smoothly. We
+ * only tag a marker `.cf-fresh` (→ animated) the first time we see its id.
+ */
+const seenPins = new Set<string>();
+
+/** A document-relative box → live screen coords (so it tracks scroll). */
+function docBoxToScreen(
+  b: BoundingBox,
+  isFixed?: boolean,
+): { top: number; left: number; width: number; height: number } {
+  return {
+    top: b.y - (isFixed ? 0 : window.scrollY),
+    left: b.x - (isFixed ? 0 : window.scrollX),
+    width: b.width,
+    height: b.height,
+  };
+}
+
+/** Short glyph shown inside the pin — agent initial, or the index. */
+function pinLabel(a: Annotation, index: number): string {
+  if (a.author?.kind === "agent") {
+    const name = (a.author.displayName ?? "").trim();
+    return name ? name.charAt(0).toUpperCase() : "AI";
+  }
+  return String(index);
+}
+
+export function renderPin(a: Annotation, index: number): HTMLElement | null {
+  const isAgent = a.author?.kind === "agent";
+  // Color-code by agent (matches their avatar + cursor); humans use severity.
+  const color = isAgent
+    ? colorForIdentity(a.author!)
+    : a.severity
+      ? SEVERITY_COLOR[a.severity]
+      : DEFAULT_DOT;
+  const resolved = a.status === "resolved" || a.status === "dismissed";
+
+  // Animate the entrance only the first render for this annotation — not on
+  // every scroll/resize re-render (which would otherwise flicker).
+  const fresh = !seenPins.has(a.id);
+  seenPins.add(a.id);
+  const flags = `${resolved ? " resolved" : ""}${isAgent ? " agent" : ""}${fresh ? " cf-fresh" : ""}`;
+
+  const pin = el(
+    "button",
+    {
+      class: `cf-pin${flags}`,
+      title: a.author?.displayName
+        ? `${a.author.displayName}: ${firstLine(a.comment)}`
+        : firstLine(a.comment),
+      onClick: () => {
+        // One popup at a time: opening a thread closes any open composer,
+        // so a stray dark composer never stacks behind the thread panel.
+        const opening = activeThreadId.value !== a.id;
+        if (opening) draft.value = null;
+        activeThreadId.value = opening ? a.id : null;
+      },
+    },
+    pinLabel(a, index),
+  );
+
+  // Hover-to-preview: a small floating card with the comment.
+  let preview: HTMLElement | null = null;
+  pin.addEventListener("mouseenter", () => {
+    if (preview || activeThreadId.value === a.id) return; // thread already open
+    preview = el("div", { class: "cf-pin-preview" }, firstLine(a.comment) || a.comment);
+    pin.appendChild(preview);
+  });
+  pin.addEventListener("mouseleave", () => {
+    preview?.remove();
+    preview = null;
+  });
+
+  // The outline box hugs each annotated element so it's obvious what the
+  // annotation refers to; the pin sits at the first element's top-left.
+  const makeWrap = (box: {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+  }): HTMLElement =>
+    el("div", {
+      class: `cf-anno${flags}`,
+      style: `${boxStyle(box)}--cf-pin:${color};`,
+    });
+
+  // Multi-element annotation → outline EVERY selected element, not just the
+  // primary; the numbered pin sits on the first box.
+  if (a.isMultiSelect && a.elementBoundingBoxes?.length) {
+    const group = el("div", { class: "cf-anno-group" });
+    a.elementBoundingBoxes.forEach((b, i) => {
+      const wrap = makeWrap(docBoxToScreen(b, a.isFixed));
+      if (i === 0) wrap.appendChild(pin);
+      group.appendChild(wrap);
+    });
+    return group;
+  }
+
+  const box = annotationBox(a);
+  if (!box) return null;
+  const wrap = makeWrap(box);
+  wrap.appendChild(pin);
+  return wrap;
+}
+
+export function MultiBox(target: Element): HTMLElement {
+  const rect = target.getBoundingClientRect();
+  return el("div", {
+    class: "cf-multi-box",
+    style: boxStyle({
+      top: rect.top,
+      left: rect.left,
+      width: rect.width,
+      height: rect.height,
+    }),
+  });
+}

package/src/ui/ThreadPanel.ts

@@ -0,0 +1,132 @@
+/**
+ * Thread panel — the per-pin discussion (human ↔ agent). Shows the
+ * root annotation comment plus the reply thread, with a compose box
+ * and a resolve affordance. Reads the active annotation from the
+ * `../store.js` signals by id. Vanilla DOM.
+ *
+ * The reply text is read from the textarea at send time (no hook state);
+ * the overlay's thread layer re-renders this on annotation changes so
+ * new thread messages appear, which clears the in-progress reply — same
+ * behavior as the previous Preact `useState("")` reset after send.
+ */
+
+import { api } from "../api.js";
+import { activeThreadId, annotations, author } from "../store.js";
+import { SEVERITY_COLOR } from "./constants.js";
+import { renderAvatar, type AvatarIdentity } from "./Avatar.js";
+import { annotationBox, placeNear } from "./helpers.js";
+import { brandGlyph } from "./brand.js";
+import { el } from "./dom.js";
+
+export function Message(idt: AvatarIdentity, content: string): HTMLElement {
+  const name = idt.displayName ?? (idt.kind === "agent" ? "Agent" : "You");
+  return el(
+    "div",
+    { class: `cf-msg cf-msg-${idt.kind}` },
+    el(
+      "div",
+      { class: "cf-msg-meta" },
+      renderAvatar(idt),
+      el("span", { class: "cf-msg-name" }, name),
+    ),
+    el("div", { class: "cf-msg-body" }, content),
+  );
+}
+
+export function renderThreadPanel(id: string): HTMLElement | null {
+  const a = annotations.value.find((x) => x.id === id);
+  if (!a) return null;
+
+  const textarea = el("textarea", {
+    class: "cf-textarea cf-textarea-sm",
+    placeholder: "Reply…",
+    onKeyDown: (e: KeyboardEvent) => {
+      if ((e.metaKey || e.ctrlKey) && e.key === "Enter") send();
+    },
+    onInput: () => syncSendState(),
+  }) as HTMLTextAreaElement;
+
+  const send = (): void => {
+    const text = textarea.value.trim();
+    if (!text) return;
+    api.replyToAnnotation(id, { role: author.value.kind, content: text });
+  };
+
+  const sendBtn = el(
+    "button",
+    { class: "cf-btn cf-btn-primary", disabled: true, onClick: send },
+    "Reply",
+  ) as HTMLButtonElement;
+
+  function syncSendState(): void {
+    sendBtn.disabled = !textarea.value.trim();
+  }
+
+  const popup = el(
+    "div",
+    { class: "cf-popup cf-thread" },
+    el(
+      "div",
+      { class: "cf-popup-head" },
+      brandGlyph("cf-popup-brand"),
+      el("span", { class: "cf-popup-target" }, `<${a.element}>`),
+      a.severity
+        ? el(
+            "span",
+            { class: "cf-tag", style: `--cf-tag:${SEVERITY_COLOR[a.severity]};` },
+            a.severity,
+          )
+        : null,
+      el(
+        "button",
+        {
+          class: "cf-icon-btn",
+          onClick: () => {
+            activeThreadId.value = null;
+          },
+          title: "Close",
+        },
+        "✕",
+      ),
+    ),
+    el(
+      "div",
+      { class: "cf-thread-body" },
+      Message(a.author ?? { kind: "human", displayName: "You" }, a.comment),
+      ...(a.thread ?? []).map((m) =>
+        Message(
+          { kind: m.role, displayName: m.role === "agent" ? "Agent" : "You" },
+          m.content,
+        ),
+      ),
+    ),
+    el(
+      "div",
+      { class: "cf-thread-compose" },
+      textarea,
+      el(
+        "div",
+        { class: "cf-thread-actions" },
+        a.status !== "resolved"
+          ? el(
+              "button",
+              {
+                class: "cf-btn cf-btn-ghost",
+                onClick: () => api.resolveAnnotation(id, author.value.kind),
+              },
+              "Resolve",
+            )
+          : el("span", { class: "cf-resolved-tag" }, "✓ resolved"),
+        sendBtn,
+      ),
+    ),
+  );
+
+  // Anchor the thread panel next to its annotated element.
+  const box = annotationBox(a);
+  if (box) placeNear(popup, box);
+  // Focus the reply field on open (the `autofocus` attribute doesn't fire
+  // on dynamically-inserted shadow-root nodes).
+  requestAnimationFrame(() => textarea.focus({ preventScroll: true }));
+  return popup;
+}