Skip to content

Commit 3954ca0

Browse files
committed
feat(ai-edition): tell the agent and MCP clients where zoom transitions are (#1028)
getCurrentDocument gives each zoom zoomInFromSec, zoomOutUntilSec, transitionSec and, when a trim cuts a move, cutByTrim. addZoom/setZoom/addTrim/setTrim (and their batches) report cutTransitions when the edit newly cuts one: a warning, never a refusal. The six tool descriptions explain the windows and the system prompt asks to leave them untrimmed. MCP clients get all of it through the shared executor and descriptions.
1 parent ebe6935 commit 3954ca0

5 files changed

Lines changed: 163 additions & 16 deletions

File tree

‎electron/ai-edition/agent-tools.test.ts‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2505,3 +2505,71 @@ describe("addTrim shapes the cut like the transcript pane", () => {
25052505
expect(lastTrim(result.document)?.endSec).toBe(15);
25062506
});
25072507
});
2508+
2509+
describe("zoom transitions are reported, not hidden (#1028)", () => {
2510+
// 1.8× (depth 3): each move lasts 0.6 + 0.55·ln 1.8 ≈ 0.923 s of screen time.
2511+
const MOVE_SEC = 0.923;
2512+
2513+
function run(document: AxcutDocument, name: string, args: unknown) {
2514+
const result = executeAgentTool(document, name, JSON.stringify(args));
2515+
expect(result.ok).toBe(true);
2516+
return { document: result.document ?? document, payload: JSON.parse(result.resultJson) };
2517+
}
2518+
2519+
function zoomedAt10to12() {
2520+
return run(shortSingleClip(), "addZoom", { startSec: 10, endSec: 12, depth: 3 });
2521+
}
2522+
2523+
function snapshotZoom(document: AxcutDocument) {
2524+
return run(document, "getCurrentDocument", {}).payload.zoomRanges[0];
2525+
}
2526+
2527+
it("gives each zoom its move windows on the timeline", () => {
2528+
const added = zoomedAt10to12();
2529+
expect(added.payload.cutTransitions).toBeUndefined();
2530+
const zoom = snapshotZoom(added.document);
2531+
expect(zoom.transitionSec).toBe(MOVE_SEC);
2532+
expect(zoom.zoomInFromSec).toBe(10 - MOVE_SEC);
2533+
expect(zoom.zoomOutUntilSec).toBe(12 + MOVE_SEC);
2534+
expect(zoom.cutByTrim).toBeUndefined();
2535+
});
2536+
2537+
it("warns when a trim at the zoom's end cuts its whole zoom-out (the issue's repro)", () => {
2538+
const trimmed = run(zoomedAt10to12().document, "addTrim", { startSec: 12, endSec: 14 });
2539+
const zoomId = snapshotZoom(trimmed.document).id;
2540+
expect(trimmed.payload.cutTransitions).toEqual([{ zoomId, side: "out", cutSec: MOVE_SEC }]);
2541+
expect(snapshotZoom(trimmed.document).cutByTrim).toBe("out");
2542+
});
2543+
2544+
it("stays quiet about a trim clear of both windows", () => {
2545+
const trimmed = run(zoomedAt10to12().document, "addTrim", { startSec: 14, endSec: 15 });
2546+
expect(trimmed.payload.cutTransitions).toBeUndefined();
2547+
});
2548+
2549+
it("warns the zoom write too, when it lands next to an existing cut", () => {
2550+
const trimmed = run(shortSingleClip(), "addTrim", { startSec: 8, endSec: 9.5 });
2551+
const added = run(trimmed.document, "addZoom", { startSec: 10, endSec: 12, depth: 3 });
2552+
expect(added.payload.cutTransitions).toEqual([
2553+
{ zoomId: added.payload.zoomId, side: "in", cutSec: 0.423 },
2554+
]);
2555+
expect(snapshotZoom(added.document).cutByTrim).toBe("in");
2556+
});
2557+
2558+
it("repeats the warning when setZoom moves a zoom that is still cut", () => {
2559+
const trimmed = run(zoomedAt10to12().document, "addTrim", { startSec: 12, endSec: 14 });
2560+
const zoomId = snapshotZoom(trimmed.document).id;
2561+
const moved = run(trimmed.document, "setZoom", { zoomId, startSec: 9 });
2562+
expect(moved.payload.cutTransitions).toEqual([
2563+
{ zoomId: moved.payload.zoomId, side: "out", cutSec: MOVE_SEC },
2564+
]);
2565+
});
2566+
2567+
it("stretches the zoom-out across a speed region, and catches a trim placed there", () => {
2568+
const sped = run(zoomedAt10to12().document, "addSpeed", { startSec: 12, endSec: 20, speed: 3 });
2569+
expect(snapshotZoom(sped.document).zoomOutUntilSec).toBe(14.77);
2570+
const trimmed = run(sped.document, "addTrims", { ranges: [{ startSec: 14, endSec: 15 }] });
2571+
expect(trimmed.payload.applied[0].cutTransitions).toEqual([
2572+
{ zoomId: snapshotZoom(trimmed.document).id, side: "out", cutSec: 0.77 },
2573+
]);
2574+
});
2575+
});

