@hyperframes/studio 0.7.46 → 0.7.47

package/src/hooks/useDomSelection.test.ts

@@ -2,7 +2,9 @@
 
 import React, { act } from "react";
 import { createRoot } from "react-dom/client";
-import { describe, expect, it, vi } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { TimelineElement } from "../player";
+import { usePlayerStore } from "../player/store/playerStore";
 import { installReactActEnvironment, makeSelection } from "./domSelectionTestHarness";
 import { useDomSelection } from "./useDomSelection";
 
@@ -12,6 +14,7 @@ interface HarnessProps {
   activeCompPath: string | null;
   projectId: string | null;
   refreshKey: number;
+  timelineElements?: TimelineElement[];
 }
 
 function renderHarness(initialProps: HarnessProps): {
@@ -32,7 +35,7 @@ function renderHarness(initialProps: HarnessProps): {
       compIdToSrc: new Map(),
       captionEditMode: false,
       previewIframeRef: { current: null },
-      timelineElements: [],
+      timelineElements: props.timelineElements ?? [],
       setSelectedTimelineElementId: vi.fn(),
       setRightCollapsed: vi.fn(),
       setRightPanelTab: vi.fn(),
@@ -64,6 +67,10 @@ function renderHarness(initialProps: HarnessProps): {
   };
 }
 
+afterEach(() => {
+  usePlayerStore.getState().reset();
+});
+
 function setupSelectedHarness() {
   const element = document.createElement("div");
   element.id = "headline";
@@ -131,4 +138,31 @@ describe("useDomSelection", () => {
     expect(harness.current().domEditSelection).toBe(selection);
     harness.cleanup();
   });
+
+  it("keeps preview marquee selections mirrored to the full timeline selection set", () => {
+    const first = document.createElement("div");
+    first.id = "clip-1";
+    const second = document.createElement("div");
+    second.id = "clip-2";
+    const firstSelection = makeSelection("First", first);
+    const secondSelection = makeSelection("Second", second);
+    const harness = renderHarness({
+      activeCompPath: "intro.html",
+      projectId: "project-1",
+      refreshKey: 0,
+      timelineElements: [
+        { id: "clip-1", domId: "clip-1", tag: "div", start: 0, duration: 1, track: 0 },
+        { id: "clip-2", domId: "clip-2", tag: "div", start: 1, duration: 1, track: 1 },
+      ],
+    });
+
+    act(() => harness.current().applyMarqueeSelection([secondSelection, firstSelection], false));
+
+    const state = usePlayerStore.getState();
+    expect([...state.selectedElementIds]).toEqual(["clip-2", "clip-1"]);
+    expect(state.selectedElementId).toBe("clip-2");
+    expect(harness.current().domEditGroupSelections).toHaveLength(2);
+    expect(harness.current().domEditSelection).toBe(secondSelection);
+    harness.cleanup();
+  });
 });

package/src/hooks/useDomSelection.ts

@@ -4,11 +4,7 @@ import {
   getAllPreviewTargetsFromPointer,
   getPreviewTargetFromPointer,
 } from "../utils/studioPreviewHelpers";
-import {
-  findMatchingTimelineElementId,
-  findTimelineIdByAncestor,
-  type RightPanelTab,
-} from "../utils/studioHelpers";
+import { resolveTimelineIdForSelection, type RightPanelTab } from "../utils/studioHelpers";
 import {
   domEditSelectionsTargetSame,
   domEditSelectionInGroup,
@@ -24,6 +20,7 @@ import {
   type DomEditSelection,
 } from "../components/editor/domEditing";
 import { reapplyPositionEditsAfterSeek } from "../components/editor/manualEdits";
+import { usePlayerStore } from "../player/store/playerStore";
 
 // ── Types ──
 
@@ -95,7 +92,6 @@ export interface UseDomSelectionReturn {
   ) => Promise<DomEditSelection | null>;
   handleTimelineElementSelect: (element: TimelineElement | null) => Promise<void>;
   refreshDomEditSelectionFromPreview: (selection: DomEditSelection) => Promise<void>;
-  refreshDomEditGroupSelectionsFromPreview: (selections: DomEditSelection[]) => Promise<void>;
   applyMarqueeSelection: (selections: DomEditSelection[], additive: boolean) => void;
 }
 
