feat(review): flag handles in the review player (metadata only)

Renders run 8 frames past the cut at each end. Directors were flagging
glitches in unfixed handles as shot problems, so the player now marks
them — without trimming or burning anything into the EXRs/MOV/MP4.

- Version.handleHead/handleTail/pictureStartFrame, Export.handleHead/
  handleTail; migration backfills pipeline exports and their preview
  versions from the manifest's handleFrames (else 8)
- AE panel: "Includes handles [8] frames each end" -> manifest.review;
  older manifests fall back to source.handleFrames
- finalize copies handles onto the Version; worker 1.6.4 reports the
  head slate length (pictureStartSeconds), else the player infers it
  as MP4 frames - EXR frameCount
- Player: hatched HANDLE / SLATE regions and cut marks on the timeline,
  "HEAD/TAIL HANDLE · NOT IN EDIT" overlay on handle frames, HANDLE badge
  on notes, "Edit range only" toggle (default on in the client portal)
- Staff Handles editor on the review page for manual uploads/corrections

Also fixes two player bugs found while testing: timeToFrame floored
float error (every seek landed a frame early), and J/reverse never ran
(the keyboard effect's cleanup stopped it on the next render).

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

components/versions/VersionHandlesButton.tsx

@@ -0,0 +1,178 @@
+"use client";
+
+import { useState } from "react";
+import { Scissors } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { useToast } from "@/components/ui/use-toast";
+import { updateVersionHandles } from "@/actions/versions";
+import { cn } from "@/lib/utils";
+
+interface VersionHandlesButtonProps {
+  versionId: string;
+  handleHead: number | null;
+  handleTail: number | null;
+  pictureStartFrame: number | null;
+  onSaved?: () => void;
+}
+
+const DEFAULT_HANDLES = 8;
+
+function toInt(value: string): number | null {
+  if (value.trim() === "") return null;
+  const n = Number(value);
+  return Number.isInteger(n) && n >= 0 ? n : NaN;
+}
+
+/**
+ * Top-bar control showing a version's handles, and a dialog to set them —
+ * for manual uploads, or to correct a render. Review metadata only.
+ */
+export function VersionHandlesButton({
+  versionId,
+  handleHead,
+  handleTail,
+  pictureStartFrame,
+  onSaved,
+}: VersionHandlesButtonProps) {
+  const marked = (handleHead ?? 0) > 0 || (handleTail ?? 0) > 0;
+  const [open, setOpen] = useState(false);
+  const [includes, setIncludes] = useState(marked);
+  const [head, setHead] = useState(String(handleHead ?? DEFAULT_HANDLES));
+  const [tail, setTail] = useState(String(handleTail ?? DEFAULT_HANDLES));
+  const [slate, setSlate] = useState(pictureStartFrame == null ? "" : String(pictureStartFrame));
+  const [saving, setSaving] = useState(false);
+  const { toast } = useToast();
+
+  const openDialog = () => {
+    setIncludes(marked);
+    setHead(String(handleHead ?? DEFAULT_HANDLES));
+    setTail(String(handleTail ?? DEFAULT_HANDLES));
+    setSlate(pictureStartFrame == null ? "" : String(pictureStartFrame));
+    setOpen(true);
+  };
+
+  const headN = toInt(head);
+  const tailN = toInt(tail);
+  const slateN = toInt(slate);
+  const invalid =
+    (includes && (headN == null || Number.isNaN(headN) || tailN == null || Number.isNaN(tailN))) ||
+    Number.isNaN(slateN);
+
+  const save = async () => {
+    if (invalid) return;
+    setSaving(true);
+    try {
+      await updateVersionHandles({
+        versionId,
+        handleHead: includes ? headN! : 0,
+        handleTail: includes ? tailN! : 0,
+        pictureStartFrame: slateN,
+      });
+      setOpen(false);
+      onSaved?.();
+    } catch {
+      toast({ title: "Couldn't save handles", variant: "destructive" });
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const label = marked
+    ? handleHead === handleTail
+      ? `Handles ${handleHead}`
+      : `Handles ${handleHead ?? 0}/${handleTail ?? 0}`
+    : "No handles";
+
+  return (
+    <>
+      <Button
+        variant="ghost"
+        size="sm"
+        className={cn("h-7 gap-1 text-xs", marked ? "text-amber-400" : "text-muted-foreground")}
+        onClick={openDialog}
+        title="Frames past the cut that aren't in the edit"
+      >
+        <Scissors className="h-3 w-3" />
+        <span className="hidden sm:inline">{label}</span>
+      </Button>
+
+      <Dialog open={open} onOpenChange={setOpen}>
+        <DialogContent className="sm:max-w-sm">
+          <DialogHeader>
+            <DialogTitle>Handles</DialogTitle>
+            <DialogDescription>
+              Frames rendered past the cut at each end. The player marks them “Handle · Not in
+              edit” so reviewers don&apos;t flag them. Nothing is burned in.
+            </DialogDescription>
+          </DialogHeader>
+
+          <label className="flex items-center gap-2 text-sm">
+            <input
+              type="checkbox"
+              checked={includes}
+              onChange={(e) => setIncludes(e.target.checked)}
+              className="h-4 w-4 accent-amber-500"
+            />
+            This version includes handles
+          </label>
+
+          <div className="grid grid-cols-2 gap-3">
+            <div className="space-y-1">
+              <Label htmlFor="handle-head" className="text-xs">Head (frames)</Label>
+              <Input
+                id="handle-head"
+                inputMode="numeric"
+                value={head}
+                disabled={!includes}
+                onChange={(e) => setHead(e.target.value)}
+              />
+            </div>
+            <div className="space-y-1">
+              <Label htmlFor="handle-tail" className="text-xs">Tail (frames)</Label>
+              <Input
+                id="handle-tail"
+                inputMode="numeric"
+                value={tail}
+                disabled={!includes}
+                onChange={(e) => setTail(e.target.value)}
+              />
+            </div>
+          </div>
+
+          <div className="space-y-1">
+            <Label htmlFor="handle-slate" className="text-xs">Slate frames before the picture</Label>
+            <Input
+              id="handle-slate"
+              inputMode="numeric"
+              placeholder="Auto"
+              value={slate}
+              onChange={(e) => setSlate(e.target.value)}
+            />
+            <p className="text-[11px] text-muted-foreground">
+              Leave blank to detect it (pipeline previews have a 1-frame slate).
+            </p>
+          </div>
+
+          <DialogFooter>
+            <Button variant="ghost" onClick={() => setOpen(false)}>
+              Cancel
+            </Button>
+            <Button onClick={save} disabled={saving || invalid}>
+              {saving ? "Saving…" : "Save"}
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+}