question-bank-framework 0.6.0 → 0.7.1

package/README.md

@@ -2,7 +2,8 @@
 
 Framework-style question bank (generalised from the COMP20008 bank). Downstream
 subjects bring their own `bank.config.ts` + `content/`; the framework ships the
-grid, filter DSL, quizzes, and Convex bindings as an npm package.
+grid, filter DSL, quizzes, and a Cloudflare Durable Object sync store as an npm
+package.
 
 Inspired by Vike's eject model: the stable core (`core/`) is never ejected;
 everything under `framework/` can be ejected into your repo and owned.
@@ -35,10 +36,47 @@ 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`.
+
 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.
 
+## Sync (Cloudflare Durable Objects)
+
+Without `sync`, quizzes and question statuses live only in the browser's
+localStorage. With `sync: { url: '/api/qb' }` in `defineBank`, they are also
+stored in a SQLite-backed Durable Object (one per bank namespace), and
+localStorage stays as an offline cache: changes are saved locally first,
+pushed to the server, and reconciled on load (newest `updatedAt` wins; deleted
+quizzes are tombstoned so stale caches can't bring them back). Quizzes that
+existed only in localStorage are uploaded on the first load with sync on.
+
+`qb init` scaffolds the three pieces:
+
+- `wrangler.jsonc` — Worker config with the `QB_STORE` Durable Object binding
+  and its `new_sqlite_classes` migration.
+- `src/server.ts` — Worker entry: `handleQuestionBankRequest(request, env)`
+  answers `/api/qb/*` and returns `null` for everything else, which falls
+  through to TanStack Start. It also re-exports `QuestionBankStore`.
+- `vite.config.ts` — adds `cloudflare({ viteEnvironment: { name: 'ssr' } })`.
+
+```sh
+pnpm add -D @cloudflare/vite-plugin wrangler
+pnpm dev                       # workerd via Miniflare; data persists in .wrangler/state
+pnpm build && wrangler deploy  # same code on Cloudflare
+```
+
+Add `.wrangler/` to `.gitignore`. The API has no auth of its own: before a
+public deploy, pass `authorize` to `handleQuestionBankRequest` (e.g. verify a
+Cloudflare Access JWT) or put the Worker behind Cloudflare Access.
+
 ## Reveal (eject) files
 
 ```sh
@@ -70,7 +108,7 @@ fields/columns/searchable flags first; eject when you need custom UI.
   package), then customize.
 
 We follow Vike: `core/` (types, `defineBank`, `BankProvider`, `useBank`) is the
-stable core; `framework/` (components/lib/routes/convex) is the ejectable
+stable core; `framework/` (components/lib/cloudflare) is the ejectable
 extension layer; `qb reveal` is the copy command.
 
 ## Layout
@@ -79,7 +117,8 @@ extension layer; `qb reveal` is the copy command.
   `defineBank`), `config.tsx` (`BankProvider`, `useBank`).
 - `framework/` — ejectable: `components/` (grid, quiz, filter builder,
   shadcn `ui/`), `lib/` (generic filter DSL, namespaced quiz/status stores,
-  `convex-api.ts`), `convex/` (quizzes + questionStatuses tables).
+  `sync-client.ts`), `cloudflare/` (sync Durable Object + request handler,
+  exported as `question-bank-framework/cloudflare`).
 - `template/` — starter: `bank.config.ts` (COMP20008-like schema),
   `content/` example, `src/routes/` thin wrappers.
 - `bin/qb.ts` (source; compiled to `bin/qb.js` with `pnpm build:bin`) — `list` / `reveal` / `init`.
@@ -89,7 +128,8 @@ extension layer; `qb reveal` is the copy command.
 ```ts
 defineBank({
   site: { title: '…', brand: 'fieldnotes' },
-  namespace: 'comp20008', // localStorage keys + Convex lookups
+  namespace: 'comp20008', // localStorage keys + sync store
+  sync: { url: '/api/qb' }, // optional: back quizzes/statuses up to the Worker
   fields: [
     { id: 'year', label: 'Year', type: 'select', getValue: (q) => String(q['year'] ?? '') },
     { id: 'marks', label: 'Marks', type: 'number', getValue: (q) => q['marks'] ?? null },
@@ -132,7 +172,8 @@ across reloads but differs between quizzes. The bank grid keeps authored
 order, so explanations should name options by content, not by letter. Opt out
 with `shuffle: false` on the question, or on a single dropdown blank, when
 order matters ("All of the above", ordered scales, options that reference
-each other).
+each other). To keep just one option in place ("None of the above" last),
+mark it `pinned: true` instead; the other options still shuffle around it.
 
 ## Dev
 

package/bin/qb.js

@@ -111,7 +111,8 @@ else if (cmd === 'init') {
             cpSync(from, to);
     }
     console.log(`Scaffolded template into ${cwd}`);
-    console.log('Next: pnpm install, then point your routes at bank.config.ts (see template/src/routes/).');
+    console.log('Next: pnpm add -D @cloudflare/vite-plugin wrangler, pnpm install, then point your routes at bank.config.ts (see template/src/routes/).');
+    console.log('wrangler.jsonc + src/server.ts serve the sync store; existing files were left untouched.');
 }
 else {
     console.error(`Unknown command: ${cmd}\nCommands: list, reveal, init`);

package/bin/qb.ts

@@ -121,7 +121,8 @@ if (cmd === 'list' || !cmd) {
     if (!existsSync(to)) cpSync(from, to);
   }
   console.log(`Scaffolded template into ${cwd}`);
-  console.log('Next: pnpm install, then point your routes at bank.config.ts (see template/src/routes/).');
+  console.log('Next: pnpm add -D @cloudflare/vite-plugin wrangler, pnpm install, then point your routes at bank.config.ts (see template/src/routes/).');
+  console.log('wrangler.jsonc + src/server.ts serve the sync store; existing files were left untouched.');
 } else {
   console.error(`Unknown command: ${cmd}\nCommands: list, reveal, init`);
   process.exit(1);

package/core/types.ts

@@ -35,6 +35,11 @@ export interface QuestionOption {
   id: string;
   /** Option body. Markdown supported. */
   text: string;
