feat(onboarding): smart step filtering and stability fixes

app/RootLayoutClient.tsx

@@ -25,6 +25,7 @@ const SearchOverlay = dynamic(() => import("@/components/shared/SearchOverlay"),
 const AirdropModal = dynamic(() => import("@/components/airdrop/AirdropModal"), { ssr: false });
 const ReportModal = dynamic(() => import("@/components/report/ReportModal"), { ssr: false });
 const AccountLinkingDetector = dynamic(() => import("@/components/layout/AccountLinkingDetector"), { ssr: false });
+const OnboardingDetector = dynamic(() => import("@/components/onboarding/OnboardingDetector"), { ssr: false });
 const CommunityToasts = dynamic(() => import("@/components/homepage/CommunityToasts"), { ssr: false });
 const IOSAppBanner = dynamic(() => import("@/components/shared/IOSAppBanner"), { ssr: false });
 const HZCEasterEgg = dynamic(() => import("@/components/shared/HZCEasterEgg"), { ssr: false });
@@ -235,6 +236,9 @@ function InnerLayout({
       {/* Account Linking Detector - auto-prompts when wallets are connected */}
       <AccountLinkingDetector />
 
+      {/* Onboarding Detector - guides new users through profile setup */}
+      <OnboardingDetector />
+
       {/* HZC Easter Egg */}
       <HZCEasterEgg onTrigger={() => searchProps?.setIsSearchOpen(false)} />
 

app/api/userbase/auth/magic-link/route.ts

@@ -88,6 +88,10 @@ function createTransport() {
       user: process.env.EMAIL_USER,
       pass: process.env.EMAIL_PASS,
     },
+    // Local development only: bypass TLS verification for self-signed/proxy certs.
+    ...(process.env.NODE_ENV === 'development' && {
+      tls: { rejectUnauthorized: false },
+    }),
   });
 }
 

app/api/userbase/auth/session/route.ts

