@hyperframes/studio 0.6.86 → 0.6.87

package/src/utils/gsapSoftReload.ts

@@ -4,7 +4,11 @@ type IframeWindow = Window & {
   __hfForceTimelineRebind?: () => void;
   __hfSuppressSceneMutations?: <T>(fn: () => T) => T;
   __hfStudioManualEditsApply?: () => void;
-  gsap?: { timeline?: (...args: unknown[]) => unknown };
+  gsap?: {
+    timeline?: (...args: unknown[]) => unknown;
+    registerPlugin?: (...plugins: unknown[]) => unknown;
+  };
+  MotionPathPlugin?: unknown;
 };
 
 function isGsapScript(text: string): boolean {
@@ -64,16 +68,32 @@ export function applySoftReload(iframe: HTMLIFrameElement | null, scriptText: st
     }
 
     oldScriptEl.remove();
-    const newScript = doc.createElement("script");
-    // IIFE prevents const/let redeclaration errors across consecutive edits.
-    // Top-level declarations are scoped to the IIFE; window.* assignments
-    // (e.g. window.__timelines["root"] = tl) still reach the global scope.
-    newScript.textContent = `(function(){${scriptText}\n})();`;
-    doc.body.appendChild(newScript);
 
-    win.__hfForceTimelineRebind?.();
-    win.__player?.seek?.(currentTime);
-    win.__hfStudioManualEditsApply?.();
+    const executeScript = () => {
+      if (win.MotionPathPlugin && win.gsap?.registerPlugin) {
+        win.gsap.registerPlugin(win.MotionPathPlugin);
+      }
+      const s = doc.createElement("script");
+      s.textContent = `(function(){${scriptText}\n})();`;
+      doc.body.appendChild(s);
+      win.__hfForceTimelineRebind?.();
+      win.__player?.seek?.(currentTime);
+      win.__hfStudioManualEditsApply?.();
+    };
+
+    // Load MotionPathPlugin on demand if the script uses motionPath.
+    // Uses the same CDN as composition templates (GSAP_CDN in constants.ts).
+    const needsMotionPath = /motionPath\s*[:{]/.test(scriptText);
+    if (needsMotionPath && !win.MotionPathPlugin && win.gsap) {
+      const pluginScript = doc.createElement("script");
+      pluginScript.src = "https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/MotionPathPlugin.min.js";
+      pluginScript.onload = () => executeScript();
+      pluginScript.onerror = () => executeScript();
+      doc.head.appendChild(pluginScript);
+      return;
+    }
+
+    executeScript();
   };
 
   try {

package/src/utils/keyframeSnapping.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, test } from "vitest";
+import { computeSnapThreshold, snapKeyframe } from "./keyframeSnapping";
+
+describe("snapKeyframe", () => {
+  test("snaps to frame boundary", () => {
+    const result = snapKeyframe(0.34, { fps: 30, keyframeTimes: [], threshold: 0.05 });
+    expect(result.snapType).toBe("frame");
+    expect(Math.abs(result.snappedTime - 1 / 3)).toBeLessThan(0.01);
+  });
+
+  test("snaps to cross-element keyframe when closest", () => {
+    const result = snapKeyframe(1.005, { fps: 30, keyframeTimes: [1.0], threshold: 0.05 });
+    expect(result.snapType).toBe("keyframe");
+    expect(result.snappedTime).toBe(1.0);
+  });
+
+  test("keyframe snap wins tie with frame at same position", () => {
+    const result = snapKeyframe(1.0, { fps: 30, keyframeTimes: [1.0], threshold: 0.05 });
+    expect(result.snapType).toBe("keyframe");
+    expect(result.snappedTime).toBe(1.0);
+  });
+
+  test("snaps to beat marker when closer than frame", () => {
+    const result = snapKeyframe(2.49, {
+      fps: 30,
+      keyframeTimes: [],
+      beatTimes: [2.5],
+      threshold: 0.05,
+    });
+    expect(result.snapType).toBe("beat");
+    expect(result.snappedTime).toBe(2.5);
+  });
+
+  test("disabled returns raw time", () => {
+    const result = snapKeyframe(1.5, {
+      fps: 30,
+      keyframeTimes: [1.5],
+      threshold: 0.05,
+      disabled: true,
+    });
+    expect(result.snapType).toBeNull();
+    expect(result.snappedTime).toBe(1.5);
+  });
+
+  test("no snap when outside threshold", () => {
+    const result = snapKeyframe(1.5, {
+      fps: 30,
+      keyframeTimes: [0.5],
+      threshold: 0.05,
+    });
+    expect(result.snapType).toBe("frame");
+  });
+
+  test("empty beat times is graceful", () => {
+    const result = snapKeyframe(0.5, {
+      fps: 30,
+      keyframeTimes: [],
+      beatTimes: [],
+      threshold: 0.05,
+    });
+    expect(result.snapType).toBe("frame");
+  });
+});
+
+describe("computeSnapThreshold", () => {
+  test("returns threshold based on pixels per second", () => {
+    const threshold = computeSnapThreshold(100, 5);
+    expect(threshold).toBe(0.05);
+  });
+
+  test("fallback for zero pixels per second", () => {
+    expect(computeSnapThreshold(0)).toBe(0.1);
+  });
+});

package/src/utils/keyframeSnapping.ts

@@ -0,0 +1,63 @@
+export type SnapType = "frame" | "keyframe" | "beat" | null;
+
+export interface SnapResult {
+  snappedTime: number;
+  snapType: SnapType;
+}
+
+export function snapKeyframe(
+  time: number,
+  options: {
+    fps: number;
+    keyframeTimes: number[];
+    beatTimes?: number[];
+    threshold: number;
+    disabled?: boolean;
+  },
+): SnapResult {
+  if (options.disabled) return { snappedTime: time, snapType: null };
+
+  const { fps, keyframeTimes, beatTimes = [], threshold } = options;
+
+  let bestDist = threshold;
+  let bestTime = time;
+  let bestType: SnapType = null;
+
+  // Priority: cross-element keyframes > beat markers > frame boundaries
+  // Higher priority snaps use strict < so they win on equal distance
+  if (fps > 0) {
+    const frameDuration = 1 / fps;
+    const nearestFrame = Math.round(time / frameDuration) * frameDuration;
+    const dist = Math.abs(time - nearestFrame);
+    if (dist < bestDist) {
+      bestDist = dist;
+      bestTime = nearestFrame;
+      bestType = "frame";
+    }
+  }
+
+  for (const bt of beatTimes) {
+    const dist = Math.abs(time - bt);
+    if (dist <= bestDist) {
+      bestDist = dist;
+      bestTime = bt;
+      bestType = "beat";
+    }
+  }
+
+  for (const kt of keyframeTimes) {
+    const dist = Math.abs(time - kt);
+    if (dist <= bestDist) {
+      bestDist = dist;
+      bestTime = kt;
+      bestType = "keyframe";
+    }
+  }
+
+  return { snappedTime: bestTime, snapType: bestType };
+}
+
+export function computeSnapThreshold(pixelsPerSecond: number, baseThresholdPx: number = 5): number {
+  if (pixelsPerSecond <= 0) return 0.1;
+  return baseThresholdPx / pixelsPerSecond;
+}

package/src/utils/rdpSimplify.ts

@@ -0,0 +1,183 @@
+/**
+ * Ramer-Douglas-Peucker simplification for time-series data.
+ *
+ * Used to reduce gesture recording samples into a minimal set of keyframes
+ * that approximate the original curve within a configurable tolerance.
+ */
+
+// ---------------------------------------------------------------------------
+// 1D time-series simplification
+// ---------------------------------------------------------------------------
+
+/**
+ * Perpendicular distance from point (t, v) to the line segment between
+ * (t1, v1) and (t2, v2).  For 1D time-series this reduces to the vertical
+ * distance from the point to the interpolated value on the line.
+ */
+function perpendicularDistance(
+  t: number,
+  v: number,
+  t1: number,
+  v1: number,
+  t2: number,
+  v2: number,
+): number {
+  // Degenerate case: start and end share the same time
+  if (t2 === t1) return Math.abs(v - v1);
+  const interpolated = v1 + ((v2 - v1) * (t - t1)) / (t2 - t1);
+  return Math.abs(v - interpolated);
+}
+
+/**
+ * Standard Ramer-Douglas-Peucker on 1D time-series data.
+ *
+ * Each point is treated as (time, value) in 2D space.  Returns the minimal
+ * subset of input points that approximates the curve within `epsilon`.
+ *
+ * - `epsilon = 0` returns all points (no simplification).
+ * - A large `epsilon` returns just the first and last points.
+ * - Empty or single-point input is returned unchanged.
+ */
+function simplifyTimeSeries(
+  points: Array<{ time: number; value: number }>,
+  epsilon: number,
+): Array<{ time: number; value: number }> {
+  if (points.length <= 2) return points;
+  if (epsilon <= 0) return points;
+
+  const first = points[0];
+  const last = points[points.length - 1];
+
+  let maxDist = 0;
+  let maxIndex = 0;
+
+  for (let i = 1; i < points.length - 1; i++) {
+    const d = perpendicularDistance(
+      points[i].time,
+      points[i].value,
+      first.time,
+      first.value,
+      last.time,
+      last.value,
+    );
+    if (d > maxDist) {
+      maxDist = d;
+      maxIndex = i;
+    }
+  }
+
+  if (maxDist > epsilon) {
+    const left = simplifyTimeSeries(points.slice(0, maxIndex + 1), epsilon);
+    const right = simplifyTimeSeries(points.slice(maxIndex), epsilon);
+    // left includes maxIndex, right starts with maxIndex — drop the duplicate
+    return left.slice(0, -1).concat(right);
+  }
+
+  return [first, last];
+}
+
+// ---------------------------------------------------------------------------
+// Multi-property gesture simplification
+// ---------------------------------------------------------------------------
+
+/**
+ * Simplify gesture recording samples into percentage-keyed keyframes.
+ *
+ * Runs `simplifyTimeSeries` independently per property across all samples,
+ * then merges the retained time points into a single Map keyed by percentage
+ * of `totalDuration` (0–100, rounded to 1 decimal).
+ *
+ * Independent per-property simplification means that complex motion on one
+ * property (e.g. `x`) does not force extra keyframes on a simpler property
+ * (e.g. `opacity`).
+ *
+ * At each retained percentage the output contains all properties interpolated
+ * at that time — not just the property that caused the time point to survive.
+ */
+export function simplifyGestureSamples(
+  samples: Array<{ time: number; properties: Record<string, number> }>,
+  totalDuration: number,
+  epsilon: number,
+): Map<number, Record<string, number>> {
+  if (samples.length === 0) return new Map();
+  if (totalDuration <= 0) return new Map();
+
+  // Collect all property keys present across samples
+  const propertyKeys = new Set<string>();
+  for (const s of samples) {
+    for (const key of Object.keys(s.properties)) {
+      propertyKeys.add(key);
+    }
+  }
+
+  // Run RDP independently per property and collect surviving times
+  const survivingTimes = new Set<number>();
+
+  for (const key of propertyKeys) {
+    const series: Array<{ time: number; value: number }> = [];
+    for (const s of samples) {
+      if (key in s.properties) {
+        series.push({ time: s.time, value: s.properties[key] });
+      }
+    }
+    const simplified = simplifyTimeSeries(series, epsilon);
+    for (const pt of simplified) {
+      survivingTimes.add(pt.time);
+    }
+  }
+
+  // Sort surviving times so we can iterate in order
+  const sortedTimes = Array.from(survivingTimes).sort((a, b) => a - b);
+
+  // For each surviving time, interpolate all properties and store by percentage
+  const result = new Map<number, Record<string, number>>();
+
+  for (const t of sortedTimes) {
+    const pct = Math.round((t / totalDuration) * 1000) / 10; // 1 decimal
+    const props: Record<string, number> = {};
+
+    for (const key of propertyKeys) {
+      props[key] = interpolatePropertyAtTime(samples, key, t);
+    }
+
+    result.set(pct, props);
+  }
+
+  return result;
+}
+
+/**
+ * Linearly interpolate a single property value at the given time from the
+ * samples array.  Assumes samples are sorted by time.
+ */
+function interpolatePropertyAtTime(
+  samples: Array<{ time: number; properties: Record<string, number> }>,
+  key: string,
+  t: number,
+): number {
+  // Find bracketing samples that contain this property
+  let before: { time: number; value: number } | undefined;
+  let after: { time: number; value: number } | undefined;
+
+  for (const s of samples) {
+    if (!(key in s.properties)) continue;
+    const v = s.properties[key];
+
+    if (s.time <= t) {
+      before = { time: s.time, value: v };
+    }
+    if (s.time >= t && after === undefined) {
+      after = { time: s.time, value: v };
+    }
+  }
+
+  // Exact match or only one side available
+  if (before && before.time === t) return before.value;
+  if (after && after.time === t) return after.value;
+  if (!before) return after!.value;
+  if (!after) return before.value;
+
+  // Linear interpolation
+  const ratio = (t - before.time) / (after.time - before.time);
+  return before.value + (after.value - before.value) * ratio;
+}

package/src/utils/sourcePatcher.ts

@@ -92,6 +92,8 @@ export interface PatchOperation {
   value: string | null;
 }
 
+// Runtime validation for hfId lives in findTagByTarget → execDataAttrPattern (CSS attr-value
+// escape). This type is documentation only; the server's MutationTarget mirrors this shape.
 export interface PatchTarget {
   id?: string | null;
   hfId?: string;