frontend/src/components/drawer/WelcomeLetterOverlay.tsx

@@ -1,6 +1,6 @@
 import { AnimatePresence, motion } from "framer-motion";
 import { useEffect, useRef, useState } from "react";
-import { getWelcomeContent } from "../../config/welcomeLetter";
+import { getWelcomeLetterContent } from "../../config/welcomeLetter";
 import { formatDate } from "../../utils/dateFormat";
 import { type CanvasTools, ComposeCanvas } from "../editor/ComposeCanvas";
 import { EnvelopeReveal } from "../reader/EnvelopeReveal";
@@ -21,7 +21,7 @@ export function WelcomeLetterOverlay({
 
   useEffect(() => {
     if (revealState === "REVEALED" && canvasRef.current) {
-      const welcomeContent = getWelcomeContent(userName);
+      const welcomeContent = getWelcomeLetterContent(userName);
       canvasRef.current.loadData(welcomeContent);
     }
   }, [revealState, userName]);

frontend/src/pages/Drawer.test.tsx

@@ -1,4 +1,4 @@
-import { render, screen } from "@testing-library/react";
+import { fireEvent, render, screen } from "@testing-library/react";
 import { MemoryRouter } from "react-router-dom";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { mockUser } from "../../test/fixtures/user.fixture";
@@ -7,77 +7,117 @@ import { useAuthStore } from "../store/useAuthStore";
 import Drawer from "./Drawer";
 
 vi.mock("../hooks/useLetters");
+vi.mock("../components/drawer/WelcomeLetterOverlay", () => ({
+  WelcomeLetterOverlay: ({ onComplete }: any) => (
+    <div data-testid="welcome-letter-overlay">
+      <button
+        type="button"
+        data-testid="overlay-exit-button"
+        onClick={onComplete}
+      >
+        I'll see you
+      </button>
+    </div>
+  ),
+}));
 
 describe("Drawer Page", () => {
-    beforeEach(() => {
-        // Setup authenticated state for the test
-        useAuthStore.setState({
-            user: mockUser,
-            accessToken: "fake-token",
-            isInitializing: false,
-        });
-
-        vi.mocked(useLetters).mockReturnValue({
-            drafts: [],
-            kept: [],
-            sent: [],
-            vault: [],
-            loading: false,
-            isAuthRequired: false,
-        });
+  beforeEach(() => {
+    // Setup authenticated state for the test
+    useAuthStore.setState({
+      user: mockUser,
+      accessToken: "fake-token",
+      isInitializing: false,
     });
 
-    it("renders the cabinet sections and empty state message", () => {
-        render(
-            <MemoryRouter>
-                <Drawer />
-            </MemoryRouter>,
-        );
+    vi.mocked(useLetters).mockReturnValue({
+      drafts: [],
+      kept: [],
+      sent: [],
+      vault: [],
+      loading: false,
+      isAuthRequired: false,
+    });
+  });
 
-        expect(screen.getByText(/Drafts/i)).toBeInTheDocument();
-        expect(screen.getAllByText(/Kept/i).length).toBeGreaterThanOrEqual(1);
-        expect(screen.getByText(/Vault/i)).toBeInTheDocument();
-        expect(screen.getByText(/This drawer remains silent/i)).toBeInTheDocument();
+  it("renders the cabinet sections and empty state message", () => {
+    render(
+      <MemoryRouter>
+        <Drawer />
+      </MemoryRouter>,
+    );
+
+    expect(screen.getByText(/Drafts/i)).toBeInTheDocument();
+    expect(screen.getAllByText(/Kept/i).length).toBeGreaterThanOrEqual(1);
+    expect(screen.getByText(/Vault/i)).toBeInTheDocument();
+    expect(screen.getByText(/This drawer remains silent/i)).toBeInTheDocument();
+  });
+
+  it("renders the loading state", () => {
+    vi.mocked(useLetters).mockReturnValue({
+      drafts: [],
+      kept: [],
+      sent: [],
+      vault: [],
+      loading: true,
+      isAuthRequired: false,
     });
 
-    it("renders the loading state", () => {
-        vi.mocked(useLetters).mockReturnValue({
-            drafts: [],
-            kept: [],
-            sent: [],
-            vault: [],
-            loading: true,
-            isAuthRequired: false,
-        });
+    render(
+      <MemoryRouter>
+        <Drawer />
+      </MemoryRouter>,
+    );
 
-        render(
-            <MemoryRouter>
-                <Drawer />
-            </MemoryRouter>,
-        );
+    expect(screen.getByText(/Opening your cabinet/i)).toBeInTheDocument();
+  });
 
-        expect(screen.getByText(/Opening your cabinet/i)).toBeInTheDocument();
+  it("renders the authentication required modal when api requires auth", () => {
+    vi.mocked(useLetters).mockReturnValue({
+      drafts: [],
+      kept: [],
+      sent: [],
+      vault: [],
+      loading: false,
+      isAuthRequired: true,
     });
 
-    it("renders the authentication required modal when api requires auth", () => {
-        vi.mocked(useLetters).mockReturnValue({
-            drafts: [],
-            kept: [],
-            sent: [],
-            vault: [],
-            loading: false,
-            isAuthRequired: true,
-        });
+    render(
+      <MemoryRouter>
+        <Drawer />
+      </MemoryRouter>,
+    );
 
-        render(
-            <MemoryRouter>
-                <Drawer />
-            </MemoryRouter>,
-        );
+    expect(screen.getByText(/You've been away a while./i)).toBeInTheDocument();
+    expect(screen.getByPlaceholderText(/password/i)).toBeInTheDocument();
+  });
 
-        expect(
-            screen.getByText(/You've been away a while./i),
-        ).toBeInTheDocument();
-        expect(screen.getByPlaceholderText(/password/i)).toBeInTheDocument();
-    });
+  it("renders the welcome letter when firstTime state is present", () => {
+    render(
+      <MemoryRouter
+        initialEntries={[{ pathname: "/drawer", state: { firstTime: true } }]}
+      >
+        <Drawer />
+      </MemoryRouter>,
+    );
+
+    expect(screen.getByTestId("welcome-letter-overlay")).toBeInTheDocument();
+  });
+
+  it("renders the drawer content when the letter is closed", () => {
+    render(
+      <MemoryRouter
+        initialEntries={[{ pathname: "/drawer", state: { firstTime: true } }]}
+      >
+        <Drawer />
+      </MemoryRouter>,
+    );
+
+    const completeButton = screen.getByTestId("overlay-exit-button");
+    fireEvent.click(completeButton);
+
+    expect(
+      screen.queryByTestId("welcome-letter-overlay"),
+    ).not.toBeInTheDocument();
+  });
 });

frontend/src/pages/Drawer.tsx

@@ -1,9 +1,10 @@
 import { FeatherIcon } from "@phosphor-icons/react";
 import { useState } from "react";
-import { useNavigate } from "react-router-dom";
+import { useLocation, useNavigate } from "react-router-dom";
 import { DrawerSection } from "../components/drawer/DrawerSection.tsx";
 import { LetterItem } from "../components/drawer/LetterItem.tsx";
 import { PasskeyModal } from "../components/drawer/PasskeyModal.tsx";
+import { WelcomeLetterOverlay } from "../components/drawer/WelcomeLetterOverlay.tsx";
 import Logo from "../components/Logo";
 import Saajan from "../components/ui/Saajan.tsx";
 import { PATHS } from "../config/routes";
@@ -19,6 +20,10 @@ export default function Drawer() {
 
   const [openSection, setOpenSection] = useState<string | null>(null);
   const navigate = useNavigate();
+  const location = useLocation();
+  const [showWelcomeLetter, setShowWelcomeLetter] = useState(
+    !!location.state?.firstTime,
+  );
   const { drafts, kept, sent, vault, loading, isAuthRequired } = useLetters();
 
   if (!user) return null;
@@ -30,6 +35,16 @@ export default function Drawer() {
     <div className="min-h-screen w-full bg-base-100 text-base-content flex flex-col items-center py-12 px-5 pb-32 font-serif transition-colors">
       <div className="fixed inset-0 bg-vig pointer-events-none z-0" />
 
+      {showWelcomeLetter && (
+        <WelcomeLetterOverlay
+          userName={user.full_name}
+          onComplete={() => {
+            setShowWelcomeLetter(false);
+            navigate(location.pathname, { replace: true, state: {} });
+          }}
+        />
+      )}
+
       {isAuthRequired && <PasskeyModal />}
       <header className="text-center mb-12 z-10 animate-in fade-in slide-in-from-top-4 duration-500">
         <Logo />
@@ -166,12 +181,14 @@ export default function Drawer() {
       <footer className="mt-25 font-sans text-[0.6rem] tracking-widester uppercase text-base-content/10 z-10">
         For your unsaid.
       </footer>
-      <div className="absolute bottom-0 z-50 font-sans">
-        <Saajan
-          message={`Good to see you again, ${user.full_name}.\nWhat's on your mind today?`}
-          position="top"
-        />
-      </div>
+      {!showWelcomeLetter && (
+        <div className="absolute bottom-0 z-50 font-sans">
+          <Saajan
+            message={`Good to see you again, ${user.full_name}.\nWhat's on your mind today?`}
+            position="top"
+          />
+        </div>
+      )}
     </div>
   );
 }