Skip to content

Write HTML. Render video. Built for agents.

17.9 KB
Raw Blame
import { resolveTimelineMove, resolveTimelineResize } from "./timelineEditing";
import {
  applyClipStartTrimDelta,
  clipStartTrimDeltaBounds,
  resolveTimelineMinDuration,
} from "./timelineGroupEditing";
import type { TimelineElement } from "../store/playerStore";
import { clampToHostStart, savedClipEdges } from "../store/timelineElement";
import {
  CLIP_Y,
  TRACK_H,
  getTimelineRowGeometry,
  type TimelineRowGeometry,
} from "./timelineLayout";
import { isMusicTrack, isAudioTimelineElement } from "../../utils/timelineInspector";
import {
  TIMELINE_SNAP_PX,
  snapMoveToTargets,
  snapTimelineTime,
  type TimelineSnapTarget,
  type TimelineSnapType,
} from "./timelineSnapping";
import { resolveInsertRow, resolveZoneDropPlacement } from "./timelineCollision";
import {
  applyTimelineGroupResizePreview,
  type TimelineGroupResizeSession,
} from "./timelineGroupEditing";
import { groupMoveFloor, resolveGroupMovers } from "./timelineMultiDragPreview";
import type { DraggedClipState, ResizingClipState } from "./timelineClipDragTypes";
import { STUDIO_PREVIEW_FPS } from "../lib/time";
import { heldAudioShiftRange, heldPartnerVideoBounds } from "./audioClipLink";

/** Snap-target builder closure supplied by the hook (closes over refs + store). */
type BuildSnapTargets = (
  excludeElementKey: string | null,
  includeBeats: boolean,
) => TimelineSnapTarget[];

export interface DragPreviewContext {
  scroll: HTMLDivElement | null;
  pps: number;
  duration: number;
  trackOrder: number[];
  rowHeights?: readonly number[];
  rowGeometry?: TimelineRowGeometry;
  allowedInsertRows?: ReadonlySet<number>;
  groupTracks?: ReadonlyMap<number, readonly number[]>;
  elements: TimelineElement[];
  selectedKeys: ReadonlySet<string>;
  buildSnapTargets: BuildSnapTargets;
  /**
   * The set of tracks that hold audio clips (drives zone-aware drop placement).
   * Frozen for the whole gesture, so the hook builds it ONCE at drag start and
   * passes it in — see useTimelineClipDrag. Absent (e.g. in unit tests) ⇒ built
   * on demand from `elements`, so the result is identical either way.
   */
  audioTracks?: ReadonlySet<number>;
  /** Seconds between the ruler's lines; 0 or absent when snapping is off. */
  gridStep?: number;
}

export function createKeyboardClipDrag(
  element: TimelineElement,
  insertRow: number,
  scrollLeft: number,
  scrollTop: number,
): DraggedClipState {
  return {
    pointerId: null,
    element,
    insertRow,
    started: true,
    previewStart: element.start,
    previewTrack: element.track,
    desiredTrack: element.track,
    originClientX: 0,
    originClientY: 0,
    originScrollLeft: scrollLeft,
    originScrollTop: scrollTop,
    pointerClientX: 0,
    pointerClientY: 0,
    pointerOffsetX: 0,
    pointerOffsetY: 0,
    snapTime: null,
    snapType: null,
  };
}

/** Content-space position for the stable viewport drag actor. */
export function getTimelineDragOverlayPosition(
  drag: DraggedClipState,
  scroll: Pick<HTMLDivElement, "scrollLeft" | "scrollTop" | "getBoundingClientRect"> | null,
): { left: number; top: number } | null {
  if (!drag.started || !scroll) return null;
  const rect = scroll.getBoundingClientRect();
  return {
    left: drag.pointerClientX - rect.left + scroll.scrollLeft - drag.pointerOffsetX,
    top: drag.pointerClientY - rect.top + scroll.scrollTop - drag.pointerOffsetY,
  };
}

