@hyperframes/studio 0.8.32 → 0.8.34

package/src/components/editor/domEditOverlayMeasurePass.ts

@@ -0,0 +1,60 @@
+/**
+ * Shared memory for ONE synchronous pass that measures many elements.
+ *
+ * The off-canvas indicator overlay re-measures every element in the preview
+ * several times a second, and almost all of that work is per-ANCESTOR, not
+ * per-element: a visibility read for every node up to the root, a transform
+ * composed over the same nodes, and a walk for the source-file boundary. Two
+ * siblings share their entire chain above themselves, so a preview of a
+ * thousand elements asked the platform the same questions about the same
+ * ancestors a thousand times.
+ *
+ * WHY THIS IS A PASS AND NOT A CACHE. A cache has to answer "what could have
+ * changed since last time", and for a MEASUREMENT the honest answer is
+ * "anything": an `<img>` finishing decode, a web font swapping in, a CSS
+ * transition frame, a container query, a `CSSStyleSheet.insertRule` — each one
+ * moves an element's box with nothing written to the DOM, so no mutation
+ * record exists to invalidate on and no observer reports all of them. A pass
+ * sidesteps the question instead of answering it wrong: it lives inside one
+ * synchronous measurement that only READS, so nothing can move under it, and
+ * it is dropped when the pass ends. Every rebuild still measures every
+ * element, exactly as it did before; it just stops asking the same question
+ * about the same ancestor once per descendant.
+ *
+ * Never store one of these across a rebuild, an await, or a frame.
+ */
+
+/** The composed transform type the overlay's corner math uses. */
+type OverlayTransform = DOMMatrix;
+
+export interface OverlayMeasurePass {
+  /** Does this node render, given everything above it? */
+  visible: Map<HTMLElement, boolean>;
+  /** This node's transform composed with every ancestor's, up to the
+   *  composition root. `null` is an answer: some node's transform is
+   *  unusable. */
+  transform: Map<HTMLElement, OverlayTransform | null>;
+  /** The nearest ancestor carrying a source-file boundary, or null. */
+  sourceBoundary: Map<HTMLElement, HTMLElement | null>;
+  /** That boundary's client rect, which is shared by everything inside it. */
+  sourceBoundaryRect: Map<HTMLElement, DOMRect>;
+}
+
+export function createOverlayMeasurePass(): OverlayMeasurePass {
+  return {
+    visible: new Map(),
+    transform: new Map(),
+    sourceBoundary: new Map(),
+    sourceBoundaryRect: new Map(),
+  };
+}
+
+/** Read through a pass's map, filling it on the way. `undefined` is the only
+ *  miss, so a memoized `null` stays an answer. */
+export function readThroughPass<K, V>(memo: Map<K, V>, key: K, compute: () => V): V {
+  const answered = memo.get(key);
+  if (answered !== undefined) return answered;
+  const value = compute();
+  memo.set(key, value);
+  return value;
+}

package/src/components/editor/domEditOverlayTransform.ts

