Skip to content

Open source CapCut alternative.

TypeScript

feat(site): a stage drag moves the clip; the crop pans from the ghost and sliders [rebuild]

David Led8bfe950003d
diff --git a/docs/guides/cut/README.md b/docs/guides/cut/README.md
index 3cc3b41e..95de16bb 100644
--- a/docs/guides/cut/README.md
+++ b/docs/guides/cut/README.md
@@ -30,7 +30,7 @@ The client probes the engine's health endpoint (dedicated port first, dev server
**A cut needs no footage.** The frame starts as a color the project owns, and everything else — clips, titles, shapes, stickers — draws over it. So a video made entirely of text and graphics is an ordinary project: it plays, exports, shares, and renders on the worker like any other, and the same color letterboxes a fitted clip and fills a gap on track 0. Elements stack by row: two on one row slide clear of each other in time, so a title that sits over a card lives a row above it. Type stays inside the picture on its own: a line wider than the room its anchor leaves is measured against the face it will actually be drawn in and broken onto another line, in the preview and in the export alike, so whoever writes the words — a person, the assistant — picks the size the design wants and lets the frame do the breaking.
-**Framing is per clip.** Every video clip meets its box — the whole frame, or the region it was given — through one geometry: fitted with margins or covering with a crop, zoomed in further, panned to choose what the crop keeps, turned, faded, cornered, masked, and shadowed. One function computes where the picture lands, the preview draws that rectangle, and the export graph scales and crops to the same numbers, so a reframed clip looks the same on every surface, freeze frames and headless renders included. On the stage the selected clip wears two outlines: a blue box for its layout, with grips to move, resize, and rotate it, and a grey dashed one standing where the source really lands, so the part a crop discards stays visible — its corners zoom the picture and its interior pans it. The shadow is cast by the shape the clip actually shows, mask included, which is what makes a circle-masked camera bubble throw a circular shadow.
+**Framing is per clip.** Every video clip meets its box — the whole frame, or the region it was given — through one geometry: fitted with margins or covering with a crop, zoomed in further, panned to choose what the crop keeps, turned, faded, cornered, masked, and shadowed. One function computes where the picture lands, the preview draws that rectangle, and the export graph scales and crops to the same numbers, so a reframed clip looks the same on every surface, freeze frames and headless renders included. On the stage the selected clip wears two outlines: a blue box for its layout — a drag anywhere on it moves the clip, its grips resize it, the button above turns it — and a grey dashed one standing where the source really lands, so the part a crop discards stays visible: its corners zoom the picture and dragging the discarded part slides the crop. The shadow is cast by the shape the clip actually shows, mask included, which is what makes a circle-masked camera bubble throw a circular shadow.
**A cutout keys the clip to a matte.** Every video clip can carry a cutout — the Inspector's Cutout tab: an alpha matte decides which of its pixels stay, ink can trace the kept silhouette, and a color or image can fill in behind it, with lower tracks showing through wherever nothing fills. Every mode resolves to that one matte in the clip's own pixels. A chroma key computes it live, from reference math in the effects kit that the GPU shader, the CPU pass, and the export all share. The AI modes bake it into a small grayscale video stored as a project asset: auto mattes the person with the on-device segmenter in seconds and for free, then a hosted tracker (credits, like all AI work) re-bakes it at quality and swaps the asset in; a custom selection goes straight to the tracker, seeded by a few words naming the subject or by the strokes painted on the stage — the instant feedback while painting comes from a small on-device tap-to-select model, and the stored words and seeds make every bake reproducible. A long clip tracks in parts: the span splits into pieces of a few minutes, each submitted to the tracker as its own billable job with the selection handed across the seam, and a persisted ticket pins the submitted parts and the exact span they were cut from — a reload resumes the run on the paid pieces, and a part whose track dies is re-bought alone on retry. A fingerprint on the matte records what it was baked from — the source and the selection, trims left out — so a retrim inside the baked range keeps the matte and its bill, while a changed selection re-bakes; a background sweep settles bakes against the doc through undo, redo, and deletion, and holds them while a brush session is still painting. For the ffmpeg export each cutout clip ships as a client-rendered pair of videos — the keyed picture's color and its alpha — baked by the same compositor that draws the preview, so the engine and the worker composite exactly what the tab showed. Headless surfaces consume stored mattes; a turn that runs with no browser writes the cutout onto the clip and the next editor session's sweep starts the bake it owes.
@@ -64,7 +64,7 @@ Each voice reads its file the way the picture's readers do: a walk held open, pu
What is on screen at a given instant is still a pure function of the document and a time, and it is still the same function an export asks. The preview reaches an instant by playing toward it and an export by jumping straight there; because both draw through one compositor from one plan, the file cannot quietly disagree with what was watched.
-The stage sits under a camera. The picture opens fitted to its pane, and that fit is 100%: from there a pinch or ⌘-scroll zooms about the cursor, a plain scroll pans, and a drag on the empty room around the picture — or a middle-button drag anywhere — moves the view. A drag on the picture belongs to the picture, whatever is drawn over it: a title, a shape, a sticker, a caption all hand the gesture down to whatever the footage itself would do with it — move the view, or slide the selected clip's crop. Selection is what arms something to be moved; a press that never travels selects what it landed on, and the drag after that moves it. The camera holds its place on screen when a panel opens or the selection changes shape; the pan absorbs the layout's move, so the picture stays where the eye left it. A round control in the pane's top-right corner appears while the camera moves and lingers a moment after, opening into the zoom level, a step in each direction, and a Reset that refits.
+The stage sits under a camera. The picture opens fitted to its pane, and that fit is 100%: from there a pinch or ⌘-scroll zooms about the cursor, a plain scroll pans, and a drag on the empty room around the picture — or a middle-button drag anywhere — moves the view. A drag on the picture belongs to the picture, whatever is drawn over it: a title, a shape, a sticker, a caption all hand the gesture down to whatever the footage itself would do with it — move the view, or move the selected clip. Selection is what arms something to be moved; a press that never travels selects what it landed on, and the drag after that moves it. The camera holds its place on screen when a panel opens or the selection changes shape; the pan absorbs the layout's move, so the picture stays where the eye left it. A round control in the pane's top-right corner appears while the camera moves and lingers a moment after, opening into the zoom level, a step in each direction, and a Reset that refits.
The playhead lives apart from the document. It moves sixty times a second and the document does not, so a moved playhead wakes the surfaces that draw it and nothing else — and a paused editor with nothing changing schedules no frames at all.
diff --git a/site/src/cut/components/Inspector.tsx b/site/src/cut/components/Inspector.tsx
index 532b8b3a..a826696c 100644
--- a/site/src/cut/components/Inspector.tsx
+++ b/site/src/cut/components/Inspector.tsx
@@ -51,7 +51,7 @@ import {
import { clipWindow, useEditor, type EditorState } from "@/cut/lib/store";
import { usePanelView } from "@/cut/lib/panelViews";
import { usePreviewTime } from "@/cut/lib/playhead";
-import { CLIP_MAX_ZOOM, clipKeyed, clipPoseAt, clipZoom, contentRect } from "@/cut/lib/types";
+import { CLIP_MAX_ZOOM, clipCovers, clipKeyed, clipPoseAt, clipZoom, contentRect } from "@/cut/lib/types";
import { AnimationCard, AnimationTiles } from "@/cut/components/AnimationTiles";
import { ColorField } from "@/cut/components/ColorField";
import { wordTimesFor } from "@/cut/lib/textWords";
@@ -529,6 +529,7 @@ function ClipAudioPanel({ clip, onBack }: { clip: VideoClip; onBack: () => void
<ValueSlider
label="Volume"
sliderClassName="clip-volume data-horizontal:w-24"
+ const panCk = useSliderCheckpoint();
valueClassName="w-9 text-muted-foreground"
value={volume}
min={0}
@@ -546,6 +547,25 @@ function ClipAudioPanel({ clip, onBack }: { clip: VideoClip; onBack: () => void
</Row>
<Row label="Mute audio">
<Switch
+ // Which axes the crop window can travel on: the picture hangs past the box
+ // there, so pan has somewhere to go. Measured in frame pixels, the same
+ // geometry the preview's grey outline draws.
+ const frPx = frameOf(aspect);
+ const boxPx = { x: rect.x * frPx.w, y: rect.y * frPx.h, w: rect.w * frPx.w, h: rect.h * frPx.h };
+ const picPx =
+ asset?.width && asset?.height
+ ? contentRect(
+ boxPx,
+ asset.width,
+ asset.height,
+ clipCovers(clip),
+ clipZoom(clip),
+ clip.panX ?? 0,
+ clip.panY ?? 0
+ )
+ : boxPx;
+ const panXFree = picPx.w - boxPx.w > 1;
+ const panYFree = picPx.h - boxPx.h > 1;
checked={clip.muted}
onCheckedChange={(v) => updateClip(clip.id, { muted: v })}
/>
@@ -724,16 +744,42 @@ function ClipPanel({ clip }: { clip: VideoClip }) {
onClick={() => updateClip(clip.id, { zoom: undefined, panX: 0, panY: 0 })}
/>
</Row>
- {((clip.panX ?? 0) !== 0 || (clip.panY ?? 0) !== 0) && (
- <Row label="Position">
- <button
- className="clip-recenter rounded-md border border-input px-2 py-0.5 text-[11.5px] text-muted-foreground transition-colors hover:text-foreground"
- onClick={() => updateClip(clip.id, { panX: 0, panY: 0 })}
- >
- Center
- </button>
- </Row>
- )}
+ {(["panX", "panY"] as const).map((axis) => {
+ const free = axis === "panX" ? panXFree : panYFree;
+ const value = clip[axis] ?? 0;
+ if (!free && value === 0) return null;
+ return (
+ <Row key={axis} label={axis === "panX" ? "Pan X" : "Pan Y"}>
+ <ValueSlider
+ label={axis === "panX" ? "Pan X" : "Pan Y"}
+ sliderClassName="clip-pan data-horizontal:w-24"
+ valueClassName="w-9 text-muted-foreground"
+ value={value}
+ min={-1}
+ max={1}
+ step={0.01}
+ snap={[0]}
+ keyStep={0.05}
+ format={formatPercent}
+ parse={parsePercentInput}
+ onDraft={(v) => {
+ panCk.begin();
+ useEditor.getState().updateClipTransient(clip.id, { [axis]: v });
+ }}
+ onCommit={(v) => {
+ panCk.begin();
+ updateClip(clip.id, { [axis]: v });
+ panCk.end();
+ }}
+ />
+ <ResetButton
+ title="Center"
+ show={value !== 0}
+ onClick={() => updateClip(clip.id, { [axis]: 0 })}
+ />
+ </Row>
+ );
+ })}
<Row label="Rotation">
<ValueSlider
label="Rotation"
diff --git a/site/src/cut/components/Preview.tsx b/site/src/cut/components/Preview.tsx
index fa61a2f2..41af7299 100644
--- a/site/src/cut/components/Preview.tsx
+++ b/site/src/cut/components/Preview.tsx
@@ -11,7 +11,7 @@ import {
usePreviewSelector,
useSkim,
} from "@/cut/lib/playhead";
-import { getClipSpans, projectDuration, useEditor } from "@/cut/lib/store";
+import { projectDuration, useEditor } from "@/cut/lib/store";
import { copyStageFrame, primeStageFrame, stageHasFrame } from "@/cut/lib/stageFrame";
import {
capturePoster,
@@ -20,7 +20,7 @@ import {
readPoster,
} from "@/cut/lib/posterCache";
import { resizePreviewSurface, setPreviewCanvas } from "@/cut/lib/previewCanvas";
-import { CLIP_MAX_ZOOM, clipCovers, clipKeyed, clipPoseAt, clipZoom, contentRect, frameOf, isFullRect, rectOf, REGION_MAX_SCALE, type Aspect, type ClipSpan, type FrameRect, type MediaAsset, type VideoClip } from "@/cut/lib/types";
+import { CLIP_MAX_ZOOM, clipCovers, clipKeyed, clipPoseAt, clipZoom, contentRect, frameOf, isFullRect, rectOf, REGION_MAX_SCALE, type VideoClip } from "@/cut/lib/types";
import { hasMaskKeys, type MaskKey } from "@donkeycut/effects-kit";
import { cn } from "@/lib/utils";
import { MaskGizmoCore, OverlayChromeHost, OverlayLayer, StagePress } from "./OverlayLayer";
@@ -33,26 +33,6 @@ import {
useEffectLanes,
} from "./StageEffects";
-/** How far a clip's picture hangs past its box, in the box's units. Zero on an
- * axis with nothing to spare. */
-function overflowOf(
- clip: VideoClip,
- asset: { width?: number; height?: number },
- box: FrameRect
-): { ox: number; oy: number } {
- if (!asset.width || !asset.height) return { ox: 0, oy: 0 };
- const pic = contentRect(
- box,
- asset.width,
- asset.height,
- clipCovers(clip),
- clipZoom(clip),
- clip.panX ?? 0,
- clip.panY ?? 0
- );
- return { ox: Math.max(0, pic.w - box.w), oy: Math.max(0, pic.h - box.h) };
-}
-
/** A stationary click on the stage: the first click clears whatever is
* selected; with nothing selected it plays or pauses, rewinding first when
* the playhead is parked at the end. */
@@ -68,21 +48,6 @@ function stageClick() {
s.setPlaying(!s.playing);
}
-/** The clip under the playhead, when its picture overflows the whole frame —
- * covering it or zoomed into it. A regioned clip is panned from its own
- * preview handle instead. */
-function pannableSpan(
- s: { clips: VideoClip[]; assets: MediaAsset[]; aspect: Aspect },
- t: number
-): ClipSpan | null {
- const spans = getClipSpans(s.clips, s.assets);
- const span = spans.find((sp) => t >= sp.start && sp.start + sp.len > t) ?? spans[spans.length - 1];
- if (!span || !isFullRect(rectOf(span.clip))) return null;
- const frame = frameOf(s.aspect);
- const { ox, oy } = overflowOf(span.clip, span.asset, { x: 0, y: 0, w: frame.w, h: frame.h });
- return ox > 1 || oy > 1 ? span : null;
-}
-
/** Paint the picture this project's preview last showed, then hand the canvas
* back to the engine. Cloud media is a network away, so without this the
* preview holds black for about a second on every open while the first decoder
@@ -205,9 +170,6 @@ export function Preview() {
// center carries the pan back out of it.
const rawRef = useRef({ x: 0, y: 0 });
const [centered, setCentered] = useState({ x: false, y: false });
- // The same for a fill clip's crop: which axis the picture inside the frame
- // is parked on center in, drawn as a guide over the stage.
- const [cropCentered, setCropCentered] = useState({ x: false, y: false });
const boxRef = useRef<HTMLDivElement>(null);
// Whether the picture has left the pane entirely. Every camera move funnels
// through applyPan, so that is where it gets decided; the geometry it reads
@@ -520,62 +482,13 @@ export function Preview() {
});
};
- // Drag a selected fill-mode clip inside the frame to choose the visible crop.
- // The clip has to be the selection: an unselected picture is something to
- // grab and move around the pane, and that press goes to the camera.
- const panDrag = (e: React.PointerEvent, onTap: () => void = stageClick) => {
- const s = useEditor.getState();
- const span = pannableSpan(s, previewAt());
- if (!span || s.selection?.kind !== "clip" || s.selection.id !== span.clip.id) return false;
- const fr = frameOf(s.aspect);
- const { ox, oy } = overflowOf(span.clip, span.asset, { x: 0, y: 0, w: fr.w, h: fr.h });
- const clipId = span.clip.id;
- const panX0 = span.clip.panX ?? 0;
- const panY0 = span.clip.panY ?? 0;
- const toFrame = fr.w / stage.w; // screen px → frame px
- // History opens only once the pointer actually travels; a stationary press
- // is a stage click, which deselects.
- let began = false;
- startDrag(e, {
- onMove: (dx, dy, ev) => {
- if (!began) {
- if (Math.abs(dx) <= 3 && Math.abs(dy) <= 3) return;
- began = true;
- useEditor.getState().pushHistory();
- }
- // Content follows the pointer; pan is the crop-window position. Each
- // axis pulls onto the middle of the picture as it passes, so a crop
- // lands centered on purpose. ⌘/Ctrl passes straight through.
- const free = ev.metaKey || ev.ctrlKey;
- const near = (v: number, over: number) =>
- !free && (Math.abs(v) * (over / 2) * stage.w) / fr.w <= PAN_SNAP_PX;
- const rawX = ox > 1 ? Math.max(-1, Math.min(1, panX0 - (dx * toFrame) / (ox / 2))) : 0;
- const rawY = oy > 1 ? Math.max(-1, Math.min(1, panY0 - (dy * toFrame) / (oy / 2))) : 0;
- const sx = ox > 1 && near(rawX, ox);
- const sy = oy > 1 && near(rawY, oy);
- setCropCentered((c) => (c.x === sx && c.y === sy ? c : { x: sx, y: sy }));
- useEditor.getState().updateClipTransient(clipId, {
- panX: sx ? 0 : rawX,
- panY: sy ? 0 : rawY,
- });
- },
- // startDrag suppresses the click event, so a stationary press on a
- // pannable clip runs the stage click here instead: clear the selection
- // first, play or pause once nothing is selected.
- onUp: (_dx, _dy, moved) => {
- setCropCentered((c) => (c.x || c.y ? { x: false, y: false } : c));
- if (!moved) onTap();
- },
- });
- return true;
- };
-
/** A press that landed on something drawn over the picture the user has not
- * selected — a title, a caption. It belongs to the picture: the drag pans,
- * exactly as it would on bare footage, and a press that never travels runs
- * `onTap`, which is where the thing under the pointer gets selected. */
+ * selected — a title, a caption. It belongs to the picture: the drag moves
+ * the camera, exactly as it would on bare footage, and a press that never
+ * travels runs `onTap`, which is where the thing under the pointer gets
+ * selected. */
const stagePress = (e: React.PointerEvent, onTap: () => void) => {
- if (!panDrag(e, onTap)) cameraDrag(e, onTap);
+ cameraDrag(e, onTap);
};
// The topmost regioned clip under a stage point at the playhead — clicking
@@ -668,7 +581,7 @@ export function Preview() {
// A press over a regioned clip belongs to the click handler
// below (select it); a pan gesture here would swallow the click.
if (clipAtPoint(e)) return;
- if (!panDrag(e)) cameraDrag(e, stageClick);
+ cameraDrag(e, stageClick);
}
}}
// Every other press starts a drag, and a drag swallows its own
@@ -722,14 +635,6 @@ export function Preview() {
className="pointer-events-none absolute inset-0"
style={{ "--stage-radius": `${stageRadius(stage.w, stage.h)}px` } as React.CSSProperties}
/>
- {/* A crop parked on the middle of its picture shows the axis it is
- centered on, drawn across the frame it sits in. */}
- {cropCentered.x && (
- <div className="pointer-events-none absolute inset-y-0 left-1/2 z-20 w-px bg-neutral-400/80" />
- )}
- {cropCentered.y && (
- <div className="pointer-events-none absolute inset-x-0 top-1/2 z-20 h-px bg-neutral-400/80" />
- )}
<ClipMaskGizmo stage={stage} />
<RemovalBrush stage={stage} />
<ClipTransformGizmo stage={stage} />
@@ -890,15 +795,15 @@ function ZoomHud({
/**
* Direct manipulation for the selected video clip, on any track and at any
- * size: drag the blue box to move it, a corner to scale it whole, a side to
- * pull one edge, the button above to turn it. Every gesture writes the clip's
- * own `frame`/`rotation`, and the gizmo shows only while the clip is live under
- * the playhead so it lines up with what the compositor draws.
+ * size: a drag anywhere on the blue box moves it, a corner scales it whole, a
+ * side pulls one edge, the button above turns it. Every gesture writes the
+ * clip's own `frame`/`rotation`, and the gizmo shows only while the clip is
+ * live under the playhead so it lines up with what the compositor draws.
*
* The grey outline beside it is the picture itself — where the source lands
* once its box has fitted or cropped it. When it overflows, its corners zoom
- * and its interior pans, which is how a landscape shot gets framed for a
- * vertical cut.
+ * and the outline itself — the part hanging past the box — drags to pan the
+ * crop, which is how a landscape shot gets framed for a vertical cut.
*/
/** How close (screen px) a box edge pulls onto a snap line while dragging. */
const SNAP_PX = 8;
@@ -970,7 +875,7 @@ function ClipTransformGizmo({ stage }: { stage: Stage }) {
const patch = (p: Partial<VideoClip>) => st().updateClipTransient(clip.id, p);
/**
* A drag on one of the gizmo's large surfaces — the box body, the picture's
- * interior. The history checkpoint waits for real travel; a press that
+ * grey outline. The history checkpoint waits for real travel; a press that
* never travels is a stage click, which here clears the clip's selection
* (playback stays put — something was selected).
*/
@@ -1193,14 +1098,25 @@ function ClipTransformGizmo({ stage }: { stage: Stage }) {
const onPanPicture = (e: React.PointerEvent) => {
const panX0 = clip.panX ?? 0;
const panY0 = clip.panY ?? 0;
- // Content follows the pointer; pan is the crop window's position.
- surfaceDrag(e, (rawX, rawY) => {
- const { dx, dy } = unturn(rawX, rawY);
- patch({
- panX: ox > 1 ? Math.max(-1, Math.min(1, panX0 - dx / (ox / 2))) : 0,
- panY: oy > 1 ? Math.max(-1, Math.min(1, panY0 - dy / (oy / 2))) : 0,
- });
- });
+ // Content follows the pointer; pan is the crop window's position. Each
+ // axis pulls onto the middle of the picture as it passes, so a crop lands
+ // centered on purpose, with a guide through the box while it holds.
+ surfaceDrag(
+ e,
+ (rawX, rawY) => {
+ const { dx, dy } = unturn(rawX, rawY);
+ const vx = ox > 1 ? Math.max(-1, Math.min(1, panX0 - dx / (ox / 2))) : 0;
+ const vy = oy > 1 ? Math.max(-1, Math.min(1, panY0 - dy / (oy / 2))) : 0;
+ const sx = ox > 1 && Math.abs(vx) * (ox / 2) <= PAN_SNAP_PX;
+ const sy = oy > 1 && Math.abs(vy) * (oy / 2) <= PAN_SNAP_PX;
+ setGuides({
+ x: sx && !rotation ? r.x + r.w / 2 : null,
+ y: sy && !rotation ? r.y + r.h / 2 : null,
+ });
+ patch({ panX: sx ? 0 : vx, panY: sy ? 0 : vy });
+ },
+ () => setGuides({ x: null, y: null })
+ );
};
// Everything draws in the pane's own space, so an oversized picture's outline
@@ -1231,11 +1147,18 @@ function ClipTransformGizmo({ stage }: { stage: Stage }) {
>
<div className="absolute inset-0" style={turn}>
{/* The picture as the source really lands it: grey where the frame
- throws it away, so a crop is something you can see and grab. */}
+ throws it away, so a crop is something you can see and grab —
+ dragging the discarded part slides the crop; the box above keeps
+ every press inside itself. */}
{showPicture && (
<div
- className="absolute rounded-[3px] border border-dashed border-white/70 shadow-[0_0_0_1px_rgba(0,0,0,0.35)]"
+ className={cn(
+ "absolute rounded-[3px] border border-dashed border-white/70 shadow-[0_0_0_1px_rgba(0,0,0,0.35)]",
+ overflows && "pointer-events-auto cursor-grab active:cursor-grabbing"
+ )}
style={picBox}
+ title={overflows ? "Drag to pan the picture" : undefined}
+ onPointerDown={overflows ? onPanPicture : undefined}
>
{overflows && (
<TransformHandles
@@ -1255,14 +1178,6 @@ function ClipTransformGizmo({ stage }: { stage: Stage }) {
style={box}
onPointerDown={onMoveBox}
>
- {/* An overflowing picture pans from the interior; the ring at the
- border moves the box, the grips resize it. */}
- {overflows && (
- <div
- className="absolute inset-2 cursor-grab active:cursor-grabbing"
- onPointerDown={onPanPicture}
- />
- )}
<TransformHandles
color="#0a84ff"
className="z-20"
diff --git a/site/src/cut/components/ScrubValue.tsx b/site/src/cut/components/ScrubValue.tsx
index 7799b740..9e466c37 100644
--- a/site/src/cut/components/ScrubValue.tsx
+++ b/site/src/cut/components/ScrubValue.tsx
@@ -245,9 +245,9 @@ export function parseSecondsInput(raw: string): number | null {
return m ? Number(m[1]) : null;
}
-/** "80", "80%" → fraction 0.8. */
+/** "80", "80%", "-25%" → fraction 0.8 / -0.25. */
export function parsePercentInput(raw: string): number | null {
- const m = raw.trim().match(/^(\d*\.?\d+)%?$/);
+ const m = raw.trim().match(/^(-?\d*\.?\d+)%?$/);
return m ? Number(m[1]) / 100 : null;
}
diff --git a/site/src/cut/server/ai/catalog.ts b/site/src/cut/server/ai/catalog.ts
index 60207912..2583b43b 100644
--- a/site/src/cut/server/ai/catalog.ts
+++ b/site/src/cut/server/ai/catalog.ts
@@ -102,7 +102,7 @@ Times are in seconds on the shared timeline. The playhead is currentTime; a skim
- Anything can be hidden instead of deleted: it stays on the timeline (grayed) but drops out of playback and export — a hidden video clip plays black and silent. Per item: set_clip_hidden, or the \`hidden\` field on update_overlay_video/update_overlay/update_audio. A transition bar hides the same way (set_transition_hidden): it keeps the cut it sits on so nothing else claims that boundary, and the cut renders hard. Whole rows: set_track_hidden (video/soundtrack/text/subtitles/transitions) and set_track_muted (video) — the eye/speaker toggles on the track headers.
- detach_audio lifts a video clip's sound to the soundtrack track (and mutes the clip) so audio can be cut independently of video.
- freeze_frame grabs one frame (default: the playhead — what the user currently sees) as a still clip and inserts it, by default at index 0 as a cover/hook frame ("make this the first frame"). The still is baked at the project's current aspect with the clip's framing applied; if the user later switches aspect they should capture a fresh one. \`with_elements\` bakes the composited picture instead — titles, captions and effects burned in — which is what a cover frame carrying the video's own text needs. The user reaches the same still by right-clicking the preview canvas: Copy frame puts that picture on their clipboard, and ⌘V drops it on the timeline.
-- set_framing: per-clip Fit (letterbox) vs Fill (crop to cover the box), plus zoom 1..4 to push further in. Whenever the picture overflows, panX/panY position the crop window; the user can also drag the video directly in the preview, where a grey outline shows the part being cropped away. The controls live in the Inspector under "Framing" when a video clip is selected. Landscape footage usually wants fill + a pan that keeps the subject.
+- set_framing: per-clip Fit (letterbox) vs Fill (crop to cover the box), plus zoom 1..4 to push further in. Whenever the picture overflows, panX/panY position the crop window; in the preview a grey outline shows the part being cropped away, and the user drags that outline to slide the crop (dragging the clip itself moves its box). The controls live in the Inspector under "Framing" when a video clip is selected. Landscape footage usually wants fill + a pan that keeps the subject.
- update_clip also carries a clip's resting transform: rotation and opacity, alongside its region (layout/region) and zoom. Use these for a tilted or faded layer; set_clip_keyframes is for a transform that moves over time.
- set_clip_style rounds a clip's corners, strokes a border ring, and casts a drop shadow from the clip's shape — mask included, so a circle-masked webcam gets a circular shadow. The floating-cam look is one recipe: put the clip on an upper track, region it small (update_clip region or the preview handles), mask it with kind circle, and give it a soft shadow.
- The user can copy/paste any selected segment (video, overlay video, audio, title) with ⌘C/⌘V; pastes aim for the playhead and slide right to free space.