@hyperframes/studio 0.7.5 → 0.7.6

package/src/utils/marqueeGeometry.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, it } from "vitest";
+import { marqueeIntersectsObb, rectsOverlap, type Point, type Rect } from "./marqueeGeometry";
+
+type Corners = [Point, Point, Point, Point];
+
+function rotateCorners(cx: number, cy: number, w: number, h: number, deg: number): Corners {
+  const rad = (deg * Math.PI) / 180;
+  const cos = Math.cos(rad);
+  const sin = Math.sin(rad);
+  const hw = w / 2;
+  const hh = h / 2;
+  const local: [number, number][] = [
+    [-hw, -hh],
+    [hw, -hh],
+    [hw, hh],
+    [-hw, hh],
+  ];
+  return local.map(([lx, ly]) => ({
+    x: cx + cos * lx - sin * ly,
+    y: cy + sin * lx + cos * ly,
+  })) as Corners;
+}
+
+function aabbCorners(r: Rect): Corners {
+  return [
+    { x: r.left, y: r.top },
+    { x: r.left + r.width, y: r.top },
+    { x: r.left + r.width, y: r.top + r.height },
+    { x: r.left, y: r.top + r.height },
+  ];
+}
+
+describe("rectsOverlap", () => {
+  it("overlapping rects", () => {
+    expect(
+      rectsOverlap(
+        { left: 0, top: 0, width: 10, height: 10 },
+        { left: 5, top: 5, width: 10, height: 10 },
+      ),
+    ).toBe(true);
+  });
+
+  it("non-overlapping rects", () => {
+    expect(
+      rectsOverlap(
+        { left: 0, top: 0, width: 10, height: 10 },
+        { left: 20, top: 20, width: 10, height: 10 },
+      ),
+    ).toBe(false);
+  });
+});
+
+describe("marqueeIntersectsObb", () => {
+  it("axis-aligned overlap", () => {
+    const marquee: Rect = { left: 0, top: 0, width: 100, height: 100 };
+    const corners = aabbCorners({ left: 50, top: 50, width: 80, height: 80 });
+    expect(marqueeIntersectsObb(marquee, corners)).toBe(true);
+  });
+
+  it("axis-aligned no overlap", () => {
+    const marquee: Rect = { left: 0, top: 0, width: 50, height: 50 };
+    const corners = aabbCorners({ left: 100, top: 100, width: 50, height: 50 });
+    expect(marqueeIntersectsObb(marquee, corners)).toBe(false);
+  });
+
+  it("marquee fully contains element", () => {
+    const marquee: Rect = { left: 0, top: 0, width: 200, height: 200 };
+    const corners = aabbCorners({ left: 50, top: 50, width: 20, height: 20 });
+    expect(marqueeIntersectsObb(marquee, corners)).toBe(true);
+  });
+
+  it("element fully contains marquee", () => {
+    const marquee: Rect = { left: 50, top: 50, width: 10, height: 10 };
+    const corners = aabbCorners({ left: 0, top: 0, width: 200, height: 200 });
+    expect(marqueeIntersectsObb(marquee, corners)).toBe(true);
+  });
+
+  it("45-degree rotated square: AABB overlaps but OBB does not", () => {
+    // 100x100 square rotated 45° centered at (200,200)
+    // Its AABB extends to ~(129,129)-(271,271)
+    // A marquee at (0,0)-(135,135) overlaps the AABB but NOT the diamond
+    const corners = rotateCorners(200, 200, 100, 100, 45);
+    const marquee: Rect = { left: 0, top: 0, width: 135, height: 135 };
+    expect(marqueeIntersectsObb(marquee, corners)).toBe(false);
+  });
+
+  it("45-degree rotated square: OBB overlaps", () => {
+    // Same rotated square, marquee reaches the diamond's left point
+    const corners = rotateCorners(200, 200, 100, 100, 45);
+    const marquee: Rect = { left: 0, top: 150, width: 155, height: 100 };
+    expect(marqueeIntersectsObb(marquee, corners)).toBe(true);
+  });
+
+  it("zero-width marquee returns false", () => {
+    const corners = aabbCorners({ left: 0, top: 0, width: 100, height: 100 });
+    expect(marqueeIntersectsObb({ left: 50, top: 50, width: 0, height: 50 }, corners)).toBe(false);
+  });
+
+  it("zero-area element returns false for degenerate OBB", () => {
+    const corners: Corners = [
+      { x: 50, y: 50 },
+      { x: 50, y: 50 },
+      { x: 50, y: 50 },
+      { x: 50, y: 50 },
+    ];
+    const marquee: Rect = { left: 0, top: 0, width: 100, height: 100 };
+    // Degenerate point — SAT still works (projections are zero-length intervals)
+    // A point inside the marquee should still intersect
+    expect(marqueeIntersectsObb(marquee, corners)).toBe(true);
+  });
+
+  it("30-degree rotated rectangle clips marquee corner", () => {
+    const corners = rotateCorners(150, 150, 200, 50, 30);
+    const marquee: Rect = { left: 0, top: 0, width: 80, height: 130 };
+    expect(marqueeIntersectsObb(marquee, corners)).toBe(true);
+  });
+
+  it("30-degree rotated rectangle misses marquee", () => {
+    const corners = rotateCorners(300, 300, 50, 50, 30);
+    const marquee: Rect = { left: 0, top: 0, width: 100, height: 100 };
+    expect(marqueeIntersectsObb(marquee, corners)).toBe(false);
+  });
+});

