Files
hyperframes/packages/core/src/runtime/bridge.test.ts
T
Miguel Ángel 840f657028 feat(player): play and loop a range of a film with range-start and range-end (#4688)
* feat(player): play and loop a range of the film with range-start and range-end

The runtime takes a set-play-range control and stops on the range end frame itself.
The player wraps to range-start with loop, fires ended without it, and reports a
range cut to the film with rangeclamped. Video and __timelines players check it per tick.

* fix(player): hold a range on its last frame and let the runtime own range jumps

A runtime with the play-range capability jumps to range-start itself when a new range leaves
the playhead outside, so a stale state no longer ends the film; older runtimes keep the
player fallback, guarded until a state lands inside. Every range stop shows the last frame
before range-end; a paused playhead re-parks only when it falls outside the new range.

* fix(player): stop a range a check early and enforce its end on a video in a background tab

* test(player): share the range video setup

* fix(player): a slow frame no longer cuts a range short; a video without a range is unchanged

* fix(player): a range still stops early where video time moves once per frame

* refactor(player): cut the range look-ahead comment to one line

* fix(player): a per-frame video time rounded down still stops a range early

* test(player): pin no rounding tolerance at a film's own end

* test(studio): expect the play-range capability on control messages
2026-09-28 23:38:32 +00:00

384 lines
14 KiB
TypeScript

import { describe, it, expect, vi } from "vitest";
import { installRuntimeControlBridge } from "./bridge";
function createMockDeps() {
return {
onPlay: vi.fn(),
onPause: vi.fn(),
onStopMedia: vi.fn(),
onSeek: vi.fn(),
onTick: vi.fn(),
onSetMuted: vi.fn(),
onSetVolume: vi.fn(),
onSetMediaOutputMuted: vi.fn(),
onSetNativeMediaSyncDisabled: vi.fn(),
onSetWebAudioMediaDisabled: vi.fn(),
onSetPlaybackRate: vi.fn(),
onSetIdleHeartbeat: vi.fn(),
onSetColorGrading: vi.fn(),
onSetColorGradingCompare: vi.fn(),
onSetRootDuration: vi.fn(),
onSetPlayRange: vi.fn(),
onEnablePickMode: vi.fn(),
onDisablePickMode: vi.fn(),
onSetRuntimeData: vi.fn(),
onClearRuntimeData: vi.fn(),
getCanonicalFps: vi.fn(() => 30),
};
}
function makeControlMessage(action: string, extra?: Record<string, unknown>) {
return new MessageEvent("message", {
source: window.parent,
data: { source: "hf-parent", type: "control", action, ...extra },
});
}
describe("installRuntimeControlBridge", () => {
it("ignores inherited and unknown action names from an authorized sender", () => {
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
try {
for (const action of [
"__proto__",
"constructor",
"hasOwnProperty",
"__defineGetter__",
"toString",
"unknown",
]) {
expect(() => handler(makeControlMessage(action))).not.toThrow();
}
expect(deps.onPlay).not.toHaveBeenCalled();
handler(makeControlMessage("play"));
expect(deps.onPlay).toHaveBeenCalledOnce();
} finally {
window.removeEventListener("message", handler);
}
});
it("rejects foreign and null senders before dispatching controls", () => {
const foreign = document.createElement("iframe");
document.body.append(foreign);
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
try {
for (const source of [foreign.contentWindow, null]) {
handler(
new MessageEvent("message", {
source,
data: { source: "hf-parent", type: "control", action: "play" },
}),
);
}
expect(deps.onPlay).not.toHaveBeenCalled();
handler(
new MessageEvent("message", {
source: window,
data: { source: "hf-parent", type: "control", action: "play" },
}),
);
expect(deps.onPlay).toHaveBeenCalledOnce();
} finally {
window.removeEventListener("message", handler);
foreign.remove();
}
});
it("accepts an embedding parent distinct from the runtime window", () => {
const frame = document.createElement("iframe");
document.body.append(frame);
vi.stubGlobal("parent", frame.contentWindow);
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
try {
handler(makeControlMessage("play"));
expect(deps.onPlay).toHaveBeenCalledOnce();
} finally {
window.removeEventListener("message", handler);
vi.unstubAllGlobals();
frame.remove();
}
});
it("dispatches play command", () => {
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
handler(makeControlMessage("play"));
expect(deps.onPlay).toHaveBeenCalledOnce();
});
it("dispatches pause command", () => {
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
handler(makeControlMessage("pause"));
expect(deps.onPause).toHaveBeenCalledOnce();
});
it("dispatches set and clear runtime data without global invocation", () => {
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
const payload = { version: 3, segments: [] };
handler(
makeControlMessage("set-runtime-data", { channel: "captions", payload, requestId: 41 }),
);
handler(makeControlMessage("clear-runtime-data", { channel: "captions", requestId: 42 }));
expect(deps.onSetRuntimeData).toHaveBeenCalledWith("captions", payload, 41);
expect(deps.onClearRuntimeData).toHaveBeenCalledWith("captions", 42);
});
it("dispatches stop-media command", () => {
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
handler(makeControlMessage("stop-media"));
expect(deps.onStopMedia).toHaveBeenCalledOnce();
});
it("dispatches seek command with frame and mode", () => {
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
handler(makeControlMessage("seek", { frame: 150, seekMode: "drag" }));
expect(deps.onSeek).toHaveBeenCalledWith(5, "drag");
});
it("prefers canonical seconds in protocol v1 seek messages", () => {
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
handler(
makeControlMessage("seek", {
protocolVersion: 1,
capabilities: ["seconds-time", "rational-fps", "seek-keep-playing"],
fps: { numerator: 60, denominator: 1 },
timeSeconds: 2.5,
frame: 999,
}),
);
expect(deps.onSeek).toHaveBeenCalledWith(2.5, "commit");
});
it("seek defaults frame to 0 and seekMode to commit", () => {
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
handler(makeControlMessage("seek"));
expect(deps.onSeek).toHaveBeenCalledWith(0, "commit");
});
it("dispatches set-muted command", () => {
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
handler(makeControlMessage("set-muted", { muted: true }));
expect(deps.onSetMuted).toHaveBeenCalledWith(true);
});
it("dispatches set-volume command", () => {
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
handler(makeControlMessage("set-volume", { volume: 0.5 }));
expect(deps.onSetVolume).toHaveBeenCalledWith(0.5);
});
it("clamps set-volume to [0, 1]", () => {
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
handler(makeControlMessage("set-volume", { volume: 1.5 }));
expect(deps.onSetVolume).toHaveBeenCalledWith(1);
handler(makeControlMessage("set-volume", { volume: -0.5 }));
expect(deps.onSetVolume).toHaveBeenCalledWith(0);
});
it("defaults volume to 1 when absent", () => {
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
handler(makeControlMessage("set-volume"));
expect(deps.onSetVolume).toHaveBeenCalledWith(1);
});
it("dispatches set-media-output-muted command", () => {
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
handler(makeControlMessage("set-media-output-muted", { muted: true }));
expect(deps.onSetMediaOutputMuted).toHaveBeenCalledWith(true);
handler(makeControlMessage("set-media-output-muted", { muted: false }));
expect(deps.onSetMediaOutputMuted).toHaveBeenCalledWith(false);
});
it("set-media-output-muted coerces absent flag to false", () => {
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
handler(makeControlMessage("set-media-output-muted"));
expect(deps.onSetMediaOutputMuted).toHaveBeenCalledWith(false);
});
it("dispatches set-native-media-sync-disabled command", () => {
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
handler(makeControlMessage("set-native-media-sync-disabled", { disabled: true }));
expect(deps.onSetNativeMediaSyncDisabled).toHaveBeenCalledWith(true);
handler(makeControlMessage("set-native-media-sync-disabled", { disabled: false }));
expect(deps.onSetNativeMediaSyncDisabled).toHaveBeenCalledWith(false);
});
it("set-native-media-sync-disabled coerces absent flag to false", () => {
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
handler(makeControlMessage("set-native-media-sync-disabled"));
expect(deps.onSetNativeMediaSyncDisabled).toHaveBeenCalledWith(false);
});
it("dispatches set-web-audio-media-disabled command", () => {
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
handler(makeControlMessage("set-web-audio-media-disabled", { disabled: true }));
expect(deps.onSetWebAudioMediaDisabled).toHaveBeenCalledWith(true);
handler(makeControlMessage("set-web-audio-media-disabled", { disabled: false }));
expect(deps.onSetWebAudioMediaDisabled).toHaveBeenCalledWith(false);
});
it("set-web-audio-media-disabled coerces absent flag to false", () => {
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
handler(makeControlMessage("set-web-audio-media-disabled"));
expect(deps.onSetWebAudioMediaDisabled).toHaveBeenCalledWith(false);
});
it("dispatches set-playback-rate command", () => {
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
handler(makeControlMessage("set-playback-rate", { playbackRate: 2 }));
expect(deps.onSetPlaybackRate).toHaveBeenCalledWith(2);
});
it("defaults playbackRate to 1", () => {
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
handler(makeControlMessage("set-playback-rate"));
expect(deps.onSetPlaybackRate).toHaveBeenCalledWith(1);
});
it("dispatches set-root-duration command with numeric seconds", () => {
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
handler(makeControlMessage("set-root-duration", { durationSeconds: "18.5" }));
expect(deps.onSetRootDuration).toHaveBeenCalledWith(18.5);
});
it("dispatches set-play-range with numeric seconds, and null for an open end", () => {
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
handler(makeControlMessage("set-play-range", { startSeconds: "2", endSeconds: 3.5 }));
handler(makeControlMessage("set-play-range", { startSeconds: null, endSeconds: null }));
expect(deps.onSetPlayRange.mock.calls).toEqual([
[2, 3.5],
[0, null],
]);
});
it("dispatches set-color-grading command with target and grading payload", () => {
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
const grading = { preset: "warm-daylight", intensity: 0.7 };
const target = { id: "hero-video", selectorIndex: 0 };
handler(makeControlMessage("set-color-grading", { target, grading }));
expect(deps.onSetColorGrading).toHaveBeenCalledWith(target, grading);
});
it("dispatches set-color-grading-compare command with target and compare payload", () => {
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
const compare = { enabled: true, position: 0.42 };
const target = { id: "hero-video", selectorIndex: 0 };
handler(makeControlMessage("set-color-grading-compare", { target, compare }));
expect(deps.onSetColorGradingCompare).toHaveBeenCalledWith(target, compare);
});
it("dispatches tick command", () => {
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
handler(makeControlMessage("tick"));
expect(deps.onTick).toHaveBeenCalledOnce();
});
it("dispatches enable-pick-mode", () => {
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
handler(makeControlMessage("enable-pick-mode"));
expect(deps.onEnablePickMode).toHaveBeenCalledOnce();
});
it("dispatches disable-pick-mode", () => {
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
handler(makeControlMessage("disable-pick-mode"));
expect(deps.onDisablePickMode).toHaveBeenCalledOnce();
});
it("ignores messages from wrong source", () => {
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
handler(
new MessageEvent("message", {
data: { source: "other", type: "control", action: "play" },
}),
);
expect(deps.onPlay).not.toHaveBeenCalled();
});
it("ignores messages with wrong type", () => {
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
handler(
new MessageEvent("message", {
data: { source: "hf-parent", type: "state", action: "play" },
}),
);
expect(deps.onPlay).not.toHaveBeenCalled();
});
it("ignores null data", () => {
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
handler(new MessageEvent("message", { data: null }));
expect(deps.onPlay).not.toHaveBeenCalled();
});
it("handles flash-elements command without crashing", () => {
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
expect(() =>
handler(makeControlMessage("flash-elements", { selectors: [".test"], duration: 500 })),
).not.toThrow();
});
it("posts a ready message to window.parent on install", () => {
// The bridge announces itself so the parent can replay any control
// messages it posted before the iframe runtime's listener was installed.
const postSpy = vi.spyOn(window.parent, "postMessage");
const deps = createMockDeps();
installRuntimeControlBridge(deps);
expect(postSpy).toHaveBeenCalledWith(
expect.objectContaining({
source: "hf-preview",
type: "ready",
protocolVersion: 1,
fps: { numerator: 30, denominator: 1 },
}),
"*",
);
postSpy.mockRestore();
});
it("rejects an unknown protocol major with a diagnostic", () => {
const postSpy = vi.spyOn(window.parent, "postMessage");
const deps = createMockDeps();
const handler = installRuntimeControlBridge(deps);
handler(makeControlMessage("play", { protocolVersion: 2 }));
expect(deps.onPlay).not.toHaveBeenCalled();
expect(postSpy).toHaveBeenCalledWith(
expect.objectContaining({
type: "diagnostic",
code: "runtime.protocol.unsupported_protocol_version",
}),
"*",
);
postSpy.mockRestore();
});
});