@hyperframes/studio 0.8.87 → 0.8.89

package/src/hooks/useDomGeometryCommit.ts

@@ -0,0 +1,147 @@
+import { useCallback, useMemo, useRef } from "react";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { DomEditSelection } from "../components/editor/domEditing";
+import type { DomEditGroupPathOffsetCommit } from "../components/editor/DomEditOverlay";
+import { isPreviewBooted } from "../player/store/playerStore";
+import type { DomEditCommitOutcome } from "./domEditCommitRunner";
+import type { UseDomStyleCommitOptions } from "./useDomStyleCommit";
+import { useGsapAnimationFetchFallback } from "./useGsapAnimationFetchFallback";
+import { useGsapAwareEditing } from "./useGsapAwareEditing";
+import { useGsapInteractionFailureTelemetry } from "./useGsapInteractionFailureTelemetry";
+import { useGsapScriptCommits } from "./useGsapScriptCommits";
+import { useGsapCacheVersion } from "./useGsapTweenCache";
+
+/**
+ * Studio's `Player` must show the project, with `beginTimelineSession(projectId)` run before it
+ * mounts; drain `waitForPendingSaves` before switching projects.
+ */
+export interface UseDomGeometryCommitOptions extends UseDomStyleCommitOptions {
+  /** Called when a save cannot patch the preview in place; defaults to reloading the iframe. */
+  reloadPreview?: () => void;
+}
+
+export interface DomGeometryCommits {
+  commitPathOffset: (
+    selection: DomEditSelection,
+    next: { x: number; y: number },
+    modifiers?: { altKey?: boolean },
+  ) => Promise<DomEditCommitOutcome>;
+  commitGroupPathOffset: (updates: DomEditGroupPathOffsetCommit[]) => Promise<DomEditCommitOutcome>;
+  commitBoxSize: (
+    selection: DomEditSelection,
+    next: { width: number; height: number },
+    offset?: { x: number; y: number },
+    restore?: () => void,
+  ) => Promise<DomEditCommitOutcome>;
+  commitRotation: (
+    selection: DomEditSelection,
+    next: { angle: number },
+  ) => Promise<DomEditCommitOutcome>;
+  waitForPendingSaves: () => Promise<void>;
+}
+
+const noop = () => {};
+const NO_SELECTED_ANIMATIONS: GsapAnimation[] = [];
+// ponytail: unreachable, the GSAP writer always exists so a resize never takes the DOM route.
+const noDomBoxSizeRoute = () => Promise.reject(new Error("Resize has no DOM route here"));
+
+/**
+ * Saves canvas moves, resizes and rotations through Studio's own GSAP-aware commits, for a host
+ * without the editor. A failed save rejects, so DomEditOverlay undoes the live gesture.
+ */
+export function useDomGeometryCommit({
+  projectId,
+  iframeRef,
+  writeProjectFile,
+  recordEdit,
+  activeCompPath = null,
+  showToast = noop,
+  reloadPreview,
+}: UseDomGeometryCommitOptions): DomGeometryCommits {
+  const projectIdRef = useRef(projectId);
+  projectIdRef.current = projectId;
+  const pending = useRef(new Set<Promise<void>>()).current;
+  const editHistory = useMemo(() => ({ recordEdit }), [recordEdit]);
+  const reload = useCallback(
+    () => (reloadPreview ? reloadPreview() : iframeRef.current?.contentWindow?.location.reload()),
+    [reloadPreview, iframeRef],
+  );
+  const { bump: bumpGsapCache } = useGsapCacheVersion();
+  const gsap = useGsapScriptCommits({
+    projectIdRef,
+    activeCompPath,
+    previewIframeRef: iframeRef,
+    editHistory,
+    reloadPreview: reload,
+    onCacheInvalidate: bumpGsapCache,
+    showToast,
+    writeProjectFile,
+  });
+  const makeFetchFallback = useGsapAnimationFetchFallback(projectId);
+  const trackGsapInteractionFailure = useGsapInteractionFailureTelemetry(activeCompPath, showToast);
+  const {
+    handleGsapAwarePathOffsetCommit,
+    handleGsapAwareGroupPathOffsetCommit,
+    handleGsapAwareBoxSizeCommit,
+    handleGsapAwareRotationCommit,
+  } = useGsapAwareEditing({
+    // The host owns selection, so every gesture reads its element's animations from the server.
+    domEditSelection: null,
+    selectedGsapAnimations: NO_SELECTED_ANIMATIONS,
+    gsapCommitMutation: gsap.commitMutation,
+    previewIframeRef: iframeRef,
+    showToast,
+    bumpGsapCache,
+    makeFetchFallback,
+    trackGsapInteractionFailure,
+    handleDomBoxSizeCommit: noDomBoxSizeRoute,
+    addGsapAnimation: gsap.addGsapAnimation,
+    convertToKeyframes: gsap.convertToKeyframes,
+    setArcPath: gsap.setArcPath,
+    updateArcSegment: gsap.updateArcSegment,
+  });
+  const saved = useCallback(
+    async (commit: () => Promise<void>, restore = noop): Promise<DomEditCommitOutcome> => {
+      const refusal = !projectIdRef.current
+        ? "No project is open"
+        : !isPreviewBooted(projectIdRef.current)
+          ? "The preview for this project has not loaded yet"
+          : null;
+      if (refusal) {
+        restore();
+        showToast(refusal, "error");
+        throw new Error(refusal);
+      }
+      const run = commit();
+      pending.add(run);
+      try {
+        await run;
+      } finally {
+        pending.delete(run);
+      }
+      return { ok: true };
+    },
+    [pending, showToast],
+  );
+  return useMemo(
+    () => ({
+      commitPathOffset: (selection, next, modifiers) =>
+        saved(() => handleGsapAwarePathOffsetCommit(selection, next, modifiers)),
+      commitGroupPathOffset: (updates) =>
+        saved(() => handleGsapAwareGroupPathOffsetCommit(updates)),
+      commitBoxSize: (selection, next, offset, restore) =>
+        saved(() => handleGsapAwareBoxSizeCommit(selection, next, offset, restore), restore),
+      commitRotation: (selection, next) =>
+        saved(() => handleGsapAwareRotationCommit(selection, next)),
+      waitForPendingSaves: () => Promise.allSettled([...pending]).then(noop),
+    }),
+    [
+      saved,
+      pending,
+      handleGsapAwarePathOffsetCommit,
+      handleGsapAwareGroupPathOffsetCommit,
+      handleGsapAwareBoxSizeCommit,
+      handleGsapAwareRotationCommit,
+    ],
+  );
+}

