@hyperframes/studio 0.7.57 → 0.7.58

package/src/player/lib/timelineDOM.ts

@@ -10,6 +10,7 @@
 
 import type { TimelineElement } from "../store/playerStore";
 import type { ClipManifestClip } from "./playbackTypes";
+import { resolveCssStackingContextId } from "@hyperframes/core/runtime/stacking-context";
 import {
   resolveMediaElement,
   applyMediaMetadataFromElement,
@@ -228,6 +229,7 @@ export function createImplicitTimelineLayersFromDOM(
       selector,
       selectorIndex,
       sourceFile,
+      stackingContextId: resolveCssStackingContextId(child),
       start: 0,
       tag: child.tagName.toLowerCase(),
       timingSource: "implicit",
@@ -303,6 +305,7 @@ export function parseTimelineFromDOM(doc: Document, rootDuration: number): Timel
       selector,
       selectorIndex,
       sourceFile,
+      stackingContextId: resolveCssStackingContextId(el),
       timingSource: "authored",
       zIndex: readTimelineElementZIndex(el),
     };

package/src/player/lib/timelineElementHelpers.ts

@@ -10,6 +10,31 @@
 import type { TimelineElement } from "../store/playerStore";
 import type { ClipManifestClip } from "./playbackTypes";
 import { isFinitePositive } from "./playbackAdapter";
+import { getSourceScopedSelectorIndex } from "../../utils/sourceScopedSelectorIndex";
+
+// ---------------------------------------------------------------------------
+// Layer-reveal lift transparency
+// ---------------------------------------------------------------------------
+
+/**
+ * Attributes carrying the pre-lift state of a Layers-panel selection reveal
+ * (useLayerRevealOverride): while a layer is selected it PAINTS on top via a
+ * temporary inline z-index, but the lift is a purely visual, ephemeral studio
+ * affordance — every z reader must keep reporting the element's TRUE z
+ * (stored here) so menus, badges, the lane mirror, and the panel sort never
+ * reason on the lifted value. A z-reorder commit removes the attributes (the
+ * commit is the new truth).
+ */
+export const LAYER_REVEAL_PRIOR_Z_ATTR = "data-hf-reveal-prior-z";
+export const LAYER_REVEAL_PRIOR_POSITION_ATTR = "data-hf-reveal-prior-pos";
+
+/** The lifted element's true (pre-lift) z, or null when no lift is active. */
+export function readLayerRevealPriorZ(el: Element): number | null {
+  const raw = el.getAttribute(LAYER_REVEAL_PRIOR_Z_ATTR);
+  if (raw == null) return null;
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) ? n : null;
+}
 
 // ---------------------------------------------------------------------------
 // Duration attribute helpers
@@ -22,8 +47,11 @@ import { isFinitePositive } from "./playbackAdapter";
  * back to computed style; "auto" / empty / unparseable ⇒ 0. Works with a
  * detached parse Document (no defaultView) as well as a live iframe. Mirrors
  * canvasContextMenuZOrder.parseZIndex semantics so the two directions agree.
