@hyperframes/studio 0.7.36 → 0.7.38

package/src/hooks/useFrameCapture.ts

@@ -1,4 +1,4 @@
-import { useState, useCallback, type MouseEvent } from "react";
+import { useState, useCallback, useRef, type MouseEvent } from "react";
 import { useMountEffect } from "./useMountEffect";
 import { liveTime, usePlayerStore } from "../player";
 import { buildFrameCaptureFilename, buildFrameCaptureUrl } from "../utils/frameCapture";
@@ -17,6 +17,8 @@ export function useFrameCapture({
   waitForPendingDomEditSaves,
 }: UseFrameCaptureParams) {
   const [captureFrameTime, setCaptureFrameTime] = useState(0);
+  const [capturing, setCapturing] = useState(false);
+  const capturingRef = useRef(false);
 
   useMountEffect(() => {
     setCaptureFrameTime(usePlayerStore.getState().currentTime);
@@ -31,6 +33,11 @@ export function useFrameCapture({
     async (event: MouseEvent<HTMLAnchorElement>) => {
       if (!projectId) return;
       event.preventDefault();
+      // A capture can take up to ~35s (save drain + server render) — ignore
+      // re-entrant clicks instead of firing parallel captures.
+      if (capturingRef.current) return;
+      capturingRef.current = true;
+      setCapturing(true);
       try {
         const time = usePlayerStore.getState().currentTime;
         setCaptureFrameTime(time);
@@ -79,6 +86,9 @@ export function useFrameCapture({
         }
       } catch (err) {
         showToast(err instanceof Error ? err.message : "Capture failed", "error");
+      } finally {
+        capturingRef.current = false;
+        setCapturing(false);
       }
     },
     [activeCompPath, projectId, showToast, waitForPendingDomEditSaves],
@@ -98,5 +108,6 @@ export function useFrameCapture({
     captureFrameFilename,
     handleCaptureFrameClick,
     refreshCaptureFrameTime,
+    capturing,
   };
 }

package/src/hooks/usePanelLayout.ts

@@ -100,6 +100,7 @@ export function usePanelLayout(initialState?: InitialPanelLayoutState) {
     leftWidth,
     setLeftWidth,
     rightWidth,
+    setRightWidth,
     leftCollapsed,
     setLeftCollapsed,
     rightCollapsed,

package/src/hooks/usePreviewPersistence.ts

@@ -8,6 +8,7 @@ import {
 import { STUDIO_MOTION_PATH } from "../components/editor/studioMotion";
 import type { EditHistoryKind } from "../utils/editHistory";
 import { createDomEditSaveQueue } from "../utils/domEditSaveQueue";
+import { flushStudioPendingEdits } from "../utils/studioPendingEdits";
 import { trackStudioEvent } from "../utils/studioTelemetry";
 
 // ── Types ──
@@ -77,6 +78,24 @@ function shouldReloadForStudioFileChange(
   return Date.now() - domEditSaveTimestampRef.current >= 4000;
 }
 
+// fallow-ignore-next-line complexity
+async function clearLegacyStudioMotionFile(
+  readOptionalProjectFile: (path: string) => Promise<string>,
+  writeProjectFile: (path: string, content: string) => Promise<void>,
+): Promise<void> {
+  const content = await readOptionalProjectFile(STUDIO_MOTION_PATH).catch(() => null);
+  if (!content) return;
+  try {
+    const parsed = JSON.parse(content) as { motions?: unknown[] };
+    if (!Array.isArray(parsed.motions) || parsed.motions.length === 0) return;
+  } catch {
+    return;
+  }
+  await writeProjectFile(STUDIO_MOTION_PATH, JSON.stringify({ version: 1, motions: [] })).catch(
+    () => {},
+  );
+}
+
 // ── Hook ──
 
 export function usePreviewPersistence({
@@ -135,6 +154,7 @@ export function usePreviewPersistence({
   }, []);
 
   const waitForPendingDomEditSaves = useCallback(async () => {
+    await flushStudioPendingEdits();
     await domEditSaveQueueRef.current?.waitForIdle();
   }, []);
 
@@ -185,20 +205,7 @@ export function usePreviewPersistence({
   // could still fire alongside the new seek-reapply runtime. Empty the file so
   // the legacy codepath no-ops.
   useMountEffect(() => {
-    _readOptionalProjectFile(STUDIO_MOTION_PATH)
-      .then((content) => {
-        if (!content) return;
-        try {
-          const parsed = JSON.parse(content) as { motions?: unknown[] };
-          if (!Array.isArray(parsed.motions) || parsed.motions.length === 0) return;
-        } catch {
-          return;
-        }
-        return _writeProjectFile(STUDIO_MOTION_PATH, JSON.stringify({ version: 1, motions: [] }));
-      })
-      .catch(() => {
-        /* best-effort migration — ignore failures */
-      });
+    void clearLegacyStudioMotionFile(_readOptionalProjectFile, _writeProjectFile);
   });
 
   // ── Listen for external file changes (HMR / SSE) ──
@@ -210,8 +217,10 @@ export function usePreviewPersistence({
           pendingTimelineEditPathRef,
           domEditSaveTimestampRef,
         )
-      )
+      ) {
+        // fallow-ignore-next-line code-duplication
         reloadPreview();
+      }
     };
     if (import.meta.hot) {
       import.meta.hot.on("hf:file-change", handler);

package/src/hooks/useStudioContextValue.ts

@@ -21,7 +21,12 @@ interface StudioContextInput {
   renderQueue: {
     jobs: unknown[];
     isRendering: boolean;
+    loadError: string | null;
+    actionError: string | null;
+    dismissActionError: () => void;
+    reloadRenders: () => void;
     deleteRender: (id: string) => void;
+    cancelRender: (id: string) => void;
     clearCompleted: () => void;
     startRender: (options: unknown) => Promise<void>;
   };

package/src/hooks/useToast.ts

@@ -2,24 +2,77 @@ import { useState, useCallback, useRef } from "react";
 import { useMountEffect } from "./useMountEffect";
 import type { AppToast } from "../utils/studioHelpers";
 
+interface ToastItem extends AppToast {
+  id: number;
+  /** True while the exit animation plays, just before removal. */
+  leaving?: boolean;
+}
+
+const AUTO_DISMISS_MS = 4000;
+const EXIT_MS = 160;
+const MAX_TOASTS = 3;
+
+let nextToastId = 1;
+
+/**
+ * Stacked toasts (max 3). Info toasts auto-dismiss after 4s; error toasts
+ * persist until explicitly dismissed so failures can't silently vanish.
+ */
 export function useToast() {
-  const [appToast, setAppToast] = useState<AppToast | null>(null);
-  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const [toasts, setToasts] = useState<ToastItem[]>([]);
+  const timersRef = useRef<Map<number, ReturnType<typeof setTimeout>>>(new Map());
 
-  const showToast = useCallback((message: string, tone: AppToast["tone"] = "error") => {
-    if (timerRef.current) clearTimeout(timerRef.current);
-    setAppToast({ message, tone });
-    timerRef.current = setTimeout(() => setAppToast(null), 4000);
+  const clearTimer = useCallback((id: number) => {
+    const timer = timersRef.current.get(id);
+    if (timer) {
+      clearTimeout(timer);
+      timersRef.current.delete(id);
+    }
   }, []);
 
+  const removeToast = useCallback(
+    (id: number) => {
+      clearTimer(id);
+      setToasts((prev) => prev.filter((t) => t.id !== id));
+    },
+    [clearTimer],
+  );
+
+  const dismissToast = useCallback(
+    (id: number) => {
+      clearTimer(id);
+      // Mark leaving so the exit animation plays, then remove.
+      setToasts((prev) => prev.map((t) => (t.id === id ? { ...t, leaving: true } : t)));
+      const timer = setTimeout(() => removeToast(id), EXIT_MS);
+      timersRef.current.set(id, timer);
+    },
+    [clearTimer, removeToast],
+  );
+
+  const showToast = useCallback(
+    (message: string, tone: AppToast["tone"] = "error") => {
+      const id = nextToastId++;
+      setToasts((prev) => {
+        const next = [...prev, { id, message, tone }];
+        // Cap the stack; drop the oldest (and its pending timer).
+        while (next.length > MAX_TOASTS) {
+          const dropped = next.shift();
+          if (dropped) clearTimer(dropped.id);
+        }
+        return next;
+      });
+      if (tone !== "error") {
+        const timer = setTimeout(() => dismissToast(id), AUTO_DISMISS_MS);
+        timersRef.current.set(id, timer);
+      }
+    },
+    [clearTimer, dismissToast],
+  );
+
   useMountEffect(() => () => {
-    if (timerRef.current) clearTimeout(timerRef.current);
+    for (const timer of timersRef.current.values()) clearTimeout(timer);
+    timersRef.current.clear();
   });
 
-  const dismissToast = useCallback(() => {
-    if (timerRef.current) clearTimeout(timerRef.current);
-    setAppToast(null);
-  }, []);
-
-  return { appToast, showToast, dismissToast };
+  return { toasts, showToast, dismissToast };
 }

package/src/styles/studio.css

@@ -251,3 +251,64 @@ body {
   background: linear-gradient(90deg, #06e3fa, #4fdb5e);
   transition: transform 160ms ease;
 }
+
+/* Toast enter/exit (StudioToast) */
+@keyframes hf-toast-in {
+  from {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@keyframes hf-toast-out {
+  from {
+    opacity: 1;
+    transform: translateY(0);
+  }
+  to {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+}
+
+.hf-toast-enter {
+  animation: hf-toast-in 160ms ease-out;
+}
+
+.hf-toast-exit {
+  animation: hf-toast-out 160ms ease-in forwards;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .hf-toast-enter,
+  .hf-toast-exit {
+    animation: none;
+  }
+  .hf-toast-exit {
+    opacity: 0;
+  }
+}
+
+/* Overlay/backdrop entrance — the heaviest visual changes shouldn't pop in */
+@keyframes hf-backdrop-in {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
+.hf-backdrop-in {
+  animation: hf-backdrop-in 150ms ease-out;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .hf-backdrop-in {
+    animation: none;
+  }
+}

package/src/utils/sdkResolverShadow.test.ts

@@ -98,6 +98,23 @@ describe("A. Flag gating", () => {
     expect(trackedEvents.filter((e) => e.event === "sdk_resolver_shadow")).toHaveLength(0);
   });
 
+  it("A2c: empty session → ONE tagged session_empty event per session, no attempt", async () => {
+    mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
+    flushAttemptCounts(); // drain counts left by earlier tests
+    const session = await openComposition("<!DOCTYPE html><html><body></body></html>");
+    const ops: PatchOperation[] = [{ type: "inline-style", property: "color", value: "blue" }];
+    runResolverShadow(session, "hf-anything", ops);
+    runResolverShadow(session, "hf-other", ops); // repeat edits do not re-emit
+    const events = trackedEvents.filter((e) => e.event === "sdk_resolver_shadow");
+    // The modeling gap stays VISIBLE (silence would blind the tripwire to the
+    // exact class that exposed the template-comp bug) but is distinguishable
+    // and rate-limited to once per session instance.
+    expect(events).toHaveLength(1);
+    expect(events[0]?.props.sessionEmpty).toBe(true);
+    expect(JSON.stringify(events[0]?.props.mismatches)).toContain("session_empty");
+    expect(flushAttemptCounts()).toBeNull(); // can't cut over → not in the denominator
+  });
+
   it("A3: shadow depends ONLY on shadow flag, not on STUDIO_SDK_CUTOVER_ENABLED", async () => {
     // The mock always returns STUDIO_SDK_CUTOVER_ENABLED=false. Use a divergence
     // (poisoned session) so the flag-on case emits; flag-off must stay silent.
@@ -268,7 +285,12 @@ describe("C. Resolver-parity detection", () => {
 
   it("C8 sourceHfIdCount: emitted element_not_found carries source occurrence count", async () => {
     mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
-    const session = { getElement: () => null, getElements: () => [] } as unknown as Composition;
+    // One unrelated element so the session isn't "empty" (empty sessions are
+    // skipped as structural modeling gaps) — it just can't resolve hf-dup.
+    const session = {
+      getElement: () => null,
+      getElements: () => [{ id: "hf-other" }],
+    } as unknown as Composition;
     // id present twice in source (duplicate-id ambiguity) but absent from session
     const source = `<div data-hf-id="hf-dup">a</div><div data-hf-id="hf-dup">b</div>`;
     runResolverShadow(
@@ -282,7 +304,10 @@ describe("C. Resolver-parity detection", () => {
 
   it("C8 sourceLooseMatchOnly: hfId matches source only as plain text, not a data-hf-id attribute", async () => {
     mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
-    const session = { getElement: () => null, getElements: () => [] } as unknown as Composition;
+    const session = {
+      getElement: () => null,
+      getElements: () => [{ id: "hf-other" }],
+    } as unknown as Composition;
     // "hf-widget" appears only inside a class name, never as data-hf-id="hf-widget".
     const source = `<div class="hf-widget-container">no attribute match here</div>`;
     runResolverShadow(
@@ -436,7 +461,7 @@ describe("F. recordResolverParity", () => {
     expect(ev?.sourceHfIdCount).toBeUndefined();
   });
 
-  it("fails open: a readSource error still emits (no suppression)", async () => {
+  it("fails open: a readSource error still emits (no suppression), tagged sourceReadFailed", async () => {
     mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
     const session = await openComposition(BASE_HTML);
     await recordResolverParity(session, "hf-missing", "setTiming", () =>
@@ -445,6 +470,31 @@ describe("F. recordResolverParity", () => {
     const ev = lastShadow();
     expect(ev?.mismatchCount).toBe(1);
     expect(ev?.sourceHfIdCount).toBeUndefined();
+    // Distinguishes "reader threw" from "no reader wired" — every wild emission
+    // of the setTiming class had an absent sourceHfIdCount and the two cases
+    // were indistinguishable in telemetry.
+    expect(ev?.sourceReadFailed).toBe(true);
+  });
+
+  it("does not tag sourceReadFailed when no reader is supplied", async () => {
+    mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
+    const session = await openComposition(BASE_HTML);
+    await recordResolverParity(session, "hf-missing", "setTiming");
+    expect(lastShadow()?.sourceReadFailed).toBeUndefined();
+  });
+
+  it("empty session → ONE tagged session_empty event, no attempt, no element_not_found", async () => {
+    mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
+    flushAttemptCounts(); // drain any counts left by earlier tests
+    const session = await openComposition("<!DOCTYPE html><html><body></body></html>");
+    await recordResolverParity(session, "hf-anything", "setTiming");
+    await recordResolverParity(session, "hf-other", "setTiming"); // no re-emit
+    const events = trackedEvents.filter((e) => e.event === "sdk_resolver_shadow");
+    expect(events).toHaveLength(1);
+    expect(events[0]?.props.sessionEmpty).toBe(true);
+    expect(JSON.stringify(events[0]?.props.mismatches)).toContain("session_empty");
+    expect(JSON.stringify(events[0]?.props.mismatches)).not.toContain("element_not_found");
+    expect(flushAttemptCounts()).toBeNull(); // can't cut over → not in the denominator
   });
 
   it("tags sourceLooseMatchOnly when hfId matches source only as plain text, not a data-hf-id attribute", async () => {
@@ -469,6 +519,12 @@ const GSAP_HTML = /* html */ `<!DOCTYPE html>
   <script>var tl = gsap.timeline({ paused: true }); tl.to("[data-hf-id=\\"hf-box\\"]", { x: 100, duration: 1 }, 0);</script>
 </body></html>`;
 
+const GSAP_UNMATCHED_SELECTOR_HTML = /* html */ `<!DOCTYPE html>
+<html><body>
+  <div data-hf-id="hf-box" style="color: red">Hello</div>
+  <script>var tl = gsap.timeline({ paused: true }); tl.to("#coral-band", { x: 100, duration: 1 }, 3);</script>
+</body></html>`;
+
 describe("G. recordAnimationResolverParity", () => {
   it("emits animation_not_found when the SDK cannot resolve the animationId", async () => {
     mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
@@ -495,6 +551,17 @@ describe("G. recordAnimationResolverParity", () => {
     recordAnimationResolverParity(session, "no-such-anim", "setGsapTween");
     expect(trackedEvents).toHaveLength(0);
   });
+
+  it("emits nothing when the animationId only resolves via getAllAnimationIds (no live DOM match) — repro of the v0.7.31 false-positive", async () => {
+    mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
+    const session = await openComposition(GSAP_UNMATCHED_SELECTOR_HTML);
+    const unmatchedId = [...session.getAllAnimationIds()][0] ?? "";
+    expect(unmatchedId).not.toBe("");
+    // Confirms the bug this fixes: the id is NOT attached to any element.
+    expect(session.getElements().some((el) => el.animationIds.includes(unmatchedId))).toBe(false);
+    recordAnimationResolverParity(session, unmatchedId, "removeAllKeyframes");
+    expect(trackedEvents.filter((e) => e.event === "sdk_resolver_shadow")).toHaveLength(0);
+  });
 });
 
 // ─── H. Inlined sub-composition: bare leaf id resolves (regression) ───────────

package/src/utils/sdkResolverShadow.ts

@@ -24,7 +24,12 @@ import { trackStudioEvent, flushViaBeacon } from "./studioTelemetry";
 // ─── Types ────────────────────────────────────────────────────────────────────
 
 export interface SdkResolverMismatch {
-  kind: "element_not_found" | "value_mismatch" | "dispatch_error" | "animation_not_found";
+  kind:
+    | "element_not_found"
+    | "value_mismatch"
+    | "dispatch_error"
+    | "animation_not_found"
+    | "session_empty";
   hfId?: string;
   animationId?: string;
   property?: string;
@@ -347,6 +352,34 @@ function redactMismatches(mismatches: SdkResolverMismatch[]): SdkResolverMismatc
  * (see below). The session is shared with the cutover path, so it MUST end the
  * call exactly as it started.
  */
+// Sessions whose empty-session modeling gap has already been reported — one
+// event per session instance, not one per edit (the per-edit storm is noise;
+// the EXISTENCE of the gap is the signal).
+const emptySessionReported = new WeakSet<Composition>();
+
+/**
+ * An empty session structurally cannot resolve ANY id — a modeling gap (empty
+ * file, comp shape the SDK can't parse into elements), not a resolver
+ * divergence, and it can't cut over either, so it stays out of the attempt
+ * denominator. But silence would blind the tripwire to exactly the class that
+ * exposed the template-comp bug — so emit ONE distinguishable `session_empty`
+ * event per session, then skip. Returns true when the caller should skip.
+ */
+function reportEmptySession(session: Composition, opLabel: string): boolean {
+  if (session.getElements().length !== 0) return false;
+  if (!emptySessionReported.has(session)) {
+    emptySessionReported.add(session);
+    trackStudioEvent("sdk_resolver_shadow", {
+      opLabel,
+      sessionEmpty: true,
+      sessionElementCount: 0,
+      mismatchCount: 1,
+      mismatches: JSON.stringify([{ kind: "session_empty" } satisfies SdkResolverMismatch]),
+    });
+  }
+  return true;
+}
+
 export function runResolverShadow(
   session: Composition,
   hfId: string | null | undefined,
@@ -356,6 +389,7 @@ export function runResolverShadow(
   if (!STUDIO_SDK_RESOLVER_SHADOW_ENABLED) return;
   if (!hfId) return;
   try {
+    if (reportEmptySession(session, "dom-edit")) return;
     recordAttempt("dom-edit");
     const mismatches = sdkResolverShadowCheck(session, hfId, ops, sourceContent);
     // Emit only on divergence — parity is silent, matching recordResolverParity
@@ -409,6 +443,7 @@ export async function recordResolverParity(
   if (!STUDIO_SDK_RESOLVER_SHADOW_ENABLED) return;
   if (!session || !hfId) return;
   try {
+    if (reportEmptySession(session, opLabel)) return;
     recordAttempt(opLabel);
     if (resolveSnapshot(session, hfId)) return; // resolves — parity, nothing to record
     // Capture BEFORE any await: this call is fire-and-forget (`void recordResolverParity(...)`)
@@ -419,11 +454,13 @@ export async function recordResolverParity(
     const sessionElementCount = session.getElements().length;
     // Cheap check passed above, so the source read only runs on a real divergence.
     let source: string | undefined;
+    let sourceReadFailed = false;
     if (readSource) {
       try {
         source = await readSource();
       } catch {
         source = undefined; // fail-open: a read error must not drop a real divergence
+        sourceReadFailed = true;
       }
     }
     // Runtime-generated node the static parse can't model — suppress (mirrors the dom-edit path).
@@ -444,6 +481,9 @@ export async function recordResolverParity(
       // Lets telemetry consumers filter this cohort without parsing the
       // sourceHfIdCount comment above.
       ...(strictCount === 0 ? { sourceLooseMatchOnly: true } : {}),
+      // The reader was wired but threw — distinguishes "read failed, emitted
+      // fail-open without the suppression/count checks" from "no reader wired".
+      ...(sourceReadFailed ? { sourceReadFailed: true } : {}),
       mismatchCount: 1,
       mismatches: JSON.stringify([
         { kind: "element_not_found", hfId } satisfies SdkResolverMismatch,
@@ -459,8 +499,9 @@ export async function recordResolverParity(
  * dispatching. Read-only: emits `animation_not_found` when the SDK can't resolve
  * the animationId the server GSAP path is addressing — the GSAP-edit-surface
  * analogue of element_not_found. The SDK's resolvable animation ids are the
- * located ids attached to elements (buildAnimationIdMap), so a target absent
- * from every element's animationIds is a resolver divergence.
+ * located ids attached to elements (buildAnimationIdMap) OR any id parsed from
+ * the script regardless of DOM match (getAllAnimationIds) — a target absent
+ * from both is a resolver divergence.
  *
  * No-op when the shadow flag is off; never throws; never mutates the session.
  */
@@ -474,7 +515,9 @@ export function recordAnimationResolverParity(
   try {
     recordAttempt(opLabel);
     const elements = session.getElements();
-    const resolves = elements.some((el) => el.animationIds.includes(animationId));
+    const resolves =
+      elements.some((el) => el.animationIds.includes(animationId)) ||
+      session.getAllAnimationIds().has(animationId);
     if (resolves) return; // SDK locates the animation — parity
     trackStudioEvent("sdk_resolver_shadow", {
       animationId,

package/src/utils/studioPendingEdits.test.ts

@@ -0,0 +1,43 @@
+// @vitest-environment jsdom
+import { describe, expect, it, vi } from "vitest";
+import {
+  addStudioPendingEditFlushListener,
+  flushStudioPendingEdits,
+  trackStudioPendingEdit,
+} from "./studioPendingEdits";
+
+describe("studio pending edit flush", () => {
+  it("waits for mounted panels to persist pending local edits", async () => {
+    const persist = vi.fn(async () => undefined);
+    const remove = addStudioPendingEditFlushListener(persist);
+
+    try {
+      await flushStudioPendingEdits();
+      expect(persist).toHaveBeenCalledTimes(1);
+    } finally {
+      remove();
+    }
+  });
+
+  it("waits for edits already started by unmounted panels", async () => {
+    const steps: string[] = [];
+    let resolvePersist!: () => void;
+    trackStudioPendingEdit(
+      new Promise<void>((resolve) => {
+        resolvePersist = resolve;
+      }).then(() => {
+        steps.push("persisted");
+      }),
+    );
+
+    const flushed = flushStudioPendingEdits().then(() => {
+      steps.push("flushed");
+    });
+    await Promise.resolve();
+    expect(steps).toEqual([]);
+
+    resolvePersist();
+    await flushed;
+    expect(steps).toEqual(["persisted", "flushed"]);
+  });
+});

package/src/utils/studioPendingEdits.ts

@@ -0,0 +1,45 @@
+const STUDIO_FLUSH_PENDING_EDITS_EVENT = "hf-studio-flush-pending-edits";
+
+interface StudioFlushPendingEditsDetail {
+  promises: Array<Promise<unknown>>;
+}
+
+const pendingEditPromises = new Set<Promise<unknown>>();
+
+export function trackStudioPendingEdit(
+  result: Promise<unknown> | unknown,
+): Promise<unknown> | undefined {
+  if (!result) return undefined;
+  const promise = Promise.resolve(result);
+  pendingEditPromises.add(promise);
+  promise.then(
+    () => pendingEditPromises.delete(promise),
+    () => pendingEditPromises.delete(promise),
+  );
+  return promise;
+}
+
+export async function flushStudioPendingEdits(): Promise<void> {
+  const detail: StudioFlushPendingEditsDetail = { promises: [] };
+  window.dispatchEvent(
+    new CustomEvent<StudioFlushPendingEditsDetail>(STUDIO_FLUSH_PENDING_EDITS_EVENT, { detail }),
+  );
+  while (detail.promises.length > 0 || pendingEditPromises.size > 0) {
+    const promises = [...detail.promises, ...pendingEditPromises];
+    detail.promises = [];
+    await Promise.allSettled(promises);
+  }
+}
+
+export function addStudioPendingEditFlushListener(
+  handler: () => Promise<unknown> | unknown,
+): () => void {
+  const listener = (event: Event) => {
+    const detail = (event as CustomEvent<StudioFlushPendingEditsDetail>).detail;
+    if (!detail?.promises) return;
+    const promise = trackStudioPendingEdit(handler());
+    if (promise) detail.promises.push(promise);
+  };
+  window.addEventListener(STUDIO_FLUSH_PENDING_EDITS_EVENT, listener);
+  return () => window.removeEventListener(STUDIO_FLUSH_PENDING_EDITS_EVENT, listener);
+}

package/src/utils/studioUiPreferences.ts

@@ -7,6 +7,7 @@ export interface StoredPreviewZoomState {
 export interface StudioUiPreferences {
   leftCollapsed?: boolean;
   timelineVisible?: boolean;
+  timelineHeight?: number;
   playbackRate?: number;
   audioMuted?: boolean;
   previewZoom?: StoredPreviewZoomState;
@@ -48,6 +49,9 @@ function readStorage(storage: Storage | null): StudioUiPreferences {
     if (typeof parsed.timelineVisible === "boolean") {
       preferences.timelineVisible = parsed.timelineVisible;
     }
+    if (typeof parsed.timelineHeight === "number" && Number.isFinite(parsed.timelineHeight)) {
+      preferences.timelineHeight = parsed.timelineHeight;
+    }
     if (typeof parsed.playbackRate === "number" && Number.isFinite(parsed.playbackRate)) {
       preferences.playbackRate = parsed.playbackRate;
     }