question-bank-framework 0.7.0 → 0.8.0

package/README.md

@@ -36,6 +36,10 @@ Your app owns:
 @source '../node_modules/question-bank-framework'; /* relative to this file */
 ```
 
+`theme.css` also pulls in the KaTeX stylesheet from the framework's own `katex`,
+matching the version that renders math. Don't import `katex/dist/katex.min.css`
+yourself — a mismatched KaTeX version breaks math layout (0.19 renamed its CSS classes).
+
 Text columns sort number-aware ("Q2" before "Q10"). New quizzes keep the
 table's current sort order, so to get source order add a numeric field (e.g.
 `order`) and sort by it, or set it in `defaultSorting`.
@@ -44,6 +48,17 @@ Pass `hideTagsColumn: true` to `defineBank` when tags merely duplicate
 dedicated fields (every tag equals a topic/type value already in its own
 column). Tags still feed free-text search.
 
+## Mock-exam timer
+
+The header has a **Timer** link to `/timer` (add `src/routes/timer.tsx`
+rendering `<ExamTimerPage />`, as in the template). Enter the exam's start
+time (e.g. 08:30) and reading/writing minutes, then press Start: the top right
+of the header shows the mock exam time, starting at 08:30, with a book icon
+during reading time and a pen during writing time. It updates once a minute.
+Toasts announce reading time over, 30 and 10 minutes remaining, and exam over;
+the clock disappears once the exam is over. The timer lives in localStorage,
+so it survives reloads and shows in every open tab.
+
 ## Sync (Cloudflare Durable Objects)
 
 Without `sync`, quizzes and question statuses live only in the browser's

package/framework/components/app-shell.tsx

@@ -4,51 +4,61 @@
 import { Link, useRouterState } from '@tanstack/react-router';
 import type { ReactNode } from 'react';
 import { cn } from '../lib/utils.ts';
+import { ExamTimerBadge } from './exam-timer.tsx';
+import { Toaster } from './ui/toast';
 
 export function AppShell({
   children,
   brand,
   homeLabel = 'Question bank',
   quizzesLabel = 'My quizzes',
+  timerLabel = 'Timer',
 }: {
   children: ReactNode;
   brand: string;
   homeLabel?: string;
   quizzesLabel?: string;
+  timerLabel?: string;
 }) {
   const pathname = useRouterState({ select: (state) => state.location.pathname });
   const navigation = [
     { label: homeLabel, to: '/' },
     { label: quizzesLabel, to: '/quizzes' },
+    { label: timerLabel, to: '/timer' },
   ] as const;
   const isQuestionBank = pathname === '/';
 
   return (
-    <div className={cn('flex flex-col bg-white', isQuestionBank ? 'h-dvh overflow-hidden' : 'min-h-dvh')}>
-      <header className="sticky top-0 z-20 shrink-0 border-b border-gray-200 bg-white">
-        <div className="mx-auto flex h-16 w-full max-w-6xl items-center gap-8 px-4">
-          <Link to="/" className="text-lg font-bold text-gray-900">
-            {brand}
-          </Link>
-          <nav className="flex items-center gap-6" aria-label="Main navigation">
-            {navigation.map(({ label, to }) => {
-              const active = to === '/' ? pathname === '/' : pathname.startsWith(to);
-              return (
-                <Link
-                  key={to}
-                  to={to}
-                  className={cn('text-sm font-semibold text-gray-600 hover:text-gray-900', active && 'text-gray-900 underline underline-offset-4')}
-                >
-                  {label}
-                </Link>
-              );
-            })}
-          </nav>
-        </div>
-      </header>
-      <main className={cn('w-full flex-1', isQuestionBank ? 'flex min-h-0 flex-col overflow-hidden' : 'mx-auto max-w-6xl px-4 py-8')}>
-        {children}
-      </main>
-    </div>
+    <Toaster>
+      <div className={cn('flex flex-col bg-white', isQuestionBank ? 'h-dvh overflow-hidden' : 'min-h-dvh')}>
+        <header className="sticky top-0 z-20 shrink-0 border-b border-gray-200 bg-white">
+          <div className="mx-auto flex h-16 w-full max-w-6xl items-center gap-8 px-4">
+            <Link to="/" className="text-lg font-bold text-gray-900">
+              {brand}
+            </Link>
+            <nav className="flex items-center gap-6" aria-label="Main navigation">
+              {navigation.map(({ label, to }) => {
+                const active = to === '/' ? pathname === '/' : pathname.startsWith(to);
+                return (
+                  <Link
+                    key={to}
+                    to={to}
+                    className={cn('text-sm font-semibold text-gray-600 hover:text-gray-900', active && 'text-gray-900 underline underline-offset-4')}
+                  >
+                    {label}
+                  </Link>
+                );
+              })}
+            </nav>
+            <div className="ml-auto">
+              <ExamTimerBadge />
+            </div>
+          </div>
+        </header>
+        <main className={cn('w-full flex-1', isQuestionBank ? 'flex min-h-0 flex-col overflow-hidden' : 'mx-auto max-w-6xl px-4 py-8')}>
+          {children}
+        </main>
+      </div>
+    </Toaster>
   );
 }

package/framework/components/exam-timer.tsx

@@ -0,0 +1,125 @@
+// Mock-exam clock: <ExamTimerBadge> shows the mock time in the header while an
+// exam is running; <ExamTimerPage> (the /timer route) is the only place to start it.
+// Framework-owned: eject with `qb reveal framework/components/exam-timer.tsx`.
+
+import { useEffect, useRef, useState, type FormEvent } from 'react';
+import { BookOpen, PenLine } from 'lucide-react';
+import { useBank } from '../../core/config.tsx';
+import { Button } from './ui/button';
+import { Input } from './ui/input';
+import { toast } from './ui/toast';
+import { examState, formatClock, MINUTE, setExamTimer, useExamNow, useExamTimer, type ExamTimer } from '../lib/exam-timer.ts';
+
+/** Moments to announce, in minutes after Start. */
+const milestones = ({ readingMinutes: reading, writingMinutes: writing }: ExamTimer) => {
+  const end = reading + writing;
+  return [
+    ...(reading > 0 ? [{ at: reading, title: 'Reading time over' }] : []),
+    ...(writing > 30 ? [{ at: end - 30, title: '30 minutes remaining' }] : []),
+    ...(writing > 10 ? [{ at: end - 10, title: '10 minutes remaining' }] : []),
+    { at: end, title: 'Exam over' },
+  ];
+};
+
+export function ExamTimerBadge() {
+  const { namespace } = useBank();
+  const timer = useExamTimer(namespace);
+  const now = useExamNow(timer);
+  const state = timer ? examState(timer, now) : null;
+
+  // Toast each milestone crossed since the last tick (not ones already past on load).
+  const last = useRef<{ startedAt: number; elapsed: number } | null>(null);
+  useEffect(() => {
+    if (!timer || !state) return;
+    const previous = last.current;
+    if (previous?.startedAt === timer.startedAt) {
+      for (const { at, title } of milestones(timer)) {
+        if (previous.elapsed < at * MINUTE && at * MINUTE <= state.elapsed) toast.add({ title });
+      }
+    }
+    last.current = { startedAt: timer.startedAt, elapsed: state.elapsed };
+  }, [timer?.startedAt, state?.elapsed]);
+
+  if (!state || state.phase === 'over') return null;
+  const Icon = state.phase === 'reading' ? BookOpen : PenLine;
+  return (
+    <span
+      className="flex items-center gap-1.5 text-sm font-medium tabular-nums text-gray-700"
+      title={state.phase === 'reading' ? 'Reading time' : 'Writing time'}
+    >
+      <Icon aria-hidden="true" className="size-4" />
+      <span className="sr-only">{state.phase === 'reading' ? 'Reading time' : 'Writing time'}, mock exam time </span>
+      {state.clock}
+    </span>
+  );
+}
+
+const parseClock = (time: string) => {
+  const [hours, minutes] = time.split(':').map(Number);
+  return (hours ?? 0) * 60 + (minutes ?? 0);
+};
+
+export function ExamTimerPage({
+  defaultStart = '08:30',
+  defaultReadingMinutes = 15,
+  defaultWritingMinutes = 180,
+}: {
+  defaultStart?: string;
+  defaultReadingMinutes?: number;
+  defaultWritingMinutes?: number;
+}) {
+  const { namespace } = useBank();
+  const timer = useExamTimer(namespace);
+  const now = useExamNow(timer);
+  const running = timer !== null && examState(timer, now).phase !== 'over';
+  const [start, setStart] = useState(defaultStart);
+  const [reading, setReading] = useState(String(defaultReadingMinutes));
+  const [writing, setWriting] = useState(String(defaultWritingMinutes));
+
+  // Show the saved settings once they're read (after hydration, or when another tab changes them).
+  useEffect(() => {
+    if (!timer) return;
+    setStart(formatClock(timer.startMinutes));
+    setReading(String(timer.readingMinutes));
+    setWriting(String(timer.writingMinutes));
+  }, [timer?.startedAt]);
+
+  const submit = (event: FormEvent) => {
+    event.preventDefault();
+    setExamTimer(namespace, {
+      startMinutes: parseClock(start),
+      startedAt: Date.now(),
+      readingMinutes: Math.max(0, Number(reading) || 0),
+      writingMinutes: Math.max(0, Number(writing) || 0),
+    });
+  };
+
+  const field = 'grid gap-1.5 text-sm font-medium text-gray-700';
+  return (
+    <div className="grid max-w-sm gap-6">
+      <h1 className="m-0 text-3xl font-bold tracking-tight text-gray-900">Timer</h1>
+      <form onSubmit={submit} className="grid gap-4">
+        <label className={field}>
+          Exam start time
+          <Input type="time" required value={start} onChange={(event) => setStart(event.target.value)} />
+        </label>
+        <label className={field}>
+          Reading minutes
+          <Input type="number" min={0} required value={reading} onChange={(event) => setReading(event.target.value)} />
+        </label>
+        <label className={field}>
+          Writing minutes
+          <Input type="number" min={0} required value={writing} onChange={(event) => setWriting(event.target.value)} />
+        </label>
+        <div className="flex gap-2">
+          <Button type="submit">{running ? 'Restart' : 'Start'}</Button>
+          {running && (
+            <Button type="button" variant="outline" onClick={() => setExamTimer(namespace, null)}>
+              Stop
+            </Button>
+          )}
+        </div>
+      </form>
+    </div>
+  );
+}

package/framework/components/markdown-content.tsx

@@ -1,30 +1,67 @@
+import katex from 'katex'
+import type { ReactNode } from 'react'
 import ReactMarkdown, { type Components } from 'react-markdown'
-import rehypeKatex from 'rehype-katex'
 import remarkGfm from 'remark-gfm'
 import remarkMath from 'remark-math'
 import { cn } from '../lib/utils.ts'
 
+// Math is rendered with the framework's own `katex` dependency rather than
+// rehype-katex, which pins katex@^0.16. KaTeX 0.19 renamed its CSS classes
+// (`.base` → `.katex-base`, …), so 0.16 markup styled by 0.19 CSS loses its
+// layout (subscripts wrap and overlap). theme.css imports the CSS from the
+// same katex package, so markup and stylesheet always agree.
+const textOf = (children: ReactNode): string =>
+  Array.isArray(children) ? children.map(textOf).join('') : typeof children === 'string' || typeof children === 'number' ? String(children) : ''
+
+const hasClass = (className: unknown, name: string) =>
+  (Array.isArray(className) ? className.map(String) : String(className ?? '').split(/\s+/)).includes(name)
+
+function MathFormula({ tex, display }: { tex: string; display: boolean }) {
+  const html = katex.renderToString(tex, { displayMode: display, throwOnError: false, strict: 'ignore' })
+  return display
+    ? <div dangerouslySetInnerHTML={{ __html: html }} />
+    : <span dangerouslySetInnerHTML={{ __html: html }} />
+}
+
+// Every renderer drops react-markdown's `node` prop so it isn't forwarded to the DOM.
 const components: Components = {
-  a: ({ ...props }) => <a className="font-medium text-green-800 underline decoration-green-300 underline-offset-2 hover:text-green-950" target="_blank" rel="noreferrer" {...props} />,
-  blockquote: ({ ...props }) => <blockquote className="my-4 border-l-2 border-gray-300 pl-4 text-gray-700" {...props} />,
-  code: ({ className, children, ...props }) => {
-    const isBlock = className?.startsWith('language-') ?? false
-    return <code className={cn(isBlock ? 'font-mono text-sm' : 'rounded bg-gray-100 px-1 py-0.5 font-mono text-[0.9em] text-gray-900 break-words', className)} {...props}>{children}</code>
+  a: ({ node: _node, ...props }) => <a className="font-medium text-green-800 underline decoration-green-300 underline-offset-2 hover:text-green-950" target="_blank" rel="noreferrer" {...props} />,
+  blockquote: ({ node: _node, ...props }) => <blockquote className="my-4 border-l-2 border-gray-300 pl-4 text-gray-700" {...props} />,
+  code: ({ node: _node, className, children, ...props }) => {
+    if (hasClass(className, 'language-math')) {
+      return <MathFormula tex={textOf(children)} display={hasClass(className, 'math-display')} />
+    }
+    // Inline-code styling; fenced blocks reset it via the `pre` renderer below.
+    return <code className={cn('rounded bg-gray-100 px-1 py-0.5 font-mono text-[0.9em] text-gray-900 break-words', className)} {...props}>{children}</code>
   },
-  h1: ({ ...props }) => <h1 className="mb-3 mt-6 text-2xl font-bold tracking-tight text-gray-950 first:mt-0" {...props} />,
-  h2: ({ ...props }) => <h2 className="mb-3 mt-6 text-xl font-bold tracking-tight text-gray-950 first:mt-0" {...props} />,
-  h3: ({ ...props }) => <h3 className="mb-2 mt-5 text-lg font-semibold text-gray-950 first:mt-0" {...props} />,
+  h1: ({ node: _node, ...props }) => <h1 className="mb-3 mt-6 text-2xl font-bold tracking-tight text-gray-950 first:mt-0" {...props} />,
+  h2: ({ node: _node, ...props }) => <h2 className="mb-3 mt-6 text-xl font-bold tracking-tight text-gray-950 first:mt-0" {...props} />,
+  h3: ({ node: _node, ...props }) => <h3 className="mb-2 mt-5 text-lg font-semibold text-gray-950 first:mt-0" {...props} />,
   hr: () => <hr className="my-5 border-gray-200" />,
-  img: ({ ...props }) => <img className="my-4 h-auto max-w-full rounded-md border border-gray-200" loading="lazy" {...props} />,
-  li: ({ ...props }) => <li className="my-1 pl-1" {...props} />,
-  ol: ({ ...props }) => <ol className="my-3 list-decimal space-y-1 pl-6" {...props} />,
-  p: ({ ...props }) => <p className="my-3 whitespace-pre-wrap leading-7 first:mt-0 last:mb-0" {...props} />,
-  pre: ({ children, ...props }) => <pre className="my-4 overflow-x-auto rounded-lg bg-gray-950 p-4 text-gray-50" {...props}>{children}</pre>,
-  table: ({ children, ...props }) => <div className="my-4 overflow-x-auto"><table className="w-full border-collapse text-left text-sm" {...props}>{children}</table></div>,
-  tbody: ({ ...props }) => <tbody className="divide-y divide-gray-200" {...props} />,
-  td: ({ ...props }) => <td className="border border-gray-200 px-3 py-2 align-top" {...props} />,
-  th: ({ ...props }) => <th className="border border-gray-200 bg-gray-50 px-3 py-2 text-left font-semibold" {...props} />,
-  ul: ({ ...props }) => <ul className="my-3 list-disc space-y-1 pl-6" {...props} />,
+  img: ({ node: _node, ...props }) => <img className="my-4 h-auto max-w-full rounded-md border border-gray-200" loading="lazy" {...props} />,
+  li: ({ node: _node, ...props }) => <li className="my-1 pl-1" {...props} />,
+  ol: ({ node: _node, ...props }) => <ol className="my-3 list-decimal space-y-1 pl-6" {...props} />,
+  p: ({ node: _node, ...props }) => <p className="my-3 whitespace-pre-wrap leading-7 first:mt-0 last:mb-0" {...props} />,
+  pre: ({ node, children, ...props }) => {
+    // remark-math emits display math as <pre><code class="language-math math-display">.
+    const first = node?.children.find((child) => child.type === 'element')
+    if (first?.type === 'element' && hasClass(first.properties.className, 'math-display')) {
+      return <div className="my-4 overflow-x-auto overflow-y-hidden py-1">{children}</div>
+    }
+    return (
+      <pre
+        className="my-4 overflow-x-auto rounded-lg bg-gray-950 p-4 text-gray-50 [&_code]:rounded-none [&_code]:bg-transparent [&_code]:p-0 [&_code]:text-sm [&_code]:text-inherit [&_code]:break-normal"
+        {...props}
+      >
+        {children}
+      </pre>
+    )
+  },
+  table: ({ node: _node, children, ...props }) => <div className="my-4 overflow-x-auto"><table className="w-full border-collapse text-left text-sm" {...props}>{children}</table></div>,
+  tbody: ({ node: _node, ...props }) => <tbody className="divide-y divide-gray-200" {...props} />,
+  td: ({ node: _node, ...props }) => <td className="border border-gray-200 px-3 py-2 align-top" {...props} />,
+  th: ({ node: _node, ...props }) => <th className="border border-gray-200 bg-gray-50 px-3 py-2 text-left font-semibold" {...props} />,
+  ul: ({ node: _node, ...props }) => <ul className="my-3 list-disc space-y-1 pl-6" {...props} />,
 }
 
 const markdownCode = /```[\s\S]*?```|~~~[\s\S]*?~~~|(`+)(?!`)[\s\S]*?\1(?!`)/g
