Skip to content

Commit 7869547

Browse files
committed
fix(player): version runtime protocol
1 parent 03acdb3 commit 7869547

30 files changed

Lines changed: 588 additions & 79 deletions

‎packages/core/package.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,12 @@
107107
"import": "./src/runtime/startExpression.ts",
108108
"types": "./src/runtime/startExpression.ts"
109109
},
110+
"./runtime/protocol": {
111+
"bun": "./src/runtime/protocol.ts",
112+
"node": "./dist/runtime/protocol.js",
113+
"import": "./src/runtime/protocol.ts",
114+
"types": "./src/runtime/protocol.ts"
115+
},
110116
"./compiler/html-document": {
111117
"bun": "./src/compiler/htmlDocument.ts",
112118
"node": "./dist/compiler/htmlDocument.js",
@@ -307,6 +313,10 @@
307313
"import": "./dist/runtime/startExpression.js",
308314
"types": "./dist/runtime/startExpression.d.ts"
309315
},
316+
"./runtime/protocol": {
317+
"import": "./dist/runtime/protocol.js",
318+
"types": "./dist/runtime/protocol.d.ts"
319+
},
310320
"./compiler/html-document": {
311321
"import": "./dist/compiler/htmlDocument.js",
312322
"types": "./dist/compiler/htmlDocument.d.ts"

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

Lines changed: 43 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ function createMockDeps() {
1919
onSetRootDuration: vi.fn(),
2020
onEnablePickMode: vi.fn(),
2121
onDisablePickMode: vi.fn(),
22+
getCanonicalFps: vi.fn(() => 30),
2223
};
2324
}
2425

@@ -54,7 +55,22 @@ describe("installRuntimeControlBridge", () => {
5455
const deps = createMockDeps();
5556
const handler = installRuntimeControlBridge(deps);
5657
handler(makeControlMessage("seek", { frame: 150, seekMode: "drag" }));
57-
expect(deps.onSeek).toHaveBeenCalledWith(150, "drag");
58+
expect(deps.onSeek).toHaveBeenCalledWith(5, "drag");
59+
});
60+
61+
it("prefers canonical seconds in protocol v1 seek messages", () => {
62+
const deps = createMockDeps();
63+
const handler = installRuntimeControlBridge(deps);
64+
handler(
65+
makeControlMessage("seek", {
66+
protocolVersion: 1,
67+
capabilities: ["seconds-time", "rational-fps", "seek-keep-playing"],
68+
fps: { numerator: 60, denominator: 1 },
69+
timeSeconds: 2.5,
70+
frame: 999,
71+
}),
72+
);
73+
expect(deps.onSeek).toHaveBeenCalledWith(2.5, "commit");
5874
});
5975

6076
it("seek defaults frame to 0 and seekMode to commit", () => {
@@ -245,7 +261,32 @@ describe("installRuntimeControlBridge", () => {
245261
const postSpy = vi.spyOn(window.parent, "postMessage");
246262
const deps = createMockDeps();
247263
installRuntimeControlBridge(deps);
248-
expect(postSpy).toHaveBeenCalledWith({ source: "hf-preview", type: "ready" }, "*");
264+
expect(postSpy).toHaveBeenCalledWith(
265+
expect.objectContaining({
266+
source: "hf-preview",
267+
type: "ready",
268+
protocolVersion: 1,
269+
fps: { numerator: 30, denominator: 1 },
270+
}),
271+
"*",
272+
);
273+
postSpy.mockRestore();
274+
});
275+
276+
it("rejects an unknown protocol major with a diagnostic", () => {
277+
const postSpy = vi.spyOn(window.parent, "postMessage");
278+
const deps = createMockDeps();
279+
const handler = installRuntimeControlBridge(deps);
280+
handler(makeControlMessage("play", { protocolVersion: 2 }));
281+
282+
expect(deps.onPlay).not.toHaveBeenCalled();
283+
expect(postSpy).toHaveBeenCalledWith(
284+
expect.objectContaining({
285+
type: "diagnostic",
286+
code: "runtime.protocol.unsupported_protocol_version",
287+
}),
288+
"*",
289+
);
249290
postSpy.mockRestore();
250291
});
251292
});

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

Lines changed: 43 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,18 @@
11
import { swallow } from "./diagnostics";
22
import type { HfColorGradingTarget } from "../colorGrading";
33
import type { RuntimeBridgeControlMessage, RuntimeOutboundMessage } from "./types";
4+
import {
5+
inspectRuntimeProtocol,
6+
runtimeProtocolFpsToNumber,
7+
runtimeProtocolMetadata,
8+
type RuntimeProtocolV1,
9+
} from "./protocol";
410

