feat(core): the preview can stream an element's geometry to the editor every frame (#8052)

* feat(core): the preview can stream an element's geometry to the editor every frame

* refactor(core): the editing client hands unasked pushes to one function

* fix(core): geometry watches are capped per page; a lost port or failed measure stops nothing else

* fix(core): the preview measures watched geometry after the frame renders, not inside rAF

* fix(core): watched geometry is measured in the frame's resize-observer step, just before paint

* docs(core): a hidden preview's geometry pushes pause until it has a size

* test(core): keep the fake resize observer's note within the line limit
This commit is contained in:
Miguel Ángel
2026-11-17 12:35:23 +00:00
committed by GitHub
parent 8ec97da011
commit f9c5ed07bf
6 changed files with 441 additions and 2 deletions
@@ -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 = `<div id="box" data-hf-group><i></i></div>`;
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<string, unknown>, 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<Element> }> = [];
vi.stubGlobal(
"ResizeObserver",
class {
entry = { report: (() => {}) as ResizeObserverCallback, targets: new Set<Element>() };
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<number, FrameRequestCallback>();
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 = `<div id="box"></div>`;
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();
});
});
@@ -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<EditingElementGeometry | null> };
type Fields = Record<string, unknown>;
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<MessagePort, EditingElementHandle[]>();
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 };
}
@@ -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 } },
@@ -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();
},
};
}
@@ -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<Record<string, unknown>> = [];
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();
+29 -2
View File
@@ -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<K extends EditingRequestKind> = EditingRequests[K]["params"];
export type EditingResult<K extends EditingRequestKind> = 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<EditingResult<K>>;
/** 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<number, Pending>();
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<string, unknown>) => {
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<unknown>) => {
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<unknown>((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()]) {