feat: integrate Umami analytics for user interactions across various components. Track sign-in, sign-up, and test attempt events, enhancing user engagement insights. Update README.md to include new db:seed command and document sticky header patterns for detail pages.

AGENTS.md

@@ -72,6 +72,7 @@ bun run db:push          # Push schema changes to PostgreSQL
 bun run db:studio        # Open Drizzle Studio UI
 bun run db:migrate       # Run migrations
 bun run db:generate      # Generate migration files
+bun run db:seed          # Seed reference data (exam types, etc.)
 bun run db:start         # Start local DB (if configured)
 bun run db:stop          # Stop local DB
 
@@ -116,9 +117,117 @@ bun run build            # Build all packages
 - App-level error boundary is in `__root.tsx` using `<ErrorFallback>` — route-level error boundaries via `errorComponent` route option.
 - Lazy-loaded route components use the `.lazy.tsx` pattern: route file is thin, heavy component lives in `components/routes/*Page.tsx` wrapped in `Suspense`.
 
+### Sticky Detail Page Header Pattern
+
+Detail pages with long scrollable content (e.g. `package.$id.index.tsx`, `attempt.$id.tsx`) use a **sticky top header** pattern:
+
+```tsx
+<div className="min-h-screen pb-32 bg-[var(--warm-cream)]">
+  {/* Sticky header */}
+  <div className="sticky top-0 z-20 bg-[var(--warm-cream)]/95 backdrop-blur-sm border-b border-[var(--oat-border)] shadow-sm">
+    <div className="px-6 md:px-12 lg:px-16 max-w-4xl mx-auto pt-4 pb-4">
+      {/* Compact breadcrumb — text-xs, truncated title */}
+      {/* Title row (left) + action buttons (right) */}
+      {/* Stats row — text-xs */}
+    </div>
+  </div>
+  {/* Scrollable content */}
+  <div className="px-6 md:px-12 lg:px-16 max-w-4xl mx-auto pt-8">
+    ...
+  </div>
+</div>
+```
+
+Rules:
+- Primary CTA ("Mulai Latihan", "Coba Lagi") and secondary actions (Edit, Share) live in the sticky header — **never only at the bottom** of a long page.
+- Breadcrumb inside the header is `text-xs` and truncates the current page title to `max-w-[240px]`.
+- On small screens (`sm:` breakpoint), button text labels hide (`hidden sm:inline`) leaving only icons.
+
+### Public/Private Toggle Hover Pattern
+
+Any button that toggles visibility between public and private must reveal **intent on hover** (what will happen, not what it currently is):
+
+```tsx
+<button
+  onClick={onTogglePublic}
+  aria-label={isPublic ? "Jadikan privat" : "Jadikan publik"}
+  className={`group ... ${isPublic
+    ? "bg-[var(--matcha-300)] text-[var(--matcha-800)] hover:bg-[var(--pomegranate-400)]/15 hover:text-[var(--pomegranate-600)]"
+    : "bg-[var(--slushie-500)]/15 text-[var(--slushie-800)] hover:bg-[var(--matcha-300)] hover:text-[var(--matcha-800)]"
+  }`}
+>
+  <MaterialIcon name={isPublic ? "public" : "lock"} className="text-xs group-hover:hidden" />
+  <MaterialIcon name={isPublic ? "lock" : "public"} className="text-xs hidden group-hover:inline" />
+  <span className="group-hover:hidden">{isPublic ? "Publik" : "Privat"}</span>
+  <span className="hidden group-hover:inline">{isPublic ? "Jadikan Privat" : "Jadikan Publik"}</span>
+</button>
+```
+
+This pattern is used in `QuestionCard.tsx` and `PackageCard.tsx`.
+
+### Component Folder Conventions
+
+Large "card" components for list items are extracted into their own folder and file, **not** inlined inside the page component:
+
+| Domain | Card component | Used in |
+|--------|---------------|---------|
+| Questions | `apps/web/src/components/bank/QuestionCard.tsx` | `BankPage.tsx` |
+| Packages | `apps/web/src/components/packages/PackageCard.tsx` | `PackagesPage.tsx` |
+
+When a list item card grows beyond ~40 lines of JSX, extract it. Pass all state through props; the card must be stateless (no data fetching).
+
+### CalloutCard
+
+`apps/web/src/components/bank/CalloutCard.tsx` is a reusable banner for "N items are private, publish them all" prompts. Use the `label` prop to customise the noun:
+
+```tsx
+<CalloutCard count={privateCount} label="soal" onPublishAll={handlePublishAllPrivate} />
+<CalloutCard count={privateCount} label="paket" onPublishAll={handlePublishAllPrivate} />
+```
+
+`count` should come from a **dedicated query with `limit: 1`** (fetches only the `total` field), **not** from the locally accumulated infinite-scroll array — those counts are partial and misleading.
+
+---
+
+## 5b. Route Shell & Layout Modes
+
+### Route Shell System
+
+Every route declares its layout via `staticData` from `apps/web/src/lib/route-shell.ts`. The root layout (`__root.tsx`) reads this to decide which shell to render:
+
+| Shell | When to use | What renders |
+|-------|-------------|-------------|
+| `routeShell.app` | Authenticated app pages | Sidebar + `<main id="main-content">` + SkipLink |
+| `routeShell.public` | Landing, login, auth flows, 404 | Bare `min-h-screen` wrapper, no sidebar |
+| `routeShell.fullscreen` | Test-taking, immersive UIs | `h-screen overflow-y-auto`, no sidebar |
+
+Usage in a route file:
+```tsx
+import { routeShell } from "@/lib/route-shell";
+
+export const Route = createFileRoute("/my-route")({
+  staticData: routeShell.app, // or .public / .fullscreen
+  ...
+});
+```
+
+**Rules:**
+- **Always** set `staticData` on every route. Routes without it default to `"app"` shell (sidebar shown).
+- Auth routes (`/login`, `/forgot-password`, `/verify-email`, `/setup-avatar`) use `routeShell.public`.
+- Test routes (`/package/$id/take`, `/package/$id/attempt/$attemptId`) use `routeShell.fullscreen`.
+- Admin routes (`/admin`, `/admin/*`) use `routeShell.fullscreen`.
+
+### Route Structure Conventions
+
+- **`/`** — Public landing page (`index.tsx` + `index.lazy.tsx`). Redirects logged-in users to `/dashboard`.
+- **`/dashboard`** — Authenticated home page (`dashboard.tsx`). Redirects unauthenticated users to `/login`.
+- **`/landing`** — Legacy redirect → `/` (keep for backward compat, do not remove).
+- **`/$.tsx`** — Catch-all 404 route. Uses `routeShell.public` so no sidebar appears. Renders `<NotFoundPage>`.
+- **Do NOT** put a `notFoundComponent` in `__root.tsx`. The 404 is handled exclusively by the splat route `$.tsx`.
+
 ---
 
