One multiple-choice question, from the bytes on disk to the click that grades it. This is the whole learn-kit pipeline made concrete — the part that turns a JSON file into something a student actually does. Our example is a Unit 3 (integers) item; here is the complete v2 envelope an importer would write:

{
  "externalId": "9f1c2a7e-…-uuid",
  "name": "Compare -7 and -3",
  "prompt": "Which statement is true? Reason about $-7$ and $-3$ on the number line.",
  "interaction": {
    "kind": "multiple_choice",
    "version": 1,
    "shuffleSeed": "u3-cmp-neg7-neg3",
    "choices": [
      { "id": "a", "content": "$-7 < -3$", "correct": true  },
      { "id": "b", "content": "$-7 > -3$", "correct": false },
      { "id": "c", "content": "$-7 = -3$", "correct": false }
    ]
  },
  "explanation": "On the number line $-7$ is farther left than $-3$, so $-7 < -3$.",
  "work": { "required": false },
  "concepts": [{ "concept": "G6.NS-KC###", "role": "target", "weight": 3 }]
}

A · DATA — how it is represented

interaction.kind = "multiple_choice" with version: 1 (mandatory), validated by multipleChoiceInteractionV1Schema.
choices is an ordered array of { id, content, correct }. id matches ^[A-Za-z0-9][A-Za-z0-9_-]{0,80}$; content is a content tree (a bare string auto-wraps to [{text}]); correct is a boolean.
The answer key is just the set of correct: true flags — pure data, regradeable and queryable.
shuffleSeed is optional; it fixes a deterministic display order (see C).
Stem, each choice content, and explanation can all carry $…$ LaTeX, rendered by KaTeX.
Every object is .strict() — an unknown key fails the whole thing to a raw view.

Notice the answer is "choice a is correct," never "the answer is A." Letters are assigned at render time, so the key never depends on position.

B · RENDER — how it is drawn

flowchart LR
  J["item .json
(MC envelope)"] --> PM["parseModelQuestion
Zod validate + normalize"]
  PM --> QR["QuestionRenderer"]
  QR --> RP["renderContentTree(prompt)
text to MarkdownDisplay + KaTeX"]
  QR --> BI["buildInteraction"]
  BI --> CC["each choice.content
to renderContentTree"]
  BI --> G["gradeMultipleChoice(choices)"]
  BI --> MC["MultipleChoice
radio cards"]
  QR --> AM["AnswerableMode
Check loop"]
  AM --> QL["QuestionLayout
prompt / answer / work / feedback"]

parseModelQuestion JSON-parses the file, normalizes (a bare-string prompt or choice becomes [{text}]), Zod-validates prompt + interaction, and returns a QuestionInput — or null (raw fallback).
QuestionRenderer draws the stem with renderContentTree(prompt) (text → MarkdownDisplay → KaTeX), prepares the optional work label + explanation, and — since the kind isn't custom — calls buildInteraction.
buildInteraction (the multiple_choice case) maps each choice to { id, content: renderContentTree(c.content, ctx), correct } — each choice body drawn through the same walker as the stem — and builds gradeMultipleChoice(choices) from that same array. It returns { render, grade, hasAnswer }.
MultipleChoice computes its display order (seededShuffle when a seed is set) and renders a role="radiogroup" of radio-card buttons; each card shows a letter badge (by display index) + the rendered content, and clicking emits onStateChange({ selectedChoiceId }).
AnswerableMode wraps it in QuestionLayout (prompt / answer / work / feedback slots).

C · INTERACT — how it is answered and graded

sequenceDiagram
  participant S as Student
  participant MC as MultipleChoice
  participant AM as AnswerableMode
  S->>MC: click choice a
  MC->>AM: onStateChange(selectedChoiceId=a)
  Note over AM: answered=true, Check enabled
  S->>AM: click Check
  Note over AM: checked=true, result=grade(state)
  AM->>MC: render(locked=true, reveal=true)
  Note over MC: correct=green, wrong selected=red
  AM-->>S: feedback + explanation
  S->>AM: click Try again
  Note over AM: checked=false, state=null

Select. Clicking a card calls onStateChange({ selectedChoiceId: choice.id }). The entire answer state is one serializable string.
Check is gated. AnswerableMode computes answered = hasAnswer(state) (an id is selected) and disables Check until then.
Grade. On Check, checked = true and result = grade(state): gradeMultipleChoice finds the selected choice by id and returns { isCorrect: selected?.correct === true }.
Lock + reveal. checked is handed to the component as both locked (cards stop accepting clicks) and reveal (correct card tints green; a wrong selected card tints red).
Feedback. "That's it." / "Not quite." plus the rendered explanation.
Try again resets checked = false and state = null.

✓ Why JSON state matters

State is { selectedChoiceId } — plain JSON.
Persist as a draft, show a teacher live, replay later.
The pure grade() re-runs server-side for authoritative scoring.

✗ Easy ways to break the render

Omit version: 1 → not interactive.
Put an unregistered component in content → "Unknown component" chip.
Reuse a choice id or break the id grammar → validation fail → raw view.

For the importer: a transcribed MCQ is exactly this envelope — stem as markdown (KaTeX ok), each option a choice with a correct flag, a stable externalId, and a shuffleSeed derived from the item id. Emit that, and the workspace preview hands you a clickable, gradable, accessible question for free.