feat(timeline): draw each zoom's move-in and move-out as trails (#1028)

A zoom pill shows the hold, while its moves run outside it. The zoom lane
now draws a trail on each side, sized on the speed-aware clock the
compositor uses (zoomTransitions), and live while a zoom, trim or speed
pill is dragged. The part a trim cuts (transitionCutsMs) is hatched, and
the trail's tooltip says how much and that the export jumps there.
Strings in all 15 locales, machine-translated outside en and fr.

Author: EtienneLescot

src/components/ai-edition/v4/EditorShellV4.module.css

@@ -1665,6 +1665,35 @@
 .laneCameraFullscreen {
 	--_c: #a855f7;
 }
+/* A zoom's camera moves (#1028): a trail on each side of the pill, fading away from it, BELOW
+   it (a chained neighbour's pill stays on top). Thinner than the pill so it reads as part of
+   it, not as another region. The part a trim cuts is hatched in the trim lane's red. */
+.zoomTrail {
+	position: absolute;
+	top: 5px;
+	height: 14px;
+	min-width: 1px;
+	overflow: hidden;
+	z-index: 1;
+}
+.zoomTrail[data-zoom-trail="in"] {
+	border-radius: 7px 0 0 7px;
+	background: linear-gradient(90deg, transparent, color-mix(in oklab, var(--_c) 55%, transparent));
+}
+.zoomTrail[data-zoom-trail="out"] {
+	border-radius: 0 7px 7px 0;
+	background: linear-gradient(90deg, color-mix(in oklab, var(--_c) 55%, transparent), transparent);
+}
+.zoomTrailCut {
+	position: absolute;
+	top: 0;
+	bottom: 0;
+	background: repeating-linear-gradient(
+		-45deg,
+		color-mix(in srgb, var(--danger) 70%, transparent) 0 3px,
+		transparent 3px 6px
+	);
+}
 /* Imported audio tracks (issue #350). A distinct pink so a BGM/voiceover track
    reads apart from the effect pills, and taller than a lane pill so the waveform
    inside it is legible. */

src/components/ai-edition/v4/V4Timeline.geometry.test.tsx

@@ -37,6 +37,7 @@ import type { I18nNamespace } from "@/i18n/config";
 import { getAvailableLocales, translate } from "@/i18n/loader";
 import type { useTimeline } from "@/lib/ai-edition/store/useTimeline";
 import { DEFAULT_SHORTCUTS, formatBinding } from "@/lib/shortcuts";
+import { zoomTransitionMs } from "@/lib/zoomMath/constants";
 import { V4Timeline } from "./V4Timeline";
 
 beforeAll(() => {
@@ -1083,3 +1084,54 @@ describe("V4Timeline toolbar tooltips", () => {
 		expect(wide).not.toHaveAttribute("title");
 	});
 });
+
+// A zoom pill shows the hold; its camera moves run outside it (#1028).
+describe("V4Timeline zoom trails", () => {
+	afterEach(() => {
+		i18n.translate = null;
+	});
+
+	const W_SEC = zoomTransitionMs(1.8) / 1000; // ≈ 0.92 s at the default depth
+	const ZOOM = { id: "z1", startMs: 10_000, endMs: 12_000, depth: 3 };
+	const pct = (sec: number) => (sec / TOTAL_SEC) * 100;
+	const trail = (side: "in" | "out") =>
+		document.querySelector<HTMLElement>(`[data-zoom-trail="${side}"]`) as HTMLElement;
+
+	function renderZoom(overrides: Record<string, unknown>) {
+		i18n.translate = (namespace, key, vars) =>
+			translate("en", namespace as I18nNamespace, key, vars);
+		renderTimeline(undefined, undefined, [NO_CAMERA_ASSET], undefined, {
+			zoomRegions: [ZOOM],
+			...overrides,
+		});
+	}
+
+	it("hatches the zoom-out a trim at the pill's end removes (issue #1028 repro)", () => {
+		renderZoom({
+			trimRanges: [
+				{ id: "t1", assetId: "a1", clipId: "c@0", startSec: 12, endSec: 14, origin: "user" },
+			],
+		});
+		expect(trail("in")).toHaveAccessibleName("Zoom-in: the view moves in until the zoom starts");
+		expect(trail("in").querySelector("[data-zoom-trail-cut]")).toBeNull();
+		expect(Number.parseFloat(trail("in").style.left)).toBeCloseTo(pct(10 - W_SEC), 6);
+
+		expect(trail("out")).toHaveAccessibleName(
+			`A trim removes ${W_SEC.toFixed(2)} s of the zoom-out. The export jumps at the cut.`,
+		);
+		expect(Number.parseFloat(trail("out").style.left)).toBeCloseTo(pct(12), 6);
+		const cut = trail("out").querySelector<HTMLElement>("[data-zoom-trail-cut]");
+		expect(Number.parseFloat(cut?.style.left ?? "")).toBeCloseTo(0, 6);
+		expect(Number.parseFloat(cut?.style.width ?? "")).toBeCloseTo(100, 6);
+	});
+
+	it("stretches the zoom-out across a speed region, uncut", () => {
+		renderZoom({ speedRegions: [{ id: "s1", startMs: 12_000, endMs: 20_000, speed: 3 }] });
+		expect(Number.parseFloat(trail("out").style.width)).toBeCloseTo(pct(3 * W_SEC), 6);
+		expect(Number.parseFloat(trail("in").style.width)).toBeCloseTo(pct(W_SEC), 6);
+		expect(trail("out")).toHaveAccessibleName(
+			"Zoom-out: the view moves back out after the zoom ends",
+		);
+		expect(trail("out").querySelector("[data-zoom-trail-cut]")).toBeNull();
+	});
+});

