@hyperframes/studio 0.9.38 → 0.9.39

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 (48) hide show
  1. package/dist/assets/{codec-Dz2VdhdD.js → codec-CY6KnWXa.js} +1 -1
  2. package/dist/assets/{hyperframes-player-BkaWdGLq.js → hyperframes-player-B9-CuG_h.js} +1 -1
  3. package/dist/assets/{index-BJTCbv8z.css → index-4VGEAZyf.css} +1 -1
  4. package/dist/assets/{index-DONaC7VF.js → index-Bjz2UaYv.js} +1 -1
  5. package/dist/assets/{index-DsNxqAwr.js → index-_pkzoYYF.js} +145 -145
  6. package/dist/assets/{pausedVideoDecoder-BGN2jKrN.js → pausedVideoDecoder-Dr7nKUUu.js} +1 -1
  7. package/dist/{chunk-63DH4LRB.js → chunk-44VRMER6.js} +2 -11
  8. package/dist/{chunk-45KKBU63.js → chunk-ATDO3YLX.js} +1 -1
  9. package/dist/chunk-FQ3VRKMC.js +148 -0
  10. package/dist/{chunk-YKBN653R.js → chunk-NBULUIWH.js} +252 -1
  11. package/dist/{domEditingLayers-7Q56QAU5.js → domEditingLayers-FRVHP6IB.js} +2 -2
  12. package/dist/index.d.ts +3 -85
  13. package/dist/index.html +2 -2
  14. package/dist/index.js +321 -341
  15. package/dist/keys-CaWcxUST.d.ts +86 -0
  16. package/dist/keys.d.ts +1 -0
  17. package/dist/keys.js +11 -0
  18. package/dist/player.js +2 -2
  19. package/dist/styles.css +1 -1
  20. package/package.json +12 -8
  21. package/src/components/editor/DomEditGestureReadout.test.tsx +204 -20
  22. package/src/components/editor/DomEditGestureReadout.tsx +36 -18
  23. package/src/components/editor/InlineTextToolbar.tsx +2 -2
  24. package/src/components/editor/domEditGestureReadoutPlacement.ts +144 -0
  25. package/src/components/editor/domEditGestureReadoutState.ts +18 -8
  26. package/src/components/editor/domEditingDom.ts +2 -15
  27. package/src/components/editor/useDomEditCompositionRect.ts +13 -4
  28. package/src/components/editor/useDomEditOverlayGestures.ts +1 -1
  29. package/src/components/editor/usePreviewCompositionRect.test.tsx +39 -0
  30. package/src/hooks/elementPickerStyles.ts +53 -0
  31. package/src/hooks/useElementPicker.test.ts +83 -3
  32. package/src/hooks/useElementPicker.ts +27 -66
  33. package/src/keys.test.ts +53 -0
  34. package/src/keys.ts +11 -0
  35. package/src/player/components/Player.tsx +2 -0
  36. package/src/player/components/studioKeyDefaults.ts +68 -0
  37. package/src/player/components/studioShortcuts.ts +2 -67
  38. package/src/player/hooks/playbackAdapterResolution.ts +15 -0
  39. package/src/player/hooks/previewMessageRouter.manifest.test.ts +67 -0
  40. package/src/player/hooks/previewMessageRouter.ts +38 -8
  41. package/src/player/hooks/timelinePlayerTestHarness.ts +26 -1
  42. package/src/player/hooks/useShadowPreviewReload.ts +4 -1
  43. package/src/player/hooks/useTimelinePlayer.ts +5 -9
  44. package/src/player/lib/bridgePlayback.ts +156 -0
  45. package/src/player/lib/previewChannel.test.ts +260 -0
  46. package/src/player/lib/previewChannel.ts +100 -0
  47. package/src/player/sceneSwap.test.ts +12 -0
  48. package/src/player/sceneSwap.ts +2 -0
