Side-by-side revision view

# Side-by-Side Revision View

Adds a new revision route (`/app/submissions/:submissionId/revise`) that shows a student's graded feedback on the left and their live editable document on the right, so they can read feedback and revise simultaneously. Previously, "Revise Essay" just opened the document editor with no feedback visible.

**Feature flag:** `side_by_side_revision_enabled`

## Problem

Students revising their essays have to switch back and forth between the graded feedback view and the document editor. There's no way to read teacher comments and edit simultaneously. This makes revision harder and more friction-filled, especially for students responding to inline comments.

## Goals

- Let students read graded feedback and edit their document in the same view.
- Preserve all critical editor capabilities (autosave, submit, version history) in the revision context.
- Gate the new flow behind a feature flag so the old flow can be preserved during rollout.

## Non-goals

- Tutor sidebar integration in the revision context (see "What we left out" below).
- Mobile layout — this is inherently a desktop UI.
- Inline comment threads in the revision panel (teacher feedback is already surfaced on the left).

## Domain notes

- **Submission** — the graded snapshot whose feedback is displayed on the left. Immutable.
- **Document** — the underlying writing surface. Exists independently; the revision editor on the right is seeded from the *submission's* content snapshot, not the live document state.
- **Assignment** — provides context (title, prompt) but not currently surfaced in this view.
- A revised submission creates a new **Submission** record linked to its parent via `parentSubmissionId`. This forms a linear revision chain — the most recent revision is the current submission for grading purposes. Previous revisions are read-only history accessible via the breadcrumb.

## UX sketch

```
┌─────────────────────────────────┬──────────────────────────────────┐
│ ← Back to feedback   Title  77% │         Submit Revised Version → │
├──────────┬──────────────────────┼──────────────────────────────────┤
│  Grade   │  Original essay      │  Your Revision                   │
│  Summary │  (with inline        │  (live editable editor)          │
│          │   highlights)        │                                  │
│  Grade   │                      │                                  │
│  Comments│                      │                                  │
└──────────┴──────────────────────┴──────────────────────────────────┘
```

Route: `/app/submissions/:submissionId/revise`

Left panel — graded submission:
- Grade summary (score, e.g. 77%)
- Rubric breakdown (scores per criterion)
- Original essay text with inline highlights
- Grade comments

Right panel — revision editor:
- Seeded from the graded submission's content snapshot (not the live document). Student starts from what was submitted, incorporating feedback as they edit.
- Full formatting toolbar (bold, italic, strikethrough, headings, alignment, lists, blockquote, horizontal rule, text color, line spacing, clear marks)
- Autosave (debounced → IndexedDB + server sync with revision timer every 5 min of idle editing)
- Auth heartbeat (locks editor if session expires; non-dismissible session-expired dialog with "Log In" preserving redirect URL)
- Editable document title (saves on blur via fetcher POST)
- Version history (clock/saved-status button → full version history sheet)
- Submit button (with submitting state, disabled-when-empty guard, confirmation dialog)

Nav bar:
- "← Back to feedback" link (left)
- Document title + grade badge (center)
- "Submit Revised Version →" button (right)

## What we left out (and why)

- **Tutor sidebar** — the AI tutor/course module flow belongs to the original learning sequence, not the revision context. At revision stage a student is responding to teacher feedback directly; re-engaging the tutor would require a significant redesign. Preserve the option to revisit — there may be value in a future flow where students rework with the tutor as part of a structured revision cycle. Not scoped here.
- **Student inline comments panel** — left panel already surfaces all teacher feedback; a second comments layer would clutter the UI.
- **Assignment prompt banner** — omitted to save vertical space; the submission title serves as a proxy.
- **Previous submissions popover** — left out to keep the nav uncluttered; the grade badge already surfaces the most recent result.
- **Archive dialog** — not relevant in the revision flow.
- **Mobile tab navigation** — side-by-side is a desktop layout; the mobile tab switcher (Tutor / Editor / Comments) doesn't apply.

## Data model implications

`Submission` table gains a nullable `parentSubmissionId` foreign key referencing `Submission(id)`.

- `null` = original submission.
- non-null = revision; references the immediately preceding submission.

Backward-compat migration:
1. Add column nullable, default null. Deploy.
2. No backfill needed — all existing submissions are originals.
3. New writes populate `parentSubmissionId` when a revision is submitted via this flow.

A revision chain is computed by walking parent references. No denormalized chain ID — chains are short (typically 1-2 revisions) and recomputing is cheap.

