@hyperframes/studio 0.7.56 → 0.7.58

package/src/player/components/timelineGapCommit.ts

@@ -0,0 +1,103 @@
+import type { TimelineElement } from "../store/playerStore";
+import { getTimelineEditCapabilities } from "./timelineEditing";
+import {
+  persistMoveEdits,
+  type DragCommitDeps,
+  type TimelineMoveEdit,
+} from "./timelineClipDragCommit";
+import {
+  laneGapFloor,
+  resolveAllTrackGaps,
+  resolveCloseGapShifts,
+  resolveTrackGapAt,
+  type TrackGapShift,
+} from "./timelineGaps";
+
+/**
+ * Commit layer for the track-gap context menu ("Close gap" / "Close all gaps").
+ *
+ * Each action is ONE atomic {@link persistMoveEdits} batch — pure time moves
+ * (`updates.track === element.track`, no authored-track rewrite) tagged with a
+ * per-gesture-unique coalesce key, so an action is exactly one undo entry and
+ * flows through the existing move pipeline (optimistic store apply + rollback,
+ * SDK fast path, patchIframeDomTiming preview).
+ *
+ * Refusal rule: if ANY clip that must shift is unmovable
+ * ({@link getTimelineEditCapabilities}.canMove === false), the whole action is
+ * refused — never a partial compaction. The menu disables the item via
+ * {@link canShiftTrackGapClips}; the commit re-checks as defense in depth.
+ */
+
+const keyOf = (e: TimelineElement) => e.key ?? e.id;
+
+// Per-gesture-unique coalesce key. A monotonic counter — NOT Date.now() /
+// Math.random() (determinism rules) — mirrors laneChangeGestureSeq in
+// timelineClipDragCommit.ts.
+let gapCloseGestureSeq = 0;
+
+/** True when every clip named in `shifts` may be time-moved. */
+export function canShiftTrackGapClips(
+  laneElements: readonly TimelineElement[],
+  shifts: readonly TrackGapShift[],
+): boolean {
+  const byKey = new Map(laneElements.map((e) => [keyOf(e), e]));
+  return shifts.every((s) => {
+    const element = byKey.get(s.key);
+    return element != null && getTimelineEditCapabilities(element).canMove;
+  });
+}
+
+function buildShiftEdits(
+  laneElements: readonly TimelineElement[],
+  shifts: readonly TrackGapShift[],
+): TimelineMoveEdit[] | null {
+  if (shifts.length === 0 || !canShiftTrackGapClips(laneElements, shifts)) return null;
+  const byKey = new Map(laneElements.map((e) => [keyOf(e), e]));
+  return shifts.map((s) => {
+    const element = byKey.get(s.key)!;
+    return { element, updates: { start: s.newStart, track: element.track } };
+  });
+}
+
+function commitShifts(
+  laneElements: readonly TimelineElement[],
+  shifts: readonly TrackGapShift[],
+  deps: DragCommitDeps,
+): boolean {
+  const edits = buildShiftEdits(laneElements, shifts);
+  if (!edits) return false;
+  void persistMoveEdits(edits, deps, `track-gap-close:${gapCloseGestureSeq++}`);
+  return true;
+}
+
+/**
+ * Close the ONE gap under `time` on the lane: the next clip and every clip
+ * after it on that lane shift left by the gap's width. Returns false (and
+ * writes nothing) when there is no gap at the point or a shifting clip is
+ * unmovable.
+ */
+export function commitCloseTrackGap(
+  laneElements: readonly TimelineElement[],
+  time: number,
+  deps: DragCommitDeps,
+): boolean {
+  const gap = resolveTrackGapAt(laneElements, time, undefined, laneGapFloor(laneElements));
+  if (!gap) return false;
+  return commitShifts(laneElements, resolveCloseGapShifts(laneElements, gap), deps);
+}
+
+/**
+ * Compact the whole lane (leading gap included): clips become contiguous from
+ * 0, order and durations preserved. Returns false (and writes nothing) when
+ * the lane has no gaps or a shifting clip is unmovable.
+ */
+export function commitCloseAllTrackGaps(
+  laneElements: readonly TimelineElement[],
+  deps: DragCommitDeps,
+): boolean {
+  return commitShifts(
+    laneElements,
+    resolveAllTrackGaps(laneElements, undefined, laneGapFloor(laneElements)),
+    deps,
+  );
+}

