@coframe-gtm/annotations 1.0.3 → 1.1.0

package/src/ui/Cursors.ts

@@ -0,0 +1,52 @@
+/**
+ * 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.kind === "agent" ? "🤖 " : ""}${c.label}`,
+    ),
+  );
+}

package/src/ui/Pins.ts

@@ -0,0 +1,68 @@
+/**
+ * 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 } from "../store.js";
+import type { Annotation } from "../types.js";
+import { DEFAULT_DOT, SEVERITY_COLOR } from "./constants.js";
+import { boxStyle, firstLine, pinPosition } from "./helpers.js";
+import { el } from "./dom.js";
+
+export function renderPin(a: Annotation, index: number): HTMLElement | null {
+  const pos = pinPosition(a);
+  if (!pos) return null;
+  const color = a.severity ? SEVERITY_COLOR[a.severity] : DEFAULT_DOT;
+  const resolved = a.status === "resolved" || a.status === "dismissed";
+
+  const pin = el(
+    "button",
+    {
+      class: `cf-pin${resolved ? " resolved" : ""}${a.author?.kind === "agent" ? " agent" : ""}`,
+      style: `top:${pos.top}px;left:${pos.left}px;--cf-pin:${color};`,
+      title: firstLine(a.comment),
+      onClick: () => {
+        activeThreadId.value = activeThreadId.value === a.id ? null : a.id;
+      },
+    },
+    a.author?.kind === "agent" ? "★" : String(index),
+  );
+
+  // Hover-to-preview: a small floating card with the comment, shown on
+  // mouseenter and removed on mouseleave. The card is appended to the
+  // pin so it lives/dies with it; it's positioned just below-right.
+  let preview: HTMLElement | null = null;
+  pin.addEventListener("mouseenter", () => {
+    if (preview) return;
+    preview = el(
+      "div",
+      { class: "cf-pin-preview" },
+      firstLine(a.comment) || a.comment,
+    );
+    pin.appendChild(preview);
+  });
+  pin.addEventListener("mouseleave", () => {
+    preview?.remove();
+    preview = null;
+  });
+
+  return pin;
+}
+
+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,120 @@
+/**
+ * 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 { el } from "./dom.js";
+
+export function Message(
+  role: "human" | "agent",
+  name: string,
+  content: string,
+): HTMLElement {
+  return el(
+    "div",
+    { class: `cf-msg cf-msg-${role}` },
+    el(
+      "div",
+      { class: "cf-msg-meta" },
+      el("span", { class: `cf-avatar cf-avatar-${role}` }, role === "agent" ? "🤖" : "🧑"),
+      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();
+  }
+
+  return el(
+    "div",
+    { class: "cf-popup cf-thread" },
+    el(
+      "div",
+      { class: "cf-popup-head" },
+      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", a.author?.displayName ?? "You", a.comment),
+      ...(a.thread ?? []).map((m) =>
+        Message(m.role, 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,
+      ),
+    ),
+  );
+}

package/src/ui/Toolbar.ts

@@ -0,0 +1,88 @@
+/**
+ * Toolbar — mode + tool switches, annotation count, and a contextual
+ * hint. Reads cross-cutting state from the `../store.js` signals and
+ * commits multi-selections through `../picker.js`.
+ *
+ * Vanilla DOM (no JSX). `renderToolbar()` builds the toolbar fresh from
+ * the current signal values; the overlay re-runs it when any of the
+ * signals the toolbar layer depends on changes.
+ */
+
+import {
+  annotations,
+  feedbackTool,
+  hoverBox,
+  mode,
+  multiSelection,
+} from "../store.js";
+import { commitMultiSelection } from "../picker.js";
+import { el } from "./dom.js";
+
+export function hintFor(tool: string): string {
+  if (tool === "text") return "Select text on the page to annotate it.";
+  if (tool === "multi") return "Click elements to group them, then commit.";
+  return "Click any element to comment. Esc to exit.";
+}
+
+export function SegButton(
+  label: string,
+  on: boolean,
+  onClick: () => void,
+): HTMLElement {
+  return el("button", { class: `cf-seg-btn${on ? " on" : ""}`, onClick }, label);
+}
+
+export function renderToolbar(): HTMLElement {
+  const active = mode.value === "feedback";
+  const count = annotations.value.length;
+  const multi = multiSelection.value.length;
+
+  return el(
+    "div",
+    { class: "cf-toolbar" },
+    el(
+      "div",
+      { class: "cf-toolbar-head" },
+      el("span", { class: "cf-logo-dot" }),
+      el("span", null, "Annotations"),
+      el("span", { class: "cf-count" }, String(count)),
+    ),
+    el(
+      "div",
+      { class: "cf-seg" },
+      SegButton("View", mode.value === "view", () => {
+        mode.value = "view";
+        hoverBox.value = null;
+        multiSelection.value = [];
+      }),
+      SegButton("Comment", active, () => {
+        mode.value = "feedback";
+      }),
+    ),
+    active
+      ? el(
+          "div",
+          { class: "cf-seg cf-tools" },
+          SegButton("Element", feedbackTool.value === "element", () => {
+            feedbackTool.value = "element";
+            multiSelection.value = [];
+          }),
+          SegButton("Text", feedbackTool.value === "text", () => {
+            feedbackTool.value = "text";
+            multiSelection.value = [];
+          }),
+          SegButton("Multi", feedbackTool.value === "multi", () => {
+            feedbackTool.value = "multi";
+          }),
+        )
+      : null,
+    active && feedbackTool.value === "multi" && multi
+      ? el(
+          "button",
+          { class: "cf-btn cf-btn-primary cf-commit", onClick: commitMultiSelection },
+          `Comment ${multi} element${multi === 1 ? "" : "s"}`,
+        )
+      : null,
+    active ? el("div", { class: "cf-hint" }, hintFor(feedbackTool.value)) : null,
+  );
+}