-## 5b. Frontend Accessibility Conventions
+## 5c. Frontend Accessibility Conventions
 
 - **Skip link**: Root layout in `__root.tsx` has a hidden `<SkipLink>` that appears on Tab press, linking to `#main-content` on the `<main>` element.
 - **Icon-only buttons**: Every `<button>` or `<Button>` with only an icon (no visible text) **must** have `aria-label`. The icon element (`<MaterialIcon>`, `<span>`) should NOT have `aria-hidden="true"` unless decorative.
@@ -276,4 +385,4 @@ bun run build            # Build all packages
 
 ---
 
-_Last updated: 2026-05-19_
+_Last updated: 2026-05-25_

apps/web/src/components/routes/GeneratePage.tsx

@@ -5,6 +5,7 @@ import { authClient } from "@/lib/auth-client";
 import { trpc } from "@/utils/trpc";
 import { useApiKeys } from "@/hooks/use-api-key";
 import { useGenerationJobs, type CompletedResult } from "@/hooks/use-generation-jobs";
+import { trackUmamiEvent, AnalyticsEvent } from "@/lib/umami";
 import { Button } from "@labas/ui/components/button";
 import {
   Select,
@@ -181,6 +182,18 @@ export function RouteComponent() {
           maxTokens: selectedConfig!.maxTokens ?? 16384,
         };
 
+    const eventName = mode === "agentic" ? AnalyticsEvent.AI_GENERATE_AGENTIC : AnalyticsEvent.AI_GENERATE_QUICK;
+    trackUmamiEvent(eventName, {
+      exam_type: examType,
+      mode,
+      sections: selectedSections,
+      formats: selectedFormats,
+      question_count: questionCount,
+      topics: selectedTopics,
+      difficulty: difficulty + 1,
+      use_free_credits: useFreeCredits,
+    });
+
     type GenerateMutateInput = Parameters<typeof generate.mutate>[0];
     generate.mutate({
       examType,

apps/web/src/components/routes/HistoryPage.tsx

@@ -4,6 +4,7 @@ import { createFileRoute, redirect, Link } from "@tanstack/react-router";
 import { z } from "zod";
 import { authClient } from "@/lib/auth-client";
 import { trpc } from "@/utils/trpc";
+import { trackUmamiEvent, AnalyticsEvent } from "@/lib/umami";
 import { Button } from "@labas/ui/components/button";
 import { Card, CardContent } from "@labas/ui/components/card";
 import { Input } from "@labas/ui/components/input";
@@ -86,6 +87,10 @@ export function HistoryComponent() {
     setLocalSearch(searchQuery);
   }, [searchQuery]);
 
+  useEffect(() => {
+    trackUmamiEvent(AnalyticsEvent.VIEW_HISTORY);
+  }, []);
+
   useEffect(() => {
     if (debounceRef.current) clearTimeout(debounceRef.current);
     debounceRef.current = setTimeout(() => {

apps/web/src/components/sign-in-form.tsx

@@ -8,6 +8,7 @@ import { toast } from "sonner";
 import z from "zod";
 
 import { authClient } from "@/lib/auth-client";
+import { trackUmamiEvent, AnalyticsEvent } from "@/lib/umami";
 
 import Loader from "./loader";
 
@@ -30,6 +31,7 @@ export default function SignInForm({ onSwitchToSignUp }: { onSwitchToSignUp: ()
         },
         {
           onSuccess: () => {
+            trackUmamiEvent(AnalyticsEvent.SIGN_IN);
             navigate({ to: "/dashboard" });
             toast.success("Sign in successful");
           },

apps/web/src/components/sign-up-form.tsx

@@ -10,6 +10,7 @@ import z from "zod";
 
 import { authClient } from "@/lib/auth-client";
 import { trpc } from "@/utils/trpc";
+import { trackUmamiEvent, AnalyticsEvent } from "@/lib/umami";
 
 import Loader from "./loader";
 
@@ -35,6 +36,7 @@ export default function SignUpForm({ onSwitchToSignIn }: { onSwitchToSignIn: ()
         },
         {
           onSuccess: async () => {
+            trackUmamiEvent(AnalyticsEvent.SIGN_UP);
             try {
               await sendOtpMutation.mutateAsync({ email: value.email });
             } catch {}

apps/web/src/hooks/use-api-key.ts

@@ -1,5 +1,6 @@
 import { useState, useEffect, useCallback } from "react";
 import { encryptText, decryptText } from "@/lib/crypto";
+import { trackUmamiEvent, AnalyticsEvent } from "@/lib/umami";
 
 const STORAGE_KEY = "labas_api_keys_v2";
 
@@ -49,6 +50,7 @@ export function useApiKeys() {
     async (config: Omit<ApiKeyConfig, "id">) => {
       const next = [...configs, { ...config, id: generateId() }];
       await persist(next);
+      trackUmamiEvent(AnalyticsEvent.API_KEY_ADDED, { provider: config.provider });
       return next[next.length - 1].id;
     },
     [configs, persist],
@@ -72,8 +74,12 @@ export function useApiKeys() {
 
   const removeConfig = useCallback(
     async (id: string) => {
+      const target = configs.find((c) => c.id === id);
       const next = configs.filter((c) => c.id !== id);
       await persist(next);
+      if (target) {
+        trackUmamiEvent(AnalyticsEvent.API_KEY_REMOVED, { provider: target.provider });
+      }
     },
     [configs, persist],
   );

apps/web/src/hooks/use-test-session.ts

@@ -212,11 +212,12 @@ export function useTestSession(packageId: string, existingAttemptId?: string) {
     if (!attemptId) return;
     setIsFinished(true);
     localStorage.setItem("pendingDonationPrompt", "exam");
-    await finishMutation.mutateAsync({ attemptId });
+    const result = await finishMutation.mutateAsync({ attemptId });
     clearElapsedTime(attemptId);
     clearMarkedQuestions(attemptId);
     clearSectionIdx(attemptId);
     navigate({ to: "/attempt/$id", params: { id: attemptId } });
+    return result;
   }, [attemptId, finishMutation, navigate]);
 
   const handleAbandon = useCallback(async () => {

apps/web/src/lib/umami.ts

@@ -0,0 +1,72 @@
+export const AnalyticsEvent = {
+  ATTEMPT_START: "attempt_start",
+  ATTEMPT_FINISH: "attempt_finish",
+  ATTEMPT_ABANDON: "attempt_abandon",
+  AI_GENERATE_QUICK: "ai_generate_quick",
+  AI_GENERATE_AGENTIC: "ai_generate_agentic",
+  SIGN_IN: "sign_in",
+  SIGN_UP: "sign_up",
+  API_KEY_ADDED: "api_key_added",
+  API_KEY_REMOVED: "api_key_removed",
+  VIEW_ANALYTICS: "view_analytics",
+  VIEW_HISTORY: "view_history",
+} as const;
+
+export type AnalyticsEventName = (typeof AnalyticsEvent)[keyof typeof AnalyticsEvent];
+
+export interface AttemptStartPayload {
+  exam_type: string;
+  question_count: number;
+}
+
+export interface AttemptFinishPayload {
+  exam_type: string;
+  score: number;
+  max_score: number;
+  percentage: number;
+  time_elapsed_sec: number;
+}
+
+export interface AttemptAbandonPayload {
+  exam_type: string;
+  questions_answered: number;
+  total_questions: number;
+}
+
+export interface AiGeneratePayload {
+  exam_type: string;
+  mode: string;
+  sections: string[];
+  formats: string[];
+  question_count: number;
+  topics: string[];
+  difficulty: number;
+  use_free_credits: boolean;
+}
+
+export interface ApiKeyPayload {
+  provider: string;
+}
+
+type EventPayloadMap = {
+  [AnalyticsEvent.ATTEMPT_START]: AttemptStartPayload;
+  [AnalyticsEvent.ATTEMPT_FINISH]: AttemptFinishPayload;
+  [AnalyticsEvent.ATTEMPT_ABANDON]: AttemptAbandonPayload;
+  [AnalyticsEvent.AI_GENERATE_QUICK]: AiGeneratePayload;
+  [AnalyticsEvent.AI_GENERATE_AGENTIC]: AiGeneratePayload;
+  [AnalyticsEvent.API_KEY_ADDED]: ApiKeyPayload;
+  [AnalyticsEvent.API_KEY_REMOVED]: ApiKeyPayload;
+  [AnalyticsEvent.SIGN_IN]: Record<string, never>;
+  [AnalyticsEvent.SIGN_UP]: Record<string, never>;
+  [AnalyticsEvent.VIEW_ANALYTICS]: Record<string, never>;
+  [AnalyticsEvent.VIEW_HISTORY]: Record<string, never>;
+};
+
+export function trackUmamiEvent<T extends AnalyticsEventName>(
+  eventName: T,
+  payload?: T extends keyof EventPayloadMap ? EventPayloadMap[T] : never,
+): void {
+  if (import.meta.env.DEV) return;
+  if (typeof window === "undefined" || !window.umami) return;
+  window.umami.track(eventName, payload as Record<string, unknown>);
+}

apps/web/src/routes/analytics.tsx

@@ -1,7 +1,8 @@
-import { Suspense, lazy } from "react";
+import { Suspense, lazy, useEffect } from "react";
 import { createFileRoute, redirect, Link } from "@tanstack/react-router";
 import { authClient } from "@/lib/auth-client";
 import { useAnalytics } from "@/hooks/use-analytics";
+import { trackUmamiEvent, AnalyticsEvent } from "@/lib/umami";
 import { MaterialIcon } from "@/components/ui/MaterialIcon";
 import { OverviewCards } from "@/components/analytics/OverviewCards";
 import { WeaknessPanel } from "@/components/analytics/WeaknessPanel";
@@ -40,6 +41,10 @@ function AnalyticsComponent() {
     isLoading,
   } = useAnalytics();
 
+  useEffect(() => {
+    trackUmamiEvent(AnalyticsEvent.VIEW_ANALYTICS);
+  }, []);
+
   if (isLoading) {
     return (
       <div className="min-h-screen pt-8 pb-32 px-6 md:px-12 lg:px-16 max-w-7xl mx-auto bg-[var(--warm-cream)]">

apps/web/src/routes/package.$id.attempt.$attemptId.tsx

@@ -1,8 +1,10 @@
+import { useCallback } from "react";
 import { useQuery } from "@tanstack/react-query";
 import { createFileRoute, redirect, Link } from "@tanstack/react-router";
 import { authClient } from "@/lib/auth-client";
 import { trpc } from "@/utils/trpc";
 import { useTestSession } from "@/hooks/use-test-session";
+import { trackUmamiEvent, AnalyticsEvent } from "@/lib/umami";
 import { Button } from "@labas/ui/components/button";
 import { MaterialIcon } from "@/components/ui/MaterialIcon";
 import { AttemptTestView } from "@/components/test/AttemptTestView";
@@ -67,6 +69,28 @@ function ContinueAttemptComponent() {
   const totalQuestions = pkg.sections.reduce((sum: number, sec) => sum + sec.questions.length, 0);
   const answeredCount = Object.keys(answers).length;
 
+  const handleFinishWithTracking = useCallback(async () => {
+    const result = await handleFinish();
+    if (result) {
+      trackUmamiEvent(AnalyticsEvent.ATTEMPT_FINISH, {
+        exam_type: pkg.examTypeName ?? "unknown",
+        score: result.totalScore,
+        max_score: result.maxScore,
+        percentage: result.percentage,
+        time_elapsed_sec: timeElapsed,
+      });
+    }
+  }, [handleFinish, pkg.examTypeName, timeElapsed]);
+
+  const handleAbandonWithTracking = useCallback(async () => {
+    await handleAbandon();
+    trackUmamiEvent(AnalyticsEvent.ATTEMPT_ABANDON, {
+      exam_type: pkg.examTypeName ?? "unknown",
+      questions_answered: answeredCount,
+      total_questions: totalQuestions,
+    });
+  }, [handleAbandon, pkg.examTypeName, answeredCount, totalQuestions]);
+
   const currentSection = pkg.sections[currentSectionIdx];
   if (!currentSection) {
     return (
@@ -74,7 +98,7 @@ function ContinueAttemptComponent() {
         <div className="text-center py-20">
           <MaterialIcon name="check_circle" className="text-6xl text-[var(--matcha-600)] mx-auto mb-4" />
           <p className="text-xl font-headline font-bold text-[var(--clay-black)]">Semua section selesai!</p>
-          <Button onClick={handleFinish} className="mt-6 bg-[var(--clay-black)] text-[var(--pure-white)] clay-hover rounded-[var(--radius-lg)]">
+          <Button onClick={handleFinishWithTracking} className="mt-6 bg-[var(--clay-black)] text-[var(--pure-white)] clay-hover rounded-[var(--radius-lg)]">
             Selesaikan & Lihat Hasil
           </Button>
         </div>
@@ -93,8 +117,8 @@ function ContinueAttemptComponent() {
       timeElapsed={timeElapsed}
       answeredCount={answeredCount}
       totalQuestions={totalQuestions}
-      onFinish={handleFinish}
-      onAbandon={handleAbandon}
+      onFinish={handleFinishWithTracking}
+      onAbandon={handleAbandonWithTracking}
       isFinished={isFinished}
       submittingQId={submittingQId}
       markedQuestions={markedQuestions}

apps/web/src/routes/package.$id.take.tsx

@@ -1,9 +1,10 @@
-import { useEffect } from "react";
+import { useEffect, useCallback } from "react";
 import { useQuery } from "@tanstack/react-query";
 import { createFileRoute, redirect, Link, useNavigate } from "@tanstack/react-router";
 import { authClient } from "@/lib/auth-client";
 import { trpc } from "@/utils/trpc";
 import { useTestSession } from "@/hooks/use-test-session";
+import { trackUmamiEvent, AnalyticsEvent } from "@/lib/umami";
 import { Button } from "@labas/ui/components/button";
 import { Card, CardContent } from "@labas/ui/components/card";
 import { MaterialIcon } from "@/components/ui/MaterialIcon";
@@ -92,6 +93,36 @@ function TakeTestComponent() {
   const totalQuestions = pkg.sections.reduce((sum: number, sec) => sum + sec.questions.length, 0);
   const answeredCount = Object.keys(answers).length;
 
+  const handleStartWithTracking = useCallback(async () => {
+    await handleStart();
+    trackUmamiEvent(AnalyticsEvent.ATTEMPT_START, {
+      exam_type: pkg.examTypeName ?? "unknown",
+      question_count: totalQuestions,
+    });
+  }, [handleStart, pkg.examTypeName, totalQuestions]);
+
+  const handleFinishWithTracking = useCallback(async () => {
+    const result = await handleFinish();
+    if (result) {
+      trackUmamiEvent(AnalyticsEvent.ATTEMPT_FINISH, {
+        exam_type: pkg.examTypeName ?? "unknown",
+        score: result.totalScore,
+        max_score: result.maxScore,
+        percentage: result.percentage,
+        time_elapsed_sec: timeElapsed,
+      });
+    }
+  }, [handleFinish, pkg.examTypeName, timeElapsed]);
+
+  const handleAbandonWithTracking = useCallback(async () => {
+    await handleAbandon();
+    trackUmamiEvent(AnalyticsEvent.ATTEMPT_ABANDON, {
+      exam_type: pkg.examTypeName ?? "unknown",
+      questions_answered: answeredCount,
+      total_questions: totalQuestions,
+    });
+  }, [handleAbandon, pkg.examTypeName, answeredCount, totalQuestions]);
+
   // Start screen
   if (!isStarted) {
     return (
@@ -144,7 +175,7 @@ function TakeTestComponent() {
           )}
 
           <Button
-            onClick={handleStart}
+            onClick={handleStartWithTracking}
             disabled={startPending}
             className="bg-[var(--clay-black)] text-[var(--pure-white)] hover:bg-[var(--warm-charcoal)] clay-hover rounded-[var(--radius-lg)] px-8 py-6 text-lg"
           >
@@ -174,7 +205,7 @@ function TakeTestComponent() {
         <div className="text-center py-20">
           <MaterialIcon name="check_circle" className="text-6xl text-[var(--matcha-600)] mx-auto mb-4" />
           <p className="text-xl font-headline font-bold text-[var(--clay-black)]">Semua section selesai!</p>
-          <Button onClick={handleFinish} className="mt-6 bg-[var(--clay-black)] text-[var(--pure-white)] clay-hover rounded-[var(--radius-lg)]">
+          <Button onClick={handleFinishWithTracking} className="mt-6 bg-[var(--clay-black)] text-[var(--pure-white)] clay-hover rounded-[var(--radius-lg)]">
             Selesaikan & Lihat Hasil
           </Button>
         </div>
@@ -193,8 +224,8 @@ function TakeTestComponent() {
       timeElapsed={timeElapsed}
       answeredCount={answeredCount}
       totalQuestions={totalQuestions}
-      onFinish={handleFinish}
-      onAbandon={handleAbandon}
+      onFinish={handleFinishWithTracking}
+      onAbandon={handleAbandonWithTracking}
       isFinished={isFinished}
       submittingQId={submittingQId}
       markedQuestions={markedQuestions}

apps/web/src/types/umami.d.ts

@@ -0,0 +1,5 @@
+interface Window {
+  umami?: {
+    track: (eventName: string, eventData?: Record<string, unknown>) => void;
+  };
+}