/**
 * Max start a drag may reach. Allow dragging past the current content into the
 * rendered timeline extent (the viewport-fill keeps that ≥ the viewport width).
 * The composition grows to fit on commit (content-driven duration), so don't
 * cap at content length.
 */
function resolveDragMaxStart(scroll: HTMLDivElement | null, pps: number, duration: number): number {
  return Math.max(duration, scroll && pps > 0 ? scroll.scrollWidth / pps : duration);
}

const INSERT_SEAM_PX = CLIP_Y;

function physicalInsertRow(
  rowFloat: number,
  y: number,
  ctx: Pick<DragPreviewContext, "trackOrder" | "allowedInsertRows">,
  geometry: TimelineRowGeometry,
) {
  const boundary = Math.round(rowFloat);
  const nearSeam = Math.abs(y - geometry.getRowTop(boundary)) <= INSERT_SEAM_PX;
  const row = nearSeam
    ? Math.max(0, Math.min(ctx.trackOrder.length, boundary))
    : resolveInsertRow(rowFloat, ctx.trackOrder.length);
  if (row !== null && ctx.allowedInsertRows && !ctx.allowedInsertRows.has(row)) return null;
  return row;
}

function dragRowAim(
  drag: DraggedClipState,
  clientY: number,
  ctx: DragPreviewContext,
  geometry: TimelineRowGeometry,
) {
  let y = clientY - (ctx.scroll?.getBoundingClientRect().top ?? 0) + (ctx.scroll?.scrollTop ?? 0);
  if (drag.started && drag.insertRow !== null) {
    const top = geometry.getRowTop(drag.insertRow);
    if (y >= top - INSERT_SEAM_PX && y <= top + TRACK_H + INSERT_SEAM_PX)
      return { rowFloat: drag.insertRow, insertRow: drag.insertRow };
    if (y > top + TRACK_H) y -= TRACK_H;
  }
  const rowFloat = geometry.getRowFromY(y);
  return { rowFloat, insertRow: physicalInsertRow(rowFloat, y, ctx, geometry) };
}

/** The drop decision for the pointer's row (see resolveZoneDropPlacement). */
function resolveDropPlacement(
  drag: DraggedClipState,
  aim: ReturnType<typeof dragRowAim>,
  previewStart: number,
  desiredTrack: number,
  ctx: DragPreviewContext,
  group: GroupDrag,
): { track: number; insertRow: number | null; start: number } {
  const { trackOrder, elements } = ctx;
  const dragKey = drag.element.key ?? drag.element.id;
  const audioTracks =
    ctx.audioTracks ?? new Set(elements.filter(isAudioTimelineElement).map((e) => e.track));
  return resolveZoneDropPlacement({
    order: trackOrder,
    audioTracks,
    elements: group.obstacles,
    desiredTrack,
    deliberateInsertRow: aim.insertRow,
    allowedInsertRows: ctx.allowedInsertRows,
    groupTracks: ctx.groupTracks,
    start: previewStart,
    duration: drag.element.duration,
    dragKey,
    isAudio: isAudioTimelineElement(drag.element),
    minStart: group.floor,
    origin: { track: drag.element.track, start: drag.element.start },
  });
}

interface GroupDrag {
  /** Clips the grabbed clip may not overlap: everything but the clips that move with it. */
  obstacles: TimelineElement[];
  /** Lowest start the grabbed clip may take (see groupMoveFloor). */
  floor: number;
  moving: ReadonlySet<string>;
}

function resolveGroupDrag(drag: DraggedClipState, ctx: DragPreviewContext): GroupDrag {
  const movers = resolveGroupMovers(
    ctx.elements,
    ctx.selectedKeys,
    drag.element.key ?? drag.element.id,
  );
  if (!movers) {
    const moving = new Set([drag.element.key ?? drag.element.id]);
    return { obstacles: ctx.elements, floor: groupMoveFloor(drag.element, []), moving };
  }
  const moving = new Set(movers.map((e) => e.key ?? e.id));
  return {
    obstacles: ctx.elements.filter((e) => !moving.has(e.key ?? e.id)),
    floor: groupMoveFloor(drag.element, movers),
    moving,
  };
}

