Skip to content

The open-source full-stack studio for Opus 5.5 motion video. Reverse engineering for any video. Code video with HTML: recreate, edit and render. BYOA + BYOK · Motion.md · Images, Video, Music & Voice.

16.5 KB
Raw Blame
// fallow-ignore-file code-duplication
// Snap computation engine — pure functions, zero React/DOM dependencies.
// All position values are in overlay-space (screen) pixels.

export const SNAP_THRESHOLD_PX = 6;
/**
 * Pointer travel a MOVE must reach before snapping is allowed to touch it.
 *
 * An element resting within the threshold of a guide is already "snappable", so
 * a snap computed on the very first frame displaces it by up to the threshold
 * while the pointer has moved nothing — pick a selection up and the whole thing
 * teleports before you have dragged at all. Snapping is meant to pull toward a
 * guide as the user drags, so it does not participate until the drag is real.
 * The value matches the distance a drag must cover to count as a drag rather
 * than a click, so nothing below it moves anything.
 */
const SNAP_ENGAGE_TRAVEL_PX = 4;

/** Whether a move of this size has travelled far enough for snapping to apply. */
export function snapEngagedForTravel(dx: number, dy: number): boolean {
  return Math.hypot(dx, dy) >= SNAP_ENGAGE_TRAVEL_PX;
}

const EQUIDISTANCE_TOLERANCE_PX = 1;

// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------

export interface SnapEdge {
  position: number;
  source: "grid";
  id: string;
}

export interface SnapTarget {
  left: number;
  top: number;
  right: number;
  bottom: number;
  centerX: number;
  centerY: number;
  id: string;
}

export interface SnapGuide {
  axis: "x" | "y";
  position: number;
  /** Extent of the guide line (min of involved elements). */
  from: number;
  /** Extent of the guide line (max of involved elements). */
  to: number;
}

export interface SpacingGuide {
  axis: "x" | "y";
  /** Position of the gap (start of gap). */
  position: number;
  /** Size of the gap in pixels. */
  size: number;
  /** Extent for rendering the indicator. */
  from: number;
  /** Extent for rendering the indicator. */
  to: number;
}

export interface SnapResult {
  dx: number;
  dy: number;
  guides: SnapGuide[];
  spacingGuides: SpacingGuide[];
}

// ---------------------------------------------------------------------------
// Rect shorthand used across the public API
// ---------------------------------------------------------------------------

export interface Rect {
  left: number;
  top: number;
  width: number;
  height: number;
}

// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------

function rectRight(r: Rect): number {
  return r.left + r.width;
}

function rectBottom(r: Rect): number {
  return r.top + r.height;
}

function rectCenterX(r: Rect): number {
  return r.left + r.width / 2;
}

function rectCenterY(r: Rect): number {
  return r.top + r.height / 2;
}

// ---------------------------------------------------------------------------
// Public API
// ---------------------------------------------------------------------------

/**
 * Convert overlay rects to snap targets with precomputed edges & centers.
 */
export function extractSnapTargets(entries: Array<{ rect: Rect; id: string }>): SnapTarget[] {
  return entries.map(({ rect: r, id }) => ({
    left: r.left,
    top: r.top,
    right: rectRight(r),
    bottom: rectBottom(r),
    centerX: rectCenterX(r),
    centerY: rectCenterY(r),
    id,
  }));
}

/**
 * Create a snap target from the composition/overlay boundary.
 */
export function buildCompositionSnapTarget(rect: Rect): SnapTarget {
  return {
    left: rect.left,
    top: rect.top,
    right: rectRight(rect),
    bottom: rectBottom(rect),
    centerX: rectCenterX(rect),
    centerY: rectCenterY(rect),
    id: "composition",
  };
}

/**
 * Generate grid-line snap edges.
 * `gridSpacing` is in composition pixels; `scale` converts to overlay pixels.
 * X edges are vertical grid lines; Y edges are horizontal grid lines.
 */