package/src/player/components/timelineGaps.test.ts

@@ -0,0 +1,221 @@
+import { describe, expect, it } from "vitest";
+import type { TimelineElement } from "../store/playerStore";
+import {
+  laneGapFloor,
+  resolveAllGapIntervals,
+  resolveAllTrackGaps,
+  resolveCloseGapShifts,
+  resolveTrackGapAt,
+  trackHasGaps,
+} from "./timelineGaps";
+
+function el(id: string, start: number, duration: number): TimelineElement {
+  return { id, tag: "video", start, duration, track: 0, domId: id };
+}
+
+describe("resolveTrackGapAt", () => {
+  it("resolves a middle gap between two clips", () => {
+    const els = [el("a", 0, 2), el("b", 5, 3)];
+    const gap = resolveTrackGapAt(els, 3);
+    expect(gap).toEqual({ gapStart: 2, gapEnd: 5, followingKeys: ["b"] });
+  });
+
+  it("resolves the leading gap before the first clip (gapStart = 0)", () => {
+    const els = [el("a", 2, 3), el("b", 6, 1)];
+    const gap = resolveTrackGapAt(els, 1);
+    expect(gap).toEqual({ gapStart: 0, gapEnd: 2, followingKeys: ["a", "b"] });
+  });
+
+  it("includes EVERY clip at/after the gap in followingKeys", () => {
+    const els = [el("a", 0, 1), el("b", 3, 1), el("c", 5, 1), el("d", 8, 1)];
+    const gap = resolveTrackGapAt(els, 2);
+    expect(gap).toEqual({ gapStart: 1, gapEnd: 3, followingKeys: ["b", "c", "d"] });
+  });
+
+  it("returns null when there is no clip to the right of the point", () => {
+    const els = [el("a", 0, 2)];
+    expect(resolveTrackGapAt(els, 5)).toBeNull();
+    expect(resolveTrackGapAt([], 1)).toBeNull(); // empty lane
+  });
+
+  it("returns null when the point is inside a clip (half-open interval)", () => {
+    const els = [el("a", 1, 2), el("b", 5, 1)];
+    expect(resolveTrackGapAt(els, 2)).toBeNull(); // strictly inside
+    expect(resolveTrackGapAt(els, 1)).toBeNull(); // at clip start (occupied)
+    // At clip END (half-open) the point is free — the gap to "b" resolves.
+    expect(resolveTrackGapAt(els, 3)).toEqual({ gapStart: 3, gapEnd: 5, followingKeys: ["b"] });
+  });
+
+  it("resolves the leading gap for a single clip", () => {
+    const gap = resolveTrackGapAt([el("a", 4, 2)], 1);
+    expect(gap).toEqual({ gapStart: 0, gapEnd: 4, followingKeys: ["a"] });
+  });
+
+  it("treats epsilon-adjacent clips as gapless (float drift)", () => {
+    // 8.4 + 2.7 = 11.100000000000001 — the classic drift: no point near the
+    // seam resolves a gap.
+    const drifted = [el("a", 8.4, 2.7), el("b", 11.1, 2)];
+    expect(resolveTrackGapAt(drifted, 11.0999)).toBeNull();
+    expect(resolveTrackGapAt(drifted, 11.1005)).toBeNull();
+    // A sub-epsilon sliver between clips is not a closable gap either.
+    const sliver = [el("a", 0, 2.0004), el("b", 2.001, 1)];
+    expect(resolveTrackGapAt(sliver, 1.9995)).toBeNull();
+  });
+
+  it("handles overlapping clips sanely (uses the max end left of the point)", () => {
+    const els = [el("a", 0, 4), el("b", 1, 2), el("c", 6, 1)];
+    const gap = resolveTrackGapAt(els, 5);
+    expect(gap).toEqual({ gapStart: 4, gapEnd: 6, followingKeys: ["c"] });
+  });
+
+  it("prefers the key over the id when present", () => {
+    const withKey = { ...el("a", 3, 1), key: "a-key" };
+    const gap = resolveTrackGapAt([withKey], 1);
+    expect(gap?.followingKeys).toEqual(["a-key"]);
+  });
+});
+
+describe("resolveCloseGapShifts", () => {
+  it("shifts the following clips left by exactly the gap width", () => {
+    const els = [el("a", 0, 2), el("b", 5, 3), el("c", 10, 1)];
+    const gap = resolveTrackGapAt(els, 3)!;
+    expect(resolveCloseGapShifts(els, gap)).toEqual([
+      { key: "b", newStart: 2 },
+      { key: "c", newStart: 7 },
+    ]);
+  });
+
+  it("closing the leading gap lands the first clip at 0", () => {
+    const els = [el("a", 2, 3), el("b", 6, 1)];
+    const gap = resolveTrackGapAt(els, 1)!;
+    expect(resolveCloseGapShifts(els, gap)).toEqual([
+      { key: "a", newStart: 0 },
+      { key: "b", newStart: 4 },
+    ]);
+  });
+
+  it("rounds shifted starts to millisecond precision", () => {
+    const els = [el("a", 0, 1.1), el("b", 3.3000000000000003, 1)];
+    const gap = resolveTrackGapAt(els, 2)!;
+    const shifts = resolveCloseGapShifts(els, gap);
+    expect(shifts).toEqual([{ key: "b", newStart: 1.1 }]);
+  });
+});
+
+describe("resolveAllTrackGaps", () => {
+  it("compacts every gap: contiguous from 0, order and durations preserved", () => {
+    const els = [el("a", 1, 2), el("b", 5, 3), el("c", 10, 1)];
+    expect(resolveAllTrackGaps(els)).toEqual([
+      { key: "a", newStart: 0 },
+      { key: "b", newStart: 2 },
+      { key: "c", newStart: 5 },
+    ]);
+  });
+
+  it("includes the leading gap for a single clip", () => {
+    expect(resolveAllTrackGaps([el("a", 4, 2)])).toEqual([{ key: "a", newStart: 0 }]);
+  });
+
+  it("returns only the clips whose start actually changes", () => {
+    const els = [el("a", 0, 2), el("b", 2, 1), el("c", 5, 1)];
+    expect(resolveAllTrackGaps(els)).toEqual([{ key: "c", newStart: 3 }]);
+  });
+
+  it("returns [] for an already-contiguous track and for an empty lane", () => {
+    expect(resolveAllTrackGaps([el("a", 0, 2), el("b", 2, 3)])).toEqual([]);
+    expect(resolveAllTrackGaps([])).toEqual([]);
+  });
+
+  it("ignores epsilon-level drift instead of emitting no-op shifts", () => {
+    const els = [el("a", 0, 8.4), el("b", 8.4, 2.7), el("c", 11.100000000000001, 2)];
+    expect(resolveAllTrackGaps(els)).toEqual([]);
+  });
+
+  it("serializes overlapping clips in start order (sum-of-durations rule)", () => {
+    const els = [el("a", 0, 4), el("b", 2, 2)];
+    expect(resolveAllTrackGaps(els)).toEqual([{ key: "b", newStart: 4 }]);
+  });
+
+  it("is deterministic for identical starts (key tie-break)", () => {
+    const els = [el("b", 3, 1), el("a", 3, 2)];
+    expect(resolveAllTrackGaps(els)).toEqual([
+      { key: "a", newStart: 0 },
+      { key: "b", newStart: 2 },
+    ]);
+  });
+});
+
+describe("resolveAllGapIntervals", () => {
+  it("reports every current gap, leading gap included, left to right", () => {
+    const els = [el("a", 1, 2), el("b", 5, 3), el("c", 10, 1)];
+    expect(resolveAllGapIntervals(els)).toEqual([
+      { start: 0, end: 1 },
+      { start: 3, end: 5 },
+      { start: 8, end: 10 },
+    ]);
+  });
+
+  it("returns [] for contiguous or empty lanes", () => {
+    expect(resolveAllGapIntervals([el("a", 0, 2), el("b", 2, 3)])).toEqual([]);
+    expect(resolveAllGapIntervals([])).toEqual([]);
+  });
+
+  it("never fabricates an interval from overlapping clips (cursor = max end)", () => {
+    const els = [el("a", 0, 4), el("b", 1, 2), el("c", 6, 1)];
+    expect(resolveAllGapIntervals(els)).toEqual([{ start: 4, end: 6 }]);
+  });
+
+  it("ignores epsilon-level drift seams", () => {
+    const els = [el("a", 0, 8.4), el("b", 8.4, 2.7), el("c", 11.100000000000001, 2)];
+    expect(resolveAllGapIntervals(els)).toEqual([]);
+  });
+});
+
+describe("trackHasGaps", () => {
+  it("detects gaps, including the leading gap", () => {
+    expect(trackHasGaps([el("a", 1, 2)])).toBe(true);
+    expect(trackHasGaps([el("a", 0, 2), el("b", 4, 1)])).toBe(true);
+  });
+
+  it("is false for contiguous or empty tracks", () => {
+    expect(trackHasGaps([el("a", 0, 2), el("b", 2, 1)])).toBe(false);
+    expect(trackHasGaps([])).toBe(false);
+  });
+});
+
+describe("lane floor (expanded sub-comp children)", () => {
+  const child = (id: string, start: number, duration: number): TimelineElement => ({
+    ...el(id, start, duration),
+    expandedParentStart: 16,
+    sourceFile: "scene.html",
+  });
+
+  it("laneGapFloor is 0 for ordinary lanes and the host window start for child lanes", () => {
+    expect(laneGapFloor([el("a", 0, 2)])).toBe(0);
+    expect(laneGapFloor([child("c1", 16.5, 2), child("c2", 20, 2)])).toBe(16);
+  });
+
+  it("compaction lands the first child at the HOST window start, never absolute 0", () => {
+    const lane = [child("c1", 18, 2), child("c2", 22, 2)];
+    expect(resolveAllTrackGaps(lane, undefined, laneGapFloor(lane))).toEqual([
+      { key: "c1", newStart: 16 },
+      { key: "c2", newStart: 18 },
+    ]);
+  });
+
+  it("the leading gap starts at the floor for both close-one and the highlight intervals", () => {
+    const lane = [child("c1", 18, 2)];
+    const floor = laneGapFloor(lane);
+    expect(resolveTrackGapAt(lane, 17, undefined, floor)).toEqual({
+      gapStart: 16,
+      gapEnd: 18,
+      followingKeys: ["c1"],
+    });
+    expect(resolveAllGapIntervals(lane, undefined, floor)).toEqual([{ start: 16, end: 18 }]);
+  });
+
+  it("a child lane contiguous from its host start has no gaps", () => {
+    const lane = [child("c1", 16, 2), child("c2", 18, 2)];
+    expect(trackHasGaps(lane, undefined, laneGapFloor(lane))).toBe(false);
+  });
+});

