@hyperframes/studio 0.7.46 → 0.7.47

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

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+import type { TimelineElement } from "../store/playerStore";
+import { RULER_H, TRACK_H } from "./timelineLayout";
+import { selectTimelineElementsInMarquee } from "./timelineEditing";
+import type { StackingTimelineLayer } from "./timelineTrackOrder";
+
+function element(id: string, start: number, duration: number, track: number): TimelineElement {
+  return { id, tag: "div", start, duration, track };
+}
+
+function layer(id: string, elements: TimelineElement[]): StackingTimelineLayer {
+  return {
+    id,
+    kind: "visual",
+    contextKey: "",
+    zIndex: 0,
+    placementTrack: elements[0]?.track ?? 0,
+    elements,
+  };
+}
+
+describe("selectTimelineElementsInMarquee", () => {
+  it("selects clips intersecting both the marquee time span and lane span", () => {
+    const layers = [
+      layer("lane-0", [element("first-hit", 1, 1, 0), element("time-miss", 5, 1, 0)]),
+      layer("lane-1", [element("second-hit", 2.25, 1, 1)]),
+      layer("lane-2", [element("lane-miss", 1.5, 1, 2)]),
+    ];
+
+    expect(
+      selectTimelineElementsInMarquee({
+        rect: {
+          startTime: 0.5,
+          endTime: 3,
+          top: RULER_H,
+          bottom: RULER_H + TRACK_H * 2,
+        },
+        layers,
+        layerOrder: layers.map((item) => item.id),
+        rulerHeight: RULER_H,
+        trackHeight: TRACK_H,
+      }),
+    ).toEqual(["first-hit", "second-hit"]);
+  });
+
+  it("returns no ids when the marquee intersects no clip", () => {
+    const layers = [layer("lane-0", [element("outside", 4, 1, 0)])];
+
+    expect(
+      selectTimelineElementsInMarquee({
+        rect: {
+          startTime: 0,
+          endTime: 1,
+          top: RULER_H,
+          bottom: RULER_H + TRACK_H,
+        },
+        layers,
+        layerOrder: ["lane-0"],
+        rulerHeight: RULER_H,
+        trackHeight: TRACK_H,
+      }),
+    ).toEqual([]);
+  });
+
+  it("accounts for context group headers before row hit testing", () => {
+    const layers: StackingTimelineLayer[] = [
+      { ...layer("lane-0", [element("above", 0, 1, 0)]), contextKey: "root" },
+      { ...layer("lane-1", [element("below", 0, 1, 1)]), contextKey: "nested" },
+    ];
+
+    expect(
+      selectTimelineElementsInMarquee({
+        rect: {
+          startTime: 0,
+          endTime: 1,
+          top: RULER_H + 18 + TRACK_H,
+          bottom: RULER_H + 18 + TRACK_H + 18 + TRACK_H,
+        },
+        layers,
+        layerOrder: ["lane-0", "lane-1"],
+        rulerHeight: RULER_H,
+        trackHeight: TRACK_H,
+        groupHeaderHeight: 18,
+      }),
+    ).toEqual(["below"]);
+  });
+});

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

