Let composition items overlap and show where their video lies (#417)

Trying the tab turned up six things to fix. Items of a track could
not overlap, so a drag stalled as soon as the pointer reached another
item. An item's ends gave no hint they could be dragged, a trimmed
video showed nowhere, clip names were hard to read and vanished when
picked, and the track menu did not match the song tab.

- Items of a track may overlap and nothing is cut or pushed aside.
  The later one lies in front, in the picture and on the timeline.
  The overlap is shaded and a line marks the covered end.
- Edges win over bodies when hit, so the covered end of the lower
  item can still be dragged. Hovering an edge lights it up and shows
  the ew-resize cursor, as in the song tab.
- A clip in the overlap plays on both items. Clips themselves still
  do not overlap; a moved clip now runs up to its neighbour instead
  of stopping short.
- Fit to media and a new video no longer cap the length at the next
  item, which only made sense while overlaps were forbidden.
- The left edge can be trimmed past the start of the video. The
  offset goes negative and the sprite shows the first picture until
  the video begins.
- Video marks: a corner triangle where the item cuts into its video,
  a line with a triangle like the song loop where the video starts or
  ends inside the item. Edges snap to the video's ends within 6 px.
- Clip names sit in their own layer above the bars, in text colour.
- The track menu matches the song tab: add above or below, move up or
  down, delete. It opens on the head and on an empty spot of the
  track. The Remove track button left the inspector.

Tests:
- Unit composition and composition-edit: 67 green, several new or
  rewritten. Bending three spots in the rules turned their tests red.
- e2e 69: ALL PASSED, 12 checks. 69b and 69c now drop the second item
  over the first and drag the covered end past it. Without edges
  winning the hit, 69c fails with hover: null.
- Gate on melektaus-atx: CHECK EXIT 0, 302 files, 4672 tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

tests/core/composition-edit.test.ts

@@ -1,7 +1,8 @@
 /**
- * Editing a composition (#417): drops land in the gap they fall into, nothing of a track overlaps,
- * the edges of an item keep to its neighbours, and an item that follows its media is fitted to it
- * again – in the same undo step – when an override gives it another video.
+ * Editing a composition (#417): items of a track may overlap, clips may not – a dropped clip lands in
+ * the gap it falls into –, the edges of an item go where they are dragged, its video's edges marked
+ * and snapped to, and an item that follows its media is fitted to it again – in the same undo step –
+ * when an override gives it another video.
  */
 import { describe, expect, it } from 'vitest';
 import { CreateAssetCommand, CreateVideoCommand } from '../../src/core/commands/assetCommands';
@@ -15,13 +16,19 @@ import {
 import { ClearOverrideCommand, SetOverrideCommand } from '../../src/core/commands/sceneObjectCommands';
 import type { CompositionClip, CompositionItem } from '../../src/core/model/Asset';
 import {
+  clampedMove,
   droppedLength,
   droppedSpan,
+  type ItemMedia,
+  mediaEdges,
+  mediaMarks,
   movedClips,
   movedItems,
   resizedItem,
+  snappedToMedia,
   trimmedItem,
 } from '../../src/core/model/compositionEdit';
+import { hitAt, overlaps, uncoveredEnd } from '../../src/editor/composition/compositionView';
 import { placementRejection } from '../../src/core/model/placement';
 import { findAsset, findAssetOf } from '../../src/core/model/Project';
 import { makeProject } from '../helpers';
@@ -77,11 +84,17 @@ describe('moving', () => {
     expect(movedItems(items, new Set(['b']), tracks, 0, 1)?.find((i) => i.id === 'b')?.track).toBe('t2');
   });
 
-  it('refuses a move onto another item, before 0 or off the tracks', () => {
-    expect(movedItems(items, new Set(['a']), tracks, 50, 0)).toBeNull();
+  it('lets an item onto another, and refuses one before 0 or off the tracks', () => {
+    expect(movedItems(items, new Set(['a']), tracks, 50, 0)?.map((i) => i.start)).toEqual([50, 100, 0]);
+    expect(movedItems(items, new Set(['a']), tracks, 0, 1)?.map((i) => i.track)).toEqual(['t2', 't1', 't2']);
     expect(movedItems(items, new Set(['b']), tracks, -150, 0)).toBeNull();
     expect(movedItems(items, new Set(['c']), tracks, 0, 1)).toBeNull();
-    expect(movedItems(items, new Set(['a']), tracks, 0, 1)).toBeNull();
+  });
+
+  it('holds a move at frame 0 and the tracks there are, as far as the pointer goes', () => {
+    expect(clampedMove(items, new Set(['b']), tracks, -150, 0)).toEqual({ frames: -100, tracks: 0 });
+    expect(clampedMove(items, new Set(['a', 'c']), tracks, 20, 1)).toEqual({ frames: 20, tracks: 0 });
+    expect(clampedMove(items, new Set(['a']), tracks, 0, -3)).toEqual({ frames: 0, tracks: 0 });
   });
 
   it('lets a picked item go where another picked one was', () => {
@@ -101,38 +114,82 @@ describe('moving', () => {
 });
 
 describe('the edges of an item', () => {
-  const items = [
-    item('a', 't1', 0, 60),
-    item('b', 't1', 100, 60, { fitMedia: true, offset: 1 }),
-    item('c', 't1', 200, 10),
-  ];
+  const b = item('b', 't1', 100, 60, { fitMedia: true, offset: 1 });
 
-  it('a dragged end stops where the next item begins, and the length is the item’s own from then on', () => {
-    const b = items[1]!;
-    expect(resizedItem(items, b, 500)).toEqual({ id: 'b', track: 't1', start: 100, length: 100, offset: 1 });
-    expect(resizedItem(items, b, 0).length).toBe(1);
+  it('a dragged end goes where it is let go, at least a frame, and the length is the item’s own from then on', () => {
+    expect(resizedItem(b, 500)).toEqual({ id: 'b', track: 't1', start: 100, length: 500, offset: 1 });
+    expect(resizedItem(b, 0).length).toBe(1);
   });
 
-  it('a dragged start stops at the item before, and moves where the video begins with it', () => {
-    const b = items[1]!;
-    const trimmed = trimmedItem(items, b, 130, 60, true);
+  it('a dragged start moves where the video begins with it', () => {
+    const trimmed = trimmedItem(b, 130, 60, true);
     expect([trimmed.start, trimmed.length, trimmed.offset, trimmed.fitMedia]).toEqual([
       130,
       30,
       1.5,
       undefined,
     ]);
-    expect(trimmedItem(items, b, 70, 60, false).start).toBe(70);
-    expect(trimmedItem(items, b, 10, 60, false).start).toBe(60);
+    expect(trimmedItem(b, 10, 60, false)).toMatchObject({ start: 10, length: 150, offset: 1 });
+    expect(trimmedItem(b, 500, 60, false).start).toBe(159);
   });
 
-  it('with a video, a dragged start stops at the video’s beginning', () => {
-    const b = items[1]!;
-    const trimmed = trimmedItem(items, b, 70, 60, true);
-    expect([trimmed.start, trimmed.offset]).toEqual([70, 0.5]);
-    // Alone on its track, one second into its video: it can reach back one second, no further.
-    expect(trimmedItem([b], b, 0, 60, true)).toMatchObject({ start: 40, length: 120, offset: 0 });
-    expect(trimmedItem([b], b, 0, 60, false)).toMatchObject({ start: 0, length: 160, offset: 1 });
+  it('with a video, a dragged start goes on before the video’s beginning, the offset below 0', () => {
+    // One second into its video: back a second the video begins with the item, back 1.5 s half a second after it.
+    expect(trimmedItem(b, 40, 60, true)).toMatchObject({ start: 40, length: 120, offset: 0 });
+    expect(trimmedItem(b, 10, 60, true)).toMatchObject({ start: 10, length: 150, offset: -0.5 });
+    expect(trimmedItem(b, -20, 60, true).start).toBe(0);
+  });
+});
+
+describe('the video of an item on the timeline', () => {
+  // A 2 s video at 60 fps that began at frame 40: the item from 100 is one second in.
+  const once: ItemMedia = { begins: 40, length: 120, loops: false };
+  const round: ItemMedia = { ...once, loops: true };
+
+  it('has its edges where it begins and each pass ends, round only when it loops', () => {
+    expect(mediaEdges(once, 0, 1000)).toEqual([40, 160]);
+    expect(mediaEdges(round, 100, 500)).toEqual([160, 280, 400]);
+    expect(mediaEdges(round, 0, 30)).toEqual([]);
+  });
+
+  it('marks an end cutting into the video, and a line where the item reaches past it', () => {
+    expect(mediaMarks(item('i', 't', 100, 30), once)).toEqual({ seams: [], cutStart: true, cutEnd: true });
+    expect(mediaMarks(item('i', 't', 40, 120), once)).toEqual({ seams: [], cutStart: false, cutEnd: false });
+    expect(mediaMarks(item('i', 't', 20, 200), once)).toEqual({
+      seams: [40, 160],
+      cutStart: false,
+      cutEnd: false,
+    });
+    expect(mediaMarks(item('i', 't', 100, 200), round).seams).toEqual([160, 280]);
+  });
+
+  it('pulls a dragged edge onto the video’s within reach, and leaves it alone further off', () => {
+    expect(snappedToMedia(157, once, 4)).toBe(160);
+    expect(snappedToMedia(150, once, 4)).toBe(150);
+    expect(snappedToMedia(42, null, 4)).toBe(42);
+  });
+});
+
+describe('overlapping items on the timeline', () => {
+  const view = { panX: 0, pxPerTick: 2, panY: 0, trackHeight: 48 };
+  const tracks = [{ id: 't1', name: 'Track 1' }];
+  // `late` covers `early` from frame 50 on; on screen the overlap runs from x 100 to 120.
+  const early = item('early', 't1', 0, 60);
+  const late = item('late', 't1', 50, 60);
+  const hit = (x: number) => hitAt(view, tracks, [late, early], [], () => 0, { x, y: 20 });
+
+  it('takes the end of the one covered, the body of the one on top', () => {
+    expect(hit(119)).toEqual({ kind: 'item', id: 'early', part: 'end' });
+    expect(hit(110)).toEqual({ kind: 'item', id: 'late', part: 'body' });
+    expect(hit(101)).toEqual({ kind: 'item', id: 'late', part: 'start' });
+    expect(hit(40)).toEqual({ kind: 'item', id: 'early', part: 'body' });
+  });
+
+  it('knows where they overlap and how much of the earlier one is seen', () => {
+    expect(overlaps([late, early])).toEqual([{ track: 't1', start: 50, end: 60 }]);
+    expect(overlaps([early, item('other', 't2', 0, 60)])).toEqual([]);
+    expect(uncoveredEnd([late, early], early)).toBe(50);
+    expect(uncoveredEnd([late, early], late)).toBe(110);
   });
 });
 
@@ -240,13 +297,13 @@ describe('an item that follows its media (fitMedia)', () => {
     expect(cut.comp().items[0]!.length).toBe(180);
   });
 
-  it('stops where the next item of its track begins, which stays where it is', () => {
+  it('runs on over the next item of its track, which stays where it is', () => {
     const cut = makeCut();
     const id = cut.add(0, 180);
     const next = cut.add(240, 60);
     wear(cut, id, cut.videoId);
     expect(cut.comp().items.map((i) => [i.id, i.start, i.length])).toEqual([
-      [id, 0, 240],
+      [id, 0, 300],
       [next, 240, 60],
     ]);
   });
@@ -254,7 +311,7 @@ describe('an item that follows its media (fitMedia)', () => {
   it('is left alone once its length is its own', () => {
     const cut = makeCut();
     const id = cut.add(0, 180);
-    const items = cut.comp().items.map((i) => resizedItem(cut.comp().items, i, 90));
+    const items = cut.comp().items.map((i) => resizedItem(i, 90));
     cut.stack.execute(new SetCompositionCommand(cut.compId, { items }));
     wear(cut, id, cut.videoId);
     expect(cut.comp().items[0]!.length).toBe(90);

tests/core/composition.test.ts

@@ -358,6 +358,29 @@ describe('animation clips', () => {
     expect(x(42, second)).toBe(70);
   });
 
+  it('over two items of a track that overlap, play on both – the later one in front', () => {
+    const cut = makeCut();
+    const track = firstTrack(cut);
+    const early = cut.item(track, cut.spriteId, 0, 60);
+    const late = cut.item(track, cut.spriteId, 30, 60);
+    cut.clip(
+      track,
+      cut.animation(cut.spriteId, [
+        [
+          'x',
+          [
+            [0, 0],
+            [9, 90],
+          ],
+        ],
+      ]),
+      0,
+    );
+    expect(liveIds(cut, 42)).toEqual([early, late]);
+    const holder = compositionHolder(cut.project, cut.comp(), 42);
+    expect([early, late].map((id) => holder.objects.find((o) => o.id === id)!.position.x)).toEqual([70, 70]);
+  });
+
   it('add a relative row to the value the item has', () => {
     const cut = makeCut();
     const item = cut.item(firstTrack(cut), cut.spriteId, 0, 120);
@@ -610,7 +633,7 @@ describe('saving and loading a composition', () => {
     expect(loaded.clips).toEqual([]);
   });
 
-  it('keeps every object at the top level, a negative offset at 0 and at least one track', () => {
+  it('keeps every object at the top level, a negative offset, and at least one track', () => {
     const cut = makeCut();
     const track = firstTrack(cut);
     const parent = cut.item(track, cut.spriteId, 0, 10);
@@ -624,7 +647,7 @@ describe('saving and loading a composition', () => {
     expect(loaded.items).toEqual([]);
     const again = findAssetOf(roundTrip(cut.project), cut.compId, 'composition')!;
     expect(again.objects.map((o) => o.parentId)).toEqual(['', '']);
-    expect(again.items.find((i) => i.id === child)!.offset).toBe(0);
+    expect(again.items.find((i) => i.id === child)!.offset).toBe(-3);
     expect(again.items.some((i) => 'fitMedia' in i)).toBe(false);
   });
 });