@hyperframes/studio 0.9.58 → 0.9.61

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 (57) hide show
  1. package/dist/assets/hyperframes-player-Cm0hYGm2.js +573 -0
  2. package/dist/assets/{index-D7ICtobF.js → index-BGrNWeLK.js} +199 -199
  3. package/dist/assets/{index-ww7-RmuM.js → index-REqr_dLu.js} +1 -1
  4. package/dist/assets/{pausedVideoDecoder-Dbe8Cmab.js → pausedVideoDecoder-DqLDSq8J.js} +1 -1
  5. package/dist/{chunk-5EEM5WO4.js → chunk-3KCEIESB.js} +1 -1
  6. package/dist/{chunk-G6FJSL7X.js → chunk-JTUKMELR.js} +34 -6
  7. package/dist/index.d.ts +29 -1
  8. package/dist/index.html +1 -1
  9. package/dist/index.js +734 -217
  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/NLEPreview.test.ts +24 -0
  28. package/src/components/nle/NLEPreview.tsx +2 -6
  29. package/src/components/nle/previewStage.ts +11 -1
  30. package/src/components/panels/VariablesPanel.test.tsx +90 -1
  31. package/src/components/panels/VariablesPanel.tsx +41 -17
  32. package/src/components/panels/renderHandoff.test.ts +86 -0
  33. package/src/components/panels/renderHandoff.ts +28 -0
  34. package/src/components/ui/Menu.test.tsx +77 -0
  35. package/src/components/ui/Menu.tsx +47 -4
  36. package/src/components/ui/Popover.tsx +5 -2
  37. package/src/elementAnimations.test.ts +13 -0
  38. package/src/hooks/useCaptionDetection.ts +175 -54
  39. package/src/hooks/useMusicBeatAnalysis.test.tsx +131 -0
  40. package/src/hooks/useMusicBeatAnalysis.ts +51 -66
  41. package/src/hooks/usePersistentEditHistory.test.ts +84 -0
  42. package/src/hooks/usePersistentEditHistory.ts +36 -3
  43. package/src/hooks/useRenderClipContent.test.ts +21 -0
  44. package/src/hooks/useRenderClipContent.ts +3 -1
  45. package/src/index.ts +2 -0
  46. package/src/player/hooks/useShadowPreviewReload.ts +7 -0
  47. package/src/player/hooks/useTimelinePlayer.shadowReload.test.ts +20 -0
  48. package/src/player/lib/previewElements.test.ts +4 -0
  49. package/src/player/lib/previewElements.ts +1 -0
  50. package/src/sealedPreviewExports.test.ts +1 -0
  51. package/src/utils/gsapUndoRestore.sealed.test.ts +73 -0
  52. package/src/utils/gsapUndoRestore.ts +66 -0
  53. package/src/utils/studioPendingEdits.test.ts +20 -0
  54. package/src/utils/studioPendingEdits.ts +11 -4
  55. package/src/utils/timelineInspector.test.ts +49 -2
  56. package/src/utils/timelineInspector.ts +21 -2
  57. package/dist/assets/hyperframes-player-B78JDyI_.js +0 -565
