@hyperframes/studio 0.7.56 → 0.7.58

package/src/player/hooks/useTimelinePlayer.ts

@@ -46,6 +46,7 @@ import { scrubMusicAtSeek, stopScrubPreviewAudio } from "../lib/playbackScrub";
 import { applyCachedSourceDurations, probeMissingSourceDurations } from "../lib/mediaProbe";
 import { shouldResumeForwardPlaybackAfterSeek, shouldStopAfterSeek } from "../lib/playbackSeek";
 import { applyPreviewVariablesToUrl } from "../../hooks/previewVariablesStore";
+import { acceptStudioRuntimeMessage } from "../lib/runtimeProtocol";
 
 /**
  * Whether the derived elements differ from the current ones in any field that
@@ -492,6 +493,9 @@ export function useTimelinePlayer() {
       if (e.source && ourIframe && e.source !== ourIframe.contentWindow) {
         return;
       }
+      if (data?.source === "hf-preview") {
+        if (!acceptStudioRuntimeMessage(data)) return;
+      }
       if (data?.source === "hf-preview" && data?.type === "state") {
         try {
           if (usePlayerStore.getState().elements.length === 0) {

package/src/player/hooks/useTimelineSyncCallbacks.ts

@@ -11,6 +11,7 @@
 import { useCallback } from "react";
 import { liveTime, usePlayerStore } from "../store/playerStore";
 import type { TimelineElement, DomClipChild } from "../store/playerStore";
+import { resolveCssStackingContextId } from "@hyperframes/core/runtime/stacking-context";
 import type { PlaybackAdapter, ClipManifestClip, IframeWindow } from "../lib/playbackTypes";
 import {
   parseTimelineFromDOM,
@@ -26,6 +27,7 @@ import {
   autoHealMissingCompositionIds,
   buildMissingCompositionElements,
 } from "../lib/timelineIframeHelpers";
+import { acceptedRuntimeMessageFps, inspectStudioRuntimeMessage } from "../lib/runtimeProtocol";
 
 interface UseTimelineSyncCallbacksParams {
   iframeRef: React.RefObject<HTMLIFrameElement | null>;
@@ -132,6 +134,9 @@ export function useTimelineSyncCallbacks({
       clips: ClipManifestClip[];
       durationInFrames: number;
       scenes?: Array<{ id: string; label: string; start: number; duration: number }>;
+      protocolVersion?: unknown;
+      capabilities?: unknown;
+      fps?: unknown;
     }) => {
       if (!data.clips || data.clips.length === 0) {
         return;
@@ -195,6 +200,7 @@ export function useTimelineSyncCallbacks({
                   parentId,
                   hostId,
                   label: isGroup ? child.getAttribute("data-hf-group") || child.id : child.id,
+                  stackingContextId: resolveCssStackingContextId(child),
                 });
                 parentMap.set(child.id, parentId);
                 if (isGroup) collect(child, child.id);
@@ -222,7 +228,7 @@ export function useTimelineSyncCallbacks({
           hostEl,
         });
       });
-      const rawDuration = data.durationInFrames / 30;
+      const rawDuration = data.durationInFrames / acceptedRuntimeMessageFps(data);
       // Clamp non-finite or absurdly large durations — the runtime can emit
       // Infinity when it detects a loop-inflated GSAP timeline without an
       // explicit data-duration on the root composition. Floor the manifest total
@@ -418,6 +424,10 @@ export function useTimelineSyncCallbacks({
       if (e.source && iframe && e.source !== iframe.contentWindow) return;
       const data = e.data;
       if (data?.source === "hf-preview" && (data?.type === "state" || data?.type === "timeline")) {
+        // The main message handler owns protocol-error diagnostics. This readiness-only
+        // listener mirrors its acceptance gate without dispatching a duplicate event:
+        // an unsupported runtime must not make the iframe appear successfully settled.
+        if (inspectStudioRuntimeMessage(data).status === "unsupported") return;
         trySettle();
       }
     };

package/src/player/index.ts

@@ -11,7 +11,9 @@ export { resolveIframe } from "./lib/timelineDOM";
 
 // Store
 export { usePlayerStore, liveTime } from "./store/playerStore";
-export type { SelectElementOptions, TimelineElement } from "./store/playerStore";
+// Public library surface; external consumers are invisible to the workspace analyzer.
+// fallow-ignore-next-line unused-exports
+export type { SelectElementOptions, TimelineElement, ZoomMode } from "./store/playerStore";
 
 // Utils
 export { formatTime } from "./lib/time";

package/src/player/lib/layerOrdering.test.ts

@@ -1,7 +1,7 @@
 // @vitest-environment jsdom
 
 import { describe, expect, it } from "vitest";
-import { computeReorderZValues, getElementZIndex, resolveContextOrder } from "./layerOrdering";
+import { getElementZIndex, resolveContextOrder } from "./layerOrdering";
 
 function makeElement(zIndex?: string): HTMLElement {
   const element = document.createElement("div");
@@ -31,20 +31,6 @@ describe("getElementZIndex", () => {
   });
 });
 
-describe("computeReorderZValues", () => {
-  it("preserves distinct existing z-index values and remaps them onto the new order", () => {
-    expect(computeReorderZValues([1, 8, 3], 0, 2)).toEqual([8, 3, 1]);
-  });
-
-  it("renumbers an all-tied group to descending contiguous z-index values", () => {
-    expect(computeReorderZValues([0, 0, 0], 2, 0)).toEqual([3, 2, 1]);
-  });
-
-  it("renumbers the whole group when any existing z-index values are tied", () => {
-    expect(computeReorderZValues([5, 5, 1], 2, 0)).toEqual([3, 2, 1]);
-  });
-});
-
 describe("resolveContextOrder", () => {
   it("sorts a flat sibling group by z-index descending then original order", () => {
     const ordered = resolveContextOrder([

package/src/player/lib/layerOrdering.ts

@@ -1,3 +1,5 @@
+import { readLayerRevealPriorZ } from "./timelineElementHelpers";
+
 export interface StackingContextDescriptor {
   parentCompositionId: string | null;
   compositionAncestors: readonly string[];
@@ -11,6 +13,9 @@ export interface ContextOrderItem extends StackingContextDescriptor {
 // fallow-ignore-next-line complexity
 export function getElementZIndex(element: HTMLElement): number {
   try {
+    // An active Layers-panel reveal lift reports the element's TRUE z.
+    const prior = readLayerRevealPriorZ(element);
+    if (prior != null) return prior;
     const inline = element.style?.zIndex;
     if (inline && inline !== "auto") {
       const parsed = parseInt(inline, 10);
@@ -27,34 +32,6 @@ export function getElementZIndex(element: HTMLElement): number {
   }
 }
 
-// fallow-ignore-next-line complexity
-export function hasExplicitZIndex(element: HTMLElement): boolean {
-  try {
-    const inline = element.style?.zIndex;
-    if (inline) return inline !== "auto";
-    const win = element.ownerDocument?.defaultView;
-    if (!win) return false;
-    const value = win.getComputedStyle(element).zIndex;
-    return value !== "auto" && value !== "";
-  } catch {
-    return false;
-  }
-}
-
-export function computeReorderZValues(
-  existingValues: readonly number[],
-  fromIndex: number,
-  toIndex: number,
-): number[] {
-  const reordered = [...existingValues];
-  const [moved] = reordered.splice(fromIndex, 1);
-  reordered.splice(toIndex, 0, moved);
-
-  const sorted = [...existingValues].sort((a, b) => b - a);
-  const hasDupes = sorted.some((v, i) => i > 0 && v === sorted[i - 1]);
-  return hasDupes ? reordered.map((_, i) => reordered.length - i) : sorted;
-}
-
 export function resolveStackingContextKey(item: StackingContextDescriptor): string {
   return item.stackingContextId ?? item.parentCompositionId ?? item.compositionAncestors[0] ?? "";
 }

package/src/player/lib/runtimeProtocol.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  acceptStudioRuntimeMessage,
+  acceptedRuntimeMessageFps,
+  createRuntimeControlMessage,
+  inspectStudioRuntimeMessage,
+  postRuntimeControlMessage,
+} from "./runtimeProtocol";
+
+describe("Studio runtime protocol", () => {
+  it("versions every control message and declares rational fps", () => {
+    expect(createRuntimeControlMessage("seek", { timeSeconds: 1.25 }, 60)).toEqual({
+      source: "hf-parent",
+      type: "control",
+      action: "seek",
+      protocolVersion: 1,
+      capabilities: ["seconds-time", "rational-fps", "seek-keep-playing"],
+      fps: { numerator: 60, denominator: 1 },
+      timeSeconds: 1.25,
+    });
+  });
+
+  it("posts the typed message to the target window", () => {
+    const target = { postMessage: vi.fn() };
+    postRuntimeControlMessage(target as unknown as Window, "pause");
+    expect(target.postMessage).toHaveBeenCalledWith(
+      expect.objectContaining({ action: "pause", protocolVersion: 1 }),
+      "*",
+    );
+  });
+
+  it("preserves legacy 30fps messages and rejects unknown majors", () => {
+    expect(inspectStudioRuntimeMessage({ source: "hf-preview" })).toEqual({
+      status: "legacy",
+      fps: 30,
+    });
+    expect(inspectStudioRuntimeMessage({ protocolVersion: 2 })).toMatchObject({
+      status: "unsupported",
+      code: "unsupported_protocol_version",
+    });
+  });
+
+  it("reads explicit fps for accepted timeline messages", () => {
+    const message = createRuntimeControlMessage("pause", {}, 60);
+    expect(acceptedRuntimeMessageFps(message)).toBe(60);
+    expect(acceptStudioRuntimeMessage(message)).toMatchObject({ status: "supported", fps: 60 });
+  });
+});

package/src/player/lib/runtimeProtocol.ts

@@ -0,0 +1,65 @@
+import {
+  inspectRuntimeProtocol,
+  runtimeProtocolMetadata,
+  type RuntimeProtocolInspection,
+} from "@hyperframes/core/runtime/protocol";
+
+export type RuntimeControlMessage = {
+  source: "hf-parent";
+  type: "control";
+  action: string;
+} & ReturnType<typeof runtimeProtocolMetadata> &
+  Record<string, unknown>;
+
+export function createRuntimeControlMessage(
+  action: string,
+  payload: Record<string, unknown> = {},
+  fps = 30,
+): RuntimeControlMessage {
+  return {
+    ...payload,
+    source: "hf-parent",
+    type: "control",
+    action,
+    ...runtimeProtocolMetadata(fps),
+  };
+}
+
+export function postRuntimeControlMessage(
+  target: Pick<Window, "postMessage"> | null | undefined,
+  action: string,
+  payload: Record<string, unknown> = {},
+  fps = 30,
+): void {
+  target?.postMessage(createRuntimeControlMessage(action, payload, fps), "*");
+}
+
+export function inspectStudioRuntimeMessage(value: unknown): RuntimeProtocolInspection {
+  return inspectRuntimeProtocol(value, 30);
+}
+
+function dispatchRuntimeProtocolError(inspection: RuntimeProtocolInspection): void {
+  if (inspection.status !== "unsupported") return;
+  window.dispatchEvent(
+    new CustomEvent("runtimeprotocolerror", {
+      detail: {
+        code: inspection.code,
+        receivedVersion: inspection.receivedVersion,
+      },
+    }),
+  );
+}
+
+export function acceptStudioRuntimeMessage(
+  value: unknown,
+): Exclude<RuntimeProtocolInspection, { status: "unsupported" }> | null {
+  const inspection = inspectStudioRuntimeMessage(value);
+  if (inspection.status !== "unsupported") return inspection;
+  dispatchRuntimeProtocolError(inspection);
+  return null;
+}
+
+export function acceptedRuntimeMessageFps(value: unknown): number {
+  const inspection = inspectStudioRuntimeMessage(value);
+  return inspection.status === "supported" ? inspection.fps : 30;
+}

package/src/player/lib/timelineDOM.test.ts

@@ -110,7 +110,79 @@ describe("parseTimelineFromDOM — hfId from data-hf-id", () => {
   });
 });
 
+describe("createTimelineElementFromManifestClip — source-scoped selector identity", () => {
+  it("ignores an index.html duplicate when indexing a scene.html selector", () => {
+    const doc = makeDoc(`
+      <div data-composition-id="root" data-composition-file="index.html">
+        <div class="sub"></div>
+        <div data-composition-id="scene" data-composition-file="scene.html">
+          <div class="sub"></div>
+          <div class="sub" data-target></div>
+        </div>
+      </div>
+    `);
+    const target = doc.querySelector("[data-target]");
+    if (!target) throw new Error("missing target");
+
+    const element = createTimelineElementFromManifestClip({
+      clip: {
+        id: null,
+        label: "Sub",
+        kind: "element",
+        tagName: "div",
+        start: 0,
+        duration: 5,
+        track: 0,
+        compositionId: null,
+        parentCompositionId: null,
+        compositionSrc: null,
+        assetUrl: null,
+      },
+      fallbackIndex: 0,
+      doc,
+      hostEl: target,
+    });
+
+    expect(element.sourceFile).toBe("scene.html");
+    expect(element.selectorIndex).toBe(1);
+    expect(element.key).toBe("scene.html:.sub:1");
+  });
+});
+
 describe("createImplicitTimelineLayersFromDOM — hfId from data-hf-id", () => {
+  it("uses the runtime root paint scope for implicit siblings of manifest clips", () => {
+    const doc = makeDoc(`
+      <div data-composition-id="root">
+        <div id="timed" data-start="0" data-duration="5"></div>
+        <div id="implicit"></div>
+      </div>
+    `);
+    const timedHost = doc.getElementById("timed");
+    const timed = createTimelineElementFromManifestClip({
+      clip: {
+        id: "timed",
+        label: "Timed",
+        start: 0,
+        duration: 5,
+        track: 0,
+        stackingContextId: "css:root",
+        kind: "element",
+        tagName: "div",
+        compositionId: null,
+        parentCompositionId: null,
+        compositionSrc: null,
+        assetUrl: null,
+      },
+      fallbackIndex: 0,
+      doc,
+      hostEl: timedHost,
+    });
+    const implicit = createImplicitTimelineLayersFromDOM(doc, 5, [timed])[0];
+
+    expect(implicit?.stackingContextId).toBe("css:root");
+    expect(implicit?.stackingContextId).toBe(timed.stackingContextId);
+  });
+
   it("harvests hfId from an implicit layer child that has data-hf-id", () => {
     const doc = makeDoc(`
       <div data-composition-id="root">

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,
@@ -113,6 +114,15 @@ export function createTimelineElementFromManifestClip(params: {
     start: clip.start,
     duration: clip.duration,
     track: clip.track,
+    // clip.track IS the authored data-track-index verbatim (the runtime honors
+    // it; see parseAuthoredTrack in core/runtime/timeline.ts). Record it at this
+    // translation boundary so later display-lane remaps (normalizeToZones,
+    // expanded-child rows) can persist in AUTHORED space instead of
+    // reconstructing it from lane occupants.
+    authoredTrack: clip.track,
+    // Runtime-computed stacking context — authoritative; helpers read it, never
+    // re-derive it.
+    stackingContextId: clip.stackingContextId ?? null,
     domId,
     hfId,
     selector,
@@ -219,6 +229,7 @@ export function createImplicitTimelineLayersFromDOM(
       selector,
       selectorIndex,
       sourceFile,
+      stackingContextId: resolveCssStackingContextId(child),
       start: 0,
       tag: child.tagName.toLowerCase(),
       timingSource: "implicit",
@@ -294,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: {
@@ -298,6 +322,25 @@ export function getTimelineElementIdentity(element: { key?: string | null; id: s
   return element.key ?? element.id;
 }
 
+/**
+ * Timeline store key for a z-reorder entry built OUTSIDE the timeline
+ * expansion (canvas context menu / LayersPanel), so the reorder commit can
+ * update the store's zIndex synchronously. Matches buildTimelineElementKey's
+ * stable branches (`sourceFile#domId`, else the selector-based key). Undefined
+ * when the element has neither a DOM id nor a selector — the timeline's
+ * fallback branch needs its own fallbackIndex, which these callers don't have,
+ * so such an entry simply skips the synchronous store update.
+ */
+export function deriveTimelineStoreKey(params: {
+  domId?: string;
+  selector?: string;
+  selectorIndex?: number;
+  sourceFile?: string;
+}): string | undefined {
+  if (!params.domId && !params.selector) return undefined;
+  return buildTimelineElementKey({ id: "", fallbackIndex: 0, ...params });
+}
+
 // ---------------------------------------------------------------------------
 // DOM node querying
 // ---------------------------------------------------------------------------

