@hyperframes/studio 0.9.2 → 0.9.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/player.js CHANGED
@@ -1,6 +1,6 @@
1
1
  import {
2
2
  Player
3
- } from "./chunk-CM72ZNGU.js";
3
+ } from "./chunk-LBXOFI5I.js";
4
4
  import "./chunk-7HZGKFFU.js";
5
5
  import "./chunk-OGIOFEC7.js";
6
6
  import "./chunk-MLKGABMK.js";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hyperframes/studio",
3
- "version": "0.9.2",
3
+ "version": "0.9.3",
4
4
  "description": "",
5
5
  "repository": {
6
6
  "type": "git",
@@ -60,12 +60,12 @@
60
60
  "dockview-react": "8.3.1",
61
61
  "gsap": "^3.13.0",
62
62
  "mediabunny": "^1.45.3",
63
- "@hyperframes/core": "0.9.2",
64
- "@hyperframes/parsers": "0.9.2",
65
- "@hyperframes/player": "0.9.2",
66
- "@hyperframes/shader-transitions": "0.9.2",
67
- "@hyperframes/studio-server": "0.9.2",
68
- "@hyperframes/sdk": "0.9.2"
63
+ "@hyperframes/player": "0.9.3",
64
+ "@hyperframes/parsers": "0.9.3",
65
+ "@hyperframes/shader-transitions": "0.9.3",
66
+ "@hyperframes/sdk": "0.9.3",
67
+ "@hyperframes/core": "0.9.3",
68
+ "@hyperframes/studio-server": "0.9.3"
69
69
  },
70
70
  "devDependencies": {
71
71
  "@tailwindcss/vite": "^4.3.3",
@@ -82,7 +82,7 @@
82
82
  "vite": "^6.4.2",
83
83
  "vitest": "^4.1.11",
84
84
  "zustand": "^5.0.0",
85
- "@hyperframes/producer": "0.9.2"
85
+ "@hyperframes/producer": "0.9.3"
86
86
  },