@@ -0,0 +1,144 @@
+import { describe, expect, it } from "vitest";
+import type { TimelineElement } from "../store/playerStore";
+import {
+  buildTimelineSnapTargets,
+  snapEdgesToTargets,
+  snapResizeEdgeToTargets,
+} from "./timelineSnapTargets";
+
+function timelineElement(input: {
+  id: string;
+  key?: string;
+  start: number;
+  duration: number;
+}): TimelineElement {
+  return {
+    id: input.id,
+    key: input.key,
+    tag: "div",
+    start: input.start,
+    duration: input.duration,
+    track: 0,
+  };
+}
+
+describe("buildTimelineSnapTargets", () => {
+  it("excludes the dragged clip's own edges", () => {
+    const dragged = timelineElement({
+      id: "dragged-id",
+      key: "dragged-key",
+      start: 1,
+      duration: 2,
+    });
+    const other = timelineElement({ id: "other", start: 4, duration: 2 });
+
+    const targets = buildTimelineSnapTargets({
+      elements: [dragged, other],
+      excludedKeys: new Set(["dragged-key"]),
+      playhead: 8,
+      compDuration: 10,
+      beats: [1.5],
+    });
+
+    const times = targets.map((target) => target.time);
+    expect(times).not.toContain(1);
+    expect(times).not.toContain(3);
+    expect(times).toContain(4);
+    expect(times).toContain(6);
+  });
+
+  it("excludes every moving group member, not just the grabbed clip", () => {
+    const a = timelineElement({ id: "a", start: 1, duration: 1 });
+    const b = timelineElement({ id: "b", start: 3, duration: 1 });
+    const other = timelineElement({ id: "other", start: 6, duration: 1 });
+
+    const targets = buildTimelineSnapTargets({
+      elements: [a, b, other],
+      excludedKeys: new Set(["a", "b"]),
+      playhead: 9,
+      compDuration: 10,
+      beats: [],
+    });
+
+    const times = targets.map((target) => target.time);
+    // Both group members' edges are excluded; the non-member's edges remain.
+    expect(times).not.toContain(1);
+    expect(times).not.toContain(2);
+    expect(times).not.toContain(3);
+    expect(times).not.toContain(4);
+    expect(times).toContain(6);
+    expect(times).toContain(7);
+  });
+
+  it("dedupes near-equal times from different sources", () => {
+    const dragged = timelineElement({ id: "dragged", start: 2, duration: 2 });
+    const other = timelineElement({ id: "other", start: 0.0004, duration: 10 });
+
+    const targets = buildTimelineSnapTargets({
+      elements: [dragged, other],
+      excludedKeys: new Set(["dragged"]),
+      playhead: 5,
+      compDuration: 10,
+      beats: [0.0002, 10.0002],
+    });
+
+    expect(targets.filter((target) => Math.abs(target.time) < 0.001)).toHaveLength(1);
+    expect(targets.filter((target) => Math.abs(target.time - 10) < 0.001)).toHaveLength(1);
+  });
+});
+
+describe("snapEdgesToTargets", () => {
+  it("snaps the start edge to another clip's end", () => {
+    const snap = snapEdgesToTargets(3.95, 2, [{ time: 4, kind: "edge" }], 100);
+
+    expect(snap).toEqual({ start: 4, snapTime: 4, snapKind: "edge" });
+  });
+
+  it("snaps the end edge to another clip's start", () => {
+    const snap = snapEdgesToTargets(2.96, 2, [{ time: 5, kind: "edge" }], 100);
+
+    expect(snap).toEqual({ start: 3, snapTime: 5, snapKind: "edge" });
+  });
+
+  it("snaps to the playhead", () => {
+    const snap = snapEdgesToTargets(2.94, 1, [{ time: 3, kind: "playhead" }], 100);
+
+    expect(snap).toEqual({ start: 3, snapTime: 3, snapKind: "playhead" });
+  });
+
+  it("snaps the start edge to the lower composition bound", () => {
+    const snap = snapEdgesToTargets(0.04, 1, [{ time: 0, kind: "bound" }], 100);
+
+    expect(snap).toEqual({ start: 0, snapTime: 0, snapKind: "bound" });
+  });
+
+  it("snaps the end edge to the upper composition bound", () => {
+    const snap = snapEdgesToTargets(7.96, 2, [{ time: 10, kind: "bound" }], 100);
+
+    expect(snap).toEqual({ start: 8, snapTime: 10, snapKind: "bound" });
+  });
+
+  it("does not snap when targets are beyond the pixel threshold", () => {
+    const snap = snapEdgesToTargets(3.9, 1, [{ time: 4, kind: "edge" }], 100);
+
+    expect(snap).toEqual({ start: 3.9, snapTime: null, snapKind: null });
+  });
+});
+
+describe("snapResizeEdgeToTargets", () => {
+  it("does not apply end-edge snaps past maxEnd or below minDuration", () => {
+    expect(
+      snapResizeEdgeToTargets("end", 4, 2.95, [{ time: 7.01, kind: "edge" }], 100, {
+        minDuration: 0.05,
+        maxEnd: 7,
+      }),
+    ).toEqual({ start: 4, duration: 2.95, snapTime: null, snapKind: null });
+
+    expect(
+      snapResizeEdgeToTargets("end", 4, 0.1, [{ time: 4.03, kind: "edge" }], 100, {
+        minDuration: 0.05,
+        maxEnd: 10,
+      }),
+    ).toEqual({ start: 4, duration: 0.1, snapTime: null, snapKind: null });
+  });
+});

