Skip to content

Open source CapCut alternative.

TypeScript

feat(site): an inspector control for every setting the assistant writes

David Le787acfc8151d
diff --git a/docs/guides/cut/ai-assistant.md b/docs/guides/cut/ai-assistant.md
index c9a797db..9ca33ef7 100644
--- a/docs/guides/cut/ai-assistant.md
+++ b/docs/guides/cut/ai-assistant.md
@@ -53,7 +53,7 @@ Which path runs is chosen by the model id alone. The picker lives in the page so
## What the model knows
-Every knowledge surface is defined once — the catalog file ships in the engine and is bundled into the page, so all providers read identical text.
+Every knowledge surface is defined once — the catalog file ships in the engine and is bundled into the page, so all providers read identical text. The tools and the inspector write the same document, and every setting a tool can put on a selected item has a control in that item's panel; a test holds the pairing, so a change made in chat is always visible, and undoable, by hand.
| Surface | Size today | When it enters context |
| --- | --- | --- |
@@ -148,6 +148,6 @@ The shared catalog (system prompt, tools, skills), the chat route with its provi
The brief-to-video pipeline is its own subsystem: the orchestrator, coverage invariant, and role interfaces in `lib/genvideo/`, its hosted-model adapters in `lib/genvideo/adapters/`, the browser controller in `lib/genScene.ts`, and the progress card in `components/SceneCard.tsx`. Its strategy — story planning, the identity ladder, where audio goes next — is the [Brief to Video](brief-to-video.md) guide.
-Project commands share the editor's tool schemas and executor through `PROJECT_TOOLS` and `runProjectCommand`. The command boundary checks the active project and excludes editor-only actions. Headless callers keep the existing serialized engine session or isolated cloud worker, since the editing store belongs to that session. Deterministic editing commands call the executor directly; hosted generation keeps its credit checks.
+Project commands share the editor's tool schemas and executor through `PROJECT_TOOLS` and `runProjectCommand`. The command boundary checks the active project and excludes editor-only actions. Headless callers keep the existing serialized engine session or isolated cloud worker, since the editing store belongs to that session. Deterministic editing commands call the executor directly; hosted generation keeps its credit checks. A host with its own model — the ChatGPT app — sends a batch of these commands as a worker job; the [ChatGPT App](../chatgpt-app.md) guide covers that path.
`render_preview` captures the current cut and returns a render job with its revision and playback URL. Cloud and Mac jobs include a status URL for the host to poll. A headless turn can enqueue the render and finish, freeing its worker slot for the render. A Mac session without the media runtime returns the existing detached-media error and can run the command from the editor tab.
diff --git a/site/src/cut/components/EffectsPanel.tsx b/site/src/cut/components/EffectsPanel.tsx
index 2180e2e7..2a6f8afd 100644
--- a/site/src/cut/components/EffectsPanel.tsx
+++ b/site/src/cut/components/EffectsPanel.tsx
@@ -750,8 +750,11 @@ export function SwatchScene({
variant = "day",
}: {
frame: string | null;
- variant?: "day" | "dusk";
+ /** `void` is nothing at all — the black a clip's open edge arrives from
+ * or leaves to. */
+ variant?: "day" | "dusk" | "void";
}) {
+ if (variant === "void") return <span className="absolute inset-0 bg-black" />;
if (frame) {
return (
// eslint-disable-next-line @next/next/no-img-element -- a transient data URL or filmstrip thumb; the image optimizer has no role
diff --git a/site/src/cut/components/Inspector.tsx b/site/src/cut/components/Inspector.tsx
index 342234c1..5866400f 100644
--- a/site/src/cut/components/Inspector.tsx
+++ b/site/src/cut/components/Inspector.tsx
@@ -2,10 +2,11 @@
import { useQueryClient } from "@tanstack/react-query";
import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
-import { AlignCenter, AlignHorizontalSpaceAround, AlignLeft, AlignRight, AlignVerticalSpaceAround, Bold, ChevronLeft, ChevronRight, Diamond, FlipHorizontal2, FlipVertical2, Frame, House, Italic, Link2, Link2Off, Loader2, type LucideIcon, Palette, PanelRightClose, PanelRightOpen, PenTool, Scissors, Smile, Sparkles, Trash2, Type, User, Volume2 } from "lucide-react";
+import { AlignCenter, AlignHorizontalSpaceAround, AlignLeft, AlignRight, AlignVerticalSpaceAround, Bold, ChevronLeft, ChevronRight, Diamond, FlipHorizontal2, FlipVertical2, Frame, House, Italic, Link2, Link2Off, Loader2, type LucideIcon, Palette, PanelRightClose, PanelRightOpen, PenTool, Scissors, Smile, Sparkles, StretchHorizontal, StretchVertical, Trash2, Type, User, Volume2 } from "lucide-react";
import { Button } from "@/components/ui/button";
import { EmojiPicker } from "@/cut/components/EmojiPicker";
import { FontPicker } from "@/cut/components/FontPicker";
+import { ClipAnimationTiles, previewBar } from "@/cut/components/TransitionsPanel";
import {
Select,
SelectContent,
@@ -77,7 +78,7 @@ import {
penClosed,
restingMaskFrame,
} from "@donkeycut/effects-kit";
-import { clipWindow, maxClipFade, useEditor, type EditorState } from "@/cut/lib/store";
+import { clipLen, clipWindow, maxClipFade, useEditor, type EditorState } from "@/cut/lib/store";
import { PANEL_GLOBAL, usePanelState, useRememberedScroll } from "@/cut/lib/panelState";
import { usePreviewTime } from "@/cut/lib/playhead";
import { CLIP_MAX_ZOOM, clipCovers, clipKeyed, clipPoseAt, clipZoom, contentRect } from "@/cut/lib/types";
@@ -141,6 +142,9 @@ import {
type StickerOverlay,
type TextOverlay,
type VideoClip,
+ ANIM_DEFAULT_SECONDS,
+ TRANSITION_MAX,
+ type AnimStyle,
} from "@/cut/lib/types";
import { beatsBusyFor, detectAssetBeats, subscribeBeatsBusy } from "@/cut/lib/media";
import { reportSwallowed } from "@/cut/lib/report";
@@ -200,6 +204,7 @@ const CLIP_TABS: readonly RailTab[] = [
{ id: "color", label: "Color", Icon: Palette },
{ id: "cutout", label: "Cutout", Icon: Scissors },
{ id: "frame", label: "Frame", Icon: Frame },
+ { id: "animate", label: "Animation", Icon: Sparkles },
{ id: "audio", label: "Audio", Icon: Volume2 },
];
@@ -552,6 +557,7 @@ function ClipColumn({ clip, tab }: { clip: VideoClip; tab: string }) {
const scroll = useRememberedScroll(clip.id, tab);
if (tab === "color") return <ColorPanel clip={clip} />;
if (tab === "cutout") return <RemovalPanel clip={clip} />;
+ if (tab === "animate") return <ClipAnimationPanel clip={clip} />;
return (
<ScrollArea key={tab} className="min-h-0 flex-1" {...scroll}>
{tab === "frame" ? (
@@ -1794,6 +1800,8 @@ function AudioPanel({ clip }: { clip: AudioClip }) {
* chevron; any value in range can still be typed or dragged. */
const LINE_HEIGHTS = [0.9, 1, 1.15, 1.25, 1.5, 1.75, 2];
const LETTER_SPACINGS = [-2, 0, 2, 5, 10, 20];
+/** Glyph stretch stops, percent of the face's own width or height. */
+const STRETCHES = [50, 75, 100, 125, 150, 200];
function TextPanel({ overlay: o }: { overlay: TextOverlay }) {
const update = useEditor((s) => s.updateOverlay);
@@ -1802,6 +1810,7 @@ function TextPanel({ overlay: o }: { overlay: TextOverlay }) {
const opacityCk = useSliderCheckpoint();
const spacingCk = useSliderCheckpoint();
const lineHeightCk = useSliderCheckpoint();
+ const stretchCk = useSliderCheckpoint();
const strokeCk = useSliderCheckpoint();
const shadowCk = useSliderCheckpoint();
const taRef = useRef<HTMLTextAreaElement>(null);
@@ -1993,6 +2002,39 @@ function TextPanel({ overlay: o }: { overlay: TextOverlay }) {
/>
</Field>
</div>
+ {/* Glyph stretch: the face drawn wider or taller than designed, the
+ same fields the stage's corner grip and the assistant write. */}
+ <div className="mt-1 grid grid-cols-2 gap-2">
+ {(["stretchX", "stretchY"] as const).map((axis) => (
+ <Field key={axis} label={axis === "stretchX" ? "Width" : "Height"}>
+ <NumberField
+ label={axis === "stretchX" ? "Width stretch" : "Height stretch"}
+ icon={axis === "stretchX" ? <StretchHorizontal /> : <StretchVertical />}
+ value={(o[axis] ?? 1) * 100}
+ min={25}
+ max={400}
+ step={5}
+ snap={[100]}
+ presets={STRETCHES}
+ format={(v) => `${Math.round(v)}%`}
+ parse={(raw) => parseNumberInput(raw.replace(/%$/, ""))}
+ onDraft={(v) => {
+ stretchCk.begin();
+ useEditor.getState().updateOverlayTransient(o.id, {
+ [axis]: Math.abs(v - 100) < 0.5 ? undefined : v / 100,
+ });
+ }}
+ onCommit={(v) => {
+ stretchCk.begin();
+ useEditor.getState().updateOverlayTransient(o.id, {
+ [axis]: Math.abs(v - 100) < 0.5 ? undefined : v / 100,
+ });
+ stretchCk.end();
+ }}
+ />
+ </Field>
+ ))}
+ </div>
<Row label="Color">
<ColorField
value={o.color}
@@ -2453,6 +2495,117 @@ function WordSettings({ overlay: o }: { overlay: Overlay }) {
/** The slots the picker fills, in tab order. */
type AnimSlot = "in" | "out" | "loop" | "move" | "words";
+/** The pill of slot tabs over an animation grid. A slot that is already set
+ * reads darker, so switching tabs is not the only way to see what an item is
+ * doing. */
+function SlotTabs<T extends string>({
+ tabs,
+ slot,
+ isSet,
+ onPick,
+}: {
+ tabs: readonly T[];
+ slot: T;
+ isSet: (id: T) => boolean;
+ onPick: (id: T) => void;
+}) {
+ return (
+ <div className="mx-3.5 flex shrink-0 rounded-lg bg-muted p-0.5 text-[11.5px] font-medium">
+ {tabs.map((id) => (
+ <button
+ key={id}
+ type="button"
+ className={cn(
+ "flex-1 rounded-md px-1.5 py-1 capitalize transition-colors",
+ slot === id ? "bg-neutral-900 text-white" : "text-muted-foreground hover:text-foreground",
+ isSet(id) && slot !== id && "text-foreground"
+ )}
+ onClick={() => onPick(id)}
+ >
+ {id}
+ </button>
+ ))}
+ </div>
+ );
+}
+
+const CLIP_ANIM_SLOTS = ["in", "out"] as const;
+
+/** The Animation view a video clip's rail opens: In and Out over the tile
+ * grid, the ramp's length on the floor. A pick lands as the bar on that edge —
+ * the timeline draws it, the Transitions tab marks it, and the assistant's
+ * set_animation writes the same one — and plays itself on the footage. */
+function ClipAnimationPanel({ clip }: { clip: VideoClip }) {
+ const [picked, setSlot] = usePanelState<"in" | "out">(clip.id, "animSlot", "in");
+ const slot = picked === "out" ? "out" : "in";
+ const tilesScroll = useRememberedScroll(clip.id, `anim:${slot}`);
+ const anim = slot === "in" ? clip.animIn : clip.animOut;
+ // The ramp's length lands once, on release: every write to the edge is a
+ // bar edit with its own undo step.
+ const [secondsDraft, setSecondsDraft] = useState<number | null>(null);
+ const len = clipLen(clip);
+ const rehearse = (seconds: number) =>
+ previewBar({ start: slot === "in" ? clip.start : clip.start + len - seconds, seconds });
+ const pick = (style: AnimStyle | null) => {
+ if (!style) {
+ if (anim) useEditor.getState().setClipAnim(clip.id, slot, null);
+ return;
+ }
+ const seconds = anim?.seconds ?? ANIM_DEFAULT_SECONDS;
+ useEditor.getState().setClipAnim(clip.id, slot, { style, seconds });
+ rehearse(seconds);
+ };
+ return (
+ <div className="flex min-h-0 flex-1 flex-col">
+ <div className="shrink-0 bg-card pb-2">
+ <div className="flex h-10 shrink-0 items-center px-3.5 text-sm font-semibold tracking-tight">
+ Animation
+ </div>
+ <SlotTabs
+ tabs={CLIP_ANIM_SLOTS}
+ slot={slot}
+ isSet={(id) => !!(id === "in" ? clip.animIn : clip.animOut)}
+ onPick={setSlot}
+ />
+ </div>
+ {/* pt-1 clears the selected tile's ring, which draws outside its box. */}
+ <ScrollArea
+ key={slot}
+ className="min-h-0 flex-1"
+ {...tilesScroll}
+ viewportClassName="overscroll-contain"
+ contentClassName="flex flex-col gap-1 px-3.5 pt-1 pb-2"
+ >
+ <ClipAnimationTiles clip={clip} which={slot} value={anim?.style} onPick={pick} />
+ </ScrollArea>
+ <div className="shrink-0 border-t border-border bg-card px-3.5 py-0.5">
+ <Row label="Duration">
+ <ValueSlider
+ label="Duration"
+ sliderClassName="data-horizontal:w-24"
+ valueClassName="w-9 text-muted-foreground"
+ value={secondsDraft ?? anim?.seconds ?? ANIM_DEFAULT_SECONDS}
+ min={0.1}
+ max={Math.min(TRANSITION_MAX, len)}
+ step={0.05}
+ snap={[ANIM_DEFAULT_SECONDS]}
+ format={(v) => `${v.toFixed(2)}s`}
+ parse={parseSecondsInput}
+ disabled={!anim}
+ onDraft={setSecondsDraft}
+ onCommit={(v) => {
+ setSecondsDraft(null);
+ if (!anim) return;
+ useEditor.getState().setClipAnim(clip.id, slot, { ...anim, seconds: v });
+ rehearse(v);
+ }}
+ />
+ </Row>
+ </div>
+ </div>
+ );
+}
+
/** The animation subview an overlay panel pushes into: a tab per slot over
* the tile grid, the active slot's own control under it. The slots pick from
* the same grid, one at a time — the tiles are big enough to read the motion,
@@ -2543,26 +2696,12 @@ function AnimationPanel({ overlay: o }: { overlay: Overlay }) {
<div className="flex h-10 shrink-0 items-center px-3.5 text-sm font-semibold tracking-tight">
Animation
</div>
- <div className="mx-3.5 flex shrink-0 rounded-lg bg-muted p-0.5 text-[11.5px] font-medium">
- {tabs.map((id) => (
- <button
- key={id}
- type="button"
- className={cn(
- "flex-1 rounded-md px-1.5 py-1 capitalize transition-colors",
- slot === id
- ? "bg-neutral-900 text-white"
- : "text-muted-foreground hover:text-foreground",
- // A slot that is already set reads darker, so switching tabs is
- // not the only way to see what an element is doing.
- (id === "move" ? !!activeMove : !!anim[id]) && slot !== id && "text-foreground"
- )}
- onClick={() => setSlot(id)}
- >
- {id}
- </button>
- ))}
- </div>
+ <SlotTabs
+ tabs={tabs}
+ slot={slot}
+ isSet={(id) => (id === "move" ? !!activeMove : !!anim[id])}
+ onPick={setSlot}
+ />
</div>
{/* pt-1 clears the selected tile's ring, which draws outside its box.
The bounce stops here rather than travelling to the panel behind. */}
diff --git a/site/src/cut/components/TransitionsPanel.tsx b/site/src/cut/components/TransitionsPanel.tsx
index 59ef2102..6ba41620 100644
--- a/site/src/cut/components/TransitionsPanel.tsx
+++ b/site/src/cut/components/TransitionsPanel.tsx
@@ -4,17 +4,24 @@ import { useEffect, useMemo, useRef, useState } from "react";
import { PHASE_STEP } from "@/cut/components/AnimationTiles";
import { SwatchScene, useSwatchClock } from "@/cut/components/EffectsPanel";
import { SectionTitle } from "@/cut/components/SectionTitle";
+import { Tile } from "@/cut/components/PanelTile";
import { clearElementDrag, setElementDragData, setObjectDragImage } from "@/cut/lib/assetDrag";
import { peekEdgeFrame, requestEdgeFrame } from "@/cut/lib/media";
import { PICKED_RING, pickGridNav, useAssetPick } from "@/cut/lib/assetPick";
import { getClipSpans, resolveTransitions, useEditor } from "@/cut/lib/store";
import { usePreviewTimeEvery } from "@/cut/lib/playhead";
import {
+ ANIM_STYLE_IDS,
+ ANIM_STYLE_LABELS,
TRANSITION_STYLE_GROUPS,
TRANSITION_STYLE_LABELS,
+ overlayAnimStyle,
+ transitionStyleOfAnim,
+ type AnimStyle,
type MediaAsset,
type TimelineTransition,
type TransitionStyle,
+ type VideoClip,
} from "@/cut/lib/types";
import { cn } from "@/lib/utils";
import { ScrollArea } from "@/components/ui/scroll-area";
@@ -175,21 +182,7 @@ function TransitionTile({
}) {
const { picked, pick } = useAssetPick(`transition:${style}`);
const ref = useRef<HTMLButtonElement>(null);
- // Hovering a tile starts its handover over from the top, so the pointer
- // never lands mid-blend waiting for the loop to come around.
- const [runEpoch, setRunEpoch] = useState(0);
- // A golden-ratio phase by place in the list staggers the grid's loops. The
- // hover restart plays from the top, so it zeroes this tile's phase too.
- const [phase, setPhase] = useState(() => (((TILE_INDEX.get(style) ?? 0) * PHASE_STEP) % 1) * X_LOOP);
- const restart = () => {
- setPhase(0);
- setRunEpoch((n) => n + 1);
- };
- const playing = useEditor((s) => s.playing);
- const clock = useSwatchClock(true, X_LOOP, runEpoch);
- // At rest during playback the clock holds its still frame; the phase only
- // shifts a running loop.
- const t = playing ? clock : (clock + phase) % X_LOOP;
+ const { t, restart } = useHandoverClock(TILE_INDEX.get(style) ?? 0);
// What the selection means for this tile: it wears the ring when it is the
// live bar's style, and a click swaps that bar onto it.
const isLive = !!live && live.style === style;
@@ -235,6 +228,109 @@ function TransitionTile({
);
}
+/** A tile's place on the handover loop. A golden-ratio phase by place in the
+ * list staggers the grid's loops; hovering a tile starts its handover over
+ * from the top, so the pointer never lands mid-blend waiting for the loop to
+ * come around. At rest during playback the clock holds its still frame; the
+ * phase only shifts a running loop. */
+function useHandoverClock(index: number): { t: number; restart: () => void } {
+ const [runEpoch, setRunEpoch] = useState(0);
+ const [phase, setPhase] = useState(() => ((index * PHASE_STEP) % 1) * X_LOOP);
+ const restart = () => {
+ setPhase(0);
+ setRunEpoch((n) => n + 1);
+ };
+ const playing = useEditor((s) => s.playing);
+ const clock = useSwatchClock(true, X_LOOP, runEpoch);
+ return { t: playing ? clock : (clock + phase) % X_LOOP, restart };
+}
+
+/**
+ * The tiles a video clip's own entrance or exit picks from — the Animation
+ * view of the clip's inspector. Each style plays on the clip's edge frame
+ * against black, the way an open edge really renders; the pick lands as the
+ * bar on that edge, the same bar a tile dragged from this tab or the
+ * assistant's set_animation writes. Upper-track clips composite through
+ * alpha, so they offer the two ramps alpha can express.
+ */
+export function ClipAnimationTiles({
+ clip,
+ which,
+ value,
+ onPick,
+}: {
+ clip: VideoClip;
+ which: "in" | "out";
+ /** The style on that edge, or undefined for none. */
+ value?: AnimStyle;
+ onPick: (style: AnimStyle | null) => void;
+}) {
+ const asset = useEditor((s) => s.assets.find((a) => a.id === clip.assetId));
+ const frame = useCutFrame(
+ `anim-${which}`,
+ asset ? { asset, srcT: which === "in" ? clip.in : clip.out } : null
+ );
+ const ids = clip.track > 0 ? ANIM_STYLE_IDS.filter((s) => overlayAnimStyle(s) === s) : ANIM_STYLE_IDS;
+ return (
+ <div className="grid grid-cols-2 gap-2" onKeyDown={pickGridNav}>
+ <Tile selected={!value} pickId="anim:none" onClick={() => onPick(null)} label="None" className="p-1">
+ <span className="relative block aspect-square w-full overflow-hidden rounded-md bg-black">
+ <Layer frame={frame} variant="day" />
+ </span>
+ </Tile>
+ {ids.map((id, i) => (
+ <ClipAnimTile
+ key={id}
+ style={id}
+ which={which}
+ frame={frame}
+ index={i}
+ selected={value === id}
+ onPick={() => onPick(id)}
+ />
+ ))}
+ </div>
+ );
+}
+
+function ClipAnimTile({
+ style,
+ which,
+ frame,
+ index,
+ selected,
+ onPick,
+}: {
+ style: AnimStyle;
+ which: "in" | "out";
+ frame: string | null;
+ index: number;
+ selected: boolean;
+ onPick: () => void;
+}) {
+ const { t, restart } = useHandoverClock(index);
+ return (
+ <Tile
+ selected={selected}
+ pickId={`anim:${style}`}
+ onClick={onPick}
+ onHover={(inside) => inside && restart()}
+ label={ANIM_STYLE_LABELS[style]}
+ className="p-1"
+ >
+ <TransitionSwatch
+ style={transitionStyleOfAnim(style)}
+ a={which === "in" ? null : frame}
+ b={which === "in" ? frame : null}
+ aVariant={which === "in" ? "void" : "day"}
+ bVariant={which === "in" ? "day" : "void"}
+ t={t}
+ className="w-full"
+ />
+ </Tile>
+ );
+}
+
/** One full-tile layer of the handover — a shot, transformed or clipped as
* the style's moment demands. */
function Layer({
@@ -243,7 +339,7 @@ function Layer({
style,
}: {
frame: string | null;
- variant: "day" | "dusk";
+ variant: "day" | "dusk" | "void";
style?: React.CSSProperties;
}) {
return (
@@ -260,20 +356,25 @@ function TransitionSwatch({
style,
a,
b,
+ aVariant = "day",
+ bVariant = "dusk",
t,
className,
}: {
style: TransitionStyle;
a: string | null;
b: string | null;
+ /** The stand-in each side shows without a frame; `void` is black. */
+ aVariant?: "day" | "dusk" | "void";
+ bVariant?: "day" | "dusk" | "void";
t: number;
className?: string;
}) {
const p0 = Math.min(1, Math.max(0, (t - X_HOLD) / X_RUN));
const p = p0 * p0 * (3 - 2 * p0);
const pc = (n: number) => `${(n * 100).toFixed(1)}%`;
- const A = (s?: React.CSSProperties) => <Layer frame={a} variant="day" style={s} />;
- const B = (s?: React.CSSProperties) => <Layer frame={b} variant="dusk" style={s} />;
+ const A = (s?: React.CSSProperties) => <Layer frame={a} variant={aVariant} style={s} />;
+ const B = (s?: React.CSSProperties) => <Layer frame={b} variant={bVariant} style={s} />;
let layers: React.ReactNode;
switch (style) {
case "crossfade":
@@ -428,7 +529,7 @@ const PREVIEW_LEAD = 0.4;
const PREVIEW_TAIL = 0.35;
/** Play a bar's window on the real footage: a beat ahead of it, a beat past. */
-function previewBar(t: { start: number; seconds: number }) {
+export function previewBar(t: { start: number; seconds: number }) {
const s = useEditor.getState();
s.previewRange(Math.max(0, t.start - PREVIEW_LEAD), t.start + t.seconds + PREVIEW_TAIL);
}
diff --git a/site/src/cut/components/inspectorToolFields.test.ts b/site/src/cut/components/inspectorToolFields.test.ts
new file mode 100644
index 00000000..4660f8bf
--- /dev/null
+++ b/site/src/cut/components/inspectorToolFields.test.ts
@@ -0,0 +1,166 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { GRADE_BASIC_FIELDS } from "@donkeycut/effects-kit";
+import { OVERLAY_ANIMATION_TOOLS } from "./AnimationTiles.tools";
+import { EFFECTS_TOOLS } from "./EffectsPanel.tools";
+import { INSPECTOR_TOOLS } from "./Inspector.tools";
+import { TIMELINE_TOOLS } from "./Timeline.tools";
+import { TRANSITIONS_TOOLS } from "./TransitionsPanel.tools";
+
+/**
+ * Every setting the assistant can write on a selected item has a control in
+ * that item's inspector. The tools and the panels write the same document,
+ * so a field the panel does not render is a change the person cannot see or
+ * undo by hand. A new tool parameter fails here until its control exists —
+ * or until it is named below as a placement or identity field, which the
+ * timeline shows instead.
+ */
+
+/** The tools that change a selected item's own settings. */
+const ITEM_TOOLS = new Set([
+ "update_overlay",
+ "set_mask",
+ "set_clip_keyframes",
+ "update_audio",
+ "set_clip_volume",
+ "set_clip_sound",
+ "set_framing",
+ "set_clip_style",
+ "set_speed",
+ "set_speed_curve",
+ "set_color_grade",
+ "set_color_preset",
+ "set_color_curves",
+ "set_color_wheels",
+ "set_color_hsl",
+ "set_overlay_animation",
+ "set_overlay_keyframes",
+ "set_animation",
+ "add_effect",
+ "update_overlay_video",
+ "set_clip_muted",
+ "set_clip_hidden",
+ "rename_item",
+]);
+
+/** The panels that render an item's settings. */
+const PANEL_SOURCES = [
+ "Inspector.tsx",
+ "ColorPanel.tsx",
+ "ColorWheel.tsx",
+ "SpeedCurveStrip.tsx",
+ "RemovalPanel.tsx",
+ "AnimationTiles.tsx",
+ "TransitionsPanel.tsx",
+];
+
+/** Parameters that say which item, or where it sits on the timeline — the
+ * timeline is their control. */
+const PLACEMENT = new Set([
+ "id", "ids", "clipId", "transitionId", "which", "kind", "effect",
+ "start", "end", "in", "out", "at", "t", "track", "lane", "layout",
+ "region", "region.x", "region.y", "region.w", "region.h",
+ "clear", "reset", "reset_all", "auto",
+]);
+
+/** A parameter whose panel control reads the document under another name:
+ * the identifier the panel source uses for it. */
+const PANEL_NAME: Record<string, string> = {
+ stroke_color: "stroke",
+ stroke_width: "stroke",
+ border_width: "border",
+ border_color: "border",
+ shadow_blur: "blur",
+ shadow_x: "shadow",
+ shadow_y: "shadow",
+ shadow_color: "shadow",
+ shadow_opacity: "shadow",
+ move_strength: "strength",
+ in_style: "AnimationTiles",
+ out_style: "AnimationTiles",
+ loop_style: "AnimationTiles",
+ in_seconds: "seconds",
+ out_seconds: "seconds",
+ loop_speed: "speed",
+ words_style: "words",
+ words_color: "words",
+ words_scale: "words",
+ words_dim: "words",
+ style: "ClipAnimationTiles",
+ seconds: "seconds",
+ smooth: "smoothSlow",
+ mode: "clipCovers",
+ focus_x: "focus",
+ focus_y: "focus",
+ "points[].x": "points",
+ "points[].y": "points",
+ protect_skin: "protect-skin",
+ master: "CurveEditor",
+ red: "CurveEditor",
+ green: "CurveEditor",
+ blue: "CurveEditor",
+ curve_contrast: "CurveEditor",
+ "shadows.dx": "WheelsTool",
+ "shadows.dy": "WheelsTool",
+ "shadows.luma": "WheelsTool",
+ "midtones.dx": "WheelsTool",
+ "midtones.dy": "WheelsTool",
+ "midtones.luma": "WheelsTool",
+ "highlights.dx": "WheelsTool",
+ "highlights.dy": "WheelsTool",
+ "highlights.luma": "WheelsTool",
+ midtones: "WheelsTool",
+ band: "HslTool",
+ sat: "HslTool",
+};
+
+/** The basic grade sliders draw from the registry the tool's parameters are
+ * built from, so the panel renders the registry itself. */
+const GRADE_FIELD_IDS = new Set<string>(GRADE_BASIC_FIELDS.map((f) => f.key));
+
+const camel = (name: string) => name.replace(/_([a-z])/g, (_, c: string) => c.toUpperCase());
+
+/** Every parameter path in a schema: nested objects and array items walk too. */
+function paramPaths(schema: unknown, prefix = ""): string[] {
+ const props = (schema as { properties?: Record<string, unknown> } | undefined)?.properties ?? {};
+ const out: string[] = [];
+ for (const [key, def] of Object.entries(props)) {
+ const path = prefix + key;
+ out.push(path);
+ const d = def as { type?: string; items?: { type?: string } };
+ if (d.type === "object") out.push(...paramPaths(d, `${path}.`));
+ if (d.type === "array" && d.items?.type === "object") out.push(...paramPaths(d.items, `${path}[].`));
+ }
+ return out;
+}
+
+describe("inspector tool fields", () => {
+ test("every item setting the assistant writes has a panel control", () => {
+ const dir = fileURLToPath(new URL(".", import.meta.url));
+ const panels = PANEL_SOURCES.map((f) => readFileSync(`${dir}${f}`, "utf8")).join("\n");
+ const rendered = (token: string) => new RegExp(`\\b${token}\\b`).test(panels);
+ const tools = [
+ ...INSPECTOR_TOOLS,
+ ...OVERLAY_ANIMATION_TOOLS,
+ ...TRANSITIONS_TOOLS,
+ ...EFFECTS_TOOLS,
+ ...TIMELINE_TOOLS,
+ ].filter((t) => ITEM_TOOLS.has(t.name));
+ expect(tools.map((t) => t.name).sort()).toEqual([...ITEM_TOOLS].sort());
+ const missing: string[] = [];
+ for (const tool of tools) {
+ for (const path of paramPaths(tool.inputSchema)) {
+ const leaf = path.split(".").pop()!.replace(/\[\]$/, "");
+ if (PLACEMENT.has(path) || PLACEMENT.has(leaf)) continue;
+ const token =
+ PANEL_NAME[path] ??
+ (GRADE_FIELD_IDS.has(path) ? "GRADE_BASIC_FIELDS" : undefined) ??
+ PANEL_NAME[leaf] ??
+ camel(leaf);
+ if (!rendered(token)) missing.push(`${tool.name}.${path} (${token})`);
+ }
+ }
+ expect(missing).toEqual([]);
+ });
+});