Open source CapCut alternative.
TypeScript
feat(site): masks cut hearts, stars and polygons, with grips for feather and corners [rebuild]
David Lef47d6afbfb1c
diff --git a/site/packages/effects-kit/src/mask.test.ts b/site/packages/effects-kit/src/mask.test.tsindex 8f3ae369..028f895b 100644--- a/site/packages/effects-kit/src/mask.test.ts+++ b/site/packages/effects-kit/src/mask.test.ts@@ -25,17 +25,25 @@ const key = (t: number, over: Partial<MaskKey> = {}): MaskKey => ({describe("mask frames", () => {test("no keys resolves to the resting geometry with defaults filled", () => {- expect(maskFrameAt(mask(), 1)).toEqual({ x: 0, y: 0, w: 0.5, h: 0.5, rotation: 0, feather: 0 });- expect(restingMaskFrame(mask({ x: 0.1, feather: 24 }))).toEqual({+ expect(maskFrameAt(mask(), 1)).toEqual({ x: 0, y: 0, w: 0.5, h: 0.5, rotation: 0, feather: 0, radius: 0 });+ expect(restingMaskFrame(mask({ x: 0.1, feather: 24, radius: 8 }))).toEqual({x: 0.1,y: 0,w: 0.5,h: 0.5,rotation: 0,feather: 24,+ radius: 8,});});+ test("a key without a radius falls back to the mask's own, and keyed radii blend", () => {+ const m = mask({ radius: 10, kf: [key(0), key(2, { radius: 30 })] });+ expect(maskFrameAt(m, 0).radius).toBe(10);+ expect(maskFrameAt(m, 1).radius).toBe(20);+ expect(maskFrameAt(m, 2).radius).toBe(30);+ });+test("geometry moves between keys and holds outside them", () => {const m = mask({ kf: [key(1, { w: 0.2 }), key(3, { w: 0.8, feather: 40 })] });expect(maskFrameAt(m, 0).w).toBeCloseTo(0.2);@@ -77,3 +85,34 @@ describe("mask animation flags", () => {expect(behindSubjectMask(undefined)).toBe(false);});});++describe("mask shapes", () => {+ test("every kind is either the person matte or has an outline of its own", async () => {+ const { MASK_KINDS, MASK_SHAPE_KINDS, maskOutlinePathD, maskSizeAxes, maskPolyKind } =+ await import("./mask");+ expect(MASK_SHAPE_KINDS).toEqual(MASK_KINDS.filter((k) => k !== "subject"));+ for (const kind of MASK_SHAPE_KINDS) {+ const d = maskOutlinePathD({ kind }, 200, 100, 1000);+ expect(d.startsWith("M")).toBe(true);+ if (kind !== "linear" && kind !== "mirror") expect(d.endsWith("Z")).toBe(true);+ }+ expect(maskOutlinePathD({ kind: "subject" }, 200, 100, 1000)).toBe("");+ expect(maskSizeAxes("square")).toEqual(["w"]);+ expect(maskSizeAxes("mirror")).toEqual(["h"]);+ expect(maskSizeAxes("linear")).toEqual([]);+ for (const kind of ["heart", "star", "triangle", "diamond", "hexagon"] as const) {+ expect(maskSizeAxes(kind)).toEqual(["w", "h"]);+ expect(maskPolyKind(kind)).toBe(kind);+ }+ expect(maskPolyKind("rect")).toBeNull();+ });++ test("a box outline rounds to its radius and never past its half side", async () => {+ const { maskOutlinePathD } = await import("./mask");+ expect(maskOutlinePathD({ kind: "rect" }, 200, 100, 1000, 0)).toBe("M-100 -50 h200 v100 h-200 Z");+ const rounded = maskOutlinePathD({ kind: "rect" }, 200, 100, 1000, 500);+ expect(rounded).toContain("a50 50");+ // A square's vertical side is its width, so the outline is square.+ expect(maskOutlinePathD({ kind: "square" }, 200, 100, 1000)).toBe("M-100 -100 h200 v200 h-200 Z");+ });+});diff --git a/site/packages/effects-kit/src/mask.ts b/site/packages/effects-kit/src/mask.tsindex 3c0024e5..4e9947ca 100644--- a/site/packages/effects-kit/src/mask.ts+++ b/site/packages/effects-kit/src/mask.ts@@ -1,7 +1,7 @@/*** Masks: per-layer coverage that trims a layer's pixels to a shape — a- * rounded rect, an ellipse, a half-plane, a band — or to the person in the- * shot. The mask travels with its layer: its center is an offset from the+ * rounded rect, an ellipse, a half-plane, a band, a heart, a star, a polygon+ * — or to the person in the shot. The mask travels with its layer: its center is an offset from the* layer's anchor, so a keyframed or dragged layer carries its mask along in* every renderer.*@@ -16,8 +16,125 @@*/import { lerpKeys, shortestTurn } from "./keys";+import { shapePathD, tracePolyShape } from "./shapePath";+import type { ShapeKind } from "./types";-export type MaskKind = "rect" | "square" | "circle" | "linear" | "mirror" | "subject";+export type MaskKind =+ | "rect"+ | "square"+ | "circle"+ | "linear"+ | "mirror"+ | "heart"+ | "star"+ | "triangle"+ | "diamond"+ | "hexagon"+ | "subject";++/** Every mask kind with the name the UI shows for it, in picker order. The+ * shape picker, the chat tool's enum and the catalog all read this list. */+export const MASK_SHAPES: { id: MaskKind; label: string }[] = [+ { id: "rect", label: "Rectangle" },+ { id: "square", label: "Square" },+ { id: "circle", label: "Circle" },+ { id: "linear", label: "Linear" },+ { id: "mirror", label: "Mirror" },+ { id: "heart", label: "Heart" },+ { id: "star", label: "Star" },+ { id: "triangle", label: "Triangle" },+ { id: "diamond", label: "Diamond" },+ { id: "hexagon", label: "Hexagon" },+ { id: "subject", label: "Subject" },+];++export const MASK_KINDS: MaskKind[] = MASK_SHAPES.map((s) => s.id);++/** The geometric kinds: everything with an outline of its own. */+export const MASK_SHAPE_KINDS: MaskKind[] = MASK_KINDS.filter((k) => k !== "subject");++/** Feather ceiling, design px at the 1080 short side. */+export const MASK_FEATHER_MAX = 200;+/** Corner radius ceiling for rect and square masks, design px. */+export const MASK_RADIUS_MAX = 400;++/** The polygon outline a mask kind traces, for the kinds that share the shape+ * element's tracer; null for the box, ellipse, band and matte kinds. */+export function maskPolyKind(kind: MaskKind): ShapeKind | null {+ switch (kind) {+ case "heart":+ case "star":+ case "triangle":+ case "diamond":+ case "hexagon":+ return kind;+ default:+ return null;+ }+}++/** Which size axes a kind has: a square one side, a mirror band one height,+ * a linear edge none, every filled outline both. */+export function maskSizeAxes(kind: MaskKind): ("w" | "h")[] {+ switch (kind) {+ case "square":+ return ["w"];+ case "mirror":+ return ["h"];+ case "linear":+ case "subject":+ return [];+ default:+ return ["w", "h"];+ }+}++/** Whether a kind takes a corner radius. */+export function maskHasRadius(kind: MaskKind): boolean {+ return kind === "rect" || kind === "square";+}++/** The hard edge of a mask's shape as SVG path data, centered on the origin+ * (offset by dx, dy) in the mask's own unrotated space, from the same+ * geometry the painter fills. A linear edge is a line across `span`, a+ * mirror band two of them. */+export function maskOutlinePathD(+ m: Mask,+ w: number,+ h: number,+ span: number,+ radiusPx = 0,+ dx = 0,+ dy = 0+): string {+ const n = (v: number) => String(+v.toFixed(2));+ const side = m.kind === "square" ? w : h;+ const poly = maskPolyKind(m.kind);+ if (poly) return shapePathD(poly, w, h, dx - w / 2, dy - h / 2);+ if (m.kind === "rect" || m.kind === "square") {+ const r = Math.min(radiusPx, w / 2, side / 2);+ const x0 = dx - w / 2;+ const y0 = dy - side / 2;+ if (r <= 0) return `M${n(x0)} ${n(y0)} h${n(w)} v${n(side)} h${n(-w)} Z`;+ return (+ `M${n(x0 + r)} ${n(y0)} h${n(w - 2 * r)} a${n(r)} ${n(r)} 0 0 1 ${n(r)} ${n(r)} ` ++ `v${n(side - 2 * r)} a${n(r)} ${n(r)} 0 0 1 ${n(-r)} ${n(r)} h${n(-(w - 2 * r))} ` ++ `a${n(r)} ${n(r)} 0 0 1 ${n(-r)} ${n(-r)} v${n(-(side - 2 * r))} a${n(r)} ${n(r)} 0 0 1 ${n(r)} ${n(-r)} Z`+ );+ }+ if (m.kind === "circle") {+ const rx = w / 2;+ const ry = h / 2;+ return (+ `M${n(dx - rx)} ${n(dy)} a${n(rx)} ${n(ry)} 0 1 0 ${n(2 * rx)} 0 ` ++ `a${n(rx)} ${n(ry)} 0 1 0 ${n(-2 * rx)} 0 Z`+ );+ }+ if (m.kind === "linear") return `M${n(dx - span)} ${n(dy)} H${n(dx + span)}`;+ if (m.kind === "mirror")+ return `M${n(dx - span)} ${n(dy - h / 2)} H${n(dx + span)} M${n(dx - span)} ${n(dy + h / 2)} H${n(dx + span)}`;+ return "";+}/** One keyed state of a mask's geometry, `t` seconds from the layer's start.* Same interpolation rules as the pose track: linear between keys, held flat@@ -30,6 +147,8 @@ export interface MaskKey {h: number; // fraction of frame height (mirror: band height; square/linear ignore)rotation: number; // degrees clockwisefeather: number; // edge softness, px at the 1080 design short side+ /** Box corner radius, design px; absent = the mask's own. */+ radius?: number;}export interface Mask {@@ -47,7 +166,7 @@ export interface Mask {feather?: number;/** Keep the pixels outside the shape (or outside the person). */invert?: boolean;- /** Rect corner radius, design px. */+ /** Rect or square corner radius, design px; a key can carry its own. */radius?: number;/** Keyframed geometry, its own track beside the layer's pose keys. */kf?: MaskKey[];@@ -61,6 +180,7 @@ export interface MaskFrame {h: number;rotation: number;feather: number;+ radius: number;}export function restingMaskFrame(m: Mask): MaskFrame {@@ -71,6 +191,7 @@ export function restingMaskFrame(m: Mask): MaskFrame {h: m.h ?? 0.5,rotation: m.rotation ?? 0,feather: m.feather ?? 0,+ radius: m.radius ?? 0,};}@@ -93,6 +214,7 @@ export function behindSubjectMask(m?: Mask): boolean {* between keys, held flat outside them, resting when there are none. */export function maskFrameAt(m: Mask, tLocal: number): MaskFrame {if (!m.kf || m.kf.length === 0) return restingMaskFrame(m);+ const rest = m.radius ?? 0;const k = lerpKeys(m.kf, tLocal, (a, b, p) => {const mix = (u: number, v: number) => u + (v - u) * p;return {@@ -103,15 +225,25 @@ export function maskFrameAt(m: Mask, tLocal: number): MaskFrame {h: mix(a.h, b.h),rotation: a.rotation + shortestTurn(a.rotation, b.rotation) * p,feather: mix(a.feather, b.feather),+ radius: mix(a.radius ?? rest, b.radius ?? rest),};});- return { x: k.x, y: k.y, w: k.w, h: k.h, rotation: k.rotation, feather: k.feather };+ return {+ x: k.x,+ y: k.y,+ w: k.w,+ h: k.h,+ rotation: k.rotation,+ feather: k.feather,+ radius: k.radius ?? rest,+ };}/** A key holding the mask's geometry at `t`, ready to be added — capturing* the live frame keeps the first key a visual no-op. */export function maskKeyAt(m: Mask, t: number): MaskKey {- return { t, ...maskFrameAt(m, t) };+ const { radius, ...f } = maskFrameAt(m, t);+ return maskHasRadius(m.kind) ? { t, ...f, radius } : { t, ...f };}/** The frame geometry the painter needs: output size plus the design-px@@ -163,13 +295,19 @@ export function paintMaskCoverage(const rh = m.kind === "square" ? w : h;if (feather > 0 && "filter" in ctx) ctx.filter = `blur(${feather / 2}px)`;ctx.beginPath();- ctx.roundRect(-w / 2, -rh / 2, w, rh, (m.radius ?? 0) * frame.scale);+ ctx.roundRect(-w / 2, -rh / 2, w, rh, Math.max(0, f.radius) * frame.scale);ctx.fill();} else if (m.kind === "circle") {if (feather > 0 && "filter" in ctx) ctx.filter = `blur(${feather / 2}px)`;ctx.beginPath();ctx.ellipse(0, 0, w / 2, h / 2, 0, 0, Math.PI * 2);ctx.fill();+ } else if (maskPolyKind(m.kind)) {+ // The shape element's own outline, filled into the w×h box.+ if (feather > 0 && "filter" in ctx) ctx.filter = `blur(${feather / 2}px)`;+ ctx.beginPath();+ tracePolyShape(ctx, maskPolyKind(m.kind)!, w, h, -w / 2, -h / 2);+ ctx.fill();} else if (m.kind === "linear") {// Half-plane: at rotation 0 the top half stays. The gradient band spans// the feather, centered on the edge line.diff --git a/site/src/cut/components/Inspector.tools.ts b/site/src/cut/components/Inspector.tools.tsindex 056cc020..9957e7e4 100644--- a/site/src/cut/components/Inspector.tools.ts+++ b/site/src/cut/components/Inspector.tools.ts@@ -22,6 +22,9 @@ import {SPEED_CURVE_MIN,SPEED_CURVE_PRESET_IDS,speedCurvePresetCatalogText,+ MASK_FEATHER_MAX,+ MASK_KINDS,+ MASK_RADIUS_MAX,} from "@donkeycut/effects-kit";import { bool, num, obj, str, type AiToolDef } from "@/cut/lib/aiToolDef";@@ -101,12 +104,12 @@ export const INSPECTOR_TOOLS = [{name: "set_mask",description:- "Mask an overlay element or a video clip — trim its picture to a shape or to the person in the shot. Kinds: rect (rounded box), square (rounded square, side = w of the frame width), circle (ellipse; w and h are frame fractions, so a perfect circle needs w × frame width = h × frame height — omitting h gives you that circle), linear (half-plane: at rotation 0 the top side stays), mirror (band across the item), subject (the person matte: invert true sits the item behind the speaker; invert false keeps it only on the person — an element newly masked as subject defaults to behind, a clip to on-person). Position is the mask center's offset from the item's own center (a clip's region center), in frame fractions; w/h size it in frame fractions; feather softens the edge; invert keeps what the shape leaves out. Subject masks use only feather and invert. Pass kind \"none\" to remove the mask. `keys` animates the geometry over time — each key is the full geometry at a moment, moving linearly between keys; pass an empty list to clear the keys and keep the mask still.",+ "Mask an overlay element or a video clip — trim its picture to a shape or to the person in the shot. Kinds: rect (rounded box), square (rounded square, side = w of the frame width), circle (ellipse; w and h are frame fractions, so a perfect circle needs w × frame width = h × frame height — omitting h gives you that circle), linear (half-plane: at rotation 0 the top side stays), mirror (band across the item), heart / star / triangle / diamond / hexagon (the outline filled into the w × h box, point up), subject (the person matte: invert true sits the item behind the speaker; invert false keeps it only on the person — an element newly masked as subject defaults to behind, a clip to on-person). Position is the mask center's offset from the item's own center (a clip's region center), in frame fractions; w/h size it in frame fractions; feather softens the edge; invert keeps what the shape leaves out; radius rounds a rect or square's corners. Subject masks use only feather and invert. Pass kind \"none\" to remove the mask. `keys` animates the geometry over time — each key is the full geometry at a moment, moving linearly between keys; pass an empty list to clear the keys and keep the mask still.",inputSchema: obj({id: str("Overlay element id or video clip id"),kind: {type: "string",- enum: ["rect", "square", "circle", "linear", "mirror", "subject", "none"],+ enum: [...MASK_KINDS, "none"],description: 'Mask shape, the person matte ("subject"), or "none" to remove the mask',},x: num("Center offset x from the element center, fraction of frame width (default 0)"),@@ -114,9 +117,9 @@ export const INSPECTOR_TOOLS = [w: num("Width, fraction of frame width (default 0.5; square: the side; linear ignores)"),h: num("Height, fraction of frame height (mirror: band height; square/linear ignore)"),rotation: num("Degrees clockwise, -180..180"),- feather: num("Edge softness, px at the 1080 design short side (0..200)"),+ feather: num(`Edge softness, px at the 1080 design short side (0..${MASK_FEATHER_MAX})`),invert: bool("Keep the pixels outside the shape"),- radius: num("Rect corner radius, px at 1080 short side"),+ radius: num(`Rect or square corner radius, px at 1080 short side (0..${MASK_RADIUS_MAX})`),keys: {type: "array",description:@@ -130,6 +133,7 @@ export const INSPECTOR_TOOLS = [h: num("Height, fraction of frame height"),rotation: num("Degrees clockwise, -180..180"),feather: num("Edge softness, px at 1080 short side"),+ radius: num("Rect or square corner radius, px at 1080 short side"),},["t"]),diff --git a/site/src/cut/components/Inspector.tsx b/site/src/cut/components/Inspector.tsxindex 866ec946..23c73dc2 100644--- a/site/src/cut/components/Inspector.tsx+++ b/site/src/cut/components/Inspector.tsx@@ -2,7 +2,7 @@import { useQueryClient } from "@tanstack/react-query";import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";-import { AlignCenter, AlignHorizontalSpaceAround, AlignLeft, AlignRight, AlignVerticalSpaceAround, Bold, ChevronLeft, ChevronRight, Diamond, Frame, Italic, Loader2, Palette, Scissors, Smile, Trash2, Type, Volume2 } from "lucide-react";+import { AlignCenter, AlignHorizontalSpaceAround, AlignLeft, AlignRight, AlignVerticalSpaceAround, Bold, ChevronLeft, ChevronRight, Diamond, Frame, Italic, Link2, Link2Off, Loader2, Palette, Scissors, Smile, Trash2, Type, User, Volume2 } from "lucide-react";import { Button } from "@/components/ui/button";import { useSpeedCurveUi } from "@/cut/lib/speedCurveUi";import { EmojiPicker } from "@/cut/components/EmojiPicker";@@ -69,6 +69,13 @@ import {retimeOf,flatSpeedCurve,hasSpeedCurve,+ MASK_FEATHER_MAX,+ MASK_RADIUS_MAX,+ MASK_SHAPES,+ maskHasRadius,+ maskOutlinePathD,+ maskSizeAxes,+ restingMaskFrame,} from "@donkeycut/effects-kit";import { clipWindow, maxClipFade, useEditor, type EditorState } from "@/cut/lib/store";import { usePanelView } from "@/cut/lib/panelViews";@@ -3015,14 +3022,26 @@ function KeyRow({);}-const MASK_SHAPES: { id: MaskKind; label: string }[] = [- { id: "rect", label: "Rectangle" },- { id: "square", label: "Square" },- { id: "circle", label: "Circle" },- { id: "linear", label: "Linear" },- { id: "mirror", label: "Mirror" },- { id: "subject", label: "Subject" },-];+/** A mask kind's picker icon, drawn from the same outline the stage gizmo+ * traces, so the tile shows the shape the mask cuts. A linear edge keeps its+ * top half, a mirror its band; the person matte wears a figure. */+function MaskShapeIcon({ kind }: { kind: MaskKind }) {+ if (kind === "subject") return <User className="size-[18px]" strokeWidth={1.75} />;+ const d = maskOutlinePathD({ kind }, 15, kind === "square" ? 15 : 12, 12, 2.5);+ return (+ <svg viewBox="-10 -10 20 20" className="size-[18px]" fill="none" stroke="currentColor" strokeWidth={1.5}>+ {kind === "linear" && <path d="M-9 -8 L9 -3 V-9 H-9 Z" fill="currentColor" opacity={0.3} stroke="none" />}+ {kind === "mirror" && <path d="M-9 -7 L9 -4 V4 L-9 7 Z" fill="currentColor" opacity={0.3} stroke="none" />}+ {kind === "linear" ? (+ <path d="M-9 -8 L9 -3" strokeDasharray="2.5 1.5" />+ ) : kind === "mirror" ? (+ <path d="M-9 -7 L9 -4 M-9 7 L9 4" strokeDasharray="2.5 1.5" />+ ) : (+ <path d={d} strokeLinejoin="round" />+ )}+ </svg>+ );+}/** How a panel's mask section reads and writes its owner's mask — the same* section serves overlay elements and video clips through this. */@@ -3414,66 +3433,108 @@ function MaskSection({ target }: { target: MaskTarget }) {const rotationCk = useSliderCheckpoint();const featherCk = useSliderCheckpoint();const radiusCk = useSliderCheckpoint();+ // Size link: scrubbing one axis carries the other so the shape keeps its+ // pixel proportions. On for a circle, which starts round.+ const [linked, setLinked] = useState<boolean | null>(null);const m = target.mask;const tLocal = localTimeOf(target.element, now);const geom = m ? maskFrameAt(m, tLocal) : null;+ const sizeLinked = linked ?? m?.kind === "circle";const writeGeom = (patch: Partial<Omit<MaskKey, "t">>) => {if (!m) return;if (hasMaskKeys(m)) return target.setKey(tLocal, patch, { transient: true });- target.setTransient({ ...m, ...patch });+ // A zero radius is no radius on the resting mask.+ const next = { ...m, ...patch };+ if (patch.radius === 0) delete next.radius;+ target.setTransient(next);};- // Which size axes the shape has: a square has one side, a mirror band one- // height, linear none.- const sizeAxes: ("w" | "h")[] =- m?.kind === "rect" || m?.kind === "circle"- ? ["w", "h"]- : m?.kind === "square"- ? ["w"]- : m?.kind === "mirror"- ? ["h"]- : [];+ // One axis moves, the other follows at the current pixel ratio.+ const writeSize = (axis: "w" | "h", v: number) => {+ if (!geom || !sizeLinked || sizeAxes.length < 2) return writeGeom({ [axis]: v });+ const fr = frameOf(useEditor.getState().aspect);+ const ratio = (geom.h * fr.h) / Math.max(1e-6, geom.w * fr.w);+ if (axis === "w") return writeGeom({ w: v, h: Math.min(2, Math.max(0.01, (v * fr.w * ratio) / fr.h)) });+ writeGeom({ h: v, w: Math.min(2, Math.max(0.01, (v * fr.h) / ratio / fr.w)) });+ };+ const sizeAxes = m ? maskSizeAxes(m.kind) : [];const subject = m?.kind === "subject";+ // A circle at rest is round: w and h are fractions of different frame+ // edges, so equal pixels means unequal fractions.+ const roundCircle = (w: number) => {+ const fr = frameOf(useEditor.getState().aspect);+ return { w, h: (w * fr.w) / fr.h };+ };+ // Reset puts the geometry back where a fresh mask starts — centered, half+ // frame, upright, hard-edged, square-cornered — keeping the kind, the+ // invert and any keys: with keys the default lands on the key at the+ // playhead.+ const reset = () => {+ if (!m) return;+ const rest = restingMaskFrame({ kind: m.kind });+ const geom = m.kind === "circle" ? { ...rest, ...roundCircle(rest.w) } : rest;+ if (hasMaskKeys(m)) {+ target.set({ ...m, radius: undefined });+ target.setKey(tLocal, geom, { transient: true });+ return;+ }+ setLinked(null);+ target.set({ kind: m.kind, invert: m.invert, kf: m.kf, ...(subject ? {} : geom) });+ };return (<Sectiontitle="Mask"- info="Trim the picture to a shape, or to the person in the shot (Subject). Feather softens the edge, and invert keeps what the shape leaves out — an inverted Subject mask sits the picture behind the speaker."+ info="Trim the picture to a shape, or to the person in the shot (Subject). Drag the shape to move it, its grips to resize, the lollipop to rotate, the chevron under it to feather the edge, and the corner grip to round a box. Invert keeps what the shape leaves out — an inverted Subject mask sits the picture behind the speaker."enabled={!!m}onEnabledChange={(v) => target.set(v ? { kind: "rect" } : undefined)}+ aside={+ m && !subject ? (+ <Button+ variant="ghost"+ size="sm"+ className="h-7 px-2 text-[12px] text-muted-foreground"+ onClick={reset}+ >+ Reset+ </Button>+ ) : undefined+ }>{m && geom && (<>- <Row label="Shape">- <Select- value={m.kind}- onValueChange={(kind) => {- // A fresh circle starts perfectly round: w and h are frame- // fractions, so equal pixels means unequal fractions. ⇧-drag- // on the stage keeps it round through resizes.- const patch =- kind === "circle" && !hasMaskKeys(m)- ? (() => {- const fr = frameOf(useEditor.getState().aspect);- const w = m.w ?? 0.5;- return { w, h: (w * fr.w) / fr.h };- })()- : kind === "subject" && m.kind !== "subject" && target.subjectStartsBehind- ? { invert: true }- : {};- target.set({ ...m, ...patch, kind: kind as MaskKind });- }}- >- <SelectTrigger className="h-8 w-36 text-[12px]">- <SelectValue />- </SelectTrigger>- <SelectContent>- {MASK_SHAPES.map((s) => (- <SelectItem key={s.id} value={s.id} className="text-[12px]">- {s.label}- </SelectItem>- ))}- </SelectContent>- </Select>- </Row>+ <div className="grid grid-cols-4 gap-1.5 py-1" role="radiogroup" aria-label="Mask shape">+ {MASK_SHAPES.map((s) => (+ <button+ key={s.id}+ type="button"+ role="radio"+ aria-checked={m.kind === s.id}+ title={s.label}+ className={cn(+ "flex flex-col items-center gap-1 rounded-md border px-1 pb-1 pt-2 text-[10px] leading-none transition-colors",+ m.kind === s.id+ ? "border-primary bg-primary/10 text-foreground"+ : "border-transparent bg-muted/60 text-muted-foreground hover:bg-muted hover:text-foreground"+ )}+ onClick={() => {+ const kind = s.id;+ if (kind === m.kind) return;+ // A fresh circle starts perfectly round: w and h are frame+ // fractions, so equal pixels means unequal fractions. The+ // size link and ⇧-drag on the stage keep it round after.+ const patch =+ kind === "circle" && !hasMaskKeys(m)+ ? roundCircle(m.w ?? 0.5)+ : kind === "subject" && m.kind !== "subject" && target.subjectStartsBehind+ ? { invert: true }+ : {};+ target.set({ ...m, ...patch, kind });+ }}+ >+ <MaskShapeIcon kind={s.id} />+ <span className="w-full truncate text-center">{s.label}</span>+ </button>+ ))}+ </div>{!subject && (<KeyRowelement={target.element}@@ -3517,8 +3578,21 @@ function MaskSection({ target }: { target: MaskTarget }) {)}{sizeAxes.length > 0 && (<Row label="Size">- {sizeAxes.map((axis) => (+ {sizeAxes.map((axis, i) => (<span key={axis} className="flex items-center gap-1">+ {i === 1 && (+ <Button+ variant="ghost"+ size="icon"+ className={cn("size-6", sizeLinked ? "text-foreground" : "text-muted-foreground/60")}+ aria-label={sizeLinked ? "Unlink width and height" : "Link width and height"}+ aria-pressed={sizeLinked}+ title={sizeLinked ? "Sizes move together" : "Sizes move on their own"}+ onClick={() => setLinked(!sizeLinked)}+ >+ {sizeLinked ? <Link2 className="size-3.5" /> : <Link2Off className="size-3.5" />}+ </Button>+ )}<span className="text-[11px] text-muted-foreground/70 uppercase">{axis}</span><ScrubValuelabel={`Mask ${axis === "w" ? "width" : "height"}`}@@ -3532,11 +3606,11 @@ function MaskSection({ target }: { target: MaskTarget }) {parse={parseNumberInput}onScrub={(v) => {sizeCk.begin();- writeGeom({ [axis]: v / 100 });+ writeSize(axis, v / 100);}}onCommit={(v) => {sizeCk.begin();- writeGeom({ [axis]: v / 100 });+ writeSize(axis, v / 100);sizeCk.end();}}/>@@ -3576,7 +3650,7 @@ function MaskSection({ target }: { target: MaskTarget }) {valueClassName="w-9 text-muted-foreground"value={geom.feather}min={0}- max={120}+ max={MASK_FEATHER_MAX}step={1}format={(v) => String(Math.round(v))}parse={parseNumberInput}@@ -3591,27 +3665,25 @@ function MaskSection({ target }: { target: MaskTarget }) {}}/></Row>- {(m.kind === "rect" || m.kind === "square") && (+ {maskHasRadius(m.kind) && (<Row label="Radius"><ValueSliderlabel="Mask corner radius"sliderClassName="data-horizontal:w-24"valueClassName="w-9 text-muted-foreground"- value={m.radius ?? 0}+ value={geom.radius}min={0}- max={200}+ max={MASK_RADIUS_MAX}step={1}format={(v) => String(Math.round(v))}parse={parseNumberInput}onDraft={(v) => {radiusCk.begin();- const radius = Math.round(v);- target.setTransient({ ...m, radius: radius === 0 ? undefined : radius });+ writeGeom({ radius: Math.round(v) });}}onCommit={(v) => {radiusCk.begin();- const radius = Math.round(v);- target.setTransient({ ...m, radius: radius === 0 ? undefined : radius });+ writeGeom({ radius: Math.round(v) });radiusCk.end();}}/>diff --git a/site/src/cut/components/OverlayLayer.tsx b/site/src/cut/components/OverlayLayer.tsxindex a27326fa..30355f3d 100644--- a/site/src/cut/components/OverlayLayer.tsx+++ b/site/src/cut/components/OverlayLayer.tsx@@ -15,7 +15,7 @@ import {subtitleLaneCount,trackPos,} from "@/cut/lib/subtitles";-import { evalOverlayFrame, glyphStateAt, hasGlyphMotion, hasMaskKeys, hasOverlayKeys, isOverlayAnimated, lineLikeShape, maskFrameAt, overlayWords, paintMaskCoverage, resolveShadow, shapeMetrics, shapePathD, textStretch, WORD_ACCENT_DEFAULT, wordDrawsAt, type LottieHandle, type Mask, type MaskKey, type OverlayFrameState, type WordDraw } from "@donkeycut/effects-kit";+import { evalOverlayFrame, glyphStateAt, hasGlyphMotion, hasMaskKeys, hasOverlayKeys, isOverlayAnimated, lineLikeShape, MASK_FEATHER_MAX, MASK_RADIUS_MAX, maskFrameAt, maskHasRadius, maskOutlinePathD, maskSizeAxes, overlayWords, paintMaskCoverage, resolveShadow, shapeMetrics, shapePathD, textStretch, WORD_ACCENT_DEFAULT, wordDrawsAt, type LottieHandle, type Mask, type MaskKey, type OverlayFrameState, type WordDraw } from "@donkeycut/effects-kit";import {LINE_HEIGHT,PLATE_PAD_X,@@ -1372,9 +1372,11 @@ function useMaskCss(/*** On-canvas mask editing, shared by elements and video clips: an amber* outline tracing the mask's edge — its interior moves the mask, a lollipop- * above rotates it and a corner grip resizes it (the band height, for- * mirror), with the same detents and red guide lines as the element's own- * handles. Coordinates are local+ * above rotates it, a corner grip resizes it (the band height, for mirror),+ * a chevron grip under the shape pulls the feather out and a grip inside the+ * top-left corner rounds a box's corners — with the same detents and red+ * guide lines as the element's own handles. A translucent band along the+ * edge shows how far the feather reaches. Coordinates are local* px around the layer's anchor — the mount point carries the layer's own* transform — and screen deltas are folded back through that transform via* `rotation`/`poseScale`, then through the mask's own angle for the resize.@@ -1397,6 +1399,7 @@ export function MaskGizmoCore({tLocal: number;rotation: number;poseScale: number;+ /** Keyed geometry: lands on the key at the playhead when keys exist. */writeGeom: (patch: Partial<Omit<MaskKey, "t">>) => void;begin: () => void;}) {@@ -1414,6 +1417,10 @@ export function MaskGizmoCore({} | null>(null);/** The angle the readout shows while a rotate drag runs; null when idle. */const [spin, setSpin] = useState<number | null>(null);+ /** The feather value shown while its grip drags; null when idle. */+ const [soft, setSoft] = useState<number | null>(null);+ /** The corner radius shown while its grip drags; null when idle. */+ const [round, setRound] = useState<number | null>(null);const interiorRef = useRef<HTMLDivElement>(null);// Screen deltas → the box's local space (undo the element transform).const toLocal = (dx: number, dy: number) => {@@ -1425,8 +1432,7 @@ export function MaskGizmoCore({};};const theta = (f.rotation * Math.PI) / 180;- const sizable =- m.kind === "rect" || m.kind === "square" || m.kind === "circle" || m.kind === "mirror";+ const sizable = maskSizeAxes(m.kind).length > 0;// The outline traces the mask's hard edge in local px; a square's side is// `w` of the frame width on both axes (the painter's rule), and// linear/mirror edges run wider than any frame so they always cross it.@@ -1450,6 +1456,14 @@ export function MaskGizmoCore({// the center onto dead center, within a couple percent of the frame.const snapTo = (v: number, target: number) => (Math.abs(v - target) < 0.02 ? target : v);const designScale = Math.min(stageWidth, stageHeight) / 1080;+ const radiusPx = f.radius * designScale;+ // The feather's reach on stage: the painter blurs the hard edge with+ // σ = feather / 2, so the transition spans about the feather width centered+ // on the edge; a mirror band's feather never exceeds the band.+ const featherPx = Math.min(f.feather * designScale, m.kind === "mirror" ? h : Infinity);+ const outlineD = maskOutlinePathD(m, w, h, span, radiusPx);+ // Where the shape's bottom edge sits in its own frame, for the feather grip.+ const bottom = m.kind === "linear" ? 0 : m.kind === "square" ? w / 2 : h / 2;const edge = {className: "pointer-events-none",fill: "none" as const,@@ -1571,6 +1585,50 @@ export function MaskGizmoCore({onUp: () => setGuide(null),});};+ // The chevron grip pulls the feather: dragging away from the shape along+ // its own down axis softens the edge, back in hardens it. Feather is design+ // px, so the stage delta divides by the design scale.+ const featherMask = (e: React.PointerEvent) => {+ e.stopPropagation();+ begin();+ const g0 = f;+ setSoft(Math.round(g0.feather));+ startDrag(e, {+ cursor: () => "ns-resize",+ onMove: (dx, dy) => {+ const l = toLocal(dx, dy);+ const my = -l.x * Math.sin(theta) + l.y * Math.cos(theta);+ const feather = Math.round(+ Math.min(MASK_FEATHER_MAX, Math.max(0, g0.feather + my / designScale))+ );+ setSoft(feather);+ writeGeom({ feather });+ },+ onUp: () => setSoft(null),+ });+ };+ // The corner grip slides along the box's diagonal: inward rounds the+ // corners, outward squares them.+ const roundMask = (e: React.PointerEvent) => {+ e.stopPropagation();+ begin();+ const r0 = f.radius;+ const side = m.kind === "square" ? w : h;+ const cap = Math.min(MASK_RADIUS_MAX, Math.min(w, side) / 2 / designScale);+ setRound(Math.round(r0));+ startDrag(e, {+ cursor: () => "nwse-resize",+ onMove: (dx, dy) => {+ const l = toLocal(dx, dy);+ const mx = l.x * Math.cos(theta) + l.y * Math.sin(theta);+ const my = -l.x * Math.sin(theta) + l.y * Math.cos(theta);+ const radius = Math.round(Math.min(cap, Math.max(0, r0 + (mx + my) / 2 / designScale)));+ setRound(radius);+ writeGeom({ radius });+ },+ onUp: () => setRound(null),+ });+ };// The whole interior moves the mask, so a drag can start anywhere inside// the outline; linear/mirror get a grabbable strip along their edge line.const grabW = m.kind === "linear" || m.kind === "mirror" ? span * 2 : w;@@ -1586,8 +1644,11 @@ export function MaskGizmoCore({width: grabW,height: grabH,transform: `translate(-50%, -50%) rotate(${f.rotation}deg)`,- borderRadius:- m.kind === "circle" ? "50%" : (m.radius ?? 0) * designScale,+ // The grab area is the shape itself: a box's rounded corners, an+ // ellipse, or the polygon's own outline.+ ...(m.kind === "linear" || m.kind === "mirror"+ ? {}+ : { clipPath: `path("${maskOutlinePathD(m, w, h, span, radiusPx, grabW / 2, grabH / 2)}")` }),}}onPointerDown={beginMove}/>@@ -1598,27 +1659,83 @@ export function MaskGizmoCore({style={{ left: `calc(50% + ${cx}px)`, top: `calc(50% + ${cy}px)` }}><g transform={`rotate(${f.rotation})`}>- {m.kind === "rect" || m.kind === "square" ? (- <rect- x={-w / 2}- y={-h / 2}- width={w}- height={h}- rx={(m.radius ?? 0) * designScale}- {...edge}+ {featherPx > 0 && (+ <path+ d={outlineD}+ fill="none"+ stroke="#ff9f0a"+ strokeOpacity={0.22}+ strokeWidth={featherPx}+ strokeLinejoin="round"/>- ) : m.kind === "circle" ? (- <ellipse cx={0} cy={0} rx={w / 2} ry={h / 2} {...edge} />- ) : m.kind === "linear" ? (- <line x1={-span} y1={0} x2={span} y2={0} {...edge} />- ) : m.kind === "mirror" ? (- <>- <line x1={-span} y1={-h / 2} x2={span} y2={-h / 2} {...edge} />- <line x1={-span} y1={h / 2} x2={span} y2={h / 2} {...edge} />- </>- ) : null}+ )}+ <path d={outlineD} {...edge} /></g></svg>+ <div+ className="pointer-events-none absolute"+ style={{+ left: `calc(50% + ${cx}px)`,+ top: `calc(50% + ${cy}px)`,+ width: 0,+ height: 0,+ transform: `rotate(${f.rotation}deg)`,+ }}+ >+ <div+ className="absolute left-0"+ style={{ top: bottom + featherPx / 2 + 22, transform: "translate(-50%, -50%)" }}+ >+ {soft !== null && (+ <span+ className="absolute left-1/2 top-full mt-1.5 rounded-full bg-black/55 px-2 py-0.5 text-[11px] font-medium tabular-nums text-white"+ style={{ transform: `translateX(-50%) rotate(${-(rotation + f.rotation)}deg)` }}+ >+ {soft}+ </span>+ )}+ {/* The grip wears the softness it controls: a ring that blurs+ outward, in the mask's amber like every other mask grip. */}+ <span+ title="Drag to feather the edge"+ onPointerDown={featherMask}+ className="pointer-events-auto block size-[13px] cursor-ns-resize rounded-full border-[2.5px] bg-white"+ style={{+ borderColor: "#ff9f0a",+ boxShadow: "0 0 0 3px rgba(255,159,10,0.35), 0 0 8px 4px rgba(255,159,10,0.3), 0 1px 4px rgba(0,0,0,0.4)",+ }}+ />+ </div>+ {maskHasRadius(m.kind) && (+ <div+ className="absolute"+ style={{+ left: -w / 2 + radiusPx * 0.3 + 14,+ top: -(m.kind === "square" ? w : h) / 2 + radiusPx * 0.3 + 14,+ transform: "translate(-50%, -50%)",+ }}+ >+ {round !== null && (+ <span+ className="absolute bottom-full left-1/2 mb-1.5 rounded-full bg-black/55 px-2 py-0.5 text-[11px] font-medium tabular-nums text-white"+ style={{ transform: `translateX(-50%) rotate(${-(rotation + f.rotation)}deg)` }}+ >+ {round}+ </span>+ )}+ <span+ title="Drag to round the corners"+ onPointerDown={roundMask}+ className="pointer-events-auto grid size-[16px] cursor-nwse-resize place-items-center rounded-full border-[2.5px] bg-white shadow-[0_1px_4px_rgba(0,0,0,0.4)]"+ style={{ borderColor: "#ff9f0a" }}+ >+ <svg viewBox="0 0 10 10" className="size-[7px]" fill="none" stroke="#ff9f0a" strokeWidth={2}>+ <path d="M1 9 V5 A4 4 0 0 1 5 1 H9" />+ </svg>+ </span>+ </div>+ )}+ </div>{guide && (<svgclassName="pointer-events-none absolute z-10 overflow-visible"diff --git a/site/src/cut/lib/aiTools.ts b/site/src/cut/lib/aiTools.tsindex 492502fc..db705dff 100644--- a/site/src/cut/lib/aiTools.ts+++ b/site/src/cut/lib/aiTools.ts@@ -42,6 +42,10 @@ import {STROKE_OFFSET_MAX,STROKE_STYLES,STROKE_WIDTH_MAX,+ MASK_FEATHER_MAX,+ MASK_KINDS,+ MASK_RADIUS_MAX,+ maskHasRadius,type RemovalStroke,type StrokeStyleId,} from "@donkeycut/effects-kit";@@ -625,27 +629,30 @@ const toolRuns: Record<BrowserToolName, ToolRun> = {setMask(undefined);return { id: input.id, mask: null };}- const kinds = ["rect", "square", "circle", "linear", "mirror", "subject"];const kind =typeof input.kind === "string"? input.kind: (current?.kind ?? "rect");- if (!kinds.includes(kind)) throw new ToolError(`Unknown mask kind. Use one of: ${kinds.join(", ")}, none.`);+ if (!(MASK_KINDS as string[]).includes(kind))+ throw new ToolError(`Unknown mask kind. Use one of: ${MASK_KINDS.join(", ")}, none.`);const geom = (k: Record<string, unknown>) => ({...(isNum(k.x) ? { x: clamp(k.x, -1, 1) } : {}),...(isNum(k.y) ? { y: clamp(k.y, -1, 1) } : {}),...(isNum(k.w) ? { w: clamp(k.w, 0.01, 2) } : {}),...(isNum(k.h) ? { h: clamp(k.h, 0.01, 2) } : {}),...(isNum(k.rotation) ? { rotation: clamp(Math.round(k.rotation), -180, 180) } : {}),- ...(isNum(k.feather) ? { feather: clamp(k.feather, 0, 200) } : {}),+ ...(isNum(k.feather) ? { feather: clamp(k.feather, 0, MASK_FEATHER_MAX) } : {}),+ ...(isNum(k.radius) ? { radius: clamp(k.radius, 0, MASK_RADIUS_MAX) } : {}),});const mask: Mask = {...(current ?? {}),...geom(input),kind: kind as Mask["kind"],...(typeof input.invert === "boolean" ? { invert: input.invert || undefined } : {}),- ...(isNum(input.radius) ? { radius: clamp(input.radius, 0, 400) || undefined } : {}),+ ...(isNum(input.radius) ? { radius: clamp(input.radius, 0, MASK_RADIUS_MAX) || undefined } : {}),};+ // A radius belongs to a box; a shape that has no corners to round drops it.+ if (!maskHasRadius(mask.kind)) delete mask.radius;// An element newly masked by the person starts behind them — the common// ask — unless the call named a direction; invert false shows it only on// the person. Clips keep the plain direction (Subject keeps the person).@@ -663,15 +670,13 @@ const toolRuns: Record<BrowserToolName, ToolRun> = {const fr = frameOf(s.aspect);mask.h = clamp(((mask.w ?? 0.5) * fr.w) / fr.h, 0.01, 2);}+ const dur = o ? Math.max(0.1, o.end - o.start) : clipLen(clip!);setMask(mask);// Keys layer on after the mask lands, so each one captures against the// geometry the call just set.const raw = input.keys;if (Array.isArray(raw)) {const st = useEditor.getState();- const dur = o- ? Math.max(0.1, o.end - o.start)- : clipLen(clip!);if (raw.length === 0) {if (o) st.clearOverlayMaskKeys(o.id);else st.clearClipMaskKeys(clip!.id);diff --git a/site/src/cut/server/ai/catalog.ts b/site/src/cut/server/ai/catalog.tsindex 2f6a56f6..901ba37b 100644--- a/site/src/cut/server/ai/catalog.ts+++ b/site/src/cut/server/ai/catalog.ts@@ -43,6 +43,7 @@ import {gradePresetCatalogText,HSL_BANDS,LOOK_EFFECTS,+ MASK_SHAPE_KINDS,OVERLAY_ANIM_STYLE_IDS,OVERLAY_LOOP_STYLE_IDS,SOUND_EQ_BANDS,@@ -200,7 +201,7 @@ Effects (add_effect): time-ranged treatments over the finished cut. Three familiAdvanced text (update_overlay): italic, align (multi-line), letter_spacing (em), line_height, stretch_x/stretch_y (glyph stretch multipliers, the side grips' axis-only resize), stroke_color/stroke_width (em outline behind the fill), and richer shadows. Bundled Google families join the system set — ${GOOGLE_FONT_IDS.join(", ")} — and so do the user's own: a .ttf/.otf/.woff/.woff2 file dropped on the Library is offered in every project under a font id like "font:<id>". Editor_state lists the ones this account has under \`fonts\` — use an id from there instead of guessing at a family name, and when someone asks for a typeface that is not in the list, tell them the Library takes font files.Animation (set_overlay_animation): every element takes preset In/Out ramps (${OVERLAY_ANIM_STYLE_IDS.join(", ")} — typewriter for titles only; the per-letter styles sweep a title character by character), a Loop (${OVERLAY_LOOP_STYLE_IDS.join(", ")}) that runs its whole duration, and a Move that says what it does WHILE it holds. A title takes one more: Words (${WORD_EFFECT_IDS.join(", ")}), which plays the line word by word — an emphasis travelling along a line that is fully up, or a build assembling the line as it is spoken. Entrances 0.3–0.6s read well; one loop per scene, sparingly; a move on the lines that matter. All of them are slots on the element, applied internally; the keyframe track (set_overlay_keyframes) is the separate power tier for motion the names do not cover, and slots compose over it.Keyframes (set_overlay_keyframes): for motion no preset covers — a path across the frame, a slow push in, a drift that holds first. A key is a whole pose (position, scale, rotation, opacity) at a time in seconds from the element's start; the pose moves linearly between keys and holds outside them, and presets still compose on top. Two or three keys carry almost everything; reach for a preset first and keyframes when the user describes a specific path or timing. In the UI the diamond in the inspector adds a key at the playhead, and dragging the element then records into it. set_clip_keyframes is the same track on a video clip (any track): pans, push-ins, picture-in-picture flights, spins, and fades on the footage itself.-Masks (set_mask): trim any element or video clip to a shape — rect, square, circle, linear, mirror — with feather, invert, and its own keyframe track for reveals and wipes. The subject kind trims by the person in the shot (on-device segmentation; preview and export match): inverted sits the item behind the speaker, plain keeps it only on the speaker. Behind-speaker reads well when the speaker is clearly separated from the background; with no detectable person it degrades to the plain picture. Groups: the user can group elements (select several, Group in the inspector) — selecting one selects all, and moves/resize/rotate/timing ride together.+Masks (set_mask): trim any element or video clip to a shape — ${MASK_SHAPE_KINDS.join(", ")} — with feather, invert, rounded corners on a box, and its own keyframe track for reveals and wipes. The subject kind trims by the person in the shot (on-device segmentation; preview and export match): inverted sits the item behind the speaker, plain keeps it only on the speaker. Behind-speaker reads well when the speaker is clearly separated from the background; with no detectable person it degrades to the plain picture. Groups: the user can group elements (select several, Group in the inspector) — selecting one selects all, and moves/resize/rotate/timing ride together.Composite builds: these primitives compose. Stacked overlay video copies, masks and their keys, pose keyframes, staggered starts, and shapes construct effects beyond any preset list. Given a reference (a screenshot or clip of an effect the user wants), reverse-engineer it:1. Read the reference as layers. For each visible piece, decide what it is: live footage, a cropped or repeated slice of the footage, a solid graphic, text, or empty background.2. Map each layer to a primitive. A slice of the picture = a copy of the same asset on its own overlay track (add_overlay_video, layout full, matching trim so every copy's picture lines up with the base) trimmed by a mask whose x/y offsets place it — a full-frame copy under a mask shows the true part of the picture at that spot, so masked copies tile back into the whole image. Gap lines and borders come from sizing masks under their spacing (track 0 left empty plays black through the gaps) or from stroked shapes. Solid panels are shapes; words are titles.