@hyperframes/studio 0.6.86 → 0.6.87

package/src/player/components/TimelinePropertyRows.tsx

@@ -0,0 +1,120 @@
+import { memo } from "react";
+import type { KeyframeCacheEntry } from "../store/playerStore";
+
+const SUB_TRACK_H = 24;
+const DIAMOND_SIZE = 6;
+const HALF = DIAMOND_SIZE / 2;
+
+interface TimelinePropertyRowsProps {
+  keyframesData: KeyframeCacheEntry;
+  clipWidthPx: number;
+  clipLeftPx: number;
+  accentColor: string;
+  isSelected: boolean;
+  currentPercentage: number;
+  elementId: string;
+  selectedKeyframes: Set<string>;
+  onClickKeyframe?: (percentage: number) => void;
+}
+
+function extractProperties(data: KeyframeCacheEntry): string[] {
+  const props = new Set<string>();
+  for (const kf of data.keyframes) {
+    for (const key of Object.keys(kf.properties)) {
+      props.add(key);
+    }
+  }
+  return Array.from(props).sort();
+}
+
+export const TimelinePropertyRows = memo(function TimelinePropertyRows({
+  keyframesData,
+  clipWidthPx,
+  clipLeftPx,
+  accentColor,
+  isSelected,
+  currentPercentage,
+  elementId,
+  selectedKeyframes,
+  onClickKeyframe,
+}: TimelinePropertyRowsProps) {
+  const properties = extractProperties(keyframesData);
+  if (properties.length === 0 || clipWidthPx < 20) return null;
+
+  return (
+    <div className="flex flex-col">
+      {properties.map((prop) => {
+        const propKeyframes = keyframesData.keyframes.filter((kf) => prop in kf.properties);
+        if (propKeyframes.length === 0) return null;
+
+        return (
+          <div key={prop} className="relative flex items-center" style={{ height: SUB_TRACK_H }}>
+            <span className="absolute left-1 text-[8px] font-medium text-neutral-600 z-10 select-none">
+              {prop}
+            </span>
+            <svg
+              className="absolute"
+              style={{ left: clipLeftPx, width: clipWidthPx, height: SUB_TRACK_H }}
+              viewBox={`0 0 ${clipWidthPx} ${SUB_TRACK_H}`}
+            >
+              <line
+                x1={0}
+                y1={SUB_TRACK_H / 2}
+                x2={clipWidthPx}
+                y2={SUB_TRACK_H / 2}
+                stroke={isSelected ? accentColor : "#525252"}
+                strokeOpacity={0.15}
+                strokeWidth={1}
+              />
+              {propKeyframes.map((kf) => {
+                const x = (kf.percentage / 100) * clipWidthPx;
+                const y = SUB_TRACK_H / 2;
+                const key = `${elementId}:${kf.percentage}`;
+                const isKfSelected = selectedKeyframes.has(key);
+                const isHold = kf.ease === "steps(1)";
+                const fillColor =
+                  isKfSelected || (isSelected && Math.abs(kf.percentage - currentPercentage) < 0.5)
+                    ? accentColor
+                    : isSelected
+                      ? `${accentColor}80`
+                      : "#737373";
+
+                return (
+                  <g
+                    key={kf.percentage}
+                    onClick={(e) => {
+                      e.stopPropagation();
+                      onClickKeyframe?.(kf.percentage);
+                    }}
+                    style={{ cursor: "pointer" }}
+                  >
+                    {isHold ? (
+                      <rect
+                        x={x - HALF}
+                        y={y - HALF}
+                        width={DIAMOND_SIZE}
+                        height={DIAMOND_SIZE}
+                        fill={fillColor}
+                      />
+                    ) : (
+                      <rect
+                        x={x - HALF}
+                        y={y - HALF}
+                        width={DIAMOND_SIZE}
+                        height={DIAMOND_SIZE}
+                        fill={fillColor}
+                        transform={`rotate(45, ${x}, ${y})`}
+                      />
+                    )}
+                  </g>
+                );
+              })}
+            </svg>
+          </div>
+        );
+      })}
+    </div>
+  );
+});
+
+export { SUB_TRACK_H };

