From 2d2599d2c202c3db9160970575380a5dd0544771 Mon Sep 17 00:00:00 2001
From: Thomas <thomas.whyyou@gmail.com>
Date: Wed, 25 Feb 2026 23:01:21 -0500
Subject: [PATCH 1/5] make the toolbar draggable

---
 .../guide/components/Toolbar/KnockButton.tsx  |  13 +-
 .../components/Toolbar/V2/DragHandle.tsx      |  38 +++
 .../guide/components/Toolbar/V2/V2.tsx        |  23 +-
 .../guide/components/Toolbar/V2/useDrag.ts    | 154 +++++++++++
 .../test/guide/Toolbar/V2/useDrag.test.ts     | 251 ++++++++++++++++++
 5 files changed, 472 insertions(+), 7 deletions(-)
 create mode 100644 packages/react/src/modules/guide/components/Toolbar/V2/DragHandle.tsx
 create mode 100644 packages/react/src/modules/guide/components/Toolbar/V2/useDrag.ts
 create mode 100644 packages/react/test/guide/Toolbar/V2/useDrag.test.ts

diff --git a/packages/react/src/modules/guide/components/Toolbar/KnockButton.tsx b/packages/react/src/modules/guide/components/Toolbar/KnockButton.tsx
index 31462a59f..dca4d4b41 100644
--- a/packages/react/src/modules/guide/components/Toolbar/KnockButton.tsx
+++ b/packages/react/src/modules/guide/components/Toolbar/KnockButton.tsx
@@ -5,15 +5,19 @@ import "./styles.css";
 
 type Props = {
   onClick: () => void;
+  positioned?: boolean;
 };
 