+  /**
+   * Keep this option at its authored position when options are shuffled,
+   * e.g. "None of the above" last. The other options still shuffle around it.
+   */
+  pinned?: boolean;
 }
 
 /** A left-hand row of a matching question, answered from the question's shared `options`. */
@@ -113,6 +118,8 @@ export interface QuizSession {
   currentQuestion: number;
   completed: boolean;
   createdAt: number;
+  /** Last local change (ms). Sync keeps the newer copy. Missing on legacy sessions. */
+  updatedAt?: number;
 }
 
 // ---------------------------------------------------------------------------
@@ -179,7 +186,7 @@ export interface BankSiteConfig {
 
 export interface DefineBankInput<Q extends BaseQuestion = BaseQuestion> {
   site: BankSiteConfig;
-  /** Namespaces localStorage keys + Convex lookups. e.g. "comp20008". */
+  /** Namespaces localStorage keys and the sync store. e.g. "comp20008". */
   namespace: string;
   /** Subject-specific schema. Built-ins (id/title/tags/status) are automatic. */
   fields: BankFieldDef<Q>[];
@@ -197,6 +204,13 @@ export interface DefineBankInput<Q extends BaseQuestion = BaseQuestion> {
   hideTagsColumn?: boolean;
   /** Extra per-question figures, resolved by prompt `![](/figures/…)` etc. */
   publicPath?: string;
+  /**
+   * Server sync for quizzes and question statuses. Point `url` at the
+   * framework's Cloudflare handler (see `question-bank-framework/cloudflare`),
+   * e.g. `{ url: '/api/qb' }`. Without it, data lives only in this browser's
+   * localStorage. localStorage is always kept as an offline cache.
+   */
+  sync?: { url: string };
 }
 
 export interface Bank extends DefineBankInput<BaseQuestion> {
@@ -242,6 +256,9 @@ function validateOptionList(questionId: string, where: string, options: readonly
       throw new Error(`Question "${questionId}" ${where} has a duplicate or empty option id "${option.id}".`);
     }
     seen.add(option.id);
+    if (option.pinned !== undefined && typeof option.pinned !== 'boolean') {
+      throw new Error(`Question "${questionId}" ${where} option "${option.id}" has a non-boolean pinned.`);
+    }
   }
   return seen;
 }
@@ -412,14 +429,16 @@ function seededRandom(seed: number): () => number {
   };
 }
 
