From ef5cdeb0a02afc993980809cc359dd68a1c4944d Mon Sep 17 00:00:00 2001 From: James Russo Date: Wed, 11 Nov 2026 16:54:46 +0000 Subject: [PATCH] feat(core): give the preview parent a typed editing port to prepare for an opaque frame (#7556) * feat(core): give the preview parent a typed editing port to prepare for an opaque frame Studio reads the preview frame's window and document directly, which stops working once the preview runs in an opaque origin. This adds the runtime half of the replacement, with no Studio consumer changed yet: - runtime/editingPort.ts: a versioned request/reply protocol, a validator that turns any bad request into a typed error, and a promise-based parent client with request ids, timeouts and dispose. Exported as @hyperframes/core/runtime/editing-port. - runtime/editingAgent.ts: on the parent's connect, the runtime hands window.parent a MessagePort once and answers hello, runtime-snapshot, wait-for-seek and set-loop-start on it. A connect from anything but the parent is ignored and does not use up the handoff. Playback transport stays on the existing control protocol. Co-Authored-By: Claude Opus 5.5 * fix(core): type the handed-off port under the runtime's strict index checks Co-Authored-By: Claude Opus 5.5 * fix(core): emit the editing-port module so the published subpath resolves Co-Authored-By: Claude Opus 5.5 * chore(producer): raise the packed size budget for the runtime's editing agent The producer ships the preview runtime, which now carries the editing agent and its request validator. The packed tarball measured 878,763 bytes in CI against an 870,000 budget. Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --- packages/core/package-subpaths.json | 6 + packages/core/package.json | 10 + .../core/src/runtime/editingAgent.test.ts | 173 +++++++++++ packages/core/src/runtime/editingAgent.ts | 133 +++++++++ packages/core/src/runtime/editingPort.test.ts | 149 ++++++++++ packages/core/src/runtime/editingPort.ts | 272 ++++++++++++++++++ packages/core/src/runtime/init.ts | 2 + packages/core/tsconfig.json | 1 + scripts/package-size-budgets.json | 2 +- 9 files changed, 747 insertions(+), 1 deletion(-) create mode 100644 packages/core/src/runtime/editingAgent.test.ts create mode 100644 packages/core/src/runtime/editingAgent.ts create mode 100644 packages/core/src/runtime/editingPort.test.ts create mode 100644 packages/core/src/runtime/editingPort.ts diff --git a/packages/core/package-subpaths.json b/packages/core/package-subpaths.json index a21e3f030f..848d450edf 100644 --- a/packages/core/package-subpaths.json +++ b/packages/core/package-subpaths.json @@ -416,6 +416,12 @@ "types": "./dist/runtime/protocol.d.ts", "environments": ["browser", "bun", "node"] }, + "./runtime/editing-port": { + "source": "./src/runtime/editingPort.ts", + "runtime": "./dist/runtime/editingPort.js", + "types": "./dist/runtime/editingPort.d.ts", + "environments": ["browser", "bun", "node"] + }, "./runtime/clip-window": { "source": "./src/runtime/clipWindow.ts", "runtime": "./dist/runtime/clipWindow.js", diff --git a/packages/core/package.json b/packages/core/package.json index d10f385812..7a465a1a8b 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -423,6 +423,12 @@ "import": "./src/runtime/protocol.ts", "types": "./src/runtime/protocol.ts" }, + "./runtime/editing-port": { + "bun": "./src/runtime/editingPort.ts", + "node": "./dist/runtime/editingPort.js", + "import": "./src/runtime/editingPort.ts", + "types": "./src/runtime/editingPort.ts" + }, "./runtime/clip-window": { "bun": "./src/runtime/clipWindow.ts", "node": "./dist/runtime/clipWindow.js", @@ -903,6 +909,10 @@ "import": "./dist/runtime/protocol.js", "types": "./dist/runtime/protocol.d.ts" }, + "./runtime/editing-port": { + "import": "./dist/runtime/editingPort.js", + "types": "./dist/runtime/editingPort.d.ts" + }, "./runtime/clip-window": { "import": "./dist/runtime/clipWindow.js", "types": "./dist/runtime/clipWindow.d.ts" diff --git a/packages/core/src/runtime/editingAgent.test.ts b/packages/core/src/runtime/editingAgent.test.ts new file mode 100644 index 0000000000..d03cb7e10d --- /dev/null +++ b/packages/core/src/runtime/editingAgent.test.ts @@ -0,0 +1,173 @@ +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { installEditingAgent } from "./editingAgent"; + +const CONNECT = { source: "hf-parent", type: "editing-connect", v: 1 }; + +function frameWindow(): Window { + const iframe = document.createElement("iframe"); + document.body.appendChild(iframe); + return iframe.contentWindow!; +} + +function post(source: Window | null, data: unknown) { + window.dispatchEvent(new MessageEvent("message", { source, data })); +} + +function ask(port: MessagePort, data: unknown): Promise> { + return new Promise((resolve) => { + port.onmessage = (event) => resolve(event.data); + port.postMessage(data); + }); +} + +describe("installEditingAgent", () => { + let parent: Window; + let handoff: ReturnType; + let agent: { dispose: () => void }; + + beforeEach(() => { + parent = frameWindow(); + handoff = vi.fn(); + parent.postMessage = handoff as unknown as Window["postMessage"]; + agent = installEditingAgent(parent); + }); + afterEach(() => { + agent.dispose(); + for (const call of handoff.mock.calls) (call[2] as MessagePort[])[0]?.close(); + document.body.innerHTML = ""; + delete window.__clipManifest; + delete window.__clipTree; + delete window.__player; + delete window.__hfStartupError; + delete window.__hfWaitForSeekCompletion; + delete window.__hf; + }); + + const connectedPort = (): MessagePort => { + post(parent, CONNECT); + return (handoff.mock.calls[0][2] as MessagePort[])[0]; + }; + + it("hands one port to the parent, once", () => { + post(parent, CONNECT); + post(parent, CONNECT); + expect(handoff).toHaveBeenCalledOnce(); + const [message, targetOrigin, transfer] = handoff.mock.calls[0]; + expect(message).toEqual({ source: "hf-preview", type: "editing-port", v: 1 }); + expect(targetOrigin).toBe("*"); + expect(transfer).toHaveLength(1); + }); + + it("ignores a connect from the page itself or another frame, without using up the handoff", () => { + post(window, CONNECT); + post(frameWindow(), CONNECT); + post(null, CONNECT); + post(parent, { ...CONNECT, v: 2 }); + post(parent, { ...CONNECT, source: "hf-preview" }); + expect(handoff).not.toHaveBeenCalled(); + post(parent, CONNECT); + expect(handoff).toHaveBeenCalledOnce(); + }); + + it("never hands off on a top-level page, where the page is its own parent", () => { + const selfPost = vi.spyOn(window, "postMessage").mockImplementation(() => {}); + const topLevel = installEditingAgent(window); + try { + post(window, CONNECT); + expect(selfPost).not.toHaveBeenCalled(); + } finally { + topLevel.dispose(); + selfPost.mockRestore(); + } + }); + + it("stops listening for a connect once disposed", () => { + agent.dispose(); + post(parent, CONNECT); + expect(handoff).not.toHaveBeenCalled(); + }); + + it("answers each request kind from the runtime's state", async () => { + const setLoopStart = vi.fn(); + const manifest = { source: "hf-preview", type: "timeline", clips: [] }; + window.__clipManifest = manifest as unknown as Window["__clipManifest"]; + window.__player = {} as Window["__player"]; + window.__hfStartupError = "boom"; + window.__hfWaitForSeekCompletion = () => Promise.resolve(); + window.__hf = { setLoopStart }; + const leaf = { id: "b", parentId: "a", children: [], element: document.body }; + window.__clipTree = { + roots: [{ id: "a", parentId: null, children: [leaf], element: document.body }], + }; + const port = connectedPort(); + + expect(await ask(port, { v: 1, id: 1, kind: "hello" })).toEqual({ + v: 1, + id: 1, + ok: true, + result: { + version: 1, + kinds: ["hello", "runtime-snapshot", "wait-for-seek", "set-loop-start"], + }, + }); + expect((await ask(port, { v: 1, id: 2, kind: "runtime-snapshot", params: {} })).result).toEqual( + { + playerReady: true, + startupError: "boom", + clipManifest: manifest, + clipParents: [["b", "a"]], + }, + ); + expect((await ask(port, { v: 1, id: 3, kind: "wait-for-seek" })).result).toEqual({ + waited: true, + }); + const loop = await ask(port, { v: 1, id: 4, kind: "set-loop-start", params: { seconds: 2 } }); + expect(loop.result).toEqual({ applied: true }); + expect(setLoopStart).toHaveBeenCalledWith(2); + }); + + it.each([ + [null, null, "malformed"], + ["hello", null, "malformed"], + [{ v: 1, kind: "hello" }, null, "malformed"], + [{ v: 1, id: -1, kind: "hello" }, null, "malformed"], + [{ v: 1, id: 1.5, kind: "hello" }, null, "malformed"], + [{ v: 2, id: 5, kind: "hello" }, 5, "unsupported-version"], + [{ id: 6, kind: "hello" }, 6, "unsupported-version"], + [{ v: 1, id: 7, kind: "__proto__" }, 7, "unknown-kind"], + [{ v: 1, id: 8, kind: "toString" }, 8, "unknown-kind"], + [{ v: 1, id: 9, kind: "hello", params: { extra: 1 } }, 9, "invalid-params"], + [{ v: 1, id: 10, kind: "hello", params: [] }, 10, "invalid-params"], + [{ v: 1, id: 11, kind: "set-loop-start" }, 11, "invalid-params"], + [{ v: 1, id: 12, kind: "set-loop-start", params: { seconds: -1 } }, 12, "invalid-params"], + [{ v: 1, id: 13, kind: "set-loop-start", params: { seconds: "2" } }, 13, "invalid-params"], + [{ v: 1, id: 14, kind: "set-loop-start", params: { seconds: NaN } }, 14, "invalid-params"], + [ + { v: 1, id: 15, kind: "set-loop-start", params: { seconds: 1, extra: 1 } }, + 15, + "invalid-params", + ], + ])("rejects %j with a typed error", async (request, id, code) => { + const setLoopStart = vi.fn(); + window.__hf = { setLoopStart }; + const reply = await ask(connectedPort(), request); + expect(reply).toMatchObject({ v: 1, id, ok: false, error: { code } }); + expect(setLoopStart).not.toHaveBeenCalled(); + }); + + it("replies failed when a handler rejects or its result cannot be cloned", async () => { + window.__hfWaitForSeekCompletion = () => Promise.reject(new Error("seek lost")); + const port = connectedPort(); + expect(await ask(port, { v: 1, id: 1, kind: "wait-for-seek" })).toMatchObject({ + id: 1, + ok: false, + error: { code: "failed", message: "seek lost" }, + }); + window.__clipManifest = { clips: [() => {}] } as unknown as Window["__clipManifest"]; + expect(await ask(port, { v: 1, id: 2, kind: "runtime-snapshot" })).toMatchObject({ + id: 2, + ok: false, + error: { code: "failed" }, + }); + }); +}); diff --git a/packages/core/src/runtime/editingAgent.ts b/packages/core/src/runtime/editingAgent.ts new file mode 100644 index 0000000000..2220afb224 --- /dev/null +++ b/packages/core/src/runtime/editingAgent.ts @@ -0,0 +1,133 @@ +/** + * The runtime's end of the editing channel (wire types in `editingPort.ts`). + * + * The port goes to `window.parent` once, when the parent asks for it, so only + * the parent holds a channel. A connect posted by anything else, including the + * page itself, is ignored and does not use up the handoff. Requests on the port + * are validated before they run; a bad one gets a typed error reply, never a throw. + */ +import { swallow } from "./diagnostics"; +import { + EDITING_CONNECT, + EDITING_PORT, + EDITING_PROTOCOL_VERSION, + EDITING_REQUEST_KINDS, + isPlainRecord, + parseEditingRequest, + type EditingParams, + type EditingReply, + type EditingRequestKind, + type EditingResult, +} from "./editingPort"; +import type { ClipNode } from "./clipTree"; + +type Handlers = { + [K in EditingRequestKind]: ( + params: EditingParams, + ) => EditingResult | Promise>; +}; + +function clipParents(nodes: readonly ClipNode[], out: Array<[string, string]> = []) { + for (const node of nodes) { + if (node.id && node.parentId) out.push([node.id, node.parentId]); + clipParents(node.children, out); + } + return out; +} + +const HANDLERS: Handlers = { + hello: () => ({ version: EDITING_PROTOCOL_VERSION, kinds: [...EDITING_REQUEST_KINDS] }), + "runtime-snapshot": () => ({ + playerReady: Boolean(window.__player), + startupError: typeof window.__hfStartupError === "string" ? window.__hfStartupError : null, + clipManifest: window.__clipManifest ?? null, + clipParents: clipParents(window.__clipTree?.roots ?? []), + }), + "wait-for-seek": async () => { + const wait = window.__hfWaitForSeekCompletion; + if (typeof wait !== "function") return { waited: false }; + await wait(); + return { waited: true }; + }, + "set-loop-start": ({ seconds }) => { + const setLoopStart = window.__hf?.setLoopStart; + if (typeof setLoopStart !== "function") return { applied: false }; + setLoopStart(seconds); + return { applied: true }; + }, +}; + +function serve(port: MessagePort): void { + const reply = (message: EditingReply) => { + try { + port.postMessage(message); + } catch (err) { + // A result that cannot be cloned still owes the parent an answer. + if (message.ok) reply(failure(message.id, err)); + else swallow("editingAgent.reply", err); + } + }; + port.onmessage = (event: MessageEvent) => { + const request = parseEditingRequest(event.data); + if (!request.ok) { + reply({ + v: EDITING_PROTOCOL_VERSION, + id: request.id, + ok: false, + error: { code: request.code, message: request.message }, + }); + return; + } + const handler = HANDLERS[request.kind] as (params: unknown) => unknown; + Promise.resolve() + .then(() => handler(request.params)) + .then( + (result) => reply({ v: EDITING_PROTOCOL_VERSION, id: request.id, ok: true, result }), + (err: unknown) => reply(failure(request.id, err)), + ); + }; +} + +function failure(id: number, err: unknown): EditingReply { + const message = err instanceof Error ? err.message : String(err); + return { + v: EDITING_PROTOCOL_VERSION, + id, + ok: false, + error: { code: "failed", message: message.slice(0, 500) }, + }; +} + +export function installEditingAgent(parent: Window = window.parent): { dispose: () => void } { + let port: MessagePort | null = null; + const onMessage = (event: MessageEvent) => { + // A top-level page is its own parent, so a self-post would pass the source check. + if (parent === window || event.source !== parent) return; + const data = event.data; + if (!isPlainRecord(data) || data.source !== "hf-parent" || data.type !== EDITING_CONNECT) + return; + if (data.v !== EDITING_PROTOCOL_VERSION) return; + window.removeEventListener("message", onMessage); + const channel = new MessageChannel(); + port = channel.port1; + serve(port); + try { + // "*" as every runtime post does (bridge.ts): the frame is not told its parent's origin. + parent.postMessage( + { source: "hf-preview", type: EDITING_PORT, v: EDITING_PROTOCOL_VERSION }, + "*", + [channel.port2], + ); + } catch (err) { + swallow("editingAgent.handoff", err); + port.close(); + } + }; + window.addEventListener("message", onMessage); + return { + dispose() { + window.removeEventListener("message", onMessage); + port?.close(); + }, + }; +} diff --git a/packages/core/src/runtime/editingPort.test.ts b/packages/core/src/runtime/editingPort.test.ts new file mode 100644 index 0000000000..8d9f205636 --- /dev/null +++ b/packages/core/src/runtime/editingPort.test.ts @@ -0,0 +1,149 @@ +import { afterEach, describe, expect, it, vi } from "vitest"; +import { installEditingAgent } from "./editingAgent"; +import { createEditingPortClient, EditingPortError, type EditingPortClient } from "./editingPort"; + +type Listener = (event: Partial) => void; + +/** A parent window whose message listener the test drives directly. */ +function fakeHost() { + let listener: Listener | null = null; + const host = { + addEventListener: (_type: string, fn: Listener) => (listener = fn), + removeEventListener: vi.fn(() => (listener = null)), + }; + return { host: host as unknown as Window, deliver: (e: Partial) => listener?.(e) }; +} + +function previewFrame() { + const iframe = document.createElement("iframe"); + document.body.appendChild(iframe); + const connects = vi.fn(); + iframe.contentWindow!.postMessage = connects as unknown as Window["postMessage"]; + return { iframe, frame: iframe.contentWindow!, connects }; +} + +const PORT_MESSAGE = { source: "hf-preview", type: "editing-port", v: 1 }; +const CONNECT = { source: "hf-parent", type: "editing-connect", v: 1 }; +const clients: EditingPortClient[] = []; +const ports: MessagePort[] = []; + +function channel() { + const pair = new MessageChannel(); + ports.push(pair.port1, pair.port2); + return pair; +} + +afterEach(() => { + for (const client of clients.splice(0)) client.dispose(); + for (const port of ports.splice(0)) port.close(); + document.body.innerHTML = ""; +}); + +describe("createEditingPortClient", () => { + it("round-trips a request with the runtime agent", async () => { + const { iframe, frame } = previewFrame(); + const { host, deliver } = fakeHost(); + // The preview's parent: what the agent sends is what the host receives. + const parent = document.body.appendChild(document.createElement("iframe")).contentWindow!; + parent.postMessage = ((data: unknown, _origin: string, transfer: MessagePort[]) => { + ports.push(...transfer); + deliver({ source: frame, data, ports: transfer }); + }) as Window["postMessage"]; + frame.postMessage = ((data: unknown) => + window.dispatchEvent( + new MessageEvent("message", { source: parent, data }), + )) as Window["postMessage"]; + const agent = installEditingAgent(parent); + try { + const client = createEditingPortClient({ iframe, host }); + clients.push(client); + await client.ready; + expect(await client.request("hello", {})).toEqual({ + version: 1, + kinds: ["hello", "runtime-snapshot", "wait-for-seek", "set-loop-start"], + }); + } finally { + agent.dispose(); + } + }); + + it("asks for the port at once and on ready, and takes it only from its own frame", async () => { + const { iframe, frame, connects } = previewFrame(); + const { host, deliver } = fakeHost(); + const client = createEditingPortClient({ iframe, host }); + clients.push(client); + deliver({ source: frame, data: { source: "hf-preview", type: "ready" } }); + expect(connects).toHaveBeenCalledTimes(2); + expect(connects).toHaveBeenLastCalledWith({ ...CONNECT }, "*"); + const settled = vi.fn(); + void client.ready.then(settled); + deliver({ source: previewFrame().frame, data: PORT_MESSAGE, ports: [channel().port2] }); + deliver({ source: frame, data: { ...PORT_MESSAGE, v: 2 }, ports: [channel().port2] }); + await Promise.resolve(); + expect(settled).not.toHaveBeenCalled(); + deliver({ source: frame, data: PORT_MESSAGE, ports: [channel().port2] }); + await client.ready; + expect(host.removeEventListener).toHaveBeenCalled(); + }); + + it("maps error and malformed replies to typed errors", async () => { + const { iframe, frame } = previewFrame(); + const { host, deliver } = fakeHost(); + const pair = channel(); + pair.port1.onmessage = (event) => { + const { id } = event.data as { id: number }; + pair.port1.postMessage( + id === 1 + ? { v: 1, id, ok: false, error: { code: "invalid-params", message: "bad" } } + : { v: 1, id, ok: "yes" }, + ); + }; + const client = createEditingPortClient({ iframe, host }); + clients.push(client); + deliver({ source: frame, data: PORT_MESSAGE, ports: [pair.port2] }); + await expect(client.request("set-loop-start", { seconds: 1 })).rejects.toMatchObject({ + code: "invalid-params", + message: "bad", + }); + await expect(client.request("hello", {})).rejects.toMatchObject({ code: "malformed" }); + }); + + it("times out a request that gets no reply, before or after the port arrives", async () => { + const { iframe, frame } = previewFrame(); + const { host, deliver } = fakeHost(); + const client = createEditingPortClient({ iframe, host, timeoutMs: 10 }); + clients.push(client); + await expect(client.request("hello", {})).rejects.toMatchObject({ code: "timeout" }); + deliver({ source: frame, data: PORT_MESSAGE, ports: [channel().port2] }); + const late = client.request("runtime-snapshot", {}, { timeoutMs: 5 }); + await expect(late).rejects.toBeInstanceOf(EditingPortError); + await expect(late).rejects.toMatchObject({ code: "timeout" }); + }); + + it("dispose rejects pending and later requests and closes the port", async () => { + const { iframe, frame } = previewFrame(); + const { host, deliver } = fakeHost(); + const pair = channel(); + const close = vi.spyOn(pair.port2, "close"); + const client = createEditingPortClient({ iframe, host }); + deliver({ source: frame, data: PORT_MESSAGE, ports: [pair.port2] }); + await client.ready; + const pending = client.request("wait-for-seek", {}); + client.dispose(); + await expect(pending).rejects.toMatchObject({ code: "disposed" }); + await expect(client.request("hello", {})).rejects.toMatchObject({ code: "disposed" }); + expect(close).toHaveBeenCalled(); + client.dispose(); + }); + + it("dispose before the handoff rejects ready and pending requests, and stops listening", async () => { + const { iframe } = previewFrame(); + const { host } = fakeHost(); + const client = createEditingPortClient({ iframe, host }); + const pending = client.request("hello", {}); + client.dispose(); + await expect(pending).rejects.toMatchObject({ code: "disposed" }); + await expect(client.ready).rejects.toMatchObject({ code: "disposed" }); + expect(host.removeEventListener).toHaveBeenCalled(); + }); +}); diff --git a/packages/core/src/runtime/editingPort.ts b/packages/core/src/runtime/editingPort.ts new file mode 100644 index 0000000000..c8c6994e86 --- /dev/null +++ b/packages/core/src/runtime/editingPort.ts @@ -0,0 +1,272 @@ +/** + * The editing channel between a preview frame and its parent: a MessagePort the + * runtime hands the parent once, carrying typed requests and replies. The + * runtime side is `editingAgent.ts`; `createEditingPortClient` is the parent + * side. Both import their wire types from here, so they cannot drift apart. + * + * Playback transport (play, pause, seek, rate, mute, play range) stays on the + * control protocol in `bridge.ts`. This channel carries the reads a parent + * otherwise takes straight off the frame's window, which an opaque-origin + * preview does not allow. + */ +import type { RuntimeTimelineMessage } from "./types"; +import { wallClearTimeout, wallSetTimeout } from "./wallClock"; + +export const EDITING_PROTOCOL_VERSION = 1 as const; +/** Parent to frame, on the window: asks the runtime for the port. */ +export const EDITING_CONNECT = "editing-connect"; +/** Frame to parent, on the window: carries the port in its transfer list. */ +export const EDITING_PORT = "editing-port"; + +export const EDITING_REQUEST_KINDS = [ + "hello", + "runtime-snapshot", + "wait-for-seek", + "set-loop-start", +] as const; +export type EditingRequestKind = (typeof EDITING_REQUEST_KINDS)[number]; + +export interface EditingRuntimeSnapshot { + /** The runtime has installed its player API. */ + playerReady: boolean; + /** Why the runtime failed to start, when it did. */ + startupError: string | null; + /** The clip manifest the runtime last posted as its `timeline` message. */ + clipManifest: RuntimeTimelineMessage | null; + /** `[childId, parentId]` for each nested clip in the runtime's clip tree. */ + clipParents: Array<[string, string]>; +} + +type NoParams = Record; +export interface EditingRequests { + hello: { + params: NoParams; + result: { version: typeof EDITING_PROTOCOL_VERSION; kinds: string[] }; + }; + "runtime-snapshot": { params: NoParams; result: EditingRuntimeSnapshot }; + /** `waited` is false when the runtime has no seek-completion hook. */ + "wait-for-seek": { params: NoParams; result: { waited: boolean } }; + /** Where a looping playback wraps to; null stops looping from a custom start. */ + "set-loop-start": { params: { seconds: number | null }; result: { applied: boolean } }; +} +export type EditingParams = EditingRequests[K]["params"]; +export type EditingResult = EditingRequests[K]["result"]; + +export type EditingErrorCode = + | "malformed" + | "unsupported-version" + | "unknown-kind" + | "invalid-params" + | "failed" + | "timeout" + | "disposed"; + +export type EditingReply = + | { v: typeof EDITING_PROTOCOL_VERSION; id: number; ok: true; result: unknown } + | { + v: typeof EDITING_PROTOCOL_VERSION; + id: number | null; + ok: false; + error: { code: EditingErrorCode; message: string }; + }; + +export type ParsedEditingRequest = + | { ok: true; id: number; kind: EditingRequestKind; params: EditingParams } + | { ok: false; id: number | null; code: EditingErrorCode; message: string }; + +export function isPlainRecord(value: unknown): value is Record { + return Object.prototype.toString.call(value) === "[object Object]"; +} + +const noParams = (params: unknown): NoParams | null => + params === undefined || (isPlainRecord(params) && Object.keys(params).length === 0) ? {} : null; + +const PARAM_PARSERS: { + [K in EditingRequestKind]: (params: unknown) => EditingParams | null; +} = { + hello: noParams, + "runtime-snapshot": noParams, + "wait-for-seek": noParams, + "set-loop-start": (params) => { + if (!isPlainRecord(params) || Object.keys(params).join() !== "seconds") return null; + const { seconds } = params; + if (seconds === null) return { seconds }; + return typeof seconds === "number" && Number.isFinite(seconds) && seconds >= 0 + ? { seconds } + : null; + }, +}; + +/** Validates one request off the wire. Never throws: anything unusable becomes a typed error. */ +export function parseEditingRequest(data: unknown): ParsedEditingRequest { + if (!isPlainRecord(data) || !Number.isSafeInteger(data.id) || (data.id as number) < 0) { + return { ok: false, id: null, code: "malformed", message: "request needs a numeric id" }; + } + const id = data.id as number; + if (data.v !== EDITING_PROTOCOL_VERSION) { + return { ok: false, id, code: "unsupported-version", message: "unsupported version" }; + } + const kind = EDITING_REQUEST_KINDS.find((known) => known === data.kind); + if (!kind) return { ok: false, id, code: "unknown-kind", message: "unknown request kind" }; + const params = PARAM_PARSERS[kind](data.params); + if (!params) + return { ok: false, id, code: "invalid-params", message: `invalid params for ${kind}` }; + return { ok: true, id, kind, params }; +} + +export class EditingPortError extends Error { + constructor( + readonly code: EditingErrorCode, + message: string, + ) { + super(message); + this.name = "EditingPortError"; + } +} + +export interface EditingPortClient { + /** Settles when the frame's runtime has handed over its port. */ + readonly ready: Promise; + request( + kind: K, + params: EditingParams, + options?: { timeoutMs?: number }, + ): Promise>; + /** Rejects every pending request with `disposed` and closes the port. */ + dispose(): void; +} + +type Outcome = { result: unknown } | { error: EditingPortError }; + +/** A reply's result or typed error. Anything off-shape is `malformed`, never a throw. */ +function replyOutcome(data: Record): Outcome { + if (data.v !== EDITING_PROTOCOL_VERSION) { + return { error: new EditingPortError("unsupported-version", "reply version") }; + } + if (data.ok === true && "result" in data) return { result: data.result }; + const error = isPlainRecord(data.error) ? data.error : null; + if (data.ok !== false || typeof error?.code !== "string") { + return { error: new EditingPortError("malformed", "malformed reply") }; + } + const message = typeof error.message === "string" ? error.message : error.code; + return { error: new EditingPortError(error.code as EditingErrorCode, message) }; +} + +/** The port this frame handed over, "ready" when its runtime came up, else null. */ +function readHandoff( + event: MessageEvent, + frame: Window | null, +): MessagePort | "ready" | null { + const data = event.data; + if (!frame || event.source !== frame || !isPlainRecord(data) || data.source !== "hf-preview") { + return null; + } + if (data.type === "ready") return "ready"; + return data.type === EDITING_PORT && data.v === EDITING_PROTOCOL_VERSION + ? onlyPort(event.ports) + : null; +} + +const onlyPort = (ports: readonly MessagePort[]): MessagePort | null => + ports.length === 1 ? (ports[0] ?? null) : null; + +type Pending = { + resolve: (result: unknown) => void; + reject: (error: EditingPortError) => void; + timer: ReturnType; +}; + +/** + * The parent's end of the editing channel for one preview frame load. Asks for + * the port at once and again on the runtime's `ready`, and takes the first port + * that frame sends. Replies are data from the frame, so callers validate results. + */ +export function createEditingPortClient(options: { + iframe: HTMLIFrameElement; + timeoutMs?: number; + host?: Window; +}): EditingPortClient { + const { iframe, timeoutMs = 5_000, host = window } = options; + const pending = new Map(); + let port: MessagePort | null = null; + let disposed = false; + let lastId = 0; + let resolveReady!: () => void; + let rejectReady!: (error: EditingPortError) => void; + const ready = new Promise((resolve, reject) => { + resolveReady = resolve; + rejectReady = reject; + }); + void ready.catch(() => {}); + + const settle = (id: number, outcome: Outcome) => { + const entry = pending.get(id); + if (!entry) return; + pending.delete(id); + wallClearTimeout(entry.timer); + if ("error" in outcome) entry.reject(outcome.error); + else entry.resolve(outcome.result); + }; + const onReply = (event: MessageEvent) => { + const data = event.data; + if (isPlainRecord(data) && typeof data.id === "number") settle(data.id, replyOutcome(data)); + }; + const connect = () => { + try { + iframe.contentWindow?.postMessage( + { source: "hf-parent", type: EDITING_CONNECT, v: EDITING_PROTOCOL_VERSION }, + "*", + ); + } catch { + // The frame is mid-navigation; its runtime's `ready` asks again. + } + }; + const onWindowMessage = (event: MessageEvent) => { + const handoff = readHandoff(event, iframe.contentWindow); + if (handoff === "ready") return connect(); + if (!handoff) return; + port = handoff; + host.removeEventListener("message", onWindowMessage); + port.onmessage = onReply; + resolveReady(); + }; + host.addEventListener("message", onWindowMessage); + connect(); + + return { + ready, + request(kind, params, requestOptions) { + if (disposed) return Promise.reject(new EditingPortError("disposed", "client disposed")); + const id = ++lastId; + const limit = requestOptions?.timeoutMs ?? timeoutMs; + const result = new Promise((resolve, reject) => { + const timer = wallSetTimeout( + () => settle(id, { error: new EditingPortError("timeout", `${kind} timed out`) }), + limit, + ); + pending.set(id, { resolve, reject, timer }); + }); + const send = () => { + if (!pending.has(id)) return; + try { + port?.postMessage({ v: EDITING_PROTOCOL_VERSION, id, kind, params }); + } catch (err) { + settle(id, { error: new EditingPortError("failed", String(err)) }); + } + }; + // A ready that rejects was disposed, which has already rejected this request. + ready.then(send, () => {}); + return result as Promise>; + }, + dispose() { + if (disposed) return; + disposed = true; + host.removeEventListener("message", onWindowMessage); + port?.close(); + rejectReady(new EditingPortError("disposed", "client disposed")); + for (const id of [...pending.keys()]) { + settle(id, { error: new EditingPortError("disposed", "client disposed") }); + } + }, + }; +} diff --git a/packages/core/src/runtime/init.ts b/packages/core/src/runtime/init.ts index b551dc4fee..e243b86b6e 100644 --- a/packages/core/src/runtime/init.ts +++ b/packages/core/src/runtime/init.ts @@ -39,6 +39,7 @@ import { createPreviewSeek } from "./previewSeek"; import { createPausedVideoFrames, releasePausedVideoFrame } from "./pausedVideoFrames"; import { copiesReady } from "./previewCopies"; import { installRuntimeControlBridge, postRuntimeMessage, setRuntimeProtocolFps } from "./bridge"; +import { installEditingAgent } from "./editingAgent"; import { instantTolerance } from "../clipFacts"; import { isClipVisibleAt, isInClipWindow } from "./clipWindow"; import { isWebKit, mediaElementTime } from "./mediaClock"; @@ -6743,6 +6744,7 @@ export function initSandboxRuntimeModular(): void { onClearRuntimeData: clearRuntimeData, getCanonicalFps: () => state.canonicalFps, }); + runtimeCleanupCallbacks.push(installEditingAgent().dispose); const teardown = () => { if (state.tornDown) return; diff --git a/packages/core/tsconfig.json b/packages/core/tsconfig.json index a73319e714..6c1fd69d8c 100644 --- a/packages/core/tsconfig.json +++ b/packages/core/tsconfig.json @@ -20,6 +20,7 @@ "src/runtime/mediaSteer.ts", "src/runtime/positionEdits.ts", "src/runtime/protocol.ts", + "src/runtime/editingPort.ts", "src/runtime/stackingContext.ts", "src/runtime/webAudioRoute.ts", "src/runtime/levelTap.ts", diff --git a/scripts/package-size-budgets.json b/scripts/package-size-budgets.json index 69e1292ca2..722bf3252c 100644 --- a/scripts/package-size-budgets.json +++ b/scripts/package-size-budgets.json @@ -36,7 +36,7 @@ "unpacked": 541601 }, "@hyperframes/producer": { - "packed": 870000, + "packed": 880000, "unpacked": 3165274 }, "@hyperframes/sdk": {