@hyperframes/studio 0.7.77 → 0.7.79

package/src/hooks/timelineTrackVisibility.ts

@@ -1,6 +1,11 @@
 import { useCallback } from "react";
 import { usePlayerStore, type TimelineElement } from "../player";
 import { useExpandedTimelineElements } from "../player/hooks/useExpandedTimelineElements";
+import {
+  timelineTrackOrder,
+  trackDisplayNumber,
+  trackDisplaySuffix,
+} from "../player/components/timelineTrackDisplay";
 import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
 import { readTagSnippetByTarget, type PatchOperation } from "../utils/sourcePatcher";
 import {
@@ -208,12 +213,17 @@ export async function toggleTimelineTrackHidden({
   domEditSaveTimestampRef,
   pendingTimelineEditPathRef,
 }: ToggleTimelineTrackHiddenInput): Promise<string[]> {
+  // `track` is the fractional sort key the callback needs; the history entry is
+  // read by a human, so it gets the display row instead.
+  const suffix = trackDisplaySuffix(
+    trackDisplayNumber(timelineTrackOrder(timelineElements), track),
+  );
   return setElementsHidden({
     projectId,
     activeCompPath,
     elements: timelineElements.filter((element) => element.track === track),
     hidden,
-    label: hidden ? `Hide track ${track}` : `Show track ${track}`,
+    label: hidden ? `Hide track${suffix}` : `Show track${suffix}`,
     previewIframe,
     writeProjectFile,
     recordEdit,

package/src/hooks/useAnimatedPropertyCommit.ts

@@ -14,7 +14,13 @@ import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { usePlayerStore } from "../player/store/playerStore";
 import { readAllAnimatedProperties, readGsapProperty } from "./gsapRuntimeBridge";
 import type { SetPatchProps } from "./gsapRuntimePatch";
-import { selectorFromSelection, computeElementPercentage, isInstantHold } from "./gsapShared";
+import {
+  selectorFromSelection,
+  computeElementPercentage,
+  isInstantHold,
+  writeTargetSelector,
+  tweenTargetsElement,
+} from "./gsapShared";
 import { resolveTweenStart, resolveTweenDuration } from "../utils/globalTimeCompiler";
 import { roundTo3 } from "../utils/rounding";
 import { commitWholePropertyOffset } from "./gsapWholePropertyOffsetCommit";
@@ -185,7 +191,9 @@ async function commitStaticSet(
     batch.push(entry);
     byGroup.set(group, batch);
   }
-  const staticWrites = animations.filter((a) => isInstantHold(a) && a.targetSelector === selector);
+  const staticWrites = animations.filter(
+    (a) => isInstantHold(a) && tweenTargetsElement(a.targetSelector, selector, selection.element),
+  );
   // Resolve every group's target BEFORE committing anything, and coalesce
   // groups that land on the SAME write into one commit: the snapshot is captured
   // once, so if two groups resolved to one legacy mixed write, a first
@@ -206,7 +214,7 @@ async function commitStaticSet(
   }
   // Fresh adds don't reshape existing sets, so their ids can't go stale.
   for (const batch of newSetBatches) {
-    await addGlobalStaticSet(selection, batch, selector, commit);
+    await addGlobalStaticSet(selection, batch, commit);
   }
 }
 
@@ -236,18 +244,22 @@ function findGroupOwningStaticWrite(
 async function addGlobalStaticSet(
   selection: DomEditSelection,
   batch: [string, number | string][],
-  selector: string,
   commit: Commit,
 ): Promise<void> {
   const numericProps: SetPatchProps = {};
   for (const [k, v] of batch) {
     if (typeof v === "number") numericProps[k as keyof SetPatchProps] = v;
   }
+  // A brand-new write, so it must address ONE element: the selection's own
+  // selector is the bare class an id-less element yields, which would hold every
+  // sibling. No one-element form means no write at all (see writeTargetSelector).
+  const target = writeTargetSelector(selection);
+  if (!target) return;
   await commit(
     selection,
     {
       type: "add",
-      targetSelector: selector,
+      targetSelector: target,
       method: "set",
       position: 0,
       properties: Object.fromEntries(batch),
@@ -259,7 +271,7 @@ async function addGlobalStaticSet(
       ...(Object.keys(numericProps).length > 0
         ? {
             instantPatch: {
-              selector,
+              selector: target,
               change: { kind: "global-set" as const, props: numericProps },
             },
           }
@@ -482,7 +494,11 @@ export function useAnimatedPropertyCommit(deps: CommitAnimatedPropertyDeps) {
         // contaminating a foreign-group tween. Mirror an existing keyframed tween's
         // time range so the new group animates over the same span. The 0% baseline is
         // an `_auto` endpoint so it tracks the nearest keyframe as you add more.
-        if (selector) {
+        // A fresh tween, so its target must address ONE element; with no
+        // one-element form the edit is dropped rather than written onto every
+        // class sibling (see writeTargetSelector).
+        const newTweenTarget = writeTargetSelector(selection);
+        if (selector && newTweenTarget) {
           const template = selectedGsapAnimations.find((a) => !!a.keyframes);
           const tStart = template ? (resolveTweenStart(template) ?? 0) : 0;
           const tDur = template ? resolveTweenDuration(template) || 1 : 1;
@@ -503,7 +519,7 @@ export function useAnimatedPropertyCommit(deps: CommitAnimatedPropertyDeps) {
             selection,
             {
               type: "add-with-keyframes",
-              targetSelector: selector,
+              targetSelector: newTweenTarget,
               position: roundTo3(tStart),
               duration: roundTo3(tDur),
               keyframes,

package/src/hooks/useEnableKeyframes.test.ts

@@ -466,3 +466,47 @@ describe("useEnableKeyframes — flat tween transaction", () => {
     });
   });
 });
+
+describe("useEnableKeyframes — new tween on a class-only element", () => {
+  it("targets the selected sibling alone, not every element sharing its class", async () => {
+    window.location.hash = "#/project/test-project";
+    usePlayerStore.setState({ currentTime: 1 });
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => ({ ok: true, json: async () => ({ animations: [] }) })),
+    );
+    const scene = document.body.appendChild(document.createElement("div"));
+    scene.id = "scene";
+    scene.innerHTML = '<i class="group"></i>'.repeat(5);
+    const groups = Array.from(scene.querySelectorAll<HTMLElement>(".group"));
+    const commitMutation = vi.fn(async () => undefined);
+    const enable = renderEnableKeyframes({
+      // A bare `.group` here writes `tl.to(".group", …)`, which animates all five
+      // siblings and reads back as all five — one add wiped the timeline.
+      domEditSelection: {
+        selector: ".group",
+        selectorIndex: 3,
+        sourceFile: "index.html",
+        element: groups[3],
+        dataAttributes: { start: "0", duration: "2" },
+      } as unknown as DomEditSelection,
+      selectedGsapAnimations: [],
+      previewIframeRef: {
+        current: {
+          contentWindow: { gsap: { getProperty: () => 7 } },
+        } as unknown as HTMLIFrameElement,
+      },
+      handleGsapAddAnimation: vi.fn(),
+      handleGsapConvertToKeyframes: vi.fn(),
+      handleGsapRemoveKeyframe: vi.fn(),
+      commitMutation,
+    });
+
+    await act(async () => enable());
+
+    const mutation = commitMutation.mock.calls[0]?.[0] as { targetSelector: string };
+    expect(mutation?.targetSelector).toBeTruthy();
+    expect(document.querySelectorAll(mutation.targetSelector)).toHaveLength(1);
+    expect(document.querySelector(mutation.targetSelector)).toBe(groups[3]);
+  });
+});

package/src/hooks/useEnableKeyframes.ts

@@ -13,11 +13,12 @@ import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { usePlayerStore } from "../player/store/playerStore";
 import { fetchParsedAnimations, getAnimationsForElement } from "./useGsapTweenCache";
 import {
-  selectorFromSelection,
+  existingTweenTargetSelector,
   computeElementPercentage,
   KEYFRAME_PCT_MATCH,
   isInstantHold,
   resolveEditableTweenDuration,
+  writeTargetSelector,
 } from "./gsapShared";
 import {
   absoluteToPercentage,
@@ -250,7 +251,10 @@ async function extendKeyframedTweenToPlayhead(
   iframe: HTMLIFrameElement | null,
   commitOverrides?: Partial<CommitMutationOptions>,
 ): Promise<void> {
-  const selector = selectorFromSelection(sel);
+  // Re-authoring an EXISTING tween: keep the target it already writes rather
+  // than re-deriving one from the selection, which would widen a tween already
+  // narrowed to one element back onto its class siblings (existingTweenTargetSelector).
+  const selector = existingTweenTargetSelector(anim, sel);
   const position = readElementPosition(iframe, sel, anim);
   if (!selector || Object.keys(position).length === 0 || !session.commitMutation) return;
   const extended = buildExtendedKeyframes(anim, currentTime, position, duration);
@@ -335,7 +339,10 @@ export async function promoteSetToKeyframes(
   t: number,
   iframe: HTMLIFrameElement | null,
 ): Promise<void> {
-  const selector = selectorFromSelection(sel);
+  // Re-authoring an EXISTING tween: keep the target it already writes rather
+  // than re-deriving one from the selection, which would widen a tween already
+  // narrowed to one element back onto its class siblings (existingTweenTargetSelector).
+  const selector = existingTweenTargetSelector(setAnim, sel);
   const setStart = resolveTweenStart(setAnim) ?? 0;
   if (!selector || !session.commitMutation) return;
   // Playhead at or before the set → there's no forward range to promote into.
@@ -389,7 +396,10 @@ export async function applyArcKeyframeAtPlayhead(
   iframe: HTMLIFrameElement | null,
 ): Promise<void> {
   if (!session.commitMutation) return;
-  const targetSelector = selectorFromSelection(sel);
+  // Re-authoring an EXISTING tween: keep the target it already writes rather
+  // than re-deriving one from the selection, which would widen a tween already
+  // narrowed to one element back onto its class siblings (existingTweenTargetSelector).
+  const targetSelector = existingTweenTargetSelector(arcAnim, sel);
   if (!targetSelector) return;
   const start = resolveTweenStart(arcAnim) ?? 0;
   const duration = resolveEditableTweenDuration(arcAnim, sel);
@@ -523,7 +533,10 @@ export function useEnableKeyframes(
         sel.dataAttributes?.duration,
         t,
       );
-      const selector = selectorFromSelection(sel);
+      // A brand-new tween: author it against the one element the user selected.
+      // The bare class selectorFromSelection hands back for an id-less element
+      // animates every sibling sharing the class (see writeTargetSelector).
+      const selector = writeTargetSelector(sel);
 
       if (!selector) {
         session.handleGsapAddAnimation("to");

package/src/hooks/useGestureCommit.ts

@@ -13,7 +13,7 @@ import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { CommitMutationOptions } from "./gsapScriptCommitTypes";
 import { roundTo3 } from "../utils/rounding";
 import { classifyPropertyGroup } from "@hyperframes/core/gsap-parser";
-import { isInstantHold, idSelector } from "./gsapShared";
+import { isInstantHold, idSelector, writeTargetSelector, tweenTargetsElement } from "./gsapShared";
 
 type RecordedKeyframe = {
   percentage: number;
@@ -168,11 +168,24 @@ export function useGestureCommit({
         if (!sortedPcts.includes(0)) sortedPcts.unshift(0);
       }
 
+      // Two different jobs, two different selectors. `selector` is the string an
+      // ALREADY-AUTHORED tween is matched against (and retargeted with, so a
+      // tween aimed at a whole group stays aimed at it). `writeSelector` is what
+      // a NEW tween is authored with: the bare class the id-less case yields here
+      // would record the gesture onto every sibling sharing it.
       const selector = sel.id ? idSelector(sel.id) : sel.selector;
       if (!selector) {
         showToast("Cannot save — element has no selector", "error");
         return;
       }
+      // A recorded gesture becomes a NEW tween, so its target must address one
+      // element; the selection's own selector would record the motion onto
+      // every sibling sharing its class (see writeTargetSelector).
+      const writeSelector = writeTargetSelector(sel);
+      if (!writeSelector) {
+        showToast("Cannot save: element has no unique selector", "error");
+        return;
+      }
       if (liveSession.commitMutation) {
         const recStart = recordingStartTimeRef.current;
         const rawKeyframes = sortedPcts.map((pct) => ({
@@ -186,7 +199,11 @@ export function useGestureCommit({
         );
         const allAnims = liveSession.selectedGsapAnimations ?? [];
         const existingPositionTween = hasPositionProps
-          ? allAnims.find((a) => a.propertyGroup === "position" && a.targetSelector === selector)
+          ? allAnims.find(
+              (a) =>
+                a.propertyGroup === "position" &&
+                tweenTargetsElement(a.targetSelector, selector, sel.element),
+            )
           : undefined;
         if (existingPositionTween) {
           if (isInstantHold(existingPositionTween)) {
@@ -261,7 +278,7 @@ export function useGestureCommit({
                 await liveSession.commitMutation(
                   {
                     type: "add-with-keyframes",
-                    targetSelector: selector,
+                    targetSelector: writeSelector,
                     position: roundTo3(recStart),
                     duration: roundTo3(duration),
                     keyframes: groupKfs,
@@ -287,7 +304,7 @@ export function useGestureCommit({
             await liveSession.commitMutation(
               {
                 type: "add-with-keyframes",
-                targetSelector: selector,
+                targetSelector: writeSelector,
                 position: roundTo3(recStart),
                 duration: roundTo3(duration),
                 keyframes: groupKfs,

package/src/hooks/useGsapScriptCommits.ts

@@ -186,6 +186,9 @@ function syncCommittedGsapMutation({
       targetPath,
       selection.id ?? undefined,
       mutation,
+      // The live preview document is what resolves a class / descendant tween to
+      // the elements it really animates; without it only whole-id selectors do.
+      iframe?.contentDocument,
     );
   }
   refreshMutationPreview(iframe, result, options, reloadPreview, onCacheInvalidate);

package/src/hooks/useGsapTweenCache.test.ts

@@ -86,16 +86,24 @@ describe("resolveSelectorElementIds", () => {
     expect(resolveSelectorElementIds(".a, .b", doc).sort()).toEqual(["x", "y"]);
   });
 
-  it("falls back to a leading #id when there is no DOM", () => {
-    expect(resolveSelectorElementIds("#card .label", null)).toEqual(["card"]);
+  // A DOM-less LEADING-id fallback attributed `#card .label` to `#card`, the
+  // ancestor it merely scopes to. Without a DOM there is nothing to resolve the
+  // descendant against, so the honest answer is no element at all.
+  it("resolves nothing for a compound selector when there is no DOM", () => {
+    expect(resolveSelectorElementIds("#card .label", null)).toEqual([]);
     expect(resolveSelectorElementIds(".dot", null)).toEqual([]);
   });
 
+  it("still resolves every whole-id part of a group selector without a DOM", () => {
+    expect(resolveSelectorElementIds("#a, #b", null)).toEqual(["a", "b"]);
+  });
+
   // The `[id="…"]` form is what writers emit for a CSS-unsafe id (digit-leading,
   // dotted). The old local `#id`-only regex read no id at all for those, so they
   // silently dropped out of both DOM-less paths.
   it("falls back to a bracketed id when there is no DOM", () => {
-    expect(resolveSelectorElementIds('[id="01-hook"] .label', null)).toEqual(["01-hook"]);
+    expect(resolveSelectorElementIds('[id="01-hook"]', null)).toEqual(["01-hook"]);
+    expect(resolveSelectorElementIds('[id="01-hook"] .label', null)).toEqual([]);
   });
 
   it("falls back to a bracketed id when querySelectorAll rejects the selector", () => {

package/src/hooks/useGsapTweenCache.ts

@@ -7,24 +7,17 @@ import {
   pruneKeyframeCacheToFiles,
   writeGsapAnimationsForElement,
 } from "./gsapKeyframeCacheHelpers";
-import { toAbsoluteTime, toClipPercentage } from "./gsapShared";
+import { resolveClipTimingBasis, toAbsoluteTime, toClipPercentage } from "./gsapShared";
 import {
   deduplicateKeyframes,
   isStaticPositionHold,
   synthesizeFlatTweenKeyframes,
 } from "./gsapTweenSynth";
-import {
-  fetchParsedAnimations,
-  populateKeyframeCacheFromAst,
-  resolveClipTimingBasis,
-} from "./keyframeCacheAstLoad";
+import { fetchParsedAnimations, populateKeyframeCacheFromAst } from "./keyframeCacheAstLoad";
 
 // Re-exported so callers keep importing the GSAP cache surface from one module.
-export {
-  fetchParsedAnimations,
-  resolveClipTimingBasis,
-  resolveSelectorElementIds,
-} from "./keyframeCacheAstLoad";
+export { resolveClipTimingBasis } from "./gsapShared";
+export { fetchParsedAnimations, resolveSelectorElementIds } from "./keyframeCacheAstLoad";
 
 /** The selected element's identity for matching tweens to it. */
 export interface GsapElementTarget {

package/src/player/components/LayerDisclosureRow.tsx

@@ -22,7 +22,10 @@ export function LayerDisclosureRow({
   /** Same adaptive width the lane rows use: a narrowed header column must not
    *  leave this row hanging over the clips it labels. */
   columnWidth: number;
-  /** Id of the element holding the lanes this row's caret expands. */
+  /** Id of the CANVAS-side element holding the diamond lanes this row's caret
+   *  expands (see TimelinePropertyLanes). The caret also reveals the per-lane
+   *  control rows in this column, but the diamonds are what following the
+   *  reference should land on. */
   lanesId: string;
   onToggleClipExpanded: () => void;
   /** Trailing controls that act on the LAYER (the visibility eye), not on a lane. */

package/src/player/components/Player.test.ts

@@ -1,7 +1,146 @@
 // @vitest-environment happy-dom
 
-import { describe, expect, it } from "vitest";
-import { hasUnloadedAssets, shouldShowCompositionLoadingOverlay } from "./Player";
+import { act, createElement } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  hasUnloadedAssets,
+  Player,
+  readPreviewErrorMessage,
+  shouldShowCompositionLoadingOverlay,
+} from "./Player";
+
+vi.mock("@hyperframes/player", () => ({}));
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+let root: Root | null = null;
+let lifecycleLog: string[] = [];
+
+class TestHyperframesPlayer extends HTMLElement {
+  readonly iframeElement = document.createElement("iframe");
+
+  constructor() {
+    super();
+
+    const addIframeListener = this.iframeElement.addEventListener.bind(this.iframeElement);
+    this.iframeElement.addEventListener = ((type, listener, options) => {
+      lifecycleLog.push(`iframe:${type}`);
+      addIframeListener(type, listener, options);
+    }) as typeof this.iframeElement.addEventListener;
+
+    const addPlayerListener = this.addEventListener.bind(this);
+    this.addEventListener = ((type, listener, options) => {
+      lifecycleLog.push(`player:${type}`);
+      addPlayerListener(type, listener, options);
+    }) as typeof this.addEventListener;
+
+    const setPlayerAttribute = this.setAttribute.bind(this);
+    this.setAttribute = (name, value) => {
+      if (name === "src") lifecycleLog.push("src");
+      setPlayerAttribute(name, value);
+    };
+  }
+}
+
+if (!customElements.get("hyperframes-player")) {
+  customElements.define("hyperframes-player", TestHyperframesPlayer);
+}
+
+afterEach(() => {
+  if (root) act(() => root?.unmount());
+  root = null;
+  lifecycleLog = [];
+  document.body.innerHTML = "";
+});
+
+async function mountPlayer() {
+  const host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+  await act(async () => {
+    root?.render(
+      createElement(Player, {
+        directUrl: "/api/projects/demo/preview",
+        onLoad: vi.fn(),
+        suppressLoadingOverlay: true,
+      }),
+    );
+    await Promise.resolve();
+  });
+
+  const player = host.querySelector<TestHyperframesPlayer>("hyperframes-player");
+  if (!player) throw new Error("player did not mount");
+  return { host, player };
+}
+
+function createAudioIframe() {
+  const iframe = document.createElement("iframe");
+  document.body.appendChild(iframe);
+  const audio = iframe.contentDocument?.createElement("audio");
+  expect(audio).toBeDefined();
+  iframe.contentDocument?.body.appendChild(audio!);
+  return { audio: audio!, iframe };
+}
+
+describe("preview errors", () => {
+  it("reads the player probe error for the visible retry state", () => {
+    expect(
+      readPreviewErrorMessage(
+        new CustomEvent("error", {
+          detail: { message: "Composition timeline not found after 8s" },
+        }),
+      ),
+    ).toBe("Composition timeline not found after 8s");
+  });
+
+  it("falls back when the player emits an unstructured error", () => {
+    expect(readPreviewErrorMessage(new Event("error"))).toBe(
+      "The composition preview did not become ready.",
+    );
+  });
+
+  it("attaches lifecycle listeners before navigating the player", async () => {
+    await mountPlayer();
+    const srcIndex = lifecycleLog.indexOf("src");
+
+    expect(srcIndex).toBeGreaterThan(-1);
+    for (const listener of [
+      "iframe:load",
+      "player:click",
+      "player:shadertransitionstate",
+      "player:ready",
+      "player:error",
+    ]) {
+      expect(lifecycleLog.indexOf(listener)).toBeGreaterThan(-1);
+      expect(lifecycleLog.indexOf(listener)).toBeLessThan(srcIndex);
+    }
+  });
+
+  it("retries a failed preview with a fresh player URL", async () => {
+    const { host, player } = await mountPlayer();
+
+    act(() => {
+      player.dispatchEvent(
+        new CustomEvent("error", {
+          detail: { message: "Composition timeline not found after 8s" },
+        }),
+      );
+    });
+
+    expect(host.querySelector('[data-testid="composition-preview-error"]')).not.toBeNull();
+    const retry = Array.from(host.querySelectorAll("button")).find(
+      (button) => button.textContent === "Retry preview",
+    );
+    if (!retry) throw new Error("retry action did not render");
+
+    act(() => retry.click());
+
+    const retryUrl = new URL(player.getAttribute("src") ?? "", window.location.origin);
+    expect(retryUrl.searchParams.get("_hfStudioRetry")).toBe("1");
+    expect(host.querySelector('[data-testid="composition-preview-error"]')).toBeNull();
+  });
+});
 
 describe("composition loading overlay", () => {
   it("shows while the composition is loading", () => {
@@ -13,10 +152,7 @@ describe("composition loading overlay", () => {
   });
 
   it("keeps the asset overlay up while media is still buffering", () => {
-    const iframe = document.createElement("iframe");
-    document.body.appendChild(iframe);
-    const audio = iframe.contentDocument?.createElement("audio");
-    expect(audio).toBeDefined();
+    const { audio, iframe } = createAudioIframe();
     Object.defineProperty(audio, "readyState", {
       value: 0,
       configurable: true,
@@ -25,7 +161,6 @@ describe("composition loading overlay", () => {
       value: 2,
       configurable: true,
     });
-    iframe.contentDocument?.body.appendChild(audio!);
 
     expect(hasUnloadedAssets(iframe, false)).toBe(true);
 
@@ -33,10 +168,7 @@ describe("composition loading overlay", () => {
   });
 
   it("does not keep the asset overlay stuck on failed media sources", () => {
-    const iframe = document.createElement("iframe");
-    document.body.appendChild(iframe);
-    const audio = iframe.contentDocument?.createElement("audio");
-    expect(audio).toBeDefined();
+    const { audio, iframe } = createAudioIframe();
     Object.defineProperty(audio, "error", {
       value: { code: 4, message: "format error" },
       configurable: true,
@@ -49,7 +181,6 @@ describe("composition loading overlay", () => {
       value: 3,
       configurable: true,
     });
-    iframe.contentDocument?.body.appendChild(audio!);
 
     expect(hasUnloadedAssets(iframe, false)).toBe(false);