feat(clip): crop a clip to a frame drawn on the picture, and give the clip panel the room it needs

An optional crop in clip mode: a Crop toggle puts a frame on the picture (free, 16:9, 9:16 or 1:1;
the whole picture stays the default). The frame is sent in fractions of the box it was drawn in,
with that box's shape; the worker fits the real picture into the box by its display aspect (sample
aspect and rotation aware), drops the part over the bars, and crops first in the filter chain. A
frame covering the whole box is no crop at all, and one off the picture is refused by name.

The crop frame is a ui primitive (CropFrame) shared with the video editor, keyboard-operable.
YouTube: the wide side panel shuts while clipping and comes back after; maximised, the clip panel
docks in the stage. Plex: the picture sits above the clip panel so the frame lies on it.

frontend/src/components/ClipPanel.dom.test.tsx

@@ -31,7 +31,7 @@ vi.mock("../lib/actionErrors", async (importOriginal) => {
   return { ...actual, notifyActionError: (e: unknown, t: string) => notifyActionError(e, t) };
 });
 
-import ClipPanel, { type ClipSource } from "./ClipPanel";
+import ClipPanel, { type ClipCrop, type ClipSource } from "./ClipPanel";
 
 afterEach(() => {
   cleanup();
@@ -58,15 +58,20 @@ function Harness({
   onSeek?: (t: number, final: boolean) => void;
 }) {
   const [clip, setClip] = useState(start);
+  const [crop, setCrop] = useState<ClipCrop | null>(null);
   return (
     <QueryClientProvider client={new QueryClient()}>
       <output data-testid="range">{`${clip.start}-${clip.end}`}</output>
+      <output data-testid="crop">{crop ? JSON.stringify(crop) : "none"}</output>
       <ClipPanel
         src={src}
         clip={clip}
         onChange={setClip}
         duration={3600}
         current={current}
+        picture={16 / 9}
+        crop={crop}
+        onCrop={setCrop}
         onSeek={onSeek}
         onPlayFrom={onPlayFrom}
         onClose={onClose}
@@ -156,4 +161,41 @@ describe("ClipPanel", () => {
     act(() => rerender(<Harness onPlayFrom={onPlayFrom} current={130.2} />));
     expect(onPlayFrom).toHaveBeenLastCalledWith(100);
   });
+
+  it("cuts the whole picture until the crop is turned on, then the frame with its box's shape", async () => {
+    render(<Harness />);
+    expect(screen.queryByRole("group", { name: "clip.shape" })).toBeNull();
+    fireEvent.click(screen.getByRole("button", { name: "clip.crop" }));
+    expect(screen.getByRole("button", { name: "clip.crop" }).getAttribute("aria-pressed")).toBe(
+      "true",
+    );
+    fireEvent.click(screen.getByRole("button", { name: "clip.cut" }));
+    await waitFor(() => expect(enqueueClip).toHaveBeenCalled());
+    expect(enqueueClip.mock.calls[0]![0].crop).toEqual({
+      x: 0.1,
+      y: 0.1,
+      w: 0.8,
+      h: 0.8,
+      aspect: 1.7778,
+    });
+  });
+
+  it("holds the frame to a shape without cutting, and goes back to the whole picture", () => {
+    render(<Harness />);
+    fireEvent.click(screen.getByRole("button", { name: "clip.crop" }));
+    // A segmented choice inside the panel's form: never a submit.
+    fireEvent.click(screen.getByRole("button", { name: "9:16" }));
+    expect(enqueueClip).not.toHaveBeenCalled();
+    const tall = JSON.parse(screen.getByTestId("crop").textContent!) as ClipCrop;
+    expect(tall.shape).toBe("9:16");
+    expect(tall.rect.h).toBeCloseTo(1, 6);
+    expect((tall.rect.w * 16) / 9 / tall.rect.h).toBeCloseTo(9 / 16, 6);
+    fireEvent.click(screen.getByRole("button", { name: "clip.whole" }));
+    expect(JSON.parse(screen.getByTestId("crop").textContent!)).toEqual({
+      rect: { x: 0, y: 0, w: 1, h: 1 },
+      shape: "free",
+    });
+    fireEvent.click(screen.getByRole("button", { name: "clip.crop" }));
+    expect(screen.getByTestId("crop").textContent).toBe("none");
+  });
 });