-export const KnockButton = ({ onClick }: Props) => {
+export const KnockButton = ({ onClick, positioned = true }: Props) => {
   return (
     <Button
       onClick={onClick}
-      position="fixed"
-      top="4"
-      right="4"
+      {...(positioned && {
+        position: "fixed" as const,
+        top: "4" as const,
+        right: "4" as const,
+        style: { zIndex: TOOLBAR_Z_INDEX },
+      })}
       bg="surface-2"
       shadow="3"
       rounded="3"
@@ -22,7 +26,6 @@ export const KnockButton = ({ onClick }: Props) => {
       variant="soft"
       data-tgph-appearance="dark"
       aria-label="Expand guide toolbar"
-      style={{ zIndex: TOOLBAR_Z_INDEX }}
     >
       <svg
         width="40"
diff --git a/packages/react/src/modules/guide/components/Toolbar/V2/DragHandle.tsx b/packages/react/src/modules/guide/components/Toolbar/V2/DragHandle.tsx
new file mode 100644
index 000000000..44a40d64a
--- /dev/null
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/DragHandle.tsx
@@ -0,0 +1,38 @@
+import { Box } from "@telegraph/layout";
+import { GripVertical } from "lucide-react";
+import React from "react";
+
+/** How far the drag handle protrudes beyond the toolbar's right edge (px). */
+export const DRAG_HANDLE_OVERHANG = 28;
+
+type DragHandleProps = {
+  onPointerDown: (e: React.PointerEvent) => void;
+  isDragging: boolean;
+};
+
+export const DragHandle = ({ onPointerDown, isDragging }: DragHandleProps) => {
+  return (
+    <Box
+      data-tgph-appearance="dark"
+      onPointerDown={onPointerDown}
+      style={{
+        position: "absolute",
+        top: "-4px",
+        right: "-28px",
+        width: "24px",
+        height: "28px",
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        cursor: isDragging ? "grabbing" : "grab",
+        touchAction: "none",
+        userSelect: "none",
+        backgroundColor: "var(--tgph-surface-2)",
+        border: "1px solid var(--tgph-border-1)",
+        borderRadius: "0 6px 6px 0",
+      }}
+    >
+      <GripVertical size={14} color="var(--tgph-text-2)" />
+    </Box>
+  );
+};
diff --git a/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx b/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
index b724a8d6c..70d0a642d 100644
--- a/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
@@ -9,6 +9,9 @@ import { KnockButton } from "../KnockButton";
 import { TOOLBAR_Z_INDEX } from "../shared";
 import "../styles.css";
 
+import { DragHandle, DRAG_HANDLE_OVERHANG } from "./DragHandle";
+import { useDrag } from "./useDrag";
+
 import { GuideContextDetails } from "./GuideContextDetails";
 import { GuideRow } from "./GuideRow";
 import {
@@ -68,15 +71,31 @@ export const V2 = () => {
     };
   }, [isVisible, client]);
 
+  const containerRef = React.useRef<HTMLDivElement>(null);
+  const { position, isDragging, handlePointerDown } = useDrag({
+    elementRef: containerRef,
+    reclampDeps: [isCollapsed],
+    rightPadding: DRAG_HANDLE_OVERHANG,
+  });
+
   const result = useInspectGuideClientStore();
   if (!result) {
     return null;
   }
 
   return (
-    <Box position="fixed" top="4" right="4" style={{ zIndex: TOOLBAR_Z_INDEX }}>
+    <Box
+      tgphRef={containerRef}
+      position="fixed"
+      style={{
+        top: position.top + "px",
+        right: position.right + "px",
+        zIndex: TOOLBAR_Z_INDEX,
+      }}
+    >
+      <DragHandle onPointerDown={handlePointerDown} isDragging={isDragging} />
       {isCollapsed ? (
-        <KnockButton onClick={() => setIsCollapsed(false)} />
+        <KnockButton onClick={() => setIsCollapsed(false)} positioned={false} />
       ) : (
         <Stack
           direction="column"
diff --git a/packages/react/src/modules/guide/components/Toolbar/V2/useDrag.ts b/packages/react/src/modules/guide/components/Toolbar/V2/useDrag.ts
new file mode 100644
index 000000000..42017fc88
--- /dev/null
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/useDrag.ts
@@ -0,0 +1,154 @@
+import React from "react";
+
+type Position = { top: number; right: number };
+
+type UseDragOptions = {
+  elementRef: React.RefObject<HTMLElement | null>;
+  initialPosition?: Position;
+  reclampDeps?: React.DependencyList;
+  /** Extra space to reserve beyond the element's right edge (px). */
+  rightPadding?: number;
+};
+
+type UseDragReturn = {
+  position: Position;
+  isDragging: boolean;
+  handlePointerDown: (e: React.PointerEvent) => void;
+};
+
+const DEFAULT_POSITION: Position = { top: 16, right: 16 };
+
+/**
+ * @param rightPadding Extra space to reserve on the right edge (e.g. for a
+ *   drag handle that protrudes beyond the element). The element's left edge
+ *   is clamped so that `elementWidth + rightPadding` stays within the viewport.
+ */
+export function clampPosition(
+  pos: Position,
+  elementWidth: number,
+  elementHeight: number,
+  rightPadding = 0,
+): Position {
+  const viewportWidth = window.innerWidth;
+  const viewportHeight = window.innerHeight;
+
+  const totalWidth = elementWidth + rightPadding;
+  const left = viewportWidth - pos.right - elementWidth;
+  const clampedLeft = Math.max(0, Math.min(left, viewportWidth - totalWidth));
+  const clampedTop = Math.max(
+    0,
+    Math.min(pos.top, viewportHeight - elementHeight),
+  );
+  const clampedRight = viewportWidth - clampedLeft - elementWidth;
+
+  return { top: clampedTop, right: clampedRight };
+}
+
+export function useDrag({
+  elementRef,
+  initialPosition = DEFAULT_POSITION,
+  reclampDeps = [],
+  rightPadding = 0,
+}: UseDragOptions): UseDragReturn {
+  const [position, setPosition] = React.useState<Position>(initialPosition);
+  const [isDragging, setIsDragging] = React.useState(false);
+
+  const positionRef = React.useRef(position);
+  positionRef.current = position;
+
+  const startPointerRef = React.useRef({ x: 0, y: 0 });
+  const startPositionRef = React.useRef<Position>({ top: 0, right: 0 });
+  const rafIdRef = React.useRef<number | null>(null);
+  const isDraggingRef = React.useRef(false);
+
+  const reclamp = React.useCallback(() => {
+    const el = elementRef.current;
+    if (!el) return;
+    const rect = el.getBoundingClientRect();
+    setPosition((prev) =>
+      clampPosition(prev, rect.width, rect.height, rightPadding),
+    );
+  }, [elementRef, rightPadding]);
+
+  // Stable pointerdown handler
+  const handlePointerDown = React.useCallback(
+    (e: React.PointerEvent) => {
+      e.preventDefault();
+      startPointerRef.current = { x: e.clientX, y: e.clientY };
+      startPositionRef.current = { ...positionRef.current };
+      isDraggingRef.current = true;
+      setIsDragging(true);
+
+      const onPointerMove = (moveEvent: PointerEvent) => {
+        if (!isDraggingRef.current) return;
+
+        if (rafIdRef.current !== null) return;
+
+        rafIdRef.current = requestAnimationFrame(() => {
+          rafIdRef.current = null;
+          if (!isDraggingRef.current) return;
+
+          const dx = moveEvent.clientX - startPointerRef.current.x;
+          const dy = moveEvent.clientY - startPointerRef.current.y;
+
+          const newPos: Position = {
+            top: startPositionRef.current.top + dy,
+            right: startPositionRef.current.right - dx,
+          };
+
+          const el = elementRef.current;
+          if (!el) return;
+          const rect = el.getBoundingClientRect();
+          const clamped = clampPosition(
+            newPos,
+            rect.width,
+            rect.height,
+            rightPadding,
+          );
+          setPosition(clamped);
+        });
+      };
+
+      const onPointerUp = () => {
+        isDraggingRef.current = false;
+        setIsDragging(false);
+        if (rafIdRef.current !== null) {
+          cancelAnimationFrame(rafIdRef.current);
+          rafIdRef.current = null;
+        }
+        document.removeEventListener("pointermove", onPointerMove);
+        document.removeEventListener("pointerup", onPointerUp);
+      };
+
+      document.addEventListener("pointermove", onPointerMove);
+      document.addEventListener("pointerup", onPointerUp);
+    },
+    [elementRef, rightPadding],
+  );
+
+  // Cleanup on unmount
+  React.useEffect(() => {
+    return () => {
+      if (rafIdRef.current !== null) {
+        cancelAnimationFrame(rafIdRef.current);
+      }
+      isDraggingRef.current = false;
+    };
+  }, []);
+
+  // Re-clamp on window resize
+  React.useEffect(() => {
+    const onResize = () => reclamp();
+    window.addEventListener("resize", onResize);
+    return () => window.removeEventListener("resize", onResize);
+  }, [reclamp]);
+
+  // Re-clamp when deps change (e.g. collapse toggle)
+  React.useEffect(() => {
+    const id = requestAnimationFrame(() => reclamp());
+    return () => cancelAnimationFrame(id);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, reclampDeps);
+
+  return { position, isDragging, handlePointerDown };
+}
diff --git a/packages/react/test/guide/Toolbar/V2/useDrag.test.ts b/packages/react/test/guide/Toolbar/V2/useDrag.test.ts
new file mode 100644
index 000000000..2d210a1f2
--- /dev/null
+++ b/packages/react/test/guide/Toolbar/V2/useDrag.test.ts
@@ -0,0 +1,251 @@
+import { act, renderHook } from "@testing-library/react";
+import { beforeEach, describe, expect, test, vi } from "vitest";
+
+import {
+  clampPosition,
+  useDrag,
+} from "../../../../src/modules/guide/components/Toolbar/V2/useDrag";
+
+// Mock RAF to execute callbacks synchronously
+let rafCallback: FrameRequestCallback | null = null;
+let rafId = 0;
+
+beforeEach(() => {
+  rafCallback = null;
+  rafId = 0;
+
+  vi.stubGlobal("innerWidth", 1024);
+  vi.stubGlobal("innerHeight", 768);
+
+  vi.stubGlobal(
+    "requestAnimationFrame",
+    vi.fn((cb: FrameRequestCallback) => {
+      rafCallback = cb;
+      return ++rafId;
+    }),
+  );
+  vi.stubGlobal("cancelAnimationFrame", vi.fn());
+});
+
+function flushRAF() {
+  if (rafCallback) {
+    const cb = rafCallback;
+    rafCallback = null;
+    cb(performance.now());
+  }
+}
+
+function makeElementRef(rect: Partial<DOMRect> = {}) {
+  const el = {
+    getBoundingClientRect: vi.fn(
+      () =>
+        ({
+          width: 40,
+          height: 40,
+          top: 0,
+          left: 0,
+          right: 40,
+          bottom: 40,
+          x: 0,
+          y: 0,
+          toJSON: () => {},
+          ...rect,
+        }) as DOMRect,
+    ),
+  } as unknown as HTMLDivElement;
+
+  return { current: el };
+}
+
+describe("clampPosition", () => {
+  test("returns position unchanged when within bounds", () => {
+    const result = clampPosition({ top: 100, right: 100 }, 40, 40);
+    expect(result).toEqual({ top: 100, right: 100 });
+  });
+
+  test("clamps top to 0 when negative", () => {
+    const result = clampPosition({ top: -50, right: 100 }, 40, 40);
+    expect(result.top).toBe(0);
+  });
+
+  test("clamps top to keep element in viewport", () => {
+    // viewport height = 768, element height = 40
+    const result = clampPosition({ top: 800, right: 100 }, 40, 40);
+    expect(result.top).toBe(728); // 768 - 40
+  });
+
+  test("clamps right to 0 when element would overflow right", () => {
+    // right = -50 means left = 1024 - (-50) - 40 = 1034
+    // totalWidth = 40, clampedLeft = min(1034, 984) = 984
+    // clampedRight = 1024 - 984 - 40 = 0
+    const result = clampPosition({ top: 100, right: -50 }, 40, 40);
+    expect(result.right).toBe(0);
+  });
+
+  test("clamps left edge (large right value)", () => {
+    // right = 1100 means left = 1024 - 1100 - 40 = -116
+    // clampedLeft = max(0, -116) = 0
+    // clampedRight = 1024 - 0 - 40 = 984
+    const result = clampPosition({ top: 100, right: 1100 }, 40, 40);
+    expect(result.right).toBe(984);
+  });
+
+  test("reserves rightPadding so handle stays visible", () => {
+    // viewport = 1024, element = 40, rightPadding = 28
+    // right = -10 means left = 1024 - (-10) - 40 = 994
+    // totalWidth = 40 + 28 = 68, max left = 1024 - 68 = 956
+    // clampedLeft = min(994, 956) = 956
+    // clampedRight = 1024 - 956 - 40 = 28
+    const result = clampPosition({ top: 100, right: -10 }, 40, 40, 28);
+    expect(result.right).toBe(28);
+  });
+
+  test("rightPadding does not affect positions already within bounds", () => {
+    const result = clampPosition({ top: 100, right: 100 }, 40, 40, 28);
+    expect(result).toEqual({ top: 100, right: 100 });
+  });
+});
+
+describe("useDrag", () => {
+  test("returns default initial position", () => {
+    const elementRef = makeElementRef();
+    const { result } = renderHook(() => useDrag({ elementRef }));
+
+    expect(result.current.position).toEqual({ top: 16, right: 16 });
+  });
+
+  test("returns custom initial position", () => {
+    const elementRef = makeElementRef();
+    const { result } = renderHook(() =>
+      useDrag({ elementRef, initialPosition: { top: 50, right: 100 } }),
+    );
+
+    expect(result.current.position).toEqual({ top: 50, right: 100 });
+  });
+
+  test("isDragging starts as false", () => {
+    const elementRef = makeElementRef();
+    const { result } = renderHook(() => useDrag({ elementRef }));
+
+    expect(result.current.isDragging).toBe(false);
+  });
+
+  test("drag sequence updates position by correct delta", () => {
+    const elementRef = makeElementRef({
+      width: 40,
+      height: 40,
+    });
+    const { result } = renderHook(() =>
+      useDrag({ elementRef, initialPosition: { top: 100, right: 100 } }),
+    );
+
+    // Start drag
+    act(() => {
+      result.current.handlePointerDown({
+        clientX: 500,
+        clientY: 300,
+        preventDefault: vi.fn(),
+      } as unknown as React.PointerEvent);
+    });
+
+    expect(result.current.isDragging).toBe(true);
+
+    // Move pointer: dx = 50, dy = 30
+    act(() => {
+      document.dispatchEvent(
+        new PointerEvent("pointermove", {
+          clientX: 550,
+          clientY: 330,
+        }),
+      );
+      flushRAF();
+    });
+
+    // top should increase by 30, right should decrease by 50
+    expect(result.current.position).toEqual({ top: 130, right: 50 });
+
+    // End drag
+    act(() => {
+      document.dispatchEvent(new PointerEvent("pointerup"));
+    });
+
+    expect(result.current.isDragging).toBe(false);
+  });
+
+  test("position is clamped to viewport bounds", () => {
+    const elementRef = makeElementRef({ width: 40, height: 40 });
+    const { result } = renderHook(() =>
+      useDrag({ elementRef, initialPosition: { top: 10, right: 10 } }),
+    );
+
+    // Start drag
+    act(() => {
+      result.current.handlePointerDown({
+        clientX: 500,
+        clientY: 300,
+        preventDefault: vi.fn(),
+      } as unknown as React.PointerEvent);
+    });
+
+    // Move far right and up (dx = 600, dy = -500)
+    act(() => {
+      document.dispatchEvent(
+        new PointerEvent("pointermove", {
+          clientX: 1100,
+          clientY: -200,
+        }),
+      );
+      flushRAF();
+    });
+
+    // top clamped to 0, right clamped to 0 (pushed past right edge)
+    expect(result.current.position.top).toBe(0);
+    expect(result.current.position.right).toBeGreaterThanOrEqual(0);
+
+    act(() => {
+      document.dispatchEvent(new PointerEvent("pointerup"));
+    });
+  });
+
+  test("cleanup removes listeners on unmount", () => {
+    const elementRef = makeElementRef();
+    const removeListenerSpy = vi.spyOn(document, "removeEventListener");
+
+    const { result, unmount } = renderHook(() => useDrag({ elementRef }));
+
+    // Start a drag to register listeners
+    act(() => {
+      result.current.handlePointerDown({
+        clientX: 100,
+        clientY: 100,
+        preventDefault: vi.fn(),
+      } as unknown as React.PointerEvent);
+    });
+
+    // Unmount while dragging
+    unmount();
+
+    // Verify cancelAnimationFrame was available for cleanup
+    expect(cancelAnimationFrame).toBeDefined();
+
+    removeListenerSpy.mockRestore();
+  });
+
+  test("window resize re-clamps position", () => {
+    const elementRef = makeElementRef({ width: 40, height: 40 });
+    const { result } = renderHook(() =>
+      useDrag({ elementRef, initialPosition: { top: 700, right: 900 } }),
+    );
+
+    // Shrink viewport
+    act(() => {
+      vi.stubGlobal("innerWidth", 500);
+      vi.stubGlobal("innerHeight", 400);
+      window.dispatchEvent(new Event("resize"));
+    });
+
+    // Position should be re-clamped to fit new viewport
+    expect(result.current.position.top).toBeLessThanOrEqual(360); // 400 - 40
+    expect(result.current.position.right).toBeLessThanOrEqual(460); // 500 - 40
+  });
+});

From 70ceee89d714adee6efd39d130b757e7a51a8ae4 Mon Sep 17 00:00:00 2001
From: Thomas <thomas.whyyou@gmail.com>
Date: Thu, 26 Feb 2026 16:31:08 -0500
Subject: [PATCH 2/5] clean up and touch up

---
 .../components/Toolbar/V2/DragHandle.tsx      | 23 ++++++++-----------
 .../guide/components/Toolbar/V2/V2.tsx        |  8 +++----
 .../V2/{useDrag.ts => useDraggable.ts}        | 11 +++++----
 3 files changed, 20 insertions(+), 22 deletions(-)
 rename packages/react/src/modules/guide/components/Toolbar/V2/{useDrag.ts => useDraggable.ts} (94%)

diff --git a/packages/react/src/modules/guide/components/Toolbar/V2/DragHandle.tsx b/packages/react/src/modules/guide/components/Toolbar/V2/DragHandle.tsx
index 44a40d64a..f74becf0d 100644
--- a/packages/react/src/modules/guide/components/Toolbar/V2/DragHandle.tsx
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/DragHandle.tsx
@@ -1,9 +1,10 @@
+import { Icon } from "@telegraph/icon";
 import { Box } from "@telegraph/layout";
 import { GripVertical } from "lucide-react";
 import React from "react";
 
-/** How far the drag handle protrudes beyond the toolbar's right edge (px). */
-export const DRAG_HANDLE_OVERHANG = 28;
+// How far the drag handle protrudes beyond the toolbar's right edge (px)
+export const DRAG_HANDLE_OVERHANG = 16;
 
 type DragHandleProps = {
   onPointerDown: (e: React.PointerEvent) => void;
@@ -15,24 +16,18 @@ export const DragHandle = ({ onPointerDown, isDragging }: DragHandleProps) => {
     <Box
       data-tgph-appearance="dark"
       onPointerDown={onPointerDown}
+      borderRadius="2"
+      position="absolute"
       style={{
-        position: "absolute",
-        top: "-4px",
-        right: "-28px",
-        width: "24px",
-        height: "28px",
-        display: "flex",
-        alignItems: "center",
-        justifyContent: "center",
+        top: "9px",
+        right: `-${DRAG_HANDLE_OVERHANG}px`,
+        height: "24px",
         cursor: isDragging ? "grabbing" : "grab",
         touchAction: "none",
         userSelect: "none",
-        backgroundColor: "var(--tgph-surface-2)",
-        border: "1px solid var(--tgph-border-1)",
-        borderRadius: "0 6px 6px 0",
       }}
     >
-      <GripVertical size={14} color="var(--tgph-text-2)" />
+      <Icon color="gray" size="1" icon={GripVertical} aria-hidden />
     </Box>
   );
 };
diff --git a/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx b/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
index 70d0a642d..7ccff6a41 100644
--- a/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
@@ -9,9 +9,7 @@ import { KnockButton } from "../KnockButton";
 import { TOOLBAR_Z_INDEX } from "../shared";
 import "../styles.css";
 
-import { DragHandle, DRAG_HANDLE_OVERHANG } from "./DragHandle";
-import { useDrag } from "./useDrag";
-
+import { DRAG_HANDLE_OVERHANG, DragHandle } from "./DragHandle";
 import { GuideContextDetails } from "./GuideContextDetails";
 import { GuideRow } from "./GuideRow";
 import {
@@ -19,6 +17,7 @@ import {
   GuidesListDisplaySelect,
 } from "./GuidesListDisplaySelect";
 import { detectToolbarParam } from "./helpers";
+import { useDraggable } from "./useDraggable";
 import {
   InspectionResult,
   useInspectGuideClientStore,
@@ -72,10 +71,11 @@ export const V2 = () => {
   }, [isVisible, client]);
 
   const containerRef = React.useRef<HTMLDivElement>(null);
-  const { position, isDragging, handlePointerDown } = useDrag({
+  const { position, isDragging, handlePointerDown } = useDraggable({
     elementRef: containerRef,
     reclampDeps: [isCollapsed],
     rightPadding: DRAG_HANDLE_OVERHANG,
+    initialPosition: { top: 16, right: 16 },
   });
 
   const result = useInspectGuideClientStore();
diff --git a/packages/react/src/modules/guide/components/Toolbar/V2/useDrag.ts b/packages/react/src/modules/guide/components/Toolbar/V2/useDraggable.ts
similarity index 94%
rename from packages/react/src/modules/guide/components/Toolbar/V2/useDrag.ts
rename to packages/react/src/modules/guide/components/Toolbar/V2/useDraggable.ts
index 42017fc88..6dae77121 100644
--- a/packages/react/src/modules/guide/components/Toolbar/V2/useDrag.ts
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/useDraggable.ts
@@ -1,8 +1,11 @@
 import React from "react";
 
+// NOTE: This hook was generated entirely with Claude then lightly touched up,
+// and the behavior works correctly from testing it manually in the browser.
+
 type Position = { top: number; right: number };
 
-type UseDragOptions = {
+type UseDraggableOptions = {
   elementRef: React.RefObject<HTMLElement | null>;
   initialPosition?: Position;
   reclampDeps?: React.DependencyList;
@@ -10,7 +13,7 @@ type UseDragOptions = {
   rightPadding?: number;
 };
 
-type UseDragReturn = {
+type UseDraggableReturn = {
   position: Position;
   isDragging: boolean;
   handlePointerDown: (e: React.PointerEvent) => void;
@@ -44,12 +47,12 @@ export function clampPosition(
   return { top: clampedTop, right: clampedRight };
 }
 
-export function useDrag({
+export function useDraggable({
   elementRef,
   initialPosition = DEFAULT_POSITION,
   reclampDeps = [],
   rightPadding = 0,
-}: UseDragOptions): UseDragReturn {
+}: UseDraggableOptions): UseDraggableReturn {
   const [position, setPosition] = React.useState<Position>(initialPosition);
   const [isDragging, setIsDragging] = React.useState(false);
 

From 946a5147030a257e6b8beac304e9ec7d3b5c2e45 Mon Sep 17 00:00:00 2001
From: Thomas <thomas.whyyou@gmail.com>
Date: Thu, 26 Feb 2026 16:31:56 -0500
Subject: [PATCH 3/5] rename in test file also

---
 .../{useDrag.test.ts => useDraggable.test.ts} | 20 +++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)
 rename packages/react/test/guide/Toolbar/V2/{useDrag.test.ts => useDraggable.test.ts} (91%)

diff --git a/packages/react/test/guide/Toolbar/V2/useDrag.test.ts b/packages/react/test/guide/Toolbar/V2/useDraggable.test.ts
similarity index 91%
rename from packages/react/test/guide/Toolbar/V2/useDrag.test.ts
rename to packages/react/test/guide/Toolbar/V2/useDraggable.test.ts
index 2d210a1f2..cae52f993 100644
--- a/packages/react/test/guide/Toolbar/V2/useDrag.test.ts
+++ b/packages/react/test/guide/Toolbar/V2/useDraggable.test.ts
@@ -3,8 +3,8 @@ import { beforeEach, describe, expect, test, vi } from "vitest";
 
 import {
   clampPosition,
-  useDrag,
-} from "../../../../src/modules/guide/components/Toolbar/V2/useDrag";
+  useDraggable,
+} from "../../../../src/modules/guide/components/Toolbar/V2/useDraggable";
 
 // Mock RAF to execute callbacks synchronously
 let rafCallback: FrameRequestCallback | null = null;
@@ -106,10 +106,10 @@ describe("clampPosition", () => {
   });
 });
 
-describe("useDrag", () => {
+describe("useDraggable", () => {
   test("returns default initial position", () => {
     const elementRef = makeElementRef();
-    const { result } = renderHook(() => useDrag({ elementRef }));
+    const { result } = renderHook(() => useDraggable({ elementRef }));
 
     expect(result.current.position).toEqual({ top: 16, right: 16 });
   });
@@ -117,7 +117,7 @@ describe("useDrag", () => {
   test("returns custom initial position", () => {
     const elementRef = makeElementRef();
     const { result } = renderHook(() =>
-      useDrag({ elementRef, initialPosition: { top: 50, right: 100 } }),
+      useDraggable({ elementRef, initialPosition: { top: 50, right: 100 } }),
     );
 
     expect(result.current.position).toEqual({ top: 50, right: 100 });
@@ -125,7 +125,7 @@ describe("useDrag", () => {
 
   test("isDragging starts as false", () => {
     const elementRef = makeElementRef();
-    const { result } = renderHook(() => useDrag({ elementRef }));
+    const { result } = renderHook(() => useDraggable({ elementRef }));
 
     expect(result.current.isDragging).toBe(false);
   });
@@ -136,7 +136,7 @@ describe("useDrag", () => {
       height: 40,
     });
     const { result } = renderHook(() =>
-      useDrag({ elementRef, initialPosition: { top: 100, right: 100 } }),
+      useDraggable({ elementRef, initialPosition: { top: 100, right: 100 } }),
     );
 
     // Start drag
@@ -175,7 +175,7 @@ describe("useDrag", () => {
   test("position is clamped to viewport bounds", () => {
     const elementRef = makeElementRef({ width: 40, height: 40 });
     const { result } = renderHook(() =>
-      useDrag({ elementRef, initialPosition: { top: 10, right: 10 } }),
+      useDraggable({ elementRef, initialPosition: { top: 10, right: 10 } }),
     );
 
     // Start drag
@@ -211,7 +211,7 @@ describe("useDrag", () => {
     const elementRef = makeElementRef();
     const removeListenerSpy = vi.spyOn(document, "removeEventListener");
 
-    const { result, unmount } = renderHook(() => useDrag({ elementRef }));
+    const { result, unmount } = renderHook(() => useDraggable({ elementRef }));
 
     // Start a drag to register listeners
     act(() => {
@@ -234,7 +234,7 @@ describe("useDrag", () => {
   test("window resize re-clamps position", () => {
     const elementRef = makeElementRef({ width: 40, height: 40 });
     const { result } = renderHook(() =>
-      useDrag({ elementRef, initialPosition: { top: 700, right: 900 } }),
+      useDraggable({ elementRef, initialPosition: { top: 700, right: 900 } }),
     );
 
     // Shrink viewport

From d3726ac3ee5d158be1a087dc14c62ce948b4975b Mon Sep 17 00:00:00 2001
From: Thomas <thomas.whyyou@gmail.com>
Date: Thu, 26 Feb 2026 17:01:31 -0500
Subject: [PATCH 4/5] relaying cursor review comment to claude lol

---
 .../guide/components/Toolbar/V2/useDraggable.ts      | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/packages/react/src/modules/guide/components/Toolbar/V2/useDraggable.ts b/packages/react/src/modules/guide/components/Toolbar/V2/useDraggable.ts
index 6dae77121..1663d3889 100644
--- a/packages/react/src/modules/guide/components/Toolbar/V2/useDraggable.ts
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/useDraggable.ts
@@ -63,6 +63,7 @@ export function useDraggable({
   const startPositionRef = React.useRef<Position>({ top: 0, right: 0 });
   const rafIdRef = React.useRef<number | null>(null);
   const isDraggingRef = React.useRef(false);
+  const cleanupListenersRef = React.useRef<(() => void) | null>(null);
 
   const reclamp = React.useCallback(() => {
     const el = elementRef.current;
@@ -112,7 +113,7 @@ export function useDraggable({
         });
       };
 
-      const onPointerUp = () => {
+      const cleanup = () => {
         isDraggingRef.current = false;
         setIsDragging(false);
         if (rafIdRef.current !== null) {
@@ -121,10 +122,14 @@ export function useDraggable({
         }
         document.removeEventListener("pointermove", onPointerMove);
         document.removeEventListener("pointerup", onPointerUp);
+        cleanupListenersRef.current = null;
       };
 
+      const onPointerUp = () => cleanup();
+
       document.addEventListener("pointermove", onPointerMove);
       document.addEventListener("pointerup", onPointerUp);
+      cleanupListenersRef.current = cleanup;
     },
     [elementRef, rightPadding],
   );
@@ -132,10 +137,7 @@ export function useDraggable({
   // Cleanup on unmount
   React.useEffect(() => {
     return () => {
-      if (rafIdRef.current !== null) {
-        cancelAnimationFrame(rafIdRef.current);
-      }
-      isDraggingRef.current = false;
+      cleanupListenersRef.current?.();
     };
   }, []);
 

From 7942fdbd7a851a2bea210b06aa25057bb7a30d8e Mon Sep 17 00:00:00 2001
From: Thomas <thomas.whyyou@gmail.com>
Date: Fri, 27 Feb 2026 14:24:00 -0500
Subject: [PATCH 5/5] changeset

---
 .changeset/shiny-webs-write.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)
 create mode 100644 .changeset/shiny-webs-write.md

diff --git a/.changeset/shiny-webs-write.md b/.changeset/shiny-webs-write.md
new file mode 100644
index 000000000..ae072b41d
--- /dev/null
+++ b/.changeset/shiny-webs-write.md
@@ -0,0 +1,12 @@
+---
+"@knocklabs/client": patch
+"@knocklabs/react": patch
+---
+
+[Guides] Add additional debug settings to guide client, and improvements to the guide toolbar V2
+
+- Add `focusedGuideKeys` debug setting to pin a target guide during preview
+- Add `ignoreDisplayInterval` debug setting to ignore throttling during preview
+- Add `skipEngagementTracking` debug setting to skip sending engagement updates to the API during preview
+- Add control UIs to the guide toolbar V2 for the newly added debug settings
+- Add a drag handle to the guide toolbar for drag and drop