feat(connector): build a QC review session for a whole project

Build QC Review Session (QC section) makes a QC_{shot}_{version} comp
for every shot in the project's QC queue. The export sits over its
earlier versions and plates, and only the export and the main plate are
switched on. Each scene also gets a continuous edit, cut to the edit
with the handles trimmed, and a contact sheet. QC Pass/Fail now act on
the shot comp in the viewer, the selected shot in a scene comp, or the
shot under the playhead in a scene edit, and label the result
green/red. The QC queue now also returns seqTimecodeStart, handleHead
and handleTail.

Compare Versions now lines versions up by EXR timecode, then by file
frame number. It used to use Export.frameStart, which is
timecode-anchored, not 1001-based.

Also includes Keep AEP (panel 2.9.0): Queue Export saves a reduced
.aep copy in each export's version folder.

Panel 2.10.0. Not yet run in After Effects.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

EXT_API_REFERENCE.md

@@ -542,4 +542,5 @@ For reference, the endpoints called by `VFXReviewConnector.jsx`:
 | Retry Export | `POST /api/ext/exports/{id}/retry` (E14) |
 | Regenerate Previews | `POST /api/ext/exports/{id}/regenerate-preview` |
 | Load QC Queue | `GET /api/ext/qc/queue?projectCode={PROJECT_CODE}` (E5) |
+| Build QC Review Session | `GET /api/ext/qc/queue?projectCode={PROJECT_CODE}` (E5): uses `scene`, `episode`, `seqTimecodeStart`, `handleHead`, `handleTail` |
 | QC Pass / QC Fail | `POST /api/ext/exports/{id}/qc` (E4) |

VFXReviewConnector.md

@@ -245,6 +245,7 @@ shot record, and submits it to the farm.
 |---|---|
 | **Urgent** | Priority 20 — claimable outside the render window, ahead of normal jobs |
 | **No preview** | Renders the EXRs but builds no preview, inheriting the previous export's MOV, review MP4 and thumbnail |
+| **Keep AEP** | Saves a reduced copy of the project in the export's version folder (see below) |
 
 **No preview** exists for deliverables framed differently from the review —
 unscaled or un-punched-in EXRs. A preview rebuilt from those frames would be
@@ -255,6 +256,37 @@ package still gets a MOV.
 Leave it unticked for an ordinary submission: the preview is what QC and the
 client review see.
 
+#### Export AEP (Keep AEP)
+
+With **Keep AEP** ticked (the default, remembered per machine), every export
+keeps a copy of the project it was queued from, so the exact comp behind a
+render can be reopened later:
+
+```
+{version folder}/{shotCode}_cmp_TT_{version}.aep    e.g. .../UNG_102_019_010/v005/UNG_102_019_010_cmp_TT_v005.aep
+```
+
+- The copy is **reduced** to the exported comp and everything it uses (nested
+  comps, footage, solids). Everything else in the project is dropped.
+- Nothing is collected. Plates and EXRs stay where they are and the copy links
+  to them by path, so it stays a few MB.
+- It is saved after the export is submitted, into the same version folder the
+  farm renders into. The worker only reads and clears `*.exr` files there, so
+  the `.aep` is never touched. Re-queuing the same version overwrites it, just
+  as the render overwrites the EXRs.
+- AE can only reduce the open project, so the panel does Save As, Reduce Project,
+  Save, and then **reopens your project**. Your project was saved first and is
+  never changed, but the reopen clears undo. Untick **Keep AEP** to skip it.
+- The copy is the project as it was when you queued. The farm still renders
+  your working AEP, so a save made before the job starts goes into the render
+  but not into the copy.
+- Reduce Project keeps only comps that are used as layers. An expression that
+  points at a comp with `comp("Name")`, where that comp isn't nested anywhere,
+  will break in the copy.
+
+If the copy can't be saved, the export is still queued and the status line says
+`AEP not saved: …` with the reason.
+
 ---
 
 ## QC
@@ -267,10 +299,63 @@ QC is per-export: a new export always needs new QC.
 |---|---|
 | **Load QC Queue** | Lists every export in `READY_FOR_QC` for the selected project, oldest first. Entries flagged with a warning count had a non-blocking validation warning worth a closer look. |
 | **Open Render** (or double-click) | Imports that export's actual EXR sequence into a `QC_{shot}_{version}` comp at full res and opens it. Re-selecting an already-imported shot just reopens the comp. |
+| **Compare Versions** | Opens the QC comp and stacks earlier versions of the shot under the export, one layer each (`v003`, `v002`…), lined up by EXR timecode (or frame number). Solo a layer to see that version, or set the top layer to **Difference** to see exactly what changed. With more than one earlier version, a dialog lets you untick the ones you don't need. Versions already in the comp are skipped. |
+| **Build QC Review Session** | Lays out the whole project's QC pass in one go. Every shot in the queue gets its `QC_{shot}_{version}` comp, and each scene gets an edit and a contact sheet. See *QC review session* below. |
 | **Notes** | Sent with the decision. Optional on pass; a fail with no notes asks for confirmation, because the artist only sees what you write here. |
 | **QC Pass** | Marks the version **ready for delivery** and nothing else — nothing is shared to the client, no approval state changes, no task moves. |
 | **QC Fail** | Sets the export to `QC_FAILED` and the comp task to **CHANGES**. The artist fixes and queues a new version; the old export is superseded. |
 