package/src/utils/marqueeGeometry.ts

@@ -0,0 +1,172 @@
+export interface Point {
+  x: number;
+  y: number;
+}
+
+export interface Rect {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+type Corners = [Point, Point, Point, Point];
+
+function isIdentityMatrix(m: DOMMatrix): boolean {
+  const e = 1e-6;
+  return Math.abs(m.a - 1) < e && Math.abs(m.b) < e && Math.abs(m.c) < e && Math.abs(m.d - 1) < e;
+}
+
+function rectsOverlap(a: Rect, b: Rect): boolean {
+  return (
+    a.left < b.left + b.width &&
+    a.left + a.width > b.left &&
+    a.top < b.top + b.height &&
+    a.top + a.height > b.top
+  );
+}
+
+function projectOntoAxis(corners: Corners, ax: number, ay: number): [number, number] {
+  let min = Infinity;
+  let max = -Infinity;
+  for (const c of corners) {
+    const dot = c.x * ax + c.y * ay;
+    if (dot < min) min = dot;
+    if (dot > max) max = dot;
+  }
+  return [min, max];
+}
+
+function projectionsOverlap(a: [number, number], b: [number, number]): boolean {
+  return a[0] <= b[1] && b[0] <= a[1];
+}
+
+/**
+ * SAT intersection test between an axis-aligned marquee rect and a
+ * convex quadrilateral (the element's OBB corners in overlay space).
+ *
+ * Separating axes: 2 from the AABB (horizontal, vertical) + 2 from
+ * the OBB's edge normals. If projections overlap on all 4 axes, the
+ * shapes intersect.
+ */
+export function marqueeIntersectsObb(marquee: Rect, corners: Corners): boolean {
+  if (marquee.width <= 0 || marquee.height <= 0) return false;
+
+  const mCorners: Corners = [
+    { x: marquee.left, y: marquee.top },
+    { x: marquee.left + marquee.width, y: marquee.top },
+    { x: marquee.left + marquee.width, y: marquee.top + marquee.height },
+    { x: marquee.left, y: marquee.top + marquee.height },
+  ];
+
+  // AABB axes: (1,0) and (0,1)
+  const mProjX: [number, number] = [marquee.left, marquee.left + marquee.width];
+  const mProjY: [number, number] = [marquee.top, marquee.top + marquee.height];
+
+  const oProjX = projectOntoAxis(corners, 1, 0);
+  const oProjY = projectOntoAxis(corners, 0, 1);
+
+  if (!projectionsOverlap(mProjX, oProjX)) return false;
+  if (!projectionsOverlap(mProjY, oProjY)) return false;
+
+  // OBB edge normals (only need 2 — edges 0→1 and 1→2)
+  for (let i = 0; i < 2; i++) {
+    const edge = {
+      x: corners[i + 1].x - corners[i].x,
+      y: corners[i + 1].y - corners[i].y,
+    };
+    const len = Math.hypot(edge.x, edge.y);
+    if (len < 1e-9) continue;
+    const ax = -edge.y / len;
+    const ay = edge.x / len;
+
+    const mProj = projectOntoAxis(mCorners, ax, ay);
+    const oProj = projectOntoAxis(corners, ax, ay);
+    if (!projectionsOverlap(mProj, oProj)) return false;
+  }
+
+  return true;
+}
+
+/**
+ * Compute the four corners of an element's OBB in overlay-pixel space.
+ *
+ * For elements with an identity transform, returns the axis-aligned
+ * corners from the element's BCR mapped to overlay space (fast path).
+ */
+// fallow-ignore-next-line complexity
+export function elementObbCorners(
+  element: HTMLElement,
+  overlayEl: HTMLDivElement,
+  iframe: HTMLIFrameElement,
+): Corners | null {
+  const doc = iframe.contentDocument;
+  if (!doc) return null;
+
+  const iframeRect = iframe.getBoundingClientRect();
+  const overlayRect = overlayEl.getBoundingClientRect();
+  const root = doc.querySelector<HTMLElement>("[data-composition-id]") ?? doc.documentElement;
+  const declaredW = Number.parseFloat(root?.getAttribute("data-width") ?? "");
+  const declaredH = Number.parseFloat(root?.getAttribute("data-height") ?? "");
+  const rootW = declaredW > 0 ? declaredW : root?.getBoundingClientRect().width || 1;
+  const rootH = declaredH > 0 ? declaredH : root?.getBoundingClientRect().height || 1;
+
+  const scaleX = iframeRect.width / rootW;
+  const scaleY = iframeRect.height / rootH;
+  const offsetX = iframeRect.left - overlayRect.left;
+  const offsetY = iframeRect.top - overlayRect.top;
+
+  const win = element.ownerDocument.defaultView;
+  if (!win) return null;
+
+  const transform = win.getComputedStyle(element).transform;
+  const m = transform && transform !== "none" ? new DOMMatrix(transform) : new DOMMatrix();
+
+  if (isIdentityMatrix(m)) {
+    const r = element.getBoundingClientRect();
+    const left = offsetX + r.left * scaleX;
+    const top = offsetY + r.top * scaleY;
+    const w = r.width * scaleX;
+    const h = r.height * scaleY;
+    return [
+      { x: left, y: top },
+      { x: left + w, y: top },
+      { x: left + w, y: top + h },
+      { x: left, y: top + h },
+    ];
+  }
+
+  // Walk offsetParent chain for pre-transform position
+  let ox = 0;
+  let oy = 0;
+  let el: HTMLElement | null = element;
+  while (el && el !== doc.body && el !== doc.documentElement) {
+    ox += el.offsetLeft;
+    oy += el.offsetTop;
+    el = el.offsetParent as HTMLElement | null;
+  }
+
+  const w = element.offsetWidth;
+  const h = element.offsetHeight;
+  // ponytail: center-based transform — CSS transforms originate at 50% 50%
+  const cx = ox + w / 2;
+  const cy = oy + h / 2;
+
+  const localCorners: [number, number][] = [
+    [-w / 2, -h / 2],
+    [w / 2, -h / 2],
+    [w / 2, h / 2],
+    [-w / 2, h / 2],
+  ];
+
+  return localCorners.map(([lx, ly]) => {
+    const tx = m.a * lx + m.c * ly + cx;
+    const ty = m.b * lx + m.d * ly + cy;
+    return {
+      x: offsetX + tx * scaleX,
+      y: offsetY + ty * scaleY,
+    };
+  }) as Corners;
+}
+
+export { rectsOverlap };

package/src/utils/optimisticUpdate.ts

@@ -11,8 +11,7 @@ export async function executeOptimistic<T>(options: OptimisticUpdateOptions<T>):
   const snapshot = options.apply();
   try {
     await options.persist();
-  } catch (error) {
+  } catch {
     options.rollback(snapshot);
-    console.warn("[optimistic] Mutation failed, rolled back:", error);
   }
 }

