@hyperframes/studio 0.7.57 → 0.7.59

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/styles/studio.css

@@ -447,3 +447,25 @@ body {
     animation: none;
   }
 }
+
+/* Flat inspector group header/body entrance (FlatGroupHeader) */
+@keyframes hf-flat-group-in {
+  from {
+    opacity: 0;
+    transform: translateY(-4px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.hf-flat-group-enter {
+  animation: hf-flat-group-in 120ms ease-out;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .hf-flat-group-enter {
+    animation: none;
+  }
+}

package/src/styles/tailwind-preset.shared.js

@@ -12,11 +12,16 @@ const studioPreset = {
         },
         panel: {
           bg: "#0C0C0E",
+          // Open inspector-section body — slightly lighter than headers (bg)
+          // so the recessed scrollable region reads distinct.
+          "bg-inset": "#121214",
           input: "#161618",
           surface: "#18181B",
           hover: "#27272A",
           border: "#1E1E1E",
           "border-input": "#27272A",
+          hairline: "#1A1A1C",
+          "text-0": "#FAFAFA",
           "text-1": "#E4E4E7",
           "text-2": "#A1A1AA",
           "text-3": "#71717A",
@@ -24,6 +29,8 @@ const studioPreset = {
           "text-5": "#3F3F46",
           accent: "#3CE6AC",
           danger: "#EF4444",
+          media: "#00E3FF",
+          container: "#F5A623",
         },
       },
     },

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/designInputTracking.test.ts

@@ -0,0 +1,97 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const trackStudioEvent = vi.fn();
+vi.mock("./studioTelemetry", () => ({
+  trackStudioEvent: (...args: unknown[]) => trackStudioEvent(...args),
+}));
+
+import {
+  __resetDesignInputThrottle,
+  slugifyDesignInput,
+  trackDesignInput,
+} from "./designInputTracking";
+
+beforeEach(() => {
+  trackStudioEvent.mockReset();
+  __resetDesignInputThrottle();
+  vi.restoreAllMocks();
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("trackDesignInput", () => {
+  it("emits one design_input event with ui/section/control/name", () => {
+    trackDesignInput({ ui: "flat", section: "Style", control: "metric", name: "Opacity" });
+    expect(trackStudioEvent).toHaveBeenCalledTimes(1);
+    expect(trackStudioEvent).toHaveBeenCalledWith("design_input", {
+      ui: "flat",
+      section: "style",
+      control: "metric",
+      name: "opacity",
+    });
+  });
+
+  it("slugifies compound names and sections", () => {
+    trackDesignInput({
+      ui: "classic",
+      section: "Color Grading",
+      control: "slider",
+      name: "Font Size",
+    });
+    expect(trackStudioEvent).toHaveBeenCalledWith("design_input", {
+      ui: "classic",
+      section: "color-grading",
+      control: "slider",
+      name: "font-size",
+    });
+  });
+
+  it("marks an unresolved name as 'unnamed' (R3 coverage signal)", () => {
+    trackDesignInput({ ui: "classic", section: "style", control: "button", name: "" });
+    expect(trackStudioEvent).toHaveBeenCalledWith(
+      "design_input",
+      expect.objectContaining({ name: "unnamed" }),
+    );
+  });
+
+  it("coalesces repeated fires of the same input within the window (R4)", () => {
+    const nowSpy = vi.spyOn(performance, "now");
+    // Same key, three quick fires -> 1 event.
+    nowSpy.mockReturnValue(1000);
+    trackDesignInput({ ui: "flat", section: "style", control: "slider", name: "opacity" });
+    nowSpy.mockReturnValue(1100);
+    trackDesignInput({ ui: "flat", section: "style", control: "slider", name: "opacity" });
+    nowSpy.mockReturnValue(1500);
+    trackDesignInput({ ui: "flat", section: "style", control: "slider", name: "opacity" });
+    expect(trackStudioEvent).toHaveBeenCalledTimes(1);
+
+    // A different input within the window is NOT collapsed.
+    nowSpy.mockReturnValue(1550);
+    trackDesignInput({ ui: "flat", section: "style", control: "slider", name: "scale" });
+    expect(trackStudioEvent).toHaveBeenCalledTimes(2);
+
+    // Same input after the window fires again.
+    nowSpy.mockReturnValue(2200);
+    trackDesignInput({ ui: "flat", section: "style", control: "slider", name: "opacity" });
+    expect(trackStudioEvent).toHaveBeenCalledTimes(3);
+  });
+
+  it("never throws even if the underlying tracker throws", () => {
+    trackStudioEvent.mockImplementation(() => {
+      throw new Error("ingest down");
+    });
+    expect(() =>
+      trackDesignInput({ ui: "flat", section: "style", control: "metric", name: "opacity" }),
+    ).not.toThrow();
+  });
+});
+
+describe("slugifyDesignInput", () => {
+  it("lowercases, collapses non-alphanumerics, and trims dashes", () => {
+    expect(slugifyDesignInput("  Border Radius (px) ")).toBe("border-radius-px");
+    expect(slugifyDesignInput("X")).toBe("x");
+    expect(slugifyDesignInput("---")).toBe("");
+  });
+});

package/src/utils/designInputTracking.ts

@@ -0,0 +1,80 @@
+import { trackStudioEvent } from "./studioTelemetry";
+
+// Per-input usage telemetry for the design (inspector) panel. Both inspector UIs
+// (classic PropertyPanel, flat PropertyPanelFlat) funnel their inputs through this
+// one helper so usage can be ranked by input to find removal candidates. Emits the
+// batched `studio:design_input` event via trackStudioEvent (opt-out-aware, never-throw).
+//
+// Fire convention (kept consistent across both UIs):
+//   - Discrete controls (metric/text/select/segmented/toggle/color/button) fire only
+//     when a real committed value change happens (the commit site guards on
+//     next !== current).
+//   - Continuous controls (sliders, scrub) fire once per user interaction that
+//     produced commits, even if the net value ends unchanged — net-change-at-settle
+//     is unreliable for them because mid-drag commits have already advanced the value,
+//     so "did the user work this control" is the honest signal. The coalescing window
+//     below collapses the many mid-drag commits into that single event.
+
+export type DesignInputUi = "flat" | "classic";
+
+export interface DesignInputDescriptor {
+  ui: DesignInputUi;
+  /** Section slug the input lives under (e.g. "style", "color-grading"). */
+  section: string;
+  /** Control kind: "metric" | "slider" | "select" | "segmented" | "toggle" | "color" | "text" | "button" | … */
+  control: string;
+  /** Input identity — the field label or CSS/GSAP property. Slugified for stable ranking. */
+  name: string;
+}
+
+// Continuous controls (sliders, scrub, wheel-nudge, live-commit text) fire many
+// commits per interaction. Collapse repeated fires of the same input within this
+// window into one event so a single drag counts once (R4).
+const COALESCE_WINDOW_MS = 600;
+
+const lastFiredByKey = new Map<string, number>();
+
+function now(): number {
+  // performance.now() is monotonic and available in the studio runtime and jsdom.
+  return typeof performance !== "undefined" && typeof performance.now === "function"
+    ? performance.now()
+    : 0;
+}
+
+export function slugifyDesignInput(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/(^-|-$)/g, "");
+}
+
+/** Test seam: clear the coalescing state between cases. */
+export function __resetDesignInputThrottle(): void {
+  lastFiredByKey.clear();
+}
+
+export function trackDesignInput(descriptor: DesignInputDescriptor): void {
+  try {
+    const section = slugifyDesignInput(descriptor.section) || "unknown";
+    const name = slugifyDesignInput(descriptor.name);
+    // An input with no resolvable name is useless for the removal analysis (R3).
+    // Emit it anyway (so a coverage test can catch it) but under an explicit marker.
+    const control = descriptor.control || "unknown";
+    const key = `${descriptor.ui}:${section}:${control}:${name || "unnamed"}`;
+
+    const t = now();
+    const last = lastFiredByKey.get(key);
+    if (last !== undefined && t - last < COALESCE_WINDOW_MS) return;
+    lastFiredByKey.set(key, t);
+
+    trackStudioEvent("design_input", {
+      ui: descriptor.ui,
+      section,
+      control,
+      name: name || "unnamed",
+    });
+  } catch {
+    // Telemetry must never break the edit path.
+  }
+}

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