feat(exercises): improve attempt time tracking and UI

- Add resetTimeSpent action to exercise store
- Update analytics to track time only during active attempts
- Improve exercise stats UI with borders and dividers
- Fix choice selection logic in exercise answers
- Update dependencies including @types/node to 25.0.8
- Add vitest config for backend testing
- Document exercise time tracking architecture in utils
- Refactor attempt duration calculation to use wall-clock time

Author: nabilfatih

AGENTS.md

@@ -8,7 +8,8 @@
 - `pnpm --filter www dev` - Start single app
 - `pnpm build` - Build all packages/apps
 - `pnpm test` - Run all tests (Vitest)
-- `pnpm --filter www test` - Run www tests, use `vitest run <file>` for single test
+- `pnpm --filter www test` - Run www tests
+- `pnpm --filter www exec vitest run <file-path>` - Run single test file
 - `pnpm lint` - Ultracite check
 - `pnpm format` - Ultracite fix
 
@@ -27,15 +28,30 @@
 
 - Check existing patterns before creating new components
 - Use shared packages (`@repo/design-system`, `@repo/ai`, etc.) instead of duplicating code
-- For MDX content: use `InlineMath` for numbers and math, inline code for programming elements
+- For MDX content: use `InlineMath` for numbers/math, inline code for programming
 - Convex backend in `packages/backend/convex/`, use auth helpers never `ctx.auth` directly, see `packages/backend/convex/lib` folder for shared utils functions
+- MDX components available without import: `BlockMath`, `InlineMath`, `CodeBlock`, `MathContainer`, `Mermaid`
+- Import required for: `NumberLine`, `LineEquation` from `@repo/design-system/components/contents/*`
+- Import aliases: `@/` for app-level imports, `@repo/*` for workspace packages
+- Allowed Biome exceptions: namespace imports, barrel files, higher cognitive complexity (40)
 - Run lint/test after all changes
 
-# TypeScript Style
+## MDX Content Guidelines
+
+- Headings: start from h2 only, max h3 depth, descriptive (not "Step 1"), no symbols, no InlineMath
+- Code vs Math: inline code (`print()`, `const x`) for programming, InlineMath (`<InlineMath math="5" />`) for math
+- Math formatting: all math in InlineMath/BlockMath, use `MathContainer` to wrap consecutive blocks, units in `\text{}`
+- CodeBlock: required `data` prop with unique languages per component, supports multiple file tabs
+- NumberLine: import required, use InlineMath for all numbers, `startLabel`/`endLabel` for fractions
+- 3D visualizations: generate points via Array.from() with math calculations (never hard-code), use `getColor()` for colors (not randomColor)
+- Lists: use hyphens `-`, no nested lists, proper indentation
+- Line breaks: blank line between text paragraphs and math blocks
+
+## TypeScript Style
 
 NEVER USE ASSERTION! Good typescript is when you can write code like javascript but still type safe.
 
-# Ultracite Code Standards
+## Ultracite Code Standards
 
 This project uses **Ultracite**, a zero-config Biome preset that enforces strict code quality standards through automated formatting and linting.
 
@@ -124,28 +140,20 @@ Write code that is **accessible, performant, type-safe, and maintainable**. Focu
 
 ### Framework-Specific Guidance
 
-**Next.js:**
-
-- Use Next.js `<Image>` component for images
-- Use `next/head` or App Router metadata API for head elements
-- Use Server Components for async data fetching instead of async Client Components
-
-**React 19+:**
-
-- Use ref as a prop instead of `React.forwardRef`
-
-**Solid/Svelte/Vue/Qwik:**
-
-- Use `class` and `for` attributes (not `className` or `htmlFor`)
+- **Next.js**: Use `<Image>` component, App Router metadata API, Server Components for async data
+- **React 19+**: Use ref as prop instead of `React.forwardRef`
 
 ---
 
 ## Testing
 
+- Framework: Vitest with shared config from `@repo/testing`
 - Write assertions inside `it()` or `test()` blocks
+- Use `describe()` for grouping related tests
 - Avoid done callbacks in async tests - use async/await instead
 - Don't use `.only` or `.skip` in committed code
 - Keep test suites reasonably flat - avoid excessive `describe` nesting
+- Test files: `__tests__/` directories or `.test.ts`/.tsx naming
 
 ## When Biome Can't Help
 

apps/api/package.json