@@ -0,0 +1,260 @@
1
+ // @vitest-environment happy-dom
2
+
3
+ import { afterEach, describe, expect, it, vi } from "vitest";
4
+ import {
5
+ AGENT_PROBE_MS,
6
+ previewClipManifest,
7
+ previewEditingClient,
8
+ previewFrameOpaque,
9
+ previewSeekPainted,
10
+ setFrameLoopStart,
11
+ } from "./previewChannel";
12
+ import { bridgePlaybackAdapter, watchPreviewFrame } from "./bridgePlayback";
13
+ import { runtimeProtocolMetadata } from "@hyperframes/core/runtime/protocol";
14
+ import { resolveFramePlaybackAdapter } from "../hooks/playbackAdapterResolution";
15
+ import { detachedFakeIframe, serveEditingRequests } from "../hooks/timelinePlayerTestHarness";
16
+
17
+ const closers: Array<() => void> = [];
18
+ afterEach(() => closers.splice(0).forEach((close) => close()));
19
+
20
+ /** A frame on another origin: any read of its window throws, as a browser's does. */
21
+ function opaqueFrame() {
22
+ const posted: unknown[] = [];
23
+ const postMessage = (message: unknown) => posted.push(message);
24
+ const frame = new Proxy({} as Record<string, unknown>, {
25
+ get: (_target, key) => {
26
+ if (key === "postMessage") return postMessage;
27
+ throw new DOMException(`blocked read of ${String(key)}`, "SecurityError");
28
+ },
29
+ });
30
+ const iframe = document.createElement("iframe");
31
+ iframe.setAttribute("sandbox", "allow-scripts");
32
+ Object.defineProperty(iframe, "contentWindow", { value: frame });
33
+ Object.defineProperty(iframe, "contentDocument", { value: null });
34
+ return { iframe, frame, posted };
35
+ }
36
+
37
+ /** Posts from `frame` as its runtime does, from an opaque origin unless told otherwise. */
38
+ function fromFrame(frame: object, data: Record<string, unknown>, origin = "null") {
39
+ const source = frame as Window;
40
+ window.dispatchEvent(
41
+ new MessageEvent("message", { source, origin, data: { source: "hf-preview", ...data } }),
42
+ );
43
+ }
44
+
45
+ /** A fake frame, same-origin unless `opaque`, whose runtime answers editing requests with `answer`. */
46
+ function servedFrame(answer: (kind: string, params: unknown) => unknown, opaque = false) {
47
+ const frame: Record<string, unknown> = {};
48
+ const iframe = detachedFakeIframe(frame);
49
+ if (opaque) {
50
+ Object.defineProperty(iframe, "contentDocument", { value: null });
51
+ Object.defineProperty(frame, "document", {
52
+ get: () => {
53
+ throw new DOMException("blocked", "SecurityError");
54
+ },
55
+ });
56
+ }
57
+ const handed = vi.fn(answer);
58
+ closers.push(serveEditingRequests(frame, handed));
59
+ return { iframe, frame, handed };
60
+ }
61
+
62
+ describe("previewFrameOpaque", () => {
63
+ it("is true only for a frame whose window refuses a read", () => {
64
+ expect(previewFrameOpaque(document.body.appendChild(document.createElement("iframe")))).toBe(
65
+ false,
66
+ );
67
+ expect(previewFrameOpaque(document.createElement("iframe"))).toBe(false);
68
+ expect(previewFrameOpaque(opaqueFrame().iframe)).toBe(true);
69
+ // A window that answers reads is not opaque, even with no document to hand.
70
+ const readable = document.createElement("iframe");
71
+ Object.defineProperty(readable, "contentWindow", { value: {} });
72
+ expect(previewFrameOpaque(readable)).toBe(false);
73
+ });
74
+ });
75
+
76
+ describe("previewEditingClient", () => {
77
+ it("keeps one client per frame load and opens a fresh one after the frame loads again", async () => {
78
+ const { iframe, handed } = servedFrame(() => ({ waited: false }));
79
+ const first = previewEditingClient(iframe);
80
+ expect(previewEditingClient(iframe)).toBe(first);
81
+ iframe.dispatchEvent(new Event("load"));
82
+ await expect(first.request("wait-for-seek", {})).rejects.toMatchObject({ code: "disposed" });
83
+ const second = previewEditingClient(iframe);
84
+ expect(second).not.toBe(first);
85
+ await expect(second.request("wait-for-seek", {})).resolves.toEqual({ waited: false });
86
+ expect(handed).toHaveBeenCalledOnce();
87
+ });
88
+
89
+ it("sends an opaque frame's loop start over the port, only when it changes", async () => {
90
+ const seen: unknown[] = [];
91
+ const { iframe } = servedFrame((_kind, params) => {
92
+ seen.push((params as { seconds: unknown }).seconds);
93
+ return { applied: true };
94
+ }, true);
95
+ setFrameLoopStart(iframe, 2);
96
+ setFrameLoopStart(iframe, 2);
97
+ setFrameLoopStart(iframe, null);
98
+ await vi.waitFor(() => expect(seen).toEqual([2, null]));
99
+ });
100
+
101
+ it("calls a scriptable frame's own loop-start hook and never opens a port", async () => {
102
+ const { iframe, frame, handed } = servedFrame(() => ({ applied: true }));
103
+ const setLoopStart = vi.fn();
104
+ frame.__hf = { setLoopStart };
105
+ setFrameLoopStart(iframe, 2);
106
+ setFrameLoopStart(iframe, 2);
107
+ expect(setLoopStart.mock.calls).toEqual([[2], [2]]);
108
+ await new Promise((resolve) => setTimeout(resolve, 20));
109
+ expect(handed).not.toHaveBeenCalled();
110
+ delete frame.__hf;
111
+ expect(() => setFrameLoopStart(iframe, null)).not.toThrow();
112
+ });
113
+
114
+ it("waits for the runtime's seek to paint, and settles anyway when no runtime answers", async () => {
115
+ const { iframe, handed } = servedFrame(() => ({ waited: true }));
116
+ await previewSeekPainted(iframe);
117
+ expect(handed).toHaveBeenCalledWith("wait-for-seek", {});
118
+ const started = Date.now();
119
+ await previewSeekPainted(opaqueFrame().iframe, 15_000);
120
+ expect(Date.now() - started).toBeLessThan(AGENT_PROBE_MS + 500);
121
+ });
122
+
123
+ it("returns the runtime's manifest only when its reply has the manifest's shape", async () => {
124
+ const manifest = { clips: [], durationInFrames: 30, scenes: [] };
125
+ let reply: unknown = { clipManifest: manifest };
126
+ const { iframe } = servedFrame(() => reply);
127
+ expect(await previewClipManifest(iframe)).toEqual(manifest);
128
+ for (const bad of [
129
+ null,
130
+ { clipManifest: "x" },
131
+ { clipManifest: { clips: {}, durationInFrames: 30 } },
132
+ { clipManifest: { clips: [], durationInFrames: "30" } },
133
+ ]) {
134
+ reply = bad;
135
+ expect(await previewClipManifest(iframe)).toBeNull();
136
+ }
137
+ reply = { clipManifest: { clips: [], durationInFrames: Infinity } };
138
+ expect(await previewClipManifest(iframe)).toBeNull();
139
+ });
140
+ });
141
+
142
+ describe("bridge playback for a frame Studio cannot script", () => {
143
+ const refs = () => ({ cache: { current: null }, warned: { current: false } });
144
+
145
+ it("drives the runtime with control messages and never reads the frame's window", () => {
146
+ const { iframe, posted } = opaqueFrame();
147
+ const adapter = resolveFramePlaybackAdapter(iframe, refs());
148
+ expect(adapter).not.toBeNull();
149
+ adapter!.play();
150
+ adapter!.seek(4);
151
+ adapter!.pause();
152
+ expect(posted).toEqual([
153
+ expect.objectContaining({ source: "hf-parent", type: "control", action: "play" }),
154
+ expect.objectContaining({ action: "seek", timeSeconds: 4 }),
155
+ expect.objectContaining({ action: "pause" }),
156
+ ]);
157
+ expect(adapter!.getTime()).toBe(4);
158
+ expect(adapter!.isPlaying()).toBe(false);
159
+ });
160
+
161
+ it("keeps a seek until the runtime confirms it, so a state posted before it cannot undo it", () => {
162
+ const { iframe, frame } = opaqueFrame();
163
+ const adapter = bridgePlaybackAdapter(iframe)!;
164
+ const clock = vi.spyOn(performance, "now").mockReturnValue(1_000);
165
+ try {
166
+ adapter.seek(4);
167
+ fromFrame(frame, { type: "state", currentTime: 1, isPlaying: false });
168
+ expect(adapter.getTime()).toBe(4);
169
+ fromFrame(frame, { type: "state", currentTime: 4, isPlaying: false });
170
+ fromFrame(frame, { type: "state", currentTime: 4.5, isPlaying: true });
171
+ expect(adapter.getTime()).toBe(4.5);
172
+ adapter.seek(99);
173
+ clock.mockReturnValue(2_000);
174
+ fromFrame(frame, { type: "state", currentTime: 12, isPlaying: false });
175
+ expect(adapter.getTime()).toBe(12);
176
+ } finally {
177
+ clock.mockRestore();
178
+ }
179
+ });
180
+
181
+ it("takes a seek the runtime landed on the frame before it, and plays on", () => {
182
+ const { iframe, frame } = opaqueFrame();
183
+ const adapter = bridgePlaybackAdapter(iframe)!;
184
+ const at30fps = runtimeProtocolMetadata(30);
185
+ adapter.seek(4.01);
186
+ fromFrame(frame, { type: "state", currentTime: 4, isPlaying: true, ...at30fps });
187
+ expect(adapter.getTime()).toBe(4);
188
+ expect(adapter.isPlaying()).toBe(true);
189
+ fromFrame(frame, { type: "state", currentTime: 4.3, isPlaying: true, ...at30fps });
190
+ expect(adapter.getTime()).toBe(4.3);
191
+ });
192
+
193
+ it("ignores a post from a window it was not built for, or from an origin its frame cannot have", () => {
194
+ const opaque = opaqueFrame();
195
+ const adapter = bridgePlaybackAdapter(opaque.iframe)!;
196
+ const stranger = opaqueFrame();
197
+ fromFrame(stranger.frame, { type: "state", currentTime: 9, isPlaying: true });
198
+ fromFrame(opaque.frame, { type: "state", currentTime: 8, isPlaying: true }, location.origin);
199
+ fromFrame(
200
+ opaque.frame,
201
+ { type: "state", currentTime: 7, isPlaying: true },
202
+ "https://example.com",
203
+ );
204
+ expect(adapter.getTime()).toBe(0);
205
+ // A post from a frame nobody registered is dropped, not kept for a later adapter.
206
+ expect(bridgePlaybackAdapter(stranger.iframe)!.getTime()).toBe(0);
207
+ fromFrame(opaque.frame, { type: "state", currentTime: 2, isPlaying: false });
208
+ expect(adapter.getTime()).toBe(2);
209
+
210
+ const sameOrigin = document.createElement("iframe");
211
+ sameOrigin.src = "/preview/index.html";
212
+ const frame = {};
213
+ Object.defineProperty(sameOrigin, "contentWindow", { value: frame });
214
+ watchPreviewFrame(sameOrigin);
215
+ const own = bridgePlaybackAdapter(sameOrigin)!;
216
+ fromFrame(frame, { type: "state", currentTime: 5, isPlaying: false }, "null");
217
+ expect(own.getTime()).toBe(0);
218
+ fromFrame(frame, { type: "state", currentTime: 5, isPlaying: false }, location.origin);
219
+ expect(own.getTime()).toBe(5);
220
+ });
221
+
222
+ it.each([
223
+ ["srcdoc", (f: HTMLIFrameElement) => f.setAttribute("srcdoc", "<p>x</p>"), location.origin],
224
+ [
225
+ "about:blank",
226
+ (f: HTMLIFrameElement) => f.setAttribute("src", "about:blank"),
227
+ location.origin,
228
+ ],
229
+ ["a data: URL", (f: HTMLIFrameElement) => f.setAttribute("src", "data:text/html,x"), "null"],
230
+ [
231
+ "another origin",
232
+ (f: HTMLIFrameElement) => f.setAttribute("src", "https://a.test/p"),
233
+ "https://a.test",
234
+ ],
235
+ ])("accepts a frame loading %s only from the origin it has", (_name, load, origin) => {
236
+ const iframe = document.createElement("iframe");
237
+ load(iframe);
238
+ const frame = {};
239
+ Object.defineProperty(iframe, "contentWindow", { value: frame });
240
+ const adapter = bridgePlaybackAdapter(iframe)!;
241
+ const wrong = origin === "null" ? location.origin : "null";
242
+ fromFrame(frame, { type: "state", currentTime: 3, isPlaying: false }, wrong);
243
+ expect(adapter.getTime()).toBe(0);
244
+ fromFrame(frame, { type: "state", currentTime: 3, isPlaying: false }, origin);
245
+ expect(adapter.getTime()).toBe(3);
246
+ });
247
+
248
+ it("takes time, play state and duration from its own frame's state and timeline messages", () => {
249
+ const { iframe, frame } = opaqueFrame();
250
+ const other = opaqueFrame();
251
+ const adapter = bridgePlaybackAdapter(iframe)!;
252
+ fromFrame(frame, { type: "timeline", durationSeconds: 12, clips: [] });
253
+ fromFrame(frame, { type: "state", currentTime: 3.5, isPlaying: true });
254
+ fromFrame(other.frame, { type: "state", currentTime: 9, isPlaying: false });
255
+ fromFrame(frame, { type: "state", currentTime: Number.NaN, isPlaying: true });
256
+ expect(adapter.getDuration()).toBe(12);
257
+ expect(adapter.getTime()).toBe(3.5);
258
+ expect(adapter.isPlaying()).toBe(true);
259
+ });
260
+ });
@@ -0,0 +1,100 @@
1
+ // Runtime-state reads over a preview frame's editing port; an opaque frame's window is out of reach.
2
+ import {
3
+ createEditingPortClient,
4
+ type EditingPortClient,
5
+ } from "@hyperframes/core/runtime/editing-port";
6
+ import type { ClipManifest, IframeWindow } from "./playbackTypes";
7
+
8
+ const clients = new WeakMap<HTMLIFrameElement, EditingPortClient>();
9
+ const loopStarts = new WeakMap<EditingPortClient, number | null>();
10
+
11
+ /** A frame whose window refuses Studio's reads; one with no window has nothing to reach either way. */
12
+ export function previewFrameOpaque(iframe: HTMLIFrameElement): boolean {
13
+ const win = iframe.contentWindow;
14
+ if (!win) return false;
15
+ try {
16
+ void win.document;
17
+ return false;
18
+ } catch {
19
+ return true;
20
+ }
21
+ }
22
+
23
+ /** One client per frame load: the frame's next load disposes it. */
24
+ export function previewEditingClient(iframe: HTMLIFrameElement): EditingPortClient {
25
+ const open = clients.get(iframe);
26
+ if (open) return open;
27
+ const client = createEditingPortClient({ iframe });
28
+ clients.set(iframe, client);
29
+ const onLoad = () => {
30
+ client.dispose();
31
+ if (clients.get(iframe) === client) clients.delete(iframe);
32
+ };
33
+ iframe.addEventListener("load", onLoad, { once: true });
34
+ return client;
35
+ }
36
+
37
+ export function setFrameLoopStart(iframe: HTMLIFrameElement, seconds: number | null): void {
38
+ if (!previewFrameOpaque(iframe)) {
39
+ try {
40
+ (iframe.contentWindow as IframeWindow | null)?.__hf?.setLoopStart?.(seconds);
41
+ } catch {}
42
+ return;
43
+ }
44
+ const client = previewEditingClient(iframe);
45
+ if (loopStarts.has(client) && loopStarts.get(client) === seconds) return;
46
+ loopStarts.set(client, seconds);
47
+ client.request("set-loop-start", { seconds }).catch(() => {
48
+ if (loopStarts.get(client) === seconds) loopStarts.delete(client);
49
+ });
50
+ }
51
+
52
+ export const AGENT_PROBE_MS = 1_000;
53
+
54
+ /** Gives up after AGENT_PROBE_MS with no port: a runtime without the editing agent never answers. */
55
+ export async function previewSeekPainted(iframe: HTMLIFrameElement, timeoutMs?: number) {
56
+ const client = previewEditingClient(iframe);
57
+ let timer: ReturnType<typeof setTimeout> | undefined;
58
+ const probe = new Promise<boolean>(
59
+ (resolve) => (timer = setTimeout(resolve, AGENT_PROBE_MS, false)),
60
+ );
61
+ const connected = await Promise.race([
62
+ client.ready.then(
63
+ () => true,
64
+ () => false,
65
+ ),
66
+ probe,
67
+ ]);
68
+ clearTimeout(timer);
69
+ if (connected) await client.request("wait-for-seek", {}, { timeoutMs }).catch(() => {});
70
+ }
71
+
72
+ /** The reply is frame data, so its shape is checked. */
73
+ export async function previewClipManifest(iframe: HTMLIFrameElement): Promise<ClipManifest | null> {
74
+ const snapshot = await previewEditingClient(iframe).request("runtime-snapshot", {});
75
+ const manifest: unknown = snapshot?.clipManifest;
76
+ if (typeof manifest !== "object" || manifest === null) return null;
77
+ const { clips, durationInFrames } = manifest as Partial<ClipManifest>;
78
+ if (!Array.isArray(clips) || typeof durationInFrames !== "number") return null;
79
+ if (!Number.isFinite(durationInFrames)) return null;
80
+ return manifest as ClipManifest;
81
+ }
82
+
83
+ /** The runtime's computed `properties` for the element `selector` names; null when it has none. */
84
+ export async function previewComputedStyles(
85
+ iframe: HTMLIFrameElement,
86
+ selector: string,
87
+ properties: string[],
88
+ ): Promise<Record<string, string> | null> {
89
+ const reply = await previewEditingClient(iframe)
90
+ .request("computed-styles", { selector, properties })
91
+ .catch(() => null);
92
+ const styles: unknown = reply?.styles;
93
+ if (typeof styles !== "object" || styles === null) return null;
94
+ const read: Record<string, string> = {};
95
+ for (const name of properties) {
96
+ const value: unknown = Object.getOwnPropertyDescriptor(styles, name)?.value;
97
+ if (typeof value === "string" && value) read[name] = value;
98
+ }
99
+ return read;
100
+ }
@@ -24,6 +24,18 @@ function swappableIframe(swap: Swap = vi.fn(async () => {})) {
24
24
  }