87
87
  "peerDependencies": {
88
88
  "react": "19",
@@ -20,6 +20,7 @@ import {
20
20
  } from "./useTimelineSyncCallbacks";
21
21
  import type { IframeWindow, PlaybackAdapter } from "../lib/playbackTypes";
22
22
  import { setPreviewReloading } from "../previewReloading";
23
+ import { studioFileRevision } from "../../utils/studioFileVersion";
23
24
  import { announcePreviewPromoted } from "../sceneSwap";
24
25
  import { afterStudioPendingEdits, isStudioEditSaving } from "../../utils/studioPendingEdits";
25
26
  import { usePlayerStore } from "../store/playerStore";
@@ -117,6 +118,7 @@ export function useShadowPreviewReload({
117
118
  const stopHoldRef = useRef<() => void>(() => {});
118
119
  const shadowUrlRef = useRef("");
119
120
  const savesAtRequestRef = useRef(0);
121
+ const revisionAtRequestRef = useRef(0);
120
122
  const beginShadowReloadRef = useRef<(url: string) => void>(() => {});
121
123
  const retry = useShadowReloadRetry(shadowGenRef, shadowUrlRef, beginShadowReloadRef);
122
124
  const promoteWhenReadyRef = useRef<(gen: number) => void>(() => {});
@@ -179,8 +181,8 @@ export function useShadowPreviewReload({
179
181
  [],
180
182
  );
181
183
 
182
- // Nothing replaces the preview under a gesture, and a shadow requested before a gesture's save
183
- // shows the file before it: once that save has landed, a fresh one loads instead.
184
+ // Nothing replaces the preview under a gesture, and a shadow requested before a write
185
+ // shows the file before it: once that write has landed, a fresh one loads instead.
184
186
  const heldOrStale = useCallback(
185
187
  (gen: number) => {
186
188
  const liveDoc = iframeRef.current?.contentDocument;
@@ -188,7 +190,11 @@ export function useShadowPreviewReload({
188
190
  return waitThenRetry(gen, "gesture", (retry) =>
189
191
  afterStudioManualEditGestures(liveDoc, retry),
190
192
  );
191
- if (gestureSavesOnScreen() === savesAtRequestRef.current) return false;
193
+ if (
194
+ gestureSavesOnScreen() === savesAtRequestRef.current &&
195
+ studioFileRevision() === revisionAtRequestRef.current
196
+ )
197
+ return false;
192
198
  if (isStudioEditSaving()) return waitThenRetry(gen, "save", afterStudioPendingEdits);
193
199
  logReload("shadow-reloaded-after-gesture-save", { gen });
194
200
  const url = new URL(shadowUrlRef.current, window.location.origin);
@@ -335,6 +341,7 @@ export function useShadowPreviewReload({
335
341
  budgetsSpentRef.current = 0;
336
342
  shadowUrlRef.current = url;
337
343
  savesAtRequestRef.current = gestureSavesOnScreen();
344
+ revisionAtRequestRef.current = studioFileRevision();
338
345
  armReadyTimer(gen);
339
346
  setPreviewSlots((prev) => planShadowReload(prev, gen, url));
340
347
  // Thumbnails of the edit wait for the new preview instead of competing with it.
@@ -8,6 +8,7 @@ import { SHADOW_READY_BUDGETS, SHADOW_READY_TIMEOUT_MS } from "./useShadowPrevie
8
8
  import { refusedPreviewMessage } from "@hyperframes/core/studio-preview-mark";
9
9
  import { usePlayerStore } from "../store/playerStore";
10
10
  import { isPreviewChanging } from "../previewReloading";
11
+ import { studioWriteHeaders } from "../../utils/studioFileVersion";
11
12
  import { NLEProvider, useNLEContext, type NLEContextValue } from "../../components/nle/NLEContext";
12
13
  import {
13
14
  makeAdapterWindow,
@@ -939,6 +940,32 @@ function stubVisibility(initial: DocumentVisibilityState) {
939
940
  };
940
941
  }
941
942
 
943
+ describe("a shadow reload loading while a write lands", () => {
944
+ it("loads the file again instead of promoting the one it asked for", () => {
945
+ const { getApi, root } = renderTimelinePlayerHarness();
946
+ const liveIframe = makeLiveIframe();
947
+ act(() => {
948
+ getApi().iframeRef.current = liveIframe;
949
+ getApi().onIframeLoad();
950
+ });
951
+ act(() => getApi().refreshPlayer());
952
+ const asked = getApi().previewSlots.find((slot) => slot.role === "shadow")!;
953
+ act(() => getApi().setShadowIframeNode(makeLiveIframe()));
954
+
955
+ // An undo writes while that shadow is still loading.
956
+ studioWriteHeaders();
957
+ act(() => {
958
+ getApi().onShadowIframeLoad(asked.gen);
959
+ getApi().onShadowReadyChange(asked.gen, true);
960
+ });
961
+
962
+ expect(getApi().iframeRef.current).toBe(liveIframe);
963
+ const loading = getApi().previewSlots.find((slot) => slot.role === "shadow")!;
964
+ expect(loading.gen).not.toBe(asked.gen);
965
+ unmount(root);
966
+ });
967
+ });
968
+
942
969
  describe("useTimelinePlayer scene swap", () => {
943
970
  function liveFilm(swap?: (html: string) => Promise<void>) {
944
971
  const { adapter, win } = makeAdapterWindow();
@@ -985,6 +1012,46 @@ describe("useTimelinePlayer scene swap", () => {
985
1012
  expect(isPreviewChanging()).toBe(false);
986
1013
  });
987
1014
 
1015
+ it("swaps the composition as it is now when a write lands while the HTML is loading", async () => {
1016
+ const swap = vi.fn(async () => {});
1017
+ const replies: Array<(r: Response) => void> = [];
1018
+ const bodies = ["<html>undone-once</html>", "<html>undone-twice</html>"];
1019
+ vi.spyOn(globalThis, "fetch").mockImplementation(
1020
+ () => new Promise<Response>((resolve) => replies.push(resolve)),
1021
+ );
1022
+ const { getApi } = liveFilm(swap);
1023
+
1024
+ act(() => getApi().refreshPlayer());
1025
+ // A second undo writes while the first one's preview HTML is still loading.
1026
+ studioWriteHeaders();
1027
+ replies[0]!(new Response(bodies[0]));
1028
+ await settle();
1029
+
1030
+ expect(swap).not.toHaveBeenCalledWith(bodies[0], expect.anything());
1031
+ expect(replies).toHaveLength(2);
1032
+ replies[1]!(new Response(bodies[1]));
1033
+ await settle();
1034
+ expect(swap).toHaveBeenCalledWith(bodies[1], expect.anything());
1035
+ });
1036
+
1037
+ it("gives up refetching and swaps what it has when writes never stop", async () => {
1038
+ const swap = vi.fn(async () => {});
1039
+ let fetches = 0;
1040
+ // The project stops moving well past the bound, so a swap that never gave up still ends.
1041
+ vi.spyOn(globalThis, "fetch").mockImplementation(async () => {
1042
+ fetches += 1;
1043
+ if (fetches < 20) studioWriteHeaders();
1044
+ return new Response("<html>vN</html>");
1045
+ });
1046
+ const { getApi } = liveFilm(swap);
1047
+
1048
+ act(() => getApi().refreshPlayer());
1049
+ await settle();
1050
+
1051
+ expect(fetches).toBe(6);
1052
+ expect(swap).toHaveBeenCalledWith("<html>vN</html>", expect.anything());
1053
+ });
1054
+
988
1055
  it("falls back to the full reload when the preview refuses the swap", async () => {
989
1056
  vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response("<html>v2</html>"));
990
1057
  const { getApi } = liveFilm(async () => {
@@ -43,8 +43,7 @@ import { createPreviewMessageHandler } from "./previewMessageRouter";
43
43
  import { usePreviewQualityForwarding } from "./usePreviewQualityForwarding";
44
44
  import { timelineElementsChanged } from "./timelinePlayerSync";
45
45
  import { safeContentDocument } from "./timelineSyncHydration";
46
- import { sceneSwapFor, supersededByNewerEdit } from "../sceneSwap";
47
- import { whileScriptWrites } from "../previewReloading";
46
+ import { sceneSwapFor, supersededByNewerEdit, swapFreshly } from "../sceneSwap";
48
47
 
49
48
  export interface UseTimelinePlayerOptions {
50
49
  /** Runs right after a reloaded preview becomes the live iframe. */
@@ -506,13 +505,7 @@ export function useTimelinePlayer({
506
505
  !!iframe.contentDocument && isStudioManualEditGestureLiveIn(iframe.contentDocument);
507
506
  if (!swap || isRefreshingRef.current || swapWouldReplaceGestureNode)
508
507
  return reloadWholeFilm(url.toString());
509
- whileScriptWrites(() => swap(url.toString(), isCurrent, cancel.signal)).catch(
510
- (error: unknown) => {
511
- if (!isCurrent()) return;
512
- logReload("scene-swap-refused", { reason: String(error) });
513
- reloadWholeFilm(url.toString());
514
- },
515
- );
508
+ swapFreshly(swap, url, isCurrent, cancel.signal, reloadWholeFilm);
516
509
  }, [reloadWholeFilm, previewGeneration]);
517
510
  const pauseRef = useRef(pause);
518
511
  pauseRef.current = pause;
@@ -1,4 +1,8 @@
1
1
  import { studioApiFetch } from "../utils/studioApiFetch";
2
+ import { studioFileRevision } from "../utils/studioFileVersion";
3
+ import { logReload } from "../utils/reloadDebug";
4
+ import { whileScriptWrites } from "./previewReloading";
5
+
2
6
  type SwapWindow = Window & {
3
7
  __hfSwapScenes?: (html: string, signal?: AbortSignal) => Promise<void>;
4
8
  };
@@ -74,6 +78,38 @@ export function markScenesStale(iframe: HTMLIFrameElement | null, files: readonl
74
78
  export const supersededByNewerEdit = () =>
75
79
  new DOMException("superseded by a newer edit", "AbortError");
76
80
 
81
+ const SWAP_REFETCHES_BEFORE_THE_COPY_IN_HAND_WINS = 5;
82
+
83
+ type SceneSwap = (url: string, isCurrent: () => boolean, cancel?: AbortSignal) => Promise<void>;
84
+
85
+ export function swapFreshly(
86
+ swap: SceneSwap,
87
+ url: URL,
88
+ isCurrent: () => boolean,
89
+ cancel: AbortSignal,
90
+ reloadWholeFilm: (url: string) => void,
91
+ attempt = 0,
92
+ ): void {
93
+ const at = studioFileRevision();
94
+ const fresh = () => studioFileRevision() === at;
95
+ const again = () => {
96
+ url.searchParams.set("_t", String(Date.now()));
97
+ swapFreshly(swap, url, isCurrent, cancel, reloadWholeFilm, attempt + 1);
98
+ };
99
+ const retries = attempt < SWAP_REFETCHES_BEFORE_THE_COPY_IN_HAND_WINS;
100
+ const gate = retries ? () => isCurrent() && fresh() : isCurrent;
101
+ whileScriptWrites(() => swap(url.toString(), gate, cancel))
102
+ .then(() => {
103
+ if (isCurrent() && !fresh() && retries) again();
104
+ })
105
+ .catch((error: unknown) => {
106
+ if (!isCurrent()) return;
107
+ if (!fresh() && retries) return again();
108
+ logReload("scene-swap-refused", { reason: String(error) });
109
+ reloadWholeFilm(url.toString());
110
+ });
111
+ }
112
+
77
113
  /** Null when the preview cannot swap; rejects when superseded, cancelled or a full reload is needed. */
78
114
  export function sceneSwapFor(
79
115
  iframe: HTMLIFrameElement,
@@ -6,6 +6,7 @@ import {
6
6
  resetStudioWriteTokens,
7
7
  studioExpectedFileVersion,
8
8
  studioFileContentVersion,
9
+ studioFileRevision,
9
10
  studioWriteHeaders,
10
11
  } from "./studioFileVersion";
11
12
 
@@ -96,4 +97,18 @@ describe("studio write-token echo identity", () => {
96
97
  markStudioWriteToken("abandoned-studio-write", 1_000);
97
98
  expect(consumeStudioWriteToken("abandoned-studio-write", 301_000)).toBe(false);
98
99
  });
100
+
101
+ it("moves the file revision once per write claimed, and not for its echo", () => {
102
+ resetStudioWriteTokens();
103
+ const start = studioFileRevision();
104
+ markStudioWriteToken("revision-write");
105
+
106
+ expect(studioFileRevision()).toBe(start + 1);
107
+ // The echo of a write already counted must not move it again: a reader asked for after the
108
+ // write was claimed would read as stale on its own echo and fetch a second time for nothing.
109
+ expect(consumeStudioWriteToken("revision-write")).toBe(true);
110
+ expect(studioFileRevision()).toBe(start + 1);
111
+ markStudioWriteToken("second-write");
112
+ expect(studioFileRevision()).toBe(start + 2);
113
+ });
99
114
  });
@@ -2,6 +2,12 @@
2
2
  // retries, and the subsequent file-change echo without retaining abandoned tokens forever.
3
3
  const WRITE_TOKEN_TTL_MS = 5 * 60_000;
4
4
  const studioWriteTokens = new Map<string, number>();
5
+ let fileRevision = 0;
6
+
7
+ /** One step per write Studio claims: a copy of the project read at a lower revision is stale. */
8
+ export function studioFileRevision(): number {
9
+ return fileRevision;
10
+ }
5
11
 
6
12
  function pruneStudioWriteTokens(now: number): void {
7
13
  for (const [token, createdAt] of studioWriteTokens) {
@@ -13,6 +19,7 @@ function pruneStudioWriteTokens(now: number): void {
13
19
  export function markStudioWriteToken(token: string, now: number = Date.now()): void {
14
20
  pruneStudioWriteTokens(now);
15
21
  studioWriteTokens.set(token, now);
22
+ fileRevision += 1;
16
23
  }
17
24
 
18
25
  /** Consumed by the external-change coordinator introduced in stack PR #2991. */