@coframe-gtm/annotations 1.1.0 → 1.2.0

package/src/ui/ThreadPanel.ts

@@ -13,20 +13,20 @@
 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(
-  role: "human" | "agent",
-  name: string,
-  content: string,
-): HTMLElement {
+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-${role}` },
+    { class: `cf-msg cf-msg-${idt.kind}` },
     el(
       "div",
       { class: "cf-msg-meta" },
-      el("span", { class: `cf-avatar cf-avatar-${role}` }, role === "agent" ? "🤖" : "🧑"),
+      renderAvatar(idt),
       el("span", { class: "cf-msg-name" }, name),
     ),
     el("div", { class: "cf-msg-body" }, content),
@@ -62,12 +62,13 @@ export function renderThreadPanel(id: string): HTMLElement | null {
     sendBtn.disabled = !textarea.value.trim();
   }
 
-  return el(
+  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(
@@ -91,9 +92,12 @@ export function renderThreadPanel(id: string): HTMLElement | null {
     el(
       "div",
       { class: "cf-thread-body" },
-      Message(a.author?.kind ?? "human", a.author?.displayName ?? "You", a.comment),
+      Message(a.author ?? { kind: "human", displayName: "You" }, a.comment),
       ...(a.thread ?? []).map((m) =>
-        Message(m.role, m.role === "agent" ? "Agent" : "You", m.content),
+        Message(
+          { kind: m.role, displayName: m.role === "agent" ? "Agent" : "You" },
+          m.content,
+        ),
       ),
     ),
     el(
@@ -117,4 +121,12 @@ export function renderThreadPanel(id: string): HTMLElement | null {
       ),
     ),
   );
+
+  // 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;
 }

package/src/ui/Toolbar.ts

@@ -1,51 +1,170 @@
 /**
- * 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`.
+ * Toolbar — minimal, logo-first control surface.
  *
- * 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.
+ *   - 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 {
+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 active = mode.value === "feedback";
   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;
 
-  return el(
+  const head = el(
     "div",
-    { class: "cf-toolbar" },
+    { 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(
-      "div",
-      { class: "cf-toolbar-head" },
-      el("span", { class: "cf-logo-dot" }),
-      el("span", null, "Annotations"),
-      el("span", { class: "cf-count" }, String(count)),
+      "button",
+      { class: "cf-collapse", title: "Collapse to icon", onClick: () => (collapsed.value = true) },
+      brandGlyph(),
     ),
     el(
       "div",
@@ -59,6 +178,57 @@ export function renderToolbar(): HTMLElement {
         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",
@@ -84,5 +254,17 @@ export function renderToolbar(): HTMLElement {
         )
       : 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/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

@@ -30,7 +30,11 @@ import {
   mode,
   feedbackTool,
   multiSelection,
+  primaryAction,
+  brandLogo,
+  collapsed,
   theme,
+  toolbarPos,
   viewportTick,
 } from "../store.js";
 import type { Signal } from "../signal.js";
@@ -129,6 +133,10 @@ export function mountOverlay(
         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(),
     );