export function buildGridSnapEdges(
  compositionRect: Rect,
  gridSpacing: number,
  scale: number,
): { x: SnapEdge[]; y: SnapEdge[] } {
  const xEdges: SnapEdge[] = [];
  const yEdges: SnapEdge[] = [];

  if (gridSpacing <= 0 || scale <= 0) return { x: xEdges, y: yEdges };

  const step = gridSpacing * scale;

  // Vertical grid lines (x-axis edges)
  let x = compositionRect.left + step;
  const xMax = compositionRect.left + compositionRect.width;
  let idx = 0;
  while (x < xMax) {
    xEdges.push({ position: x, source: "grid", id: `grid-x-${idx}` });
    x += step;
    idx++;
  }

  // Horizontal grid lines (y-axis edges)
  let y = compositionRect.top + step;
  const yMax = compositionRect.top + compositionRect.height;
  idx = 0;
  while (y < yMax) {
    yEdges.push({ position: y, source: "grid", id: `grid-y-${idx}` });
    y += step;
    idx++;
  }

  return { x: xEdges, y: yEdges };
}

// ---------------------------------------------------------------------------
// Internal snap resolution helpers
// ---------------------------------------------------------------------------

interface EdgeCandidate {
  /** Distance the moving rect must adjust to align with this edge. */
  adjustment: number;
  /** Absolute distance (for comparison). */
  distance: number;
  /** Position of the guide line. */
  guidePosition: number;
  /** Source of the match. */
  source: "element" | "composition" | "grid";
  /** Id of the target or grid line. */
  targetId: string;
}

/**
 * Collect edge candidates on a single axis for a moving rect.
 * `movingEdges` are the edges of the moving rect (e.g. left, centerX, right).
 * `targetEdges` are the corresponding edges on each target.
 */
// fallow-ignore-next-line complexity
function collectCandidates(
  movingEdges: number[],
  targets: SnapTarget[],
  targetEdgeExtractor: (t: SnapTarget) => number[],
  gridEdges: SnapEdge[] | undefined,
  threshold: number,
): EdgeCandidate[] {
  const candidates: EdgeCandidate[] = [];

  for (const target of targets) {
    const tEdges = targetEdgeExtractor(target);
    for (const mEdge of movingEdges) {
      for (const tEdge of tEdges) {
        const adjustment = tEdge - mEdge;
        const distance = Math.abs(adjustment);
        if (distance <= threshold) {
          candidates.push({
            adjustment,
            distance,
            guidePosition: tEdge,
            source: target.id === "composition" ? "composition" : "element",
            targetId: target.id,
          });
        }
      }
    }
  }

  if (gridEdges) {
    for (const edge of gridEdges) {
      for (const mEdge of movingEdges) {
        const adjustment = edge.position - mEdge;
        const distance = Math.abs(adjustment);
        if (distance <= threshold) {
          candidates.push({
            adjustment,
            distance,
            guidePosition: edge.position,
            source: "grid",
            targetId: edge.id,
          });
        }
      }
    }
  }

  return candidates;
}

/**
 * From a list of candidates, pick the best adjustment:
 * - Element/composition matches take priority over grid matches.
 * - Among equal-priority matches, pick the smallest distance.
 * - Return all guides that share the winning adjustment.
 */
function pickBest(candidates: EdgeCandidate[]): {
  adjustment: number;
  matches: EdgeCandidate[];
} | null {
  if (candidates.length === 0) return null;

  // Partition into element/composition vs grid
  const elementCandidates = candidates.filter(
    (c) => c.source === "element" || c.source === "composition",
  );
  const gridCandidates = candidates.filter((c) => c.source === "grid");

  // Pick the pool with the best (smallest distance) match, preferring element
  let pool: EdgeCandidate[];
  const bestElem = elementCandidates.length
    ? Math.min(...elementCandidates.map((c) => c.distance))
    : Infinity;
  const bestGrid = gridCandidates.length
    ? Math.min(...gridCandidates.map((c) => c.distance))
    : Infinity;

  if (bestElem <= bestGrid) {
    pool = elementCandidates;
  } else {
    pool = gridCandidates;
  }

  const minDist = Math.min(...pool.map((c) => c.distance));
  const winners = pool.filter((c) => c.distance === minDist);

  // When candidates at the same distance pull in opposite directions (e.g.
  // element centered between two equidistant targets), suppress the snap
  // entirely — the element holds where the user dragged it.
  const hasPositive = winners.some((c) => c.adjustment > 0);
  const hasNegative = winners.some((c) => c.adjustment < 0);
  if (hasPositive && hasNegative) return null;

  const adjustment = winners[0].adjustment;
  const matches = pool.filter((c) => c.adjustment === adjustment);
  return { adjustment, matches };
}