package/src/ui/constants.ts

@@ -0,0 +1,24 @@
+/**
+ * Shared overlay constants — colors, palettes, and the option lists
+ * the composer chips iterate over. Plain module (no JSX) so it can be
+ * imported by both the `.tsx` components and any plain `.ts` consumer.
+ */
+
+import type {
+  AnnotationIntent,
+  AnnotationSeverity,
+} from "../types.js";
+
+export const SEVERITY_COLOR: Record<AnnotationSeverity, string> = {
+  blocking: "#ef4444",
+  important: "#f59e0b",
+  suggestion: "#3ecf8e",
+};
+export const DEFAULT_DOT = "#a78bfa";
+
+export const INTENTS: AnnotationIntent[] = ["fix", "change", "question", "approve"];
+export const SEVERITIES: AnnotationSeverity[] = ["blocking", "important", "suggestion"];
+
+export const SEVERITY_NEUTRAL = "#8b94a3";
+
+export const CURSOR_PALETTE = ["#a78bfa", "#3ecf8e", "#f59e0b", "#38bdf8", "#f472b6"];

package/src/ui/dom.ts

@@ -0,0 +1,95 @@
+/**
+ * Tiny DRY DOM-building helpers — the vanilla replacement for JSX.
+ *
+ * `el(tag, props?, ...children)` builds an HTMLElement; `svg(tag, …)`
+ * does the same in the SVG namespace (for the cursor arrow). Props map
+ * onto attributes/handlers the same way the old JSX did:
+ *
+ *   - `class`            → className
+ *   - `style`            → inline style string
+ *   - `on*` (onClick…)   → addEventListener (onClick→click, onInput→input,
+ *                          onKeyDown→keydown — lowercased remainder)
+ *   - `dataset`          → element.dataset entries
+ *   - boolean attrs      → present when true, omitted when false
+ *   - everything else    → setAttribute(key, String(value))
+ *
+ * Children may be strings (text nodes), Nodes, arrays (flattened), or
+ * null/false/undefined (skipped).
+ */
+
+const SVG_NS = "http://www.w3.org/2000/svg";
+
+export type Child = Node | string | number | null | false | undefined | Child[];
+
+export interface Props {
+  [key: string]: unknown;
+}
+
+function applyProps(node: Element, props: Props): void {
+  for (const [key, value] of Object.entries(props)) {
+    if (value === undefined || value === null) continue;
+
+    if (key === "class") {
+      node.setAttribute("class", String(value));
+      continue;
+    }
+    if (key === "style") {
+      node.setAttribute("style", String(value));
+      continue;
+    }
+    if (key === "dataset") {
+      const data = value as Record<string, string>;
+      if (node instanceof HTMLElement) {
+        for (const [dk, dv] of Object.entries(data)) node.dataset[dk] = dv;
+      }
+      continue;
+    }
+    if (key.startsWith("on") && typeof value === "function") {
+      const event = key.slice(2).toLowerCase();
+      node.addEventListener(event, value as EventListener);
+      continue;
+    }
+    if (typeof value === "boolean") {
+      if (value) node.setAttribute(key, "");
+      continue;
+    }
+    node.setAttribute(key, String(value));
+  }
+}
+
+function appendChildren(node: Element, children: Child[]): void {
+  for (const child of children) {
+    if (child === null || child === false || child === undefined) continue;
+    if (Array.isArray(child)) {
+      appendChildren(node, child);
+      continue;
+    }
+    if (child instanceof Node) {
+      node.appendChild(child);
+      continue;
+    }
+    node.appendChild(document.createTextNode(String(child)));
+  }
+}
+
+export function el(
+  tag: string,
+  props?: Props | null,
+  ...children: Child[]
+): HTMLElement {
+  const node = document.createElement(tag);
+  if (props) applyProps(node, props);
+  appendChildren(node, children);
+  return node;
+}
+
+export function svg(
+  tag: string,
+  props?: Props | null,
+  ...children: Child[]
+): SVGElement {
+  const node = document.createElementNS(SVG_NS, tag);
+  if (props) applyProps(node, props);
+  appendChildren(node, children);
+  return node;
+}

