@hyperframes/studio 0.6.72 → 0.6.74

package/src/components/TimelineToolbar.tsx

@@ -3,25 +3,251 @@ import {
   getTimelineZoomPercent,
 } from "../player/components/timelineZoom";
 import { getTimelineToggleTitle } from "../utils/timelineDiscovery";
-import { usePlayerStore } from "../player";
+import { usePlayerStore, type TimelineElement } from "../player";
+import { STUDIO_KEYFRAMES_ENABLED } from "./editor/manualEditingAvailability";
 import { Tooltip } from "./ui";
+import { Scissors } from "../icons/SystemIcons";
+import type { GsapAnimation, GsapPercentageKeyframe } from "@hyperframes/core/gsap-parser";
+import type { DomEditSelection } from "./editor/domEditingTypes";
+
+function interpolateKeyframeProperties(
+  keyframes: GsapPercentageKeyframe[],
+  pct: number,
+): Record<string, number> {
+  const sorted = keyframes.slice().sort((a, b) => a.percentage - b.percentage);
+  const allProps = new Set<string>();
+  for (const kf of sorted) {
+    for (const p of Object.keys(kf.properties)) {
+      if (typeof kf.properties[p] === "number") allProps.add(p);
+    }
+  }
+  const result: Record<string, number> = {};
+  for (const prop of allProps) {
+    let prev: { pct: number; val: number } | null = null;
+    let next: { pct: number; val: number } | null = null;
+    for (const kf of sorted) {
+      const v = kf.properties[prop];
+      if (typeof v !== "number") continue;
+      if (kf.percentage <= pct) prev = { pct: kf.percentage, val: v };
+      if (kf.percentage >= pct && !next) next = { pct: kf.percentage, val: v };
+    }
+    if (prev && next && prev.pct !== next.pct) {
+      const t = (pct - prev.pct) / (next.pct - prev.pct);
+      result[prop] = Math.round(prev.val + t * (next.val - prev.val));
+    } else if (prev) {
+      result[prop] = Math.round(prev.val);
+    } else if (next) {
+      result[prop] = Math.round(next.val);
+    }
+  }
+  return result;
+}
+
+function readRuntimeKeyframeValues(
+  iframe: HTMLIFrameElement | null,
+  sel: DomEditSelection,
+  keyframes: GsapPercentageKeyframe[],
+): Record<string, number> {
+  if (!iframe?.contentWindow) return {};
+  let gsap: { getProperty?: (el: Element, prop: string) => number } | undefined;
+  try {
+    gsap = (iframe.contentWindow as Window & { gsap?: typeof gsap }).gsap;
+  } catch {
+    return {};
+  }
+  if (!gsap?.getProperty) return {};
+  const selector = sel.id ? `#${sel.id}` : sel.selector;
+  if (!selector) return {};
+  let doc: Document | null = null;
+  try {
+    doc = iframe.contentDocument;
+  } catch {
+    return {};
+  }
+  const element = doc?.querySelector(selector);
+  if (!element) return {};
+  const allProps = new Set<string>();
+  for (const kf of keyframes) {
+    for (const p of Object.keys(kf.properties)) {
+      if (typeof kf.properties[p] === "number") allProps.add(p);
+    }
+  }
+  const result: Record<string, number> = {};
+  for (const prop of allProps) {
+    const val = Number(gsap.getProperty(element, prop));
+    if (Number.isFinite(val)) result[prop] = Math.round(val);
+  }
+  return result;
+}
+
+interface DomEditSessionSlice {
+  domEditSelection: DomEditSelection | null;
+  selectedGsapAnimations: GsapAnimation[];
+  handleGsapRemoveKeyframe: (animId: string, pct: number) => void;
+  handleGsapAddKeyframe: (animId: string, pct: number, prop: string, val: number | string) => void;
+  handleGsapConvertToKeyframes: (animId: string) => void;
+  handleGsapMaterializeKeyframes?: (animId: string) => Promise<void>;
+  handleGsapAddAnimation: (method: "to" | "from" | "set" | "fromTo") => void;
+  previewIframeRef?: React.RefObject<HTMLIFrameElement | null>;
+}
 
 interface TimelineToolbarProps {
   toggleTimelineVisibility: () => void;
+  domEditSession?: DomEditSessionSlice;
+  onSplitElement?: (element: TimelineElement, splitTime: number) => void;
 }
 
