@hyperframes/studio 0.8.32 → 0.8.34

package/src/components/editor/domEditLayerWalkCache.ts

@@ -0,0 +1,327 @@
+/**
+ * Incremental memory for `collectDomEditLayerItems`.
+ *
+ * The layer walk is re-run from scratch every time a MutationObserver says the
+ * preview changed, and the observer's loudest source is inline `style` — which
+ * is exactly what animation writes. So a paused-looking editor re-derived every
+ * element's patch target, label and child count several times a second, and each
+ * derivation costs two `getComputedStyle` reads (its own plus one per direct
+ * child), two ancestor walks for the source file, and a `textContent` read whose
+ * cost is the element's whole subtree.
+ *
+ * None of that depends on the traversal — only on the element. So the traversal
+ * stays live (it is pointer-chasing, and `depth` genuinely is positional) and the
+ * per-element half is memoized, with the mutation records deciding what to drop.
+ *
+ * WHAT MAKES A CACHED ENTRY WRONG, and how each is caught:
+ *
+ *   - the element's own attributes (`style` -> computed display, `class`/`id`/
+ *     `data-hf-group` -> selector and label)        -> attribute record on it
+ *   - an ancestor's `visibility`, the ONLY inherited input to the
+ *     display/visibility gate (`display:none` on an ancestor does not change a
+ *     descendant's own computed `display`)          -> attribute record on the
+ *                                                      ancestor, whose subtree is
+ *                                                      dropped only when the
+ *                                                      style declares visibility
+ *   - a direct child appearing or disappearing from the layer list, which moves
+ *     the parent's `childCount`                     -> the parent is dropped
+ *                                                      alongside every element
+ *   - descendant text, which moves an ancestor's label -> characterData record,
+ *                                                      ancestors dropped
+ *   - selector occurrence indices, which shift for EVERY element sharing a
+ *     selector when one element's identity changes  -> whole cache dropped
+ *   - nodes added or removed, which shift indices, order, labels and counts at
+ *     once and cannot be attributed to one element  -> whole cache dropped
+ *   - a different active composition path, or a new composition-id -> source-file
+ *     map, both of which re-scope every source file -> checked per walk
+ *
+ * The bias is deliberate and matches the duration cache in the runtime: a
+ * redundant recomputation is a missed optimisation, a missed one is a wrong
+ * layer tree.
+ */
+
+import { buildElementLabel, getCompositionSourceMapRevision, isHtmlElement } from "./domEditingDom";
+import {
+  getDirectLayerChildren,
+  isInspectableLayerElement,
+  resolveDomLayerIdentity,
+} from "./domEditingElement";
+import type { DomEditSelection } from "./domEditingTypes";
+
+/** How an element is addressed. Survives style writes; see `readIdentity`. */
+export type DomEditLayerIdentity = Pick<
+  DomEditSelection,
+  "id" | "hfId" | "selector" | "selectorIndex" | "sourceFile"
+>;
+
+/** Whether the element renders, and how many of its direct children are layers.
+ *  Both are computed style reads, and both a style write can flip. Filled
+ *  lazily: `childCount` is only asked for once an element is known to be one. */
+interface PresenceMemo {
+  inspectable?: boolean;
+  childCount?: number;
+}
+
+interface IdentityMemo {
+  identity?: DomEditLayerIdentity | null;
+  label?: string;
+}
+
+/**
+ * Attributes that decide an element's SELECTOR, and therefore the occurrence
+ * index of every other element sharing that selector. One of these changing
+ * renumbers elements the record does not mention, so the only sound response is
+ * to drop everything. `class` is here because `buildStableSelector` falls back
+ * to the preferred class.
+ */
+const SELECTOR_IDENTITY_ATTRIBUTES = new Set([
+  "id",
+  "class",
+  "data-hf-group",
+  "data-composition-id",
+  "data-composition-file",
+  "data-composition-src",
+  "data-hf-original-composition-id",
+]);
+
+/**
+ * The observer configuration the cache's invalidation is written against.
+ * Exported so the refresh loop and the tests cannot drift from it.
+ *
+ * No `attributeFilter`: an unlisted attribute is one the cache would never learn
+ * about, and serving a stale entry is worse than the extra records.
+ */
+export const DOM_EDIT_LAYER_OBSERVER_INIT: MutationObserverInit = {
+  attributes: true,
+  characterData: true,
+  childList: true,
+  subtree: true,
+};
+
+/**
+ * The inline `visibility` each element last presented. Deliberately NOT cleared
+ * by `invalidateAll`: it records what the DOM said, not a value derived from it.
+ */
+const lastInlineVisibility = new WeakMap<HTMLElement, string>();
+
+/**
+ * Did this style write move the element's inline `visibility`?
+ *
+ * `visibility` is inherited, so changing it changes the layer-list membership of
+ * the element's whole subtree, and only then is the subtree worth dropping.
+ *
+ * The comparison is on the PARSED value, remembered per element. Testing the
+ * attribute TEXT for "visibility" looks equivalent and is not: the standard
+ * GSAP fade (`autoAlpha`) writes `visibility: visible` once and leaves it in the
+ * attribute for the rest of the clip, so a text test stays true for every
+ * transform tick afterwards. That is a whole-subtree walk per animation frame,
+ * in the observer callback rather than behind the rebuild throttle, on exactly
+ * the elements a composition animates most.
+ *
+ * An element seen for the first time reports changed, which costs one drop and
+ * is the safe answer: its entries were derived before this write.
+ */
+function inlineVisibilityChanged(el: HTMLElement): boolean {
+  const next = el.style.visibility;
+  if (lastInlineVisibility.get(el) === next) return false;
+  lastInlineVisibility.set(el, next);
+  return true;
+}
+
+export interface DomEditLayerWalkCache {
+  /**
+   * Start a walk. Drops everything when the scoping inputs the entries were
+   * built under no longer hold. Call once per `collectDomEditLayerItems`.
+   */
+  beginWalk(activeCompositionPath: string | null): void;
+  /**
+   * Does `el` render? Cheap to invalidate and invalidated often: any attribute
+   * write on the element, on its parent, or a `visibility` write on an ancestor
+   * drops it, because all three can flip the answer.
+   */
+  readInspectable(el: HTMLElement, compute: () => boolean): boolean;
+  /** How many of `el`'s direct children are layers. Same lifetime as
+   *  `readInspectable`: it is a sum over their answers. */
+  readChildCount(el: HTMLElement, compute: () => number): number;
+  /**
+   * `el`'s selector, occurrence index and source file. A SEPARATE, much longer
+   * lifetime than presence: a style write cannot renumber a selector, so this
+   * survives one, and it is the only part of the walk that queries the
+   * document. That split is what makes an ordinary animation frame cost no
+   * document queries at all.
+   */
+  readIdentity(
+    el: HTMLElement,
+    compute: () => DomEditLayerIdentity | null,
+  ): DomEditLayerIdentity | null;
+  /** `el`'s display label. Shares the identity lifetime, plus descendant text. */
+  readLabel(el: HTMLElement, compute: () => string): string;
+  /** Apply mutation records. Safe to call with an empty array. */
+  ingest(records: MutationRecord[]): void;
+  /** Forget every entry — the fallback for anything not attributable. */
+  invalidateAll(): void;
+}
+
+export function createDomEditLayerWalkCache(): DomEditLayerWalkCache {
+  let presence = new WeakMap<HTMLElement, PresenceMemo>();
+  let identities = new WeakMap<HTMLElement, IdentityMemo>();
+  let scope: string | null = null;
+
+  const invalidateAll = () => {
+    presence = new WeakMap();
+    identities = new WeakMap();
+  };
+
+  const drop = (el: HTMLElement | null) => {
+    if (el) presence.delete(el);
+  };
+
+  const dropSubtree = (el: HTMLElement) => {
+    for (const descendant of el.querySelectorAll("*")) {
+      if (isHtmlElement(descendant)) presence.delete(descendant);
+    }
+  };
+
+  const ingestOne = (record: MutationRecord): boolean => {
+    // Structural change: order, occurrence indices, labels and child counts all
+    // move at once, and the record names the parent rather than everything
+    // affected. This is the documented full-rebuild fallback.
+    if (record.type === "childList") return false;
+
+    if (record.type === "characterData") {
+      // `buildElementLabel` falls back to `textContent`, so edited text changes
+      // the label of every ancestor that contains it.
+      for (
+        let ancestor = record.target.parentElement;
+        ancestor;
+        ancestor = ancestor.parentElement
+      ) {
+        identities.delete(ancestor);
+      }
+      return true;
+    }
+
+    const target = record.target;
+    if (!isHtmlElement(target)) return true;
+    if (record.attributeName && SELECTOR_IDENTITY_ATTRIBUTES.has(record.attributeName))
+      return false;
+
+    drop(target);
+    // The parent counts its layer children, and this element may have just
+    // joined or left that count.
+    drop(target.parentElement);
+    if (record.attributeName === "style" && inlineVisibilityChanged(target)) dropSubtree(target);
+    return true;
+  };
+
+  return {
+    beginWalk(activeCompositionPath) {
+      const nextScope = `${activeCompositionPath ?? ""}|${getCompositionSourceMapRevision()}`;
+      if (nextScope === scope) return;
+      scope = nextScope;
+      invalidateAll();
+    },
+    readInspectable(el, compute) {
+      const memo = presence.get(el) ?? {};
+      if (memo.inspectable === undefined) {
+        memo.inspectable = compute();
+        presence.set(el, memo);
+      }
+      return memo.inspectable;
+    },
+    readChildCount(el, compute) {
+      const memo = presence.get(el) ?? {};
+      if (memo.childCount === undefined) {
+        memo.childCount = compute();
+        presence.set(el, memo);
+      }
+      return memo.childCount;
+    },
+    readIdentity(el, compute) {
+      const memo = identities.get(el) ?? {};
+      if (memo.identity === undefined) {
+        memo.identity = compute();
+        identities.set(el, memo);
+      }
+      return memo.identity;
+    },
+    readLabel(el, compute) {
+      const memo = identities.get(el) ?? {};
+      if (memo.label === undefined) {
+        memo.label = compute();
+        identities.set(el, memo);
+      }
+      return memo.label;
+    },
+    ingest(records) {
+      for (const record of records) {
+        if (!ingestOne(record)) {
+          invalidateAll();
+          return;
+        }
+      }
+    },
+    invalidateAll,
+  };
+}
+
+/** One element's contribution to a layer walk. `depth` is absent on purpose: it
+ *  belongs to the traversal, not to the element. */
+export interface DomEditLayerWalkEntry {
+  target: DomEditLayerIdentity;
+  label: string;
+  childCount: number;
+}
+
+/**
+ * Everything `collectDomEditLayerItems` needs about ONE element, served from
+ * `cache` where it is still valid. Null when the element is not a layer.
+ *
+ * The four reads go through the cache separately rather than as one record
+ * because they do not go stale together: a style write flips whether an element
+ * renders without touching how it is addressed. Without a cache this is exactly
+ * the original per-element derivation, which is what every other caller of the
+ * walk still gets.
+ *
+ * Lives here rather than in the walk so the two halves of the memoization —
+ * what is stored and what is read — sit in one file.
+ */
+export function readDomEditLayerWalkEntry(
+  el: HTMLElement,
+  activeCompositionPath: string | null,
+  cache?: DomEditLayerWalkCache,
+): DomEditLayerWalkEntry | null {
+  const inspectable = cache
+    ? cache.readInspectable(el, () => isInspectableLayerElement(el))
+    : isInspectableLayerElement(el);
+  if (!inspectable) return null;
+
+  const identity = () => resolveDomLayerIdentity(el, activeCompositionPath);
+  const target = cache ? cache.readIdentity(el, identity) : identity();
+  if (!target) return null;
+
+  const label = () => buildElementLabel(el);
+  const childCount = () => getDirectLayerChildren(el).length;
+  return {
+    target,
+    label: cache ? cache.readLabel(el, label) : label(),
+    childCount: cache ? cache.readChildCount(el, childCount) : childCount(),
+  };
+}
+
+/**
+ * Apply the records the observer has taken in but not yet delivered.
+ *
+ * Records arrive in a microtask, so an edit made earlier in THIS task would
+ * otherwise be read back against entries that predate it. Taking them suppresses
+ * the observer's own callback for them, which is equivalent here: that callback
+ * only ingests and marks a rebuild owed, and a caller draining is rebuilding
+ * regardless. A caller with no observer yet has nothing pending.
+ */
+export function drainPendingLayerMutations(
+  observer: MutationObserver | null,
+  cache: DomEditLayerWalkCache,
+): void {
+  if (!observer) return;
+  cache.ingest(observer.takeRecords());
+}

