DBQ assignment screen

# DBQ assignment screen

The student-facing writing surface for a Document-Based Question — the screen a student opens when they sit down to draft a DBQ. Covers layout, mode-switching, the source viewer, the planning sidebar, citation chips, annotation persistence, and timed-vs-untimed display rules. Tutor coaching behavior and the grading assistant for DBQs are intentionally out of scope; both depend on this surface but will be specified separately.

## Scope

**In scope.** Everything the student sees and touches while reading documents, planning, and writing a DBQ. The shape of the canvas, the controls, the affordances, the persistence of student-generated artifacts (annotations, planning notes, draft body), and the way the screen changes between timed reading phase, timed writing phase, and untimed practice.

**Out of scope** (specified separately):

- DBQ tutor behavior — phase coaching, failure-mode detectors, what the coach says and when. See [`ap-history-essay-use-case.md`](ap-history-essay-use-case.md) "Tutor flow."
- DBQ grading assistant — rubric scoring, calibration-sample anchoring, errors-don't-subtract enforcement. See [`ap-history-essay-use-case.md`](ap-history-essay-use-case.md) "GA tuning rules."
- Teacher authoring (DBQ Builder, PDF upload, library). See the parent spec.
- Teacher grading view (rubric panel, column-wise mode, calibration drawer). See the parent spec.
- LEQ student screen. LEQ has no documents and reduces to editor + planning sidebar; it deserves its own (much thinner) spec.

The parent [`ap-history-essay-use-case.md`](ap-history-essay-use-case.md) sketches a starting shape for this screen — this spec inherits that sketch and drives it to engineering-ready.

## Problem

A DBQ is the densest writing surface in Yawp: 5–7 primary-source documents the student must read, annotate, group, and cite, alongside a planning surface (thesis, outline, document groupings, outside-evidence brainstorm) and the essay editor itself. Showing everything at once doesn't fit on a laptop screen. Showing too little forces the student to flip context constantly and breaks the AP-exam pedagogy of "deep reading first, fast reference while writing."

Today there is no DBQ-aware drafting surface in Yawp at all. Students who want to practice DBQs either write in Google Docs (no source-side affordances, no annotation persistence, no citation help) or use third-party tools that don't integrate with their teacher's gradebook. The student-side gap is the single biggest reason Yawp can't yet serve AP history classes.

## Goals

- A drafting surface that matches the AP-exam pedagogy: a **reading-first mode** where documents are the canvas and the editor is locked or absent, and a **writing-first mode** where the editor is the canvas and documents are a fast lookup.
- Annotations, highlights, and planning notes made during reading persist into writing — the student should never re-do work.
- During writing, looking up a document should be one click or one hover, not a context switch. Citation chips inside the editor should make most lookups inline.
- The screen should feel calm under exam pressure. No clutter, no AI branding (per platform rule), no animations that distract during a 60-minute clock.
- Mobile responsiveness: students touch this surface; teacher tools have more latitude (per platform rule). At minimum, tablet-friendly — phone is a stretch goal.
- Behavior under timed mode is unambiguous: the student can tell at a glance which phase they're in, how much time is left, and what they can and cannot do right now.

## Non-goals

- Not a tutor surface — the coach panel is part of this screen's layout, but its contents and behavior are specified in the parent spec.
- Not a grading surface — no rubric panel here; the rubric appears in the submission view, not the drafting view.
- Not LEQ — LEQ is a much simpler shape and gets its own spec.
- Not the College Board exam interface — Yawp is not trying to replicate the actual exam UI pixel-for-pixel. The goal is exam-condition *practice*, not exam *simulation*.
- Not a PDF reader — sources are stored as structured data (title, attribution, body, optional image). The original PDF the teacher may have uploaded lives in the authoring side, not the student side.

## Domain notes