src/components/ai-edition/v4/V4Timeline.tsx

@@ -67,6 +67,8 @@ import {
 	resolveTimelineSpanToTrim,
 	ventilateTimelineSpanToTrims,
 } from "@/lib/ai-edition/timeline/trim-mapping";
+import { effectiveZoomScale } from "@/lib/ai-edition/timeline/zoom-scale";
+import { transitionCutsMs, zoomTransitions } from "@/lib/ai-edition/timeline/zoom-transitions";
 import { formatBinding } from "@/lib/shortcuts";
 import { nativeBridgeClient } from "@/native/client";
 import { TransportBar } from "../TransportBar";
@@ -742,7 +744,8 @@ export function V4Timeline({
 		label: t("toolbar.newAnnotation"),
 		sourceIds: p.ids,
 	}));
-	const speedPills: LanePill[] = coalesceRegionsForRuler(tl.speedRegions).map((p) => ({
+	const speedRuns = coalesceRegionsForRuler(tl.speedRegions);
+	const speedPills: LanePill[] = speedRuns.map((p) => ({
 		id: p.ids[0],
 		kind: "speed",
 		start: p.start,
@@ -760,7 +763,8 @@ export function V4Timeline({
 			sourceIds: p.ids,
 		}),
 	);
-	const zoomPills: LanePill[] = coalesceRegionsForRuler(tl.zoomRegions).map((p) => ({
+	const zoomRuns = coalesceRegionsForRuler(tl.zoomRegions);
+	const zoomPills: LanePill[] = zoomRuns.map((p) => ({
 		id: p.ids[0],
 		kind: "zoom",
 		start: p.start,
@@ -1748,13 +1752,14 @@ export function V4Timeline({
 		);
 	};
 
+	// A pill's span as drawn: the live drag geometry while it is being dragged.
+	const liveSpan = <T extends { start: number; end: number }>(id: string, p: T): T =>
+		activePillDrag && activePillDrag.id === id
+			? { ...p, start: activePillDrag.start, end: activePillDrag.end }
+			: p;
+
 	const renderPills = (pills: LanePill[], emptyLabel: string) => {
-		const effectivePills = pills.map((p) => {
-			if (activePillDrag && activePillDrag.id === p.id) {
-				return { ...p, start: activePillDrag.start, end: activePillDrag.end };
-			}
-			return p;
-		});
+		const effectivePills = pills.map((p) => liveSpan(p.id, p));
 		return (
 			<>
 				{effectivePills.length === 0 ? (
@@ -1831,6 +1836,85 @@ export function V4Timeline({
 		);
 	};
 
+	// Each zoom's camera moves (#1028): the pill shows the hold, the zoom-in runs in the trail
+	// before it and the zoom-out in the trail after it, on the speed-aware clock the compositor
+	// uses. The part a trim cuts is hatched: the export jumps there instead of easing. Display
+	// only, not a control. Hidden while a clip is dragged, when the pills split and slide.
+	const renderZoomTrails = () => {
+		if (clipDrag) return null;
+		const ms = (span: { start: number; end: number }) => ({
+			startMs: span.start * 1000,
+			endMs: span.end * 1000,
+		});
+		const speeds = speedRuns.map((r) => ({
+			id: r.ids[0],
+			speed: r.member.speed,
+			...ms(liveSpan(r.ids[0], r)),
+		}));
+		const trims = trimPills.map((p) => ms(liveSpan(p.id, p)));
+		const totalMs = total * 1000;
+		const sec = (cutMs: number) => (cutMs / 1000).toFixed(2);
+		return zoomRuns.flatMap((r) => {
+			const zoom = ms(liveSpan(r.ids[0], r));
+			const moves = zoomTransitions({ ...zoom, scale: effectiveZoomScale(r.member) }, speeds);
+			const cut = transitionCutsMs(zoom, moves, trims);
+			const outUntilMs = Math.min(moves.outUntilMs, totalMs);
+			const trails = [
+				{
+					side: "in",
+					fromMs: moves.inFromMs,
+					toMs: zoom.startMs,
+					cutFromMs: moves.inFromMs,
+					cutToMs: moves.inFromMs + cut.inMs,
+					text:
+						cut.inMs > 0 ? t("trails.zoomInCut", { seconds: sec(cut.inMs) }) : t("trails.zoomIn"),
+				},
+				{
+					side: "out",
+					fromMs: zoom.endMs,
+					toMs: outUntilMs,
+					cutFromMs: moves.outUntilMs - cut.outMs,
+					cutToMs: outUntilMs,
+					text:
+						cut.outMs > 0
+							? t("trails.zoomOutCut", { seconds: sec(cut.outMs) })
+							: t("trails.zoomOut"),
+				},
+			];
+			return trails
+				.filter((trail) => trail.toMs > trail.fromMs)
+				.map((trail) => {
+					const lengthMs = trail.toMs - trail.fromMs;
+					const cutMs = trail.cutToMs - trail.cutFromMs;
+					return (
+						<Tooltip key={`${r.ids[0]}:${trail.side}`} content={trail.text}>
+							<div
+								role="img"
+								aria-label={trail.text}
+								data-zoom-trail={trail.side}
+								className={`${styles.zoomTrail} ${styles.laneZoom}`}
+								style={{
+									left: `${pctAt(trail.fromMs / 1000)}%`,
+									width: `${pctOf(lengthMs / 1000)}%`,
+								}}
+							>
+								{cutMs > 0 ? (
+									<span
+										data-zoom-trail-cut=""
+										className={styles.zoomTrailCut}
+										style={{
+											left: `${((trail.cutFromMs - trail.fromMs) / lengthMs) * 100}%`,
+											width: `${(cutMs / lengthMs) * 100}%`,
+										}}
+									/>
+								) : null}
+							</div>
+						</Tooltip>
+					);
+				});
+		});
+	};
+
 	return (
 		<div className={styles.tl} ref={panelRef}>
 			<div className={styles.tlToolbar}>
@@ -2174,6 +2258,8 @@ export function V4Timeline({
 									)}
 								</div>
 								<div className={styles.tlLane}>
+									{/* Its own provider, like the toolbar's: see the note there. */}
+									<TooltipProvider>{renderZoomTrails()}</TooltipProvider>
 									{renderPills(
 										zoomPills,
 										t("hints.pressZoom", { key: formatBinding(shortcuts.addZoom, isMac) }),

src/i18n/__tests__/tooltipCopy.test.ts

@@ -42,6 +42,7 @@ const TOOLTIP_KEYS: Record<string, string[]> = {
 		"deviceSettings.title",
 		"deviceSettings.close",
 	],
+	timeline: ["trails.zoomIn", "trails.zoomOut", "trails.zoomInCut", "trails.zoomOutCut"],
 };
 
 function read(locale: string, namespace: string, key: string): string {

src/i18n/locales/ar/timeline.json

@@ -33,6 +33,12 @@
 		"cameraFullscreen": "كاميرا كاملة الشاشة",
 		"cameraFullscreenItem": "كاميرا كاملة الشاشة {{index}}"
 	},
+	"trails": {
+		"zoomIn": "التكبير التدريجي: تقترب الصورة حتى بداية التكبير",
+		"zoomOut": "التصغير التدريجي: تبتعد الصورة مجددًا بعد نهاية التكبير",
+		"zoomInCut": "يزيل قص {{seconds}} ث من التكبير التدريجي. يقفز التصدير عند القص.",
+		"zoomOutCut": "يزيل قص {{seconds}} ث من التصغير التدريجي. يقفز التصدير عند القص."
+	},
 	"emptyState": {
 		"noVideo": "لم يتم تحميل أي فيديو",
 		"dragAndDrop": "اسحب وأفلت مقطع فيديو لبدء التعديل"

src/i18n/locales/cs/timeline.json

@@ -33,6 +33,12 @@
 		"cameraFullscreen": "Celá kamera",
 		"cameraFullscreenItem": "Celá kamera {{index}}"
 	},
+	"trails": {
+		"zoomIn": "Najetí: pohled se přibližuje až do začátku přiblížení",
+		"zoomOut": "Oddálení: pohled se po konci přiblížení znovu oddaluje",
+		"zoomInCut": "Oříznutí odstraní {{seconds}} s najetí. Export v místě střihu skočí.",
+		"zoomOutCut": "Oříznutí odstraní {{seconds}} s oddálení. Export v místě střihu skočí."
+	},
 	"emptyState": {
 		"noVideo": "Žádné video nenačteno",
 		"dragAndDrop": "Přetáhněte video pro zahájení úprav"

src/i18n/locales/de/timeline.json

@@ -33,6 +33,12 @@
 		"cameraFullscreen": "Vollbild-Kamera",
 		"cameraFullscreenItem": "Vollbild-Kamera {{index}}"
 	},
+	"trails": {
+		"zoomIn": "Hineinzoomen: Die Ansicht zoomt bis zum Beginn des Zooms hinein",
+		"zoomOut": "Herauszoomen: Die Ansicht zoomt nach dem Ende des Zooms wieder heraus",
+		"zoomInCut": "Ein Trim entfernt {{seconds}} s des Hineinzoomens. Der Export springt am Schnitt.",
+		"zoomOutCut": "Ein Trim entfernt {{seconds}} s des Herauszoomens. Der Export springt am Schnitt."
+	},
 	"emptyState": {
 		"noVideo": "Kein Video geladen",
 		"dragAndDrop": "Zieh ein Video hierher, um mit dem Bearbeiten zu beginnen"

src/i18n/locales/en/timeline.json

@@ -33,6 +33,12 @@
 		"cameraFullscreen": "Full Camera",
 		"cameraFullscreenItem": "Full Camera {{index}}"
 	},
+	"trails": {
+		"zoomIn": "Zoom-in: the view moves in until the zoom starts",
+		"zoomOut": "Zoom-out: the view moves back out after the zoom ends",
+		"zoomInCut": "A trim removes {{seconds}} s of the zoom-in. The export jumps at the cut.",
+		"zoomOutCut": "A trim removes {{seconds}} s of the zoom-out. The export jumps at the cut."
+	},
 	"emptyState": {
 		"noVideo": "No video loaded",
 		"dragAndDrop": "Drag and drop a video to start editing"

src/i18n/locales/es/timeline.json

@@ -33,6 +33,12 @@
 		"cameraFullscreen": "Cámara a pantalla completa",
 		"cameraFullscreenItem": "Cámara a pantalla completa {{index}}"
 	},
+	"trails": {
+		"zoomIn": "Acercamiento: la vista se acerca hasta que empieza el zoom",
+		"zoomOut": "Alejamiento: la vista se aleja de nuevo cuando termina el zoom",
+		"zoomInCut": "Un recorte quita {{seconds}} s del acercamiento. La exportación salta en el corte.",
+		"zoomOutCut": "Un recorte quita {{seconds}} s del alejamiento. La exportación salta en el corte."
+	},
 	"emptyState": {
 		"noVideo": "No hay video cargado",
 		"dragAndDrop": "Arrastra y suelta un video para comenzar a editar"

src/i18n/locales/fr/timeline.json

@@ -33,6 +33,12 @@
 		"cameraFullscreen": "Caméra plein écran",
 		"cameraFullscreenItem": "Caméra plein écran {{index}}"
 	},
+	"trails": {
+		"zoomIn": "Zoom avant : l'image se resserre jusqu'au début du zoom",
+		"zoomOut": "Zoom arrière : l'image s'élargit à nouveau après la fin du zoom",
+		"zoomInCut": "Une coupe retire {{seconds}} s du zoom avant. L'export saute à la coupe.",
+		"zoomOutCut": "Une coupe retire {{seconds}} s du zoom arrière. L'export saute à la coupe."
+	},
 	"emptyState": {
 		"noVideo": "Aucune vidéo chargée",
 		"dragAndDrop": "Glissez-déposez une vidéo pour commencer à éditer"