@hyperframes/studio 0.6.122-alpha.0 → 0.7.1

package/src/hooks/useSafeGsapCommitMutation.test.tsx

@@ -0,0 +1,86 @@
+// @vitest-environment happy-dom
+import { describe, it, expect, vi } from "vitest";
+import { act, createElement } from "react";
+import { createRoot } from "react-dom/client";
+
+// React's act() emits a warning unless the runtime is flagged as a test env.
+(globalThis as Record<string, unknown>).IS_REACT_ACT_ENVIRONMENT = true;
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import type { CommitMutation } from "./gsapScriptCommitTypes";
+import { useSafeGsapCommitMutation } from "./useSafeGsapCommitMutation";
+
+/**
+ * Regression: the safe wrapper used to `void` the commit and return undefined, so
+ * the facade resolved IMMEDIATELY — consumers that `await session.commitMutation`
+ * (gesture recording, enable-keyframes) fired their post-actions (toast, reseek,
+ * "idle") BEFORE the server save landed. The wrapper must now RETURN the chain so
+ * awaiters resolve only after the save (and its error handling) settles.
+ */
+
+const selection = { id: "box", selector: "#box" } as unknown as DomEditSelection;
+
+// Mount a hook and capture its return value via a ref.
+function renderSafeCommit(
+  commitMutation: CommitMutation,
+  showToast?: (message: string, tone?: "error" | "info") => void,
+) {
+  const captured: { fn: ReturnType<typeof useSafeGsapCommitMutation> | null } = { fn: null };
+  function Probe() {
+    captured.fn = useSafeGsapCommitMutation(commitMutation, vi.fn(), showToast);
+    return null;
+  }
+  const container = document.createElement("div");
+  const root = createRoot(container);
+  act(() => {
+    root.render(createElement(Probe));
+  });
+  return captured.fn!;
+}
+
+describe("useSafeGsapCommitMutation — returned promise settles after the commit", () => {
+  it("resolves only after the underlying commit resolves", async () => {
+    let resolveCommit!: () => void;
+    const order: string[] = [];
+    const commitMutation: CommitMutation = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          resolveCommit = () => {
+            order.push("commit-settled");
+            resolve();
+          };
+        }),
+    );
+
+    const safe = renderSafeCommit(commitMutation);
+    const awaited = safe(selection, { type: "noop" }, { label: "test" }).then(() => {
+      order.push("awaiter-resumed");
+    });
+
+    // Give the microtask queue a chance — the awaiter must NOT have resumed yet
+    // because the commit is still pending.
+    await Promise.resolve();
+    expect(order).toEqual([]);
+
+    resolveCommit();
+    await awaited;
+    expect(order).toEqual(["commit-settled", "awaiter-resumed"]);
+  });
+
+  it("resolves (success-after-handled) after a failed commit, surfacing a toast", async () => {
+    const showToast = vi.fn();
+    const order: string[] = [];
+    const commitMutation: CommitMutation = vi.fn(async () => {
+      order.push("commit-rejected");
+      throw new Error("save failed");
+    });
+
+    const safe = renderSafeCommit(commitMutation, showToast);
+    await safe(selection, { type: "noop" }, { label: "test" });
+    order.push("awaiter-resumed");
+
+    // The awaiter resumes AFTER the rejection was handled, and the promise does
+    // not reject (the .catch swallows it for the toast).
+    expect(order).toEqual(["commit-rejected", "awaiter-resumed"]);
+    expect(showToast).toHaveBeenCalledWith(expect.stringContaining("Couldn't save"), "error");
+  });
+});

package/src/hooks/useSafeGsapCommitMutation.ts

@@ -42,12 +42,16 @@ export function useSafeGsapCommitMutation(
       selection: DomEditSelection,
       mutation: Record<string, unknown>,
       options: CommitMutationOptions,
-    ) => {
-      void commitMutation(selection, mutation, options).catch((error) => {
+    ): Promise<void> =>
+      // Return the chain so awaiting consumers (gesture commit, enable-keyframes)
+      // run their post-actions AFTER the server save settles, not immediately.
+      // The `.catch` handles the failure (toast + telemetry) and resolves the
+      // chain, so awaiters see a settled (success-after-handled) promise rather
+      // than an unhandled rejection.
+      commitMutation(selection, mutation, options).catch((error) => {
         trackGsapSaveFailure(error, selection, mutation, options.label);
         showToast?.(`Couldn't save animation: ${getStudioSaveErrorMessage(error)}`, "error");
-      });
-    },
+      }),
     [commitMutation, trackGsapSaveFailure, showToast],
   );
 }

