@hyperframes/studio 0.6.122-alpha.0 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.6.122-alpha.0",
+  "version": "0.7.1",
   "description": "",
   "repository": {
     "type": "git",
@@ -45,9 +45,9 @@
     "dompurify": "^3.2.4",
     "marked": "^14.1.4",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.6.122-alpha.0",
-    "@hyperframes/player": "0.6.122-alpha.0",
-    "@hyperframes/sdk": "0.6.122-alpha.0"
+    "@hyperframes/core": "0.7.1",
+    "@hyperframes/player": "0.7.1",
+    "@hyperframes/sdk": "0.7.1"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -62,7 +62,7 @@
     "vite": "^6.4.2",
     "vitest": "^3.2.4",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.6.122-alpha.0"
+    "@hyperframes/producer": "0.7.1"
   },
   "peerDependencies": {
     "react": "19",

package/src/App.tsx

@@ -428,6 +428,7 @@ export function StudioApp() {
     domEditSelection: domEditSession.domEditSelection,
     buildDomSelectionFromTarget: domEditSession.buildDomSelectionFromTarget,
     applyDomSelection: domEditSession.applyDomSelection,
+    setRightPanelTab: panelLayout.setRightPanelTab,
     initialState: initialUrlStateRef.current,
   });
   const studioCtxValue = buildStudioContextValue({

package/src/components/StudioHeader.tsx

@@ -8,7 +8,6 @@ import {
 import { getHistoryShortcutLabel } from "../utils/studioHelpers";
 import { useStudioShellContext } from "../contexts/StudioContext";
 import { usePanelLayoutContext } from "../contexts/PanelLayoutContext";
-import { useDomEditActionsContext } from "../contexts/DomEditContext";
 import { useViewMode, type StudioViewMode } from "../contexts/ViewModeContext";
 import { trackStudioEvent } from "../utils/studioTelemetry";
 
@@ -194,7 +193,6 @@ export function StudioHeader({
 }: StudioHeaderProps) {
   const { projectId, editHistory, handleUndo, handleRedo } = useStudioShellContext();
   const { rightCollapsed, setRightCollapsed, setRightPanelTab } = usePanelLayoutContext();
-  const { clearDomSelection } = useDomEditActionsContext();
 
   return (
     <div className="flex items-center justify-between h-10 px-3 bg-neutral-900 border-b border-neutral-800 flex-shrink-0">
@@ -279,7 +277,8 @@ export function StudioHeader({
               return;
             }
             trackStudioEvent("panel_toggle", { panel: "inspector", collapsed: true });
-            clearDomSelection();
+            // Keep the current selection when collapsing the Inspector — closing
+            // the panel shouldn't deselect the element.
             setRightCollapsed(true);
           }}
           disabled={!STUDIO_INSPECTOR_PANELS_ENABLED}

package/src/components/StudioPreviewArea.tsx

@@ -3,6 +3,8 @@ import { NLELayout } from "./nle/NLELayout";
 import { CaptionOverlay } from "../captions/components/CaptionOverlay";
 import { CaptionTimeline } from "../captions/components/CaptionTimeline";
 import { DomEditOverlay } from "./editor/DomEditOverlay";
+import { MotionPathOverlay } from "./editor/MotionPathOverlay";
+import { useCompositionDimensions } from "../hooks/useCompositionDimensions";
 import { SnapToolbar } from "./editor/SnapToolbar";
 import { StudioFeedbackBar } from "./StudioFeedbackBar";
 import type { TimelineElement } from "../player";
@@ -10,6 +12,7 @@ import { usePlayerStore } from "../player/store/playerStore";
 import type { BlockedTimelineEditIntent } from "../player/components/timelineEditing";
 import {
   STUDIO_INSPECTOR_PANELS_ENABLED,
+  STUDIO_KEYFRAMES_ENABLED,
   STUDIO_PREVIEW_MANUAL_EDITING_ENABLED,
   STUDIO_PREVIEW_SELECTION_ENABLED,
 } from "./editor/manualEditingAvailability";
@@ -108,6 +111,7 @@ export function StudioPreviewArea({
     isPlaying,
     refreshPreviewDocumentVersion,
   } = useStudioPlaybackContext();
+  const compositionDimensions = useCompositionDimensions();
 
   const {
     domEditHoverSelection,
@@ -337,6 +341,14 @@ export function StudioPreviewArea({
                     onToggleRecording={onToggleRecording}
                   />
                   <SnapToolbar onSnapChange={setSnapPrefs} />
+                  {STUDIO_KEYFRAMES_ENABLED && (
+                    <MotionPathOverlay
+                      iframeRef={previewIframeRef}
+                      selection={shouldShowSelectedDomBounds ? domEditSelection : null}
+                      compositionSize={compositionDimensions}
+                      isPlaying={isPlaying}
+                    />
+                  )}
                   {gestureOverlay}
                 </>
               ) : null

package/src/components/TimelineToolbar.tsx

@@ -1,5 +1,10 @@
 import { useRef } from "react";
-import { useEnableKeyframes, type EnableKeyframesSession } from "../hooks/useEnableKeyframes";
+import {
+  useEnableKeyframes,
+  isPlayheadWithinTween,
+  type EnableKeyframesSession,
+} from "../hooks/useEnableKeyframes";
+import { computeElementPercentage } from "../hooks/gsapShared";
 import {
   getNextTimelineZoomPercent,
   getTimelineZoomPercent,
@@ -44,23 +49,25 @@ function useKeyframeToggle(session?: DomEditSessionSlice) {
   const anims = session.selectedGsapAnimations;
   const kfAnim = anims.find((a) => a.keyframes);
 
-  const computePct = (time: number) => {
-    const elStart = Number.parseFloat(sel?.dataAttributes?.start ?? "0") || 0;
-    const elDuration = Number.parseFloat(sel?.dataAttributes?.duration ?? "1") || 1;
-    return elDuration > 0
-      ? Math.max(0, Math.min(100, Math.round(((time - elStart) / elDuration) * 1000) / 10))
-      : 0;
-  };
-
   let state: "active" | "inactive" | "none" = "none";
+  // Outside the tween, clicking extends the animation to the playhead rather than
+  // toggling a (clamped) edge keyframe — so the button stays an "add" affordance.
+  let willExtend = false;
   if (kfAnim?.keyframes && sel) {
-    const pct = computePct(currentTime);
-    state = kfAnim.keyframes.keyframes.some((k) => Math.abs(k.percentage - pct) <= 1)
-      ? "active"
-      : "inactive";
+    if (!isPlayheadWithinTween(kfAnim, currentTime)) {
+      state = "inactive";
+      willExtend = true;
+    } else {
+      // Tween-relative percentage (not the clip range) so the button state matches
+      // where the keyframe would actually land.
+      const pct = computeElementPercentage(currentTime, sel, kfAnim);
+      state = kfAnim.keyframes.keyframes.some((k) => Math.abs(k.percentage - pct) <= 1)
+        ? "active"
+        : "inactive";
+    }
   }
 
-  return { state, onToggle: sel ? onToggle : undefined };
+  return { state, willExtend, onToggle: sel ? onToggle : undefined };
 }
 
 // fallow-ignore-next-line complexity
@@ -76,7 +83,11 @@ export function TimelineToolbar({
   const beatAnalysisReady = usePlayerStore((s) => s.beatAnalysis !== null);
   const { zoomMode, manualZoomPercent, setZoomMode, setManualZoomPercent } = useTimelineZoom();
   const displayedTimelineZoomPercent = getTimelineZoomPercent(zoomMode, manualZoomPercent);
-  const { state: keyframeState, onToggle: onToggleKeyframe } = useKeyframeToggle(domEditSession);
+  const {
+    state: keyframeState,
+    willExtend: keyframeWillExtend,
+    onToggle: onToggleKeyframe,
+  } = useKeyframeToggle(domEditSession);
 
   return (
     <div className="border-b border-neutral-800/40 bg-neutral-950/96">
@@ -124,7 +135,9 @@ export function TimelineToolbar({
                   keyframeState === "active"
                     ? "Remove keyframe at playhead"
                     : keyframeState === "inactive"
-                      ? "Add keyframe at playhead"
+                      ? keyframeWillExtend
+                        ? "Add keyframe at playhead (extends animation)"
+                        : "Add keyframe at playhead"
                       : "Enable keyframes"
                 }
               >

package/src/components/editor/DomEditOverlay.test.ts

@@ -282,7 +282,6 @@ describe("DomEditOverlay", () => {
     };
 
     let currentSelection: DomEditSelection | null = selection;
-    const onToggleRecording = vi.fn();
     const iframeRef = { current: document.createElement("iframe") as HTMLIFrameElement | null };
     const originalPointerCapture = HTMLDivElement.prototype.setPointerCapture;
     HTMLDivElement.prototype.setPointerCapture = () => {};
@@ -298,8 +297,6 @@ describe("DomEditOverlay", () => {
           hoverSelection: null,
           onSelectionChange: (next: DomEditSelection) => setSelected(next),
         }),
-        recordingState: "idle",
-        onToggleRecording,
       });
     }
 
@@ -340,16 +337,6 @@ describe("DomEditOverlay", () => {
       "drag",
       expect.objectContaining({ button: 0 }),
     );
-    const recordButton = host.querySelector(
-      '[aria-label="Record gesture (R)"]',
-    ) as HTMLButtonElement;
-    expect(recordButton).toBeTruthy();
-
-    act(() => {
-      recordButton.click();
-    });
-
-    expect(onToggleRecording).toHaveBeenCalledTimes(1);
 
     act(() => {
       root.unmount();

package/src/components/editor/DomEditOverlay.tsx

@@ -14,7 +14,7 @@ import { useDomEditOverlayRects } from "./useDomEditOverlayRects";
 import { createDomEditOverlayGestureHandlers } from "./useDomEditOverlayGestures";
 import { SnapGuideOverlay, type SnapGuidesState } from "./SnapGuideOverlay";
 import { GridOverlay } from "./GridOverlay";
-import { GestureRecordBadge, type GestureRecordingState } from "./GestureRecordControl";
+import type { GestureRecordingState } from "./GestureRecordControl";
 
 // Re-exports for external consumers — preserving existing import paths.
 export {
@@ -55,6 +55,7 @@ interface DomEditOverlayProps {
   onPathOffsetCommit: (
     selection: DomEditSelection,
     next: { x: number; y: number },
+    modifiers?: { altKey?: boolean },
   ) => Promise<void> | void;
   onGroupPathOffsetCommit: (updates: DomEditGroupPathOffsetCommit[]) => Promise<void> | void;
   onBoxSizeCommit: (
@@ -87,8 +88,6 @@ export const DomEditOverlay = memo(function DomEditOverlay({
   onGroupPathOffsetCommit,
   onBoxSizeCommit,
   onRotationCommit,
-  recordingState,
-  onToggleRecording,
 }: DomEditOverlayProps) {
   const overlayRef = useRef<HTMLDivElement | null>(null);
   const boxRef = useRef<HTMLDivElement | null>(null);
@@ -243,6 +242,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
     if (!selection) return "none";
     return `${selection.sourceFile}:${selection.id ?? selection.selector ?? selection.label}:${selection.selectorIndex ?? 0}`;
   }, [selection]);
+
   const groupBounds = useMemo(
     () => resolveDomEditGroupOverlayRect(groupOverlayItems.map((item) => item.rect)),
     [groupOverlayItems],
@@ -433,13 +433,6 @@ export const DomEditOverlay = memo(function DomEditOverlay({
               />
             </div>
           )}
-          {onToggleRecording && (
-            <GestureRecordBadge
-              rect={overlayRect}
-              recordingState={recordingState}
-              onToggleRecording={onToggleRecording}
-            />
-          )}
           <div
             key={selectionKey}
             ref={boxRef}

package/src/components/editor/KeyframeNavigation.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { clipToTweenPercentage } from "./KeyframeNavigation";
+
+/**
+ * Regression: keyframe add/remove are keyed by TWEEN-relative percentage (what the
+ * GSAP writer + runtime use), NOT the clip-relative playhead used for display/seek.
+ * The Layout-panel diamond used to emit clip-relative %, so the mutation missed
+ * every keyframe (off by the tween's offset/scale) → a silent no-op on disk that
+ * the optimistic cache hid, so the motion path never refreshed.
+ */
+
+// A tween that starts partway through the element's lifetime and is shorter than
+// it: the clip→tween map is linear with tween% = (clip% - 20) * 2.5 over [20, 60].
+const KEYFRAMES = [
+  { percentage: 20, tweenPercentage: 0, properties: { x: 0 } },
+  { percentage: 30, tweenPercentage: 25, properties: { x: -180 } },
+  { percentage: 50, tweenPercentage: 75, properties: { x: -320 } },
+  { percentage: 60, tweenPercentage: 100, properties: { x: -460 } },
+];
+
+describe("clipToTweenPercentage", () => {
+  it("maps anchor keyframes to their tween-relative percentages", () => {
+    expect(clipToTweenPercentage(KEYFRAMES, 20)).toBeCloseTo(0, 5);
+    expect(clipToTweenPercentage(KEYFRAMES, 60)).toBeCloseTo(100, 5);
+  });
+
+  it("linearly interpolates a clip-relative playhead into tween space", () => {
+    // clip 40% is the midpoint of the tween's clip span [20, 60] → tween 50%.
+    expect(clipToTweenPercentage(KEYFRAMES, 40)).toBeCloseTo(50, 5);
+  });
+
+  it("falls back to the input when there's no usable mapping", () => {
+    expect(clipToTweenPercentage([], 40)).toBe(40);
+    expect(clipToTweenPercentage([{ percentage: 10 }], 40)).toBe(40);
+  });
+});

package/src/components/editor/KeyframeNavigation.tsx

@@ -3,9 +3,12 @@ import { KeyframeDiamond, type DiamondState } from "./KeyframeDiamond";
 
 interface KeyframeNavigationProps {
   property: string;
-  /** All keyframes for this element's tween, or null if no keyframes exist */
+  /** All keyframes for this element's tween, or null if no keyframes exist.
+   *  `percentage` is clip-relative (element lifetime) for display/seek;
+   *  `tweenPercentage` is the tween-relative value the writer/runtime key on. */
   keyframes: Array<{
     percentage: number;
+    tweenPercentage?: number;
     properties: Record<string, number | string>;
     ease?: string;
   }> | null;
@@ -19,6 +22,26 @@ interface KeyframeNavigationProps {
 
 const TOLERANCE = 0.5;
 
+/**
+ * Convert a clip-relative percentage (element lifetime, used for display/seek) to
+ * the TWEEN-relative percentage the GSAP writer/runtime key on. The clip→tween
+ * map is linear, recovered from the keyframes' own (percentage, tweenPercentage)
+ * pairs. Falls back to the input when there's no usable mapping (e.g. parser
+ * keyframes that are already tween-relative, or fewer than two anchors).
+ */
+export function clipToTweenPercentage(
+  keyframes: ReadonlyArray<{ percentage: number; tweenPercentage?: number }>,
+  clipPct: number,
+): number {
+  const mapped = keyframes.filter((kf) => typeof kf.tweenPercentage === "number");
+  if (mapped.length < 2) return clipPct;
+  const a = mapped[0]!;
+  const b = mapped[mapped.length - 1]!;
+  if (b.percentage === a.percentage) return a.tweenPercentage!;
+  const slope = (b.tweenPercentage! - a.tweenPercentage!) / (b.percentage - a.percentage);
+  return a.tweenPercentage! + (clipPct - a.percentage) * slope;
+}
+
 function ArrowLeft({ disabled }: { disabled: boolean }) {
   return (
     <svg
@@ -94,13 +117,20 @@ export const KeyframeNavigation = memo(function KeyframeNavigation({
     diamondState = "ghost";
   }
 
+  // Keyframe add/remove are keyed by TWEEN-relative percentage (what the GSAP
+  // writer + runtime use), not the clip-relative `currentPercentage` used for
+  // display/seek. Removing on an existing keyframe uses its own tweenPercentage;
+  // adding converts the clip-relative playhead through the keyframes' own
+  // clip→tween linear mapping. Passing clip-relative % made the mutation miss
+  // every keyframe (off by the tween's offset/scale) → a silent no-op on disk
+  // while the optimistic cache hid it, so the motion path never refreshed.
   const handleDiamondClick = () => {
     if (diamondState === "ghost") {
       onConvertToKeyframes();
-    } else if (diamondState === "active") {
-      onRemoveKeyframe(currentPercentage);
+    } else if (diamondState === "active" && atCurrent) {
+      onRemoveKeyframe(atCurrent.tweenPercentage ?? atCurrent.percentage);
     } else {
-      onAddKeyframe(currentPercentage);
+      onAddKeyframe(clipToTweenPercentage(propertyKeyframes, currentPercentage));
     }
   };
 

package/src/components/editor/MotionPathNode.tsx

@@ -0,0 +1,98 @@
+import type React from "react";
+
+// Editor primary color (themeable via --hf-accent). Applied through inline
+// style because CSS var() isn't valid in SVG presentation attributes.
+export const ACCENT = "var(--hf-accent, #3CE6AC)";
+
+/** One path node: a diamond (matching the timeline keyframe), a wider transparent
+ *  grab target (when editable), and a hover-revealed × delete badge (when removable). */
+export function MotionPathNode(props: {
+  cx: number;
+  cy: number;
+  r: number;
+  interactive: boolean;
+  removable: boolean;
+  grabbing: boolean;
+  selected: boolean;
+  onEnter: () => void;
+  onLeave: () => void;
+  onPointerDown: (e: React.PointerEvent) => void;
+  onPointerMove: (e: React.PointerEvent) => void;
+  onPointerUp: (e: React.PointerEvent) => void;
+  onRemove: (e: React.PointerEvent) => void;
+  onContextMenu?: (e: React.MouseEvent) => void;
+}) {
+  const { cx, cy, r, interactive, removable, grabbing, selected } = props;
+  const bx = cx + r * 1.8;
+  const by = cy - r * 1.8;
+  const k = r * 0.55;
+  // Diamond matching the timeline keyframe (a 45°-rotated rounded square).
+  // `side` is chosen so the diamond's points reach ~`r` from center, matching the
+  // old dot's footprint; selection is shown by enlarging it (no extra shape).
+  const side = (selected ? r * 1.5 : r) * 1.414;
+  return (
+    <g onPointerEnter={props.onEnter} onPointerLeave={props.onLeave}>
+      <rect
+        x={cx - side / 2}
+        y={cy - side / 2}
+        width={side}
+        height={side}
+        rx={side * 0.17}
+        transform={`rotate(45 ${cx} ${cy})`}
+        stroke="#0b0f1a"
+        strokeWidth={1.5}
+        vectorEffect="non-scaling-stroke"
+        style={{ fill: ACCENT }}
+      />
+      {interactive && (
+        <circle
+          cx={cx}
+          cy={cy}
+          r={r * 2.4}
+          fill="transparent"
+          className="pointer-events-auto"
+          style={{ cursor: grabbing ? "grabbing" : "grab" }}
+          onPointerDown={props.onPointerDown}
+          onPointerMove={props.onPointerMove}
+          onPointerUp={props.onPointerUp}
+          onContextMenu={props.onContextMenu}
+        />
+      )}
+      {removable && (
+        <g
+          className="pointer-events-auto"
+          style={{ cursor: "pointer" }}
+          onPointerDown={props.onRemove}
+        >
+          <circle
+            cx={bx}
+            cy={by}
+            r={r * 1.3}
+            stroke="#0b0f1a"
+            strokeWidth={1}
+            vectorEffect="non-scaling-stroke"
+            style={{ fill: ACCENT }}
+          />
+          <line
+            x1={bx - k}
+            y1={by - k}
+            x2={bx + k}
+            y2={by + k}
+            stroke="#0b0f1a"
+            strokeWidth={1.5}
+            vectorEffect="non-scaling-stroke"
+          />
+          <line
+            x1={bx + k}
+            y1={by - k}
+            x2={bx - k}
+            y2={by + k}
+            stroke="#0b0f1a"
+            strokeWidth={1.5}
+            vectorEffect="non-scaling-stroke"
+          />
+        </g>
+      )}
+    </g>
+  );
+}