@hyperframes/studio 0.8.46 → 0.8.47

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.46",
+  "version": "0.8.47",
   "description": "",
   "repository": {
     "type": "git",
@@ -48,11 +48,11 @@
     "gsap": "^3.13.0",
     "marked": "^14.1.4",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.46",
-    "@hyperframes/parsers": "0.8.46",
-    "@hyperframes/player": "0.8.46",
-    "@hyperframes/studio-server": "0.8.46",
-    "@hyperframes/sdk": "0.8.46"
+    "@hyperframes/core": "0.8.47",
+    "@hyperframes/sdk": "0.8.47",
+    "@hyperframes/parsers": "0.8.47",
+    "@hyperframes/studio-server": "0.8.47",
+    "@hyperframes/player": "0.8.47"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -69,7 +69,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.46"
+    "@hyperframes/producer": "0.8.47"
   },
   "peerDependencies": {
     "react": "19",

package/src/components/editor/manualEditingAvailability.test.ts

@@ -1,5 +1,6 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { resolveStudioBooleanEnvFlag } from "./manualEditingAvailability";
+import { STUDIO_SDK_OPERATION_FAMILIES } from "../../utils/sdkCutoverPolicy";
 
 async function loadAvailabilityWithEnv(env: Record<string, string | undefined>) {
   vi.resetModules();
@@ -88,4 +89,22 @@ describe("manual editing availability", () => {
     });
     expect(off.STUDIO_FLAT_INSPECTOR_ENABLED).toBe(false);
   });
+
+  it("defaults SDK cutover on for every family", async () => {
+    const all = await loadAvailabilityWithEnv({});
+    expect(all.STUDIO_SDK_CUTOVER_ENABLED).toBe(true);
+    expect(all.STUDIO_SDK_CUTOVER_FAMILIES).toEqual(new Set(STUDIO_SDK_OPERATION_FAMILIES));
+  });
+
+  it("honors the SDK cutover kill switches", async () => {
+    const off = await loadAvailabilityWithEnv({ VITE_STUDIO_SDK_CUTOVER_ENABLED: "false" });
+    expect(off.STUDIO_SDK_CUTOVER_ENABLED).toBe(false);
+    expect(off.STUDIO_SDK_CUTOVER_FAMILIES.size).toBe(0);
+
+    const subset = await loadAvailabilityWithEnv({
+      VITE_STUDIO_SDK_CUTOVER_FAMILIES: "dom,timing",
+    });
+    expect(subset.STUDIO_SDK_CUTOVER_ENABLED).toBe(true);
+    expect(subset.STUDIO_SDK_CUTOVER_FAMILIES).toEqual(new Set(["dom", "timing"]));
+  });
 });

package/src/components/editor/manualEditingAvailability.ts

@@ -38,16 +38,20 @@ const runtimeEnv =
     : {};
 const env = { ...(import.meta.env ?? {}), ...runtimeEnv } as StudioFeatureFlagEnv;
 
-// Stage 7 Step 3c: SDK cutover — routes inline-style ops through SDK dispatch
-// instead of the server patch-element API. Default false; enable via
-// VITE_STUDIO_SDK_CUTOVER_ENABLED=true. Requires SDK session to be open.
+// Stage 7 SDK cutover — routes Studio edits through SDK dispatch instead of the
+// server patch/mutation routes. Default TRUE as of the flip release (spec:
+// 2026-09-17-studio-sdk-cutover-flip-design.md). Kill switch:
+// VITE_STUDIO_SDK_CUTOVER_ENABLED=false (works at runtime via __HF_STUDIO_ENV__).
 export const STUDIO_SDK_CUTOVER_ENABLED = resolveStudioBooleanEnvFlag(
   env,
   ["VITE_STUDIO_SDK_CUTOVER_ENABLED"],
-  false,
+  true,
 );
 