package/src/player/lib/timelineIframeHelpers.ts

@@ -20,6 +20,7 @@ import {
   buildTimelineElementIdentity,
   readTimelineElementZIndex,
 } from "./timelineElementHelpers";
+import { postRuntimeControlMessage } from "./runtimeProtocol";
 
 // ---------------------------------------------------------------------------
 // Viewport / DOM normalisation
@@ -103,10 +104,7 @@ function postPreviewControl(
   action: string,
   payload: Record<string, unknown>,
 ): void {
-  iframe.contentWindow?.postMessage(
-    { source: "hf-parent", type: "control", action, ...payload },
-    "*",
-  );
+  postRuntimeControlMessage(iframe.contentWindow, action, payload);
 }
 
 export function shouldMutePreviewAudio(audioMuted: boolean, playbackRate: number): boolean {

package/src/player/store/playerStore.test.ts

@@ -1,6 +1,16 @@
 import { describe, it, expect, beforeEach, vi } from "vitest";
 import { usePlayerStore, liveTime, type TimelineElement } from "./playerStore";
 
+/** The playback/selection state `reset()` restores (persistent prefs asserted separately). */
+function expectResettableDefaults(state: ReturnType<typeof usePlayerStore.getState>): void {
+  expect(state.isPlaying).toBe(false);
+  expect(state.currentTime).toBe(0);
+  expect(state.duration).toBe(0);
+  expect(state.timelineReady).toBe(false);
+  expect(state.elements).toEqual([]);
+  expect(state.selectedElementId).toBeNull();
+}
+
 describe("usePlayerStore", () => {
   beforeEach(() => {
     usePlayerStore.getState().reset();
@@ -9,12 +19,7 @@ describe("usePlayerStore", () => {
   describe("initial state", () => {
     it("has correct defaults", () => {
       const state = usePlayerStore.getState();
-      expect(state.isPlaying).toBe(false);
-      expect(state.currentTime).toBe(0);
-      expect(state.duration).toBe(0);
-      expect(state.timelineReady).toBe(false);
-      expect(state.elements).toEqual([]);
-      expect(state.selectedElementId).toBeNull();
+      expectResettableDefaults(state);
       expect(state.playbackRate).toBe(1);
       expect(state.audioMuted).toBe(false);
       expect(state.loopEnabled).toBe(false);
@@ -384,6 +389,32 @@ describe("usePlayerStore", () => {
     });
   });
 
+  describe("clipRevealRequest", () => {
+    it("starts null and carries the requested element id", () => {
+      expect(usePlayerStore.getState().clipRevealRequest).toBeNull();
+      usePlayerStore.getState().requestClipReveal("el-1");
+      expect(usePlayerStore.getState().clipRevealRequest?.elementId).toBe("el-1");
+    });
+
+    it("bumps the nonce on repeat requests for the same clip", () => {
+      usePlayerStore.getState().requestClipReveal("el-1");
+      const first = usePlayerStore.getState().clipRevealRequest;
+      usePlayerStore.getState().requestClipReveal("el-1");
+      const second = usePlayerStore.getState().clipRevealRequest;
+      expect(second?.nonce).not.toBe(first?.nonce);
+    });
+
+    it("clears via clearClipRevealRequest and on reset", () => {
+      usePlayerStore.getState().requestClipReveal("el-1");
+      usePlayerStore.getState().clearClipRevealRequest();
+      expect(usePlayerStore.getState().clipRevealRequest).toBeNull();
+
+      usePlayerStore.getState().requestClipReveal("el-2");
+      usePlayerStore.getState().reset();
+      expect(usePlayerStore.getState().clipRevealRequest).toBeNull();
+    });
+  });
+
   describe("reset", () => {
     it("resets all state to defaults", () => {
       // Mutate everything
@@ -398,13 +429,7 @@ describe("usePlayerStore", () => {
       // Reset
       usePlayerStore.getState().reset();
 
-      const state = usePlayerStore.getState();
-      expect(state.isPlaying).toBe(false);
-      expect(state.currentTime).toBe(0);
-      expect(state.duration).toBe(0);
-      expect(state.timelineReady).toBe(false);
-      expect(state.elements).toEqual([]);
-      expect(state.selectedElementId).toBeNull();
+      expectResettableDefaults(usePlayerStore.getState());
     });
 
     it("does not reset playbackRate, audioMuted, loopEnabled, zoomMode, or manualZoomPercent", () => {