-function seededShuffle<T>(list: readonly T[], seed: string): T[] {
-  const out = [...list];
+/** Shuffle the unpinned options; pinned options keep their authored index. */
+function seededShuffle(list: readonly QuestionOption[], seed: string): QuestionOption[] {
+  const free = list.filter((option) => option.pinned !== true);
   const random = seededRandom(hashSeed(seed));
-  for (let i = out.length - 1; i > 0; i -= 1) {
+  for (let i = free.length - 1; i > 0; i -= 1) {
     const j = Math.floor(random() * (i + 1));
-    [out[i], out[j]] = [out[j]!, out[i]!];
+    [free[i], free[j]] = [free[j]!, free[i]!];
   }
-  return out;
+  let next = 0;
+  return list.map((option) => (option.pinned === true ? option : free[next++]!));
 }
 
 /**
@@ -427,7 +446,8 @@ function seededShuffle<T>(list: readonly T[], seed: string): T[] {
  * for `seed` (e.g. a quiz session id) so the order is stable across reloads
  * but differs between quizzes. Answers are stored as option ids, so grading is
  * unaffected. Questions with `shuffle: false` (and blanks with
- * `shuffle: false`) keep their authored order.
+ * `shuffle: false`) keep their authored order; `pinned` options keep their
+ * authored position while the rest shuffle.
  */
 export function shuffleQuestionOptions<Q extends BaseQuestion>(question: Q, seed: string): Q {
   const enabled = question.shuffle !== false;

package/framework/cloudflare/index.ts

@@ -0,0 +1,240 @@
+// Cloudflare sync backend: one SQLite-backed Durable Object per bank
+// namespace stores quizzes and question statuses. Import from
+// "question-bank-framework/cloudflare" in your Worker entry (src/server.ts):
+//
+//   import handler from '@tanstack/react-start/server-entry';
+//   import { handleQuestionBankRequest } from 'question-bank-framework/cloudflare';
+//   export { QuestionBankStore } from 'question-bank-framework/cloudflare';
+//   export default {
+//     async fetch(request, env) {
+//       return (await handleQuestionBankRequest(request, env)) ?? handler.fetch(request);
+//     },
+//   };
+//
+// and bind it in wrangler.jsonc (see template/wrangler.jsonc). Local dev with
+// @cloudflare/vite-plugin runs the same code in workerd and persists to
+// .wrangler/state. Framework-owned: eject with `qb reveal framework/cloudflare/index.ts`.
+//
+// No Workers type packages needed: the few runtime types used are declared
+// structurally below.
+
+interface SqlStorage {
+  exec<T = Record<string, string | number | null>>(query: string, ...bindings: unknown[]): { toArray(): T[] };
+}
+
+interface DurableObjectState {
+  storage: { sql: SqlStorage };
+}
+
+interface DurableObjectStub {
+  fetch(request: Request): Promise<Response>;
+}
+
+interface DurableObjectNamespace {
+  idFromName(name: string): unknown;
+  get(id: unknown): DurableObjectStub;
+}
+
+const MAX_BODY_BYTES = 1_000_000;
+const NAMESPACE_PATTERN = /^[A-Za-z0-9_.-]{1,64}$/;
+const statuses = new Set(['unanswered', 'revisit', 'complete']);
+
+const json = (data: unknown, status = 200) =>
+  new Response(JSON.stringify(data), { status, headers: { 'content-type': 'application/json', 'cache-control': 'no-store' } });
+
+const error = (status: number, message: string) => json({ error: message }, status);
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  !!value && typeof value === 'object' && !Array.isArray(value);
+
+const isQuizAnswer = (value: unknown) =>
+  typeof value === 'string' ||
+  (Array.isArray(value) && value.every((item) => typeof item === 'string')) ||
+  (isObject(value) && Object.values(value).every((item) => typeof item === 'string'));
+
+interface StoredQuiz {
+  id: string;
+  title: string;
+  questionIds: string[];
+  answers: Record<string, unknown>;
+  currentQuestion: number;
+  completed: boolean;
+  createdAt: number;
+  updatedAt: number;
+}
+
+function parseQuiz(id: string, body: unknown): StoredQuiz | null {
+  if (!isObject(body)) return null;
+  const { title, questionIds, answers, currentQuestion, completed, createdAt, updatedAt } = body;
+  if (body.id !== id || typeof title !== 'string' || title.length > 500) return null;
+  if (!Array.isArray(questionIds) || !questionIds.every((q) => typeof q === 'string')) return null;
+  if (!isObject(answers) || !Object.values(answers).every(isQuizAnswer)) return null;
+  if (!Number.isInteger(currentQuestion) || typeof completed !== 'boolean') return null;
+  if (!Number.isFinite(createdAt) || !Number.isFinite(updatedAt)) return null;
+  return {
+    id,
+    title,
+    questionIds: questionIds as string[],
+    answers,
+    currentQuestion: currentQuestion as number,
+    completed,
+    createdAt: createdAt as number,
+    updatedAt: updatedAt as number,
+  };
+}
+
+async function readBody(request: Request): Promise<unknown> {
+  const text = await request.text();
+  if (text.length > MAX_BODY_BYTES) throw new Error('too large');
+  return JSON.parse(text);
+}
+
+/** Durable Object holding one bank namespace. Export it from your Worker entry. */
+export class QuestionBankStore {
+  private sql: SqlStorage;
+
+  constructor(state: DurableObjectState, _env: unknown) {
+    this.sql = state.storage.sql;
+    this.sql.exec(`CREATE TABLE IF NOT EXISTS quizzes (
+      id TEXT PRIMARY KEY,
+      data TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      deleted INTEGER NOT NULL DEFAULT 0
+    )`);
+    this.sql.exec(`CREATE TABLE IF NOT EXISTS statuses (
+      question_id TEXT PRIMARY KEY,
+      status TEXT NOT NULL,
+      updated_at INTEGER NOT NULL
+    )`);
+  }
+
+  async fetch(request: Request): Promise<Response> {
+    const segments = new URL(request.url).pathname.split('/').filter(Boolean).map(decodeURIComponent);
+    const [collection, key] = segments;
+    try {
+      if (collection === 'quizzes' && segments.length === 1 && request.method === 'GET') return this.listQuizzes();
+      if (collection === 'quizzes' && key && segments.length === 2) {
+        if (request.method === 'PUT') return this.putQuiz(key, await readBody(request));
+        if (request.method === 'DELETE') return this.deleteQuiz(key);
+      }
+      if (collection === 'statuses' && segments.length === 1 && request.method === 'GET') return this.listStatuses();
+      if (collection === 'statuses' && key && segments.length === 2 && request.method === 'PUT') {
+        return this.putStatus(key, await readBody(request));
+      }
+      return error(404, 'Not found');
+    } catch {
+      return error(400, 'Bad request');
+    }
+  }
+
+  private listQuizzes(): Response {
+    const rows = this.sql.exec<{ id: string; data: string; deleted: number }>(
+      'SELECT id, data, deleted FROM quizzes ORDER BY created_at DESC',
+    ).toArray();
+    return json({
+      quizzes: rows.filter((row) => !row.deleted).map((row) => JSON.parse(row.data) as StoredQuiz),
+      deleted: rows.filter((row) => row.deleted).map((row) => row.id),
+    });
+  }
+
+  /** Upsert, keeping whichever copy has the newer updatedAt. Returns the stored copy; 410 if deleted. */
+  private putQuiz(id: string, body: unknown): Response {
+    const quiz = parseQuiz(id, body);
+    if (!quiz) return error(400, 'Invalid quiz');
+    const [existing] = this.sql.exec<{ data: string; updated_at: number; deleted: number }>(
+      'SELECT data, updated_at, deleted FROM quizzes WHERE id = ?',
+      id,
+    ).toArray();
+    if (existing?.deleted) return json({ deleted: true }, 410);
+    if (existing && existing.updated_at >= quiz.updatedAt) return json(JSON.parse(existing.data));
+    this.sql.exec(
+      `INSERT INTO quizzes (id, data, created_at, updated_at, deleted) VALUES (?, ?, ?, ?, 0)
+       ON CONFLICT(id) DO UPDATE SET data = excluded.data, updated_at = excluded.updated_at`,
+      id,
+      JSON.stringify(quiz),
+      quiz.createdAt,
+      quiz.updatedAt,
+    );
+    return json(quiz);
+  }
+
+  /** Tombstone, so stale browser caches can't resurrect the quiz. */
+  private deleteQuiz(id: string): Response {
+    const now = Date.now();
+    this.sql.exec(
+      `INSERT INTO quizzes (id, data, created_at, updated_at, deleted) VALUES (?, '{}', ?, ?, 1)
+       ON CONFLICT(id) DO UPDATE SET data = '{}', updated_at = excluded.updated_at, deleted = 1`,
+      id,
+      now,
+      now,
+    );
+    return json({ deleted: true });
+  }
+
+  private listStatuses(): Response {
+    const rows = this.sql.exec<{ question_id: string; status: string; updated_at: number }>(
+      'SELECT question_id, status, updated_at FROM statuses',
+    ).toArray();
+    return json(Object.fromEntries(rows.map((row) => [row.question_id, { status: row.status, updatedAt: row.updated_at }])));
+  }
+
+  private putStatus(questionId: string, body: unknown): Response {
+    if (!isObject(body) || typeof body.status !== 'string' || !statuses.has(body.status) || !Number.isFinite(body.updatedAt)) {
+      return error(400, 'Invalid status');
+    }
+    const updatedAt = body.updatedAt as number;
+    this.sql.exec(
+      `INSERT INTO statuses (question_id, status, updated_at) VALUES (?, ?, ?)
+       ON CONFLICT(question_id) DO UPDATE SET status = excluded.status, updated_at = excluded.updated_at
+       WHERE excluded.updated_at > statuses.updated_at`,
+      questionId,
+      body.status,
+      updatedAt,
+    );
+    const [row] = this.sql.exec<{ status: string; updated_at: number }>(
+      'SELECT status, updated_at FROM statuses WHERE question_id = ?',
+      questionId,
+    ).toArray();
+    return json({ status: row!.status, updatedAt: row!.updated_at });
+  }
+}
+
+export interface QuestionBankHandlerOptions {
+  /** URL prefix the API is served under; must match the bank's `sync.url`. Default "/api/qb". */
+  prefix?: string;
+  /** Name of the Durable Object binding in wrangler.jsonc. Default "QB_STORE". */
+  binding?: string;
+  /**
+   * Gate every request, e.g. verify a Cloudflare Access JWT. Return false to
+   * answer 401. Without it the API is open to anyone who can reach the Worker.
+   */
+  authorize?: (request: Request) => boolean | Promise<boolean>;
+}
+
+/**
+ * Serve the sync API. Returns null for requests outside `prefix`, so the
+ * caller can fall through to the app handler.
+ */
+export async function handleQuestionBankRequest(
+  request: Request,
+  env: object,
+  options: QuestionBankHandlerOptions = {},
+): Promise<Response | null> {
+  const prefix = (options.prefix ?? '/api/qb').replace(/\/+$/, '');
+  const url = new URL(request.url);
+  if (url.pathname !== prefix && !url.pathname.startsWith(`${prefix}/`)) return null;
+  if (options.authorize && !(await options.authorize(request))) return error(401, 'Unauthorized');
+
+  const [namespace, ...rest] = url.pathname.slice(prefix.length).split('/').filter(Boolean);
+  const name = namespace ? decodeURIComponent(namespace) : '';
+  if (!NAMESPACE_PATTERN.test(name)) return error(404, 'Not found');
+
+  const binding = (env as Record<string, unknown>)[options.binding ?? 'QB_STORE'] as DurableObjectNamespace | undefined;
+  if (!binding || typeof binding.idFromName !== 'function') {
+    return error(500, `Durable Object binding "${options.binding ?? 'QB_STORE'}" is not configured.`);
+  }
+  const stub = binding.get(binding.idFromName(name));
+  const inner = new URL(`https://qb.internal/${rest.join('/')}`);
+  return stub.fetch(new Request(inner, request));
+}

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>
   )