+**Where Compare Versions looks:** next to the export's own render folder (resolved
+as for Open Render), in both on-disk layouts. That means farm version folders
+(`{shot}/v002/`, `{shot}/v003/`…) and the older flat folder with
+`{shot}_cmp_TT_{ver}.#####.exr` side by side. Only versions numbered below the
+export's are used. If earlier exports were written under a different root (see
+*More than one on-disk convention*), they won't be found.
+
+### QC review session
+
+**Build QC Review Session** loads the queue for the selected project. A dialog
+lists its scenes. Ctrl-click a scene to leave it out, or untick *Also import
+earlier versions*. Everything is built in one undo step, under
+`QC_SESSION_{project}` in the Project panel:
+
+| Item | What it is |
+|---|---|
+| `{scene}/shots/QC_{shot}_{version}` | One comp per shot, reusing the comp from Open Render if there is one. The export sits on top, earlier versions under it (`v003`, `v002`…), and the shot's plates at the bottom, found as Build Shot finds them. **Only the export and the main plate (the longest) are switched on.** |
+| `{scene}/QC_EDIT_{scene}` | The scene's shot comps as one continuous edit. Each shot is cut to the edit, with the handles the render carries trimmed off, and has a layer marker with its name. |
+| `{scene}/QC_CONTACT_{scene}` | Every shot of the scene in a grid, each starting at its cut in, with its name under it. |
+| `_footage` | The EXR sequences it imported. Plates already in the project are reused, not imported again. |
+
+A scene is the shot record's scene, which is not always the scene in the shot
+code. Episodic shows group by episode too (`UNG_109_SC013`), and standard ones
+by show (`DH2_VFX_SC033`). Shots run in sequence-timecode order when every shot
+in the scene has one, and in shot-code order otherwise. Only the newest queued
+version of a shot gets a comp; older queued versions appear as earlier versions
+in it.
+
+Plates and earlier versions are lined up with the export by EXR timecode. A
+timecode more than a shot's length away is ignored, because a shot's elements
+can carry unrelated camera timecodes. The file frame number is used next, then
+the export's first frame. Exports from before handles were recorded have no
+handle count, so they play in full in the edit, and the status line counts them.
+
+Running the button again adds anything new to the shot comps and rebuilds the
+scene edits and contact sheets from scratch. Don't do your own work in those
+two comps.
+
+**Approving from the session.** QC Pass and QC Fail act on the shot in front of
+you, without finding it in the list:
+
+- the `QC_{shot}_{version}` comp in the viewer, or
+- the shot layer (or its label) selected in a scene edit or contact sheet, or
+- with nothing selected in a scene edit, the shot under the playhead.
+
+The confirmation names the shot, and a fail with notes is confirmed too when it
+came from the viewer. If a scene comp is active and no shot is picked, nothing
+is sent. Pick a shot, or switch to another comp to use the list selection. After
+a decision, that shot's comp and its layers in the scene comps are labelled
+**green** (pass) or **red** (fail).
+
 Passing an export is what makes it eligible for a delivery package on the web
 app's **Pipeline → Deliveries** page.
 

lib/render-pipeline/qc.ts

@@ -147,7 +147,7 @@ export async function getQCQueue(filter: QCQueueFilter) {
     orderBy: { statusChangedAt: "asc" }, // oldest first — nothing should sit in QC
     take: limit,
     include: {
-      shot: { select: { id: true, shotCode: true, episode: true, scene: true, project: { select: { code: true, name: true } } } },
+      shot: { select: { id: true, shotCode: true, episode: true, scene: true, seqTimecodeStart: true, project: { select: { code: true, name: true } } } },
       validations: { where: { status: { in: ["FAIL", "WARN"] } }, select: { checkName: true, status: true, message: true } },
     },
   });
@@ -167,6 +167,11 @@ export async function getQCQueue(filter: QCQueueFilter) {
       frameStart: e.frameStart,
       frameEnd: e.frameEnd,
       fps: e.fps,
+      // The panel's QC session cuts each shot into a scene edit: in edit order,
+      // with the handles the render carries trimmed off. Null on old exports.
+      seqTimecodeStart: e.shot.seqTimecodeStart,
+      handleHead: e.handleHead,
+      handleTail: e.handleTail,
       deliveryMovPath: e.deliveryMovPath,
       thumbnailUrl: e.thumbnailKey ? `/api/files/${e.thumbnailKey}` : null,
       previewUrl: e.previewMovKey ? `/api/files/${e.previewMovKey}` : null,