@@ -102,16 +139,16 @@ const normalizeGfmTables = (content: string) => {
 // blank labels) can sit inside buttons, select triggers and flex rows.
 const inlineComponents: Components = {
   ...components,
-  p: ({ ...props }) => <span className="whitespace-pre-wrap" {...props} />,
+  p: ({ node: _node, ...props }) => <span className="whitespace-pre-wrap" {...props} />,
 }
 
 // min-w-0 + break-words keep long tokens inside the column; display math
-// and wide tables/code scroll horizontally instead of widening the page.
-const blockClassName = 'min-w-0 max-w-full break-words [&_.katex-display]:overflow-x-auto [&_.katex-display]:overflow-y-hidden [&_.katex-display]:py-1'
+// and wide tables/code scroll horizontally (see the `pre`/`table` renderers).
+const blockClassName = 'min-w-0 max-w-full break-words'
 
 export function MarkdownContent({ content, className, inline = false }: { content: string; className?: string; inline?: boolean }) {
   const markdown = (
-    <ReactMarkdown remarkPlugins={[remarkGfm, remarkMath]} rehypePlugins={[rehypeKatex]} components={inline ? inlineComponents : components}>
+    <ReactMarkdown remarkPlugins={[remarkGfm, remarkMath]} components={inline ? inlineComponents : components}>
       {normalizeGfmTables(normalizeMathDelimiters(content))}
     </ReactMarkdown>
   )

package/framework/components/question-response.tsx

@@ -166,19 +166,21 @@ export function PairingResponse({
             <li
               key={slot.id}
               className={cn(
-                'flex flex-col gap-2 rounded-lg border p-3 sm:flex-row sm:items-center',
+                // Wraps instead of squeezing: short items sit beside their select, while
+                // wide items (long formulas) take the full row and the select drops below.
+                'flex flex-wrap items-center gap-x-4 gap-y-2 rounded-lg border p-3',
                 state === 'idle' && 'border-gray-200 bg-white',
                 state === 'correct' && 'border-green-300 bg-green-50/50',
                 (state === 'incorrect' || state === 'missing') && 'border-red-300 bg-red-50/50',
               )}
             >
-              <div className="flex min-w-0 flex-1 items-start gap-2">
+              <div className="flex min-w-0 max-w-full flex-[1_1_auto] items-start gap-2">
                 <span className="mt-0.5 w-6 shrink-0 text-sm font-semibold tabular-nums text-gray-500">{index + 1}.</span>
-                <label htmlFor={selectId} className="min-w-0 flex-1 overflow-x-auto text-base leading-7 text-gray-900">
+                <label htmlFor={selectId} className="min-w-0 flex-1 overflow-x-auto overflow-y-hidden text-base leading-7 text-gray-900">
                   <MarkdownContent inline content={label} />
                 </label>
               </div>
-              <div className="flex shrink-0 flex-col gap-1 pl-8 sm:pl-0">
+              <div className="ml-auto flex shrink-0 flex-col gap-1 pl-8 sm:pl-0">
                 <div className="flex items-center gap-2">
                   <OptionSelect
                     id={selectId}

package/framework/components/ui/toast.tsx

@@ -0,0 +1,234 @@
+// shadcn/ui Toast (Base UI, base-nova style). Framework-owned: eject with `qb reveal framework/components/ui/toast.tsx`.
+
+import * as React from "react"
+import { Toast as ToastPrimitive } from "@base-ui/react/toast"
+import { CircleCheckIcon, InfoIcon, Loader2Icon, OctagonXIcon, TriangleAlertIcon, XIcon } from "lucide-react"
+import { cn } from "../../lib/utils.ts"
+
+import { Button } from "./button"
+
+const toast = ToastPrimitive.createToastManager()
+
+function ToastProvider({ ...props }: ToastPrimitive.Provider.Props) {
+  return <ToastPrimitive.Provider {...props} />
+}
+
+function ToastPortal({ ...props }: ToastPrimitive.Portal.Props) {
+  return <ToastPrimitive.Portal data-slot="toast-portal" {...props} />
+}
+
+function ToastViewport({ className, ...props }: ToastPrimitive.Viewport.Props) {
+  return (
+    <ToastPrimitive.Viewport
+      data-slot="toast-viewport"
+      className={cn(
+        "pointer-events-none fixed inset-x-4 bottom-4 z-50 mx-auto w-auto max-w-sm outline-none sm:right-4 sm:left-auto sm:mx-0 sm:w-full",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function Toast({ className, ...props }: ToastPrimitive.Root.Props) {
+  return (
+    <ToastPrimitive.Root
+      data-slot="toast"
+      className={cn(
+        "group/toast pointer-events-auto absolute right-0 bottom-0 z-[calc(1000-var(--toast-index))] w-full origin-bottom rounded-2xl border border-gray-200 bg-popover text-popover-foreground shadow-lg will-change-transform outline-none select-none focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50",
+        "[--gap:0.75rem] [--height:var(--toast-frontmost-height,var(--toast-height))] [--offset-y:calc(var(--toast-offset-y)*-1+calc(var(--toast-index)*var(--gap)*-1)+var(--toast-swipe-movement-y))] [--peek:0.75rem] [--scale:calc(max(0,1-(var(--toast-index)*0.1)))] [--shrink:calc(1-var(--scale))]",
+        "h-(--height) [transform:translateX(var(--toast-swipe-movement-x))_translateY(calc(var(--toast-swipe-movement-y)-(var(--toast-index)*var(--peek))-(var(--shrink)*var(--height))))_scale(var(--scale))] [transition:transform_500ms_cubic-bezier(0.22,1,0.36,1),opacity_500ms,height_150ms]",
+        "after:absolute after:top-full after:left-0 after:h-[calc(var(--gap)+1px)] after:w-full after:content-['']",
+        "data-expanded:h-(--toast-height) data-expanded:[transform:translateX(var(--toast-swipe-movement-x))_translateY(var(--offset-y))]",
+        "data-limited:opacity-0 data-starting-style:[transform:translateY(150%)]",
+        "[&[data-ending-style]:not([data-limited]):not([data-swipe-direction])]:[transform:translateY(150%)]",
+        "data-ending-style:data-[swipe-direction=down]:[transform:translateY(calc(var(--toast-swipe-movement-y)+150%))]",
+        "data-ending-style:data-[swipe-direction=left]:[transform:translateX(calc(var(--toast-swipe-movement-x)-150%))_translateY(var(--offset-y))]",
+        "data-ending-style:data-[swipe-direction=right]:[transform:translateX(calc(var(--toast-swipe-movement-x)+150%))_translateY(var(--offset-y))]",
+        "data-ending-style:data-[swipe-direction=up]:[transform:translateY(calc(var(--toast-swipe-movement-y)-150%))]",
+        "data-expanded:data-ending-style:data-[swipe-direction=down]:[transform:translateY(calc(var(--toast-swipe-movement-y)+150%))]",
+        "data-expanded:data-ending-style:data-[swipe-direction=left]:[transform:translateX(calc(var(--toast-swipe-movement-x)-150%))_translateY(var(--offset-y))]",
+        "data-expanded:data-ending-style:data-[swipe-direction=right]:[transform:translateX(calc(var(--toast-swipe-movement-x)+150%))_translateY(var(--offset-y))]",
+        "data-expanded:data-ending-style:data-[swipe-direction=up]:[transform:translateY(calc(var(--toast-swipe-movement-y)-150%))]",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function ToastContent({ className, ...props }: ToastPrimitive.Content.Props) {
+  return (
+    <ToastPrimitive.Content
+      data-slot="toast-content"
+      className={cn(
+        "flex h-full items-center gap-3 overflow-hidden p-4 transition-opacity duration-250 ease-[cubic-bezier(0.22,1,0.36,1)] data-behind:opacity-0 data-expanded:opacity-100",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function ToastTitle({ className, ...props }: ToastPrimitive.Title.Props) {
+  return (
+    <ToastPrimitive.Title
+      data-slot="toast-title"
+      className={cn("text-sm font-medium", className)}
+      {...props}
+    />
+  )
+}
+
+function ToastDescription({
+  className,
+  ...props
+}: ToastPrimitive.Description.Props) {
+  return (
+    <ToastPrimitive.Description
+      data-slot="toast-description"
+      className={cn("text-sm text-muted-foreground", className)}
+      {...props}
+    />
+  )
+}
+
+function ToastAction({
+  className,
+  render = <Button variant="outline" size="sm" />,
+  ...props
+}: ToastPrimitive.Action.Props) {
+  return (
+    <ToastPrimitive.Action
+      data-slot="toast-action"
+      render={render}
+      className={cn("shrink-0", className)}
+      {...props}
+    />
+  )
+}
+
+function ToastClose({
+  className,
+  children,
+  render = <Button variant="ghost" size="icon-sm" />,
+  ...props
+}: ToastPrimitive.Close.Props) {
+  return (
+    <ToastPrimitive.Close
+      data-slot="toast-close"
+      aria-label="Close toast"
+      render={render}
+      className={cn(
+        "relative shrink-0 text-muted-foreground after:absolute after:-inset-2 after:content-[''] hover:text-foreground",
+        className
+      )}
+      {...props}
+    >
+      {children ?? (
+        <XIcon aria-hidden="true" />
+      )}
+    </ToastPrimitive.Close>
+  )
+}
+
+function ToastIcon({ type }: { type: string | undefined }) {
+  let icon: React.ReactNode = null
+
+  if (type === "success") {
+    icon = (
+      <CircleCheckIcon aria-hidden="true" />
+    )
+  }
+
+  if (type === "info") {
+    icon = (
+      <InfoIcon aria-hidden="true" />
+    )
+  }
+
+  if (type === "warning") {
+    icon = (
+      <TriangleAlertIcon aria-hidden="true" />
+    )
+  }
+
+  if (type === "error") {
+    icon = (
+      <OctagonXIcon className="text-destructive" aria-hidden="true" />
+    )
+  }
+
+  if (type === "loading") {
+    icon = (
+      <Loader2Icon className="animate-spin" aria-hidden="true" />
+    )
+  }
+
+  if (!icon) {
+    return null
+  }
+
+  return (
+    <span
+      data-slot="toast-icon"
+      className="shrink-0 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4"
+    >
+      {icon}
+    </span>
+  )
+}
+
+function ToastList() {
+  const { toasts } = ToastPrimitive.useToastManager()
+
+  return toasts.map((toastItem) => (
+    <Toast key={toastItem.id} toast={toastItem}>
+      <ToastContent>
+        <ToastIcon type={toastItem.type} />
+        <div className="flex min-w-0 flex-1 flex-col gap-1">
+          <ToastTitle />
+          <ToastDescription />
+        </div>
+        <ToastAction />
+        <ToastClose />
+      </ToastContent>
+    </Toast>
+  ))
+}
+
+function Toaster({
+  children,
+  toastManager = toast,
+  ...props
+}: ToastPrimitive.Provider.Props) {
+  return (
+    <ToastProvider toastManager={toastManager} {...props}>
+      {children}
+      <ToastPortal>
+        <ToastViewport>
+          <ToastList />
+        </ToastViewport>
+      </ToastPortal>
+    </ToastProvider>
+  )
+}
+
+const createToastManager = ToastPrimitive.createToastManager
+const useToastManager = ToastPrimitive.useToastManager
+
+export {
+  Toaster,
+  Toast,
+  ToastAction,
+  ToastClose,
+  ToastContent,
+  ToastDescription,
+  ToastPortal,
+  ToastProvider,
+  ToastTitle,
+  ToastViewport,
+  createToastManager,
+  toast,
+  useToastManager,
+}

package/framework/index.ts

@@ -5,6 +5,7 @@ export { QuestionBank } from './components/question-bank.tsx';
 export { QuizPage } from './components/quiz-page.tsx';
 export { QuizList } from './components/quiz-list.tsx';
 export { AppShell } from './components/app-shell.tsx';
+export { ExamTimerBadge, ExamTimerPage } from './components/exam-timer.tsx';
 export { FilterBuilder } from './components/filter-builder.tsx';
 export { MarkdownContent } from './components/markdown-content.tsx';
 export { NumericalResponse, PairingResponse, formatNumericAnswer } from './components/question-response.tsx';
@@ -32,5 +33,8 @@ export {
   syncQuiz,
 } from './lib/quiz-storage.ts';
 export { getQuestionStatuses, setQuestionStatus } from './lib/question-status-storage.ts';
+export { examState, setExamTimer, useExamTimer } from './lib/exam-timer.ts';
+export type { ExamState, ExamTimer } from './lib/exam-timer.ts';
+export { Toaster, toast } from './components/ui/toast.tsx';
 export type { StorageTarget } from './lib/sync-client.ts';
 export { cn } from './lib/utils.ts';

package/framework/lib/exam-timer.ts

@@ -0,0 +1,115 @@
+// Mock-exam clock: pressing Start on /timer pretends it's the exam's start time
+// (e.g. 08:30) right now, then the clock runs forward from there. Kept in
+// localStorage so it survives reloads and is shared by every open tab.
+// Framework-owned: eject with `qb reveal framework/lib/exam-timer.ts`.
+
+import { useEffect, useState, useSyncExternalStore } from 'react';
+
+export type ExamTimer = {
+  /** Exam start on the mock clock, in minutes after midnight (08:30 → 510). */
+  startMinutes: number;
+  /** When Start was pressed (epoch ms). */
+  startedAt: number;
+  readingMinutes: number;
+  writingMinutes: number;
+};
+
+export type ExamState = {
+  phase: 'reading' | 'writing' | 'over';
+  /** Mock clock time, "HH:MM". */
+  clock: string;
+  /** Ms since Start was pressed. */
+  elapsed: number;
+};
+
+export const MINUTE = 60_000;
+const CHANGE_EVENT = 'qb-exam-timer-change';
+const keyFor = (namespace: string) => `${namespace}-question-bank-exam-timer`;
+
+const isTimer = (value: unknown): value is ExamTimer => {
+  if (!value || typeof value !== 'object') return false;
+  const { startMinutes, startedAt, readingMinutes, writingMinutes } = value as Record<string, unknown>;
+  return [startMinutes, startedAt, readingMinutes, writingMinutes].every(
+    (n) => typeof n === 'number' && Number.isFinite(n) && n >= 0,
+  );
+};
+
+const parse = (raw: string | null): ExamTimer | null => {
+  try {
+    const value: unknown = JSON.parse(raw ?? 'null');
+    return isTimer(value) ? value : null;
+  } catch {
+    return null;
+  }
+};
+
+export function setExamTimer(namespace: string, timer: ExamTimer | null): void {
+  if (typeof window === 'undefined') return;
+  if (timer) window.localStorage.setItem(keyFor(namespace), JSON.stringify(timer));
+  else window.localStorage.removeItem(keyFor(namespace));
+  // `storage` only fires in other tabs; tell this one too.
+  window.dispatchEvent(new Event(CHANGE_EVENT));
+}
+
+function subscribe(onChange: () => void) {
+  window.addEventListener('storage', onChange);
+  window.addEventListener(CHANGE_EVENT, onChange);
+  return () => {
+    window.removeEventListener('storage', onChange);
+    window.removeEventListener(CHANGE_EVENT, onChange);
+  };
+}
+
+/** The saved timer, or null. Always null during SSR. */
+export function useExamTimer(namespace: string): ExamTimer | null {
+  const raw = useSyncExternalStore(
+    subscribe,
+    () => window.localStorage.getItem(keyFor(namespace)),
+    () => null,
+  );
+  return parse(raw);
+}
+
+export const formatClock = (minutesAfterMidnight: number) => {
+  const minutes = Math.floor(minutesAfterMidnight) % (24 * 60);
+  return `${String(Math.floor(minutes / 60)).padStart(2, '0')}:${String(minutes % 60).padStart(2, '0')}`;
+};
+
+export function examState(timer: ExamTimer, now: number): ExamState {
+  const elapsed = Math.max(0, now - timer.startedAt);
+  const minutes = elapsed / MINUTE;
+  const phase =
+    minutes < timer.readingMinutes ? 'reading' : minutes < timer.readingMinutes + timer.writingMinutes ? 'writing' : 'over';
+  return { phase, clock: formatClock(timer.startMinutes + minutes), elapsed };
+}
+
+/**
+ * Current time, re-read each time the mock clock ticks over a minute (and
+ * when the tab becomes visible again). Never re-renders more than once a minute.
+ */
+export function useExamNow(timer: ExamTimer | null): number {
+  const [now, setNow] = useState(() => Date.now());
+  const startedAt = timer?.startedAt;
+  useEffect(() => {
+    if (startedAt === undefined) return;
+    let timeout: ReturnType<typeof setTimeout>;
+    const tick = () => {
+      const current = Date.now();
+      setNow(current);
+      const intoMinute = (((current - startedAt) % MINUTE) + MINUTE) % MINUTE;
+      timeout = setTimeout(tick, MINUTE - intoMinute + 50);
+    };
+    const onVisible = () => {
+      if (document.visibilityState !== 'visible') return;
+      clearTimeout(timeout);
+      tick();
+    };
+    tick();
+    document.addEventListener('visibilitychange', onVisible);
+    return () => {
+      clearTimeout(timeout);
+      document.removeEventListener('visibilitychange', onVisible);
+    };
+  }, [startedAt]);
+  return now;
+}

package/framework/styles/theme.css

@@ -7,6 +7,10 @@
  *   @import 'question-bank-framework/framework/styles/theme.css';
  */
 
+/* KaTeX CSS from the framework's own katex, matching the version that renders
+ * math in MarkdownContent. Don't import katex CSS separately in your app. */
+@import 'katex/dist/katex.min.css';
+
 @theme inline {
   --font-sans: 'DM Sans', ui-sans-serif, system-ui, sans-serif;
   --font-display: 'Fraunces', Georgia, serif;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "question-bank-framework",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Framework-style question bank: TanStack Start + TanStack Table grid, quizzes, and filter DSL. Bring your own bank.config.ts + content/. Eject any framework/ file with `qb reveal` (Vike-style).",
   "type": "module",
   "license": "MIT",
@@ -32,6 +32,7 @@
     "react-dom": "^19.2.0"
   },
   "dependencies": {
+    "@base-ui/react": "^1.9.0",
     "@tanstack/react-table": "^8.21.3",
     "@tanstack/react-virtual": "^3.14.19",
     "class-variance-authority": "^0.7.1",
@@ -40,7 +41,6 @@
     "lucide-react": "^1.57.0",
     "radix-ui": "^1.8.1",
     "react-markdown": "^10.1.0",
-    "rehype-katex": "^7.0.1",
     "remark-gfm": "^4.0.1",
     "remark-math": "^6.0.0",
     "tailwind-merge": "^3.7.0",

package/template/src/routes/styles.css

@@ -1,5 +1,4 @@
 @import url('https://fonts.googleapis.com/css2?family=DM+Mono:wght@400;500&family=DM+Sans:wght@400;500;600;700;800&family=Fraunces:opsz,wght@9..144,600;9..144,700&display=swap');
-@import 'katex/dist/katex.min.css';
 @import 'tailwindcss';
 @import 'tw-animate-css';
 @import 'question-bank-framework/framework/styles/theme.css';

package/template/src/routes/timer.tsx

@@ -0,0 +1,4 @@
+import { createFileRoute } from '@tanstack/react-router';
+import { ExamTimerPage } from 'question-bank-framework/framework';
+
+export const Route = createFileRoute('/timer')({ component: () => <ExamTimerPage /> });