From 30183cb014c8bf69f263ee14c1807b139b50401d Mon Sep 17 00:00:00 2001
From: Thomas <thomas.whyyou@gmail.com>
Date: Mon, 30 Mar 2026 09:42:26 -0400
Subject: [PATCH 01/10] add FocusChin to the guide toolbar v2 with dedicated
 controls

---
 .../guide/components/Toolbar/V2/FocusChin.tsx | 174 ++++++++++++++++++
 .../guide/components/Toolbar/V2/V2.tsx        |  75 ++++----
 .../guide/components/Toolbar/V2/helpers.ts    |   2 +
 .../guide/components/Toolbar/styles.css       |   2 +-
 4 files changed, 214 insertions(+), 39 deletions(-)
 create mode 100644 packages/react/src/modules/guide/components/Toolbar/V2/FocusChin.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
new file mode 100644
index 000000000..2ff3463ce
--- /dev/null
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/FocusChin.tsx
@@ -0,0 +1,174 @@
+import { useGuideContext, useStore } from "@knocklabs/react-core";
+import { Button } from "@telegraph/button";
+import { Box, Stack } from "@telegraph/layout";
+import { Tooltip } from "@telegraph/tooltip";
+import { Text } from "@telegraph/typography";
+import { ChevronLeft, ChevronRight, X } from "lucide-react";
+
+import { DisplayOption } from "./helpers";
+// import React from "react";
+
+import { InspectionResultOk } from "./useInspectGuideClientStore";
+
+// const findNextPrevKey = (
+//   currKey: string,
+//   guides: InspectionResultOk["guides"]
+// ) => {
+//   const selectableGuides = guides.filter(g => !!g.annotation.selectable);
+//   const currIndex = selectableGuides.findIndex(g => g.key === currKey);
+//
+//   const prevGuide = currIndex === 0
+//     ? undefined
+//     : selectableGuides[currIndex - 1];
+//
+//   const nextGuide = currIndex + 1 > selectableGuides.length - 1
+//     ? undefined
+//     : selectableGuides[currIndex + 1];
+//
+//   return { prev: prevGuide, next: nextGuide };
+// }
+// const findNextGuideKey = (
+//   currKey: string,
+//   guides: InspectionResultOk["guides"]
+// ) => {
+//   const selectableGuides = guides.filter(g => !!g.annotation.selectable);
+//   const currIndex = selectableGuides.findIndex(g => g.key === currKey);
+//
+//   const prevGuide = currIndex === 0
+//     ? undefined
+//     : selectableGuides[currIndex - 1];
+//
+//   const nextGuide = currIndex + 1 > selectableGuides.length - 1
+//     ? undefined
+//     : selectableGuides[currIndex + 1];
+//
+//   return { prev: prevGuide, next: nextGuide };
+// }
+
+type Props = {
+  guides: InspectionResultOk["guides"];
+  displayOption: DisplayOption;
+};
+
+export const FocusChin = ({ guides, displayOption }: Props) => {
+  const { client } = useGuideContext();
+  const { debugSettings } = useStore(client.store, (state) => ({
+    debugSettings: state.debug || {},
+  }));
+
+  const focusedKeys = Object.keys(debugSettings.focusedGuideKeys || {});
+
+  // const { prev, next } = React.useMemo(() => {
+  //   if (focusedKeys.length === 0) {
+  //     return {}
+  //   }
+  //   const currentKey = focusedKeys[0];
+  //
+  //   return findNextAndPrevGuideKey(currentKey, guides)
+  // }, [displayOption, focusedKeys.length]);
+
+  const isFocused = focusedKeys.length > 0;
+  if (!isFocused) {
+    return null;
+  }
+
+  const currentKey = focusedKeys[0];
+
+  // const currentIndex = currentKey ? guideKeys.indexOf(currentKey) : -1;
+
+  // const setFocus = (key: string) => {
+  //   client.setDebug({
+  //     ...debugSettings,
+  //     focusedGuideKeys: { [key]: true },
+  //   });
+  // };
+  //
+  // const hasPrev = currentIndex > 0;
+  // const hasNext = currentIndex >= 0 && currentIndex < guideKeys.length - 1;
+
+  return (
+    <Box
+      borderTop="px"
+      px="3"
+      py="1"
+      overflow="hidden"
+      backgroundColor="blue-2"
+    >
+      <Stack align="center" justify="space-between">
+        <Text as="span" size="1" weight="medium" color="blue">
+          Focus lock: {currentKey}
+        </Text>
+        <Stack align="center" gap="1">
+          <Tooltip label="Focus previous guide">
+            <Button
+              size="0"
+              variant="ghost"
+              color="blue"
+              leadingIcon={{ icon: ChevronLeft, alt: "Previous guide" }}
+              // disabled={!hasPrev}
+              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 },
+                });
+              }}
+            />
+          </Tooltip>
+          <Tooltip label="Focus next guide">
+            <Button
+              size="0"
+              variant="ghost"
+              color="blue"
+              leadingIcon={{ icon: ChevronRight, alt: "Next guide" }}
+              // disabled={!hasNext}
+              onClick={() => {
+                const selectableGuides = guides.filter(
+                  (g) => !!g.annotation.selectable.status,
+                );
+                console.log(1, selectableGuides);
+                const currIndex = selectableGuides.findIndex(
+                  (g) => g.key === currentKey,
+                );
+
+                const nextGuide =
+                  currIndex + 1 > selectableGuides.length - 1
+                    ? undefined
+                    : selectableGuides[currIndex + 1];
+
+                if (!nextGuide) return;
+
+                client.setDebug({
+                  ...debugSettings,
+                  focusedGuideKeys: { [nextGuide.key]: true },
+                });
+              }}
+            />
+          </Tooltip>
+          <Tooltip label="Exit focus lock">
+            <Button
+              size="0"
+              variant="ghost"
+              color="blue"
+              leadingIcon={{ icon: X, alt: "Clear focus" }}
+              onClick={() => {
+                client.setDebug({ ...debugSettings, focusedGuideKeys: {} });
+              }}
+            />
+          </Tooltip>
+        </Stack>
+      </Stack>
+    </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 08ddfdd3e..8f19a37d8 100644
--- a/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
@@ -19,9 +19,10 @@ import { KnockButton } from "../KnockButton";
 import { TOOLBAR_Z_INDEX } from "../shared";
 import "../styles.css";
 
