@hyperframes/studio 0.6.58 → 0.6.60

package/src/components/editor/domEditingElement.ts

@@ -153,31 +153,49 @@ export function resolveVisualDomEditSelectionTarget(
   elementsFromPoint: Iterable<Element | null | undefined>,
   options: Pick<DomEditContextOptions, "activeCompositionPath">,
 ): HTMLElement | null {
-  const candidates: HTMLElement[] = [];
+  const candidates = resolveAllVisualDomEditTargets(elementsFromPoint, options);
+  return candidates[0] ?? null;
+}
+
+/**
+ * Returns all independently-selectable elements at the given point, in paint
+ * order (topmost first). Used for click-cycling through stacked layers.
+ *
+ * Each entry in the returned array is an independent "layer" — an element
+ * that is not an ancestor of an earlier entry. This gives one result per
+ * z-stacked element rather than one per DOM node.
+ */
+export function resolveAllVisualDomEditTargets(
+  elementsFromPoint: Iterable<Element | null | undefined>,
+  options: Pick<DomEditContextOptions, "activeCompositionPath">,
+): HTMLElement[] {
+  const raw: HTMLElement[] = [];
 
   for (const entry of elementsFromPoint) {
     if (!isHtmlElement(entry)) continue;
     if (hasRenderedBox(entry) && getDomLayerPatchTarget(entry, options.activeCompositionPath)) {
-      candidates.push(entry);
+      raw.push(entry);
     }
   }
 
-  if (candidates.length === 0) return null;
-
-  // candidates are in visual stacking order (topmost first, from elementsFromPoint).
-  // Start with the topmost and only replace with a descendant that is more
-  // specific within the same visual subtree. Never jump to an unrelated
-  // element that happens to be painted behind the current pick.
-  let best = candidates[0];
-
-  for (let i = 1; i < candidates.length; i++) {
-    const candidate = candidates[i];
-    if (best.contains(candidate)) {
-      best = candidate;
+  if (raw.length === 0) return [];
+
+  // First pass: for each contiguous ancestor-descendant run, keep only the
+  // deepest (most specific) element, matching the original single-pick logic.
+  const layers: HTMLElement[] = [];
+  let best = raw[0];
+  for (let i = 1; i < raw.length; i++) {
+    const el = raw[i];
+    if (best.contains(el)) {
+      best = el; // go deeper in this subtree
+    } else {
+      layers.push(best);
+      best = el;
     }
   }
+  layers.push(best);
 
-  return best;
+  return layers;
 }
 
 // ─── Raster detection ────────────────────────────────────────────────────────
@@ -248,6 +266,7 @@ export function findElementForSelection(
   return matches[0] ?? null;
 }
 
+// fallow-ignore-next-line complexity
 export function findElementForTimelineElement(
   doc: Document,
   element: TimelineElementDomTarget,

package/src/components/editor/gsapAnimationConstants.ts

@@ -4,7 +4,7 @@ export const METHOD_LABELS: Record<string, string> = {
   set: "Set",
   to: "Animate",
   from: "Animate In",
-  fromTo: "Animate",
+  fromTo: "From → To",
 };
 
 export const METHOD_TOOLTIPS: Record<string, string> = {
@@ -121,6 +121,8 @@ export function parseCustomEaseFromString(ease: string): {
   return { x1: nums[2], y1: nums[3], x2: nums[4], y2: nums[5] };
 }
 
+export const PERCENT_PROPS = new Set(["opacity", "autoAlpha"]);
+
 export const ADD_METHODS = ["to", "from", "fromTo", "set"] as const;
 
 export const ADD_METHOD_LABELS: Record<string, string> = {

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

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+import { buildTweenSummary } from "./gsapAnimationHelpers";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+
+function anim(overrides: Partial<GsapAnimation>): GsapAnimation {
+  return {
+    id: "a1",
+    method: "to",
+    targetSelector: "#box",
+    properties: {},
+    position: 0,
+    duration: 1,
+    ease: "power2.out",
+    ...overrides,
+  } as GsapAnimation;
+}
+
+describe("buildTweenSummary", () => {
+  it("describes a to tween", () => {
+    const s = buildTweenSummary(anim({ properties: { opacity: 1, x: 100 } }));
+    expect(s).toContain("#box");
+    expect(s).toContain("opacity");
+    expect(s).toContain("move x");
+  });
+
+  it("describes a from tween", () => {
+    const s = buildTweenSummary(anim({ method: "from", properties: { opacity: 0 } }));
+    expect(s).toContain("enters from");
+    expect(s).toContain("opacity");
+  });
+
+  it("describes a set tween", () => {
+    const s = buildTweenSummary(anim({ method: "set", properties: { opacity: 0 } }));
+    expect(s).toMatch(/^At 0s, instantly set/);
+    expect(s).toContain("opacity");
+  });
+
+  it("describes a fromTo tween with both from and to sections", () => {
+    const s = buildTweenSummary(
+      anim({
+        method: "fromTo",
+        fromProperties: { opacity: 0, x: -50 },
+        properties: { opacity: 1, x: 0 },
+        position: 0.5,
+        duration: 1.5,
+        ease: "expo.out",
+      }),
+    );
+    expect(s).toContain("animates from");
+    expect(s).toContain("[opacity 0%");
+    expect(s).toContain("move x -50px");
+    expect(s).toContain("opacity to 100%");
+    expect(s).toContain("very snappy stop");
+  });
+
+  it("handles fromTo with empty fromProperties", () => {
+    const s = buildTweenSummary(
+      anim({ method: "fromTo", fromProperties: {}, properties: { scale: 2 } }),
+    );
+    expect(s).toContain("from [—]");
+  });
+
+  it("handles no properties", () => {
+    const s = buildTweenSummary(anim({ properties: {} }));
+    expect(s).toContain("no properties yet");
+  });
+});

package/src/components/editor/gsapAnimationHelpers.ts

@@ -0,0 +1,36 @@
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import { EASE_LABELS, PERCENT_PROPS, PROP_LABELS, PROP_UNITS } from "./gsapAnimationConstants";
+
+function formatPropValue(prop: string, v: number | string): string {
+  const unit = PROP_UNITS[prop] ?? "";
+  if (PERCENT_PROPS.has(prop)) return `${Math.round(Number(v) * 100)}${unit}`;
+  return `${v}${unit}`;
+}
+
+// fallow-ignore-next-line complexity
+export function buildTweenSummary(animation: GsapAnimation): string {
+  const easeName = animation.ease ?? "none";
+  const ease = EASE_LABELS[easeName] ?? easeName;
+  const props = Object.entries(animation.properties);
+  const target = animation.targetSelector;
+  const dur = animation.duration ?? 0;
+  const pos = animation.position;
+  const propDescs = props.map(([p, v]) => {
+    const label = (PROP_LABELS[p] ?? p).toLowerCase();
+    return `${label} to ${formatPropValue(p, v)}`;
+  });
+  const propText = propDescs.length > 0 ? propDescs.join(", ") : "no properties yet";
+  if (animation.method === "set") return `At ${pos}s, instantly set ${target}'s ${propText}.`;
+  if (animation.method === "from")
+    return `Starting at ${pos}s, over ${dur}s, ${target} enters from ${propText} using a ${ease.toLowerCase()} curve.`;
+  if (animation.method === "fromTo") {
+    const fromProps = Object.entries(animation.fromProperties ?? {});
+    const fromDescs = fromProps.map(([p, v]) => {
+      const label = (PROP_LABELS[p] ?? p).toLowerCase();
+      return `${label} ${formatPropValue(p, v)}`;
+    });
+    const fromText = fromDescs.length > 0 ? fromDescs.join(", ") : "—";
+    return `Starting at ${pos}s, over ${dur}s, ${target} animates from [${fromText}] to [${propText}] using a ${ease.toLowerCase()} curve.`;
+  }
+  return `Starting at ${pos}s, over ${dur}s, animate ${target}'s ${propText} using a ${ease.toLowerCase()} curve.`;
+}

package/src/components/editor/propertyPanelPrimitives.tsx

@@ -29,7 +29,7 @@ function CommitField({
     const el = inputRef.current;
     if (!el) return;
     const handler = (e: WheelEvent) => {
-      if (disabled) return;
+      if (disabled || document.activeElement !== el) return;
       const delta = e.deltaY === 0 ? e.deltaX : e.deltaY;
       if (delta === 0) return;
       const nextDraft = adjustNumericToken(draftRef.current, delta < 0 ? 1 : -1, e);

package/src/components/nle/NLELayout.tsx

@@ -97,6 +97,7 @@ export function shouldDisableTimelineWhileCompositionLoading(compositionLoading:
   return compositionLoading;
 }
 
+// fallow-ignore-next-line complexity
 export const NLELayout = memo(function NLELayout({
   projectId,
   portrait,
@@ -367,7 +368,7 @@ export const NLELayout = memo(function NLELayout({
       {/* Preview + player controls */}
       <div className="flex-1 min-h-0 flex flex-col">
         <div
-          className="flex-1 min-h-0 relative"
+          className="flex-1 min-h-0 relative overflow-hidden"
           data-preview-pan-surface="true"
           onDragOver={handlePreviewDragOver}
           onDragLeave={handlePreviewDragLeave}

package/src/hooks/useDomEditSession.ts

@@ -67,6 +67,7 @@ export interface UseDomEditSessionParams {
 
 // ── Hook ──
 
+// fallow-ignore-next-line complexity
 export function useDomEditSession({
   projectId,
   activeCompPath,
@@ -129,6 +130,7 @@ export function useDomEditSession({
     clearDomSelection,
     buildDomSelectionFromTarget,
     resolveDomSelectionFromPreviewPoint,
+    resolveAllDomSelectionsFromPreviewPoint,
     updateDomEditHoverSelection,
     buildDomSelectionForTimelineElement,
     handleTimelineElementSelect,
@@ -187,6 +189,7 @@ export function useDomEditSession({
     showToast,
     applyDomSelection,
     resolveDomSelectionFromPreviewPoint,
+    resolveAllDomSelectionsFromPreviewPoint,
     updateDomEditHoverSelection,
     onClickToSource,
   });
@@ -343,6 +346,7 @@ export function useDomEditSession({
   useEffect(() => {
     if (!previewIframe) return;
 
+    // fallow-ignore-next-line complexity
     const syncSelectionFromDocument = async () => {
       if (!STUDIO_INSPECTOR_PANELS_ENABLED || captionEditMode) return;
       const currentSelection = domEditSelectionRef.current;
@@ -402,16 +406,20 @@ export function useDomEditSession({
   // not when openSourceForSelection is recreated due to editingFile content updates.
   const openSourceRef = useRef(openSourceForSelection);
   openSourceRef.current = openSourceForSelection;
-  useEffect(() => {
-    if (!domEditSelection || !openSourceRef.current || !getSidebarTab) return;
-    if (!domEditSelection.sourceFile) return;
-    if (getSidebarTab() !== "code") return;
-    openSourceRef.current(domEditSelection.sourceFile, {
-      id: domEditSelection.id,
-      selector: domEditSelection.selector,
-      selectorIndex: domEditSelection.selectorIndex,
-    });
-  }, [domEditSelection, getSidebarTab]);
+  useEffect(
+    // fallow-ignore-next-line complexity
+    () => {
+      if (!domEditSelection || !openSourceRef.current || !getSidebarTab) return;
+      if (!domEditSelection.sourceFile) return;
+      if (getSidebarTab() !== "code") return;
+      openSourceRef.current(domEditSelection.sourceFile, {
+        id: domEditSelection.id,
+        selector: domEditSelection.selector,
+        selectorIndex: domEditSelection.selectorIndex,
+      });
+    },
+    [domEditSelection, getSidebarTab],
+  );
 
   return {
     // State

package/src/hooks/useDomSelection.ts

@@ -1,6 +1,9 @@
 import { useState, useCallback, useRef, useEffect } from "react";
 import type { TimelineElement } from "../player";
-import { getPreviewTargetFromPointer } from "../utils/studioPreviewHelpers";
+import {
+  getAllPreviewTargetsFromPointer,
+  getPreviewTargetFromPointer,
+} from "../utils/studioPreviewHelpers";
 import { findMatchingTimelineElementId, type RightPanelTab } from "../utils/studioHelpers";
 import {
   domEditSelectionsTargetSame,
@@ -67,6 +70,10 @@ export interface UseDomSelectionReturn {
     clientY: number,
     options?: { preferClipAncestor?: boolean },
   ) => Promise<DomEditSelection | null>;
+  resolveAllDomSelectionsFromPreviewPoint: (
+    clientX: number,
+    clientY: number,
+  ) => Promise<DomEditSelection[]>;
   updateDomEditHoverSelection: (selection: DomEditSelection | null) => void;
   buildDomSelectionForTimelineElement: (
     element: TimelineElement,
@@ -113,6 +120,7 @@ export function useDomSelection({
   // ── Callbacks ──
 
   const applyDomSelection = useCallback(
+    // fallow-ignore-next-line complexity
     (
       selection: DomEditSelection | null,
       options?: {
@@ -212,6 +220,7 @@ export function useDomSelection({
   );
 
   const resolveDomSelectionFromPreviewPoint = useCallback(
+    // fallow-ignore-next-line complexity
     async (
       clientX: number,
       clientY: number,
@@ -234,6 +243,27 @@ export function useDomSelection({
     [activeCompPath, buildDomSelectionFromTarget, captionEditMode, previewIframeRef],
   );
 
+  const resolveAllDomSelectionsFromPreviewPoint = useCallback(
+    // fallow-ignore-next-line complexity
+    async (clientX: number, clientY: number): Promise<DomEditSelection[]> => {
+      const iframe = previewIframeRef.current;
+      if (!iframe || captionEditMode) return [];
+      try {
+        if (iframe.contentDocument) reapplyPositionEditsAfterSeek(iframe.contentDocument);
+      } catch {
+        /* cross-origin guard */
+      }
+      const targets = getAllPreviewTargetsFromPointer(iframe, clientX, clientY, activeCompPath);
+      const results: DomEditSelection[] = [];
+      for (const target of targets) {
+        const sel = await buildDomSelectionFromTarget(target, { skipSourceProbe: true });
+        if (sel) results.push(sel);
+      }
+      return results;
+    },
+    [activeCompPath, buildDomSelectionFromTarget, captionEditMode, previewIframeRef],
+  );
+
   const updateDomEditHoverSelection = useCallback((selection: DomEditSelection | null) => {
     if (domEditSelectionsTargetSame(domEditHoverSelectionRef.current, selection)) return;
     domEditHoverSelectionRef.current = selection;
@@ -241,6 +271,7 @@ export function useDomSelection({
   }, []);
 
   const buildDomSelectionForTimelineElement = useCallback(
+    // fallow-ignore-next-line complexity
     async (element: TimelineElement): Promise<DomEditSelection | null> => {
       const iframe = previewIframeRef.current;
       let doc: Document | null = null;
@@ -282,6 +313,7 @@ export function useDomSelection({
   );
 
   const refreshDomEditSelectionFromPreview = useCallback(
+    // fallow-ignore-next-line complexity
     async (selection: DomEditSelection) => {
       const iframe = previewIframeRef.current;
       let doc: Document | null = null;
@@ -307,6 +339,7 @@ export function useDomSelection({
   );
 
   const refreshDomEditGroupSelectionsFromPreview = useCallback(
+    // fallow-ignore-next-line complexity
     async (selections: DomEditSelection[]) => {
       const iframe = previewIframeRef.current;
       let doc: Document | null = null;
@@ -430,6 +463,7 @@ export function useDomSelection({
     clearDomSelection,
     buildDomSelectionFromTarget,
     resolveDomSelectionFromPreviewPoint,
+    resolveAllDomSelectionsFromPreviewPoint,
     updateDomEditHoverSelection,
     buildDomSelectionForTimelineElement,
     handleTimelineElementSelect,

package/src/hooks/useFileManager.ts

@@ -38,6 +38,7 @@ export function useFileManager({
   const [editingFile, setEditingFile] = useState<EditingFile | null>(null);
   const [projectDir, setProjectDir] = useState<string | null>(null);
   const [fileTree, setFileTree] = useState<string[]>([]);
+  const [compositionPaths, setCompositionPaths] = useState<string[]>([]);
   const [fileTreeLoaded, setFileTreeLoaded] = useState(false);
   const [revealSourceOffset, setRevealSourceOffset] = useState<number | null>(null);
 
@@ -65,8 +66,9 @@ export function useFileManager({
     setFileTreeLoaded(false);
     fetch(`/api/projects/${projectId}`)
       .then((r) => r.json())
-      .then((data: { files?: string[]; dir?: string }) => {
+      .then((data: { files?: string[]; dir?: string; compositions?: string[] }) => {
         if (!cancelled && data.files) setFileTree(data.files);
+        if (!cancelled && data.compositions) setCompositionPaths(data.compositions);
         if (!cancelled) setProjectDir(typeof data.dir === "string" ? data.dir : null);
       })
       .catch(() => {
@@ -417,10 +419,7 @@ export function useFileManager({
 
   // ── Derived state ──
 
-  const compositions = useMemo(
-    () => fileTree.filter((f) => f === "index.html" || f.startsWith("compositions/")),
-    [fileTree],
-  );
+  const compositions = compositionPaths;
 
   const assets = useMemo(
     () =>

package/src/hooks/useGsapScriptCommits.ts

@@ -105,6 +105,7 @@ export function useGsapScriptCommits({
 
   /** Send a mutation and record the edit in undo history. */
   const commitMutation = useCallback(
+    // fallow-ignore-next-line complexity
     async (
       selection: DomEditSelection,
       mutation: Record<string, unknown>,
@@ -210,6 +211,7 @@ export function useGsapScriptCommits({
   );
 
   const addGsapAnimation = useCallback(
+    // fallow-ignore-next-line complexity
     async (
       selection: DomEditSelection,
       method: "to" | "from" | "set" | "fromTo",
@@ -268,6 +270,7 @@ export function useGsapScriptCommits({
   );
 
   const addGsapProperty = useCallback(
+    // fallow-ignore-next-line complexity
     (selection: DomEditSelection, animationId: string, property: string) => {
       let defaultValue = PROPERTY_DEFAULTS[property] ?? 0;
       const el = selection.element;

package/src/hooks/usePreviewInteraction.ts

@@ -1,4 +1,4 @@
-import { useCallback } from "react";
+import { useCallback, useRef } from "react";
 import { liveTime, usePlayerStore } from "../player";
 import { pauseStudioPreviewPlayback } from "../utils/studioPreviewHelpers";
 import { STUDIO_PREVIEW_SELECTION_ENABLED } from "../components/editor/manualEditingAvailability";
@@ -22,11 +22,26 @@ export interface UsePreviewInteractionParams {
     clientY: number,
     options?: { preferClipAncestor?: boolean; skipSourceProbe?: boolean },
   ) => Promise<DomEditSelection | null>;
+  resolveAllDomSelectionsFromPreviewPoint: (
+    clientX: number,
+    clientY: number,
+  ) => Promise<DomEditSelection[]>;
   updateDomEditHoverSelection: (selection: DomEditSelection | null) => void;
 
   onClickToSource?: (selection: DomEditSelection) => void;
 }
 
+interface ClickCycleState {
+  x: number;
+  y: number;
+  candidates: DomEditSelection[];
+  index: number;
+  at: number;
+}
+
+const CYCLE_RADIUS_PX = 6;
+const CYCLE_WINDOW_MS = 600;
+
 // ── Hook ──
 
 export function usePreviewInteraction({
@@ -36,36 +51,85 @@ export function usePreviewInteraction({
   showToast,
   applyDomSelection,
   resolveDomSelectionFromPreviewPoint,
+  resolveAllDomSelectionsFromPreviewPoint,
   updateDomEditHoverSelection,
   onClickToSource,
 }: UsePreviewInteractionParams) {
+  const cycleRef = useRef<ClickCycleState | null>(null);
+
   const handlePreviewCanvasMouseDown = useCallback(
+    // fallow-ignore-next-line complexity
     async (e: React.MouseEvent<HTMLDivElement>, options?: { preferClipAncestor?: boolean }) => {
       if (!STUDIO_PREVIEW_SELECTION_ENABLED || captionEditMode || compositionLoading) return;
+
+      const now = Date.now();
+      const prev = cycleRef.current;
+      const dx = prev ? e.clientX - prev.x : Infinity;
+      const dy = prev ? e.clientY - prev.y : Infinity;
+      const sameSpot =
+        prev !== null &&
+        Math.sqrt(dx * dx + dy * dy) < CYCLE_RADIUS_PX &&
+        now - prev.at < CYCLE_WINDOW_MS;
+
+      if (e.shiftKey) {
+        // Additive selection — no cycling
+        cycleRef.current = null;
+        const nextSelection = await resolveDomSelectionFromPreviewPoint(e.clientX, e.clientY, {
+          preferClipAncestor: options?.preferClipAncestor ?? false,
+        });
+        if (!nextSelection) return;
+        e.preventDefault();
+        e.stopPropagation();
+        applyDomSelection(nextSelection, { additive: true });
+        return;
+      }
+
+      if (sameSpot && prev) {
+        // Cycle to next candidate in z-stack
+        const nextIndex = (prev.index + 1) % prev.candidates.length;
+        const nextSel = prev.candidates[nextIndex];
+        cycleRef.current = { ...prev, index: nextIndex, at: now };
+        e.preventDefault();
+        e.stopPropagation();
+        applyDomSelection(nextSel);
+        return;
+      }
+
+      // Fresh click — resolve topmost element
       const nextSelection = await resolveDomSelectionFromPreviewPoint(e.clientX, e.clientY, {
         preferClipAncestor: options?.preferClipAncestor ?? false,
       });
       if (!nextSelection) {
-        if (!e.shiftKey) applyDomSelection(null, { revealPanel: false });
+        cycleRef.current = null;
+        applyDomSelection(null, { revealPanel: false });
         return;
       }
       e.preventDefault();
       e.stopPropagation();
-      applyDomSelection(nextSelection, { additive: e.shiftKey });
+      applyDomSelection(nextSelection);
+
       if (!e.shiftKey && e.altKey && onClickToSource) {
         onClickToSource(nextSelection);
       }
+
+      // Resolve all stacked candidates so a subsequent click at the same
+      // position can cycle to the next layer (issues #1124, #1125).
+      const all = await resolveAllDomSelectionsFromPreviewPoint(e.clientX, e.clientY);
+      cycleRef.current =
+        all.length > 1 ? { x: e.clientX, y: e.clientY, candidates: all, index: 0, at: now } : null;
     },
     [
       applyDomSelection,
       captionEditMode,
       compositionLoading,
       onClickToSource,
+      resolveAllDomSelectionsFromPreviewPoint,
       resolveDomSelectionFromPreviewPoint,
     ],
   );
 
   const handlePreviewCanvasPointerMove = useCallback(
+    // fallow-ignore-next-line complexity
     async (e: React.PointerEvent<HTMLDivElement>, options?: { preferClipAncestor?: boolean }) => {
       if (!STUDIO_PREVIEW_SELECTION_ENABLED || captionEditMode || compositionLoading) {
         updateDomEditHoverSelection(null);