@hyperframes/studio 0.4.12 → 0.4.13-alpha.2

package/src/player/components/TimelineClip.tsx

@@ -1,7 +1,9 @@
+import type { TimelineTrackStyle } from "./timelineTheme";
 // TimelineClip — Visual clip component for the NLE timeline.
 
 import { memo, type ReactNode } from "react";
 import type { TimelineElement } from "../store/playerStore";
+import { defaultTimelineTheme, getClipHandleOpacity, type TimelineTheme } from "./timelineTheme";
 
 interface TimelineClipProps {
   el: TimelineElement;
@@ -9,11 +11,15 @@ interface TimelineClipProps {
   clipY: number;
   isSelected: boolean;
   isHovered: boolean;
+  isDragging?: boolean;
   hasCustomContent: boolean;
-  style: { clip: string; label: string };
+  theme?: TimelineTheme;
+  trackStyle: TimelineTrackStyle;
   isComposition: boolean;
   onHoverStart: () => void;
   onHoverEnd: () => void;
+  onPointerDown?: (e: React.PointerEvent) => void;
+  onResizeStart?: (edge: "start" | "end", e: React.PointerEvent) => void;
   onClick: (e: React.MouseEvent) => void;
   onDoubleClick: (e: React.MouseEvent) => void;
   children?: ReactNode;
@@ -25,43 +31,62 @@ export const TimelineClip = memo(function TimelineClip({
   clipY,
   isSelected,
   isHovered,
+  isDragging = false,
   hasCustomContent,
-  style,
+  theme = defaultTimelineTheme,
+  trackStyle,
   isComposition,
   onHoverStart,
   onHoverEnd,
+  onPointerDown,
+  onResizeStart,
   onClick,
   onDoubleClick,
   children,
 }: TimelineClipProps) {
   const leftPx = el.start * pps;
   const widthPx = Math.max(el.duration * pps, 4);
+  const handleOpacity = getClipHandleOpacity({ isHovered, isSelected, isDragging });
+  const borderColor = isSelected
+    ? theme.clipBorderActive
+    : isHovered
+      ? theme.clipBorderHover
+      : theme.clipBorder;
+  const boxShadow = isDragging
+    ? theme.clipShadowDragging
+    : isSelected
+      ? theme.clipShadowActive
+      : isHovered
+        ? theme.clipShadowHover
+        : theme.clipShadow;
+  const showHandles = handleOpacity > 0.01;
 
   return (
     <div
       data-clip="true"
-      className={hasCustomContent ? "absolute" : "absolute flex items-center"}
+      className={
+        hasCustomContent ? "absolute overflow-hidden" : "absolute flex items-center overflow-hidden"
+      }
       style={{
         left: leftPx,
         width: widthPx,
         top: clipY,
         bottom: clipY,
-        borderRadius: 5,
-        backgroundColor: hasCustomContent ? (isComposition ? "#111" : style.clip) : style.clip,
+        borderRadius: theme.clipRadius,
+        background: isSelected
+          ? `linear-gradient(180deg, rgba(255,255,255,0.03), rgba(255,255,255,0)), linear-gradient(120deg, ${trackStyle.accent}22, transparent 28%), ${theme.clipBackgroundActive}`
+          : `linear-gradient(180deg, rgba(255,255,255,0.02), rgba(255,255,255,0)), linear-gradient(120deg, ${trackStyle.accent}1e, transparent 28%), ${theme.clipBackground}`,
         backgroundImage:
           isComposition && !hasCustomContent
-            ? `repeating-linear-gradient(135deg, transparent, transparent 3px, rgba(255,255,255,0.08) 3px, rgba(255,255,255,0.08) 6px)`
+            ? `repeating-linear-gradient(135deg, transparent, transparent 3px, rgba(255,255,255,0.05) 3px, rgba(255,255,255,0.05) 6px)`
             : undefined,
-        border: isSelected
-          ? `2px solid rgba(255,255,255,0.9)`
-          : `1px solid rgba(255,255,255,${isHovered ? 0.3 : 0.15})`,
-        boxShadow: isSelected
-          ? `0 0 0 1px ${style.clip}, 0 2px 8px rgba(0,0,0,0.4)`
-          : isHovered
-            ? "0 1px 4px rgba(0,0,0,0.3)"
-            : "none",
-        transition: "border-color 120ms, box-shadow 120ms",
-        zIndex: isSelected ? 10 : isHovered ? 5 : 1,
+        border: `1px solid ${borderColor}`,
+        boxShadow,
+        transition:
+          "border-color 120ms ease-out, box-shadow 140ms ease-out, background 140ms ease-out",
+        zIndex: isDragging ? 20 : isSelected ? 10 : isHovered ? 5 : 1,
+        cursor: "grab",
+        transform: isDragging ? "translateY(-1px)" : undefined,
       }}
       title={
         isComposition
@@ -70,9 +95,80 @@ export const TimelineClip = memo(function TimelineClip({
       }
       onPointerEnter={onHoverStart}
       onPointerLeave={onHoverEnd}
+      onPointerDown={onPointerDown}
       onClick={onClick}
       onDoubleClick={onDoubleClick}
     >
+      <div
+        aria-hidden="true"
+        role="presentation"
+        onPointerDown={(e) => onResizeStart?.("start", e)}
+        style={{
+          position: "absolute",
+          left: 0,
+          top: 0,
+          bottom: 0,
+          width: 18,
+          opacity: showHandles ? 1 : 0,
+          pointerEvents: onResizeStart ? "auto" : "none",
+          zIndex: 4,
+          transition: "opacity 120ms ease-out",
+          cursor: "col-resize",
+          background: showHandles
+            ? `linear-gradient(90deg, ${trackStyle.accent}4d 0%, ${trackStyle.accent}22 42%, transparent 100%)`
+            : "transparent",
+        }}
+      >
+        <div
+          style={{
+            position: "absolute",
+            left: 6,
+            top: 7,
+            bottom: 7,
+            width: 3,
+            borderRadius: 999,
+            background: theme.handleColor,
+            boxShadow: `0 0 0 1px ${trackStyle.accent}38, 0 0 12px ${trackStyle.accent}18`,
+            opacity: handleOpacity,
+            pointerEvents: "none",
+          }}
+        />
+      </div>
+      <div
+        aria-hidden="true"
+        role="presentation"
+        onPointerDown={(e) => onResizeStart?.("end", e)}
+        style={{
+          position: "absolute",
+          right: 0,
+          top: 0,
+          bottom: 0,
+          width: 18,
+          opacity: showHandles ? 1 : 0,
+          pointerEvents: onResizeStart ? "auto" : "none",
+          zIndex: 4,
+          transition: "opacity 120ms ease-out",
+          cursor: "col-resize",
+          background: showHandles
+            ? `linear-gradient(270deg, ${trackStyle.accent}4d 0%, ${trackStyle.accent}22 42%, transparent 100%)`
+            : "transparent",
+        }}
+      >
+        <div
+          style={{
+            position: "absolute",
+            right: 6,
+            top: 7,
+            bottom: 7,
+            width: 3,
+            borderRadius: 999,
+            background: theme.handleColor,
+            boxShadow: `0 0 0 1px ${trackStyle.accent}38, 0 0 12px ${trackStyle.accent}18`,
+            opacity: handleOpacity,
+            pointerEvents: "none",
+          }}
+        />
+      </div>
       {children}
     </div>
   );

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

@@ -0,0 +1,310 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildTrackZIndexMap,
+  buildPromptCopyText,
+  buildTimelineAgentPrompt,
+  resolveTimelineAutoScroll,
+  resolveTimelineMove,
+  resolveTimelineResize,
+  type TimelinePromptElement,
+} from "./timelineEditing";
+
+describe("resolveTimelineMove", () => {
+  it("moves timing based on horizontal drag and snaps to centiseconds", () => {
+    expect(
+      resolveTimelineMove(
+        {
+          start: 1.25,
+          track: 2,
+          duration: 2,
+          originClientX: 100,
+          originClientY: 200,
+          pixelsPerSecond: 100,
+          trackHeight: 72,
+          maxStart: 8,
+          trackOrder: [0, 1, 2, 3, 4],
+        },
+        245,
+        200,
+      ),
+    ).toEqual({ start: 2.7, track: 2 });
+  });
+
+  it("moves layers based on vertical drag and clamps to the allowed range", () => {
+    expect(
+      resolveTimelineMove(
+        {
+          start: 2,
+          track: 1,
+          duration: 3,
+          originClientX: 200,
+          originClientY: 200,
+          pixelsPerSecond: 100,
+          trackHeight: 72,
+          maxStart: 10,
+          trackOrder: [0, 1, 5, 9],
+        },
+        150,
+        390,
+      ),
+    ).toEqual({ start: 1.5, track: 9 });
+  });
+
+  it("prevents moving before zero or past the last valid start", () => {
+    expect(
+      resolveTimelineMove(
+        {
+          start: 0.2,
+          track: 0,
+          duration: 4,
+          originClientX: 300,
+          originClientY: 200,
+          pixelsPerSecond: 100,
+          trackHeight: 72,
+          maxStart: 6,
+          trackOrder: [0, 10, 20],
+        },
+        -100,
+        -200,
+      ),
+    ).toEqual({ start: 0, track: -1 });
+
+    expect(
+      resolveTimelineMove(
+        {
+          start: 5.8,
+          track: 10,
+          duration: 4,
+          originClientX: 300,
+          originClientY: 200,
+          pixelsPerSecond: 100,
+          trackHeight: 72,
+          maxStart: 6,
+          trackOrder: [0, 10, 20],
+        },
+        500,
+        200,
+      ),
+    ).toEqual({ start: 6, track: 10 });
+  });
+
+  it("creates a new top track when dragged past the first row threshold", () => {
+    expect(
+      resolveTimelineMove(
+        {
+          start: 1,
+          track: 0,
+          duration: 2,
+          originClientX: 100,
+          originClientY: 200,
+          pixelsPerSecond: 100,
+          trackHeight: 72,
+          maxStart: 8,
+          trackOrder: [0, 10, 20],
+        },
+        100,
+        150,
+      ),
+    ).toEqual({ start: 1, track: -1 });
+  });
+
+  it("creates a new bottom track when dragged past the last row threshold", () => {
+    expect(
+      resolveTimelineMove(
+        {
+          start: 1,
+          track: 20,
+          duration: 2,
+          originClientX: 100,
+          originClientY: 200,
+          pixelsPerSecond: 100,
+          trackHeight: 72,
+          maxStart: 8,
+          trackOrder: [0, 10, 20],
+        },
+        100,
+        250,
+      ),
+    ).toEqual({ start: 1, track: 21 });
+  });
+
+  it("accounts for scroll displacement while dragging", () => {
+    expect(
+      resolveTimelineMove(
+        {
+          start: 1,
+          track: 0,
+          duration: 2,
+          originClientX: 100,
+          originClientY: 200,
+          originScrollLeft: 0,
+          originScrollTop: 0,
+          currentScrollLeft: 100,
+          currentScrollTop: 144,
+          pixelsPerSecond: 100,
+          trackHeight: 72,
+          maxStart: 8,
+          trackOrder: [0, 1, 2, 3],
+        },
+        100,
+        200,
+      ),
+    ).toEqual({ start: 2, track: 2 });
+  });
+});
+
+describe("buildTrackZIndexMap", () => {
+  it("maps sorted tracks onto stable positive z-index values", () => {
+    expect(buildTrackZIndexMap([-2, -1, 0, 3])).toEqual(
+      new Map([
+        [-2, 1],
+        [-1, 2],
+        [0, 3],
+        [3, 4],
+      ]),
+    );
+  });
+
+  it("deduplicates tracks before assigning z-index values", () => {
+    expect(buildTrackZIndexMap([-1, 0, -1, 3, 3])).toEqual(
+      new Map([
+        [-1, 1],
+        [0, 2],
+        [3, 3],
+      ]),
+    );
+  });
+});
+
+describe("resolveTimelineAutoScroll", () => {
+  it("does not scroll when the pointer stays away from the edges", () => {
+    expect(
+      resolveTimelineAutoScroll(
+        {
+          left: 100,
+          top: 100,
+          right: 500,
+          bottom: 400,
+        },
+        300,
+        250,
+      ),
+    ).toEqual({ x: 0, y: 0 });
+  });
+
+  it("scrolls upward and leftward near the top-left edge", () => {
+    expect(
+      resolveTimelineAutoScroll(
+        {
+          left: 100,
+          top: 100,
+          right: 500,
+          bottom: 400,
+        },
+        110,
+        120,
+      ),
+    ).toEqual({ x: -9, y: -6 });
+  });
+
+  it("scrolls downward and rightward near the bottom-right edge", () => {
+    expect(
+      resolveTimelineAutoScroll(
+        {
+          left: 100,
+          top: 100,
+          right: 500,
+          bottom: 400,
+        },
+        490,
+        380,
+      ),
+    ).toEqual({ x: 9, y: 6 });
+  });
+});
+
+describe("buildTimelineAgentPrompt", () => {
+  it("includes the selected range, elements, and user request", () => {
+    const elements: TimelinePromptElement[] = [
+      { id: "title", tag: "div", start: 1, duration: 3, track: 0 },
+      { id: "music", tag: "audio", start: 0, duration: 8, track: 2 },
+    ];
+
+    const text = buildTimelineAgentPrompt({
+      rangeStart: 1,
+      rangeEnd: 4,
+      elements,
+      prompt: "Move the title later and lower the music",
+    });
+
+    expect(text).toContain("Time range: 0:01 — 0:04");
+    expect(text).toContain("#title (div)");
+    expect(text).toContain("#music (audio)");
+    expect(text).toContain("Move the title later and lower the music");
+  });
+});
+
+describe("resolveTimelineResize", () => {
+  it("shrinks clip duration from the right edge", () => {
+    expect(
+      resolveTimelineResize(
+        {
+          start: 1,
+          duration: 3,
+          originClientX: 100,
+          pixelsPerSecond: 100,
+          minStart: 0,
+          maxEnd: 10,
+        },
+        "end",
+        40,
+      ),
+    ).toEqual({ start: 1, duration: 2.4, playbackStart: undefined });
+  });
+
+  it("trims media from the left edge by advancing playback start and clip start", () => {
+    expect(
+      resolveTimelineResize(
+        {
+          start: 1,
+          duration: 3,
+          originClientX: 100,
+          pixelsPerSecond: 100,
+          minStart: 0,
+          maxEnd: 10,
+          playbackStart: 0.5,
+          playbackRate: 1,
+        },
+        "start",
+        150,
+      ),
+    ).toEqual({ start: 1.5, duration: 2.5, playbackStart: 1 });
+  });
+
+  it("prevents extending media left past available source before media-start", () => {
+    expect(
+      resolveTimelineResize(
+        {
+          start: 1,
+          duration: 3,
+          originClientX: 100,
+          pixelsPerSecond: 100,
+          minStart: 0,
+          maxEnd: 10,
+          playbackStart: 0.2,
+          playbackRate: 1,
+        },
+        "start",
+        0,
+      ),
+    ).toEqual({ start: 0.8, duration: 3.2, playbackStart: 0 });
+  });
+});
+
+describe("buildPromptCopyText", () => {
+  it("returns a trimmed prompt for the copy-prompt action", () => {
+    expect(buildPromptCopyText("  Tighten the headline timing  ")).toBe(
+      "Tighten the headline timing",
+    );
+  });
+});

package/src/player/components/timelineEditing.ts

@@ -0,0 +1,213 @@
+import { formatTime } from "../lib/time";
+
+const TIME_PRECISION = 100;
+
+function roundToCentiseconds(value: number): number {
+  return Math.round(value * TIME_PRECISION) / TIME_PRECISION;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+const EDGE_TRACK_CREATE_THRESHOLD = 0.55;
+const AUTO_SCROLL_EDGE_ZONE = 40;
+const AUTO_SCROLL_MAX_SPEED = 12;
+
+export interface TimelineMoveInput {
+  start: number;
+  track: number;
+  duration: number;
+  originClientX: number;
+  originClientY: number;
+  originScrollLeft?: number;
+  originScrollTop?: number;
+  currentScrollLeft?: number;
+  currentScrollTop?: number;
+  pixelsPerSecond: number;
+  trackHeight: number;
+  maxStart: number;
+  trackOrder: number[];
+}
+
+export interface TimelineResizeInput {
+  start: number;
+  duration: number;
+  originClientX: number;
+  pixelsPerSecond: number;
+  minStart: number;
+  maxEnd: number;
+  minDuration?: number;
+  playbackStart?: number;
+  playbackRate?: number;
+}
+
+export interface TimelineAutoScrollBounds {
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+}
+
+export function resolveTimelineAutoScroll(
+  bounds: TimelineAutoScrollBounds,
+  clientX: number,
+  clientY: number,
+): { x: number; y: number } {
+  const getAxisDelta = (start: number, end: number, pointer: number) => {
+    if (pointer < start + AUTO_SCROLL_EDGE_ZONE) {
+      const proximity = Math.max(0, 1 - (pointer - start) / AUTO_SCROLL_EDGE_ZONE);
+      return -Math.round(AUTO_SCROLL_MAX_SPEED * proximity);
+    }
+    if (pointer > end - AUTO_SCROLL_EDGE_ZONE) {
+      const proximity = Math.max(0, 1 - (end - pointer) / AUTO_SCROLL_EDGE_ZONE);
+      return Math.round(AUTO_SCROLL_MAX_SPEED * proximity);
+    }
+    return 0;
+  };
+
+  return {
+    x: getAxisDelta(bounds.left, bounds.right, clientX),
+    y: getAxisDelta(bounds.top, bounds.bottom, clientY),
+  };
+}
+
+export function resolveTimelineMove(
+  input: TimelineMoveInput,
+  clientX: number,
+  clientY: number,
+): { start: number; track: number } {
+  const scrollDeltaX = (input.currentScrollLeft ?? 0) - (input.originScrollLeft ?? 0);
+  const scrollDeltaY = (input.currentScrollTop ?? 0) - (input.originScrollTop ?? 0);
+  const deltaTime =
+    (clientX - input.originClientX + scrollDeltaX) / Math.max(input.pixelsPerSecond, 1);
+  const trackDeltaRaw =
+    (clientY - input.originClientY + scrollDeltaY) / Math.max(input.trackHeight, 1);
+  const deltaTrack = Math.round(trackDeltaRaw);
+  const currentTrackIndex = Math.max(0, input.trackOrder.indexOf(input.track));
+  const desiredTrackIndex = currentTrackIndex + deltaTrack;
+  const nextTrackIndex = clamp(desiredTrackIndex, 0, Math.max(0, input.trackOrder.length - 1));
+  const minTrack = Math.min(...input.trackOrder);
+  const maxTrack = Math.max(...input.trackOrder);
+  let nextTrack = input.trackOrder[nextTrackIndex] ?? input.track;
+
+  const startedOnFirstTrack = currentTrackIndex === 0;
+  const startedOnLastTrack = currentTrackIndex === input.trackOrder.length - 1;
+
+  if (
+    startedOnFirstTrack &&
+    desiredTrackIndex < 0 &&
+    currentTrackIndex + trackDeltaRaw <= -EDGE_TRACK_CREATE_THRESHOLD
+  ) {
+    nextTrack = minTrack - 1;
+  } else if (
+    startedOnLastTrack &&
+    desiredTrackIndex > input.trackOrder.length - 1 &&
+    currentTrackIndex + trackDeltaRaw >= input.trackOrder.length - 1 + EDGE_TRACK_CREATE_THRESHOLD
+  ) {
+    nextTrack = maxTrack + 1;
+  }
+
+  return {
+    start: clamp(roundToCentiseconds(input.start + deltaTime), 0, Math.max(0, input.maxStart)),
+    track: nextTrack,
+  };
+}
+
+export function buildTrackZIndexMap(tracks: number[]): Map<number, number> {
+  const uniqueTracks = Array.from(new Set(tracks)).sort((a, b) => a - b);
+  return new Map(uniqueTracks.map((track, index) => [track, index + 1]));
+}
+
+export function resolveTimelineResize(
+  input: TimelineResizeInput,
+  edge: "start" | "end",
+  clientX: number,
+): { start: number; duration: number; playbackStart?: number } {
+  const minDuration = Math.max(0.05, input.minDuration ?? 0.1);
+  const deltaTime = (clientX - input.originClientX) / Math.max(input.pixelsPerSecond, 1);
+
+  if (edge === "end") {
+    const nextDuration = clamp(
+      roundToCentiseconds(input.duration + deltaTime),
+      minDuration,
+      Math.max(minDuration, input.maxEnd - input.start),
+    );
+    return {
+      start: input.start,
+      duration: nextDuration,
+      playbackStart: input.playbackStart,
+    };
+  }
+
+  const playbackRate = Math.max(0.1, input.playbackRate ?? 1);
+  const maxLeftExtensionFromMedia =
+    input.playbackStart != null ? input.playbackStart / playbackRate : Number.POSITIVE_INFINITY;
+  const minDelta = -Math.min(input.start - input.minStart, maxLeftExtensionFromMedia);
+  const maxDelta = input.duration - minDuration;
+  const clampedDelta = clamp(deltaTime, minDelta, maxDelta);
+  const nextStart = roundToCentiseconds(input.start + clampedDelta);
+  const nextDuration = roundToCentiseconds(input.duration - clampedDelta);
+  const nextPlaybackStart =
+    input.playbackStart != null
+      ? roundToCentiseconds(Math.max(0, input.playbackStart + clampedDelta * playbackRate))
+      : undefined;
+
+  return {
+    start: nextStart,
+    duration: nextDuration,
+    playbackStart: nextPlaybackStart,
+  };
+}
+
+export interface TimelinePromptElement {
+  id: string;
+  tag: string;
+  start: number;
+  duration: number;
+  track: number;
+}
+
+export function buildTimelineAgentPrompt({
+  rangeStart,
+  rangeEnd,
+  elements,
+  prompt,
+}: {
+  rangeStart: number;
+  rangeEnd: number;
+  elements: TimelinePromptElement[];
+  prompt: string;
+}): string {
+  const start = Math.min(rangeStart, rangeEnd);
+  const end = Math.max(rangeStart, rangeEnd);
+  const elementLines = elements
+    .map(
+      (el) =>
+        `- #${el.id} (${el.tag}) — ${formatTime(el.start)} to ${formatTime(el.start + el.duration)}, track ${el.track}`,
+    )
+    .join("\n");
+
+  return `Edit the following HyperFrames composition:
+
+Time range: ${formatTime(start)} — ${formatTime(end)}
+
+Elements in range:
+${elementLines || "(none)"}
+
+User request:
+${prompt.trim() || "(no prompt provided)"}
+
+Instructions:
+Modify only the elements listed above within the specified time range.
+The composition uses HyperFrames data attributes (data-start, data-duration, data-track-index) and GSAP for animations.
+Preserve all other elements and timing outside this range.`;
+}
+
+export function buildPromptCopyText(prompt: string): string {
+  return prompt.trim();
+}
+
+export function formatTimelineAttributeNumber(value: number): string {
+  return Number(roundToCentiseconds(value).toFixed(2)).toString();
+}