‎electron/ai-edition/agent-tools.ts‎

Lines changed: 73 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,10 @@ import {
4848
replacePillSpan,
4949
resolvePillIds,
5050
} from "../../src/lib/ai-edition/timeline/timelineMap";
51-
import { trimAppliesToClip } from "../../src/lib/ai-edition/timeline/trim-mapping";
51+
import {
52+
trimAppliesToClip,
53+
trimToTimelineSpan,
54+
} from "../../src/lib/ai-edition/timeline/trim-mapping";
5255
// ponytail: relative, and it has to stay that way — `electron/` never resolves
5356
// the `@/` alias (the main-process build does not declare it), which is why the
5457
// scale table was moved out of `components/video-editor/types.ts` to be
@@ -57,6 +60,10 @@ import {
5760
effectiveZoomScale,
5861
ZOOM_DEPTH_LEGEND,
5962
} from "../../src/lib/ai-edition/timeline/zoom-scale";
63+
import {
64+
transitionCutsMs,
65+
zoomTransitions,
66+
} from "../../src/lib/ai-edition/timeline/zoom-transitions";
6067
import { SETTING_BOUNDS } from "../../src/lib/projectDefaults";
6168

6269
export interface AgentToolExecution {
@@ -713,6 +720,46 @@ function roundSec(ms: number): number {
713720
return Math.round(ms) / 1000;
714721
}
715722

723+
// Each zoom pill's camera moves in virtual ms, and how much of each a trim cuts off (#1028).
724+
// The pill shows the hold only: the move in runs before it, the move out after it, and a
725+
// trim over either makes the export jump at the cut.
726+
function zoomTransitionsForAgent(document: AxcutDocument) {
727+
const legacy = document.legacyEditor as Record<string, unknown> | null;
728+
const speedRegions =
729+
(legacy?.speedRegions as
730+
| Array<{ id: string; startMs: number; endMs: number; speed: number }>
731+
| undefined) ?? [];
732+
const trims = document.timeline.trimRanges.flatMap((trim) => {
733+
const span = trimToTimelineSpan(trim, document.timeline.clips);
734+
return span ? [{ startMs: span.start * 1000, endMs: span.end * 1000 }] : [];
735+
});
736+
return coalesceForAgent(document.zoomRanges).map((zoom) => {
737+
const transitions = zoomTransitions({ ...zoom, scale: effectiveZoomScale(zoom) }, speedRegions);
738+
return { zoom, transitions, cut: transitionCutsMs(zoom, transitions, trims) };
739+
});
740+
}
741+
742+
/** The transitions this edit cut that were not cut, or not this way, before it: the warning a
743+
* zoom or trim write carries, like `cursorAnchor`: reported, never refused. */
744+
function cutTransitionsReport(before: AxcutDocument, after: AxcutDocument) {
745+
const cutsOf = (document: AxcutDocument) =>
746+
zoomTransitionsForAgent(document).flatMap(({ zoom, cut }) =>
747+
(["in", "out"] as const)
748+
.map((side) => ({
749+
zoomId: zoom.id,
750+
side,
751+
cutSec: roundSec(side === "in" ? cut.inMs : cut.outMs),
752+
key: `${zoom.id}:${side}:${zoom.startMs}:${zoom.endMs}`,
753+
}))
754+
.filter((c) => c.cutSec > 0),
755+
);
756+
const known = new Set(cutsOf(before).map((c) => `${c.key}:${c.cutSec}`));
757+
const cuts = cutsOf(after)
758+
.filter((c) => !known.has(`${c.key}:${c.cutSec}`))
759+
.map(({ key: _key, ...c }) => c);
760+
return cuts.length ? { cutTransitions: cuts } : {};
761+
}
762+
716763
// Compact projection of the document for the model: everything it needs to
717764
// reference ids and times, nothing it doesn't (no waveform paths, no history).
718765
//
@@ -764,7 +811,10 @@ export function documentSnapshotForModel(
764811
zoomNote:
765812
`renderedScale is what the viewer sees (depth is an ordinal, not a factor: ${ZOOM_DEPTH_LEGEND}). ` +
766813
"When a zoom carries customScale it wins over depth and depthIsOverridden is true — " +
767-
"a setZoom that only changes depth on such a zoom clears customScale so the depth takes effect.",
814+
"a setZoom that only changes depth on such a zoom clears customScale so the depth takes effect. " +
815+
"startSec–endSec is where the zoom HOLDS: it animates in over zoomInFromSec–startSec and out over " +
816+
"endSec–zoomOutUntilSec (transitionSec of screen time each, stretched on the timeline by a speed " +
817+
"region). cutByTrim names the move a trim cuts into (in, out or both): the export jumps at that cut.",
768818
project: { id: document.project.id, title: document.project.title },
769819
primaryAssetId: document.project.primaryAssetId ?? document.assets[0]?.id ?? null,
770820
autoFocusAll,
@@ -821,10 +871,16 @@ export function documentSnapshotForModel(
821871
endSec: s.endSec,
822872
reason: s.reason,
823873
})),
824-
zoomRanges: coalesceForAgent(document.zoomRanges).map((z) => ({
874+
zoomRanges: zoomTransitionsForAgent(document).map(({ zoom: z, transitions, cut }) => ({
825875
id: z.id,
826876
startSec: roundSec(z.startMs),
827877
endSec: roundSec(z.endMs),
878+
zoomInFromSec: roundSec(transitions.inFromMs),
879+
zoomOutUntilSec: roundSec(transitions.outUntilMs),
880+
transitionSec: roundSec(transitions.durationMs),
881+
...(cut.inMs > 0 || cut.outMs > 0
882+
? { cutByTrim: cut.inMs > 0 ? (cut.outMs > 0 ? "both" : "in") : "out" }
883+
: {}),
828884
depth: z.depth,
829885
renderedScale: effectiveZoomScale(z),
830886
// Emitted only when set: an unconditional `customScale: null` on every
@@ -1501,7 +1557,12 @@ export function executeAgentTool(
15011557
return {
15021558
ok: true,
15031559
document: next,
1504-
resultJson: JSON.stringify({ trimRangeId: trim.id, startSec, endSec }),
1560+
resultJson: JSON.stringify({
1561+
trimRangeId: trim.id,
1562+
startSec,
1563+
endSec,
1564+
...cutTransitionsReport(document, next),
1565+
}),
15051566
summary: `added trim ${formatSec(startSec)} – ${formatSec(endSec)}`,
15061567
};
15071568
}
@@ -1548,7 +1609,12 @@ export function executeAgentTool(
15481609
return {
15491610
ok: true,
15501611
document: next,
1551-
resultJson: JSON.stringify({ trimRangeId, startSec, endSec }),
1612+
resultJson: JSON.stringify({
1613+
trimRangeId,
1614+
startSec,
1615+
endSec,
1616+
...cutTransitionsReport(document, next),
1617+
}),
15521618
summary: `moved trim to ${formatSec(startSec)} – ${formatSec(endSec)}`,
15531619
};
15541620
}
@@ -1744,6 +1810,7 @@ export function executeAgentTool(
17441810
renderedScale: effectiveZoomScale(zoom),
17451811
...landingReport(landing, startMs / 1000, endMs / 1000),
17461812
...(anchor ? { cursorAnchor: anchor } : {}),
1813+
...cutTransitionsReport(document, next),
17471814
}),
17481815
summary:
17491816
`added zoom ${formatSec(landing.startSec)} – ${formatSec(landing.endSec)} ` +
@@ -1828,6 +1895,7 @@ export function executeAgentTool(
18281895
...(clearsCustomScale ? { clearedCustomScale: true } : {}),
18291896
...landingReport(landing, startMs / 1000, endMs / 1000),
18301897
...(anchor ? { cursorAnchor: anchor } : {}),
1898+
...cutTransitionsReport(document, next),
18311899
}),
18321900
summary:
18331901
`updated zoom ${formatSec(landing.startSec)} – ${formatSec(landing.endSec)}` +

‎electron/ai-edition/deep-agent/service.test.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -390,6 +390,14 @@ describe("what the descriptions say about zoom strength", () => {
390390
expect(TOOL_DESCRIPTIONS.addCameraFullscreen).toMatch(/hasCameraTrack/);
391391
expect(SYSTEM_PROMPT).toMatch(/hasCameraTrack/);
392392
});
393+
394+
it("tells every zoom and trim write where a zoom's moves are (#1028)", () => {
395+
for (const name of ["addZoom", "addZooms", "setZoom", "addTrim", "addTrims", "setTrim"]) {
396+
expect(TOOL_DESCRIPTIONS[name]).toContain("zoomOutUntilSec");
397+
expect(TOOL_DESCRIPTIONS[name]).toContain("cutTransitions");
398+
}
399+
expect(SYSTEM_PROMPT).toMatch(/zoomInFromSec.*untrimmed/);
400+
});
393401
});
394402

395403
// ── D-CONSENT ───────────────────────────────────────────────────────────────

0 commit comments

Comments
 (0)