package/src/hooks/useServerConnection.ts

@@ -26,7 +26,10 @@ export function useServerConnection(): ServerConnectionState {
   useMountEffect(() => {
     const hashProjectId = parseProjectIdFromHash(window.location.hash);
     let cancelled = false;
-    let retryTimer: ReturnType<typeof window.setTimeout> | null = null;
+    // Explicitly `number` (the DOM return of window.setTimeout) rather than
+    // ReturnType<typeof window.setTimeout> — with @types/node present, that infers
+    // NodeJS.Timeout and clashes with the DOM number the call actually returns.
+    let retryTimer: number | null = null;
 
     function scheduleRetry() {
       setWaitingForServer(true);

package/src/hooks/useStudioContextValue.ts

@@ -90,8 +90,9 @@ export function useInspectorState(
       inspectorPanelActive,
       inspectorButtonActive:
         STUDIO_INSPECTOR_PANELS_ENABLED && !rightCollapsed && inspectorPanelActive,
-      shouldShowSelectedDomBounds:
-        inspectorPanelActive && !rightCollapsed && !isPlaying && !isGestureRecording,
+      // Keep the selection box + motion path drawn even when the Inspector is
+      // collapsed — closing the panel shouldn't visually deselect the element.
+      shouldShowSelectedDomBounds: inspectorPanelActive && !isPlaying && !isGestureRecording,
     };
   }, [rightPanelTab, rightInspectorPanes, rightCollapsed, isPlaying, isGestureRecording]);
 }

package/src/hooks/useStudioUrlState.ts

@@ -1,9 +1,11 @@
-import { useCallback, useEffect, useRef } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { usePlayerStore } from "../player";
 import { findElementForSelection, type DomEditSelection } from "../components/editor/domEditing";
 import { clampNumber, type RightPanelTab } from "../utils/studioHelpers";
+import { parseProjectIdFromHash } from "../utils/projectRouting";
 import {
   buildStudioHash,
+  parseStudioUrlStateFromHash,
   type StudioUrlSelectionState,
   type StudioUrlState,
 } from "../utils/studioUrlState";
@@ -33,6 +35,7 @@ interface UseStudioUrlStateParams {
       preserveGroup?: boolean;
     },
   ) => void;
+  setRightPanelTab: (tab: RightPanelTab) => void;
   initialState: StudioUrlState;
 }
 
