Skip to content

Commit 4f00336

Browse files
authored
feat(player): add retained runtime data channels (#3471)
1 parent 9aaa755 commit 4f00336

17 files changed

Lines changed: 422 additions & 21 deletions

‎packages/core/src/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
// Types
2+
export type { RuntimeTimelineClipIdentity } from "./runtime/types.js";
23
export type {
34
ExecutionMode,
45
Orientation,

‎packages/core/src/runtime/bridge.test.ts‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,8 @@ function createMockDeps() {
1919
onSetRootDuration: vi.fn(),
2020
onEnablePickMode: vi.fn(),
2121
onDisablePickMode: vi.fn(),
22+
onSetRuntimeData: vi.fn(),
23+
onClearRuntimeData: vi.fn(),
2224
getCanonicalFps: vi.fn(() => 30),
2325
};
2426
}
@@ -44,6 +46,16 @@ describe("installRuntimeControlBridge", () => {
4446
expect(deps.onPause).toHaveBeenCalledOnce();
4547
});
4648

49+
it("dispatches set and clear runtime data without global invocation", () => {
50+
const deps = createMockDeps();
51+
const handler = installRuntimeControlBridge(deps);
52+
const payload = { version: 3, segments: [] };
53+
handler(makeControlMessage("set-runtime-data", { channel: "captions", payload }));
54+
handler(makeControlMessage("clear-runtime-data", { channel: "captions" }));
55+
expect(deps.onSetRuntimeData).toHaveBeenCalledWith("captions", payload);
56+
expect(deps.onClearRuntimeData).toHaveBeenCalledWith("captions");
57+
});
58+
4759
it("dispatches stop-media command", () => {
4860
const deps = createMockDeps();
4961
const handler = installRuntimeControlBridge(deps);

‎packages/core/src/runtime/bridge.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,8 @@ type BridgeDeps = {
2828
) => void;
2929
onEnablePickMode: () => void;
3030
onDisablePickMode: () => void;
31+
onSetRuntimeData?: (channel: string, payload: unknown) => void;
32+
onClearRuntimeData?: (channel: string) => void;
3133
getCanonicalFps: () => number;
3234
};
3335

@@ -75,6 +77,12 @@ const CONTROL_HANDLERS: Record<string, ControlHandler> = {
7577
"enable-pick-mode": (_d, deps) => deps.onEnablePickMode(),
7678
"disable-pick-mode": (_d, deps) => deps.onDisablePickMode(),
7779
"flash-elements": (data) => handleFlashElements(data),
80+
"set-runtime-data": (data, deps) => {
81+
if (typeof data.channel === "string") deps.onSetRuntimeData?.(data.channel, data.payload);
82+
},
83+
"clear-runtime-data": (data, deps) => {
84+
if (typeof data.channel === "string") deps.onClearRuntimeData?.(data.channel);
85+
},
7886
};
7987

8088
function resolveSeekTimeSeconds(data: BridgeControlData, deps: BridgeDeps): number {

‎packages/core/src/runtime/entry.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,17 @@ import { installAuthoredOpacityCapture } from "./colorGrading";
33
import { fitTextFontSize } from "../text/fitTextFontSize";
44
import { pretext } from "../text/pretext";
55
import { getVariables } from "./getVariables";
6+
import { clearRuntimeData, registerRuntimeDataHandler, setRuntimeData } from "./runtimeData";
67

78
type HyperframeWindow = Window & {
89
__hyperframeRuntimeBootstrapped?: boolean;
910
__hyperframes?: {
1011
fitTextFontSize: typeof fitTextFontSize;
1112
getVariables: typeof getVariables;
1213
pretext: typeof pretext;
14+
registerRuntimeDataHandler: typeof registerRuntimeDataHandler;
15+
setRuntimeData: typeof setRuntimeData;
16+
clearRuntimeData: typeof clearRuntimeData;
1317
};
1418
};
1519

@@ -29,6 +33,9 @@ installAuthoredOpacityCapture();
2933
fitTextFontSize,
3034
getVariables,
3135
pretext,
36+
registerRuntimeDataHandler,
37+
setRuntimeData,
38+
clearRuntimeData,
3239
};
3340

3441
function bootstrapHyperframeRuntime(): void {

‎packages/core/src/runtime/init.ts‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,7 @@ import { shouldAttemptPeriodicTimelineBind } from "./timelineRebindPolicy";
6767
import { installStudioCustomEase } from "./customEase";
6868
import { parseNumeric } from "./startExpression";
6969
import { parseStrictFiniteTimingNumber } from "./playbackRate";
70+
import { clearRuntimeData, setRuntimeData, setRuntimeDataErrorReporter } from "./runtimeData";
7071

7172
const AUTHORED_DURATION_ATTR = "data-hf-authored-duration";
7273
const AUTHORED_END_ATTR = "data-hf-authored-end";
@@ -132,6 +133,14 @@ export function initSandboxRuntimeModular(): void {
132133
// Own the analytics bridge before any best-effort runtime installation so
133134
// early failures are observable instead of disappearing before player setup.
134135
initRuntimeAnalytics(postRuntimeMessage as (payload: unknown) => void);
136+
setRuntimeDataErrorReporter((channel, error) => {
137+
postRuntimeMessage({
138+
source: "hf-preview",
139+
type: "runtime-data-error",
140+
channel,
141+
message: error instanceof Error ? error.message : String(error),
142+
});
143+
});
135144
// SDK moveElement edits must render even when no usable GSAP timeline ever
136145
// binds (CSS/WAAPI-animated or fully static compositions) — apply at init.
137146
// This runs at DOMContentLoaded, after inline composition scripts have
@@ -3383,6 +3392,8 @@ export function initSandboxRuntimeModular(): void {
33833392
},
33843393
onEnablePickMode: () => picker.enablePickMode(),
33853394
onDisablePickMode: () => picker.disablePickMode(),
3395+
onSetRuntimeData: setRuntimeData,
3396+
onClearRuntimeData: clearRuntimeData,
33863397
getCanonicalFps: () => state.canonicalFps,
33873398
});
33883399

‎packages/core/src/runtime/protocol.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ export const RUNTIME_PROTOCOL_CAPABILITIES = [
55
"rational-fps",
66
"seek-keep-playing",
77
"composition-manifest-v1",
8+
"runtime-data",
89
] as const;
910

1011
export type RuntimeProtocolFps = {
Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
import { beforeEach, describe, expect, it, vi } from "vitest";
2+
import {
3+
clearRuntimeData,
4+
registerRuntimeDataHandler,
5+
resetRuntimeDataForTests,
6+
setRuntimeData,
7+
setRuntimeDataErrorReporter,
8+
} from "./runtimeData";
9+
10+
describe("runtime data registry", () => {
11+
beforeEach(resetRuntimeDataForTests);
12+
13+
it("delivers retained data when the handler registers later", () => {
14+
const handler = vi.fn();
15+
setRuntimeData("captions", { words: ["before"] });
16+
registerRuntimeDataHandler("captions", handler);
17+
expect(handler).toHaveBeenCalledWith({ words: ["before"] });
18+
});
19+
20+
it("replaces handlers and keeps channels isolated", () => {
21+
const oldHandler = vi.fn();
22+
const newHandler = vi.fn();
23+
const other = vi.fn();
24+
registerRuntimeDataHandler("captions", oldHandler);
25+
registerRuntimeDataHandler("captions", newHandler);
26+
registerRuntimeDataHandler("telemetry", other);
27+
setRuntimeData("captions", { words: ["latest"] });
28+
expect(oldHandler).not.toHaveBeenCalled();
29+
expect(newHandler).toHaveBeenCalledOnce();
30+
expect(other).not.toHaveBeenCalled();
31+
});
32+
33+
it("notifies the current handler with undefined when cleared", () => {
34+
const handler = vi.fn();
35+
registerRuntimeDataHandler("captions", handler);
36+
setRuntimeData("captions", { words: [] });
37+
clearRuntimeData("captions");
38+
expect(handler).toHaveBeenLastCalledWith(undefined);
39+
const replacement = vi.fn();
40+
registerRuntimeDataHandler("captions", replacement);
41+
expect(replacement).not.toHaveBeenCalled();
42+
});
43+
44+
it("reports handler exceptions without breaking later delivery", () => {
45+
const reporter = vi.fn();
46+
setRuntimeDataErrorReporter(reporter);
47+
registerRuntimeDataHandler("captions", () => {
48+
throw new Error("attach failed");
49+
});
50+
expect(() => setRuntimeData("captions", {})).not.toThrow();
51+
expect(reporter).toHaveBeenCalledWith("captions", expect.any(Error));
52+
});
53+
});
Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
export type RuntimeDataHandler = (payload: unknown) => void;
2+
export type RuntimeDataErrorReporter = (channel: string, error: unknown) => void;
3+
4+
const retained = new Map<string, unknown>();
5+
const handlers = new Map<string, RuntimeDataHandler>();
6+
let reportError: RuntimeDataErrorReporter = () => undefined;
7+
8+
function validChannel(channel: string): boolean {
9+
return /^[a-z][a-z0-9-]{0,63}$/.test(channel);
10+
}
11+
12+
function deliver(channel: string, payload: unknown): void {
13+
const handler = handlers.get(channel);
14+
if (!handler) return;
15+
try {
16+
handler(payload);
17+
} catch (error) {
18+
reportError(channel, error);
19+
}
20+
}
21+
22+
export function setRuntimeDataErrorReporter(reporter: RuntimeDataErrorReporter): void {
23+
reportError = reporter;
24+
}
25+
26+
export function setRuntimeData(channel: string, payload: unknown): void {
27+
if (!validChannel(channel)) return;
28+
retained.set(channel, payload);
29+
deliver(channel, payload);
30+
}
31+
32+
export function clearRuntimeData(channel: string): void {
33+
if (!validChannel(channel)) return;
34+
retained.delete(channel);
35+
deliver(channel, undefined);
36+
}
37+
38+
export function registerRuntimeDataHandler(
39+
channel: string,
40+
handler: RuntimeDataHandler,
41+
): () => void {
42+
if (!validChannel(channel))
43+
throw new Error(`Invalid HyperFrames runtime-data channel: ${channel}`);
44+
handlers.set(channel, handler);
45+
if (retained.has(channel)) deliver(channel, retained.get(channel));
46+
return () => {
47+
if (handlers.get(channel) === handler) handlers.delete(channel);
48+
};
49+
}
50+
51+
export function resetRuntimeDataForTests(): void {
52+
retained.clear();
53+
handlers.clear();
54+
reportError = () => undefined;
55+
}

‎packages/core/src/runtime/types.ts‎

Lines changed: 32 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ import type { HyperframeControlAction } from "../inline-scripts/runtimeContract.
1313
import type { HyperframePickerElementInfo } from "../inline-scripts/pickerApi.js";
1414
import type { RuntimeProtocolV1 } from "./protocol.js";
1515

16-
export type RuntimeBridgeControlAction =
16+
type RuntimeBridgeControlActionBase =
1717
| HyperframeControlAction
1818
| "tick"
1919
| "set-volume"
@@ -24,7 +24,7 @@ export type RuntimeBridgeControlAction =
2424
| "stop-media"
2525
| "flash-elements";
2626

27-
export type RuntimeBridgeControlMessage = {
27+
type RuntimeBridgeControlMessageBase = {
2828
source: "hf-parent";
2929
type: "control";
3030
action: RuntimeBridgeControlAction;
@@ -50,24 +50,27 @@ export type RuntimeStateMessage = {
5050
playbackRate: number;
5151
};
5252

53-
export type RuntimeTimelineClip = {
53+
export type RuntimeTimelineClipIdentity = {
5454
id: string | null;
5555
label: string;
5656
start: number;
5757
duration: number;
5858
track: number;
59-
zIndex: number;
60-
stackingContextId: string | null;
6159
kind: "video" | "audio" | "image" | "element" | "composition";
6260
tagName: string | null;
6361
compositionId: string | null;
64-
compositionAncestors: string[];
6562
parentCompositionId: string | null;
66-
nodePath: string | null;
6763
compositionSrc: string | null;
64+
assetUrl: string | null;
65+
};
66+
67+
export type RuntimeTimelineClip = RuntimeTimelineClipIdentity & {
68+
zIndex: number;
69+
stackingContextId: string | null;
70+
compositionAncestors: string[];
71+
nodePath: string | null;
6872
playbackStart: number;
6973
playbackRate: number;
70-
assetUrl: string | null;
7174
timelineRole: string | null;
7275
timelineLabel: string | null;
7376
timelineGroup: string | null;
@@ -168,6 +171,13 @@ export type RuntimeReadyMessage = {
168171
type: "ready";
169172
};
170173

174+
export type RuntimeDataErrorMessage = {
175+
source: "hf-preview";
176+
type: "runtime-data-error";
177+
channel: string;
178+
message: string;
179+
};
180+
171181
/**
172182
* Analytics events emitted by the runtime.
173183
*
@@ -218,6 +228,7 @@ export type RuntimeOutboundMessage =
218228
| RuntimeStageSizeMessage
219229
| RuntimeMediaAutoplayBlockedMessage
220230
| RuntimeReadyMessage
231+
| RuntimeDataErrorMessage
221232
| RuntimeAnalyticsMessage
222233
| RuntimePerformanceMessage
223234
| RuntimeGroupLevelsMessage;
@@ -317,3 +328,16 @@ export type RuntimeDeterministicAdapter = {
317328
export type RuntimeGsapSetTarget = string | Element | Element[] | null;
318329

319330
export type RuntimeGsapSetVars = Record<string, string | number | boolean | null | undefined>;
331+
332+
type RuntimeDataControlFields = {
333+
channel?: string;
334+
payload?: unknown;
335+
};
336+
337+
type RuntimeBridgeControlAction =
338+
| RuntimeBridgeControlActionBase
339+
| "set-runtime-data"
340+
| "clear-runtime-data";
341+
342+
export type RuntimeBridgeControlMessage = RuntimeBridgeControlMessageBase &
343+
RuntimeDataControlFields;

‎packages/core/src/runtime/window.d.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,15 @@ declare global {
3030
interface Window {
3131
__timelines: Record<string, RuntimeTimelineLike>;
3232
__player?: PlayerAPI;
33+
__hyperframes?: {
34+
registerRuntimeDataHandler?: (
35+
channel: string,
36+
handler: (payload: unknown) => void,
37+
) => () => void;
38+
setRuntimeData?: (channel: string, payload: unknown) => void;
39+
clearRuntimeData?: (channel: string) => void;
40+
[key: string]: unknown;
41+
};
3342
__clipManifest?: RuntimeTimelineMessage;
3443
__clipTree?: ClipTree;
3544
__hf?: {

0 commit comments

Comments
 (0)