@hyperframes/studio 0.8.33 → 0.8.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.33",
+  "version": "0.8.34",
   "description": "",
   "repository": {
     "type": "git",
@@ -48,11 +48,11 @@
     "gsap": "^3.13.0",
     "marked": "^14.1.4",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.33",
-    "@hyperframes/player": "0.8.33",
-    "@hyperframes/parsers": "0.8.33",
-    "@hyperframes/sdk": "0.8.33",
-    "@hyperframes/studio-server": "0.8.33"
+    "@hyperframes/core": "0.8.34",
+    "@hyperframes/parsers": "0.8.34",
+    "@hyperframes/player": "0.8.34",
+    "@hyperframes/sdk": "0.8.34",
+    "@hyperframes/studio-server": "0.8.34"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -67,9 +67,9 @@
     "tsup": "^8.0.0",
     "typescript": "^5.0.0",
     "vite": "^6.4.2",
-    "vitest": "^3.2.4",
+    "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.33"
+    "@hyperframes/producer": "0.8.34"
   },
   "peerDependencies": {
     "react": "19",

package/src/App.tsx

@@ -1,3 +1,4 @@
+import { buildProjectApiPath } from "./utils/projectRouting";
 import { useState, useCallback, useRef, useMemo, useLayoutEffect } from "react";
 import type { LeftSidebarHandle, SidebarTab } from "./components/sidebar/LeftSidebar";
 import { useRenderQueue } from "./components/renders/useRenderQueue";
@@ -326,12 +327,13 @@ export function StudioApp() {
   const renderClipContent = useRenderClipContent({
     projectIdRef: fileManager.projectIdRef,
     compIdToSrc,
-    activePreviewUrl: activeCompPath
-      ? `/api/projects/${projectId}/preview/comp/${activeCompPath}`
-      : null,
+    activePreviewUrl:
+      activeCompPath && projectId
+        ? buildProjectApiPath(projectId, `/preview/comp/${activeCompPath}`)
+        : null,
     effectiveTimelineDuration,
   });
-  const compositionDimensions = useCompositionDimensions();
+  const compositionDimensions = useCompositionDimensions(previewIframeRef);
   const { lintModal, linting, handleLint, closeLintModal, findingsByFile } = useLintModal(
     projectId,
     refreshKey,

package/src/captions/components/CaptionOverlay.sender.test.tsx

@@ -0,0 +1,47 @@
+// @vitest-environment jsdom
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { expect, it, vi } from "vitest";
+import { CaptionOverlay } from "./CaptionOverlay";
+import { useCaptionStore } from "../store";
+
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+
+it("only schedules caption layout for messages from its preview", () => {
+  const host = document.createElement("div");
+  const preview = document.createElement("iframe");
+  const foreign = document.createElement("iframe");
+  document.body.append(host, preview, foreign);
+  const root = createRoot(host);
+  const schedule = vi.fn(() => 1);
+  vi.stubGlobal("requestAnimationFrame", schedule);
+  vi.stubGlobal("cancelAnimationFrame", vi.fn());
+  vi.stubGlobal(
+    "ResizeObserver",
+    class {
+      observe() {}
+      disconnect() {}
+    },
+  );
+  useCaptionStore.getState().setEditMode(true);
+  const send = (source: MessageEventSource | null) =>
+    act(() => {
+      window.dispatchEvent(new MessageEvent("message", { source, data: { source: "hf-preview" } }));
+    });
+  try {
+    act(() => root.render(<CaptionOverlay iframeRef={{ current: preview }} />));
+    schedule.mockClear();
+    send(foreign.contentWindow);
+    send(null);
+    expect(schedule).not.toHaveBeenCalled();
+    send(preview.contentWindow);
+    expect(schedule).toHaveBeenCalledOnce();
+  } finally {
+    act(() => root.unmount());
+    useCaptionStore.getState().reset();
+    host.remove();
+    preview.remove();
+    foreign.remove();
+    vi.unstubAllGlobals();
+  }
+});

package/src/captions/components/CaptionOverlay.tsx

@@ -116,6 +116,7 @@ export const CaptionOverlay = memo(function CaptionOverlay({ iframeRef }: Captio
     // messages, element resize, window resize.
     const unsubPlayer = usePlayerStore.subscribe(scheduleTick);
     const handleMessage = (e: MessageEvent) => {
+      if (!e.source || e.source !== iframeRef.current?.contentWindow) return;
       const data = e.data;
       if (data?.source === "hf-preview") scheduleTick();
     };

package/src/captions/generator.test.ts

@@ -1,5 +1,6 @@
 // @vitest-environment node
 import { describe, it, expect } from "vitest";
+import { Window } from "happy-dom";
 import { generateCaptionHtml } from "./generator";
 import { buildCaptionModel, TranscriptWord } from "./parser";
 
@@ -31,6 +32,35 @@ function buildTestModel(wordsPerGroup = 5) {
 // ---------------------------------------------------------------------------
 
 describe("generateCaptionHtml", () => {
+  it("keeps script-closing text and word IDs as data when HTML is parsed", () => {
+    const text = '</ScRiPt><img src=x onerror="alert(1)"><!-- <script> & end';
+    const id = '</script><svg onload="alert(2)">';
+    const model = buildCaptionModel([{ text, id, start: 0, end: 1 }], {
+      width: 1920,
+      height: 1080,
+      duration: 2,
+      wordsPerGroup: 5,
+    });
+    const window = new Window();
+    const template = window.document.createElement("template");
+    template.innerHTML = generateCaptionHtml(model);
+    const nested = template.content.querySelector("template");
+    expect(nested).not.toBeNull();
+    const content = nested!.content;
+    expect(content.querySelector("img, svg")).toBeNull();
+    const scripts = content.querySelectorAll("script");
+    expect(scripts).toHaveLength(1);
+    const script = scripts[0].textContent;
+    const transcript = script.match(/const TRANSCRIPT = ([\s\S]*?);/);
+    expect(transcript).not.toBeNull();
+    expect(JSON.parse(transcript![1])).toEqual([{ text, id, start: 0, end: 1 }]);
+    const wordText = script.match(/\.textContent = (.*);/);
+    const wordId = script.match(/\.id = (.*);/);
+    expect(JSON.parse(wordText![1])).toBe(text);
+    expect(JSON.parse(wordId![1])).toBe(id);
+    window.close();
+  });
+
   describe("HTML structure", () => {
     it("wraps output in a <template id='captions-template'>", () => {
       const model = buildTestModel();

package/src/captions/generator.ts

@@ -277,7 +277,7 @@ function generateJs(model: CaptionModel): string {
     }
   }
 
-  const transcriptJson = JSON.stringify(allSegments, null, 2);
+  const transcriptJson = JSON.stringify(allSegments, null, 2).replace(/</g, "\\u003c");
 
   const groupBlocks: string[] = [];
 
@@ -303,9 +303,11 @@ function generateJs(model: CaptionModel): string {
 
     // Build word spans
     const wordLines: string[] = groupSegments.map((seg) => {
-      const escaped = JSON.stringify(seg.text);
+      const escaped = JSON.stringify(seg.text).replace(/</g, "\\u003c");
       const segVar = `w_${seg.id.replace(/[^a-zA-Z0-9_]/g, "_")}`;
-      const idLine = seg.wordId ? `\n  ${segVar}.id = ${JSON.stringify(seg.wordId)};` : "";
+      const idLine = seg.wordId
+        ? `\n  ${segVar}.id = ${JSON.stringify(seg.wordId).replace(/</g, "\\u003c")};`
+        : "";
       return (
         `  const ${segVar} = document.createElement('span');` +
         `\n  ${segVar}.className = 'word clip';` +

package/src/captions/hooks/useCaptionSync.ts

@@ -1,3 +1,4 @@
+import { buildProjectApiPath } from "../../utils/projectRouting";
 import { useCallback, useRef } from "react";
 import { useCaptionStore } from "../store";
 import { useMountEffect } from "../../hooks/useMountEffect";
@@ -92,7 +93,7 @@ export function useCaptionSync(projectId: string | null) {
     const seqAtSave = editSeqRef.current;
     const overrides = buildOverrides(state.model);
 
-    fetch(`/api/projects/${pid}/files/${encodeURIComponent("caption-overrides.json")}`, {
+    fetch(buildProjectApiPath(pid, `/files/${encodeURIComponent("caption-overrides.json")}`), {
       method: "PUT",
       headers: { "Content-Type": "text/plain", ...studioWriteHeaders() },
       body: JSON.stringify(overrides, null, 2),
@@ -171,7 +172,7 @@ export function useCaptionSync(projectId: string | null) {
     let data: { content?: string };
     try {
       const res = await fetch(
-        `/api/projects/${pid}/files/${encodeURIComponent("caption-overrides.json")}`,
+        buildProjectApiPath(pid, `/files/${encodeURIComponent("caption-overrides.json")}`),
       );
       if (!res.ok) return; // no overrides file yet — normal
       data = await res.json();

package/src/components/MediaPreview.tsx

@@ -1,3 +1,4 @@
+import { buildProjectApiPath } from "../utils/projectRouting";
 import { useState } from "react";
 import { IMAGE_EXT, VIDEO_EXT, AUDIO_EXT } from "../utils/mediaTypes";
 
@@ -28,7 +29,7 @@ function MediaErrorPanel({ name, filePath }: { name: string; filePath: string })
 }
 
 export function MediaPreview({ projectId, filePath }: { projectId: string; filePath: string }) {
-  const serveUrl = `/api/projects/${projectId}/preview/${filePath}`;
+  const serveUrl = buildProjectApiPath(projectId, `/preview/${filePath}`);
   const name = filePath.split("/").pop() ?? filePath;
   // Keyed by path so switching to another file clears a previous failure.
   const [failedPath, setFailedPath] = useState<string | null>(null);

package/src/components/editor/AnimationCard.test.tsx

@@ -3,7 +3,7 @@
 import React, { act } from "react";
 import { createRoot } from "react-dom/client";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, describe, expect, it, vi, type Mock } from "vitest";
 import { AnimationCard } from "./AnimationCard";
 import { EASE_PRESETS } from "./easePresetLibrary";
 import type { AnimationKeyframeTarget } from "../../hooks/gsapTweenSynth";
@@ -118,8 +118,8 @@ function renderCard({
   animation?: GsapAnimation;
   defaultExpanded?: boolean;
   flat?: boolean;
-  onUpdateMeta?: ReturnType<typeof vi.fn>;
-  onUpdateKeyframeEase?: ReturnType<typeof vi.fn>;
+  onUpdateMeta?: Mock;
+  onUpdateKeyframeEase?: Mock;
   onDeleteAnimation?: (id: string) => void;
 } = {}) {
   const host = document.createElement("div");

package/src/components/editor/PropertyPanel.test.tsx

@@ -1001,20 +1001,24 @@ describe("PropertyPanel — Motion is for things that move", () => {
         return element;
       },
     ],
-  ])("recognizes %s through the shared audio predicate", async (_label, makeElement) => {
-    const fixture = {
-      ...audioClipElement(),
-      element: makeElement(),
-      tagName: "div",
-    };
-    const { host, root } = await renderPanel(true, fixture);
-    const titles = Array.from(
-      host.querySelectorAll<HTMLElement>("[data-flat-group-collapsed], [data-flat-group-open]"),
-    ).map((node) => node.textContent ?? "");
-    expect(titles.some((title) => title.includes("Motion"))).toBe(false);
-    expect(titles.some((title) => title.includes("Timing"))).toBe(true);
-    act(() => root.unmount());
-  });
+  ])(
+    "recognizes %s through the shared audio predicate",
+    async (_label, makeElement) => {
+      const fixture = {
+        ...audioClipElement(),
+        element: makeElement(),
+        tagName: "div",
+      };
+      const { host, root } = await renderPanel(true, fixture);
+      const titles = Array.from(
+        host.querySelectorAll<HTMLElement>("[data-flat-group-collapsed], [data-flat-group-open]"),
+      ).map((node) => node.textContent ?? "");
+      expect(titles.some((title) => title.includes("Motion"))).toBe(false);
+      expect(titles.some((title) => title.includes("Timing"))).toBe(true);
+      act(() => root.unmount());
+    },
+    RENDER_TIMEOUT_MS,
+  );
 
   it(
     "calls the section Timing on an audio clip, and offers no tween editor",

package/src/components/editor/SnapGuideOverlay.tsx

@@ -1,6 +1,7 @@
 import { memo, useRef, type RefObject } from "react";
 import { useMountEffect } from "../../hooks/useMountEffect";
 import { resolveGuideLineRect, type SnapGuide, type SpacingGuide } from "./snapEngine";
+import { subscribeOverlayFrame } from "./overlayFrameLoop";
 
 export interface SnapGuidesState {
   guides: SnapGuide[];
@@ -47,12 +48,8 @@ export const SnapGuideOverlay = memo(function SnapGuideOverlay({
   };
 
   useMountEffect(() => {
-    let frame = 0;
-
     // fallow-ignore-next-line complexity
     const update = () => {
-      frame = requestAnimationFrame(update);
-
       const state = snapGuidesRef.current;
       const guides = state?.guides ?? [];
       const spacingGuides = state?.spacingGuides ?? [];
@@ -116,8 +113,7 @@ export const SnapGuideOverlay = memo(function SnapGuideOverlay({
       }
     };
 
-    frame = requestAnimationFrame(update);
-    return () => cancelAnimationFrame(frame);
+    return subscribeOverlayFrame(update);
   });
 
   return (

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

@@ -0,0 +1,284 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  DOM_EDIT_LAYER_OBSERVER_INIT,
+  type DomEditLayerWalkCache,
+  createDomEditLayerWalkCache,
+  drainPendingLayerMutations,
+} from "./domEditLayerWalkCache";
+import { collectDomEditLayerItems } from "./domEditingLayers";
+import type { DomEditLayerItem } from "./domEditingTypes";
+
+const opts = { activeCompositionPath: "index.html", isMasterView: true };
+
+/** Attached, not detached: the occurrence index is resolved with a whole-document
+ *  query, so a detached fixture would number every element as a miss. */
+function mountPreview(cardCount: number): HTMLElement {
+  const cards = Array.from(
+    { length: cardCount },
+    (_unused, i) =>
+      `<div class="box"><span class="label">card ${i}</span><b class="tag">t${i}</b></div>`,
+  ).join("");
+  document.body.innerHTML = `<div data-composition-id="index.html">${cards}</div>`;
+  return document.body.firstElementChild as HTMLElement;
+}
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+/** Everything a caller can observe about a walk. Compared field by field so a
+ *  divergence names itself instead of failing on object identity. */
+function shape(items: DomEditLayerItem[]): unknown {
+  return items.map((item) => ({
+    key: item.key,
+    label: item.label,
+    tagName: item.tagName,
+    depth: item.depth,
+    childCount: item.childCount,
+    id: item.id,
+    hfId: item.hfId,
+    selector: item.selector,
+    selectorIndex: item.selectorIndex,
+    sourceFile: item.sourceFile,
+    element: item.element,
+  }));
+}
+
+/**
+ * Count `getComputedStyle` calls, which is the per-element cost this cache
+ * exists to avoid: `isInspectableLayerElement` makes one for the element and
+ * `getDirectLayerChildren` one more for each direct child. A count that does not
+ * grow with the document is the whole claim.
+ */
+function countingComputedStyle(): { calls: () => number; restore: () => void } {
+  const real = window.getComputedStyle.bind(window);
+  let calls = 0;
+  window.getComputedStyle = ((el: Element, pseudo?: string | null) => {
+    calls += 1;
+    return real(el, pseudo ?? undefined);
+  }) as typeof window.getComputedStyle;
+  return { calls: () => calls, restore: () => (window.getComputedStyle = real) };
+}
+
+interface WarmWalk {
+  root: HTMLElement;
+  cache: DomEditLayerWalkCache;
+  observer: MutationObserver;
+}
+
+/**
+ * A mounted preview whose cache has already done one full walk, with the
+ * observer live. Every test here needs exactly this before it can measure what
+ * a SECOND walk costs, so it lives in one place.
+ */
+function withWarmWalk<T>(cardCount: number, run: (ctx: WarmWalk) => T): T {
+  const root = mountPreview(cardCount);
+  const cache = createDomEditLayerWalkCache();
+  const observer = new MutationObserver(() => {});
+  observer.observe(document.documentElement, DOM_EDIT_LAYER_OBSERVER_INIT);
+  try {
+    collectDomEditLayerItems(root, opts, undefined, cache);
+    return run({ root, cache, observer });
+  } finally {
+    observer.disconnect();
+  }
+}
+
+describe("collectDomEditLayerItems incremental rebuild", () => {
+  /**
+   * The load-bearing assertion, and it is INVARIANCE, not a threshold: a
+   * threshold ("under 20 style reads") passes on a small fixture and still
+   * degrades linearly on a real preview. Quadrupling the card count must not
+   * change what one style edit costs at all.
+   *
+   * Before the cache both numbers tracked the document size (every element and
+   * every direct child re-derived on every mutation, whatever the mutation was).
+   */
+  function styleEditRebuildCost(cardCount: number): number {
+    return withWarmWalk(cardCount, ({ root, cache, observer }) => {
+      // What animation writes on a frame: one element's transform, nothing that
+      // can change any element's selector, membership or label.
+      root.querySelector<HTMLElement>(".box")!.style.transform = "translateX(4px)";
+      cache.ingest(observer.takeRecords());
+
+      const probe = countingComputedStyle();
+      try {
+        collectDomEditLayerItems(root, opts, undefined, cache);
+        return probe.calls();
+      } finally {
+        probe.restore();
+      }
+    });
+  }
+
+  it("costs the same for one style edit at n cards and at 4n", () => {
+    const small = styleEditRebuildCost(12);
+    const large = styleEditRebuildCost(48);
+
+    expect(large).toBe(small);
+    // A ceiling as well, so a future change that reintroduces a per-element term
+    // fails here even if it happens to be document-size-flat. The edited element,
+    // its parent, and each of their direct children is the whole budget.
+    expect(small).toBeLessThanOrEqual(12);
+  });
+
+  it("performs no document query at all for an edit that touches no selector", () => {
+    withWarmWalk(12, ({ root, cache, observer }) => {
+      root.querySelector<HTMLElement>(".tag")!.style.opacity = "0.5";
+      cache.ingest(observer.takeRecords());
+
+      const real = document.querySelectorAll.bind(document);
+      let queries = 0;
+      Object.defineProperty(document, "querySelectorAll", {
+        configurable: true,
+        value: (selector: string) => {
+          queries += 1;
+          return real(selector);
+        },
+      });
+      try {
+        collectDomEditLayerItems(root, opts, undefined, cache);
+      } finally {
+        delete (document as Partial<Document>).querySelectorAll;
+      }
+      // The only document query in the walk resolves a selector's occurrence
+      // index, and no cached selector was invalidated.
+      expect(queries).toBe(0);
+    });
+  });
+
+  /**
+   * The equivalence half, and the one that would catch a wrong optimisation
+   * rather than a missing one. Every mutation KIND the invalidation reasons
+   * about is applied in turn, and after each the incremental walk must equal a
+   * walk with no cache at all — which is what every other caller still gets.
+   */
+  it("matches an uncached walk after every kind of mutation it reasons about", () => {
+    const root = mountPreview(6);
+    const cache = createDomEditLayerWalkCache();
+    const observer = new MutationObserver(() => {});
+    observer.observe(document.documentElement, DOM_EDIT_LAYER_OBSERVER_INIT);
+    // Captured up front: later cases change class and id, so re-querying `.box`
+    // would hand the next case a different element than it names.
+    const cards = Array.from(root.querySelectorAll<HTMLElement>(".box"));
+    const box = (i: number) => cards[i]!;
+
+    const mutations: Array<[string, () => void]> = [
+      ["a style write that cannot change membership", () => (box(0).style.opacity = "0.5")],
+      // Inherited: the subtree's computed visibility moves with it.
+      ["a style write that hides a subtree", () => (box(1).style.visibility = "hidden")],
+      ["clearing that same subtree hide", () => (box(1).style.visibility = "")],
+      // display:none removes the element from the list and shifts its
+      // descendants' depth by one, without touching their own computed display.
+      ["display:none on a card", () => (box(2).style.display = "none")],
+      // Renumbers `.box` for every card after it, and relabels this one.
+      ["a class change that renumbers a shared selector", () => (box(3).className = "crate")],
+      ["an id, which outranks the class selector", () => (box(4).id = "hero")],
+      ["edited text, which is a label input", () => (box(5).firstChild!.textContent = "renamed")],
+      // The unattributable case: the documented full-rebuild fallback.
+      ["a node inserted mid-document", () => box(0).append(document.createElement("i"))],
+      ["a node removed", () => box(0).querySelector("b")!.remove()],
+      ["a data attribute nothing derives from", () => box(0).setAttribute("data-x", "1")],
+    ];
+
+    try {
+      collectDomEditLayerItems(root, opts, undefined, cache);
+      for (const [what, mutate] of mutations) {
+        mutate();
+        cache.ingest(observer.takeRecords());
+        expect(
+          shape(collectDomEditLayerItems(root, opts, undefined, cache)),
+          `incremental walk diverged after ${what}`,
+        ).toEqual(shape(collectDomEditLayerItems(root, opts)));
+      }
+    } finally {
+      observer.disconnect();
+    }
+  });
+
+  /**
+   * The subtree drop is the one expensive branch in the ingest path, and it runs
+   * in the raw observer callback — not behind the rebuild throttle. GSAP's
+   * `autoAlpha` writes `visibility: visible` into inline style ONCE on fade-in
+   * and leaves it there, so a rule that fires whenever the style attribute
+   * mentions visibility fires on every transform tick for the rest of the clip:
+   * a whole-subtree walk per animation frame, for the exact elements a
+   * composition animates most.
+   */
+  it("does not re-walk a subtree when a faded-in element merely animates", () => {
+    const root = mountPreview(6);
+    const cache = createDomEditLayerWalkCache();
+    const observer = new MutationObserver(() => {});
+    observer.observe(document.documentElement, DOM_EDIT_LAYER_OBSERVER_INIT);
+    const card = root.querySelector<HTMLElement>(".box")!;
+    try {
+      collectDomEditLayerItems(root, opts, undefined, cache);
+      // The fade-in itself. This one legitimately invalidates the subtree.
+      card.style.visibility = "visible";
+      cache.ingest(observer.takeRecords());
+
+      let subtreeWalks = 0;
+      const real = Element.prototype.querySelectorAll;
+      Element.prototype.querySelectorAll = function (this: Element, selector: string) {
+        if (selector === "*") subtreeWalks += 1;
+        return real.call(this, selector);
+      } as typeof Element.prototype.querySelectorAll;
+      try {
+        // Ordinary animation frames. `visibility: visible` is still sitting in
+        // the attribute, but the value has not moved.
+        card.style.transform = "translateX(1px)";
+        cache.ingest(observer.takeRecords());
+        card.style.transform = "translateX(2px)";
+        cache.ingest(observer.takeRecords());
+      } finally {
+        Element.prototype.querySelectorAll = real;
+      }
+
+      expect(subtreeWalks).toBe(0);
+    } finally {
+      observer.disconnect();
+    }
+  });
+
+  it("drops everything when the walk is re-scoped to a different composition", () => {
+    const root = mountPreview(3);
+    const cache = createDomEditLayerWalkCache();
+    collectDomEditLayerItems(root, opts, undefined, cache);
+
+    const rescoped = { ...opts, activeCompositionPath: "scenes/two.html" };
+    expect(shape(collectDomEditLayerItems(root, rescoped, undefined, cache))).toEqual(
+      shape(collectDomEditLayerItems(root, rescoped)),
+    );
+  });
+});
+
+describe("drainPendingLayerMutations", () => {
+  it("applies records the observer has not delivered yet", () => {
+    withWarmWalk(6, ({ root, cache, observer }) => {
+      const card = root.querySelector<HTMLElement>(".box")!;
+      // Not delivered: the callback runs in a microtask, and this test never
+      // yields to one.
+      card.id = "renamed";
+
+      drainPendingLayerMutations(observer, cache);
+
+      // An identity attribute drops the whole cache, so the walk after the drain
+      // must agree with an uncached walk.
+      expect(shape(collectDomEditLayerItems(root, opts, undefined, cache))).toEqual(
+        shape(collectDomEditLayerItems(root, opts)),
+      );
+      // And the records really were consumed by the drain, not still queued.
+      expect(observer.takeRecords()).toHaveLength(0);
+    });
+  });
+
+  it("is a no-op when no observer is attached yet", () => {
+    withWarmWalk(6, ({ root, cache }) => {
+      expect(() => drainPendingLayerMutations(null, cache)).not.toThrow();
+      expect(collectDomEditLayerItems(root, opts, undefined, cache)).toHaveLength(
+        collectDomEditLayerItems(root, opts).length,
+      );
+    });
+  });
+});