@hyperframes/studio 0.7.107 → 0.7.108

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

@@ -0,0 +1,82 @@
+import { describe, expect, it } from "vitest";
+import { generateShape } from "./automationShapes";
+import { resolveAutomationRange, VOLUME_RANGE } from "@hyperframes/core/audio-automation";
+import type { HfAutomationLane } from "@hyperframes/core/audio-automation";
+
+const flat: HfAutomationLane = {
+  target: "volume",
+  points: [
+    { t: 0, v: 0.8 },
+    { t: 6, v: 0.8 },
+  ],
+};
+
+describe("generateShape", () => {
+  it("ramp-up fades in from the floor to the envelope's own value", () => {
+    const pts = generateShape({ shape: "ramp-up", lane: flat, range: VOLUME_RANGE, t0: 1, t1: 3 });
+    expect(pts).toEqual([
+      { t: 1, v: VOLUME_RANGE.min },
+      { t: 3, v: 0.8 },
+    ]);
+  });
+
+  it("ramp-down fades out from the envelope's own value", () => {
+    const pts = generateShape({
+      shape: "ramp-down",
+      lane: flat,
+      range: VOLUME_RANGE,
+      t0: 1,
+      t1: 3,
+    });
+    expect(pts).toEqual([
+      { t: 1, v: 0.8 },
+      { t: 3, v: VOLUME_RANGE.min },
+    ]);
+  });
+
+  it("swell peaks at range max mid-selection, smoothed", () => {
+    const pts = generateShape({ shape: "swell", lane: flat, range: VOLUME_RANGE, t0: 1, t1: 3 });
+    expect(pts).toHaveLength(3);
+    expect(pts[1]).toMatchObject({ t: 2, v: VOLUME_RANGE.max });
+    expect(pts[0]?.curve).toBeDefined(); // eased, not a triangle
+  });
+
+  it("dip ducks to a quarter of the edge value in unit space", () => {
+    const pts = generateShape({ shape: "dip", lane: flat, range: VOLUME_RANGE, t0: 1, t1: 3 });
+    // volume is linear 0..1: unit(0.8) = 0.8, floor = 0.2
+    expect(pts[1]?.v).toBeCloseTo(0.2, 5);
+  });
+
+  it("computes in unit space on a log lane", () => {
+    const range = resolveAutomationRange("fx.n1.frequency", {
+      version: 1,
+      nodes: [{ type: "lowpass", id: "n1", params: {} }],
+    });
+    expect(range?.scale).toBe("log");
+    if (!range) return;
+    const lane: HfAutomationLane = {
+      target: "fx.n1.frequency",
+      points: [
+        { t: 0, v: 2000 },
+        { t: 6, v: 2000 },
+      ],
+    };
+    const pts = generateShape({ shape: "dip", lane, range, t0: 1, t1: 3 });
+    const floor = pts[1]?.v ?? 0;
+    // A quarter of the way up the LOG axis, not 500 Hz.
+    expect(floor).toBeGreaterThan(range.min);
+    expect(floor).toBeLessThan(2000 * 0.25);
+  });
+
+  it("uses the range default when the lane is empty", () => {
+    const empty: HfAutomationLane = { target: "volume", points: [] };
+    const pts = generateShape({
+      shape: "ramp-down",
+      lane: empty,
+      range: VOLUME_RANGE,
+      t0: 1,
+      t1: 3,
+    });
+    expect(pts[0]?.v).toBe(VOLUME_RANGE.default);
+  });
+});

package/src/player/components/automationShapes.ts