- The student is working on a **Document** tied to an **Assignment** whose **AssignmentType.kind = 'dbq'** (per the parent spec). The AssignmentType carries the ordered source set, the prompt, the period, and the time mode default. The Assignment instance may override the time mode.
- **TimedSession** (from the parent spec's data model) tracks phase, transitions, and timestamps for a timed run. This screen is the surface where those transitions happen — when the 15-minute reading clock expires, this screen flips from reading mode to writing mode.
- **Document annotations and planning-sidebar contents persist alongside the document body** on the same Document row (or a tightly joined table). They are not Submission artifacts — they live with the working draft and travel with it.
- Submission still works as today: the student clicks submit, the Document body snapshots into a Submission, and the student leaves this screen. Annotations and planning notes may or may not snapshot with the Submission — open question below.
- Cross-reference [`multi-tab-editing-warning.md`](multi-tab-editing-warning.md) — DBQs are a particularly bad multi-tab case because annotation state is stateful per tab. Worth resolving consistently.

## UX sketch

**Four zones, one screen, visible at all times.** The layout echoes the revision flow's three-column shape (left feedback panel / original essay / revision editor) and rearranges it for the DBQ task: the tutor takes the slim left column, the documents take the middle, the draft takes the right, and a thin prompt banner spans the top of the two main panels.

```
┌──────────┬────────────────────────────────────────────────────────────┐
│          │ Prompt: Evaluate the extent to which Reconstruction (1865– │
│  Tutor   │          1877) marked a turning point in the lives of...   │
│  chat    ├──────────────────────────────┬─────────────────────────────┤
│          │                              │                             │
│ ┌──────┐ │   Sources                    │   Your draft                │
│ │ tutor│ │   [D1] [D2] [D3] [D4]…       │                             │
│ │ turn │ │                              │   The Reconstruction era    │
│ └──────┘ │   Doc 3 — "Letter from..."   │   marked a turning point... │
│          │   Author: ...  Date: ...     │                             │
│ ┌──────┐ │                              │   ...as shown in [D3], by   │
│ │ you  │ │   [full source text,         │   the 1870s the federal     │
│ └──────┘ │    highlightable, with       │                ─────        │
│          │    margin notes]             │   citation chip on hover ↑  │
│ ┌──────┐ │                              │                             │
│ │ tutor│ │                              │                             │
│ │ turn │ │                              │                             │
│ └──────┘ │                              │                             │
│          │                              │                             │
│ [ask ▸ ] │                              │                             │
└──────────┴──────────────────────────────┴─────────────────────────────┘
```

### Zone 1 — Tutor stripe (far left, full height, collapsible)

A vertical chat surface running the full height of the screen, formatted the way the GA and teacher-comments column is formatted in the revision view. Stacked message bubbles, scrollable, with an input affordance at the bottom for the student to ask the tutor a question. The tutor speaks here and only here — it never injects into the editor.

- Always present, but **collapsible**. One-click affordance (chevron on the edge) collapses the stripe to a slim icon strip (showing "tutor" vertically or an icon); same affordance re-expands. Default state is expanded; collapse state is per-student and persists across reloads.
- Width is fixed when expanded (think the revision flow's left column, slightly narrower) — the tutor is a peripheral coach, not the main canvas.
- Behavior (what the tutor *says*, when, and why) is **out of scope for this spec** — see [`ap-history-essay-use-case.md`](ap-history-essay-use-case.md) "Tutor flow." This spec only specifies the surface.
- During the timed reading phase, the tutor stripe is **visible but silent** — no proactive turns, the input is disabled with a "tutor is quiet during reading" hint. Reverts to normal behavior once writing begins. Students who want full focus on the sources during reading can collapse the stripe themselves.

### Zone 2 — Prompt banner (top, spans sources + editor)

A thin horizontal banner above the two main panels, displaying the DBQ prompt verbatim. Always visible. Small "show full prompt" affordance if the prompt is long enough to truncate.

- Spans the width of the sources + draft panels only — the tutor stripe extends above it (so the tutor column starts at the very top, the prompt sits to the right of it).
- Static once rendered. No interactivity beyond expand/collapse for long prompts.
- Period and reasoning-skill tags can live here as small chips on the right side (e.g., "APUSH · continuity-and-change") — useful student-facing context without being intrusive.

### Zone 3 — Sources panel (middle, large)

Where the documents live. A single panel showing one source at a time, with navigation across the 5–7 docs at the top of the panel.

- **Doc navigation across the top of the panel.** Numbered tabs/chips `[D1] [D2] [D3] …` along the top of the sources panel. Active doc highlighted. Tabs show annotation-count indicators (a small dot or count) so the student can see at a glance which docs they've worked on.
- **Single-doc view.** Click a tab → that doc's body fills the panel. Title, attribution, date above the body; full text below, with the in-platform highlighter and margin-note affordances.
- **"Pin two" affordance.** A pin icon on each tab lets the student pin one doc while opening another — the panel splits vertically into two sub-panes (or stacks, on narrow screens). Cap at 2 pinned. Useful for cross-doc analysis.
- Annotations and highlights persist per doc, per Document; visible whenever a doc is reopened.
- **v1: single highlight color + free-text margin notes** — no tag taxonomy, zero cognitive load during reading. **v2 candidate: tagged highlights** (e.g., `evidence`, `POV`, `context`, `outside-knowledge cue`) so the citation-chip flow can later surface "you tagged this as evidence — want to cite it?"

### Zone 4 — Draft editor (right, large)

The student's writing surface. Same editor as the rest of Yawp — autosave, formatting toolbar, version history — with one DBQ-specific affordance: **citation chips**.

- **Citation chips.** When the student types `Document 3`, `Doc 3`, `[D3]`, or similar, the editor recognizes the reference and offers to convert it via an inline suggestion badge (see "Citation chip suggestion behavior" below). Once accepted, the chip is interactive: **hover** → the doc's content surfaces in a hover panel; **click** → that doc opens in the sources panel (replacing or pinning alongside whatever's there).
- Citation chips also drive a passive count surfaced somewhere unobtrusive (e.g., in the doc-tab strip: a small badge on each tab the student has cited). Lets the student see coverage without putting the rubric in front of them.
- Standard submit affordance (top-right of the draft panel or top of the screen — see open question below).

### No in-app planning sidebar

The parent spec sketched a dedicated planning sidebar (thesis draft, document groupings, outside-evidence brainstorm). **This screen does not include one.** Two reasons:

1. **The tutor does the planning coaching.** Walking the student through thesis-shaping, document grouping, and outside-evidence brainstorming is exactly what the DBQ tutor's first phases are for (per the parent spec's "Tutor flow"). Building a parallel in-app planning surface duplicates work the tutor is already doing — and worse, fragments planning across two surfaces.
2. **Scrap paper is good enough — and arguably better.** The AP exam itself is written by hand with scratch paper for planning; students who practice with scratch paper are practicing under conditions closer to the real exam. A glossy in-app planner solves a problem students don't actually have.

