@hyperframes/studio 0.9.2 → 0.9.4

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.4",
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/core": "0.9.4",
64
+ "@hyperframes/player": "0.9.4",
65
+ "@hyperframes/sdk": "0.9.4",
66
+ "@hyperframes/shader-transitions": "0.9.4",
67
+ "@hyperframes/studio-server": "0.9.4",
68
+ "@hyperframes/parsers": "0.9.4"
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.4"
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,
@@ -1,4 +1,5 @@
1
1
  import { COLOR_GRADING_SOURCE_HIDDEN_ATTR } from "@hyperframes/core/color-grading";
2
+ import { parseGsapScript } from "@hyperframes/parsers/gsap-parser";
2
3
  import { GSAP_BASE_URL_META, motionPathPluginUrl } from "@hyperframes/core/gsap-cdn";
3
4
  import { findAuthoredElement } from "./authoredSource";
4
5
  import { applyAuthoredInlineOpacity, readStampedAuthoredOpacity } from "./authoredOpacity";
@@ -298,6 +299,40 @@ export function applySoftReloadFinalization(
298
299
  }
299
300
  }
300
301
 
302
+ const animatedBy = (doc: Document, scriptText: string): Set<Element> => {
303
+ const animated = new Set<Element>();
304
+ for (const { targetSelector } of parseGsapScript(scriptText).animations) {
305
+ try {
306
+ for (const element of doc.querySelectorAll(targetSelector)) animated.add(element);
307
+ } catch {
308
+ // A selector this document cannot parse animates nothing in it.
309
+ }
310
+ }
311
+ return animated;
312
+ };
313
+
314
+ /** Authored style back on the elements the restored script stops animating, before a reload lands. */
315
+ export function repaintDroppedTweenStyle(
316
+ win: IframeWindow,
317
+ doc: Document,
318
+ authored: Document,
319
+ targetKeys: string[],
320
+ restoredScript: string | null,
321
+ ): void {
322
+ const live = findGsapScriptElements(doc)
323
+ .map((script) => script.textContent ?? "")
324
+ .join("");
325
+ if (live === (restoredScript ?? "")) return;
326
+ const kept = restoredScript ? animatedBy(doc, restoredScript) : new Set<Element>();
327
+ for (const [element, tweened] of collectResetTargets(win, doc, targetKeys)) {
328
+ if (kept.has(element)) continue;
329
+ const source = findAuthoredElement(authored, element);
330
+ const style =
331
+ source instanceof HTMLElement || source instanceof SVGElement ? source.style : null;
332
+ restoreAuthoredStyle((element as HTMLElement).style, style, tweened);
333
+ }
334
+ }
335
+
301
336
  export function timelineKeys(scriptText: string): string[] {
302
337
  return [...scriptText.matchAll(/__timelines\s*\[\s*["'`]([^"'`]+)["'`]\s*\]/g)]
303
338
  .map((m) => m[1]!)
@@ -115,6 +115,50 @@ function buildLiveIframe(bodyHtml: string) {
115
115
  describe("applyUndoRestoreToPreview", () => {
116
116
  const ROOT = "index.html";
117
117
 
118
+ it("takes GSAP's composed transform off the preview it is about to reload", () => {
119
+ // Undoing "enable keyframes" removes the script: no in-place patch expresses that, so the
120
+ // preview reloads — and until it lands it shows where the timeline last put the box, though
121
+ // the file it is going back to places it with CSS and no inline transform at all.
122
+ const tween = `window.__timelines["root"]=gsap.timeline().to("#a",{x:139.893,y:-195.508});`;
123
+ const film = (box: string, script: string) =>
124
+ `<div data-composition-id="root"><div id="a"${box}>a</div></div>${script}`;
125
+ const composed = ` style="transform: translate(139.893px, -195.508px)"`;
126
+ const { iframe, doc } = buildLiveIframe(film(composed, `<script>${tween}</script>`));
127
+ recordLiveSet(doc.getElementById("a")!, { x: 139.893, y: -195.508 });
128
+ const files = {
129
+ [ROOT]: {
130
+ previous: wrap(film("", `<script>${tween}</script>`)),
131
+ restored: wrap(film("", "")),
132
+ },
133
+ };
134
+
135
+ expect(applyUndoRestoreToPreview(iframe, ROOT, files, 3, vi.fn())).toBe("full");
136
+
137
+ expect(doc.getElementById("a")!.style.transform).toBe("");
138
+ });
139
+
140
+ it("leaves a still-animated element alone when the restore only removes another", () => {
141
+ // Nothing about the animation changed: #a is where the live timeline put it, and the reload
142
+ // re-renders it. Clearing it here would flash the box back to its authored place first.
143
+ const script = `window.__timelines["root"]=gsap.timeline().to("#a",{x:100});`;
144
+ const film = (body: string) =>
145
+ `<div data-composition-id="root">${body}</div><script>${script}</script>`;
146
+ const { iframe, doc } = buildLiveIframe(
147
+ film(`<div id="a" style="transform: translate(100px, 0px)">a</div><div id="b">b</div>`),
148
+ );
149
+ recordLiveSet(doc.getElementById("a")!, { x: 100 });
150
+ const files = {
151
+ [ROOT]: {
152
+ previous: wrap(film(`<div id="a">a</div><div id="b">b</div>`)),
153
+ restored: wrap(film(`<div id="a">a</div>`)),
154
+ },
155
+ };
156
+
157
+ expect(applyUndoRestoreToPreview(iframe, ROOT, files, 3, vi.fn())).toBe("full");
158
+
159
+ expect(doc.getElementById("a")!.style.transform).toBe("translate(100px, 0px)");
160
+ });
161
+
118
162
  it("never stamps an undo whose sides are both already stamped", () => {
119
163
  const film = (color: string) =>
120
164
  `<div id="root" data-composition-id="root"><div id="target" style="background-color: ${color}">T</div><p>caption</p></div>`;
@@ -8,6 +8,8 @@ import {
8
8
  extractGsapScriptText,
9
9
  findGsapScriptElements,
10
10
  readNestedFiles,
11
+ repaintDroppedTweenStyle,
12
+ timelineKeys,
11
13
  } from "./gsapSoftReload";
12
14
  import { ensureHfIds, isCompositionTemplate } from "@hyperframes/parsers/hf-ids";
13
15
  import { findAuthoredElement, parseSavedSource } from "./authoredSource";
@@ -341,6 +343,19 @@ export function readUndoNestedFiles(
341
343
  return script ? readNestedFiles(iframe, script, readFile) : null;
342
344
  }
343
345
 
346
+ /** A preview about to reload still shows the timeline's last composed transform; take it back to the file. */
347
+ function repaintWhileReloading(win: PreviewWindow, doc: Document, restored?: string): void {
348
+ const keys = findGsapScriptElements(doc).flatMap((s) => timelineKeys(s.textContent ?? ""));
349
+ if (!restored || keys.length === 0) return;
350
+ repaintDroppedTweenStyle(
351
+ win,
352
+ doc,
353
+ parseRestoreSource(restored),
354
+ keys,
355
+ extractGsapScriptText(restored),
356
+ );
357
+ }
358
+
344
359
  /**
345
360
  * Soft-apply an undo/redo restore to the live preview WITHOUT a full iframe
346
361
  * remount (which blanks the frame black and re-flashes the WebGL context). Eligible
@@ -391,6 +406,7 @@ export function applyUndoRestoreToPreview(
391
406
  const win = iframe?.contentWindow as PreviewWindow | null;
392
407
  const plan = doc && files && win ? planRestoreTargets(doc, activeDocPath, files) : null;
393
408
  if (!iframe || !doc || !files || !win || !plan) {
409
+ if (doc && win) repaintWhileReloading(win, doc, files?.[activeDocPath]?.restored);
394
410
  reloadPreview();
395
411
  return "full";
396
412
  }
@@ -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. */