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": {