Net effect on this screen: no planning textarea, no groupings widget, no outside-evidence brainstorm field. The tutor stripe handles the coaching; whatever notes the student wants to keep, they keep on paper next to their laptop.

If usage data later shows students struggling without an in-app planner, this is reversible — the four-zone layout has room to add a `[Plan]` tab on the sources panel or a collapsible region on the draft editor without restructuring anything else.

### Citation chip suggestion behavior

Auto-conversion-as-you-type would be jumpy and surprising; explicit-syntax-only adds friction. The middle path is **inline suggestion**, modeled on the @-mention / slash-command pattern students already know from Google Docs, Notion, and Slack.

- As the student types a recognized pattern (`Document 3`, `Doc 3`, `D3`, `[D3]`, case-insensitive), a small **suggestion badge** appears at or just below the cursor: a thumbnail-style chip previewing the matched doc (e.g., `→ D3 "Letter from..." — press Tab to insert`).
- **Accept** with `Tab`, `Enter`, or a click on the badge → the typed text converts to a citation chip in place.
- **Dismiss** with `Esc`, a space-then-keep-typing, or just ignoring it (the badge fades after a beat) → the text stays as plain prose.
- **Invalid references** (e.g., `Document 8` on a 7-doc DBQ) → the badge appears in a "no match" state: `→ No Document 8 in this DBQ`. No chip can be inserted; the student can self-correct or leave the text as-is. Quiet and non-blocking.
- The suggestion UI is consistent with the rest of yawp-2.0's autocomplete patterns; final visual treatment to be set in design.

### Resizable panels

The three vertical zones (tutor stripe / sources panel / draft editor) are **separated by drag handles** the student can grab to resize. This lets the student rebalance the layout to fit what they're doing right now: pull the sources panel wide while reading, widen the editor while writing, shrink the tutor stripe (or collapse it entirely) when they want minimum distraction.