+ * Reveal-lift transparent: an active lift reports the stored TRUE z.
  */
 export function readTimelineElementZIndex(el: Element): number {
+  const prior = readLayerRevealPriorZ(el);
+  if (prior != null) return prior;
   const html = el as HTMLElement;
   const parseZ = (value: string | null | undefined): number | null => {
     if (value == null || value === "" || value === "auto") return null;
@@ -237,17 +265,13 @@ export function getTimelineElementSelectorIndex(
   el: Element,
   selector: string | undefined,
 ): number | undefined {
-  if (!selector || selector.startsWith("#") || selector.startsWith("[data-composition-id=")) {
-    return undefined;
-  }
-
-  try {
-    const matches = Array.from(doc.querySelectorAll(selector));
-    const matchIndex = matches.indexOf(el);
-    return matchIndex >= 0 ? matchIndex : undefined;
-  } catch {
-    return undefined;
-  }
+  return getSourceScopedSelectorIndex(
+    doc,
+    el,
+    selector,
+    getTimelineElementSourceFile(el),
+    getTimelineElementSourceFile,
+  );
 }
 
 export function buildTimelineElementKey(params: {

package/src/player/store/playerStore.ts

@@ -44,7 +44,7 @@ export interface TimelineElement {
   zIndex?: number;
   /** True when the effective z-index was authored inline or through CSS, not auto. */
   hasExplicitZIndex?: boolean;
-  /** Stacking context this element belongs to; root clips use the root composition id. */
+  /** Canonical CSS stacking context this element's z-index participates in. */
   stackingContextId?: string | null;
   /** Nearest parent composition context, matching RuntimeTimelineClip. */
   parentCompositionId?: string | null;
@@ -124,6 +124,13 @@ interface PlayerState {
   zoomMode: ZoomMode;
   /** Timeline zoom percent relative to the fit width when in manual mode */
   manualZoomPercent: number;
+  /**
+   * Bumped on every live z-index edit (handleDomZIndexReorderCommit apply AND
+   * rollback). Flashless z commits (skipReload) never reload the iframe or
+   * bump refreshKey, so DOM-derived views (the Layers panel's z-sorted tree)
+   * subscribe to this to re-read the live DOM while playback is paused.
+   */
+  zEditVersion: number;
   /** Work-area in-point (seconds). When set, loop starts here and A jumps here. */
   inPoint: number | null;
   /** Work-area out-point (seconds). When set, loop ends here and E jumps here. */
@@ -212,6 +219,7 @@ interface PlayerState {
   ) => void;
   setZoomMode: (mode: ZoomMode) => void;
   setManualZoomPercent: (percent: number) => void;
+  bumpZEditVersion: () => void;
   setInPoint: (time: number | null) => void;
   setOutPoint: (time: number | null) => void;
   reset: () => void;
@@ -274,6 +282,7 @@ export interface DomClipChild {
   /** The manifest sub-comp host clip id this descendant ultimately lives under. */
   hostId: string;
   label: string;
+  stackingContextId: string;
 }
 
 interface BeatHistoryEntry {
@@ -308,6 +317,7 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
   loopEnabled: false,
   zoomMode: "fit",
   manualZoomPercent: 100,
+  zEditVersion: 0,
   timelinePps: 100,
   timelineFitPps: 100,
   inPoint: null,
@@ -494,6 +504,7 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
     }),
   setManualZoomPercent: (percent) =>
     set({ manualZoomPercent: Math.max(10, Math.min(2000, Math.round(percent))) }),
+  bumpZEditVersion: () => set((state) => ({ zEditVersion: state.zEditVersion + 1 })),
   setCurrentTime: (time) => set({ currentTime: Number.isFinite(time) ? time : 0 }),
   setDuration: (duration) => set({ duration: Number.isFinite(duration) ? duration : 0 }),
   setTimelineReady: (ready) => set({ timelineReady: ready }),

package/src/telemetry/events.test.ts

@@ -12,6 +12,7 @@ const {
   trackStudioRenderStart,
   trackStudioRazorSplit,
   trackStudioExpandedClipEdit,
+  trackStudioFeedback,
 } = await import("./events");
 
 describe("studio telemetry events", () => {
@@ -69,4 +70,13 @@ describe("studio telemetry events", () => {
     trackStudioExpandedClipEdit({ action: "resize" });
     expect(trackEvent).toHaveBeenCalledWith("studio_expanded_clip_edit", { action: "resize" });
   });
+
+  it.each([0, 10])("trackStudioFeedback preserves NPS boundary %i and its scale", (rating) => {
+    trackStudioFeedback({ rating });
+
+    expect(trackEvent).toHaveBeenCalledWith(
+      "survey sent",
+      expect.objectContaining({ $survey_response: rating, rating_scale: 10 }),
+    );
+  });
 });

package/src/telemetry/events.ts

@@ -67,6 +67,7 @@ export function trackStudioFeedback(props: { rating: number; comment?: string })
   trackEvent("survey sent", {
     $survey_id: "studio_experience",
     $survey_response: props.rating,
+    rating_scale: 10,
     ...(props.comment ? { $survey_response_2: props.comment } : {}),
     doctor_summary: getBrowserDoctorSummary(),
     source: "studio",

package/src/utils/domEditSaveQueue.ts

@@ -13,7 +13,7 @@ interface DomEditSaveQueueOptions {
 }
 
 export interface DomEditSaveQueue {
-  enqueue: (save: () => Promise<void>) => Promise<void>;
+  enqueue: <T>(save: () => Promise<T>) => Promise<T>;
   waitForIdle: () => Promise<void>;
   reset: () => void;
   destroy: () => void;
@@ -52,10 +52,11 @@ export function createDomEditSaveQueue(options: DomEditSaveQueueOptions = {}): D
     });
   };
 
-  const run = async (save: () => Promise<void>) => {
+  const run = async <T>(save: () => Promise<T>): Promise<T> => {
     try {
-      await save();
+      const result = await save();
       if (!breakerOpen) consecutiveFailures = 0;
+      return result;
     } catch (error) {
       consecutiveFailures += 1;
       if (consecutiveFailures >= failureThreshold) open(error);

package/src/utils/editHistory.test.ts

@@ -277,6 +277,88 @@ describe("edit history", () => {
     expect(state.undo[0].files["index.html"].after).toBe("timing+gsap");
   });
 
+  it("keeps timing-only files when a multi-file GSAP follow-up touches one path", () => {
+    const timing = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Move timeline clips",
+      kind: "timeline",
+      coalesceKey: "timeline-group-move:a,b",
+      files: {
+        "index.html": { before: "index-before", after: "index-timing" },
+        "scene.html": { before: "scene-before", after: "scene-timing" },
+      },
+      now: 0,
+      id: "timing",
+    });
+    const gsap = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Move timeline clips",
+      kind: "timeline",
+      coalesceKey: "timeline-group-move:a,b",
+      coalesceMs: 10_000,
+      files: {
+        "index.html": { before: "index-timing", after: "index-timing+gsap" },
+      },
+      now: 2000,
+      id: "gsap",
+    });
+
+    const state = pushEditHistoryEntry(
+      pushEditHistoryEntry(createEmptyEditHistory(), timing),
+      gsap,
+    );
+
+    expect(state.undo).toHaveLength(1);
+    expect(Object.keys(state.undo[0].files)).toEqual(["index.html", "scene.html"]);
+    expect(state.undo[0].files).toMatchObject({
+      "index.html": { before: "index-before", after: "index-timing+gsap" },
+      "scene.html": { before: "scene-before", after: "scene-timing" },
+    });
+  });
+
+  it("keeps a discontinuous GSAP follow-up separate and preserves foreign bytes on undo", () => {
+    const timing = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Move timeline clip",
+      kind: "timeline",
+      coalesceKey: "timeline-move:clip",
+      files: { "index.html": { before: "A", after: "B" } },
+      now: 0,
+      id: "timing",
+    });
+    const gsapAfterForeignWrite = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Move timeline clip",
+      kind: "timeline",
+      coalesceKey: "timeline-move:clip",
+      coalesceMs: 10_000,
+      files: { "index.html": { before: "F", after: "G" } },
+      now: 2000,
+      id: "gsap",
+    });
+
+    const state = pushEditHistoryEntry(
+      pushEditHistoryEntry(createEmptyEditHistory(), timing),
+      gsapAfterForeignWrite,
+    );
+
+    expect(state.undo.map((entry) => entry.id)).toEqual(["timing", "gsap"]);
+    const undoGsap = undoEditHistory(state, { "index.html": hashEditHistoryContent("G") }, 3000);
+    expect(undoGsap.ok).toBe(true);
+    expect(undoGsap.filesToWrite).toEqual({ "index.html": "F" });
+
+    const undoTiming = undoEditHistory(
+      undoGsap.state,
+      { "index.html": hashEditHistoryContent("F") },
+      4000,
+    );
+    expect(undoTiming).toMatchObject({
+      ok: false,
+      reason: "content-mismatch",
+      filesToWrite: {},
+    });
+  });
+
   it("does not merge a slow follow-up without the coalesceMs override", () => {
     const timing = buildEditHistoryEntry({
       projectId: "project-1",

package/src/utils/editHistory.ts

@@ -126,9 +126,21 @@ export function pushEditHistoryEntry(
     previous &&
     previous.coalesceKey &&
     previous.coalesceKey === entry.coalesceKey &&
-    entry.createdAt - previous.createdAt <= coalesceMs
+    entry.createdAt - previous.createdAt <= coalesceMs &&
+    // A shared key/window is not enough: bytes from an external writer may
+    // have landed between the two Studio-owned edits. Only fold a path when
+    // the follow-up starts from the exact output the previous entry recorded.
+    // Otherwise keep both entries so undo restores the foreign bytes first and
+    // the older entry's content check safely blocks at that ownership boundary.
+    Object.entries(entry.files).every(([path, snapshot]) => {
+      const previousSnapshot = previous.files[path];
+      return !previousSnapshot || previousSnapshot.after === snapshot.before;
+    })
   ) {
-    const files: Record<string, EditHistoryFileSnapshot> = {};
+    // A follow-up may touch only a subset of the files in the original edit
+    // (for example, only one file in a multi-file timing move has GSAP). Keep
+    // previous-only paths in the single coalesced undo entry.
+    const files: Record<string, EditHistoryFileSnapshot> = { ...previous.files };
     for (const [path, snapshot] of Object.entries(entry.files)) {
       const previousSnapshot = previous.files[path];
       files[path] = previousSnapshot

package/src/utils/gsapSoftReload.test.ts

@@ -3,9 +3,8 @@
 import { describe, it, expect, vi } from "vitest";
 import {
   applySoftReload,
+  applySoftReloadFinalization,
   ensureMotionPathPluginLoaded,
-  diffSoftReloadableRestore,
-  applyUndoRestoreToPreview,
 } from "./gsapSoftReload";
 
 const SCRIPT_TEXT = `
@@ -66,6 +65,7 @@ function buildMockIframe(overrides: Record<string, unknown> = {}) {
     iframe: { contentWindow, contentDocument } as unknown as HTMLIFrameElement,
     contentWindow,
     mockTimeline,
+    container,
   };
 }
 
@@ -288,6 +288,58 @@ describe("applySoftReload", () => {
   });
 });
 
+// ── Finalization-only path: seek → rebind → manual edits, with NO script
+// execution — the flashless sync for timing edits that changed no script.
+describe("applySoftReloadFinalization", () => {
+  it("seeks, rebinds, and reapplies manual edits without touching any script", () => {
+    const { iframe, contentWindow, container, mockTimeline } = buildMockIframe();
+    const scriptsBefore = container.querySelectorAll("script").length;
+
+    expect(applySoftReloadFinalization(iframe, 2.0)).toBe(true);
+
+    expect(contentWindow.__player.seek).toHaveBeenCalledWith(2.0);
+    expect(contentWindow.__hfForceTimelineRebind).toHaveBeenCalledTimes(1);
+    expect(contentWindow.__hfStudioManualEditsApply).toHaveBeenCalledTimes(1);
+    // No script executed or removed; the live timeline was never killed.
+    expect(container.querySelectorAll("script").length).toBe(scriptsBefore);
+    expect(mockTimeline.kill).not.toHaveBeenCalled();
+    expect(contentWindow.__timelines.root).toBe(mockTimeline);
+  });
+
+  it("runs inside __hfSuppressSceneMutations when the runtime provides it", () => {
+    const suppress = vi.fn(<T>(fn: () => T): T => fn());
+    const { iframe, contentWindow } = buildMockIframe({
+      __hfSuppressSceneMutations: suppress,
+    });
+
+    expect(applySoftReloadFinalization(iframe, 1.5)).toBe(true);
+
+    expect(suppress).toHaveBeenCalledTimes(1);
+    expect(contentWindow.__hfForceTimelineRebind).toHaveBeenCalledTimes(1);
+  });
+
+  it("does NOT require gsap — a script-less runtime with the rebind hook works", () => {
+    const { iframe, contentWindow } = buildMockIframe({ gsap: undefined });
+    expect(applySoftReloadFinalization(iframe, 0)).toBe(true);
+    expect(contentWindow.__hfForceTimelineRebind).toHaveBeenCalledTimes(1);
+  });
+
+  it("returns false when the iframe or the rebind hook is unavailable", () => {
+    expect(applySoftReloadFinalization(null, 0)).toBe(false);
+    const { iframe } = buildMockIframe({ __hfForceTimelineRebind: undefined });
+    expect(applySoftReloadFinalization(iframe, 0)).toBe(false);
+  });
+
+  it("returns false when the rebind throws (caller full-reloads)", () => {
+    const { iframe } = buildMockIframe({
+      __hfForceTimelineRebind: vi.fn(() => {
+        throw new Error("runtime mid-teardown");
+      }),
+    });
+    expect(applySoftReloadFinalization(iframe, 0)).toBe(false);
+  });
+});
+
 function buildBootstrapIframe(overrides: Record<string, unknown> = {}) {
   const head = document.createElement("div");
   const appendedScripts: HTMLScriptElement[] = [];
@@ -452,116 +504,3 @@ describe("applySoftReload authored-opacity restore", () => {
     expect(restoreOpacity(el)).toBe("");
   });
 });
-
-// ── Bug 2: undo/redo restore soft-apply ──────────────────────────────────────
-
-const wrap = (body: string) => `<html><body>${body}</body></html>`;
-
-describe("diffSoftReloadableRestore", () => {
-  it("reports the changed id for an attribute/inline-style-only diff", () => {
-    const prev = wrap(`<div id="a" style="translate: 10px 10px">t</div>`);
-    const next = wrap(`<div id="a" style="translate: 0px 0px">t</div>`);
-    expect(diffSoftReloadableRestore(prev, next)).toEqual({ changedElementIds: ["a"] });
-  });
-
-  it("treats a structural change (added element) as NOT soft-reloadable", () => {
-    const prev = wrap(`<div id="a">t</div>`);
-    const next = wrap(`<div id="a">t</div><div id="a-split">t</div>`);
-    expect(diffSoftReloadableRestore(prev, next)).toBeNull();
-  });
-
-  it("treats an element text/child change as NOT soft-reloadable", () => {
-    const prev = wrap(`<div id="a">one</div>`);
-    const next = wrap(`<div id="a">two</div>`);
-    expect(diffSoftReloadableRestore(prev, next)).toBeNull();
-  });
-
-  it("allows a GSAP-script-only change (no id'd-attribute diff)", () => {
-    const prev = wrap(
-      `<div id="a">t</div><script>window.__timelines["root"]=gsap.timeline().to("#a",{x:1});</script>`,
-    );
-    const next = wrap(
-      `<div id="a">t</div><script>window.__timelines["root"]=gsap.timeline().to("#a",{x:9});</script>`,
-    );
-    expect(diffSoftReloadableRestore(prev, next)).toEqual({ changedElementIds: [] });
-  });
-});
-
-function buildLiveIframe(bodyHtml: string) {
-  const doc = document.implementation.createHTMLDocument("");
-  doc.body.innerHTML = bodyHtml;
-  const contentWindow = {
-    gsap: { timeline: () => {} },
-    __hfForceTimelineRebind: () => {},
-    __timelines: {} as Record<string, unknown>,
-    __player: { getTime: () => 3, seek: vi.fn() },
-    __hfStudioManualEditsApply: vi.fn(),
-  };
-  return {
-    iframe: { contentWindow, contentDocument: doc } as unknown as HTMLIFrameElement,
-    contentWindow,
-    doc,
-  };
-}
-
-describe("applyUndoRestoreToPreview", () => {
-  const ROOT = "index.html";
-
-  it("soft-applies an attribute/style-only restore: syncs the live element, no full reload", () => {
-    const { iframe, contentWindow, doc } = buildLiveIframe(
-      `<div id="a" style="translate: 10px 10px" data-hf-path-offset="true">t</div>`,
-    );
-    const reloadPreview = vi.fn();
-    const files = {
-      [ROOT]: {
-        previous: wrap(
-          `<div id="a" style="translate: 10px 10px" data-hf-path-offset="true">t</div>`,
-        ),
-        restored: wrap(`<div id="a" style="translate: 0px 0px" data-hf-path-offset="true">t</div>`),
-      },
-    };
-    const outcome = applyUndoRestoreToPreview(iframe, ROOT, files, 3, reloadPreview);
-    expect(outcome).toBe("soft");
-    expect(reloadPreview).not.toHaveBeenCalled();
-    // Live element reverted to the restored inline style.
-    expect(doc.getElementById("a")!.getAttribute("style")).toBe("translate: 0px 0px");
-    // No GSAP script in the restore → the manual-edit reapply runs, playhead held.
-    expect(contentWindow.__player.seek).toHaveBeenCalledWith(3);
-    expect(contentWindow.__hfStudioManualEditsApply).toHaveBeenCalled();
-  });
-
-  it("full-reloads a multi-file restore", () => {
-    const { iframe } = buildLiveIframe(`<div id="a">t</div>`);
-    const reloadPreview = vi.fn();
-    const files = {
-      [ROOT]: {
-        previous: wrap(`<div id="a" style="x">t</div>`),
-        restored: wrap(`<div id="a">t</div>`),
-      },
-      "scenes/intro.html": { previous: "a", restored: "b" },
-    };
-    expect(applyUndoRestoreToPreview(iframe, ROOT, files, 3, reloadPreview)).toBe("full");
-    expect(reloadPreview).toHaveBeenCalledTimes(1);
-  });
-
-  it("full-reloads a structural restore (split/delete undo)", () => {
-    const { iframe } = buildLiveIframe(`<div id="a">t</div><div id="a-split">t</div>`);
-    const reloadPreview = vi.fn();
-    const files = {
-      [ROOT]: {
-        previous: wrap(`<div id="a">t</div><div id="a-split">t</div>`),
-        restored: wrap(`<div id="a">t</div>`),
-      },
-    };
-    expect(applyUndoRestoreToPreview(iframe, ROOT, files, 3, reloadPreview)).toBe("full");
-    expect(reloadPreview).toHaveBeenCalledTimes(1);
-  });
-
-  it("full-reloads when the restore touches a sub-comp, not the active comp", () => {
-    const { iframe } = buildLiveIframe(`<div id="a">t</div>`);
-    const reloadPreview = vi.fn();
-    const files = { "scenes/intro.html": { previous: "a", restored: "b" } };
-    expect(applyUndoRestoreToPreview(iframe, ROOT, files, 3, reloadPreview)).toBe("full");
-    expect(reloadPreview).toHaveBeenCalledTimes(1);
-  });
-});