@coframe-gtm/annotations 1.0.4 → 1.2.0

package/src/ui/Toolbar.ts

@@ -0,0 +1,270 @@
+/**
+ * Toolbar — minimal, logo-first control surface.
+ *
+ *   - Collapsed (default): a small draggable logo "FAB". Tap to expand.
+ *   - Expanded: a tight row — [grip] [logo] [View | Comment] [count] —
+ *     plus the tool row + primary action when commenting. A visible grip
+ *     signals "draggable"; the logo collapses back to the puck.
+ *
+ * Vanilla DOM. `renderToolbar()` rebuilds from the current signal values.
+ */
+
+import {
+  activeThreadId,
+  annotations,
+  collapsed,
+  feedbackTool,
+  hoverBox,
+  mode,
+  multiSelection,
+  primaryAction,
+  toolbarPos,
+} from "../store.js";
+import { commitMultiSelection } from "../picker.js";
+import { api } from "../api.js";
+import { brandGlyph } from "./brand.js";
+import { el } from "./dom.js";
+
+const EDGE = 8; // keep this many px of margin from every viewport edge
+const clamp = (v: number, lo: number, hi: number): number => Math.max(lo, Math.min(v, hi));
+
+/**
+ * Drag `target` by `handle`. Buttons inside the handle still click
+ * (they're skipped). Moves the element directly during the drag, then
+ * commits the final position to `toolbarPos`. If the pointer barely
+ * moved it's a tap → `onTap` (used to expand the collapsed FAB).
+ */
+function attachDrag(target: HTMLElement, handle: HTMLElement, onTap?: () => void): void {
+  handle.addEventListener("pointerdown", (e: PointerEvent) => {
+    if ((e.target as HTMLElement)?.closest("button")) return; // let buttons click
+    e.preventDefault();
+    const rect = target.getBoundingClientRect();
+    const offX = e.clientX - rect.left;
+    const offY = e.clientY - rect.top;
+    const startX = e.clientX;
+    const startY = e.clientY;
+    let x = rect.left;
+    let y = rect.top;
+    let moved = false;
+    handle.setPointerCapture(e.pointerId);
+    target.classList.add("cf-dragging");
+
+    const move = (ev: PointerEvent): void => {
+      if (Math.abs(ev.clientX - startX) + Math.abs(ev.clientY - startY) > 4) moved = true;
+      x = clamp(ev.clientX - offX, EDGE, window.innerWidth - target.offsetWidth - EDGE);
+      y = clamp(ev.clientY - offY, EDGE, window.innerHeight - target.offsetHeight - EDGE);
+      target.style.left = `${x}px`;
+      target.style.top = `${y}px`;
+      target.style.right = "auto";
+      target.style.bottom = "auto";
+    };
+    const up = (): void => {
+      target.classList.remove("cf-dragging");
+      handle.removeEventListener("pointermove", move);
+      handle.removeEventListener("pointerup", up);
+      if (moved) toolbarPos.value = { x, y };
+      else onTap?.();
+    };
+    handle.addEventListener("pointermove", move);
+    handle.addEventListener("pointerup", up);
+  });
+}
+
+/** Scroll the annotation's element into view and open its thread. */
+function jumpTo(index: number): void {
+  const list = annotations.value;
+  if (!list.length) return;
+  const i = ((index % list.length) + list.length) % list.length;
+  const a = list[i]!;
+  let target: Element | null = null;
+  try {
+    target =
+      (a.fullPath && document.querySelector(a.fullPath)) ||
+      (a.elementPath ? document.querySelector(a.elementPath) : null);
+  } catch {
+    /* invalid selector — fall through */
+  }
+  target?.scrollIntoView({ behavior: "smooth", block: "center" });
+  activeThreadId.value = a.id;
+}
+
+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);
+}
+
+function posStyle(): string | undefined {
+  const pos = toolbarPos.value;
+  return pos ? `left:${pos.x}px;top:${pos.y}px;right:auto;bottom:auto;` : undefined;
+}
+
+/**
+ * After the element is in the DOM, measure its real size and nudge it
+ * fully on-screen. The panel anchors top-left, so a wide expansion near
+ * the right/bottom edge would otherwise overflow — this pulls it back.
+ */
+function keepOnScreen(elx: HTMLElement): void {
+  requestAnimationFrame(() => {
+    const r = elx.getBoundingClientRect();
+    if (!r.width || !r.height) return;
+    const x = clamp(r.left, EDGE, Math.max(EDGE, window.innerWidth - r.width - EDGE));
+    const y = clamp(r.top, EDGE, Math.max(EDGE, window.innerHeight - r.height - EDGE));
+    if (Math.abs(x - r.left) > 0.5 || Math.abs(y - r.top) > 0.5) {
+      elx.style.left = `${x}px`;
+      elx.style.top = `${y}px`;
+      elx.style.right = "auto";
+      elx.style.bottom = "auto";
+    }
+  });
+}
+
+export function renderToolbar(): HTMLElement {
+  const count = annotations.value.length;
+
+  // Collapsed → a minimal draggable logo. Tap (or Enter/Space) to open.
+  if (collapsed.value) {
+    const fab = el("div", {
+      class: "cf-fab",
+      role: "button",
+      tabindex: "0",
+      title: "Open annotations · drag to move",
+      style: posStyle(),
+    });
+    fab.appendChild(brandGlyph());
+    if (count > 0) {
+      fab.appendChild(el("span", { class: "cf-fab-badge" }, count > 99 ? "99+" : String(count)));
+    }
+    fab.addEventListener("keydown", (e: KeyboardEvent) => {
+      if (e.key === "Enter" || e.key === " ") {
+        e.preventDefault();
+        collapsed.value = false;
+      }
+    });
+    attachDrag(fab, fab, () => {
+      collapsed.value = false;
+    });
+    keepOnScreen(fab);
+    return fab;
+  }
+
+  const active = mode.value === "feedback";
+  const multi = multiSelection.value.length;
+
+  const head = el(
+    "div",
+    { class: "cf-toolbar-head", title: "Drag to move" },
+    // Visible grip → "you can drag this".
+    el("span", { class: "cf-grip", "aria-hidden": "true" }, "⠿"),
+    // Logo → collapses back to the puck.
+    el(
+      "button",
+      { class: "cf-collapse", title: "Collapse to icon", onClick: () => (collapsed.value = true) },
+      brandGlyph(),
+    ),
+    el(
+      "div",
+      { class: "cf-seg" },
+      SegButton("View", mode.value === "view", () => {
+        mode.value = "view";
+        hoverBox.value = null;
+        multiSelection.value = [];
+      }),
+      SegButton("Comment", active, () => {
+        mode.value = "feedback";
+      }),
+    ),
+    el("span", { class: "cf-count" }, String(count)),
+    // Erase board — clears every annotation.
+    count > 0
+      ? el(
+          "button",
+          {
+            class: "cf-icon-btn cf-clear",
+            title: "Clear all annotations",
+            onClick: () => {
+              api.clearAnnotations();
+              api.clearCursors();
+            },
+          },
+          "Clear",
+        )
+      : null,
+  );
+
+  // Suggestions navigator — count + jump to each annotation.
+  const list = annotations.value;
+  const agentCount = list.filter((a) => a.author?.kind === "agent").length;
+  const cur = Math.max(0, list.findIndex((a) => a.id === activeThreadId.value));
+  const nav =
+    count > 0
+      ? el(
+          "div",
+          { class: "cf-nav" },
+          el(
+            "button",
+            { class: "cf-nav-btn", title: "Previous", onClick: () => jumpTo(cur - 1) },
+            "‹",
+          ),
+          el(
+            "span",
+            { class: "cf-nav-label" },
+            agentCount > 0
+              ? `${agentCount} agent${agentCount === 1 ? "" : "s"} · ${cur + 1}/${count}`
+              : `${cur + 1} / ${count}`,
+          ),
+          el(
+            "button",
+            { class: "cf-nav-btn", title: "Next", onClick: () => jumpTo(cur + 1) },
+            "›",
+          ),
+        )
+      : null;
+
+  const toolbar = el("div", { class: "cf-toolbar", style: posStyle() });
+  const children: Array<Node | null> = [
+    head,
+    nav,
+    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,
+    primaryAction.value
+      ? el(
+          "button",
+          { class: "cf-btn cf-btn-primary cf-launch", onClick: () => primaryAction.value?.run() },
+          primaryAction.value.label,
+        )
+      : null,
+  ];
+  for (const child of children) if (child) toolbar.appendChild(child);
+
+  attachDrag(toolbar, head);
+  keepOnScreen(toolbar);
+  return toolbar;
+}