- Drag handles between each pair of zones; cursor changes on hover to signal grabability.
- Sensible minimums on each zone so a student can't accidentally crush one to zero width (zero-width collapse is what the tutor stripe's explicit collapse affordance is for).
- Sensible maximums so one zone can't push another off-screen.
- Resized widths persist per-student across reloads (alongside the tutor-collapse state).
- A "reset layout" affordance somewhere unobtrusive (settings menu or a small icon near the layout chrome) restores defaults.

### Timed mode behavior in this layout

The four-zone layout is the same in timed and untimed practice — no separate "reading mode" and "writing mode" screens. Timed mode just adds enforcement:

- **Reading phase (minutes 0–15).** Draft editor is **locked** (read-only, visibly dimmed with a "Writing phase begins in MM:SS" overlay). The tutor stripe is visible but silent. The sources panel and the planning area inside the editor (if option 1) are fully active. A visible clock lives in the prompt banner.
- **Writing phase (minutes 15–60).** Editor unlocks; clock keeps running. Tutor stripe behaves normally. Sources panel unchanged.
- **Auto-submit at minute 60.** Whatever's in the editor snapshots into a Submission.
- **Untimed practice.** Everything unlocked from the start; no clock; manual submit only.

Lock-the-editor (rather than hide it) is the right call in this layout — hiding a whole zone would re-trigger the two-mode split. A clear "you can't write yet, but you can see where you'll write" is calmer.

### Annotation taxonomy

Annotations made during reading must be useful at writing time. Open question on whether they're:

1. **Single-color highlights + free-text margin notes** (simplest, lowest friction).
2. **Tagged highlights** (e.g., "evidence," "POV," "context," "outside-knowledge cue") that the citation chip system can surface later.
3. **HIPP-tagged margin notes** (Historical situation / Intended audience / Purpose / Point of view) — pedagogically rich but adds cognitive load during reading.

Leaning option 2 — gives the writing-mode lookup something to organize around without forcing the student into a heavy taxonomy.

### Empty / loading / error states

