@hyperframes/studio 0.8.46 → 0.8.47

package/dist/assets/{index-CbchRscN.js → index-ryL7q1QG.js}

@@ -1,4 +1,4 @@
-import{n as Qi}from"./index-DCblmTX3.js";/*!
+import{n as Qi}from"./index-j-4hCrZU.js";/*!
  * Copyright (c) 2026-present, Vanilagy and contributors
  *
  * This Source Code Form is subject to the terms of the Mozilla Public

package/dist/index.d.ts

@@ -4,6 +4,7 @@ import { ReactNode, RefObject } from 'react';
 import { RuntimeTimelineClipIdentity } from '@hyperframes/core';
 import { GsapAnimation, PropertyGroupName } from '@hyperframes/core/gsap-parser';
 import * as zustand from 'zustand';
+import { StoreApi } from 'zustand';
 import { MusicBeatAnalysis } from '@hyperframes/core/beats';
 import { GsapAnimation as GsapAnimation$1, ArcPathSegment } from '@hyperframes/parsers/gsap-parser';
 
@@ -250,6 +251,20 @@ interface ThumbnailSlice {
     bumpThumbnailContentRevision: () => void;
 }
 
+/** Gates `timelineReady` on the composition's declared readiness inputs
+ * (media, for now) instead of just a known duration. The generation counter
+ * is module-scope, not store state: it guards an in-flight settlement, not
+ * something a component reads, so bumping it shouldn't trigger a render. */
+
+interface PlaybackReadinessSlice {
+    timelineReady: boolean;
+    setTimelineReady: (ready: boolean) => void;
+    /** Sets timelineReady once doc's readiness inputs settle, or immediately
+     *  if doc is null. A wait a later call supersedes never wins the race. */
+    requestTimelineReady: (doc: Document | null) => void;
+}
+declare function createPlaybackReadinessSlice(set: StoreApi<PlaybackReadinessSlice>["setState"]): PlaybackReadinessSlice;
+
 type TimeListener = (time: number) => void;
 declare const liveTime: {
     notify: (time: number) => void;
@@ -382,11 +397,11 @@ type TimelineTool = "select" | "razor";
 interface SelectElementOptions {
     preserveSet?: boolean;
 }
-interface PlayerState extends KeyframeSlice, AutomationSelectionSlice, ThumbnailSlice, EditingModeSlice {
+type PlayerStoreSlices = KeyframeSlice & AutomationSelectionSlice & ThumbnailSlice & EditingModeSlice & ReturnType<typeof createPlaybackReadinessSlice>;
+interface PlayerState extends PlayerStoreSlices {
     isPlaying: boolean;
     currentTime: number;
     duration: number;
-    timelineReady: boolean;
     /** Increments exactly once when the Studio switches to a different project. */
     timelineSessionEpoch: number;
     /** Project owning the current timeline session; null outside a project-scoped reset. */
@@ -452,7 +467,6 @@ interface PlayerState extends KeyframeSlice, AutomationSelectionSlice, Thumbnail
     setAudioMuted: (muted: boolean) => void;
     setAudioVolume: (volume: number) => void;
     setLoopEnabled: (enabled: boolean) => void;
-    setTimelineReady: (ready: boolean) => void;
     setBeatDragging: (dragging: boolean) => void;
     setElements: (elements: TimelineElement[]) => void;
     setSelectedElementId: (id: string | null, options?: SelectElementOptions) => void;

package/dist/index.html

@@ -5,7 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <title>HyperFrames Studio</title>
-    <script type="module" crossorigin src="/assets/index-DCblmTX3.js"></script>
+    <script type="module" crossorigin src="/assets/index-j-4hCrZU.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-DnRfAiK2.css">
   </head>
   <body>

package/dist/index.js

@@ -1594,6 +1594,30 @@ function createThumbnailSlice(set) {
   };
 }
 
+// src/player/store/readinessSlice.ts
+import { settleCompositionReadiness } from "@hyperframes/core/composition-readiness";
+var timelineReadyGeneration = 0;
+function resetPlaybackReadinessState() {
+  timelineReadyGeneration++;
+  return { timelineReady: false };
+}
+function createPlaybackReadinessSlice(set) {
+  return {
+    timelineReady: false,
+    setTimelineReady: (ready) => {
+      timelineReadyGeneration++;
+      set({ timelineReady: ready });
+    },
+    requestTimelineReady: (doc) => {
+      const generation = ++timelineReadyGeneration;
+      if (!doc) return set({ timelineReady: true });
+      settleCompositionReadiness(doc, () => {
+        if (generation === timelineReadyGeneration) set({ timelineReady: true });
+      });
+    }
+  };
+}
+
 // src/player/store/liveTime.ts
 var timeListeners = /* @__PURE__ */ new Set();
 var liveTime = {
@@ -1623,7 +1647,7 @@ function createTimelineResetState() {
     isPlaying: false,
     currentTime: 0,
     duration: 0,
-    timelineReady: false,
+    ...resetPlaybackReadinessState(),
     beatDragging: false,
     elements: [],
     selectedElementId: null,
@@ -1666,7 +1690,6 @@ var usePlayerStore = create2((set, get) => ({
   isPlaying: false,
   currentTime: 0,
   duration: 0,
-  timelineReady: false,
   timelineSessionEpoch: 0,
   timelineProjectId: null,
   beatDragging: false,
@@ -1692,6 +1715,7 @@ var usePlayerStore = create2((set, get) => ({
   ...createThumbnailSlice(set),
   ...createAutomationSelectionSlice(set),
   ...createEditingModeSlice(set),
+  ...createPlaybackReadinessSlice(set),
   activeKeyframePct: null,
   setActiveKeyframePct: (pct) => set({ activeKeyframePct: pct }),
   selectedElementIds: /* @__PURE__ */ new Set(),
@@ -1856,7 +1880,6 @@ var usePlayerStore = create2((set, get) => ({
   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 }),
   setBeatDragging: (dragging) => set({ beatDragging: dragging }),
   setElements: (elements) => set({ elements }),
   // A genuine single selection: always collapse the set to just this element. User
@@ -25080,7 +25103,7 @@ function useTimelineSyncCallbacks({
   syncTimelineElements,
   setDuration,
   setCurrentTime,
-  setTimelineReady,
+  requestTimelineReady,
   setIsPlaying,
   attachIframeShortcutListeners,
   applyPreviewAudioState
@@ -25152,7 +25175,7 @@ function useTimelineSyncCallbacks({
     syncAdapterDuration(adapter, setDuration);
     setCurrentTime(startTime);
     if (!isRefreshingRef.current) {
-      setTimelineReady(true);
+      requestTimelineReady(safeContentDocument(iframeRef.current));
     }
     isRefreshingRef.current = false;
     setIsPlaying(false);
@@ -25170,7 +25193,7 @@ function useTimelineSyncCallbacks({
     getAdapter,
     setDuration,
     setCurrentTime,
-    setTimelineReady,
+    requestTimelineReady,
     setIsPlaying,
     processTimelineMessage,
     enrichMissingCompositions,
@@ -25641,7 +25664,7 @@ function useTimelinePlayer() {
   const lastTimelineMessageRef = useRef44(0);
   const staticSeekAdapterRef = useRef44(null);
   const staticSeekWarnedRef = useRef44(false);
-  const { setIsPlaying, setCurrentTime, setDuration, setTimelineReady, setElements } = usePlayerStore.getState();
+  const { setIsPlaying, setCurrentTime, setDuration, requestTimelineReady, setElements } = usePlayerStore.getState();
   const syncTimelineElements = useCallback36(
     // The lease guard adds one deliberate branch at the shared synchronization boundary.
     // fallow-ignore-next-line complexity
@@ -25667,7 +25690,7 @@ function useTimelinePlayer() {
         setDuration(nextDuration ?? 0);
       }
       if (!state.timelineReady) {
-        setTimelineReady(true);
+        requestTimelineReady(safeContentDocument(iframeRef.current));
       }
       void probeMissingSourceDurations(
         mergedElements,
@@ -25683,7 +25706,7 @@ function useTimelinePlayer() {
         }
       );
     },
-    [setElements, setTimelineReady, setDuration]
+    [setElements, requestTimelineReady, setDuration]
   );
   const getAdapter = useCallback36(() => {
     try {
@@ -25953,7 +25976,7 @@ function useTimelinePlayer() {
     syncTimelineElements,
     setDuration,
     setCurrentTime,
-    setTimelineReady,
+    requestTimelineReady,
     setIsPlaying,
     attachIframeShortcutListeners,
     applyPreviewAudioState
@@ -38233,7 +38256,7 @@ var STUDIO_SDK_OPERATION_FAMILIES = [
 function resolveEnabledSdkFamilies(env2, masterEnabled) {
   if (!masterEnabled) return /* @__PURE__ */ new Set();
   const raw = env2["VITE_STUDIO_SDK_CUTOVER_FAMILIES"];
-  if (typeof raw !== "string" || raw.trim() === "") return /* @__PURE__ */ new Set();
+  if (typeof raw !== "string" || raw.trim() === "") return new Set(STUDIO_SDK_OPERATION_FAMILIES);
   const requested = raw.split(",").map((family) => family.trim()).filter(Boolean);
   const known = new Set(STUDIO_SDK_OPERATION_FAMILIES);
   const unknown = requested.filter((family) => !known.has(family));
@@ -38266,7 +38289,7 @@ var env = { ...import.meta.env ?? {}, ...runtimeEnv };
 var STUDIO_SDK_CUTOVER_ENABLED = resolveStudioBooleanEnvFlag(
   env,
   ["VITE_STUDIO_SDK_CUTOVER_ENABLED"],
-  false
+  true
 );
 var STUDIO_SDK_CUTOVER_FAMILIES = resolveEnabledSdkFamilies(
   env,
@@ -38759,6 +38782,13 @@ function shouldDeclineTextCutoverForTarget(target, ops) {
   const tag = elementTag(children[0]);
   return tag !== null && NON_HTML_CHILD_TAGS.has(tag);
 }
+function isResolverDisagreement(session, hfId) {
+  try {
+    return resolveSnapshot(session, hfId) !== null;
+  } catch {
+    return false;
+  }
+}
 function shouldUseSdkCutover(flagEnabled, hasSession, hfId, ops) {
   return flagEnabled && hasSession && !!hfId && ops.length > 0 && ops.every((o) => CUTOVER_OP_TYPES.has(o.type)) && // SDK edit ops target only the element hfId; child-scoped patch ops need the server path.
   !hasChildScopedOp(ops) && !ops.some(mapsToReservedAttr) && !hasUnsafeHtmlAttributeOp(ops);
@@ -38800,7 +38830,12 @@ function isSelfWriteEcho(path, content, now2 = Date.now()) {
 }
 
 // src/utils/sdkEditTransaction.ts
-function declinedCutover(reason) {
+function declinedCutover(reason, family, resolverDisagreement) {
+  trackStudioEvent("sdk_cutover_declined", {
+    reason,
+    family: family ?? null,
+    ...resolverDisagreement ? { resolverDisagreement: true } : {}
+  });
   return { status: "declined", reason };
 }
 function asCutoverError(error) {
@@ -38967,15 +39002,17 @@ function gsapReadSource(deps, targetPath) {
 }
 async function sdkCutoverPersist(selection, ops, originalContent, targetPath, sdkSession, deps, options) {
   if (!shouldUseSdkCutover(sdkFamilyEnabled("dom"), !!sdkSession, selection.hfId, ops))
-    return declinedCutover("ineligible_operation");
-  if (!sdkSession) return declinedCutover("session_unavailable");
+    return declinedCutover("ineligible_operation", "dom");
+  if (!sdkSession) return declinedCutover("session_unavailable", "dom");
   const hfId = selection.hfId;
-  if (!hfId) return declinedCutover("target_unaddressable");
+  if (!hfId) return declinedCutover("target_unaddressable", "dom");
   const target = sdkSession.getElement(hfId);
-  if (!target) return declinedCutover("target_not_found");
+  if (!target)
+    return declinedCutover("target_not_found", "dom", isResolverDisagreement(sdkSession, hfId));
   if (shouldDeclineTextCutoverForTarget(target, ops))
-    return declinedCutover("unsupported_text_target");
-  if (wrongCompositionFile(deps, targetPath)) return declinedCutover("wrong_composition_file");
+    return declinedCutover("unsupported_text_target", "dom");
+  if (wrongCompositionFile(deps, targetPath))
+    return declinedCutover("wrong_composition_file", "dom");
   const result = await persistSdkCandidateMutation(
     sdkSession,
     targetPath,
@@ -38998,10 +39035,12 @@ async function sdkTimingPersist(hfId, targetPath, timingUpdate, sdkSession, deps
     timingSrc ? () => timingSrc(targetPath) : void 0,
     { targetPath, compositionPath: deps.compositionPath }
   );
-  if (!sdkFamilyEnabled("timing")) return declinedCutover("feature_disabled");
-  if (!sdkSession) return declinedCutover("session_unavailable");
-  if (!sdkSession.getElement(hfId)) return declinedCutover("target_not_found");
-  if (wrongCompositionFile(deps, targetPath)) return declinedCutover("wrong_composition_file");
+  if (!sdkFamilyEnabled("timing")) return declinedCutover("feature_disabled", "timing");
+  if (!sdkSession) return declinedCutover("session_unavailable", "timing");
+  if (!sdkSession.getElement(hfId))
+    return declinedCutover("target_not_found", "timing", isResolverDisagreement(sdkSession, hfId));
+  if (wrongCompositionFile(deps, targetPath))
+    return declinedCutover("wrong_composition_file", "timing");
   try {
     const serializedBefore = sdkSession.serialize();
     const result = await persistSdkCandidateMutation(
@@ -39032,11 +39071,17 @@ async function sdkTimingBatchPersist(changes, targetPath, sdkSession, deps, opti
       { targetPath, compositionPath: deps.compositionPath }
     );
   }
-  if (!sdkFamilyEnabled("timing")) return declinedCutover("feature_disabled");
-  if (!sdkSession) return declinedCutover("session_unavailable");
-  if (wrongCompositionFile(deps, targetPath)) return declinedCutover("wrong_composition_file");
-  if (changes.some((change) => !sdkSession.getElement(change.hfId)))
-    return declinedCutover("target_not_found");
+  if (!sdkFamilyEnabled("timing")) return declinedCutover("feature_disabled", "timing");
+  if (!sdkSession) return declinedCutover("session_unavailable", "timing");
+  if (wrongCompositionFile(deps, targetPath))
+    return declinedCutover("wrong_composition_file", "timing");
+  const unresolved = changes.find((change) => !sdkSession.getElement(change.hfId));
+  if (unresolved)
+    return declinedCutover(
+      "target_not_found",
+      "timing",
+      isResolverDisagreement(sdkSession, unresolved.hfId)
+    );
   try {
     const serializedBefore = sdkSession.serialize();
     const result = await persistSdkCandidateMutation(
@@ -39091,9 +39136,9 @@ function sdkGsapTweenPersist(targetPath, op, sdkSession, deps, options) {
     );
   }
   if (!sdkFamilyEnabled("gsap-animation"))
-    return Promise.resolve(declinedCutover("feature_disabled"));
+    return Promise.resolve(declinedCutover("feature_disabled", "gsap-animation"));
   if (op.kind === "add" && sdkSession && !sdkSession.getElement(op.target))
-    return Promise.resolve(declinedCutover("target_not_found"));
+    return Promise.resolve(declinedCutover("target_not_found", "gsap-animation"));
   return dispatchGsapOpAndPersist("gsap-animation", targetPath, sdkSession, deps, options, (s) => {
     s.batch(() => {
       if (op.kind === "add") {
@@ -39116,9 +39161,10 @@ async function dispatchGsapOpAndPersist(family, targetPath, sdkSession, deps, op
       { targetPath, compositionPath: deps.compositionPath }
     );
   }
-  if (!sdkFamilyEnabled(family)) return declinedCutover("feature_disabled");
-  if (!sdkSession) return declinedCutover("session_unavailable");
-  if (wrongCompositionFile(deps, targetPath)) return declinedCutover("wrong_composition_file");
+  if (!sdkFamilyEnabled(family)) return declinedCutover("feature_disabled", family);
+  if (!sdkSession) return declinedCutover("session_unavailable", family);
+  if (wrongCompositionFile(deps, targetPath))
+    return declinedCutover("wrong_composition_file", family);
   const session = sdkSession;
   try {
     const serializedBefore = session.serialize();
@@ -39271,10 +39317,16 @@ async function sdkDeletePersist(hfId, originalContent, targetPath, sdkSession, d
     () => Promise.resolve(originalContent),
     { targetPath, compositionPath: deps.compositionPath }
   );
-  if (!sdkFamilyEnabled("lifecycle")) return declinedCutover("feature_disabled");
-  if (!sdkSession) return declinedCutover("session_unavailable");
-  if (!sdkSession.getElement(hfId)) return declinedCutover("target_not_found");
-  if (wrongCompositionFile(deps, targetPath)) return declinedCutover("wrong_composition_file");
+  if (!sdkFamilyEnabled("lifecycle")) return declinedCutover("feature_disabled", "lifecycle");
+  if (!sdkSession) return declinedCutover("session_unavailable", "lifecycle");
+  if (!sdkSession.getElement(hfId))
+    return declinedCutover(
+      "target_not_found",
+      "lifecycle",
+      isResolverDisagreement(sdkSession, hfId)
+    );
+  if (wrongCompositionFile(deps, targetPath))
+    return declinedCutover("wrong_composition_file", "lifecycle");
   const result = await persistSdkCandidateMutation(
     sdkSession,
     targetPath,
@@ -74679,7 +74731,11 @@ function useSdkSession(projectId, activeCompPath) {
       generation
     };
     readProjectFileOptional(projectId, activeCompPath).then(async (content) => {
-      if (cancelled || typeof content !== "string") return;
+      if (cancelled) return;
+      if (typeof content !== "string") {
+        trackStudioEvent("sdk_session_unavailable", { stage: "read" });
+        return;
+      }
       const comp = await openComposition3(content, { history: false });
       if (cancelled) {
         disposeSdkSession(comp);
@@ -74693,6 +74749,7 @@ function useSdkSession(projectId, activeCompPath) {
         reloadTokenRef.current
       )) {
         disposeSdkSession(comp);
+        trackStudioEvent("sdk_session_unavailable", { stage: "ownership" });
         return;
       }
       const displaced = ownedSessionRef.current;
@@ -74701,8 +74758,14 @@ function useSdkSession(projectId, activeCompPath) {
       ownedSessionRef.current = installed;
       setOwnedSession(installed);
       if (displaced && displaced.session !== comp) disposeSdkSession(displaced.session);
-    }).catch(() => {
-      if (!cancelled && generationRef.current === generation) setOwnedSession(null);
+    }).catch((error) => {
+      if (!cancelled && generationRef.current === generation) {
+        setOwnedSession(null);
+        trackStudioEvent("sdk_session_unavailable", {
+          stage: "open",
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
     });
     return () => {
       cancelled = true;