feat: add focusedGuideKeys debug setting to pin a guide (#879)

Author: thomaswhyyou

packages/client/src/clients/guide/client.ts

@@ -211,6 +211,12 @@ const predicate = (
   // If in debug mode with a forced guide key, bypass other filtering and always
   // return true for that guide only. This should always run AFTER checking the
   // filters but BEFORE checking archived status and location rules.
+  if (
+    debug.focusedGuideKeys &&
+    Object.keys(debug.focusedGuideKeys).length > 0
+  ) {
+    return !!debug.focusedGuideKeys[guide.key];
+  }
   if (debug.forcedGuideKey) {
     return debug.forcedGuideKey === guide.key;
   }
@@ -563,7 +569,11 @@ export class KnockGuideClient {
     // Clear debug state from store
     this.store.setState((state) => ({
       ...state,
-      debug: { forcedGuideKey: null, previewSessionId: null },
+      debug: {
+        forcedGuideKey: null,
+        previewSessionId: null,
+        focusedGuideKeys: {},
+      },
       previewGuides: {}, // Clear preview guides when exiting debug mode
     }));
 
@@ -591,6 +601,7 @@ export class KnockGuideClient {
       debug: {
         skipEngagementTracking: true,
         ignoreDisplayInterval: true,
+        focusedGuideKeys: {},
         ...debugOpts,
         debugging: true,
       },
@@ -754,6 +765,10 @@ export class KnockGuideClient {
       return guide;
     }
 
+    // If focused while in debug mode, then we want to ignore the guide order
+    // and throttle settings and force render this guide.
+    const focusedInDebug = state.debug?.focusedGuideKeys?.[guide.key];
+
     const throttled = !opts.includeThrottled && checkStateIfThrottled(state);
 
     switch (this.stage.status) {
@@ -770,6 +785,13 @@ export class KnockGuideClient {
         // we can re-resolve when the group stage closes.
         this.stage.ordered[index] = guide.key;
 
+        if (focusedInDebug) {
+          this.knock.log(
+            `[Guide] Focused to return \`${guide.key}\` (stage: ${formatGroupStage(this.stage)})`,
+          );
+          return guide;
+        }
+
         if (throttled) {
           this.knock.log(`[Guide] Throttling the selected guide: ${guide.key}`);
           return undefined;
@@ -783,6 +805,13 @@ export class KnockGuideClient {
       }
 
       case "closed": {
+        if (focusedInDebug) {
+          this.knock.log(
+            `[Guide] Focused to return \`${guide.key}\` (stage: ${formatGroupStage(this.stage)})`,
+          );
+          return guide;
+        }
+
         if (throttled) {
           this.knock.log(`[Guide] Throttling the selected guide: ${guide.key}`);
           return undefined;
@@ -1082,7 +1111,10 @@ export class KnockGuideClient {
       // Get the next unarchived step.
       getStep() {
         // If debugging this guide, return the first step regardless of archive status
-        if (self.store.state.debug?.forcedGuideKey === this.key) {
+        if (
+          self.store.state.debug?.forcedGuideKey === this.key ||
+          self.store.state.debug?.focusedGuideKeys?.[this.key]
+        ) {
           return this.steps[0];
         }
 

packages/client/src/clients/guide/types.ts

@@ -232,6 +232,7 @@ export type QueryStatus = {
 export type DebugState = {
   debugging?: boolean;
   forcedGuideKey?: string | null;
+  focusedGuideKeys?: Record<KnockGuide["key"], true>;
   previewSessionId?: string | null;
   skipEngagementTracking?: boolean;
   ignoreDisplayInterval?: boolean;

packages/client/test/clients/guide/guide.test.ts

@@ -2260,6 +2260,116 @@ describe("KnockGuideClient", () => {
       expect(result).toBeUndefined();
     });
 
+    test("returns an archived guide when focusedGuideKeys includes it", () => {
+      const archivedGuide = {
+        ...mockGuideThree,
+        steps: [
+          {
+            ...mockStep,
+            message: {
+              ...mockStep.message,
+              archived_at: new Date().toISOString(),
+            },
+          },
+        ],
+      };
+
+      const stateWithArchivedGuide = {
+        guideGroups: [mockDefaultGroup],
+        guideGroupDisplayLogs: {},
+        guides: {
+          ...mockGuides,
+          [mockGuideThree.key]: archivedGuide,
+        },
+        ineligibleGuides: {},
+        previewGuides: {},
+        queries: {},
+        location: undefined,
+        counter: 0,
+        debug: {
+          focusedGuideKeys: { [mockGuideThree.key]: true as const },
+        },
+      };
+
+      const client = new KnockGuideClient(mockKnock, channelId);
+      const result = client["_selectGuide"](stateWithArchivedGuide, {
+        key: mockGuideThree.key,
+      });
+
+      // Should return the focused guide even though it's archived
+      expect(result!.key).toBe("system_status");
+      expect(result!.steps[0]!.message.archived_at).toBeTruthy();
+    });
+
+    test("returns only focused guides when focusedGuideKeys is set", () => {
+      const stateWithGuides = {
+        guideGroups: [mockDefaultGroup],
+        guideGroupDisplayLogs: {},
+        guides: mockGuides,
+        ineligibleGuides: {},
+        previewGuides: {},
+        queries: {},
+        location: undefined,
+        counter: 0,
+        debug: {
+          focusedGuideKeys: { [mockGuideTwo.key]: true as const },
+        },
+      };
+
+      const client = new KnockGuideClient(mockKnock, channelId);
+      const result = client["_selectGuide"](stateWithGuides);
+
+      // Should return the focused guide
+      expect(result!.key).toBe("feature_tour");
+    });
+
+    test("doesn't return a guide not in focusedGuideKeys", () => {
+      const stateWithGuides = {
+        guideGroups: [mockDefaultGroup],
+        guideGroupDisplayLogs: {},
+        guides: mockGuides,
+        ineligibleGuides: {},
+        previewGuides: {},
+        queries: {},
+        location: undefined,
+        counter: 0,
+        debug: {
+          focusedGuideKeys: { [mockGuideTwo.key]: true as const },
+        },
+      };
+
+      const client = new KnockGuideClient(mockKnock, channelId);
+      const result = client["_selectGuide"](stateWithGuides, {
+        key: mockGuideOne.key,
+      });
+
+      // Guide one is not in focusedGuideKeys, so should not be returned
+      expect(result).toBeUndefined();
+    });
+
+    test("falls through to normal filtering when focusedGuideKeys is empty object", () => {
+      const stateWithGuides = {
+        guideGroups: [mockDefaultGroup],
+        guideGroupDisplayLogs: {},
+        guides: mockGuides,
+        ineligibleGuides: {},
+        previewGuides: {},
+        queries: {},
+        location: undefined,
+        counter: 0,
+        debug: {
+          focusedGuideKeys: {},
+        },
+      };
+
+      const client = new KnockGuideClient(mockKnock, channelId);
+      const result = client["_selectGuide"](stateWithGuides);
+
+      // Empty focusedGuideKeys should not filter — normal selection applies
+      expect(result).toBeDefined();
+      expect(result!.key).toBe("feature_tour");
+    });
+
     test("does not return a guide inside a throttle window ", () => {
       const stateWithGuides = {
         guideGroups: [
@@ -4217,6 +4327,152 @@ describe("KnockGuideClient", () => {
       expect(result).toBeDefined();
       expect(result!.key).toBe("onboarding");
     });
+
+    test("returns focused guide in closed stage even when throttled", () => {
+      const stateWithGuides = {
+        guideGroups: [throttleDefaultGroup],
+        guideGroupDisplayLogs: {
+          default: new Date().toISOString(),
+        },
+        guides: { onboarding: mockGuide },
+        ineligibleGuides: {},
+        previewGuides: {},
+        queries: {},
+        location: undefined,
+        counter: 0,
+        debug: {
+          focusedGuideKeys: { onboarding: true as const },
+        },
+      };
+
+      const client = new KnockGuideClient(mockKnock, channelId);
+
+      // Set up a closed stage with the guide resolved
+      client["stage"] = {
+        status: "closed",
+        ordered: ["onboarding"],
+        resolved: "onboarding",
+        results: {},
+        timeoutId: null,
+      };
+
+      // Focused guides bypass throttle in closed stage
+      const result = client.selectGuide(stateWithGuides, {
+        key: "onboarding",
+      });
+      expect(result).toBeDefined();
+      expect(result!.key).toBe("onboarding");
+    });
+
+    test("returns focused guide in patch stage even when throttled", () => {
+      const stateWithGuides = {
+        guideGroups: [throttleDefaultGroup],
+        guideGroupDisplayLogs: {
+          default: new Date().toISOString(),
+        },
+        guides: { onboarding: mockGuide },
+        ineligibleGuides: {},
+        previewGuides: {},
+        queries: {},
+        location: undefined,
+        counter: 0,
+        debug: {
+          focusedGuideKeys: { onboarding: true as const },
+        },
+      };
+
+      const client = new KnockGuideClient(mockKnock, channelId);
+
+      // Set up a closed stage then patch it
+      client["stage"] = {
+        status: "closed",
+        ordered: ["onboarding"],
+        resolved: "onboarding",
+        results: {},
+        timeoutId: null,
+      };
+      client["patchClosedGroupStage"]();
+
+      expect(client.getStage()!.status).toBe("patch");
+
+      // Focused guides bypass throttle in patch stage
+      const result = client.selectGuide(stateWithGuides, {
+        key: "onboarding",
+      });
+      expect(result).toBeDefined();
+      expect(result!.key).toBe("onboarding");
+    });
+
+    test("returns focused guide in patch stage even when not the resolved guide", () => {
+      const stateWithGuides = {
+        guideGroups: [throttleDefaultGroup],
+        guideGroupDisplayLogs: {},
+        guides: { onboarding: mockGuide },
+        ineligibleGuides: {},
+        previewGuides: {},
+        queries: {},
+        location: undefined,
+        counter: 0,
+        debug: {
+          focusedGuideKeys: { onboarding: true as const },
+        },
+      };
+
+      const client = new KnockGuideClient(mockKnock, channelId);
+
+      // Set up a closed stage where a DIFFERENT guide was resolved
+      client["stage"] = {
+        status: "closed",
+        ordered: ["onboarding"],
+        resolved: "some_other_guide",
+        results: {},
+        timeoutId: null,
+      };
+      client["patchClosedGroupStage"]();
+
+      expect(client.getStage()!.status).toBe("patch");
+
+      // Focused guides bypass the resolved check in patch stage
+      const result = client.selectGuide(stateWithGuides, {
+        key: "onboarding",
+      });
+      expect(result).toBeDefined();
+      expect(result!.key).toBe("onboarding");
+    });
+
+    test("returns focused guide in closed stage even when not the resolved guide", () => {
+      const stateWithGuides = {
+        guideGroups: [throttleDefaultGroup],
+        guideGroupDisplayLogs: {},
+        guides: { onboarding: mockGuide },
+        ineligibleGuides: {},
+        previewGuides: {},
+        queries: {},
+        location: undefined,
+        counter: 0,
+        debug: {
+          focusedGuideKeys: { onboarding: true as const },
+        },
+      };
+
+      const client = new KnockGuideClient(mockKnock, channelId);
+
+      // Set up a closed stage where a DIFFERENT guide was resolved
+      client["stage"] = {
+        status: "closed",
+        ordered: ["onboarding"],
+        resolved: "some_other_guide",
+        results: {},
+        timeoutId: null,
+      };
+
+      // Focused guides bypass the resolved check in closed stage
+      const result = client.selectGuide(stateWithGuides, {
+        key: "onboarding",
+      });
+      expect(result).toBeDefined();
+      expect(result!.key).toBe("onboarding");
+    });
   });
 
   describe("setDebug", () => {

packages/react/src/modules/guide/components/Toolbar/V2/GuideContextDetails.tsx

@@ -14,10 +14,7 @@ export const GuideContextDetails = () => {
   const { defaultGroup, debugSettings } = useStore(client.store, (state) => {
     return {
       defaultGroup: state.guideGroups[0],
-      debugSettings: {
-        skipEngagementTracking: !!state.debug?.skipEngagementTracking,
-        ignoreDisplayInterval: !!state.debug?.ignoreDisplayInterval,
-      },
+      debugSettings: state.debug || {},
     };
   });
   const displayInterval = defaultGroup?.display_interval ?? null;