@@ -0,0 +1,70 @@
+/**
+ * The utility shapes a video author reaches for: fade in, fade out, swell,
+ * duck. One shape scaled to the selection — this is not a DAW, nobody needs a
+ * tempo-synced LFO. Edge values come from the envelope itself so a shape
+ * splices into whatever is already there; vertical maths runs in unit space so
+ * a log knob (frequency) behaves like the lane that draws it.
+ */
+import {
+  sampleAutomationLane,
+  type AutomationRange,
+  type HfAutomationLane,
+  type HfAutomationPoint,
+} from "@hyperframes/core/audio-automation";
+import { fromUnit, toUnit } from "./automationLaneGeometry";
+
+export type AutomationShapeId = "ramp-up" | "ramp-down" | "swell" | "dip";
+
+export const AUTOMATION_SHAPES: ReadonlyArray<{ id: AutomationShapeId; label: string }> = [
+  { id: "ramp-up", label: "Ramp up" },
+  { id: "ramp-down", label: "Ramp down" },
+  { id: "swell", label: "Swell" },
+  { id: "dip", label: "Dip" },
+];
+
+/** Ease used on the segments entering/leaving a swell or dip midpoint. */
+const SMOOTH = 0.4;
+/** A dip ducks to this fraction of the edge value, in unit space. */
+const DIP_FLOOR = 0.25;
+
+function edgeValue(lane: HfAutomationLane, range: AutomationRange, t: number): number {
+  if (lane.points.length === 0) return range.default ?? (range.min + range.max) / 2;
+  return sampleAutomationLane(lane, t, range.scale);
+}
+
+export function generateShape(input: {
+  shape: AutomationShapeId;
+  lane: HfAutomationLane;
+  range: AutomationRange;
+  t0: number;
+  t1: number;
+}): HfAutomationPoint[] {
+  const { shape, lane, range, t0, t1 } = input;
+  const v0 = edgeValue(lane, range, t0);
+  const v1 = edgeValue(lane, range, t1);
+  const mid = (t0 + t1) / 2;
+  switch (shape) {
+    case "ramp-up":
+      return [
+        { t: t0, v: range.min },
+        { t: t1, v: v1 },
+      ];
+    case "ramp-down":
+      return [
+        { t: t0, v: v0 },
+        { t: t1, v: range.min },
+      ];
+    case "swell":
+      return [
+        { t: t0, v: v0, curve: SMOOTH },
+        { t: mid, v: range.max, curve: -SMOOTH },
+        { t: t1, v: v1 },
+      ];
+    case "dip":
+      return [
+        { t: t0, v: v0, curve: -SMOOTH },
+        { t: mid, v: fromUnit(range, toUnit(range, v0) * DIP_FLOOR), curve: SMOOTH },
+        { t: t1, v: v1 },
+      ];
+  }
+}

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

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import { simplifyPoints } from "./automationSimplify";
+import { VOLUME_RANGE } from "@hyperframes/core/audio-automation";
+import { toUnit } from "./automationLaneGeometry";
+import type { HfAutomationPoint } from "@hyperframes/core/audio-automation";
+
+describe("simplifyPoints", () => {
+  it("collapses collinear runs to their endpoints", () => {
+    const line: HfAutomationPoint[] = Array.from({ length: 50 }, (_, i) => ({
+      t: i * 0.1,
+      v: 1 - i * 0.01,
+    }));
+    const out = simplifyPoints(line, VOLUME_RANGE);
+    expect(out).toHaveLength(2);
+    expect(out[0]).toEqual(line[0]);
+    expect(out[out.length - 1]).toEqual(line[line.length - 1]);
+  });
+
+  it("keeps every survivor within epsilon of the original", () => {
+    const wave: HfAutomationPoint[] = Array.from({ length: 100 }, (_, i) => ({
+      t: i * 0.05,
+      v: 0.5 + 0.4 * Math.sin(i * 0.2),
+    }));
+    const out = simplifyPoints(wave, VOLUME_RANGE, 0.02);
+    expect(out.length).toBeLessThan(wave.length / 2);
+    // Every dropped point must sit within epsilon (unit space) of the
+    // simplified polyline — check by linear interpolation between survivors.
+    for (const p of wave) {
+      const rIdx = out.findIndex((q) => q.t >= p.t);
+      const b = out[rIdx] ?? out[out.length - 1];
+      const a = out[rIdx - 1] ?? b;
+      if (!a || !b) continue;
+      const span = b.t - a.t;
+      const f = span > 0 ? (p.t - a.t) / span : 0;
+      const approx =
+        toUnit(VOLUME_RANGE, a.v) + f * (toUnit(VOLUME_RANGE, b.v) - toUnit(VOLUME_RANGE, a.v));
+      expect(Math.abs(approx - toUnit(VOLUME_RANGE, p.v))).toBeLessThanOrEqual(0.021);
+    }
+  });
+
+  it("returns short inputs untouched", () => {
+    const two: HfAutomationPoint[] = [
+      { t: 0, v: 1 },
+      { t: 1, v: 0 },
+    ];
+    expect(simplifyPoints(two, VOLUME_RANGE)).toEqual(two);
+  });
+});