@@ -68,12 +71,17 @@ export function useStudioUrlState({
   domEditSelection,
   buildDomSelectionFromTarget,
   applyDomSelection,
+  setRightPanelTab,
   initialState,
 }: UseStudioUrlStateParams) {
   const currentTime = usePlayerStore((s) => s.currentTime);
   const hydratedSeekRef = useRef(initialState.currentTime == null);
   const hydratedInitialTimeRef = useRef(initialState.currentTime == null);
   const hydratedSelectionRef = useRef(initialState.selection == null);
+  // Mirrors hydratedSelectionRef as state so the selection-hydration effect can
+  // drop its currentTime subscription once hydration completes — otherwise it
+  // re-runs on every playhead tick for the lifetime of the session.
+  const [selectionHydrated, setSelectionHydrated] = useState(initialState.selection == null);
   const pendingSelectionRef = useRef(initialState.selection);
   const stableTimeRef = useRef<number | null>(initialState.currentTime);
 
@@ -91,67 +99,91 @@ export function useStudioUrlState({
     [activeCompPath, domEditSelection, rightCollapsed, rightPanelTab, timelineVisible],
   );
 
+  // Resolve a URL selection to a live element and apply it. Shared by the initial
+  // hydration effect and the external-navigation (hashchange) handler. Returns
+  // false ONLY when the iframe document isn't ready yet (caller should retry);
+  // a missing element or null selection clears the selection and returns true.
+  const applyUrlSelection = useCallback(
+    (selection: StudioUrlSelectionState | null): boolean => {
+      if (!selection) {
+        applyDomSelection(null, { revealPanel: false });
+        return true;
+      }
+      let doc: Document | null = null;
+      try {
+        doc = previewIframeRef.current?.contentDocument ?? null;
+      } catch {
+        return false;
+      }
+      if (!doc) return false;
+      const element = findElementForSelection(
+        doc,
+        {
+          sourceFile: selection.sourceFile ?? "",
+          id: selection.id,
+          selector: selection.selector,
+          selectorIndex: selection.selectorIndex,
+        },
+        activeCompPath,
+      );
+      if (!element) {
+        applyDomSelection(null, { revealPanel: false });
+        return true;
+      }
+      void buildDomSelectionFromTarget(element, { preferClipAncestor: false }).then((resolved) => {
+        applyDomSelection(resolved, { revealPanel: false });
+      });
+      return true;
+    },
+    [activeCompPath, applyDomSelection, buildDomSelectionFromTarget, previewIframeRef],
+  );
+
   useEffect(() => {
     if (!projectId || hydratedSeekRef.current || compositionLoading) return;
     const nextTime =
       duration > 0
         ? clampNumber(initialState.currentTime ?? 0, 0, duration)
         : Math.max(0, initialState.currentTime ?? 0);
+    // The request is honored even if it fires before the player runtime mounts:
+    // initializeAdapter reconciles the store's requestedSeekTime when the adapter
+    // becomes ready. currentTime then settles to nextTime, releasing the selection
+    // hydration below.
     usePlayerStore.getState().requestSeek(nextTime);
     stableTimeRef.current = nextTime;
     hydratedSeekRef.current = true;
   }, [projectId, compositionLoading, duration, initialState.currentTime]);
 
+  // Once hydration completes the selection effect no longer needs the playhead,
+  // so freeze its time dependency. This stops the effect re-running on every tick
+  // for the rest of the session (cosmetic perf) while still retrying as the seek
+  // settles before hydration.
+  const selectionHydrationTime = selectionHydrated ? 0 : currentTime;
   useEffect(() => {
     if (!projectId || hydratedSelectionRef.current || compositionLoading) return;
     if (!hydratedSeekRef.current) return;
     const targetTime = initialState.currentTime;
-    if (targetTime != null && Math.abs(currentTime - stableTimeRef.current!) > 0.05) return;
-
-    const pendingSelection = pendingSelectionRef.current;
-    if (!pendingSelection) {
-      hydratedSelectionRef.current = true;
+    if (targetTime != null && Math.abs(selectionHydrationTime - stableTimeRef.current!) > 0.05) {
       return;
     }
 
-    let doc: Document | null = null;
-    try {
-      doc = previewIframeRef.current?.contentDocument ?? null;
-    } catch {
-      return;
-    }
-    if (!doc) return;
-
-    const element = findElementForSelection(
-      doc,
-      {
-        sourceFile: pendingSelection.sourceFile ?? "",
-        id: pendingSelection.id,
-        selector: pendingSelection.selector,
-        selectorIndex: pendingSelection.selectorIndex,
-      },
-      activeCompPath,
-    );
-    if (!element) {
-      applyDomSelection(null, { revealPanel: false });
+    const markHydrated = () => {
       hydratedSelectionRef.current = true;
-      pendingSelectionRef.current = null;
+      setSelectionHydrated(true);
+    };
+    const pendingSelection = pendingSelectionRef.current;
+    if (!pendingSelection) {
+      markHydrated();
       return;
     }
-
-    hydratedSelectionRef.current = true;
+    // Doc not ready yet → leave hydration pending so a later tick retries.
+    if (!applyUrlSelection(pendingSelection)) return;
+    markHydrated();
     pendingSelectionRef.current = null;
-    void buildDomSelectionFromTarget(element, { preferClipAncestor: false }).then((selection) => {
-      applyDomSelection(selection, { revealPanel: false });
-    });
   }, [
-    activeCompPath,
-    applyDomSelection,
-    buildDomSelectionFromTarget,
+    applyUrlSelection,
     compositionLoading,
-    currentTime,
+    selectionHydrationTime,
     initialState.currentTime,
-    previewIframeRef,
     projectId,
     refreshKey,
   ]);
@@ -185,4 +217,32 @@ export function useStudioUrlState({
     if (!projectId) return;
     replaceHash(buildStudioHash(projectId, buildUrlState()));
   }, [activeCompPathHydrated, buildUrlState, projectId]);
+
+  // Re-apply URL state when the hash changes externally (pasting a new link,
+  // back/forward) AFTER initial load. The app only reads the URL once on mount
+  // and otherwise WRITES the hash via replaceState (which never fires
+  // `hashchange`), so this listener sees only genuine external navigations —
+  // without it, opening a same-project deep link (different `t`, element, or
+  // tab) is silently ignored and then overwritten by the next hash-sync.
+  useEffect(() => {
+    if (!projectId) return;
+    const onHashChange = () => {
+      if (parseProjectIdFromHash(window.location.hash) !== projectId) return; // different project → remount handles it
+      const parsed = parseStudioUrlStateFromHash(window.location.hash);
+      if (parsed.currentTime != null) {
+        const clamped =
+          duration > 0
+            ? clampNumber(parsed.currentTime, 0, duration)
+            : Math.max(0, parsed.currentTime);
+        if (Math.abs(usePlayerStore.getState().currentTime - clamped) > 0.05) {
+          usePlayerStore.getState().requestSeek(clamped);
+          stableTimeRef.current = clamped;
+        }
+      }
+      applyUrlSelection(parsed.selection);
+      if (parsed.rightPanelTab) setRightPanelTab(parsed.rightPanelTab);
+    };
+    window.addEventListener("hashchange", onHashChange);
+    return () => window.removeEventListener("hashchange", onHashChange);
+  }, [projectId, duration, applyUrlSelection, setRightPanelTab]);
 }

package/src/player/components/ShortcutsPanel.tsx

@@ -50,6 +50,14 @@ const SHORTCUT_SECTIONS = [
       { key: "⌘ Scroll", label: "Record scale" },
     ],
   },
+  {
+    title: "Canvas",
+    hints: [
+      { key: "Drag", label: "Move element / add keyframe" },
+      { key: "⌥ Drag", label: "Move entire animation path" },
+      { key: "⇧ Drag", label: "Uniform resize" },
+    ],
+  },
   {
     title: "Panels",
     hints: [

package/src/player/components/TimelineClipDiamonds.tsx

@@ -42,13 +42,10 @@ interface TimelineClipDiamondsProps {
 const DIAMOND_RATIO = 0.8;
 // Percentage tolerance for rendering keyframes near clip boundaries. Keyframes
 // slightly outside [0, 100] (from rounding or stale cache during the async
-// persist → reload cycle) are clamped to the clip edge rather than hidden.
-export const KF_MIN_PCT = -5;
-export const KF_MAX_PCT = 105;
-
-function clampDiamondLeft(rawLeft: number, diamondSize: number, clipWidth: number): number {
-  return Math.max(0, Math.min(clipWidth - diamondSize, rawLeft));
-}
+// persist → reload cycle) are still rendered (the clip is overflow-visible) at
+// their true position rather than hidden.
+const KF_MIN_PCT = -5;
+const KF_MAX_PCT = 105;
 
 export const TimelineClipDiamonds = memo(function TimelineClipDiamonds({
   keyframesData,
@@ -225,11 +222,12 @@ export const TimelineClipDiamonds = memo(function TimelineClipDiamonds({
       })}
 
       {sorted.map((kf, i) => {
-        const leftPx = clampDiamondLeft(
-          (effPct(kf.percentage) / 100) * clipWidthPx - half,
-          diamondSize,
-          clipWidthPx,
-        );
+        // Center the diamond ON its keyframe %: left = (% · width) − half so the
+        // diamond's midpoint sits exactly at the percentage. At 0% the midpoint
+        // is the clip's left edge (the diamond's left half overflows, which the
+        // overflow-visible clip shows) — NOT shifted fully inside. No clamp, or
+        // boundary keyframes (0% / 100%) would render off-center.
+        const leftPx = (effPct(kf.percentage) / 100) * clipWidthPx - half;
         const kfKey = `${elementId}:${kf.percentage}`;
         const isKfSelected = selectedKeyframes.has(kfKey);
         const atPlayhead = isSelected && Math.abs(kf.percentage - currentPercentage) < 0.5;

package/src/player/hooks/useExpandedTimelineElements.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { buildExpandedElements } from "./useExpandedTimelineElements";
+import { buildTimelineElementKey } from "../lib/timelineElementHelpers";
 import type { TimelineElement } from "../store/playerStore";
 import type { ClipManifestClip } from "../lib/playbackTypes";
 
@@ -88,4 +89,37 @@ describe("buildExpandedElements", () => {
     expect(child.expandedParentStart).toBe(13); // C's start, not B's 12 or A's 10
     expect(child.sourceFile).toBe("c.html"); // C's file, not b.html or a.html
   });
+
+  // Regression: an expanded child must share one identity (`key`) with the flat
+  // store element for the same DOM id. Before the fix the child key fell back to
+  // the colon form (`index.html:eyebrow:N`) while the store/selection used the
+  // hash form (`index.html#eyebrow`), so clicking an expanded child never
+  // highlighted it (isSelected compares the two keys).
+  it("keys expanded children in hash form, matching the flat store element", () => {
+    // Single composition (no sub-comps): scene `s1` with same-file children.
+    const elements = [el({ id: "s1", domId: "s1", start: 0, duration: 14 })];
+    const manifest = [
+      clip({ id: "s1", start: 0, duration: 14 }),
+      clip({ id: "eyebrow", start: 0, duration: 14 }),
+      clip({ id: "title", start: 0, duration: 14 }),
+    ];
+    const parentMap = new Map([
+      ["eyebrow", "s1"],
+      ["title", "s1"],
+    ]);
+
+    const out = buildExpandedElements(elements, manifest, parentMap, "s1", "s1");
+    const child = out.find((e) => e.domId === "eyebrow")!;
+
+    const expectedStoreKey = buildTimelineElementKey({
+      id: "eyebrow",
+      fallbackIndex: 0,
+      domId: "eyebrow",
+      selector: "#eyebrow",
+      sourceFile: undefined,
+    });
+    expect(expectedStoreKey).toBe("index.html#eyebrow");
+    expect(child.key).toBe("index.html#eyebrow");
+    expect(child.key).toBe(expectedStoreKey);
+  });
 });

package/src/player/hooks/useExpandedTimelineElements.ts

@@ -2,6 +2,7 @@ import { useMemo } from "react";
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import type { ClipManifestClip } from "../lib/playbackTypes";
 import { createTimelineElementFromManifestClip } from "../lib/timelineDOM";
+import { buildTimelineElementKey } from "../lib/timelineElementHelpers";
 
 function findTopLevelAncestor(id: string, parentMap: Map<string, string>): string | null {
   let current = parentMap.get(id);
@@ -78,14 +79,31 @@ function buildChildElements(
       clip: child,
       fallbackIndex: result.length,
     });
+    const domId = child.id ?? undefined;
+    const selector = child.id ? `#${child.id}` : undefined;
+    // `base.key` was built without a hostEl, so it fell back to the colon form
+    // (`index.html:<id>:<idx>`) even though we set domId below. Recompute it from
+    // the same inputs the store uses (`<sourceFile>#<domId>`) so an expanded
+    // child shares one identity with its flat store element — otherwise selecting
+    // it sets `selectedElementId` to the store's hash key while the rendered row
+    // is keyed by the colon form, and `isSelected` never matches (no highlight).
+    const key = buildTimelineElementKey({
+      id: base.id,
+      fallbackIndex: result.length,
+      domId,
+      selector,
+      selectorIndex: base.selectorIndex,
+      sourceFile: editBasis.sourceFile,
+    });
     result.push({
       ...base,
+      key,
       start: clamped.start,
       duration: clamped.duration,
       track: display.track + result.length,
       expandedParentStart: editBasis.start,
-      domId: child.id ?? undefined,
-      selector: child.id ? `#${child.id}` : undefined,
+      domId,
+      selector,
       sourceFile: editBasis.sourceFile,
       timingSource: "authored" as const,
     });

package/src/player/hooks/useTimelineSyncCallbacks.ts

@@ -174,8 +174,16 @@ export function useTimelineSyncCallbacks({
     if (!adapter || adapter.getDuration() <= 0) return false;
 
     adapter.pause();
-    const seekTo = pendingSeekRef.current;
+    // Honor a seek requested before the adapter was ready. It may sit in either
+    // place: `pendingSeekRef` if the store subscription was mounted when requestSeek
+    // fired, or only in the store's `requestedSeekTime` if it fired earlier still
+    // (deep-link hydration runs before the player subscription mounts, so the request
+    // never reaches pendingSeekRef). Reconciling with the store here is what makes a
+    // deep-linked `?t=` land instead of starting at 0.
+    const storeSeek = usePlayerStore.getState().requestedSeekTime;
+    const seekTo = pendingSeekRef.current ?? storeSeek;
     pendingSeekRef.current = null;
+    if (storeSeek != null) usePlayerStore.getState().clearSeekRequest();
     const startTime = seekTo != null ? Math.min(seekTo, adapter.getDuration()) : 0;
 
     adapter.seek(startTime);

package/src/player/lib/mediaProbe.ts

@@ -8,6 +8,9 @@ interface MediaProbeResult {
 
 const cache = new Map<string, MediaProbeResult>();
 const inflight = new Map<string, Promise<MediaProbeResult | null>>();
+// URLs whose probe failed (CORS, 404, non-media). Remembered so the rAF-driven
+// timeline re-derive doesn't re-fetch them every frame and flood the console.
+const failed = new Set<string>();
 
 let mediabunnyModule: typeof import("mediabunny") | null | false = null;
 
@@ -97,7 +100,8 @@ export async function probeMissingSourceDurations<
       el.src &&
       el.sourceDuration == null &&
       ["video", "audio"].includes(el.tag.toLowerCase()) &&
-      !getCachedProbe(el.src),
+      !getCachedProbe(el.src) &&
+      !failed.has(normalizeUrl(el.src)),
   );
   if (needs.length === 0) return;
   await Promise.allSettled(
@@ -112,6 +116,7 @@ async function probeMediaUrl(url: string): Promise<MediaProbeResult | null> {
   const key = normalizeUrl(url);
   const cached = cache.get(key);
   if (cached) return cached;
+  if (failed.has(key)) return null;
 
   let pending = inflight.get(key);
   if (pending) return pending;
@@ -119,6 +124,7 @@ async function probeMediaUrl(url: string): Promise<MediaProbeResult | null> {
   pending = probeOne(key).then((result) => {
     inflight.delete(key);
     if (result) cache.set(key, result);
+    else failed.add(key);
     return result;
   });
   inflight.set(key, pending);

package/src/player/store/playerStore.ts

@@ -96,6 +96,14 @@ interface PlayerState {
    *  (drag, resize, rotate) target this instead of recomputing from playhead. */
   activeKeyframePct: number | null;
   setActiveKeyframePct: (pct: number | null) => void;
+  /** Motion-path "set destination" mode. Armed from the preview toolbar (replaces
+   *  the old double-click-on-canvas UX); while armed, one canvas click places the
+   *  new path's destination. `available` is published by MotionPathOverlay so the
+   *  toolbar shows the button only when the selected element can take a path. */
+  motionPathArmed: boolean;
+  setMotionPathArmed: (armed: boolean) => void;
+  motionPathCreateAvailable: boolean;
+  setMotionPathCreateAvailable: (available: boolean) => void;
 
   /** Multi-select: additional selected elements beyond selectedElementId. */
   selectedElementIds: Set<string>;
@@ -209,6 +217,10 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
 
   activeKeyframePct: null,
   setActiveKeyframePct: (pct) => set({ activeKeyframePct: pct }),
+  motionPathArmed: false,
+  setMotionPathArmed: (armed) => set({ motionPathArmed: armed }),
+  motionPathCreateAvailable: false,
+  setMotionPathCreateAvailable: (available) => set({ motionPathCreateAvailable: available }),
 
   selectedElementIds: new Set<string>(),
   toggleSelectedElementId: (id: string) =>
@@ -327,7 +339,16 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
   setTimelineReady: (ready) => set({ timelineReady: ready }),
   setBeatDragging: (dragging) => set({ beatDragging: dragging }),
   setElements: (elements) => set({ elements }),
-  setSelectedElementId: (id) => set({ selectedElementId: id }),
+  setSelectedElementId: (id) =>
+    set((s) =>
+      // Selecting a different element drops any active keyframe selection — otherwise
+      // a stale activeKeyframePct from a prior diamond click would force the next drag
+      // to "modify" a keyframe on the new element. A diamond click sets the pct AFTER
+      // calling setSelectedElementId, so this never clobbers a genuine keyframe select.
+      id !== s.selectedElementId
+        ? { selectedElementId: id, activeKeyframePct: null, motionPathArmed: false }
+        : { selectedElementId: id },
+    ),
   updateElement: (elementId, updates) =>
     set((state) => ({
       elements: state.elements.map((el) =>
@@ -361,3 +382,19 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
       clipParentMap: new Map(),
     }),
 }));
+
+// Bug-bash aid: expose the store so a reproduction can dump live state from the
+// console, e.g. `__playerStore.getState().selectedElementId`. Harmless read
+// handle; no behavioural effect.
+// Only in dev. `import.meta.env` may be undefined in non-Vite bundlers (Next.js
+// Turbopack), so guard the access like the telemetry client does.
+function isDevBuild(): boolean {
+  try {
+    return import.meta.env.DEV === true;
+  } catch {
+    return false;
+  }
+}
+if (isDevBuild() && typeof window !== "undefined") {
+  (window as unknown as { __playerStore?: typeof usePlayerStore }).__playerStore = usePlayerStore;
+}

package/src/telemetry/config.ts

@@ -5,6 +5,8 @@
 //   localStorage.setItem('hyperframes-studio:telemetryDisabled','1')
 // ---------------------------------------------------------------------------
 
+import { generateId } from "../utils/generateId";
+
 const ANON_ID_KEY = "hyperframes-studio:anonymousId";
 const OPT_OUT_KEY = "hyperframes-studio:telemetryDisabled";
 const NOTICE_KEY = "hyperframes-studio:telemetryNoticeShown";
@@ -18,8 +20,7 @@ function safeLocalStorage(): Storage | null {
 }
 
 function newAnonymousId(): string {
-  if (typeof crypto !== "undefined" && "randomUUID" in crypto) return crypto.randomUUID();
-  return `anon-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+  return generateId();
 }
 
 export function getAnonymousId(): string {

package/src/utils/editDebugLog.ts

@@ -0,0 +1,16 @@
+// Gated strategic logging for the GSAP keyframe / manual-drag / gesture / razor
+// edit flows. Silent in production; on in dev builds, or anywhere once you set
+// `window.__hfDebug = true` in the console. Single `[hf-edit:<scope>]` prefix so
+// the whole edit pipeline is greppable. Fires only at commit boundaries (user
+// actions), never in render/raf loops, so it doesn't spam.
+export function editLog(scope: string, ...args: unknown[]): void {
+  if (typeof window === "undefined") return;
+  const w = window as unknown as { __hfDebug?: boolean };
+  if (!import.meta.env.DEV && !w.__hfDebug) return;
+  // Stringify object args so the console prints their contents inline (`{x:1}`)
+  // instead of a collapsed `Object` — keeps the edit trail greppable/copyable.
+  const parts = args.map((a) =>
+    typeof a === "object" && a !== null ? JSON.stringify(a) : String(a),
+  );
+  console.debug(`[hf-edit:${scope}]`, ...parts);
+}

package/src/utils/generateId.ts

@@ -0,0 +1,7 @@
+// ponytail: crypto.randomUUID is undefined on plain HTTP non-localhost origins
+export function generateId(): string {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+}