package/src/ui/helpers.ts

@@ -0,0 +1,50 @@
+/**
+ * Pure layout/text helpers shared across the overlay components.
+ * Plain module (no JSX). `pinPosition` re-anchors a pin to its live
+ * element; `boxStyle` builds the inline-style string for highlight
+ * boxes; the rest are small string utilities.
+ */
+
+import { requery } from "../capture.js";
+import type { Annotation } from "../types.js";
+
+export function boxStyle(b: {
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+}): string {
+  return `top:${b.top}px;left:${b.left}px;width:${b.width}px;height:${b.height}px;`;
+}
+
+export function firstLine(markdown: string): string {
+  const trimmed = markdown.trim();
+  const nl = trimmed.indexOf("\n");
+  return nl > 0 ? trimmed.slice(0, nl) : trimmed;
+}
+
+export function truncate(text: string, max: number): string {
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+
+export function hashId(s: string): number {
+  let h = 0;
+  for (let i = 0; i < s.length; i++) h = (h << 5) - h + s.charCodeAt(i);
+  return h;
+}
+
+/** Live screen position of a pin, re-anchored to the element. */
+export function pinPosition(a: Annotation): { top: number; left: number } | null {
+  const el = requery(a.fullPath ?? "") ?? requery(a.elementPath ?? "");
+  if (el) {
+    const rect = el.getBoundingClientRect();
+    return { top: rect.top - 11, left: rect.left - 11 };
+  }
+  if (a.boundingBox) {
+    return {
+      top: a.boundingBox.y - (a.isFixed ? 0 : window.scrollY) - 11,
+      left: a.boundingBox.x - (a.isFixed ? 0 : window.scrollX) - 11,
+    };
+  }
+  return null;
+}

package/src/ui/overlay.ts

@@ -0,0 +1,155 @@
+/**
+ * Vanilla per-layer overlay mount — the replacement for the single
+ * Preact <App/> tree.
+ *
+ * Each visual layer gets its OWN container and subscribes ONLY to the
+ * signals it depends on, re-rendering just that layer when one changes.
+ * This is deliberate: `hoverBox` updates on every mousemove, and a
+ * single global re-render would destroy an open composer (blowing away
+ * the textarea's focus + value) on each move. Layer isolation keeps the
+ * composer alive while the hover box repaints independently.
+ *
+ * Layers (all inside the closed Shadow DOM, fixed-positioned):
+ *   1. styles      — static <style> with STYLES (once)
+ *   2. hover       <- hoverBox, draft        (hidden while composing)
+ *   3. multi-box   <- multiSelection, viewportTick
+ *   4. pins        <- annotations, viewportTick
+ *   5. cursors     <- cursors                (multi-cursor)
+ *   6. toolbar     <- mode, feedbackTool, annotations, multiSelection
+ *                     (skipped entirely when init headless = true)
+ *   7. composer    <- draft   (rebuilt only when the draft opens/closes)
+ *   8. thread      <- activeThreadId, annotations
+ */
+
+import {
+  activeThreadId,
+  annotations,
+  cursors,
+  draft,
+  hoverBox,
+  mode,
+  feedbackTool,
+  multiSelection,
+  theme,
+  viewportTick,
+} from "../store.js";
+import type { Signal } from "../signal.js";
+import { boxStyle } from "./helpers.js";
+import { renderToolbar } from "./Toolbar.js";
+import { MultiBox, renderPin } from "./Pins.js";
+import { renderCursor } from "./Cursors.js";
+import { renderComposer } from "./Composer.js";
+import { renderThreadPanel } from "./ThreadPanel.js";
+import { STYLES } from "./styles.js";
+import { el } from "./dom.js";
+
+interface MountOptions {
+  /** When true the toolbar layer is not mounted (parent frame drives mode). */
+  headless?: boolean;
+}
+
+/** Wire a layer container to a set of signals; re-render on any change. */
+function bindLayer(
+  container: HTMLElement,
+  deps: Signal<unknown>[],
+  render: () => Node | Node[] | null,
+): void {
+  const paint = (): void => {
+    container.replaceChildren();
+    const out = render();
+    if (out === null) return;
+    if (Array.isArray(out)) container.append(...out);
+    else container.append(out);
+  };
+  paint();
+  for (const dep of deps) dep.subscribe(paint);
+}
+
+export function mountOverlay(
+  appRoot: HTMLElement,
+  options: MountOptions = {},
+): void {
+  const root = el("div", { class: "cf-overlay" });
+
+  const setTheme = (): void => {
+    root.setAttribute("data-theme", theme.value === "auto" ? "dark" : theme.value);
+  };
+  setTheme();
+  theme.subscribe(setTheme);
+
+  // 1. Styles — static, once.
+  const style = document.createElement("style");
+  style.textContent = STYLES;
+  root.appendChild(style);
+
+  // 2. Hover highlight (hidden while composing).
+  const hoverLayer = el("div", { class: "cf-layer-hover" });
+  bindLayer(hoverLayer, [hoverBox as Signal<unknown>, draft as Signal<unknown>], () => {
+    const box = hoverBox.value;
+    if (!box || draft.value) return null;
+    return el("div", { class: "cf-hover", style: boxStyle(box) });
+  });
+  root.appendChild(hoverLayer);
+
+  // 3. Multi-select boxes.
+  const multiLayer = el("div", { class: "cf-layer-multi" });
+  bindLayer(
+    multiLayer,
+    [multiSelection as Signal<unknown>, viewportTick as Signal<unknown>],
+    () => multiSelection.value.map((element) => MultiBox(element)),
+  );
+  root.appendChild(multiLayer);
+
+  // 4. Pins.
+  const pinsLayer = el("div", { class: "cf-layer-pins" });
+  bindLayer(
+    pinsLayer,
+    [annotations as Signal<unknown>, viewportTick as Signal<unknown>],
+    () =>
+      annotations.value
+        .map((a, i) => renderPin(a, i + 1))
+        .filter((n): n is HTMLElement => n !== null),
+  );
+  root.appendChild(pinsLayer);
+
+  // 5. Cursors (multi-cursor — one labeled cursor per entry).
+  const cursorsLayer = el("div", { class: "cf-layer-cursors" });
+  bindLayer(cursorsLayer, [cursors as Signal<unknown>], () =>
+    cursors.value.map((c) => renderCursor(c)),
+  );
+  root.appendChild(cursorsLayer);
+
+  // 6. Toolbar — skipped entirely in headless mode.
+  if (!options.headless) {
+    const toolbarLayer = el("div", { class: "cf-layer-toolbar" });
+    bindLayer(
+      toolbarLayer,
+      [
+        mode as Signal<unknown>,
+        feedbackTool as Signal<unknown>,
+        annotations as Signal<unknown>,
+        multiSelection as Signal<unknown>,
+      ],
+      () => renderToolbar(),
+    );
+    root.appendChild(toolbarLayer);
+  }
+
+  // 7. Composer — rebuilt only when the draft opens/closes.
+  const composerLayer = el("div", { class: "cf-layer-composer" });
+  bindLayer(composerLayer, [draft as Signal<unknown>], () =>
+    draft.value ? renderComposer(draft.value) : null,
+  );
+  root.appendChild(composerLayer);
+
+  // 8. Thread panel.
+  const threadLayer = el("div", { class: "cf-layer-thread" });
+  bindLayer(
+    threadLayer,
+    [activeThreadId as Signal<unknown>, annotations as Signal<unknown>],
+    () => (activeThreadId.value ? renderThreadPanel(activeThreadId.value) : null),
+  );
+  root.appendChild(threadLayer);
+
+  appRoot.appendChild(root);
+}

package/src/ui/styles.ts

@@ -108,6 +108,29 @@ export const STYLES = `
   pointer-events: none;
 }
 
+/* Hover-to-preview card — shown next to a pin on mouseenter. */
+.cf-pin-preview {
+  position: absolute;
+  top: 26px; left: 0;
+  max-width: 240px;
+  width: max-content;
+  pointer-events: none;
+  background: var(--cf-bg);
+  border: 1px solid var(--cf-border);
+  border-radius: 9px;
+  padding: 7px 10px;
+  font: 500 12px -apple-system, system-ui;
+  line-height: 1.4;
+  color: #f4f4f5;
+  white-space: normal;
+  overflow-wrap: anywhere;
+  backdrop-filter: blur(16px) saturate(140%);
+  box-shadow: 0 8px 28px rgba(0,0,0,0.5);
+  z-index: 7;
+  animation: cf-rise .14s cubic-bezier(.16,1,.3,1) both;
+}
+.cf-overlay[data-theme="light"] .cf-pin-preview { color: #18181b; }
+
 @keyframes cf-pin-pop {
   0% { transform: scale(0); opacity: 0; }
   60% { transform: scale(1.25); opacity: 1; }