package/src/player/components/automationSimplify.ts

@@ -0,0 +1,51 @@
+/**
+ * Ramer–Douglas–Peucker over an envelope's points, deviation measured
+ * VERTICALLY in unit space. Vertical (not perpendicular) because an envelope
+ * is a function of time — what matters is how far the value strays, and it
+ * keeps the metric independent of the time axis' units. Exists for dense
+ * producers: carve output and heavy hand edits.
+ */
+import type { AutomationRange, HfAutomationPoint } from "@hyperframes/core/audio-automation";
+import { toUnit } from "./automationLaneGeometry";
+
+export function simplifyPoints(
+  points: HfAutomationPoint[],
+  range: AutomationRange,
+  epsilon = 0.02,
+): HfAutomationPoint[] {
+  if (points.length <= 2) return points;
+  const keep = new Array<boolean>(points.length).fill(false);
+  const last = keep.length - 1;
+  keep[0] = true;
+  keep[last] = true;
+
+  const stack: Array<[number, number]> = [[0, last]];
+  while (stack.length > 0) {
+    const seg = stack.pop();
+    if (!seg) break;
+    const [a, b] = seg;
+    const pa = points[a];
+    const pb = points[b];
+    if (!pa || !pb || b - a < 2) continue;
+    const ua = toUnit(range, pa.v);
+    const ub = toUnit(range, pb.v);
+    const span = pb.t - pa.t;
+    let worst = -1;
+    let worstDev = epsilon;
+    for (let i = a + 1; i < b; i += 1) {
+      const p = points[i];
+      if (!p) continue;
+      const f = span > 0 ? (p.t - pa.t) / span : 0;
+      const dev = Math.abs(toUnit(range, p.v) - (ua + f * (ub - ua)));
+      if (dev > worstDev) {
+        worstDev = dev;
+        worst = i;
+      }
+    }
+    if (worst >= 0) {
+      keep[worst] = true;
+      stack.push([a, worst], [worst, b]);
+    }
+  }
+  return points.filter((_, i) => keep[i]);
+}

package/src/player/components/timelineClipGestureHandlers.ts

