@brandon_m_behring/book-scaffold-astro 4.19.0 → 4.21.0

package/CLAUDE.md

@@ -104,7 +104,7 @@ Two callout families coexist. Authors import what they need.
 
 **Provenance** (v4.8.0, any profile, **auto-injected by the chapter route — not author-imported**): per-chapter "How this was made" audit-trail block, rendered from the optional `provenance` frontmatter (`ai_tools`, `prompts_archive`, `decisions_log`, `audit_history`, `citation_backstop`). **Opt-out**: a chapter with no `provenance` shows a fallback ("Audit history not yet recorded"). Distinct from `AICollaborationDisclosure` (book-level, manual model+role disclosure). Repo-relative path fields render as `<code>`; only `http(s)` values link.
 
-**Study-guide (v4.17.0+, #112; opt-in).** A schema-validated `questions` content collection drives an exam-prep "question bank". Author questions under `src/content/questions/**.{md,mdx}` — frontmatter `id` (unique, required) / `type` (`mcq`|`free`|`cloze`) / `chapter` / `domain` (+ optional `part`/`bloom_level`/`objective_id`/`difficulty`), MDX body = the stem. MCQ carries `options: [{ id, text, correct }]` (exactly one `correct: true`); free-response carries an `answer` (model answer). An MCQ must **not** set `answer` — its answer is the option marked `correct`, and explanations for any type go in a `<Rationale>` body block. Declare the per-book domain taxonomy in `defineBookConfig({ examDomains: ['…'] })` — a question whose `domain` isn't registered **throws at build** (fail-loud, like `<BookLink>`'s `siblingBooks`). Enable the static `/practice-exam` route with `defineBookConfig({ routes: { practiceExam: true } })` (renders the bank grouped by domain with answers behind a `<details>` reveal; `cloze` is reserved/render-deferred). `<ObjectiveMap />` renders the exam-domain → chapter coverage matrix auto-derived from the collection (no separate data file). `<Rationale>` is a collapsible answer/explanation marker for a question's MDX body. `<Diagnostic>` (v4.19.0, #110) renders a per-chapter pre-reading "Do I Know This Already?" self-check (pedagogy family above; static `<details>` answer reveal). `<PartReview part={N} />` (v4.19.0, #111) aggregates a Part's `<Exercise>` items for interleaved review — reusing the `build-exercises` index + the chapters' `part` field (run `book-scaffold build-exercises` first; presence-gated otherwise). A **searchable glossary** (v4.19.0, #115): author terms under `src/content/glossary/**` (frontmatter `term` + an MDX-body definition), enable the static `/glossary` route via `defineBookConfig({ routes: { glossary: true } })`, and link inline with `<Term id="…">…</Term>` (→ `/glossary#term-<id>`). (Scoring, the rationale appendix, and flashcards are later increments — see `docs/plans/active/study-guide-epic_*.md`.)
+**Study-guide (v4.17.0+, #112; opt-in).** A schema-validated `questions` content collection drives an exam-prep "question bank". Author questions under `src/content/questions/**.{md,mdx}` — frontmatter `id` (unique, required) / `type` (`mcq`|`free`|`cloze`) / `chapter` / `domain` (+ optional `part`/`bloom_level`/`objective_id`/`difficulty`), MDX body = the stem. MCQ carries `options: [{ id, text, correct }]` (exactly one `correct: true`); free-response carries an `answer` (model answer). An MCQ must **not** set `answer` — its answer is the option marked `correct`, and explanations for any type go in a `<Rationale>` body block. Declare the per-book domain taxonomy in `defineBookConfig({ examDomains: ['…'] })` — a question whose `domain` isn't registered **throws at build** (fail-loud, like `<BookLink>`'s `siblingBooks`). Enable the static `/practice-exam` route with `defineBookConfig({ routes: { practiceExam: true } })` (renders the bank grouped by domain with answers behind a `<details>` reveal; `cloze` is reserved/render-deferred). `<ObjectiveMap />` renders the exam-domain → chapter coverage matrix auto-derived from the collection (no separate data file). `<Rationale>` is a collapsible answer/explanation marker for a question's MDX body. `<Diagnostic>` (v4.19.0, #110) renders a per-chapter pre-reading "Do I Know This Already?" self-check (pedagogy family above; static `<details>` answer reveal). `<PartReview part={N} />` (v4.19.0, #111) aggregates a Part's `<Exercise>` items for interleaved review — reusing the `build-exercises` index + the chapters' `part` field (run `book-scaffold build-exercises` first; presence-gated otherwise). A **searchable glossary** (v4.19.0, #115): author terms under `src/content/glossary/**` (frontmatter `term` + an MDX-body definition), enable the static `/glossary` route via `defineBookConfig({ routes: { glossary: true } })`, and link inline with `<Term id="…">…</Term>` (→ `/glossary#term-<id>`). **Interactive layer (v4.21.0, #112-UI/#113/#114):** `/practice-exam` mounts the **ExamRunner island** (`client:idle`) — Start samples a form client-side (`sampleExam`), hides the rest of the bank + the answer reveals, scores checked radios on submit (`scoreExam`), and reads out per-domain results with weak-domain anchors (no JS → the static bank is the fallback). `<AssessmentTest />` is the whole-book front-matter diagnostic: a cross-domain sampled form whose weak-domain readout routes to the chapters carrying those domains' questions. The `/answers` route (`routes: { answers: true }`) is the Sybex back-appendix — every question grouped by chapter with the correct answer + rationale pre-expanded; `<Rationale appendix for="<id>">` renders inline as a link into it (and throws at build without `for=` or with the route disabled). (Flashcards are the remaining increment — see `docs/plans/active/study-guide-epic_*.md`.)
 
 Full reference in `recipes/04-component-library.md`.
 

package/components/AssessmentTest.astro

@@ -0,0 +1,124 @@
+---
+/**
+ * <AssessmentTest> — whole-book front-matter assessment test (v4.21.0, #113).
+ *
+ * The Sybex-style "where do I stand?" diagnostic: a cross-domain sampled form
+ * drawn from the WHOLE question bank, scored client-side with a weak-domain
+ * readout that routes the reader to the chapters carrying those domains'
+ * questions. Drop into a front-matter / intro page (like <ObjectiveMap>);
+ * any profile.
+ *
+ * Server side (this file): presence-gate the questions collection, fail loud on
+ * unregistered domains (assertKnownDomain), render every scoreable MCQ as a
+ * QuestionCard (stems are MDX — they can't cross into island props), and mount
+ * the ExamRunner island in assessment mode with the pure manifest + the
+ * domain→chapters routing map (deriveDomainRouting: string chapters link to
+ * /chapters/<slug>/, numeric chapters render as labels — no fabricated URLs).
+ * Cross-domain spread is the island's blueprint (spreadBlueprint).
+ *
+ * free/cloze questions are omitted here entirely (not just hidden): the
+ * assessment is the scored diagnostic, while /practice-exam remains the
+ * complete bank listing.
+ *
+ * No-JS fallback: the cards render with radios as a manual self-check and
+ * <details> answer reveals.
+ */
+import bookConfig from 'virtual:book-scaffold/book-config';
+import { render } from 'astro:content';
+import QuestionCard from './QuestionCard.astro';
+import ExamRunner from '@brandon_m_behring/book-scaffold-astro/components/ExamRunner';
+import { getAllQuestions } from '../src/lib/questions';
+import { assertKnownDomain } from '../src/lib/exam-domains';
+import { buildExamManifest, deriveDomainRouting } from '../src/lib/exam-manifest';
+import '../styles/exam-runner.css';
+
+interface Props {
+  /** Heading above the test. Defaults to "Assessment test". */
+  title?: string;
+  /** Default form size (clamped to the scoreable pool). Defaults to 12. */
+  count?: number;
+  /** Weak-domain threshold (0–1) passed to scoreExam. Defaults to 0.7. */
+  passMark?: number;
+}
+const { title = 'Assessment test', count, passMark } = Astro.props;
+
+// Fail loud on prop misuse (v4.15.0 closed-union-props line): passMark={70}
+// (percent-vs-fraction confusion) would silently flag EVERY domain weak on
+// every run — confidently-wrong output, the exact class this repo forbids.
+if (passMark !== undefined && !(passMark > 0 && passMark <= 1)) {
+  throw new Error(
+    `<AssessmentTest passMark={${passMark}}> — passMark is a fraction in (0, 1] ` +
+      `(e.g. 0.7 for 70%), not a percent.`,
+  );
+}
+if (count !== undefined && (!Number.isInteger(count) || count < 1)) {
+  throw new Error(
+    `<AssessmentTest count={${count}}> — count must be a positive integer.`,
+  );
+}
+
+// Presence-gate: only touch the collection when the directory holds files
+// (same twin-gate as <ObjectiveMap> / practice-exam.astro).
+const questionModules = import.meta.glob('/src/content/questions/**/*.{md,mdx}', {
+  query: '?raw',
+  import: 'default',
+  eager: true,
+});
+const hasQuestions = Object.keys(questionModules).length > 0;
+
+const entries = hasQuestions ? await getAllQuestions() : [];
+
+// Fail loud: an unregistered/typo'd domain must throw at build, not silently
+// skew the assessment's domain spread.
+for (const e of entries) {
+  assertKnownDomain(bookConfig.examDomains, e.data.domain, { id: e.data.id });
+}
+
+// entries are already draft-filtered (getAllQuestions filters !draft), so this
+// is type-shape filtering only — it matches buildExamManifest's pool exactly,
+// which is what the island's drift guard assumes.
+const scoreable = entries.filter(
+  (e) => e.data.type === 'mcq' && (e.data.options?.length ?? 0) > 0,
+);
+const manifest = buildExamManifest(entries);
+const domainRouting = deriveDomainRouting(entries);
+const practiceExamHref = (bookConfig.enabledRoutes ?? []).includes('practiceExam')
+  ? '/practice-exam'
+  : null;
+
+const rendered = await Promise.all(
+  scoreable.map(async (e) => ({ data: e.data, Content: (await render(e)).Content })),
+);
+---
+{!hasQuestions ? (
+  <p class="assessment-empty">
+    No questions found under <code>src/content/questions/</code> — the assessment
+    test draws from the question bank. Add question MDX files and declare your
+    <code>examDomains</code> in <code>defineBookConfig</code>.
+  </p>
+) : (
+  <section class="assessment-test" data-exam-root aria-label={title}>
+    <h2 class="assessment-title">{title}</h2>
+    {/* Without JS the island's Start button would render dead — hide the
+        controls; the cards below remain a manual self-check. */}
+    <noscript><style is:inline>.exam-runner { display: none; }</style></noscript>
+    <ExamRunner
+      client:idle
+      mode="assessment"
+      manifest={manifest}
+      count={count}
+      passMark={passMark}
+      domainRouting={domainRouting}
+      practiceExamHref={practiceExamHref}
+    />
+    {rendered.map((q) => (
+      <QuestionCard data={q.data} Content={q.Content} reserved={false} />
+    ))}
+  </section>
+)}
+
+<style>
+  .assessment-test { margin-block: 1.5rem; }
+  .assessment-title { margin-block-end: 0.5rem; }
+  .assessment-empty { color: var(--color-text-muted, #6b7280); }
+</style>

package/components/ExamRunner.tsx

@@ -0,0 +1,313 @@
+/**
+ * ExamRunner — Preact island driving the interactive practice exam (#112-UI)
+ * and the front-matter assessment test (#113).
+ *
+ * Architecture: a CONTROLLER over server-rendered question cards, not a
+ * client-side renderer. MDX stems can't serialize into island props, so the
+ * .astro side renders every card statically (QuestionCard.astro: stem, options
+ * as radio inputs named `exam-<qid>`, answer behind <details>) and this island
+ * receives only the pure manifest — the exact `ExamQuestion` shape
+ * sampleExam/scoreExam consume. The island samples a form client-side, hides
+ * the cards that aren't in it, collects the checked radios on submit, scores
+ * with the SAME engine the node:test suite verifies, and renders the
+ * score/per-domain/weak-domain readout. No JS → the static bank with
+ * <details> reveals is untouched.
+ *
+ * DOM contract with the .astro side (QuestionCard inside a [data-exam-root]):
+ *   [data-exam-root]                      wrapper section; gains
+ *                                         data-exam-phase="active|review"
+ *   [data-question-id="<id>"]             one card per question; toggled via
+ *                                         the `hidden` attribute; gains
+ *                                         data-exam-result="correct|incorrect"
+ *   input[name="exam-<id>"]:checked       the reader's chosen option id
+ *   details.question-reveal               force-opened on review
+ *
+ * Hydrated with `client:idle`. Theme via CSS tokens only (no canvas — no
+ * book:theme:change listener needed).
+ */
+import { useRef, useState } from 'preact/hooks';
+import {
+  sampleExam,
+  scoreExam,
+  type ExamQuestion,
+  type ExamResult,
+} from '../src/lib/exam-engine';
+import { spreadBlueprint, type RoutingChapter } from '../src/lib/exam-manifest';
+
+interface Props {
+  /** Scoreable MCQ pool (buildExamManifest output) — ids/domains/options only. */
+  manifest: ExamQuestion[];
+  /** practice: domain-agnostic sampling, weak domains anchor to #domain-<d> on
+   *  the same page. assessment: cross-domain spread blueprint, weak domains
+   *  route to chapters via `domainRouting`. */
+  mode: 'practice' | 'assessment';
+  /** Default form size (clamped to the pool; reader can adjust before start). */
+  count?: number;
+  /** Weak-domain threshold passed to scoreExam (default 0.7). */
+  passMark?: number;
+  /** Assessment mode: domain → chapters carrying its questions (deriveDomainRouting). */
+  domainRouting?: Record<string, RoutingChapter[]>;
+  /** Assessment mode: href of the practice bank when that route is enabled, else null. */
+  practiceExamHref?: string | null;
+}
+
+type Phase = 'idle' | 'active' | 'review';
+
+export default function ExamRunner({
+  manifest,
+  mode,
+  count,
+  passMark = 0.7,
+  domainRouting = {},
+  practiceExamHref = null,
+}: Props) {
+  const poolSize = manifest.length;
+  const domainCount = new Set(manifest.map((q) => q.domain)).size;
+  // Assessment floors at one question per domain (see start()); the default
+  // and the input's min respect that so the UI can't request a starved form.
+  const minCount = mode === 'assessment' ? Math.max(1, domainCount) : 1;
+  const defaultCount = Math.min(
+    Math.max(count ?? (mode === 'assessment' ? 12 : 10), minCount),
+    poolSize,
+  );
+  const [phase, setPhase] = useState<Phase>('idle');
+  const [requested, setRequested] = useState(defaultCount);
+  const [form, setForm] = useState<ExamQuestion[]>([]);
+  const [result, setResult] = useState<ExamResult | null>(null);
+  const ref = useRef<HTMLDivElement>(null);
+
+  function requireRoot(): HTMLElement {
+    // Fail loud (house invariant): a silently dead Start button is the worst
+    // failure mode. The throw surfaces as an uncaught console error.
+    const r = ref.current?.closest<HTMLElement>('[data-exam-root]');
+    if (!r) {
+      throw new Error(
+        'ExamRunner: no [data-exam-root] ancestor — mount the island inside the ' +
+          'wrapper that contains its QuestionCards (see the DOM contract in ExamRunner.tsx).',
+      );
+    }
+    return r;
+  }
+  function cards(r: HTMLElement): HTMLElement[] {
+    // Array.from, not spread — the dts tsconfig lib lacks DOM.Iterable.
+    return Array.from(r.querySelectorAll<HTMLElement>('[data-question-id]'));
+  }
+  function radios(r: HTMLElement): HTMLInputElement[] {
+    return Array.from(r.querySelectorAll<HTMLInputElement>('input[type="radio"]'));
+  }
+
+  function start(): void {
+    const r = requireRoot();
+    // Assessment mode floors at one question per domain — a "cross-domain"
+    // form that silently drops late-book domains would betray its own point
+    // (spreadBlueprint's quota order starves the tail otherwise).
+    const n = Math.max(minCount, Math.min(requested, poolSize));
+    const sampled =
+      mode === 'assessment'
+        ? sampleExam(manifest, spreadBlueprint(manifest, n))
+        : sampleExam(manifest, { count: n });
+    const inForm = new Set(sampled.map((q) => q.id));
+    const allCards = cards(r);
+    // Fail loud on manifest/DOM drift: a sampled question with no rendered
+    // card would be invisible yet scored incorrect — silently wrong results.
+    const cardIds = new Set(allCards.map((c) => c.dataset.questionId));
+    const missing = sampled.filter((q) => !cardIds.has(q.id));
+    if (missing.length > 0) {
+      throw new Error(
+        `ExamRunner: manifest/DOM drift — no rendered card for question(s): ` +
+          `${missing.map((q) => q.id).join(', ')}.`,
+      );
+    }
+    for (const card of allCards) {
+      card.hidden = !inForm.has(card.dataset.questionId ?? '');
+      card.removeAttribute('data-exam-result');
+      const reveal = card.querySelector<HTMLDetailsElement>('details.question-reveal');
+      if (reveal) reveal.open = false;
+    }
+    for (const input of radios(r)) {
+      input.checked = false;
+    }
+    r.setAttribute('data-exam-phase', 'active');
+    setForm(sampled);
+    setResult(null);
+    setPhase('active');
+  }
+
+  function submit(): void {
+    const r = requireRoot();
+    const answers: Record<string, string> = {};
+    for (const q of form) {
+      // CSS.escape: a question id containing a quote would otherwise break
+      // the selector and throw a DOMException mid-submit (frozen exam).
+      const checked = r.querySelector<HTMLInputElement>(
+        `input[name="exam-${CSS.escape(q.id)}"]:checked`,
+      );
+      if (checked) answers[q.id] = checked.value;
+    }
+    for (const q of form) {
+      const card = r.querySelector<HTMLElement>(
+        `[data-question-id="${CSS.escape(q.id)}"]`,
+      );
+      if (!card) {
+        // start() already guards drift; defense in depth, same loud failure.
+        throw new Error(`ExamRunner: no rendered card for question "${q.id}".`);
+      }
+      const right = q.options.some((o) => o.correct === true && o.id === answers[q.id]);
+      card.setAttribute('data-exam-result', right ? 'correct' : 'incorrect');
+      const reveal = card.querySelector<HTMLDetailsElement>('details.question-reveal');
+      if (reveal) reveal.open = true;
+    }
+    r.setAttribute('data-exam-phase', 'review');
+    setResult(scoreExam(form, answers, passMark));
+    setPhase('review');
+  }
+
+  function reset(): void {
+    const r = requireRoot();
+    for (const card of cards(r)) {
+      card.hidden = false;
+      card.removeAttribute('data-exam-result');
+    }
+    for (const input of radios(r)) {
+      input.checked = false;
+    }
+    r.removeAttribute('data-exam-phase');
+    setForm([]);
+    setResult(null);
+    setPhase('idle');
+  }
+
+  if (poolSize === 0) {
+    return (
+      <p class="exam-runner-empty">
+        No auto-scoreable (multiple-choice) questions available — free-response and
+        cloze items can't be machine-scored.
+      </p>
+    );
+  }
+
+  return (
+    <div class="exam-runner" ref={ref}>
+      {phase === 'idle' && (
+        <div class="exam-runner-controls">
+          <p class="exam-runner-intro">
+            {mode === 'assessment'
+              ? 'Take a cross-domain assessment: a sampled form spread over every exam domain, scored with a weak-domain readout routing you to the chapters to (re)read.'
+              : 'Take a scored practice exam: a random form sampled from the bank below, with a per-domain score readout.'}
+          </p>
+          <label class="exam-runner-count-label">
+            Questions:{' '}
+            <input
+              type="number"
+              class="exam-runner-count"
+              min={minCount}
+              max={poolSize}
+              value={requested}
+              onInput={(e) => {
+                const v = Number.parseInt((e.target as HTMLInputElement).value, 10);
+                if (Number.isFinite(v)) setRequested(Math.max(minCount, Math.min(v, poolSize)));
+              }}
+            />{' '}
+            of {poolSize}
+          </label>
+          <button type="button" class="exam-runner-button exam-runner-start" onClick={start}>
+            Start {mode === 'assessment' ? 'assessment' : 'practice exam'}
+          </button>
+        </div>
+      )}
+
+      {phase === 'active' && (
+        <div class="exam-runner-controls">
+          <p class="exam-runner-status" role="status">
+            {form.length} question{form.length === 1 ? '' : 's'} below — answers stay
+            hidden until you submit.
+          </p>
+          <button type="button" class="exam-runner-button exam-runner-submit" onClick={submit}>
+            Submit answers
+          </button>
+          <button type="button" class="exam-runner-button exam-runner-cancel" onClick={reset}>
+            Cancel
+          </button>
+        </div>
+      )}
+
+      {phase === 'review' && result && (
+        <div class="exam-runner-scoreboard" aria-live="polite">
+          <p class="exam-runner-score">
+            <strong>{result.pct}%</strong> — {result.correct} of {result.total} correct
+          </p>
+          <table class="exam-runner-domains">
+            <thead>
+              <tr>
+                <th scope="col">Domain</th>
+                <th scope="col">Score</th>
+              </tr>
+            </thead>
+            <tbody>
+              {result.byDomain.map((d) => (
+                <tr class={result.weakDomains.includes(d.domain) ? 'exam-runner-weak' : undefined}>
+                  <th scope="row">{d.domain}</th>
+                  <td>
+                    {d.correct}/{d.total}
+                    {result.weakDomains.includes(d.domain) && (
+                      <span class="exam-runner-weak-mark"> — review</span>
+                    )}
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+          {result.weakDomains.length > 0 && (
+            <div class="exam-runner-routing">
+              <p class="exam-runner-routing-lead">
+                {mode === 'assessment'
+                  ? 'Weak domains — start with these chapters:'
+                  : 'Weak domains — review these sections of the bank:'}
+              </p>
+              <ul class="exam-runner-routing-list">
+                {result.weakDomains.map((domain) => (
+                  <li>
+                    <strong class="exam-runner-routing-domain">{domain}</strong>
+                    {mode === 'practice' && (
+                      <>
+                        {' '}
+                        — <a href={`#domain-${domain}`}>jump to {domain} questions</a>
+                      </>
+                    )}
+                    {mode === 'assessment' && (domainRouting[domain]?.length ?? 0) > 0 && (
+                      <>
+                        {' — '}
+                        {domainRouting[domain]!.map((ch, i) => (
+                          <>
+                            {i > 0 && ', '}
+                            {ch.href ? (
+                              <a href={ch.href}>chapter {ch.label}</a>
+                            ) : (
+                              <span>chapter {ch.label}</span>
+                            )}
+                          </>
+                        ))}
+                      </>
+                    )}
+                    {mode === 'assessment' && practiceExamHref && (
+                      <>
+                        {' '}
+                        (<a href={`${practiceExamHref}#domain-${domain}`}>practice more</a>)
+                      </>
+                    )}
+                  </li>
+                ))}
+              </ul>
+            </div>
+          )}
+          <button type="button" class="exam-runner-button exam-runner-retake" onClick={start}>
+            Retake
+          </button>
+          <button type="button" class="exam-runner-button exam-runner-reset" onClick={reset}>
+            {mode === 'assessment' ? 'Show all questions' : 'Show full bank'}
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}

package/components/QuestionCard.astro

@@ -0,0 +1,166 @@
+---
+/**
+ * QuestionCard — one server-rendered question card (v4.21.0, #112-UI/#113).
+ *
+ * The shared partial between /practice-exam and <AssessmentTest>: renders the
+ * MDX stem (passed as a rendered Content component — stems can't cross into
+ * island props), MCQ options as radio inputs the ExamRunner island reads on
+ * submit, and the answer behind the static <details> reveal (the no-JS
+ * fallback — radios still work as a manual self-check without the island).
+ *
+ * DOM contract with ExamRunner.tsx (see its module doc): data-question-id /
+ * data-exam-scoreable on the article; input[name="exam-<id>"] per option;
+ * details.question-reveal. The exam-phase CSS lives here (with :global() for
+ * the [data-exam-phase] ancestor the island sets on the wrapper section):
+ * answers hide during an active exam, cards get a result border on review.
+ */
+import type { Question } from '../src/schemas.js';
+
+interface Props {
+  /** The question's frontmatter (CollectionEntry data). */
+  data: Question;
+  /** The rendered MDX stem, or null for reserved (cloze) questions. */
+  Content: any | null;
+  /** True for cloze — schema-accepted, render-deferred. */
+  reserved: boolean;
+}
+const { data, Content, reserved } = Astro.props;
+
+const scoreable = data.type === 'mcq' && (data.options?.length ?? 0) > 0;
+const correct = data.type === 'mcq' && data.options
+  ? data.options.find((o) => o.correct)
+  : undefined;
+
+/** Filled/hollow diamonds for a 1–4 difficulty, mirroring Practice.astro. */
+function difficultyMarks(d: string | undefined): string {
+  if (!d) return '';
+  const n = Number.parseInt(d, 10);
+  return '◆'.repeat(n) + '◇'.repeat(4 - n);
+}
+---
+<article
+  class="question"
+  id={`question-${data.id}`}
+  data-question-id={data.id}
+  data-question-domain={data.domain}
+  data-exam-scoreable={scoreable ? 'true' : 'false'}
+>
+  <header class="question-header">
+    <span class="question-meta-id">{data.id}</span>
+    <span class="question-meta-type">{data.type}</span>
+    {data.bloom_level && <span class="question-meta-bloom">{data.bloom_level}</span>}
+    {data.difficulty && (
+      <span class="question-meta-difficulty" aria-label={`Difficulty ${data.difficulty} of 4`}>
+        {difficultyMarks(data.difficulty)}
+      </span>
+    )}
+  </header>
+
+  {reserved ? (
+    <p class="question-reserved">
+      Cloze question — interactive rendering deferred to a later release.
+    </p>
+  ) : (
+    Content && (
+      <div class="question-stem"><Content /></div>
+    )
+  )}
+
+  {data.type === 'mcq' && data.options && (
+    <fieldset class="question-options">
+      <legend class="question-options-legend">Options</legend>
+      {data.options.map((o) => (
+        <label class="question-option">
+          <input type="radio" name={`exam-${data.id}`} value={o.id} />
+          <span class="question-option-key">{o.id}.</span>
+          <span class="question-option-text">{o.text ?? o.id}</span>
+        </label>
+      ))}
+    </fieldset>
+  )}
+
+  {!reserved && (
+    <details class="question-reveal">
+      <summary>Show answer</summary>
+      {data.type === 'mcq' && correct && (
+        <p class="question-answer-line">
+          Correct: <strong>{correct.text ?? correct.id}</strong>
+        </p>
+      )}
+      {data.type === 'free' && data.answer && (
+        <p class="question-answer-line">{data.answer}</p>
+      )}
+    </details>
+  )}
+</article>
+
+<style>
+  .question {
+    margin-block: 1.25rem;
+    padding: 1rem 1.1rem;
+    border: 1px solid var(--color-border, #e5e7eb);
+    border-radius: 0.5rem;
+    background: var(--color-surface, transparent);
+  }
+  .question-header {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.5rem;
+    align-items: center;
+    font-size: 0.78rem;
+    color: var(--color-text-muted, #6b7280);
+    margin-block-end: 0.5rem;
+  }
+  .question-meta-id { font-family: var(--font-mono, ui-monospace, monospace); }
+  .question-meta-type,
+  .question-meta-bloom {
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    padding: 0.05rem 0.4rem;
+    border-radius: 0.25rem;
+    background: var(--color-code-bg, rgba(127, 127, 127, 0.12));
+  }
+  .question-meta-difficulty { margin-inline-start: auto; letter-spacing: 0.1em; }
+  .question-options {
+    margin-block: 0.6rem;
+    border: none;
+    padding: 0;
+  }
+  .question-options-legend {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+  }
+  .question-option {
+    display: flex;
+    gap: 0.5rem;
+    align-items: baseline;
+    margin-block: 0.25rem;
+    cursor: pointer;
+  }
+  .question-option-key { color: var(--color-text-muted, #6b7280); }
+  .question-reveal { margin-block-start: 0.6rem; }
+  .question-reveal > summary {
+    cursor: pointer;
+    font-weight: 600;
+    color: var(--color-accent, #4f46e5);
+  }
+  .question-answer-line { margin-block: 0.5rem 0.25rem; }
+  .question-reserved { color: var(--color-text-muted, #6b7280); font-style: italic; }
+
+  /* Exam phases (ExamRunner island sets data-exam-phase on the wrapper
+     section): no peeking at answers during an active exam; result borders +
+     re-opened reveals on review. :global() crosses the wrapper's scope — the
+     element side stays scoped to this card. */
+  :global([data-exam-phase='active']) .question-reveal { display: none; }
+  .question[data-exam-result='correct'] {
+    border-color: var(--color-success, #15803d);
+    box-shadow: inset 3px 0 0 var(--color-success, #15803d);
+  }
+  .question[data-exam-result='incorrect'] {
+    border-color: var(--color-danger, #b91c1c);
+    box-shadow: inset 3px 0 0 var(--color-danger, #b91c1c);
+  }
+</style>