@@ -31,7 +31,7 @@
   },
   "devDependencies": {
     "@repo/typescript-config": "workspace:*",
-    "@types/node": "25.0.7",
+    "@types/node": "25.0.8",
     "@types/react": "19.2.8",
     "typescript": "^5.9.3",
     "@vitest/coverage-istanbul": "^4.0.17",

apps/email/package.json

@@ -18,7 +18,7 @@
   "devDependencies": {
     "@react-email/preview-server": "^5.0.5",
     "@repo/typescript-config": "workspace:*",
-    "@types/node": "25.0.7",
+    "@types/node": "25.0.8",
     "@types/react": "19.2.8",
     "typescript": "^5.9.3"
   }

apps/mcp/package.json

@@ -27,7 +27,7 @@
   },
   "devDependencies": {
     "@repo/typescript-config": "workspace:*",
-    "@types/node": "25.0.7",
+    "@types/node": "25.0.8",
     "@types/react": "19.2.8",
     "typescript": "^5.9.3"
   }

apps/www/app/[locale]/(study)/(main)/(contents)/exercises/[category]/[type]/[material]/[...slug]/analytics.tsx

@@ -1,12 +1,9 @@
 "use client";
 
-import {
-  useDebouncedCallback,
-  useIntersection,
-  useInterval,
-} from "@mantine/hooks";
+import { useIntersection, useInterval } from "@mantine/hooks";
 import type { ReactNode } from "react";
 import { useEffect, useRef } from "react";