-export function TimelineToolbar({ toggleTimelineVisibility }: TimelineToolbarProps) {
+// fallow-ignore-next-line complexity
+function useKeyframeToggle(session?: DomEditSessionSlice) {
+  const currentTime = usePlayerStore((s) => s.currentTime);
+  if (!session) return { state: "none" as const, onToggle: undefined };
+
+  const sel = session.domEditSelection;
+  const anims = session.selectedGsapAnimations;
+  const kfAnim = anims.find((a) => a.keyframes);
+  const flatAnim = anims.find((a) => !a.keyframes);
+
+  let state: "active" | "inactive" | "none" = "none";
+  if (kfAnim?.keyframes && sel) {
+    const elStart = Number.parseFloat(sel.dataAttributes?.start ?? "0") || 0;
+    const elDuration = Number.parseFloat(sel.dataAttributes?.duration ?? "1") || 1;
+    const pct =
+      elDuration > 0
+        ? Math.max(0, Math.min(100, Math.round(((currentTime - elStart) / elDuration) * 1000) / 10))
+        : 0;
+    state = kfAnim.keyframes.keyframes.some((k) => Math.abs(k.percentage - pct) <= 1)
+      ? "active"
+      : "inactive";
+  }
+
+  // fallow-ignore-next-line complexity
+  const onToggle = sel
+    ? async () => {
+        const t = usePlayerStore.getState().currentTime;
+        if (kfAnim?.keyframes) {
+          if (kfAnim.hasUnresolvedKeyframes) {
+            await session.handleGsapMaterializeKeyframes?.(kfAnim.id);
+          }
+          const elStart = Number.parseFloat(sel.dataAttributes?.start ?? "0") || 0;
+          const elDuration = Number.parseFloat(sel.dataAttributes?.duration ?? "1") || 1;
+          const pct =
+            elDuration > 0
+              ? Math.max(0, Math.min(100, Math.round(((t - elStart) / elDuration) * 1000) / 10))
+              : 0;
+          const existing = kfAnim.keyframes.keyframes.find(
+            (k) => Math.abs(k.percentage - pct) <= 1,
+          );
+          if (existing) {
+            session.handleGsapRemoveKeyframe(kfAnim.id, existing.percentage);
+          } else {
+            const runtimeValues = readRuntimeKeyframeValues(
+              session.previewIframeRef?.current ?? null,
+              sel,
+              kfAnim.keyframes.keyframes,
+            );
+            const values =
+              Object.keys(runtimeValues).length > 0
+                ? runtimeValues
+                : interpolateKeyframeProperties(kfAnim.keyframes.keyframes, pct);
+            for (const [prop, val] of Object.entries(values)) {
+              session.handleGsapAddKeyframe(kfAnim.id, pct, prop, val);
+            }
+          }
+        } else if (flatAnim) {
+          session.handleGsapConvertToKeyframes(flatAnim.id);
+        } else {
+          session.handleGsapAddAnimation("to");
+        }
+      }
+    : undefined;
+
+  return { state, onToggle };
+}
+
+export function TimelineToolbar({
+  toggleTimelineVisibility,
+  domEditSession,
+  onSplitElement,
+}: TimelineToolbarProps) {
   const zoomMode = usePlayerStore((s) => s.zoomMode);
   const manualZoomPercent = usePlayerStore((s) => s.manualZoomPercent);
   const setZoomMode = usePlayerStore((s) => s.setZoomMode);
   const setManualZoomPercent = usePlayerStore((s) => s.setManualZoomPercent);
   const displayedTimelineZoomPercent = getTimelineZoomPercent(zoomMode, manualZoomPercent);
+  const { state: keyframeState, onToggle: onToggleKeyframe } = useKeyframeToggle(domEditSession);
 
   return (
     <div className="border-b border-neutral-800/40 bg-neutral-950/96">
       <div className="flex items-center justify-between px-3 py-2">
-        <div className="text-[10px] font-medium uppercase tracking-[0.16em] text-neutral-500">
-          Timeline
+        <div className="flex items-center gap-3">
+          <div className="text-[10px] font-medium uppercase tracking-[0.16em] text-neutral-500">
+            Timeline
+          </div>
+          {STUDIO_KEYFRAMES_ENABLED && onToggleKeyframe && (
+            <Tooltip
+              label={
+                keyframeState === "active"
+                  ? "Remove keyframe at playhead"
+                  : keyframeState === "inactive"
+                    ? "Add keyframe at playhead"
+                    : "Enable keyframes"
+              }
+            >
+              <button
+                type="button"
+                onClick={onToggleKeyframe}
+                className={`flex h-7 w-7 items-center justify-center rounded transition-colors ${
+                  keyframeState === "active"
+                    ? "text-studio-accent"
+                    : keyframeState === "inactive"
+                      ? "text-neutral-400 hover:text-studio-accent"
+                      : "text-neutral-600 hover:text-neutral-400"
+                }`}
+              >
+                <svg width="18" height="18" viewBox="0 0 10 10" fill="currentColor">
+                  {keyframeState === "active" ? (
+                    <path d="M5 0.5L9.5 5L5 9.5L0.5 5Z" />
+                  ) : (
+                    <path
+                      d="M5 1.2L8.8 5L5 8.8L1.2 5Z"
+                      fill="none"
+                      stroke="currentColor"
+                      strokeWidth="1.2"
+                    />
+                  )}
+                </svg>
+              </button>
+            </Tooltip>
+          )}
+          {onSplitElement &&
+            (() => {
+              const { selectedElementId, elements, currentTime } = usePlayerStore.getState();
+              const el = selectedElementId
+                ? elements.find((e) => (e.key ?? e.id) === selectedElementId)
+                : null;
+              const splittable =
+                el && !el.compositionSrc && ["video", "audio", "img"].includes(el.tag);
+              if (!splittable) return null;
+              const canSplit = currentTime > el.start && currentTime < el.start + el.duration;
+              return (
+                <Tooltip label="Split clip at playhead (S)">
+                  <button
+                    type="button"
+                    disabled={!canSplit}
+                    onClick={() => {
+                      if (canSplit) onSplitElement(el, currentTime);
+                    }}
+                    className={`flex h-7 w-7 items-center justify-center rounded transition-colors ${
+                      canSplit
+                        ? "text-neutral-500 hover:text-neutral-200"
+                        : "text-neutral-700 cursor-not-allowed"
+                    }`}
+                  >
+                    <Scissors size={15} />
+                  </button>
+                </Tooltip>
+              );
+            })()}
         </div>
         <div className="flex items-center gap-1">
           <Tooltip label="Fit timeline to width">

package/src/components/editor/AnimationCard.tsx

@@ -9,13 +9,29 @@ import {
   METHOD_LABELS,
   METHOD_TOOLTIPS,
   PERCENT_PROPS,
+  PROP_CONSTRAINTS,
   PROP_LABELS,
   PROP_TOOLTIPS,
   PROP_UNITS,
+  clampPropertyValue,
 } from "./gsapAnimationConstants";
 import { buildTweenSummary } from "./gsapAnimationHelpers";
 import { EaseCurveSection } from "./EaseCurveSection";
 const BOOLEAN_PROPS = new Set(["visibility"]);
+const STRING_PROPS = new Set(["filter", "clipPath"]);
+
+const FILTER_PRESETS = [
+  { label: "Blur", value: "blur(4px)" },
+  { label: "Bright", value: "brightness(1.5)" },
+  { label: "Gray", value: "grayscale(1)" },
+  { label: "None", value: "none" },
+];
+
+const CLIP_PATH_PRESETS = [
+  { label: "Circle", value: "circle(50% at 50% 50%)" },
+  { label: "Inset", value: "inset(10%)" },
+  { label: "None", value: "none" },
+];
 
 function isPercentProp(prop: string): boolean {
   return PERCENT_PROPS.has(prop);
@@ -27,7 +43,11 @@ function displayValue(prop: string, val: number | string): string {
 }
 
 function adjustedValue(prop: string, raw: string): string {
-  if (isPercentProp(prop)) return String(Math.max(0, Math.min(1, Number(raw) / 100)));
+  if (isPercentProp(prop)) return String(clampPropertyValue(prop, Number(raw) / 100));
+  const num = Number(raw);
+  if (!Number.isNaN(num) && PROP_CONSTRAINTS[prop]) {
+    return String(clampPropertyValue(prop, num));
+  }
   return raw;
 }
 
@@ -90,6 +110,48 @@ function PropertyRow({
     );
   }
 
+  if (STRING_PROPS.has(prop)) {
+    const presets =
+      prop === "filter" ? FILTER_PRESETS : prop === "clipPath" ? CLIP_PATH_PRESETS : [];
+    return (
+      <div className="flex flex-col gap-1">
+        <div className="flex items-center gap-1">
+          <div className="min-w-0 flex-1 flex items-center gap-2 px-2 py-1 rounded-lg bg-neutral-900 border border-neutral-800">
+            <span className="flex-shrink-0 text-[11px] font-medium text-neutral-500">
+              {PROP_LABELS[prop] ?? prop}
+            </span>
+            <input
+              type="text"
+              defaultValue={String(val)}
+              className="flex-1 bg-transparent text-[11px] text-neutral-200 outline-none"
+              onBlur={(e) => onCommit(e.currentTarget.value)}
+              onKeyDown={(e) => {
+                if (e.key === "Enter") {
+                  e.currentTarget.blur();
+                }
+              }}
+            />
+          </div>
+          <RemoveButton onClick={onRemove} title={removeTitle} />
+        </div>
+        {presets.length > 0 && (
+          <div className="flex gap-1 pl-1">
+            {presets.map((p) => (
+              <button
+                key={p.value}
+                type="button"
+                onClick={() => onCommit(p.value)}
+                className="px-1.5 py-0.5 rounded text-[9px] font-medium text-neutral-500 bg-neutral-800/50 hover:bg-neutral-800 hover:text-neutral-300 transition-colors"
+              >
+                {p.label}
+              </button>
+            ))}
+          </div>
+        )}
+      </div>
+    );
+  }
+
   return (
     <div className="flex items-center gap-1">
       <div className="min-w-0 flex-1">
@@ -292,8 +354,10 @@ export const AnimationCard = memo(function AnimationCard({
           {methodLabel}
         </span>
         <span className="text-[11px] font-medium text-neutral-400" title="When this effect plays">
-          {typeof animation.position === "number" ? `${animation.position}s` : animation.position} –{" "}
-          {typeof endTime === "number" ? `${endTime.toFixed(1)}s` : endTime}
+          {typeof animation.position === "number"
+            ? `${parseFloat(animation.position.toFixed(3))}s`
+            : animation.position}{" "}
+          – {typeof endTime === "number" ? `${parseFloat(endTime.toFixed(3))}s` : endTime}
         </span>
         <span className="ml-auto text-[10px] text-neutral-500" title={easeName}>
           {easeLabel}
@@ -344,7 +408,7 @@ export const AnimationCard = memo(function AnimationCard({
                 value={
                   typeof animation.position === "string"
                     ? animation.position
-                    : String(Math.max(0, animation.position))
+                    : String(parseFloat(Math.max(0, animation.position).toFixed(3)))
                 }
                 suffix={typeof animation.position === "number" ? "s" : undefined}
                 tooltip="When this effect begins on the timeline"

package/src/components/editor/DomEditOverlay.tsx

@@ -1,4 +1,5 @@
-import { memo, useMemo, useRef, type RefObject } from "react";
+import { memo, useMemo, useRef, useState, type RefObject } from "react";
+import { useMountEffect } from "../../hooks/useMountEffect";
 import { type DomEditSelection } from "./domEditing";
 import { resolveDomEditGroupOverlayRect, toOverlayRect } from "./domEditOverlayGeometry";
 import {
@@ -10,6 +11,8 @@ import {
 } from "./domEditOverlayGestures";
 import { useDomEditOverlayRects } from "./useDomEditOverlayRects";
 import { createDomEditOverlayGestureHandlers } from "./useDomEditOverlayGestures";
+import { SnapGuideOverlay, type SnapGuidesState } from "./SnapGuideOverlay";
+import { GridOverlay } from "./GridOverlay";
 
 // Re-exports for external consumers — preserving existing import paths.
 export {
@@ -61,6 +64,8 @@ interface DomEditOverlayProps {
     next: { width: number; height: number },
   ) => Promise<void> | void;
   onRotationCommit: (selection: DomEditSelection, next: { angle: number }) => Promise<void> | void;
+  gridVisible?: boolean;
+  gridSpacing?: number;
 }
 
 export const DomEditOverlay = memo(function DomEditOverlay({
@@ -75,6 +80,8 @@ export const DomEditOverlay = memo(function DomEditOverlay({
   onCanvasPointerLeave,
   onSelectionChange,
   onBlockedMove,
+  gridVisible = false,
+  gridSpacing = 50,
   onManualDragStart,
   onPathOffsetCommit,
   onGroupPathOffsetCommit,
@@ -89,6 +96,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
   const suppressNextBoxClickRef = useRef(false);
   const suppressNextBoxMouseDownRef = useRef(false);
   const suppressNextOverlayMouseDownRef = useRef(false);
+  const snapGuidesRef = useRef<SnapGuidesState | null>(null);
   const rafPausedRef = useRef(false);
 
   const selectionRef = useRef(selection);
@@ -136,6 +144,50 @@ export const DomEditOverlay = memo(function DomEditOverlay({
     rafPausedRef,
   });
 
+  const [compRect, setCompRect] = useState({
+    left: 0,
+    top: 0,
+    width: 0,
+    height: 0,
+    scaleX: 1,
+    scaleY: 1,
+  });
+  useMountEffect(() => {
+    let frame = 0;
+    // fallow-ignore-next-line complexity
+    const update = () => {
+      frame = requestAnimationFrame(update);
+      const iframe = iframeRef.current;
+      const overlayEl = overlayRef.current;
+      if (!iframe || !overlayEl) return;
+      const iRect = iframe.getBoundingClientRect();
+      const oRect = overlayEl.getBoundingClientRect();
+      const left = iRect.left - oRect.left;
+      const top = iRect.top - oRect.top;
+      if (iRect.width <= 0 || iRect.height <= 0) return;
+      const doc = iframe.contentDocument;
+      const root = doc?.querySelector<HTMLElement>("[data-composition-id]") ?? doc?.documentElement;
+      const dw = Number.parseFloat(root?.getAttribute("data-width") ?? "");
+      const dh = Number.parseFloat(root?.getAttribute("data-height") ?? "");
+      const scaleX = dw > 0 ? iRect.width / dw : 1;
+      const scaleY = dh > 0 ? iRect.height / dh : 1;
+      setCompRect((prev) => {
+        if (
+          Math.abs(prev.left - left) < 0.5 &&
+          Math.abs(prev.top - top) < 0.5 &&
+          Math.abs(prev.width - iRect.width) < 0.5 &&
+          Math.abs(prev.height - iRect.height) < 0.5 &&
+          Math.abs(prev.scaleX - scaleX) < 0.001 &&
+          Math.abs(prev.scaleY - scaleY) < 0.001
+        )
+          return prev;
+        return { left, top, width: iRect.width, height: iRect.height, scaleX, scaleY };
+      });
+    };
+    frame = requestAnimationFrame(update);
+    return () => cancelAnimationFrame(frame);
+  });
+
   const gestures = createDomEditOverlayGestureHandlers({
     overlayRef,
     iframeRef,
@@ -158,6 +210,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
     onRotationCommitRef,
     onCanvasPointerMoveRef,
     onCanvasMouseDown,
+    snapGuidesRef,
   });
 
   const selectionKey = useMemo(() => {
@@ -192,6 +245,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
     }
   };
 
+  // fallow-ignore-next-line complexity
   const handleOverlayPointerDown = (event: React.PointerEvent<HTMLDivElement>) => {
     if (!allowCanvasMovement || event.button !== 0) return;
     if (event.shiftKey) {
@@ -387,6 +441,21 @@ export const DomEditOverlay = memo(function DomEditOverlay({
           </div>
         </>
       )}
+      <GridOverlay
+        visible={gridVisible}
+        spacing={gridSpacing}
+        scaleX={compRect.scaleX}
+        scaleY={compRect.scaleY}
+        compositionLeft={compRect.left}
+        compositionTop={compRect.top}
+        compositionWidth={compRect.width}
+        compositionHeight={compRect.height}
+      />
+      <SnapGuideOverlay
+        snapGuidesRef={snapGuidesRef}
+        overlayWidth={compRect.width}
+        overlayHeight={compRect.height}
+      />
     </div>
   );
 });

package/src/components/editor/GridOverlay.tsx

@@ -0,0 +1,50 @@
+// fallow-ignore-file unused-file
+import { memo } from "react";
+
+interface GridOverlayProps {
+  visible: boolean;
+  spacing: number;
+  scaleX: number;
+  scaleY: number;
+  compositionLeft: number;
+  compositionTop: number;
+  compositionWidth: number;
+  compositionHeight: number;
+}
+
+// fallow-ignore-next-line complexity
+export const GridOverlay = memo(function GridOverlay({
+  visible,
+  spacing,
+  scaleX,
+  scaleY,
+  compositionLeft,
+  compositionTop,
+  compositionWidth,
+  compositionHeight,
+}: GridOverlayProps) {
+  if (!visible || spacing <= 0) return null;
+
+  const overlaySpacingX = spacing * scaleX;
+  const overlaySpacingY = spacing * scaleY;
+
+  if (overlaySpacingX < 4 || overlaySpacingY < 4) return null;
+
+  return (
+    <div
+      aria-hidden="true"
+      className="pointer-events-none absolute"
+      style={{
+        left: compositionLeft,
+        top: compositionTop,
+        width: compositionWidth,
+        height: compositionHeight,
+        backgroundImage: [
+          `repeating-linear-gradient(90deg, rgba(255,255,255,0.12) 0px, rgba(255,255,255,0.12) 1px, transparent 1px, transparent ${overlaySpacingX}px)`,
+          `repeating-linear-gradient(0deg, rgba(255,255,255,0.12) 0px, rgba(255,255,255,0.12) 1px, transparent 1px, transparent ${overlaySpacingY}px)`,
+        ].join(", "),
+        backgroundSize: `${overlaySpacingX}px ${overlaySpacingY}px`,
+      }}
+    />
+  );
+});

package/src/components/editor/KeyframeDiamond.tsx

@@ -0,0 +1,49 @@
+import { memo } from "react";
+
+export type DiamondState = "active" | "inactive" | "ghost";
+
+interface KeyframeDiamondProps {
+  state: DiamondState;
+  onClick: () => void;
+  title?: string;
+  size?: number;
+}
+
+// fallow-ignore-next-line complexity
+export const KeyframeDiamond = memo(function KeyframeDiamond({
+  state,
+  onClick,
+  title,
+  size = 10,
+}: KeyframeDiamondProps) {
+  const isFilled = state === "active";
+  const opacity = state === "ghost" ? 0.25 : state === "inactive" ? 0.6 : 1;
+  const color = state === "active" ? "#3b82f6" : "#a3a3a3";
+
+  return (
+    <button
+      type="button"
+      onClick={(e) => {
+        e.stopPropagation();
+        onClick();
+      }}
+      className="flex-shrink-0 p-0.5 transition-opacity hover:opacity-100"
+      style={{ color, opacity }}
+      title={title}
+    >
+      <svg width={size} height={size} viewBox="0 0 10 10">
+        <rect
+          x="5"
+          y="0.7"
+          width="6"
+          height="6"
+          rx="1"
+          transform="rotate(45 5 0.7)"
+          fill={isFilled ? "currentColor" : "none"}
+          stroke="currentColor"
+          strokeWidth="1.2"
+        />
+      </svg>
+    </button>
+  );
+});