const SHIFT_EPSILON_S = 1e-6;

/** Recompute the dragged-clip preview (move + snap + group clamp + drop placement). */
export function computeDragPreview(
  drag: DraggedClipState,
  clientX: number,
  clientY: number,
  ctx: DragPreviewContext,
): DraggedClipState {
  const { scroll, pps, duration, trackOrder, buildSnapTargets } = ctx;
  const dragMaxStart = resolveDragMaxStart(scroll, pps, duration);
  const scrollRectTop = scroll?.getBoundingClientRect().top ?? 0;
  const geometry =
    ctx.rowGeometry ?? getTimelineRowGeometry(ctx.rowHeights ?? ctx.trackOrder.map(() => TRACK_H));
  const originRow = geometry.getRowFromY(drag.originClientY - scrollRectTop + drag.originScrollTop);
  const aim = dragRowAim(drag, clientY, ctx, geometry);
  const currentRow = aim.rowFloat;
  // resolveTimelineMove's vertical axis is row indices, which is why the pointer
  // and scroll pixels are folded into originRow/currentRow above.
  const nextMove = resolveTimelineMove(
    {
      start: drag.element.start,
      track: drag.element.track,
      duration: drag.element.duration,
      originClientX: drag.originClientX,
      originRow,
      originScrollLeft: drag.originScrollLeft,
      currentScrollLeft: scroll?.scrollLeft ?? drag.originScrollLeft,
      pixelsPerSecond: pps,
      minStart: clampToHostStart(drag.element, 0),
      maxStart: dragMaxStart,
      trackOrder,
    },
    clientX,
    currentRow,
  );
  // The music track defines the beats, so it must not snap to them —
  // but it still snaps to the playhead and other clip edges.
  const targets = buildSnapTargets(
    drag.element.key ?? drag.element.id,
    !isMusicTrack(drag.element),
  );
  const snapped = snapMoveToTargets(
    nextMove.start,
    drag.element.duration,
    targets,
    pps,
    // Relaxed clamp: allow the snapped start past the content, up to the
    // rendered extent (see dragMaxStart) — the composition grows on commit.
    dragMaxStart + drag.element.duration,
    ctx.gridStep,
  );
  // A snap the saved clip would miss jumps on release, so the clip stays where the pointer put it.
  const target = snapTarget(snapped);
  const missed =
    target !== null && !guideIfSaved(drag.element, { start: snapped.start }, target, pps);
  const snap = missed ? { start: nextMove.start, snapTime: null, snapType: null } : snapped;
  // A group moves rigidly: the grabbed clip stops where any mover would cross its host's start.
  const group = resolveGroupDrag(drag, ctx);
  const dragKey = drag.element.key ?? drag.element.id;
  const passengers = ctx.elements.filter(
    (el) => (el.key ?? el.id) !== dragKey && group.moving.has(el.key ?? el.id),
  );
  const movers = [drag.element, ...passengers];
  const shift = heldAudioShiftRange(movers, ctx.elements, group.moving);
  const origin = drag.element.start;
  const floored = Math.max(snap.start, group.floor);
  const previewStart = origin + Math.max(shift.min, Math.min(floored - origin, shift.max));
  const placement = resolveDropPlacement(drag, aim, previewStart, nextMove.track, ctx, group);
  const placedShift = placement.start - origin;
  if (placedShift < shift.min - SHIFT_EPSILON_S || placedShift > shift.max + SHIFT_EPSILON_S) {
    return { ...drag, started: true };
  }
  const { track: previewTrack, insertRow } = placement;
  const guide = placement.start === snap.start ? snapTarget(snap) : null;
  return {
    ...drag,
    started: true,
    pointerClientX: clientX - (floored - previewStart) * pps,
    pointerClientY: clientY,
    previewStart: placement.start,
    previewTrack,
    // The lane the POINTER aims at (before the zone clamp): the commit reads it to
    // tell a deliberate vertical lane change from a horizontal drag.
    desiredTrack: nextMove.track,
    insertRow,
    snapTime: guide?.time ?? null,
    snapType: guide?.type ?? null,
  };
}