@@ -0,0 +1,223 @@
+import type { PointerEvent as ReactPointerEvent, MouseEvent as ReactMouseEvent } from "react";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import type { DraggedClipState, ResizingClipState, BlockedClipState } from "./useTimelineClipDrag";
+import {
+  resolveBlockedTimelineEditIntent,
+  type BlockedTimelineEditIntent,
+} from "./timelineEditing";
+import type { TimelineEditCapabilities } from "./timelineEditCapabilities";
+import type { TimelineEditCallbacks } from "./timelineCallbacks";
+import { CLIP_HANDLE_W } from "./timelineLayout";
+import { SPLIT_BOUNDARY_EPSILON_S } from "../../utils/timelineElementSplit";
+
+export interface ClipGestureDeps {
+  pps: number;
+  onResizeElement?: TimelineEditCallbacks["onResizeElement"];
+  onMoveElement?: TimelineEditCallbacks["onMoveElement"];
+  onRazorSplit?: (element: TimelineElement, splitTime: number) => Promise<void> | void;
+  onRazorSplitAll?: (splitTime: number) => Promise<void> | void;
+  blockedClipRef: React.RefObject<BlockedClipState | null>;
+  shiftClickClipRef: React.RefObject<{
+    element: TimelineElement;
+    anchorX: number;
+    anchorY: number;
+  } | null>;
+  suppressClickRef: React.RefObject<boolean>;
+  scrollRef: React.RefObject<HTMLDivElement | null>;
+  setShowPopover(v: boolean): void;
+  setRangeSelection(v: null): void;
+  setResizingClip(v: ResizingClipState | null): void;
+  setDraggedClip(v: DraggedClipState | null): void;
+  setSelectedElementId(id: string | null): void;
+  onSelectElement?: (element: TimelineElement | null) => void;
+}
+
+/** Whether a resize-handle drag on `edge` is allowed to begin at all. */
+function canStartResize(
+  edge: "start" | "end",
+  e: ReactPointerEvent,
+  capabilities: TimelineEditCapabilities,
+  onResizeElement: ClipGestureDeps["onResizeElement"],
+): boolean {
+  if (e.button !== 0 || e.shiftKey || !onResizeElement) return false;
+  if (edge === "start") return capabilities.canTrimStart;
+  return capabilities.canTrimEnd;
+}
+
+type PointerDownAction =
+  | { kind: "ignore" }
+  | { kind: "arm-shift-click" }
+  | { kind: "block"; intent: BlockedTimelineEditIntent; rect: DOMRect }
+  | { kind: "move"; rect: DOMRect };
+
+/**
+ * A hit-tested intent is "blocked" when the pointer landed on a smaller
+ * target than the gesture it implies would need — e.g. a resize handle too
+ * narrow to grab reliably — AND that gesture is actually wired up. An intent
+ * with nowhere to go (no matching callback) is not blocking anything.
+ */
+function isIntentBlocked(
+  intent: BlockedTimelineEditIntent | null,
+  onResizeElement: ClipGestureDeps["onResizeElement"],
+  onMoveElement: ClipGestureDeps["onMoveElement"],
+): intent is BlockedTimelineEditIntent {
+  if (!intent) return false;
+  return intent === "move" ? Boolean(onMoveElement) : Boolean(onResizeElement);
+}
+
+/**
+ * What a pointerdown on a clip bar means, before any state is touched. Kept
+ * pure (no refs, no store writes) so the branching that decides move vs.
+ * resize-handle vs. blocked-by-a-smaller-hit-target lives in one place,
+ * separate from the side effects `onPointerDown` below performs for it.
+ */
+function resolvePointerDownAction(
+  e: ReactPointerEvent,
+  capabilities: TimelineEditCapabilities,
+  onResizeElement: ClipGestureDeps["onResizeElement"],
+  onMoveElement: ClipGestureDeps["onMoveElement"],
+): PointerDownAction {
+  if (e.button !== 0) return { kind: "ignore" };
+  if (usePlayerStore.getState().activeTool === "razor") return { kind: "ignore" };
+  if (e.shiftKey) return { kind: "arm-shift-click" };
+
+  const rect = (e.currentTarget as HTMLElement).getBoundingClientRect();
+  const intent = resolveBlockedTimelineEditIntent({
+    width: rect.width,
+    offsetX: e.clientX - rect.left,
+    handleWidth: CLIP_HANDLE_W,
+    capabilities,
+  });
+  if (isIntentBlocked(intent, onResizeElement, onMoveElement)) {
+    return { kind: "block", intent, rect };
+  }
+
+  if (!onMoveElement || !capabilities.canMove) return { kind: "ignore" };
+  return { kind: "move", rect };
+}
+
+/**
+ * The three pointer/click gestures a clip bar answers to. Factored out of
+ * TimelineLanes' render loop — one call per rendered clip, closing over that
+ * clip's own `el`/`elementKey`/`previewElement`/`capabilities` — so the huge
+ * per-track map body reads as JSX instead of ~120 lines of gesture logic.
+ */
+export function createClipGestureHandlers(
+  el: TimelineElement,
+  elementKey: string,
+  previewElement: TimelineElement,
+  capabilities: TimelineEditCapabilities,
+  deps: ClipGestureDeps,
+) {
+  const {
+    pps,
+    onResizeElement,
+    onMoveElement,
+    onRazorSplit,
+    onRazorSplitAll,
+    blockedClipRef,
+    shiftClickClipRef,
+    suppressClickRef,
+    scrollRef,
+    setShowPopover,
+    setRangeSelection,
+    setResizingClip,
+    setDraggedClip,
+    setSelectedElementId,
+    onSelectElement,
+  } = deps;
+
+  const onResizeStart = (edge: "start" | "end", e: ReactPointerEvent): void => {
+    if (!canStartResize(edge, e, capabilities, onResizeElement)) return;
+    e.stopPropagation();
+    blockedClipRef.current = null;
+    setShowPopover(false);
+    setRangeSelection(null);
+    setResizingClip({
+      pointerId: e.pointerId,
+      element: el,
+      edge,
+      originClientX: e.clientX,
+      originScrollLeft: scrollRef.current?.scrollLeft ?? 0,
+      previewStart: el.start,
+      previewDuration: el.duration,
+      previewPlaybackStart: el.playbackStart,
+      started: false,
+    });
+  };
+
+  const onPointerDown = (e: ReactPointerEvent): void => {
+    const action = resolvePointerDownAction(e, capabilities, onResizeElement, onMoveElement);
+    if (action.kind === "ignore") return;
+
+    if (action.kind === "arm-shift-click") {
+      shiftClickClipRef.current = { element: el, anchorX: e.clientX, anchorY: e.clientY };
+      return;
+    }
+
+    if (action.kind === "block") {
+      blockedClipRef.current = {
+        pointerId: e.pointerId,
+        element: el,
+        intent: action.intent,
+        originClientX: e.clientX,
+        originClientY: e.clientY,
+        started: false,
+      };
+      return;
+    }
+
+    const { rect } = action;
+    blockedClipRef.current = null;
+    setShowPopover(false);
+    setRangeSelection(null);
+    setDraggedClip({
+      pointerId: e.pointerId,
+      element: el,
+      originClientX: e.clientX,
+      originClientY: e.clientY,
+      originScrollLeft: scrollRef.current?.scrollLeft ?? 0,
+      originScrollTop: scrollRef.current?.scrollTop ?? 0,
+      pointerClientX: e.clientX,
+      pointerClientY: e.clientY,
+      pointerOffsetX: e.clientX - rect.left,
+      pointerOffsetY: e.clientY - rect.top,
+      previewStart: el.start,
+      previewTrack: el.track,
+      desiredTrack: el.track,
+      insertRow: null,
+      snapTime: null,
+      snapType: null,
+      started: false,
+    });
+  };
+
+  const onClick = (e: ReactMouseEvent): void => {
+    e.stopPropagation();
+    if (suppressClickRef.current) return;
+    const { activeTool } = usePlayerStore.getState();
+    if (activeTool === "razor" && onRazorSplit) {
+      const clipRect = (e.currentTarget as HTMLElement).getBoundingClientRect();
+      const clickOffsetX = e.clientX - clipRect.left;
+      const splitTime = previewElement.start + clickOffsetX / pps;
+      const clampedTime = Math.max(
+        previewElement.start + SPLIT_BOUNDARY_EPSILON_S,
+        Math.min(
+          previewElement.start + previewElement.duration - SPLIT_BOUNDARY_EPSILON_S,
+          splitTime,
+        ),
+      );
+      if (e.shiftKey && onRazorSplitAll) {
+        onRazorSplitAll(clampedTime);
+      } else {
+        onRazorSplit(el, clampedTime);
+      }
+      return;
+    }
+    // Clip selection is idempotent; empty timeline space owns deselection.
+    setSelectedElementId(elementKey);
+    onSelectElement?.(el);
+  };
+
+  return { onResizeStart, onPointerDown, onClick };
+}