// ---------------------------------------------------------------------------
// Guide extent computation
// ---------------------------------------------------------------------------

function computeGuideExtent(
  axis: "x" | "y",
  movingRect: Rect,
  matchedTargetIds: string[],
  targetMap: Map<string, SnapTarget>,
): { from: number; to: number } {
  const extents: number[] = [];

  if (axis === "x") {
    extents.push(movingRect.top, rectBottom(movingRect));
    for (const tid of matchedTargetIds) {
      const t = targetMap.get(tid);
      if (t) extents.push(t.top, t.bottom);
    }
  } else {
    extents.push(movingRect.left, rectRight(movingRect));
    for (const tid of matchedTargetIds) {
      const t = targetMap.get(tid);
      if (t) extents.push(t.left, t.right);
    }
  }

  return { from: Math.min(...extents), to: Math.max(...extents) };
}

// ---------------------------------------------------------------------------
// Shared guide-building logic
// ---------------------------------------------------------------------------

function buildGuidesFromMatches(
  bestX: { adjustment: number; matches: EdgeCandidate[] } | null,
  bestY: { adjustment: number; matches: EdgeCandidate[] } | null,
  adjustedRect: Rect,
  targetMap: Map<string, SnapTarget>,
): SnapGuide[] {
  const guides: SnapGuide[] = [];

  for (const [axis, best] of [
    ["x", bestX],
    ["y", bestY],
  ] as const) {
    if (!best) continue;
    const seenPositions = new Set<number>();
    for (const m of best.matches) {
      if (seenPositions.has(m.guidePosition)) continue;
      seenPositions.add(m.guidePosition);
      const targetIds = best.matches
        .filter((mm) => mm.guidePosition === m.guidePosition)
        .map((mm) => mm.targetId);
      const extent = computeGuideExtent(axis, adjustedRect, targetIds, targetMap);
      guides.push({ axis, position: m.guidePosition, from: extent.from, to: extent.to });
    }
  }

  return guides;
}

const DISABLED_RESULT = (dx: number, dy: number): SnapResult => ({
  dx,
  dy,
  guides: [],
  spacingGuides: [],
});

// ---------------------------------------------------------------------------
// resolveSnapAdjustment — main drag snap entry point
// ---------------------------------------------------------------------------

// fallow-ignore-next-line complexity
export function resolveSnapAdjustment(input: {
  movingRect: Rect;
  proposedDx: number;
  proposedDy: number;
  targets: SnapTarget[];
  gridEdges?: { x: SnapEdge[]; y: SnapEdge[] };
  threshold: number;
  disabled: boolean;
  /** Set when the gesture has not travelled far enough for snapping yet. */
  disabledForTravel?: boolean;
  lockedAxis?: "x" | "y";
}): SnapResult {
  if (input.disabled || input.disabledForTravel || input.threshold <= 0) {
    return DISABLED_RESULT(input.proposedDx, input.proposedDy);
  }

  const mr = input.movingRect;
  const proposed: Rect = {
    left: mr.left + input.proposedDx,
    top: mr.top + input.proposedDy,
    width: mr.width,
    height: mr.height,
  };

  const xCandidates = collectCandidates(
    [proposed.left, rectCenterX(proposed), rectRight(proposed)],
    input.targets,
    (t) => [t.left, t.centerX, t.right],
    input.gridEdges?.x,
    input.threshold,
  );
  const yCandidates = collectCandidates(
    [proposed.top, rectCenterY(proposed), rectBottom(proposed)],
    input.targets,
    (t) => [t.top, t.centerY, t.bottom],
    input.gridEdges?.y,
    input.threshold,
  );

  const bestX = input.lockedAxis === "x" ? null : pickBest(xCandidates);
  const bestY = input.lockedAxis === "y" ? null : pickBest(yCandidates);
  const adjustedDx = input.proposedDx + (bestX?.adjustment ?? 0);
  const adjustedDy = input.proposedDy + (bestY?.adjustment ?? 0);

  const adjustedRect: Rect = {
    left: mr.left + adjustedDx,
    top: mr.top + adjustedDy,
    width: mr.width,
    height: mr.height,
  };

  const targetMap = new Map(input.targets.map((t) => [t.id, t]));

  return {
    dx: adjustedDx,
    dy: adjustedDy,
    guides: buildGuidesFromMatches(bestX, bestY, adjustedRect, targetMap),
    spacingGuides: [], // computed separately via resolveEquidistanceGuides
  };
}

