@hyperframes/studio 0.8.201 → 0.8.203

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-J6T4KD7Y.js";
3
+ } from "./chunk-2YCKGJFD.js";
4
4
  import "./chunk-7HZGKFFU.js";
5
5
  import "./chunk-T43DM7Q6.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.8.201",
3
+ "version": "0.8.203",
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.8.201",
64
- "@hyperframes/player": "0.8.201",
65
- "@hyperframes/parsers": "0.8.201",
66
- "@hyperframes/sdk": "0.8.201",
67
- "@hyperframes/shader-transitions": "0.8.201",
68
- "@hyperframes/studio-server": "0.8.201"
63
+ "@hyperframes/core": "0.8.203",
64
+ "@hyperframes/parsers": "0.8.203",
65
+ "@hyperframes/player": "0.8.203",
66
+ "@hyperframes/sdk": "0.8.203",
67
+ "@hyperframes/shader-transitions": "0.8.203",
68
+ "@hyperframes/studio-server": "0.8.203"
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.8.201"
85
+ "@hyperframes/producer": "0.8.203"
86
86
  },
87
87
  "peerDependencies": {
88
88
  "react": "19",
package/src/index.ts CHANGED
@@ -34,6 +34,13 @@ export {
34
34
  formatTime,
35
35
  } from "./player";
36
36
  export { usePreviewIframeStore } from "./player/store/previewIframeStore";
37
+ export { PREVIEW_QUALITY_LEVELS, type PreviewQuality } from "@hyperframes/core/preview-quality";
38
+ export type {
39
+ PlaybackHealth,
40
+ PreviewCopies,
41
+ PreviewFacts,
42
+ PreviewQualityChosenBy,
43
+ } from "./player/store/previewQualitySlice";
37
44
  export {
38
45
  openAudioGainDialog,
39
46
  useAudioGainDialogStore,
@@ -1,4 +1,5 @@
1
1
  import { describe, expect, it, vi } from "vitest";
2
+ import { usePlayerStore } from "../store/playerStore";
2
3
  import { createPreviewMessageHandler } from "./previewMessageRouter";
3
4
 
4
5
  function route(isPlaying: boolean) {
@@ -21,3 +22,84 @@ describe("preview state messages", () => {
21
22
  expect(route(false)).toHaveBeenCalledTimes(1);
22
23
  });
23
24
  });
25
+
26
+ describe("preview quality messages", () => {
27
+ function routeMessage(data: unknown, frame?: { postMessage: (message: unknown) => void }) {
28
+ const iframe = frame ? ({ contentWindow: frame } as unknown as HTMLIFrameElement) : null;
29
+ createPreviewMessageHandler({
30
+ iframeRef: { current: iframe },
31
+ processTimelineMessageRef: { current: vi.fn() },
32
+ enrichMissingCompositionsRef: { current: vi.fn() },
33
+ lastTimelineMessageRef: { current: 0 },
34
+ getAdapter: () => null,
35
+ syncTimelineElements: vi.fn(),
36
+ })(new MessageEvent("message", { data }));
37
+ }
38
+
39
+ it("keeps what the preview says about its lighter copies, and clears it when it says none", () => {
40
+ routeMessage({
41
+ source: "hf-preview",
42
+ type: "preview-copies",
43
+ copies: { total: 3, ready: 1, failed: 0, progress: 0.5, error: null },
44
+ });
45
+ expect(usePlayerStore.getState().previewCopies).toEqual({
46
+ total: 3,
47
+ ready: 1,
48
+ failed: 0,
49
+ progress: 0.5,
50
+ error: null,
51
+ });
52
+
53
+ routeMessage({ source: "hf-preview", type: "preview-copies", copies: null });
54
+ expect(usePlayerStore.getState().previewCopies).toBeNull();
55
+ });
56
+
57
+ it("keeps the preview's playback health, and clears it when the preview says none", () => {
58
+ const health = {
59
+ droppedShare: 0.4,
60
+ seconds: 3,
61
+ choppy: true,
62
+ fps: 18,
63
+ worstFrameMs: 90,
64
+ mode: "play",
65
+ };
66
+ routeMessage({ source: "hf-preview", type: "preview-health", health });
67
+ expect(usePlayerStore.getState().playbackHealth).toEqual(health);
68
+
69
+ routeMessage({ source: "hf-preview", type: "preview-health", health: null });
70
+ expect(usePlayerStore.getState().playbackHealth).toBeNull();
71
+ });
72
+
73
+ it("keeps the preview's facts and drops a malformed answer", () => {
74
+ const facts = {
75
+ sceneCount: 2,
76
+ mountedElementCount: 120,
77
+ durationSeconds: 30,
78
+ videos: [{ codec: "hevc", width: 3840, height: 2160, bitDepth: 10, count: 2 }],
79
+ lighterAt: [0.25, 0.125],
80
+ copiesReady: true,
81
+ };
82
+ routeMessage({ source: "hf-preview", type: "preview-facts", facts });
83
+ expect(usePlayerStore.getState().previewFacts).toEqual(facts);
84
+
85
+ routeMessage({
86
+ source: "hf-preview",
87
+ type: "preview-facts",
88
+ facts: { ...facts, sceneCount: "2" },
89
+ });
90
+ expect(usePlayerStore.getState().previewFacts).toBeNull();
91
+ });
92
+
93
+ it("sends the chosen quality to a preview that has just loaded", () => {
94
+ usePlayerStore.getState().setPreviewQuality(0.25);
95
+ const postMessage = vi.fn();
96
+
97
+ routeMessage({ source: "hf-preview", type: "ready" }, { postMessage });
98
+
99
+ expect(postMessage).toHaveBeenCalledWith(
100
+ expect.objectContaining({ action: "set-preview-quality", level: 0.25 }),
101
+ "*",
102
+ );
103
+ usePlayerStore.getState().setPreviewQuality(1);
104
+ });
105
+ });
@@ -12,7 +12,12 @@
12
12
  import { usePlayerStore, type TimelineElement } from "../store/playerStore";
13
13
  import type { ClipManifestClip, IframeWindow, PlaybackAdapter } from "../lib/playbackTypes";
14
14
  import { hasTimelinePerformanceFixtureLease } from "../lib/timelinePerformanceFixture";
15
- import { acceptStudioRuntimeMessage } from "../lib/runtimeProtocol";
15
+ import { acceptStudioRuntimeMessage, postRuntimeControlMessage } from "../lib/runtimeProtocol";
16
+ import {
17
+ parsePlaybackHealth,
18
+ parsePreviewCopies,
19
+ parsePreviewFacts,
20
+ } from "../store/previewQualitySlice";
16
21
  import { parseTimelineFromDOM } from "../lib/timelineDOM";
17
22
 
18
23
  /** What `processTimelineMessage` accepts — the clip-manifest postMessage. */
@@ -30,6 +35,9 @@ interface PreviewMessage {
30
35
  type?: string;
31
36
  clips?: unknown;
32
37
  isPlaying?: unknown;
38
+ copies?: unknown;
39
+ health?: unknown;
40
+ facts?: unknown;
33
41
  }
34
42
 
35
43
  export interface PreviewMessageRouterDeps {
@@ -107,6 +115,23 @@ function handleTimelineMessage(
107
115
  } catch {}
108
116
  }
109
117
 
118
+ function applyStoreReport(data: PreviewMessage): boolean {
119
+ const store = usePlayerStore.getState();
120
+ switch (data.type) {
121
+ case "preview-copies":
122
+ store.setPreviewCopies(parsePreviewCopies(data.copies));
123
+ return true;
124
+ case "preview-health":
125
+ store.setPlaybackHealth(parsePlaybackHealth(data.health));
126
+ return true;
127
+ case "preview-facts":
128
+ store.setPreviewFacts(parsePreviewFacts(data.facts));
129
+ return true;
130
+ default:
131
+ return false;
132
+ }
133
+ }
134
+
110
135
  export function createPreviewMessageHandler(
111
136
  deps: PreviewMessageRouterDeps,
112
137
  ): (e: MessageEvent) => void {
@@ -115,6 +140,12 @@ export function createPreviewMessageHandler(
115
140
  const data = acceptedPreviewMessage(e, iframe);
116
141
  if (!data) return;
117
142
  if (data.type === "state") return handleStateMessage(deps, iframe, data.isPlaying === true);
143
+ if (applyStoreReport(data)) return;
144
+ if (data.type === "ready") {
145
+ const level = usePlayerStore.getState().previewQuality;
146
+ postRuntimeControlMessage(iframe?.contentWindow, "set-preview-quality", { level });
147
+ return;
148
+ }
118
149
  if (data.type === "timeline" && Array.isArray(data.clips)) {
119
150
  handleTimelineMessage(deps, iframe, data as unknown as ClipManifestMessage);
120
151
  }
@@ -0,0 +1,63 @@
1
+ // @vitest-environment happy-dom
2
+
3
+ import React, { act } from "react";
4
+ import { createRoot } from "react-dom/client";
5
+ import { afterEach, describe, expect, it, vi } from "vitest";
6
+ import { usePlayerStore } from "../store/playerStore";
7
+ import { usePreviewQualityForwarding } from "./usePreviewQualityForwarding";
8
+
9
+ (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
10
+
11
+ afterEach(() => {
12
+ document.body.innerHTML = "";
13
+ usePlayerStore.getState().setPreviewQuality(1);
14
+ });
15
+
16
+ function mount(frame: { postMessage: (message: unknown) => void } | null) {
17
+ const iframeRef = {
18
+ current: frame ? ({ contentWindow: frame } as unknown as HTMLIFrameElement) : null,
19
+ };
20
+ function Probe() {
21
+ usePreviewQualityForwarding(iframeRef);
22
+ return null;
23
+ }
24
+ const host = document.createElement("div");
25
+ document.body.append(host);
26
+ const root = createRoot(host);
27
+ act(() => root.render(React.createElement(Probe)));
28
+ return root;
29
+ }
30
+
31
+ const actions = (postMessage: ReturnType<typeof vi.fn>) =>
32
+ postMessage.mock.calls.map(([message]) => (message as { action: string }).action);
33
+
34
+ describe("usePreviewQualityForwarding", () => {
35
+ it("sends the level when it changes, and each retry, to the preview", () => {
36
+ const postMessage = vi.fn();
37
+ mount({ postMessage });
38
+
39
+ act(() => usePlayerStore.getState().setPreviewQuality(0.5));
40
+ expect(postMessage).toHaveBeenLastCalledWith(
41
+ expect.objectContaining({ action: "set-preview-quality", level: 0.5 }),
42
+ "*",
43
+ );
44
+
45
+ const before = postMessage.mock.calls.length;
46
+ act(() => usePlayerStore.getState().retryPreviewCopies());
47
+ expect(actions(postMessage).slice(before)).toEqual(["retry-preview-copies"]);
48
+ });
49
+
50
+ it("asks the preview for its facts each time they are requested", () => {
51
+ const postMessage = vi.fn();
52
+ mount({ postMessage });
53
+ const before = postMessage.mock.calls.length;
54
+
55
+ act(() => usePlayerStore.getState().requestPreviewFacts());
56
+ expect(actions(postMessage).slice(before)).toEqual(["request-preview-facts"]);
57
+ });
58
+
59
+ it("does nothing while there is no preview", () => {
60
+ mount(null);
61
+ expect(() => act(() => usePlayerStore.getState().setPreviewQuality(0.25))).not.toThrow();
62
+ });
63
+ });
@@ -0,0 +1,24 @@
1
+ import { useEffect, type RefObject } from "react";
2
+ import { usePlayerStore } from "../store/playerStore";
3
+ import { postRuntimeControlMessage } from "../lib/runtimeProtocol";
4
+
5
+ /** Sends the preview quality, and each retry, to the live preview; a reloaded preview asks again when it is ready. */
6
+ export function usePreviewQualityForwarding(iframeRef: RefObject<HTMLIFrameElement | null>): void {
7
+ const level = usePlayerStore((state) => state.previewQuality);
8
+ const retries = usePlayerStore((state) => state.previewCopiesRetry);
9
+ useEffect(() => {
10
+ const frame = iframeRef.current;
11
+ if (frame) postRuntimeControlMessage(frame.contentWindow, "set-preview-quality", { level });
12
+ }, [iframeRef, level]);
13
+ const factsRequests = usePlayerStore((state) => state.previewFactsRequests);
14
+ useEffect(() => {
15
+ const frame = iframeRef.current;
16
+ if (frame && factsRequests > 0)
17
+ postRuntimeControlMessage(frame.contentWindow, "request-preview-facts");
18
+ }, [iframeRef, factsRequests]);
19
+ useEffect(() => {
20
+ const frame = iframeRef.current;
21
+ if (frame && retries > 0)
22
+ postRuntimeControlMessage(frame.contentWindow, "retry-preview-copies");
23
+ }, [iframeRef, retries]);
24
+ }
@@ -40,6 +40,7 @@ import { shouldResumeForwardPlaybackAfterSeek, shouldStopAfterSeek } from "../li
40
40
  import { applyPreviewVariablesToUrl } from "../../hooks/previewVariablesStore";
41
41
  import { isStudioManualEditGestureLiveIn } from "../../components/editor/manualEditsDom";
42
42
  import { createPreviewMessageHandler } from "./previewMessageRouter";
43
+ import { usePreviewQualityForwarding } from "./usePreviewQualityForwarding";
43
44
  import { timelineElementsChanged } from "./timelinePlayerSync";
44
45
  import { safeContentDocument } from "./timelineSyncHydration";
45
46
  import { sceneSwapFor, supersededByNewerEdit } from "../sceneSwap";
@@ -55,6 +56,7 @@ export interface UseTimelinePlayerOptions {
55
56
  const publishSeek = (time: number, options?: { follow?: boolean }) =>
56
57
  options?.follow === false ? liveTime.notify(time) : liveTime.notifySeek(time);
57
58
 
59
+ // fallow-ignore-next-line complexity
58
60
  export function useTimelinePlayer({
59
61
  onShadowPromoted,
60
62
  onPreviewReloadFailed,
@@ -78,7 +80,6 @@ export function useTimelinePlayer({
78
80
  // The fixture lease belongs at this shared synchronization boundary so every
79
81
  // iframe discovery path has the same owner for deciding whether it may write.
80
82
  const syncTimelineElements = useCallback(
81
- // The lease guard adds one deliberate branch at the shared synchronization boundary.
82
83
  // fallow-ignore-next-line complexity
83
84
  (elements: TimelineElement[], nextDuration?: number) => {
84
85
  if (hasTimelinePerformanceFixtureLease()) return;
@@ -516,6 +517,8 @@ export function useTimelinePlayer({
516
517
  const pauseRef = useRef(pause);
517
518
  pauseRef.current = pause;
518
519
 
520
+ usePreviewQualityForwarding(iframeRef);
521
+
519
522
  useMountEffect(() => {
520
523
  const handleWindowKeyDown = (e: KeyboardEvent) => playbackKeyDownRef.current(e);
521
524
  const handleWindowKeyUp = (e: KeyboardEvent) => playbackKeyUpRef.current(e);
@@ -16,6 +16,7 @@ import {
16
16
  type AutomationSelectionSlice,
17
17
  } from "./automationSelectionSlice";
18
18
  import { createEditingModeSlice, type EditingModeSlice } from "./editingModeSlice";
19
+ import { createPreviewQualitySlice, type PreviewQualitySlice } from "./previewQualitySlice";
19
20
  import { createTimelineFocusRequest, type TimelineFocusRequest } from "./timelineFocusState";
20
21
  import { createThumbnailSlice, type ThumbnailSlice } from "./thumbnailSlice";
21
22
  import { createPlaybackReadinessSlice } from "./readinessSlice";
@@ -62,6 +63,7 @@ type PlayerStoreSlices = KeyframeSlice &
62
63
  AutomationSelectionSlice &
63
64
  ThumbnailSlice &
64
65
  EditingModeSlice &
66
+ PreviewQualitySlice &
65
67
  ReturnType<typeof createPlaybackReadinessSlice> &
66
68
  RangeSelectionSlice;
67
69
  interface PlayerState extends PlayerStoreSlices {
@@ -96,12 +98,10 @@ interface PlayerState extends PlayerStoreSlices {
96
98
  inPoint: number | null;
97
99
  /** Work-area out-point (seconds). When set, loop ends here and E jumps here. */
98
100
  outPoint: number | null;
99
-
100
101
  activeTool: TimelineTool;
101
102
  setActiveTool: (tool: TimelineTool) => void;
102
103
  selectLeftward: () => void;
103
104
  selectRightward: () => void;
104
-
105
105
  /** Tween-relative percentage of the last-clicked keyframe diamond. Operations
106
106
  * (drag, resize, rotate) target this instead of recomputing from playhead. */
107
107
  activeKeyframePct: number | null;
@@ -301,6 +301,7 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
301
301
 
302
302
  ...createAutomationSelectionSlice(set),
303
303
  ...createEditingModeSlice(set),
304
+ ...createPreviewQualitySlice(set, get),
304
305
  ...createRangeSelectionSlice(),
305
306
  ...createPlaybackReadinessSlice(set),
306
307
 
@@ -0,0 +1,72 @@
1
+ // @vitest-environment happy-dom
2
+
3
+ import { describe, expect, it } from "vitest";
4
+ import { usePlayerStore } from "./playerStore";
5
+ import { readStudioUiPreferences } from "../../utils/studioUiPreferences";
6
+ import { parsePreviewCopies } from "./previewQualitySlice";
7
+
8
+ describe("preview quality in the player store", () => {
9
+ it("starts at full quality with no copies, and counts retries", () => {
10
+ const state = usePlayerStore.getState();
11
+ expect(state.previewQuality).toBe(1);
12
+ expect(state.previewCopies).toBeNull();
13
+
14
+ const before = state.previewCopiesRetry;
15
+ state.retryPreviewCopies();
16
+ expect(usePlayerStore.getState().previewCopiesRetry).toBe(before + 1);
17
+ });
18
+
19
+ it("keeps a person's pick over the app's, and does not save the app's", () => {
20
+ usePlayerStore.setState({ previewQuality: 1, previewQualityChosenBy: null });
21
+ usePlayerStore.getState().setPreviewQuality(0.25, { by: "app" });
22
+ expect(usePlayerStore.getState()).toMatchObject({
23
+ previewQuality: 0.25,
24
+ previewQualityChosenBy: "app",
25
+ });
26
+ expect(readStudioUiPreferences().previewQuality).toBeUndefined();
27
+
28
+ usePlayerStore.getState().setPreviewQuality(0.5);
29
+ expect(usePlayerStore.getState()).toMatchObject({
30
+ previewQuality: 0.5,
31
+ previewQualityChosenBy: "person",
32
+ });
33
+ expect(readStudioUiPreferences().previewQuality).toBe(0.5);
34
+
35
+ usePlayerStore.getState().setPreviewQuality(0.125, { by: "app" });
36
+ expect(usePlayerStore.getState().previewQuality).toBe(0.5);
37
+ usePlayerStore.getState().setPreviewQuality(1);
38
+ });
39
+
40
+ it("drops the health reading measured at the old level when the level changes", () => {
41
+ const choppy = {
42
+ droppedShare: 0.5,
43
+ seconds: 3,
44
+ choppy: true,
45
+ fps: 14,
46
+ worstFrameMs: 180,
47
+ mode: "play",
48
+ } as const;
49
+ usePlayerStore.setState({ previewQuality: 1, previewQualityChosenBy: null });
50
+ usePlayerStore.getState().setPlaybackHealth(choppy);
51
+ usePlayerStore.getState().setPreviewQuality(1);
52
+ expect(usePlayerStore.getState().playbackHealth).toEqual(choppy);
53
+
54
+ usePlayerStore.getState().setPreviewQuality(0.5);
55
+ expect(usePlayerStore.getState().playbackHealth).toBeNull();
56
+
57
+ usePlayerStore.setState({ previewQualityChosenBy: null });
58
+ usePlayerStore.getState().setPlaybackHealth(choppy);
59
+ usePlayerStore.getState().setPreviewQuality(0.25, { by: "app" });
60
+ expect(usePlayerStore.getState().playbackHealth).toBeNull();
61
+ usePlayerStore.getState().setPreviewQuality(1);
62
+ });
63
+
64
+ it("reads a report of the copies only when it has the shape of one", () => {
65
+ expect(
66
+ parsePreviewCopies({ total: 2, ready: 1, failed: 1, progress: 0.75, error: "failed" }),
67
+ ).toEqual({ total: 2, ready: 1, failed: 1, progress: 0.75, error: "failed" });
68
+ expect(parsePreviewCopies(null)).toBeNull();
69
+ expect(parsePreviewCopies({ total: "2", ready: 1, failed: 0, progress: 0 })).toBeNull();
70
+ expect(parsePreviewCopies({ total: 2, ready: 1, failed: 0 })).toBeNull();
71
+ });
72
+ });
@@ -0,0 +1,156 @@
1
+ import type { StoreApi } from "zustand";
2
+ import { isPreviewQuality, type PreviewQuality } from "@hyperframes/core/preview-quality";
3
+ import { readStudioUiPreferences, writeStudioUiPreferences } from "../../utils/studioUiPreferences";
4
+
5
+ /** The lighter copies of heavy videos the preview wants at its current quality. */
6
+ export interface PreviewCopies {
7
+ total: number;
8
+ ready: number;
9
+ failed: number;
10
+ progress: number | null;
11
+ error: string | null;
12
+ }
13
+
14
+ /** How playback went over the last few seconds of play; null while paused, seeking or warming up. */
15
+ export interface PlaybackHealth {
16
+ droppedShare: number;
17
+ seconds: number;
18
+ choppy: boolean;
19
+ fps: number;
20
+ worstFrameMs: number;
21
+ mode: "play";
22
+ }
23
+
24
+ /** What the preview holds, counts and classes only, filled when asked for. */
25
+ export interface PreviewFacts {
26
+ sceneCount: number;
27
+ mountedElementCount: number;
28
+ durationSeconds: number;
29
+ videos: Array<{ codec: string; width: number; height: number; bitDepth: number; count: number }>;
30
+ lighterAt: PreviewQuality[];
31
+ copiesReady: boolean;
32
+ }
33
+
34
+ export type PreviewQualityChosenBy = "person" | "app";
35
+
36
+ export interface PreviewQualitySlice {
37
+ previewQuality: PreviewQuality;
38
+ /** Who set the level: a person (saved level, or a pick) or the app (never saved); null while nothing has. */
39
+ previewQualityChosenBy: PreviewQualityChosenBy | null;
40
+ /** A person's pick is saved; `by: "app"` sets the level without saving it and never overrides a saved pick. */
41
+ setPreviewQuality: (level: PreviewQuality, options?: { by?: PreviewQualityChosenBy }) => void;
42
+ /** Null when no copies are wanted: full quality, or nothing heavy. */
43
+ previewCopies: PreviewCopies | null;
44
+ setPreviewCopies: (copies: PreviewCopies | null) => void;
45
+ /** Bumped by retryPreviewCopies; the preview owner forwards each bump to the runtime. */
46
+ previewCopiesRetry: number;
47
+ retryPreviewCopies: () => void;
48
+ playbackHealth: PlaybackHealth | null;
49
+ setPlaybackHealth: (health: PlaybackHealth | null) => void;
50
+ previewFacts: PreviewFacts | null;
51
+ setPreviewFacts: (facts: PreviewFacts | null) => void;
52
+ /** Bumped by requestPreviewFacts; the preview owner forwards each bump and the answer lands in previewFacts. */
53
+ previewFactsRequests: number;
54
+ requestPreviewFacts: () => void;
55
+ }
56
+
57
+ export function createPreviewQualitySlice(
58
+ set: StoreApi<PreviewQualitySlice>["setState"],
59
+ get: StoreApi<PreviewQualitySlice>["getState"],
60
+ ): PreviewQualitySlice {
61
+ const saved = readStudioUiPreferences().previewQuality;
62
+ return {
63
+ previewQuality: saved ?? 1,
64
+ previewQualityChosenBy: saved === undefined ? null : "person",
65
+ setPreviewQuality: (previewQuality, options) => {
66
+ // A health reading belongs to the level it was measured at; drop it in the same update as the level.
67
+ const stale = previewQuality === get().previewQuality ? {} : { playbackHealth: null };
68
+ if (options?.by === "app") {
69
+ if (get().previewQualityChosenBy !== "person") {
70
+ set({ previewQuality, previewQualityChosenBy: "app", ...stale });
71
+ }
72
+ return;
73
+ }
74
+ writeStudioUiPreferences({ previewQuality });
75
+ set({ previewQuality, previewQualityChosenBy: "person", ...stale });
76
+ },
77
+ previewCopies: null,
78
+ setPreviewCopies: (previewCopies) => set({ previewCopies }),
79
+ previewCopiesRetry: 0,
80
+ retryPreviewCopies: () =>
81
+ set((state) => ({ previewCopiesRetry: state.previewCopiesRetry + 1 })),
82
+ playbackHealth: null,
83
+ setPlaybackHealth: (playbackHealth) => set({ playbackHealth }),
84
+ previewFacts: null,
85
+ setPreviewFacts: (previewFacts) => set({ previewFacts }),
86
+ previewFactsRequests: 0,
87
+ requestPreviewFacts: () =>
88
+ set((state) => ({ previewFactsRequests: state.previewFactsRequests + 1 })),
89
+ };
90
+ }
91
+
92
+ /** The runtime's report, kept only when it has the shape of one. */
93
+ export function parsePreviewCopies(value: unknown): PreviewCopies | null {
94
+ if (typeof value !== "object" || value === null) return null;
95
+ const { total, ready, failed, progress, error } = value as Record<string, unknown>;
96
+ const counts = [total, ready, failed].every((count) => typeof count === "number");
97
+ if (!counts || typeof progress !== "number") return null;
98
+ return {
99
+ total: total as number,
100
+ ready: ready as number,
101
+ failed: failed as number,
102
+ progress,
103
+ error: typeof error === "string" ? error : null,
104
+ };
105
+ }
106
+
107
+ export function parsePlaybackHealth(value: unknown): PlaybackHealth | null {
108
+ if (typeof value !== "object" || value === null) return null;
109
+ const { droppedShare, seconds, choppy, fps, worstFrameMs } = value as Record<string, unknown>;
110
+ const numbers = [droppedShare, seconds, fps, worstFrameMs].every((n) => typeof n === "number");
111
+ if (!numbers || typeof choppy !== "boolean") return null;
112
+ return {
113
+ droppedShare: droppedShare as number,
114
+ seconds: seconds as number,
115
+ choppy,
116
+ fps: fps as number,
117
+ worstFrameMs: worstFrameMs as number,
118
+ mode: "play",
119
+ };
120
+ }
121
+
122
+ export function parsePreviewFacts(value: unknown): PreviewFacts | null {
123
+ if (typeof value !== "object" || value === null) return null;
124
+ const { sceneCount, mountedElementCount, durationSeconds, videos, copiesReady, lighterAt } =
125
+ value as Record<string, unknown>;
126
+ const numbers = [sceneCount, mountedElementCount, durationSeconds].every(
127
+ (n) => typeof n === "number",
128
+ );
129
+ if (!numbers || !Array.isArray(videos) || typeof copiesReady !== "boolean") return null;
130
+ const grouped = videos.flatMap((video: unknown) => {
131
+ if (typeof video !== "object" || video === null) return [];
132
+ const { codec, width, height, bitDepth, count } = video as Record<string, unknown>;
133
+ const ok =
134
+ typeof codec === "string" &&
135
+ [width, height, bitDepth, count].every((n) => typeof n === "number");
136
+ return ok
137
+ ? [
138
+ {
139
+ codec,
140
+ width: width as number,
141
+ height: height as number,
142
+ bitDepth: bitDepth as number,
143
+ count: count as number,
144
+ },
145
+ ]
146
+ : [];
147
+ });
148
+ return {
149
+ lighterAt: Array.isArray(lighterAt) ? lighterAt.filter(isPreviewQuality) : [],
150
+ sceneCount: sceneCount as number,
151
+ mountedElementCount: mountedElementCount as number,
152
+ durationSeconds: durationSeconds as number,
153
+ videos: grouped,
154
+ copiesReady,
155
+ };
156
+ }
@@ -32,6 +32,15 @@ describe("studio UI preferences", () => {
32
32
  });
33
33
  });
34
34
 
35
+ it("remembers the preview quality, and drops a level that is not one of the four", () => {
36
+ const storage = createStorage();
37
+ writeStudioUiPreferences({ previewQuality: 0.25 }, storage);
38
+ expect(readStudioUiPreferences(storage)).toEqual({ previewQuality: 0.25 });
39
+
40
+ storage.setItem("hf-studio-ui-preferences", JSON.stringify({ previewQuality: 0.75 }));
41
+ expect(readStudioUiPreferences(storage).previewQuality).toBeUndefined();
42
+ });
43
+
35
44
  it("remembers the ruler and safe-margin toggles and drops non-boolean values", () => {
36
45
  const storage = createStorage();
37
46
  writeStudioUiPreferences({ rulerVisible: true, safeMarginsVisible: false }, storage);
@@ -1,3 +1,4 @@
1
+ import { isPreviewQuality, type PreviewQuality } from "@hyperframes/core/preview-quality";
1
2
  import type { SerializedDockview } from "dockview-react";
2
3
  import { parseDockLayout } from "../components/dock/dockLayoutSchema";
3
4
 
@@ -7,6 +8,7 @@ export type StudioTheme = "light" | "dark";
7
8
  export interface StudioUiPreferences {
8
9
  timelineVisible?: boolean;
9
10
  playbackRate?: number;
11
+ previewQuality?: PreviewQuality;
10
12
  audioMuted?: boolean;
11
13
  audioVolume?: number;
12
14
  thumbnailMode?: "adaptive" | "hidden";
@@ -84,6 +86,9 @@ function readStorage(storage: Storage | null, key: string): StudioUiPreferences
84
86
  if (typeof parsed.playbackRate === "number" && Number.isFinite(parsed.playbackRate)) {
85
87
  preferences.playbackRate = parsed.playbackRate;
86
88
  }
89
+ if (isPreviewQuality(parsed.previewQuality)) {
90
+ preferences.previewQuality = parsed.previewQuality;
91
+ }
87
92
  if (typeof parsed.audioMuted === "boolean") {
88
93
  preferences.audioMuted = parsed.audioMuted;
89
94
  }