package/src/ui/brand.ts

@@ -0,0 +1,16 @@
+/**
+ * Brand glyph — the host-supplied logo (the "floater" mark) or a neutral
+ * dot fallback. Shared by the toolbar/FAB and the popups, so the composer
+ * reads as the floater that grew into a box.
+ */
+
+import { brandLogo } from "../store.js";
+import { el } from "./dom.js";
+
+export function brandGlyph(extraClass = ""): HTMLElement {
+  const span = el("span", { class: `cf-brand${extraClass ? ` ${extraClass}` : ""}` });
+  const logo = brandLogo.value;
+  if (logo) span.innerHTML = logo;
+  else span.appendChild(el("span", { class: "cf-logo-dot" }));
+  return span;
+}

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

@@ -27,6 +27,71 @@ export function truncate(text: string, max: number): string {
   return text.length > max ? `${text.slice(0, max - 1)}…` : text;
 }
 
+/**
+ * Anchor a popup just below its target element (viewport-coords box),
+ * then clamp it on-screen — flipping above when it would overflow the
+ * bottom. Keeps the composer/thread next to what they refer to.
+ *
+ * Once placed, the popup *morphs out of the floater*: it animates from
+ * the launcher's position + size (the FAB / toolbar puck) to its final
+ * rect, so the box reads as the floater that flew over and opened.
+ */
+export function placeNear(
+  popup: HTMLElement,
+  box: { left: number; top: number; width: number; height: number },
+): void {
+  popup.style.position = "fixed";
+  popup.style.left = `${box.left}px`;
+  popup.style.top = `${box.top + box.height + 10}px`;
+  popup.style.right = "auto";
+  popup.style.bottom = "auto";
+  requestAnimationFrame(() => {
+    const r = popup.getBoundingClientRect();
+    if (!r.width) return;
+    const left = Math.max(8, Math.min(box.left, window.innerWidth - r.width - 8));
+    let top = box.top + box.height + 10;
+    if (top + r.height > window.innerHeight - 8) top = box.top - r.height - 10;
+    top = Math.max(8, Math.min(top, window.innerHeight - r.height - 8));
+    popup.style.left = `${left}px`;
+    popup.style.top = `${top}px`;
+    morphFromLauncher(popup);
+  });
+}
+
+/**
+ * Spring the popup open from the floater (FAB / toolbar puck): a FLIP
+ * that starts the popup shrunk + translated onto the launcher, then
+ * animates to its real position. Falls back silently if the launcher
+ * can't be found or the Web Animations API is unavailable.
+ */
+function morphFromLauncher(popup: HTMLElement): void {
+  if (typeof popup.animate !== "function") return;
+  const root = popup.closest(".cf-overlay");
+  const launcher = root?.querySelector<HTMLElement>(".cf-fab, .cf-toolbar");
+  if (!launcher) return;
+  const from = launcher.getBoundingClientRect();
+  const to = popup.getBoundingClientRect();
+  if (!from.width || !to.width) return;
+
+  const dx = from.left + from.width / 2 - (to.left + to.width / 2);
+  const dy = from.top + from.height / 2 - (to.top + to.height / 2);
+  const sx = Math.max(0.08, from.width / to.width);
+  const sy = Math.max(0.08, from.height / to.height);
+
+  // Suppress the CSS keyframe so it doesn't fight the morph.
+  popup.classList.add("cf-morph");
+  popup.style.transformOrigin = "center center";
+  popup.animate(
+    [
+      { transform: `translate(${dx}px, ${dy}px) scale(${sx}, ${sy})`, opacity: 0.25 },
+      { transform: "translate(0, 0) scale(1, 1)", opacity: 1 },
+    ],
+    { duration: 360, easing: "cubic-bezier(.34,1.3,.5,1)", fill: "both" },
+  ).addEventListener("finish", () => {
+    popup.style.transform = "";
+  });
+}
+
 export function hashId(s: string): number {
   let h = 0;
   for (let i = 0; i < s.length; i++) h = (h << 5) - h + s.charCodeAt(i);
@@ -48,3 +113,27 @@ export function pinPosition(a: Annotation): { top: number; left: number } | null
   }
   return null;
 }