package/src/player/components/timelineSnapTargets.ts

@@ -0,0 +1,164 @@
+import type { TimelineElement } from "../store/playerStore";
+
+export type TimelineSnapKind = "beat" | "edge" | "playhead" | "bound";
+
+export interface TimelineSnapTarget {
+  time: number;
+  kind: TimelineSnapKind;
+}
+
+interface NearestSnap {
+  target: TimelineSnapTarget;
+  distance: number;
+}
+
+const SNAP_PX = 8;
+const DEDUPE_EPSILON_SECONDS = 0.001;
+const ROUND_FACTOR = 1000;
+const KIND_PRIORITY: Record<TimelineSnapKind, number> = {
+  bound: 0,
+  playhead: 1,
+  edge: 2,
+  beat: 3,
+};
+
+function roundToMillis(value: number): number {
+  return Math.round(value * ROUND_FACTOR) / ROUND_FACTOR;
+}
+
+function addTarget(targets: TimelineSnapTarget[], candidate: TimelineSnapTarget) {
+  if (!Number.isFinite(candidate.time)) return;
+  const existingIndex = targets.findIndex(
+    (target) => Math.abs(target.time - candidate.time) < DEDUPE_EPSILON_SECONDS,
+  );
+  if (existingIndex === -1) {
+    targets.push(candidate);
+    return;
+  }
+
+  const existing = targets[existingIndex];
+  if (!existing || KIND_PRIORITY[candidate.kind] >= KIND_PRIORITY[existing.kind]) return;
+  targets[existingIndex] = candidate;
+}
+
+export function buildTimelineSnapTargets(input: {
+  elements: TimelineElement[];
+  /** Keys of every clip moving in this gesture (the whole group), excluded as targets. */
+  excludedKeys: ReadonlySet<string>;
+  playhead: number;
+  compDuration: number;
+  beats: number[];
+}): TimelineSnapTarget[] {
+  const targets: TimelineSnapTarget[] = [];
+
+  addTarget(targets, { time: 0, kind: "bound" });
+  addTarget(targets, { time: Math.max(0, input.compDuration), kind: "bound" });
+  addTarget(targets, { time: Math.max(0, input.playhead), kind: "playhead" });
+
+  for (const element of input.elements) {
+    const elementKey = element.key ?? element.id;
+    if (input.excludedKeys.has(elementKey) || input.excludedKeys.has(element.id)) continue;
+    addTarget(targets, { time: element.start, kind: "edge" });
+    addTarget(targets, { time: element.start + element.duration, kind: "edge" });
+  }
+
+  for (const beat of input.beats) {
+    addTarget(targets, { time: beat, kind: "beat" });
+  }
+
+  return targets.sort((a, b) => a.time - b.time || KIND_PRIORITY[a.kind] - KIND_PRIORITY[b.kind]);
+}
+
+function nearestSnap(
+  time: number,
+  targets: TimelineSnapTarget[],
+  thresholdSeconds: number,
+): NearestSnap | null {
+  let best: NearestSnap | null = null;
+  let bestDistance = thresholdSeconds;
+  for (const target of targets) {
+    if (target.time === time) continue;
+    const distance = Math.abs(target.time - time);
+    if (distance < bestDistance) {
+      bestDistance = distance;
+      best = { target, distance };
+    }
+  }
+  return best;
+}
+
+export function snapEdgesToTargets(
+  start: number,
+  duration: number,
+  targets: TimelineSnapTarget[],
+  pixelsPerSecond: number,
+  options?: { maxStart?: number },
+): { start: number; snapTime: number | null; snapKind: TimelineSnapKind | null } {
+  const thresholdSeconds = SNAP_PX / Math.max(pixelsPerSecond, 1);
+  const startSnap = nearestSnap(start, targets, thresholdSeconds);
+  const endSnap = nearestSnap(start + duration, targets, thresholdSeconds);
+
+  let candidate = start;
+  let snapTarget: TimelineSnapTarget | null = null;
+  if (startSnap && (!endSnap || startSnap.distance <= endSnap.distance)) {
+    candidate = startSnap.target.time;
+    snapTarget = startSnap.target;
+  } else if (endSnap) {
+    candidate = endSnap.target.time - duration;
+    snapTarget = endSnap.target;
+  }
+
+  const maxStart = options?.maxStart ?? Number.POSITIVE_INFINITY;
+  const upperStart = Number.isFinite(maxStart) ? Math.max(0, maxStart) : Number.POSITIVE_INFINITY;
+  const clamped = Math.max(0, Math.min(upperStart, roundToMillis(candidate)));
+  if (snapTarget && Math.abs(clamped - candidate) > 1e-6) {
+    return { start: clamped, snapTime: null, snapKind: null };
+  }
+  return {
+    start: clamped,
+    snapTime: snapTarget?.time ?? null,
+    snapKind: snapTarget?.kind ?? null,
+  };
+}
+
+export function snapResizeEdgeToTargets(
+  edge: "start" | "end",
+  start: number,
+  duration: number,
+  targets: TimelineSnapTarget[],
+  pixelsPerSecond: number,
+  limits: { minDuration: number; maxEnd: number; maxLeftDelta?: number },
+): { start: number; duration: number; snapTime: number | null; snapKind: TimelineSnapKind | null } {
+  const thresholdSeconds = SNAP_PX / Math.max(pixelsPerSecond, 1);
+
+  if (edge === "end") {
+    const snap = nearestSnap(start + duration, targets, thresholdSeconds);
+    if (!snap) return { start, duration, snapTime: null, snapKind: null };
+    const snappedDuration = roundToMillis(snap.target.time - start);
+    if (snap.target.time > limits.maxEnd + 1e-6 || snappedDuration < limits.minDuration) {
+      return { start, duration, snapTime: null, snapKind: null };
+    }
+    return {
+      start,
+      duration: snappedDuration,
+      snapTime: snap.target.time,
+      snapKind: snap.target.kind,
+    };
+  }
+
+  const snap = nearestSnap(start, targets, thresholdSeconds);
+  if (!snap) return { start, duration, snapTime: null, snapKind: null };
+  const snappedStart = roundToMillis(snap.target.time);
+  const delta = start - snappedStart;
+  const snappedDuration = roundToMillis(duration + delta);
+  const maxLeftDelta = limits.maxLeftDelta ?? Number.POSITIVE_INFINITY;
+  if (snappedStart < 0 || delta > maxLeftDelta + 1e-6 || snappedDuration < limits.minDuration) {
+    return { start, duration, snapTime: null, snapKind: null };
+  }
+  return {
+    start: snappedStart,
+    duration: snappedDuration,
+    snapTime: snap.target.time,
+    snapKind: snap.target.kind,
+  };
+}