511
type BridgeDeps = {
612
onPlay: () => void;
713
onPause: () => void;
814
onStopMedia: () => void;
9-
onSeek: (frame: number, seekMode: "drag" | "commit") => void;
15+
onSeek: (timeSeconds: number, seekMode: "drag" | "commit") => void;
1016
onTick: () => void;
1117
onSetMuted: (muted: boolean) => void;
1218
onSetVolume: (volume: number) => void;
@@ -22,18 +28,25 @@ type BridgeDeps = {
2228
) => void;
2329
onEnablePickMode: () => void;
2430
onDisablePickMode: () => void;
31+
getCanonicalFps: () => number;
2532
};
2633

34+
let runtimeProtocolFps = 30;
35+
36+
export function setRuntimeProtocolFps(fps: number): void {
37+
runtimeProtocolFps = Number.isFinite(fps) && fps > 0 ? fps : 30;
38+
}
39+
2740
export function postRuntimeMessage(payload: RuntimeOutboundMessage): void {
2841
try {
29-
window.parent.postMessage(payload, "*");
42+
window.parent.postMessage({ ...payload, ...runtimeProtocolMetadata(runtimeProtocolFps) }, "*");
3043
} catch (err) {
3144
// Cross-frame posting can throw if the parent is gone or origin-isolated.
3245
swallow("bridge.postMessage", err);
3346
}
3447
}
3548

36-
type BridgeControlData = Partial<RuntimeBridgeControlMessage>;
49+
type BridgeControlData = Partial<RuntimeBridgeControlMessage & RuntimeProtocolV1>;
3750
type ControlHandler = (data: BridgeControlData, deps: BridgeDeps) => void;
3851

