Skip to content

Open source CapCut alternative.

TypeScript

feat(site): name any timeline item [rebuild]

David Lef2dd9316bee4
diff --git a/site/packages/effects-kit/src/types.ts b/site/packages/effects-kit/src/types.ts
index 2db0f4e6..44aa9a6f 100644
--- a/site/packages/effects-kit/src/types.ts
+++ b/site/packages/effects-kit/src/types.ts
@@ -14,6 +14,10 @@ import type { WordDraw } from "./words/types";
/** Fields every overlay element carries, whatever its kind. */
export interface OverlayBase {
id: string;
+ /** What the person calls this element: the timeline chip, the inspector
+ * title and chat references read it. Absent = named by what it is (a
+ * title's text, a shape's kind). */
+ name?: string;
start: number; // timeline seconds
end: number;
x: number; // center, fraction of frame width 0..1
diff --git a/site/src/cut/components/Inspector.tools.ts b/site/src/cut/components/Inspector.tools.ts
index a35d4e2f..804d57e2 100644
--- a/site/src/cut/components/Inspector.tools.ts
+++ b/site/src/cut/components/Inspector.tools.ts
@@ -69,9 +69,10 @@ export const INSPECTOR_TOOLS = [
{
name: "update_overlay",
description:
- "Update any overlay element — title, shape, or sticker — by id (from the selection or state). Titles take text/size/font/weight/color/shadow/plate; shapes take w/h/fill/fill_opacity/radius/stroke; stickers take w/h. Every kind takes timing, position, rotation, opacity, hidden. This is the tool for 'make this text better' requests too.",
+ "Update any overlay element — title, shape, or sticker — by id (from the selection or state). Titles take text/size/font/weight/color/shadow/plate; shapes take w/h/fill/fill_opacity/radius/stroke; stickers take w/h. Every kind takes name, timing, position, rotation, opacity, hidden. This is the tool for 'make this text better' requests too.",
inputSchema: obj({
id: str("Overlay element id"),
+ name: str("What the person calls this element — shown on its timeline chip and inspector title (empty string clears it, back to what it is)"),
text: str("New text (titles)"),
follows_clip: bool(
"Whether the element rides the clip under it (on by default): true homes it to that clip, false frees it where it is"
diff --git a/site/src/cut/components/Inspector.tsx b/site/src/cut/components/Inspector.tsx
index 509e47fe..41f68671 100644
--- a/site/src/cut/components/Inspector.tsx
+++ b/site/src/cut/components/Inspector.tsx
@@ -25,7 +25,6 @@ import { Switch } from "@/components/ui/switch";
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip";
import { Textarea } from "@/components/ui/textarea";
import {
- EFFECT_LABELS,
hasMaskKeys,
hasOverlayAnim,
hasOverlayKeys,
@@ -123,7 +122,6 @@ import {
onFontsChanged,
rectOf,
regionLabel,
- SHAPE_LABELS,
SPEED_FLOOR,
SPEED_MAX,
SPEED_MIN,
@@ -136,6 +134,7 @@ import {
type LayoutId,
type EffectOverlay,
type MediaAsset,
+ overlayName,
type Overlay,
type ShapeOverlay,
type StickerOverlay,
@@ -353,22 +352,86 @@ function RailButton({
);
}
-function PanelTitle({ children }: { children: React.ReactNode }) {
+/** An element panel's title: the element's name, typed over in place. What
+ * it is — the text, the shape, the effect — stands in until a name is given
+ * and again when the name is cleared. Enter or leaving the field commits;
+ * Escape puts back what was there. The timeline chip and chat references
+ * show the same name. */
+function ElementTitle({ overlay: o }: { overlay: Overlay }) {
+ const update = useEditor((s) => s.updateOverlay);
+ const [draft, setDraft] = useState<string | null>(null);
+ const shown = draft ?? o.name ?? "";
+ const commit = () => {
+ if (draft === null) return;
+ const name = draft.trim().slice(0, 60);
+ setDraft(null);
+ if ((name || undefined) !== (o.name || undefined)) update(o.id, { name: name || undefined });
+ };
return (
- <div className="flex h-10 shrink-0 items-center px-3.5 text-sm font-semibold tracking-tight">
- {children}
+ <div className="flex h-10 shrink-0 items-center px-3.5">
+ <input
+ key={o.id}
+ aria-label="Element name"
+ className="h-7 w-full min-w-0 rounded-md bg-transparent px-1 -mx-1 text-sm font-semibold tracking-tight outline-none placeholder:text-foreground focus:bg-muted/60 focus:placeholder:text-muted-foreground"
+ value={shown}
+ placeholder={overlayName({ ...o, name: undefined } as Overlay) || "Text"}
+ spellCheck={false}
+ onChange={(e) => setDraft(e.target.value)}
+ onBlur={commit}
+ onKeyDown={(e) => {
+ if (e.key === "Enter") e.currentTarget.blur();
+ if (e.key === "Escape") {
+ setDraft(null);
+ e.currentTarget.blur();
+ }
+ }}
+ />
</div>
);
}
-/** One-line header for a media clip's panel: the file name (ellipsised, with
- * the full name in its hover tooltip) and the clip's running length. */
-function ClipHead({ name, time }: { name?: string; time: string }) {
+/** One-line header for a media clip's panel: the clip's name, typed over
+ * in place (the file's name stands in until one is given, and again when it
+ * is cleared), and the clip's running length. Enter or leaving the field
+ * commits; Escape puts back what was there. The timeline bar shows the same
+ * name. */
+function ClipHead({
+ clip,
+ fileName,
+ time,
+ onRename,
+}: {
+ clip: { id: string; name?: string };
+ fileName?: string;
+ time: string;
+ onRename: (name: string | undefined) => void;
+}) {
+ const [draft, setDraft] = useState<string | null>(null);
+ const commit = () => {
+ if (draft === null) return;
+ const name = draft.trim().slice(0, 60);
+ setDraft(null);
+ if ((name || undefined) !== (clip.name || undefined)) onRename(name || undefined);
+ };
return (
<div className="mb-1.5 flex h-10 shrink-0 items-center justify-between gap-2 border-b border-border">
- <div className="min-w-0 truncate text-sm font-semibold tracking-tight" title={name}>
- {name}
- </div>
+ <input
+ key={clip.id}
+ aria-label="Clip name"
+ className="h-7 w-full min-w-0 rounded-md bg-transparent px-1 -mx-1 text-sm font-semibold tracking-tight outline-none placeholder:text-foreground focus:bg-muted/60 focus:placeholder:text-muted-foreground"
+ value={draft ?? clip.name ?? ""}
+ placeholder={fileName}
+ spellCheck={false}
+ onChange={(e) => setDraft(e.target.value)}
+ onBlur={commit}
+ onKeyDown={(e) => {
+ if (e.key === "Enter") e.currentTarget.blur();
+ if (e.key === "Escape") {
+ setDraft(null);
+ e.currentTarget.blur();
+ }
+ }}
+ />
<Value className="shrink-0 text-muted-foreground">{time}</Value>
</div>
);
@@ -1097,7 +1160,12 @@ function ClipPanel({ clip }: { clip: VideoClip }) {
return (
<>
<div className="flex flex-col gap-1 px-3.5 pb-4">
- <ClipHead name={asset?.name} time={formatTime(speedLen)} />
+ <ClipHead
+ clip={clip}
+ fileName={asset?.name}
+ time={formatTime(speedLen)}
+ onRename={(name) => updateClip(clip.id, { name })}
+ />
<Row label="Trim">
<ScrubValue
label="Trim start"
@@ -1577,7 +1645,12 @@ function AudioPanel({ clip }: { clip: AudioClip }) {
return (
<>
<div className="flex flex-col gap-1 px-3.5 pb-4">
- <ClipHead name={asset?.name} time={formatTime(len)} />
+ <ClipHead
+ clip={clip}
+ fileName={asset?.name}
+ time={formatTime(len)}
+ onRename={(name) => useEditor.getState().updateAudio(clip.id, { name })}
+ />
<Row label="Trim">
<ScrubValue
label="Trim start"
@@ -1796,7 +1869,7 @@ function TextPanel({ overlay: o }: { overlay: TextOverlay }) {
return (
<>
- <PanelTitle>Text</PanelTitle>
+ <ElementTitle overlay={o} />
<div className="flex flex-col gap-1 px-3.5 pb-4">
<div className="relative mb-2">
<Textarea
@@ -3690,7 +3763,7 @@ function ShapePanel({ overlay: o }: { overlay: ShapeOverlay }) {
const boxShape = !lineLikeShape(o.shape);
return (
<>
- <PanelTitle>{SHAPE_LABELS[o.shape]}</PanelTitle>
+ <ElementTitle overlay={o} />
<div className="flex flex-col gap-1 px-3.5 pb-4">
<Row label={boxShape ? "Fill" : "Color"}>
<ColorField
@@ -3819,7 +3892,7 @@ function EffectPanel({ overlay: o }: { overlay: EffectOverlay }) {
const amountCk = useSliderCheckpoint();
return (
<>
- <PanelTitle>{EFFECT_LABELS[o.effect]}</PanelTitle>
+ <ElementTitle overlay={o} />
{/* Which effect this is belongs to the Effects tab: it marks this one and
swaps it on a click, so the panel is only its knobs. */}
<div className="flex flex-col gap-1 px-3.5 pb-4">
@@ -3999,7 +4072,7 @@ function StickerPanel({ overlay: o }: { overlay: StickerOverlay }) {
);
return (
<>
- <PanelTitle>Sticker</PanelTitle>
+ <ElementTitle overlay={o} />
<div className="flex flex-col gap-1 px-3.5 pb-4">
{asset ? (
<div className="mb-1 truncate text-[12px] text-muted-foreground" title={asset.name}>
diff --git a/site/src/cut/components/Timeline.tools.ts b/site/src/cut/components/Timeline.tools.ts
index 0fe00fea..ce39b741 100644
--- a/site/src/cut/components/Timeline.tools.ts
+++ b/site/src/cut/components/Timeline.tools.ts
@@ -87,6 +87,12 @@ export const TIMELINE_TOOLS = [
description: "Mute or unmute a video clip's own audio.",
inputSchema: obj({ clipId: str("Video clip id"), muted: bool("true to mute") }, ["clipId", "muted"]),
},
+ {
+ name: "rename_item",
+ description:
+ "Name any timeline item — a video or image clip on any track, a soundtrack clip, or a title/shape/sticker/effect element — by id. The name shows on its timeline bar, in the inspector and in editor_state, so a cut full of look-alike items stays legible. An empty name clears it, back to the file's name or what the element is.",
+ inputSchema: obj({ id: str("Clip, soundtrack clip, or element id"), name: str("The name, up to 60 characters; empty clears") }, ["id", "name"]),
+ },
{
name: "set_clip_hidden",
description:
diff --git a/site/src/cut/components/Timeline.tsx b/site/src/cut/components/Timeline.tsx
index 2a93c902..530554b9 100644
--- a/site/src/cut/components/Timeline.tsx
+++ b/site/src/cut/components/Timeline.tsx
@@ -59,7 +59,7 @@ import { useMatteBakes } from "@/cut/lib/removal/bakeJobs";
import { laneHidden, subtitleLaneCount } from "@/cut/lib/subtitles";
import { formatTime, formatTimecode } from "@/cut/lib/time";
import { EFFECT_LABELS, hasSpeedCurve, headSrc, retimeOf, SPEED_CURVE_MAX, SPEED_CURVE_MIN, tailSrc, type EffectId, type Retime, type SpeedNode } from "@donkeycut/effects-kit";
-import { assetIsSilent, emptySubtitles, fontStack, IMAGE_CLIP_SECONDS, isAudioTransition, isTextOverlay, SHAPE_LABELS, TRANSITION_MAX, TRANSITION_STYLE_LABELS, transitionBarStart, transitionDefaultSeconds, XBAR_MAGNET_PX, type ShapeKind } from "@/cut/lib/types";
+import { assetIsSilent, emptySubtitles, fontStack, IMAGE_CLIP_SECONDS, isAudioTransition, clipName, isTextOverlay, overlayName, SHAPE_LABELS, TRANSITION_MAX, TRANSITION_STYLE_LABELS, transitionBarStart, transitionDefaultSeconds, XBAR_MAGNET_PX, type ShapeKind } from "@/cut/lib/types";
import type { AudioClip, ClipSpan, ColorGrade, MediaAsset, Overlay, Selection, StickerOverlay, SubtitleCue, TimelineTransition, TransitionBoundaryKind, TransitionStyle, VideoClip } from "@/cut/lib/types";
import { isLottieAsset } from "@/cut/lib/lottieAssets";
import { gradeCssApprox } from "@donkeycut/effects-kit";
@@ -3887,6 +3887,18 @@ function ClipView({
{barW >= 96 ? "Cutting…" : "C…"}
</span>
)}
+ {clip.name && !baking && !drag && (
+ // A clip the person named wears it over the film, where the hover
+ // controls live: it steps aside for the mention chip as they arrive.
+ <span
+ className={cn(
+ "tl-name-chip pointer-events-none absolute top-1 left-1 z-2 max-w-[calc(100%-8px)] truncate rounded-[5px] bg-black/65 px-1.5 py-px text-[10px] text-white transition-opacity",
+ mention && !loading && "group-hover:opacity-0"
+ )}
+ >
+ {clip.name}
+ </span>
+ )}
{mention &&
(drag ? (
<span className="tl-dur-chip pointer-events-none absolute top-1 left-1 z-2 rounded-[5px] bg-black/65 px-1.5 py-px font-mono text-[10px] tabular-nums text-white">
@@ -5316,7 +5328,7 @@ function AudioView({
mention && !drag && "group-hover:opacity-0"
)}
>
- {asset.name}
+ {clipName(clip, asset)}
</span>
{mention && !drag && !loading && (
<span className="tl-mention-chip pointer-events-none absolute top-1 left-1 z-2 rounded-[5px] bg-black/65 px-1.5 py-px font-mono text-[10px] text-white opacity-0 transition-opacity group-hover:opacity-100">
@@ -5666,20 +5678,20 @@ function TextBar({
o.kind === "shape" ? (
<>
<ShapeIcon className="mr-1 size-2.5 shrink-0" />
- {SHAPE_LABELS[o.shape]}
+ {overlayName(o)}
</>
) : o.kind === "sticker" ? (
<>
<StickerThumb overlay={o} />
- Sticker
+ {overlayName(o)}
</>
) : o.kind === "effect" ? (
<>
<EffectChipIcon effect={o.effect} />
- {EFFECT_LABELS[o.effect]}
+ {overlayName(o)}
</>
) : (
- o.text.replace(/\n/g, " ")
+ overlayName(o)
);
return (
diff --git a/site/src/cut/lib/aiContext.ts b/site/src/cut/lib/aiContext.ts
index 3180ef1d..094c51dc 100644
--- a/site/src/cut/lib/aiContext.ts
+++ b/site/src/cut/lib/aiContext.ts
@@ -23,6 +23,7 @@ import {
type ClipSpan,
type MediaAsset,
type MediaFolder,
+ overlayName,
type Overlay,
type ProjectDoc,
type SubtitlesBlock,
@@ -465,6 +466,7 @@ function describeState(
index,
id: sp.clip.id,
asset: sp.asset.name,
+ ...(sp.clip.name ? { name: sp.clip.name } : {}),
start: r(sp.start),
len: r(sp.len),
in: r(sp.clip.in),
@@ -615,13 +617,14 @@ function describeRate(c: { speed?: number; speedCurve?: SpeedNode[]; reverse?: b
}
function describeAudio(
- a: { assetId: string; start: number; in: number; out: number; volume: number; fadeIn?: number; fadeOut?: number; speed?: number; speedCurve?: SpeedNode[]; reverse?: boolean; sound?: ClipSound; duck?: number; lane?: number; hidden?: boolean },
+ a: { assetId: string; name?: string; start: number; in: number; out: number; volume: number; fadeIn?: number; fadeOut?: number; speed?: number; speedCurve?: SpeedNode[]; reverse?: boolean; sound?: ClipSound; duck?: number; lane?: number; hidden?: boolean },
assets: Map<string, { name: string }>
) {
const rt = retimeOf(a);
const speed = rt.rate;
return {
asset: assets.get(a.assetId)?.name ?? a.assetId,
+ ...(a.name ? { name: a.name } : {}),
start: r(a.start),
len: r(rt.len),
in: r(a.in),
@@ -642,6 +645,7 @@ function describeOverlayClip(c: VideoClip, assets: Map<string, { name: string }>
const rect = rectOf(c);
return {
asset: assets.get(c.assetId)?.name ?? c.assetId,
+ ...(c.name ? { name: c.name } : {}),
track: c.track,
start: r(c.start),
len: r(retimeOf(c).len),
@@ -677,6 +681,7 @@ function describeOverlayClip(c: VideoClip, assets: Map<string, { name: string }>
function describeOverlay(o: Overlay) {
const base = {
kind: o.kind ?? "text",
+ name: overlayName(o),
start: r(o.start),
end: r(o.end),
x: r(o.x),
diff --git a/site/src/cut/lib/aiTools.ts b/site/src/cut/lib/aiTools.ts
index fc68a4f8..2d301110 100644
--- a/site/src/cut/lib/aiTools.ts
+++ b/site/src/cut/lib/aiTools.ts
@@ -1611,6 +1611,16 @@ const toolRuns: Record<BrowserToolName, ToolRun> = {
return { id: next.id, volume: next.volume ?? 1 };
},
+ rename_item: (s, input) => {
+ const name = String(input.name ?? "").trim().slice(0, 60) || undefined;
+ const id = String(input.id ?? "");
+ if (s.clips.some((c) => c.id === id)) s.updateClip(id, { name });
+ else if (s.audioClips.some((a) => a.id === id)) s.updateAudio(id, { name });
+ else if (s.overlays.some((o) => o.id === id)) s.updateOverlay(id, { name });
+ else throw new ToolError(`No clip, soundtrack clip, or element with id ${id}.`);
+ return { id, name: name ?? null };
+ },
+
set_clip_hidden: (s, input) => {
const clip = requireItem(s.clips, input.clipId, "video clip");
s.updateClip(clip.id, { hidden: input.hidden ? true : undefined });
@@ -4888,6 +4898,7 @@ function overlayPatch(input: Record<string, unknown>, kind: "text" | "shape" | "
if (isNum(input.opacity))
patch.opacity = input.opacity >= 0.995 ? undefined : clamp(input.opacity, 0, 1);
if (typeof input.hidden === "boolean") patch.hidden = input.hidden || undefined;
+ if (typeof input.name === "string") patch.name = input.name.trim().slice(0, 60) || undefined;
if (kind === "text") {
// A literal backslash-n in the call is always a meant newline — models
diff --git a/site/src/cut/lib/assetRef.ts b/site/src/cut/lib/assetRef.ts
index cb3ba702..f58d7a67 100644
--- a/site/src/cut/lib/assetRef.ts
+++ b/site/src/cut/lib/assetRef.ts
@@ -20,7 +20,7 @@ import {
isEffectOverlay,
isShapeOverlay,
isStickerOverlay,
- isTextOverlay,
+ overlayName,
SHAPE_LABELS,
TRANSITION_STYLE_IDS,
TRANSITION_STYLE_LABELS,
@@ -599,13 +599,7 @@ function overlayBaseName(o: Overlay, fallback: string): string {
// A sticker's identity is its art — the pill shows the thumbnail — and its
// asset name is often a generation prompt, which would collide with the
// media asset carrying the same name. It names by kind.
- const raw = isTextOverlay(o)
- ? o.text
- : isShapeOverlay(o)
- ? SHAPE_LABELS[o.shape]
- : isEffectOverlay(o)
- ? EFFECT_LABELS[o.effect]
- : "Sticker";
+ const raw = overlayName(o);
const clean = (raw ?? "")
.replace(/[\n"]+/g, " ")
.replace(/\s+/g, " ")
diff --git a/site/src/cut/lib/types.ts b/site/src/cut/lib/types.ts
index e92ef5d6..82a4209c 100644
--- a/site/src/cut/lib/types.ts
+++ b/site/src/cut/lib/types.ts
@@ -1,5 +1,6 @@
import type { GuideId, GuideLines } from "./guides";
import {
+ EFFECT_LABELS,
behindSubjectMask,
overlayKind,
poseAt,
@@ -508,6 +509,9 @@ export function regionLabel(r: FrameRect): string {
export interface VideoClip {
id: string;
assetId: string;
+ /** What the person calls this clip on the timeline and in the inspector;
+ * absent = the file's name. */
+ name?: string;
/** Which video track this clip sits on. Tracks number 0..N bottom-up:
* track 0's clips form the sequence that drives playback; higher tracks
* composite in front (highest wins where clips overlap). Every track
@@ -1005,6 +1009,9 @@ export function migrateLegacyTransitions(clips: VideoClip[]): VideoClip[] {
export interface AudioClip {
id: string;
assetId: string;
+ /** What the person calls this clip on the timeline and in the inspector;
+ * absent = the file's name. */
+ name?: string;
start: number; // timeline position, seconds
in: number;
out: number;
@@ -1276,6 +1283,26 @@ export function migrateBehindSubject<T extends Overlay>(overlays: T[]): T[] {
});
}
+/** The name a clip goes by: the one the person gave it, or its file's. */
+export function clipName(c: { name?: string }, asset: { name: string } | undefined): string {
+ return c.name?.trim() || asset?.name || "";
+}
+
+/**
+ * The name an element goes by everywhere it is listed: the one the person
+ * gave it, or what it is — a title's text on one line, a shape's kind, an
+ * effect's name, "Sticker". A title with nothing typed yet has no name;
+ * each surface shows its own stand-in for that.
+ */
+export function overlayName(o: Overlay): string {
+ const own = o.name?.trim();
+ if (own) return own;
+ if (isTextOverlay(o)) return o.text.replace(/\s*\n\s*/g, " ").trim();
+ if (isShapeOverlay(o)) return SHAPE_LABELS[o.shape];
+ if (isEffectOverlay(o)) return EFFECT_LABELS[o.effect];
+ return "Sticker";
+}
+
export const SHAPE_LABELS: Record<ShapeKind, string> = {
rect: "Rectangle",
ellipse: "Ellipse",
diff --git a/site/src/cut/server/ai/catalog.ts b/site/src/cut/server/ai/catalog.ts
index 0e4ab6b2..b0ed8416 100644
--- a/site/src/cut/server/ai/catalog.ts
+++ b/site/src/cut/server/ai/catalog.ts
@@ -107,6 +107,7 @@ Times are in seconds on the shared timeline. The playhead is currentTime; a skim
- split_at cuts the track-0 clip under that time into two clips at the exact frame. With a soundtrack or overlay clip selected it splits that instead.
- The Media and Library panels take the same gestures: ⌘/⇧-click a tile, or sweep a rubber-band over the grid, and dragging any picked tile onto the timeline lays the whole set down one after another from the drop point.
- The user can multi-select (⌘/⇧-click, or sweep a rubber-band over empty track space) across every kind at once — clips, audio, titles, cues. Deleting or copying acts on the whole selection, and dragging any member moves the set as one: every item shifts by the same time, relative spacing kept, while unselected items slide out of the way and flow back. A selection of one kind on the multi-row tracks (audio, titles) also retracks together on a vertical drag, one row past the end opening a new track. A hover chip on each video clip toggles its own audio.
+- Anything can be named: rename_item puts the person's own name on a clip, a soundtrack clip, or an element, and the timeline bar, the inspector title and editor_state show it (\`name\`, beside the file's \`asset\` name). A cut full of look-alike rectangles or takes stays legible that way; an empty name clears it.
- 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.
@@ -195,7 +196,7 @@ UI: select a clip → Inspector "Effects" opens the panel (Transition / In / Out
What the user sees on the transitions row: one badge per bar, and nothing else — the row holds no buttons, no placeholders, and no add-affordances. A playing bar is blue; a parked one is the same badge in grey. So a user reporting "greyed out transitions", "grey circles", or "dead/lingering transitions" on that row is describing parked bars, which are real objects saved in their project — never dismiss them as editor chrome or claim they won't export, because the badge is the transition itself. Read \`transitions\` in editor_state and answer from the parked entries there. A bar can also be hidden (set_transition_hidden): it grays out but keeps its cut, so the joint plays as a hard cut and the bar is there to switch back on — that is how to audition a cut without its blend. Grey elsewhere means something different: a clip, element, or track shown grayed is hidden (the \`hidden\` flag), which does drop out of playback and export.`,
"graphics": `# Graphics: titles, shapes & stickers
-The title lanes hold three overlay element kinds, all sharing timing (start/end), center position (x/y fractions 0..1), rotation (degrees), opacity, and a lane; \`overlays\` in editor_state lists them with their \`kind\`. All burn into the export exactly as previewed.
+The title lanes hold three overlay element kinds, all sharing a name (what the person calls it, or what it is — a title's text, "Rectangle"; \`name\` on update_overlay renames it, and the timeline chip, the inspector and @-references show that name, which is how a cut full of look-alike shapes stays legible), timing (start/end), center position (x/y fractions 0..1), rotation (degrees), opacity, and a lane; \`overlays\` in editor_state lists them with their \`kind\` and \`name\`. All burn into the export exactly as previewed.
Rows are how elements stack (\`lane\`, 0 = the front row; a higher row draws further back). Two elements on ONE row never overlap in time — placing a title where a shape already sits slides it clear instead of laying it on top — so anything meant to sit over something else names a LOWER row: title on lane 0, the background shape behind it on lane 1. Every add tool and update_overlay take \`lane\`.
An element rides the frames of the video clip under it (\`host\` in editor_state, the clip on the highest track beneath its middle): moving, retiming or splitting that clip carries the element over the same footage, trimming leaves it on the frames it covered, and deleting the clip leaves the element in place, homed to whatever now sits under it. Placing an element homes it automatically; update_overlay follows_clip:false frees one (\`free\` in editor_state) and true homes it again.
The frame's own color is set_background, not a full-frame rectangle: it fills the frame behind every clip and element, holds for the whole cut, letterboxes fitted footage, and shows through gaps on track 0. "Make the background white", a colored card behind a title sequence, a text-and-graphics video with no footage at all — all of them start with set_background. A rectangle element is for a panel or a band inside the frame, not for the frame itself.