feat: add replayable onboarding tour

package.json

@@ -9,7 +9,6 @@
     "lint": "next lint"
   },
   "dependencies": {
-    "@sorosave/sdk": "workspace:*",
     "@stellar/freighter-api": "^2.0.0",
     "next": "^14.2.0",
     "react": "^18.3.0",

src/app/groups/[id]/page.tsx

@@ -5,10 +5,10 @@ import { MemberList } from "@/components/MemberList";
 import { RoundProgress } from "@/components/RoundProgress";
 import { ContributeModal } from "@/components/ContributeModal";
 import { useState } from "react";
+import { useParams } from "next/navigation";
 import { formatAmount, GroupStatus } from "@sorosave/sdk";
 
-// TODO: Fetch real data from contract
-const MOCK_GROUP = {
+const FORMING_GROUP = {
   id: 1,
   name: "Lagos Savings Circle",
   admin: "GABCDEFGHIJKLMNOPQRSTUVWXYZ234567ABCDEFG",
@@ -21,20 +21,45 @@ const MOCK_GROUP = {
     "GEFGHIJKLMNOPQRSTUVWXYZ234567ABCDEFGHIJ",
     "GIJKLMNOPQRSTUVWXYZ234567ABCDEFGHIJKLMN",
   ],
+  payoutOrder: [],
+  currentRound: 0,
+  totalRounds: 5,
+  status: GroupStatus.Forming,
+  createdAt: 1700000000,
+};
+
+const ACTIVE_GROUP = {
+  id: 2,
+  name: "DeFi Builders Fund",
+  admin: "GABCDEFGHIJKLMNOPQRSTUVWXYZ234567ABCDEFG",
+  token: "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC",
+  contributionAmount: 5000000000n,
+  cycleLength: 2592000,
+  maxMembers: 10,
+  members: [
+    "GABCDEFGHIJKLMNOPQRSTUVWXYZ234567ABCDEFG",
+    "GEFGHIJKLMNOPQRSTUVWXYZ234567ABCDEFGHIJ",
+    "GIJKLMNOPQRSTUVWXYZ234567ABCDEFGHIJKLMN",
+    "GMNOPQRSTUVWXYZ234567ABCDEFGHIJKLMNQRST",
+    "GQRSTUVWXYZ234567ABCDEFGHIJKLMNQRSTUVWX",
+  ],
   payoutOrder: [
     "GABCDEFGHIJKLMNOPQRSTUVWXYZ234567ABCDEFG",
     "GEFGHIJKLMNOPQRSTUVWXYZ234567ABCDEFGHIJ",
     "GIJKLMNOPQRSTUVWXYZ234567ABCDEFGHIJKLMN",
+    "GMNOPQRSTUVWXYZ234567ABCDEFGHIJKLMNQRST",
+    "GQRSTUVWXYZ234567ABCDEFGHIJKLMNQRSTUVWX",
   ],
   currentRound: 1,
-  totalRounds: 3,
+  totalRounds: 5,
   status: GroupStatus.Active,
   createdAt: 1700000000,
 };
 
 export default function GroupDetailPage() {
+  const params = useParams<{ id: string }>();
   const [showContributeModal, setShowContributeModal] = useState(false);
-  const group = MOCK_GROUP;
+  const group = params?.id === "1" ? FORMING_GROUP : ACTIVE_GROUP;
 
   return (
     <>
@@ -73,13 +98,17 @@ export default function GroupDetailPage() {
                 {group.status === GroupStatus.Active && (
                   <button
                     onClick={() => setShowContributeModal(true)}
+                    data-tour="contribute-group"
                     className="w-full bg-primary-600 text-white py-3 rounded-lg font-medium hover:bg-primary-700 transition-colors"
                   >
                     Contribute
                   </button>
                 )}
                 {group.status === GroupStatus.Forming && (
-                  <button className="w-full bg-blue-600 text-white py-3 rounded-lg font-medium hover:bg-blue-700 transition-colors">
+                  <button
+                    data-tour="join-group"
+                    className="w-full bg-blue-600 text-white py-3 rounded-lg font-medium hover:bg-blue-700 transition-colors"
+                  >
                     Join Group
                   </button>
                 )}

src/app/groups/page.tsx

@@ -17,7 +17,7 @@ const PLACEHOLDER_GROUPS: SavingsGroup[] = [
     members: ["GABCD...", "GEFGH...", "GIJKL..."],
     payoutOrder: [],
     currentRound: 0,
-    totalRounds: 0,
+    totalRounds: 5,
     status: GroupStatus.Forming,
     createdAt: 1700000000,
   },

src/app/page.tsx

@@ -21,6 +21,7 @@ export default function Home() {
               <div className="flex space-x-4">
                 <Link
                   href="/groups"
+                  data-tour="browse-groups"
                   className="bg-white text-primary-700 px-6 py-3 rounded-lg font-semibold hover:bg-primary-50 transition-colors"
                 >
                   Browse Groups

src/app/providers.tsx

@@ -1,7 +1,15 @@
 "use client";
 
-import React, { createContext, useContext, useState, useCallback, useEffect } from "react";
+import React, {
+  createContext,
+  useContext,
+  useState,
+  useCallback,
+  useEffect,
+  startTransition,
+} from "react";
 import { connectWallet, getPublicKey, isFreighterInstalled } from "@/lib/wallet";
+import { OnboardingTour } from "@/components/OnboardingTour";
 
 interface WalletContextType {
   address: string | null;
@@ -11,6 +19,10 @@ interface WalletContextType {
   disconnect: () => void;
 }
 
+interface OnboardingContextType {
+  startTour: () => void;
+}
+
 const WalletContext = createContext<WalletContextType>({
   address: null,
   isConnected: false,
@@ -19,13 +31,22 @@ const WalletContext = createContext<WalletContextType>({
   disconnect: () => {},
 });
 
+const OnboardingContext = createContext<OnboardingContextType>({
+  startTour: () => {},
+});
+
 export function useWallet() {
   return useContext(WalletContext);
 }
 
+export function useOnboardingTour() {
+  return useContext(OnboardingContext);
+}
+
 export function Providers({ children }: { children: React.ReactNode }) {
   const [address, setAddress] = useState<string | null>(null);
   const [isFreighterAvailable, setIsFreighterAvailable] = useState(false);
+  const [tourRunId, setTourRunId] = useState(0);
 
   useEffect(() => {
     isFreighterInstalled().then(setIsFreighterAvailable);
@@ -45,16 +66,27 @@ export function Providers({ children }: { children: React.ReactNode }) {
   }, []);
 
   return (
-    <WalletContext.Provider
+    <OnboardingContext.Provider
       value={{
-        address,
-        isConnected: !!address,
-        isFreighterAvailable,
-        connect,
-        disconnect,
+        startTour: () => {
+          startTransition(() => {
+            setTourRunId((value) => value + 1);
+          });
+        },
       }}
     >
-      {children}
-    </WalletContext.Provider>
+      <WalletContext.Provider
+        value={{
+          address,
+          isConnected: !!address,
+          isFreighterAvailable,
+          connect,
+          disconnect,
+        }}
+      >
+        {children}
+        <OnboardingTour runId={tourRunId} />
+      </WalletContext.Provider>
+    </OnboardingContext.Provider>
   );
 }

src/components/ConnectWallet.tsx

@@ -13,6 +13,7 @@ export function ConnectWallet() {
         href="https://www.freighter.app/"
         target="_blank"
         rel="noopener noreferrer"
+        data-tour="wallet-connect"
         className="bg-gray-200 text-gray-700 px-4 py-2 rounded-lg text-sm font-medium hover:bg-gray-300"
       >
         Install Freighter
@@ -39,6 +40,7 @@ export function ConnectWallet() {
   return (
     <button
       onClick={connect}
+      data-tour="wallet-connect"
       className="bg-primary-600 text-white px-4 py-2 rounded-lg text-sm font-medium hover:bg-primary-700 transition-colors"
     >
       Connect Wallet

src/components/GroupCard.tsx

@@ -16,8 +16,11 @@ const statusColors: Record<string, string> = {
 };
 
 export function GroupCard({ group }: GroupCardProps) {
+  const tourTarget =
+    group.id === 1 ? "tour-forming-group" : group.id === 2 ? "tour-active-group" : undefined;
+
   return (
-    <Link href={`/groups/${group.id}`}>
+    <Link href={`/groups/${group.id}`} data-tour={tourTarget}>
       <div className="bg-white rounded-xl shadow-sm border p-6 hover:shadow-md transition-shadow cursor-pointer">
         <div className="flex justify-between items-start mb-4">
           <h3 className="text-lg font-semibold text-gray-900">{group.name}</h3>

src/components/Navbar.tsx

@@ -2,8 +2,11 @@
 
 import Link from "next/link";
 import { ConnectWallet } from "./ConnectWallet";
+import { useOnboardingTour } from "@/app/providers";
 
 export function Navbar() {
+  const { startTour } = useOnboardingTour();
+
   return (
     <nav className="bg-white shadow-sm border-b">
       <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
@@ -27,7 +30,16 @@ export function Navbar() {
               </Link>
             </div>
           </div>
-          <ConnectWallet />
+          <div className="flex items-center gap-3">
+            <button
+              type="button"
+              onClick={startTour}
+              className="hidden rounded-full border border-slate-200 px-3 py-2 text-sm font-medium text-slate-600 transition-colors hover:border-slate-300 hover:text-slate-900 sm:inline-flex"
+            >
+              Replay Tour
+            </button>
+            <ConnectWallet />
+          </div>
         </div>
       </div>
     </nav>