@hyperframes/studio 0.8.71 → 0.8.73

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.71",
+  "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.71",
-    "@hyperframes/parsers": "0.8.71",
-    "@hyperframes/player": "0.8.71",
-    "@hyperframes/studio-server": "0.8.71",
-    "@hyperframes/sdk": "0.8.71"
+    "@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.71"
+    "@hyperframes/producer": "0.8.73"
   },
   "peerDependencies": {
     "react": "19",

package/src/components/nle/NLEPreview.test.ts

@@ -80,6 +80,10 @@ function renderPreview(
   previewSlots: Array<{ gen: number; role: "live" | "shadow"; url?: string }> = [
     { gen: 0, role: "live" },
   ],
+  {
+    box = { width: 800, height: 600 },
+    fillBox,
+  }: { box?: { width: number; height: number }; fillBox?: boolean } = {},
 ) {
   resizeCallbacks = [];
   const host = document.createElement("div");
@@ -99,6 +103,7 @@ function renderPreview(
         onShadowError: () => {},
         setShadowIframeNode: () => {},
         resetPreviewSlots: () => {},
+        fillBox,
       }),
     );
   });
@@ -108,7 +113,7 @@ function renderPreview(
   expect(viewport).toBeTruthy();
   expect(stage).toBeTruthy();
 
-  setRect(viewport, { width: 800, height: 600 });
+  setRect(viewport, box);
   act(() => {
     for (const fire of resizeCallbacks) fire();
   });
@@ -251,6 +256,19 @@ describe("NLEPreview", () => {
     view.cleanup();
   });
 
+  it("insets the picture by default and fills a same-shape box when fillBox is on", () => {
+    const box = { width: 640, height: 360 };
+    const inset = renderPreview(undefined, { box });
+    expect([inset.stage.style.width, inset.stage.style.height]).toEqual(["611.5556px", "344px"]);
+    expect(parseFloat(inset.stage.parentElement!.style.inset)).toBe(8);
+    inset.cleanup();
+
+    const filled = renderPreview(undefined, { box, fillBox: true });
+    expect([filled.stage.style.width, filled.stage.style.height]).toEqual(["640px", "360px"]);
+    expect(parseFloat(filled.stage.parentElement!.style.inset)).toBe(0);
+    filled.cleanup();
+  });
+
   it("clips a shadow reload so its own loading overlay cannot paint over the live frame", () => {
     const view = renderPreview([
       { gen: 0, role: "live" },

package/src/components/nle/NLEPreview.tsx

@@ -36,6 +36,8 @@ interface NLEPreviewProps {
   onStageRef?: (ref: React.RefObject<HTMLDivElement | null>) => void;
   /** Reports the authored composition size measured from the loaded preview. */
   onCompositionSizeChange?: (size: PreviewCompositionSize | null) => void;
+  /** Draws the picture edge to edge in this box, without Studio's inset band. */
+  fillBox?: boolean;
 }
 
 export function getPreviewPlayerKey({
@@ -50,7 +52,7 @@ export function getPreviewPlayerKey({
 
 const ZOOM_HUD_TIMEOUT_MS = 1200;
 const ZOOM_SETTLE_MS = 200;
-const PREVIEW_STAGE_INSET_PX = 16;
+const PREVIEW_STAGE_INSET_PX = 8;
 
 // clip-path as well as visibility: the player's loading overlay sets its own
 // visibility:visible and would otherwise paint over the live frame.
@@ -87,9 +89,10 @@ export function resolvePreviewStageSize(
   compositionSize: PreviewCompositionSize | null,
   portrait: boolean | undefined,
   gutterPx = 0,
+  insetPx = PREVIEW_STAGE_INSET_PX,
 ): { width: number; height: number } {
-  const availableWidth = Math.max(0, viewportWidth - PREVIEW_STAGE_INSET_PX - 2 * gutterPx);
-  const availableHeight = Math.max(0, viewportHeight - PREVIEW_STAGE_INSET_PX - 2 * gutterPx);
+  const availableWidth = Math.max(0, viewportWidth - 2 * (insetPx + gutterPx));
+  const availableHeight = Math.max(0, viewportHeight - 2 * (insetPx + gutterPx));
   const aspectRatio =
     compositionSize && compositionSize.width > 0 && compositionSize.height > 0
       ? compositionSize.width / compositionSize.height
@@ -130,6 +133,7 @@ export const NLEPreview = memo(function NLEPreview({
   suppressLoadingOverlay,
   onStageRef,
   onCompositionSizeChange,
+  fillBox,
 }: NLEPreviewProps) {
   const activeKey = getPreviewPlayerKey({ projectId, directUrl });
   const viewportRef = useRef<HTMLDivElement>(null);
@@ -151,6 +155,7 @@ export const NLEPreview = memo(function NLEPreview({
   const reportPreviewFirstFrame = usePreviewFirstFrameTelemetry(previewSlots);
   const [compositionSize, setCompositionSize] = useState<PreviewCompositionSize | null>(null);
   const gutterPx = usePreviewGuidesStore((s) => (s.rulerVisible ? RULER_GUTTER_PX : 0));
+  const insetPx = fillBox ? 0 : PREVIEW_STAGE_INSET_PX;
   const [stageSize, setStageSize] = useState(() => resolvePreviewStageSize(0, 0, null, portrait));
 
   const zoomRef = useRef<PreviewZoomState>(loadInitialZoom());
@@ -181,7 +186,14 @@ export const NLEPreview = memo(function NLEPreview({
     const updateStageSize = () => {
       const rect = viewport.getBoundingClientRect();
       setStageSize(
-        resolvePreviewStageSize(rect.width, rect.height, compositionSize, portrait, gutterPx),
+        resolvePreviewStageSize(
+          rect.width,
+          rect.height,
+          compositionSize,
+          portrait,
+          gutterPx,
+          insetPx,
+        ),
       );
     };
 
@@ -189,7 +201,7 @@ export const NLEPreview = memo(function NLEPreview({
     const observer = new ResizeObserver(updateStageSize);
     observer.observe(viewport);
     return () => observer.disconnect();
-  }, [compositionSize, portrait, gutterPx]);
+  }, [compositionSize, portrait, gutterPx, insetPx]);
 
   const onCompositionSizeChangeRef = useRef(onCompositionSizeChange);
   onCompositionSizeChangeRef.current = onCompositionSizeChange;
@@ -467,11 +479,14 @@ export const NLEPreview = memo(function NLEPreview({
     <div className="flex flex-col h-full min-h-0">
       <div
         ref={viewportRef}
-        className="relative flex-1 flex items-center justify-center p-2 overflow-hidden min-h-0 outline-hidden focus:ring-1 focus:ring-studio-accent/40 bg-[var(--studio-preview-bg,var(--color-neutral-950))]"
+        className="relative flex-1 flex items-center justify-center overflow-hidden min-h-0 outline-hidden focus:ring-1 focus:ring-studio-accent/40 bg-[var(--studio-preview-bg,var(--color-neutral-950))]"
         tabIndex={0}
         aria-label="Composition preview"
       >
-        <div className="absolute inset-2 flex items-center justify-center pointer-events-none">
+        <div
+          className="absolute flex items-center justify-center pointer-events-none"
+          style={{ inset: insetPx }}
+        >
           <div
             ref={stageRef}
             className="relative shrink-0 pointer-events-auto"

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.