@agent-native/toolkit 0.205.0 → 0.206.0-nightly-20261009011246

package/src/app/onboarding/FirstRunOnboarding.spec.tsx

@@ -5,6 +5,7 @@ import { registerFirstRunOnboardingExtension } from "@agent-native/core/client/o
 import { TooltipProvider } from "@agent-native/toolkit/ui/tooltip";
 import React, { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
+import { MemoryRouter, Route, Routes } from "react-router";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import { createToolkitI18nCatalog } from "../i18n.js";
@@ -31,7 +32,10 @@ const mocks = vi.hoisted(() => ({
   completeFirstRun: vi.fn(),
   useBuilderConnectFlow: vi.fn(),
   routePathname: "/",
+  useActualRouter: false,
+  navigate: vi.fn(),
   trackOnboardingEvent: vi.fn(),
+  setCustomKeyOnboardingAttempt: vi.fn(),
   useOnboarding: vi.fn(),
   useOnboardingPreviewMode: vi.fn(),
   useOnboardingPreviewStep: vi.fn(),
@@ -41,7 +45,12 @@ vi.mock("react-router", async (importOriginal) => {
   const actual = await importOriginal<typeof import("react-router")>();
   return {
     ...actual,
-    useLocation: () => ({ pathname: mocks.routePathname }),
+    useLocation: () =>
+      mocks.useActualRouter
+        ? actual.useLocation()
+        : { pathname: mocks.routePathname },
+    useNavigate: () =>
+      mocks.useActualRouter ? actual.useNavigate() : mocks.navigate,
   };
 });
 
@@ -50,6 +59,8 @@ vi.mock("@agent-native/core/client/feature-flags/use-feature-flag", () => ({
 }));
 
 vi.mock("@agent-native/core/client/onboarding/use-onboarding", () => ({
+  createOnboardingCorrelationId: () => "test-onboarding-correlation-id",
+  setCustomKeyOnboardingAttempt: mocks.setCustomKeyOnboardingAttempt,
   trackOnboardingEvent: mocks.trackOnboardingEvent,
   useOnboarding: mocks.useOnboarding,
 }));
@@ -77,9 +88,13 @@ describe("FirstRunOnboarding", () => {
     vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
     mocks.completeFirstRun.mockReset();
     mocks.routePathname = "/";
+    mocks.useActualRouter = false;
+    mocks.navigate.mockReset();
     mocks.completeFirstRun.mockResolvedValue(undefined);
     mocks.useBuilderConnectFlow.mockReset();
     mocks.trackOnboardingEvent.mockReset();
+    mocks.setCustomKeyOnboardingAttempt.mockReset();
+    mocks.setCustomKeyOnboardingAttempt.mockResolvedValue("stored");
     mocks.useOnboarding.mockReset();
     mocks.useOnboardingPreviewMode.mockReset();
     mocks.useOnboardingPreviewStep.mockReset();
@@ -768,6 +783,11 @@ describe("FirstRunOnboarding", () => {
         .querySelector("[data-testid='first-run-role-skip']")
         ?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
     });
+    expect(
+      document.body.querySelector(
+        '[data-testid="first-run-builder-create-account"]',
+      )?.textContent,
+    ).toBe("Use Builder.io");
     act(() => {
       document.body
         .querySelector('[data-testid="first-run-builder-create-account"]')
@@ -1325,6 +1345,7 @@ describe("FirstRunOnboarding", () => {
     );
     const attemptId = (methodClick?.[1] as Record<string, unknown>)
       ?.onboarding_attempt_id;
+    expect(mocks.setCustomKeyOnboardingAttempt).toHaveBeenCalledWith(attemptId);
     expect(mocks.trackOnboardingEvent).toHaveBeenCalledWith(
       "onboarding_method_outcome",
       expect.objectContaining({
@@ -1336,6 +1357,61 @@ describe("FirstRunOnboarding", () => {
     window.history.replaceState(null, "", "/");
   });
 
+  it.each(["no_session", "unavailable"] as const)(
+    "navigates while custom-key attempt storage resolves and reports %s",
+    async (status) => {
+      let resolveAttemptStorage:
+        | ((status: "stored" | "no_session" | "unavailable") => void)
+        | undefined;
+      mocks.setCustomKeyOnboardingAttempt.mockReturnValue(
+        new Promise((resolve) => {
+          resolveAttemptStorage = resolve;
+        }),
+      );
+
+      act(() => {
+        root.render(
+          <TooltipProvider>
+            <FirstRunOnboarding />
+          </TooltipProvider>,
+        );
+      });
+      act(() => {
+        document.body
+          .querySelector("[data-testid='first-run-role-skip']")
+          ?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+      });
+
+      await act(async () => {
+        document.body
+          .querySelector("[data-testid='first-run-open-key-settings']")
+          ?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+        await Promise.resolve();
+      });
+
+      expect(window.location.pathname).toBe(
+        manualSetupSettingsRoute({ redesign: true }),
+      );
+      expect(mocks.trackOnboardingEvent).toHaveBeenCalledWith(
+        "onboarding_method_outcome",
+        expect.objectContaining({
+          method_id: "custom_keys",
+          outcome: "settings_opened",
+        }),
+      );
+
+      await act(async () => {
+        resolveAttemptStorage?.(status);
+        await Promise.resolve();
+      });
+      expect(mocks.trackOnboardingEvent).toHaveBeenCalledWith(
+        "onboarding_correlation_unavailable",
+        expect.objectContaining({ correlation_status: status }),
+      );
+      window.history.replaceState(null, "", "/");
+    },
+  );
+
   it("lets Clips skip provider setup and finish first-run onboarding", async () => {
     let resolveCompletion: (() => void) | undefined;
     mocks.completeFirstRun.mockImplementation(
@@ -1356,6 +1432,7 @@ describe("FirstRunOnboarding", () => {
       completeFirstRun: mocks.completeFirstRun,
       completeFirstRunError: null,
     });
+    mocks.routePathname = "/library";
 
     await act(async () => {
       root.render(
@@ -1399,7 +1476,8 @@ describe("FirstRunOnboarding", () => {
     });
 
     expect(mocks.completeFirstRun).toHaveBeenCalledOnce();
-    expect(window.location.pathname).toBe("/");
+    expect(mocks.navigate).toHaveBeenCalledOnce();
+    expect(mocks.navigate).toHaveBeenCalledWith("/record", { replace: true });
     expect(mocks.trackOnboardingEvent).toHaveBeenCalledWith(
       "onboarding_step_skipped",
       expect.objectContaining({
@@ -1414,6 +1492,63 @@ describe("FirstRunOnboarding", () => {
     );
   });
 
+  it("navigates to Clips recording inside the router basename", async () => {
+    mocks.useActualRouter = true;
+    mocks.useOnboardingPreviewMode.mockReturnValue(true);
+    mocks.useOnboardingPreviewStep.mockReturnValue("choice");
+    mocks.useOnboarding.mockReturnValue({
+      firstRun: true,
+      loading: false,
+      error: null,
+      profile: {
+        appId: "clips",
+        appName: "Clips",
+        capabilities: [],
+      },
+      completeFirstRun: mocks.completeFirstRun,
+      completeFirstRunError: null,
+    });
+    vi.stubEnv("VITE_APP_BASE_PATH", "/clips");
+    window.history.replaceState(
+      null,
+      "",
+      "/clips/library?onboarding=preview&step=choice",
+    );
+
+    await act(async () => {
+      root.render(
+        <MemoryRouter
+          basename="/clips"
+          initialEntries={["/clips/library?onboarding=preview&step=choice"]}
+        >
+          <Routes>
+            <Route path="/library" element={<FirstRunOnboarding />} />
+            <Route
+              path="/record"
+              element={<div data-testid="clips-record-route" />}
+            />
+            <Route path="*" element={<div data-testid="not-found-route" />} />
+          </Routes>
+        </MemoryRouter>,
+      );
+    });
+
+    await act(async () => {
+      document.body
+        .querySelector("[data-testid='first-run-setup-skip']")
+        ?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    expect(
+      document.body.querySelector('[data-testid="clips-record-route"]'),
+    ).not.toBeNull();
+    expect(
+      document.body.querySelector('[data-testid="not-found-route"]'),
+    ).toBeNull();
+  });
+
   it("does not start duplicate manual setup attempts while completion is pending", async () => {
     let resolveCompletion: (() => void) | undefined;
     mocks.completeFirstRun.mockImplementation(
@@ -1619,6 +1754,56 @@ describe("FirstRunOnboarding", () => {
     );
   });
 
+  it("does not reuse a failed skip redirect for manual setup completion", async () => {
+    mocks.completeFirstRun
+      .mockRejectedValueOnce(new Error("first-run completion failed: 500"))
+      .mockResolvedValueOnce(undefined);
+    mocks.useOnboarding.mockReturnValue({
+      firstRun: true,
+      loading: false,
+      error: null,
+      profile: {
+        appId: "clips",
+        appName: "Clips",
+        capabilities: [],
+      },
+      completeFirstRun: mocks.completeFirstRun,
+      completeFirstRunError: "first-run completion failed: 500",
+    });
+
+    await act(async () => {
+      root.render(
+        <TooltipProvider>
+          <FirstRunOnboarding />
+        </TooltipProvider>,
+      );
+    });
+    act(() => {
+      document.body
+        .querySelector("[data-testid='first-run-role-skip']")
+        ?.click();
+    });
+    await act(async () => {
+      document.body
+        .querySelector("[data-testid='first-run-setup-skip']")
+        ?.click();
+      await Promise.resolve();
+    });
+
+    expect(mocks.completeFirstRun).toHaveBeenCalledOnce();
+    await act(async () => {
+      document.body
+        .querySelector("[data-testid='first-run-open-key-settings']")
+        ?.click();
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    expect(mocks.completeFirstRun).toHaveBeenCalledTimes(2);
+    expect(mocks.navigate).not.toHaveBeenCalled();
+    expect(window.location.pathname).toBe("/settings/model");
+  });
+
   it("preserves the completed step when first-run completion succeeds on retry", async () => {
     let completionResult: boolean | void;
     mocks.completeFirstRun
@@ -1983,4 +2168,69 @@ describe("FirstRunOnboarding", () => {
       ),
     ).toBeNull();
   });
+
+  it("preserves a skip redirect when the diverted completion is retried", async () => {
+    mocks.completeFirstRun
+      .mockRejectedValueOnce(new Error("first-run completion failed: 500"))
+      .mockResolvedValueOnce(undefined);
+    mocks.useOnboarding.mockReturnValue({
+      firstRun: true,
+      loading: false,
+      error: null,
+      profile: {
+        appId: "clips",
+        appName: "Clips",
+        capabilities: [],
+      },
+      completeFirstRun: mocks.completeFirstRun,
+      completeFirstRunError: "first-run completion failed: 500",
+    });
+
+    await act(async () => {
+      root.render(
+        <TooltipProvider>
+          <FirstRunOnboarding />
+        </TooltipProvider>,
+      );
+    });
+    act(() => {
+      document.body
+        .querySelector("[data-testid='first-run-role-skip']")
+        ?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    });
+    await act(async () => {
+      document.body
+        .querySelector("[data-testid='first-run-setup-skip']")
+        ?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+      await Promise.resolve();
+    });
+
+    const extensionSkip = [...document.body.querySelectorAll("button")].find(
+      (button) => button.textContent === "Extension Skip",
+    );
+    if (extensionSkip) {
+      await act(async () => {
+        extensionSkip.click();
+        await Promise.resolve();
+      });
+    }
+
+    expect(mocks.completeFirstRun).toHaveBeenCalledTimes(1);
+    expect(document.body.textContent).toContain(
+      "first-run completion failed: 500",
+    );
+    await act(async () => {
+      [...document.body.querySelectorAll("button")]
+        .find((button) => button.textContent === "Try again")
+        ?.click();
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    expect(mocks.completeFirstRun).toHaveBeenCalledTimes(2);
+    expect(mocks.navigate).toHaveBeenCalledOnce();
+    expect(mocks.navigate).toHaveBeenCalledWith("/record", {
+      replace: true,
+    });
+  });
 });

package/src/app/onboarding/FirstRunOnboarding.tsx

@@ -7,6 +7,8 @@ import {
 } from "@agent-native/core/client/onboarding/first-run-registry";
 import { saveFirstRunOnboardingRole } from "@agent-native/core/client/onboarding/first-run-status";
 import {
+  createOnboardingCorrelationId,
+  setCustomKeyOnboardingAttempt,
   trackOnboardingEvent,
   useOnboarding,
 } from "@agent-native/core/client/onboarding/use-onboarding";
@@ -37,7 +39,7 @@ import React, {
   useRef,
   useState,
 } from "react";
-import { useLocation } from "react-router";
+import { useLocation, useNavigate } from "react-router";
 
 import { useBuilderConnectFlow } from "../settings/useBuilderStatus.js";
 import {
@@ -166,6 +168,7 @@ export function FirstRunOnboarding({
 }: FirstRunOnboardingProps = {}) {
   const t = useT();
   const { pathname } = useLocation();
+  const navigate = useNavigate();
   const previewMode = useOnboardingPreviewMode();
   const previewStep = useOnboardingPreviewStep();
   const {
@@ -301,18 +304,21 @@ export function FirstRunOnboarding({
   const completionAttemptRef = useRef<{
     screen: FirstRunScreen | null;
     extensionIndex: number;
+    redirect: string | null;
   } | null>(null);
   const completionInFlightRef = useRef(false);
+  const completionRedirectRef = useRef<string | null>(null);
   const setupSkipStartedRef = useRef(false);
   const onboardingTerminalRef = useRef(false);
   const abandonmentTrackedRef = useRef(false);
   const setupAttemptRef = useRef<FirstRunSetupAttempt | null>(null);
   const builderSetupAttemptRef = useRef<FirstRunSetupAttempt | null>(null);
+  const stepViewRef = useRef<{ key: string; id: string } | null>(null);
   const startSetupMethod = useCallback(
     (methodId: FirstRunSetupMethodId, methodKind: "builder" | "manual") => {
       if (previewMode || typeof window === "undefined") return null;
       const attempt = {
-        id: window.crypto.randomUUID(),
+        id: createOnboardingCorrelationId(),
         methodId,
         outcomeTracked: false,
       };
@@ -334,10 +340,14 @@ export function FirstRunOnboarding({
     async (
       completedScreen: FirstRunScreen | null,
       completedExtensionIndex = extensionIndex,
+      retryRedirect: string | null = completionRedirectRef.current,
     ) => {
-      completionAttemptRef.current = completedScreen
-        ? { screen: completedScreen, extensionIndex: completedExtensionIndex }
-        : { screen: null, extensionIndex: completedExtensionIndex };
+      completionRedirectRef.current = null;
+      completionAttemptRef.current = {
+        screen: completedScreen,
+        extensionIndex: completedExtensionIndex,
+        redirect: retryRedirect,
+      };
       completionInFlightRef.current = true;
       try {
         await completeFirstRun();
@@ -346,6 +356,9 @@ export function FirstRunOnboarding({
         }
         onboardingTerminalRef.current = true;
         completionAttemptRef.current = null;
+        if (retryRedirect) {
+          navigate(retryRedirect, { replace: true });
+        }
         return true;
       } catch {
         // coercion-ok: completeFirstRun exposes this failure as the inline retry state.
@@ -354,7 +367,13 @@ export function FirstRunOnboarding({
         completionInFlightRef.current = false;
       }
     },
-    [completeFirstRun, extensionIndex, trackFirstRunStepCompleted],
+    [
+      completeFirstRun,
+      extensionIndex,
+      navigate,
+      pathname,
+      trackFirstRunStepCompleted,
+    ],
   );
   useEffect(() => {
     if (!previewMode && firstRun && !loading && profile) {
@@ -362,7 +381,10 @@ export function FirstRunOnboarding({
     }
   }, [firstRun, loading, previewMode, profile]);
   useEffect(() => {
-    if (previewMode || !firstRun || loading || !profile) return;
+    if (previewMode || !firstRun || loading || !profile) {
+      stepViewRef.current = null;
+      return;
+    }
     const step = firstRunStepProperties(
       screen,
       beforeSetupExtensions,
@@ -371,7 +393,14 @@ export function FirstRunOnboarding({
       extensionIndex,
       extensionStepIndex,
     );
-    trackOnboardingEvent("onboarding_step_viewed", step);
+    const key = [step.step_id, step.extension_id, step.step_index].join(":");
+    if (stepViewRef.current?.key !== key) {
+      stepViewRef.current = { key, id: createOnboardingCorrelationId() };
+    }
+    trackOnboardingEvent("onboarding_step_viewed", {
+      ...step,
+      step_view_id: stepViewRef.current.id,
+    });
   }, [
     afterSetupExtensions,
     beforeSetupExtensions,
@@ -498,6 +527,7 @@ export function FirstRunOnboarding({
     void finishOnboarding(
       attempt?.screen ?? null,
       attempt?.extensionIndex ?? extensionIndex,
+      attempt?.redirect ?? null,
     );
   }, [extensionIndex, finishOnboarding]);
   const completionErrorProps = {
@@ -581,7 +611,23 @@ export function FirstRunOnboarding({
       );
       return;
     }
+    const attemptStorage = attempt
+      ? setCustomKeyOnboardingAttempt(attempt.id)
+      : null;
     trackFirstRunSetupOutcome(attempt, "settings_opened");
+    if (attempt && attemptStorage) {
+      void attemptStorage.then((status) => {
+        if (status !== "stored") {
+          trackOnboardingEvent("onboarding_correlation_unavailable", {
+            flow: "first_run",
+            step_id: "choice",
+            method_id: "custom_keys",
+            onboarding_attempt_id: attempt.id,
+            correlation_status: status,
+          });
+        }
+      });
+    }
     if (typeof window === "undefined") return;
     const search = new URLSearchParams(window.location.search);
     search.delete(ONBOARDING_PREVIEW_QUERY_PARAM);
@@ -756,7 +802,7 @@ export function FirstRunOnboarding({
                       onClick={() => handleBuilder(true)}
                       disabled={connectFlow.connecting}
                     >
-                      {t("agentChat.onboarding.builderCreateAndActivate")}
+                      {t("agentChat.onboarding.builderCreateAccount")}
                     </button>
                   )}
                   <button
@@ -839,6 +885,7 @@ export function FirstRunOnboarding({
                       return;
                     setupSkipStartedRef.current = true;
                     trackFirstRunStepSkipped("choice");
+                    completionRedirectRef.current = "/record";
                     handleFinish(null);
                   }}
                 >

package/src/app/onboarding/OnboardingPanel.save-scope.spec.tsx

@@ -9,6 +9,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 
 let steps: OnboardingStepStatus[] = [];
 vi.mock("@agent-native/core/client/onboarding/use-onboarding", () => ({
+  createOnboardingCorrelationId: () => "test-onboarding-correlation-id",
   trackOnboardingEvent: vi.fn(),
   useOnboarding: () => ({
     steps,

package/src/app/onboarding/OnboardingPanel.tsx

@@ -2,6 +2,7 @@ import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
 import { agentNativePath } from "@agent-native/core/client/api-path";
 import { useT } from "@agent-native/core/client/i18n";
 import {
+  createOnboardingCorrelationId,
   trackOnboardingEvent,
   useOnboarding,
 } from "@agent-native/core/client/onboarding/use-onboarding";
@@ -26,7 +27,7 @@ import {
   IconKey,
   IconLoader2,
 } from "@tabler/icons-react";
-import React, { useState, useEffect, useId } from "react";
+import React, { useState, useEffect, useId, useRef } from "react";
 
 import {
   BuilderConnectPopover,
@@ -74,21 +75,32 @@ export function OnboardingPanel({
   const checklistVisible =
     !loading && totalCount > 0 && (previewMode || (!dismissed && !allComplete));
   const [expanded, setExpanded] = useState(true);
+  const stepViewRef = useRef<{ key: string; id: string } | null>(null);
 
   useEffect(() => {
-    if (!checklistVisible) return;
+    if (!checklistVisible || !expanded) {
+      stepViewRef.current = null;
+      return;
+    }
     const activeStepIndex = steps.findIndex(
       (step) => step.id === currentStepId,
     );
     const activeStep = steps[activeStepIndex];
     trackOnboardingEvent("onboarding_started", { flow: "checklist" });
     if (!activeStep) return;
+    if (stepViewRef.current?.key !== activeStep.id) {
+      stepViewRef.current = {
+        key: activeStep.id,
+        id: createOnboardingCorrelationId(),
+      };
+    }
     trackOnboardingEvent("onboarding_step_viewed", {
       flow: "checklist",
       step_id: activeStep.id,
       step_index: activeStepIndex,
+      step_view_id: stepViewRef.current.id,
     });
-  }, [checklistVisible, currentStepId, previewMode, steps]);
+  }, [checklistVisible, currentStepId, expanded, previewMode, steps]);
 
   if (loading || totalCount === 0) return null;
   if (!previewMode) {