Skip to content

YC (S26) | Open Computer History | Continuously record your company computer work, map your workflows, help you find work worth automating, and power your agents' context

fix(onboarding): replay final guide after reset

Louis Beaumont7ae69651ca73
diff --git a/apps/screenpipe-app-tauri/components/settings/general-settings.tsx b/apps/screenpipe-app-tauri/components/settings/general-settings.tsx
index 7803e41f9..1e7b81eb7 100644
--- a/apps/screenpipe-app-tauri/components/settings/general-settings.tsx
+++ b/apps/screenpipe-app-tauri/components/settings/general-settings.tsx
@@ -16,6 +16,7 @@ import { Button } from "@/components/ui/button";
import { Settings } from "@/lib/hooks/use-settings";
import { getVersion } from "@tauri-apps/api/app";
import { commands } from "@/lib/utils/tauri";
+import { useOnboarding } from "@/lib/hooks/use-onboarding";
import { UpdateBanner } from "@/components/update-banner";
import type { SettingsField } from "./settings-search";
@@ -40,9 +41,34 @@ import {
export default function GeneralSettings() {
const { isManagedDeployment } = useManagedPolicy();
const { settings, updateSettings } = useSettings();
+ const resetOnboarding = useOnboarding((state) => state.resetOnboarding);
const { toast } = useToast();
const [currentVersion, setCurrentVersion] = useState<string | null>(null);
const [isCheckingForUpdate, setIsCheckingForUpdate] = useState(false);
+ const [isResettingOnboarding, setIsResettingOnboarding] = useState(false);
+
+ const handleResetOnboarding = async () => {
+ setIsResettingOnboarding(true);
+ try {
+ // The final guided tour is persisted separately from native onboarding.
+ // Re-arm it before opening setup so a completed personalized-dashboard
+ // path can still replay the full experience after an explicit reset.
+ await updateSettings({ firstRunGuideDone: false });
+ await resetOnboarding();
+ const result = await commands.showOnboardingWindow();
+ if (result.status === "error") throw new Error(result.error);
+ } catch (error) {
+ console.error("failed to reset onboarding:", error);
+ toast({
+ title: "couldn't reset onboarding",
+ description:
+ error instanceof Error ? error.message : "please try again",
+ variant: "destructive",
+ });
+ } finally {
+ setIsResettingOnboarding(false);
+ }
+ };
const handleCheckForUpdates = async () => {
setIsCheckingForUpdate(true);
@@ -343,16 +369,10 @@ export default function GeneralSettings() {
variant="outline"
size="sm"
className="ml-4 h-7 text-xs"
- onClick={async () => {
- try {
- await commands.resetOnboarding();
- await commands.showOnboardingWindow();
- } catch (e) {
- console.error("failed to open onboarding:", e);
- }
- }}
+ disabled={isResettingOnboarding}
+ onClick={() => void handleResetOnboarding()}
>
- reset
+ {isResettingOnboarding ? "resetting..." : "reset"}
</Button>
</div>
</CardContent>
diff --git a/apps/screenpipe-app-tauri/lib/first-run-guide.test.ts b/apps/screenpipe-app-tauri/lib/first-run-guide.test.ts
index 11f32e7a9..b786a30e4 100644
--- a/apps/screenpipe-app-tauri/lib/first-run-guide.test.ts
+++ b/apps/screenpipe-app-tauri/lib/first-run-guide.test.ts
@@ -6,7 +6,9 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
import {
consumeFirstRunGuidePending,
isFirstRunGuidePending,
+ isFirstRunGuideReplayAfterOnboarding,
setFirstRunGuidePending,
+ setFirstRunGuideReplayAfterOnboarding,
shouldShowFirstRunGuide,
} from "./first-run-guide";
@@ -90,4 +92,14 @@ describe("first-run guide eligibility", () => {
expect(isFirstRunGuidePending()).toBe(false);
expect(consumeFirstRunGuidePending()).toBe(false);
});
+
+ it("persists a reset replay request separately from the Home handoff", () => {
+ setFirstRunGuideReplayAfterOnboarding(true);
+
+ expect(isFirstRunGuideReplayAfterOnboarding()).toBe(true);
+ expect(isFirstRunGuidePending()).toBe(false);
+
+ setFirstRunGuideReplayAfterOnboarding(false);
+ expect(isFirstRunGuideReplayAfterOnboarding()).toBe(false);
+ });
});
diff --git a/apps/screenpipe-app-tauri/lib/first-run-guide.ts b/apps/screenpipe-app-tauri/lib/first-run-guide.ts
index 66bcd40cf..ab4bd1627 100644
--- a/apps/screenpipe-app-tauri/lib/first-run-guide.ts
+++ b/apps/screenpipe-app-tauri/lib/first-run-guide.ts
@@ -4,6 +4,8 @@
export const FIRST_RUN_GUIDE_PENDING_KEY =
"screenpipe:first-run-guide-pending";
+export const FIRST_RUN_GUIDE_REPLAY_AFTER_ONBOARDING_KEY =
+ "screenpipe:first-run-guide-replay-after-onboarding";
export function isFirstRunGuidePending(): boolean {
try {
@@ -25,6 +27,39 @@ export function setFirstRunGuidePending(pending: boolean): void {
}
}
+/**
+ * Remember that an explicit onboarding reset should replay the final guide.
+ * This is separate from the one-time Home handoff: setting the handoff during
+ * onboarding would show the guide too early, on top of the setup window.
+ */
+export function isFirstRunGuideReplayAfterOnboarding(): boolean {
+ try {
+ return (
+ localStorage.getItem(FIRST_RUN_GUIDE_REPLAY_AFTER_ONBOARDING_KEY) ===
+ "true"
+ );
+ } catch {
+ return false;
+ }
+}
+
+export function setFirstRunGuideReplayAfterOnboarding(
+ shouldReplay: boolean,
+): void {
+ try {
+ if (shouldReplay) {
+ localStorage.setItem(
+ FIRST_RUN_GUIDE_REPLAY_AFTER_ONBOARDING_KEY,
+ "true",
+ );
+ } else {
+ localStorage.removeItem(FIRST_RUN_GUIDE_REPLAY_AFTER_ONBOARDING_KEY);
+ }
+ } catch {
+ // localStorage may be unavailable in restricted webviews.
+ }
+}
+
/**
* Read and immediately consume the one-time guide handoff. The current Home
* window keeps the returned value in React state, while any later reload or
diff --git a/apps/screenpipe-app-tauri/lib/hooks/__tests__/use-onboarding.test.ts b/apps/screenpipe-app-tauri/lib/hooks/__tests__/use-onboarding.test.ts
index f4b94049f..26e02a7cf 100644
--- a/apps/screenpipe-app-tauri/lib/hooks/__tests__/use-onboarding.test.ts
+++ b/apps/screenpipe-app-tauri/lib/hooks/__tests__/use-onboarding.test.ts
@@ -25,6 +25,7 @@ const localStorageMock = (() => {
const mocks = vi.hoisted(() => ({
completeOnboarding: vi.fn(),
+ resetOnboarding: vi.fn(),
capture: vi.fn(),
emit: vi.fn().mockResolvedValue(undefined),
}));
@@ -32,6 +33,7 @@ const mocks = vi.hoisted(() => ({
vi.mock("@/lib/utils/tauri", () => ({
commands: {
completeOnboarding: mocks.completeOnboarding,
+ resetOnboarding: mocks.resetOnboarding,
},
}));
@@ -145,4 +147,39 @@ describe("useOnboarding measurement", () => {
goal_category: "work_memory",
});
});
+
+ it("replays the final guide after an explicit onboarding reset", async () => {
+ mocks.resetOnboarding.mockResolvedValue({ status: "ok", data: null });
+ mocks.completeOnboarding.mockResolvedValue({ status: "ok", data: null });
+ localStorage.setItem("screenpipe:first-run-guide-pending", "true");
+
+ await useOnboarding.getState().resetOnboarding();
+
+ expect(
+ localStorage.getItem("screenpipe:first-run-guide-pending"),
+ ).toBeNull();
+ expect(
+ localStorage.getItem(
+ "screenpipe:first-run-guide-replay-after-onboarding",
+ ),
+ ).toBe("true");
+
+ await useOnboarding.getState().completeOnboarding({
+ method: "live_view_created",
+ dashboardBlockCount: 4,
+ });
+
+ expect(
+ localStorage.getItem(
+ "screenpipe:first-run-guide-replay-after-onboarding",
+ ),
+ ).toBeNull();
+ expect(
+ localStorage.getItem("screenpipe:first-run-guide-pending"),
+ ).toBe("true");
+ expect(mocks.emit).toHaveBeenCalledWith("first-run-guide-pending");
+ expect(mocks.emit).not.toHaveBeenCalledWith("navigate", {
+ url: "screenpipe://home?section=brain",
+ });
+ });
});
diff --git a/apps/screenpipe-app-tauri/lib/hooks/use-onboarding.tsx b/apps/screenpipe-app-tauri/lib/hooks/use-onboarding.tsx
index f89af1366..dfc8ff3fe 100644
--- a/apps/screenpipe-app-tauri/lib/hooks/use-onboarding.tsx
+++ b/apps/screenpipe-app-tauri/lib/hooks/use-onboarding.tsx
@@ -13,7 +13,9 @@ import {
} from "@/lib/sidebar-pipes";
import {
isFirstRunGuidePending,
+ isFirstRunGuideReplayAfterOnboarding,
setFirstRunGuidePending,
+ setFirstRunGuideReplayAfterOnboarding,
} from "@/lib/first-run-guide";
export type OnboardingCompletionContext = {
@@ -71,7 +73,9 @@ export const useOnboarding = create<OnboardingState>((set, get) => ({
completeOnboarding: async (context) => {
let previousPipesCollapsed: string | null = null;
const firstRunGuideWasPending = isFirstRunGuidePending();
- const prepareFirstRunGuide = context.method !== "live_view_created";
+ const replayFirstRunGuide = isFirstRunGuideReplayAfterOnboarding();
+ const prepareFirstRunGuide =
+ context.method !== "live_view_created" || replayFirstRunGuide;
try {
set({ isLoading: true, error: null });
if (prepareFirstRunGuide) {
@@ -96,6 +100,9 @@ export const useOnboarding = create<OnboardingState>((set, get) => ({
const result = await commands.completeOnboarding();
if (result.status === "ok") {
+ if (replayFirstRunGuide) {
+ setFirstRunGuideReplayAfterOnboarding(false);
+ }
// Update local state
set(state => ({
onboardingData: {
@@ -169,6 +176,11 @@ export const useOnboarding = create<OnboardingState>((set, get) => ({
const result = await commands.resetOnboarding();
if (result.status === "ok") {
+ // Resetting setup is an explicit request to see the entire first-run
+ // experience again. Keep this intent separate from the Home handoff so
+ // the guide cannot appear over the onboarding window.
+ setFirstRunGuidePending(false);
+ setFirstRunGuideReplayAfterOnboarding(true);
// Update local state
set(state => ({
onboardingData: {