Skip to content

Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.

feat: add stacked timeline tracks for annotations

Aiden Guan633c6a9e637f
diff --git a/electron/ai-edition/agent-tools.test.ts b/electron/ai-edition/agent-tools.test.ts
index 55a9c17bd..fffd23feb 100644
--- a/electron/ai-edition/agent-tools.test.ts
+++ b/electron/ai-edition/agent-tools.test.ts
@@ -772,6 +772,23 @@ describe("executeAgentTool", () => {
expect(() => documentSchema.parse(result.document)).not.toThrow();
});
+ it("MCP addAnnotation uses the highest saved layer after deletions", () => {
+ const initial = executeAgentTool(
+ fixtureDocument(),
+ "addAnnotation",
+ JSON.stringify({ startSec: 1, endSec: 2, text: "First" }),
+ );
+ const doc = initial.document as AxcutDocument;
+ doc.annotations[0].zIndex = 12;
+ const added = executeAgentTool(
+ doc,
+ "addAnnotation",
+ JSON.stringify({ startSec: 3, endSec: 4, text: "Next" }),
+ );
+ expect(added.ok).toBe(true);
+ expect(added.document?.annotations.map((a) => a.zIndex)).toEqual([12, 13]);
+ });
+
it("addAnnotation centres the text on a dark plate by default, and keeps it in frame", () => {
const centred = executeAgentTool(
fixtureDocument(),
@@ -919,7 +936,7 @@ describe("executeAgentTool", () => {
}
});
- it("refuses a set that would run into another region, instead of landing it elsewhere", () => {
+ it("allows overlapping annotations while refusing overlapping modifiers", () => {
let document = fixtureDocument();
const add = (name: string, args: Record<string, unknown>) => {
const result = executeAgentTool(document, name, JSON.stringify(args));
@@ -934,9 +951,11 @@ describe("executeAgentTool", () => {
"setAnnotation",
JSON.stringify({ annotationId: firstId, startSec: 7, endSec: 9 }),
);
- expect(blocked.ok).toBe(false);
- expect(blocked.document).toBeUndefined();
- expect(blocked.resultJson).toMatch(/NOT changed.*6\.0|NOT changed/);
+ expect(blocked.ok).toBe(true);
+ expect(blocked.document?.annotations.find((a) => a.id === firstId)).toMatchObject({
+ startMs: 7000,
+ endMs: 9000,
+ });
// The same rule for every kind of effect.
const zoom = add("addZoom", { startSec: 1, endSec: 2, depth: 2 });
diff --git a/electron/ai-edition/agent-tools.ts b/electron/ai-edition/agent-tools.ts
index c9b64ecb6..2a485ce38 100644
--- a/electron/ai-edition/agent-tools.ts
+++ b/electron/ai-edition/agent-tools.ts
@@ -385,8 +385,9 @@ function placeTextOnFrame<T extends AxcutAnnotationRegion>(
// first region under each — which every set*/remove* tool accepts as the id.
function coalesceForAgent<T extends { id: string; startMs: number; endMs: number }>(
regions: T[],
+ annotations = false,
): T[] {
- return coalesceRegionsForRuler(regions).map((pill) => ({
+ return coalesceRegionsForRuler(regions, 0.001, { annotations }).map((pill) => ({
...pill.member,
id: pill.ids[0],
startMs: Math.round(pill.start * 1000),
@@ -1464,7 +1465,7 @@ export function documentSnapshotForModel(
endSec: roundSec(s.endMs),
speed: s.speed,
})),
- annotations: coalesceForAgent(document.annotations).map((a) => ({
+ annotations: coalesceForAgent(document.annotations, true).map((a) => ({
id: a.id,
startSec: roundSec(a.startMs),
endSec: roundSec(a.endMs),
@@ -3171,7 +3172,7 @@ export function executeAgentTool(
},
parsed.data,
),
- zIndex: document.annotations.length + 1,
+ zIndex: Math.max(0, ...document.annotations.map((a) => a.zIndex)) + 1,
} as AxcutAnnotationRegion,
{ x: parsed.data.x, y: parsed.data.y },
document,
@@ -3230,14 +3231,12 @@ export function executeAgentTool(
if (!parsed.success) return failure(parsed.error.message);
const { annotationId } = parsed.data;
const existing = document.annotations.find((a) => a.id === annotationId);
- const annPill = new Set(resolvePillIds(document.annotations, annotationId));
+ const annPill = new Set(
+ resolvePillIds(document.annotations, annotationId, 0.001, { annotations: true }),
+ );
if (!existing) return failure(`Unknown annotation: ${annotationId}`);
const { startMs, endMs } = resolveSpanMs(existing, parsed.data.startSec, parsed.data.endSec);
- const blocked = refuseIfBlocked("annotation", document.annotations, annotationId, {
- startMs,
- endMs,
- });
- if (blocked) return blocked;
+
const { x, y, text, type, width, height } = parsed.data;
const mismatch = refuseShapeMismatch(type ?? existing.type, parsed.data);
if (mismatch) return mismatch;
@@ -3307,6 +3306,9 @@ export function executeAgentTool(
endMs,
document.timeline.clips,
() => createId("ann"),
+ 0.001,
+ {},
+ { annotations: true },
);
const landing = landingAfterPillEdit(
document.annotations,
diff --git a/src/components/ai-edition/NewEditorShell.timelineHeight.test.tsx b/src/components/ai-edition/NewEditorShell.timelineHeight.test.tsx
index 9ecf446fc..7a8d92580 100644
--- a/src/components/ai-edition/NewEditorShell.timelineHeight.test.tsx
+++ b/src/components/ai-edition/NewEditorShell.timelineHeight.test.tsx
@@ -29,7 +29,11 @@ vi.mock("@/contexts/I18nContext", () => ({
import { TooltipProvider } from "@/components/ui/tooltip";
import { EditorDialogsProvider } from "@/contexts/EditorDialogsContext";
import { AUDIO_ROW_EXPANSION_PX } from "@/lib/ai-edition/document/audioTracks";
-import { createAudioTrack, createEmptyDocument } from "@/lib/ai-edition/schema";
+import {
+ annotationRegionSchema,
+ createAudioTrack,
+ createEmptyDocument,
+} from "@/lib/ai-edition/schema";
import { useProjectStore } from "@/lib/ai-edition/store/projectStore";
import {
DEFAULT_TIMELINE_HEIGHT_PX,
@@ -235,4 +239,50 @@ describe("NewEditorShell timeline height", () => {
expect(root.style.gridTemplateRows).toBe(`58px 1fr ${DEFAULT_TIMELINE_HEIGHT_PX}px`);
});
+
+ it("expands for overlapping annotation rows, caps the panel height and restores the saved base height", () => {
+ useProjectStore.getState().clear();
+ const { container } = renderShell();
+ const root = container.firstElementChild as HTMLElement;
+ const doc = createEmptyDocument({ projectId: "p", title: "t" });
+ doc.annotations = Array.from({ length: 8 }, (_, i) =>
+ annotationRegionSchema.parse({
+ id: `ann-${i}`,
+ startMs: 0,
+ endMs: 5000,
+ type: "text",
+ content: "Hello",
+ zIndex: i,
+ position: { x: 20, y: 20 },
+ size: { width: 30, height: 20 },
+ style: { color: "#ffffff", fontSize: 32, fontFamily: "Inter" },
+ }),
+ );
+ act(() => {
+ useProjectStore.setState({ document: { ...doc, annotations: doc.annotations.slice(0, 2) } });
+ });
+ expect(root.style.gridTemplateRows).toBe(`58px 1fr ${DEFAULT_TIMELINE_HEIGHT_PX + 27}px`);
+ act(() => {
+ useProjectStore.setState({ document: doc });
+ });
+ expect(root.style.gridTemplateRows).toBe(`58px 1fr ${MAX_TIMELINE_HEIGHT_PX}px`);
+ act(() => {
+ useProjectStore.setState({
+ document: {
+ ...doc,
+ annotations: doc.annotations.map((ann, i) => ({
+ ...ann,
+ startMs: i * 1000,
+ endMs: (i + 1) * 1000,
+ })),
+ },
+ });
+ });
+ expect(root.style.gridTemplateRows).toBe(`58px 1fr ${DEFAULT_TIMELINE_HEIGHT_PX}px`);
+
+ act(() => {
+ useProjectStore.setState({ document: { ...doc, annotations: [] } });
+ });
+ expect(root.style.gridTemplateRows).toBe(`58px 1fr ${DEFAULT_TIMELINE_HEIGHT_PX}px`);
+ });
});
diff --git a/src/components/ai-edition/NewEditorShell.tsx b/src/components/ai-edition/NewEditorShell.tsx
index 13e5c1c47..5b2478bab 100644
--- a/src/components/ai-edition/NewEditorShell.tsx
+++ b/src/components/ai-edition/NewEditorShell.tsx
@@ -43,6 +43,7 @@ import { useTimeline } from "@/lib/ai-edition/store/useTimeline";
import { isGeneratedAssetId } from "@/lib/ai-edition/timeline/clip-parts";
import { mergeCloseCuts } from "@/lib/ai-edition/timeline/cut-breath";
import { newRegionDurationSec } from "@/lib/ai-edition/timeline/newRegionDuration";
+import { REGION_ROW_STEP_PX } from "@/lib/ai-edition/timeline/regionTracks";
import {
dropTrimPillsByIds,
trimAppliesToClip,
@@ -253,9 +254,12 @@ export function NewEditorShell() {
[document?.audioTracks],
);
const hasEffects = (document?.shaderEffectRanges?.length ?? 0) > 0;
+ const extraAudioHeightPx = Math.max(0, audioRowCount - 1) * AUDIO_ROW_EXPANSION_PX;
+ // The rendered annotation layout reports its live row count, including a drag preview.
+ const [annotationRowCount, setAnnotationRowCount] = useState(1);
+ const extraAnnotationHeightPx = (annotationRowCount - 1) * REGION_ROW_STEP_PX;
const extraLaneHeightPx =
- Math.max(0, audioRowCount - 1) * AUDIO_ROW_EXPANSION_PX +
- (hasEffects ? EFFECT_LANE_EXPANSION_PX : 0);
+ extraAudioHeightPx + extraAnnotationHeightPx + (hasEffects ? EFFECT_LANE_EXPANSION_PX : 0);
const timelineHeightPx = Math.min(
MAX_TIMELINE_HEIGHT_PX,
Math.max(MIN_TIMELINE_HEIGHT_PX, timelineBaseHeightPx + extraLaneHeightPx),
@@ -1231,6 +1235,7 @@ export function NewEditorShell() {
const region = wholePillOf(
source as Array<{ id: string; startMs: number; endMs: number }>,
sel.id,
+ { annotations: sel.kind === "annotation" },
);
if (!region) return;
copyRegion({ kind: sel.kind, region: region as unknown as Record<string, unknown> });
@@ -1715,6 +1720,7 @@ export function NewEditorShell() {
/>
) : null}
<V4Timeline
+ onAnnotationRowCountChange={setAnnotationRowCount}
tl={tl}
setCurrentTime={handleSeek}
variant={mode === "media" ? "media" : "edit"}
diff --git a/src/components/ai-edition/v4/V4Timeline.geometry.test.tsx b/src/components/ai-edition/v4/V4Timeline.geometry.test.tsx
index bebe463b1..65a857e51 100644
--- a/src/components/ai-edition/v4/V4Timeline.geometry.test.tsx
+++ b/src/components/ai-edition/v4/V4Timeline.geometry.test.tsx
@@ -146,6 +146,7 @@ function renderTimeline(
...overrides,
};
const setCurrentTime = vi.fn();
+ const onAnnotationRowCountChange = vi.fn();
const timeline = (
<ShortcutsProvider>
<V4Timeline
@@ -157,6 +158,7 @@ function renderTimeline(
onTogglePlay={vi.fn()}
onEditClip={vi.fn()}
onAddVoiceover={vi.fn()}
+ onAnnotationRowCountChange={onAnnotationRowCountChange}
/>
</ShortcutsProvider>
);
@@ -170,10 +172,11 @@ function renderTimeline(
),
);
return {
+ onAnnotationRowCountChange,
// A getter: a test that empties `annotationRegions` renders no such pill, and an eager
// lookup would throw before its own assertions ran.
get pill() {
- return screen.getByTitle("toolbar.newAnnotation");
+ return screen.getByTitle(/^toolbar\.newAnnotation/);
},
clipEls: Array.from(document.querySelectorAll<HTMLElement>("[data-clip-id]")),
tl,
@@ -205,6 +208,122 @@ function zoomIn(notches: number) {
wheelZoomOn(document.querySelector("[class*=tlTracks]") as HTMLElement, notches);
}
+describe("timeline tracks", () => {
+ afterEach(cleanup);
+
+ it("shows identical nested annotations on separate rows and selects each independently", () => {
+ const { tl } = renderTimeline(undefined, undefined, undefined, undefined, {
+ annotationRegions: [
+ { id: "main", startMs: 0, endMs: 67000, type: "text", content: "Same", zIndex: 1 },
+ { id: "second", startMs: 35000, endMs: 40000, type: "text", content: "Same", zIndex: 1 },
+ ],
+ });
+ const pills = [...document.querySelectorAll<HTMLElement>("[data-region-id]")];
+ expect(pills).toHaveLength(2);
+ expect(new Set(pills.map((p) => p.style.top)).size).toBe(2);
+ for (const pill of pills) {
+ fireEvent.keyDown(pill, { key: "Enter" });
+ expect(tl.selectRegion).toHaveBeenLastCalledWith("annotation", pill.dataset.regionId, {
+ additive: false,
+ });
+ }
+ });
+
+ it("reuses a single row for back-to-back annotations and keeps the empty lane free of drag hints", () => {
+ renderTimeline(undefined, undefined, undefined, undefined, {
+ annotationRegions: Array.from({ length: 10 }, (_, i) => ({
+ id: `ann-${i}`,
+ startMs: i * 1000,
+ endMs: (i + 1) * 1000,
+ zIndex: i + 1,
+ })),
+ });
+ const lane = document.querySelector<HTMLElement>(
+ '[data-track-kind="annotation"]',
+ ) as HTMLElement;
+ expect(lane.style.height).toBe("24px");
+ expect(lane.title).toBe("");
+ expect(
+ new Set([...lane.querySelectorAll<HTMLElement>("[data-region-id]")].map((p) => p.style.top))
+ .size,
+ ).toBe(1);
+ expect(lane.querySelector<HTMLElement>("[data-region-id]")?.title).toContain("tracks.dragHint");
+ cleanup();
+ renderTimeline(undefined, undefined, undefined, undefined, { annotationRegions: [] });
+ expect(document.querySelector<HTMLElement>('[data-track-kind="annotation"]')?.title).toBe("");
+ });
+
+ it("creates a separate live row when a horizontal drag moves into an existing annotation", () => {
+ const { tl, onAnnotationRowCountChange } = renderTimeline(
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ {
+ annotationRegions: [
+ { id: "main", startMs: 0, endMs: 100000, zIndex: 1 },
+ { id: "second", startMs: 200000, endMs: 300000, zIndex: 1 },
+ ],
+ },
+ );
+ expect(onAnnotationRowCountChange).toHaveBeenLastCalledWith(1);
+ const second = document.querySelector<HTMLElement>('[data-region-id="second"]') as HTMLElement;
+ const main = document.querySelector<HTMLElement>('[data-region-id="main"]') as HTMLElement;
+ fireEvent.pointerDown(second, { clientX: 100, clientY: 10 });
+ act(() => {
+ window.dispatchEvent(new MouseEvent("pointermove", { clientX: 10, clientY: 10 }));
+ });
+ expect(onAnnotationRowCountChange).toHaveBeenLastCalledWith(2);
+ expect(second.style.top).not.toBe(main.style.top);
+ expect(
+ document.querySelector<HTMLElement>('[data-track-kind="annotation"]')?.style.height,
+ ).toBe("51px");
+ act(() => {
+ window.dispatchEvent(new MouseEvent("pointerup"));
+ });
+ expect(tl.updateAnnotationSpan).toHaveBeenCalledWith("second", 20000, 120000);
+ });
+
+ it("moves annotations vertically between existing layers and creates layers above and below", () => {
+ const { tl } = renderTimeline(undefined, undefined, undefined, undefined, {
+ annotationRegions: [
+ { id: "low", startMs: 0, endMs: 100000, zIndex: 0 },
+ { id: "high", startMs: 0, endMs: 100000, zIndex: 4 },
+ ],
+ });
+ const low = document.querySelector<HTMLElement>('[data-region-id="low"]') as HTMLElement;
+ expect(low.dataset.trackRow).toBe("1");
+ for (const dy of [-27, -54, 27]) {
+ fireEvent.pointerDown(low, { clientX: 10, clientY: 100 });
+ act(() => {
+ window.dispatchEvent(new MouseEvent("pointermove", { clientX: 10, clientY: 100 + dy }));
+ });
+ act(() => {
+ window.dispatchEvent(new MouseEvent("pointerup"));
+ });
+ expect(tl.updateAnnotationSpan).toHaveBeenLastCalledWith("low", 0, 100000, {
+ row: 1 + dy / 27,
+ direction: dy < 0 ? "up" : "down",
+ });
+ }
+ });
+
+ it("keeps speed regions in a single lane", () => {
+ renderTimeline(undefined, undefined, undefined, undefined, {
+ annotationRegions: [],
+ speedRegions: [
+ { id: "a", startMs: 0, endMs: 67000, speed: 2 },
+ { id: "b", startMs: 35000, endMs: 40000, speed: 3 },
+ ],
+ });
+ const pills = [
+ ...document.querySelectorAll<HTMLElement>('[data-track-kind="speed"] [data-region-id]'),
+ ];
+ expect(pills).toHaveLength(2);
+ expect(pills[0].style.top).toBe(pills[1].style.top);
+ });
+});
+
describe("V4Timeline scrubbing", () => {
it("publishes at most one React scrub-state update per animation frame", () => {
const frames = new Map<number, FrameRequestCallback>();
@@ -1095,18 +1214,18 @@ describe("V4Timeline toolbar tooltips", () => {
for (const button of buttons) expect(button).not.toHaveAttribute("title");
});
- it("names a pill on hover only when it cannot draw its own label", () => {
+ it("shows the annotation drag hint on pills of any width", () => {
// A hairline pill draws nothing, so the title is the only place its name is.
renderTimeline();
- const hairline = screen.getByTitle("toolbar.newAnnotation");
+ const hairline = screen.getByTitle(/^toolbar\.newAnnotation/);
expect(hairline.textContent).toBe("");
- // One that fills the timeline draws its label, and a title would repeat it.
+ // A wide annotation still teaches vertical dragging on hover.
cleanup();
renderTimeline(undefined, { id: "ann1", startMs: 0, endMs: TOTAL_SEC * 1000 });
const wide = document.querySelector("[class*=lanePill]") as HTMLElement;
expect(wide).toHaveTextContent("toolbar.newAnnotation");
- expect(wide).not.toHaveAttribute("title");
+ expect(wide.title).toContain("tracks.dragHint");
});
});
diff --git a/src/components/ai-edition/v4/V4Timeline.tsx b/src/components/ai-edition/v4/V4Timeline.tsx
index bb026fcd8..83ae04ce9 100644
--- a/src/components/ai-edition/v4/V4Timeline.tsx
+++ b/src/components/ai-edition/v4/V4Timeline.tsx
@@ -61,6 +61,15 @@ import {
setTimelineScale,
} from "@/lib/ai-edition/timeline/newRegionDuration";
import { ventilateSpanAcrossClips } from "@/lib/ai-edition/timeline/region-ventilation";
+import {
+ type AnnotationTrackDrop,
+ annotationDropLayers,
+ annotationTrackPills,
+ packRegionRows,
+ REGION_LANE_PAD_PX,
+ REGION_ROW_STEP_PX,
+ regionLaneHeight,
+} from "@/lib/ai-edition/timeline/regionTracks";
import { coalesceRegionsForRuler } from "@/lib/ai-edition/timeline/timelineMap";
import {
coalescedTrimGroups,
@@ -602,6 +611,8 @@ interface LanePill {
label: string;
/** Underlying row ids this pill represents — >1 for a coalesced trim group. */
sourceIds: string[];
+ layer?: number;
+ stackOrder?: number;
}
export function V4Timeline({
@@ -614,6 +625,7 @@ export function V4Timeline({
onTogglePlay,
onEditClip,
onAddVoiceover,
+ onAnnotationRowCountChange,
}: {
tl: TimelineApi;
setCurrentTime: (sec: number) => void;
@@ -628,6 +640,8 @@ export function V4Timeline({
/** Opens the voiceover recorder. Shell-level like the clip editor: the
* dialog owns the microphone and the shell owns the transport. */
onAddVoiceover: () => void;
+ /** Exact rendered annotation row count, including the current drag preview. */
+ onAnnotationRowCountChange?: (rowCount: number) => void;
}) {
const t = useScopedT("timeline");
// The live bindings, not the defaults: these keys are remappable, and a menu
@@ -738,16 +752,26 @@ export function V4Timeline({
// touching-but-different regions must not silently merge into one.
// Pills follow the universal merge rule (timelineMap): regions of the same kind whose
// PROPERTIES are equal and whose spans touch render as ONE pill, however they came to be
- // adjacent. Different properties never merge (and cannot overlap — they repel on edit).
+ // adjacent. Annotations can overlap on separate tracks; other modifiers repel on edit.
// Trims obey the same rule with an empty property set, so they always merge.
- const annPills: LanePill[] = coalesceRegionsForRuler(tl.annotationRegions).map((p) => ({
- id: p.ids[0],
- kind: "annotation",
- start: p.start,
- end: p.end,
- label: t("toolbar.newAnnotation"),
- sourceIds: p.ids,
- }));
+ const annPills: LanePill[] = useMemo(
+ () =>
+ annotationTrackPills(tl.annotationRegions).map((p) => ({
+ id: p.id,
+ kind: "annotation" as const,
+ start: p.start,
+ end: p.end,
+ label:
+ (p.member.type === "text" ? p.member.content || p.member.textContent : "")?.trim() ||
+ t("toolbar.newAnnotation"),
+ sourceIds: p.ids,
+ layer: p.layer,
+ stackOrder: p.stackOrder,
+ })),
+ [tl.annotationRegions, t],
+ );
+ const savedAnnotationRows = useMemo(() => packRegionRows(annPills), [annPills]);
+
const speedRuns = coalesceRegionsForRuler(tl.speedRegions);
const speedPills: LanePill[] = speedRuns.map((p) => ({
id: p.ids[0],
@@ -929,12 +953,16 @@ export function V4Timeline({
kind: LanePill["kind"];
start: number;
end: number;
+ drop?: AnnotationTrackDrop;
+ layers?: Map<string, number>;
} | null>(null);
const activePillDragRef = useRef<{
id: string;
kind: LanePill["kind"];
start: number;
end: number;
+ drop?: AnnotationTrackDrop;
+ layers?: Map<string, number>;
} | null>(null);
// A merged pill can be several regions that merely match (#1017), and an edit must reach
@@ -979,6 +1007,8 @@ export function V4Timeline({
// A move rebuilds the pill as one region that keeps this id, so the selection survives.
const grabbed = selectPill(pill, e.shiftKey, ((e.clientX - r.left) / r.width) * total);
const startX = e.clientX;
+ const startY = e.clientY;
+ const originalRow = savedAnnotationRows.rowOf.get(pill.id) ?? 0;
const dur = pill.end - pill.start;
// A trim can span several clips; it's stored as one source-time entry per
// covered clip. `trimOwned` are the entry ids this drag controls — seeded
@@ -1016,14 +1046,19 @@ export function V4Timeline({
setSnapPct(best === v ? null : (best / total) * 100);
return best;
};
- const apply = async (start: number, end: number): Promise<void> => {
+ const apply = async (
+ start: number,
+ end: number,
+ drop?: AnnotationTrackDrop,
+ ): Promise<void> => {
const s = Math.max(0, Math.min(end - MIN_REGION_SEC, start));
const en = Math.min(total, Math.max(s + MIN_REGION_SEC, end));
if (pill.kind === "zoom") await tl.updateZoomSpan(grabbed, s * 1000, en * 1000);
else if (pill.kind === "speed") await tl.updateSpeedSpan(grabbed, s * 1000, en * 1000);
- else if (pill.kind === "annotation")
- await tl.updateAnnotationSpan(grabbed, s * 1000, en * 1000);
- else if (pill.kind === "cameraFullscreen")
+ else if (pill.kind === "annotation") {
+ if (drop === undefined) await tl.updateAnnotationSpan(grabbed, s * 1000, en * 1000);
+ else await tl.updateAnnotationSpan(grabbed, s * 1000, en * 1000, drop);
+ } else if (pill.kind === "cameraFullscreen")
await tl.updateCameraFullscreenSpan(grabbed, s * 1000, en * 1000);
else if (pill.kind === "shaderEffect")
await tl.updateShaderEffectSpan(grabbed, s * 1000, en * 1000);
@@ -1062,7 +1097,25 @@ export function V4Timeline({
ns = pill.start;
ne = Math.min(total, Math.max(pill.start + MIN_REGION_SEC, snap(pill.end + dxSec)));
}
- const nextState = { id: pill.id, kind: pill.kind, start: ns, end: ne };
+ let drop: AnnotationTrackDrop | undefined;
+ if (pill.kind === "annotation" && dragMode === "move") {
+ const rowDelta = Math.round((ev.clientY - startY) / REGION_ROW_STEP_PX);
+ if (rowDelta !== 0)
+ drop = {
+ row: originalRow + rowDelta,
+ direction: rowDelta < 0 ? "up" : "down",
+ };
+ }
+ const layers = drop
+ ? annotationDropLayers(
+ annPills,
+ pill.id,
+ { start: ns, end: ne },
+ drop,
+ savedAnnotationRows,
+ )
+ : undefined;
+ const nextState = { id: pill.id, kind: pill.kind, start: ns, end: ne, drop, layers };
activePillDragRef.current = nextState;
setActivePillDrag(nextState);
};
@@ -1072,7 +1125,7 @@ export function V4Timeline({
window.removeEventListener("pointerup", up);
const finalDrag = activePillDragRef.current;
if (finalDrag) {
- void apply(finalDrag.start, finalDrag.end).finally(() => {
+ void apply(finalDrag.start, finalDrag.end, finalDrag.drop).finally(() => {
if (activePillDragRef.current === finalDrag) {
activePillDragRef.current = null;
setActivePillDrag(null);
@@ -1086,7 +1139,7 @@ export function V4Timeline({
window.addEventListener("pointermove", move);
window.addEventListener("pointerup", up);
},
- [tl, selectPill, total, clips, pxPerSec],
+ [tl, selectPill, total, clips, pxPerSec, annPills, savedAnnotationRows],
);
// Live preview geometry for an audio track being dragged (issue #350), the
@@ -1684,6 +1737,7 @@ export function V4Timeline({
// edge de-styled so a split pill still reads as one continuous shape.
const renderOnePill = (seg: {
pill: LanePill;
+ row: number;
key: string;
segStart: number;
segEnd: number;
@@ -1703,11 +1757,19 @@ export function V4Timeline({
<div
key={seg.key}
role={seg.interactive ? "button" : undefined}
+ data-region-id={p.id}
+ data-track-row={seg.row}
+ aria-label={
+ p.kind === "annotation"
+ ? `${p.label}, ${t("tracks.annotation", { index: seg.row + 1 })}`
+ : p.label
+ }
tabIndex={seg.interactive ? 0 : undefined}
className={`${styles.lanePill} ${laneOf(p.kind)}${
compact ? ` ${styles.lanePillCompact}` : ""
}${seg.interactive && isPillSelected(p) ? ` ${styles.lanePillSel}` : ""}`}
style={{
+ top: REGION_LANE_PAD_PX + seg.row * REGION_ROW_STEP_PX,
left: `${pctAt(seg.segStart)}%`,
// Measured on the expanded ruler at BOTH ends: a region straddling a pause
// covers it, so its box has to grow by that pause and not merely slide.
@@ -1744,9 +1806,15 @@ export function V4Timeline({
}
: undefined
}
- // The name on hover only where the pill cannot show it: a pill that draws its own
- // label would repeat it.
- title={seg.showContent && roomForLabel ? undefined : p.label}
+ // Annotations teach vertical dragging on the pill; other kinds only repeat
+ // their name when the pill is too narrow to draw it.
+ title={
+ p.kind === "annotation"
+ ? `${p.label} — ${t("tracks.dragHint")}`
+ : seg.showContent && roomForLabel
+ ? undefined
+ : p.label
+ }
>
{seg.interactive ? (
<span
@@ -1772,14 +1840,35 @@ export function V4Timeline({
);
};
- // A pill's span as drawn: the live drag geometry while it is being dragged.
+ // Only annotations stack. Pack their live geometry once, for pills and lane height.
+ const effectiveAnnotations = useMemo(
+ () =>
+ annPills.map((p) => ({
+ ...p,
+ ...(activePillDrag?.id === p.id
+ ? { start: activePillDrag.start, end: activePillDrag.end }
+ : {}),
+ layer: activePillDrag?.layers?.get(p.id) ?? p.layer,
+ })),
+ [annPills, activePillDrag],
+ );
+ const annotationRows = useMemo(
+ () =>
+ activePillDrag?.kind === "annotation"
+ ? packRegionRows(effectiveAnnotations)
+ : savedAnnotationRows,
+ [effectiveAnnotations, savedAnnotationRows, activePillDrag?.kind],
+ );
+ useEffect(() => {
+ onAnnotationRowCountChange?.(annotationRows.rowCount);
+ }, [annotationRows.rowCount, onAnnotationRowCountChange]);
+
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;
+ activePillDrag?.id === id ? { ...p, start: activePillDrag.start, end: activePillDrag.end } : p;
const renderPills = (pills: LanePill[], emptyLabel: string) => {
- const effectivePills = pills.map((p) => liveSpan(p.id, p));
+ const annotations = pills === annPills;
+ const effectivePills = annotations ? effectiveAnnotations : pills.map((p) => liveSpan(p.id, p));
return (
<>
{effectivePills.length === 0 ? (
@@ -1821,6 +1910,7 @@ export function V4Timeline({
return [
renderOnePill({
pill: p,
+ row: annotations ? (annotationRows.rowOf.get(p.id) ?? 0) : 0,
key: `${p.id}__f${i}`,
segStart: c.timelineStartSec + f.localStartSec,
segEnd: c.timelineStartSec + f.localEndSec,
@@ -1840,6 +1930,7 @@ export function V4Timeline({
return [
renderOnePill({
pill: p,
+ row: annotations ? (annotationRows.rowOf.get(p.id) ?? 0) : 0,
key: p.id,
segStart: p.start,
segEnd: p.end,
@@ -1939,6 +2030,7 @@ export function V4Timeline({
data-zoom-trail={trail.side}
className={`${styles.zoomTrail} ${styles.laneZoom}`}
style={{
+ top: 5,
left: `${pctAt(trail.fromMs / 1000)}%`,
width: `${pctOf(lengthMs / 1000)}%`,
}}
@@ -2282,7 +2374,11 @@ export function V4Timeline({
strings the pre-v4 timeline used, so the keys stay translated. The key
is the live binding, formatted like the toolbar tooltip's chip, so a
rebind in the shortcuts dialog moves the hint with it (#966). */}
- <div className={styles.tlLane}>
+ <div
+ className={styles.tlLane}
+ data-track-kind="annotation"
+ style={{ height: regionLaneHeight(annotationRows.rowCount) }}
+ >
{renderPills(
annPills,
t("hints.pressAnnotation", {
@@ -2290,19 +2386,19 @@ export function V4Timeline({
}),
)}
</div>
- <div className={styles.tlLane}>
+ <div className={styles.tlLane} data-track-kind="speed">
{renderPills(
speedPills,
t("hints.pressSpeed", { key: formatBinding(shortcuts.addSpeed, isMac) }),
)}
</div>
- <div className={styles.tlLane}>
+ <div className={styles.tlLane} data-track-kind="trim">
{renderPills(
trimPills,
t("hints.pressTrim", { key: formatBinding(shortcuts.addTrim, isMac) }),
)}
</div>
- <div className={styles.tlLane}>
+ <div className={styles.tlLane} data-track-kind="zoom">
{/* Its own provider, like the toolbar's: see the note there. */}
<TooltipProvider>{renderZoomTrails()}</TooltipProvider>
{renderPills(
@@ -2310,7 +2406,7 @@ export function V4Timeline({
t("hints.pressZoom", { key: formatBinding(shortcuts.addZoom, isMac) }),
)}
</div>
- <div className={styles.tlLane}>
+ <div className={styles.tlLane} data-track-kind="cameraFullscreen">
{/* Advertising "Press C" on a project with no webcam invites a keystroke
that `addCameraFullscreen` now refuses (#353). The toolbar button is
already disabled; this keeps the lane from contradicting it. */}
diff --git a/src/i18n/locales/ar/timeline.json b/src/i18n/locales/ar/timeline.json
index 21e5d5fae..c802060db 100644
--- a/src/i18n/locales/ar/timeline.json
+++ b/src/i18n/locales/ar/timeline.json
@@ -112,5 +112,9 @@
"recordingUnavailable": "التسجيل غير متاح هنا",
"saveFailed": "تعذر حفظ التسجيل",
"importFailed": "تعذر استيراد الملف الصوتي"
+ },
+ "tracks": {
+ "annotation": "طبقة التعليق {{index}}",
+ "dragHint": "اسحب يمينًا أو يسارًا لتغيير الوقت. اسحب لأعلى أو لأسفل لتغيير الطبقة؛ تظهر الطبقات الأعلى في المقدمة."
}
}
diff --git a/src/i18n/locales/cs/timeline.json b/src/i18n/locales/cs/timeline.json
index 9e93b4eb7..8fe84616b 100644
--- a/src/i18n/locales/cs/timeline.json
+++ b/src/i18n/locales/cs/timeline.json
@@ -112,5 +112,9 @@
"recordingUnavailable": "Nahrávání zde není dostupné",
"saveFailed": "Nepodařilo se uložit nahrávku",
"importFailed": "Nepodařilo se importovat zvukový soubor"
+ },
+ "tracks": {
+ "annotation": "Vrstva anotace {{index}}",
+ "dragHint": "Tažením doleva nebo doprava posunete čas. Tažením nahoru nebo dolů změníte vrstvu; vyšší vrstvy jsou v popředí."
}
}
diff --git a/src/i18n/locales/de/timeline.json b/src/i18n/locales/de/timeline.json
index fa18db607..9707bbfcc 100644
--- a/src/i18n/locales/de/timeline.json
+++ b/src/i18n/locales/de/timeline.json
@@ -112,5 +112,9 @@
"recordingUnavailable": "Aufnahme ist hier nicht verfügbar",
"saveFailed": "Die Aufnahme konnte nicht gespeichert werden",
"importFailed": "Die Audiodatei konnte nicht importiert werden"
+ },
+ "tracks": {
+ "annotation": "Anmerkungsebene {{index}}",
+ "dragHint": "Nach links oder rechts ziehen, um die Zeit zu ändern. Nach oben oder unten ziehen, um die Ebene zu ändern; höhere Ebenen liegen vorne."
}
}
diff --git a/src/i18n/locales/en/timeline.json b/src/i18n/locales/en/timeline.json
index ec4b8d28f..febfb7bc3 100644
--- a/src/i18n/locales/en/timeline.json
+++ b/src/i18n/locales/en/timeline.json
@@ -112,5 +112,9 @@
"recordingUnavailable": "Recording is not available here",
"saveFailed": "Could not save the recording",
"importFailed": "Could not import the audio file"
+ },
+ "tracks": {
+ "annotation": "Annotation layer {{index}}",
+ "dragHint": "Drag left or right to move in time. Drag up or down to change layer; higher layers appear on top."
}
}
diff --git a/src/i18n/locales/es/timeline.json b/src/i18n/locales/es/timeline.json
index f4fcd4374..70df7142d 100644
--- a/src/i18n/locales/es/timeline.json
+++ b/src/i18n/locales/es/timeline.json
@@ -112,5 +112,9 @@
"recordingUnavailable": "La grabación no está disponible aquí",
"saveFailed": "No se pudo guardar la grabación",
"importFailed": "No se pudo importar el archivo de audio"
+ },
+ "tracks": {
+ "annotation": "Capa de anotación {{index}}",
+ "dragHint": "Arrastra a izquierda o derecha para cambiar el tiempo. Arrastra arriba o abajo para cambiar de capa; las capas superiores aparecen delante."
}
}
diff --git a/src/i18n/locales/fr/timeline.json b/src/i18n/locales/fr/timeline.json
index 4fd7b3123..ed36c7d2f 100644
--- a/src/i18n/locales/fr/timeline.json
+++ b/src/i18n/locales/fr/timeline.json
@@ -112,5 +112,9 @@
"recordingUnavailable": "L'enregistrement n'est pas disponible ici",
"saveFailed": "Impossible d'enregistrer la capture",
"importFailed": "Impossible d'importer le fichier audio"
+ },
+ "tracks": {
+ "annotation": "Calque d’annotation {{index}}",
+ "dragHint": "Glissez à gauche ou à droite pour déplacer dans le temps. Glissez vers le haut ou le bas pour changer de calque ; les calques supérieurs apparaissent devant."
}
}
diff --git a/src/i18n/locales/it/timeline.json b/src/i18n/locales/it/timeline.json
index e73a04db9..c712b6880 100644
--- a/src/i18n/locales/it/timeline.json
+++ b/src/i18n/locales/it/timeline.json
@@ -112,5 +112,9 @@
"recordingUnavailable": "La registrazione non è disponibile qui",
"saveFailed": "Impossibile salvare la registrazione",
"importFailed": "Impossibile importare il file audio"
+ },
+ "tracks": {
+ "annotation": "Livello annotazione {{index}}",
+ "dragHint": "Trascina a sinistra o destra per spostare nel tempo. Trascina in alto o in basso per cambiare livello; i livelli superiori appaiono davanti."
}
}
diff --git a/src/i18n/locales/ja-JP/timeline.json b/src/i18n/locales/ja-JP/timeline.json
index 0f41b8fc9..3b6d983f7 100644
--- a/src/i18n/locales/ja-JP/timeline.json
+++ b/src/i18n/locales/ja-JP/timeline.json
@@ -112,5 +112,9 @@
"recordingUnavailable": "ここでは録音できません",
"saveFailed": "録音を保存できませんでした",
"importFailed": "音声ファイルを読み込めませんでした"
+ },
+ "tracks": {
+ "annotation": "注釈レイヤー {{index}}",
+ "dragHint": "左右にドラッグして時間を移動します。上下にドラッグしてレイヤーを変更します。上のレイヤーが手前に表示されます。"
}
}
diff --git a/src/i18n/locales/ko-KR/timeline.json b/src/i18n/locales/ko-KR/timeline.json
index 64670c712..b1724c757 100644
--- a/src/i18n/locales/ko-KR/timeline.json
+++ b/src/i18n/locales/ko-KR/timeline.json
@@ -112,5 +112,9 @@
"recordingUnavailable": "여기에서는 녹음할 수 없습니다",
"saveFailed": "녹음을 저장하지 못했습니다",
"importFailed": "오디오 파일을 가져오지 못했습니다"
+ },
+ "tracks": {
+ "annotation": "주석 레이어 {{index}}",
+ "dragHint": "좌우로 드래그하여 시간을 이동합니다. 위아래로 드래그하여 레이어를 변경합니다. 위쪽 레이어가 앞에 표시됩니다."
}
}
diff --git a/src/i18n/locales/pt-BR/timeline.json b/src/i18n/locales/pt-BR/timeline.json
index fee6e6933..7680fb05c 100644
--- a/src/i18n/locales/pt-BR/timeline.json
+++ b/src/i18n/locales/pt-BR/timeline.json
@@ -112,5 +112,9 @@
"recordingUnavailable": "A gravação não está disponível aqui",
"saveFailed": "Não foi possível salvar a gravação",
"importFailed": "Não foi possível importar o arquivo de áudio"
+ },
+ "tracks": {
+ "annotation": "Camada de anotação {{index}}",
+ "dragHint": "Arraste para a esquerda ou direita para mover no tempo. Arraste para cima ou baixo para mudar de camada; as camadas superiores aparecem na frente."
}
}
diff --git a/src/i18n/locales/ru/timeline.json b/src/i18n/locales/ru/timeline.json
index f7ad39905..18e2850d9 100644
--- a/src/i18n/locales/ru/timeline.json
+++ b/src/i18n/locales/ru/timeline.json
@@ -112,5 +112,9 @@
"recordingUnavailable": "Запись здесь недоступна",
"saveFailed": "Не удалось сохранить запись",
"importFailed": "Не удалось импортировать аудиофайл"
+ },
+ "tracks": {
+ "annotation": "Слой аннотации {{index}}",
+ "dragHint": "Перетаскивайте влево или вправо для перемещения по времени. Перетаскивайте вверх или вниз для смены слоя; верхние слои отображаются впереди."
}
}
diff --git a/src/i18n/locales/tr/timeline.json b/src/i18n/locales/tr/timeline.json
index d0dae7ceb..977041ea8 100644
--- a/src/i18n/locales/tr/timeline.json
+++ b/src/i18n/locales/tr/timeline.json
@@ -112,5 +112,9 @@
"recordingUnavailable": "Burada kayıt kullanılamıyor",
"saveFailed": "Kayıt kaydedilemedi",
"importFailed": "Ses dosyası içe aktarılamadı"
+ },
+ "tracks": {
+ "annotation": "Açıklama katmanı {{index}}",
+ "dragHint": "Zamanı değiştirmek için sola veya sağa sürükleyin. Katmanı değiştirmek için yukarı veya aşağı sürükleyin; üst katmanlar önde görünür."
}
}
diff --git a/src/i18n/locales/vi/timeline.json b/src/i18n/locales/vi/timeline.json
index 9baf8a115..da6c13099 100644
--- a/src/i18n/locales/vi/timeline.json
+++ b/src/i18n/locales/vi/timeline.json
@@ -112,5 +112,9 @@
"recordingUnavailable": "Không thể ghi âm ở đây",
"saveFailed": "Không thể lưu bản ghi",
"importFailed": "Không thể nhập tệp âm thanh"
+ },
+ "tracks": {
+ "annotation": "Lớp chú thích {{index}}",
+ "dragHint": "Kéo sang trái hoặc phải để di chuyển theo thời gian. Kéo lên hoặc xuống để đổi lớp; lớp cao hơn hiển thị phía trước."
}
}
diff --git a/src/i18n/locales/zh-CN/timeline.json b/src/i18n/locales/zh-CN/timeline.json
index 149a56a61..d15a420b7 100644
--- a/src/i18n/locales/zh-CN/timeline.json
+++ b/src/i18n/locales/zh-CN/timeline.json
@@ -112,5 +112,9 @@
"recordingUnavailable": "此处无法录音",
"saveFailed": "无法保存录音",
"importFailed": "无法导入音频文件"
+ },
+ "tracks": {
+ "annotation": "注释图层 {{index}}",
+ "dragHint": "左右拖动以调整时间。上下拖动以切换图层;上方图层显示在前面。"
}
}
diff --git a/src/i18n/locales/zh-TW/timeline.json b/src/i18n/locales/zh-TW/timeline.json
index ed255420b..ec99b7582 100644
--- a/src/i18n/locales/zh-TW/timeline.json
+++ b/src/i18n/locales/zh-TW/timeline.json
@@ -112,5 +112,9 @@
"recordingUnavailable": "此處無法錄音",
"saveFailed": "無法儲存錄音",
"importFailed": "無法匯入音訊檔案"
+ },
+ "tracks": {
+ "annotation": "註解圖層 {{index}}",
+ "dragHint": "左右拖曳以調整時間。上下拖曳以切換圖層;上方圖層顯示在前面。"
}
}
diff --git a/src/lib/ai-edition/document/timeline.ts b/src/lib/ai-edition/document/timeline.ts
index 2b8366ba3..6b1c95f3d 100644
--- a/src/lib/ai-edition/document/timeline.ts
+++ b/src/lib/ai-edition/document/timeline.ts
@@ -1178,7 +1178,10 @@ export function removeRegion(document: AxcutDocument, kind: RegionKind, id: stri
zoomRanges: dropPillById(document.zoomRanges, id) as AxcutDocument["zoomRanges"],
};
case "annotation":
- return { ...document, annotations: dropPillById(document.annotations, id) };
+ return {
+ ...document,
+ annotations: dropPillById(document.annotations, id, { annotations: true }),
+ };
case "audio":
// Not `dropPillById`: an audio track's fragments are grouped by
// `trackId`, and deleting the pill has to take the asset with it when
diff --git a/src/lib/ai-edition/store/useTimeline.test.ts b/src/lib/ai-edition/store/useTimeline.test.ts
index f8e6ba8a3..49be2a3ca 100644
--- a/src/lib/ai-edition/store/useTimeline.test.ts
+++ b/src/lib/ai-edition/store/useTimeline.test.ts
@@ -838,6 +838,146 @@ describe("useTimeline.addAnnotation", () => {
expect([position.x + size.width / 2, position.y + size.height / 2]).toEqual([50, 50]);
expect(annotation.style.backgroundColor).toBe(DEFAULT_TEXT_PLATE);
});
+
+ it("adds above the highest saved layer even after other annotations were deleted", async () => {
+ const { result } = renderTimeline();
+ await act(async () => {
+ await result.current.addAnnotation();
+ });
+ const doc = useProjectStore.getState().document as AxcutDocument;
+ act(() => {
+ useProjectStore.setState({
+ document: {
+ ...doc,
+ annotations: [{ ...doc.annotations[0], zIndex: 12 }],
+ },
+ });
+ });
+ await act(async () => {
+ await result.current.addAnnotation();
+ });
+ expect(useProjectStore.getState().document?.annotations.map((a) => a.zIndex)).toEqual([12, 13]);
+ });
+
+ it("moves above an overlapping annotation on an occupied track", async () => {
+ const { result } = renderTimeline();
+ await act(async () => {
+ await result.current.addAnnotation();
+ });
+ await act(async () => {
+ await result.current.addAnnotation();
+ });
+ const before = useProjectStore.getState().document as AxcutDocument;
+ const [low, high] = before.annotations;
+ await act(async () => {
+ await result.current.updateAnnotationSpan(low.id, 1500, 3500, { row: 0, direction: "up" });
+ });
+ const after = useProjectStore.getState().document as AxcutDocument;
+ expect(after.annotations.find((a) => a.id === high.id)).toMatchObject({ ...high, zIndex: 0 });
+ expect(after.annotations.find((a) => a.id === low.id)?.zIndex).toBe(1);
+ });
+
+ it("preserves saved compositing tie order on a horizontal move into an identical annotation", async () => {
+ const { result } = renderTimeline();
+ await act(async () => {
+ await result.current.addAnnotation();
+ });
+ const doc = useProjectStore.getState().document as AxcutDocument;
+ const original = doc.annotations[0];
+ act(() => {
+ useProjectStore.setState({
+ document: {
+ ...doc,
+ annotations: [
+ original,
+ {
+ ...original,
+ id: "second",
+ startMs: 5000,
+ endMs: 7000,
+ sourceStartSec: 5,
+ sourceEndSec: 7,
+ },
+ ],
+ },
+ });
+ });
+ await act(async () => {
+ await result.current.updateAnnotationSpan("second", 2000, 4000);
+ });
+ const after = useProjectStore.getState().document as AxcutDocument;
+ expect(after.annotations.find((a) => a.id === original.id)).toEqual(original);
+ expect(after.annotations.find((a) => a.id === "second")).toMatchObject({
+ zIndex: original.zIndex,
+ startMs: 2000,
+ endMs: 4000,
+ });
+ });
+
+ it("moves down below an overlapping annotation with the same saved layer", async () => {
+ const { result } = renderTimeline();
+ await act(async () => {
+ await result.current.addAnnotation();
+ });
+ const doc = useProjectStore.getState().document as AxcutDocument;
+ const back = doc.annotations[0];
+ act(() => {
+ useProjectStore.setState({
+ document: { ...doc, annotations: [back, { ...back, id: "front" }] },
+ });
+ });
+ await act(async () => {
+ await result.current.updateAnnotationSpan("front", 2000, 4000, { row: 1, direction: "down" });
+ });
+ const annotations = useProjectStore.getState().document?.annotations ?? [];
+ expect(annotations.find((a) => a.id === "front")?.zIndex).toBe(0);
+ expect(annotations.find((a) => a.id === back.id)?.zIndex).toBe(1);
+ });
+
+ it("saves an overlapping span and bottom-layer move together and supports undo, redo and reload", async () => {
+ const { result } = renderTimeline();
+ await act(async () => {
+ await result.current.addAnnotation();
+ });
+ await act(async () => {
+ await result.current.addAnnotation();
+ });
+ const doc = useProjectStore.getState().document as AxcutDocument;
+ act(() => {
+ useProjectStore.setState({
+ document: {
+ ...doc,
+ annotations: doc.annotations.map((a, i) => ({ ...a, zIndex: i })),
+ },
+ });
+ });
+ const before = useProjectStore.getState().document as AxcutDocument;
+ clearHistory();
+ bridgeMocks.save.mockClear();
+ const id = before.annotations[1].id;
+ await act(async () => {
+ await result.current.updateAnnotationSpan(id, 2000, 4000, { row: 1, direction: "down" });
+ });
+ const after = useProjectStore.getState().document as AxcutDocument;
+ expect(bridgeMocks.save).toHaveBeenCalledTimes(1);
+ expect(after.annotations.find((a) => a.id === id)).toMatchObject({
+ startMs: 2000,
+ endMs: 4000,
+ zIndex: 0,
+ });
+ expect(after.annotations.find((a) => a.id !== id)?.zIndex).toBe(1);
+ expect(parseDocumentFile(JSON.parse(JSON.stringify(after))).annotations).toEqual(
+ after.annotations,
+ );
+ await act(async () => {
+ await undo();
+ });
+ expect(useProjectStore.getState().document?.annotations).toEqual(before.annotations);
+ await act(async () => {
+ await redo();
+ });
+ expect(useProjectStore.getState().document?.annotations).toEqual(after.annotations);
+ });
});
// The Clear timeline button. Every edit region on every clip, one write; the content stays.
diff --git a/src/lib/ai-edition/store/useTimeline.ts b/src/lib/ai-edition/store/useTimeline.ts
index 7d650ed85..50d717046 100644
--- a/src/lib/ai-edition/store/useTimeline.ts
+++ b/src/lib/ai-edition/store/useTimeline.ts
@@ -51,6 +51,11 @@ import {
import { appendAutoZoomSuggestions } from "../timeline/apply-auto-zooms";
import { hasAnyClipWithCamera } from "../timeline/camera";
import { probeAudioDuration, probeVideoDimensions, probeVideoDuration } from "../timeline/duration";
+import {
+ type AnnotationTrackDrop,
+ annotationDropLayers,
+ annotationTrackPills,
+} from "../timeline/regionTracks";
import {
anchorRegionsWithDerivedMs,
dropPillsByIds,
@@ -102,8 +107,9 @@ function patchRegionById<T extends { id: string; startMs: number; endMs: number;
regions: T[],
id: string,
patch: Partial<T>,
+ annotations = false,
): T[] {
- const under = new Set(resolveRegionIds(regions, id));
+ const under = new Set(resolveRegionIds(regions, id, 0.001, { annotations }));
return regions.map((r) => (under.has(r.id) ? { ...r, ...patch } : r));
}
@@ -520,7 +526,7 @@ export function useTimeline() {
textAlign: "center",
textAnimation: "none",
},
- zIndex: document.annotations.length + 1,
+ zIndex: Math.max(0, ...document.annotations.map((a) => a.zIndex)) + 1,
};
const frameAspect = resolveAspectRatioValue(
document,
@@ -969,22 +975,41 @@ export function useTimeline() {
);
const updateAnnotationSpan = useCallback(
- async (id: string, startMs: number, endMs: number) => {
+ async (id: string, startMs: number, endMs: number, drop?: AnnotationTrackDrop) => {
if (!document) return;
- const s = finiteMs(startMs);
- const e = finiteMs(endMs);
- const next: AxcutDocument = {
- ...document,
- annotations: replacePillSpan(
- document.annotations,
- id,
- Math.min(s, e),
- Math.max(s, e),
- document.timeline.clips,
- () => createId("ann"),
- ),
- };
- await saveDocument(next, { history: true });
+ const s = Math.min(finiteMs(startMs), finiteMs(endMs));
+ const e = Math.max(finiteMs(startMs), finiteMs(endMs));
+ const pills = annotationTrackPills(document.annotations);
+ const pill = pills.find((p) => p.ids.includes(id));
+ if (!pill) return;
+ const layers = drop
+ ? annotationDropLayers(pills, pill.id, { start: s / 1000, end: e / 1000 }, drop)
+ : new Map<string, number>();
+ const layerByRegion = new Map(
+ pills.flatMap((p) => p.ids.map((regionId) => [regionId, layers.get(p.id)] as const)),
+ );
+ const annotations = document.annotations.map((a) => {
+ const layer = layerByRegion.get(a.id);
+ return layer === undefined ? a : { ...a, zIndex: layer };
+ });
+ // Span and compositing order persist together as one undo step.
+ await saveDocument(
+ {
+ ...document,
+ annotations: replacePillSpan(
+ annotations,
+ id,
+ s,
+ e,
+ document.timeline.clips,
+ () => createId("ann"),
+ 0.001,
+ {},
+ { annotations: true },
+ ),
+ },
+ { history: true },
+ );
},
[document, saveDocument],
);
@@ -1001,7 +1026,7 @@ export function useTimeline() {
if (annotationLiveRef.current !== doc) annotationRollbackRef.current = doc;
const next: AxcutDocument = {
...doc,
- annotations: patchRegionById(doc.annotations, id, patch),
+ annotations: patchRegionById(doc.annotations, id, patch, true),
};
setDocument(next, { history: false });
annotationLiveRef.current = next;
@@ -1228,7 +1253,7 @@ export function useTimeline() {
const next: AxcutDocument = pruneUnusedShaderEffects({
...document,
zoomRanges: dropPillsByIds(document.zoomRanges, zoomIds) as AxcutDocument["zoomRanges"],
- annotations: dropPillsByIds(document.annotations, annotationIds),
+ annotations: dropPillsByIds(document.annotations, annotationIds, { annotations: true }),
...(shaderEffectIds.size > 0
? {
shaderEffectRanges: dropPillsByIds(
diff --git a/src/lib/ai-edition/timeline/regionTracks.test.ts b/src/lib/ai-edition/timeline/regionTracks.test.ts
new file mode 100644
index 000000000..bc963a423
--- /dev/null
+++ b/src/lib/ai-edition/timeline/regionTracks.test.ts
@@ -0,0 +1,116 @@
+import { describe, expect, it } from "vitest";
+import {
+ annotationDropLayers,
+ annotationTrackPills,
+ packRegionRows,
+ regionLaneHeight,
+} from "./regionTracks";
+
+describe("region tracks", () => {
+ it("keeps nested and identical spans independently reachable", () => {
+ const tracks = packRegionRows([
+ { id: "background", start: 0, end: 67 },
+ { id: "second", start: 35, end: 40 },
+ { id: "third", start: 35, end: 40 },
+ ]);
+ expect(tracks.rowCount).toBe(3);
+ expect(new Set(tracks.rowOf.values()).size).toBe(3);
+ expect(regionLaneHeight(tracks.rowCount)).toBe(78);
+ });
+
+ it("reuses rows for nonoverlapping elements regardless of their saved layers", () => {
+ const tracks = packRegionRows([
+ { id: "low", start: 0, end: 2, layer: 1 },
+ { id: "high", start: 0, end: 2, layer: 10 },
+ { id: "later", start: 2, end: 4, layer: 10 },
+ ]);
+ expect(tracks.rowCount).toBe(2);
+ expect(tracks.rowOf.get("high")).toBe(0);
+ expect(tracks.rowOf.get("later")).toBe(0);
+ expect(tracks.rowOf.get("low")).toBe(1);
+ });
+
+ it("packs ten back-to-back annotations with unique saved layers into one row", () => {
+ const spans = Array.from({ length: 10 }, (_, i) => ({
+ id: String(i),
+ start: i / 10,
+ end: (i + 1) / 10,
+ layer: i + 1,
+ }));
+ expect(packRegionRows(spans).rowCount).toBe(1);
+ });
+
+ it("places a lower annotation below every higher annotation it overlaps", () => {
+ const tracks = packRegionRows([
+ { id: "top", start: 0, end: 2, layer: 3 },
+ { id: "middle", start: 1, end: 4, layer: 2 },
+ { id: "bottom", start: 3, end: 5, layer: 1 },
+ ]);
+ expect([...tracks.rowOf.entries()]).toEqual([
+ ["top", 0],
+ ["middle", 1],
+ ["bottom", 2],
+ ]);
+ });
+
+ it("uses saved tie order consistently for drawing and height, independent of start order", () => {
+ const spans = annotationTrackPills([
+ { id: "back", startMs: 3000, endMs: 5000, zIndex: 1 },
+ { id: "middle", startMs: 1000, endMs: 4000, zIndex: 1 },
+ { id: "front", startMs: 0, endMs: 2000, zIndex: 1 },
+ ]);
+ const tracks = packRegionRows(spans);
+ expect(tracks.rowCount).toBe(3);
+ expect(tracks.rowOf.get("back")).toBe(2);
+ });
+
+ it("drops down below an occupied row even when annotations share a saved layer", () => {
+ const spans = [
+ { id: "back", start: 0, end: 10, layer: 1, stackOrder: 0 },
+ { id: "front", start: 0, end: 10, layer: 1, stackOrder: 1 },
+ ];
+ const layers = annotationDropLayers(
+ spans,
+ "front",
+ { start: 0, end: 10 },
+ { row: 1, direction: "down" },
+ );
+ expect(layers.get("front")).toBeLessThan(layers.get("back") ?? 0);
+ });
+
+ it("reorders against overlaps at the horizontal drop position", () => {
+ const spans = [
+ { id: "left", start: 0, end: 10, layer: 100 },
+ { id: "right", start: 20, end: 30, layer: 1 },
+ { id: "moving", start: 0, end: 10, layer: 50 },
+ ];
+ const layers = annotationDropLayers(
+ spans,
+ "moving",
+ { start: 20, end: 30 },
+ { row: 0, direction: "up" },
+ );
+ expect(layers.get("moving")).toBeGreaterThan(layers.get("right") ?? 0);
+ expect(layers.get("left")).toBeGreaterThan(layers.get("moving") ?? 0);
+ expect(
+ annotationDropLayers(spans, "moving", { start: 40, end: 50 }, { row: 0, direction: "up" })
+ .size,
+ ).toBe(0);
+ });
+
+ it("keeps one empty track for the add-element hint", () => {
+ expect(packRegionRows([]).rowCount).toBe(1);
+ expect(regionLaneHeight(1)).toBe(24);
+ });
+
+ it("matches compositing order for legacy annotations sharing a layer", () => {
+ const tracks = packRegionRows([
+ { id: "back", start: 0, end: 67, layer: 1, stackOrder: 0 },
+ { id: "front", start: 35, end: 40, layer: 1, stackOrder: 1 },
+ { id: "later", start: 45, end: 50, layer: 1, stackOrder: 2 },
+ ]);
+ expect(tracks.rowOf.get("front")).toBe(0);
+ expect(tracks.rowOf.get("back")).toBe(1);
+ expect(tracks.rowOf.get("later")).toBe(0);
+ });
+});
diff --git a/src/lib/ai-edition/timeline/regionTracks.ts b/src/lib/ai-edition/timeline/regionTracks.ts
new file mode 100644
index 000000000..fa479a14c
--- /dev/null
+++ b/src/lib/ai-edition/timeline/regionTracks.ts
@@ -0,0 +1,96 @@
+import { coalesceRegionsForRuler } from "./timelineMap";
+
+// Track geometry shared by the timeline and its automatic height adjustment.
+export const REGION_ROW_HEIGHT_PX = 22;
+export const REGION_ROW_GAP_PX = 5;
+export const REGION_LANE_PAD_PX = 1;
+export const REGION_ROW_STEP_PX = REGION_ROW_HEIGHT_PX + REGION_ROW_GAP_PX;
+
+export interface TrackSpan {
+ id: string;
+ start: number;
+ end: number;
+ /** Higher annotation layers appear above lower ones, as in the compositor. */
+ layer?: number;
+ /** Stable compositing order for annotations that share a saved zIndex. */
+ stackOrder?: number;
+}
+
+const frontFirst = (a: TrackSpan, b: TrackSpan) =>
+ (b.layer ?? 0) - (a.layer ?? 0) || (b.stackOrder ?? 0) - (a.stackOrder ?? 0);
+const overlaps = (a: TrackSpan, b: { start: number; end: number }) =>
+ a.start < b.end && a.end > b.start;
+
+/** Put each annotation on the highest free row below every higher annotation it
+ * overlaps. Nonoverlapping layers share rows; zoom and resize handles never add rows. */
+export function packRegionRows(spans: readonly TrackSpan[]) {
+ const rowOf = new Map<string, number>();
+ const placed: TrackSpan[] = [];
+ let rowCount = 1;
+ for (const span of [...spans].sort(frontFirst)) {
+ let row = 0;
+ for (const higher of placed) {
+ if (overlaps(higher, span)) row = Math.max(row, (rowOf.get(higher.id) ?? 0) + 1);
+ }
+ rowOf.set(span.id, row);
+ rowCount = Math.max(rowCount, row + 1);
+ placed.push(span);
+ }
+ return { rowOf, rowCount };
+}
+
+/** Shared pill geometry and saved tie order, used for both drawing and panel height. */
+export function annotationTrackPills<
+ T extends { id: string; startMs: number; endMs: number; zIndex?: number },
+>(regions: T[]) {
+ const order = new Map(regions.map((region, index) => [region.id, index]));
+ return coalesceRegionsForRuler(regions, 0.001, { annotations: true }).map((pill) => ({
+ ...pill,
+ id: pill.ids[0],
+ layer: pill.member.zIndex,
+ stackOrder: Math.max(...pill.ids.map((id) => order.get(id) ?? 0)),
+ }));
+}
+
+export interface AnnotationTrackDrop {
+ row: number;
+ direction: "up" | "down";
+}
+
+/** Reorder relative to annotations overlapping the DROP span, on the requested row.
+ * Direction resolves drops onto occupied rows, including equal saved layers. Other
+ * annotations keep their relative compositing order. The same plan drives the preview
+ * and the single persisted span/order change. */
+export function annotationDropLayers(
+ spans: readonly TrackSpan[],
+ id: string,
+ desired: { start: number; end: number },
+ drop: AnnotationTrackDrop,
+ rows = packRegionRows(spans),
+) {
+ const ordered = [...spans].sort(frontFirst);
+ const moved = ordered.find((p) => p.id === id);
+ const layers = new Map<string, number>();
+ if (!moved) return layers;
+ const others = ordered.filter((p) => p !== moved);
+ const neighbours = others.filter((p) => overlaps(p, desired));
+ if (neighbours.length === 0) return layers;
+ const below = neighbours.find((p) => {
+ const row = rows.rowOf.get(p.id) ?? 0;
+ return drop.direction === "up" ? row >= drop.row : row > drop.row;
+ });
+ const insertAt = below
+ ? others.indexOf(below)
+ : others.indexOf(neighbours[neighbours.length - 1]) + 1;
+ others.splice(insertAt, 0, moved);
+ // Materialize tie order as unique integer layers before rebuilding fragments.
+ others.forEach((p, index) => layers.set(p.id, others.length - index - 1));
+ return layers;
+}
+
+/** Height of an annotation lane, including its top/bottom inset. */
+export function regionLaneHeight(rowCount: number) {
+ return (
+ rowCount * REGION_ROW_HEIGHT_PX + (rowCount - 1) * REGION_ROW_GAP_PX + REGION_LANE_PAD_PX * 2
+ );
+}
diff --git a/src/lib/ai-edition/timeline/timelineMap.test.ts b/src/lib/ai-edition/timeline/timelineMap.test.ts
index dbaebf9db..6a7a904fe 100644
--- a/src/lib/ai-edition/timeline/timelineMap.test.ts
+++ b/src/lib/ai-edition/timeline/timelineMap.test.ts
@@ -12,6 +12,7 @@ import {
clampSpanAgainstNeighbours,
coalesceByIdentity,
coalesceRegionsForRuler,
+ dropPillById,
projectRegionsToSource,
regionIdentityKey,
replacePillSpan,
@@ -834,6 +835,88 @@ describe("pills wired to the universal rules", () => {
expect(wholePillOf(regions, "gone")).toBeNull();
});
+ it("keeps identical overlapping annotations separate for selection, edits and deletion", () => {
+ const regions = [
+ { id: "background", startMs: 0, endMs: 67000, type: "text", content: "Hi", zIndex: 1 },
+ { id: "second", startMs: 35000, endMs: 40000, type: "text", content: "Hi", zIndex: 1 },
+ ];
+ expect(
+ coalesceRegionsForRuler(regions, 0.001, { annotations: true }).map((p) => p.ids),
+ ).toEqual([["background"], ["second"]]);
+ expect(resolveRegionIds(regions, "second", 0.001, { annotations: true })).toEqual(["second"]);
+ expect(dropPillById(regions, "second", { annotations: true })).toEqual([regions[0]]);
+ const moved = replacePillSpan(
+ regions,
+ "second",
+ 5000,
+ 10000,
+ [],
+ ids(),
+ 0.001,
+ {},
+ { annotations: true },
+ );
+ expect(moved).toContainEqual(regions[0]);
+ expect(moved.find((r) => r.id === "second")).toMatchObject({ startMs: 5000, endMs: 10000 });
+ });
+
+ it("lets annotations overlap across layers and preserves a layer change across clip fragments", () => {
+ const regions = [
+ { id: "low", startMs: 0, endMs: 10000, type: "text", content: "Low", zIndex: 1 },
+ { id: "high", startMs: 30000, endMs: 40000, type: "text", content: "High", zIndex: 2 },
+ ];
+ const moved = replacePillSpan(
+ regions,
+ "high",
+ 5000,
+ 30000,
+ clips,
+ ids(),
+ 0.001,
+ { zIndex: 0 },
+ { annotations: true },
+ );
+ expect(moved[0]).toEqual(regions[0]);
+ const fragments = moved.slice(1);
+ expect(fragments.length).toBeGreaterThan(1);
+ expect(fragments.every((r) => r.zIndex === 0)).toBe(true);
+ const pill = coalesceRegionsForRuler(fragments, 0.001, { annotations: true })[0];
+ expect(pill).toMatchObject({ start: 5, end: 30 });
+ expect(resolveRegionIds(moved, "high", 0.001, { annotations: true })).toHaveLength(
+ fragments.length,
+ );
+ });
+
+ it("does not exchange ambiguous identical annotation fragments at a shared clip boundary", () => {
+ const payload = { type: "text", content: "Same", zIndex: 1 };
+ const regions = [
+ { ...payload, id: "back-a", startMs: 0, endMs: 25000, clipId: "a" },
+ { ...payload, id: "back-b", startMs: 25000, endMs: 50000, clipId: "b" },
+ { ...payload, id: "front-a", startMs: 20000, endMs: 25000, clipId: "a" },
+ { ...payload, id: "front-b", startMs: 25000, endMs: 30000, clipId: "b" },
+ ];
+ expect(coalesceRegionsForRuler(regions, 0.001, { annotations: true })).toHaveLength(4);
+ expect(resolveRegionIds(regions, "front-a", 0.001, { annotations: true })).toEqual(["front-a"]);
+ expect(dropPillById(regions, "front-a", { annotations: true })).toEqual(
+ regions.filter((r) => r.id !== "front-a"),
+ );
+ });
+
+ it("keeps ordinary region merge and repulsion rules when they carry a zIndex", () => {
+ const regions = [
+ { id: "a", startMs: 0, endMs: 1000, zIndex: 1, speed: 2 },
+ { id: "b", startMs: 500, endMs: 1500, zIndex: 1, speed: 2 },
+ ];
+ expect(coalesceRegionsForRuler(regions)).toHaveLength(1);
+ const separate = [
+ { ...regions[0], endMs: 1000 },
+ { ...regions[1], startMs: 2000, endMs: 3000 },
+ ];
+ expect(
+ replacePillSpan(separate, "a", 1500, 2500, [], ids()).find((r) => r.id === "a"),
+ ).toMatchObject({ startMs: 1000, endMs: 2000 });
+ });
+
it("keeps adjacent regions with different properties as separate pills", () => {
const pills = coalesceRegionsForRuler([
{ id: "a", startMs: 2000, endMs: 5000, speed: 3 },
diff --git a/src/lib/ai-edition/timeline/timelineMap.ts b/src/lib/ai-edition/timeline/timelineMap.ts
index 15c9907ba..be0c63ea2 100644
--- a/src/lib/ai-edition/timeline/timelineMap.ts
+++ b/src/lib/ai-edition/timeline/timelineMap.ts
@@ -131,7 +131,8 @@ export function anchoredToRawSpanSec(
// 2. REPEL — a moved or resized pill may not overlap another pill of its kind, of
// any identity. An edit clamps to the neighbour's edge; the neighbour
// never moves (no cascade). Once flush, a same-identity neighbour merges
-// with it on display (rule 1).
+// with it on display (rule 1). Annotations are composited layers:
+// they may overlap and each overlapping instance stays a separate pill.
//
// A kind with no properties (trim, full-camera) collapses to a constant identity, so
// its regions always merge — the long-standing trim behaviour, now *derived* from the
@@ -281,6 +282,11 @@ export interface RegionPill<T> extends MergedSpan {
member: T;
}
+export interface RegionPillOptions {
+ /** Annotations remain independent when identical objects overlap. */
+ annotations?: boolean;
+}
+
/**
* Group stored regions into the pills the ruler draws, via the universal merge rule.
* Works off the DERIVED `startMs`/`endMs`: they are always present (even before a region
@@ -290,6 +296,7 @@ export interface RegionPill<T> extends MergedSpan {
export function coalesceRegionsForRuler<T extends { id: string; startMs: number; endMs: number }>(
regions: T[],
epsilonSec = 0.001,
+ options: RegionPillOptions = {},
): RegionPill<T>[] {
const byId = new Map(regions.map((r) => [r.id, r]));
const spans = regions.map((r) => ({
@@ -298,7 +305,39 @@ export function coalesceRegionsForRuler<T extends { id: string; startMs: number;
end: r.endMs / 1000,
identity: regionIdentityKey(r as unknown as Record<string, unknown>),
}));
- return coalesceByIdentity(spans, epsilonSec).map((merged) => ({
+ // Identical overlapping annotations are still two independently selectable objects.
+ // Partition them before coalescing, while keeping touching clip fragments together.
+ const annotationsByIdentity = new Map<string, IdentifiedSpan[]>();
+ const ordinary: IdentifiedSpan[] = [];
+ for (const span of [...spans].sort((a, b) => a.start - b.start || a.end - b.end)) {
+ if (!options.annotations) {
+ ordinary.push(span);
+ continue;
+ }
+ const list = annotationsByIdentity.get(span.identity) ?? [];
+ list.push(span);
+ annotationsByIdentity.set(span.identity, list);
+ }
+ const annotationPills = [...annotationsByIdentity.values()].flatMap((list) => {
+ const runs: IdentifiedSpan[][] = [];
+ for (const span of list) {
+ // Old projects can have identical overlapping objects split at the same
+ // clip boundary. There is no provenance to pair their fragments safely.
+ // Only join an unambiguous continuation; otherwise keep each selectable.
+ const touching = (end: number) => end <= span.start && span.start - end <= epsilonSec;
+ const run = runs.find((r) => touching(r[r.length - 1].end));
+ const uniqueEnd = list.filter((s) => touching(s.end)).length === 1;
+ const uniqueStart =
+ list.filter((s) => Math.abs(s.start - span.start) <= epsilonSec).length === 1;
+ if (run && uniqueEnd && uniqueStart) run.push(span);
+ else runs.push([span]);
+ }
+ return runs.flatMap((run) => coalesceByIdentity(run, epsilonSec));
+ });
+ const mergedSpans = [...coalesceByIdentity(ordinary, epsilonSec), ...annotationPills].sort(
+ (a, b) => a.start - b.start,
+ );
+ return mergedSpans.map((merged) => ({
...merged,
member: byId.get(merged.ids[0]) as T,
}));
@@ -312,8 +351,9 @@ export function coalesceRegionsForRuler<T extends { id: string; startMs: number;
export function wholePillOf<T extends { id: string; startMs: number; endMs: number }>(
regions: T[],
id: string,
+ options: RegionPillOptions = {},
): T | null {
- const pill = coalesceRegionsForRuler(regions).find((p) => p.ids.includes(id));
+ const pill = coalesceRegionsForRuler(regions, 0.001, options).find((p) => p.ids.includes(id));
if (!pill) return null;
return {
...pill.member,
@@ -333,8 +373,13 @@ export function resolvePillIds<T extends { id: string; startMs: number; endMs: n
regions: T[],
id: string,
epsilonSec = 0.001,
+ options: RegionPillOptions = {},
): string[] {
- return coalesceRegionsForRuler(regions, epsilonSec).find((p) => p.ids.includes(id))?.ids ?? [id];
+ return (
+ coalesceRegionsForRuler(regions, epsilonSec, options).find((p) => p.ids.includes(id))?.ids ?? [
+ id,
+ ]
+ );
}
/**
@@ -346,7 +391,7 @@ export function resolvePillIds<T extends { id: string; startMs: number; endMs: n
* - a region that merely matches and touches it on the SAME clip. A region keeps at most one
* fragment per clip, so that is another region: the edit leaves it alone, the identities
* part, and the pill splits in two.
- * Same-clip regions that OVERLAP stay together: changing one alone would leave two regions of
+ * Same-clip non-annotation regions that OVERLAP stay together: changing one alone would leave two regions of
* different identities overlapping, which rule 2 forbids.
*
* Nothing records provenance, so two regions meeting exactly at a clip junction still edit as
@@ -354,13 +399,13 @@ export function resolvePillIds<T extends { id: string; startMs: number; endMs: n
*/
export function resolveRegionIds<
T extends { id: string; startMs: number; endMs: number; clipId?: string },
->(regions: T[], id: string, epsilonSec = 0.001): string[] {
+>(regions: T[], id: string, epsilonSec = 0.001, options: RegionPillOptions = {}): string[] {
const byId = new Map(regions.map((r) => [r.id, r]));
let run: string[] = [];
let runEndSec = Number.NEGATIVE_INFINITY;
let prev: T | undefined;
// Left to right; a same-clip member that only touches ends the run (whole ms: no epsilon).
- for (const memberId of resolvePillIds(regions, id, epsilonSec)) {
+ for (const memberId of resolvePillIds(regions, id, epsilonSec, options)) {
const member = byId.get(memberId);
if (!member) continue;
const startSec = member.startMs / 1000;
@@ -386,8 +431,9 @@ export function resolveRegionIds<
export function dropPillById<T extends { id: string; startMs: number; endMs: number }>(
regions: T[],
id: string,
+ options: RegionPillOptions = {},
): T[] {
- const under = new Set(resolvePillIds(regions, id));
+ const under = new Set(resolvePillIds(regions, id, 0.001, options));
return regions.filter((r) => !under.has(r.id));
}
@@ -395,18 +441,20 @@ export function dropPillById<T extends { id: string; startMs: number; endMs: num
export function dropPillsByIds<T extends { id: string; startMs: number; endMs: number }>(
regions: T[],
ids: Iterable<string>,
+ options: RegionPillOptions = {},
): T[] {
let out = regions;
- for (const id of ids) out = dropPillById(out, id);
+ for (const id of ids) out = dropPillById(out, id, options);
return out;
}
/**
- * Move/resize the pill containing `id`, obeying both rules: the requested span is first
+ * Move/resize the pill containing `id`. Annotations allow overlaps on separate tracks;
+ * other modifiers obey both rules: the requested span is first
* CLAMPED against every other pill (rule 2 — they act as walls and never
* move), on the ruler and from where the pill sits now, so a moved pill keeps its length;
* then the pill's regions are replaced by fragments re-anchored to the clamped
- * span, carrying the pill's payload. Crossing a clip boundary re-splits into one fragment
+ * span, carrying the pill's payload and any simultaneous layer change. Crossing a clip boundary re-splits into one fragment
* per clip; coming back inside one clip collapses again; and neighbours of the same
* identity simply merge on display (rule 1). No provenance is consulted anywhere.
*
@@ -421,16 +469,21 @@ export function replacePillSpan<T extends { id: string; startMs: number; endMs:
clips: AxcutClip[],
makeId: () => string,
epsilonSec = 0.001,
+ payloadPatch: Partial<T> = {},
+ options: RegionPillOptions = {},
): T[] {
- const pills = coalesceRegionsForRuler(regions, epsilonSec);
+ const pills = coalesceRegionsForRuler(regions, epsilonSec, options);
const pill = pills.find((p) => p.ids.includes(id));
if (!pill) return regions;
- const clamped = clampSpanAgainstNeighbours(
- { start: Math.min(startMs, endMs) / 1000, end: Math.max(startMs, endMs) / 1000 },
- pills.filter((p) => p !== pill),
- pill,
- );
+ const desired = { start: Math.min(startMs, endMs) / 1000, end: Math.max(startMs, endMs) / 1000 };
+ const clamped = options.annotations
+ ? desired
+ : clampSpanAgainstNeighbours(
+ desired,
+ pills.filter((p) => p !== pill),
+ pill,
+ );
const under = new Set(pill.ids);
const { startMs: _s, endMs: _e, ...payload } = pill.member;
@@ -438,6 +491,7 @@ export function replacePillSpan<T extends { id: string; startMs: number; endMs:
[
{
...payload,
+ ...payloadPatch,
id,
startMs: Math.round(clamped.start * 1000),
endMs: Math.round(clamped.end * 1000),
@@ -446,6 +500,10 @@ export function replacePillSpan<T extends { id: string; startMs: number; endMs:
clips,
makeId,
) as unknown as T[];
+ // Preserve array order: equal-zIndex annotations composite in their saved order.
+ if (options.annotations) {
+ return regions.flatMap((r) => (r.id === pill.ids[0] ? rebuilt : under.has(r.id) ? [] : [r]));
+ }
return [...regions.filter((r) => !under.has(r.id)), ...rebuilt];
}
diff --git a/technical-documentation/architecture/timeline-model.md b/technical-documentation/architecture/timeline-model.md
index 1bcd37980..369707734 100644
--- a/technical-documentation/architecture/timeline-model.md
+++ b/technical-documentation/architecture/timeline-model.md
@@ -70,13 +70,13 @@ Every public export of
| `resolvePillIds` (`:314`) | Region id → every region id under its pill (recomputed, not stored) | id → ids |
| `resolveRegionIds` (`:337`) | Region id → the ids of the one region it belongs to: its fragments across clip junctions, not a look-alike that touches it on the same clip (see below) | id → ids |
| `dropPillById` / `dropPillsByIds` (`:368` / `:377`) | Delete every region under a pill (resolved from the merge rule) | regions → regions |
-| `replacePillSpan` (`:398`) | Move/resize a pill: clamp against every other pill, then re-anchor to the clamped span, keeping the id of the member it was called with | pill + clip layout → re-anchored fragments |
+| `replacePillSpan` | Move/resize a pill: clamp non-annotation modifiers against neighbours, then re-anchor, keeping the selected id. Annotations may overlap and can carry a layer change in the same write. | pill + clip layout → re-anchored fragments |
| `segmentRawSpanSec` (`:481`) | One kept playback segment → its RAW-virtual extent | segment → RAW span |
| `projectRegionsToSource` (`:641`) | Region array → source-ms entries with `clipIndex` for native (anchored path uses anchor; unanchored path falls back to RAW mapping through each segment's own raw extent — never drops an un-anchorable region onto an unrelated clip). A region wholly under a trim is emitted once, marked `underTrim`, addressed by the segment the cut interrupts. A region a cut splits marks each piece's cut edge `continuesBefore` / `continuesAfter`, so Full Camera ramps only at its own edges and stays full across the cut | RAW/anchored → source + `clipIndex` |
| `resolveNativePosition` (`:759`) | RAW-virtual playhead → `{clip, clipIndex, sourceTimeSec}` for the active native decoder + paired camera (over a trimmed-out stretch it presents the removed frames themselves, borrowing the same segment index the modifiers under that cut borrow) | RAW-virtual → source + `clipIndex` |
-The two **universal region rules** every region kind obeys are expressed once in this
-file rather than re-derived per kind:
+The shared region rules are expressed once in this file rather than re-derived per kind.
+Annotations have the layer exception described below:
1. **Merge** (`coalesceByIdentity`) — two regions of the same kind with the same
identity that touch are one pill. How they became adjacent (authored side by side,
@@ -88,7 +88,32 @@ file rather than re-derived per kind:
before the edit, so a moved region keeps its length and stops flush against the
neighbour on the side it came from. A same-identity neighbour is a wall too: let
through, it stayed stored under the moved region and an edit of either half reached
- both (#1133). Stopped flush, the two merge on display (rule 1).
+ both (#1133). Stopped flush, the two merge on display (rule 1). Annotations may
+ overlap: their `zIndex` controls compositing, and the timeline displays separate tracks.
+
+### Annotation tracks
+
+![Overlapping annotations on separate tracks](../assets/annotation-tracks.png)
+
+`regionTracks.ts` packs only annotations into visible rows. Each annotation takes the
+highest free row below every higher annotation it overlaps. Nonoverlapping annotations
+share a row regardless of their saved `zIndex`; zoom and compact resize handles do not
+change the row count. Equal layers follow the document's compositing order. The timeline
+reports its exact rendered row count (including a drag preview) to the shell for panel sizing.
+Identical overlapping annotations remain separate pills, so selecting, editing, copying or
+deleting one cannot reach the other. Unambiguous touching fragments still coalesce across
+clip boundaries. If legacy objects share both an identity and a boundary, their fragments
+remain separately selectable instead of guessing their pairing. These annotation rules
+are explicit options to the pill operations, never inferred from the presence of `zIndex`.
+
+Adding an annotation, from either the editor or MCP, uses the highest saved layer plus one.
+Dragging vertically places it above or below the annotations it overlaps at the drop time,
+using the target row and drag direction, even when the saved layers are equal. The live
+preview and persisted change use the same ordering plan. Horizontal moves and resizes keep
+the existing compositing order. Span and order changes persist in one history entry through
+save/load, preview and export. Speed, trim, zoom, camera and effect regions keep their
+single lanes and existing repulsion rules. The panel grows for annotation rows up to its
+height limit; additional rows remain vertically scrollable.
A kind with no properties (trim, full-camera) collapses to a constant identity, so its
regions always merge — the long-standing trim behaviour, now derived from the general
@@ -102,8 +127,8 @@ pointer; editing it changes every fragment of that region across clip junctions,
region drawn over a cut stays one pill, but leaves alone a region that merely matches it
and touches it on the same clip. A region keeps at most one fragment per clip, so a
same-clip neighbour is necessarily another region: the identities part and the pill
-splits. Same-clip regions that overlap still edit together, since changing one alone would
-break rule 2. Delete, move and resize keep acting on the whole pill; a move rebuilds it as
+splits. Overlapping non-annotation regions of equal identity still edit together, since
+changing one alone would break rule 2. Delete, move and resize keep acting on the whole pill; a move rebuilds it as
one region that keeps the id it was grabbed by, so the selection survives. Without provenance,
two regions meeting exactly at a clip junction cannot be told apart from one region's two
fragments, so they edit as one.
@@ -258,9 +283,9 @@ the contract a reviewer can grade against. Each is asserted in
- **Repel never cascades.** A neighbour acts as a wall — the edited span stops at its
edge and the neighbour never moves. (`clampSpanAgainstNeighbours` "stops at a
neighbour on the right" / "left".)
-- **Repel ignores identity.** An identical region dragged into another stops flush
+- **Repel ignores identity for non-annotation modifiers.** An identical region dragged into another stops flush
instead of overlapping it; the pair then shows as one pill and an edit of either half
- splits it. (`replacePillSpan` "stops a speed / zoom / annotation / full-camera region
+ splits it. (`replacePillSpan` "stops a speed / zoom / full-camera region
flush against an identical one instead of overlapping it (#1133)".)
- **Repel never shortens a move.** A region dragged into a neighbour
keeps its length and stops against it on the side it came from, clip boundary or not;
@@ -322,4 +347,4 @@ in the same commit, or the project round-trips into an inconsistent state:
is rewritten by an older code path before the v5 preprocess runs may briefly carry
the un-anchored form downstream. The single parse-time entry point keeps the
surface small but does not make it impossible; the regression is caught by
- `migrate.test.ts`.
\ No newline at end of file
+ `migrate.test.ts`.
diff --git a/technical-documentation/assets/annotation-tracks.png b/technical-documentation/assets/annotation-tracks.png
new file mode 100644
index 000000000..f9333526f
Binary files /dev/null and b/technical-documentation/assets/annotation-tracks.png differ
diff --git a/tests/e2e/v4-shell.spec.ts b/tests/e2e/v4-shell.spec.ts
index 9b0604093..4bd77b42d 100644
--- a/tests/e2e/v4-shell.spec.ts
+++ b/tests/e2e/v4-shell.spec.ts
@@ -75,7 +75,7 @@ function makeDoc() {
speedRanges: [],
captionRanges: [],
},
- annotations: [],
+ annotations: [] as Array<Record<string, unknown>>,
zoomRanges: [] as ZoomFixture[],
legacyEditor: null,
agent: { pendingQuestions: [], suggestions: [], lastAppliedOperations: [] },
@@ -90,6 +90,10 @@ function makeDoc() {
// and `ZOOM_DEPTH_SCALES` renders it as the "1.80×" the pill is addressed by below.
function makeZoomDoc(): ReturnType<typeof makeDoc> {
const doc = makeDoc();
+ // The keyboard test exercises all four presets. A 1080p source now hides
+ // the deepest one through zoomScaleLimit's source-magnification guard.
+ doc.assets[0].video.width = 3840;
+ doc.assets[0].video.height = 2160;
doc.zoomRanges = [
{
id: "zoom_e2e",
@@ -141,7 +145,7 @@ function makeTwoClipDoc(): ReturnType<typeof makeDoc> {
// it is not (a title next to a visible label would repeat it), so a pill is found by either.
function zoomPill(page: Page, label: string): Locator {
return page.locator(
- `[class*="lanePill"][title="${label}"], [class*="lanePill"]:has-text("${label}")`,
+ `[data-track-kind="zoom"] [data-region-id][title="${label}"], [data-track-kind="zoom"] [data-region-id]:has-text("${label}")`,
);
}
@@ -166,6 +170,103 @@ async function seedAndOpen(page: Page, doc: ReturnType<typeof makeDoc> = makeDoc
}
test.describe("v4 editor shell", () => {
+ test("overlapping annotations stay reachable through dragging, layer changes and undo", async ({
+ page,
+ }, testInfo) => {
+ const doc = makeDoc();
+ doc.project.title = "Annotation tracks";
+ doc.timeline.clips[0].timelineEndSec = 67.2;
+ doc.timeline.clips[0].sourceEndSec = 67.2;
+ doc.annotations = [
+ { id: "background", startMs: 0, endMs: 67200, content: "Main annotation", zIndex: 1 },
+ { id: "second", startMs: 34000, endMs: 42000, content: "Second annotation", zIndex: 1 },
+ { id: "third", startMs: 36000, endMs: 47000, content: "Third annotation", zIndex: 1 },
+ ].map((a) => ({
+ ...a,
+ type: "text",
+ position: { x: 30, y: 40 },
+ size: { width: 30, height: 20 },
+ style: { color: "#ffffff", fontSize: 32, fontFamily: "Inter" },
+ }));
+ await page.setViewportSize({ width: 1440, height: 1000 });
+ await seedAndOpen(page, doc);
+ const pills = page.locator('[data-track-kind="annotation"] [data-region-id]');
+ await expect(pills).toHaveCount(3);
+ const positions = await pills.evaluateAll((els) =>
+ els.map((el) => el.getBoundingClientRect().y),
+ );
+ expect(new Set(positions).size).toBe(3);
+ for (const id of ["background", "second", "third"]) {
+ const pill = page.locator(`[data-region-id="${id}"]`);
+ await pill.click();
+ await expect(pill).toHaveClass(/lanePillSel/);
+ }
+ const stored = () =>
+ page.evaluate(() => {
+ const state = JSON.parse(localStorage.getItem("browser-shim-projects-v2") ?? "{}");
+ return state.documents.proj_e2e.annotations as Array<{
+ id: string;
+ startMs: number;
+ zIndex: number;
+ }>;
+ });
+ const second = page.locator('[data-region-id="second"]');
+ const box = await second.boundingBox();
+ if (!box) throw new Error("second annotation has no bounding box");
+ await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2);
+ await page.mouse.down();
+ await page.mouse.move(box.x + box.width / 2 + 45, box.y + box.height / 2 + 54, { steps: 10 });
+ await page.mouse.up();
+ await expect.poll(async () => (await stored()).find((a) => a.id === "second")?.zIndex).toBe(0);
+ const moved = (await stored()).find((a) => a.id === "second");
+ expect(moved?.startMs).toBeGreaterThan(34000);
+ await second.click();
+ await expect(second).toHaveClass(/lanePillSel/);
+ await page.getByRole("button", { name: "Undo", exact: true }).click();
+ await expect.poll(async () => (await stored()).find((a) => a.id === "second")?.zIndex).toBe(1);
+ await page.getByRole("button", { name: "Redo", exact: true }).click();
+ await expect.poll(async () => (await stored()).find((a) => a.id === "second")?.zIndex).toBe(0);
+ await expect(pills).toHaveCount(3);
+ await page
+ .locator('[data-track-kind="annotation"]')
+ .screenshot({ path: testInfo.outputPath("annotation-tracks.png") });
+ });
+
+ test("ten sequential annotation layers share one row at every timeline zoom", async ({
+ page,
+ }) => {
+ const doc = makeDoc();
+ doc.annotations = Array.from({ length: 10 }, (_, i) => ({
+ id: `sequential-${i}`,
+ startMs: i * 1000,
+ endMs: (i + 1) * 1000,
+ zIndex: i + 1,
+ type: "text",
+ content: `Annotation ${i}`,
+ position: { x: 30, y: 40 },
+ size: { width: 30, height: 20 },
+ style: { color: "#ffffff", fontSize: 32, fontFamily: "Inter" },
+ }));
+ await seedAndOpen(page, doc);
+ const lane = page.locator('[data-track-kind="annotation"]');
+ await expect(lane.locator("[data-region-id]")).toHaveCount(10);
+ await expect(lane).toHaveCSS("height", "24px");
+ await expect(lane).not.toHaveAttribute("title");
+ const tracks = page.locator('[class*="tlTracks"]');
+ await tracks.hover();
+ await page.keyboard.down("Control");
+ await page.mouse.wheel(0, -600);
+ await page.keyboard.up("Control");
+ await expect(lane).toHaveCSS("height", "24px");
+ expect(
+ new Set(
+ await lane
+ .locator("[data-region-id]")
+ .evaluateAll((els) => els.map((el) => el.getBoundingClientRect().y)),
+ ).size,
+ ).toBe(1);
+ });
+
test("media stage shows each asset's file size, em-dash when unknown", async ({ page }) => {
await seedAndOpen(page);
await page.getByRole("tab", { name: "Media" }).click();