package/src/utils/sourcePatcher.ts

@@ -239,16 +239,6 @@ function execDataAttrPattern(html: string, attr: string, value: string): TagMatc
   const pattern = new RegExp(`(<[^>]*\\b${attr}=(["'])${escapeRegex(value)}\\2[^>]*)>`, "i");
   const match = pattern.exec(html);
   if (match?.index == null) return null;
-  // Defensive: a second exact match means a duplicate id/attr in the source
-  // (id drift). Don't silently patch the first while leaving the other stale —
-  // surface it. By the mint contract this should never fire.
-  const all = html.match(new RegExp(`<[^>]*\\b${attr}=(["'])${escapeRegex(value)}\\1[^>]*>`, "gi"));
-  if (all && all.length > 1) {
-    // eslint-disable-next-line no-console
-    console.warn(
-      `sourcePatcher: ${attr}="${value}" matched ${all.length} elements; patching the first. ids/attrs must be unique per document.`,
-    );
-  }
   return { tag: match[1], start: match.index, end: match.index + match[1].length };
 }
 

package/src/utils/velocityEaseFitter.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+import { fitEasesFromVelocity, type FittedKeyframe } from "./velocityEaseFitter";
+
+function makeSamples(
+  count: number,
+  duration: number,
+  velocityFn: (t: number) => number,
+): { time: number; properties: Record<string, number> }[] {
+  const samples = [];
+  let pos = 0;
+  for (let i = 0; i <= count; i++) {
+    const t = (i / count) * duration;
+    const v = velocityFn(t / duration);
+    pos += v * (duration / count);
+    samples.push({ time: t, properties: { x: pos } });
+  }
+  return samples;
+}
+
+describe("fitEasesFromVelocity", () => {
+  it("constant speed → no ease assigned", () => {
+    const kfs: FittedKeyframe[] = [
+      { percentage: 0, properties: { x: 0 } },
+      { percentage: 100, properties: { x: 100 } },
+    ];
+    const samples = makeSamples(60, 1, () => 100);
+    const result = fitEasesFromVelocity(kfs, samples, 1);
+    expect(result[1].ease).toBeUndefined();
+  });
+
+  it("decelerate at end → AE Easy Ease In (slow-end curve)", () => {
+    const kfs: FittedKeyframe[] = [
+      { percentage: 0, properties: { x: 0 } },
+      { percentage: 100, properties: { x: 100 } },
+    ];
+    // Start fast, end slow → playback must also be slow at the end (CP2 y=1).
+    const samples = makeSamples(60, 1, (t) => Math.max(0, 200 * (1 - t)));
+    const result = fitEasesFromVelocity(kfs, samples, 1);
+    expect(result[1].ease).toBe("custom(M0,0 C0.333,0.333 0.667,1 1,1)");
+  });
+
+  it("accelerate from start → AE Easy Ease Out (slow-start curve)", () => {
+    const kfs: FittedKeyframe[] = [
+      { percentage: 0, properties: { x: 0 } },
+      { percentage: 100, properties: { x: 100 } },
+    ];
+    // Start slow, end fast → playback must also be slow at the start (CP1 y=0).
+    const samples = makeSamples(60, 1, (t) => 200 * t);
+    const result = fitEasesFromVelocity(kfs, samples, 1);
+    expect(result[1].ease).toBe("custom(M0,0 C0.333,0 0.667,0.667 1,1)");
+  });
+
+  it("single keyframe → returns unchanged", () => {
+    const kfs: FittedKeyframe[] = [{ percentage: 0, properties: { x: 0 } }];
+    const result = fitEasesFromVelocity(kfs, [], 1);
+    expect(result).toEqual(kfs);
+  });
+});

