Review and correct occurrence tracks in the interface, behind the tracking flag

[mihow]

Summary

This is the interface for occurrence tracking: the tools a person uses to review and correct what tracking did, split out of #1272 so each half can be reviewed on its own. It is based on #1272 and should merge after it.

The tools were shaped by a research partner who used them on a development deployment to build a fully human-checked set of tracks, which is what tracking will be measured against. You can follow a track across captures and see its path, with the earlier and later frames faded by distance. You can find the right occurrence to merge with, build or extend a track by clicking detections capture by capture, correct a wrong frame, and mark a track as complete and accurate.

Everything is behind the project's tracking feature flag, added in #1272. With the flag off, the interface looks like main. With it on, ML data managers and project managers (the people the server reports run_tracking for) can also start a tracking run from the jobs page or a session page.

List of Changes

Change (what a reviewer gets)	Notes
Every tracking surface is hidden unless the project has opted in	One helper, hasProjectFeature / useProjectFeature, gates the tracking cards, film strip and frame menus, extend mode, the path and faded frames, the capture-view panel, the grouping filter and the track columns. With the flag off, the capture view keeps main's tooltip
Start a tracking run from the interface	"Run tracking" in the jobs dialog (a session or a capture set, an optional cost threshold, and whether feature vectors are required) and on the session page. Shown to the people the server reports run_tracking for (ML data managers and project managers). It sends the jobs API body documented in #1272
See a track's path over the capture, with the other frames drawn as faded crops, fainter the further away they are, always beneath the current capture's boxes, and the time offset on the nearest frame each side	Onion-skinned path frames with a fallback when a crop is missing
Merge dialog lists the frames next to a track first, with time, distance, similarity, the tracking cost and the tracker's own verdict; merge several at once; compare crops side by side on hover; open a candidate in the session in a new tab	Sortable Match and Cost columns
Build a track by clicking detections capture by capture	Session view extend mode (?extend=): add, merge a whole track or move one frame, remove, replace, auto-advance, arrow keys, Escape
While extending, every box is coloured by how likely it is the same animal, and the box the tracker would link is marked	Uses capture-matches
Link to a single detection in its original capture, which keeps working after the detection moves to another occurrence	?detection= with a copy-link button
A re-laid-out occurrence panel: identity, then frame position and status, then the actions	"Mark track as complete and accurate" replaces "Mark grouping correct" (translation values only; API names unchanged)
Film-strip frames with each frame's own label and score, the names given across a track, frame position, and a badge on frames without a feature vector
Faster stepping between captures, and a timeline showing where each selected occurrence appears	Neighbouring captures are prefetched
Filter occurrences by confirmed grouping; sort by frames, motion, size change and agreement; export confirmed tracks as CSV
"Extend track" is now "Edit track", marked with a pencil, and opens only for an occurrence the person may edit in this session	Capture toolbar and ?extend= are gated on the same permission as the track edits
"Run tracking" appears for everyone the server says may run it, and the form says which sessions tracking will skip and why	Reads run_tracking from the project's user_permissions (#1272)
Moving a frame shows the destinations ranked by how well that frame matches them, in a dialog wide enough for the ranked columns	Uses merge-candidates?detection=; species names stay on one line
Merge candidates can be sorted by species and by frame count, and a failed or refused load says why instead of asking for a wider scope	Refusals (403) are not retried
After confirming an occurrence from the list, the dialog moves to the next one, in the order the list was opened in	A snapshot of the list's order; stays on the occurrence when it is not in the list
Tracking and other post-processing jobs are named in the jobs list, and the tracks export is offered only on projects that use tracking
Long tracks open quickly: the frame strip shows 20 frames at a time, earliest first, with "Frames i–j of N" and buttons for the first, earlier, later and last frames, and opens on the page holding the frame a ?detection= link points at, which is highlighted	The first page comes from the occurrence detail, later pages from /occurrences/{id}/detections/ (#1272), cached per occurrence under the occurrence query key so track edits refresh them. The strip now runs earliest first (it ran newest first), so a split still moves the chosen frame and everything after it. Frame names and the first and last frame come from the server; extend mode in the session view reads every frame from the path payload instead of the detail

How to test

1. Check out this branch, run yarn install, then yarn tsc --noEmit, yarn lint and yarn test.
2. On a project with the tracking flag off, the occurrence page, the session view and the occurrences list look like main.
3. Turn the flag on, then open a session, select an occurrence and use "Edit track". The other frames appear faded, clicking a box adds it, and the view steps to the next capture.
4. Start "Run tracking" from the jobs page for one session, and watch the job finish.

Part of #1412. Based on #1272.

🤖 Generated with Claude Code

https://claude.ai/code/session_01C7Xf6VPbwWtTumhjjF15g8

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 85a5eced-5505-449b-96a6-6da38d64d33f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[netlify]

✅ Deploy Preview for antenna-preview canceled.

Name	Link
🔨 Latest commit	d098429
🔍 Latest deploy log	https://app.netlify.com/projects/antenna-preview/deploys/6abd5ddf005d0a000834cea8

[mihow]

Claude says: The merge order and plan for tracking, agreed with the owner today, are on #1412: #1412 (comment)

This PR's place: the review and correction interface comes back after #1469 as smaller PRs based on main (#1431, #1433), built from the work here and in #1441.