@hyperframes/studio 0.8.114 → 0.8.116

package/src/utils/gsapUndoRestore.browser.test.ts

@@ -43,54 +43,60 @@ beforeAll(async () => {
 
 afterAll(() => browser?.close());
 
+// The first case opens the cold browser's first page, which overran 5 s on a loaded CI runner.
 it.each([
   { gsap: "hold", placement: "px", rotation: 0 },
   { gsap: "tween", placement: "px", rotation: 0 },
   { gsap: "tween", placement: "xpercent", rotation: 30 },
-])("an undone crop leaves a $gsap $placement r$rotation layer where it was", async (spec) => {
-  const dir = join(mkdtempSync(join(tmpdir(), "undo-gsap-")), "case");
-  writeFixture({ gesture: "crop", nesting: "root", zoom: 100, ...spec }, dir);
-  const restored = readFileSync(join(dir, "index.html"), "utf8");
-  const previous = restored.replace(
-    `<div id="target"`,
-    `<div id="target" style="clip-path: ${CROP}"`,
-  );
-  const page = await browser.newPage();
-  await page.setViewport({ width: 1920, height: 1080 });
-  await page.setRequestInterception(true);
-  page.on("request", (request) =>
-    request.url().endsWith("/gsap.min.js")
-      ? request.respond({ body: readFileSync(require.resolve("gsap/dist/gsap.min.js"), "utf8") })
-      : request.continue(),
-  );
-  await page.setContent(restored, { waitUntil: "load" });
-  await page.evaluate(readFileSync(require.resolve("@hyperframes/core/runtime"), "utf8"));
-  await page.waitForFunction(() => "__player" in window);
-  await page.evaluate(undoBundle);
+])(
+  "an undone crop leaves a $gsap $placement r$rotation layer where it was",
+  async (spec) => {
+    const dir = join(mkdtempSync(join(tmpdir(), "undo-gsap-")), "case");
+    writeFixture({ gesture: "crop", nesting: "root", zoom: 100, ...spec }, dir);
+    const restored = readFileSync(join(dir, "index.html"), "utf8");
+    const previous = restored.replace(
+      `<div id="target"`,
+      `<div id="target" style="clip-path: ${CROP}"`,
+    );
+    const page = await browser.newPage();
+    await page.setViewport({ width: 1920, height: 1080 });
+    await page.setRequestInterception(true);
+    // Only the fixture's GSAP CDN script is served; anything else is refused, never fetched.
+    page.on("request", (request) =>
+      request.url().endsWith("/gsap.min.js")
+        ? request.respond({ body: readFileSync(require.resolve("gsap/dist/gsap.min.js"), "utf8") })
+        : request.abort("blockedbyclient"),
+    );
+    await page.setContent(restored, { waitUntil: "load" });
+    await page.evaluate(readFileSync(require.resolve("@hyperframes/core/runtime"), "utf8"));
+    await page.waitForFunction(() => "__player" in window);
+    await page.evaluate(undoBundle);
 
-  const box = () =>
-    page.evaluate(() => {
-      const { left, top, width, height } = document
-        .getElementById("target")!
-        .getBoundingClientRect();
-      return [left, top, width, height].map((n) => Math.round(n * 100) / 100);
-    });
-  await page.evaluate(() =>
-    (window as unknown as { __player: { seek(t: number): void } }).__player.seek(1),
-  );
-  const before = await box();
-  const outcome = await page.evaluate(
-    (files, crop) => {
-      document.getElementById("target")!.style.setProperty("clip-path", crop);
-      const undo = (window as unknown as { hfUndo: typeof import("./gsapUndoRestore") }).hfUndo;
-      const iframe = { contentDocument: document, contentWindow: window } as HTMLIFrameElement;
-      return undo.applyUndoRestoreToPreview(iframe, "index.html", files, 1, () => {});
-    },
-    { "index.html": { previous, restored } },
-    CROP,
-  );
+    const box = () =>
+      page.evaluate(() => {
+        const { left, top, width, height } = document
+          .getElementById("target")!
+          .getBoundingClientRect();
+        return [left, top, width, height].map((n) => Math.round(n * 100) / 100);
+      });
+    await page.evaluate(() =>
+      (window as unknown as { __player: { seek(t: number): void } }).__player.seek(1),
+    );
+    const before = await box();
+    const outcome = await page.evaluate(
+      (files, crop) => {
+        document.getElementById("target")!.style.setProperty("clip-path", crop);
+        const undo = (window as unknown as { hfUndo: typeof import("./gsapUndoRestore") }).hfUndo;
+        const iframe = { contentDocument: document, contentWindow: window } as HTMLIFrameElement;
+        return undo.applyUndoRestoreToPreview(iframe, "index.html", files, 1, () => {});
+      },
+      { "index.html": { previous, restored } },
+      CROP,
+    );
 
-  expect(outcome).toBe("soft");
-  expect(await box()).toEqual(before);
-  await page.close();
-});
+    expect(outcome).toBe("soft");
+    expect(await box()).toEqual(before);
+    await page.close();
+  },
+  30_000,
+);