const snapTarget = (s: { snapTime: number | null; snapType: TimelineSnapType | null }) =>
  s.snapTime !== null && s.snapType !== null ? { time: s.snapTime, type: s.snapType } : null;

/** A snap's guide, kept only when the clip's edge as its file will save it is within a pixel of it. */
export function guideIfSaved(
  element: TimelineElement,
  clip: { start: number; duration?: number },
  target: TimelineSnapTarget | null,
  pps: number,
): TimelineSnapTarget | null {
  if (!target) return null;
  const saved = savedClipEdges(element, clip.start, clip.duration);
  const off = Math.min(Math.abs(saved.start - target.time), Math.abs(saved.end - target.time));
  return off * pps < 1 ? target : null;
}

/** One frame: the last visible frame of a clip sits just before its end time. */
const TRIM_END_FRAME_LEAD_S = 1 / STUDIO_PREVIEW_FPS;

/** The composition time whose frame a trim shows: the edge being dragged. */
export function trimPreviewTime(edge: "start" | "end", start: number, duration: number): number {
  return edge === "start" ? start : Math.max(start, start + duration - TRIM_END_FRAME_LEAD_S);
}

export interface ResizePreviewContext {
  scroll: HTMLDivElement | null;
  pps: number;
  buildSnapTargets: BuildSnapTargets;
  elements?: readonly TimelineElement[];
  gestureKeys?: ReadonlySet<string>;
  /** Seconds between the ruler's lines; 0 or absent when snapping is off. */
  gridStep?: number;
}

export interface ResizePreviewResult {
  originScrollLeft: number;
  previewStart: number;
  previewDuration: number;
  previewPlaybackStart?: number;
  /** The target the trimmed edge snapped to; null when the edge is free. */
  snapTime: number | null;
  snapType: TimelineSnapType | null;
}