+
+/**
+ * Live viewport rect of the element an annotation targets — used to
+ * draw the highlight outline around it. Re-anchors to the live element
+ * (falls back to the stored bounding box). Mirrors {@link pinPosition}.
+ */
+export function annotationBox(
+  a: Annotation,
+): { top: number; left: number; width: number; height: number } | null {
+  const el = requery(a.fullPath ?? "") ?? requery(a.elementPath ?? "");
+  if (el) {
+    const r = el.getBoundingClientRect();
+    return { top: r.top, left: r.left, width: r.width, height: r.height };
+  }
+  if (a.boundingBox) {
+    return {
+      top: a.boundingBox.y - (a.isFixed ? 0 : window.scrollY),
+      left: a.boundingBox.x - (a.isFixed ? 0 : window.scrollX),
+      width: a.boundingBox.width,
+      height: a.boundingBox.height,
+    };
+  }
+  return null;
+}

package/src/ui/overlay.ts

@@ -0,0 +1,163 @@
+/**
+ * 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,
+  primaryAction,
+  brandLogo,
+  collapsed,
+  theme,
+  toolbarPos,
+  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>,
+        toolbarPos as Signal<unknown>,
+        primaryAction as Signal<unknown>,
+        collapsed as Signal<unknown>,
+        brandLogo 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);
+}