# Simulator

## Purpose
The Preview Simulator allows admins to open a real-time exam-style preview of questions in a new tab. It is intended for testing question presentation, answer selection, notes, flags, and review flow without affecting real exam data.

## How to open
- From the admin question index page, the `Preview Simulator` button appears only when questions exist.
- The simulator opens in a new browser tab using the admin layout.

## Question selection
- The simulator loads random questions from each available question type.
- It now selects up to **4 questions per type** for the preview.
- Scenario questions are shown with full-width scenario content and the child question content below.

## Screen layout
### Top bar
- Project logo and header are inherited from admin layout.
- Timer is always visible in a fixed-width section.
- `Hide` / `Show` toggles only the timer text, without shifting layout.
- `Full screen` enters browser fullscreen mode.
- `Exit simulator` ends the preview and shows the thank-you page.

### Question card
- Current question number, progress bar, and primary action controls appear above the question.
- `Erase highlight` clears selected text highlights.
- `Add note` opens a modal for question notes.
- `Flag to revisit` toggles flagged state.
- The note icon is highlighted in the simulator when a note exists.

### Answer area
- Single choice and multiple choice questions show selectable option buttons.
- Selected options are styled with the theme brand color.
- Fill-in-the-blank questions allow typing, and the typed answer appears live under `Your answer is:`.
- `Select the best answer` text only appears for choice questions.

### Bottom controls
- `Previous` and `Next` buttons navigate the preview.
- The `Next` button becomes `Submit` on the last question.
- `Submit` ends the preview and shows the thank-you screen.

## Review panel
- Clicking `Review` opens the left review slide panel.
- Question tiles show the question number.
- Answered questions use the theme primary color.
- Flagged questions use the theme primary color styling.
- Questions with notes are also highlighted in the review panel.
- A small note icon appears on noted questions.

## Thank-you page
- After submit or exit, a thank-you page is shown.
- It shows `Score` and `Answered` counts.

## Simulator implementation files
- View: `resources/views/pages/admin/question/preview-simulator.blade.php`
- JavaScript / Alpine: `resources/js/admin/question-preview-simulator.js`
- Service logic: `app/Services/Admin/QuestionService.php`

## QuestionService briefing
The simulator uses the following protected methods in `QuestionService`:

- `previewSimulatorQuestions(int $perType = 4): array`
  - Builds a randomized simulator payload with up to 4 questions per type.

- `serializeSimulatorQuestions(Collection $questions): array`
  - Serializes parent and scenario child questions into a flat simulator list.

- `serializeSimulatorQuestion(Question $question, string $number, ?Question $scenario = null): array`
  - Converts a question into simulator payload fields.

- `modeForSimulator(Question $question, array $options, ?string $answer): string`
  - Determines question mode: `single_choice`, `multi_choice`, `fill_blank`, or `text`.

- `optionsForSimulator(Question $question): array`
  - Extracts and formats option data from question content.

- `answerForSimulator(Question $question, array $options): ?string`
  - Computes the correct answer string for simulator questions.

- `hintForSimulator(array $content): ?string`
  - Extracts a hint from question content if available.

- `cleanText($value): string`
  - Strips HTML and normalizes text for comparisons.

## Notes
- The simulator is designed as a preview, not a final exam submission module.
- It uses the admin theme classes and dark/light mode styling.
- Existing question data must be published and available for previewing.