Files
hyperframes/packages/studio/src/components/editor/domEditOverlayTransform.ts
T
Miguel Ángel 0408fbcd99 perf(studio): scrubbing a large composition no longer stalls the editor (#3842)
* perf(studio): ask each ancestor once per off-canvas rebuild, not once per element

The dashed off-canvas markers are rebuilt whenever anything in the preview
changes, which during playback or a scrub is several times a second. Most of
what a rebuild asked about an element was really a question about its
ANCESTORS: does each node up to the root render, what does each contribute to
the composed transform, which node is the source-file boundary. Two siblings
share their whole chain, so a preview of a thousand elements asked the platform
the same questions about the same ancestors a thousand times over.

A rebuild now threads one measure pass through the walk, and each node answers
once. On a 1689-element carousel that takes computed-style reads from 11,159 to
2,526 per rebuild and the rebuild itself from 59 to 12-18 ms per seek, with the
rendered marker set byte-identical.

The pass is deliberately not a cache. A cache would have to say what could have
changed since last time, and for a measurement the answer is anything: an image
finishing decode, a font swapping in, a transition frame, a container query, an
inserted stylesheet rule all move an element's box with nothing written to the
DOM and no record to invalidate on. A pass lives inside one synchronous
measurement that only reads, so nothing can move under it, and it is dropped
when the measurement ends. Every rebuild still measures every element.

Layout reads are untouched on purpose: each element still takes its own client
rect every rebuild, because that is the read that cannot be shared and must not
be remembered.

* test(studio): give one PropertyPanel case the file's own render timeout

Every other render test in that file passes RENDER_TIMEOUT_MS; this it.each was
left on vitest's 5s default and times out when the whole suite runs on a loaded
machine. Unrelated to any behaviour: it passes on either side of the change
when the machine is quiet, and fails in a full-suite run on either side when it
is not.

* refactor(studio): share the source-boundary walk and dedupe the rebuild fixtures

Three follow-ups from review of the measure pass, none of them behaviour:

The source boundary was memoized against the element that asked for it, so two
siblings still walked their whole chain separately and only the answer was
reused. It now memoizes every node on the way up, like the other two walks:
an element's boundary IS its parent's unless the element is one itself.

`isElementVisibleThroughAncestors` returns what it always returned, but it now
resolves top-down, so the set of nodes it takes a style read for is different
(smaller for a subtree hidden near the root). Three callers use it with no
memo, so that is written down next to it rather than left to be discovered.

The three rebuild fixtures in the indicator tests each carried their own copy
of the iframe/overlay/layout-stub scaffolding, which is four clone groups and
126 duplicated lines. One `mountPreview` helper now serves all of them and the
pre-existing selector-index fixture too.

* test(studio): pin the measure pass to one rebuild through an ancestor-derived input

The existing no-mutation-record test varies an element's own box, and the pass
never memoizes a box — so hoisting the pass to module scope, which is exactly
the mistake that would reintroduce cross-rebuild staleness, left every test
green.

This one fades a wrapper between two rebuilds and asserts the marker under it
goes away. Visibility through ancestors IS memoized, so the pass surviving the
rebuild serves the stale answer: with `createOverlayMeasurePass()` hoisted the
suite exits 1 on this test alone, and exits 0 at head.
2026-09-10 14:48:30 +00:00

127 lines
5.3 KiB
TypeScript

/**
* One walk from an element up to its composition root, composing the transform
* it actually paints under.
*
* The overlay measures an element's angle in two places — the selection box and
* the crop frame — and they need different arithmetic: one works in DOMMatrix
* because it goes on to transform corner points, the other in plain 2D
* components because it only needs an angle and a scale. What they must never
* differ on is *which* transforms count and in what order, because when they
* disagree the chrome disagrees with itself: the selection box drawn at one
* angle and the crop outline at another, on the same element.
*
* So the walk lives here once and takes the arithmetic as a parameter. Adding
* an individual property CSS grew later — `translate`, `scale` — means adding
* one step here and one method to each algebra, rather than finding both walks
* and hoping.
*/
/** The composition's own root; the walk stops there rather than at the document. */
const COMPOSITION_ROOT_ATTR = "data-composition-id";
/**
* The arithmetic the walk needs, whatever the caller's matrix type is.
*
* `fromTransform` returns null for a transform the caller cannot use — a
* perspective matrix, say — which aborts the walk rather than composing a
* matrix that describes something other than what is painted.
*/
export interface PlanarTransformOps<M> {
identity(): M;
fromTransform(value: string): M | null;
fromRotate(degrees: number): M;
/** `outer` applied around `inner`, as an ancestor composes over a child. */
compose(outer: M, inner: M): M;
}
/**
* The planar rotation in the CSS `rotate` property, in degrees.
*
* Computes to `none`, an angle (`-22deg`), or an axis plus an angle
* (`0 0 1 -22deg`). Only a rotation about z stays in the overlay's plane; any
* other axis is 3D and reports 0, which leaves the caller on its axis-aligned
* fallback rather than drawing a box at a plausible-looking wrong angle.
*/
export function individualRotateDegrees(value: string | undefined): number {
if (!value || value === "none") return 0;
const parts = value.trim().split(/\s+/);
const angle = parts.at(-1);
if (!angle?.endsWith("deg")) return 0;
if (parts.length === 4) {
const [x, y, z] = parts;
if (Number(x) !== 0 || Number(y) !== 0 || Math.abs(Number(z)) !== 1) return 0;
const deg = Number.parseFloat(angle);
return Number.isFinite(deg) ? deg * Math.sign(Number(z)) : 0;
}
if (parts.length !== 1) return 0;
const deg = Number.parseFloat(angle);
return Number.isFinite(deg) ? deg : 0;
}
/** One node's own contribution, with the individual properties applied before
* `transform` the way CSS does. Null when the node's transform is unusable. */
function ownNodeTransform<M>(
node: HTMLElement,
ops: PlanarTransformOps<M>,
getStyle: (node: HTMLElement) => CSSStyleDeclaration | null,
): M | null {
const style = getStyle(node);
if (!style) return null;
const transform = style.transform;
const own = transform && transform !== "none" ? ops.fromTransform(transform) : ops.identity();
if (!own) return null;
const spin = individualRotateDegrees(style.rotate);
return spin === 0 ? own : ops.compose(ops.fromRotate(spin), own);
}
/**
* The element's transform composed with every ancestor's, up to the composition
* root.
*
* Within a node, CSS applies the individual properties before `transform`, so
* `rotate` composes on the left of it. Between nodes, an ancestor applies
* outside its child. Null means some node's transform was unusable and the
* caller should fall back rather than guess.
*
* `memo` holds each node's COMPOSED chain, for a caller walking many elements
* in one synchronous pass.
*
* A chain is `chain(parent)` composed with the node's own, so siblings share
* everything above them and the whole tree costs one style read and one
* compose per node instead of one per node PER DESCENDANT. Valid only for the
* length of one pass, which is why the caller owns it: nothing here writes to
* the DOM, so nothing can move under it, and it is dropped before anything
* else runs. Omitted, every call composes its own chain from scratch.
*/
export function composeElementTransform<M>(
element: HTMLElement,
ops: PlanarTransformOps<M>,
getStyle: (node: HTMLElement) => CSSStyleDeclaration | null,
memo?: Map<HTMLElement, M | null>,
): M | null {
const pending: HTMLElement[] = [];
// `undefined` means nothing on the way up was already composed, so the chain
// starts from identity. A memoized `null` is an answer, not a miss: some node
// above carries a transform this algebra cannot represent.
let above: M | null | undefined;
for (let node: HTMLElement | null = element; node; node = node.parentElement) {
above = memo?.get(node);
if (above !== undefined) break;
pending.push(node);
if (node.hasAttribute(COMPOSITION_ROOT_ATTR)) break;
}
let acc: M | null = above === undefined ? ops.identity() : above;
for (let i = pending.length - 1; i >= 0; i -= 1) {
const node = pending[i]!;
if (acc !== null) {
const own = ownNodeTransform(node, ops, getStyle);
// The ancestors' chain is the OUTER of the pair, as an ancestor applies
// around its child.
acc = own === null ? null : ops.compose(acc, own);
}
memo?.set(node, acc);
}
return acc;
}