package/src/utils/velocityEaseFitter.ts

@@ -0,0 +1,121 @@
+interface TimedSample {
+  time: number;
+  value: number;
+}
+
+// After Effects convention (ease named by the keyframe side it acts on):
+//   Easy Ease     — slow at both ends (cubic-bezier 0.333,0 0.667,1)
+//   Easy Ease In   — eases *into* the keyframe → decelerates → slow at the END
+//   Easy Ease Out  — eases *out of* the keyframe → accelerates → slow at the START
+// The control-point y values must match that polarity (a flat tangent at the
+// slow side): slow-end pins CP2 at y=1, slow-start pins CP1 at y=0.
+const AE_EASE = "custom(M0,0 C0.333,0 0.667,1 1,1)";
+const AE_EASE_IN = "custom(M0,0 C0.333,0.333 0.667,1 1,1)";
+const AE_EASE_OUT = "custom(M0,0 C0.333,0 0.667,0.667 1,1)";
+const VELOCITY_THRESHOLD = 0.3;
+
+function averageSpeed(samples: TimedSample[], from: number, to: number): number {
+  const seg = samples.filter((s) => s.time >= from && s.time <= to);
+  if (seg.length < 2) return 0;
+  let total = 0;
+  for (let i = 1; i < seg.length; i++) {
+    const dt = seg[i].time - seg[i - 1].time;
+    if (dt > 0) total += Math.abs(seg[i].value - seg[i - 1].value) / dt;
+  }
+  return total / (seg.length - 1);
+}
+
+function speedAtEdge(
+  samples: TimedSample[],
+  t: number,
+  window: number,
+  side: "start" | "end",
+): number {
+  const near = samples.filter((s) =>
+    side === "start" ? s.time >= t && s.time <= t + window : s.time >= t - window && s.time <= t,
+  );
+  if (near.length < 2) return 0;
+  let total = 0;
+  for (let i = 1; i < near.length; i++) {
+    const dt = near[i].time - near[i - 1].time;
+    if (dt > 0) total += Math.abs(near[i].value - near[i - 1].value) / dt;
+  }
+  return total / (near.length - 1);
+}
+
+export interface FittedKeyframe {
+  percentage: number;
+  properties: Record<string, number | string>;
+  ease?: string;
+}
+
+/**
+ * Analyze velocity profile of raw samples between keyframes and assign
+ * per-keyframe eases based on deceleration/acceleration patterns.
+ *
+ * For each segment between consecutive keyframes:
+ * - Constant speed → linear ("none")
+ * - Decelerates at end → Easy Ease In
+ * - Accelerates from start → Easy Ease Out
+ * - Both → Easy Ease (full)
+ */
+// fallow-ignore-next-line complexity
+export function fitEasesFromVelocity(
+  keyframes: FittedKeyframe[],
+  rawSamples: { time: number; properties: Record<string, number> }[],
+  totalDuration: number,
+): FittedKeyframe[] {
+  if (keyframes.length < 2 || rawSamples.length < 3) return keyframes;
+
+  const result = [...keyframes.map((kf) => ({ ...kf }))];
+
+  for (let i = 1; i < result.length; i++) {
+    const prevPct = result[i - 1].percentage;
+    const currPct = result[i].percentage;
+    const segStart = (prevPct / 100) * totalDuration;
+    const segEnd = (currPct / 100) * totalDuration;
+    const segDur = segEnd - segStart;
+    if (segDur <= 0) continue;
+
+    // Use the dominant property (largest range) for velocity analysis
+    const props = Object.keys(result[i].properties);
+    let bestProp = props[0] ?? "x";
+    let bestRange = 0;
+    for (const p of props) {
+      const startVal = Number(result[i - 1].properties[p] ?? 0);
+      const endVal = Number(result[i].properties[p] ?? 0);
+      const range = Math.abs(endVal - startVal);
+      if (range > bestRange) {
+        bestRange = range;
+        bestProp = p;
+      }
+    }
+
+    const propSamples: TimedSample[] = rawSamples
+      .filter((s) => s.time >= segStart && s.time <= segEnd)
+      .map((s) => ({ time: s.time, value: s.properties[bestProp] ?? 0 }));
+
+    if (propSamples.length < 3) continue;
+
+    const edgeWindow = segDur * 0.25;
+    const avgSpd = averageSpeed(propSamples, segStart, segEnd);
+    if (avgSpd < 1e-6) continue;
+
+    const startSpd = speedAtEdge(propSamples, segStart, edgeWindow, "start");
+    const endSpd = speedAtEdge(propSamples, segEnd, edgeWindow, "end");
+
+    const slowStart = startSpd / avgSpd < VELOCITY_THRESHOLD;
+    const slowEnd = endSpd / avgSpd < VELOCITY_THRESHOLD;
+
+    if (slowStart && slowEnd) {
+      result[i].ease = AE_EASE;
+    } else if (slowEnd) {
+      result[i].ease = AE_EASE_IN;
+    } else if (slowStart) {
+      result[i].ease = AE_EASE_OUT;
+    }
+    // Otherwise leave ease undefined → linear (constant speed)
+  }
+
+  return result;
+}