@hyperframes/studio 0.9.59 → 0.9.63

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.
Files changed (61) hide show
  1. package/dist/assets/{hyperframes-player-bya4hgms.js → hyperframes-player-CUQxAJaE.js} +1 -1
  2. package/dist/assets/{index--dcfSUzI.js → index-D3rdYBVx.js} +1 -1
  3. package/dist/assets/{index-Bxh5lW0C.js → index-DSrTQv-k.js} +204 -204
  4. package/dist/assets/{pausedVideoDecoder-BKym1jA6.js → pausedVideoDecoder-BWllfjF-.js} +1 -1
  5. package/dist/{chunk-G6FJSL7X.js → chunk-JTUKMELR.js} +34 -6
  6. package/dist/{chunk-5EEM5WO4.js → chunk-ZUDVUI7K.js} +11 -1
  7. package/dist/index.d.ts +28 -1
  8. package/dist/index.html +1 -1
  9. package/dist/index.js +1815 -1104
  10. package/dist/player.js +2 -2
  11. package/dist/ui.js +1 -1
  12. package/package.json +8 -8
  13. package/src/captions/components/CaptionOverlay.sealed.test.ts +273 -0
  14. package/src/captions/components/CaptionOverlay.tsx +112 -57
  15. package/src/captions/components/CaptionOverlayUtils.ts +319 -33
  16. package/src/captions/components/CaptionPropertyPanel.tsx +17 -0
  17. package/src/components/editor/LayersPanel.opaque.test.ts +2 -2
  18. package/src/components/editor/previewDrafts.test.ts +2 -2
  19. package/src/components/editor/previewGestureStartRead.test.ts +2 -2
  20. package/src/components/editor/previewLayers.test.ts +2 -2
  21. package/src/components/editor/previewOverlayRects.test.ts +2 -2
  22. package/src/components/editor/previewPointerTargets.test.ts +2 -2
  23. package/src/components/editor/previewSelection.test.ts +2 -2
  24. package/src/components/editor/useColorGradingController.sealed.test.ts +165 -0
  25. package/src/components/editor/useColorGradingController.ts +20 -1
  26. package/src/components/editor/useColorGradingPreviews.ts +127 -43
  27. package/src/components/nle/AudioMeterStrip.tsx +63 -2
  28. package/src/components/nle/NLEPreview.test.ts +24 -0
  29. package/src/components/nle/NLEPreview.tsx +2 -6
  30. package/src/components/nle/audioSealedPreview.test.ts +254 -0
  31. package/src/components/nle/previewStage.ts +11 -1
  32. package/src/components/nle/zLaneGesture.test.ts +67 -0
  33. package/src/components/nle/zLaneGesture.ts +4 -0
  34. package/src/components/panels/VariablesPanel.test.tsx +90 -1
  35. package/src/components/panels/VariablesPanel.tsx +41 -17
  36. package/src/components/panels/renderHandoff.test.ts +86 -0
  37. package/src/components/panels/renderHandoff.ts +28 -0
  38. package/src/components/ui/Menu.test.tsx +77 -0
  39. package/src/components/ui/Menu.tsx +47 -4
  40. package/src/components/ui/Popover.tsx +5 -2
  41. package/src/elementAnimations.test.ts +13 -0
  42. package/src/hooks/timelineAudioGroupCreate.ts +57 -7
  43. package/src/hooks/timelineAudioGroupVolume.ts +110 -34
  44. package/src/hooks/useCaptionDetection.ts +175 -54
  45. package/src/hooks/usePersistentEditHistory.test.ts +84 -0
  46. package/src/hooks/usePersistentEditHistory.ts +36 -3
  47. package/src/index.ts +1 -0
  48. package/src/main.tsx +14 -11
  49. package/src/player/components/Timeline.newTrack.test.tsx +106 -0
  50. package/src/player/components/TimelineLanes.tsx +4 -2
  51. package/src/player/components/TimelineTrackHeader.tsx +12 -4
  52. package/src/player/components/clipMenuAudioItems.tsx +46 -3
  53. package/src/player/components/timelineRowKeys.test.ts +28 -0
  54. package/src/player/components/timelineRowKeys.ts +27 -0
  55. package/src/player/hooks/useShadowPreviewReload.ts +7 -0
  56. package/src/player/hooks/useTimelinePlayer.shadowReload.test.ts +20 -0
  57. package/src/player/lib/previewChannel.ts +10 -0
  58. package/src/utils/gsapUndoRestore.sealed.test.ts +73 -0
  59. package/src/utils/gsapUndoRestore.ts +66 -0
  60. package/src/utils/studioPendingEdits.test.ts +20 -0
  61. package/src/utils/studioPendingEdits.ts +11 -4