package/src/player/components/timelineStacking.ts

@@ -0,0 +1,62 @@
+import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
+
+export interface TimelineStackingElement {
+  id: string;
+  key?: string;
+  tag?: string;
+  start: number;
+  duration: number;
+  track: number;
+  zIndex?: number;
+  stackingContextId?: string | null;
+  parentCompositionId?: string | null;
+  compositionAncestors?: string[];
+  // Locator for resolving the live element at commit time (sub-comp children
+  // aren't in the top-level element list, so the reorder intent must be
+  // self-contained rather than re-looked-up by identity).
+  domId?: string;
+  selector?: string;
+  selectorIndex?: number;
+  sourceFile?: string;
+}
+
+export interface TimelineStackingOrderItem {
+  key: string;
+  track: number;
+  zIndex: number;
+  stackingContextId: string | null;
+  parentCompositionId: string | null;
+  compositionAncestors: readonly string[];
+}
+
+export type TimelineLayerDropPlacement =
+  | { type: "onto"; layerId: string }
+  | { type: "between"; beforeLayerId: string; afterLayerId: string }
+  | { type: "above"; layerId: string }
+  | { type: "below"; layerId: string };
+
+export interface TimelineStackingZIndexChange {
+  key: string;
+  zIndex: number;
+  domId?: string;
+  selector?: string;
+  selectorIndex?: number;
+  sourceFile?: string;
+}
+
+export interface TimelineStackingReorderIntent {
+  contextKey: string;
+  placement: TimelineLayerDropPlacement;
+  zIndexChanges: TimelineStackingZIndexChange[];
+}
+
+export function toStackingOrderItem(element: TimelineStackingElement): TimelineStackingOrderItem {
+  return {
+    key: getTimelineElementIdentity(element),
+    track: element.track,
+    zIndex: element.zIndex ?? 0,
+    stackingContextId: element.stackingContextId ?? null,
+    parentCompositionId: element.parentCompositionId ?? null,
+    compositionAncestors: element.compositionAncestors ?? [],
+  };
+}

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

