@useclickly/react 1.0.2 → 1.0.4

package/dist/index.js

@@ -1,1027 +1,19 @@
-// packages/react/src/Clickly.tsx
+// ../react/src/Clickly.tsx
 import { useEffect as useEffect7, useState as useState7 } from "react";
 import { createPortal } from "react-dom";
+import {
+  Overlay,
+  SelectionEngine,
+  createShadowHost
+} from "@useclickly/core";
 
-// packages/core/dist/index.js
-function pickElementAt(doc, x, y, excludeHost) {
-  if (typeof doc.elementsFromPoint !== "function") return null;
-  const chain = doc.elementsFromPoint(x, y);
-  for (const el of chain) {
-    if (!isInExcludedSubtree(el, excludeHost)) return el;
-  }
-  return null;
-}
-function pickElementsInRect(root, rect, excludeHost) {
-  const out = [];
-  const stack = [root];
-  while (stack.length) {
-    const el = stack.pop();
-    if (isInExcludedSubtree(el, excludeHost)) continue;
-    const box = el.getBoundingClientRect();
-    if (box.width > 0 && box.height > 0 && containedIn(box, rect)) {
-      out.push(el);
-    }
-    for (let i = 0; i < el.children.length; i++) {
-      const child = el.children[i];
-      if (child) stack.push(child);
-    }
-  }
-  return out;
-}
-function containedIn(el, sel) {
-  return el.left >= sel.x && el.top >= sel.y && el.right <= sel.x + sel.width && el.bottom <= sel.y + sel.height;
-}
-function isInExcludedSubtree(el, host) {
-  if (!host) return false;
-  let cur = el;
-  while (cur) {
-    if (cur === host) return true;
-    cur = cur.parentNode;
-  }
-  return false;
-}
-function manhattan(a, b) {
-  return Math.abs(a.x - b.x) + Math.abs(a.y - b.y);
-}
-function rectFromPoints(start, current) {
-  const x = Math.min(start.x, current.x);
-  const y = Math.min(start.y, current.y);
-  const width = Math.abs(current.x - start.x);
-  const height = Math.abs(current.y - start.y);
-  return { x, y, width, height };
-}
-var DRAG_THRESHOLD_PX = 12;
-var initialState = { kind: "idle" };
-function reduce(state, event) {
-  if (event.type === "DEACTIVATE") return { kind: "idle" };
-  if (event.type === "ESCAPE") {
-    if (state.kind === "idle") return state;
-    if (state.kind === "annotating") return resumeInspect(
-      [],
-      /* mode */
-      void 0
-    );
-    if (state.kind === "inspect" && state.pinned.length > 0) {
-      return { ...state, pinned: [], hoverTarget: null };
-    }
-    return resumeInspect("pinned" in state ? state.pinned : []);
-  }
-  if (event.type === "CLEAR_PINNED") {
-    if (state.kind === "idle") return state;
-    if (state.kind === "inspect") return { ...state, pinned: [] };
-    return state;
-  }
-  switch (state.kind) {
-    case "idle":
-      if (event.type === "ACTIVATE") {
-        return {
-          kind: "inspect",
-          mode: event.mode ?? "single",
-          hoverTarget: null,
-          pinned: []
-        };
-      }
-      return state;
-    case "inspect":
-      if (event.type === "MODE_CHANGE") return { ...state, mode: event.mode };
-      if (event.type === "POINTER_MOVE") return { ...state, hoverTarget: event.target };
-      if (event.type === "POINTER_DOWN") {
-        return {
-          kind: "pressed",
-          mode: state.mode,
-          start: event.point,
-          target: event.target,
-          additive: event.additive,
-          pinned: state.pinned
-        };
-      }
-      if (event.type === "ANNOTATE_PINNED") {
-        if (state.pinned.length === 0) return state;
-        return {
-          kind: "annotating",
-          selection: { kind: "multi", elements: state.pinned },
-          pinned: state.pinned
-        };
-      }
-      return state;
-    case "pressed":
-      if (event.type === "POINTER_MOVE") {
-        if (manhattan(state.start, event.point) >= DRAG_THRESHOLD_PX) {
-          return {
-            kind: "dragging",
-            mode: state.mode,
-            start: state.start,
-            current: event.point,
-            pinned: state.pinned
-          };
-        }
-        return state;
-      }
-      if (event.type === "POINTER_UP") {
-        if (!state.target) {
-          return resumeInspect(state.pinned, state.mode);
-        }
-        if (state.additive || state.mode === "multi") {
-          const nextPinned = togglePinned(state.pinned, state.target);
-          return {
-            kind: "inspect",
-            mode: state.mode,
-            hoverTarget: state.target,
-            pinned: nextPinned
-          };
-        }
-        return {
-          kind: "annotating",
-          selection: { kind: "single", element: state.target },
-          pinned: state.pinned
-        };
-      }
-      return state;
-    case "dragging":
-      if (event.type === "POINTER_MOVE") return { ...state, current: event.point };
-      if (event.type === "POINTER_UP") {
-        const rect = rectFromPoints(state.start, state.current);
-        const selection = { kind: "area", rect, elements: [] };
-        return { kind: "annotating", selection, pinned: state.pinned };
-      }
-      return state;
-    case "annotating":
-      if (event.type === "COMMIT") {
-        return resumeInspect([]);
-      }
-      return state;
-  }
-}
-function resumeInspect(pinned, mode) {
-  return {
-    kind: "inspect",
-    mode: mode ?? "single",
-    hoverTarget: null,
-    pinned
-  };
-}
-function togglePinned(pinned, el) {
-  const idx = pinned.indexOf(el);
-  if (idx === -1) return [...pinned, el];
-  const next = pinned.slice();
-  next.splice(idx, 1);
-  return next;
-}
-var SelectionEngine = class {
-  state = initialState;
-  listeners = /* @__PURE__ */ new Set();
-  doc;
-  host;
-  raf;
-  caf;
-  searchRoot;
-  pendingPointer = null;
-  rafHandle = null;
-  /** Guard for the pointermove RAF coalescer. Separate from `rafHandle`
-   *  because a synchronous `raf` (used in tests) returns a handle the cb
-   *  has already invalidated — boolean is the safe sentinel. */
-  rafPending = false;
-  attached = false;
-  boundHandlers = [];
-  constructor(deps = {}) {
-    this.doc = deps.document ?? (typeof document !== "undefined" ? document : null);
-    if (!this.doc) {
-      throw new Error("SelectionEngine: no Document available (pass `deps.document`).");
-    }
-    this.host = deps.host ?? null;
-    this.raf = deps.raf ?? ((cb) => typeof requestAnimationFrame !== "undefined" ? requestAnimationFrame(cb) : setTimeout(() => cb(performance.now()), 16));
-    this.caf = deps.caf ?? ((h) => {
-      if (typeof cancelAnimationFrame !== "undefined") cancelAnimationFrame(h);
-      else clearTimeout(h);
-    });
-    this.searchRoot = deps.searchRoot ?? this.doc.body;
-  }
-  /* ─── Subscribable<EngineState> ───────────────────────────────── */
-  subscribe(listener) {
-    this.listeners.add(listener);
-    return () => this.listeners.delete(listener);
-  }
-  getSnapshot() {
-    return this.state;
-  }
-  /* ─── Public control ──────────────────────────────────────────── */
-  activate(mode) {
-    perfMark("clickly:engine:activate");
-    this.dispatch(mode ? { type: "ACTIVATE", mode } : { type: "ACTIVATE" });
-    this.attach();
-  }
-  deactivate() {
-    perfMark("clickly:engine:deactivate");
-    this.detach();
-    this.dispatch({ type: "DEACTIVATE" });
-  }
-  setMode(mode) {
-    this.dispatch({ type: "MODE_CHANGE", mode });
-  }
-  commit() {
-    this.dispatch({ type: "COMMIT" });
-  }
-  clearPinned() {
-    this.dispatch({ type: "CLEAR_PINNED" });
-  }
-  /** Open the annotation popup populated with everything currently pinned. */
-  annotatePinned() {
-    this.dispatch({ type: "ANNOTATE_PINNED" });
-  }
-  /**
-   * Returns the resolved selection from the current annotating state, with
-   * area-mode element enumeration filled in (the reducer leaves it empty).
-   * Returns null if not currently annotating.
-   */
-  resolveSelection() {
-    if (this.state.kind !== "annotating") return null;
-    const sel = this.state.selection;
-    if (sel.kind !== "area") return sel;
-    const elements = pickElementsInRect(this.searchRoot, sel.rect, this.host);
-    return { ...sel, elements };
-  }
-  /* ─── Lifecycle ───────────────────────────────────────────────── */
-  attach() {
-    if (this.attached) return;
-    this.attached = true;
-    const win = this.doc.defaultView ?? globalThis;
-    this.bind(this.doc, "pointermove", this.onPointerMove, { passive: true });
-    this.bind(this.doc, "pointerdown", this.onPointerDown);
-    this.bind(this.doc, "pointerup", this.onPointerUp);
-    this.bind(win, "keydown", this.onKeyDown);
-  }
-  detach() {
-    if (!this.attached) return;
-    for (const [t, ev, fn, opts] of this.boundHandlers) t.removeEventListener(ev, fn, opts);
-    this.boundHandlers = [];
-    this.attached = false;
-    if (this.rafHandle !== null) {
-      this.caf(this.rafHandle);
-      this.rafHandle = null;
-    }
-    this.rafPending = false;
-  }
-  destroy() {
-    this.detach();
-    this.listeners.clear();
-  }
-  bind(target, ev, fn, opts) {
-    target.addEventListener(ev, fn, opts);
-    this.boundHandlers.push([target, ev, fn, opts]);
-  }
-  /* ─── DOM event handlers ──────────────────────────────────────── */
-  onPointerMove = (e) => {
-    this.pendingPointer = { x: e.clientX, y: e.clientY };
-    if (this.rafPending) return;
-    this.rafPending = true;
-    this.rafHandle = this.raf(() => {
-      this.rafPending = false;
-      this.rafHandle = null;
-      const pt = this.pendingPointer;
-      this.pendingPointer = null;
-      if (!pt) return;
-      const target = pickElementAt(this.doc, pt.x, pt.y, this.host);
-      this.dispatch({ type: "POINTER_MOVE", point: pt, target });
-    });
-  };
-  onPointerDown = (e) => {
-    if (this.host && e.composedPath().includes(this.host)) return;
-    const target = pickElementAt(this.doc, e.clientX, e.clientY, this.host);
-    this.dispatch({
-      type: "POINTER_DOWN",
-      point: { x: e.clientX, y: e.clientY },
-      target,
-      additive: e.shiftKey || e.metaKey || e.ctrlKey
-    });
-  };
-  onPointerUp = (e) => {
-    this.dispatch({ type: "POINTER_UP", point: { x: e.clientX, y: e.clientY } });
-  };
-  onKeyDown = (e) => {
-    if (e.key === "Escape") this.dispatch({ type: "ESCAPE" });
-  };
-  /* ─── Reducer plumbing ────────────────────────────────────────── */
-  dispatch(event) {
-    const next = reduce(this.state, event);
-    if (next === this.state) return;
-    this.state = next;
-    for (const l of this.listeners) l(next);
-  }
-};
-function perfMark(name) {
-  if (typeof performance !== "undefined" && typeof performance.mark === "function") {
-    try {
-      performance.mark(name);
-    } catch {
-    }
-  }
-}
-var OVERLAY_CSS = `
-:host {
-  --clickly-hover: #06b6d4;
-  --clickly-pinned: #f59e0b;
-  --clickly-selected: #10b981;
-  --clickly-marquee-stroke: #10b981;
-  --clickly-marquee-fill: rgba(16, 185, 129, 0.10);
-  --clickly-label-bg: rgba(15, 23, 42, 0.92);
-  --clickly-label-fg: #f8fafc;
-  --clickly-shadow: 0 0 0 1px rgba(255,255,255,0.5);
-
-  all: initial;
-  position: fixed;
-  inset: 0;
-  z-index: 2147483647;
-  pointer-events: none;
-  contain: layout style paint;
-  isolation: isolate;
-  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
-}
-
-.layer {
-  position: fixed;
-  left: 0;
-  top: 0;
-  width: 0;
-  height: 0;
-  pointer-events: none;
-  will-change: transform, width, height, opacity;
-}
-
-.marker {
-  position: fixed;
-  left: 0;
-  top: 0;
-  box-sizing: border-box;
-  border-radius: 2px;
-  pointer-events: none;
-  will-change: transform, width, height, opacity;
-  transition: opacity 80ms linear;
-}
-
-.marker[hidden] { display: none; }
-
-.marker.hover     { box-shadow: 0 0 0 2px var(--clickly-hover),     var(--clickly-shadow); }
-.marker.pinned    { box-shadow: 0 0 0 2px var(--clickly-pinned),    var(--clickly-shadow); }
-.marker.selected  { box-shadow: 0 0 0 2px var(--clickly-selected),  var(--clickly-shadow); }
-
-/* Marquee \u2014 used during drag (dashed) AND for the committed union
-   box around multi/area selections (solid).                          */
-.marker.marquee {
-  border: 2px dashed var(--clickly-marquee-stroke);
-  background: var(--clickly-marquee-fill);
-  border-radius: 8px;
-}
-.marker.marquee.is-committed {
-  border-style: solid;
-  box-shadow: 0 0 0 1px rgba(16, 185, 129, 0.18);
-}
-
-.label {
-  position: fixed;
-  left: 0;
-  top: 0;
-  padding: 2px 6px;
-  background: var(--clickly-label-bg);
-  color: var(--clickly-label-fg);
-  font-size: 11px;
-  line-height: 1.4;
-  border-radius: 4px;
-  white-space: nowrap;
-  pointer-events: none;
-  user-select: none;
-  max-width: 50vw;
-  overflow: hidden;
-  text-overflow: ellipsis;
-}
-`;
-var HOST_TAG = "clickly-root";
-function createShadowHost(deps = {}) {
-  const doc = deps.document ?? (typeof document !== "undefined" ? document : null);
-  if (!doc) throw new Error("createShadowHost: no Document available");
-  const existing = doc.querySelector(HOST_TAG);
-  const host = existing ?? doc.createElement(HOST_TAG);
-  if (!existing) doc.body.appendChild(host);
-  const root = host.shadowRoot ?? host.attachShadow({ mode: "open" });
-  if (!root.querySelector("style[data-clickly]")) {
-    const style = doc.createElement("style");
-    style.setAttribute("data-clickly", "");
-    style.textContent = OVERLAY_CSS;
-    root.appendChild(style);
-  }
-  return {
-    host,
-    root,
-    destroy() {
-      host.remove();
-    }
-  };
-}
-var OverlayRenderer = class {
-  root;
-  document;
-  layer;
-  hover;
-  hoverLabel;
-  /** Marquee rect — used both for live drag AND for the union box
-   *  drawn around multi-element selections after commit. */
-  marquee;
-  /** Pinned/selected single-element rings (recycled across renders). */
-  pinnedPool = [];
-  selectedPool = [];
-  /** Last rendered state — used to re-render on scroll without a state change. */
-  lastState = null;
-  constructor(root, document2) {
-    this.root = root;
-    this.document = document2 ?? root.ownerDocument ?? (typeof globalThis !== "undefined" && globalThis.document ? globalThis.document : null);
-    if (!this.document) throw new Error("OverlayRenderer: no Document available");
-    this.layer = this.div("layer");
-    this.root.appendChild(this.layer);
-    this.hover = this.div("marker hover");
-    this.hover.hidden = true;
-    this.layer.appendChild(this.hover);
-    this.hoverLabel = this.div("label");
-    this.hoverLabel.hidden = true;
-    this.layer.appendChild(this.hoverLabel);
-    this.marquee = this.div("marker marquee");
-    this.marquee.hidden = true;
-    this.layer.appendChild(this.marquee);
-    this.document.addEventListener("scroll", this.onScroll, {
-      passive: true,
-      capture: true
-    });
-  }
-  onScroll = () => {
-    if (this.lastState) this.renderState(this.lastState);
-  };
-  render(state) {
-    this.lastState = state;
-    this.renderState(state);
-  }
-  renderState(state) {
-    this.renderSingle(this.hover, state.hover);
-    if (state.hover) {
-      this.hoverLabel.hidden = false;
-      this.hoverLabel.textContent = describeElement(state.hover);
-      const rect = state.hover.getBoundingClientRect();
-      const labelY = rect.top - 20 < 0 ? rect.bottom + 4 : rect.top - 20;
-      moveTo(this.hoverLabel, rect.left, labelY);
-    } else {
-      this.hoverLabel.hidden = true;
-    }
-    this.renderList(this.pinnedPool, state.pinned, "marker pinned");
-    const sel = state.selection ?? [];
-    const isMultiUnion = sel.length > 1 || state.marquee !== null && sel.length === 0;
-    if (sel.length === 1) {
-      this.renderList(this.selectedPool, [sel[0]], "marker selected");
-    } else {
-      this.renderList(this.selectedPool, [], "marker selected");
-    }
-    const marqueeRect = state.marquee ?? (sel.length > 1 ? unionOf(sel) : null);
-    if (marqueeRect) {
-      this.marquee.classList.toggle("is-committed", state.marquee === null);
-      this.placeRect(this.marquee, marqueeRect);
-      this.marquee.hidden = false;
-    } else {
-      this.marquee.hidden = true;
-    }
-    void isMultiUnion;
-  }
-  destroy() {
-    this.document.removeEventListener("scroll", this.onScroll, { capture: true });
-    this.lastState = null;
-    this.layer.remove();
-  }
-  /* ─── Internals ───────────────────────────────────────────────── */
-  renderSingle(node, target) {
-    if (!target) {
-      node.hidden = true;
-      return;
-    }
-    const r = target.getBoundingClientRect();
-    if (r.width === 0 && r.height === 0) {
-      node.hidden = true;
-      return;
-    }
-    this.placeRect(node, { x: r.left, y: r.top, width: r.width, height: r.height });
-    node.hidden = false;
-  }
-  renderList(pool, targets, className) {
-    while (pool.length < targets.length) {
-      const el = this.div(className);
-      el.hidden = true;
-      this.layer.appendChild(el);
-      pool.push(el);
-    }
-    for (let i = 0; i < pool.length; i++) {
-      const node = pool[i];
-      const target = targets[i];
-      if (!target) {
-        node.hidden = true;
-        continue;
-      }
-      const r = target.getBoundingClientRect();
-      if (r.width === 0 && r.height === 0) {
-        node.hidden = true;
-        continue;
-      }
-      this.placeRect(node, { x: r.left, y: r.top, width: r.width, height: r.height });
-      node.hidden = false;
-    }
-  }
-  placeRect(node, rect) {
-    moveTo(node, rect.x, rect.y);
-    node.style.width = `${rect.width}px`;
-    node.style.height = `${rect.height}px`;
-  }
-  div(className) {
-    const el = this.document.createElement("div");
-    el.className = className;
-    return el;
-  }
-};
-function moveTo(node, x, y) {
-  const tx = Math.round(x);
-  const ty = Math.round(y);
-  node.style.transform = `translate3d(${tx}px, ${ty}px, 0)`;
-}
-var TAG_LABELS = {
-  p: "paragraph",
-  h1: "heading",
-  h2: "heading",
-  h3: "heading",
-  h4: "heading",
-  h5: "heading",
-  h6: "heading",
-  a: "link",
-  button: "button",
-  input: "input",
-  textarea: "textarea",
-  select: "select",
-  img: "image",
-  video: "video",
-  audio: "audio",
-  form: "form",
-  nav: "nav",
-  header: "header",
-  footer: "footer",
-  main: "main",
-  section: "section",
-  article: "article",
-  aside: "aside",
-  ul: "list",
-  ol: "list",
-  li: "list item",
-  table: "table",
-  thead: "table head",
-  tbody: "table body",
-  tr: "table row",
-  td: "cell",
-  th: "header cell",
-  span: "span",
-  div: "div",
-  label: "label",
-  code: "code",
-  pre: "code block",
-  blockquote: "quote",
-  strong: "bold",
-  em: "italic",
-  kbd: "key",
-  svg: "svg",
-  canvas: "canvas"
-};
-function describeElement(el) {
-  const tag = el.tagName.toLowerCase();
-  const type = TAG_LABELS[tag] ?? tag;
-  const text = (el.textContent ?? "").replace(/\s+/g, " ").trim();
-  if (text.length > 0) {
-    const preview = text.length > 48 ? text.slice(0, 48) + "\u2026" : text;
-    return `${type}: "${preview}"`;
-  }
-  if (el.id) return `${type}: #${el.id}`;
-  const cls = el.classList[0];
-  if (cls) return `${type}: .${cls}`;
-  return type;
-}
-function unionOf(elements) {
-  let minX = Infinity;
-  let minY = Infinity;
-  let maxX = -Infinity;
-  let maxY = -Infinity;
-  let any = false;
-  for (const el of elements) {
-    const r = el.getBoundingClientRect();
-    if (r.width === 0 && r.height === 0) continue;
-    any = true;
-    if (r.left < minX) minX = r.left;
-    if (r.top < minY) minY = r.top;
-    if (r.right > maxX) maxX = r.right;
-    if (r.bottom > maxY) maxY = r.bottom;
-  }
-  if (!any) return null;
-  const PAD = 4;
-  return {
-    x: minX - PAD,
-    y: minY - PAD,
-    width: maxX - minX + PAD * 2,
-    height: maxY - minY + PAD * 2
-  };
-}
-var emptyRenderState = {
-  hover: null,
-  pinned: [],
-  selection: null,
-  marquee: null
-};
-var Overlay = class {
-  renderer;
-  engine;
-  doc;
-  win;
-  searchRoot;
-  excludeHost;
-  raf;
-  caf;
-  state = emptyRenderState;
-  unsubscribe = null;
-  rafHandle = null;
-  /** Guard for scheduleRender re-entry. Tracked separately from `rafHandle`
-   *  because a synchronous `raf` (used in tests) returns a handle the cb has
-   *  already invalidated — boolean is the safe sentinel. */
-  renderPending = false;
-  destroyed = false;
-  bound = [];
-  constructor(opts) {
-    this.engine = opts.engine;
-    this.doc = opts.document ?? opts.root.ownerDocument ?? null;
-    if (!this.doc) throw new Error("Overlay: no Document available");
-    this.win = this.doc.defaultView ?? globalThis;
-    this.searchRoot = opts.searchRoot ?? this.doc.body;
-    this.excludeHost = opts.excludeHost ?? null;
-    this.raf = opts.raf ?? ((cb) => typeof requestAnimationFrame !== "undefined" ? requestAnimationFrame(cb) : setTimeout(() => cb(performance.now()), 16));
-    this.caf = opts.caf ?? ((h) => {
-      if (typeof cancelAnimationFrame !== "undefined") cancelAnimationFrame(h);
-      else clearTimeout(h);
-    });
-    this.renderer = new OverlayRenderer(opts.root, this.doc);
-    this.bindEvent(this.doc, "scroll", this.onReposition, { passive: true, capture: true });
-    this.bindEvent(this.win, "resize", this.onReposition, { passive: true });
-    this.unsubscribe = this.engine.subscribe((s) => this.onEngineState(s));
-    this.onEngineState(this.engine.getSnapshot());
-  }
-  destroy() {
-    this.destroyed = true;
-    if (this.unsubscribe) this.unsubscribe();
-    this.unsubscribe = null;
-    if (this.rafHandle !== null) this.caf(this.rafHandle);
-    this.rafHandle = null;
-    for (const [t, ev, fn, opts] of this.bound) t.removeEventListener(ev, fn, opts);
-    this.bound = [];
-    this.renderer.destroy();
-  }
-  /* ─── Internals ───────────────────────────────────────────────── */
-  onReposition = () => {
-    if (this.destroyed) return;
-    if (hasAnythingToTrack(this.state)) this.scheduleRender();
-  };
-  onEngineState(s) {
-    this.state = this.derive(s);
-    this.scheduleRender();
-  }
-  /** Engine state → render state. */
-  derive(s) {
-    switch (s.kind) {
-      case "idle":
-        return emptyRenderState;
-      case "inspect":
-        return { hover: s.hoverTarget, pinned: s.pinned, selection: null, marquee: null };
-      case "pressed":
-        return { hover: s.target, pinned: s.pinned, selection: null, marquee: null };
-      case "dragging": {
-        const rect = rectFromPoints(s.start, s.current);
-        return { hover: null, pinned: s.pinned, selection: null, marquee: rect };
-      }
-      case "annotating": {
-        const sel = s.selection;
-        const elements = sel.kind === "area" ? pickElementsInRect(this.searchRoot, sel.rect, this.excludeHost) : sel.kind === "multi" ? sel.elements : [sel.element];
-        return { hover: null, pinned: s.pinned, selection: elements, marquee: null };
-      }
-    }
-  }
-  scheduleRender() {
-    if (this.destroyed || this.renderPending) return;
-    this.renderPending = true;
-    this.rafHandle = this.raf(() => {
-      this.renderPending = false;
-      this.rafHandle = null;
-      if (this.destroyed) return;
-      this.renderer.render(this.state);
-    });
-  }
-  bindEvent(target, ev, fn, opts) {
-    target.addEventListener(ev, fn, opts);
-    this.bound.push([target, ev, fn, opts]);
-  }
-};
-function hasAnythingToTrack(s) {
-  return s.hover !== null || s.pinned.length > 0 || s.selection !== null && s.selection.length > 0 || s.marquee !== null;
-}
-var FIBER_PROP_PREFIX = "__reactFiber$";
-function getFiber(node) {
-  if (!node) return null;
-  for (const key of Object.keys(node)) {
-    if (key.startsWith(FIBER_PROP_PREFIX)) return node[key];
-  }
-  return null;
-}
-function getComponentChain(node) {
-  const fiber = getFiber(node);
-  if (!fiber) return [];
-  const names = [];
-  let cur = fiber;
-  while (cur) {
-    const name = getComponentName(cur);
-    if (name) names.unshift(name);
-    cur = cur.return;
-  }
-  return dedupeConsecutive(names);
-}
-function getComponentName(fiber) {
-  const t = fiber.type;
-  if (!t) return null;
-  if (typeof t === "string") return null;
-  if (typeof t === "function") {
-    const fn = t;
-    return fn.displayName || fn.name || null;
-  }
-  if (typeof t === "object") {
-    const o = t;
-    if (o.displayName) return o.displayName;
-    if (o.render) return o.render.displayName || o.render.name || null;
-    if (o.type) return o.type.displayName || o.type.name || null;
-  }
-  return null;
-}
-function dedupeConsecutive(names) {
-  const out = [];
-  for (const n of names) {
-    if (out[out.length - 1] !== n) out.push(n);
-  }
-  return out;
-}
-function getSourceInfo(node) {
-  const fiber = getFiber(node);
-  if (!fiber) return null;
-  let cur = fiber._debugOwner;
-  while (cur) {
-    if (cur._debugSource) return cur._debugSource;
-    cur = cur._debugOwner;
-  }
-  cur = fiber;
-  while (cur) {
-    if (cur._debugSource) return cur._debugSource;
-    cur = cur.return;
-  }
-  return null;
-}
-function collectAccessibility(el) {
-  const parts = [];
-  const role = el.getAttribute("role");
-  if (role) parts.push(`role=${role}`);
-  for (const attr of Array.from(el.attributes)) {
-    if (attr.name.startsWith("aria-") && attr.value) {
-      parts.push(`${attr.name}=${attr.value}`);
-    }
-  }
-  const tabindex = el.getAttribute("tabindex");
-  if (tabindex !== null && tabindex !== "") parts.push(`tabindex=${tabindex}`);
-  const title = el.getAttribute("title");
-  if (title) parts.push(`title=${title}`);
-  return parts.join("; ");
-}
-var GROUPS = {
-  layout: [
-    "display",
-    "position",
-    "top",
-    "right",
-    "bottom",
-    "left",
-    "width",
-    "height",
-    "margin",
-    "padding",
-    "box-sizing"
-  ],
-  visual: [
-    "color",
-    "background-color",
-    "border",
-    "border-radius",
-    "outline"
-  ],
-  text: [
-    "font-family",
-    "font-size",
-    "font-weight",
-    "line-height",
-    "letter-spacing",
-    "text-align",
-    "white-space"
-  ],
-  flexgrid: [
-    "flex-direction",
-    "justify-content",
-    "align-items",
-    "gap",
-    "grid-template-columns",
-    "grid-template-rows"
-  ],
-  effects: ["transform", "box-shadow", "filter"],
-  misc: ["cursor", "z-index", "overflow", "opacity", "transition", "animation"]
-};
-var TIER_GROUPS = {
-  compact: [],
-  standard: ["layout", "visual", "text"],
-  detailed: ["layout", "visual", "text", "flexgrid", "effects"],
-  forensic: ["layout", "visual", "text", "flexgrid", "effects", "misc"]
-};
-function collectComputedStyles(el, detail) {
-  if (detail === "compact") return {};
-  const doc = el.ownerDocument;
-  const win = doc?.defaultView ?? globalThis;
-  if (typeof win.getComputedStyle !== "function") return {};
-  const cs = win.getComputedStyle(el);
-  const props = /* @__PURE__ */ new Set();
-  for (const g of TIER_GROUPS[detail]) {
-    for (const p of GROUPS[g]) props.add(p);
-  }
-  const out = {};
-  for (const p of props) {
-    const v = cs.getPropertyValue(p);
-    if (!v) continue;
-    const trimmed = v.trim();
-    if (isUninterestingDefault(p, trimmed)) continue;
-    out[p] = trimmed;
-  }
-  return out;
-}
-function isUninterestingDefault(prop, value) {
-  if (!value || value === "none" || value === "auto" || value === "normal") return true;
-  if (value === "0px" || value === "0%") return true;
-  if (value === "rgba(0, 0, 0, 0)") return true;
-  if (prop === "color" || prop === "background-color") {
-    return value === "rgba(0, 0, 0, 0)";
-  }
-  return false;
-}
-var SHORT_MAX_DEPTH = 5;
-var FULL_MAX_DEPTH = 8;
-function buildSelector(target, doc = target.ownerDocument ?? document) {
-  if (target.id && isStableId(target.id)) {
-    const escaped = cssEscape(target.id);
-    const id = `#${escaped}`;
-    return { short: id, full: id };
-  }
-  const segments = [];
-  let cur = target;
-  let short = null;
-  for (let depth = 0; cur && depth < FULL_MAX_DEPTH; depth++) {
-    segments.unshift(segmentFor(cur));
-    const candidate = segments.join(" > ");
-    if (short === null && depth < SHORT_MAX_DEPTH && isUnique(doc, candidate)) {
-      short = candidate;
-    }
-    cur = cur.parentElement;
-    if (!cur || cur === doc.documentElement || cur.tagName.toLowerCase() === "html") break;
-  }
-  const full = segments.join(" > ");
-  return { short: short ?? full, full };
-}
-function segmentFor(el) {
-  const tag = el.tagName.toLowerCase();
-  if (el.id && isStableId(el.id)) return `${tag}#${cssEscape(el.id)}`;
-  const classes = Array.from(el.classList).filter(isUseableClass).slice(0, 3);
-  let segment = classes.length ? `${tag}.${classes.map(cssEscape).join(".")}` : tag;
-  const parent = el.parentElement;
-  if (parent) {
-    const sameTag = Array.from(parent.children).filter(
-      (c) => c.tagName === el.tagName
-    );
-    if (sameTag.length > 1) {
-      const idx = sameTag.indexOf(el) + 1;
-      if (idx > 0) segment += `:nth-of-type(${idx})`;
-    }
-  }
-  return segment;
-}
-function isUseableClass(c) {
-  if (!c) return false;
-  if (c.length > 30) return false;
-  if (/^css-[a-z0-9]+$/i.test(c)) return false;
-  if (/^jsx-\d+$/i.test(c)) return false;
-  if (/^_.+_[a-z0-9]{5,}$/i.test(c)) return false;
-  if (/^\d/.test(c)) return false;
-  return true;
-}
-function isStableId(id) {
-  if (/^:[a-z]\d+:/i.test(id)) return false;
-  if (/^radix-/i.test(id)) return false;
-  if (/^headlessui-/i.test(id)) return false;
-  return true;
-}
-function isUnique(doc, selector) {
-  try {
-    return doc.querySelectorAll(selector).length === 1;
-  } catch {
-    return false;
-  }
-}
-function cssEscape(s) {
-  const g = globalThis;
-  if (g.CSS?.escape) return g.CSS.escape(s);
-  return s.replace(/[^a-zA-Z0-9_-]/g, (c) => "\\" + c);
-}
-var NEARBY_MAX = 200;
-function collectNearbyText(el) {
-  const own = readText(el);
-  if (own) return truncate(own, NEARBY_MAX);
-  const parent = el.parentElement;
-  if (parent) {
-    const t = readText(parent);
-    if (t) return truncate(t, NEARBY_MAX);
-  }
-  return "";
-}
-function collectSelectedText(doc = document) {
-  const win = doc.defaultView ?? globalThis;
-  if (typeof win.getSelection !== "function") return "";
-  const sel = win.getSelection();
-  if (!sel) return "";
-  return sel.toString().trim();
-}
-function readText(el) {
-  const t = el.innerText ?? el.textContent ?? "";
-  return t.replace(/\s+/g, " ").trim();
-}
-function truncate(s, n) {
-  return s.length <= n ? s : s.slice(0, n - 1) + "\u2026";
-}
-var POSITIONED_FIXED = /* @__PURE__ */ new Set(["fixed", "sticky"]);
-function collectMetadata(el, options = {}) {
-  perfMark2("clickly:metadata:collect");
-  const detail = options.detail ?? "standard";
-  const includeReact = options.includeReact !== false && detail !== "compact";
-  const doc = options.document ?? el.ownerDocument ?? document;
-  const { short, full } = buildSelector(el, doc);
-  const rect = el.getBoundingClientRect();
-  const boundingBox = { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
-  const reactComponents = includeReact ? getComponentChain(el).join(" > ") : "";
-  const source = includeReact ? getSourceInfo(el) : null;
-  return {
-    element: el.tagName.toLowerCase(),
-    elementPath: short,
-    fullPath: full,
-    cssClasses: typeof el.className === "string" ? el.className.trim() : "",
-    computedStyles: collectComputedStyles(el, detail),
-    accessibility: collectAccessibility(el),
-    nearbyText: collectNearbyText(el),
-    selectedText: options.selectedText ?? collectSelectedText(doc),
-    boundingBox,
-    isFixed: hasFixedAncestor(el),
-    reactComponents,
-    sourceFile: source?.fileName ?? "",
-    sourceLine: source?.lineNumber ?? 0,
-    sourceColumn: source?.columnNumber ?? 0
-  };
-}
-function perfMark2(name) {
-  if (typeof performance !== "undefined" && typeof performance.mark === "function") {
-    try {
-      performance.mark(name);
-    } catch {
-    }
-  }
-}
-function hasFixedAncestor(el) {
-  const doc = el.ownerDocument;
-  const win = doc?.defaultView ?? globalThis;
-  if (typeof win.getComputedStyle !== "function") return false;
-  let cur = el;
-  for (let i = 0; cur && i < 8; i++) {
-    const pos = win.getComputedStyle(cur).getPropertyValue("position");
-    if (POSITIONED_FIXED.has(pos)) return true;
-    cur = cur.parentElement;
-  }
-  return false;
-}
-
-// packages/react/src/internal/ClicklyRoot.tsx
+// ../react/src/internal/ClicklyRoot.tsx
 import { useEffect as useEffect6, useState as useState6 } from "react";
 
-// packages/react/src/internal/Toolbar.tsx
+// ../react/src/internal/Toolbar.tsx
 import { useRef as useRef4, useState as useState3 } from "react";
 
-// packages/react/src/hooks/useDraggable.ts
+// ../react/src/hooks/useDraggable.ts
 import { useCallback, useEffect, useRef, useState } from "react";
 function useDraggable(defaultPos, size) {
   const [position, setPosition] = useState(defaultPos);
@@ -1078,7 +70,7 @@ function clamp(n, lo, hi) {
   return Math.max(lo, Math.min(hi, n));
 }
 
-// packages/react/src/state/useEngineState.ts
+// ../react/src/state/useEngineState.ts
 import { useSyncExternalStore } from "react";
 function useEngineState(engine) {
   return useSyncExternalStore(
@@ -1090,118 +82,9 @@ function useEngineState(engine) {
 }
 var IDLE = { kind: "idle" };
 
-// node_modules/.pnpm/zustand@5.0.14_@types+react@18.3.31_react@18.3.1/node_modules/zustand/esm/vanilla.mjs
-var createStoreImpl = (createState) => {
-  let state;
-  const listeners = /* @__PURE__ */ new Set();
-  const setState = (partial, replace) => {
-    const nextState = typeof partial === "function" ? partial(state) : partial;
-    if (!Object.is(nextState, state)) {
-      const previousState = state;
-      state = (replace != null ? replace : typeof nextState !== "object" || nextState === null) ? nextState : Object.assign({}, state, nextState);
-      listeners.forEach((listener) => listener(state, previousState));
-    }
-  };
-  const getState = () => state;
-  const getInitialState = () => initialState2;
-  const subscribe = (listener) => {
-    listeners.add(listener);
-    return () => listeners.delete(listener);
-  };
-  const api = { setState, getState, getInitialState, subscribe };
-  const initialState2 = state = createState(setState, getState, api);
-  return api;
-};
-var createStore = ((createState) => createState ? createStoreImpl(createState) : createStoreImpl);
-
-// node_modules/.pnpm/zustand@5.0.14_@types+react@18.3.31_react@18.3.1/node_modules/zustand/esm/react.mjs
-import React from "react";
-var identity = (arg) => arg;
-function useStore(api, selector = identity) {
-  const slice = React.useSyncExternalStore(
-    api.subscribe,
-    React.useCallback(() => selector(api.getState()), [api, selector]),
-    React.useCallback(() => selector(api.getInitialState()), [api, selector])
-  );
-  React.useDebugValue(slice);
-  return slice;
-}
-var createImpl = (createState) => {
-  const api = createStore(createState);
-  const useBoundStore = (selector) => useStore(api, selector);
-  Object.assign(useBoundStore, api);
-  return useBoundStore;
-};
-var create = ((createState) => createState ? createImpl(createState) : createImpl);
-
-// node_modules/.pnpm/zustand@5.0.14_@types+react@18.3.31_react@18.3.1/node_modules/zustand/esm/react/shallow.mjs
-import React2 from "react";
-
-// node_modules/.pnpm/zustand@5.0.14_@types+react@18.3.31_react@18.3.1/node_modules/zustand/esm/vanilla/shallow.mjs
-var isIterable = (obj) => Symbol.iterator in obj;
-var hasIterableEntries = (value) => (
-  // HACK: avoid checking entries type
-  "entries" in value
-);
-var compareEntries = (valueA, valueB) => {
-  const mapA = valueA instanceof Map ? valueA : new Map(valueA.entries());
-  const mapB = valueB instanceof Map ? valueB : new Map(valueB.entries());
-  if (mapA.size !== mapB.size) {
-    return false;
-  }
-  for (const [key, value] of mapA) {
-    if (!mapB.has(key) || !Object.is(value, mapB.get(key))) {
-      return false;
-    }
-  }
-  return true;
-};
-var compareIterables = (valueA, valueB) => {
-  const iteratorA = valueA[Symbol.iterator]();
-  const iteratorB = valueB[Symbol.iterator]();
-  let nextA = iteratorA.next();
-  let nextB = iteratorB.next();
-  while (!nextA.done && !nextB.done) {
-    if (!Object.is(nextA.value, nextB.value)) {
-      return false;
-    }
-    nextA = iteratorA.next();
-    nextB = iteratorB.next();
-  }
-  return !!nextA.done && !!nextB.done;
-};
-function shallow(valueA, valueB) {
-  if (Object.is(valueA, valueB)) {
-    return true;
-  }
-  if (typeof valueA !== "object" || valueA === null || typeof valueB !== "object" || valueB === null) {
-    return false;
-  }
-  if (Object.getPrototypeOf(valueA) !== Object.getPrototypeOf(valueB)) {
-    return false;
-  }
-  if (isIterable(valueA) && isIterable(valueB)) {
-    if (hasIterableEntries(valueA) && hasIterableEntries(valueB)) {
-      return compareEntries(valueA, valueB);
-    }
-    return compareIterables(valueA, valueB);
-  }
-  return compareEntries(
-    { entries: () => Object.entries(valueA) },
-    { entries: () => Object.entries(valueB) }
-  );
-}
-
-// node_modules/.pnpm/zustand@5.0.14_@types+react@18.3.31_react@18.3.1/node_modules/zustand/esm/react/shallow.mjs
-function useShallow(selector) {
-  const prev = React2.useRef(void 0);
-  return (state) => {
-    const next = selector(state);
-    return shallow(prev.current, next) ? prev.current : prev.current = next;
-  };
-}
-
-// packages/react/src/state/annotations.ts
+// ../react/src/state/annotations.ts
+import { create } from "zustand";
+import { useShallow } from "zustand/react/shallow";
 var useAnnotations = create((set, get) => ({
   byId: {},
   order: [],
@@ -1232,7 +115,8 @@ function useAnnotationsList() {
   );
 }
 
-// packages/react/src/state/settings.ts
+// ../react/src/state/settings.ts
+import { create as create2 } from "zustand";
 var DEFAULTS = {
   outputDetail: "standard",
   copyOnAdd: true,
@@ -1258,7 +142,7 @@ function persist(s) {
   } catch {
   }
 }
-var useSettings = create((set) => ({
+var useSettings = create2((set) => ({
   ...load(),
   set: (patch) => set((cur) => {
     const next = { ...cur, ...patch };
@@ -1271,7 +155,7 @@ var useSettings = create((set) => ({
   }
 }));
 
-// packages/react/src/output/markdown.ts
+// ../react/src/output/markdown.ts
 function annotationsToMarkdown(annotations, detail = "standard") {
   if (!annotations.length) return "(no annotations)";
   return annotations.map((a, i) => formatOne(a, i + 1, detail)).join("\n\n");
@@ -1294,7 +178,7 @@ function formatOne(a, index, detail) {
   }
   if (detail === "detailed" || detail === "forensic") {
     if (a.reactComponents) lines.push(`**React:** ${a.reactComponents}`);
-    if (a.nearbyText) lines.push(`**Nearby text:** ${truncate2(a.nearbyText, 120)}`);
+    if (a.nearbyText) lines.push(`**Nearby text:** ${truncate(a.nearbyText, 120)}`);
   }
   if (detail === "forensic" && a.computedStyles) {
     lines.push("**Computed styles:**\n```css\n" + a.computedStyles + "\n```");
@@ -1306,11 +190,11 @@ function formatOne(a, index, detail) {
   if (a.severity) lines.push(`**Severity:** ${a.severity}`);
   return lines.join("\n");
 }
-function truncate2(s, n) {
+function truncate(s, n) {
   return s.length <= n ? s : s.slice(0, n - 1) + "\u2026";
 }
 
-// packages/react/src/internal/icons.tsx
+// ../react/src/internal/icons.tsx
 import { jsx, jsxs } from "react/jsx-runtime";
 function Icon({
   children,
@@ -1332,6 +216,18 @@ function Icon({
     }
   );
 }
+var IconFreeze = () => /* @__PURE__ */ jsxs(Icon, { size: 15, children: [
+  /* @__PURE__ */ jsx("line", { x1: "12", y1: "2", x2: "12", y2: "22" }),
+  /* @__PURE__ */ jsx("line", { x1: "2", y1: "12", x2: "22", y2: "12" }),
+  /* @__PURE__ */ jsx("line", { x1: "5", y1: "5", x2: "19", y2: "19" }),
+  /* @__PURE__ */ jsx("line", { x1: "19", y1: "5", x2: "5", y2: "19" }),
+  /* @__PURE__ */ jsx("circle", { cx: "12", cy: "12", r: "2", fill: "currentColor", stroke: "none" })
+] });
+var IconInfo = () => /* @__PURE__ */ jsxs(Icon, { size: 14, children: [
+  /* @__PURE__ */ jsx("circle", { cx: "12", cy: "12", r: "10" }),
+  /* @__PURE__ */ jsx("line", { x1: "12", y1: "8", x2: "12", y2: "8", strokeWidth: "2.5" }),
+  /* @__PURE__ */ jsx("line", { x1: "12", y1: "12", x2: "12", y2: "16" })
+] });
 var IconCursor = () => /* @__PURE__ */ jsx(Icon, { children: /* @__PURE__ */ jsx("path", { d: "M4 4l6 16 2-7 7-2z" }) });
 var IconLayers = () => /* @__PURE__ */ jsxs(Icon, { children: [
   /* @__PURE__ */ jsx("path", { d: "M12 2l9 5-9 5-9-5 9-5z" }),
@@ -1359,7 +255,7 @@ var IconClose = () => /* @__PURE__ */ jsx(Icon, { children: /* @__PURE__ */ jsx(
 var IconCheck = () => /* @__PURE__ */ jsx(Icon, { children: /* @__PURE__ */ jsx("path", { d: "M5 12l5 5L20 7" }) });
 var IconList = () => /* @__PURE__ */ jsx(Icon, { children: /* @__PURE__ */ jsx("path", { d: "M8 6h13M8 12h13M8 18h13M3 6h.01M3 12h.01M3 18h.01" }) });
 
-// packages/react/src/internal/SettingsPopover.tsx
+// ../react/src/internal/SettingsPopover.tsx
 import { useEffect as useEffect2, useRef as useRef2 } from "react";
 import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
 function SettingsPopover({ anchor, width, onClose }) {
@@ -1460,7 +356,7 @@ function SettingsPopover({ anchor, width, onClose }) {
   ] });
 }
 
-// packages/react/src/internal/AnnotationList.tsx
+// ../react/src/internal/AnnotationList.tsx
 import { useEffect as useEffect3, useRef as useRef3, useState as useState2 } from "react";
 import { jsx as jsx3, jsxs as jsxs3 } from "react/jsx-runtime";
 function AnnotationList({ anchor, width, onClose }) {
@@ -1548,9 +444,48 @@ function AnnotationCard({
   ] });
 }
 
-// packages/react/src/internal/Toolbar.tsx
+// ../react/src/internal/Toolbar.tsx
 import { Fragment, jsx as jsx4, jsxs as jsxs4 } from "react/jsx-runtime";
-var TOOLBAR_SIZE = { width: 320, height: 44 };
+var TOOLBAR_SIZE = { width: 360, height: 44 };
+var SHORTCUTS = [
+  { keys: ["\u2318", "\u21E7", "F"], label: "Toggle toolbar" },
+  { keys: ["1"], label: "Single select mode" },
+  { keys: ["2"], label: "Multi select mode" },
+  { keys: ["3"], label: "Area drag mode" },
+  { keys: ["\u21B5"], label: "Annotate pinned elements" },
+  { keys: ["Esc"], label: "Cancel / clear / close" },
+  { keys: ["\u2318", "\u21B5"], label: "Submit annotation" },
+  { keys: ["C"], label: "Copy all annotations" },
+  { keys: ["X"], label: "Clear all annotations" }
+];
+function ShortcutsPanel() {
+  const [visible, setVisible] = useState3(false);
+  return /* @__PURE__ */ jsxs4(
+    "span",
+    {
+      className: "clickly-tip shortcuts-trigger",
+      onMouseEnter: () => setVisible(true),
+      onMouseLeave: () => setVisible(false),
+      children: [
+        /* @__PURE__ */ jsx4(
+          "button",
+          {
+            className: "clickly-btn icon-only",
+            "aria-label": "Show keyboard shortcuts",
+            children: /* @__PURE__ */ jsx4(IconInfo, {})
+          }
+        ),
+        visible && /* @__PURE__ */ jsxs4("div", { className: "shortcuts-panel", role: "tooltip", children: [
+          /* @__PURE__ */ jsx4("div", { className: "shortcuts-title", children: "Keyboard shortcuts" }),
+          SHORTCUTS.map((s) => /* @__PURE__ */ jsxs4("div", { className: "shortcuts-row", children: [
+            /* @__PURE__ */ jsx4("span", { className: "shortcuts-label", children: s.label }),
+            /* @__PURE__ */ jsx4("span", { className: "shortcuts-keys", children: s.keys.map((k) => /* @__PURE__ */ jsx4("kbd", { children: k }, k)) })
+          ] }, s.label))
+        ] })
+      ]
+    }
+  );
+}
 function Tip({
   label,
   shortcut,
@@ -1564,7 +499,7 @@ function Tip({
     ] })
   ] });
 }
-function Toolbar({ engine, onCollapse }) {
+function Toolbar({ engine, onCollapse, isClosing, onCloseEnd, frozen, onFreezeToggle }) {
   const state = useEngineState(engine);
   const annotations = useAnnotationsList();
   const clearAnnotations = useAnnotations((s) => s.clear);
@@ -1597,8 +532,9 @@ function Toolbar({ engine, onCollapse }) {
     "div",
     {
       ref: anchorRef,
-      className: "clickly-toolbar",
+      className: `clickly-toolbar${isClosing ? " is-closing" : ""}`,
       style: { left: position.x, top: position.y, width: TOOLBAR_SIZE.width },
+      onAnimationEnd: isClosing ? onCloseEnd : void 0,
       "aria-label": "Clickly toolbar",
       children: [
         /* @__PURE__ */ jsx4(Tip, { label: "Move", children: /* @__PURE__ */ jsx4(
@@ -1654,6 +590,16 @@ function Toolbar({ engine, onCollapse }) {
           ) }),
           /* @__PURE__ */ jsx4("div", { className: "divider" })
         ] }),
+        /* @__PURE__ */ jsx4(Tip, { label: frozen ? "Unfreeze animations" : "Freeze animations", children: /* @__PURE__ */ jsx4(
+          "button",
+          {
+            className: `clickly-btn icon-only${frozen ? " is-freeze" : ""}`,
+            onClick: onFreezeToggle,
+            "aria-label": frozen ? "Unfreeze page animations" : "Freeze page animations",
+            "aria-pressed": frozen,
+            children: /* @__PURE__ */ jsx4(IconFreeze, {})
+          }
+        ) }),
         /* @__PURE__ */ jsx4(Tip, { label: "Annotations", shortcut: "L", children: /* @__PURE__ */ jsxs4(
           "button",
           {
@@ -1687,6 +633,7 @@ function Toolbar({ engine, onCollapse }) {
           }
         ) }),
         /* @__PURE__ */ jsx4("div", { className: "divider" }),
+        /* @__PURE__ */ jsx4(ShortcutsPanel, {}),
         /* @__PURE__ */ jsx4(Tip, { label: "Settings", children: /* @__PURE__ */ jsx4(
           "button",
           {
@@ -1727,7 +674,7 @@ function Toolbar({ engine, onCollapse }) {
   );
 }
 
-// packages/react/src/internal/CollapsedFAB.tsx
+// ../react/src/internal/CollapsedFAB.tsx
 import { jsx as jsx5, jsxs as jsxs5 } from "react/jsx-runtime";
 function CollapsedFAB({ onExpand }) {
   const annotations = useAnnotationsList();
@@ -1746,9 +693,27 @@ function CollapsedFAB({ onExpand }) {
   );
 }
 
-// packages/react/src/internal/AnnotationPopup.tsx
+// ../react/src/internal/AnnotationPopup.tsx
 import { useCallback as useCallback2, useEffect as useEffect4, useRef as useRef5, useState as useState4 } from "react";
-import { nanoid } from "nanoid";
+
+// ../../node_modules/.pnpm/nanoid@5.1.16/node_modules/nanoid/url-alphabet/index.js
+var urlAlphabet = "useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict";
+
+// ../../node_modules/.pnpm/nanoid@5.1.16/node_modules/nanoid/index.browser.js
+var nanoid = (size = 21) => {
+  let id = "";
+  let bytes = crypto.getRandomValues(new Uint8Array(size |= 0));
+  while (size--) {
+    id += urlAlphabet[bytes[size] & 63];
+  }
+  return id;
+};
+
+// ../react/src/internal/AnnotationPopup.tsx
+import {
+  collectMetadata,
+  collectComputedStyles
+} from "@useclickly/core";
 import { jsx as jsx6, jsxs as jsxs6 } from "react/jsx-runtime";
 var POPUP_W = 320;
 var POPUP_H_EST = 240;
@@ -2024,7 +989,7 @@ function anchorRect(sel) {
   if (sel.elements.length === 0) return null;
   return sel.elements[0].getBoundingClientRect();
 }
-var TAG_LABELS2 = {
+var TAG_LABELS = {
   p: "paragraph",
   h1: "heading",
   h2: "heading",
@@ -2066,9 +1031,9 @@ var TAG_LABELS2 = {
   svg: "svg",
   canvas: "canvas"
 };
-function describeElement2(el) {
+function describeElement(el) {
   const tag = el.tagName.toLowerCase();
-  const type = TAG_LABELS2[tag] ?? tag;
+  const type = TAG_LABELS[tag] ?? tag;
   const text = (el.textContent ?? "").replace(/\s+/g, " ").trim();
   if (text.length > 0) {
     const preview = text.length > 48 ? text.slice(0, 48) + "\u2026" : text;
@@ -2080,13 +1045,13 @@ function describeElement2(el) {
   return type;
 }
 function describeSelection(sel) {
-  if (sel.kind === "single") return describeElement2(sel.element);
+  if (sel.kind === "single") return describeElement(sel.element);
   if (sel.kind === "area") return `area \xB7 ${sel.elements.length} element(s)`;
-  if (sel.elements.length === 1) return describeElement2(sel.elements[0]);
+  if (sel.elements.length === 1) return describeElement(sel.elements[0]);
   return `${sel.elements.length} element(s)`;
 }
 
-// packages/react/src/internal/AnnotationPins.tsx
+// ../react/src/internal/AnnotationPins.tsx
 import { useEffect as useEffect5, useRef as useRef6, useState as useState5 } from "react";
 import { Fragment as Fragment2, jsx as jsx7, jsxs as jsxs7 } from "react/jsx-runtime";
 function AnnotationPins() {
@@ -2111,7 +1076,7 @@ function AnnotationPins() {
   }, []);
   return /* @__PURE__ */ jsx7(Fragment2, { children: annotations.map((a, i) => /* @__PURE__ */ jsx7(Pin, { number: i + 1, annotation: a }, a.id)) });
 }
-var TAG_LABELS3 = {
+var TAG_LABELS2 = {
   p: "paragraph",
   h1: "heading",
   h2: "heading",
@@ -2151,7 +1116,7 @@ var TAG_LABELS3 = {
 function pinLabel(annotation) {
   const raw = (annotation.element ?? "").toLowerCase();
   const tag = raw.split(/[.#\s]/)[0] ?? "";
-  return (TAG_LABELS3[tag] ?? tag) || "element";
+  return (TAG_LABELS2[tag] ?? tag) || "element";
 }
 function parseStyles(raw) {
   if (!raw) return [];
@@ -2329,13 +1294,22 @@ function resolvePosition(a) {
   return null;
 }
 
-// packages/react/src/internal/ClicklyRoot.tsx
+// ../react/src/internal/ClicklyRoot.tsx
 import { Fragment as Fragment3, jsx as jsx8, jsxs as jsxs8 } from "react/jsx-runtime";
 function ClicklyRoot({
   engine,
   host
 }) {
   const [expanded, setExpanded] = useState6(false);
+  const [toolbarClosing, setToolbarClosing] = useState6(false);
+  const [frozen, setFrozen] = useState6(false);
+  const collapse = () => {
+    setToolbarClosing(true);
+  };
+  const onToolbarCloseEnd = () => {
+    setToolbarClosing(false);
+    setExpanded(false);
+  };
   const clearAnnotations = useAnnotations((s) => s.clear);
   const outputDetail = useSettings((s) => s.outputDetail);
   const markerColor = useSettings((s) => s.markerColor);
@@ -2343,6 +1317,32 @@ function ClicklyRoot({
   useEffect6(() => {
     host.style.setProperty("--clickly-hover", markerColor);
   }, [host, markerColor]);
+  useEffect6(() => {
+    const STYLE_ID = "clickly-freeze-animations";
+    const gsap = window.gsap;
+    if (frozen) {
+      if (!document.getElementById(STYLE_ID)) {
+        const el = document.createElement("style");
+        el.id = STYLE_ID;
+        el.textContent = `
+          *, *::before, *::after {
+            animation-play-state: paused !important;
+            transition-duration: 0ms !important;
+            transition-delay: 0ms !important;
+          }
+        `;
+        document.head.appendChild(el);
+      }
+      if (gsap?.globalTimeline) gsap.globalTimeline.pause();
+    } else {
+      document.getElementById(STYLE_ID)?.remove();
+      if (gsap?.globalTimeline) gsap.globalTimeline.resume();
+    }
+    return () => {
+      document.getElementById(STYLE_ID)?.remove();
+      if (gsap?.globalTimeline) gsap.globalTimeline.resume();
+    };
+  }, [frozen]);
   useEffect6(() => {
     if (expanded) {
       if (engine.getSnapshot().kind === "idle") engine.activate("single");
@@ -2377,12 +1377,13 @@ function ClicklyRoot({
       if (active && (active.tagName === "TEXTAREA" || active.tagName === "INPUT")) return;
       if (e.key.toLowerCase() === "f" && e.shiftKey && (e.metaKey || e.ctrlKey)) {
         e.preventDefault();
-        setExpanded((v) => !v);
+        if (expanded) collapse();
+        else setExpanded(true);
         return;
       }
       if (e.key === "Escape") {
         if (engine.getSnapshot().kind === "annotating") return;
-        if (expanded) setExpanded(false);
+        if (expanded) collapse();
         return;
       }
       if (!expanded) return;
@@ -2413,14 +1414,24 @@ function ClicklyRoot({
   }, [clearAnnotations, outputDetail, expanded, engine]);
   return /* @__PURE__ */ jsxs8("div", { className: "clickly-ui", children: [
     /* @__PURE__ */ jsx8(AnnotationPins, {}),
-    expanded ? /* @__PURE__ */ jsxs8(Fragment3, { children: [
-      /* @__PURE__ */ jsx8(Toolbar, { engine, onCollapse: () => setExpanded(false) }),
-      /* @__PURE__ */ jsx8(AnnotationPopup, { engine })
+    expanded || toolbarClosing ? /* @__PURE__ */ jsxs8(Fragment3, { children: [
+      /* @__PURE__ */ jsx8(
+        Toolbar,
+        {
+          engine,
+          onCollapse: collapse,
+          isClosing: toolbarClosing,
+          onCloseEnd: onToolbarCloseEnd,
+          frozen,
+          onFreezeToggle: () => setFrozen((v) => !v)
+        }
+      ),
+      !toolbarClosing && /* @__PURE__ */ jsx8(AnnotationPopup, { engine })
     ] }) : /* @__PURE__ */ jsx8(CollapsedFAB, { onExpand: () => setExpanded(true) })
   ] });
 }
 
-// packages/react/src/internal/styles.ts
+// ../react/src/internal/styles.ts
 var REACT_UI_CSS = `
 .clickly-ui, .clickly-ui * { box-sizing: border-box; }
 
@@ -2446,6 +1457,11 @@ var REACT_UI_CSS = `
     0 0 0 1px rgba(255,255,255,0.06) inset;
   transition: transform 140ms ease, box-shadow 140ms ease;
   z-index: 1;
+  animation: clickly-fab-open 280ms cubic-bezier(0.34, 1.56, 0.64, 1) both;
+}
+@keyframes clickly-fab-open {
+  from { opacity: 0; transform: scale(0.5); }
+  to   { opacity: 1; transform: scale(1); }
 }
 .clickly-fab:hover {
   transform: scale(1.06);
@@ -2492,12 +1508,21 @@ var REACT_UI_CSS = `
   pointer-events: auto;
   user-select: none;
   z-index: 1;
-  animation: clickly-fade-in 150ms cubic-bezier(0.16, 1, 0.3, 1);
+  transform-origin: bottom right;
+  animation: clickly-toolbar-open 240ms cubic-bezier(0.16, 1, 0.3, 1) both;
+}
+.clickly-toolbar.is-closing {
+  animation: clickly-toolbar-close 200ms cubic-bezier(0.4, 0, 1, 1) both;
+  pointer-events: none;
 }
 
-@keyframes clickly-fade-in {
-  from { opacity: 0; transform: translateY(6px) scale(0.97); }
-  to   { opacity: 1; transform: translateY(0) scale(1); }
+@keyframes clickly-toolbar-open {
+  from { opacity: 0; transform: scale(0.82) translateY(10px); }
+  to   { opacity: 1; transform: scale(1) translateY(0); }
+}
+@keyframes clickly-toolbar-close {
+  from { opacity: 1; transform: scale(1) translateY(0); }
+  to   { opacity: 0; transform: scale(0.82) translateY(10px); }
 }
 
 .clickly-toolbar .grip {
@@ -2548,6 +1573,14 @@ var REACT_UI_CSS = `
 .clickly-btn.is-active:hover { background: #0284c7; }
 .clickly-btn[disabled] { opacity: 0.28; cursor: not-allowed; pointer-events: none; }
 
+/* Freeze-animations active state \u2014 icy blue */
+.clickly-btn.is-freeze {
+  background: rgba(99, 179, 237, 0.18);
+  color: #63b3ed;
+  box-shadow: 0 0 0 1px rgba(99,179,237,0.35), 0 2px 8px rgba(99,179,237,0.2);
+}
+.clickly-btn.is-freeze:hover { background: rgba(99, 179, 237, 0.26); }
+
 .clickly-btn.icon-only {
   width: 32px;
   padding: 0;
@@ -2625,6 +1658,91 @@ var REACT_UI_CSS = `
   color: #94a3b8;
 }
 
+/* \u2500\u2500\u2500 Shortcuts panel \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
+
+.shortcuts-trigger {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.shortcuts-panel {
+  position: absolute;
+  bottom: calc(100% + 12px);
+  left: 50%;
+  transform: translateX(-50%);
+  width: 260px;
+  background: rgba(9, 14, 28, 0.97);
+  border: 1px solid rgba(255,255,255,0.08);
+  border-radius: 12px;
+  box-shadow: 0 16px 40px rgba(0,0,0,0.45);
+  padding: 10px;
+  z-index: 10;
+  animation: clickly-fade-in 100ms ease-out;
+  pointer-events: none;
+}
+
+/* Arrow pointing down */
+.shortcuts-panel::after {
+  content: "";
+  position: absolute;
+  top: 100%;
+  left: 50%;
+  transform: translateX(-50%);
+  border: 6px solid transparent;
+  border-top-color: rgba(9, 14, 28, 0.97);
+}
+
+.shortcuts-title {
+  font: 600 11px/1 -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
+  color: #64748b;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  padding: 2px 4px 8px;
+  border-bottom: 1px solid rgba(255,255,255,0.06);
+  margin-bottom: 6px;
+}
+
+.shortcuts-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 4px 4px;
+  border-radius: 6px;
+  gap: 8px;
+}
+.shortcuts-row:hover { background: rgba(255,255,255,0.04); }
+
+.shortcuts-label {
+  font: 12px/1.4 -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
+  color: #94a3b8;
+  flex: 1;
+  min-width: 0;
+}
+
+.shortcuts-keys {
+  display: flex;
+  gap: 3px;
+  align-items: center;
+  flex-shrink: 0;
+}
+
+.shortcuts-keys kbd {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 20px;
+  height: 20px;
+  padding: 0 5px;
+  background: rgba(255,255,255,0.08);
+  border: 1px solid rgba(255,255,255,0.10);
+  border-bottom-width: 2px;
+  border-radius: 5px;
+  font: 11px/1 ui-monospace, "SF Mono", Menlo, monospace;
+  color: #e2e8f0;
+}
+
 /* \u2500\u2500\u2500 Popup & popovers \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
 
 .clickly-popup, .clickly-popover {
@@ -3376,7 +2494,7 @@ var REACT_UI_CSS = `
 }
 `;
 
-// packages/react/src/internal/globalStyles.ts
+// ../react/src/internal/globalStyles.ts
 var GLOBAL_PAGE_CSS = `
 body[data-clickly-active] {
   -webkit-user-select: none !important;
@@ -3397,7 +2515,7 @@ body[data-clickly-annotating] {
 }
 `;
 
-// packages/react/src/Clickly.tsx
+// ../react/src/Clickly.tsx
 import { jsx as jsx9 } from "react/jsx-runtime";
 function Clickly({ className } = {}) {
   const [mount, setMount] = useState7(null);