3952
// Per-action dispatchers. Splitting the handler into a lookup table keeps the
@@ -43,7 +56,7 @@ const CONTROL_HANDLERS: Record<string, ControlHandler> = {
4356
play: (_d, deps) => deps.onPlay(),
4457
pause: (_d, deps) => deps.onPause(),
4558
"stop-media": (_d, deps) => deps.onStopMedia(),
46-
seek: (data, deps) => deps.onSeek(Number(data.frame ?? 0), data.seekMode ?? "commit"),
59+
seek: (data, deps) => deps.onSeek(resolveSeekTimeSeconds(data, deps), data.seekMode ?? "commit"),
4760
tick: (_d, deps) => deps.onTick(),
4861
"set-muted": (data, deps) => deps.onSetMuted(Boolean(data.muted)),
4962
"set-volume": (data, deps) =>
@@ -64,6 +77,31 @@ const CONTROL_HANDLERS: Record<string, ControlHandler> = {
6477
"flash-elements": (data) => handleFlashElements(data),
6578
};
6679

80+
function resolveSeekTimeSeconds(data: BridgeControlData, deps: BridgeDeps): number {
81+
const explicitSeconds = Number(data.timeSeconds);
82+
if (Number.isFinite(explicitSeconds)) return Math.max(0, explicitSeconds);
83+
const messageFps = runtimeProtocolFpsToNumber(data.fps);
84+
const fps = messageFps ?? deps.getCanonicalFps();
85+
return Math.max(0, Number(data.frame ?? 0)) / fps;
86+
}
87+
88+
function rejectUnsupportedProtocol(data: BridgeControlData): boolean {
89+
const protocol = inspectRuntimeProtocol(data);
90+
if (protocol.status !== "unsupported") return false;
91+
postRuntimeMessage({
92+
source: "hf-preview",
93+
type: "diagnostic",
94+
code: `runtime.protocol.${protocol.code}`,
95+
details: {
96+
receivedVersion:
97+
typeof protocol.receivedVersion === "string" || typeof protocol.receivedVersion === "number"
98+
? protocol.receivedVersion
99+
: null,
100+
},
101+
});
102+
return true;
103+
}
104+
67105
function handleFlashElements(data: BridgeControlData): void {
68106
// Briefly highlight elements — used by the chat-canvas bridge
69107
// to show what changed after an agent edit
@@ -78,6 +116,7 @@ export function installRuntimeControlBridge(deps: BridgeDeps): (event: MessageEv
78116
const handler = (event: MessageEvent) => {
79117
const data = event.data as BridgeControlData | null;
80118
if (!data || data.source !== "hf-parent" || data.type !== "control") return;
119+
if (rejectUnsupportedProtocol(data)) return;
81120
const action = data.action;
82121
if (typeof action !== "string") return;
83122
const fn = CONTROL_HANDLERS[action];

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

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
// fallow-ignore-file code-duplication complexity
2-
import { installRuntimeControlBridge, postRuntimeMessage } from "./bridge";
2+
import { installRuntimeControlBridge, postRuntimeMessage, setRuntimeProtocolFps } from "./bridge";
33
import { initRuntimeAnalytics, emitAnalyticsEvent } from "./analytics";
44
import { injectCompositionCssVariables } from "./getVariables";
55
import { createCssAdapter } from "./adapters/css";
@@ -93,6 +93,7 @@ export function initSandboxRuntimeModular(): void {
9393
applyVariableBindings(document);
9494
const exportRenderFps = resolveExportRenderFps();
9595
state.canonicalFps = exportRenderFps.fps ?? state.canonicalFps;
96+
setRuntimeProtocolFps(state.canonicalFps);
9697
if (window.__HF_EXPORT_RENDER_SEEK_CONFIG) {
9798
console.info("[hyperframes] render runtime fps", {
9899
canonicalFps: state.canonicalFps,
@@ -2167,10 +2168,9 @@ export function initSandboxRuntimeModular(): void {
21672168
if (el instanceof HTMLMediaElement && !el.paused) el.pause();
21682169
}
21692170
},
2170-
onSeek: (frame, _seekMode) => {
2171-
const time = Math.max(0, frame) / state.canonicalFps;
2172-
player.seek(time);
2173-
emitAnalyticsEvent("composition_seeked", { time });
2171+
onSeek: (timeSeconds, _seekMode) => {
2172+
player.seek(timeSeconds);
2173+
emitAnalyticsEvent("composition_seeked", { time: timeSeconds });
21742174
},
21752175
onSetMuted: (muted) => {
21762176
state.bridgeMuted = muted;
@@ -2261,6 +2261,7 @@ export function initSandboxRuntimeModular(): void {
22612261
},
22622262
onEnablePickMode: () => picker.enablePickMode(),
22632263
onDisablePickMode: () => picker.disablePickMode(),
2264+
getCanonicalFps: () => state.canonicalFps,
22642265
});
22652266

22662267
state.deterministicAdapters = [
Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
import { describe, expect, it } from "vitest";
2+
import {
3+
inspectRuntimeProtocol,
4+
runtimeProtocolFpsFromNumber,
5+
runtimeProtocolFpsToNumber,
6+
runtimeProtocolMetadata,
7+
} from "./protocol";
8+
9+
describe("runtime protocol", () => {
10+
it.each([24, 30, 60, 24_000 / 1_001, 30_000 / 1_001])(
11+
"round-trips %s fps as a rational",
12+
(fps) => {
13+
expect(runtimeProtocolFpsToNumber(runtimeProtocolFpsFromNumber(fps))).toBeCloseTo(fps, 6);
14+
},
15+
);
16+
17+
it("accepts protocol v1 metadata and exposes its fps", () => {
18+
expect(inspectRuntimeProtocol(runtimeProtocolMetadata(60))).toMatchObject({
19+
status: "supported",
20+
fps: 60,
21+
});
22+
});
23+
24+
it("tolerates additive capabilities within protocol v1", () => {
25+
const metadata = runtimeProtocolMetadata(30);
26+
expect(
27+
inspectRuntimeProtocol({
28+
...metadata,
29+
capabilities: [...metadata.capabilities, "future-cap"],
30+
}),
31+
).toMatchObject({ status: "supported", fps: 30 });
32+
});
33+
34+
it("keeps an explicit legacy fallback", () => {
35+
expect(inspectRuntimeProtocol({ source: "hf-preview" }, 24)).toEqual({
36+
status: "legacy",
37+
fps: 24,
38+
});
39+
});
40+
41+
it("rejects unknown protocol versions and malformed v1 metadata", () => {
42+
expect(inspectRuntimeProtocol({ protocolVersion: 2 })).toMatchObject({
43+
status: "unsupported",
44+
code: "unsupported_protocol_version",
45+
});
46+
expect(
47+
inspectRuntimeProtocol({ protocolVersion: 1, fps: { numerator: 30, denominator: 1 } }),
48+
).toMatchObject({ status: "unsupported", code: "invalid_protocol_metadata" });
49+
});
50+
});
Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
export const RUNTIME_PROTOCOL_VERSION = 1 as const;
2+
3+
export const RUNTIME_PROTOCOL_CAPABILITIES = [
4+
"seconds-time",
5+
"rational-fps",
6+
"seek-keep-playing",
7+
] as const;
8+
9+
export type RuntimeProtocolFps = {
10+
numerator: number;
11+
denominator: number;
12+
};
13+
14+
export type RuntimeProtocolV1 = {
15+
protocolVersion: typeof RUNTIME_PROTOCOL_VERSION;
16+
capabilities: readonly string[];
17+
fps: RuntimeProtocolFps;
18+
};
19+
20+
export type RuntimeProtocolInspection =
21+
| { status: "legacy"; fps: number }
22+
| { status: "supported"; fps: number; metadata: RuntimeProtocolV1 }
23+
| {
24+
status: "unsupported";
25+
code: "unsupported_protocol_version" | "invalid_protocol_metadata";
26+
receivedVersion: unknown;
27+
};
28+
29+
function greatestCommonDivisor(a: number, b: number): number {
30+
let left = Math.abs(a);
31+
let right = Math.abs(b);
32+
while (right !== 0) {
33+
const remainder = left % right;
34+
left = right;
35+
right = remainder;
36+
}
37+
return left || 1;
38+
}
39+
40+
export function runtimeProtocolFpsFromNumber(value: number): RuntimeProtocolFps {
41+
const safe = Number.isFinite(value) && value > 0 ? value : 30;
42+
const denominator = Number.isInteger(safe) ? 1 : 1_000_000;
43+
const numerator = Math.round(safe * denominator);
44+
const divisor = greatestCommonDivisor(numerator, denominator);
45+
return { numerator: numerator / divisor, denominator: denominator / divisor };
46+
}
47+
48+
export function runtimeProtocolFpsToNumber(value: unknown): number | null {
49+
if (typeof value !== "object" || value === null) return null;
50+
const fps = value as Partial<RuntimeProtocolFps>;
51+
if (!Number.isFinite(fps.numerator) || !Number.isFinite(fps.denominator)) return null;
52+
if ((fps.numerator ?? 0) <= 0 || (fps.denominator ?? 0) <= 0) return null;
53+
return Number(fps.numerator) / Number(fps.denominator);
54+
}
55+
56+
export function runtimeProtocolMetadata(fps: number): RuntimeProtocolV1 {
57+
return {
58+
protocolVersion: RUNTIME_PROTOCOL_VERSION,
59+
capabilities: RUNTIME_PROTOCOL_CAPABILITIES,
60+
fps: runtimeProtocolFpsFromNumber(fps),
61+
};
62+
}
63+
64+
function hasDeclaredCapabilities(value: unknown): boolean {
65+
return Array.isArray(value) && value.every((capability) => typeof capability === "string");
66+
}
67+
68+
export function inspectRuntimeProtocol(value: unknown, legacyFps = 30): RuntimeProtocolInspection {
69+
if (typeof value !== "object" || value === null) return { status: "legacy", fps: legacyFps };
70+
const message = value as Record<string, unknown>;
71+
if (message.protocolVersion === undefined) return { status: "legacy", fps: legacyFps };
72+
if (message.protocolVersion !== RUNTIME_PROTOCOL_VERSION) {
73+
return {
74+
status: "unsupported",
75+
code: "unsupported_protocol_version",
76+
receivedVersion: message.protocolVersion,
77+
};
78+
}
79+
const fps = runtimeProtocolFpsToNumber(message.fps);
80+
if (fps === null || !hasDeclaredCapabilities(message.capabilities)) {
81+
return {
82+
status: "unsupported",
83+
code: "invalid_protocol_metadata",
84+
receivedVersion: message.protocolVersion,
85+
};
86+
}
87+
return {
88+
status: "supported",
89+
fps,
90+
metadata: message as RuntimeProtocolV1,
91+
};
92+
}

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ export type RuntimeBridgeControlMessage = {
2727
type: "control";
2828
action: RuntimeBridgeControlAction;
2929
frame?: number;
30+
timeSeconds?: number;
3031
muted?: boolean;
3132
volume?: number;
3233
durationSeconds?: number;

‎packages/core/tsconfig.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,8 @@
1616
"files": [
1717
"src/runtime/clipTree.ts",
1818
"src/runtime/mediaVolumeEnvelope.ts",
19-
"src/runtime/positionEdits.ts"
19+
"src/runtime/positionEdits.ts",
20+
"src/runtime/protocol.ts"
2021
],
2122
"include": ["src/**/*"],
2223
"exclude": [

‎packages/player/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@
2828
}
2929
},
3030
"scripts": {
31-
"build": "tsup",
31+
"build": "tsup && node scripts/verify-runtime-pin.mjs",
3232
"typecheck": "tsc --noEmit && tsc --noEmit -p tests/perf/tsconfig.json",
3333
"test": "vitest run",
3434
"perf": "bun run tests/perf/index.ts"

0 commit comments

Comments
 (0)