package/src/utils/gsapUndoRestore.ts

@@ -398,20 +398,17 @@ export function applyUndoRestoreToPreview(
   const active = files[activeDocPath];
   const restoredScript = active ? extractGsapScriptText(active.restored) : null;
   const previousScript = active ? extractGsapScriptText(active.previous) : null;
-  const reparse = plan.scripted
-    ? plan.targets.map(({ live }) => live).filter((el) => "_gsap" in el)
-    : [];
-  if (reparse.length && !restoredScript) {
+  const reparse = plan.scripted && plan.targets.some(({ live }) => "_gsap" in live);
+  if (reparse && !restoredScript) {
     reloadPreview();
     return "full";
   }
-  if (restoredScript && (restoredScript !== previousScript || reparse.length)) {
+  if (restoredScript && (restoredScript !== previousScript || reparse)) {
     syncStaleEditMarks(doc, active);
     const result = applySoftReload(iframe, restoredScript, {
       onAsyncFailure: reloadPreview,
       currentTimeOverride: currentTime,
       authoredHtml: active.restored,
-      reparse,
       nestedFiles,
     });
     if (result === "cannot-soft-reload") {

package/src/utils/keyframeUsage.ts

@@ -0,0 +1,79 @@
+import type { CommitMutationOptions, MutationResult } from "../hooks/gsapScriptCommitTypes";
+import { trackStudioEvent } from "./studioTelemetry";
+
+export type KeyframeUsageAction = "add" | "convert" | "remove_all" | "reset";
+
+export function keyframeUsageActions(
+  mutations: ReadonlyArray<Record<string, unknown>>,
+  semanticActions?: ReadonlyArray<KeyframeUsageAction | undefined>,
+): Set<KeyframeUsageAction> {
+  const actions = new Set<KeyframeUsageAction>();
+  for (const [index, mutation] of mutations.entries()) {
+    const semanticAction = semanticActions?.[index];
+    if (semanticAction) {
+      actions.add(semanticAction);
+      continue;
+    }
+    switch (mutation.type) {
+      case "add-keyframe":
+      case "add-with-keyframes":
+        actions.add("add");
+        break;
+      case "convert-to-keyframes":
+        actions.add("convert");
+        break;
+      case "remove-all-keyframes":
+        actions.add("remove_all");
+        break;
+    }
+  }
+  return actions;
+}
+
+export function trackKeyframeUsage(action: KeyframeUsageAction, property?: string): void {
+  trackStudioEvent("keyframe", property === undefined ? { action } : { action, property });
+}
+
+export function primaryKeyframeAction(
+  actions: ReadonlySet<KeyframeUsageAction>,
+): KeyframeUsageAction | undefined {
+  return (["add", "convert", "remove_all", "reset"] as const).find((action) => actions.has(action));
+}
+
+export function changedMutationIndices(
+  result: MutationResult,
+  count: number,
+  options?: ReadonlyArray<Pick<CommitMutationOptions, "keyframeTelemetry">>,
+): number[] {
+  if (!result.ok || result.changed !== true) return [];
+  const changes = count === 1 ? [true] : result.mutationChanges;
+  if (
+    !Array.isArray(changes) ||
+    changes.length !== count ||
+    changes.some((value) => typeof value !== "boolean")
+  )
+    return [];
+  return changes.flatMap((changed, index) =>
+    changed && options?.[index]?.keyframeTelemetry !== false ? [index] : [],
+  );
+}
+
+export function trackKeyframeCommit(
+  mutations: ReadonlyArray<Record<string, unknown>>,
+  result: MutationResult,
+  options: CommitMutationOptions,
+  memberOptions?: ReadonlyArray<CommitMutationOptions>,
+): void {
+  if (!result.ok || result.changed !== true || options.keyframeTelemetry === false) return;
+  const indices = changedMutationIndices(result, mutations.length, memberOptions);
+  const actions = keyframeUsageActions(
+    indices.map((index) => mutations[index]!),
+    indices.map(
+      (index) =>
+        memberOptions?.[index]?.keyframeAction ??
+        (mutations.length === 1 ? options.keyframeAction : undefined),
+    ),
+  );
+  const action = primaryKeyframeAction(actions);
+  if (action) trackKeyframeUsage(action, action === "add" ? options.keyframeProperty : undefined);
+}

package/src/utils/previewFeatureUsage.test.ts

@@ -0,0 +1,32 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { trackPreviewEditResult } from "./previewFeatureUsage";
+import { trackStudioEvent } from "./studioTelemetry";
+vi.mock("./studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+beforeEach(() => vi.clearAllMocks());
+describe("preview write usage", () => {
+  it.each([
+    { ok: true, changed: true },
+    {
+      ok: true,
+      persistence: { changed: true, sourceFile: "private.html", content: "private text" },
+    },
+  ])("sends only gesture metadata after a changed result", (result) => {
+    trackPreviewEditResult("resize", "drag", result);
+    expect(trackStudioEvent).toHaveBeenCalledExactlyOnceWith("feature_used", {
+      feature: "resize",
+      surface: "preview",
+      method: "drag",
+    });
+  });
+  it.each([
+    undefined,
+    null,
+    {},
+    { ok: false, changed: true },
+    { changed: false },
+    { persistence: { changed: false } },
+  ])("does not count unavailable, failed or unchanged results (%j)", (result) => {
+    trackPreviewEditResult("move", "drag", result);
+    expect(trackStudioEvent).not.toHaveBeenCalled();
+  });
+});

package/src/utils/previewFeatureUsage.ts

@@ -0,0 +1,46 @@
+import { trackStudioEvent } from "./studioTelemetry";
+
+export type PreviewFeature =
+  | "move"
+  | "resize"
+  | "rotate"
+  | "crop"
+  | "nudge"
+  | "multi_select"
+  | "z_order"
+  | "text_edit"
+  | "motion_path"
+  | "gesture_recording"
+  | "snapping"
+  | "grid"
+  | "grid_spacing"
+  | "snap_to_grid"
+  | "ruler"
+  | "safe_margins";
+
+export type PreviewMethod = "drag" | "button" | "keyboard" | "field";
+
+export interface GeometryCommitResult {
+  ok: true;
+  changed: boolean;
+}
+
+export function trackPreviewFeatureUsed(feature: PreviewFeature, method: PreviewMethod): void {
+  trackStudioEvent("feature_used", { feature, surface: "preview", method });
+}
+
+export function trackPreviewEditResult(
+  feature: PreviewFeature,
+  method: PreviewMethod,
+  result: unknown,
+): void {
+  if (typeof result !== "object" || result === null) return;
+  if (Reflect.get(result, "ok") === false) return;
+  const persistence = Reflect.get(result, "persistence");
+  const changed =
+    Reflect.get(result, "changed") === true ||
+    (typeof persistence === "object" &&
+      persistence !== null &&
+      Reflect.get(persistence, "changed") === true);
+  if (changed) trackPreviewFeatureUsed(feature, method);
+}

package/src/utils/previewPrefetch.ts

@@ -1,5 +1,6 @@
 import { applyPreviewVariablesToUrl } from "../hooks/previewVariablesStore";
 import { buildProjectApiPath, parseProjectIdFromHash } from "./projectRouting";
+import { studioApiFetch } from "./studioApiFetch";
 
 let prefetched: string | null = null;
 
@@ -10,5 +11,5 @@ export function prefetchPreviewForHash(hash: string): void {
   prefetched = projectId;
   const url = new URL(buildProjectApiPath(projectId, "/preview"), window.location.origin);
   applyPreviewVariablesToUrl(url);
-  fetch(url).catch(() => undefined);
+  studioApiFetch(url).catch(() => undefined);
 }

package/src/utils/razorSplitTransaction.ts

@@ -6,6 +6,7 @@ import { serializeStudioFileMutations } from "./studioFileMutationCoordinator";
 import { buildProjectApiPath } from "./projectRouting";
 import { markStudioWriteToken } from "./studioFileVersion";
 import { resolveElementTrack } from "./studioHelpers";
+import { studioApiFetch } from "./studioApiFetch";
 
 type ProjectFileWriter = (path: string, content: string, expectedContent?: string) => Promise<void>;
 
@@ -101,7 +102,7 @@ export function buildAtomicCutIntents(
 }
 
 async function readFileVersion(projectId: string, path: string): Promise<string> {
-  const response = await fetch(
+  const response = await studioApiFetch(
     buildProjectApiPath(projectId, `/files/${encodeURIComponent(path)}`),
   );
   if (!response.ok) throw new Error(`Failed to read ${path} before cut (${response.status})`);
@@ -124,14 +125,17 @@ async function requestAtomicCut(
   }
   const transactionToken = `cut:${crypto.randomUUID()}`;
   markStudioWriteToken(transactionToken);
-  const response = await fetch(buildProjectApiPath(projectId, "/file-mutations/split-batch"), {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      "X-Hyperframes-Write-Token": transactionToken,
+  const response = await studioApiFetch(
+    buildProjectApiPath(projectId, "/file-mutations/split-batch"),
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Hyperframes-Write-Token": transactionToken,
+      },
+      body: JSON.stringify({ files, transactionToken }),
     },
-    body: JSON.stringify({ files, transactionToken }),
-  });
+  );
   const body = (await response.json().catch(() => null)) as
     | (Partial<CutBatchResponse> & { error?: string; outcome?: string })
     | null;

package/src/utils/softReloadTargets.ts

@@ -48,10 +48,8 @@ export function collectResetTargets(
   win: { __timelines?: Record<string, unknown> },
   doc: Document,
   targetKeys: string[],
-  reparse: Element[] = [],
 ): Map<Element, Set<string>> {
-  // Elements the caller needs GSAP to parse again, with nothing tweened yet.
-  const targets = new Map<Element, Set<string>>(reparse.map((el) => [el, new Set<string>()]));
+  const targets = new Map<Element, Set<string>>();
   const timelines = (win.__timelines ?? {}) as Record<string, TweenLike | undefined>;
   const others = new Set<unknown>(
     Object.entries(timelines).flatMap(([key, tl]) => (targetKeys.includes(key) ? [] : [tl])),

package/src/utils/studioApiFetch.test.ts

@@ -0,0 +1,75 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+async function loadWithEnv(env: Record<string, string>) {
+  vi.resetModules();
+  for (const [key, value] of Object.entries(env)) vi.stubEnv(key, value);
+  return import("./studioApiFetch");
+}
+
+describe("studioApiFetch", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.unstubAllEnvs();
+    vi.resetModules();
+  });
+
+  it("sends Studio's requests without credentials, keeping the caller's options", async () => {
+    const fetchMock = vi.fn(async () => new Response("ok"));
+    vi.stubGlobal("fetch", fetchMock);
+    const { studioApiFetch } = await loadWithEnv({});
+    const signal = new AbortController().signal;
+
+    await studioApiFetch("/api/projects/demo/history/step", { method: "POST", signal });
+
+    expect(fetchMock).toHaveBeenCalledWith("/api/projects/demo/history/step", {
+      method: "POST",
+      signal,
+      credentials: "omit",
+    });
+  });
+
+  it.each([
+    ["the CLI or Studio dev server", "http://localhost:5190/"],
+    ["Desktop's own server", "http://127.0.0.1:43117/"],
+    ["IPv6 loopback", "http://[::1]:8080/"],
+  ])("leaves cookies out when Studio is served from %s", async (_, page) => {
+    const fetchMock = vi.fn(async () => new Response("ok"));
+    vi.stubGlobal("fetch", fetchMock);
+    vi.stubGlobal("location", new URL(page));
+    const { studioApiFetch } = await loadWithEnv({});
+
+    await studioApiFetch("/api/projects/demo/files/index.html");
+
+    expect(fetchMock).toHaveBeenCalledWith("/api/projects/demo/files/index.html", {
+      credentials: "omit",
+    });
+  });
+
+  it("keeps same-origin cookies off loopback, where a proxy or tunnel may authenticate with them", async () => {
+    const fetchMock = vi.fn(async () => new Response("ok"));
+    vi.stubGlobal("fetch", fetchMock);
+    vi.stubGlobal("location", new URL("https://studio.example.com/editor"));
+    const { studioApiFetch } = await loadWithEnv({});
+
+    await studioApiFetch("/api/projects/demo/files/index.html");
+
+    expect(fetchMock).toHaveBeenCalledWith("/api/projects/demo/files/index.html", {
+      credentials: "same-origin",
+    });
+  });
+
+  it("sends same-origin credentials on loopback for a host that opted out", async () => {
+    vi.stubGlobal("location", new URL("http://localhost:5190/"));
+    const fetchMock = vi.fn(async () => new Response("ok"));
+    vi.stubGlobal("fetch", fetchMock);
+    const { studioApiFetch } = await loadWithEnv({
+      VITE_STUDIO_API_SAME_ORIGIN_CREDENTIALS: "true",
+    });
+
+    await studioApiFetch("/api/projects/demo/files/index.html");
+
+    expect(fetchMock).toHaveBeenCalledWith("/api/projects/demo/files/index.html", {
+      credentials: "same-origin",
+    });
+  });
+});

package/src/utils/studioApiFetch.ts

@@ -0,0 +1,13 @@
+import { STUDIO_API_SAME_ORIGIN_CREDENTIALS } from "../components/editor/manualEditingAvailability";
+
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+
+function studioApiCredentials(): RequestCredentials {
+  if (STUDIO_API_SAME_ORIGIN_CREDENTIALS) return "same-origin";
+  const host = globalThis.location?.hostname;
+  return !host || LOOPBACK_HOSTS.has(host) ? "omit" : "same-origin";
+}
+
+export function studioApiFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response> {
+  return globalThis.fetch(input, { ...init, credentials: studioApiCredentials() });
+}

package/src/utils/studioFileHistory.ts

@@ -2,6 +2,7 @@ import { buildProjectApiPath } from "./projectRouting";
 import type { MutableRefObject } from "react";
 import { serializeStudioFileMutations } from "./studioFileMutationCoordinator";
 import { createStudioSaveHttpError } from "./studioSaveDiagnostics";
+import { studioApiFetch } from "./studioApiFetch";
 
 export interface RecordEditInput {
   label: string;
@@ -49,7 +50,9 @@ interface SaveProjectFilesWithHistoryInput {
 }
 
 export async function readProjectFileContent(pid: string, path: string): Promise<string> {
-  const response = await fetch(buildProjectApiPath(pid, `/files/${encodeURIComponent(path)}`));
+  const response = await studioApiFetch(
+    buildProjectApiPath(pid, `/files/${encodeURIComponent(path)}`),
+  );
   if (!response.ok) {
     throw await createStudioSaveHttpError(response, `Failed to read ${path}`);
   }

package/src/utils/studioHelpers.ts

@@ -4,6 +4,7 @@ import type { TimelineElement } from "../player/store/playerStore";
 import type { DomEditSelection } from "../components/editor/domEditing";
 import type { TimelineAssetKind } from "./timelineAssetDrop";
 import { roundToCenti } from "./rounding";
+import { studioApiFetch } from "./studioApiFetch";
 
 export interface EditingFile {
   path: string;
@@ -91,6 +92,11 @@ export function isImageBackgroundValue(value: string): boolean {
   return /^url\(/i.test(value.trim());
 }
 
+export function cssPropertyName(property: string): string {
+  if (property.startsWith("--")) return property;
+  return property.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`).replace(/^ms-/, "-ms-");
+}
+
 export function isManualGeometryStyleProperty(property: string): boolean {
   return property === "left" || property === "top" || property === "width" || property === "height";
 }
@@ -401,7 +407,7 @@ export async function resolveAssetHasAudio(
   assetPath: string,
 ): Promise<boolean | null> {
   try {
-    const response = await fetch(mediaMetadataUrl(projectId, assetPath));
+    const response = await studioApiFetch(mediaMetadataUrl(projectId, assetPath));
     if (!response.ok) return null;
     const data: unknown = await response.json();
     const metadata = isPlainRecord(data) ? data.metadata : undefined;

package/src/utils/studioPendingEdits.test.ts

@@ -5,7 +5,7 @@ import {
   beginStudioPendingEdit,
   flushStudioPendingEdits,
   hasStudioPendingEdits,
-  revertNewestStudioPendingEdit,
+  paintBackNewestStudioPendingEdit,
   trackStudioPendingEdit,
   trackedStudioEdit,
 } from "./studioPendingEdits";
@@ -227,12 +227,12 @@ describe("a pending edit undo can paint back", () => {
     shown.length = 0;
     const first = edit("first");
     const second = edit("second");
-    const again = revertNewestStudioPendingEdit();
+    const again = paintBackNewestStudioPendingEdit();
     expect(shown).toEqual(["second undone"]);
     expect(second.reverted()).toBe(true);
     expect(first.reverted()).toBe(false);
-    expect(revertNewestStudioPendingEdit()).toBeNull();
-    again!();
+    expect(paintBackNewestStudioPendingEdit()).toBeNull();
+    again!.showAgain();
     expect(shown).toEqual(["second undone", "second again"]);
     first.settle();
     second.settle();
@@ -243,7 +243,7 @@ describe("a pending edit undo can paint back", () => {
     const move = edit("move");
     let saved!: () => void;
     trackStudioPendingEdit(new Promise<void>((resolve) => (saved = resolve)));
-    expect(revertNewestStudioPendingEdit()).toBeNull();
+    expect(paintBackNewestStudioPendingEdit()).toBeNull();
     expect(shown).toEqual([]);
     saved();
     move.settle();
@@ -258,7 +258,7 @@ describe("a pending edit undo can paint back", () => {
       trackStudioPendingEdit(new Promise<void>((resolve) => (saved = resolve))),
     );
     move.settle(save);
-    revertNewestStudioPendingEdit();
+    paintBackNewestStudioPendingEdit();
     expect(shown).toEqual(["move undone"]);
     saved();
     await expect(flushStudioPendingEdits()).resolves.toEqual({ status: "clean" });
@@ -295,3 +295,20 @@ describe("the package's public revert", () => {
     }
   });
 });
+
+describe("a drain of only the current edits", () => {
+  it("ends once the edits pending at its start land, without waiting for one started after", async () => {
+    let landFirst!: () => void;
+    let landLater!: () => void;
+    trackStudioPendingEdit(new Promise<void>((resolve) => (landFirst = resolve)));
+    let drained = false;
+    const drain = flushStudioPendingEdits({ onlyCurrent: true }).then(() => (drained = true));
+    await Promise.resolve();
+    trackStudioPendingEdit(new Promise<void>((resolve) => (landLater = resolve)));
+    landFirst();
+    await drain;
+    expect(drained).toBe(true);
+    expect(hasStudioPendingEdits()).toBe(true);
+    landLater();
+  });
+});

package/src/utils/studioPendingEdits.ts

@@ -11,7 +11,13 @@ export type StudioPendingEditsDrainResult = StudioSaveDrainResult;
 
 export type StudioEditRevert = () => () => void;
 
-const pendingEdits = new Map<Promise<unknown>, { revert: StudioEditRevert | null }>();
+interface PendingEdit {
+  revert: StudioEditRevert | null;
+  landed: () => Promise<boolean>;
+}
+
+const pendingEdits = new Map<Promise<unknown>, PendingEdit>();
+const NOT_SAVED = () => Promise.resolve(false);
 let adopting = false;
 
 function waitForPostBlurEffects(): Promise<void> {
@@ -67,7 +73,7 @@ export function trackStudioPendingEdit(
   if (!result) return undefined;
   const promise = Promise.resolve(result);
   if (adopting) return promise;
-  pendingEdits.set(promise, { revert: null });
+  pendingEdits.set(promise, { revert: null, landed: NOT_SAVED });
   promise.then(
     () => pendingEdits.delete(promise),
     () => pendingEdits.delete(promise),
@@ -90,6 +96,8 @@ export function beginStudioPendingEdit(revert: StudioEditRevert | null) {
   const promise = trackStudioPendingEdit(new Promise<unknown>((resolve) => (settle = resolve)))!;
   const entry = pendingEdits.get(promise)!;
   entry.revert = revert;
+  let landed = Promise.resolve(false);
+  entry.landed = () => landed;
   return {
     settle,
     reverted: () => entry.revert === null && revert !== null,
@@ -97,7 +105,12 @@ export function beginStudioPendingEdit(revert: StudioEditRevert | null) {
     adopt<T>(start: () => T): T {
       adopting = true;
       try {
-        return start();
+        const committed = start();
+        landed = Promise.resolve(committed).then(
+          () => true,
+          () => false,
+        );
+        return committed;
       } catch (error) {
         settle();
         throw error;
@@ -108,15 +121,24 @@ export function beginStudioPendingEdit(revert: StudioEditRevert | null) {
   };
 }
 
-export function revertNewestStudioPendingEdit(): (() => void) | null {
+export function paintBackNewestStudioPendingEdit(): {
+  showAgain: () => void;
+  landed: () => Promise<boolean>;
+} | null {
   const newest = [...pendingEdits.values()].at(-1);
   const revert = newest?.revert;
   if (!newest || !revert) return null;
   newest.revert = null;
-  return revert();
+  return { showAgain: revert(), landed: newest.landed };
+}
+
+export function revertNewestStudioPendingEdit(): (() => void) | null {
+  return paintBackNewestStudioPendingEdit()?.showAgain ?? null;
 }
 
-export async function flushStudioPendingEdits(): Promise<StudioPendingEditsDrainResult> {
+export async function flushStudioPendingEdits({
+  onlyCurrent = false,
+} = {}): Promise<StudioPendingEditsDrainResult> {
   const active = focusedField();
   if (active) {
     active.blur();
@@ -128,10 +150,12 @@ export async function flushStudioPendingEdits(): Promise<StudioPendingEditsDrain
   window.dispatchEvent(
     new CustomEvent<StudioFlushPendingEditsDetail>(STUDIO_FLUSH_PENDING_EDITS_EVENT, { detail }),
   );
+  const current = onlyCurrent ? new Set(pendingEdits.keys()) : null;
+  const waiting = () => [...pendingEdits.keys()].filter((edit) => !current || current.has(edit));
   let conflict: StudioFileConflictError | undefined;
   let firstFailure: PromiseRejectedResult | undefined;
-  while (detail.promises.length > 0 || pendingEdits.size > 0) {
-    const promises = [...detail.promises, ...pendingEdits.keys()];
+  while (detail.promises.length > 0 || waiting().length > 0) {
+    const promises = [...detail.promises, ...waiting()];
     detail.promises = [];
     const batchFailures = inspectDrainFailures(await Promise.allSettled(promises));
     conflict ??= batchFailures.conflict;