@@ -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 ? (
@@ -0,0 +1,86 @@
1
+ import { afterEach, describe, expect, it, vi } from "vitest";
2
+ import { RENDER_VARIABLES_FILE } from "@hyperframes/core/project-folders";
3
+ import { renderHandoffCommand, saveRenderVariables } from "./renderHandoff";
4
+
5
+ afterEach(() => {
6
+ vi.unstubAllGlobals();
7
+ });
8
+
9
+ describe("renderHandoffCommand", () => {
10
+ it.each(["index.html", "compositions/intro.html", "scenes/v2_final-cut.html", "2026/q4.html"])(
11
+ "renders %s with the values file",
12
+ (compPath) => {
13
+ expect(renderHandoffCommand(compPath)).toBe(
14
+ `npx hyperframes render -c ${compPath} --variables-file .hyperframes/render-variables.json`,
15
+ );
16
+ },
17
+ );
18
+
19
+ it.each([
20
+ "x';calc;'.html",
21
+ 'x";calc;".html',
22
+ "a&calc.html",
23
+ "a|calc.html",
24
+ "a;calc.html",
25
+ "a\\b.html",
26
+ "a b.html",
27
+ "$(id).html",
28
+ "`id`.html",
29
+ "%PATH%.html",
30
+ "a^b.html",
31
+ "a(b).html",
32
+ "a!b.html",
33
+ "a,b.html",
34
+ "a{b}.html",
35
+ "a*b.html",
36
+ "a\nb.html",
37
+ "~/a.html",
38
+ "@a.html",
39
+ "#a.html",
40
+ "-o.html",
41
+ "--output=x.html",
42
+ ".x.html",
43
+ "intró.html",
44
+ "",
45
+ ])("never puts a composition name a shell reads as syntax in the command: %j", (compPath) => {
46
+ expect(renderHandoffCommand(compPath)).toBeNull();
47
+ });
48
+
49
+ it("names a values file that is one plain word in every shell", () => {
50
+ expect(RENDER_VARIABLES_FILE).toMatch(/^[A-Za-z0-9_./-]+$/);
51
+ });
52
+ });
53
+
54
+ describe("saveRenderVariables", () => {
55
+ it("puts the values as JSON to the project's render-variables route", async () => {
56
+ const fetch = vi.fn(async () => new Response("{}", { status: 200 }));
57
+ vi.stubGlobal("fetch", fetch);
58
+ const values = { title: "It's Q4'; calc; '", count: 3 };
59
+
60
+ expect(await saveRenderVariables("my project", values)).toBe(true);
61
+
62
+ expect(fetch).toHaveBeenCalledTimes(1);
63
+ const [url, init] = fetch.mock.calls[0] as unknown as [string, RequestInit];
64
+ expect(url).toBe("/api/projects/my%20project/render-variables");
65
+ expect(init.method).toBe("PUT");
66
+ expect(JSON.parse(String(init.body))).toEqual(values);
67
+ });
68
+
69
+ it("is false when the server refuses the write", async () => {
70
+ vi.stubGlobal(
71
+ "fetch",
72
+ vi.fn(async () => new Response("{}", { status: 403 })),
73
+ );
74
+ expect(await saveRenderVariables("p", {})).toBe(false);
75
+ });
76
+
77
+ it("is false when the server cannot be reached", async () => {
78
+ vi.stubGlobal(
79
+ "fetch",
80
+ vi.fn(async () => {
81
+ throw new TypeError("Failed to fetch");
82
+ }),
83
+ );
84
+ expect(await saveRenderVariables("p", {})).toBe(false);
85
+ });
86
+ });
@@ -0,0 +1,28 @@
1
+ import { RENDER_VARIABLES_FILE } from "@hyperframes/core/project-folders";
2
+ import { buildProjectApiPath } from "../../utils/projectRouting";
3
+ import { studioApiFetch } from "../../utils/studioApiFetch";
4
+
5
+ // One literal word to sh, bash, zsh, fish, PowerShell and cmd.exe, also on cmd's second pass over npx.cmd's arguments.
6
+ // No one quoting is safe in all of them, so values go in a file and a path that is not such a word gets no command.
7
+ const SHELL_WORD = /^[A-Za-z0-9_][A-Za-z0-9_./-]*$/;
8
+
9
+ export function renderHandoffCommand(compPath: string): string | null {
10
+ if (!SHELL_WORD.test(compPath)) return null;
11
+ return `npx hyperframes render -c ${compPath} --variables-file ${RENDER_VARIABLES_FILE}`;
12
+ }
13
+
14
+ export async function saveRenderVariables(
15
+ projectId: string,
16
+ values: Record<string, unknown>,
17
+ ): Promise<boolean> {
18
+ try {
19
+ const response = await studioApiFetch(buildProjectApiPath(projectId, "/render-variables"), {
20
+ method: "PUT",
21
+ headers: { "Content-Type": "application/json" },
22
+ body: JSON.stringify(values),
23
+ });
24
+ return response.ok;
25
+ } catch {
26
+ return false;
27
+ }
28
+ }
@@ -372,6 +372,83 @@ describe("Popover", () => {
372
372
  });
373
373
  });
374
374
 