@@ -58,6 +58,22 @@ export function individualRotateDegrees(value: string | undefined): number {
   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.
@@ -66,23 +82,45 @@ export function individualRotateDegrees(value: string | undefined): number {
  * `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 {
-  let acc = ops.identity();
+  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) {
-    const style = getStyle(node);
-    if (!style) return null;
-    const transform = style.transform;
-    let own = transform && transform !== "none" ? ops.fromTransform(transform) : ops.identity();
-    if (!own) return null;
-    const spin = individualRotateDegrees(style.rotate);
-    if (spin !== 0) own = ops.compose(ops.fromRotate(spin), own);
-    acc = ops.compose(own, acc);
+    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;
 }

package/src/components/editor/domEditingDom.ts

@@ -30,23 +30,63 @@ export function isTextBearingTag(tagName: string): boolean {
   return ["div", "span", "p", "strong", "h1", "h2", "h3", "h4", "h5", "h6"].includes(tagName);
 }
 
-export function isElementVisibleThroughAncestors(el: HTMLElement): boolean {
+/** Does this node render AT ALL, ignoring what it inherits? Sole owner of the
+ *  rule; the walk below only decides which nodes to ask it about. */
+function elementRendersItself(win: Window, el: HTMLElement): boolean {
+  const computed = win.getComputedStyle(el);
+  if (computed.display === "none" || computed.visibility === "hidden") return false;
+  const opacity = Number.parseFloat(computed.opacity);
+  return !(
+    Number.isFinite(opacity) &&
+    opacity <= 0.01 &&
+    !el.hasAttribute(COLOR_GRADING_SOURCE_HIDDEN_ATTR)
+  );
+}
+
+/**
+ * Does `el` render, given everything above it?
+ *
+ * `memo` is for a caller asking this about MANY elements in one synchronous
+ * pass. Answers are a function of the node and its ancestors, and siblings
+ * share almost all of their chain, so memoizing per node turns a walk per
+ * element into one style read per node in the tree. It is only ever valid for
+ * the length of one pass — the DOM cannot change under a pass, and every read
+ * here is a read — so the caller creates it and drops it, and nothing survives
+ * to be invalidated. Omitted, every call walks the chain itself.
+ *
+ * The ANSWER is what it always was. Which nodes get a style read is not: this
+ * resolves top-down and stops at the first node that is out, where the previous
+ * version resolved bottom-up and stopped at the first one that is out going the
+ * other way. Same boolean for every input, a different (and, for a subtree
+ * hidden near the root, smaller) set of reads.
+ */
+export function isElementVisibleThroughAncestors(
+  el: HTMLElement,
+  memo?: Map<HTMLElement, boolean>,
+): boolean {
   const win = el.ownerDocument.defaultView;
   if (!win) return true;
-  let current: HTMLElement | null = el;
-  while (current) {
-    const computed = win.getComputedStyle(current);
-    if (computed.display === "none" || computed.visibility === "hidden") return false;
-    const opacity = Number.parseFloat(computed.opacity);
-    if (
-      Number.isFinite(opacity) &&
-      opacity <= 0.01 &&
-      !current.hasAttribute(COLOR_GRADING_SOURCE_HIDDEN_ATTR)
-    )
-      return false;
-    current = current.parentElement;
+  // Up to the first node already answered for, then back down: a node's answer
+  // needs its ancestors' first, and the topmost unanswered node is where the
+  // chain of unknowns starts.
+  const pending: HTMLElement[] = [];
+  let inherited = true;
+  for (let node: HTMLElement | null = el; node; node = node.parentElement) {
+    const answered = memo?.get(node);
+    if (answered !== undefined) {
+      inherited = answered;
+      break;
+    }
+    pending.push(node);
   }
-  return true;
+  for (let i = pending.length - 1; i >= 0; i -= 1) {
+    const node = pending[i]!;
+    // Once an ancestor is out, its descendants are out with it, and asking the
+    // platform about them would be a style read for an answer already known.
+    inherited = inherited && elementRendersItself(win, node);
+    memo?.set(node, inherited);
+  }
+  return inherited;
 }
 
 // ─── Style accessors ──────────────────────────────────────────────────────────
@@ -109,9 +149,18 @@ export function findClosestByAttribute(
 // time, so module scope is the right lifetime; it's empty until set, in which case
 // resolution falls back to the historical attribute-only behavior.
 let compositionSourceMap: Map<string, string> = new Map();
+// Bumped on every replacement so a consumer that memoizes a resolved source file
+// can tell that the map it resolved against is gone. The map is module state
+// with no DOM footprint, so nothing else can observe the change.
+let compositionSourceMapRevision = 0;
 
 export function setCompositionSourceMap(map: Map<string, string>): void {
   compositionSourceMap = map;
+  compositionSourceMapRevision += 1;
+}
+
+export function getCompositionSourceMapRevision(): number {
+  return compositionSourceMapRevision;
 }
 
 function sourceFromCompositionId(ownerRoot: HTMLElement | null): string | undefined {

package/src/components/editor/domEditingElement.ts

@@ -22,8 +22,11 @@ import {
 
 // ─── Visibility ──────────────────────────────────────────────────────────────
 
-export function isElementComputedVisible(el: HTMLElement): boolean {
-  return isElementVisibleThroughAncestors(el);
+export function isElementComputedVisible(
+  el: HTMLElement,
+  memo?: Map<HTMLElement, boolean>,
+): boolean {
+  return isElementVisibleThroughAncestors(el, memo);
 }
 
 const VISUAL_LEAF_TAGS = new Set(["img", "video", "canvas", "svg", "audio"]);
@@ -91,7 +94,13 @@ const DOM_LAYER_IGNORED_TAGS = new Set([
   "wbr",
 ]);
 
-function isInspectableLayerElement(el: HTMLElement): boolean {
+/**
+ * Is the element rendered at all? The half of `getDomLayerPatchTarget` that a
+ * plain style write can flip, and the only half that reads computed style.
+ * Exported so a caller memoizing a layer walk can give it its own (short)
+ * cache lifetime — see `domEditLayerWalkCache`.
+ */
+export function isInspectableLayerElement(el: HTMLElement): boolean {
   const tagName = el.tagName.toLowerCase();
   if (DOM_LAYER_IGNORED_TAGS.has(tagName)) return false;
 
@@ -101,14 +110,29 @@ function isInspectableLayerElement(el: HTMLElement): boolean {
   return true;
 }
 
-export function getDomLayerPatchTarget(
+/**
+ * How the element is ADDRESSED — its selector, that selector's occurrence index
+ * within the source file, and the file itself. Independent of whether the
+ * element currently renders, so it survives every style write and moves only
+ * when an identity attribute changes or the document's population of elements
+ * sharing the selector does.
+ */
+/**
+ * The selector an element is addressed by, or undefined when it cannot be a
+ * layer at all. Sole owner of that rule: `isDomLayerElement` answers the same
+ * question without paying for the occurrence index, and a second copy of the
+ * conditions would go stale the first time one of them changed.
+ */
+function resolveLayerSelector(el: HTMLElement): string | undefined {
+  if (el.hasAttribute("data-composition-id")) return undefined;
+  return buildStableSelector(el);
+}
+
+export function resolveDomLayerIdentity(
   el: HTMLElement,
   activeCompositionPath: string | null,
 ): Pick<DomEditSelection, "id" | "hfId" | "selector" | "selectorIndex" | "sourceFile"> | null {
-  if (!isInspectableLayerElement(el)) return null;
-  if (el.hasAttribute("data-composition-id")) return null;
-
-  const selector = buildStableSelector(el);
+  const selector = resolveLayerSelector(el);
   if (!selector) return null;
 
   const { sourceFile } = getSourceFileForElement(el, activeCompositionPath);
@@ -127,6 +151,26 @@ export function getDomLayerPatchTarget(
   };
 }
 
+export function getDomLayerPatchTarget(
+  el: HTMLElement,
+  activeCompositionPath: string | null,
+): Pick<DomEditSelection, "id" | "hfId" | "selector" | "selectorIndex" | "sourceFile"> | null {
+  return isInspectableLayerElement(el) ? resolveDomLayerIdentity(el, activeCompositionPath) : null;
+}
+
+/**
+ * Is `el` a layer at all? Exactly the condition under which
+ * `getDomLayerPatchTarget` returns non-null, for callers that want the yes/no
+ * and throw the target away.
+ *
+ * Worth its own function because the target carries the selector's OCCURRENCE
+ * INDEX, and resolving that is a whole-document query — which the yes/no does
+ * not depend on. Counting an element's layer children asked for one per child.
+ */
+export function isDomLayerElement(el: HTMLElement): boolean {
+  return isInspectableLayerElement(el) && resolveLayerSelector(el) !== undefined;
+}
+
 // ─── Clip ancestor / selection candidate ─────────────────────────────────────
 
 function getPreferredClipAncestor(startEl: HTMLElement): HTMLElement | null {
@@ -323,12 +367,10 @@ export function findElementForTimelineElement(
 
 // ─── Layer children ───────────────────────────────────────────────────────────
 
-export function getDirectLayerChildren(
-  el: HTMLElement,
-  options: DomEditContextOptions,
-): HTMLElement[] {
+/** `el`'s direct children that are layers. No longer takes the context options:
+ *  layer-ness does not depend on the active composition path. */
+export function getDirectLayerChildren(el: HTMLElement): HTMLElement[] {
   return Array.from(el.children).filter(
-    (child): child is HTMLElement =>
-      isHtmlElement(child) && getDomLayerPatchTarget(child, options.activeCompositionPath) !== null,
+    (child): child is HTMLElement => isHtmlElement(child) && isDomLayerElement(child),
   );
 }

package/src/components/editor/domEditingLayers.test.ts

@@ -257,3 +257,51 @@ describe("collectDomEditLayerItems item budget", () => {
     expect(collectDomEditLayerItems(documentWith(200), opts, 80)).toHaveLength(80);
   });
 });
+
+describe("collectDomEditLayerItems selector-index cost", () => {
+  // Attached, unlike the fixture above: a detached subtree is invisible to
+  // document.querySelectorAll, so the occurrence lookup would find nothing.
+  function attachedRootWithSharedClass(count: number): HTMLElement {
+    const root = document.createElement("div");
+    root.setAttribute("data-composition-id", "index.html");
+    for (let i = 0; i < count; i++) {
+      const child = document.createElement("div");
+      child.className = "box";
+      root.append(child);
+    }
+    document.body.append(root);
+    return root;
+  }
+
+  /** Class-selector document queries made by one walk over `count` sibling cards. */
+  function classSelectorQueries(count: number): number {
+    const root = attachedRootWithSharedClass(count);
+    const doc = root.ownerDocument;
+    const real = doc.querySelectorAll.bind(doc);
+    let calls = 0;
+    Object.defineProperty(doc, "querySelectorAll", {
+      configurable: true,
+      value: (selector: string) => {
+        if (selector.startsWith(".")) calls += 1;
+        return real(selector);
+      },
+    });
+    try {
+      expect(collectDomEditLayerItems(root, opts)).toHaveLength(count);
+      return calls;
+    } finally {
+      delete (doc as Partial<Document>).querySelectorAll;
+      root.remove();
+    }
+  }
+
+  // The occurrence index is resolved here, for every item, so an unshared index
+  // costs one whole-document query per element — quadratic once a composition
+  // repeats a card or tile class. Owning the pass here rather than at each call
+  // site is what keeps the layers panel, the marquee and the agent's look tool
+  // linear too; invariance across a 4x fixture fails for any per-element term.
+  it("resolves a shared selector once per walk, not once per element", () => {
+    expect(classSelectorQueries(48)).toBe(classSelectorQueries(12));
+    expect(classSelectorQueries(12)).toBe(1);
+  });
+});

package/src/components/editor/domEditingLayers.ts

@@ -1,3 +1,4 @@
+import { probeSourceElement } from "./probeSourceElement";
 import type { PatchOperation } from "../../utils/sourcePatcher";
 import {
   resolveEditingAffordances,
@@ -26,11 +27,12 @@ import {
 } from "./domEditingDom";
 import {
   findElementForSelection,
-  getDomLayerPatchTarget,
-  getDirectLayerChildren,
   getSelectionCandidate,
+  isDomLayerElement,
 } from "./domEditingElement";
 import { isCompositionRootLayer } from "./domEditingRootLayer";
+import { withSelectorIndexPass } from "../../utils/sourceScopedSelectorIndex";
+import { type DomEditLayerWalkCache, readDomEditLayerWalkEntry } from "./domEditLayerWalkCache";
 
 export function isEditableTextLeaf(el: HTMLElement): boolean {
   return isTextBearingTag(el.tagName.toLowerCase()) && el.children.length === 0;
@@ -281,31 +283,6 @@ export function resolveDomEditCapabilities(args: {
   ).capabilities;
 }
 
-async function probeSourceElement(
-  projectId: string,
-  sourceFile: string,
-  target: { id?: string; hfId?: string; selector?: string; selectorIndex?: number },
-): Promise<boolean> {
-  try {
-    const response = await fetch(
-      `/api/projects/${projectId}/file-mutations/probe-element/${encodeURIComponent(sourceFile)}`,
-      {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ target }),
-      },
-    );
-    if (!response.ok) return true;
-    const data = await response.json();
-    if (data && typeof data === "object" && "exists" in data && data.exists === false) {
-      return false;
-    }
-    return true;
-  } catch {
-    return true;
-  }
-}
-
 // fallow-ignore-next-line complexity
 export async function resolveDomEditSelection(
   startEl: HTMLElement | null,
@@ -445,7 +422,7 @@ export function countDomEditChildLayers(
   const visit = (el: HTMLElement) => {
     for (const child of Array.from(el.children)) {
       if (!isHtmlElement(child)) continue;
-      if (getDomLayerPatchTarget(child, options.activeCompositionPath)) {
+      if (isDomLayerElement(child)) {
         count += 1;
         if (count >= maxCount) return;
       }
@@ -466,23 +443,26 @@ export function collectDomEditLayerItems(
   root: HTMLElement | null | undefined,
   options: DomEditContextOptions,
   maxItems = Number.POSITIVE_INFINITY,
+  cache?: DomEditLayerWalkCache,
 ): DomEditLayerItem[] {
   if (!root) return [];
+  cache?.beginWalk(options.activeCompositionPath);
 
   const items: DomEditLayerItem[] = [];
   // fallow-ignore-next-line complexity
   const visit = (el: HTMLElement, depth: number) => {
     if (items.length >= maxItems) return;
 
-    const target = getDomLayerPatchTarget(el, options.activeCompositionPath);
-    if (target) {
+    const entry = readDomEditLayerWalkEntry(el, options.activeCompositionPath, cache);
+    if (entry) {
+      const { target } = entry;
       items.push({
         key: getDomEditLayerKey(target),
         element: el,
-        label: buildElementLabel(el),
+        label: entry.label,
         tagName: el.tagName.toLowerCase(),
         depth,
-        childCount: getDirectLayerChildren(el, options).length,
+        childCount: entry.childCount,
         id: target.id ?? undefined,
         hfId: target.hfId ?? undefined,
         selector: target.selector ?? undefined,
@@ -491,7 +471,7 @@ export function collectDomEditLayerItems(
       });
     }
 
-    const nextDepth = target ? depth + 1 : depth;
+    const nextDepth = entry ? depth + 1 : depth;
     for (const child of Array.from(el.children)) {
       if (!isHtmlElement(child)) continue;
       visit(child, nextDepth);
@@ -499,8 +479,15 @@ export function collectDomEditLayerItems(
     }
   };
 
-  // Drilled into a group → show only its members; otherwise the whole tree.
-  for (const el of groupScopedLayerRoots(root, options.activeGroupElement ?? null)) visit(el, 0);
+  // Every item resolves its selector's occurrence index, and unshared that is a
+  // whole-document query per element — quadratic once a composition repeats a
+  // card or tile class. The walk is one synchronous read of a document it does
+  // not mutate, so one index per selector serves the whole of it. The pass lives
+  // here rather than in each caller because this function owns the loop.
+  withSelectorIndexPass(root.ownerDocument, () => {
+    // Drilled into a group → show only its members; otherwise the whole tree.
+    for (const el of groupScopedLayerRoots(root, options.activeGroupElement ?? null)) visit(el, 0);
+  });
   return items;
 }