From dbf8055f0bb4a18edb150ae0e5db6b8af240786c Mon Sep 17 00:00:00 2001
From: baiqing <lbx12309@icloud.com>
Date: Wed, 1 Jul 2026 22:48:23 +0800
Subject: [PATCH] =?UTF-8?q?feat(preview):=20on-canvas=20Transform=20overla?=
 =?UTF-8?q?y=20=E2=80=94=20drag=20to=20move/resize=20the=20selected=20clip?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Port upstream TransformOverlayView: when a single visual clip is selected, draw a
bounding box with 4 corner resize handles + a move surface over the composited
preview canvas, committing to the clip's transform. Faithful to what upstream
ACTUALLY has — corners only (no edge handles) and NO rotation handle (upstream
sets rotation only via the Inspector field; grep atan2/rotationHandle across the
upstream repo = zero hits), so neither is invented.

- clip.ts: moveTransformByDelta (normalized center translate + canvas-edge/center
  snap when unrotated, preserving upstream's single-width-threshold quirk),
  rotateDeltaIntoLocalFrame (R(-theta) so a screen-space corner drag maps into the
  rotated box's local frame; move deltas stay raw, rotation-invariant),
  sampledTransform (topLeft/size/rotation samplers -> center Transform = upstream
  clip.transformAt(frame:), so the box tracks keyframed transform), and
  findSelectedVisualClip. resizeTransformFromCorner reused unchanged. 20 tests.
- TransformOverlay.tsx: the box + handles; container pointerEvents:none with only
  the handles/move-surface interactive (never blocks the preview); local-optimistic
  drag preview, ONE setClipProperties on pointerup (avoids per-move undo-stack
  spam / IPC latency — KeyframesLaneRow's pattern). 6 render tests.
- Preview.tsx: surgical mount inside the canvas div, gated on a single selected
  visual clip. 4 negative-mount tests.

Scope cuts (documented in code): pink center-snap GUIDE LINES (functional snap
ported, guide rendering not); text-clip fontScale resize (no applyTextStyle wired
yet — text resizes via transform). On-canvas drag still needs a real-machine
visual pass (headless/Dock-blocked here); tsc + unit tests are green.

Verified: pnpm build (tsc) clean; pnpm test 239 passed (+30).
---
 web/src/components/preview/Preview.test.tsx   |  65 +++++
 web/src/components/preview/Preview.tsx        |  26 ++
 .../preview/TransformOverlay.test.tsx         | 135 ++++++++++
 .../components/preview/TransformOverlay.tsx   | 214 ++++++++++++++++
 web/src/lib/clip.test.ts                      | 232 +++++++++++++++++-
 web/src/lib/clip.ts                           | 152 ++++++++++++
 6 files changed, 823 insertions(+), 1 deletion(-)
 create mode 100644 web/src/components/preview/TransformOverlay.test.tsx
 create mode 100644 web/src/components/preview/TransformOverlay.tsx

diff --git a/web/src/components/preview/Preview.test.tsx b/web/src/components/preview/Preview.test.tsx
index 245dd7e..18a05a5 100644
--- a/web/src/components/preview/Preview.test.tsx
+++ b/web/src/components/preview/Preview.test.tsx
@@ -11,6 +11,7 @@ const store = vi.hoisted(() => ({
     isPlaying: false,
     isScrubbing: false,
     previewMediaId: null as string | null,
+    selectedClipIds: new Set<string>(),
     setCurrentFrame: vi.fn(),
     setScrubbing: vi.fn(),
     togglePlay: vi.fn(),
@@ -109,6 +110,7 @@ describe("Preview timeline rendering", () => {
       isPlaying: false,
       isScrubbing: false,
       previewMediaId: null,
+      selectedClipIds: new Set<string>(),
     };
     store.media.items = [
       { id: "base", name: "base", type: "video", duration: 10, hasAudio: true, path: "/base.mov" },
@@ -187,4 +189,67 @@ describe("Preview timeline rendering", () => {
     expect(html).toContain("<img");
     expect(html).toContain("pointer-events:none");
   });
+
+  // Note: only the NEGATIVE guard cases are provable here. `renderToStaticMarkup`
+  // never runs `useEffect`, so the ResizeObserver that measures `stageSize` (and
+  // therefore `fittedCanvas`, Preview.tsx:156) never fires — `fittedCanvas` is
+  // always null in this test file, and TransformOverlay correctly (and
+  // deliberately) renders nothing for a degenerate canvas. The POSITIVE
+  // rendering path — given a real canvasPx — is covered by TransformOverlay.test.tsx,
+  // which renders the component directly instead of through Preview's sizing.
+  describe("Transform overlay mount guard (T3-10)", () => {
+    beforeEach(() => {
+      store.timeline = timeline([
+        track({
+          id: "v1",
+          type: "video",
+          clips: [
+            clip({ id: "base-clip", mediaRef: "base", mediaType: "video" }),
+            clip({ id: "text-clip", mediaRef: "base", mediaType: "text", startFrame: 10 }),
+          ],
+        }),
+        track({
+          id: "a1",
+          type: "audio",
+          clips: [clip({ id: "audio-clip", mediaRef: "base", mediaType: "audio", startFrame: 20 })],
+        }),
+      ]);
+    });
+
+    it("stays hidden when no clip is selected", () => {
+      store.ui.selectedClipIds = new Set();
+
+      const html = renderToStaticMarkup(<Preview />);
+
+      expect(html).not.toContain('data-testid="transform-overlay"');
+    });
+
+    it("stays hidden when more than one clip is selected (marquee)", () => {
+      store.ui.selectedClipIds = new Set(["base-clip", "text-clip"]);
+
+      const html = renderToStaticMarkup(<Preview />);
+
+      expect(html).not.toContain('data-testid="transform-overlay"');
+    });
+
+    it("stays hidden when the single selected clip is on an audio track", () => {
+      store.ui.selectedClipIds = new Set(["audio-clip"]);
+
+      const html = renderToStaticMarkup(<Preview />);
+
+      expect(html).not.toContain('data-testid="transform-overlay"');
+    });
+
+    it("stays hidden while viewing a media-library preview, even with a visual clip selected", () => {
+      store.ui.selectedClipIds = new Set(["base-clip"]);
+      store.ui.previewMediaId = "still";
+      store.media.items = [
+        { id: "still", name: "still", type: "image", duration: 1, hasAudio: false, path: "/still.png" },
+      ];
+
+      const html = renderToStaticMarkup(<Preview />);
+
+      expect(html).not.toContain('data-testid="transform-overlay"');
+    });
+  });
 });
diff --git a/web/src/components/preview/Preview.tsx b/web/src/components/preview/Preview.tsx
index b53d84c..286ca68 100644
--- a/web/src/components/preview/Preview.tsx
+++ b/web/src/components/preview/Preview.tsx
@@ -22,6 +22,7 @@ import { useMediaStore } from "../../store/mediaStore";
 import { formatTimecode, totalFrames } from "../../lib/geometry";
 import { assetUrl } from "../../lib/asset";
 import { TimelinePlayback } from "./TimelinePlaybackLayer";
+import { TransformOverlay } from "./TransformOverlay";
 import { aspectFitBox, timelinePreviewCanvasStyle } from "./previewLayerStyles";
 import { useT } from "../../i18n";
 import {
@@ -32,6 +33,7 @@ import {
 } from "../../lib/api";
 import { rustEngineEnabled } from "./rustEngine";
 import { shouldUseRustEngine } from "./timelinePlayback";
+import { findSelectedVisualClip, mediaCanvasAspect } from "../../lib/clip";
 import type { MediaItem } from "../../lib/types";
 
 export function Preview() {
@@ -43,10 +45,27 @@ export function Preview() {
   const setScrubbing = useEditorUiStore((s) => s.setScrubbing);
   const togglePlayTimeline = useEditorUiStore((s) => s.togglePlay);
   const previewMediaId = useEditorUiStore((s) => s.previewMediaId);
+  const selectedClipIds = useEditorUiStore((s) => s.selectedClipIds);
   const pushToast = useEditorUiStore((s) => s.pushToast);
   const previewItem = useMediaStore((s) =>
     previewMediaId ? s.items.find((m) => m.id === previewMediaId) ?? null : null,
   );
+  // The Transform overlay's target clip + media aspect (Inspector.tsx:295-301's
+  // same mediaCanvasAspect lookup pattern, reused so both surfaces agree on
+  // aspect-preserving resize). `transformClip` is null whenever upstream's
+  // TransformOverlayView.selectedClip would also be nil (see clip.ts's
+  // findSelectedVisualClip doc comment) — resolved unconditionally here (cheap)
+  // and gated at render time alongside the timeline-tab / has-content checks.
+  const transformClip = findSelectedVisualClip(timeline, selectedClipIds);
+  const transformMediaItem = useMediaStore((s) =>
+    transformClip ? s.items.find((m) => m.id === transformClip.mediaRef) ?? null : null,
+  );
+  const transformMediaAspect = mediaCanvasAspect(
+    transformMediaItem?.width,
+    transformMediaItem?.height,
+    timeline.width,
+    timeline.height,
+  );
 
   // Media-preview playback is driven by the app transport (more capable than the
   // <video>'s native controls), so the <video>/<audio> renders WITHOUT controls
@@ -179,6 +198,13 @@ export function Preview() {
               <>
                 <TimelinePlayback timeline={timeline} fps={fps} />
                 <TimelineRustOverlay />
+                {transformClip && fittedCanvas && (
+                  <TransformOverlay
+                    clip={transformClip}
+                    canvasPx={fittedCanvas}
+                    mediaAspect={transformMediaAspect}
+                  />
+                )}
               </>
             ) : (
               // Empty timeline: a framed 16:9 canvas surface placeholder.
diff --git a/web/src/components/preview/TransformOverlay.test.tsx b/web/src/components/preview/TransformOverlay.test.tsx
new file mode 100644
index 0000000..57237ee
--- /dev/null
+++ b/web/src/components/preview/TransformOverlay.test.tsx
@@ -0,0 +1,135 @@
+/**
+ * TransformOverlay (T3-10) render tests. Renders the component directly with
+ * an explicit `canvasPx`, instead of through <Preview/>'s ResizeObserver-driven
+ * `fittedCanvas` — `renderToStaticMarkup` never runs `useEffect`, so that value
+ * is always null in Preview.test.tsx and can't exercise the positive render
+ * path there. See Preview.test.tsx's "Transform overlay mount guard" describe
+ * block for the (negative-only) guard coverage at the Preview.tsx level.
+ */
+import React from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it, vi } from "vitest";
+import type { Clip } from "../../lib/types";
+
+const uiStore = vi.hoisted(() => ({ activeFrame: 0 }));
+
+vi.mock("../../store/uiStore", () => ({
+  useEditorUiStore: Object.assign((selector: (state: typeof uiStore) => unknown) => selector(uiStore), {
+    getState: () => uiStore,
+  }),
+}));
+
+vi.mock("../../store/editActions", () => ({
+  setClipProperties: vi.fn(),
+}));
+
+import { TransformOverlay } from "./TransformOverlay";
+
+function clip(over: Partial<Clip> = {}): Clip {
+  return {
+    id: "clip",
+    mediaRef: "asset",
+    mediaType: "video",
+    sourceClipType: "video",
+    startFrame: 0,
+    durationFrames: 100,
+    trimStartFrame: 0,
+    trimEndFrame: 0,
+    speed: 1,
+    volume: 1,
+    fadeInFrames: 0,
+    fadeOutFrames: 0,
+    fadeInInterpolation: "smooth",
+    fadeOutInterpolation: "smooth",
+    opacity: 1,
+    transform: {
+      centerX: 0.5,
+      centerY: 0.5,
+      width: 0.4,
+      height: 0.3,
+      rotation: 0,
+      flipHorizontal: false,
+      flipVertical: false,
+    },
+    crop: { left: 0, top: 0, right: 0, bottom: 0 },
+    ...over,
+  };
+}
+
+describe("TransformOverlay", () => {
+  it("positions and sizes the box from transform * canvasPx", () => {
+    const html = renderToStaticMarkup(
+      <TransformOverlay clip={clip()} canvasPx={{ width: 1000, height: 500 }} mediaAspect={null} />,
+    );
+
+    expect(html).toContain('data-testid="transform-overlay"');
+    expect(html).toContain("left:500"); // centerX(0.5) * 1000
+    expect(html).toContain("top:250"); // centerY(0.5) * 500
+    expect(html).toContain("width:400"); // width(0.4) * 1000
+    expect(html).toContain("height:150"); // height(0.3) * 500
+    expect(html).toContain("translate(-50%, -50%) rotate(0deg)");
+  });
+
+  it("rotates the box via the transform's rotation degrees", () => {
+    const html = renderToStaticMarkup(
+      <TransformOverlay
+        clip={clip({ transform: { ...clip().transform, rotation: 45 } })}
+        canvasPx={{ width: 1000, height: 500 }}
+        mediaAspect={null}
+      />,
+    );
+
+    expect(html).toContain("rotate(45deg)");
+  });
+
+  it("renders 4 corner handles at the OpenTake spacing/opacity tokens matching upstream AppTheme.Spacing.smMd / Opacity.strong", () => {
+    const html = renderToStaticMarkup(
+      <TransformOverlay clip={clip()} canvasPx={{ width: 1000, height: 500 }} mediaAspect={null} />,
+    );
+
+    expect(html.match(/cursor:nwse-resize/g)?.length).toBe(2); // topLeft + bottomRight
+    expect(html.match(/cursor:nesw-resize/g)?.length).toBe(2); // topRight + bottomLeft
+    expect(html).toContain("width:8px;height:8px"); // AppTheme.Spacing.smMd
+    expect(html).toContain("background:rgba(255,255,255,0.55)"); // white @ Opacity.strong
+    expect(html).toContain("border:1px solid rgba(255,255,255,0.55)"); // BorderWidth.thin
+  });
+
+  it("keeps the outer container pointer-events:none and only the move-surface/handles pointer-events:auto", () => {
+    const html = renderToStaticMarkup(
+      <TransformOverlay clip={clip()} canvasPx={{ width: 1000, height: 500 }} mediaAspect={null} />,
+    );
+    const overlayStart = html.indexOf('data-testid="transform-overlay"');
+
+    // The outer <div data-testid=...> itself carries pointer-events:none.
+    expect(html.slice(overlayStart, overlayStart + 300)).toContain("pointer-events:none");
+    // 1 move-surface + 4 corner handles = 5 pointer-events:auto elements.
+    expect(html.match(/pointer-events:auto/g)?.length).toBe(5);
+  });
+
+  it("follows a live keyframe track (sampledTransform), not the static transform, when one is active", () => {
+    uiStore.activeFrame = 60;
+    const animated = clip({
+      startFrame: 0,
+      positionTrack: {
+        keyframes: [{ frame: 60, value: { a: 0.1, b: 0.2 }, interpolationOut: "hold" }],
+      },
+    });
+
+    const html = renderToStaticMarkup(
+      <TransformOverlay clip={animated} canvasPx={{ width: 1000, height: 1000 }} mediaAspect={null} />,
+    );
+
+    // topLeft (0.1, 0.2) + half of the static size (0.4/2, 0.3/2) = center (0.3, 0.35).
+    expect(html).toContain("left:300");
+    expect(html).toContain("top:350");
+    uiStore.activeFrame = 0;
+  });
+
+  it("renders nothing for a degenerate (zero-size) canvas", () => {
+    const html = renderToStaticMarkup(
+      <TransformOverlay clip={clip()} canvasPx={{ width: 0, height: 0 }} mediaAspect={null} />,
+    );
+
+    expect(html).toBe("");
+  });
+});
diff --git a/web/src/components/preview/TransformOverlay.tsx b/web/src/components/preview/TransformOverlay.tsx
new file mode 100644
index 0000000..d6e4b94
--- /dev/null
+++ b/web/src/components/preview/TransformOverlay.tsx
@@ -0,0 +1,214 @@
+/**
+ * TransformOverlay (T3-10). On-canvas Transform manipulation for the single
+ * selected visual clip: a bounding box with 4 corner resize handles and a
+ * move-drag surface, mounted as an add-on layer over the composited preview
+ * canvas. 1:1 port of upstream TransformOverlayView.swift's ACTUAL behavior —
+ * see clip.ts's moveTransformByDelta/rotateDeltaIntoLocalFrame/sampledTransform
+ * doc comments for exact upstream line references.
+ *
+ * Two things upstream's file does NOT have, despite being easy to assume from
+ * a casual feature description: edge (midpoint) handles and a rotation handle.
+ * It only has `ForEach(Corner.allCases)` — 4 corners, nothing else — and there
+ * is zero rotation-gesture code (`atan2`, a rotation handle view, etc.) anywhere
+ * in the upstream repo. Rotation is Inspector-only (see Inspector.tsx's
+ * rotation ScrubbableNumberField, already existing, unrelated to this file).
+ * Neither is invented here.
+ *
+ * Pointer drags use window pointermove/up listeners + a cleanup ref + an
+ * unmount-safety effect (KeyframesLaneRow.tsx's drag pattern). Every move
+ * updates only local state so the box tracks the cursor live; the actual clip
+ * commits via ONE `setClipProperties` call on release. `setClipProperties`
+ * round-trips through Tauri IPC and clones the whole Timeline for the undo
+ * stack (see project CLAUDE.md), so calling it per pointermove would spam the
+ * undo stack and add IPC latency to every frame of the drag — the same
+ * reasoning KeyframesLaneRow already applies to `moveKeyframe`.
+ */
+
+import { useEffect, useRef, useState } from "react";
+import { useEditorUiStore } from "../../store/uiStore";
+import * as edit from "../../store/editActions";
+import {
+  moveTransformByDelta,
+  resizeTransformFromCorner,
+  rotateDeltaIntoLocalFrame,
+  sampledTransform,
+  type TransformResizeCorner,
+} from "../../lib/clip";
+import { SNAP, SPACE } from "../../lib/theme";
+import type { Clip, Transform } from "../../lib/types";
+
+/** AppTheme.Spacing.smMd (TransformOverlayView.swift:6). */
+const HANDLE_SIZE = SPACE.smMd;
+/** white @ AppTheme.Opacity.strong (TransformOverlayView.swift:7). */
+const BORDER_COLOR = "rgba(255,255,255,0.55)";
+/** AppTheme.BorderWidth.thin (TransformOverlayView.swift:31). */
+const BORDER_WIDTH = 1;
+
+const CORNERS: TransformResizeCorner[] = ["topLeft", "topRight", "bottomLeft", "bottomRight"];
+
+const CORNER_POSITION: Record<TransformResizeCorner, { left: string; top: string }> = {
+  topLeft: { left: "0%", top: "0%" },
+  topRight: { left: "100%", top: "0%" },
+  bottomLeft: { left: "0%", top: "100%" },
+  bottomRight: { left: "100%", top: "100%" },
+};
+
+const CORNER_CURSOR: Record<TransformResizeCorner, string> = {
+  topLeft: "nwse-resize",
+  bottomRight: "nwse-resize",
+  topRight: "nesw-resize",
+  bottomLeft: "nesw-resize",
+};
+
+export function TransformOverlay({
+  clip,
+  canvasPx,
+  mediaAspect,
+}: {
+  clip: Clip;
+  canvasPx: { width: number; height: number };
+  mediaAspect: number | null;
+}) {
+  const activeFrame = useEditorUiStore((s) => s.activeFrame);
+  // Live-sampled rest position (matches upstream `clip.transformAt(frame:)`) —
+  // follows keyframed position/scale/rotation tracks the same way the actual
+  // composited frame does, so the box always aligns with the rendered clip.
+  const restTransform = sampledTransform(clip, activeFrame);
+  const [dragTransform, setDragTransform] = useState<Transform | null>(null);
+  const dragCleanupRef = useRef<(() => void) | null>(null);
+
+  // Selection moved to a different clip mid-drag (e.g. clicked elsewhere) —
+  // don't let a stale local preview from the PREVIOUS clip leak onto this one.
+  useEffect(() => {
+    setDragTransform(null);
+  }, [clip.id]);
+
+  // Unmount safety: remove any active drag's window listeners.
+  useEffect(() => {
+    return () => {
+      dragCleanupRef.current?.();
+      dragCleanupRef.current = null;
+    };
+  }, []);
+
+  const display = dragTransform ?? restTransform;
+
+  // Shared drag scaffolding: registers window pointermove/up, feeds each move's
+  // pixel delta through `computeNext` for live local preview, and commits once
+  // via setClipProperties on release. `computeNext` carries the move-vs-resize
+  // math difference; the listener lifecycle is identical for both.
+  const beginDrag = (
+    e: React.PointerEvent,
+    computeNext: (dxPx: number, dyPx: number) => Transform,
+  ) => {
+    e.stopPropagation();
+    e.preventDefault();
+    const startClientX = e.clientX;
+    const startClientY = e.clientY;
+    const onMove = (ev: PointerEvent) => {
+      setDragTransform(computeNext(ev.clientX - startClientX, ev.clientY - startClientY));
+    };
+    const onUp = () => {
+      window.removeEventListener("pointermove", onMove);
+      window.removeEventListener("pointerup", onUp);
+      dragCleanupRef.current = null;
+      setDragTransform((cur) => {
+        if (cur) void edit.setClipProperties([clip.id], { transform: cur });
+        return null;
+      });
+    };
+    window.addEventListener("pointermove", onMove);
+    window.addEventListener("pointerup", onUp);
+    dragCleanupRef.current = () => {
+      window.removeEventListener("pointermove", onMove);
+      window.removeEventListener("pointerup", onUp);
+    };
+  };
+
+  const handleMoveDown = (e: React.PointerEvent) => {
+    const start = restTransform;
+    const rotated = start.rotation !== 0;
+    beginDrag(e, (dx, dy) =>
+      moveTransformByDelta(start, { width: dx, height: dy }, canvasPx, rotated, SNAP.thresholdPixels),
+    );
+  };
+
+  const handleResizeDown = (e: React.PointerEvent, corner: TransformResizeCorner) => {
+    const start = restTransform;
+    const rotated = start.rotation !== 0;
+    beginDrag(e, (dx, dy) => {
+      // Corner handles rotate with the box on screen, so a raw screen-space
+      // delta must be rotated into the box's own local frame first — see
+      // rotateDeltaIntoLocalFrame's doc comment for why move doesn't need this.
+      const local = rotateDeltaIntoLocalFrame({ width: dx, height: dy }, start.rotation);
+      return resizeTransformFromCorner(
+        start,
+        corner,
+        local,
+        canvasPx,
+        mediaAspect,
+        rotated,
+        SNAP.thresholdPixels,
+      );
+    });
+  };
+
+  if (
+    !Number.isFinite(canvasPx.width) ||
+    !Number.isFinite(canvasPx.height) ||
+    canvasPx.width <= 0 ||
+    canvasPx.height <= 0
+  ) {
+    return null;
+  }
+
+  return (
+    <div
+      data-testid="transform-overlay"
+      style={{
+        position: "absolute",
+        left: display.centerX * canvasPx.width,
+        top: display.centerY * canvasPx.height,
+        width: display.width * canvasPx.width,
+        height: display.height * canvasPx.height,
+        // translate first centers the (still-unrotated) box on the point,
+        // then rotate turns it around its own center — same idiom already
+        // used for keyframe diamonds (KeyframesLaneRow.tsx).
+        transform: `translate(-50%, -50%) rotate(${display.rotation}deg)`,
+        pointerEvents: "none",
+        zIndex: 3,
+      }}
+    >
+      {/* Move-drag surface + visual outline in one element (upstream's box
+          border, TransformOverlayView.swift:30-31). */}
+      <div
+        onPointerDown={handleMoveDown}
+        style={{
+          position: "absolute",
+          inset: 0,
+          border: `${BORDER_WIDTH}px solid ${BORDER_COLOR}`,
+          cursor: "move",
+          pointerEvents: "auto",
+        }}
+      />
+      {CORNERS.map((corner) => (
+        <div
+          key={corner}
+          onPointerDown={(e) => handleResizeDown(e, corner)}
+          style={{
+            position: "absolute",
+            left: CORNER_POSITION[corner].left,
+            top: CORNER_POSITION[corner].top,
+            width: HANDLE_SIZE,
+            height: HANDLE_SIZE,
+            marginLeft: -HANDLE_SIZE / 2,
+            marginTop: -HANDLE_SIZE / 2,
+            background: BORDER_COLOR,
+            cursor: CORNER_CURSOR[corner],
+            pointerEvents: "auto",
+          }}
+        />
+      ))}
+    </div>
+  );
+}
diff --git a/web/src/lib/clip.test.ts b/web/src/lib/clip.test.ts
index 0e6b435..5630d91 100644
--- a/web/src/lib/clip.test.ts
+++ b/web/src/lib/clip.test.ts
@@ -1,13 +1,65 @@
 import { describe, expect, it } from "vitest";
 import {
   clampTrimDeltaFrames,
+  findSelectedVisualClip,
   fitTransformForMedia,
   mediaCanvasAspect,
+  moveTransformByDelta,
   resizeTransformKeepingSourceAspect,
+  rotateDeltaIntoLocalFrame,
+  sampledTransform,
   trimSourceValues,
   trimToPlayheadEdits,
 } from "./clip";
-import type { Clip, ClipType } from "./types";
+import type { Clip, ClipType, Timeline, Track, Transform } from "./types";
+
+/** Full-Clip fixture, matching previewLayerStyles.test.ts / Preview.test.tsx's
+ *  shape so fixtures stay consistent across the codebase. */
+function clip(over: Partial<Clip> = {}): Clip {
+  return {
+    id: "clip",
+    mediaRef: "asset",
+    mediaType: "video",
+    sourceClipType: "video",
+    startFrame: 0,
+    durationFrames: 100,
+    trimStartFrame: 0,
+    trimEndFrame: 0,
+    speed: 1,
+    volume: 1,
+    fadeInFrames: 0,
+    fadeOutFrames: 0,
+    fadeInInterpolation: "smooth",
+    fadeOutInterpolation: "smooth",
+    opacity: 1,
+    transform: {
+      centerX: 0.5,
+      centerY: 0.5,
+      width: 1,
+      height: 1,
+      rotation: 0,
+      flipHorizontal: false,
+      flipVertical: false,
+    },
+    crop: { left: 0, top: 0, right: 0, bottom: 0 },
+    ...over,
+  };
+}
+
+function track(over: Partial<Track> & { id: string; type: ClipType; clips: Clip[] }): Track {
+  return {
+    id: over.id,
+    type: over.type,
+    muted: over.muted ?? false,
+    hidden: over.hidden ?? false,
+    syncLocked: over.syncLocked ?? true,
+    clips: over.clips,
+  };
+}
+
+function timeline(tracks: Track[]): Timeline {
+  return { fps: 30, width: 1920, height: 1080, settingsConfigured: true, tracks };
+}
 
 function tc(over: Partial<{ durationFrames: number; speed: number; trimStartFrame: number; trimEndFrame: number; mediaType: ClipType }> = {}) {
   return {
@@ -165,3 +217,181 @@ describe("media aspect transform helpers", () => {
     });
   });
 });
+
+describe("sampledTransform (upstream Clip.transformAt(frame:) port)", () => {
+  it("with no active tracks, recomposes the clip's static transform unchanged", () => {
+    const c = clip({
+      transform: {
+        centerX: 0.3,
+        centerY: 0.7,
+        width: 0.4,
+        height: 0.25,
+        rotation: 15,
+        flipHorizontal: true,
+        flipVertical: false,
+      },
+    });
+    const s = sampledTransform(c, 0);
+    expect(s.centerX).toBeCloseTo(c.transform.centerX);
+    expect(s.centerY).toBeCloseTo(c.transform.centerY);
+    expect(s.width).toBe(c.transform.width);
+    expect(s.height).toBe(c.transform.height);
+    expect(s.rotation).toBe(c.transform.rotation);
+    expect(s.flipHorizontal).toBe(c.transform.flipHorizontal);
+    expect(s.flipVertical).toBe(c.transform.flipVertical);
+  });
+
+  it("follows an active position/scale/rotation track at an exact keyframe", () => {
+    const c = clip({
+      startFrame: 100,
+      positionTrack: {
+        keyframes: [
+          { frame: 0, value: { a: 0.1, b: 0.2 }, interpolationOut: "linear" },
+          { frame: 50, value: { a: 0.6, b: 0.1 }, interpolationOut: "hold" },
+        ],
+      },
+      scaleTrack: {
+        keyframes: [{ frame: 0, value: { a: 0.5, b: 0.3 }, interpolationOut: "hold" }],
+      },
+      rotationTrack: {
+        keyframes: [
+          { frame: 0, value: 45, interpolationOut: "hold" },
+          { frame: 50, value: 45, interpolationOut: "hold" },
+        ],
+      },
+    });
+
+    // Absolute frame 150 = clip-relative 50 = the second (held) keyframe.
+    const s = sampledTransform(c, 150);
+    expect(s.rotation).toBe(45);
+    expect(s.width).toBeCloseTo(0.5);
+    expect(s.height).toBeCloseTo(0.3);
+    // topLeftAt returns the sampled position directly; center = topLeft + size/2.
+    expect(s.centerX).toBeCloseTo(0.6 + 0.5 / 2);
+    expect(s.centerY).toBeCloseTo(0.1 + 0.3 / 2);
+  });
+
+  it("passes flipHorizontal/flipVertical through from the static transform (never keyframed)", () => {
+    const c = clip({ transform: { ...clip().transform, flipHorizontal: true, flipVertical: true } });
+    const s = sampledTransform(c, 0);
+    expect(s.flipHorizontal).toBe(true);
+    expect(s.flipVertical).toBe(true);
+  });
+});
+
+describe("moveTransformByDelta (upstream TransformOverlayView.movedTransform port)", () => {
+  const canvas = { width: 1000, height: 1000 };
+  const start: Transform = {
+    centerX: 0.5,
+    centerY: 0.5,
+    width: 0.2,
+    height: 0.2,
+    rotation: 0,
+    flipHorizontal: false,
+    flipVertical: false,
+  };
+
+  it("translates the center by delta/canvasPx on each axis", () => {
+    const moved = moveTransformByDelta(start, { width: 100, height: 50 }, canvas, false);
+    expect(moved.centerX).toBeCloseTo(0.6);
+    expect(moved.centerY).toBeCloseTo(0.55);
+    expect(moved.width).toBe(0.2);
+    expect(moved.height).toBe(0.2);
+  });
+
+  it("snaps the left edge to the canvas boundary within threshold", () => {
+    // topLeft.x after translate = 0.5-0.1 + delta/1000. Land it 3px from x=0.
+    const moved = moveTransformByDelta(start, { width: -397, height: 0 }, canvas, false, 8);
+    expect(moved.centerX).toBeCloseTo(0.1); // left edge pinned to exactly 0
+  });
+
+  it("snaps the center to the canvas center within threshold", () => {
+    const nudged = { ...start, centerX: 0.503, centerY: 0.497 };
+    const moved = moveTransformByDelta(nudged, { width: 0, height: 0 }, canvas, false, 8);
+    expect(moved.centerX).toBe(0.5);
+    expect(moved.centerY).toBe(0.5);
+  });
+
+  it("skips all snapping while rotated, even within threshold", () => {
+    const rotatedStart: Transform = { ...start, rotation: 30, centerX: 0.503 };
+    const moved = moveTransformByDelta(rotatedStart, { width: 0, height: 0 }, canvas, true, 8);
+    expect(moved.centerX).toBe(0.503); // not snapped to 0.5
+  });
+
+  it("skips snapping when snapThresholdPx is omitted (defaults to 0)", () => {
+    const nudged = { ...start, centerX: 0.5001 };
+    const moved = moveTransformByDelta(nudged, { width: 0, height: 0 }, canvas, false);
+    expect(moved.centerX).toBe(0.5001);
+  });
+
+  it("returns start unchanged for a degenerate (zero-size) canvas", () => {
+    expect(moveTransformByDelta(start, { width: 50, height: 50 }, { width: 0, height: 0 }, false)).toBe(start);
+  });
+});
+
+describe("rotateDeltaIntoLocalFrame", () => {
+  it("is the identity at 0 degrees", () => {
+    expect(rotateDeltaIntoLocalFrame({ width: 12, height: -7 }, 0)).toEqual({ width: 12, height: -7 });
+  });
+
+  it("maps a screen-down drag to local +X at 90 degrees (box rotated 90deg CW)", () => {
+    const local = rotateDeltaIntoLocalFrame({ width: 0, height: 10 }, 90);
+    expect(local.width).toBeCloseTo(10);
+    expect(local.height).toBeCloseTo(0);
+  });
+
+  it("negates both axes at 180 degrees", () => {
+    const local = rotateDeltaIntoLocalFrame({ width: 5, height: 3 }, 180);
+    expect(local.width).toBeCloseTo(-5);
+    expect(local.height).toBeCloseTo(-3);
+  });
+
+  it("maps a screen-down drag to local -X at -90 degrees", () => {
+    const local = rotateDeltaIntoLocalFrame({ width: 0, height: 10 }, -90);
+    expect(local.width).toBeCloseTo(-10);
+    expect(local.height).toBeCloseTo(0);
+  });
+
+  it("preserves vector magnitude at a non-axis-aligned angle", () => {
+    const input = { width: 8, height: -6 };
+    const local = rotateDeltaIntoLocalFrame(input, 37);
+    const beforeMag = Math.hypot(input.width, input.height);
+    const afterMag = Math.hypot(local.width, local.height);
+    expect(afterMag).toBeCloseTo(beforeMag);
+  });
+});
+
+describe("findSelectedVisualClip", () => {
+  const visual = clip({ id: "v1", mediaType: "video" });
+  const textClip = clip({ id: "t1", mediaType: "text" });
+  const audioClip = clip({ id: "a1", mediaType: "audio" });
+  const tl = timeline([
+    track({ id: "vt", type: "video", clips: [visual, textClip] }),
+    track({ id: "at", type: "audio", clips: [audioClip] }),
+  ]);
+
+  it("resolves the single selected visual clip", () => {
+    expect(findSelectedVisualClip(tl, new Set(["v1"]))).toBe(visual);
+    expect(findSelectedVisualClip(tl, new Set(["t1"]))).toBe(textClip);
+  });
+
+  it("returns null when the single selected clip is on an audio track", () => {
+    expect(findSelectedVisualClip(tl, new Set(["a1"]))).toBeNull();
+  });
+
+  it("returns null when zero clips are selected", () => {
+    expect(findSelectedVisualClip(tl, new Set())).toBeNull();
+  });
+
+  it("returns null when more than one clip is selected (marquee)", () => {
+    expect(findSelectedVisualClip(tl, new Set(["v1", "t1"]))).toBeNull();
+  });
+
+  it("returns null when selectedClipIds is undefined (defensive for test-store mocks)", () => {
+    expect(findSelectedVisualClip(tl, undefined)).toBeNull();
+  });
+
+  it("returns null for an id that doesn't exist in the timeline", () => {
+    expect(findSelectedVisualClip(tl, new Set(["missing"]))).toBeNull();
+  });
+});
diff --git a/web/src/lib/clip.ts b/web/src/lib/clip.ts
index dbac19c..8d4f818 100644
--- a/web/src/lib/clip.ts
+++ b/web/src/lib/clip.ts
@@ -271,6 +271,107 @@ export function resizeTransformFromCorner(
   );
 }
 
+/** Snap clip edges to canvas boundaries (0 or 1). 1:1 port of upstream
+ *  `Transform.snapToCanvasEdges(threshold:)` (Models/Timeline.swift:463-481) —
+ *  including its one quirk: both axes share the single `threshold` the caller
+ *  passes (upstream's own `movedTransform` only derives it from canvas WIDTH,
+ *  never height, even for the vertical check). Preserved as-is; not "fixed". */
+function snapTransformToCanvasEdges(t: Transform, threshold: number): Transform {
+  const tl = topLeftForTransform(t);
+  let centerX = t.centerX;
+  const snappedLeft = snapToBoundary(tl.x, threshold);
+  const snappedRight = snapToBoundary(tl.x + t.width, threshold);
+  if (snappedLeft !== tl.x) {
+    centerX -= tl.x - snappedLeft;
+  } else if (snappedRight !== tl.x + t.width) {
+    centerX -= tl.x + t.width - snappedRight;
+  }
+
+  const tl2 = topLeftForTransform({ ...t, centerX });
+  let centerY = t.centerY;
+  const snappedTop = snapToBoundary(tl2.y, threshold);
+  const snappedBottom = snapToBoundary(tl2.y + t.height, threshold);
+  if (snappedTop !== tl2.y) {
+    centerY -= tl2.y - snappedTop;
+  } else if (snappedBottom !== tl2.y + t.height) {
+    centerY -= tl2.y + t.height - snappedBottom;
+  }
+  return { ...t, centerX, centerY };
+}
+
+/** Snap the clip's center to the canvas center (0.5, 0.5) per axis within
+ *  threshold. 1:1 port of upstream `Transform.snapCenterToCanvasCenter`
+ *  (Models/Timeline.swift:484-497), minus the `(x,y)` snapped-flags return —
+ *  OpenTake doesn't port upstream's pink center-guide lines (TransformOverlayView
+ *  centerGuideX/Y), only the functional snap that affects landing position. */
+function snapTransformCenterToCanvasCenter(t: Transform, thresholdH: number, thresholdV: number): Transform {
+  let centerX = t.centerX;
+  let centerY = t.centerY;
+  if (Math.abs(centerX - 0.5) < thresholdH) centerX = 0.5;
+  if (Math.abs(centerY - 0.5) < thresholdV) centerY = 0.5;
+  return { ...t, centerX, centerY };
+}
+
+/** Upstream TransformOverlayView `movedTransform` port (private func,
+ *  TransformOverlayView.swift:98-113). Translates the clip's center by a pixel
+ *  delta, then — only when not rotated — snaps edges to the canvas boundary and
+ *  the center to the canvas center, both using `snapThresholdPx` (0 = no snap,
+ *  matching `resizeTransformFromCorner`'s convention). Used by the on-canvas
+ *  move-drag; corner resizes go through `resizeTransformFromCorner` instead. */
+export function moveTransformByDelta(
+  start: Transform,
+  deltaPx: { width: number; height: number },
+  canvasPx: { width: number; height: number },
+  rotated: boolean,
+  snapThresholdPx = 0,
+): Transform {
+  if (!positiveFinite(canvasPx.width) || !positiveFinite(canvasPx.height)) return start;
+  const moved: Transform = {
+    ...start,
+    centerX: start.centerX + deltaPx.width / canvasPx.width,
+    centerY: start.centerY + deltaPx.height / canvasPx.height,
+  };
+  if (rotated || snapThresholdPx <= 0) return moved;
+  const edgeSnapped = snapTransformToCanvasEdges(moved, snapThresholdPx / canvasPx.width);
+  return snapTransformCenterToCanvasCenter(
+    edgeSnapped,
+    snapThresholdPx / canvasPx.width,
+    snapThresholdPx / canvasPx.height,
+  );
+}
+
+/**
+ * Rotates a screen-space pointer delta into the transform box's own (unrotated)
+ * local frame — the inverse of the box's CSS `rotate(rotationDegrees)` (positive
+ * = clockwise, matching `Transform.rotation`'s upstream doc comment).
+ *
+ * Only the corner-resize drag needs this. Upstream nests its 4 corner handles
+ * inside the box's rotated `ZStack` ancestor (TransformOverlayView.swift:29-43),
+ * so SwiftUI's local-space `DragGesture` translation arrives already rotated
+ * into the box's frame before `resizedTransform` ever sees it. A raw web pointer
+ * delta (`clientX`/`clientY`) has no such compensation, so this applies it
+ * explicitly before the delta reaches `resizeTransformFromCorner`.
+ *
+ * The move gesture does NOT need this: upstream deliberately keeps its move
+ * hit-target OUTSIDE the rotated ZStack (a sibling view sized to the rotated
+ * AABB with a custom `contentShape`, TransformOverlayView.swift:20-27,284-295),
+ * so its translation is raw screen-space too — translating a box's center by a
+ * screen delta is rotation-invariant regardless, so this would be a no-op there.
+ */
+export function rotateDeltaIntoLocalFrame(
+  deltaPx: { width: number; height: number },
+  rotationDegrees: number,
+): { width: number; height: number } {
+  if (rotationDegrees === 0) return deltaPx;
+  const theta = (rotationDegrees * Math.PI) / 180;
+  const cos = Math.cos(theta);
+  const sin = Math.sin(theta);
+  return {
+    width: deltaPx.width * cos + deltaPx.height * sin,
+    height: -deltaPx.width * sin + deltaPx.height * cos,
+  };
+}
+
 /** Which edge a trim drag grabs. */
 export type TrimEdge = "left" | "right";
 
@@ -555,6 +656,29 @@ export function cropAt(clip: Clip, frame: number): Crop {
   return sampleCropTrack(clip.cropTrack, keyframeOffset(clip, frame), clip.crop);
 }
 
+/**
+ * Live-sampled `Transform` at `frame`, incorporating any active position/scale/
+ * rotation keyframe tracks — 1:1 port of upstream `Clip.transformAt(frame:)`,
+ * composed from the already-ported `topLeftAt`/`sizeAt`/`rotationAt` samplers.
+ * `flipHorizontal`/`flipVertical` are never keyframed, so they pass through
+ * from the clip's static `transform` unchanged. Used by the on-canvas Transform
+ * overlay to seed its box position/size/rotation and each drag's start value
+ * (TransformOverlayView.swift:14-16,77,119: `clip.transformAt(frame:)`).
+ */
+export function sampledTransform(clip: Clip, frame: number): Transform {
+  const topLeft = topLeftAt(clip, frame);
+  const [width, height] = sizeAt(clip, frame);
+  return {
+    centerX: topLeft.x + width / 2,
+    centerY: topLeft.y + height / 2,
+    width,
+    height,
+    rotation: rotationAt(clip, frame),
+    flipHorizontal: clip.transform.flipHorizontal,
+    flipVertical: clip.transform.flipVertical,
+  };
+}
+
 /** Whether any transform-related track is active. 1:1 port of `Clip::has_transform_animation`. */
 export function hasTransformAnimation(clip: Clip): boolean {
   return (
@@ -598,3 +722,31 @@ export function linkOffsetForClip(timeline: Timeline, clipId: string): number |
   if (offset === 0) return null; // lead clip → no badge
   return offset;
 }
+
+/**
+ * The single clip the on-canvas Transform overlay should target, or `null` if
+ * it shouldn't render. Adapts upstream `TransformOverlayView.selectedClip`
+ * (TransformOverlayView.swift:304-313), which scans every non-audio track for
+ * ANY selected clip and returns the first match (so it can render even with
+ * other clips also selected). OpenTake tightens this to exactly one clip
+ * selected total, per the feature's "single visual clip selected" scope —
+ * still a strict subset of when upstream would show the overlay, never wider.
+ * `track.type !== "audio"` mirrors upstream's `track.type != .audio` (covers
+ * video/image/text/lottie — any non-audio track), not `clip.mediaType`.
+ * `selectedClipIds` is optional so callers (and test mocks of the UI store)
+ * that omit it don't need a defensive check of their own.
+ */
+export function findSelectedVisualClip(
+  timeline: Timeline,
+  selectedClipIds: Set<string> | undefined,
+): Clip | null {
+  if (!selectedClipIds || selectedClipIds.size !== 1) return null;
+  const [id] = selectedClipIds;
+  for (const track of timeline.tracks) {
+    if (track.type === "audio") continue;
+    for (const c of track.clips) {
+      if (c.id === id) return c;
+    }
+  }
+  return null;
+}