package/src/player/components/timelineLaneProps.ts

@@ -9,6 +9,8 @@ import type { DraggedClipState, ResizingClipState, BlockedClipState } from "./us
 import type { TimelineClipIndex, TimelineTimeRange } from "../lib/timelineClipIndex";
 import type { TimelineRowGeometry } from "./timelineLayout";
 import type { TimelineVirtualRow } from "./useTimelineVirtualRows";
+import type { MultiDragPreviewInput } from "./timelineMultiDragPreview";
+import type { TimelineEditCallbacks } from "./timelineCallbacks";
 import type { TimelineLogicalRow } from "./timelineKeyboardNavigation";
 import type { TimelineClipRenderContext } from "./TimelineTypes";
 
@@ -98,3 +100,20 @@ export interface TimelineLaneBaseProps {
   onContextMenuLane?: (e: React.MouseEvent, track: number, time: number) => void;
   beatAnalysis?: MusicBeatAnalysis | null;
 }
+
+/**
+ * {@link TimelineLaneBaseProps} plus the handful of props only the lane
+ * renderer ({@link import("./TimelineLanes")}) itself needs — the drag-preview
+ * state and the edit callbacks TimelineCanvas does not otherwise touch.
+ */
+export interface TimelineLanesProps extends TimelineLaneBaseProps {
+  /** Live-derived by TimelineCanvas from {@link TimelineLaneBaseProps.draggedClip}. */
+  draggedElement: TimelineElement | null;
+  multiDragPreview: MultiDragPreviewInput | null;
+  onToggleTrackHidden: TimelineEditCallbacks["onToggleTrackHidden"];
+  onTogglePropertyGroupKeyframe: TimelineEditCallbacks["onTogglePropertyGroupKeyframe"];
+  onResizeElement: TimelineEditCallbacks["onResizeElement"];
+  onMoveElement: TimelineEditCallbacks["onMoveElement"];
+  onRazorSplit: TimelineEditCallbacks["onRazorSplit"];
+  onRazorSplitAll: TimelineEditCallbacks["onRazorSplitAll"];
+}