package/src/components/editor/domEditOverlayBasis.ts

@@ -0,0 +1,72 @@
+/**
+ * The iframe→overlay coordinate basis: everything needed to map a rect measured
+ * inside the preview document into the Studio overlay's own coordinates.
+ *
+ * It is a property of the COMPOSITION and the canvas zoom, not of any element,
+ * so a caller measuring many elements in one synchronous pass resolves it once
+ * and threads it through the geometry functions in `domEditOverlayGeometry`.
+ * Resolved per element it costs a `querySelector("[data-composition-id]")` plus
+ * three layout reads each.
+ *
+ * Its own module because it is the one piece of that file every other piece
+ * depends on and nothing in it is about a single element's geometry.
+ */
+
+/** iframe→overlay mapping basis shared by every overlay-geometry function. */
+export interface OverlayRootScale {
+  iframeRect: DOMRect;
+  overlayRect: DOMRect;
+  rootScaleX: number;
+  rootScaleY: number;
+}
+
+export function readPositiveDimension(value: string | null): number | null {
+  if (!value) return null;
+  const parsed = Number.parseFloat(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+}
+
+/** The composition root element inside the preview doc (or null when absent). */
+function findOverlayRootElement(doc: Document | null): HTMLElement | null {
+  return doc?.querySelector<HTMLElement>("[data-composition-id]") ?? doc?.documentElement ?? null;
+}
+
+/**
+ * The root's effective width/height for scaling: prefer the composition's
+ * declared dimensions (data-width/data-height), which stay fixed while GSAP
+ * transforms mutate the measured rect; fall back to the measured rect. Null when
+ * unmeasurable.
+ */
+function resolveRootDimensions(root: HTMLElement | null): { width: number; height: number } | null {
+  if (!root) return null;
+  const rootRect = root.getBoundingClientRect();
+  const width = readPositiveDimension(root.getAttribute("data-width")) ?? rootRect.width;
+  const height = readPositiveDimension(root.getAttribute("data-height")) ?? rootRect.height;
+  if (!width || !height) return null;
+  return { width, height };
+}
+
+/**
+ * The iframe/overlay client rects and the iframe→root scale factors. Uses the
+ * composition's declared dimensions (data-width/data-height) for the scale
+ * instead of rootRect.width/height: when GSAP applies transforms (scale,
+ * translate) to the root, rootRect dimensions change but the composition's
+ * canonical size stays fixed, and using rootRect misaligns the overlay during
+ * animated playback. Returns null when the geometry is unmeasurable.
+ */
+export function computeOverlayRootScale(
+  overlayEl: HTMLDivElement,
+  iframe: HTMLIFrameElement,
+  doc: Document | null,
+): OverlayRootScale | null {
+  const iframeRect = iframe.getBoundingClientRect();
+  const overlayRect = overlayEl.getBoundingClientRect();
+  const dims = resolveRootDimensions(findOverlayRootElement(doc));
+  if (!dims) return null;
+  return {
+    iframeRect,
+    overlayRect,
+    rootScaleX: iframeRect.width / dims.width,
+    rootScaleY: iframeRect.height / dims.height,
+  };
+}

package/src/components/editor/domEditOverlayGeometry.ts

@@ -1,7 +1,13 @@
 import { type DomEditSelection, findElementForSelection } from "./domEditing";
+import {
+  computeOverlayRootScale,
+  type OverlayRootScale,
+  readPositiveDimension,
+} from "./domEditOverlayBasis";
 import { isElementVisibleThroughAncestors } from "./domEditingDom";
 import { hugRectForElement } from "./domEditOverlayCrop";
 import { composeElementTransform, type PlanarTransformOps } from "./domEditOverlayTransform";
+import { type OverlayMeasurePass, readThroughPass } from "./domEditOverlayMeasurePass";
 
 export interface OverlayRect {
   left: number;
@@ -47,24 +53,28 @@ export function isElementVisibleForOverlay(el: HTMLElement): boolean {
 // shapes (rectangular cards, text, full-bleed media) don't have interior holes, so this
 // doesn't bite. If ring/cutout shapes become editable targets, sample more densely or
 // hit-test against the element's actual painted geometry instead of its bounding box.
-function readPositiveDimension(value: string | null): number | null {
-  if (!value) return null;
-  const parsed = Number.parseFloat(value);
-  return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
-}
-
-function findSourceBoundary(element: HTMLElement): HTMLElement | null {
-  let current: HTMLElement | null = element;
-  while (current) {
-    if (
-      current.hasAttribute("data-composition-file") ||
-      current.hasAttribute("data-composition-src")
-    ) {
-      return current;
+const isSourceBoundary = (node: HTMLElement): boolean =>
+  node.hasAttribute("data-composition-file") || node.hasAttribute("data-composition-src");
+
+/** With a `pass`, every node on the way up is memoized rather than only the
+ *  element asked about: an element's boundary IS its parent's unless it is one
+ *  itself, so siblings share the walk instead of each repeating it. */
+function findSourceBoundary(element: HTMLElement, pass?: OverlayMeasurePass): HTMLElement | null {
+  const pending: HTMLElement[] = [];
+  let boundary: HTMLElement | null | undefined;
+  for (let node: HTMLElement | null = element; node; node = node.parentElement) {
+    boundary = pass?.sourceBoundary.get(node);
+    if (boundary !== undefined) break;
+    if (isSourceBoundary(node)) {
+      boundary = node;
+      pass?.sourceBoundary.set(node, node);
+      break;
     }
-    current = current.parentElement;
+    pending.push(node);
   }
-  return null;
+  const answer = boundary ?? null;
+  if (pass) for (const node of pending) pass.sourceBoundary.set(node, answer);
+  return answer;
 }
 
 export function resolveDomEditCoordinateScale(input: {
@@ -102,8 +112,9 @@ export function toVisibleOverlayRect(
   overlayEl: HTMLDivElement,
   iframe: HTMLIFrameElement,
   element: HTMLElement,
+  precomputedScale?: OverlayRootScale | null,
 ): OverlayRect | null {
-  const rect = toOverlayRect(overlayEl, iframe, element);
+  const rect = toOverlayRect(overlayEl, iframe, element, precomputedScale);
   return rect ? { ...rect, ...hugRectForElement(rect, element) } : null;
 }
 
@@ -157,6 +168,7 @@ interface ElementTransformSnapshot {
 function readElementTransformSnapshot(
   win: Window,
   element: HTMLElement,
+  pass?: OverlayMeasurePass,
 ): ElementTransformSnapshot | null {
   const DOMMatrixCtor = (win as Window & typeof globalThis).DOMMatrix;
   if (!DOMMatrixCtor) return null;
@@ -170,8 +182,11 @@ function readElementTransformSnapshot(
     compose: (outer, inner) => outer.multiply(inner),
   };
   try {
-    const matrix = composeElementTransform(element, ops, (node) =>
-      node === element ? cs : win.getComputedStyle(node),
+    const matrix = composeElementTransform(
+      element,
+      ops,
+      (node) => (node === element ? cs : win.getComputedStyle(node)),
+      pass?.transform,
     );
     return matrix ? { matrix, cs } : null;
   } catch {
@@ -206,64 +221,12 @@ function rotationDegreesFromMatrix(matrix: DOMMatrix): number {
  *  matrix-decomposition floating-point noise, never an actual rotation. */
 const ROTATION_GATE_EPSILON_DEG = 1e-4;
 
-/** iframe→overlay mapping basis shared by every overlay-geometry function. */
-interface OverlayRootScale {
-  iframeRect: DOMRect;
-  overlayRect: DOMRect;
-  rootScaleX: number;
-  rootScaleY: number;
-}
-
-/** The composition root element inside the preview doc (or null when absent). */
-function findOverlayRootElement(doc: Document | null): HTMLElement | null {
-  return doc?.querySelector<HTMLElement>("[data-composition-id]") ?? doc?.documentElement ?? null;
-}
-
-/**
- * The root's effective width/height for scaling: prefer the composition's
- * declared dimensions (data-width/data-height), which stay fixed while GSAP
- * transforms mutate the measured rect; fall back to the measured rect. Null when
- * unmeasurable.
- */
-function resolveRootDimensions(root: HTMLElement | null): { width: number; height: number } | null {
-  if (!root) return null;
-  const rootRect = root.getBoundingClientRect();
-  const width = readPositiveDimension(root.getAttribute("data-width")) ?? rootRect.width;
-  const height = readPositiveDimension(root.getAttribute("data-height")) ?? rootRect.height;
-  if (!width || !height) return null;
-  return { width, height };
-}
-
-/**
- * The iframe/overlay client rects and the iframe→root scale factors. Uses the
- * composition's declared dimensions (data-width/data-height) for the scale
- * instead of rootRect.width/height: when GSAP applies transforms (scale,
- * translate) to the root, rootRect dimensions change but the composition's
- * canonical size stays fixed, and using rootRect misaligns the overlay during
- * animated playback. Returns null when the geometry is unmeasurable.
- */
-function computeOverlayRootScale(
-  overlayEl: HTMLDivElement,
-  iframe: HTMLIFrameElement,
-  doc: Document | null,
-): OverlayRootScale | null {
-  const iframeRect = iframe.getBoundingClientRect();
-  const overlayRect = overlayEl.getBoundingClientRect();
-  const dims = resolveRootDimensions(findOverlayRootElement(doc));
-  if (!dims) return null;
-  return {
-    iframeRect,
-    overlayRect,
-    rootScaleX: iframeRect.width / dims.width,
-    rootScaleY: iframeRect.height / dims.height,
-  };
-}
-
 function toOverlayRect(
   overlayEl: HTMLDivElement,
   iframe: HTMLIFrameElement,
   element: HTMLElement,
   precomputedScale?: OverlayRootScale | null,
+  pass?: OverlayMeasurePass,
 ): OverlayRect | null {
   const scale =
     precomputedScale ?? computeOverlayRootScale(overlayEl, iframe, iframe.contentDocument);
@@ -271,8 +234,15 @@ function toOverlayRect(
   const { iframeRect, overlayRect, rootScaleX, rootScaleY } = scale;
 
   const elementRect = element.getBoundingClientRect();
-  const sourceBoundary = findSourceBoundary(element);
-  const sourceBoundaryRect = sourceBoundary?.getBoundingClientRect();
+  const sourceBoundary = findSourceBoundary(element, pass);
+  // Every element inside one sub-composition shares this boundary, so its rect
+  // is one layout read per boundary rather than one per element.
+  const sourceBoundaryRect =
+    sourceBoundary && pass
+      ? readThroughPass(pass.sourceBoundaryRect, sourceBoundary, () =>
+          sourceBoundary.getBoundingClientRect(),
+        )
+      : sourceBoundary?.getBoundingClientRect();
   const editScale = resolveDomEditCoordinateScale({
     rootScaleX,
     rootScaleY,
@@ -415,14 +385,17 @@ export function orientedOverlayRect(
   overlayEl: HTMLDivElement,
   iframe: HTMLIFrameElement,
   element: HTMLElement,
+  precomputedScale?: OverlayRootScale | null,
+  pass?: OverlayMeasurePass,
 ): OverlayRect | null {
-  const scale = computeOverlayRootScale(overlayEl, iframe, iframe.contentDocument);
+  const scale =
+    precomputedScale ?? computeOverlayRootScale(overlayEl, iframe, iframe.contentDocument);
   if (!scale) return null;
-  const base = toOverlayRect(overlayEl, iframe, element, scale);
+  const base = toOverlayRect(overlayEl, iframe, element, scale, pass);
   if (!base) return null;
 
   const win = iframe.contentWindow;
-  const transform = win ? readElementTransformSnapshot(win, element) : null;
+  const transform = win ? readElementTransformSnapshot(win, element, pass) : null;
   const angle = transform ? rotationDegreesFromMatrix(transform.matrix) : 0;
   if (Math.abs(angle) < ROTATION_GATE_EPSILON_DEG) return base;
 
@@ -460,8 +433,9 @@ export function orientedVisibleOverlayRect(
   overlayEl: HTMLDivElement,
   iframe: HTMLIFrameElement,
   element: HTMLElement,
+  precomputedScale?: OverlayRootScale | null,
 ): OverlayRect | null {
-  const rect = orientedOverlayRect(overlayEl, iframe, element);
+  const rect = orientedOverlayRect(overlayEl, iframe, element, precomputedScale);
   return rect ? { ...rect, ...hugRectForElement(rect, element) } : null;
 }
 
@@ -531,8 +505,10 @@ export function groupAwareOverlayRect(
   overlayEl: HTMLDivElement,
   iframe: HTMLIFrameElement,
   el: HTMLElement,
+  precomputedScale?: OverlayRootScale | null,
+  pass?: OverlayMeasurePass,
 ): OverlayRect | null {
-  const rect = toOverlayRect(overlayEl, iframe, el);
+  const rect = toOverlayRect(overlayEl, iframe, el, precomputedScale, pass);
   if (!rect || !el.hasAttribute("data-hf-group")) return rect;
   // Union the MEMBERS' rendered rects — where the content actually is — not the
   // wrapper's own box. The wrapper is invisible and its box can sit apart from the
@@ -540,7 +516,13 @@ export function groupAwareOverlayRect(
   // group's bounds (and its off-canvas marker) off to a stale position.
   const rects: OverlayRect[] = [];
   for (const child of Array.from(el.children)) {
-    const childRect = toOverlayRect(overlayEl, iframe, child as HTMLElement);
+    const childRect = toOverlayRect(
+      overlayEl,
+      iframe,
+      child as HTMLElement,
+      precomputedScale,
+      pass,
+    );
     if (childRect) rects.push(childRect);
   }
   const union = rects.length > 0 ? resolveDomEditGroupOverlayRect(rects) : null;
@@ -551,15 +533,28 @@ export function groupAwareOverlayRect(
   return { ...union, editScaleX: rect.editScaleX, editScaleY: rect.editScaleY };
 }
 
-/** Groups stay axis-aligned unions; ordinary elements keep their oriented box. */
+/**
+ * Groups stay axis-aligned unions; ordinary elements keep their oriented box.
+ *
+ * `precomputedScale` is the iframe→overlay basis from `computeOverlayRootScale`.
+ * Without it every call resolves the composition root itself — one
+ * `querySelector("[data-composition-id]")` plus three `getBoundingClientRect`
+ * reads PER ELEMENT — and a caller measuring a whole preview therefore pays that
+ * once per element rather than once per composition. The basis is a property of
+ * the composition and the canvas zoom, not of the element, so a caller that
+ * measures many elements in one synchronous pass resolves it once and threads it
+ * through. See `toVisibleOverlayRects` for the same batching in miniature.
+ */
 export function orientedGroupAwareOverlayRect(
   overlayEl: HTMLDivElement,
   iframe: HTMLIFrameElement,
   el: HTMLElement,
+  precomputedScale?: OverlayRootScale | null,
+  pass?: OverlayMeasurePass,
 ): OverlayRect | null {
   return el.hasAttribute("data-hf-group")
-    ? groupAwareOverlayRect(overlayEl, iframe, el)
-    : orientedOverlayRect(overlayEl, iframe, el);
+    ? groupAwareOverlayRect(overlayEl, iframe, el, precomputedScale, pass)
+    : orientedOverlayRect(overlayEl, iframe, el, precomputedScale, pass);
 }
 
 export function filterNestedDomEditGroupItems<T extends { element: HTMLElement }>(items: T[]): T[] {