+import { FocusChin } from "./FocusChin";
 import { GuideContextDetails } from "./GuideContextDetails";
 import { GuideRow } from "./GuideRow";
-import { clearRunConfigLS, getRunConfig } from "./helpers";
+import { DisplayOption, clearRunConfigLS, getRunConfig } from "./helpers";
 import { useDraggable } from "./useDraggable";
 import {
   InspectionResultOk,
@@ -48,46 +49,21 @@ const Kbd = ({ children }: { children: React.ReactNode }) => {
   );
 };
 
-type DisplayOption = "all-guides" | "only-eligible" | "only-displayable";
-
-const GuidesList = ({
-  guides,
-  displayOption,
-}: {
-  guides: InspectionResultOk["guides"];
-  displayOption: DisplayOption;
-}) => {
-  const [expandedGuideRowKey, setExpandedGuideRowKey] = React.useState<
-    string | undefined
-  >();
-
-  React.useEffect(() => {
-    setExpandedGuideRowKey(undefined);
-  }, [displayOption]);
-
-  return guides.map((guide, idx) => {
+const filterGuides = (
+  guides: InspectionResultOk["guides"],
+  displayOption: DisplayOption,
+) => {
+  return guides.filter((guide) => {
     const { isEligible, isQualified } = guide.annotation;
     const isDisplayable = isEligible && isQualified;
 
     if (displayOption === "only-displayable" && !isDisplayable) {
-      return null;
+      return false;
     }
     if (displayOption === "only-eligible" && !isEligible) {
-      return null;
+      return false;
     }
-    return (
-      <GuideRow
-        key={guide.key}
-        guide={guide}
-        orderIndex={idx}
-        isExpanded={guide.key === expandedGuideRowKey}
-        onClick={() => {
-          setExpandedGuideRowKey((k) =>
-            k && k === guide.key ? undefined : guide.key,
-          );
-        }}
-      />
-    );
+    return true;
   });
 };
 
@@ -100,6 +76,14 @@ export const V2 = () => {
   const [isCollapsed, setIsCollapsed] = React.useState(false);
   const [isContextPanelOpen, setIsContextPanelOpen] = React.useState(false);
 
+  const [expandedGuideRowKey, setExpandedGuideRowKey] = React.useState<
+    string | undefined
+  >();
+
+  React.useEffect(() => {
+    setExpandedGuideRowKey(undefined);
+  }, [displayOption]);
+
   React.useEffect(() => {
     const { isVisible = false, focusedGuideKeys = {} } = runConfig || {};
     const isDebugging = client.store.state.debug?.debugging;
@@ -157,6 +141,9 @@ export const V2 = () => {
     return null;
   }
 
+  const guides =
+    result.status === "ok" ? filterGuides(result.guides, displayOption) : [];
+
   return (
     <Box
       tgphRef={containerRef}
@@ -358,12 +345,24 @@ export const V2 = () => {
                 </Text>
               </Box>
             ) : (
-              <GuidesList
-                guides={result.guides}
-                displayOption={displayOption}
-              />
+              guides.map((guide, idx) => (
+                <GuideRow
+                  key={guide.key}
+                  guide={guide}
+                  orderIndex={idx}
+                  isExpanded={guide.key === expandedGuideRowKey}
+                  onClick={() => {
+                    setExpandedGuideRowKey((k) =>
+                      k && k === guide.key ? undefined : guide.key,
+                    );
+                  }}
+                />
+              ))
             )}
           </Box>
+
+          {/* Focus chin with dedicated controls */}
+          <FocusChin guides={guides} displayOption={displayOption} />
         </Stack>
       )}
     </Box>
diff --git a/packages/react/src/modules/guide/components/Toolbar/V2/helpers.ts b/packages/react/src/modules/guide/components/Toolbar/V2/helpers.ts
index bef3d6fac..443b019d3 100644
--- a/packages/react/src/modules/guide/components/Toolbar/V2/helpers.ts
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/helpers.ts
@@ -2,6 +2,8 @@ import { KnockGuide } from "@knocklabs/client";
 
 import { checkForWindow } from "../../../../../modules/core";
 
+export type DisplayOption = "all-guides" | "only-eligible" | "only-displayable";
+
 // Use this param to start Toolbar and enter into a debugging session when
 // it is present and set to true.
 const TOOLBAR_QUERY_PARAM = "knock_guide_toolbar";
diff --git a/packages/react/src/modules/guide/components/Toolbar/styles.css b/packages/react/src/modules/guide/components/Toolbar/styles.css
index 47686d4c3..5c2d980f2 100644
--- a/packages/react/src/modules/guide/components/Toolbar/styles.css
+++ b/packages/react/src/modules/guide/components/Toolbar/styles.css
@@ -24,4 +24,4 @@
     opacity: 1;
     transform: scale(1);
   }
-}
+}
\ No newline at end of file

From a76f5b7b925c60b2de6c3de8d68eeb30cdefef85 Mon Sep 17 00:00:00 2001
From: Thomas <thomas.whyyou@gmail.com>
Date: Mon, 30 Mar 2026 18:27:27 -0400
Subject: [PATCH 02/10] clean up

---
 .../guide/components/Toolbar/V2/FocusChin.tsx | 69 +------------------
 .../guide/components/Toolbar/V2/V2.tsx        |  2 +-
 2 files changed, 3 insertions(+), 68 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 2ff3463ce..f22131351 100644
--- a/packages/react/src/modules/guide/components/Toolbar/V2/FocusChin.tsx
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/FocusChin.tsx
@@ -5,52 +5,13 @@ import { Tooltip } from "@telegraph/tooltip";
 import { Text } from "@telegraph/typography";
 import { ChevronLeft, ChevronRight, X } from "lucide-react";
 
-import { DisplayOption } from "./helpers";
-// import React from "react";
-
 import { InspectionResultOk } from "./useInspectGuideClientStore";
 
-// const findNextPrevKey = (
-//   currKey: string,
-//   guides: InspectionResultOk["guides"]
-// ) => {
-//   const selectableGuides = guides.filter(g => !!g.annotation.selectable);
-//   const currIndex = selectableGuides.findIndex(g => g.key === currKey);
-//
-//   const prevGuide = currIndex === 0
-//     ? undefined
-//     : selectableGuides[currIndex - 1];
-//
-//   const nextGuide = currIndex + 1 > selectableGuides.length - 1
-//     ? undefined
-//     : selectableGuides[currIndex + 1];
-//
-//   return { prev: prevGuide, next: nextGuide };
-// }
-// const findNextGuideKey = (
-//   currKey: string,
-//   guides: InspectionResultOk["guides"]
-// ) => {
-//   const selectableGuides = guides.filter(g => !!g.annotation.selectable);
-//   const currIndex = selectableGuides.findIndex(g => g.key === currKey);
-//
-//   const prevGuide = currIndex === 0
-//     ? undefined
-//     : selectableGuides[currIndex - 1];
-//
-//   const nextGuide = currIndex + 1 > selectableGuides.length - 1
-//     ? undefined
-//     : selectableGuides[currIndex + 1];
-//
-//   return { prev: prevGuide, next: nextGuide };
-// }
-
 type Props = {
   guides: InspectionResultOk["guides"];
-  displayOption: DisplayOption;
 };
 
-export const FocusChin = ({ guides, displayOption }: Props) => {
+export const FocusChin = ({ guides }: Props) => {
   const { client } = useGuideContext();
   const { debugSettings } = useStore(client.store, (state) => ({
     debugSettings: state.debug || {},
@@ -58,33 +19,12 @@ export const FocusChin = ({ guides, displayOption }: Props) => {
 
   const focusedKeys = Object.keys(debugSettings.focusedGuideKeys || {});
 
-  // const { prev, next } = React.useMemo(() => {
-  //   if (focusedKeys.length === 0) {
-  //     return {}
-  //   }
-  //   const currentKey = focusedKeys[0];
-  //
-  //   return findNextAndPrevGuideKey(currentKey, guides)
-  // }, [displayOption, focusedKeys.length]);
-
   const isFocused = focusedKeys.length > 0;
   if (!isFocused) {
     return null;
   }
 
-  const currentKey = focusedKeys[0];
-
-  // const currentIndex = currentKey ? guideKeys.indexOf(currentKey) : -1;
-
-  // const setFocus = (key: string) => {
-  //   client.setDebug({
-  //     ...debugSettings,
-  //     focusedGuideKeys: { [key]: true },
-  //   });
-  // };
-  //
-  // const hasPrev = currentIndex > 0;
-  // const hasNext = currentIndex >= 0 && currentIndex < guideKeys.length - 1;
+  const currentKey = focusedKeys[0]!;
 
   return (
     <Box
@@ -105,7 +45,6 @@ export const FocusChin = ({ guides, displayOption }: Props) => {
               variant="ghost"
               color="blue"
               leadingIcon={{ icon: ChevronLeft, alt: "Previous guide" }}
-              // disabled={!hasPrev}
               onClick={() => {
                 const selectableGuides = guides.filter(
                   (g) => !!g.annotation.selectable.status,
@@ -113,7 +52,6 @@ export const FocusChin = ({ guides, displayOption }: Props) => {
                 const currIndex = selectableGuides.findIndex(
                   (g) => g.key === currentKey,
                 );
-
                 const prevGuide =
                   currIndex === 0 ? undefined : selectableGuides[currIndex - 1];
 
@@ -132,16 +70,13 @@ export const FocusChin = ({ guides, displayOption }: Props) => {
               variant="ghost"
               color="blue"
               leadingIcon={{ icon: ChevronRight, alt: "Next guide" }}
-              // disabled={!hasNext}
               onClick={() => {
                 const selectableGuides = guides.filter(
                   (g) => !!g.annotation.selectable.status,
                 );
-                console.log(1, selectableGuides);
                 const currIndex = selectableGuides.findIndex(
                   (g) => g.key === currentKey,
                 );
-
                 const nextGuide =
                   currIndex + 1 > selectableGuides.length - 1
                     ? undefined
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 8f19a37d8..c38096cde 100644
--- a/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
@@ -362,7 +362,7 @@ export const V2 = () => {
           </Box>
 
           {/* Focus chin with dedicated controls */}
-          <FocusChin guides={guides} displayOption={displayOption} />
+          <FocusChin guides={guides} />
         </Stack>
       )}
     </Box>

From d23bccc62e12c2e5f8b04fbdaca2c04bd7b2f44a Mon Sep 17 00:00:00 2001
From: Thomas <thomas.whyyou@gmail.com>
Date: Tue, 31 Mar 2026 10:27:18 -0400
Subject: [PATCH 03/10] add a todo

---
 .../src/modules/guide/components/Toolbar/V2/FocusChin.tsx   | 6 ++++--
 1 file changed, 4 insertions(+), 2 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 f22131351..d4f092d0b 100644
--- a/packages/react/src/modules/guide/components/Toolbar/V2/FocusChin.tsx
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/FocusChin.tsx
@@ -26,6 +26,8 @@ export const FocusChin = ({ guides }: Props) => {
 
   const currentKey = focusedKeys[0]!;
 
+  // TODO: clear if focused guide key not found in guides.
+
   return (
     <Box
       borderTop="px"
@@ -53,7 +55,7 @@ export const FocusChin = ({ guides }: Props) => {
                   (g) => g.key === currentKey,
                 );
                 const prevGuide =
-                  currIndex === 0 ? undefined : selectableGuides[currIndex - 1];
+                  currIndex <= 0 ? undefined : selectableGuides[currIndex - 1];
 
                 if (!prevGuide) return;
 
@@ -78,7 +80,7 @@ export const FocusChin = ({ guides }: Props) => {
                   (g) => g.key === currentKey,
                 );
                 const nextGuide =
-                  currIndex + 1 > selectableGuides.length - 1
+                  currIndex < 0 || currIndex + 1 > selectableGuides.length - 1
                     ? undefined
                     : selectableGuides[currIndex + 1];
 

From 641d56bbb036f3570011bf10eca16d739c9a8af4 Mon Sep 17 00:00:00 2001
From: Thomas <thomas.whyyou@gmail.com>
Date: Tue, 31 Mar 2026 15:05:24 -0400
Subject: [PATCH 04/10] unfocus when switching the list filter if focused guide
 becomes not visible

---
 .../guide/components/Toolbar/V2/FocusChin.tsx |  6 ++---
 .../guide/components/Toolbar/V2/V2.tsx        | 23 +++++++++++++++++++
 2 files changed, 25 insertions(+), 4 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 d4f092d0b..87720d30f 100644
--- a/packages/react/src/modules/guide/components/Toolbar/V2/FocusChin.tsx
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/FocusChin.tsx
@@ -14,10 +14,10 @@ type Props = {
 export const FocusChin = ({ guides }: Props) => {
   const { client } = useGuideContext();
   const { debugSettings } = useStore(client.store, (state) => ({
-    debugSettings: state.debug || {},
+    debugSettings: state.debug,
   }));
 
-  const focusedKeys = Object.keys(debugSettings.focusedGuideKeys || {});
+  const focusedKeys = Object.keys(debugSettings?.focusedGuideKeys || {});
 
   const isFocused = focusedKeys.length > 0;
   if (!isFocused) {
@@ -26,8 +26,6 @@ export const FocusChin = ({ guides }: Props) => {
 
   const currentKey = focusedKeys[0]!;
 
-  // TODO: clear if focused guide key not found in guides.
-
   return (
     <Box
       borderTop="px"
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 c38096cde..c2514511b 100644
--- a/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
@@ -256,6 +256,29 @@ export const V2 = () => {
                   value={displayOption}
                   onValueChange={(val: DisplayOption) => {
                     if (!val) return;
+
+                    const debugSettings = client.store.state.debug;
+
+                    const focusedGuideKeys = Object.keys(
+                      debugSettings?.focusedGuideKeys || {},
+                    );
+
+                    // Exit out of focus if the currently focused guide is not
+                    // part of the selected list filter.
+                    if (result.status === "ok" && focusedGuideKeys.length > 0) {
+                      const currFocusedGuide = filterGuides(
+                        result.guides,
+                        val,
+                      ).find((g) => g.key === focusedGuideKeys[0]);
+
+                      if (!currFocusedGuide) {
+                        client.setDebug({
+                          ...debugSettings,
+                          focusedGuideKeys: {},
+                        });
+                      }
+                    }
+
                     setDisplayOption(val);
                   }}
                 >

From 5f75a1604f8fe3bc429c99c56ff9cfbabb1ca8e9 Mon Sep 17 00:00:00 2001
From: Thomas <thomas.whyyou@gmail.com>
Date: Tue, 31 Mar 2026 15:16:33 -0400
Subject: [PATCH 05/10] use guide order index number based on the guide group
 display seq

---
 .../src/modules/guide/components/Toolbar/V2/V2.tsx  |  4 ++--
 .../Toolbar/V2/useInspectGuideClientStore.ts        | 13 +++++++++----
 2 files changed, 11 insertions(+), 6 deletions(-)

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 c2514511b..d604ed465 100644
--- a/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
@@ -368,11 +368,11 @@ export const V2 = () => {
                 </Text>
               </Box>
             ) : (
-              guides.map((guide, idx) => (
+              guides.map((guide) => (
                 <GuideRow
                   key={guide.key}
                   guide={guide}
-                  orderIndex={idx}
+                  orderIndex={guide.orderIndex}
                   isExpanded={guide.key === expandedGuideRowKey}
                   onClick={() => {
                     setExpandedGuideRowKey((k) =>
diff --git a/packages/react/src/modules/guide/components/Toolbar/V2/useInspectGuideClientStore.ts b/packages/react/src/modules/guide/components/Toolbar/V2/useInspectGuideClientStore.ts
index 77cc36d38..edbbdf4ee 100644
--- a/packages/react/src/modules/guide/components/Toolbar/V2/useInspectGuideClientStore.ts
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/useInspectGuideClientStore.ts
@@ -91,6 +91,7 @@ type GuideAnnotation = AnnotatedStatuses & {
 };
 
 export type AnnotatedGuide = KnockGuide & {
+  orderIndex: number;
   annotation: GuideAnnotation;
 
   // Legacy fields, typed only to make tsc happy when we prune these out.
@@ -103,6 +104,7 @@ export type AnnotatedGuide = KnockGuide & {
 // never been published to switchboard.
 export type UncommittedGuide = {
   __typename: "UncommittedGuide";
+  orderIndex: number;
   key: KnockGuide["key"];
   active: false;
   bypass_global_group_limit: false;
@@ -364,6 +366,7 @@ export const resolveIsQualified = ({
 
 const annotateGuide = (
   guide: KnockGuide,
+  orderIndex: number,
   snapshot: StoreStateSnapshot,
   stage: KnockGuideClientGroupStage | undefined,
 ): AnnotatedGuide => {
@@ -389,14 +392,16 @@ const annotateGuide = (
 
   return {
     ...guide,
+    orderIndex,
     annotation,
   };
 };
 
-const newUncommittedGuide = (key: KnockGuide["key"]) =>
+const newUncommittedGuide = (key: KnockGuide["key"], orderIndex: number) =>
   ({
     __typename: "UncommittedGuide",
     key,
+    orderIndex,
     active: false,
     bypass_global_group_limit: false,
     annotation: {
@@ -458,13 +463,13 @@ export const useInspectGuideClientStore = (
 
   // Annotate guides for various eligibility, activation and query statuses
   // that are useful for debugging purposes.
-  const orderedGuides = defaultGroup.display_sequence.map((guideKey) => {
+  const orderedGuides = defaultGroup.display_sequence.map((guideKey, index) => {
     const guide = snapshot.guides[guideKey];
     if (!guide) {
-      return newUncommittedGuide(guideKey);
+      return newUncommittedGuide(guideKey, index);
     }
 
-    return annotateGuide(guide, snapshot, groupStage);
+    return annotateGuide(guide, index, snapshot, groupStage);
   });
 
   // Check if the focused guide actually exists and is selectable on the page.

From 9a3e61ba6fc229b61d97e0cbcc0ed19f2bf913cd Mon Sep 17 00:00:00 2001
From: Thomas <thomas.whyyou@gmail.com>
Date: Wed, 1 Apr 2026 10:31:31 -0400
Subject: [PATCH 06/10] show an empty state message when no guides under the
 current filter

---
 .../react/src/modules/guide/components/Toolbar/V2/V2.tsx    | 6 ++++++
 1 file changed, 6 insertions(+)

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 d604ed465..cc9a31ff6 100644
--- a/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
@@ -367,6 +367,12 @@ export const V2 = () => {
                   {result.message}
                 </Text>
               </Box>
+            ) : guides.length === 0 ? (
+              <Box px="2" pb="1" style={{ lineHeight: "1.2" }}>
+                <Text as="span" size="1" weight="medium" color="default">
+                  No guides match the current filter.
+                </Text>
+              </Box>
             ) : (
               guides.map((guide) => (
                 <GuideRow

From 0353751f60ccaf30d0850c97788a3898be0b361f Mon Sep 17 00:00:00 2001
From: Thomas <thomas.whyyou@gmail.com>
Date: Wed, 1 Apr 2026 10:35:53 -0400
Subject: [PATCH 07/10] changeset

---
 .changeset/hip-hoops-kneel.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/hip-hoops-kneel.md

diff --git a/.changeset/hip-hoops-kneel.md b/.changeset/hip-hoops-kneel.md
new file mode 100644
index 000000000..4bd67c2ad
--- /dev/null
+++ b/.changeset/hip-hoops-kneel.md
@@ -0,0 +1,5 @@
+---
+"@knocklabs/react": patch
+---
+
+[Guides] Add FocusChin to highlight focus mode w/ dedicated controls

From 09276909c5dfd3e505595713642c7242cd461c6c Mon Sep 17 00:00:00 2001
From: Thomas <thomas.whyyou@gmail.com>
Date: Wed, 1 Apr 2026 10:39:55 -0400
Subject: [PATCH 08/10] change focus lock -> focus mode

---
 .../react/src/modules/guide/components/Toolbar/V2/FocusChin.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

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 87720d30f..42dd92ff1 100644
--- a/packages/react/src/modules/guide/components/Toolbar/V2/FocusChin.tsx
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/FocusChin.tsx
@@ -36,7 +36,7 @@ export const FocusChin = ({ guides }: Props) => {
     >
       <Stack align="center" justify="space-between">
         <Text as="span" size="1" weight="medium" color="blue">
-          Focus lock: {currentKey}
+          Focus mode: {currentKey}
         </Text>
         <Stack align="center" gap="1">
           <Tooltip label="Focus previous guide">

From 38a54604a1cacf9db02dcc5c826bb032dcb56064 Mon Sep 17 00:00:00 2001
From: Thomas <thomas.whyyou@gmail.com>
Date: Wed, 1 Apr 2026 11:20:12 -0400
Subject: [PATCH 09/10] truncate a long guide key in FocusChin

---
 .../guide/components/Toolbar/V2/FocusChin.tsx  | 18 +++++++++++++++---
 1 file changed, 15 insertions(+), 3 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 42dd92ff1..22d2e3ccf 100644
--- a/packages/react/src/modules/guide/components/Toolbar/V2/FocusChin.tsx
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/FocusChin.tsx
@@ -34,11 +34,23 @@ export const FocusChin = ({ guides }: Props) => {
       overflow="hidden"
       backgroundColor="blue-2"
     >
-      <Stack align="center" justify="space-between">
-        <Text as="span" size="1" weight="medium" color="blue">
+      <Stack align="center" justify="space-between" gap="4">
+        <Text
+          as="span"
+          size="1"
+          weight="medium"
+          color="blue"
+          style={{
+            display: "block",
+            overflow: "hidden",
+            textOverflow: "ellipsis",
+            whiteSpace: "nowrap",
+            minWidth: 0,
+          }}
+        >
           Focus mode: {currentKey}
         </Text>
-        <Stack align="center" gap="1">
+        <Stack align="center" gap="1" style={{ flexShrink: 0 }}>
           <Tooltip label="Focus previous guide">
             <Button
               size="0"

From 91adc51a56451c403705d4a15b7414d23ab00262 Mon Sep 17 00:00:00 2001
From: Thomas <thomas.whyyou@gmail.com>
Date: Wed, 1 Apr 2026 14:22:22 -0400
Subject: [PATCH 10/10] auto scroll to a focused guide if it goes outside of
 scroll view

---
 .../guide/components/Toolbar/V2/FocusChin.tsx | 47 ++++++++++++++++++-
 .../guide/components/Toolbar/V2/GuideRow.tsx  |  4 ++
 .../guide/components/Toolbar/V2/V2.tsx        | 10 +++-
 3 files changed, 58 insertions(+), 3 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 22d2e3ccf..337239604 100644
--- a/packages/react/src/modules/guide/components/Toolbar/V2/FocusChin.tsx
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/FocusChin.tsx
@@ -4,14 +4,51 @@ import { Box, Stack } from "@telegraph/layout";
 import { Tooltip } from "@telegraph/tooltip";
 import { Text } from "@telegraph/typography";
 import { ChevronLeft, ChevronRight, X } from "lucide-react";
+import * as React from "react";
 
+import { GUIDE_ROW_DATA_SELECTOR } from "./GuideRow";
 import { InspectionResultOk } from "./useInspectGuideClientStore";
 
+// Extra scroll overshoot so the focused guide plus ~1-2 neighbors are visible,
+// reducing how often consecutive next/prev clicks trigger a scroll.
+const SCROLL_OVERSHOOT = 60;
+
+const maybeScrollGuideIntoView = (container: HTMLElement, guideKey: string) => {
+  requestAnimationFrame(() => {
+    const el = container.querySelector(
+      `[${GUIDE_ROW_DATA_SELECTOR}="${CSS.escape(guideKey)}"]`,
+    );
+    if (!el || !(el instanceof HTMLElement)) return;
+
+    const containerRect = container.getBoundingClientRect();
+    const elRect = el.getBoundingClientRect();
+
+    if (elRect.top < containerRect.top) {
+      container.scrollTo({
+        top:
+          container.scrollTop -
+          (containerRect.top - elRect.top) -
+          SCROLL_OVERSHOOT,
+        behavior: "smooth",
+      });
+    } else if (elRect.bottom > containerRect.bottom) {
+      container.scrollTo({
+        top:
+          container.scrollTop +
+          (elRect.bottom - containerRect.bottom) +
+          SCROLL_OVERSHOOT,
+        behavior: "smooth",
+      });
+    }
+  });
+};
+
 type Props = {
   guides: InspectionResultOk["guides"];
+  guideListRef: React.RefObject<HTMLDivElement | null>;
 };
 
-export const FocusChin = ({ guides }: Props) => {
+export const FocusChin = ({ guides, guideListRef }: Props) => {
   const { client } = useGuideContext();
   const { debugSettings } = useStore(client.store, (state) => ({
     debugSettings: state.debug,
@@ -73,6 +110,10 @@ export const FocusChin = ({ guides }: Props) => {
                   ...debugSettings,
                   focusedGuideKeys: { [prevGuide.key]: true },
                 });
+
+                if (guideListRef.current) {
+                  maybeScrollGuideIntoView(guideListRef.current, prevGuide.key);
+                }
               }}
             />
           </Tooltip>
@@ -100,6 +141,10 @@ export const FocusChin = ({ guides }: Props) => {
                   ...debugSettings,
                   focusedGuideKeys: { [nextGuide.key]: true },
                 });
+
+                if (guideListRef.current) {
+                  maybeScrollGuideIntoView(guideListRef.current, nextGuide.key);
+                }
               }}
             />
           </Tooltip>
diff --git a/packages/react/src/modules/guide/components/Toolbar/V2/GuideRow.tsx b/packages/react/src/modules/guide/components/Toolbar/V2/GuideRow.tsx
index df8d0a1cd..58f27a911 100644
--- a/packages/react/src/modules/guide/components/Toolbar/V2/GuideRow.tsx
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/GuideRow.tsx
@@ -25,6 +25,8 @@ import {
   isUncommittedGuide,
 } from "./useInspectGuideClientStore";
 
+export const GUIDE_ROW_DATA_SELECTOR = "data-kgt-guide-row-key";
+
 const Pill = ({
   label,
   color = "gray",
@@ -188,6 +190,7 @@ export const GuideRow = ({ guide, orderIndex, isExpanded, onClick }: Props) => {
 
   const dots = getStatusDots(guide);
   const summary = getStatusSummary(guide);
+  const dataAttrs = { [GUIDE_ROW_DATA_SELECTOR]: guide.key };
 
   return (
     <Box
@@ -199,6 +202,7 @@ export const GuideRow = ({ guide, orderIndex, isExpanded, onClick }: Props) => {
       onMouseEnter={() => setIsHovered(true)}
       onMouseLeave={() => setIsHovered(false)}
       style={{ cursor: "pointer" }}
+      {...dataAttrs}
     >
       <Stack
         h="7"
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 cc9a31ff6..c40921ed9 100644
--- a/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
@@ -129,6 +129,7 @@ export const V2 = () => {
   }, []);
 
   const containerRef = React.useRef<HTMLDivElement>(null);
+  const guideListRef = React.useRef<HTMLDivElement>(null);
   const { position, isDragging, handlePointerDown, hasDraggedRef } =
     useDraggable({
       elementRef: containerRef,
@@ -353,7 +354,12 @@ export const V2 = () => {
           )}
 
           {/* Guide list content area */}
-          <Box p="1" overflow="auto" style={{ maxHeight: "calc(80vh - 96px)" }}>
+          <Box
+            tgphRef={guideListRef}
+            p="1"
+            overflow="auto"
+            style={{ maxHeight: "calc(80vh - 96px)" }}
+          >
             {result.status === "error" ? (
               <Box px="2" pb="1" style={{ lineHeight: "1.2" }}>
                 <Text
@@ -391,7 +397,7 @@ export const V2 = () => {
           </Box>
 
           {/* Focus chin with dedicated controls */}
-          <FocusChin guides={guides} />
+          <FocusChin guides={guides} guideListRef={guideListRef} />
         </Stack>
       )}
     </Box>