// ---------------------------------------------------------------------------
// resolveGuideLineRect — screen rect for rendering a snap guide line
// ---------------------------------------------------------------------------

/**
 * Full-length guide line spanning the composition: a vertical line (axis "x")
 * runs the composition's height at the snapped x position; a horizontal line
 * (axis "y") runs the composition's width. `composition` is the composition
 * rect in overlay space — guide positions are already overlay-space, so the
 * line must be offset by the composition's left/top (the canvas is usually
 * letterboxed inside the overlay).
 */
export function resolveGuideLineRect(guide: SnapGuide, composition: Rect): Rect {
  if (guide.axis === "x") {
    return { left: guide.position, top: composition.top, width: 1, height: composition.height };
  }
  return { left: composition.left, top: guide.position, width: composition.width, height: 1 };
}

// ---------------------------------------------------------------------------
// resolveEquidistanceGuides
// ---------------------------------------------------------------------------

// fallow-ignore-next-line complexity
export function resolveEquidistanceGuides(input: {
  movingRect: Rect;
  targets: SnapTarget[];
  threshold: number;
}): SpacingGuide[] {
  const guides: SpacingGuide[] = [];
  const mr = input.movingRect;

  const movingTarget: SnapTarget = {
    left: mr.left,
    top: mr.top,
    right: rectRight(mr),
    bottom: rectBottom(mr),
    centerX: rectCenterX(mr),
    centerY: rectCenterY(mr),
    id: "\0__snap_moving__",
  };

  const allTargets = [...input.targets, movingTarget];

  // X axis: sort by centerX, scan for equal gaps between adjacent triplets
  const sortedX = [...allTargets].sort((a, b) => a.centerX - b.centerX);
  for (let i = 0; i < sortedX.length - 2; i++) {
    const a = sortedX[i];
    const b = sortedX[i + 1];
    const c = sortedX[i + 2];

    // Gap between A and B = B.left - A.right
    const gapAB = b.left - a.right;
    const gapBC = c.left - b.right;

    if (gapAB < 0 || gapBC < 0) continue; // overlapping elements

    // Check if the moving rect is one of A, B, or C
    const involvesMoving =
      a.id === "\0__snap_moving__" || b.id === "\0__snap_moving__" || c.id === "\0__snap_moving__";
    if (!involvesMoving) continue;

    if (Math.abs(gapAB - gapBC) <= EQUIDISTANCE_TOLERANCE_PX) {
      const crossMin = Math.min(a.top, b.top, c.top);
      const crossMax = Math.max(a.bottom, b.bottom, c.bottom);

      // Gap A-B
      guides.push({
        axis: "x",
        position: a.right,
        size: gapAB,
        from: crossMin,
        to: crossMax,
      });
      // Gap B-C
      guides.push({
        axis: "x",
        position: b.right,
        size: gapBC,
        from: crossMin,
        to: crossMax,
      });
    }
  }

  // Y axis: sort by centerY, scan for equal gaps between adjacent triplets
  const sortedY = [...allTargets].sort((a, b) => a.centerY - b.centerY);
  for (let i = 0; i < sortedY.length - 2; i++) {
    const a = sortedY[i];
    const b = sortedY[i + 1];
    const c = sortedY[i + 2];

    const gapAB = b.top - a.bottom;
    const gapBC = c.top - b.bottom;

    if (gapAB < 0 || gapBC < 0) continue;

    const involvesMoving =
      a.id === "\0__snap_moving__" || b.id === "\0__snap_moving__" || c.id === "\0__snap_moving__";
    if (!involvesMoving) continue;

    if (Math.abs(gapAB - gapBC) <= EQUIDISTANCE_TOLERANCE_PX) {
      const crossMin = Math.min(a.left, b.left, c.left);
      const crossMax = Math.max(a.right, b.right, c.right);

      guides.push({
        axis: "y",
        position: a.bottom,
        size: gapAB,
        from: crossMin,
        to: crossMax,
      });
      guides.push({
        axis: "y",
        position: b.bottom,
        size: gapBC,
        from: crossMin,
        to: crossMax,
      });
    }
  }

  return guides;
}