From 695d99279d6928c69765bfdd2fed628bdf7037f3 Mon Sep 17 00:00:00 2001
From: Thomas <thomas.whyyou@gmail.com>
Date: Tue, 24 Mar 2026 18:22:01 -0400
Subject: [PATCH 1/2] better handling of focus error reason and message

---
 .../guide/components/Toolbar/V2/GuideRow.tsx  | 12 ++++---
 .../guide/components/Toolbar/V2/V2.tsx        |  2 +-
 .../guide/components/Toolbar/V2/helpers.ts    |  6 ++++
 .../Toolbar/V2/useInspectGuideClientStore.ts  | 36 ++++++++++++++-----
 4 files changed, 43 insertions(+), 13 deletions(-)

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 0e72f2f03..2222f3122 100644
--- a/packages/react/src/modules/guide/components/Toolbar/V2/GuideRow.tsx
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/GuideRow.tsx
@@ -13,6 +13,7 @@ import {
   GuideAnnotatedStatusDot as StatusDot,
 } from "./GuideAnnotatedStatusDot";
 import { GuideRowDetails } from "./GuideRowDetails";
+import { ERROR_MESSAGE } from "./helpers";
 import {
   AnnotatedGuide,
   AnnotatedStatuses,
@@ -354,12 +355,15 @@ export const GuideRow = ({ guide, orderIndex, isExpanded, onClick }: Props) => {
 
           <Tooltip
             label={
+              isUncommittedGuide(guide)
+                ? ERROR_MESSAGE.focusUncommittedGuide
+                : guide.annotation.selectable.status === undefined
+                  ? ERROR_MESSAGE.focusUnselectableGuide
+                  : ""
+            }
+            enabled={
               isUncommittedGuide(guide) ||
               guide.annotation.selectable.status === undefined
-                ? "No component found that can render this guide"
-                : isFocused
-                  ? "Unfocus this guide"
-                  : "Focus on this guide"
             }
           >
             <Button
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 1b3e26990..096daaeab 100644
--- a/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/V2.tsx
@@ -334,7 +334,7 @@ export const V2 = () => {
           {/* Guide list content area */}
           <Box p="1" overflow="auto" style={{ maxHeight: "calc(80vh - 96px)" }}>
             {result.status === "error" ? (
-              <Box px="2" pb="1">
+              <Box px="2" pb="1" style={{ lineHeight: "1.2" }}>
                 <Text
                   as="span"
                   size="1"
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 913029a5f..8d096af1a 100644
--- a/packages/react/src/modules/guide/components/Toolbar/V2/helpers.ts
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/helpers.ts
@@ -84,3 +84,9 @@ export const clearRunConfigLS = () => {
     // localStorage may be unavailable (e.g. private browsing)
   }
 };
+
+export const ERROR_MESSAGE = {
+  focusUnknownGuide: "No such guide exists",
+  focusUncommittedGuide: "This guide has not been committed",
+  focusUnselectableGuide: "No component that can render this guide is present",
+};
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 78db9d833..41192d6ce 100644
--- a/packages/react/src/modules/guide/components/Toolbar/V2/useInspectGuideClientStore.ts
+++ b/packages/react/src/modules/guide/components/Toolbar/V2/useInspectGuideClientStore.ts
@@ -9,7 +9,7 @@ import {
 } from "@knocklabs/client";
 import { useGuideContext, useStore } from "@knocklabs/react-core";
 
-import { ToolbarV2RunConfig } from "./helpers";
+import { ERROR_MESSAGE, ToolbarV2RunConfig } from "./helpers";
 
 const byKey = <T extends { key: string }>(items: T[]) => {
   return items.reduce((acc, item) => ({ ...acc, [item.key]: item }), {});
@@ -121,7 +121,12 @@ export type InspectionResultOk = {
 };
 type InspectionResultError = {
   status: "error";
-  error: "no_guides_fetched" | "no_guide_group" | "no_guide_present";
+  error:
+    | "no_guides_fetched"
+    | "no_guide_group"
+    | "focus_unknown_guide"
+    | "focus_uncommitted_guide"
+    | "focus_unselectable_guide";
   message: string;
 };
 type InspectionResult = InspectionResultOk | InspectionResultError;
@@ -465,14 +470,29 @@ export const useInspectGuideClientStore = (
   // Check if the focused guide actually exists and is selectable on the page.
   const focusedGuideKey = Object.keys(runConfig.focusedGuideKeys || {})[0];
   if (groupStage?.status === "closed" && focusedGuideKey) {
-    const focusableGuide = orderedGuides.find(
-      (g) => g.key === focusedGuideKey && g.annotation.selectable.status,
-    );
-    if (!focusableGuide) {
+    const foundGuide = orderedGuides.find((g) => g.key === focusedGuideKey);
+
+    if (!foundGuide) {
+      return {
+        status: "error",
+        error: "focus_unknown_guide",
+        message: `Unable to display \`${focusedGuideKey}\`, ${ERROR_MESSAGE.focusUnknownGuide.toLowerCase()}.`,
+      };
+    }
+
+    if (isUncommittedGuide(foundGuide)) {
+      return {
+        status: "error",
+        error: "focus_uncommitted_guide",
+        message: `Unable to display \`${focusedGuideKey}\`, ${ERROR_MESSAGE.focusUncommittedGuide.toLowerCase()}.`,
+      };
+    }
+
+    if (!foundGuide.annotation.selectable.status) {
       return {
         status: "error",
-        error: "no_guide_present",
-        message: `No component that can render \`${focusedGuideKey}\` was found`,
+        error: "focus_unselectable_guide",
+        message: `Unable to display \`${focusedGuideKey}\`, ${ERROR_MESSAGE.focusUnselectableGuide.toLowerCase()}.`,
       };
     }
   }

From fdd38c4ac519cbffc437cca3572eb578063a5d64 Mon Sep 17 00:00:00 2001
From: Thomas <thomas.whyyou@gmail.com>
Date: Tue, 24 Mar 2026 18:28:36 -0400
Subject: [PATCH 2/2] add tests

---
 .../V2/useInspectGuideClientStore.test.ts     | 66 +++++++++++++++++--
 1 file changed, 62 insertions(+), 4 deletions(-)

diff --git a/packages/react/test/guide/Toolbar/V2/useInspectGuideClientStore.test.ts b/packages/react/test/guide/Toolbar/V2/useInspectGuideClientStore.test.ts
index ac107a0b0..102749ab7 100644
--- a/packages/react/test/guide/Toolbar/V2/useInspectGuideClientStore.test.ts
+++ b/packages/react/test/guide/Toolbar/V2/useInspectGuideClientStore.test.ts
@@ -1548,10 +1548,10 @@ describe("useInspectGuideClientStore", () => {
     });
   });
 
-  // ----- focused guide (no_guide_present) -----
+  // ----- focused guide errors -----
 
   describe("focused guide filtering", () => {
-    test("returns no_guide_present when focused guide is not selectable on closed stage", () => {
+    test("returns focus_unknown_guide when focused guide key is not in ordered guides", () => {
       mockGroupStage = {
         status: "closed",
         ordered: ["g1"],
@@ -1574,8 +1574,66 @@ describe("useInspectGuideClientStore", () => {
       });
       expect(result).toEqual({
         status: "error",
-        error: "no_guide_present",
-        message: "No component that can render `other_guide` was found",
+        error: "focus_unknown_guide",
+        message: "Unable to display `other_guide`, no such guide exists.",
+      });
+    });
+
+    test("returns focus_uncommitted_guide when focused guide is uncommitted", () => {
+      mockGroupStage = {
+        status: "closed",
+        ordered: ["uncommitted_g"],
+        resolved: undefined,
+        timeoutId: null,
+        results: {},
+      };
+      // Guide key is in display_sequence but NOT in guides map => UncommittedGuide
+      setSnapshot({
+        guideGroups: [makeGuideGroup(["uncommitted_g"])],
+        guides: {},
+        ineligibleGuides: {},
+      });
+
+      const result = renderInspect({
+        isVisible: true,
+        focusedGuideKeys: { uncommitted_g: true },
+      });
+      expect(result).toEqual({
+        status: "error",
+        error: "focus_uncommitted_guide",
+        message:
+          "Unable to display `uncommitted_g`, this guide has not been committed.",
+      });
+    });
+
+    test("returns focus_unselectable_guide when focused guide exists but is not selectable", () => {
+      mockGroupStage = {
+        status: "closed",
+        ordered: ["g1"],
+        resolved: "g1",
+        timeoutId: null,
+        results: {
+          key: { g1: { one: makeSelectionResult() } },
+        },
+      };
+      const guide = makeGuide({ key: "g1" });
+      // Guide is in the group but not queried by any matching selection result,
+      // so selectable.status will be undefined (not selectable).
+      setSnapshot({
+        guideGroups: [makeGuideGroup(["g1", "g2"])],
+        guides: { g1: guide, g2: makeGuide({ key: "g2" }) },
+        ineligibleGuides: {},
+      });
+
+      const result = renderInspect({
+        isVisible: true,
+        focusedGuideKeys: { g2: true },
+      });
+      expect(result).toEqual({
+        status: "error",
+        error: "focus_unselectable_guide",
+        message:
+          "Unable to display `g2`, no component that can render this guide is present.",
       });
     });