package/src/hooks/useGsapAwareEditing.ts

@@ -298,10 +298,15 @@ export function useGsapAwareEditing({
       offset?: { x: number; y: number },
       restore: () => void = () => undefined,
     ) => {
-      const ownedAnimations = getGsapAnimationsForSelection(selection);
-      const targetAnimations = Array.isArray(ownedAnimations)
-        ? ownedAnimations
-        : await ownedAnimations;
+      let targetAnimations: GsapAnimation[];
+      try {
+        const ownedAnimations = getGsapAnimationsForSelection(selection);
+        targetAnimations = Array.isArray(ownedAnimations) ? ownedAnimations : await ownedAnimations;
+      } catch (error) {
+        restore();
+        trackGsapInteractionFailure(error, selection, "resize", "Resize animated layer");
+        throw error;
+      }
       const scaleRoute = targetAnimations.some((anim) => anim.propertyGroup === "scale");
       const selector = selectorFromSelection(selection);
       const hasLivePositionTween = selector

package/src/index.ts

@@ -167,7 +167,7 @@ export type { AudioMeterStripProps } from "./components/nle/AudioMeterStrip";
 export { useClipboard } from "./hooks/useClipboard";
 export type { UseClipboardOptions } from "./hooks/useClipboard";
 
-// DOM editing for a host outside EditorShell; useDomStyleCommit saves styles without the session.
+// DOM editing for a host outside EditorShell; the Commit hooks save without useDomEditSession.
 export { useDomEditSession } from "./hooks/useDomEditSession";
 export type { UseDomEditSessionParams } from "./hooks/useDomEditSession";
 export { usePreviewPersistence } from "./hooks/usePreviewPersistence";
@@ -181,6 +181,8 @@ export { useDomStyleCommit } from "./hooks/useDomStyleCommit";
 export type { UseDomStyleCommitOptions } from "./hooks/useDomStyleCommit";
 export type { DomEditCommitDeclineReason, DomEditCommitOutcome } from "./hooks/domEditCommitRunner";
 export { resolveDomEditSelection } from "./components/editor/domEditingLayers";
+export { useDomGeometryCommit } from "./hooks/useDomGeometryCommit";
+export type { DomGeometryCommits, UseDomGeometryCommitOptions } from "./hooks/useDomGeometryCommit";
 export { DomEditOverlay } from "./components/editor/DomEditOverlay";
 export type {
   DomEditGroupPathOffsetCommit,

package/src/player/components/Timeline.showKeyframes.test.tsx

@@ -0,0 +1,91 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it } from "vitest";
+import { Timeline } from "./Timeline";
+import { installTimelineMountEnv } from "./timelineMountTestEnv";
+import { usePlayerStore } from "../store/playerStore";
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+installTimelineMountEnv();
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+async function mountKeyframed(showKeyframes?: boolean, withLanes = true) {
+  usePlayerStore.setState({
+    duration: 10,
+    currentTime: 0,
+    timelineReady: true,
+    selectedElementId: "card",
+    elements: [{ id: "card", label: "Hero card", tag: "div", start: 0, duration: 4, track: 0 }],
+    gsapAnimations: withLanes
+      ? new Map([
+          [
+            "card",
+            [
+              {
+                id: "card-position",
+                targetSelector: "#card",
+                method: "to",
+                position: 0,
+                duration: 2,
+                properties: {},
+                propertyGroup: "position",
+                keyframes: {
+                  format: "percentage",
+                  keyframes: [
+                    { percentage: 0, properties: { x: 0 } },
+                    { percentage: 50, properties: { x: 100 } },
+                  ],
+                },
+              },
+            ],
+          ],
+        ])
+      : new Map(),
+    keyframeCache: new Map([
+      [
+        "card",
+        {
+          format: "percentage",
+          keyframes: [{ percentage: 50, properties: { x: 100 }, tweenPercentage: 50 }],
+        },
+      ],
+    ]),
+  });
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  await act(async () => root.render(<Timeline showKeyframes={showKeyframes} />));
+  const diamonds = host.querySelectorAll('button[title="50%"]').length;
+  const named = Array.from(host.querySelectorAll("[role=rowheader]")).some((h) =>
+    h.textContent?.includes("Hero card"),
+  );
+  const lanes = host.textContent?.includes("Position") ?? false;
+  act(() => root.unmount());
+  return { diamonds, named, lanes };
+}
+
+describe("Timeline showKeyframes", () => {
+  it("draws a keyframed clip's diamonds by default", async () => {
+    expect((await mountKeyframed(undefined, false)).diamonds).toBeGreaterThan(0);
+  });
+
+  it("draws no keyframe diamonds when the host turns keyframes off", async () => {
+    expect((await mountKeyframed(false, false)).diamonds).toBe(0);
+  });
+
+  it("draws the keyframe lanes by default and none when keyframes are off", async () => {
+    expect((await mountKeyframed()).lanes).toBe(true);
+    expect((await mountKeyframed(false)).lanes).toBe(false);
+  });
+
+  it("keeps each track's name in the header when keyframes are off", async () => {
+    expect((await mountKeyframed()).named).toBe(true);
+    expect((await mountKeyframed(false)).named).toBe(true);
+  });
+});

package/src/player/components/TimelineTypes.ts

@@ -34,4 +34,5 @@ export interface TimelineProps
   canPasteClip?: () => boolean;
   theme?: Partial<TimelineTheme>;
   showAudioEffects?: boolean;
+  showKeyframes?: boolean;
 }

package/src/player/components/studioShortcuts.ts

@@ -52,6 +52,8 @@ export const DEFAULT_SHORTCUT_SECTIONS: readonly ShortcutSection[] = [
       { key: "⌘X", label: "Cut element" },
       { key: hintKey(STUDIO_PLAIN_KEYS.split), label: "Split clip at playhead" },
       { key: "⇧Click", label: "Razor tool: split all tracks" },
+      { key: "[", label: "Select clips starting before the playhead" },
+      { key: "]", label: "Select clips starting at or after the playhead" },
       { key: "⌘G", label: "Group elements" },
       { key: "⌘⇧G", label: "Ungroup" },
       { key: "Del", label: "Delete selected element (no keyframe selected)" },

package/src/player/components/useTimelineKeyframeData.ts

@@ -0,0 +1,14 @@
+import { usePlayerStore, type KeyframeCacheEntry } from "../store/playerStore";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+
+const HIDDEN = {
+  gsapAnimations: new Map<string, GsapAnimation[]>(),
+  keyframeCache: new Map<string, KeyframeCacheEntry>(),
+};
+
+/** The keyframe data the timeline draws, or none when the host hides keyframes. */
+export function useTimelineKeyframeData(showKeyframes: boolean) {
+  const gsapAnimations = usePlayerStore((s) => s.gsapAnimations);
+  const keyframeCache = usePlayerStore((s) => s.keyframeCache);
+  return showKeyframes ? { gsapAnimations, keyframeCache } : HIDDEN;
+}

package/src/player/components/useTimelineProviderState.tsx

@@ -21,6 +21,7 @@ import { useTimelineGeometry } from "./useTimelineGeometry";
 import { useAutoExpandKeyframedClips } from "./useAutoExpandKeyframedClips";
 import { GUTTER, LABEL_COL_W } from "./timelineLayout";
 import { useTimelineLabelColumn } from "./useTimelineLabelColumn";
+import { useTimelineKeyframeData } from "./useTimelineKeyframeData";
 import { useTimelineScrollViewport } from "./useTimelineScrollViewport";
 import { ClipContentOnceShown } from "./timelineClipChildren";
 import { useResolvedTimelineEditCallbacks } from "./useResolvedTimelineEditCallbacks";
@@ -68,6 +69,7 @@ export function useTimelineProviderState({
   canPasteClip,
   theme: themeOverrides,
   showAudioEffects = true,
+  showKeyframes = true,
   sessionEpoch = 0,
   previewIframeRef,
   onZIndexReorder,
@@ -104,8 +106,9 @@ export function useTimelineProviderState({
   const selectedElementId = usePlayerStore((s) => s.selectedElementId);
   const selectedElementIds = usePlayerStore((s) => s.selectedElementIds);
   const focusedEaseSegment = usePlayerStore((s) => s.focusedEaseSegment);
-  const gsapAnimations = usePlayerStore((s) => s.gsapAnimations);
-  const { labelMode, contentOrigin } = useTimelineLabelColumn(gsapAnimations, timelineElements);
+  const { gsapAnimations, keyframeCache } = useTimelineKeyframeData(showKeyframes);
+  const namedAnimations = usePlayerStore((s) => s.gsapAnimations);
+  const { labelMode, contentOrigin } = useTimelineLabelColumn(namedAnimations, timelineElements);
   const setSelectedElementId = usePlayerStore((s) => s.setSelectedElementId);
   const currentTime = usePlayerStore((s) => s.currentTime);
   const beatDragging = usePlayerStore((s) => s.beatDragging);
@@ -130,7 +133,6 @@ export function useTimelineProviderState({
     () => getEffectiveTimelineDuration(duration, timelineElements),
     [duration, timelineElements],
   );
-  const keyframeCache = usePlayerStore((s) => s.keyframeCache);
   useAutoExpandKeyframedClips(gsapAnimations);
   const {
     tracks,

package/src/player/store/playerStore.ts

@@ -23,6 +23,7 @@ import { createRangeSelectionSlice, type RangeSelectionSlice } from "./rangeSele
 import { createTimelineResetState } from "./timelineResetState";
 export type { KeyframeCacheEntry } from "./keyframeSlice";
 export { liveTime } from "./liveTime";
+import { liveTime } from "./liveTime";
 export { createTimelineResetState };
 
 import type {
@@ -96,6 +97,8 @@ interface PlayerState extends PlayerStoreSlices {
 
   activeTool: TimelineTool;
   setActiveTool: (tool: TimelineTool) => void;
+  selectLeftward: () => void;
+  selectRightward: () => void;
 
   /** Tween-relative percentage of the last-clicked keyframe diamond. Operations
    *  (drag, resize, rotate) target this instead of recomputing from playhead. */
@@ -250,6 +253,17 @@ interface BeatHistoryEntry {
   label: string;
 }
 
+/** Selects like the marquee: the primary first, so its resets run, then the whole set. */
+function selectAroundPlayhead(
+  state: PlayerState,
+  keep: (start: number, playhead: number) => boolean,
+): void {
+  const playhead = state.isPlaying ? liveTime.latest() : state.currentTime;
+  const ids = state.elements.filter((el) => keep(el.start, playhead)).map((el) => el.key ?? el.id);
+  state.setSelectedElementId(ids[0] ?? null);
+  state.setSelectedElementIds(new Set(ids));
+}
+
 export const usePlayerStore = create<PlayerState>((set, get) => ({
   isPlaying: false,
   currentTime: 0,
@@ -273,6 +287,8 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
 
   activeTool: "select",
   setActiveTool: (tool) => set({ activeTool: tool }),
+  selectLeftward: () => selectAroundPlayhead(get(), (start, playhead) => start < playhead),
+  selectRightward: () => selectAroundPlayhead(get(), (start, playhead) => start >= playhead),
 
   ...createKeyframeSlice(set, () => ({
     timelineProjectId: get().timelineProjectId,