@hyperframes/studio 0.8.72 → 0.8.73

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.72",
+  "version": "0.8.73",
   "description": "",
   "repository": {
     "type": "git",
@@ -52,11 +52,11 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.72",
-    "@hyperframes/parsers": "0.8.72",
-    "@hyperframes/player": "0.8.72",
-    "@hyperframes/studio-server": "0.8.72",
-    "@hyperframes/sdk": "0.8.72"
+    "@hyperframes/core": "0.8.73",
+    "@hyperframes/sdk": "0.8.73",
+    "@hyperframes/player": "0.8.73",
+    "@hyperframes/studio-server": "0.8.73",
+    "@hyperframes/parsers": "0.8.73"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -72,7 +72,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.72"
+    "@hyperframes/producer": "0.8.73"
   },
   "peerDependencies": {
     "react": "19",

package/src/hooks/appHotkeysDispatch.ts

@@ -8,6 +8,7 @@ import { isEditableTarget } from "../utils/timelineDiscovery";
 import { shouldIgnoreHistoryShortcut } from "../utils/studioHelpers";
 import { canSplitElement } from "../utils/timelineElementSplit";
 import { trackStudioEvent } from "../utils/studioTelemetry";
+import { STUDIO_PLAIN_KEYS } from "../player/components/studioShortcuts";
 
 // Extracted from useAppHotkeys.ts to keep it under the studio 600-line cap,
 // following useTimelineDeleteOps's precedent. Pure functions, no hooks — the
@@ -158,7 +159,7 @@ export function dispatchModifierKey(
  *  Delete arbitration between keyframes, an automation range and the clip can
  *  be asserted without standing up the whole hook. */
 export function dispatchPlainKey(event: KeyboardEvent, key: string, cb: HotkeyCallbacks): void {
-  if (key === "f" && !event.shiftKey && !event.altKey) {
+  if (key === STUDIO_PLAIN_KEYS.fullscreen && !event.shiftKey && !event.altKey) {
     event.preventDefault();
     if (document.fullscreenElement) void document.exitFullscreen();
     else
@@ -166,7 +167,7 @@ export function dispatchPlainKey(event: KeyboardEvent, key: string, cb: HotkeyCa
     return;
   }
 
-  if (event.key === "s" && !event.altKey) {
+  if (event.key === STUDIO_PLAIN_KEYS.split && !event.altKey) {
     // Reserve bare `s` for Split even when the current selection cannot split,
     // so secondary listeners do not reinterpret the same key as Snap toggle.
     event.preventDefault();
@@ -274,7 +275,12 @@ export function dispatchPlainKey(event: KeyboardEvent, key: string, cb: HotkeyCa
     return;
   }
 
-  if (event.key === "r" && !event.shiftKey && !event.altKey && cb.onToggleRecording) {
+  if (
+    event.key === STUDIO_PLAIN_KEYS.record &&
+    !event.shiftKey &&
+    !event.altKey &&
+    cb.onToggleRecording
+  ) {
     event.preventDefault();
     cb.onToggleRecording();
   }

package/src/index.ts

@@ -35,6 +35,8 @@ export type { ToggleProps } from "./components/ui/Toggle";
 export { EditorShell } from "./components/EditorShell";
 export type { EditorShellProps } from "./components/EditorShell";
 export { NLEPreview } from "./components/nle/NLEPreview";
+export { DEFAULT_SHORTCUT_SECTIONS } from "./player/components/studioShortcuts";
+export type { ShortcutHint, ShortcutSection } from "./player/components/studioShortcuts";
 export { CompositionBreadcrumb } from "./components/nle/CompositionBreadcrumb";
 export type { CompositionLevel } from "./components/nle/CompositionBreadcrumb";
 

package/src/player/components/PlayerControls.tsx

@@ -7,6 +7,7 @@ import { trackStudioEvent } from "../../utils/studioTelemetry";
 import { Tooltip } from "../../components/ui";
 import { useMountEffect } from "../../hooks/useMountEffect";
 import { ShortcutsPanel } from "./ShortcutsPanel";
+import type { ShortcutSection } from "./studioShortcuts";
 import { SpeedMenu } from "./SpeedMenu";
 import { VolumeControl } from "./VolumeControl";
 
@@ -161,6 +162,8 @@ interface PlayerControlsProps {
   disabled?: boolean;
   isFullscreen?: boolean;
   onToggleFullscreen?: () => void;
+  /** Replaces the shortcuts panel's list, e.g. DEFAULT_SHORTCUT_SECTIONS with entries dropped or relabelled. */
+  shortcutSections?: readonly ShortcutSection[];
 }
 
 export const PlayerControls = memo(function PlayerControls({
@@ -169,6 +172,7 @@ export const PlayerControls = memo(function PlayerControls({
   disabled = false,
   isFullscreen = false,
   onToggleFullscreen,
+  shortcutSections,
 }: PlayerControlsProps) {
   const isPlaying = usePlayerStore((s) => s.isPlaying);
   const duration = usePlayerStore((s) => s.duration);
@@ -291,6 +295,7 @@ export const PlayerControls = memo(function PlayerControls({
             setInPoint={setInPoint}
             setOutPoint={setOutPoint}
             onSeek={onSeek}
+            sections={shortcutSections}
           />
         </div>
       </div>

package/src/player/components/ShortcutsPanel.test.tsx

@@ -3,6 +3,8 @@
 import React, { act, Profiler } from "react";
 import { describe, expect, it, vi } from "vitest";
 import { ShortcutsPanel } from "./ShortcutsPanel";
+import { PlayerControls } from "./PlayerControls";
+import { DEFAULT_SHORTCUT_SECTIONS, type ShortcutSection } from "./studioShortcuts";
 import { createHappyDomRootHarness } from "./testRootHarness";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
@@ -149,4 +151,53 @@ describe("ShortcutsPanel", () => {
     expect(panel?.getAttribute("aria-modal")).toBeNull();
     expect(panel?.id).toBe(panelId);
   });
+
+  it("lists what an embedder passes to PlayerControls instead of Studio's defaults", () => {
+    const listed = (sections?: readonly ShortcutSection[]) => {
+      const host = document.createElement("div");
+      document.body.append(host);
+      act(() => {
+        mount(host).render(
+          <PlayerControls onTogglePlay={vi.fn()} onSeek={vi.fn()} shortcutSections={sections} />,
+        );
+      });
+      openPanel(host.querySelector<HTMLButtonElement>('button[aria-label="Shortcuts and tools"]')!);
+      return host.textContent ?? "";
+    };
+    const withoutSplit = DEFAULT_SHORTCUT_SECTIONS.map((section) => ({
+      ...section,
+      hints: section.hints.filter((hint) => hint.label !== "Split clip at playhead"),
+    }));
+
+    expect(listed()).toContain("Split clip at playhead");
+    expect(listed(withoutSplit)).not.toContain("Split clip at playhead");
+    expect(listed(withoutSplit)).toContain("Toggle fullscreen");
+  });
+
+  it("renders an embedder list that repeats a key or a section title without key clashes", () => {
+    const errors = vi.spyOn(console, "error").mockImplementation(() => {});
+    const host = document.createElement("div");
+    document.body.append(host);
+    const sections = [
+      {
+        title: "Keys",
+        hints: [
+          { key: "S", label: "Select" },
+          { key: "S", label: "Snap" },
+        ],
+      },
+      { title: "Keys", hints: [{ key: "V", label: "Move" }] },
+    ];
+    act(() => {
+      mount(host).render(
+        <PlayerControls onTogglePlay={vi.fn()} onSeek={vi.fn()} shortcutSections={sections} />,
+      );
+    });
+    openPanel(host.querySelector<HTMLButtonElement>('button[aria-label="Shortcuts and tools"]')!);
+
+    expect(host.textContent).toContain("Select");
+    expect(host.textContent).toContain("Snap");
+    expect(errors.mock.calls.flat().join(" ")).not.toMatch(/same key/);
+    errors.mockRestore();
+  });
 });

package/src/player/components/ShortcutsPanel.tsx

@@ -2,92 +2,7 @@ import { useState, useCallback, useEffect, useId, useRef, memo } from "react";
 import { formatTime, frameToSeconds } from "../lib/time";
 import { Tooltip } from "../../components/ui";
 import { useContextMenuDismiss } from "../../hooks/useContextMenuDismiss";
-
-const SHORTCUT_SECTIONS = [
-  {
-    title: "Playback",
-    hints: [
-      { key: "Space", label: "Play / Pause" },
-      { key: "J", label: "Play backward" },
-      { key: "K", label: "Stop" },
-      { key: "L", label: "Play forward" },
-      { key: "M", label: "Toggle mute" },
-      { key: "⇧L", label: "Toggle loop" },
-      { key: "←/→", label: "Step 1 frame" },
-      { key: "⇧←/⇧→", label: "Step 10 frames" },
-      { key: "F", label: "Toggle fullscreen" },
-    ],
-  },
-  {
-    title: "Keyframes (when an element is selected)",
-    hints: [
-      { key: "K", label: "Add keyframe at playhead" },
-      { key: "Del", label: "Delete selected keyframe" },
-      { key: "H", label: "Toggle hold / bezier" },
-      { key: "U", label: "Expand / collapse properties" },
-      { key: "R", label: "Record gesture" },
-    ],
-  },
-  {
-    title: "Editing",
-    hints: [
-      { key: "⌘Z", label: "Undo" },
-      { key: "⌘⇧Z", label: "Redo" },
-      { key: "⌘C", label: "Copy element" },
-      { key: "⌘V", label: "Paste element" },
-      { key: "⌘X", label: "Cut element" },
-      { key: "S", label: "Split clip at playhead" },
-      { key: "⇧Click", label: "Razor tool: split all tracks" },
-      { key: "⌘G", label: "Group elements" },
-      { key: "⌘⇧G", label: "Ungroup" },
-      { key: "Del", label: "Delete selected element (no keyframe selected)" },
-    ],
-  },
-  {
-    title: "Gesture recording modifiers",
-    hints: [
-      { key: "Drag", label: "Record x / y position" },
-      { key: "Scroll", label: "Record z depth" },
-      { key: "⇧ Drag", label: "Record rotationX / rotationY" },
-      { key: "⌥ Drag", label: "Record rotation" },
-      { key: "⌘ Drag↕", label: "Record opacity" },
-      { key: "⌘ Scroll", label: "Record scale" },
-    ],
-  },
-  {
-    title: "Canvas",
-    hints: [
-      { key: "Drag", label: "Move element / add keyframe" },
-      { key: "⌥ Drag", label: "Move entire animation path" },
-      { key: "⇧ Drag", label: "Uniform resize" },
-    ],
-  },
-  {
-    title: "Crop",
-    hints: [
-      { key: "Drag edge", label: "Crop a side" },
-      { key: "Drag center", label: "Reposition the crop" },
-    ],
-  },
-  {
-    title: "Panels",
-    hints: [
-      { key: "⌘1", label: "Compositions tab" },
-      { key: "⌘2", label: "Assets tab" },
-    ],
-  },
-  {
-    title: "Work area",
-    hints: [
-      { key: "I", label: "Set in-point" },
-      { key: "⇧I", label: "Clear in-point" },
-      { key: "O", label: "Set out-point" },
-      { key: "⇧O", label: "Clear out-point" },
-      { key: "A", label: "Jump to in-point" },
-      { key: "E", label: "Jump to out-point" },
-    ],
-  },
-] as const;
+import { DEFAULT_SHORTCUT_SECTIONS, type ShortcutSection } from "./studioShortcuts";
 
 interface ShortcutsPanelProps {
   disabled: boolean;
@@ -97,6 +12,7 @@ interface ShortcutsPanelProps {
   setInPoint: (v: number | null) => void;
   setOutPoint: (v: number | null) => void;
   onSeek: (time: number) => void;
+  sections?: readonly ShortcutSection[];
 }
 
 export const ShortcutsPanel = memo(function ShortcutsPanel({
@@ -107,6 +23,7 @@ export const ShortcutsPanel = memo(function ShortcutsPanel({
   setInPoint,
   setOutPoint,
   onSeek,
+  sections = DEFAULT_SHORTCUT_SECTIONS,
 }: ShortcutsPanelProps) {
   const [showShortcuts, setShowShortcuts] = useState(false);
   const [jumpFrame, setJumpFrame] = useState("");
@@ -319,14 +236,14 @@ export const ShortcutsPanel = memo(function ShortcutsPanel({
           </div>
           <div style={{ borderTop: "1px solid rgba(255,255,255,0.06)" }} />
           <div className="px-3 pt-2.5 pb-3 flex flex-col gap-3">
-            {SHORTCUT_SECTIONS.map((section) => (
-              <div key={section.title}>
+            {sections.map((section, sectionIndex) => (
+              <div key={sectionIndex}>
                 <p className="text-[9px] font-medium text-neutral-500 uppercase tracking-wider mb-1.5">
                   {section.title}
                 </p>
                 <div className="flex flex-col gap-1">
-                  {section.hints.map((hint) => (
-                    <div key={hint.key} className="flex items-center gap-3">
+                  {section.hints.map((hint, hintIndex) => (
+                    <div key={hintIndex} className="flex items-center gap-3">
                       <span
                         className="font-mono text-[10px] rounded-sm border border-neutral-700 px-1.5 py-0.5 text-neutral-300 min-w-[36px] text-center"
                         style={{ background: "rgba(255,255,255,0.05)" }}

package/src/player/components/studioShortcuts.ts

@@ -0,0 +1,101 @@
+/** Bare keys Studio's app hotkeys bind; the shortcuts list names them from here. */
+export const STUDIO_PLAIN_KEYS = { fullscreen: "f", split: "s", record: "r" } as const;
+
+export interface ShortcutHint {
+  key: string;
+  label: string;
+}
+
+export interface ShortcutSection {
+  title: string;
+  hints: readonly ShortcutHint[];
+}
+
+const hintKey = (key: string) => key.toUpperCase();
+
+/** What PlayerControls' shortcuts panel lists unless an embedder passes its own sections. */
+export const DEFAULT_SHORTCUT_SECTIONS: readonly ShortcutSection[] = [
+  {
+    title: "Playback",
+    hints: [
+      { key: "Space", label: "Play / Pause" },
+      { key: "J", label: "Play backward" },
+      { key: "K", label: "Stop" },
+      { key: "L", label: "Play forward" },
+      { key: "M", label: "Toggle mute" },
+      { key: "⇧L", label: "Toggle loop" },
+      { key: "←/→", label: "Step 1 frame" },
+      { key: "⇧←/⇧→", label: "Step 10 frames" },
+      { key: hintKey(STUDIO_PLAIN_KEYS.fullscreen), label: "Toggle fullscreen" },
+    ],
+  },
+  {
+    title: "Keyframes (when an element is selected)",
+    hints: [
+      { key: "K", label: "Add keyframe at playhead" },
+      { key: "Del", label: "Delete selected keyframe" },
+      { key: "H", label: "Toggle hold / bezier" },
+      { key: "U", label: "Expand / collapse properties" },
+      { key: hintKey(STUDIO_PLAIN_KEYS.record), label: "Record gesture" },
+    ],
+  },
+  {
+    title: "Editing",
+    hints: [
+      { key: "⌘Z", label: "Undo" },
+      { key: "⌘⇧Z", label: "Redo" },
+      { key: "⌘C", label: "Copy element" },
+      { key: "⌘V", label: "Paste element" },
+      { key: "⌘X", label: "Cut element" },
+      { key: hintKey(STUDIO_PLAIN_KEYS.split), label: "Split clip at playhead" },
+      { key: "⇧Click", label: "Razor tool: split all tracks" },
+      { key: "⌘G", label: "Group elements" },
+      { key: "⌘⇧G", label: "Ungroup" },
+      { key: "Del", label: "Delete selected element (no keyframe selected)" },
+    ],
+  },
+  {
+    title: "Gesture recording modifiers",
+    hints: [
+      { key: "Drag", label: "Record x / y position" },
+      { key: "Scroll", label: "Record z depth" },
+      { key: "⇧ Drag", label: "Record rotationX / rotationY" },
+      { key: "⌥ Drag", label: "Record rotation" },
+      { key: "⌘ Drag↕", label: "Record opacity" },
+      { key: "⌘ Scroll", label: "Record scale" },
+    ],
+  },
+  {
+    title: "Canvas",
+    hints: [
+      { key: "Drag", label: "Move element / add keyframe" },
+      { key: "⌥ Drag", label: "Move entire animation path" },
+      { key: "⇧ Drag", label: "Uniform resize" },
+    ],
+  },
+  {
+    title: "Crop",
+    hints: [
+      { key: "Drag edge", label: "Crop a side" },
+      { key: "Drag center", label: "Reposition the crop" },
+    ],
+  },
+  {
+    title: "Panels",
+    hints: [
+      { key: "⌘1", label: "Compositions tab" },
+      { key: "⌘2", label: "Assets tab" },
+    ],
+  },
+  {
+    title: "Work area",
+    hints: [
+      { key: "I", label: "Set in-point" },
+      { key: "⇧I", label: "Clear in-point" },
+      { key: "O", label: "Set out-point" },
+      { key: "⇧O", label: "Clear out-point" },
+      { key: "A", label: "Jump to in-point" },
+      { key: "E", label: "Jump to out-point" },
+    ],
+  },
+];

package/src/player/components/useTimelinePlayhead.test.tsx

@@ -0,0 +1,65 @@
+// @vitest-environment happy-dom
+
+import { act, createRef } from "react";
+import { createRoot } from "react-dom/client";
+import { describe, expect, it } from "vitest";
+import { useTimelinePlayhead } from "./useTimelinePlayhead";
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+function scrollBox(scrollLeft: number) {
+  const el = document.createElement("div");
+  let left = scrollLeft;
+  Object.defineProperties(el, {
+    clientWidth: { value: 800 },
+    scrollWidth: { value: 20_000 },
+    scrollLeft: { get: () => left, set: (v: number) => (left = v) },
+  });
+  return el;
+}
+
+function Harness({ pps, scroll }: { pps: number; scroll: HTMLDivElement }) {
+  useTimelinePlayhead({
+    playheadRef: createRef(),
+    scrollRef: { current: scroll },
+    ppsRef: { current: pps },
+    durationRef: { current: 60 },
+    isDragging: { current: false },
+    currentTime: 0,
+    zoomMode: "manual",
+    manualZoomPercent: 100,
+    zoomModeRef: { current: "manual" },
+    manualZoomPercentRef: { current: 100 },
+    fitPps: pps,
+    fitPpsRef: { current: pps },
+    effectiveDuration: 60,
+    pps,
+    timelineReady: true,
+    elementsLength: 1,
+    setZoomMode: () => {},
+    setManualZoomPercent: () => {},
+    contentOrigin: 32,
+  });
+  return null;
+}
+
+function zoom(scrollLeft: number, fromPps: number, toPps: number) {
+  const scroll = scrollBox(scrollLeft);
+  const host = document.createElement("div");
+  const root = createRoot(host);
+  act(() => root.render(<Harness pps={fromPps} scroll={scroll} />));
+  act(() => root.render(<Harness pps={toPps} scroll={scroll} />));
+  act(() => root.unmount());
+  return scroll.scrollLeft;
+}
+
+describe("useTimelinePlayhead centre anchor", () => {
+  it("keeps a view at the start at the start when the scale changes", () => {
+    expect(zoom(0, 100, 114)).toBe(0);
+  });
+
+  it("keeps the time at the viewport centre when the view is scrolled", () => {
+    // Centre time (400 + 400 - 32) / 100 = 7.68s lands at 32 + 7.68 * 200 - 400.
+    expect(zoom(400, 100, 200)).toBe(1168);
+  });
+});

package/src/player/components/useTimelinePlayhead.ts

@@ -75,7 +75,8 @@ export function useTimelinePlayhead({
     // it true and the next toolbar zoom would wrongly skip center-anchoring.
     const skip = skipCenterAnchorRef.current;
     skipCenterAnchorRef.current = false;
-    if (!scroll || pps === prevPps || skip) return;
+    // A view at the start stays there: a resize or a host zoom must not hide 00:00.
+    if (!scroll || pps === prevPps || skip || scroll.scrollLeft < 1) return;
     const nextScrollLeft = getTimelineScrollLeftForZoomAnchor({
       pointerX: scroll.clientWidth / 2,
       currentScrollLeft: scroll.scrollLeft,

package/src/player/hooks/useShadowPreviewReload.ts

@@ -15,10 +15,12 @@ import {
 import type { PlaybackAdapter } from "../lib/playbackTypes";
 import { thumbnailScheduler } from "../lib/thumbnailScheduler";
 
-// The single wait budget for a shadow: the player's 8s asset cap plus its 0.42s loader fade
+// One wait budget for a shadow: the player's 8s asset cap plus its 0.42s loader fade
 // leaves about 6.5s for the document load and runtime boot. Nothing shorter may fail the swap.
 // It only runs while the tab is visible: readiness is frame-driven, and a hidden tab renders none.
 export const SHADOW_READY_TIMEOUT_MS = 15_000;
+// A busy machine can need more than one budget; the shadow keeps loading for this many before it is dropped.
+export const SHADOW_READY_BUDGETS = 3;
 
 function isDocumentHidden(): boolean {
   return typeof document !== "undefined" && document.visibilityState === "hidden";
@@ -61,6 +63,7 @@ export function useShadowPreviewReload({
   const onReloadFailedRef = useRef(onReloadFailed);
   onReloadFailedRef.current = onReloadFailed;
   const readyTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  const budgetsSpentRef = useRef(0);
   // The shadow still owed a wait budget, so a hidden tab can resume it when it becomes visible.
   const budgetGenRef = useRef<number | null>(null);
   const cancelPendingLoadRef = useRef<() => void>(() => {});
@@ -160,10 +163,16 @@ export function useShadowPreviewReload({
     (gen: number) => {
       clearTimeout(readyTimerRef.current);
       if (isDocumentHidden()) return;
-      readyTimerRef.current = setTimeout(
-        () => failShadow(gen, "it took too long to load"),
-        SHADOW_READY_TIMEOUT_MS,
-      );
+      readyTimerRef.current = setTimeout(() => {
+        if (gen !== shadowGenRef.current) return;
+        budgetsSpentRef.current += 1;
+        if (budgetsSpentRef.current < SHADOW_READY_BUDGETS) {
+          logReload("shadow-slow", { budgetsSpent: budgetsSpentRef.current });
+          armReadyTimerRef.current(gen);
+          return;
+        }
+        failShadow(gen, "it took too long to load");
+      }, SHADOW_READY_TIMEOUT_MS);
     },
     [failShadow],
   );
@@ -176,6 +185,7 @@ export function useShadowPreviewReload({
       const gen = shadowGenRef.current;
       stopPendingShadow();
       budgetGenRef.current = gen;
+      budgetsSpentRef.current = 0;
       armReadyTimer(gen);
       setPreviewSlots((prev) => planShadowReload(prev, gen, url));
       // Thumbnails of the edit wait for the new preview instead of competing with it.

package/src/player/hooks/useTimelinePlayer.shadowReload.test.ts

@@ -4,7 +4,7 @@
 import React, { act } from "react";
 import { createRoot } from "react-dom/client";
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { SHADOW_READY_TIMEOUT_MS } from "./useShadowPreviewReload";
+import { SHADOW_READY_BUDGETS, SHADOW_READY_TIMEOUT_MS } from "./useShadowPreviewReload";
 import { usePlayerStore } from "../store/playerStore";
 import { NLEProvider, useNLEContext, type NLEContextValue } from "../../components/nle/NLEContext";
 import {
@@ -16,6 +16,8 @@ import {
 
 globalThis.IS_REACT_ACT_ENVIRONMENT = true;
 
+const FULL_WAIT_MS = SHADOW_READY_TIMEOUT_MS * SHADOW_READY_BUDGETS;
+
 vi.mock("../../utils/gsapSoftReload", async (importOriginal) => ({
   ...(await importOriginal<typeof import("../../utils/gsapSoftReload")>()),
   ensureMotionPathPluginLoaded: vi.fn(),
@@ -258,7 +260,7 @@ describe("shadow reload readiness and failure", () => {
     const { getApi, live, root } = beginReload({ onPreviewReloadFailed });
     expect(getApi().previewSlots).toHaveLength(2);
 
-    act(() => void vi.advanceTimersByTime(SHADOW_READY_TIMEOUT_MS));
+    act(() => void vi.advanceTimersByTime(FULL_WAIT_MS));
 
     expect(getApi().previewSlots).toEqual([{ gen: 0, role: "live" }]);
     expect(getApi().iframeRef.current).toBe(live);
@@ -268,7 +270,7 @@ describe("shadow reload readiness and failure", () => {
     unmount(root);
   });
 
-  it("keeps a slow shadow pending past 5s and fails it only at the single budget", () => {
+  it("keeps a slow shadow pending past 5s and fails it only once all budgets are spent", () => {
     vi.useFakeTimers();
     vi.spyOn(console, "error").mockImplementation(() => {});
     const onPreviewReloadFailed = vi.fn();
@@ -283,12 +285,47 @@ describe("shadow reload readiness and failure", () => {
     expect(getApi().previewSlots).toHaveLength(2);
     expect(onPreviewReloadFailed).not.toHaveBeenCalled();
 
-    act(() => void vi.advanceTimersByTime(SHADOW_READY_TIMEOUT_MS));
+    act(() => void vi.advanceTimersByTime(FULL_WAIT_MS - 5001 - 1));
+    expect(onPreviewReloadFailed).not.toHaveBeenCalled();
+    act(() => void vi.advanceTimersByTime(1));
     expect(getApi().previewSlots).toEqual([{ gen: 0, role: "live" }]);
     expect(onPreviewReloadFailed).toHaveBeenCalledWith(expect.stringContaining("too long"));
     unmount(root);
   });
 
+  // A busy machine: the edit's shadow paints after one budget; dropping it left the stage on the pre-edit file.
+  it("promotes a shadow that paints after its first budget instead of dropping the edit", () => {
+    vi.useFakeTimers();
+    const onPreviewReloadFailed = vi.fn();
+    const { getApi, gen, root } = beginReload({ onPreviewReloadFailed });
+    const shadow = makeShadowWithSpies();
+    act(() => {
+      getApi().setShadowIframeNode(shadow.iframe);
+      getApi().onShadowIframeLoad(gen);
+    });
+
+    act(() => void vi.advanceTimersByTime(SHADOW_READY_TIMEOUT_MS + 2000));
+    expect(onPreviewReloadFailed).not.toHaveBeenCalled();
+    act(() => getApi().onShadowReadyChange(gen, true));
+    expect(getApi().iframeRef.current).toBe(shadow.iframe);
+    unmount(root);
+  });
+
+  it("gives a reload that replaces a slow one its own full set of budgets", () => {
+    vi.useFakeTimers();
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const onPreviewReloadFailed = vi.fn();
+    const { getApi, root } = beginReload({ onPreviewReloadFailed });
+    act(() => void vi.advanceTimersByTime(SHADOW_READY_TIMEOUT_MS + 1000));
+
+    act(() => getApi().refreshPlayer());
+    act(() => void vi.advanceTimersByTime(FULL_WAIT_MS - 1));
+    expect(onPreviewReloadFailed).not.toHaveBeenCalled();
+    act(() => void vi.advanceTimersByTime(1));
+    expect(onPreviewReloadFailed).toHaveBeenCalledWith(expect.stringContaining("too long"));
+    unmount(root);
+  });
+
   it("does not spend the budget while the tab is hidden, and promotes once it is visible", () => {
     vi.useFakeTimers();
     const onPreviewReloadFailed = vi.fn();
@@ -325,7 +362,7 @@ describe("shadow reload readiness and failure", () => {
     expect(onPreviewReloadFailed).not.toHaveBeenCalled();
 
     act(() => setVisibility("visible"));
-    act(() => void vi.advanceTimersByTime(SHADOW_READY_TIMEOUT_MS - 1));
+    act(() => void vi.advanceTimersByTime(FULL_WAIT_MS - 1));
     expect(onPreviewReloadFailed).not.toHaveBeenCalled();
     act(() => void vi.advanceTimersByTime(1));
     expect(onPreviewReloadFailed).toHaveBeenCalledWith(expect.stringContaining("too long"));
@@ -431,7 +468,7 @@ describe("shadow reload store ownership and readiness", () => {
     const { getApi, rerender, root } = setup({ onPreviewReloadFailed: first });
     expect(getApi().previewSlots).toHaveLength(2);
     rerender({ onPreviewReloadFailed: latest });
-    act(() => void vi.advanceTimersByTime(SHADOW_READY_TIMEOUT_MS));
+    act(() => void vi.advanceTimersByTime(FULL_WAIT_MS));
     expect(latest).toHaveBeenCalled();
     expect(first).not.toHaveBeenCalled();
     unmount(root);