-/** Explicit per-operation-family canary selection; the master flag alone enables nothing. */
+/**
+ * Per-family selection. Unset = every family (the master alone enables all).
+ * Set `VITE_STUDIO_SDK_CUTOVER_FAMILIES=dom,timing` to RESTRICT to a subset.
+ */
 export const STUDIO_SDK_CUTOVER_FAMILIES = resolveEnabledSdkFamilies(
   env,
   STUDIO_SDK_CUTOVER_ENABLED,

package/src/hooks/useSdkSession.lifecycle.test.tsx

@@ -12,6 +12,17 @@ vi.mock("@hyperframes/sdk", () => ({
 import type { Composition } from "@hyperframes/sdk";
 import { useSdkSession, type SdkSessionHandle } from "./useSdkSession";
 
+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+
+import { trackStudioEvent } from "../utils/studioTelemetry";
+
+const trackMock = vi.mocked(trackStudioEvent);
+
+function Probe({ projectId }: { projectId: string }) {
+  useSdkSession(projectId, "index.html");
+  return null;
+}
+
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
 function fakeSession(): Composition {
@@ -135,3 +146,68 @@ describe("useSdkSession ownership", () => {
     expect(published.dispose).toHaveBeenCalledOnce();
   });
 });
+
+describe("useSdkSession unavailable telemetry", () => {
+  beforeEach(() => {
+    openComposition.mockReset();
+    trackMock.mockClear();
+    class FakeEventSource {
+      addEventListener(): void {}
+      close(): void {}
+    }
+    vi.stubGlobal("EventSource", FakeEventSource);
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  // Every cutover chokepoint silently takes the server path when there is no
+  // session, and the shadow never runs either — so a missing session is a total,
+  // otherwise-invisible SDK bypass. These three exits are its only origin.
+  it("reports an unreadable composition", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => ({ ok: false, json: async () => ({}) }) as Response),
+    );
+    const root = createRoot(document.createElement("div"));
+    await act(async () => root.render(<Probe projectId="project-a" />));
+    await flushAsyncEffects();
+
+    expect(trackMock).toHaveBeenCalledWith("sdk_session_unavailable", { stage: "read" });
+    await act(async () => root.unmount());
+  });
+
+  it("reports a parse failure with its message", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => response("PROJECT_A")),
+    );
+    openComposition.mockRejectedValue(new Error("unparseable composition"));
+
+    const root = createRoot(document.createElement("div"));
+    await act(async () => root.render(<Probe projectId="project-a" />));
+    await flushAsyncEffects();
+
+    expect(trackMock).toHaveBeenCalledWith("sdk_session_unavailable", {
+      stage: "open",
+      error: "unparseable composition",
+    });
+    await act(async () => root.unmount());
+  });
+
+  it("stays silent on the happy path", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => response("PROJECT_A")),
+    );
+    openComposition.mockResolvedValue(fakeSession());
+
+    const root = createRoot(document.createElement("div"));
+    await act(async () => root.render(<Probe projectId="project-a" />));
+    await flushAsyncEffects();
+
+    expect(trackMock).not.toHaveBeenCalledWith("sdk_session_unavailable", expect.anything());
+    await act(async () => root.unmount());
+  });
+});

package/src/hooks/useSdkSession.ts