+import { useAttempt } from "@/lib/context/use-attempt";
 import { useExercise } from "@/lib/context/use-exercise";
 
 export function QuestionAnalytics({
@@ -16,36 +13,30 @@ export function QuestionAnalytics({
   exerciseNumber: number;
   children: ReactNode;
 }) {
+  const attempt = useAttempt((state) => state.attempt);
+
   const ref = useIntersection({ threshold: 0.75 });
   const isActive = ref.entry?.isIntersecting ?? false;
   const timeCounterRef = useRef(0);
 
   const setTimeSpent = useExercise((state) => state.setTimeSpent);
 
-  const debouncedPersist = useDebouncedCallback((time: number) => {
-    setTimeSpent(exerciseNumber, time);
-  }, 1000);
+  const hasActiveAttempt = attempt?.status === "in-progress";
 
   const interval = useInterval(() => {
-    if (isActive) {
+    if (isActive && hasActiveAttempt) {
       timeCounterRef.current += 1;
-      debouncedPersist(timeCounterRef.current);
+      setTimeSpent(exerciseNumber, timeCounterRef.current);
     }
   }, 1000);
 
   useEffect(() => {
-    if (isActive) {
+    if (isActive && hasActiveAttempt) {
       interval.start();
     } else {
       interval.stop();
     }
-  }, [isActive, interval]);
-
-  useEffect(() => {
-    return () => {
-      debouncedPersist.flush();
-    };
-  }, [debouncedPersist]);
+  }, [isActive, hasActiveAttempt, interval]);
 
   return <div ref={ref.ref}>{children}</div>;
 }

apps/www/app/[locale]/(study)/(main)/(contents)/exercises/[category]/[type]/[material]/[...slug]/attempt-complete-button.tsx

@@ -24,6 +24,7 @@ export function CompleteExerciseButton() {
 
   const showStats = useExercise((state) => state.showStats);
   const setShowStats = useExercise((state) => state.setShowStats);
+  const resetTimeSpent = useExercise((state) => state.resetTimeSpent);
 
   const user = useUser((state) => state.user);
   const attempt = useAttempt((state) => state.attempt);
@@ -52,6 +53,7 @@ export function CompleteExerciseButton() {
       try {
         await completeAttempt({ attemptId: attempt._id });
         setOpen(false);
+        resetTimeSpent();
         setShowStats(true);
       } catch {
         toast.error(t("complete-exercise-error"), {
@@ -62,7 +64,7 @@ export function CompleteExerciseButton() {
   };
 
   return (
-    <ButtonGroup>
+    <ButtonGroup className="divide-x divide-primary-foreground/20">
       <Button
         disabled={isPending}
         onClick={() => setOpen(true)}

apps/www/app/[locale]/(study)/(main)/(contents)/exercises/[category]/[type]/[material]/[...slug]/attempt-start-button.tsx

@@ -74,6 +74,7 @@ export function StartExerciseButton({
   const slug = useExercise((state) => state.slug);
   const showStats = useExercise((state) => state.showStats);
   const setShowStats = useExercise((state) => state.setShowStats);
+  const resetTimeSpent = useExercise((state) => state.resetTimeSpent);
 
   const user = useUser((state) => state.user);
   const startAttempt = useMutation(api.exercises.mutations.startAttempt);
@@ -103,6 +104,7 @@ export function StartExerciseButton({
           timeLimit,
         });
         setOpen(false);
+        resetTimeSpent();
         setShowStats(true);
         toast.success(t("start-exercise-success"), {
           position: "bottom-center",
@@ -123,7 +125,7 @@ export function StartExerciseButton({
         form.handleSubmit();
       }}
     >
-      <ButtonGroup>
+      <ButtonGroup className="divide-x divide-primary-foreground/20">
         <Button onClick={() => setOpen(true)} type="button">
           <HugeIcons icon={StartUp02Icon} />
           {t("start-exercise-title")}

apps/www/app/[locale]/(study)/(main)/(contents)/exercises/[category]/[type]/[material]/[...slug]/attempt-stats.tsx

@@ -49,7 +49,7 @@ function StatsResult({ attempt }: { attempt: Doc<"exerciseAttempts"> }) {
   const t = useTranslations("Exercises");
 
   return (
-    <section className="space-y-3 rounded-md bg-muted/20 p-4">
+    <section className="space-y-3 rounded-lg border border-border/50 bg-muted/20 p-4">
       <div className="grid grid-cols-2 gap-3">
         <div className="flex flex-col gap-1">
           <div className="text-muted-foreground text-sm">{t("score")}</div>
@@ -120,7 +120,7 @@ function StatsProgress({
   const progress = totalCount > 0 ? (answeredCount / totalCount) * 100 : 0;
 
   return (
-    <div className="flex flex-col gap-4 rounded-md bg-muted/20 p-4">
+    <div className="flex flex-col gap-4 rounded-lg border border-border/50 bg-muted/20 p-4">
       <div className="flex items-center justify-between text-sm">
         <Badge variant="default-subtle">
           <HugeIcons

apps/www/app/[locale]/(study)/(main)/(contents)/exercises/[category]/[type]/[material]/[...slug]/choices.tsx

@@ -40,7 +40,13 @@ export function ExerciseChoices({ id, exerciseNumber, choices }: Props) {
     (a) => a.exerciseNumber === exerciseNumber
   );
 
-  function handleSubmit(choice: ExercisesChoices[keyof ExercisesChoices][0]) {
+  function handleSubmit({
+    choice,
+    index,
+  }: {
+    choice: ExercisesChoices[keyof ExercisesChoices][number];
+    index: number;
+  }) {
     if (!attempt) {
       toast.info(t("attempt-not-found"), { position: "bottom-center" });
       return;
@@ -57,7 +63,7 @@ export function ExerciseChoices({ id, exerciseNumber, choices }: Props) {
         await submitAttempt({
           attemptId: attempt._id,
           exerciseNumber,
-          selectedOptionId: choice.label,
+          selectedOptionId: index.toString(),
           textAnswer: choice.label,
           isCorrect: choice.value,
           timeSpent,
@@ -70,9 +76,12 @@ export function ExerciseChoices({ id, exerciseNumber, choices }: Props) {
 
   return (
     <div className="grid grid-cols-1 gap-2 md:grid-cols-2">
-      {choices.map((choice) => {
+      {choices.map((choice, index) => {
         let variant: ComponentProps<typeof Button>["variant"] = "outline";
-        const checked = currentAnswer?.selectedOptionId === choice.label;
+
+        const checked =
+          currentAnswer?.selectedOptionId === index.toString() ||
+          currentAnswer?.textAnswer === choice.label;
 
         if (checked) {
           variant = "default-outline";
@@ -97,12 +106,12 @@ export function ExerciseChoices({ id, exerciseNumber, choices }: Props) {
             key={choice.label}
           >
             <Checkbox
-              checked={currentAnswer?.selectedOptionId === choice.label}
+              checked={checked}
               className="cursor-pointer"
               disabled={isPending}
               onCheckedChange={(checked) => {
                 if (checked) {
-                  handleSubmit(choice);
+                  handleSubmit({ choice, index });
                 }
               }}
             />

apps/www/components/shared/open-content.tsx

@@ -32,7 +32,7 @@ import { getGithubUrl } from "@/lib/utils/github";
 
 export function OpenContent({ slug }: { slug: string }) {
   return (
-    <div className="inline-flex divide-x divide-secondary-foreground/10 rounded-md shadow-xs rtl:space-x-reverse">
+    <div className="inline-flex divide-x divide-secondary-foreground/20 rounded-md shadow-xs rtl:space-x-reverse">
       <LLmCopyButton slug={slug} />
       <ViewOptions slug={slug} />
     </div>