25
25
 
26
26
  describe("sceneSwapFor", () => {
27
+ it("returns no swap for an opaque frame, without reading its window", () => {
28
+ const iframe = document.createElement("iframe");
29
+ const blocked = new Proxy({} as Window, {
30
+ get: () => {
31
+ throw new DOMException("blocked", "SecurityError");
32
+ },
33
+ });
34
+ Object.defineProperty(iframe, "contentWindow", { value: blocked });
35
+ Object.defineProperty(iframe, "contentDocument", { value: null });
36
+ expect(sceneSwapFor(iframe)).toBeNull();
37
+ });
38
+
27
39
  it("gives up on a preview download that never finishes, so the caller can reload", async () => {
28
40
  vi.useFakeTimers();
29
41
  vi.spyOn(globalThis, "fetch").mockImplementation(
@@ -2,6 +2,7 @@ import { studioApiFetch } from "../utils/studioApiFetch";
2
2
  import { studioFileRevision } from "../utils/studioFileVersion";
3
3
  import { logReload } from "../utils/reloadDebug";
4
4
  import { whileScriptWrites } from "./previewReloading";
5
+ import { previewFrameOpaque } from "./lib/previewChannel";
5
6
 
6
7
  type SwapWindow = Window & {
7
8
  __hfSwapScenes?: (html: string, signal?: AbortSignal) => Promise<void>;
@@ -114,6 +115,7 @@ export function swapFreshly(
114
115
  export function sceneSwapFor(
115
116
  iframe: HTMLIFrameElement,
116
117
  ): ((url: string, isCurrent: () => boolean, cancel?: AbortSignal) => Promise<void>) | null {
118
+ if (previewFrameOpaque(iframe)) return null;
117
119
  const win = iframe.contentWindow as SwapWindow | null;
118
120
  const swap = win?.__hfSwapScenes;
119
121
  if (typeof swap !== "function") return null;