# Quiz Builder

## Objective

Build a scored quiz with branching questions and a result page that reflects the answers.

An authoring tool for multi-question quizzes with scoring rules and answer-based branching, plus the taking experience and a result page.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Reuse the app's existing form machinery for the taking experience. If Multi-Step Form and Conditional Form Fields exist, the quiz runner is those features driven by the quiz definition, not a second form engine.
2. Support a small set of question types that actually score: single choice, multiple choice, and short text with an exact or pattern match. Free-text grading and media questions are a separate scope and should be deferred.
3. Give the author a way to see the quiz as a taker would, including a specific answer path, before it is published. A branching quiz cannot be checked by reading the editor.
4. Keep the entire scoring model on the server. Correct answers, weights and branch rules are never sent to the browser, and the result page is computed from the submitted attempt.
5. Do not let a broken quiz be published. Validate the structure at publish time and block on the problems that produce a dead end for the taker.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- Branching produces questions no path can ever reach, and rules that loop back on themselves. Detect both at publish time and name the specific questions involved rather than refusing with a generic error.
- Correct answers must never be readable from the page. If the browser holds the answer key, or the runner reveals correctness before submission, the score means nothing.
- People leave halfway through. Save progress and let a partially completed attempt resume on the same device, and be explicit about whether resuming is allowed after the attempt has been submitted.
- Skipped and partially answered questions need a defined score, decided by the author rather than assumed. A multiple-choice question with two of three correct answers selected must score the same way every time.
- Editing a live quiz changes what past attempts mean. Version the definition, keep attempts pinned to the version they were taken against, and keep old results reportable after the questions change.
- A quiz open to the public invites automated submissions. Rate limit attempts and reuse the app's existing abuse protections rather than trusting the front end.
- Two submissions of the same attempt must produce one result. Reuse the app's idempotent submission handling so a double click or a retry does not create a duplicate score.
- The result page must render meaningfully when nothing was answered, and when a branch ends the quiz early.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] Authors can create branching, scored quizzes and preview a specific answer path before publishing.
- [ ] Publish is blocked when a question is unreachable or a branch loops, with the offending questions named.
- [ ] Correct answers, weights and branch rules never reach the browser.
- [ ] Partial attempts resume on the same device with answers intact.
- [ ] Scoring for skipped and partially answered questions is explicit and consistent.
- [ ] Quiz definitions are versioned and past attempts still report against the version they were taken on.
- [ ] Duplicate submissions of one attempt produce a single result.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.