diff --git a/packages/core/src/runtime/editing/watchGeometry.test.ts b/packages/core/src/runtime/editing/watchGeometry.test.ts new file mode 100644 index 0000000000..5da70c89b0 --- /dev/null +++ b/packages/core/src/runtime/editing/watchGeometry.test.ts @@ -0,0 +1,232 @@ +import { afterEach, describe, expect, it, vi } from "vitest"; +import { elementGeometry } from "../editingGeometry"; +import { handleFor } from "../editingHandles"; +import { + geometryEvent, + MAX_GEOMETRY_WATCHERS, + MAX_WATCHED_GEOMETRY, + parseWatchGeometry, + stopWatchingGeometry, + watchGeometry, +} from "./watchGeometry"; + +const H = "0123456789abcdef:1"; + +describe("parseWatchGeometry", () => { + it("takes up to the cap of handles, and an empty list as the stop", () => { + expect(parseWatchGeometry({ handles: [] })).toEqual({ handles: [] }); + const full = Array(MAX_WATCHED_GEOMETRY).fill(H); + expect(parseWatchGeometry({ handles: full })).toEqual({ handles: full }); + }); + + it("refuses an over-cap list, a non-handle and an extra field", () => { + for (const params of [ + { handles: Array(MAX_WATCHED_GEOMETRY + 1).fill(H) }, + { handles: ["1"] }, + { handles: [1] }, + { handles: H }, + { handles: [H], extra: 1 }, + {}, + ]) + expect(parseWatchGeometry(params)).toBeNull(); + }); +}); + +describe("geometryEvent", () => { + const measured = () => { + document.body.innerHTML = `
`; + return elementGeometry([handleFor(document.getElementById("box")!)], undefined).elements[0]!; + }; + + it("takes what the frame measures, and a gone element as null", () => { + const element = measured(); + const data = { v: 1, event: "geometry", at: 12.5, elements: [element, null] }; + expect(geometryEvent(data, 1)).toEqual({ at: 12.5, elements: [element, null] }); + }); + + it("drops a push with a field it does not allow, at any level", () => { + const element = measured(); + const push = (over: Record, el: unknown = element) => ({ + v: 1, + event: "geometry", + at: 1, + elements: [el], + ...over, + }); + for (const bad of [ + push({ extra: 1 }), + push({ v: 2 }), + push({ event: "key" }), + push({ at: Number.NaN }), + push({ elements: Array(MAX_WATCHED_GEOMETRY + 1).fill(null) }), + push({}, { ...element, extra: 1 }), + push({}, { ...element, rect: { ...element.rect, z: 0 } }), + push({}, { ...element, rect: { ...element.rect, x: "0" } }), + push({}, { ...element, visible: "yes" }), + push({}, { ...element, clipPath: "x".repeat(2_001) }), + push({}, { ...element, members: [{ ...element.rect, z: 0 }] }), + push({}, { ...element, corners: { nw: { x: 0, y: 0 } } }), + push({}, { ...element, source: { width: 1, height: 1, declaredWidth: null } }), + ]) + expect(geometryEvent(bad, 1)).toBeNull(); + }); +}); + +// jsdom has no ResizeObserver: this one reports each observed target after the frame's rAF callbacks, as browsers do. +const observed: Array<{ report: ResizeObserverCallback; targets: Set }> = []; +vi.stubGlobal( + "ResizeObserver", + class { + entry = { report: (() => {}) as ResizeObserverCallback, targets: new Set() }; + constructor(report: ResizeObserverCallback) { + this.entry.report = report; + observed.push(this.entry); + } + observe(target: Element) { + this.entry.targets.add(target); + } + unobserve(target: Element) { + this.entry.targets.delete(target); + } + }, +); + +describe("watchGeometry", () => { + const frames = new Map(); + let lastFrame = 0; + let now = 0; + const step = () => { + now += 16; + const due = [...frames.values()]; + frames.clear(); + for (const run of due) run(now); + for (const { report, targets } of observed) if (targets.size) report([], {} as ResizeObserver); + }; + const pushes = (port: MessagePort) => { + const seen: unknown[] = []; + port.onmessage = (event) => seen.push(event.data); + return seen; + }; + + afterEach(() => { + stopWatchingGeometry(); + vi.restoreAllMocks(); + frames.clear(); + }); + + const setUp = () => { + vi.spyOn(performance, "now").mockImplementation(() => now); + vi.spyOn(window, "requestAnimationFrame").mockImplementation((run) => { + frames.set(++lastFrame, run); + return lastFrame; + }); + vi.spyOn(window, "cancelAnimationFrame").mockImplementation((key) => frames.delete(key)); + document.body.innerHTML = `
`; + const handle = handleFor(document.getElementById("box")!); + const { port1, port2 } = new MessageChannel(); + return { handle, frame: port1, parent: port2 }; + }; + + it("pushes the watched elements' geometry each animation frame, stamped on the shared clock", async () => { + const { handle, frame, parent } = setUp(); + const seen = pushes(parent); + expect(watchGeometry(frame, { handles: [handle, H] }, 1)).toEqual({ watching: 2 }); + step(); + await vi.waitFor(() => expect(seen).toHaveLength(1)); + step(); + await vi.waitFor(() => expect(seen).toHaveLength(2)); + const [expected] = elementGeometry([handle], undefined).elements; + expect(seen[1]).toEqual({ + v: 1, + event: "geometry", + at: performance.timeOrigin + 32, + elements: [expected, null], + }); + expect(geometryEvent(seen[1], 1)).not.toBeNull(); + parent.close(); + }); + + it("refuses a port past the watcher cap, and still lets a watching port change its list", () => { + const { handle, frame, parent } = setUp(); + const others = Array.from({ length: MAX_GEOMETRY_WATCHERS - 1 }, () => new MessageChannel()); + watchGeometry(frame, { handles: [handle] }, 1); + for (const { port1 } of others) watchGeometry(port1, { handles: [handle] }, 1); + const extra = new MessageChannel(); + expect(() => watchGeometry(extra.port1, { handles: [handle] }, 1)).toThrow(/at most/); + expect(watchGeometry(frame, { handles: [handle, H] }, 1)).toEqual({ watching: 2 }); + for (const { port1, port2 } of [...others, extra]) { + port1.close(); + port2.close(); + } + parent.close(); + }); + + it("drops a watch whose port throws, and keeps pushing to the rest", async () => { + const { handle, frame, parent } = setUp(); + const seen = pushes(parent); + const lost = { + postMessage: () => { + throw new Error("gone"); + }, + } as unknown as MessagePort; + watchGeometry(lost, { handles: [handle] }, 1); + watchGeometry(frame, { handles: [handle] }, 1); + step(); + await vi.waitFor(() => expect(seen).toHaveLength(1)); + step(); + await vi.waitFor(() => expect(seen).toHaveLength(2)); + stopWatchingGeometry(frame); + expect(frames.size).toBe(0); + parent.close(); + }); + + it("keeps the loop running when a frame's measure throws", async () => { + const { handle, frame, parent } = setUp(); + watchGeometry(frame, { handles: [handle] }, 1); + const measure = vi.spyOn(window, "getComputedStyle").mockImplementationOnce(() => { + throw new Error("detached"); + }); + step(); + await vi.waitFor(() => expect(frames.size).toBe(1)); + expect(measure).toHaveBeenCalled(); + parent.close(); + }); + + it("measures after the frame renders, so a later rAF callback's change is what it reports", async () => { + const { handle, frame, parent } = setUp(); + const seen = pushes(parent); + const box = document.getElementById("box")!; + watchGeometry(frame, { handles: [handle] }, 1); + // A callback queued after the watch's, as Studio's or the runtime's own rAF work would be. + requestAnimationFrame(() => box.style.setProperty("clip-path", "inset(2px)")); + step(); + await vi.waitFor(() => expect(seen).toHaveLength(1)); + const [element] = (seen[0] as { elements: Array<{ clipPath: string }> }).elements; + expect(element.clipPath).toBe("inset(2px)"); + parent.close(); + }); + + it("stops on an empty list, on the page hiding, and on the agent's stop", () => { + const { handle, frame, parent } = setUp(); + const stops = [ + () => watchGeometry(frame, { handles: [] }, 1), + () => window.dispatchEvent(new Event("pagehide")), + () => stopWatchingGeometry(frame), + ]; + const observing = () => observed.some(({ targets }) => targets.size > 0); + for (const stop of stops) { + watchGeometry(frame, { handles: [handle] }, 1); + expect(frames.size).toBe(1); + stop(); + expect(frames.size).toBe(0); + // Stopped again between a frame's re-arm and its observer step: the observer lets go too. + watchGeometry(frame, { handles: [handle] }, 1); + for (const arm of [...frames.values()]) arm(now); + frames.clear(); + expect(observing()).toBe(true); + stop(); + expect(observing()).toBe(false); + } + parent.close(); + }); +}); diff --git a/packages/core/src/runtime/editing/watchGeometry.ts b/packages/core/src/runtime/editing/watchGeometry.ts new file mode 100644 index 0000000000..2c5a10fd53 --- /dev/null +++ b/packages/core/src/runtime/editing/watchGeometry.ts @@ -0,0 +1,147 @@ +// `watch-geometry`: the frame pushes the named elements' `geometry` fields once per animation frame, +// stamped on the clock both windows share, until an empty list, the page hiding, or the parent's release. +import { + EDITING_ELEMENT_HANDLE, + MAX_ELEMENT_ENTRIES, + MAX_ELEMENT_VALUE, + type EditingElementHandle, + type EditingRect, +} from "../editingElement"; +import { swallow } from "../diagnostics"; +import { elementGeometry, type EditingElementGeometry } from "../editingGeometry"; + +export const MAX_WATCHED_GEOMETRY = 32; +export const MAX_GEOMETRY_WATCHERS = 8; + +export type WatchGeometryParams = { handles: EditingElementHandle[] }; +/** `at` is `performance.timeOrigin + performance.now()` in the frame when it measured. */ +export type EditingGeometryEvent = { at: number; elements: Array }; + +type Fields = Record; +const isRecord = (value: unknown): value is Fields => + Object.prototype.toString.call(value) === "[object Object]"; +const keysAre = (value: unknown, keys: string): value is Fields => + isRecord(value) && Object.keys(value).sort().join() === keys; +const finite = (value: unknown): value is number => Number.isFinite(value); +const finiteOrNull = (value: unknown) => value === null || finite(value); + +export function parseWatchGeometry(params: unknown): WatchGeometryParams | null { + if (!keysAre(params, "handles") || !Array.isArray(params.handles)) return null; + const { handles } = params; + if (handles.length > MAX_WATCHED_GEOMETRY) return null; + const valid = handles.every((h) => typeof h === "string" && EDITING_ELEMENT_HANDLE.test(h)); + return valid ? { handles } : null; +} + +const isRect = (value: unknown): value is EditingRect => + keysAre(value, "height,width,x,y") && [value.x, value.y, value.width, value.height].every(finite); +const isPoint = (value: unknown) => keysAre(value, "x,y") && finite(value.x) && finite(value.y); +const isCorners = (value: unknown) => + value === null || (keysAre(value, "ne,nw,se,sw") && Object.values(value).every(isPoint)); +const isSource = (value: unknown) => + value === null || + (keysAre(value, "declaredHeight,declaredWidth,height,width") && + finite(value.width) && + finite(value.height) && + finiteOrNull(value.declaredWidth) && + finiteOrNull(value.declaredHeight)); +const isClipPath = (value: unknown) => + value === null || (typeof value === "string" && value.length <= MAX_ELEMENT_VALUE); +const isMembers = (value: unknown) => + value === null || + (Array.isArray(value) && value.length <= MAX_ELEMENT_ENTRIES && value.every(isRect)); + +function isGeometry(value: unknown): value is EditingElementGeometry { + if (!keysAre(value, "angle,clipPath,corners,members,rect,source,visible")) return false; + return ( + isRect(value.rect) && + finite(value.angle) && + isCorners(value.corners) && + isSource(value.source) && + isClipPath(value.clipPath) && + typeof value.visible === "boolean" && + isMembers(value.members) + ); +} + +/** One pushed message off the port, or null for anything with a field it does not allow. */ +export function geometryEvent(data: unknown, version: number): EditingGeometryEvent | null { + if (!keysAre(data, "at,elements,event,v") || data.v !== version || data.event !== "geometry") { + return null; + } + const { at, elements } = data; + if (!finite(at) || !Array.isArray(elements) || elements.length > MAX_WATCHED_GEOMETRY) + return null; + return elements.every((e) => e === null || isGeometry(e)) ? { at, elements } : null; +} + +const watches = new Map(); +let wireVersion = 0; + +function pushTo(port: MessagePort, handles: EditingElementHandle[], at: number): void { + const { elements } = elementGeometry(handles, undefined); + try { + port.postMessage({ v: wireVersion, event: "geometry", at, elements }); + } catch { + watches.delete(port); + } +} + +function push(): void { + observer?.unobserve(document.documentElement); + observing = false; + const at = performance.timeOrigin + performance.now(); + try { + for (const [port, handles] of watches) pushTo(port, handles, at); + } catch (err) { + swallow("watchGeometry.push", err); + } finally { + schedule(); + } +} + +// The measure runs in the frame's ResizeObserver step: after every rAF callback and layout, just before paint. +// observe() resets the last reported size, so the root reports once each frame it is observed, resized or not. +// A frame with no size has nothing to report: a hidden frame's pushes pause until it gets one. +let observer: ResizeObserver | null = null; +let observing = false; +let nextFrame = 0; +function observeThisFrame(): void { + nextFrame = 0; + if (!watches.size) return; + observer ??= new ResizeObserver(push); + observer.observe(document.documentElement); + observing = true; +} + +function schedule(): void { + if (watches.size && !nextFrame && !observing) nextFrame = requestAnimationFrame(observeThisFrame); + if (watches.size) return; + if (nextFrame) cancelAnimationFrame(nextFrame); + if (observing) observer?.unobserve(document.documentElement); + nextFrame = 0; + observing = false; +} + +/** Stops `port`'s watch, or every watch when no port is named. */ +export function stopWatchingGeometry(port?: MessagePort): void { + if (port) watches.delete(port); + else watches.clear(); + schedule(); +} + +const stopAll = () => stopWatchingGeometry(); + +export function watchGeometry( + port: MessagePort, + { handles }: WatchGeometryParams, + version: number, +): { watching: number } { + if (!handles.length) watches.delete(port); + else if (watches.has(port) || watches.size < MAX_GEOMETRY_WATCHERS) watches.set(port, handles); + else throw new Error(`at most ${MAX_GEOMETRY_WATCHERS} ports may watch geometry`); + wireVersion = version; + window.addEventListener("pagehide", stopAll); + schedule(); + return { watching: handles.length }; +} diff --git a/packages/core/src/runtime/editingAgent.test.ts b/packages/core/src/runtime/editingAgent.test.ts index e0a72969cf..db4158ff93 100644 --- a/packages/core/src/runtime/editingAgent.test.ts +++ b/packages/core/src/runtime/editingAgent.test.ts @@ -190,6 +190,7 @@ describe("installEditingAgent", () => { "color-grading-status", "color-grading-previews", "color-grading-playback", + "watch-geometry", ], }, }); @@ -415,6 +416,13 @@ describe("installEditingAgent", () => { 180 + index, "invalid-params", ]), + ...[{}, { handles: ["1"] }, { handles: Array(33).fill(H) }, { handles: [], extra: 1 }].map( + (params, index) => [ + { v: 1, id: 900 + index, kind: "watch-geometry", params }, + 900 + index, + "invalid-params", + ], + ), ...[["--"], ["--a b"], ["--a;b"], ["--a:b"], ["Color"], ["-x"], ["--" + "a".repeat(255)]].map( (properties, index) => [ { v: 1, id: 60 + index, kind: "computed-styles", params: { selector: "p", properties } }, diff --git a/packages/core/src/runtime/editingAgent.ts b/packages/core/src/runtime/editingAgent.ts index 493933e5a2..af4212ec82 100644 --- a/packages/core/src/runtime/editingAgent.ts +++ b/packages/core/src/runtime/editingAgent.ts @@ -33,6 +33,7 @@ import { pointerTargetsAt } from "./editingTargets"; import { layersOf } from "./editingLayers"; import { drawDrafts } from "./editingDraft"; import { restoreAttributes } from "./editing/restoreAttributes"; +import { stopWatchingGeometry, watchGeometry } from "./editing/watchGeometry"; import { gestureStart } from "./editingGestureStart"; import { getLogicalOpacity, @@ -200,6 +201,7 @@ const HANDLERS: Handlers = { "color-grading-status": colorGradingStatus, "color-grading-previews": colorGradingPreviews, "color-grading-playback": colorGradingPlayback, + "watch-geometry": (params, port) => watchGeometry(port, params, EDITING_PROTOCOL_VERSION), }; function serve(port: MessagePort): void { @@ -279,6 +281,7 @@ export function installEditingAgent(parent: Window = window.parent): { dispose: consoleWatch = null; keyWatches.clear(); listenForKeys(false); + stopWatchingGeometry(); }, }; } diff --git a/packages/core/src/runtime/editingPort.test.ts b/packages/core/src/runtime/editingPort.test.ts index 4ecd1fe023..192753d52c 100644 --- a/packages/core/src/runtime/editingPort.test.ts +++ b/packages/core/src/runtime/editingPort.test.ts @@ -83,6 +83,7 @@ describe("createEditingPortClient", () => { "color-grading-status", "color-grading-previews", "color-grading-playback", + "watch-geometry", ], }); } finally { @@ -246,6 +247,27 @@ describe("createEditingPortClient", () => { await expect(late).rejects.toMatchObject({ code: "timeout" }); }); + it("hands each geometry push to its listeners, drops off-shape ones, and stops the watch on dispose", async () => { + const { iframe, frame } = previewFrame(); + const { host, deliver } = fakeHost(); + const client = createEditingPortClient({ iframe, host }); + const { port1, port2 } = channel(); + deliver({ source: frame, data: PORT_MESSAGE, ports: [port1] }); + await client.ready; + const asked: Array> = []; + port2.onmessage = (event) => asked.push(event.data); + const heard = vi.fn(); + client.onGeometry(heard); + void client.request("watch-geometry", { handles: ["0123456789abcdef:1"] }).catch(() => {}); + port2.postMessage({ v: 1, event: "geometry", at: 1, elements: [null], extra: 1 }); + port2.postMessage({ v: 1, event: "geometry", at: 2, elements: [null] }); + await vi.waitFor(() => expect(heard).toHaveBeenCalledOnce()); + expect(heard).toHaveBeenCalledWith({ at: 2, elements: [null] }); + client.dispose(); + await vi.waitFor(() => expect(asked).toHaveLength(2)); + expect(asked[1]).toMatchObject({ kind: "watch-geometry", params: { handles: [] } }); + }); + it("dispose rejects pending and later requests and closes the port", async () => { const { iframe, frame } = previewFrame(); const { host, deliver } = fakeHost(); diff --git a/packages/core/src/runtime/editingPort.ts b/packages/core/src/runtime/editingPort.ts index 05798d126e..b064f5a2c3 100644 --- a/packages/core/src/runtime/editingPort.ts +++ b/packages/core/src/runtime/editingPort.ts @@ -10,6 +10,12 @@ * preview does not allow. */ import { parseRestoreAttributes, type RestoreAttributesParams } from "./editing/restoreAttributes"; +import { + geometryEvent, + parseWatchGeometry, + type EditingGeometryEvent, + type WatchGeometryParams, +} from "./editing/watchGeometry"; import { EDITING_ELEMENT_HANDLE, MAX_DESCRIBE_HANDLES, @@ -139,6 +145,7 @@ export const EDITING_REQUEST_KINDS = [ "color-grading-status", "color-grading-previews", "color-grading-playback", + "watch-geometry", ] as const; export type EditingRequestKind = (typeof EDITING_REQUEST_KINDS)[number]; @@ -254,6 +261,7 @@ export interface EditingRequests { "color-grading-status": ColorGradingStatusRequest; "color-grading-previews": ColorGradingPreviewsRequest; "color-grading-playback": ColorGradingPlaybackRequest; + "watch-geometry": { params: WatchGeometryParams; result: { watching: number } }; } export type EditingParams = EditingRequests[K]["params"]; export type EditingResult = EditingRequests[K]["result"]; @@ -446,6 +454,7 @@ const PARAM_PARSERS: { "color-grading-status": parseColorGradingStatusParams, "color-grading-previews": parseColorGradingPreviewsParams, "color-grading-playback": parseColorGradingPlaybackParams, + "watch-geometry": parseWatchGeometry, }; /** Validates one request off the wire. Never throws: anything unusable becomes a typed error. */ @@ -485,6 +494,7 @@ export interface EditingPortClient { ): Promise>; /** Calls `listener` with each key the frame forwards for `watch-keys`; returns the unsubscribe. */ onKey(listener: (key: EditingKeyEvent) => void): () => void; + onGeometry(listener: (event: EditingGeometryEvent) => void): () => void; /** Rejects every pending request with `disposed` and closes the port. */ dispose(): void; } @@ -542,6 +552,8 @@ export function createEditingPortClient(options: { const { iframe, timeoutMs = 5_000, host = window } = options; const pending = new Map(); const keyListeners = new Set<(key: EditingKeyEvent) => void>(); + const geometryListeners = new Set<(event: EditingGeometryEvent) => void>(); + let watchedGeometry = false; let port: MessagePort | null = null; let disposed = false; let lastId = 0; @@ -561,12 +573,17 @@ export function createEditingPortClient(options: { if ("error" in outcome) entry.reject(outcome.error); else entry.resolve(outcome.result); }; + const onPush = (data: Record) => { + const key = data.v === EDITING_PROTOCOL_VERSION && data.event === "key" && keyEvent(data.key); + if (key) return keyListeners.forEach((listener) => listener(key)); + const geometry = geometryEvent(data, EDITING_PROTOCOL_VERSION); + if (geometry) geometryListeners.forEach((listener) => listener(geometry)); + }; const onReply = (event: MessageEvent) => { const data = event.data; if (!isPlainRecord(data)) return; if (typeof data.id === "number") return settle(data.id, replyOutcome(data)); - const key = data.v === EDITING_PROTOCOL_VERSION && data.event === "key" && keyEvent(data.key); - if (key) for (const listener of keyListeners) listener(key); + onPush(data); }; const connect = () => { try { @@ -595,6 +612,7 @@ export function createEditingPortClient(options: { request(kind, params, requestOptions) { if (disposed) return Promise.reject(new EditingPortError("disposed", "client disposed")); const id = ++lastId; + if (kind === "watch-geometry") watchedGeometry = true; const limit = requestOptions?.timeoutMs ?? timeoutMs; const result = new Promise((resolve, reject) => { const timer = wallSetTimeout( @@ -619,11 +637,20 @@ export function createEditingPortClient(options: { keyListeners.add(listener); return () => keyListeners.delete(listener); }, + onGeometry(listener) { + geometryListeners.add(listener); + return () => geometryListeners.delete(listener); + }, dispose() { if (disposed) return; disposed = true; keyListeners.clear(); + geometryListeners.clear(); host.removeEventListener("message", onWindowMessage); + if (watchedGeometry) { + const stop = { kind: "watch-geometry", params: { handles: [] } }; + port?.postMessage({ v: EDITING_PROTOCOL_VERSION, id: ++lastId, ...stop }); + } port?.close(); rejectReady(new EditingPortError("disposed", "client disposed")); for (const id of [...pending.keys()]) {