package/src/player/components/timelineGaps.ts

@@ -0,0 +1,182 @@
+import type { TimelineElement } from "../store/playerStore";
+
+/**
+ * Pure gap math for a single timeline display lane (CapCut/Premiere-style
+ * "Close gap" / "Close all gaps"). Operates on the DISPLAY element set the
+ * timeline renders for one lane — the caller passes the clips of the
+ * right-clicked lane only; cross-lane behavior is out of scope by design.
+ *
+ * Conventions:
+ * - A clip occupies the half-open interval [start, start + duration).
+ * - Comparisons are epsilon-tolerant ({@link TRACK_GAP_EPSILON_S}) so float
+ *   drift (e.g. 8.4 + 2.7 = 11.100000000000001) never fabricates a sliver gap.
+ * - Computed starts are rounded to millisecond precision, matching the drag
+ *   commit's `round3`.
+ */
+const TRACK_GAP_EPSILON_S = 1e-3;
+
+const keyOf = (e: TimelineElement) => e.key ?? e.id;
+
+/**
+ * The lane's time ORIGIN — the earliest start a clip on this lane may take.
+ * 0 for ordinary lanes; for a lane of expanded sub-comp children (post-
+ * collision-fix a lane is always single-origin) it is the children's host
+ * window start (`expandedParentStart`): display times are host-absolute, so
+ * compacting toward absolute 0 would drag a child BEFORE its host's window
+ * and persist a wrong (even negative) local time.
+ */
+export function laneGapFloor(elements: readonly TimelineElement[]): number {
+  return Math.max(0, ...elements.map((e) => e.expandedParentStart ?? 0));
+}
+const round3 = (v: number) => Math.round(v * 1000) / 1000;
+const endOf = (e: TimelineElement) => e.start + e.duration;
+
+/** Lane clips sorted by start (key as a deterministic tie-break). */
+function sortedLaneClips(elements: readonly TimelineElement[]): TimelineElement[] {
+  return [...elements].sort((a, b) => a.start - b.start || keyOf(a).localeCompare(keyOf(b)));
+}
+
+export interface TrackGapAt {
+  /** Gap left edge: the max end of the clips left of the point (0 for the leading gap). */
+  gapStart: number;
+  /** Gap right edge: the start of the next clip on the lane. */
+  gapEnd: number;
+  /** Keys of the next clip and every clip after it on the lane, in start order. */
+  followingKeys: string[];
+}
+
+/**
+ * Resolve the gap under a right-clicked point on one lane.
+ *
+ * Returns null when the point sits inside a clip, when there is no clip to the
+ * right of the point (nothing to close), or when the neighbouring clips are
+ * epsilon-adjacent (no real gap).
+ */
+export function resolveTrackGapAt(
+  elements: readonly TimelineElement[],
+  time: number,
+  epsilon: number = TRACK_GAP_EPSILON_S,
+  floor: number = 0,
+): TrackGapAt | null {
+  const clips = sortedLaneClips(elements);
+  // Point inside a clip's half-open [start, end) → not empty space.
+  const occupied = clips.some((c) => time >= c.start - epsilon && time < endOf(c) - epsilon);
+  if (occupied) return null;
+
+  const following = clips.filter((c) => c.start > time - epsilon);
+  if (following.length === 0) return null; // nothing to the right — nothing to close
+
+  const gapEnd = following[0].start;
+  // Max end among clips left of the point (they all end at/before it since the
+  // point is unoccupied); the lane floor for the leading gap before the first
+  // clip (0 for ordinary lanes, the host window start for expanded children).
+  const gapStart = Math.max(
+    floor,
+    ...clips.filter((c) => c.start <= time - epsilon).map((c) => endOf(c)),
+  );
+  if (gapEnd - gapStart <= epsilon) return null; // epsilon-adjacent — no gap
+
+  return { gapStart, gapEnd, followingKeys: following.map(keyOf) };
+}
+
+export interface TrackGapShift {
+  key: string;
+  newStart: number;
+}
+
+/** An empty interval on the lane, [start, end) in seconds. */
+export interface TrackGapInterval {
+  start: number;
+  end: number;
+}
+
+/**
+ * Every CURRENT empty interval on the lane, leading gap included — the regions
+ * "Close all gaps" would collapse, in left-to-right order. Purely descriptive
+ * (for the hover-highlight overlay): unlike {@link resolveAllTrackGaps} it
+ * reports the gaps as they are now, not the post-compaction clip starts.
+ * Overlapping clips never fabricate a negative interval (the cursor tracks the
+ * max end seen so far).
+ */
+export function resolveAllGapIntervals(
+  elements: readonly TimelineElement[],
+  epsilon: number = TRACK_GAP_EPSILON_S,
+  floor: number = 0,
+): TrackGapInterval[] {
+  const gaps: TrackGapInterval[] = [];
+  let cursor = floor;
+  for (const clip of sortedLaneClips(elements)) {
+    if (clip.start - cursor > epsilon) gaps.push({ start: cursor, end: clip.start });
+    cursor = Math.max(cursor, endOf(clip));
+  }
+  return gaps;
+}
+
+/**
+ * Compact the whole lane: every clip lands at the sum of the durations of the
+ * clips before it (contiguous from 0, order and durations preserved).
+ * Overlapping clips (spill lanes) are serialized in start order — sane, if
+ * lossy for deliberate overlaps; the display lane set should not contain them.
+ *
+ * Returns ONLY the clips whose start actually changes (beyond epsilon).
+ */
+export function resolveAllTrackGaps(
+  elements: readonly TimelineElement[],
+  epsilon: number = TRACK_GAP_EPSILON_S,
+  floor: number = 0,
+): TrackGapShift[] {
+  const shifts: TrackGapShift[] = [];
+  let cursor = floor;
+  for (const clip of sortedLaneClips(elements)) {
+    const newStart = round3(cursor);
+    if (Math.abs(newStart - clip.start) > epsilon) {
+      shifts.push({ key: keyOf(clip), newStart });
+    }
+    cursor += clip.duration;
+  }
+  return shifts;
+}
+
+/**
+ * Every empty interval on the lane across the FULL rendered extent `[0, end)`:
+ * the closable gaps plus the open region after the last clip. Powers the
+ * click-selected lane highlight ("light the whole track except the clips") —
+ * unlike {@link resolveAllGapIntervals} it is not limited to what a gap-close
+ * could collapse.
+ */
+export function resolveLaneEmptyIntervals(
+  elements: readonly TimelineElement[],
+  end: number,
+  epsilon: number = TRACK_GAP_EPSILON_S,
+  floor: number = 0,
+): TrackGapInterval[] {
+  const gaps = resolveAllGapIntervals(elements, epsilon, floor);
+  const maxEnd = Math.max(floor, ...elements.map(endOf));
+  if (end - maxEnd > epsilon) gaps.push({ start: maxEnd, end });
+  return gaps;
+}
+
+/** Whether the lane has any gap "Close all gaps" would collapse. */
+export function trackHasGaps(
+  elements: readonly TimelineElement[],
+  epsilon: number = TRACK_GAP_EPSILON_S,
+  floor: number = 0,
+): boolean {
+  return resolveAllTrackGaps(elements, epsilon, floor).length > 0;
+}
+
+/**
+ * Per-clip shifts for closing ONE gap: the next clip and every clip after it
+ * on the lane move left by the gap's width. Starts are clamped at 0 (float
+ * safety; real shifts never cross the gap's own left edge).
+ */
+export function resolveCloseGapShifts(
+  elements: readonly TimelineElement[],
+  gap: TrackGapAt,
+): TrackGapShift[] {
+  const width = gap.gapEnd - gap.gapStart;
+  const followSet = new Set(gap.followingKeys);
+  return sortedLaneClips(elements)
+    .filter((c) => followSet.has(keyOf(c)))
+    .map((c) => ({ key: keyOf(c), newStart: Math.max(gap.gapStart, round3(c.start - width)) }));
+}

package/src/player/components/timelineLayout.test.ts

@@ -5,6 +5,7 @@ import {
   TRACKS_TOP_PAD,
   TRACKS_BOTTOM_PAD,
   GUTTER,
+  TRACKS_LEFT_PAD,
   getTimelineRowTop,
   getTimelineRowFromY,
   getTimelineCanvasHeight,
@@ -85,7 +86,7 @@ describe("track-area breathing pad y-math", () => {
 
     it("drops onto lane 0 when the pointer is in the middle of the first lane", () => {
       const clientY = getTimelineRowTop(0) + TRACK_H / 2;
-      const clientX = GUTTER + 100; // t = 1s
+      const clientX = GUTTER + TRACKS_LEFT_PAD + 100; // t = 1s
       const { start, track } = resolveTimelineAssetDrop(base, clientX, clientY);
       expect(track).toBe(0);
       expect(start).toBe(1);