# Submission UX review

Scope: static AI review of `/workspace/sites/who-holds-advantage-game/game.template.html`, read only. This is an interface and implementation review, not evidence from students, teachers, classroom observation, or timed use. The source template was not edited.

## Recommended decisions

Proceed with the requested changes. They can make the homework output and resumption path clearer while retaining the present requirements for a complication, competing account, distinguishing evidence, second-case comparison, and a meaningful source limit. Keep the existing full report alongside the new compact summary.

| Change | Precise recommendation |
| --- | --- |
| Class paste rule | Block paste into learner-response fields only when `state.mode === 'class'`. Show the rule beside the writing fields and announce a short message on a blocked paste. Keep ordinary editing, supplied starter insertion, copying output, and JSON import available. |
| Main explanation length | Display an aim of 60–85 words; permit finishing at 50–120 inclusive. Do not change the 30–45-word comparison requirement without a separate decision. |
| Submission choices | Add `Copy hand-in summary`; label the existing print action `Print / Save as PDF`; retain `Download full report (HTML)`, `Copy full record`, and `Download editable backup (JSON)`. |
| PDF behavior | The current action calls `window.print()`. Describe the browser print dialog accurately; do not label it a direct PDF download. |
| Target support | Offer country-specific target prompts as optional buttons. Each must name a real event/opportunity in the supplied case, with an actor and period, without asserting an unproved effect. |
| Short-answer support | Add generic insertion buttons beside the competing-account and needed-evidence fields. Insert a scaffold, preserve existing work, and leave the historical answer to the learner. |
| Evidence guidance | Place `What the record supports` and `Where the claim stops` in the always-visible part of each evidence card. Keep source-record details available separately. |
| Internal verification note | No internal QA note was found in this template. Locate and remove the exact note in injected data or built output; retain substantive source limitations and locators. |

## Exact learner-facing wording

### Explanation length

Editor heading suffix: `Aim for 60–85 words`

Counter: `72 words · aim 60–85 · 50–120 accepted to finish`

Inclusion check: `Current explanation contains 50–120 words (aim: 60–85)`

Opening instructions: `A 60–85-word explanation is the aim; 50–120 words can finish the record. Cite both supporting card IDs, address your complication, and state a source limit relevant to your claim.`

Use the same wording on the initial counter and the live counter. Words outside the preferred aim but within 50–120 must not receive the existing error styling or a failed check. Keep the comparison counter and gate at 30–45.

### For class paste rule

Persistent writing hint: `For class: type your responses in the writing fields. Pasting is turned off. You can use the supplied starters.`

Blocked-paste announcement: `Pasting is turned off in For class. Type your response or use a starter.`

Apply to research target, causal steps, board reasons, explanation, comparison, rival, needed evidence, hearing-decision reasons/revisions, and learner reflection. Optional name and glossary search are not assessed writing fields and need not be blocked. The mode switch should apply the rule immediately while preserving existing text. Do not describe this feature as an originality or authorship check.

Implementation: use a shared predicate identifying learner-response controls, and prevent the `paste` event when class mode is active. Also handle `beforeinput` with `inputType === 'insertFromPaste'` for browser editing paths that expose it. Avoid a blanket keydown rule or blocking ordinary `input` events: those can interfere with selection, accessibility input, and the app's own insertion controls. Do not block `copy`, `cut`, clipboard output, or the deliberate JSON-resume operation. This review does not recommend changing imported content or preventing resumption.

### Save and hand-in panel

Heading: `Save or hand in your work`

Body: `Use the format your teacher asks for: copy the hand-in summary into the assignment, or use Print / Save as PDF. This page does not send your work to a teacher. Download the editable backup to reopen your evidence board, notes and drafts later.`

Primary action: `Copy hand-in summary`

Print action: `Print / Save as PDF`

Print helper: `Opens your browser’s print dialog. Choose Save as PDF if your browser offers it.`

Backup action: `Download editable backup (JSON)`

Backup helper: `Reopen it with Import JSON. It contains your saved workspace and any entered name.`

Preserve the existing preview. Keep `Download full report (HTML)` and `Copy full record` available together as fuller evidence records. The existing `copy-report` action should retain its full-report behavior; give the compact action its own name and function.

## Compact hand-in summary: minimum content

The summary should be a structured plain-text output, not a shorter generated explanation. Copy the learner's actual stored text, using `Not yet written` for missing parts. It must not silently drop unfinished requirements or imply a draft has passed.

Recommended order:

1. **Identity and status:** title, optional entered name, solo/shared pair record, main country and historical period, current `Draft` or `Finished` status. Do not call the result graded or approved.
2. **Research target.**
3. **Current explanation**, with current word count and the learner's actual card-ID citations retained verbatim.
4. **Supporting evidence:** both chosen card IDs and titles; short learner notes if present. Include selected board cards even if an ID is missing from the paragraph.
5. **Complication:** selected card ID/title and its required learner reason. This section is essential even when the paragraph's treatment is weak or absent.
6. **Source limit:** any optional limitation callout, plus the recorded self-check status. Do not convert a checked box into an app assertion that the paragraph contains a valid limit. Use `Limit self-check: learner confirmed / not confirmed`. When no optional callout exists, the reader can assess the actual paragraph above; do not invent or infer a limit sentence.
7. **Competing account and shared uncertain link:** the full rival response.
8. **Distinguishing evidence request:** the full expected-patterns/evidence response.
9. **Second-case comparison:** second country/period, comparison question, full comparison paragraph and count. Keep all cited second-case IDs.
10. **Hearing response:** the two applied decisions and reasons, including any narrowing/replacement. Include the initial explanation if space permits; it is already short and supports assessment of revision.
11. **Assessment boundary:** `Item checks record presence, lengths, IDs and learner confirmations. A person reviews the reasoning. Full record available separately.`

A compact summary can omit supplied source excerpts, repeated feedback, full attempt history, retired cards, and the full source bibliography. Those remain in the full report. Do not omit the learner's complication, rival, comparison, evidence request, or limits to achieve compactness. Avoid an arbitrary clipboard character cap that truncates these fields.

On clipboard failure, show the exact summary in a selectable textarea/dialog with an accessible label and manual-copy instruction. Do not discard it or require a second full workflow. The existing full-copy button should remain distinct in both its label and success message.

## Target prompts and insertion controls

`renderResearchTarget` is the appropriate location for optional country-specific prompt buttons. Button group label: `Choose a starting target, then edit it`. Each button should set or insert a neutral target phrase drawn from the relevant supplied historical window. Do not guess the case facts from the country name. This template injects the case data at `/*__CASE_DATA__*/`, so the exact per-country target text requires checking that data.

Safe prompt pattern: `[named actor]’s opportunity to [specific recorded action], [period]` or `Implementation of [named decision], [period]`. A target can ask whether an effect is established; it must not force a measured effect the file cannot show. Preserve an existing target unless the learner explicitly chooses replacement, then use the same board-review invalidation and persistence path as manual target edits.

Competing-account button: `Insert a competing-account starter`

Starter: `Both accounts try to explain __. My account is __; a competing account is __.`

Evidence button: `Insert an evidence-request starter`

Starter: `My account predicts __; the other predicts __. I would check __, for __ during __.`

Insert at the caret where practical, or append to existing text. Never silently replace the whole response. Repeated activation should not create unnoticed duplicates. Move focus to the destination and select or position the caret at the first placeholder. Persist through the existing field-binding path. Starters must be allowed in For class and must not generate or fill the final historical paragraph. Mere placeholder insertion is not meaningful reasoning: an unchanged inserted starter should remain structurally incomplete and prompt `Finish the starter in your own words`. This is a placeholder check, not a judgment of meaning.

## Evidence-card visibility

`renderCardLimit` already supplies two useful headings from `PLAYER_SUPPORT`: `What the record supports` and `Where the claim stops`. Currently it is nested inside the closed `Source details` disclosure in `renderCard`.

Move that provided guidance just below `Recorded point` so both headings and their text are visible by default in main- and second-case cards. Retain the longer full-card text and original source records in their disclosures. Avoid rendering the same guidance twice. Visible provided guidance must remain labelled as supplied guidance in the exported report; it is not the learner's own analysis. Moving it must not falsely count a source-record opening or mark the learner as having read the source.

## Focused acceptance checks

- In class, paste is blocked in each learner-response field and announced; the same field permits paste in Just for fun. Switching modes retains work. Starter buttons still work in class.
- Main explanation counts of 49 and 121 fail the length item; 50, 59, 60, 85, 86 and 120 pass it. The preferred 60–85 aim remains visible. The comparison rule still behaves as labelled.
- `Print / Save as PDF` opens the browser print dialog and prepares the current full report. No success message claims a PDF was saved or an assignment submitted.
- JSON export/import round-trips target, both supporting notes, complication, current explanation, rival, evidence request and comparison.
- Compact output contains all required sections for a complete record and explicit missing-text/status labels for a draft. The existing full-copy output remains available.
- Target and starter controls preserve existing text, focus the destination, persist changes, and invoke the same review-reset behavior as equivalent typing.
- Both positive support and claim limits are visible on all evidence cards without expanding Source details. Original record-open counters do not advance merely because the guidance is visible.

Source anchors: template lines 124 (explanation editor), 126–127 (rival/evidence fields), 151 (evidence-card rendering), 176 (structural gates), 178 (finish/save flow), 184 (live counters), 185 (full report), and 206 (print/clipboard actions). Line numbers reflect the reviewed file and may shift after edits.