package/src/player/components/timelineLayout.ts

@@ -1,3 +1,4 @@
+import { AUTOMATION_LANE_H } from "./automationLaneHeight";
 import type { ZoomMode } from "../store/playerStore";
 import type { TimelineTimeRange } from "../lib/timelineClipIndex";
 
@@ -86,6 +87,8 @@ export const TRACKS_LEFT_PAD = 48;
 export interface TimelineTrackHeightClip {
   clipId: string;
   laneCount: number;
+  /** Audio automation lanes shown when expanded, reserved at their own height. */
+  automationLaneCount?: number;
 }
 
 type TimelineTrackHeightInput = readonly (readonly TimelineTrackHeightClip[])[];
@@ -101,12 +104,15 @@ export function trackHeights(
 ): number[] {
   return tracks.map((clips) => {
     let laneCount = 0;
-    if (expandedClipIds) {
-      for (const clip of clips) {
-        if (expandedClipIds.has(clip.clipId)) laneCount = Math.max(laneCount, clip.laneCount);
-      }
+    let automationLanes = 0;
+    for (const clip of clips) {
+      if (!expandedClipIds?.has(clip.clipId)) continue;
+      laneCount = Math.max(laneCount, clip.laneCount);
+      automationLanes = Math.max(automationLanes, clip.automationLaneCount ?? 0);
     }
-    return TRACK_H + Math.max(0, Math.trunc(laneCount)) * LANE_H;
+    return (
+      TRACK_H + Math.max(0, Math.trunc(laneCount)) * LANE_H + automationLanes * AUTOMATION_LANE_H
+    );
   });
 }
 

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

@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+import { clampEdge } from "./useAutomationEdgeStretch";
+
+describe("clampEdge", () => {
+  it("keeps the dragged edge inside the clip", () => {
+    expect(clampEdge("t0", -5, { t0: 1, t1: 3 }, 4)).toBe(0);
+    expect(clampEdge("t1", 99, { t0: 1, t1: 3 }, 4)).toBe(4);
+  });
+
+  it("keeps the dragged edge clear of its partner", () => {
+    expect(clampEdge("t0", 3.5, { t0: 1, t1: 3 }, 4)).toBeCloseTo(2.98, 5);
+    expect(clampEdge("t1", 0.5, { t0: 1, t1: 3 }, 4)).toBeCloseTo(1.02, 5);
+  });
+
+  it("never yields a negative time, even when the partner bound is itself below zero", () => {
+    // A selection thinner than the minimum width has no legal t0 at all. Bounding
+    // against the partner AFTER the 0-floor returned that illegal value, and
+    // core's cleanPoint collapses a negative time onto a duplicate t=0 on the
+    // next serialize round-trip — silent envelope corruption, not a visible bug.
+    expect(clampEdge("t0", -1, { t0: 0.004, t1: 0.01 }, 4)).toBe(0);
+    expect(clampEdge("t0", 0.008, { t0: 0.004, t1: 0.01 }, 4)).toBe(0);
+  });
+
+  it("never yields a time past the clip when the partner bound is past it", () => {
+    expect(clampEdge("t1", 99, { t0: 3.995, t1: 4 }, 4)).toBe(4);
+  });
+});