375
+ // fails without the fix: Escape in a modal opened from a popover's row closed the popover and cancelled the key, so the
376
+ // modal stayed open over a page with no popover (a paywall opened from a picker row).
377
+ describe("Escape goes to the topmost open layer", () => {
378
+ /** A modal opened above the popup, as a paywall from a picker row is: outside the popup, focus inside it. */
379
+ function modalAbove(): HTMLButtonElement {
380
+ const dialog = document.createElement("div");
381
+ dialog.setAttribute("role", "dialog");
382
+ dialog.setAttribute("aria-modal", "true");
383
+ const close = document.createElement("button");
384
+ dialog.append(close);
385
+ document.body.append(dialog);
386
+ act(() => close.focus());
387
+ return close;
388
+ }
389
+ /** Escape at `target`, and whether anything cancelled it. */
390
+ function escapeAt(target: Element): boolean {
391
+ const event = new KeyboardEvent("keydown", {
392
+ key: "Escape",
393
+ bubbles: true,
394
+ cancelable: true,
395
+ composed: true,
396
+ });
397
+ act(() => void target.dispatchEvent(event));
398
+ return event.defaultPrevented;
399
+ }
400
+
401
+ it("leaves a Popover open and the key uncancelled when the modal above it has focus; its own Escape still closes it", async () => {
402
+ render(
403
+ <Popover trigger={<button data-testid="trigger">Pickers</button>} aria-label="Pickers">
404
+ <button>Ultra</button>
405
+ </Popover>,
406
+ );
407
+ act(() => trigger().click());
408
+ await settle();
409
+ const close = modalAbove();
410
+ expect(escapeAt(close), "the modal's Escape is left to the modal").toBe(false);
411
+ await settle();
412
+ expect(document.querySelector('[aria-label="Pickers"]')).not.toBeNull();
413
+ close.parentElement!.remove();
414
+
415
+ escapeAt(one('[aria-label="Pickers"] button', "popover row"));
416
+ await settle();
417
+ expect(document.querySelector('[aria-label="Pickers"]')).toBeNull();
418
+ });
419
+
420
+ it("leaves a Menu open under a modal above it", async () => {
421
+ render(
422
+ <Menu trigger={<button data-testid="trigger">Model</button>} aria-label="Model">
423
+ <MenuItem>Ultra</MenuItem>
424
+ </Menu>,
425
+ );
426
+ act(() => trigger().click());
427
+ await settle();
428
+ expect(escapeAt(modalAbove())).toBe(false);
429
+ await settle();
430
+ expect(document.querySelector('[role="menu"]')).not.toBeNull();
431
+ });
432
+
433
+ it("closes a Popover opened from inside a dialog on Escape there: that dialog is under it, not above", async () => {
434
+ const dialog = document.createElement("dialog");
435
+ dialog.setAttribute("open", "");
436
+ document.body.append(dialog);
437
+ const host = render(
438
+ <Popover trigger={<button data-testid="trigger">Speed</button>} aria-label="Speed">
439
+ <span>1x</span>
440
+ </Popover>,
441
+ );
442
+ dialog.append(host);
443
+ act(() => trigger().click());
444
+ await settle();
445
+ escapeAt(trigger());
446
+ await settle();
447
+ expect(document.querySelector('[aria-label="Speed"]')).toBeNull();
448
+ dialog.remove();
449
+ });
450
+ });
451
+
375
452
  describe("hotkey classification", () => {
376
453
  it("classifies menu rows and popover contents the way the menus they replace were", async () => {
377
454
  // `typingTarget` and `playbackShortcuts` match exact role strings; Base UI renders
@@ -98,6 +98,45 @@ interface PositionedProps {
98
98
  "data-preview-state"?: PopupPreviewState;
99
99
  }
100
100
 
101
+ /** What Base UI hands `onOpenChange`: why it would close, the event, and a way to keep it open. */
102
+ type OpenChangeDetails = { reason: string; event: Event; cancel: () => void };
103
+
104
+ /**
105
+ * The topmost open layer owns Escape. Escape pressed inside a dialog that holds neither this popup nor its trigger (one
106
+ * opened from the popup's own row) keeps the popup open and leaves the key alone, so that dialog closes first; the
107
+ * popup hears the next Escape, once it is on top again.
108
+ */
109
+ export function useTopLayerEscape<D extends OpenChangeDetails>(
110
+ onOpenChange: ((open: boolean, details: D) => void) | undefined,
111
+ ) {
112
+ const own = useRef<{ popup: Element | null; trigger: Element | null }>({
113
+ popup: null,
114
+ trigger: null,
115
+ });
116
+ const change = (open: boolean, details: D) => {
117
+ const { popup, trigger } = own.current;
118
+ if (
119
+ !open &&
120
+ details.reason === "escape-key" &&
121
+ insideLayerAbove([popup, trigger], details.event)
122
+ )
123
+ return details.cancel();
124
+ onOpenChange?.(open, details);
125
+ };
126
+ return {
127
+ popup: (el: Element | null) => void (own.current.popup = el),
128
+ trigger: (el: Element | null) => void (own.current.trigger = el),
129
+ onOpenChange: change,
130
+ };
131
+ }
132
+
133
+ /** Whether `event` started inside an open dialog or modal that holds none of `own`. */
134
+ function insideLayerAbove(own: (Element | null)[], event: Event): boolean {
135
+ const from = event.composedPath()[0];
136
+ const layer = from instanceof Element ? from.closest('dialog[open], [aria-modal="true"]') : null;
137
+ return layer !== null && !own.some((el) => el !== null && layer.contains(el));
138
+ }
139
+
101
140
  interface MenuProps
102
141
  extends PositionedProps, Omit<ComponentPropsWithoutRef<typeof BaseMenu.Root>, "children"> {
103
142
  /** A single element. It becomes the trigger; no wrapper is added around it. */
@@ -123,9 +162,10 @@ export function Menu({
123
162
  ...root
124
163
  }: MenuProps) {
125
164
  const inline = useInlinePortal(container);
165
+ const escape = useTopLayerEscape(root.onOpenChange);
126
166
  return (
127
- <BaseMenu.Root {...root}>
128
- <BaseMenu.Trigger render={trigger} />
167
+ <BaseMenu.Root {...root} onOpenChange={escape.onOpenChange}>
168
+ <BaseMenu.Trigger ref={escape.trigger} render={trigger} />
129
169
  {inline.host}
130
170
  <BaseMenu.Portal {...inline.portal}>
131
171
  <BaseMenu.Positioner
@@ -136,6 +176,7 @@ export function Menu({
136
176
  className={POPUP_LAYER}
137
177
  >
138
178
  <BaseMenu.Popup
179
+ ref={escape.popup}
139
180
  aria-label={ariaLabel}
140
181
  data-preview-state={previewState}
141
182
  className={cn(menuPopup, className)}
@@ -169,13 +210,15 @@ export function ContextMenu({
169
210
  ...root
170
211
  }: Omit<ContextMenuProps, "side" | "align" | "sideOffset">) {
171
212
  const inline = useInlinePortal(container);
213
+ const escape = useTopLayerEscape(root.onOpenChange);
172
214
  return (
173
- <BaseContextMenu.Root {...root}>
174
- <BaseContextMenu.Trigger render={trigger} />
215
+ <BaseContextMenu.Root {...root} onOpenChange={escape.onOpenChange}>
216
+ <BaseContextMenu.Trigger ref={escape.trigger} render={trigger} />
175
217
  {inline.host}
176
218
  <BaseContextMenu.Portal {...inline.portal}>
177
219
  <BaseContextMenu.Positioner collisionPadding={VIEWPORT_MARGIN} className={POPUP_LAYER}>
178
220
  <BaseContextMenu.Popup
221
+ ref={escape.popup}
179
222
  aria-label={ariaLabel}
180
223
  data-preview-state={previewState}
181
224
  className={cn(menuPopup, className)}
@@ -12,6 +12,7 @@ import {
12
12
  useInlinePortal,
13
13
  type PopupPreviewState,
14
14
  type PortalContainer,
15
+ useTopLayerEscape,
15
16
  } from "./Menu";
16
17
 
17
18
  /** Matches Menu's gap from its trigger, and its viewport margin. */
@@ -71,9 +72,10 @@ export function Popover({
71
72
  ...root
72
73
  }: PopoverProps) {
73
74
  const inline = useInlinePortal(container);
75
+ const escape = useTopLayerEscape(root.onOpenChange);
74
76
  return (
75
- <BasePopover.Root {...root}>
76
- <BasePopover.Trigger render={trigger} aria-describedby={describedBy} />
77
+ <BasePopover.Root {...root} onOpenChange={escape.onOpenChange}>
78
+ <BasePopover.Trigger ref={escape.trigger} render={trigger} aria-describedby={describedBy} />
77
79
  {inline.host}
78
80
  <BasePopover.Portal {...inline.portal}>
79
81
  <BasePopover.Positioner
@@ -86,6 +88,7 @@ export function Popover({
86
88
  className={POPUP_LAYER}
87
89
  >
88
90
  <BasePopover.Popup
91
+ ref={escape.popup}
89
92
  aria-label={ariaLabel}
90
93
  initialFocus={initialFocus}
91
94
  data-preview-state={previewState}
@@ -0,0 +1,13 @@
1
+ import { describe, expect, it } from "vitest";
2
+ import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
3
+ import { getAnimationsForElement } from "./index";
4
+
5
+ const tween = (targetSelector: string) => ({ targetSelector }) as GsapAnimation;
6
+
7
+ describe("an element's animations from Studio's public API", () => {
8
+ it("are the parsed tweens that address it by id or selector, read where a sealed preview's host can", () => {
9
+ const parsed = [tween("#title"), tween(".card, .hero"), tween("#other")];
10
+ expect(getAnimationsForElement(parsed, { id: "title", selector: null })).toEqual([parsed[0]]);
11
+ expect(getAnimationsForElement(parsed, { id: null, selector: ".hero" })).toEqual([parsed[1]]);
12
+ });
13
+ });