package/src/player/lib/timelineDOM.test.ts

@@ -0,0 +1,55 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from "vitest";
+import { parseTimelineFromDOM, createImplicitTimelineLayersFromDOM } from "./timelineDOM";
+
+function makeDoc(html: string): Document {
+  const d = document.implementation.createHTMLDocument();
+  d.body.innerHTML = html;
+  return d;
+}
+
+describe("parseTimelineFromDOM — hfId from data-hf-id", () => {
+  it("harvests hfId from a data-start element that has data-hf-id", () => {
+    const doc = makeDoc(`
+      <div data-composition-id="root">
+        <div id="hero" class="clip" data-start="0" data-duration="5" data-hf-id="hf-abc123"></div>
+      </div>
+    `);
+
+    const elements = parseTimelineFromDOM(doc, 10);
+    const hero = elements.find((el) => el.domId === "hero");
+
+    expect(hero).toBeDefined();
+    expect(hero?.hfId).toBe("hf-abc123");
+  });
+
+  it("leaves hfId undefined when element has no data-hf-id", () => {
+    const doc = makeDoc(`
+      <div data-composition-id="root">
+        <div id="plain" class="clip" data-start="0" data-duration="5"></div>
+      </div>
+    `);
+
+    const elements = parseTimelineFromDOM(doc, 10);
+    const plain = elements.find((el) => el.domId === "plain");
+
+    expect(plain).toBeDefined();
+    expect(plain?.hfId).toBeUndefined();
+  });
+});
+
+describe("createImplicitTimelineLayersFromDOM — hfId from data-hf-id", () => {
+  it("harvests hfId from an implicit layer child that has data-hf-id", () => {
+    const doc = makeDoc(`
+      <div data-composition-id="root">
+        <div id="layer" class="clip" data-hf-id="hf-xyz789"></div>
+      </div>
+    `);
+
+    const layers = createImplicitTimelineLayersFromDOM(doc, 10);
+    const layer = layers.find((el) => el.domId === "layer");
+
+    expect(layer).toBeDefined();
+    expect(layer?.hfId).toBe("hf-xyz789");
+  });
+});

package/src/player/lib/timelineDOM.ts