@@ -283,7 +283,7 @@ export async function GET(request: NextRequest) {
 
     const { data: sessionRows, error: sessionError } = await supabase
       .from('userbase_sessions')
-      .select('id, user_id, expires_at, revoked_at, userbase_users(id, handle, display_name, avatar_url, status, onboarding_step)')
+      .select('id, user_id, expires_at, revoked_at, userbase_users(id, handle, display_name, avatar_url, bio, status, onboarding_step, created_at)')
       .eq('refresh_token_hash', refreshTokenHash)
       .is('revoked_at', null)
       .limit(1);
@@ -342,7 +342,7 @@ export async function GET(request: NextRequest) {
           .from("userbase_users")
           .update(updates)
           .eq("id", user.id)
-          .select("id, handle, display_name, avatar_url, status, onboarding_step")
+          .select("id, handle, display_name, avatar_url, bio, status, onboarding_step, created_at")
           .single();
         if (updatedUser) {
           user = updatedUser;

app/api/userbase/hive/comment/route.ts

@@ -433,6 +433,13 @@ export async function POST(request: NextRequest) {
       });
     }
 
+    // DRY RUN — set HIVE_DRY_RUN=true in .env.local to skip broadcast during local dev.
+    // Guarded by NODE_ENV=development to prevent accidental use in staging/CI.
+    if (process.env.NODE_ENV === "development" && process.env.HIVE_DRY_RUN === "true") {
+      console.log("[dry-run] Hive broadcast skipped:", { author, permlink, ops });
+      return NextResponse.json({ success: true, author, permlink, dry_run: true });
+    }
+
     const privateKey = PrivateKey.fromString(postingKey as string);
     await HiveClient.broadcast.sendOperations(ops, privateKey);
 

app/api/userbase/profile/route.ts

@@ -245,10 +245,10 @@ export async function PATCH(request: NextRequest) {
 
     // Parse request body
     const body = await request.json();
-    const { display_name, avatar_url, cover_url, bio, location, handle } = body;
+    const { display_name, avatar_url, cover_url, bio, location, handle, onboarding_step_flag } = body;
 
     // Build update object with only provided fields
-    const updateData: Record<string, string | null> = {};
+    const updateData: Record<string, string | number | null> = {};
     if (display_name !== undefined) updateData.display_name = display_name;
     if (avatar_url !== undefined) updateData.avatar_url = avatar_url;
     if (cover_url !== undefined) updateData.cover_url = cover_url;
@@ -262,6 +262,18 @@ export async function PATCH(request: NextRequest) {
       updateData.handle = normalizedHandle;
     }
 
+    // onboarding_step_flag: bitmask OR — only adds bits, never removes them
+    // bit 0 (1) = photo, bit 1 (2) = bio, bit 2 (4) = intro post
+    if (typeof onboarding_step_flag === "number" && onboarding_step_flag > 0) {
+      const { data: currentUser } = await supabase
+        .from("userbase_users")
+        .select("onboarding_step")
+        .eq("id", userId)
+        .single();
+      const currentStep = currentUser?.onboarding_step ?? 0;
+      updateData.onboarding_step = currentStep | onboarding_step_flag;
+    }
+
     if (Object.keys(updateData).length === 0) {
       return NextResponse.json(
         { error: "No fields to update" },

components/onboarding/OnboardingDetector.tsx

@@ -0,0 +1,226 @@
+"use client";
+
+/**
+ * OnboardingDetector
+ *
+ * - Auto-opens the OnboardingModal on first login (once per browser session).
+ * - Shows a persistent floating card until all 3 steps are done.
+ * - Bitmask: photo=1, bio=2, intro post=4 — all done when onboarding_step === 7.
+ */
+
+import { useEffect, useRef, useState } from "react";
+import {
+  Box,
+  Flex,
+  Text,
+  Icon,
+  IconButton,
+  VStack,
+  HStack,
+  Button,
+  useTheme,
+} from "@chakra-ui/react";
+import { FiCamera, FiFileText, FiEdit3, FiCheck, FiX } from "react-icons/fi";
+import dynamic from "next/dynamic";
+import { useUserbaseAuth } from "@/contexts/UserbaseAuthContext";
+import {
+  ONBOARDING_FLAG_PHOTO,
+  ONBOARDING_FLAG_BIO,
+  ONBOARDING_FLAG_POST,
+  ONBOARDING_ALL_DONE,
+  DICEBEAR_URL_PATTERN,
+} from "./OnboardingModal";
+
+const OnboardingModal = dynamic(() => import("./OnboardingModal"), { ssr: false });
+
+// Accounts created before this date are excluded from onboarding.
+const ONBOARDING_LAUNCH_DATE = new Date("2026-04-22");
+
+// sessionStorage keys
+const SS_SEEN = "onboarding_modal_seen"; // set after first auto-open
+const SS_DONE = "onboarding_done";       // set immediately when modal finishes
+
+function isLocallyDone() {
+  return typeof window !== "undefined" && sessionStorage.getItem(SS_DONE) === "true";
+}
+
+export default function OnboardingDetector() {
+  const { user } = useUserbaseAuth();
+  const theme = useTheme();
+
+  const [isModalOpen, setIsModalOpen] = useState(false);
+  const [isCardDismissed, setIsCardDismissed] = useState(false);
+  const hasAutoOpened = useRef(false);
+
+  // ── Auto-open once per browser session for new users ─────────────────────
+  useEffect(() => {
+    if (!user) return;
+    if (hasAutoOpened.current) return;
+
+    const isDone = ((user.onboarding_step ?? 0) & ONBOARDING_ALL_DONE) === ONBOARDING_ALL_DONE || isLocallyDone();
+    if (isDone) return;
+
+    const alreadySeen = typeof window !== "undefined"
+      ? sessionStorage.getItem(SS_SEEN) === "true"
+      : false;
+
+    if (!alreadySeen) {
+      const timeout = setTimeout(() => {
+        setIsModalOpen(true);
+        sessionStorage.setItem(SS_SEEN, "true");
+        hasAutoOpened.current = true;
+      }, 1200);
+      return () => clearTimeout(timeout);
+    }
+
+    hasAutoOpened.current = true;
+  }, [user]);
+
+  // ── Clean up SS_DONE once the server confirms onboarding_step === 7 ───────
+  useEffect(() => {
+    if (!user) return;
+    if (((user.onboarding_step ?? 0) & ONBOARDING_ALL_DONE) === ONBOARDING_ALL_DONE) {
+      sessionStorage.removeItem(SS_DONE);
+    }
+  }, [user]);
+
+  // ── Reset on logout ───────────────────────────────────────────────────────
+  useEffect(() => {
+    if (!user) {
+      hasAutoOpened.current = false;
+      setIsCardDismissed(false);
+      sessionStorage.removeItem(SS_SEEN);
+      sessionStorage.removeItem(SS_DONE);
+    }
+  }, [user]);
+
+  // ── Nothing to show ───────────────────────────────────────────────────────
+  // isLoading intentionally excluded: background refreshes (focus/visibility
+  // events) set isLoading=true while user stays non-null, which would unmount
+  // the modal mid-flow and reset its state.
+  if (!user) return null;
+
+  // Only show onboarding for accounts created after the feature launch date.
+  // Existing users are excluded without any database migration.
+  const createdAt = new Date(user.created_at);
+  if (isNaN(createdAt.getTime()) || createdAt < ONBOARDING_LAUNCH_DATE) return null;
+
+  const step = user.onboarding_step ?? 0;
+  const hasCustomAvatar = !!user.avatar_url && !user.avatar_url.includes(DICEBEAR_URL_PATTERN);
+  const hasBio = !!user.bio?.trim();
+  const effectiveStep = (hasCustomAvatar ? ONBOARDING_FLAG_PHOTO : 0)
+    | (hasBio ? ONBOARDING_FLAG_BIO : 0)
+    | step;
+  const isDone = (effectiveStep & ONBOARDING_ALL_DONE) === ONBOARDING_ALL_DONE || isLocallyDone();
+  if (isDone) return null;
+
+  const items = [
+    ...(!hasCustomAvatar ? [{ flag: ONBOARDING_FLAG_PHOTO, icon: FiCamera, label: "Add a photo" }] : []),
+    ...(!hasBio ? [{ flag: ONBOARDING_FLAG_BIO, icon: FiFileText, label: "Write your bio" }] : []),
+    { flag: ONBOARDING_FLAG_POST, icon: FiEdit3, label: "Intro post" },
+  ];
+
+  const pendingItems = items.filter(({ flag }) => !(effectiveStep & flag));
+  const ctaLabel = pendingItems.length === 1 ? pendingItems[0].label : "finish setup";
+
+  const bgColor = theme.colors.panel || theme.colors.background;
+  const borderColor = theme.colors.border;
+  const dimColor = theme.colors.dim;
+
+  return (
+    <>
+      {/* Modal */}
+      <OnboardingModal
+        isOpen={isModalOpen}
+        onClose={() => setIsModalOpen(false)}
+      />
+
+      {/* Floating card — hidden when dismissed for session OR when modal is open */}
+      {!isCardDismissed && !isModalOpen && (
+        <Box
+          position="fixed"
+          bottom={{ base: "70px", md: "24px" }}
+          right="16px"
+          zIndex={1400}
+          bg={bgColor}
+          border="1px solid"
+          borderColor={borderColor}
+          borderRadius="md"
+          boxShadow="lg"
+          w="200px"
+          overflow="hidden"
+        >
+          {/* Header */}
+          <Flex
+            align="center"
+            justify="space-between"
+            px={3}
+            py={1.5}
+            bg={bgColor}
+            borderBottom="1px solid"
+            borderColor={borderColor}
+          >
+            <Text fontSize="2xs" color={dimColor} fontFamily="mono">
+              profile.sh
+            </Text>
+            <IconButton
+              aria-label="Dismiss"
+              icon={<Icon as={FiX} boxSize={3} />}
+              size="xs"
+              variant="ghost"
+              minW="auto"
+              h="auto"
+              p={0}
+              color={dimColor}
+              onClick={() => setIsCardDismissed(true)}
+            />
+          </Flex>
+
+          {/* Steps checklist */}
+          <VStack align="stretch" spacing={0} px={3} py={2}>
+            {items.map(({ flag, icon, label }) => {
+              const done = Boolean(effectiveStep & flag);
+              return (
+                <HStack key={flag} spacing={2} py={1}>
+                  <Icon
+                    as={done ? FiCheck : icon}
+                    boxSize={3.5}
+                    color={done ? "green.400" : "orange.400"}
+                    flexShrink={0}
+                  />
+                  <Text
+                    fontSize="xs"
+                    fontFamily="mono"
+                    color={done ? "green.400" : "text"}
+                    textDecoration={done ? "line-through" : "none"}
+                    opacity={done ? 0.6 : 1}
+                  >
+                    {label}
+                  </Text>
+                  {!done && (
+                    <Text fontSize="2xs" color="orange.400" fontFamily="mono" ml="auto">
+                      pending
+                    </Text>
+                  )}
+                </HStack>
+              );
+            })}
+          </VStack>
+
+          {/* CTA */}
+          <Box px={3} pb={3}>
+            <Button
+              size="xs"
+              w="full"
+              colorScheme="orange"
+              fontFamily="mono"
+              onClick={() => setIsModalOpen(true)}
+            >
+              {ctaLabel}
+            </Button>
+          </Box>
+        </Box>
+      )}
+    </>
+  );
+}