Skip to content

Voice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.

fix(mobile): Show the keyboard step when replaying onboarding (#2414)

Chad Piha25e0ce09354f
diff --git a/openwhispr-mobile/src/screens/onboarding/steps/KeyboardIntroStep.tsx b/openwhispr-mobile/src/screens/onboarding/steps/KeyboardIntroStep.tsx
index 4b4d4f4f0..7ea974552 100644
--- a/openwhispr-mobile/src/screens/onboarding/steps/KeyboardIntroStep.tsx
+++ b/openwhispr-mobile/src/screens/onboarding/steps/KeyboardIntroStep.tsx
@@ -21,6 +21,8 @@ const STEPS = [
export function KeyboardIntroStep() {
const { goNext, progress } = useOnboardingStep('keyboard-intro');
const setKeyboardInstalled = useOnboardingStore((s) => s.setKeyboardInstalled);
+ const replaying = useOnboardingStore((s) => s.replaying);
+ const [installedOnArrival] = useState(() => isKeyboardInstalled());
const [openedSettings, setOpenedSettings] = useState(false);
const [hasReturned, setHasReturned] = useState(false);
const [settingsLaunchPending, setSettingsLaunchPending] = useState(false);
@@ -49,14 +51,15 @@ export function KeyboardIntroStep() {
// Mirror MicrophoneStep's auto-skip pattern: if the OpenWhispr keyboard is
// already enabled in iOS, advance immediately without showing this screen.
+ // A replay shows it anyway, so Reset onboarding can walk through setup again.
useEffect(() => {
if (skipCheckRef.current) return;
skipCheckRef.current = true;
- if (isKeyboardInstalled()) {
+ if (installedOnArrival && !replaying) {
stopPipTutorial();
void advance();
}
- }, [advance, stopPipTutorial]);
+ }, [advance, installedOnArrival, replaying, stopPipTutorial]);
useEffect(() => {
let pollHandle: ReturnType<typeof setInterval> | null = null;
@@ -123,22 +126,42 @@ export function KeyboardIntroStep() {
}
}, []);
+ const content =
+ replaying && installedOnArrival && !openedSettings
+ ? {
+ title: 'The keyboard is already on.',
+ titleAccent: 'already on',
+ subtitle: 'OpenWhispr is enabled in Settings. Continue, or walk through setup again.',
+ ctaLabel: 'Continue',
+ onCta: advance,
+ secondaryCtaLabel: 'Open Settings',
+ onSecondaryCta: openSettings,
+ }
+ : hasReturned
+ ? {
+ title: 'Did you enable the keyboard?',
+ titleAccent: 'enable',
+ subtitle:
+ 'We didn’t detect the keyboard yet. Make sure both toggles are on, then try again.',
+ ctaLabel: 'Try again',
+ onCta: openSettings,
+ secondaryCtaLabel: "I've enabled it",
+ onSecondaryCta: advance,
+ }
+ : {
+ title: 'Use OpenWhispr in any app.',
+ titleAccent: 'any app',
+ subtitle: 'Follow these steps in Settings. We’ll be here when you come back.',
+ ctaLabel: 'Open Settings',
+ onCta: openSettings,
+ };
+
return (
<OnboardingShell
+ {...content}
progress={progress}
- title={hasReturned ? 'Did you enable the keyboard?' : 'Use OpenWhispr in any app.'}
- titleAccent={hasReturned ? 'enable' : 'any app'}
- subtitle={
- hasReturned
- ? 'We didn’t detect the keyboard yet. Make sure both toggles are on, then try again.'
- : 'Follow these steps in Settings. We’ll be here when you come back.'
- }
- ctaLabel={hasReturned ? 'Try again' : 'Open Settings'}
ctaDisabled={settingsLaunchPending}
ctaLoading={settingsLaunchPending}
- onCta={openSettings}
- secondaryCtaLabel={hasReturned ? "I've enabled it" : undefined}
- onSecondaryCta={hasReturned ? advance : undefined}
>
<View className="flex-1 justify-center gap-4">
{openedSettings ? (
diff --git a/openwhispr-mobile/src/screens/onboarding/steps/__tests__/OnboardingTransitions.test.tsx b/openwhispr-mobile/src/screens/onboarding/steps/__tests__/OnboardingTransitions.test.tsx
index fb175ef13..36bb71f55 100644
--- a/openwhispr-mobile/src/screens/onboarding/steps/__tests__/OnboardingTransitions.test.tsx
+++ b/openwhispr-mobile/src/screens/onboarding/steps/__tests__/OnboardingTransitions.test.tsx
@@ -79,6 +79,7 @@ const mockFinish = jest.fn();
const mockPermission = jest.fn();
const mockKeyboardInstalled = jest.fn();
const mockIsInstalled = jest.fn();
+let mockReplaying = false;
const mockStatus = jest.fn();
const mockRequest = jest.fn();
jest.mock('@/store/useOnboardingStore', () => ({
@@ -88,6 +89,7 @@ jest.mock('@/store/useOnboardingStore', () => ({
finish: mockFinish,
setPermissionGranted: mockPermission,
setKeyboardInstalled: mockKeyboardInstalled,
+ replaying: mockReplaying,
}),
getStepProgress: () => ({ current: 1, total: 8 }),
}));
@@ -106,6 +108,7 @@ beforeEach(() => {
mockRequestMicPermission.mockResolvedValue({ granted: true, canAskAgain: true });
mockKeyboardInstalled.mockResolvedValue(undefined);
mockIsInstalled.mockReturnValue(false);
+ mockReplaying = false;
mockStatus.mockResolvedValue('undetermined');
mockRequest.mockResolvedValue('denied');
jest.spyOn(Linking, 'canOpenURL').mockResolvedValue(false);
@@ -168,6 +171,37 @@ it('explains a failed keyboard continuation without native error text', async ()
alert.mockRestore();
});
+it('skips the keyboard step when the keyboard is already on', async () => {
+ mockIsInstalled.mockReturnValue(true);
+ render(<KeyboardIntroStep />);
+ await waitFor(() => expect(mockNext).toHaveBeenCalledWith('keyboard-intro'));
+});
+
+it('shows the keyboard step on a replay even when the keyboard is already on', async () => {
+ mockReplaying = true;
+ mockIsInstalled.mockReturnValue(true);
+ const screen = render(<KeyboardIntroStep />);
+
+ expect(screen.getByText('The keyboard is already on.')).toBeTruthy();
+ expect(mockNext).not.toHaveBeenCalled();
+
+ fireEvent.press(screen.getByText('Continue'));
+ await waitFor(() => expect(mockNext).toHaveBeenCalledWith('keyboard-intro'));
+ expect(mockKeyboardInstalled).toHaveBeenCalledWith(true);
+});
+
+it('lets a replay walk through keyboard setup in Settings again', async () => {
+ mockReplaying = true;
+ mockIsInstalled.mockReturnValue(true);
+ const openSettings = jest.spyOn(Linking, 'openSettings').mockResolvedValue(undefined);
+ const screen = render(<KeyboardIntroStep />);
+
+ fireEvent.press(screen.getByText('Open Settings'));
+ await waitFor(() => expect(openSettings).toHaveBeenCalledTimes(1));
+ expect(screen.getByText('Use OpenWhispr in any app.')).toBeTruthy();
+ expect(mockNext).not.toHaveBeenCalled();
+});
+
it('finishes setup before launching an external app', async () => {
let resolveFinish: () => void = () => undefined;
mockFinish.mockReturnValue(
diff --git a/openwhispr-mobile/src/store/__tests__/useOnboardingStore.test.ts b/openwhispr-mobile/src/store/__tests__/useOnboardingStore.test.ts
index 190059a3f..a12406d4d 100644
--- a/openwhispr-mobile/src/store/__tests__/useOnboardingStore.test.ts
+++ b/openwhispr-mobile/src/store/__tests__/useOnboardingStore.test.ts
@@ -330,3 +330,27 @@ it('preserves the tracking request marker when resetting setup', async () => {
trackingAuthorizationRequestAttempted: true,
});
});
+
+it('marks a reset setup as a replay, across a relaunch', async () => {
+ useOnboardingStore.setState({ finished: true });
+ await useOnboardingStore.getState().reset();
+ expect(useOnboardingStore.getState().replaying).toBe(true);
+
+ service.getProgress.mockResolvedValue(service.setProgress.mock.calls.at(-1)![0]);
+ useOnboardingStore.setState(useOnboardingStore.getInitialState());
+ await useOnboardingStore.getState().hydrate();
+ expect(useOnboardingStore.getState()).toMatchObject({
+ currentStep: 'get-started',
+ replaying: true,
+ });
+});
+
+it('does not treat a first setup as a replay', async () => {
+ service.getProgress.mockResolvedValue({
+ step: 'keyboard-intro',
+ keyboardInstalled: false,
+ permissionsGranted: { microphone: false, notifications: false },
+ });
+ await useOnboardingStore.getState().hydrate();
+ expect(useOnboardingStore.getState().replaying).toBe(false);
+});
diff --git a/openwhispr-mobile/src/store/useOnboardingStore.ts b/openwhispr-mobile/src/store/useOnboardingStore.ts
index eca385edc..2a5d93f0a 100644
--- a/openwhispr-mobile/src/store/useOnboardingStore.ts
+++ b/openwhispr-mobile/src/store/useOnboardingStore.ts
@@ -129,6 +129,8 @@ interface OnboardingStore {
paywallHandled: boolean;
paywallNextStep: PaywallNextStep;
tutorialCompleted: boolean;
+ // Set by Reset onboarding: steps that skip themselves when setup is already done show instead.
+ replaying: boolean;
keyboardInstalled: boolean;
trackingAuthorizationRequestAttempted: boolean;
permissionsGranted: { microphone: boolean; notifications: boolean };
@@ -155,6 +157,7 @@ function snapshot(state: OnboardingStore): OnboardingProgress {
paywallHandled: state.paywallHandled,
paywallNextStep: state.paywallNextStep,
tutorialCompleted: state.tutorialCompleted,
+ replaying: state.replaying,
keyboardInstalled: state.keyboardInstalled,
permissionsGranted: state.permissionsGranted,
};
@@ -186,6 +189,7 @@ export const useOnboardingStore = create<OnboardingStore>((set, get) => {
paywallHandled: false,
paywallNextStep: 'language',
tutorialCompleted: false,
+ replaying: false,
keyboardInstalled: false,
trackingAuthorizationRequestAttempted: false,
permissionsGranted: { microphone: false, notifications: false },
@@ -216,6 +220,7 @@ export const useOnboardingStore = create<OnboardingStore>((set, get) => {
? progress.paywallNextStep
: 'language',
tutorialCompleted: progress.tutorialCompleted === true,
+ replaying: progress.replaying === true,
keyboardInstalled: progress.keyboardInstalled,
trackingAuthorizationRequestAttempted,
permissionsGranted: progress.permissionsGranted,
@@ -308,10 +313,13 @@ export const useOnboardingStore = create<OnboardingStore>((set, get) => {
paywallHandled: false,
paywallNextStep: 'language',
tutorialCompleted: false,
+ replaying: true,
keyboardInstalled: false,
trackingAuthorizationRequestAttempted: attempted,
permissionsGranted: { microphone: false, notifications: false },
});
+ // The replay has to outlive the relaunch Reset asks for.
+ await OnboardingService.setProgress(snapshot(get()));
},
};
});
diff --git a/openwhispr-mobile/src/utils/onboarding.ts b/openwhispr-mobile/src/utils/onboarding.ts
index f8b70a2cb..68ca778d8 100644
--- a/openwhispr-mobile/src/utils/onboarding.ts
+++ b/openwhispr-mobile/src/utils/onboarding.ts
@@ -20,6 +20,7 @@ export interface OnboardingProgress {
paywallHandled?: boolean;
paywallNextStep?: PaywallNextStep;
tutorialCompleted?: boolean;
+ replaying?: boolean;
keyboardInstalled: boolean;
permissionsGranted: {
microphone: boolean;