@@ -0,0 +1,254 @@
1
+ // @vitest-environment happy-dom
2
+
3
+ import { act, createElement } from "react";
4
+ import { createRoot, type Root } from "react-dom/client";
5
+ import { afterEach, beforeEach, expect, it, vi } from "vitest";
6
+ // The frame's real runtime agent, serving the opaque frame from this document.
7
+ import { installMarkedEditingAgent } from "../../../../core/src/runtime/editingAgent.test-helpers";
8
+ import { usePlayerStore, type TimelineElement } from "../../player";
9
+ import { ClipMenuAudioItems } from "../../player/components/clipMenuAudioItems";
10
+ import { usePreviewIframeStore } from "../../player/store/previewIframeStore";
11
+ import { TimelineEditProvider } from "../../contexts/TimelineEditContext";
12
+ import { createAudioGroupAndAssignMembers } from "../../hooks/timelineAudioGroupCreate";
13
+ import { mintGroupId } from "../editor/useFxCarveGrouping";
14
+ import { detachedFakeIframe } from "../../player/hooks/timelinePlayerTestHarness";
15
+ import { useAudioMetersVisible } from "../../utils/audioMeterVisibility";
16
+ import { useSetAudioGroupAttribute } from "../../hooks/timelineAudioGroupVolume";
17
+ import { previewDocumentCopy } from "../../player/lib/previewChannel";
18
+ import { AudioMeterStrip } from "./AudioMeterStrip";
19
+
20
+ (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
21
+
22
+ type MeterWindow = Window & { __hf?: Record<string, unknown> };
23
+
24
+ const closers: Array<() => void> = [];
25
+ const roots: Root[] = [];
26
+ let frames: FrameRequestCallback[] = [];
27
+ const tick = () => {
28
+ const run = frames;
29
+ frames = [];
30
+ act(() => run.forEach((cb) => cb(performance.now())));
31
+ };
32
+
33
+ beforeEach(() => {
34
+ frames = [];
35
+ vi.stubGlobal("requestAnimationFrame", (cb: FrameRequestCallback) => frames.push(cb));
36
+ vi.stubGlobal("cancelAnimationFrame", () => {});
37
+ useAudioMetersVisible.setState({ visible: true });
38
+ });
39
+ afterEach(() => {
40
+ act(() => roots.splice(0).forEach((root) => root.unmount()));
41
+ closers.splice(0).forEach((close) => close());
42
+ delete (window as MeterWindow).__hf;
43
+ vi.unstubAllGlobals();
44
+ usePlayerStore.getState().reset();
45
+ usePreviewIframeStore.setState({ iframe: null });
46
+ document.body.innerHTML = "";
47
+ });
48
+
49
+ /** A frame Studio cannot read, whose runtime is the real editing agent over this document. */
50
+ function opaqueFrame() {
51
+ const frame: Record<string, unknown> = {};
52
+ const iframe = detachedFakeIframe(frame);
53
+ Object.defineProperty(iframe, "contentDocument", { value: null });
54
+ Object.defineProperty(frame, "document", {
55
+ get: () => {
56
+ throw new DOMException("blocked", "SecurityError");
57
+ },
58
+ });
59
+ const parent = {
60
+ postMessage: (data: unknown, _origin: string, ports: MessagePort[]) =>
61
+ window.dispatchEvent(
62
+ new MessageEvent("message", { source: frame as unknown as Window, data, ports }),
63
+ ),
64
+ } as unknown as Window;
65
+ const agent = installMarkedEditingAgent(parent);
66
+ frame.postMessage = (data: unknown) =>
67
+ window.dispatchEvent(new MessageEvent("message", { source: parent, data }));
68
+ closers.push(() => agent.dispose());
69
+ return iframe;
70
+ }
71
+
72
+ const member = (domId: string): TimelineElement => ({
73
+ id: domId,
74
+ key: `compositions/voices.html#${domId}`,
75
+ domId,
76
+ tag: "audio",
77
+ start: 0,
78
+ duration: 5,
79
+ track: 0,
80
+ audioGroup: "vo",
81
+ audioGroupVolume: 1,
82
+ });
83
+
84
+ const VOICES = `<section data-composition-id="voices">
85
+ <audio id="voice-1" data-audio-group="vo"></audio>
86
+ <hf-audio-group id="vo" data-volume="1"></hf-audio-group>
87
+ </section>`;
88
+
89
+ function stubProjectFiles(files: Map<string, string>) {
90
+ vi.stubGlobal(
91
+ "fetch",
92
+ vi.fn(async (input: RequestInfo | URL) => {
93
+ const url = String(input);
94
+ const content = files.get(decodeURIComponent(url.slice(url.lastIndexOf("/") + 1)));
95
+ return new Response(JSON.stringify({ content }), {
96
+ status: content === undefined ? 404 : 200,
97
+ headers: { "Content-Type": "application/json" },
98
+ });
99
+ }),
100
+ );
101
+ }
102
+
103
+ it("meter moves + group volume sealed", async () => {
104
+ document.body.innerHTML = `<main data-composition-id="root">
105
+ <div id="voices-host" data-composition-id="voices-host" data-composition-file="compositions/voices.html">${VOICES}</div>
106
+ </main>`;
107
+ const groupEl = document.getElementById("vo")!;
108
+ const meter = {
109
+ start: vi.fn(),
110
+ stop: vi.fn(),
111
+ read: vi.fn(() => ({ master: { l: 1, r: 1 }, groups: { vo: { l: 1, r: 1 } } })),
112
+ };
113
+ (window as MeterWindow).__hf = { audioMeter: meter };
114
+ usePlayerStore.getState().setElements([member("voice-1")]);
115
+ const iframe = opaqueFrame();
116
+
117
+ const host = document.createElement("div");
118
+ document.body.append(host);
119
+ const root = createRoot(host);
120
+ roots.push(root);
121
+ act(() => root.render(createElement(AudioMeterStrip, { previewIframeRef: { current: iframe } })));
122
+ const masks = [...host.querySelectorAll<HTMLElement>("[data-testid=meter-mask]")];
123
+ expect(masks).toHaveLength(4);
124
+ await vi.waitFor(() => {
125
+ tick();
126
+ expect(masks.map((mask) => mask.style.height)).toEqual(["0%", "0%", "0%", "0%"]);
127
+ });
128
+ expect(meter.start).toHaveBeenCalled();
129
+ act(() => roots.splice(0).forEach((r) => r.unmount()));
130
+ await vi.waitFor(() => expect(meter.stop).toHaveBeenCalled());
131
+
132
+ stubProjectFiles(new Map([["compositions/voices.html", VOICES]]));
133
+ const writes = new Map<string, string>();
134
+ const held: { setter: ReturnType<typeof useSetAudioGroupAttribute> | null } = { setter: null };
135
+ function Probe() {
136
+ held.setter = useSetAudioGroupAttribute({
137
+ projectIdRef: { current: "project-1" },
138
+ activeCompPath: "index.html",
139
+ showToast: vi.fn(),
140
+ writeProjectFile: async (path, content) => void writes.set(path, content),
141
+ recordEdit: async () => {},
142
+ pendingTimelineEditPathRef: { current: new Set() },
143
+ previewIframeRef: { current: iframe },
144
+ });
145
+ return null;
146
+ }
147
+ const probeRoot = createRoot(document.createElement("div"));
148
+ roots.push(probeRoot);
149
+ act(() => probeRoot.render(createElement(Probe)));
150
+ const setter = held.setter!;
151
+
152
+ setter.setLive("vo", "data-volume", "0.5");
153
+ setter.setLive("vo", "data-volume", "0.4");
154
+ await vi.waitFor(() => expect(groupEl.getAttribute("data-volume")).toBe("0.4"));
155
+ expect(usePlayerStore.getState().elements[0]?.audioGroupVolume).toBeCloseTo(0.4, 6);
156
+
157
+ await expect(setter.setQuiet("vo", "data-volume", "0.25", "Set volume")).resolves.toEqual({
158
+ status: "saved",
159
+ });
160
+ expect([...writes.keys()]).toEqual(["compositions/voices.html"]);
161
+ expect(writes.get("compositions/voices.html")).toContain(
162
+ '<hf-audio-group id="vo" data-volume="0.25">',
163
+ );
164
+ await vi.waitFor(() => expect(groupEl.getAttribute("data-volume")).toBe("0.25"));
165
+ });
166
+
167
+ it("groups clips in a sealed preview, and unwinds the preview when the save fails", async () => {
168
+ document.body.innerHTML = `<main data-composition-id="root">
169
+ <audio id="voice-1" data-audio-group="old"></audio><audio id="voice-2"></audio>
170
+ </main>`;
171
+ const iframe = opaqueFrame();
172
+ const files = new Map([["index.html", document.body.innerHTML]]);
173
+ stubProjectFiles(files);
174
+ const elements = ["voice-1", "voice-2"].map((domId) => ({
175
+ ...member(domId),
176
+ key: `index.html#${domId}`,
177
+ audioGroup: undefined,
178
+ }));
179
+ const input = {
180
+ projectId: "project-1",
181
+ activeCompPath: "index.html",
182
+ elements,
183
+ groupId: "vo",
184
+ groupLabel: "Voice",
185
+ previewIframe: iframe,
186
+ recordEdit: async () => {},
187
+ pendingTimelineEditPathRef: { current: new Set<string>() },
188
+ };
189
+ const groupOf = (id: string) => document.getElementById(id)!.getAttribute("data-audio-group");
190
+
191
+ await expect(
192
+ createAudioGroupAndAssignMembers({
193
+ ...input,
194
+ writeProjectFile: async () => {
195
+ expect([groupOf("voice-1"), groupOf("voice-2")]).toEqual(["vo", "vo"]);
196
+ expect(document.querySelector("hf-audio-group#vo")?.getAttribute("data-label")).toBe(
197
+ "Voice",
198
+ );
199
+ throw new Error("disk full");
200
+ },
201
+ }),
202
+ ).rejects.toThrow("disk full");
203
+ expect([groupOf("voice-1"), groupOf("voice-2")]).toEqual(["old", null]);
204
+ expect(document.getElementById("vo")).toBeNull();
205
+
206
+ await createAudioGroupAndAssignMembers({ ...input, writeProjectFile: async () => {} });
207
+ expect([groupOf("voice-1"), groupOf("voice-2")]).toEqual(["vo", "vo"]);
208
+ expect(document.querySelector("hf-audio-group#vo")).not.toBeNull();
209
+ });
210
+
211
+ it("reads a sealed preview's groups and ids off an inert copy", async () => {
212
+ document.body.innerHTML = `<audio id="voiceover"></audio><audio id="music" src="bed.wav"></audio>`;
213
+ const copy = await previewDocumentCopy(opaqueFrame());
214
+ expect(copy).not.toBeNull();
215
+ expect(copy).not.toBe(document);
216
+ expect(mintGroupId(copy!)).toBe("voiceover-2");
217
+ expect(copy!.baseURI).toBe(document.baseURI);
218
+ });
219
+
220
+ it("offers Duck under voice for a bed in a sealed preview", async () => {
221
+ document.body.innerHTML = `<main data-composition-id="root">
222
+ <audio id="music" src="bed.wav" data-start="0" data-duration="10"></audio>
223
+ <audio id="voiceover" src="vo.wav" data-start="1" data-duration="2"></audio>
224
+ </main>`;
225
+ const iframe = opaqueFrame();
226
+ usePreviewIframeStore.setState({ iframe });
227
+ usePlayerStore.getState().beginTimelineSession("project-1");
228
+ const bed: TimelineElement = {
229
+ id: "music",
230
+ domId: "music",
231
+ tag: "audio",
232
+ start: 0,
233
+ duration: 10,
234
+ track: 0,
235
+ };
236
+ const host = document.createElement("div");
237
+ document.body.append(host);
238
+ const root = createRoot(host);
239
+ roots.push(root);
240
+ const value = {
241
+ onSetElementAttributeQuiet: vi.fn(async () => ({ status: "saved" as const })),
242
+ onNotice: vi.fn(),
243
+ };
244
+ act(() =>
245
+ root.render(
246
+ createElement(
247
+ TimelineEditProvider,
248
+ { value },
249
+ createElement(ClipMenuAudioItems, { part: "duck", element: bed, onClose: () => {} }),
250
+ ),
251
+ ),
252
+ );
253
+ await vi.waitFor(() => expect(host.textContent).toContain("Duck under voice"));
254
+ });
@@ -6,7 +6,7 @@ export const PREVIEW_STAGE_INSET_PX = 8;
6
6
 
7
7
  // clip-path as well as visibility: the player's loading overlay sets its own
8
8
  // visibility:visible and would otherwise paint over the live frame.
9
- export const SHADOW_IFRAME_STYLE: CSSProperties = {
9
+ const SHADOW_IFRAME_STYLE: CSSProperties = {
10
10
  position: "absolute",
11
11
  inset: 0,
12
12
  visibility: "hidden",
@@ -14,6 +14,16 @@ export const SHADOW_IFRAME_STYLE: CSSProperties = {
14
14
  pointerEvents: "none",
15
15
  };
16
16
 
17
+ const RENDERING_SHADOW_IFRAME_STYLE: CSSProperties = {
18
+ position: "absolute",
19
+ inset: 0,
20
+ opacity: 0,
21
+ pointerEvents: "none",
22
+ };
23
+
24
+ export const shadowIframeStyle = (sandboxOrigin: "opaque" | undefined): CSSProperties =>
25
+ sandboxOrigin === "opaque" ? RENDERING_SHADOW_IFRAME_STYLE : SHADOW_IFRAME_STYLE;
26
+
17
27
  export function resolvePreviewStageSize(
18
28
  viewportWidth: number,
19
29
  viewportHeight: number,
@@ -1,4 +1,10 @@
1
1
  import { describe, expect, it, vi } from "vitest";
2
+ import {
3
+ beginStudioPendingEdit,
4
+ paintBackNewestStudioPendingEdit,
5
+ setStudioPendingEditsSettled,
6
+ trackStudioPendingEdit,
7
+ } from "../../utils/studioPendingEdits";
2
8
  import { runLaneZGesture, runZLaneGesture } from "./zLaneGesture";
3
9
 
4
10
  const durable = { durable: true, allMatched: true, changed: true };
@@ -174,3 +180,64 @@ describe("runZLaneGesture", () => {
174
180
  expect(next).toBe(true);
175
181
  });
176
182
  });
183
+
184
+ // fails without the fix: the z write settled before the lane mirror began, which closed the gesture's undo step.
185
+ describe("one undo step per gesture", () => {
186
+ it.each([
187
+ [
188
+ "z then lanes",
189
+ (first: () => Promise<void>, second: () => Promise<boolean>) =>
190
+ runZLaneGesture({ commitZ: async () => void (await first()), mirror: second }),
191
+ ],
192
+ [
193
+ "lanes then z",
194
+ (first: () => Promise<void>, second: () => Promise<boolean>) =>
195
+ runLaneZGesture({
196
+ commitLane: async () => (await first(), true),
197
+ commitZ: async () => void (await second()),
198
+ }),
199
+ ],
200
+ ])(
201
+ "a layer reorder (%s) is one undo step: Studio's edits stay pending between its two writes",
202
+ async (_, gesture) => {
203
+ const settled = vi.fn();
204
+ setStudioPendingEditsSettled(settled);
205
+ const secondWrite = deferred<boolean>();
206
+ try {
207
+ const done = gesture(
208
+ () => trackStudioPendingEdit(Promise.resolve()) as Promise<void>,
209
+ () => trackStudioPendingEdit(secondWrite.promise) as Promise<boolean>,
210
+ );
211
+ await new Promise((resolve) => setTimeout(resolve, 0));
212
+ expect(settled).not.toHaveBeenCalled();
213
+ secondWrite.resolve(true);
214
+ await done;
215
+ await new Promise((resolve) => setTimeout(resolve, 0));
216
+ expect(settled).toHaveBeenCalledTimes(1);
217
+ } finally {
218
+ secondWrite.resolve(true);
219
+ setStudioPendingEditsSettled(null);
220
+ }
221
+ },
222
+ );
223
+
224
+ it("Cmd+Z during a lane drag's save still paints that drag back at once", async () => {
225
+ const revert = vi.fn(() => () => {});
226
+ const save = deferred<void>();
227
+ const done = runLaneZGesture({
228
+ commitLane: async () => {
229
+ beginStudioPendingEdit(revert).settle(save.promise);
230
+ await save.promise;
231
+ return true;
232
+ },
233
+ commitZ: async () => {},
234
+ });
235
+ try {
236
+ expect(paintBackNewestStudioPendingEdit()).not.toBeNull();
237
+ expect(revert).toHaveBeenCalledTimes(1);
238
+ } finally {
239
+ save.resolve();
240
+ await done;
241
+ }
242
+ });
243
+ });
@@ -1,4 +1,5 @@
1
1
  import type { DomEditPatchBatchesResult } from "../../hooks/domEditCommitTypes";
2
+ import { trackStudioPendingEdit } from "../../utils/studioPendingEdits";
2
3
 
3
4
  /**
4
5
  * Run one COMPLETE z→lane gesture — the z-index persist followed by its
@@ -27,6 +28,8 @@ let gestureTail: Promise<void> | null = null;
27
28
  /** The single ordering owner for every gesture that crosses z/lane persistence. */
28
29
  export function serializeZLaneGesture<Result>(run: () => Promise<Result>): Promise<Result> {
29
30
  const previous = gestureTail;
31
+ let release!: () => void;
32
+ trackStudioPendingEdit(new Promise<void>((resolve) => (release = resolve)));
30
33
  // Preserve synchronous optimistic updates for the first gesture. A queued
31
34
  // gesture starts only after the preceding gesture fully settled.
32
35
  let gesture: Promise<Result>;
@@ -39,6 +42,7 @@ export function serializeZLaneGesture<Result>(run: () => Promise<Result>): Promi
39
42
  gesture = Promise.reject(error);
40
43
  }
41
44
  }
45
+ void gesture.then(release, release);
42
46
  const tail = gesture.then(
43
47
  () => undefined,
44
48
  () => undefined,
@@ -24,11 +24,20 @@ const shell = {
24
24
  activeCompPath: "index.html" as string | null,
25
25
  compositions: ["index.html", "scene.html"],
26
26
  };
27
+ const showToast = vi.fn();
28
+ const copyTextToClipboard = vi.fn(async (_text: string) => true);
27
29
 
28
30
  vi.mock("../../contexts/StudioContext", () => ({
29
- useStudioShellContext: () => ({ activeCompPath: shell.activeCompPath, showToast: vi.fn() }),
31
+ useStudioShellContext: () => ({
32
+ projectId: "demo",
33
+ activeCompPath: shell.activeCompPath,
34
+ showToast,
35
+ }),
30
36
  useStudioPlaybackContext: () => ({ refreshKey: 0 }),
31
37
  }));
38
+ vi.mock("../../utils/clipboard", () => ({
39
+ copyTextToClipboard: (text: string) => copyTextToClipboard(text),
40
+ }));
32
41
  vi.mock("../../contexts/DomEditContext", () => ({
33
42
  useDomEditContext: () => ({ domEditSelection: null }),
34
43
  }));
@@ -47,8 +56,29 @@ afterEach(() => {
47
56
  act(() => root?.unmount());
48
57
  root = null;
49
58
  document.body.innerHTML = "";
59
+ showToast.mockClear();
60
+ copyTextToClipboard.mockClear();
61
+ vi.unstubAllGlobals();
50
62
  });
51
63
 
64
+ async function renderPanel(html: string): Promise<HTMLElement> {
65
+ const host = document.createElement("div");
66
+ document.body.append(host);
67
+ root = createRoot(host);
68
+ const session = await openComposition(html, { history: false });
69
+ await act(async () => {
70
+ root?.render(
71
+ <VariablesPanel
72
+ sdkSession={session}
73
+ publishSdkSession={vi.fn()}
74
+ reloadPreview={vi.fn()}
75
+ recordEdit={vi.fn(async () => {})}
76
+ />,
77
+ );
78
+ });
79
+ return host;
80
+ }
81
+
52
82
  async function renderOtherCompositions(sessionPath: string): Promise<string> {
53
83
  const host = document.createElement("div");
54
84
  document.body.append(host);
@@ -84,3 +114,62 @@ describe("VariablesPanel other compositions", () => {
84
114
  expect(await renderOtherCompositions("main.html")).not.toContain("main.html");
85
115
  });
86
116
  });
117
+
118
+ // A shared project's author writes these, so they reach the copied command as hostile text.
119
+ const HOSTILE = `x'; calc.exe; '" & calc.exe | calc.exe \\ $(id) %PATH%`;
120
+ const withHostileDefault = `<!DOCTYPE html>
121
+ <html data-composition-variables='${JSON.stringify([
122
+ { id: "title", type: "string", label: "Title", default: HOSTILE },
123
+ ]).replace(/'/g, "&#39;")}'>
124
+ <body><div data-composition-id="main" data-hf-id="hf-stage" data-hf-root data-duration="5"></div></body>
125
+ </html>`;
126
+
127
+ const button = (host: HTMLElement, label: string) =>
128
+ [...host.querySelectorAll("button")].find((b) => b.textContent === label);
129
+
130
+ describe("VariablesPanel render command", () => {
131
+ it("does not let a hostile variable default into the copied render command", async () => {
132
+ shell.activeCompPath = "compositions/intro.html";
133
+ const fetch = vi.fn(async (_url: string, _init?: RequestInit) => new Response("{}"));
134
+ vi.stubGlobal("fetch", fetch);
135
+ const host = await renderPanel(withHostileDefault);
136
+ const expected =
137
+ "npx hyperframes render -c compositions/intro.html --variables-file .hyperframes/render-variables.json";
138
+
139
+ expect(host.querySelector("code")?.textContent).toBe(expected);
140
+ await act(async () => button(host, "Copy render command")?.click());
141
+
142
+ expect(copyTextToClipboard).toHaveBeenCalledWith(expected);
143
+ await vi.waitFor(() => expect(showToast).toHaveBeenCalledWith("Render command copied", "info"));
144
+ const [url, init] = fetch.mock.calls[0]!;
145
+ expect(url).toBe("/api/projects/demo/render-variables");
146
+ expect(JSON.parse(String(init?.body))).toEqual({ title: HOSTILE });
147
+ });
148
+
149
+ it("says the values were not saved when the server refuses them", async () => {
150
+ shell.activeCompPath = "index.html";
151
+ vi.stubGlobal(
152
+ "fetch",
153
+ vi.fn(async () => new Response("{}", { status: 403 })),
154
+ );
155
+ const host = await renderPanel(withHostileDefault);
156
+
157
+ await act(async () => button(host, "Copy render command")?.click());
158
+
159
+ await vi.waitFor(() =>
160
+ expect(showToast).toHaveBeenCalledWith(
161
+ "Couldn't save the values to .hyperframes/render-variables.json",
162
+ "error",
163
+ ),
164
+ );
165
+ });
166
+
167
+ it("offers no render command for a composition whose name a shell reads as syntax", async () => {
168
+ shell.activeCompPath = "x';calc;'.html";
169
+ const host = await renderPanel(withHostileDefault);
170
+
171
+ expect(button(host, "Copy render command")).toBeUndefined();
172
+ expect(button(host, "Copy values JSON")).toBeDefined();
173
+ expect(host.textContent).not.toContain("npx hyperframes render");
174
+ });
175
+ });
@@ -24,11 +24,8 @@ import { PreviewValueControl } from "./VariablesValueControls";
24
24
  import { copyTextToClipboard } from "../../utils/clipboard";
25
25
  import { resolveMasterCompositionPath } from "../../utils/studioUrlState";
26
26
  import { isScalarVariableValue as isScalar } from "@hyperframes/core/variables";
27
-
28
- /** POSIX single-quote escaping so the copied command survives quotes in values. */
29
- function shellSingleQuote(value: string): string {
30
- return `'${value.replace(/'/g, `'\\''`)}'`;
31
- }
27
+ import { RENDER_VARIABLES_FILE } from "@hyperframes/core/project-folders";
28
+ import { renderHandoffCommand, saveRenderVariables } from "./renderHandoff";
32
29
 
33
30
  export interface StudioEditPersistenceProps {
34
31
  sdkSession: Composition | null;
@@ -195,34 +192,45 @@ function PreviewModeHeader({
195
192
  }
196
193
 
197
194
  /**
198
- * Developer/agent handoff: copy the effective values as JSON or as a
199
- * ready-to-run render command mirroring exactly what the preview shows.
195
+ * Developer/agent handoff: copy the effective values as JSON, or a render
196
+ * command that reads them from the file Studio writes when it is copied.
200
197
  */
201
198
  function HandoffFooter({
202
199
  effectiveValues,
203
200
  compPath,
204
201
  onCopy,
202
+ onCopyCommand,
205
203
  }: {
206
204
  effectiveValues: Record<string, unknown>;
207
205
  compPath: string;
208
206
  onCopy: (text: string, what: string) => void;
207
+ onCopyCommand: (command: string) => void;
209
208
  }) {
210
209
  const json = JSON.stringify(effectiveValues);
211
- const command = `npx hyperframes render ${shellSingleQuote(compPath)} --variables ${shellSingleQuote(json)}`;
210
+ const command = renderHandoffCommand(compPath);
212
211
  return (
213
212
  <div className="space-y-1.5 rounded-lg border border-neutral-800/70 bg-neutral-900/40 p-2">
214
213
  <p className="text-[9px] font-medium uppercase tracking-wider text-neutral-500">
215
214
  Use this template
216
215
  </p>
217
- <code className="block truncate font-mono text-[9px] text-neutral-500" title={command}>
218
- {command}
219
- </code>
216
+ {command ? (
217
+ <code className="block truncate font-mono text-[9px] text-neutral-500" title={command}>
218
+ {command}
219
+ </code>
220
+ ) : (
221
+ <p className="text-[9px] leading-relaxed text-neutral-500">
222
+ Rename this composition to letters, digits, <code className="font-mono">_ . / -</code> to
223
+ copy a render command. A shell would read other characters in its name as syntax.
224
+ </p>
225
+ )}
220
226
  <div className="flex items-center gap-2">
221
- <RowAction
222
- label="Copy render command"
223
- title="CLI command rendering exactly what the preview shows"
224
- onClick={() => onCopy(command, "Render command")}
225
- />
227
+ {command && (
228
+ <RowAction
229
+ label="Copy render command"
230
+ title={`Saves what the preview shows to ${RENDER_VARIABLES_FILE}. Run the command from the project folder.`}
231
+ onClick={() => onCopyCommand(command)}
232
+ />
233
+ )}
226
234
  <RowAction
227
235
  label="Copy values JSON"
228
236
  title="Effective values (defaults merged with preview overrides)"
@@ -250,7 +258,7 @@ export const VariablesPanel = memo(function VariablesPanel({
250
258
  reloadPreview,
251
259
  recordEdit,
252
260
  }: VariablesPanelProps) {
253
- const { activeCompPath, showToast } = useStudioShellContext();
261
+ const { projectId, activeCompPath, showToast } = useStudioShellContext();
254
262
  const { refreshKey } = useStudioPlaybackContext();
255
263
  const { readProjectFile, writeProjectFile, compositions } = useFileManagerContext();
256
264
  const { domEditSelection } = useDomEditContext();
@@ -317,6 +325,21 @@ export const VariablesPanel = memo(function VariablesPanel({
317
325
  [showToast],
318
326
  );
319
327
 
328
+ const copyRenderCommand = useCallback(
329
+ (command: string) => {
330
+ // Both start inside the click: a clipboard write after an await loses the user activation Safari requires.
331
+ const copied = copyTextToClipboard(command);
332
+ const saved = saveRenderVariables(projectId, effectiveValues);
333
+ void Promise.all([saved, copied]).then(([wasSaved, wasCopied]) => {
334
+ if (!wasCopied) showToast("Couldn't copy render command", "error");
335
+ else if (!wasSaved)
336
+ showToast(`Couldn't save the values to ${RENDER_VARIABLES_FILE}`, "error");
337
+ else showToast("Render command copied", "info");
338
+ });
339
+ },
340
+ [projectId, effectiveValues, showToast],
341
+ );
342
+
320
343
  const dropPreviewOverride = useCallback(
321
344
  (id: string) => {
322
345
  if (previewValues && id in previewValues) {
@@ -516,6 +539,7 @@ export const VariablesPanel = memo(function VariablesPanel({
516
539
  effectiveValues={effectiveValues}
517
540
  compPath={effectiveCompPath ?? "index.html"}
518
541
  onCopy={copyToClipboard}
542
+ onCopyCommand={copyRenderCommand}
519
543
  />
520
544
  )}
521
545
  {addOpen ? (