@@ -181,7 +181,15 @@ export function useSdkSession(
 
     readProjectFileOptional(projectId, activeCompPath)
       .then(async (content) => {
-        if (cancelled || typeof content !== "string") return;
+        if (cancelled) return;
+        if (typeof content !== "string") {
+          // No SDK session follows, so EVERY cutover chokepoint below takes the
+          // server path and emits nothing — the shadow never runs either. This
+          // is the only place a missing session can originate, so a broken read
+          // would otherwise be a silent, total SDK bypass.
+          trackStudioEvent("sdk_session_unavailable", { stage: "read" });
+          return;
+        }
         // No persist queue: Studio's writeProjectFile (via sdkCutover's
         // persistSdkSerialize) is the SINGLE writer. Wiring the SDK persist
         // queue too would double-write the file (queue auto-writes on every
@@ -206,6 +214,7 @@ export function useSdkSession(
           )
         ) {
           disposeSdkSession(comp);
+          trackStudioEvent("sdk_session_unavailable", { stage: "ownership" });
           return;
         }
         const displaced = ownedSessionRef.current;
@@ -215,8 +224,17 @@ export function useSdkSession(
         setOwnedSession(installed);
         if (displaced && displaced.session !== comp) disposeSdkSession(displaced.session);
       })
-      .catch(() => {
-        if (!cancelled && generationRef.current === generation) setOwnedSession(null);
+      .catch((error: unknown) => {
+        if (!cancelled && generationRef.current === generation) {
+          setOwnedSession(null);
+          // openComposition threw (unparseable composition, OOM) — same total
+          // bypass as the read failure above, but this one is a real defect
+          // rather than a missing file. Carry the message; it is the only clue.
+          trackStudioEvent("sdk_session_unavailable", {
+            stage: "open",
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
       });
 
     return () => {

package/src/player/hooks/useTimelinePlayer.ts

@@ -45,6 +45,7 @@ import { shouldResumeForwardPlaybackAfterSeek, shouldStopAfterSeek } from "../li
 import { applyPreviewVariablesToUrl } from "../../hooks/previewVariablesStore";
 import { createPreviewMessageHandler } from "./previewMessageRouter";
 import { timelineElementsChanged } from "./timelinePlayerSync";
+import { safeContentDocument } from "./timelineSyncHydration";
 
 export function useTimelinePlayer() {
   const iframeRef = useRef<HTMLIFrameElement | null>(null);
@@ -60,7 +61,7 @@ export function useTimelinePlayer() {
   const staticSeekAdapterRef = useRef<StaticSeekCacheEntry | null>(null);
   const staticSeekWarnedRef = useRef(false);
 
-  const { setIsPlaying, setCurrentTime, setDuration, setTimelineReady, setElements } =
+  const { setIsPlaying, setCurrentTime, setDuration, requestTimelineReady, setElements } =
     usePlayerStore.getState();
 
   // The fixture lease belongs at this shared synchronization boundary so every
@@ -101,7 +102,11 @@ export function useTimelinePlayer() {
         setDuration(nextDuration ?? 0);
       }
       if (!state.timelineReady) {
-        setTimelineReady(true);
+        // Same gate as initializeAdapter's own readiness wait: this is the
+        // message-based fallback for compositions that report their duration
+        // via clip manifest rather than the direct adapter, and it must not
+        // enable Play any earlier than that path does.
+        requestTimelineReady(safeContentDocument(iframeRef.current));
       }
 
       // Asynchronously enrich media elements still missing sourceDuration
@@ -120,7 +125,7 @@ export function useTimelinePlayer() {
         },
       );
     },
-    [setElements, setTimelineReady, setDuration],
+    [setElements, requestTimelineReady, setDuration],
   );
 
   // Pre-existing dispatcher complexity — surfaced by this PR's line shifts, not new logic.
@@ -425,7 +430,7 @@ export function useTimelinePlayer() {
       syncTimelineElements,
       setDuration,
       setCurrentTime,
-      setTimelineReady,
+      requestTimelineReady,
       setIsPlaying,
       attachIframeShortcutListeners,
       applyPreviewAudioState,

package/src/player/hooks/useTimelineSyncCallbacks.ts

@@ -42,7 +42,7 @@ interface UseTimelineSyncCallbacksParams {
   syncTimelineElements: (elements: TimelineElement[], nextDuration?: number) => void;
   setDuration: (v: number) => void;
   setCurrentTime: (v: number) => void;
-  setTimelineReady: (v: boolean) => void;
+  requestTimelineReady: (doc: Document | null) => void;
   setIsPlaying: (v: boolean) => void;
   attachIframeShortcutListeners: () => void;
   applyPreviewAudioState: () => void;
@@ -106,7 +106,7 @@ export function useTimelineSyncCallbacks({
   syncTimelineElements,
   setDuration,
   setCurrentTime,
-  setTimelineReady,
+  requestTimelineReady,
   setIsPlaying,
   attachIframeShortcutListeners,
   applyPreviewAudioState,
@@ -204,7 +204,10 @@ export function useTimelineSyncCallbacks({
     syncAdapterDuration(adapter, setDuration);
     setCurrentTime(startTime);
     if (!isRefreshingRef.current) {
-      setTimelineReady(true);
+      // Enables Play from actual play-readiness, not just a known duration —
+      // a click before this resolves used to start the timeline with media,
+      // images or fonts still loading and never recover.
+      requestTimelineReady(safeContentDocument(iframeRef.current));
     }
     isRefreshingRef.current = false;
     setIsPlaying(false);
@@ -223,7 +226,7 @@ export function useTimelineSyncCallbacks({
     getAdapter,
     setDuration,
     setCurrentTime,
-    setTimelineReady,
+    requestTimelineReady,
     setIsPlaying,
     processTimelineMessage,
     enrichMissingCompositions,

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

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { describe, it, expect, beforeEach, vi } from "vitest";
 import { usePlayerStore, liveTime, type TimelineElement } from "./playerStore";
 
@@ -322,6 +323,47 @@ describe("usePlayerStore", () => {
     });
   });
 
+  describe("requestTimelineReady", () => {
+    function stalledVideoDoc(): { doc: Document; video: HTMLVideoElement } {
+      const doc = document.implementation.createHTMLDocument("composition");
+      const video = doc.createElement("video");
+      Object.defineProperty(video, "readyState", { value: 0, configurable: true });
+      doc.body.appendChild(video);
+      return { doc, video };
+    }
+
+    it("resolves timelineReady once the doc's media settles", async () => {
+      const { doc, video } = stalledVideoDoc();
+      usePlayerStore.getState().requestTimelineReady(doc);
+      expect(usePlayerStore.getState().timelineReady).toBe(false);
+
+      video.dispatchEvent(new Event("canplay"));
+      await new Promise((resolve) => setTimeout(resolve, 0));
+
+      expect(usePlayerStore.getState().timelineReady).toBe(true);
+    });
+
+    it("a stale wait from a project switched away from never marks the new project ready", async () => {
+      // beginTimelineSession no-ops when projectId is unchanged, so pin a
+      // known starting project first rather than relying on reset()'s
+      // leftover timelineProjectId from whatever test ran before this one.
+      usePlayerStore.getState().beginTimelineSession("readiness-test-project-a");
+      const { doc: docA, video: videoA } = stalledVideoDoc();
+      usePlayerStore.getState().requestTimelineReady(docA);
+
+      // Switches projects mid-wait — beginTimelineSession resets timelineReady
+      // to false for project B, whose own media has not been checked at all.
+      usePlayerStore.getState().beginTimelineSession("readiness-test-project-b");
+      expect(usePlayerStore.getState().timelineReady).toBe(false);
+
+      // A's wait settles late; it must not resolve into B's readiness.
+      videoA.dispatchEvent(new Event("canplay"));
+      await new Promise((resolve) => setTimeout(resolve, 0));
+
+      expect(usePlayerStore.getState().timelineReady).toBe(false);
+    });
+  });
+
   describe("setElements", () => {
     it("sets the elements array", () => {
       const elements: TimelineElement[] = [

package/src/player/store/playerStore.ts

@@ -19,6 +19,7 @@ import {
 import { createEditingModeSlice, type EditingModeSlice } from "./editingModeSlice";
 import { createTimelineFocusRequest, type TimelineFocusRequest } from "./timelineFocusState";
 import { createThumbnailSlice, type ThumbnailSlice } from "./thumbnailSlice";
+import { createPlaybackReadinessSlice, resetPlaybackReadinessState } from "./readinessSlice";
 
 export type { KeyframeCacheEntry } from "./keyframeSlice";
 export { liveTime } from "./liveTime";
@@ -54,12 +55,15 @@ function resolveElementSelection(
   };
 }
 
-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. */
@@ -129,7 +133,6 @@ interface PlayerState
   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;
@@ -260,7 +263,7 @@ export function createTimelineResetState() {
     isPlaying: false,
     currentTime: 0,
     duration: 0,
-    timelineReady: false,
+    ...resetPlaybackReadinessState(),
     beatDragging: false,
     elements: [],
     selectedElementId: null,
@@ -304,7 +307,6 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
   isPlaying: false,
   currentTime: 0,
   duration: 0,
-  timelineReady: false,
   timelineSessionEpoch: 0,
   timelineProjectId: null,
   beatDragging: false,
@@ -333,6 +335,7 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
 
   ...createAutomationSelectionSlice(set),
   ...createEditingModeSlice(set),
+  ...createPlaybackReadinessSlice(set),
 
   activeKeyframePct: null,
   setActiveKeyframePct: (pct) => set({ activeKeyframePct: pct }),
@@ -521,7 +524,6 @@ export const usePlayerStore = create<PlayerState>((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

package/src/player/store/readinessSlice.ts

@@ -0,0 +1,42 @@
+/** 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. */
+import type { StoreApi } from "zustand";
+import { settleCompositionReadiness } from "@hyperframes/core/composition-readiness";
+
+export 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;
+}
+
+let timelineReadyGeneration = 0;
+
+/** For a full timeline reset: bumps the generation so any requestTimelineReady
+ * wait in flight can never resolve into what replaced it. */
+export function resetPlaybackReadinessState(): Pick<PlaybackReadinessSlice, "timelineReady"> {
+  timelineReadyGeneration++;
+  return { timelineReady: false };
+}
+
+export function createPlaybackReadinessSlice(
+  set: StoreApi<PlaybackReadinessSlice>["setState"],
+): PlaybackReadinessSlice {
+  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 });
+      });
+    },
+  };
+}

package/src/utils/sdkCutover.gate.test.ts

@@ -1,11 +1,12 @@
 import { describe, expect, it, vi } from "vitest";
 
-// Dark-launch contract: with STUDIO_SDK_CUTOVER_ENABLED=false, EVERY cutover
+// Kill-switch contract: with VITE_STUDIO_SDK_CUTOVER_ENABLED=false, EVERY cutover
 // persist chokepoint must explicitly decline so the caller takes the legacy server
 // path — even when a valid SDK session exists (one always does, for
-// shadow/selection). This is the contract the prod flag-flip rests on; a future
-// refactor of the gate guards that silently re-enables cutover on flag-off
-// turns these red. (sdkCutover.test.ts mocks the flag TRUE; this is its sibling.)
+// shadow/selection). Default is ON (manualEditingAvailability.test.ts pins that);
+// this file pins that the env override still turns it fully off. A future
+// refactor of the gate guards that ignores the flag turns these red.
+// (sdkCutover.test.ts mocks the flag TRUE; this is its sibling.)
 vi.mock("../components/editor/manualEditingAvailability", () => ({
   STUDIO_SDK_CUTOVER_ENABLED: false,
   STUDIO_SDK_RESOLVER_SHADOW_ENABLED: false,

package/src/utils/sdkCutover.test.ts

@@ -23,6 +23,8 @@ vi.mock("./studioTelemetry", () => ({
   trackStudioEvent: vi.fn(),
 }));
 
+import { trackStudioEvent } from "./studioTelemetry";
+
 const styleOp = (property: string, value: string): PatchOperation => ({
   type: "inline-style",
   property,
@@ -202,6 +204,46 @@ describe("sdkCutoverPersist", () => {
     expect(result.status).toBe("declined");
   });
 
+  it("tags target_not_found with resolverDisagreement when dispatch could have resolved it", async () => {
+    // getElement is canonical-only for a bare id; resolveSnapshot mirrors what
+    // dispatch resolves (bare ids anywhere). An element present under a scoped
+    // id is dispatchable, so getElement refusing it is a resolver disagreement
+    // — and one the shadow event stays silent about.
+    const deps = makeDeps();
+    const session = makeSession(false);
+    (session as unknown as { getElements: () => unknown[] }).getElements = () => [
+      { id: "hf-abc", scopedId: "host/hf-abc" },
+    ];
+    const sel = { hfId: "hf-abc" } as never;
+
+    await sdkCutoverPersist(sel, [styleOp("color", "red")], "before", "/path.html", session, deps);
+
+    expect(trackStudioEvent).toHaveBeenCalledWith(
+      "sdk_cutover_declined",
+      expect.objectContaining({ reason: "target_not_found", resolverDisagreement: true }),
+    );
+  });
+
+  it("does not tag resolverDisagreement when the element is genuinely absent", async () => {
+    const deps = makeDeps();
+    const session = makeSession(false);
+    (session as unknown as { getElements: () => unknown[] }).getElements = () => [
+      { id: "hf-other", scopedId: "hf-other" },
+    ];
+    const sel = { hfId: "hf-abc" } as never;
+    vi.mocked(trackStudioEvent).mockClear();
+
+    await sdkCutoverPersist(sel, [styleOp("color", "red")], "before", "/path.html", session, deps);
+
+    expect(trackStudioEvent).toHaveBeenLastCalledWith(
+      "sdk_cutover_declined",
+      expect.objectContaining({ reason: "target_not_found" }),
+    );
+    expect(vi.mocked(trackStudioEvent).mock.lastCall?.[1]).not.toHaveProperty(
+      "resolverDisagreement",
+    );
+  });
+
   it("dispatches setStyle for inline-style ops", async () => {
     const deps = makeDeps();
     const session = makeSession(true);