From fe0d9f904277172246570d2e035fef3fce8ca545 Mon Sep 17 00:00:00 2001
From: Thomas <thomas.whyyou@gmail.com>
Date: Fri, 17 Apr 2026 15:10:05 -0400
Subject: [PATCH 1/3] first pass at adding hotkeys for moving focus prev or
 next

---
 .../guide/components/Toolbar/V2/FocusChin.tsx | 147 ++++++++++++------
 .../guide/components/Toolbar/V2/Kbd.tsx       |  17 ++
 .../guide/components/Toolbar/V2/V2.tsx        |  17 +-
 3 files changed, 116 insertions(+), 65 deletions(-)
 create mode 100644 packages/react/src/modules/guide/components/Toolbar/V2/Kbd.tsx

diff --git a/packages/react/src/modules/guide/components/Toolbar/V2/FocusChin.tsx b/packages/react/src/modules/guide/components/Toolbar/V2/FocusChin.tsx
index a043433a6..af87c6314 100644
--- a/packages/react/src/modules/guide/components/Toolbar/V2/FocusChin.tsx
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/FocusChin.tsx
@@ -7,6 +7,7 @@ import { ChevronLeft, ChevronRight, X } from "lucide-react";
 import * as React from "react";
 
 import { GUIDE_ROW_DATA_SELECTOR } from "./GuideRow";
+import { Kbd } from "./Kbd";
 import { sharedTooltipProps } from "./helpers";
 import { InspectionResultOk } from "./useInspectGuideClientStore";
 
@@ -14,6 +15,9 @@ import { InspectionResultOk } from "./useInspectGuideClientStore";
 // reducing how often consecutive next/prev clicks trigger a scroll.
 const SCROLL_OVERSHOOT = 60;
 
+const FOCUS_PREV_HOTKEY = ",";
+const FOCUS_NEXT_HOTKEY = "/";
+
 const maybeScrollGuideIntoView = (container: HTMLElement, guideKey: string) => {
   requestAnimationFrame(() => {
     const el = container.querySelector(
@@ -56,14 +60,81 @@ export const FocusChin = ({ guides, guideListRef }: Props) => {
   }));
 
   const focusedKeys = Object.keys(debugSettings?.focusedGuideKeys || {});
-
   const isFocused = focusedKeys.length > 0;
+  const currentKey = focusedKeys[0];
+
+  const focusGuide = React.useCallback(
+    (guideKey: string) => {
+      client.setDebug({
+        ...client.store.state.debug,
+        focusedGuideKeys: { [guideKey]: true },
+      });
+      if (guideListRef.current) {
+        maybeScrollGuideIntoView(guideListRef.current, guideKey);
+      }
+    },
+    [client, guideListRef],
+  );
+
+  const focusPrevious = React.useCallback(() => {
+    const selectableGuides = guides.filter(
+      (g) => !!g.annotation.selectable.status,
+    );
+    if (selectableGuides.length === 0) return;
+
+    if (!currentKey) {
+      focusGuide(selectableGuides[selectableGuides.length - 1]!.key);
+      return;
+    }
+
+    const currIndex = selectableGuides.findIndex((g) => g.key === currentKey);
+    const prevGuide =
+      currIndex <= 0 ? undefined : selectableGuides[currIndex - 1];
+    if (!prevGuide) return;
+    focusGuide(prevGuide.key);
+  }, [guides, currentKey, focusGuide]);
+
+  const focusNext = React.useCallback(() => {
+    const selectableGuides = guides.filter(
+      (g) => !!g.annotation.selectable.status,
+    );
+    if (selectableGuides.length === 0) return;
+
+    if (!currentKey) {
+      focusGuide(selectableGuides[0]!.key);
+      return;
+    }
+
+    const currIndex = selectableGuides.findIndex((g) => g.key === currentKey);
+    const nextGuide =
+      currIndex < 0 || currIndex + 1 > selectableGuides.length - 1
+        ? undefined
+        : selectableGuides[currIndex + 1];
+    if (!nextGuide) return;
+    focusGuide(nextGuide.key);
+  }, [guides, currentKey, focusGuide]);
+
+  React.useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (!e.ctrlKey || e.repeat) return;
+      if (e.key === FOCUS_PREV_HOTKEY) {
+        e.preventDefault();
+        focusPrevious();
+      } else if (e.key === FOCUS_NEXT_HOTKEY) {
+        e.preventDefault();
+        focusNext();
+      }
+    };
+    window.addEventListener("keydown", handleKeyDown);
+    return () => {
+      window.removeEventListener("keydown", handleKeyDown);
+    };
+  }, [focusPrevious, focusNext]);
+
   if (!isFocused) {
     return null;
   }
 
