Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.
TypeScript cross-platformelectronffmpegopen-sourceproduct-demorustscreen-capturescreen-recorderscreen-recordingscreen-studioscreencastspeech-to-texttypescriptvideo-editingvideo-editorwaylandwgpuwhisper
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.tsindex 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.tsindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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({<divkey={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 keyis the live binding, formatted like the toolbar tooltip's chip, so arebind 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 keystrokethat `addCameraFullscreen` now refuses (#353). The toolbar button isalready disabled; this keeps the lane from contradicting it. */}diff --git a/src/i18n/locales/ar/timeline.json b/src/i18n/locales/ar/timeline.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.tsindex 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: strizoomRanges: 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 whendiff --git a/src/lib/ai-edition/store/useTimeline.test.ts b/src/lib/ai-edition/store/useTimeline.test.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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: nregions: 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: numexport 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.mdindex 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 sameidentity 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 theneighbour on the side it came from. A same-identity neighbour is a wall too: letthrough, 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++++`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 itsregions 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 itand touches it on the same clip. A region keeps at most one fragment per clip, so asame-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 asone 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 twofragments, 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 itsedge and the neighbour never moves. (`clampSpanAgainstNeighbours` "stops at aneighbour 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 flushinstead 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 regionflush against an identical one instead of overlapping it (#1133)".)- **Repel never shortens a move.** A region dragged into a neighbourkeeps 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 carrythe un-anchored form downstream. The single parse-time entry point keeps thesurface 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.pngnew file mode 100644index 000000000..f9333526fBinary files /dev/null and b/technical-documentation/assets/annotation-tracks.png differdiff --git a/tests/e2e/v4-shell.spec.ts b/tests/e2e/v4-shell.spec.tsindex 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();