@@ -26,14 +26,21 @@ import {
 
 // Re-export helpers that were previously public from this module so that
 // existing import sites (hook + tests) don't need to change.
+// fallow-ignore-next-line unused-exports
 export {
   readTimelineDurationFromDocument,
+  // fallow-ignore-next-line unused-exports
   resolveMediaElement,
+  // fallow-ignore-next-line unused-exports
   applyMediaMetadataFromElement,
   getTimelineElementSelector,
+  // fallow-ignore-next-line unused-exports
   getTimelineElementSourceFile,
+  // fallow-ignore-next-line unused-exports
   getTimelineElementSelectorIndex,
+  // fallow-ignore-next-line unused-exports
   buildTimelineElementIdentity,
+  // fallow-ignore-next-line unused-exports
   getTimelineElementIdentity,
   findTimelineDomNodeForClip,
 } from "./timelineElementHelpers";
@@ -72,8 +79,10 @@ export function createTimelineElementFromManifestClip(params: {
   let selectorIndex: number | undefined;
   let sourceFile: string | undefined;
 
+  let hfId: string | undefined;
   if (hostEl) {
     domId = hostEl.id || undefined;
+    hfId = hostEl.getAttribute("data-hf-id") || undefined;
     selector = getTimelineElementSelector(hostEl);
     selectorIndex =
       doc && selector ? getTimelineElementSelectorIndex(doc, hostEl, selector) : undefined;
@@ -98,6 +107,7 @@ export function createTimelineElementFromManifestClip(params: {
     duration: clip.duration,
     track: clip.track,
     domId,
+    hfId,
     selector,
     selectorIndex,
     sourceFile,
@@ -127,6 +137,7 @@ export function createTimelineElementFromManifestClip(params: {
     }
     if (hostEl) {
       entry.domId = hostEl.id || undefined;
+      entry.hfId = hostEl.getAttribute("data-hf-id") || undefined;
       entry.selector = getTimelineElementSelector(hostEl);
       entry.selectorIndex =
         doc && entry.selector
@@ -187,6 +198,7 @@ export function createImplicitTimelineLayersFromDOM(
 
     layers.push({
       domId: child.id || undefined,
+      hfId: child.getAttribute("data-hf-id") || undefined,
       duration: rootDuration,
       id: identity.id,
       key: identity.key,
@@ -262,6 +274,7 @@ export function parseTimelineFromDOM(doc: Document, rootDuration: number): Timel
       duration: dur,
       track: isNaN(track) ? 0 : track,
       domId: el.id || undefined,
+      hfId: el.getAttribute("data-hf-id") || undefined,
       selector,
       selectorIndex,
       sourceFile,

package/src/player/lib/timelineIframeHelpers.test.ts

@@ -0,0 +1,51 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from "vitest";
+import { buildMissingCompositionElements } from "./timelineIframeHelpers";
+import type { IframeWindow } from "./playbackTypes";
+
+function makeDoc(html: string): Document {
+  const d = document.implementation.createHTMLDocument();
+  d.body.innerHTML = html;
+  return d;
+}
+
+describe("buildMissingCompositionElements — hfId (R7)", () => {
+  it("harvests hfId from data-hf-id on composition host elements", () => {
+    const doc = makeDoc(`
+      <div data-composition-id="root">
+        <div
+          data-composition-id="scene-a"
+          data-composition-src="scenes/a.html"
+          data-hf-id="hf-scene1"
+          data-start="0"
+          data-duration="5"
+        ></div>
+      </div>
+    `);
+
+    const { missing } = buildMissingCompositionElements(doc, window as IframeWindow, [], 10);
+    const entry = missing[0];
+
+    expect(entry).toBeDefined();
+    expect(entry?.hfId).toBe("hf-scene1");
+  });
+
+  it("leaves hfId undefined when element has no data-hf-id", () => {
+    const doc = makeDoc(`
+      <div data-composition-id="root">
+        <div
+          data-composition-id="scene-b"
+          data-composition-src="scenes/b.html"
+          data-start="0"
+          data-duration="5"
+        ></div>
+      </div>
+    `);
+
+    const { missing } = buildMissingCompositionElements(doc, window as IframeWindow, [], 10);
+    const entry = missing[0];
+
+    expect(entry).toBeDefined();
+    expect(entry?.hfId).toBeUndefined();
+  });
+});

package/src/player/lib/timelineIframeHelpers.ts

@@ -286,6 +286,7 @@ export function buildMissingCompositionElements(
       duration: dur,
       track: isNaN(track) ? 0 : track,
       domId: el.id || undefined,
+      hfId: el.getAttribute("data-hf-id") || undefined,
       selector,
       selectorIndex,
       sourceFile,

package/src/player/store/playerStore.ts

@@ -22,6 +22,8 @@ export interface TimelineElement {
   duration: number;
   track: number;
   domId?: string;
+  /** Stable `data-hf-id` attribute value — used as primary patch target when present */
+  hfId?: string;
   /** Best-effort selector used when patching source HTML back from timeline edits */
   selector?: string;
   /** Zero-based occurrence index for non-unique selectors */
@@ -68,6 +70,23 @@ interface PlayerState {
   toggleSelectedKeyframe: (key: string) => void;
   clearSelectedKeyframes: () => void;
 
+  /** Multi-select: additional selected elements beyond selectedElementId. */
+  selectedElementIds: Set<string>;
+  toggleSelectedElementId: (id: string) => void;
+  clearSelectedElementIds: () => void;
+
+  /** Clipboard for keyframe copy/paste — stores keyframes with relative times. */
+  keyframeClipboard: Array<{
+    relativeTime: number;
+    properties: Record<string, number | string>;
+    ease?: string;
+  }> | null;
+  setKeyframeClipboard: (data: PlayerState["keyframeClipboard"]) => void;
+
+  /** Elements with expanded property rows in the timeline. */
+  expandedTimelineElements: Set<string>;
+  toggleExpandedElement: (id: string) => void;
+
   /** Keyframe data per element id, populated from parsed GSAP animations. */
   keyframeCache: Map<string, KeyframeCacheEntry>;
   setKeyframeCache: (elementId: string, data: KeyframeCacheEntry | undefined) => void;
@@ -138,6 +157,28 @@ export const usePlayerStore = create<PlayerState>((set) => ({
     }),
   clearSelectedKeyframes: () => set({ selectedKeyframes: new Set() }),
 
+  keyframeClipboard: null,
+  setKeyframeClipboard: (data) => set({ keyframeClipboard: data }),
+
+  selectedElementIds: new Set<string>(),
+  toggleSelectedElementId: (id: string) =>
+    set((s) => {
+      const next = new Set(s.selectedElementIds);
+      if (next.has(id)) next.delete(id);
+      else next.add(id);
+      return { selectedElementIds: next };
+    }),
+  clearSelectedElementIds: () => set({ selectedElementIds: new Set() }),
+
+  expandedTimelineElements: new Set<string>(),
+  toggleExpandedElement: (id: string) =>
+    set((s) => {
+      const next = new Set(s.expandedTimelineElements);
+      if (next.has(id)) next.delete(id);
+      else next.add(id);
+      return { expandedTimelineElements: next };
+    }),
+
   keyframeCache: new Map(),
   setKeyframeCache: (elementId, data) =>
     set((s) => {
@@ -210,6 +251,8 @@ export const usePlayerStore = create<PlayerState>((set) => ({
       inPoint: null,
       outPoint: null,
       selectedKeyframes: new Set(),
+      selectedElementIds: new Set(),
+      expandedTimelineElements: new Set(),
       keyframeCache: new Map(),
     }),
 }));

package/src/utils/audioBeatDetection.ts

@@ -0,0 +1,58 @@
+const WINDOW_SIZE = 1024;
+const HOP_SIZE = 512;
+
+// fallow-ignore-next-line complexity
+export async function detectBeats(audioBuffer: AudioBuffer): Promise<number[]> {
+  const channelData = audioBuffer.getChannelData(0);
+  const sampleRate = audioBuffer.sampleRate;
+
+  const energies: number[] = [];
+  for (let i = 0; i < channelData.length - WINDOW_SIZE; i += HOP_SIZE) {
+    let sum = 0;
+    for (let j = 0; j < WINDOW_SIZE; j++) {
+      const sample = channelData[i + j]!;
+      sum += sample * sample;
+    }
+    energies.push(sum / WINDOW_SIZE);
+  }
+
+  const beats: number[] = [];
+  const localWindowSize = 20;
+
+  for (let i = localWindowSize; i < energies.length - localWindowSize; i++) {
+    let localMean = 0;
+    for (let j = i - localWindowSize; j < i + localWindowSize; j++) {
+      localMean += energies[j]!;
+    }
+    localMean /= localWindowSize * 2;
+
+    const threshold = localMean * 1.5;
+    const current = energies[i]!;
+
+    if (
+      current > threshold &&
+      current > (energies[i - 1] ?? 0) &&
+      current > (energies[i + 1] ?? 0)
+    ) {
+      const timeInSeconds = (i * HOP_SIZE) / sampleRate;
+      if (beats.length === 0 || timeInSeconds - beats[beats.length - 1]! > 0.1) {
+        beats.push(Math.round(timeInSeconds * 1000) / 1000);
+      }
+    }
+  }
+
+  return beats;
+}
+
+// fallow-ignore-next-line complexity
+export async function detectBeatsFromUrl(url: string): Promise<number[]> {
+  const audioContext = new AudioContext();
+  try {
+    const response = await fetch(url);
+    const arrayBuffer = await response.arrayBuffer();
+    const audioBuffer = await audioContext.decodeAudioData(arrayBuffer);
+    return detectBeats(audioBuffer);
+  } finally {
+    await audioContext.close();
+  }
+}

package/src/utils/globalTimeCompiler.test.ts

@@ -0,0 +1,169 @@
+import { describe, expect, test } from "vitest";
+import {
+  absoluteToPercentage,
+  absoluteToPercentageForAnimation,
+  findTweenAtTime,
+  isTimeWithinTween,
+  percentageToAbsolute,
+  percentageToAbsoluteForAnimation,
+  resolveTweenDuration,
+  resolveTweenStart,
+} from "./globalTimeCompiler";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+
+function makeAnim(overrides: Partial<GsapAnimation> = {}): GsapAnimation {
+  return {
+    id: "#el-to-0",
+    targetSelector: "#el",
+    method: "to",
+    position: 0,
+    properties: { x: 100 },
+    ...overrides,
+  };
+}
+
+describe("absoluteToPercentage", () => {
+  test("mid-point of a tween", () => {
+    expect(absoluteToPercentage(0.5, 0, 2)).toBe(25);
+  });
+
+  test("tween with offset start", () => {
+    expect(absoluteToPercentage(1.0, 0.5, 1)).toBe(50);
+  });
+
+  test("clamps below tween start to 0%", () => {
+    expect(absoluteToPercentage(-1, 0, 2)).toBe(0);
+  });
+
+  test("clamps past tween end to 100%", () => {
+    expect(absoluteToPercentage(5, 0, 2)).toBe(100);
+  });
+
+  test("zero duration returns 0", () => {
+    expect(absoluteToPercentage(1, 0, 0)).toBe(0);
+  });
+});
+
+describe("percentageToAbsolute", () => {
+  test("converts percentage back to absolute time", () => {
+    expect(percentageToAbsolute(50, 0.5, 1)).toBe(1.0);
+  });
+
+  test("0% returns tween start", () => {
+    expect(percentageToAbsolute(0, 2, 3)).toBe(2);
+  });
+
+  test("100% returns tween end", () => {
+    expect(percentageToAbsolute(100, 2, 3)).toBe(5);
+  });
+});
+
+describe("isTimeWithinTween", () => {
+  test("time inside returns true", () => {
+    expect(isTimeWithinTween(0.5, 0, 2)).toBe(true);
+  });
+
+  test("time at start returns true", () => {
+    expect(isTimeWithinTween(0, 0, 2)).toBe(true);
+  });
+
+  test("time at end returns true", () => {
+    expect(isTimeWithinTween(2, 0, 2)).toBe(true);
+  });
+
+  test("time before returns false", () => {
+    expect(isTimeWithinTween(-0.1, 0, 2)).toBe(false);
+  });
+
+  test("time after returns false", () => {
+    expect(isTimeWithinTween(2.1, 0, 2)).toBe(false);
+  });
+});
+
+describe("resolveTweenStart", () => {
+  test("numeric position", () => {
+    expect(resolveTweenStart(makeAnim({ position: 1.5 }))).toBe(1.5);
+  });
+
+  test("parseable string position", () => {
+    expect(resolveTweenStart(makeAnim({ position: "2.5" }))).toBe(2.5);
+  });
+
+  test("unparseable string position returns null", () => {
+    expect(resolveTweenStart(makeAnim({ position: "myLabel" }))).toBeNull();
+  });
+
+  test("relative position +=0.5 returns null", () => {
+    expect(resolveTweenStart(makeAnim({ position: "+=0.5" }))).toBeNull();
+  });
+});
+
+describe("resolveTweenDuration", () => {
+  test("explicit duration", () => {
+    expect(resolveTweenDuration(makeAnim({ duration: 2 }))).toBe(2);
+  });
+
+  test("missing duration defaults to 1", () => {
+    expect(resolveTweenDuration(makeAnim({ duration: undefined }))).toBe(1);
+  });
+});
+
+describe("findTweenAtTime", () => {
+  const anims = [
+    makeAnim({ id: "#el-to-0", position: 0, duration: 0.5 }),
+    makeAnim({ id: "#el-to-1", position: 1, duration: 1 }),
+    makeAnim({
+      id: "#other-to-0",
+      targetSelector: "#other",
+      position: 0,
+      duration: 2,
+    }),
+  ];
+
+  test("finds tween at time within range", () => {
+    expect(findTweenAtTime(0.3, anims, "#el")?.id).toBe("#el-to-0");
+  });
+
+  test("finds second tween", () => {
+    expect(findTweenAtTime(1.5, anims, "#el")?.id).toBe("#el-to-1");
+  });
+
+  test("returns null for gap between tweens", () => {
+    expect(findTweenAtTime(0.7, anims, "#el")).toBeNull();
+  });
+
+  test("filters by selector", () => {
+    expect(findTweenAtTime(0.3, anims, "#other")?.id).toBe("#other-to-0");
+  });
+
+  test("returns null for unmatched selector", () => {
+    expect(findTweenAtTime(0.3, anims, "#missing")).toBeNull();
+  });
+
+  test("skips tweens with unresolvable string positions", () => {
+    const withLabel = [makeAnim({ id: "#el-to-0", position: "myLabel", duration: 1 })];
+    expect(findTweenAtTime(0.5, withLabel, "#el")).toBeNull();
+  });
+});
+
+describe("animation-level helpers", () => {
+  const anim = makeAnim({ position: 0.5, duration: 2 });
+
+  test("absoluteToPercentageForAnimation", () => {
+    expect(absoluteToPercentageForAnimation(1.5, anim)).toBe(50);
+  });
+
+  test("absoluteToPercentageForAnimation returns null for string position", () => {
+    const labelAnim = makeAnim({ position: "label" });
+    expect(absoluteToPercentageForAnimation(0.5, labelAnim)).toBeNull();
+  });
+
+  test("percentageToAbsoluteForAnimation", () => {
+    expect(percentageToAbsoluteForAnimation(50, anim)).toBe(1.5);
+  });
+
+  test("percentageToAbsoluteForAnimation returns null for string position", () => {
+    const labelAnim = makeAnim({ position: "+=1" });
+    expect(percentageToAbsoluteForAnimation(50, labelAnim)).toBeNull();
+  });
+});

package/src/utils/globalTimeCompiler.ts

@@ -0,0 +1,77 @@
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+
+export function absoluteToPercentage(
+  time: number,
+  tweenStart: number,
+  tweenDuration: number,
+): number {
+  if (tweenDuration <= 0) return 0;
+  const raw = ((time - tweenStart) / tweenDuration) * 100;
+  return Math.max(0, Math.min(100, Math.round(raw * 10) / 10));
+}
+
+export function percentageToAbsolute(
+  pct: number,
+  tweenStart: number,
+  tweenDuration: number,
+): number {
+  return tweenStart + (pct / 100) * tweenDuration;
+}
+
+export function isTimeWithinTween(
+  time: number,
+  tweenStart: number,
+  tweenDuration: number,
+): boolean {
+  return time >= tweenStart && time <= tweenStart + tweenDuration;
+}
+
+export function resolveTweenStart(animation: GsapAnimation): number | null {
+  if (typeof animation.position === "number") return animation.position;
+  const parsed = Number.parseFloat(animation.position as string);
+  if (!Number.isNaN(parsed)) return parsed;
+  return null;
+}
+
+export function resolveTweenDuration(animation: GsapAnimation): number {
+  return animation.duration ?? 1;
+}
+
+export function findTweenAtTime(
+  time: number,
+  animations: GsapAnimation[],
+  selector: string,
+): GsapAnimation | null {
+  for (const anim of animations) {
+    if (!matchesSelector(anim.targetSelector, selector)) continue;
+    const start = resolveTweenStart(anim);
+    if (start === null) continue;
+    const duration = resolveTweenDuration(anim);
+    if (isTimeWithinTween(time, start, duration)) return anim;
+  }
+  return null;
+}
+
+export function absoluteToPercentageForAnimation(
+  time: number,
+  animation: GsapAnimation,
+): number | null {
+  const start = resolveTweenStart(animation);
+  if (start === null) return null;
+  const duration = resolveTweenDuration(animation);
+  return absoluteToPercentage(time, start, duration);
+}
+
+export function percentageToAbsoluteForAnimation(
+  pct: number,
+  animation: GsapAnimation,
+): number | null {
+  const start = resolveTweenStart(animation);
+  if (start === null) return null;
+  const duration = resolveTweenDuration(animation);
+  return percentageToAbsolute(pct, start, duration);
+}
+
+function matchesSelector(tweenSelector: string, querySelector: string): boolean {
+  return tweenSelector.split(",").some((part) => part.trim() === querySelector);
+}