- Doc rail with zero annotations on day one: chips show no dots; that's the empty state.
- Document body fails to load: show the attribution and a retry button; don't block the rest of the screen.
- Timed mode loaded after the clock should have already started (browser was closed, network issue): resume at the correct phase based on the server's `TimedSession.startedAt`; never restart the clock.
- Student opens the screen on a phone (under-spec'd device): show a "this screen works best on a laptop or tablet" notice rather than a broken layout. Phone-friendly drafting is a non-goal at v1.

## Data model implications

This screen is thin from a data perspective — most of the model lives in the parent spec. Specific to this surface:

- **Annotations** — per-Document, per-source, structured as `{ sourceIndex, selectionRange, kind, body? }`. Persisted alongside the Document body. New table `DbqAnnotation` (or JSON column on the Document, TBD).
- **No planning-sidebar storage.** The in-app planning surface was dropped (see UX sketch); nothing to persist.
- **TimedSession** transitions — already specified in the parent. This screen reads `phase` and `startedAt` to render the right state.
- **Citation chips** are a rendering concern, not a persistence concern. The chip is just a way of displaying a substring like `[D3]` in the editor — no new storage needed.
- **Pinned-doc state** — ephemeral, client-side only. Lost on reload. Not worth persisting.
- **Per-student layout preferences** — tutor-stripe collapse state and resized panel widths. Persists per student (not per Document — a student's preferred layout is a global preference, not a per-DBQ one). Small JSON on the User record or a separate `UserPreferences` row.

Backward-compat: all additive. Non-DBQ Documents are unaffected. No destructive migration.

## File paths in `yawp-2.0` likely to change

Best-guess only; engineering will refine.

- `services/web-app/app/routes/documents/$documentId.tsx` (or wherever the Document route lives) — branch on AssignmentType kind to render the DBQ screen layout.
- `services/web-app/app/components/document/dbq/` (new) — the whole DBQ-specific layout: reading mode, writing mode, doc rail, source viewer, planning sidebar, citation-chip extension to the editor.
- `services/web-app/app/components/document/dbq/reading-mode.tsx`
- `services/web-app/app/components/document/dbq/writing-mode.tsx`
- `services/web-app/app/components/document/dbq/doc-rail.tsx`
- `services/web-app/app/components/document/dbq/source-viewer.tsx`
- `services/web-app/app/components/document/dbq/planning-sidebar.tsx`
- `services/web-app/app/components/document/dbq/citation-chip.tsx` — editor extension; depends on the editor framework (TipTap/ProseMirror/etc. — Bryant to confirm).
- `services/web-app/app/components/document/dbq/timed-mode-banner.tsx`
- `packages/db/...` — `DbqAnnotation` table or JSON column; planning-sidebar JSON column.
- `packages/domain/...` — phase-transition logic for `TimedSession`.

## Open questions

- [x] **Planning area placement** — **resolved: no in-app planning sidebar in v1.** The tutor handles planning coaching; students plan on scrap paper. Reversible later if usage data shows a gap. (Kevin)
- [x] **Tutor stripe collapse** — **resolved: collapsible via a one-click affordance, default expanded, state persists per student.** (Kevin)
- [x] **Tutor stripe during timed reading phase** — **resolved: visible but silent, input disabled with a "tutor is quiet during reading" hint. Student can collapse it if they want full focus.** (Kevin)
- [ ] **Resizable panels — minimums, maximums, persistence scope.** Confirmed in v1 (drag handles between the three zones). Exact pixel/percent minimums and whether "reset layout" lives in a settings menu or as a visible icon — to detail in design. (Kevin / Bryant)
- [ ] **Prompt banner — how long is too long?** APUSH DBQ prompts are typically 1–3 sentences but some run longer. Truncate with expand, or always show full and let it eat vertical space? (Kevin)
- [ ] **Sources-panel navigation** — tabs across the top (current sketch), a dropdown, or a vertical chip rail inside the panel? Tabs feel right for ≤7 docs; might need to revisit if a Euro/World DBQ ships with more. (Kevin)
- [x] **Submit button placement** — **resolved: match the existing convention used by other Yawp assignments** (Daily Pages, narrative essay, standard thesis essay). Whatever placement and label those use today, the DBQ screen inherits. Bryant to confirm the current convention so the spec lands on a concrete location before handoff. (Kevin)
- [x] **Annotation taxonomy** — **resolved: option 1 (free) for v1.** Single highlight color, free-text margin notes; zero cognitive load during reading. Tagged highlights (option 2) marked as a strong v2 candidate — once usage shows what students actually want to surface at writing time, we can pick the right tag set with data. (Kevin)
- [ ] Do annotations snapshot into the Submission, or stay on the Document only? Argument for snapshotting: it preserves the student's work-product for the teacher to inspect. Argument against: clutters the submission view. (Kevin / Bryant)
- [ ] Editor framework — what is `yawp-2.0` using today, and does it support the citation-chip extension natively? (Bryant)
- [ ] Mobile responsiveness floor — tablet-only at v1, or phone-friendly? Phone seems unrealistic given four zones; tablet (iPad-class) feels like the right floor. Narrow tablet portrait may need to collapse the tutor stripe by default. (Kevin)
- [ ] Source tabs behavior on >7 docs — cap at 7 for v1 or design for arbitrary count? (Kevin)
- [ ] "Pin two" — strict cap at 2, or allow N pinned docs? Probably 2 for v1. (Kevin)
- [x] **Citation-chip parsing rules** — **resolved: inline suggestion badge as the student types** a recognized pattern (`Document N`, `Doc N`, `D N`, `[DN]`, case-insensitive). Accept with Tab/Enter/click; dismiss with Esc or by continuing to type. Patterns above the v1 recognized set; spelled-out numbers ("Document Three") and exotic forms can come later. (Kevin)
- [x] **Invalid doc references** — **resolved: badge appears in a "no match" state** (e.g., `No Document 8 in this DBQ`), no chip insertable, student can self-correct. Quiet and non-blocking. (Kevin)
- [ ] Timed-mode resume across tab close — auto-resume at correct clock position via server-side `TimedSession.startedAt`. Confirm. (Bryant)
- [ ] Submit-during-reading-phase — is it allowed? Probably yes ("I'm done, grade what I have") but with a confirmation. (Kevin)
- [ ] Keyboard accessibility — arrow keys to switch source tabs, tab to focus chips, shortcut to focus the tutor input. Needs a pass before launch. (Kevin / Bryant)
- [ ] Visual treatment of citation chips — pill, bracket, link-style? Should distinguish from regular prose at a glance. (Kevin to brief on design.)
- [ ] Does the planning area carry into the LEQ screen? Probably yes, in a stripped form — worth deciding now so the data model lines up. (Kevin)

## Edge cases

- Student opens a DBQ in timed mode, closes the tab at minute 5, reopens at minute 14: resume in reading mode with 1 minute left, transitions to writing at minute 15 as scheduled.
- Student opens a DBQ in timed mode, closes the tab at minute 5, reopens at minute 30: resume in writing mode with 30 minutes left; reading mode is no longer accessible (reading phase has passed).
- Student opens a DBQ in timed mode, closes the tab at minute 5, reopens at minute 70: auto-submitted at minute 60 server-side; show the submitted state, not the drafting screen.
- Student types `[D8]` on a 7-doc DBQ — see open question; current lean is inline warning, no chip render.
- Student highlights the same span twice — second highlight replaces the first; no stacking.
- Student pastes a large block of text into the editor — paste alert fires per the platform-wide policy (cross-reference `bugs/paste-alert-detection-broken.md`).
- Student opens the DBQ in two tabs — cross-reference `features/multi-tab-editing-warning.md`. Annotation state in particular must not split-brain.
- Teacher edits the DBQ AssignmentType (adds a source, removes a source, edits a body) while a student has it open mid-draft — versioning question lives in the parent spec; this screen needs to render whatever version the student's Document is anchored to, not the latest AssignmentType.
- Student's network drops mid-write — editor's existing autosave behavior applies; planning sidebar and annotations should follow the same autosave guarantees.
- Student switches between reading and writing modes in untimed practice 50 times in 10 minutes — no penalty, no state loss, no perf regression.
- Source document contains an image (post image-support) — viewer renders the image inline; annotation on an image is out of scope at v1 (highlights and notes are text-only for now).
- Long source body (multi-screen scroll) — viewer scrolls within its pane; doesn't push the rail or planning sidebar out of view.
- Student copy-pastes from a source into the editor — paste alert fires; the citation chip system does not auto-add a citation chip (that would over-promise).
- Student has accessibility settings on (large text, high contrast) — layout has to hold up. Tablet portrait + large text is the stress case.

## Test plan

To be detailed. Starting list:

- Unit tests on citation-chip parsing (each recognized pattern; invalid doc number; mid-word vs. clean-boundary matches).
- Unit tests on `TimedSession` phase resolution given a `startedAt` and a current time.
- Component tests on the doc rail (annotation-count rendering, pinning, active-state, >7 docs if we support it).
- Integration test: timed-mode happy path — open DBQ, annotate three docs, transition at 15 min, write with citation chips, auto-submit at 60.
- Integration test: timed-mode resume across tab close at minutes 5, 14, 16, 59, 61.
- Integration test: untimed mode — manual mode switching, no clock, no auto-submit.
- E2E: student writes a real DBQ end-to-end on a laptop and on an iPad.
- Manual QA: keyboard-only navigation through the full read-then-write flow.
- Manual QA: paste-alert interaction (cross-reference `bugs/paste-alert-detection-broken.md` — may need to land first).
- Performance: doc rail with 7 docs each ~2000 words, rapid pinning and switching, no jank.

## Rollout

Feature flag (shares the `dbq_assignment_type` flag from the parent spec; this screen ships when the AssignmentType ships). Default off.

APUSH-first pilot per the parent spec: UA professor → Washington → Birmingham City. The student screen needs to land before any pilot teacher can run a real DBQ, so this is on the critical path for the parent spec's v1.

Within v1, the phase-structured timed mode is the most ambitious piece. If feasibility risk surfaces, the fallback is a thinner v0 with a 60-minute clock that doesn't enforce reading/writing phase separation — single mode, planning sidebar always available, no auto-lock. The full phase-structured experience then lands in v1.1.

## Engineering handoff checklist

- [ ] Domain context covered
- [ ] File paths in `yawp-2.0` listed
- [ ] Data model implications spelled out, including backward-compat plan
- [ ] UX sketch in prose
- [ ] Edge cases enumerated
- [ ] Test plan written
- [ ] Rollout plan decided