feat: implement first-run onboarding walkthrough and Help & FAQ screen; update app state and tests

Author: Lalit Sharma

CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.31] — 2026-02-26
+
+### Added
+- Added first-run onboarding walkthrough for new users with step-by-step guidance across `Landing`, `Timer`, and `Settings`.
+- Added persisted onboarding completion state in app preferences with an explicit `Skip` option.
+- Added an in-app `Help & FAQ` screen under `Settings` with concise FAQ/troubleshooting content and deep links to full documentation.
+- Added regression tests for onboarding walkthrough configuration and Help content/doc-link validation.
+
+### Changed
+- Updated `RootNavigator` to wire onboarding overlay behavior and Help route deep-link path (`eclipsetimer://settings/help`).
+- Updated `documents/planning/tech-debt.md` to mark `ADD-11` and `ADD-13` as completed and remove them from pending execution order.
+- Bumped `apps/mobile` version to `1.1.31`.
+
+### Tests
+- Verified mobile checks pass: `pnpm -C apps/mobile typecheck`, `pnpm -C apps/mobile lint`, and `pnpm -C apps/mobile test`.
+
 ## [1.1.30] — 2026-02-26
 
 ### Changed

apps/mobile/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eclipse-timer/mobile",
-  "version": "1.1.30",
+  "version": "1.1.31",
   "private": true,
   "main": "index.js",
   "scripts": {

apps/mobile/src/navigation/FirstRunOnboardingOverlay.tsx

@@ -0,0 +1,158 @@
+import { useMemo } from "react";
+import { Pressable, StyleSheet, Text, View } from "react-native";
+
+import { useAppTheme } from "../theme/useAppTheme";
+import {
+  type OnboardingRouteName,
+  type OnboardingWalkthroughStep,
+  onboardingRouteLabel,
+} from "./onboardingWalkthrough";
+
+type FirstRunOnboardingOverlayProps = {
+  visible: boolean;
+  step: OnboardingWalkthroughStep | null;
+  stepIndex: number;
+  stepCount: number;
+  isStepRouteActive: boolean;
+  onGoToStepRoute: (route: OnboardingRouteName) => void;
+  onNext: () => void;
+  onSkip: () => void;
+};
+
+export default function FirstRunOnboardingOverlay({
+  visible,
+  step,
+  stepIndex,
+  stepCount,
+  isStepRouteActive,
+  onGoToStepRoute,
+  onNext,
+  onSkip,
+}: FirstRunOnboardingOverlayProps) {
+  const { colors } = useAppTheme();
+  const styles = useMemo(() => createStyles(colors), [colors]);
+
+  if (!visible || !step) return null;
+
+  const isLastStep = stepIndex >= stepCount - 1;
+  const primaryLabel = isStepRouteActive
+    ? isLastStep
+      ? "Finish"
+      : "Next Tip"
+    : `Go to ${onboardingRouteLabel(step.route)}`;
+
+  return (
+    <View style={styles.overlay}>
+      <View style={styles.backdrop} />
+      <View style={styles.card}>
+        <View style={styles.headerRow}>
+          <Text style={styles.progressLabel}>
+            Step {stepIndex + 1} of {stepCount}
+          </Text>
+          <Pressable style={styles.skipButton} onPress={onSkip} accessibilityRole="button">
+            <Text style={styles.skipLabel}>Skip</Text>
+          </Pressable>
+        </View>
+
+        <Text style={styles.title}>{step.title}</Text>
+        <Text style={styles.description}>{step.description}</Text>
+        <Text style={styles.highlight}>Highlight: {step.highlightLabel}</Text>
+
+        <Pressable
+          style={styles.primaryButton}
+          onPress={() => {
+            if (isStepRouteActive) {
+              onNext();
+              return;
+            }
+            onGoToStepRoute(step.route);
+          }}
+          accessibilityRole="button"
+          accessibilityLabel={primaryLabel}
+        >
+          <Text style={styles.primaryLabel}>{primaryLabel}</Text>
+        </Pressable>
+      </View>
+    </View>
+  );
+}
+
+function createStyles(colors: ReturnType<typeof useAppTheme>["colors"]) {
+  return StyleSheet.create({
+    overlay: {
+      ...StyleSheet.absoluteFillObject,
+      zIndex: 40,
+      justifyContent: "flex-end",
+      paddingHorizontal: 12,
+      paddingBottom: 14,
+    },
+    backdrop: {
+      ...StyleSheet.absoluteFillObject,
+      backgroundColor: colors.overlay,
+    },
+    card: {
+      borderRadius: 14,
+      borderWidth: 1,
+      borderColor: colors.borderStrong,
+      backgroundColor: colors.surface,
+      paddingVertical: 14,
+      paddingHorizontal: 12,
+      gap: 8,
+    },
+    headerRow: {
+      flexDirection: "row",
+      alignItems: "center",
+      justifyContent: "space-between",
+      gap: 8,
+    },
+    progressLabel: {
+      color: colors.textSecondary,
+      fontSize: 12,
+      fontWeight: "700",
+      textTransform: "uppercase",
+      letterSpacing: 0.5,
+    },
+    skipButton: {
+      borderRadius: 999,
+      borderWidth: 1,
+      borderColor: colors.inputBorder,
+      backgroundColor: colors.surfaceMuted,
+      paddingVertical: 7,
+      paddingHorizontal: 10,
+    },
+    skipLabel: {
+      color: colors.textSecondary,
+      fontSize: 12,
+      fontWeight: "700",
+    },
+    title: {
+      color: colors.textPrimary,
+      fontSize: 17,
+      fontWeight: "800",
+    },
+    description: {
+      color: colors.textMuted,
+      fontSize: 13,
+      lineHeight: 19,
+    },
+    highlight: {
+      color: colors.textSecondary,
+      fontSize: 12,
+      fontWeight: "700",
+    },
+    primaryButton: {
+      marginTop: 4,
+      borderRadius: 10,
+      backgroundColor: colors.primary,
+      alignItems: "center",
+      justifyContent: "center",
+      paddingVertical: 11,
+    },
+    primaryLabel: {
+      color: colors.primaryText,
+      fontSize: 14,
+      fontWeight: "800",
+      textTransform: "uppercase",
+    },
+  });
+}

apps/mobile/src/navigation/RootNavigator.tsx

@@ -44,6 +44,7 @@ import { useLandingScroll } from "../hooks/useLandingScroll";
 import { useNotificationScheduler } from "../hooks/useNotificationScheduler";
 import { useTimerState } from "../hooks/useTimerState";
 import EclipsePreviewScreen, { type PreviewPayload } from "../screens/EclipsePreviewScreen";
+import HelpScreen from "../screens/HelpScreen";
 import LandingScreen from "../screens/LandingScreen";
 import LocationSettingsScreen from "../screens/LocationSettingsScreen";
 import NotificationSettingsScreen from "../screens/NotificationSettingsScreen";
@@ -56,6 +57,8 @@ import { type FavoriteLocation, useAppState } from "../state/appState";
 import { useAppTheme } from "../theme/useAppTheme";
 import { localYmdNow } from "../utils/date";
 import { kindCodeForRecord, kindLabelFromCode } from "../utils/eclipse";
+import FirstRunOnboardingOverlay from "./FirstRunOnboardingOverlay";
+import { ONBOARDING_WALKTHROUGH_STEPS, type OnboardingRouteName } from "./onboardingWalkthrough";
 import SideMenu, { type MenuRouteName } from "./SideMenu";
 
 enableScreens();
@@ -65,6 +68,7 @@ type RootStackParamList = {
   Timer: undefined;
   Preview: { payload: PreviewPayload };
   Settings: undefined;
+  Help: undefined;
   ThemeSettings: undefined;
   NotificationSettings: undefined;
   LocationSettings: undefined;
@@ -77,6 +81,7 @@ const linking: LinkingOptions<RootStackParamList> = {
       Landing: "landing",
       Timer: "timer",
       Settings: "settings",
+      Help: "settings/help",
       ThemeSettings: "settings/theme",
       NotificationSettings: "notifications",
       LocationSettings: "locations",
@@ -168,6 +173,7 @@ function toMenuRouteName(route: keyof RootStackParamList): MenuRouteName | null
   if (route === "Landing" || route === "Timer") return route;
   if (
     route === "Settings" ||
+    route === "Help" ||
     route === "ThemeSettings" ||
     route === "NotificationSettings" ||
     route === "LocationSettings"
@@ -468,13 +474,18 @@ function SettingsRoute({ navigation, onOpenMenu }: SettingsRouteProps) {
   return (
     <SettingsScreen
       onOpenMenu={onOpenMenu}
+      onOpenHelp={() => navigation.navigate("Help")}
       onOpenThemeSettings={() => navigation.navigate("ThemeSettings")}
       onOpenNotificationSettings={() => navigation.navigate("NotificationSettings")}
       onOpenLocationSettings={() => navigation.navigate("LocationSettings")}
     />
   );
 }
 
+function HelpRoute({ onOpenMenu }: RouteWithMenuProps) {
+  return <HelpScreen onOpenMenu={onOpenMenu} />;
+}
+
 function ThemeSettingsRoute({ onOpenMenu }: ThemeSettingsRouteProps) {
   const { state, actions } = useAppState();
 
@@ -517,12 +528,13 @@ function LocationSettingsRoute({ onOpenMenu }: RouteWithMenuProps) {
 }
 
 export default function RootNavigator() {
-  const { state: appState, actions } = useAppState();
+  const { state: appState, hasHydratedPreferences, actions } = useAppState();
   const { colors, resolvedTheme } = useAppTheme();
   const navigationRef = useNavigationContainerRef<RootStackParamList>();
   const pendingFeaturedDeepLinkActionRef = useRef<FeaturedEclipseDeepLinkAction | null>(null);
   const [catalog, setCatalog] = useState<EclipseRecord[] | null>(null);
   const [isMenuOpen, setIsMenuOpen] = useState(false);
+  const [onboardingStepIndex, setOnboardingStepIndex] = useState(0);
   const [currentRouteName, setCurrentRouteName] = useState<keyof RootStackParamList>("Landing");
   const navigationTheme = useMemo<NavigationTheme>(() => {
     const base = resolvedTheme === "light" ? NavigationLightTheme : NavigationDarkTheme;
@@ -665,6 +677,48 @@ export default function RootNavigator() {
   );
 
   const activeMenuRoute = useMemo(() => toMenuRouteName(currentRouteName), [currentRouteName]);
+  const onboardingStepCount = ONBOARDING_WALKTHROUGH_STEPS.length;
+  const onboardingStep = ONBOARDING_WALKTHROUGH_STEPS[onboardingStepIndex] ?? null;
+  const isFirstRunOnboardingVisible =
+    hasHydratedPreferences && !appState.hasCompletedOnboarding && onboardingStepCount > 0;
+  const isOnboardingStepRouteActive = onboardingStep
+    ? currentRouteName === onboardingStep.route
+    : false;
+
+  const completeOnboarding = useCallback(() => {
+    closeMenu();
+    setOnboardingStepIndex(0);
+    actions.setOnboardingCompleted(true);
+  }, [actions, closeMenu]);
+
+  const goToOnboardingStepRoute = useCallback(
+    (route: OnboardingRouteName) => {
+      closeMenu();
+      if (!navigationRef.isReady()) return;
+      const currentRoute = navigationRef.getCurrentRoute()?.name;
+      if (currentRoute === route) return;
+      navigationRef.navigate(route);
+    },
+    [closeMenu, navigationRef],
+  );
+
+  const goToNextOnboardingStep = useCallback(() => {
+    if (!onboardingStepCount) {
+      completeOnboarding();
+      return;
+    }
+    if (onboardingStepIndex >= onboardingStepCount - 1) {
+      completeOnboarding();
+      return;
+    }
+
+    const nextStepIndex = onboardingStepIndex + 1;
+    setOnboardingStepIndex(nextStepIndex);
+
+    const nextStep = ONBOARDING_WALKTHROUGH_STEPS[nextStepIndex];
+    if (!nextStep) return;
+    goToOnboardingStepRoute(nextStep.route);
+  }, [completeOnboarding, goToOnboardingStepRoute, onboardingStepCount, onboardingStepIndex]);
 
   useEffect(() => {
     if (!isMenuOpen) return;
@@ -675,6 +729,21 @@ export default function RootNavigator() {
     return () => subscription.remove();
   }, [closeMenu, isMenuOpen]);
 
+  useEffect(() => {
+    if (!isFirstRunOnboardingVisible) {
+      setOnboardingStepIndex(0);
+      return;
+    }
+    if (onboardingStepIndex >= onboardingStepCount) {
+      setOnboardingStepIndex(Math.max(0, onboardingStepCount - 1));
+    }
+  }, [isFirstRunOnboardingVisible, onboardingStepCount, onboardingStepIndex]);
+
+  useEffect(() => {
+    if (!isFirstRunOnboardingVisible || !isMenuOpen) return;
+    closeMenu();
+  }, [closeMenu, isFirstRunOnboardingVisible, isMenuOpen]);
+
   useEffect(() => {
     let didCancel = false;
 
@@ -737,6 +806,7 @@ export default function RootNavigator() {
           <Stack.Screen name="Settings">
             {(props) => <SettingsRoute {...props} onOpenMenu={openMenu} />}
           </Stack.Screen>
+          <Stack.Screen name="Help">{() => <HelpRoute onOpenMenu={openMenu} />}</Stack.Screen>
           <Stack.Screen name="ThemeSettings">
             {(props) => <ThemeSettingsRoute {...props} onOpenMenu={openMenu} />}
           </Stack.Screen>
@@ -753,6 +823,16 @@ export default function RootNavigator() {
           onClose={closeMenu}
           onNavigate={onNavigateFromMenu}
         />
+        <FirstRunOnboardingOverlay
+          visible={isFirstRunOnboardingVisible}
+          step={onboardingStep}
+          stepIndex={onboardingStepIndex}
+          stepCount={onboardingStepCount}
+          isStepRouteActive={isOnboardingStepRouteActive}
+          onGoToStepRoute={goToOnboardingStepRoute}
+          onNext={goToNextOnboardingStep}
+          onSkip={completeOnboarding}
+        />
       </View>
     </NavigationContainer>
   );