-  const currentKey = focusedKeys[0]!;
-
   return (
     <Box
       borderTop="px"
@@ -89,64 +160,42 @@ export const FocusChin = ({ guides, guideListRef }: Props) => {
           Focus mode: {currentKey}
         </Text>
         <Stack align="center" gap="1" style={{ flexShrink: 0 }}>
-          <Tooltip label="Focus previous guide" {...sharedTooltipProps}>
+          <Tooltip
+            label={
+              <Text as="span" size="1">
+                Focus previous guide
+                <Stack display="inline-block" ml="3">
+                  <Kbd>ctrl</Kbd> + <Kbd>,</Kbd>
+                </Stack>
+              </Text>
+            }
+            {...sharedTooltipProps}
+          >
             <Button
               size="0"
               variant="ghost"
               color="blue"
               leadingIcon={{ icon: ChevronLeft, alt: "Previous guide" }}
-              onClick={() => {
-                const selectableGuides = guides.filter(
-                  (g) => !!g.annotation.selectable.status,
-                );
-                const currIndex = selectableGuides.findIndex(
-                  (g) => g.key === currentKey,
-                );
-                const prevGuide =
-                  currIndex <= 0 ? undefined : selectableGuides[currIndex - 1];
-
-                if (!prevGuide) return;
-
-                client.setDebug({
-                  ...debugSettings,
-                  focusedGuideKeys: { [prevGuide.key]: true },
-                });
-
-                if (guideListRef.current) {
-                  maybeScrollGuideIntoView(guideListRef.current, prevGuide.key);
-                }
-              }}
+              onClick={focusPrevious}
             />
           </Tooltip>
-          <Tooltip label="Focus next guide" {...sharedTooltipProps}>
+          <Tooltip
+            label={
+              <Text as="span" size="1">
+                Focus next guide
+                <Stack display="inline-block" ml="3">
+                  <Kbd>ctrl</Kbd> + <Kbd>/</Kbd>
+                </Stack>
+              </Text>
+            }
+            {...sharedTooltipProps}
+          >
             <Button
               size="0"
               variant="ghost"
               color="blue"
               leadingIcon={{ icon: ChevronRight, alt: "Next guide" }}
-              onClick={() => {
-                const selectableGuides = guides.filter(
-                  (g) => !!g.annotation.selectable.status,
-                );
-                const currIndex = selectableGuides.findIndex(
-                  (g) => g.key === currentKey,
-                );
-                const nextGuide =
-                  currIndex < 0 || currIndex + 1 > selectableGuides.length - 1
-                    ? undefined
-                    : selectableGuides[currIndex + 1];
-
-                if (!nextGuide) return;
-
-                client.setDebug({
-                  ...debugSettings,
-                  focusedGuideKeys: { [nextGuide.key]: true },
-                });
-
-                if (guideListRef.current) {
-                  maybeScrollGuideIntoView(guideListRef.current, nextGuide.key);
-                }
-              }}
+              onClick={focusNext}
             />
           </Tooltip>
           <Tooltip label="Exit focus mode" {...sharedTooltipProps}>
diff --git a/packages/react/src/modules/guide/components/Toolbar/V2/Kbd.tsx b/packages/react/src/modules/guide/components/Toolbar/V2/Kbd.tsx
new file mode 100644
index 000000000..046df9c04
--- /dev/null
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/Kbd.tsx
@@ -0,0 +1,17 @@
+import * as React from "react";
+
+export const Kbd = ({ children }: { children: React.ReactNode }) => {
+  return (
+    <kbd
+      style={{
+        display: "inline-block",
+        padding: "1px 4px",
+        borderRadius: "var(--tgph-rounded-2)",
+        border: "1px solid rgba(255, 255, 255, 0.3)",
+        backgroundColor: "rgba(255, 255, 255, 0.15)",
+      }}
+    >
+      {children}
+    </kbd>
+  );
+};
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 489ec76ac..eab48cb6f 100644
--- a/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
@@ -24,6 +24,7 @@ import { FocusChin } from "./FocusChin";
 import { GuideContextDetails } from "./GuideContextDetails";
 import { GuideRow } from "./GuideRow";
 import { DisplayOption, sharedTooltipProps } from "./helpers";
+import { Kbd } from "./Kbd";
 import { useDraggable } from "./useDraggable";
 import {
   InspectionResultOk,
@@ -43,22 +44,6 @@ const TOOLBAR_BOX_SHADOW = [
   "0 8px 16px -4px rgba(0, 0, 0, 0.06)",
 ].join(", ");
 
-const Kbd = ({ children }: { children: React.ReactNode }) => {
-  return (
-    <kbd
-      style={{
-        display: "inline-block",
-        padding: "1px 4px",
-        borderRadius: "var(--tgph-rounded-2)",
-        border: "1px solid rgba(255, 255, 255, 0.3)",
-        backgroundColor: "rgba(255, 255, 255, 0.15)",
-      }}
-    >
-      {children}
-    </kbd>
-  );
-};
-
 const getEmptyStateMessage = (displayOption: DisplayOption) => {
   switch (displayOption) {
     case "all-guides":

From 9e32800804e44f57b6e8ad23c712e2288fabc8ab Mon Sep 17 00:00:00 2001
From: Thomas <thomas.whyyou@gmail.com>
Date: Fri, 17 Apr 2026 15:26:52 -0400
Subject: [PATCH 2/3] refactor to minimize sub/unsub-ing window listners

---
 .../guide/components/Toolbar/V2/FocusChin.tsx | 97 +++++++++++--------
 .../guide/components/Toolbar/V2/V2.tsx        |  2 +-
 2 files changed, 56 insertions(+), 43 deletions(-)

diff --git a/packages/react/src/modules/guide/components/Toolbar/V2/FocusChin.tsx b/packages/react/src/modules/guide/components/Toolbar/V2/FocusChin.tsx
index af87c6314..a94ac0e06 100644
--- a/packages/react/src/modules/guide/components/Toolbar/V2/FocusChin.tsx
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/FocusChin.tsx
@@ -48,6 +48,50 @@ const maybeScrollGuideIntoView = (container: HTMLElement, guideKey: string) => {
   });
 };
 
+type FocusNav = {
+  guides: InspectionResultOk["guides"];
+  currentKey: string | undefined;
+  focusGuide: (guideKey: string) => void;
+};
+
+const focusPrev = ({ guides, currentKey, focusGuide }: FocusNav) => {
+  const selectableGuides = guides.filter(
+    (g) => !!g.annotation.selectable.status,
+  );
+  if (selectableGuides.length === 0) return;
+
+  if (!currentKey) {
+    focusGuide(selectableGuides[selectableGuides.length - 1]!.key);
+    return;
+  }
+
+  const currIndex = selectableGuides.findIndex((g) => g.key === currentKey);
+  const prevGuide =
+    currIndex <= 0 ? undefined : selectableGuides[currIndex - 1];
+  if (!prevGuide) return;
+  focusGuide(prevGuide.key);
+};
+
+const focusNext = ({ guides, currentKey, focusGuide }: FocusNav) => {
+  const selectableGuides = guides.filter(
+    (g) => !!g.annotation.selectable.status,
+  );
+  if (selectableGuides.length === 0) return;
+
+  if (!currentKey) {
+    focusGuide(selectableGuides[0]!.key);
+    return;
+  }
+
+  const currIndex = selectableGuides.findIndex((g) => g.key === currentKey);
+  const nextGuide =
+    currIndex < 0 || currIndex + 1 > selectableGuides.length - 1
+      ? undefined
+      : selectableGuides[currIndex + 1];
+  if (!nextGuide) return;
+  focusGuide(nextGuide.key);
+};
+
 type Props = {
   guides: InspectionResultOk["guides"];
   guideListRef: React.RefObject<HTMLDivElement | null>;
@@ -76,60 +120,29 @@ export const FocusChin = ({ guides, guideListRef }: Props) => {
     [client, guideListRef],
   );
 
-  const focusPrevious = React.useCallback(() => {
-    const selectableGuides = guides.filter(
-      (g) => !!g.annotation.selectable.status,
-    );
-    if (selectableGuides.length === 0) return;
-
-    if (!currentKey) {
-      focusGuide(selectableGuides[selectableGuides.length - 1]!.key);
-      return;
-    }
-
-    const currIndex = selectableGuides.findIndex((g) => g.key === currentKey);
-    const prevGuide =
-      currIndex <= 0 ? undefined : selectableGuides[currIndex - 1];
-    if (!prevGuide) return;
-    focusGuide(prevGuide.key);
-  }, [guides, currentKey, focusGuide]);
-
-  const focusNext = React.useCallback(() => {
-    const selectableGuides = guides.filter(
-      (g) => !!g.annotation.selectable.status,
-    );
-    if (selectableGuides.length === 0) return;
-
-    if (!currentKey) {
-      focusGuide(selectableGuides[0]!.key);
-      return;
-    }
-
-    const currIndex = selectableGuides.findIndex((g) => g.key === currentKey);
-    const nextGuide =
-      currIndex < 0 || currIndex + 1 > selectableGuides.length - 1
-        ? undefined
-        : selectableGuides[currIndex + 1];
-    if (!nextGuide) return;
-    focusGuide(nextGuide.key);
-  }, [guides, currentKey, focusGuide]);
+  // Latest-ref so the window keydown listener below can attach once and always
+  // read the current guides / focused key without needing to re-subscribe.
+  const latestRef = React.useRef<FocusNav>({ guides, currentKey, focusGuide });
+  React.useEffect(() => {
+    latestRef.current = { guides, currentKey, focusGuide };
+  });
 
   React.useEffect(() => {
     const handleKeyDown = (e: KeyboardEvent) => {
       if (!e.ctrlKey || e.repeat) return;
       if (e.key === FOCUS_PREV_HOTKEY) {
         e.preventDefault();
-        focusPrevious();
+        focusPrev(latestRef.current);
       } else if (e.key === FOCUS_NEXT_HOTKEY) {
         e.preventDefault();
-        focusNext();
+        focusNext(latestRef.current);
       }
     };
     window.addEventListener("keydown", handleKeyDown);
     return () => {
       window.removeEventListener("keydown", handleKeyDown);
     };
-  }, [focusPrevious, focusNext]);
+  }, []);
 
   if (!isFocused) {
     return null;
@@ -176,7 +189,7 @@ export const FocusChin = ({ guides, guideListRef }: Props) => {
               variant="ghost"
               color="blue"
               leadingIcon={{ icon: ChevronLeft, alt: "Previous guide" }}
-              onClick={focusPrevious}
+              onClick={() => focusPrev(latestRef.current)}
             />
           </Tooltip>
           <Tooltip
@@ -195,7 +208,7 @@ export const FocusChin = ({ guides, guideListRef }: Props) => {
               variant="ghost"
               color="blue"
               leadingIcon={{ icon: ChevronRight, alt: "Next guide" }}
-              onClick={focusNext}
+              onClick={() => focusNext(latestRef.current)}
             />
           </Tooltip>
           <Tooltip label="Exit focus mode" {...sharedTooltipProps}>
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 eab48cb6f..9065f76c3 100644
--- a/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
@@ -23,8 +23,8 @@ import "../styles.css";
 import { FocusChin } from "./FocusChin";
 import { GuideContextDetails } from "./GuideContextDetails";
 import { GuideRow } from "./GuideRow";
-import { DisplayOption, sharedTooltipProps } from "./helpers";
 import { Kbd } from "./Kbd";
+import { DisplayOption, sharedTooltipProps } from "./helpers";
 import { useDraggable } from "./useDraggable";
 import {
   InspectionResultOk,

From cd2c008ad2ac965767004d0dfa3f809766870dce Mon Sep 17 00:00:00 2001
From: Thomas <thomas.whyyou@gmail.com>
Date: Fri, 17 Apr 2026 16:59:16 -0400
Subject: [PATCH 3/3] changeset

---
 .changeset/smooth-lands-draw.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/smooth-lands-draw.md

diff --git a/.changeset/smooth-lands-draw.md b/.changeset/smooth-lands-draw.md
new file mode 100644
index 000000000..0f0f83f94
--- /dev/null
+++ b/.changeset/smooth-lands-draw.md
@@ -0,0 +1,5 @@
+---
+"@knocklabs/react": patch
+---
+
+[Guide] Add hotkey support for moving focus in guide toolbar