@@ -126,11 +122,16 @@ export function useDomSelection({
 
   // ── Refs ──
 
+  const rightPanelTabRef = useRef(rightPanelTab);
+  rightPanelTabRef.current = rightPanelTab;
   const domEditSelectionRef = useRef<DomEditSelection | null>(domEditSelection);
   const domEditGroupSelectionsRef = useRef<DomEditSelection[]>(domEditGroupSelections);
   const domEditHoverSelectionRef = useRef<DomEditSelection | null>(domEditHoverSelection);
   const activeGroupElementRef = useRef<HTMLElement | null>(activeGroupElement);
   const compositionIdentityRef = useRef({ activeCompPath, projectId });
+  // Monotonic token so a rapid A->B timeline-clip select can't let A's slower async
+  // resolution land after B and restore the wrong selection.
+  const timelineSelectSeqRef = useRef(0);
 
   // Keep refs in sync with state
   domEditSelectionRef.current = domEditSelection;
@@ -205,22 +206,42 @@ export function useDomSelection({
       if (nextSelection) {
         if (options?.revealPanel !== false) {
           setRightCollapsed(false);
-          setRightPanelTab("design");
+          // Keep the Variables tab in place — selecting elements is part of
+          // the bind flow there; yanking to Design would lose the context.
+          if (rightPanelTabRef.current !== "variables") {
+            setRightPanelTab("design");
+          }
+        }
+        // Mirror the whole DOM group to the store so it stays the single source of
+        // truth: a single selection collapses to one id; a preserved group (echo
+        // during a gesture) keeps every member instead of shrinking to the anchor.
+        const anchorId = resolveTimelineIdForSelection(
+          nextSelection,
+          timelineElements,
+          activeCompPath,
+        );
+        const groupIds = nextGroup
+          .map((selection) =>
+            resolveTimelineIdForSelection(selection, timelineElements, activeCompPath),
+          )
+          .filter((id): id is string => Boolean(id));
+        if (groupIds.length > 0) {
+          usePlayerStore.getState().setSelection(groupIds, anchorId);
+        } else {
+          setSelectedTimelineElementId(anchorId);
         }
-        const nextSelectedTimelineId =
-          findMatchingTimelineElementId(nextSelection, timelineElements) ??
-          findTimelineIdByAncestor(
-            nextSelection.element,
-            timelineElements,
-            nextSelection.sourceFile || "index.html",
-          );
-        setSelectedTimelineElementId(nextSelectedTimelineId);
         return;
       }
 
       setSelectedTimelineElementId(null);
     },
-    [setSelectedTimelineElementId, timelineElements, setRightCollapsed, setRightPanelTab],
+    [
+      setSelectedTimelineElementId,
+      timelineElements,
+      setRightCollapsed,
+      setRightPanelTab,
+      activeCompPath,
+    ],
   );
 
   const clearDomSelection = useCallback(() => {
@@ -360,12 +381,15 @@ export function useDomSelection({
   const handleTimelineElementSelect = useCallback(
     async (element: TimelineElement | null) => {
       if (!STUDIO_INSPECTOR_PANELS_ENABLED) return;
+      const seq = ++timelineSelectSeqRef.current;
       if (!element) {
         applyDomSelection(null, { revealPanel: false });
         return;
       }
 
       const selection = await buildDomSelectionForTimelineElement(element);
+      // A newer selection superseded this one while we were resolving — drop the stale result.
+      if (seq !== timelineSelectSeqRef.current) return;
       if (selection) applyDomSelection(selection);
     },
     [applyDomSelection, buildDomSelectionForTimelineElement],
@@ -400,55 +424,6 @@ export function useDomSelection({
     [activeCompPath, applyDomSelection, buildDomSelectionFromTarget, previewIframeRef],
   );
 
-  const refreshDomEditGroupSelectionsFromPreview = useCallback(
-    // fallow-ignore-next-line complexity
-    async (selections: DomEditSelection[]) => {
-      const iframe = previewIframeRef.current;
-      let doc: Document | null = null;
-      try {
-        doc = iframe?.contentDocument ?? null;
-      } catch {
-        return;
-      }
-      if (!doc) return;
-
-      const nextGroup: DomEditSelection[] = [];
-      for (const selection of selections) {
-        const element = findElementForSelection(doc, selection, activeCompPath);
-        if (!element) continue;
-        const nextSelection = await buildDomSelectionFromTarget(element);
-        if (nextSelection) nextGroup.push(nextSelection);
-      }
-      if (nextGroup.length === 0) return;
-
-      const currentSelection = domEditSelectionRef.current;
-      const nextSelection =
-        nextGroup.find((selection) => domEditSelectionsTargetSame(selection, currentSelection)) ??
-        nextGroup[0] ??
-        null;
-
-      domEditSelectionRef.current = nextSelection;
-      domEditGroupSelectionsRef.current = nextGroup;
-      setDomEditSelection(nextSelection);
-      setDomEditGroupSelections(nextGroup);
-
-      if (nextSelection) {
-        setSelectedTimelineElementId(
-          findMatchingTimelineElementId(nextSelection, timelineElements),
-        );
-      } else {
-        setSelectedTimelineElementId(null);
-      }
-    },
-    [
-      activeCompPath,
-      buildDomSelectionFromTarget,
-      setSelectedTimelineElementId,
-      timelineElements,
-      previewIframeRef,
-    ],
-  );
-
   // ── Effects ──
 
   // Clear hover unconditionally on composition/project/preview change
@@ -530,16 +505,23 @@ export function useDomSelection({
       domEditGroupSelectionsRef.current = nextGroup;
       setDomEditSelection(nextSelection);
       setDomEditGroupSelections(nextGroup);
-      const nextTimelineId =
-        findMatchingTimelineElementId(nextSelection, timelineElements) ??
-        findTimelineIdByAncestor(
-          nextSelection.element,
-          timelineElements,
-          nextSelection.sourceFile || "index.html",
-        );
-      setSelectedTimelineElementId(nextTimelineId);
+      const nextTimelineId = resolveTimelineIdForSelection(
+        nextSelection,
+        timelineElements,
+        activeCompPath,
+      );
+      const nextTimelineIds = nextGroup
+        .map((selection) =>
+          resolveTimelineIdForSelection(selection, timelineElements, activeCompPath),
+        )
+        .filter((id): id is string => Boolean(id));
+      if (nextTimelineIds.length > 0) {
+        usePlayerStore.getState().setSelection(nextTimelineIds, nextTimelineId);
+      } else {
+        setSelectedTimelineElementId(null);
+      }
     },
-    [applyDomSelection, timelineElements, setSelectedTimelineElementId],
+    [applyDomSelection, timelineElements, setSelectedTimelineElementId, activeCompPath],
   );
 
   // Disabled inspector effect
@@ -576,7 +558,6 @@ export function useDomSelection({
     buildDomSelectionForTimelineElement,
     handleTimelineElementSelect,
     refreshDomEditSelectionFromPreview,
-    refreshDomEditGroupSelectionsFromPreview,
     applyMarqueeSelection,
   };
 }

package/src/hooks/useElementLifecycleOps.ts

@@ -160,6 +160,7 @@ export function useElementLifecycleOps({
   // persistDomEditOperations → onTrySdkPersist, so it is already SDK-cut-over as setStyle.
   // No SDK reorder/reparent op exists; DOM sibling order stays server-authoritative if ever needed.
   const handleDomZIndexReorderCommit = useCallback(
+    // fallow-ignore-next-line complexity
     (
       entries: Array<{
         element: HTMLElement;
@@ -168,17 +169,26 @@ export function useElementLifecycleOps({
         selector?: string;
         selectorIndex?: number;
         sourceFile: string;
+        key?: string;
       }>,
     ) => {
-      if (entries.length === 0) return;
+      if (entries.length === 0) return Promise.resolve();
       // Resolver shadow (telemetry-only, decoupled from cutover): record whether
       // the SDK resolves each reordered element — the reorderElements op's targets.
       onReorderShadow?.(
         entries.map((e) => readHfId(e.element)).filter((id): id is string => id != null),
       );
       const coalesceKey = `z-reorder:${entries.map((e) => e.id ?? e.selector ?? e.element.getAttribute("data-hf-id") ?? "el").join(":")}`;
+      const saves: Array<Promise<void>> = [];
+      const rollbacks: Array<() => void> = [];
       for (let i = 0; i < entries.length; i++) {
         const entry = entries[i];
+        const priorZIndex = entry.element.style.zIndex;
+        const priorPosition = entry.element.style.position;
+        const priorStoreEntry = entry.key
+          ? usePlayerStore.getState().elements.find((el) => (el.key ?? el.id) === entry.key)
+          : undefined;
+        let positionChanged = false;
         entry.element.style.zIndex = String(entry.zIndex);
         const patches: Array<{ type: "inline-style"; property: string; value: string }> = [
           { type: "inline-style", property: "z-index", value: String(entry.zIndex) },
@@ -187,28 +197,58 @@ export function useElementLifecycleOps({
           const win = entry.element.ownerDocument?.defaultView;
           if (win && win.getComputedStyle(entry.element).position === "static") {
             entry.element.style.position = "relative";
+            positionChanged = true;
             patches.push({ type: "inline-style", property: "position", value: "relative" });
           }
         } catch {
           /* cross-origin or detached — skip */
         }
-        void commitPositionPatchToHtml(
-          {
-            element: entry.element,
-            id: entry.id ?? null,
-            hfId: readHfId(entry.element),
-            selector: entry.selector,
-            selectorIndex: entry.selectorIndex,
-            sourceFile: entry.sourceFile,
-          } as unknown as DomEditSelection,
-          patches,
-          {
-            label: "Reorder layers",
-            coalesceKey,
-            skipRefresh: i < entries.length - 1,
-          },
-        ).catch(() => undefined);
+        if (entry.key) {
+          usePlayerStore
+            .getState()
+            .updateElement(entry.key, { zIndex: entry.zIndex, hasExplicitZIndex: true });
+        }
+        rollbacks.push(() => {
+          entry.element.style.zIndex = priorZIndex;
+          if (positionChanged) entry.element.style.position = priorPosition;
+          if (entry.key && priorStoreEntry) {
+            usePlayerStore.getState().updateElement(entry.key, {
+              zIndex: priorStoreEntry.zIndex,
+              hasExplicitZIndex: priorStoreEntry.hasExplicitZIndex,
+            });
+          }
+        });
+        saves.push(
+          commitPositionPatchToHtml(
+            {
+              element: entry.element,
+              id: entry.id ?? null,
+              hfId: readHfId(entry.element),
+              selector: entry.selector,
+              selectorIndex: entry.selectorIndex,
+              sourceFile: entry.sourceFile,
+            } as unknown as DomEditSelection,
+            patches,
+            {
+              label: "Reorder layers",
+              coalesceKey,
+              skipRefresh: i < entries.length - 1,
+            },
+          ),
+        );
       }
+      // Resolves once every z-index patch is persisted so a same-file timing write
+      // can be ordered after it (see applyTimelineStackingReorder callers).
+      return Promise.allSettled(saves).then((settled) => {
+        const rejected = settled.find(
+          (result): result is PromiseRejectedResult => result.status === "rejected",
+        );
+        if (rejected) {
+          for (const rollback of rollbacks) rollback();
+          return Promise.reject(rejected.reason);
+        }
+        return undefined;
+      });
     },
     [commitPositionPatchToHtml, onReorderShadow],
   );

package/src/hooks/usePreviewDocumentVersion.ts

@@ -0,0 +1,27 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+/**
+ * Version counter for the preview DOM. `refresh` bumps immediately and again
+ * at 80ms / 300ms so consumers re-scan after the iframe settles; pending
+ * timers are collapsed by each new refresh and cleared on unmount.
+ */
+export function usePreviewDocumentVersion(): [number, () => void] {
+  const [previewDocumentVersion, setPreviewDocumentVersion] = useState(0);
+  const refreshTimersRef = useRef<number[]>([]);
+  const refresh = useCallback(() => {
+    for (const id of refreshTimersRef.current) clearTimeout(id);
+    refreshTimersRef.current = [];
+    setPreviewDocumentVersion((v) => v + 1);
+    refreshTimersRef.current.push(
+      window.setTimeout(() => setPreviewDocumentVersion((v) => v + 1), 80),
+      window.setTimeout(() => setPreviewDocumentVersion((v) => v + 1), 300),
+    );
+  }, []);
+  useEffect(
+    () => () => {
+      for (const id of refreshTimersRef.current) clearTimeout(id);
+    },
+    [],
+  );
+  return [previewDocumentVersion, refresh];
+}

package/src/hooks/useProjectCompositionVariables.ts

@@ -0,0 +1,131 @@
+import { useCallback, useEffect, useState, type MutableRefObject } from "react";
+import { openComposition, type Composition, type CompositionVariable } from "@hyperframes/sdk";
+import { persistSdkSerialize } from "../utils/sdkCutover";
+import type { EditHistoryKind } from "../utils/editHistory";
+
+/** Records an edit into the studio's undo history (label + kind + per-file before/after). */
+export type RecordEditFn = (entry: {
+  label: string;
+  kind: EditHistoryKind;
+  files: Record<string, { before: string; after: string }>;
+}) => Promise<void>;
+
+export interface CompositionVariableGroup {
+  /** Project-relative file path, e.g. "compositions/frames/02-problem.html". */
+  path: string;
+  /** The composition's variable declarations (empty groups are dropped by the hook). */
+  variables: CompositionVariable[];
+}
+
+/** Read one composition file's declarations, or null to skip (unreadable / none / unparseable). */
+// fallow-ignore-next-line complexity
+async function readGroup(
+  path: string,
+  readProjectFile: (path: string) => Promise<string>,
+): Promise<CompositionVariableGroup | null> {
+  let content: string;
+  try {
+    content = await readProjectFile(path);
+  } catch {
+    return null;
+  }
+  if (!content.includes("data-composition-variables")) return null;
+  try {
+    const comp = await openComposition(content, { history: false });
+    try {
+      const variables = comp.getVariableDeclarations();
+      return variables.length > 0 ? { path, variables } : null;
+    } finally {
+      comp.dispose();
+    }
+  } catch {
+    return null; // Unparseable composition — skip rather than break the whole panel.
+  }
+}
+
+/**
+ * Read variable declarations from every composition file in the project except
+ * `excludePath` (the active composition, which the panel renders with its full
+ * preview/add controls). Powers the Variables tab's "other compositions"
+ * sections so a variable promoted into a sub-comp file is visible alongside the
+ * host's own. Re-reads whenever `refreshKey` changes (after an edit or preview
+ * reload). A cheap substring guard skips files with no declarations before the
+ * full parse, so large projects don't pay N openComposition calls.
+ */
+export function useProjectCompositionVariables(
+  fileTree: string[],
+  excludePath: string | null,
+  readProjectFile: (path: string) => Promise<string>,
+  refreshKey: unknown,
+): CompositionVariableGroup[] {
+  const [groups, setGroups] = useState<CompositionVariableGroup[]>([]);
+
+  useEffect(() => {
+    let cancelled = false;
+    const htmlFiles = fileTree.filter((p) => p.endsWith(".html") && p !== excludePath);
+
+    void (async () => {
+      const out: CompositionVariableGroup[] = [];
+      for (const path of htmlFiles) {
+        const group = await readGroup(path, readProjectFile);
+        if (group) out.push(group);
+      }
+      if (!cancelled) setGroups(out);
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [fileTree, excludePath, readProjectFile, refreshKey]);
+
+  return groups;
+}
+
+interface EditVariablesDeps {
+  readProjectFile: (path: string) => Promise<string>;
+  writeProjectFile: (path: string, content: string) => Promise<void>;
+  recordEdit: RecordEditFn;
+  reloadPreview: () => void;
+  domEditSaveTimestampRef: MutableRefObject<number>;
+}
+
+/**
+ * Apply a variable-schema mutation to an arbitrary composition file (a sub-comp
+ * that isn't the active SDK session) and persist it through the standard
+ * single-writer path. Opens a throwaway session on the file, runs `mutate`,
+ * and writes the serialized result — the same contract as useVariablesPersist,
+ * but keyed on `path` rather than a live session.
+ */
+export function useEditVariablesInFile(deps: EditVariablesDeps) {
+  const { readProjectFile, writeProjectFile, recordEdit, reloadPreview, domEditSaveTimestampRef } =
+    deps;
+  return useCallback(
+    async (path: string, label: string, mutate: (session: Composition) => void): Promise<void> => {
+      const originalContent = await readProjectFile(path);
+      const comp = await openComposition(originalContent, { history: false });
+      let after: string;
+      try {
+        mutate(comp);
+        after = comp.serialize();
+      } finally {
+        comp.dispose();
+      }
+      if (after === originalContent) return;
+      await persistSdkSerialize(
+        after,
+        path,
+        originalContent,
+        {
+          editHistory: { recordEdit },
+          writeProjectFile,
+          reloadPreview,
+          domEditSaveTimestampRef,
+          compositionPath: path,
+        },
+        { label },
+      );
+    },
+    [readProjectFile, writeProjectFile, recordEdit, reloadPreview, domEditSaveTimestampRef],
+  );
+}

package/src/hooks/useStudioContextValue.ts

@@ -97,7 +97,12 @@ export function useInspectorState(
         STUDIO_INSPECTOR_PANELS_ENABLED && !rightCollapsed && inspectorPanelActive,
       // 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,
+      // The Variables tab also works against the canvas selection (bind card),
+      // so the selection outline stays visible there too.
+      shouldShowSelectedDomBounds:
+        (inspectorPanelActive || rightPanelTab === "variables") &&
+        !isPlaying &&
+        !isGestureRecording,
     };
   }, [rightPanelTab, rightInspectorPanes, rightCollapsed, isPlaying, isGestureRecording]);
 }

package/src/hooks/useStudioSdkSessions.ts

@@ -0,0 +1,37 @@
+import { useEffect, type MutableRefObject } from "react";
+import { useSdkSession } from "./useSdkSession";
+import { usePreviewVariablesStore } from "./previewVariablesStore";
+
+/**
+ * Open the studio's SDK session with master-view semantics.
+ *
+ * The master view has no explicit comp path, but the session must still model
+ * the project's main composition so schema-level panels (Variables, Slideshow)
+ * work there. Edit-flow consumers keep the legacy "no session on master view"
+ * gating via `editFlowSdkSession` so cutover behavior is unchanged.
+ *
+ * Also clears preview variable overrides whenever the composition or project
+ * changes — overrides are per-composition and must never leak into another
+ * composition's preview or render.
+ */
+export function useStudioSdkSessions(
+  projectId: string | null,
+  activeCompPath: string | null,
+  domEditSaveTimestampRef: MutableRefObject<number>,
+  masterCompPath: string | null,
+) {
+  // On the master view (no explicit comp) the schema panels target the project's
+  // resolved main composition — the first `.html` in the tree, not a hardcoded
+  // "index.html" that may not exist. `null` when the project has no composition
+  // yet, which correctly leaves the session (and the panels) empty.
+  const sdkHandle = useSdkSession(
+    projectId,
+    activeCompPath ?? masterCompPath,
+    domEditSaveTimestampRef,
+  );
+  const editFlowSdkSession = activeCompPath ? sdkHandle.session : null;
+  useEffect(() => {
+    usePreviewVariablesStore.getState().setValues(null);
+  }, [projectId, activeCompPath]);
+  return { sdkHandle, editFlowSdkSession };
+}