@@ -0,0 +1,144 @@
+import { describe, expect, it } from "vitest";
+import type { TimelineElement } from "../store/playerStore";
+import { buildStackingTimelineLayers, insertPreviewTrackOrder } from "./timelineTrackOrder";
+
+// fallow-ignore-next-line complexity
+function rowElement(input: {
+  id: string;
+  track?: number;
+  zIndex?: number;
+  hasExplicitZIndex?: boolean;
+  start?: number;
+  duration?: number;
+  tag?: string;
+  stackingContextId?: string | null;
+  parentCompositionId?: string | null;
+  compositionAncestors?: string[];
+}): TimelineElement {
+  return {
+    id: input.id,
+    tag: input.tag ?? "div",
+    start: input.start ?? 0,
+    duration: input.duration ?? 1,
+    track: input.track ?? 0,
+    zIndex: input.zIndex ?? 0,
+    hasExplicitZIndex: input.hasExplicitZIndex ?? true,
+    stackingContextId: input.stackingContextId ?? "root",
+    parentCompositionId: input.parentCompositionId ?? null,
+    compositionAncestors: input.compositionAncestors ?? ["root"],
+  };
+}
+
+function rowIds(rows: readonly { elements: readonly TimelineElement[] }[]): string[][] {
+  return rows.map((row) => row.elements.map((element) => element.id));
+}
+
+describe("buildStackingTimelineLayers", () => {
+  it("splits non-overlapping clips into separate lanes when their z-index differs", () => {
+    // A lane is a z-band: differing z must land on different rows even when the
+    // clips don't overlap in time, so a vertical (z) restack actually moves the
+    // clip's row. Rows are ordered by descending z.
+    const result = buildStackingTimelineLayers([
+      rowElement({ id: "back", zIndex: 1, start: 0, duration: 1 }),
+      rowElement({ id: "front", zIndex: 10, start: 1, duration: 1 }),
+    ]);
+
+    expect(rowIds(result.visualLayers)).toEqual([["front"], ["back"]]);
+    expect(result.visualLayers[0]?.zIndex).toBe(10);
+  });
+
+  it("packs non-overlapping clips into one lane when they share a z-index", () => {
+    const result = buildStackingTimelineLayers([
+      rowElement({ id: "back", zIndex: 5, start: 0, duration: 1 }),
+      rowElement({ id: "front", zIndex: 5, start: 1, duration: 1 }),
+    ]);
+
+    expect(rowIds(result.visualLayers)).toEqual([["back", "front"]]);
+    expect(result.visualLayers[0]?.zIndex).toBe(5);
+  });
+
+  it("splits clips into separate lanes when they overlap in time", () => {
+    const result = buildStackingTimelineLayers([
+      rowElement({ id: "front", zIndex: 10, start: 0, duration: 2 }),
+      rowElement({ id: "back", zIndex: 1, start: 1, duration: 2 }),
+    ]);
+
+    expect(rowIds(result.visualLayers)).toEqual([["front"], ["back"]]);
+  });
+
+  it("uses DOM order to break stacking ties before lane packing", () => {
+    const result = buildStackingTimelineLayers([
+      rowElement({ id: "first", track: 2, zIndex: 5, start: 0, duration: 2 }),
+      rowElement({ id: "second", track: 0, zIndex: 5, start: 1, duration: 2 }),
+    ]);
+
+    expect(rowIds(result.visualLayers)).toEqual([["first"], ["second"]]);
+  });
+
+  it("packs auto-z clips by time instead of forcing one row per clip", () => {
+    const result = buildStackingTimelineLayers([
+      rowElement({ id: "a", zIndex: 0, hasExplicitZIndex: false, start: 0, duration: 1 }),
+      rowElement({ id: "b", zIndex: 0, hasExplicitZIndex: false, start: 1, duration: 1 }),
+    ]);
+
+    expect(rowIds(result.visualLayers)).toEqual([["a", "b"]]);
+  });
+
+  it("does not merge equal z-index clips across stacking contexts", () => {
+    const result = buildStackingTimelineLayers([
+      rowElement({ id: "root", zIndex: 4, start: 0, duration: 1 }),
+      rowElement({
+        id: "nested",
+        zIndex: 4,
+        start: 1,
+        duration: 1,
+        stackingContextId: "scene",
+        parentCompositionId: "scene",
+        compositionAncestors: ["root", "scene"],
+      }),
+    ]);
+
+    expect(rowIds(result.visualLayers)).toEqual([["root"], ["nested"]]);
+  });
+
+  it("returns audio clips as separate bottom rows without merging them into z layers", () => {
+    const result = buildStackingTimelineLayers([
+      rowElement({ id: "front", zIndex: 10 }),
+      rowElement({ id: "music-a", tag: "audio", track: 4 }),
+      rowElement({ id: "music-b", tag: "audio", track: 2 }),
+    ]);
+
+    expect(rowIds(result.visualLayers)).toEqual([["front"]]);
+    expect(rowIds(result.audioLayers)).toEqual([["music-a"], ["music-b"]]);
+    expect(rowIds(result.rows)).toEqual([["front"], ["music-a"], ["music-b"]]);
+  });
+
+  it("orders rows by descending z-index with auto-z clips ranked at computed zero", () => {
+    const result = buildStackingTimelineLayers([
+      rowElement({ id: "auto-a", zIndex: 0, hasExplicitZIndex: false }),
+      rowElement({ id: "back", zIndex: -1 }),
+      rowElement({ id: "front", zIndex: 10 }),
+      rowElement({ id: "auto-b", zIndex: 0, hasExplicitZIndex: false }),
+    ]);
+
+    expect(rowIds(result.visualLayers)).toEqual([["front"], ["auto-a"], ["auto-b"], ["back"]]);
+  });
+
+  it("keeps a row key stable when a clip's z-index changes but membership does not", () => {
+    const before = buildStackingTimelineLayers([rowElement({ id: "hero", zIndex: 1 })]);
+    const after = buildStackingTimelineLayers([rowElement({ id: "hero", zIndex: 20 })]);
+
+    expect(after.visualLayers[0]?.id).toBe(before.visualLayers[0]?.id);
+  });
+});
+
+describe("insertPreviewTrackOrder", () => {
+  it("inserts preview layer ids by target row index", () => {
+    expect(insertPreviewTrackOrder(["a", "b", "c"], "preview", 1)).toEqual([
+      "a",
+      "preview",
+      "b",
+      "c",
+    ]);
+  });
+});