For grade aggregation: gradebook shows the grade of the most recent revision. Earlier revisions' grades remain attached to those rows for history but don't roll up.

Inline comments are scoped to a single submission. When a student revises, they start with no comments on the new submission. The previous revision's comments are visible read-only on the left panel.

The feature flag is DB-driven via the existing `Setting` table.

To enable:
```sql
INSERT INTO "Setting" (name, value, "valueType")
VALUES ('side_by_side_revision_enabled', 'true', 'boolean');
```

To disable:
```sql
UPDATE "Setting" SET value = 'false' WHERE name = 'side_by_side_revision_enabled';
```

Backward-compat: old `?revise=1` flow stays active until the new flow has been validated in production for a couple of weeks. The feature flag gates which path is served.

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

- `app/routes/app_.submissions_.$submissionId_.revise/route.tsx` — new route
- `app/routes/app_.submissions_.$submissionId/route.tsx` — "Revise Essay" points to new route when flag is on
- `app/utils/feature-flags.server.ts` — `SIDE_BY_SIDE_REVISION` flag + `isSideBySideRevisionEnabled()`
- `e2e/seed-e2e.ts` — seeds the feature flag for e2e tests
- `e2e/tests/student.revision-view.spec.ts` — new e2e tests for the revision view

Reference PR: #102 on `yawp-2.0` (branch `claude/plan-feedback-resubmission-FbxDo`).

## Open questions

- [ ] **Feature flag not seeded in production/preview** — the flag only exists in the e2e seed. Needs a manual SQL insert in any environment where you want to test with real data. Should this be part of a deploy runbook, or should we automate seeding it as disabled-by-default?
- [ ] **E2e tests not yet run** — `e2e/tests/student.revision-view.spec.ts` was written but hasn't been executed in CI or locally. Must be verified before merge.
- [ ] **Submit flow destination** — after submitting a revised essay, the student lands on `/app/submissions/:newSubmissionId`. Needs verification that this route renders a sensible "submission received" or feedback view rather than an error.
- [ ] **Old flow removal timing** — old `?revise=1` flow must stay active during the flag-gated rollout. What's the trigger to remove it? (Suggested: after 2 weeks of production validation with no regressions.) Should we open a follow-up ticket now?

## Edge cases

- Student submits revision while session is expiring — auth heartbeat catches this; session-expired dialog appears, editor locks, redirect preserves URL.
- Student has no graded feedback yet (e.g. navigates directly to `/revise`) — left panel should gracefully handle missing grade data; define empty state.
- Teacher updates grade/comments after student opens the revision view — left panel is a static snapshot of the submission at load time; no live sync needed.
- Document is empty when student hits "Submit Revised Version" — submit button is disabled-when-empty; guard is already in place.
- Rubric has zero criteria — grade summary should not break; handle empty rubric gracefully.
- Student is on mobile and somehow reaches the route — layout will be awkward; consider a redirect or a "best viewed on desktop" banner rather than a broken split view.

## Test plan

- [ ] **E2e (new):** `e2e/tests/student.revision-view.spec.ts` — run against local server before merge.
- [ ] **E2e (regression):** existing student submission + feedback e2e tests still pass with flag off.
- [ ] **Manual QA (flag off):** "Revise Essay" from feedback view still opens old flow.
- [ ] **Manual QA (flag on):** "Revise Essay" opens `/app/submissions/:id/revise`; left panel shows grade + essay; right panel is editable; autosave fires; version history opens; session-expired dialog appears on expired session.
- [ ] **Manual QA:** submit revised version → lands on a sensible view (not an error).
- [ ] **Manual QA:** editable title saves on blur.
- [ ] **Manual QA:** mobile — verify graceful degradation or redirect.

## Rollout

Feature flag `side_by_side_revision_enabled` is DB-driven and off by default.

1. Enable for internal testing (manual SQL insert per environment).
2. Enable for UA professor (highest-volume single user) — watch for regressions.
3. Enable for Washington and Birmingham City pilots after UA validation.
4. Broader rollout once pilot confidence is established.
5. After ~2 weeks of production stability, remove old `?revise=1` flow and the flag.

## Engineering handoff checklist

- [x] Domain context covered
- [x] File paths in `yawp-2.0` listed
- [x] Data model implications spelled out, including backward-compat plan
- [x] UX sketch in prose
- [ ] Edge cases enumerated *(mobile empty state and missing-grade-data handling need answers)*
- [ ] Test plan written *(e2e tests need to actually run)*
- [ ] Rollout plan decided *(open questions above must be resolved first)*