/** Compute the trim preview for a pointer x (pure — the hook applies the state). */
// fallow-ignore-next-line complexity
export function computeResizePreview(
  resize: ResizingClipState,
  clientX: number,
  ctx: ResizePreviewContext,
): ResizePreviewResult {
  const { scroll, pps, buildSnapTargets } = ctx;
  // Scroll compensation: auto-scroll moves the content while the pointer stays
  // put, so fold the scroll delta into the pointer x (mirrors
  // resolveTimelineMove's originScrollLeft handling).
  const originScrollLeft = resize.originScrollLeft ?? scroll?.scrollLeft ?? 0;
  const effectiveClientX = clientX + ((scroll?.scrollLeft ?? originScrollLeft) - originScrollLeft);

  const sourceRemaining =
    resize.element.sourceDuration != null
      ? Math.max(
          0,
          (resize.element.sourceDuration - (resize.element.playbackStart ?? 0)) /
            Math.max(resize.element.playbackRate ?? 1, 0.1),
        )
      : Number.POSITIVE_INFINITY;
  const normalizedTag = resize.element.tag.toLowerCase();
  const canSeedPlaybackStart =
    resize.element.kind === "composition" || normalizedTag === "audio" || normalizedTag === "video";
  // Trim limit = available source media only — NOT the composition length.
  // Duration is content-driven (the comp grows/shrinks to fit on commit), so
  // capping a trim at the current comp end both blocked extending the last clip
  // rightward and, after a far move, collapsed a clip to the sliver between its
  // start and the comp end (the 8s→0.95s audio incident). Images/text/shapes
  // have no source, so they extend freely.
  const video = ctx.elements
    ? heldPartnerVideoBounds(resize.element, ctx.elements, ctx.gestureKeys ?? new Set())
    : null;
  const minStart = Math.max(clampToHostStart(resize.element, 0), video?.start ?? 0);
  const maxEnd = Math.min(resize.element.start + sourceRemaining, video?.end ?? Infinity);
  let nextResize = resolveTimelineResize(
    {
      start: resize.element.start,
      duration: resize.element.duration,
      originClientX: resize.originClientX,
      pixelsPerSecond: pps,
      minStart,
      maxEnd,
      playbackStart:
        resize.edge === "start" && canSeedPlaybackStart
          ? (resize.element.playbackStart ?? 0)
          : resize.element.playbackStart,
      playbackRate: resize.element.playbackRate,
    },
    resize.edge,
    effectiveClientX,
  );

  // Snap within the same limits resolveTimelineResize enforces. The music
  // track defines the beats, so it must not snap to them.
  const trimTargets = buildSnapTargets(
    resize.element.key ?? resize.element.id,
    !isMusicTrack(resize.element),
  );
  const gridStep = ctx.gridStep ?? 0;
  let snap: TimelineSnapTarget | null = null;
  const snapSecs = TIMELINE_SNAP_PX / Math.max(pps, 1);
  if (resize.edge === "end") {
    const edgeTime = nextResize.start + nextResize.duration;
    const { time: snapped, target } = snapTimelineTime(edgeTime, trimTargets, snapSecs, gridStep);
    // Stay within [start+minDuration, maxEnd] so the snap can't create a
    // degenerate clip or run past the source/composition limit.
    const snappedDuration = Math.round((snapped - nextResize.start) * 1000) / 1000;
    if (
      target &&
      snapped <= maxEnd + 1e-6 &&
      snappedDuration >= resolveTimelineMinDuration() - 1e-6
    ) {
      const onTarget =
        snapped === edgeTime ? nextResize : { ...nextResize, duration: snappedDuration };
      snap = guideIfSaved(resize.element, onTarget, target, pps);
      if (snap) nextResize = onTarget;
    }
  } else {
    const { time: snapped, target } = snapTimelineTime(
      nextResize.start,
      trimTargets,
      snapSecs,
      gridStep,
    );
    const clip = { ...nextResize, playbackRate: resize.element.playbackRate };
    const delta = snapped - nextResize.start;
    const bounds = clipStartTrimDeltaBounds(clip, minStart, resolveTimelineMinDuration());
    if (target && delta >= bounds.minDelta - 1e-6 && delta <= bounds.maxDelta + 1e-6) {
      const onTarget =
        snapped === nextResize.start ? nextResize : applyClipStartTrimDelta(clip, delta);
      snap = guideIfSaved(resize.element, onTarget, target, pps);
      if (snap) nextResize = onTarget;
    }
  }

  return {
    originScrollLeft,
    previewStart: nextResize.start,
    previewDuration: nextResize.duration,
    previewPlaybackStart: nextResize.playbackStart,
    snapTime: snap?.time ?? null,
    snapType: snap?.type ?? null,
  };
}

/**
 * Apply a rigid group-resize preview: fold the grabbed clip's raw delta into the
 * session and publish a coordinator-owned projection. Canonical elements stay
 * pristine until the exactly-once commit.
 */
export function previewGroupResize(
  session: TimelineGroupResizeSession,
  next: ResizePreviewResult,
  setResizeState: (
    v: ResizePreviewResult & { groupPreview: TimelineGroupResizeSession["changes"] },
  ) => void,
): void {
  const grabbedChange = applyTimelineGroupResizePreview(session, next);
  const previewStart = grabbedChange?.start ?? next.previewStart;
  const previewDuration = grabbedChange?.duration ?? next.previewDuration;
  // A member clamp can pull the grabbed edge off the raw snap target; then no guide.
  const edgeTime = session.edge === "end" ? previewStart + previewDuration : previewStart;
  const stillSnapped = next.snapTime != null && Math.abs(edgeTime - next.snapTime) < 1e-3;
  setResizeState({
    originScrollLeft: next.originScrollLeft,
    previewStart,
    previewDuration,
    previewPlaybackStart: grabbedChange?.playbackStart ?? next.previewPlaybackStart,
    snapTime: stillSnapped ? next.snapTime : null,
    snapType: stillSnapped ? next.snapType : null,
    groupPreview: session.changes,
  });
}