@hyperframes/studio 0.8.144 → 0.8.146

package/src/hooks/useGestureCommit.ts

@@ -182,11 +182,11 @@ export function useGestureCommit({
         frozenSamples.length > 0 ? (frozenSamples[frozenSamples.length - 1]?.time ?? 0) : 0;
 
       if (frozenSamples.length <= 2) {
-        showToast("No gesture detected — move the pointer while recording", "error");
+        showToast("No gesture detected. Move the pointer while recording", "error");
         return;
       }
       if (duration <= 0) {
-        showToast("Recording too short — try again", "error");
+        showToast("Recording too short. Try again", "error");
         return;
       }
 
@@ -213,7 +213,7 @@ export function useGestureCommit({
       // would record the gesture onto every sibling sharing it.
       const selector = sel.id ? idSelector(sel.id) : sel.selector;
       if (!selector) {
-        showToast("Cannot save — element has no selector", "error");
+        showToast("Cannot save: element has no selector", "error");
         return;
       }
       // A recorded gesture becomes a NEW tween, so its target must address one
@@ -412,7 +412,7 @@ export function useGestureCommit({
       }
       const iframe = previewIframeRef.current;
       if (!iframe) {
-        showToast("Preview not ready — try again", "error");
+        showToast("Preview not ready. Try again", "error");
         return;
       }
 

package/src/hooks/useGsapScriptCommits.ts

@@ -81,7 +81,7 @@ async function runMutationRequest(
 ): Promise<MutationResult | undefined> {
   const unsafeFields = mutations.flatMap((mutation) => findUnsafeMutationValues(mutation));
   if (unsafeFields.length > 0) {
-    showToast?.("Couldn't read element layout — try again at a different playhead time", "error");
+    showToast?.("Couldn't read element layout. Try again at a different playhead time", "error");
     if (options.skipReload) return;
     throw markStudioSaveErrorAlreadyToasted(
       new Error(

package/src/index.ts

@@ -202,6 +202,7 @@ export type { UseClipboardOptions } from "./hooks/useClipboard";
 export { useDomEditSession } from "./hooks/useDomEditSession";
 export type { UseDomEditSessionParams } from "./hooks/useDomEditSession";
 export { useLivePreviewIframe } from "./hooks/useLivePreviewIframe";
+export { announcePreviewDocumentLoaded } from "./player/sceneSwap";
 export type { PreviewPromotion } from "./player/sceneSwap";
 export { usePreviewPersistence } from "./hooks/usePreviewPersistence";
 export type { UsePreviewPersistenceParams } from "./hooks/usePreviewPersistence";

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

@@ -126,7 +126,7 @@ describe("AudioGainDialog", () => {
   it("disables the peak options when the clip cannot be measured", async () => {
     stubPeaks({});
     open([clip("unmeasured")]);
-    await vi.waitFor(() => expect(peakText()).toBe("Peak Amplitude: —"));
+    await vi.waitFor(() => expect(peakText()).toBe("Peak Amplitude: Unavailable"));
     expect(row("Normalize Max Peak to")?.querySelector("input")?.disabled).toBe(true);
     expect(row("Adjust Gain by")?.querySelector("input")?.disabled).toBe(false);
   });

package/src/player/components/AudioGainDialog.tsx

@@ -185,7 +185,8 @@ export function AudioGainDialog({
           onSelect={() => setMode("loudness")}
         />
         <div className="mt-3 text-neutral-400" data-testid="audio-gain-peak">
-          Peak Amplitude: {peaks === null ? "measuring…" : peakDb === null ? "—" : dbText(peakDb)}
+          Peak Amplitude:{" "}
+          {peaks === null ? "measuring…" : peakDb === null ? "Unavailable" : dbText(peakDb)}
         </div>
         {outOfRange && <div className="mt-1 text-red-400">Peak targets must be 0 dB or lower.</div>}
         <div className="mt-4 flex justify-end gap-2">

package/src/player/components/EditModal.tsx

@@ -134,7 +134,7 @@ export function EditPopover({ rangeStart, rangeEnd, anchorX, anchorY, onClose }:
           <div className="flex items-center gap-2">
             <div className="w-1.5 h-1.5 rounded-full bg-studio-accent" />
             <span className="text-[11px] font-medium text-neutral-300">
-              {formatTime(start)} — {formatTime(end)}
+              {formatTime(start)} to {formatTime(end)}
             </span>
           </div>
           <span className="text-[10px] text-neutral-600">
@@ -175,7 +175,7 @@ export function EditPopover({ rangeStart, rangeEnd, anchorX, anchorY, onClose }:
         {/* Action */}
         {copyError && (
           <p className="px-3 pb-2 text-[10px] text-danger-ink" role="alert">
-            Copy failed — check clipboard permissions and try again.
+            Copy failed. Check clipboard permissions and try again.
           </p>
         )}
         <div className="grid grid-cols-2 gap-2 px-3 pb-3">

package/src/player/components/KeyframeDiamondContextMenu.tsx

@@ -142,7 +142,7 @@ export function KeyframeDiamondContextMenu({
           {copyStatus === "copied"
             ? "Copied!"
             : copyStatus === "failed"
-              ? "Copy failed — check permissions"
+              ? "Copy failed. Check permissions"
               : "Copy Properties"}
         </button>
       )}

package/src/player/components/OutOfSyncBadge.tsx

@@ -103,7 +103,7 @@ export const OutOfSyncBadge = memo(function OutOfSyncBadge({ el }: { el: Timelin
         tabIndex={-1}
         aria-haspopup="menu"
         aria-label={`Out of sync with ${partnerName} by ${label} frames`}
-        title={`Out of sync with ${partnerName} by ${label} — click for Move or Slip into Sync`}
+        title={`Out of sync with ${partnerName} by ${label}. Click for Move or Slip into Sync`}
         data-testid="out-of-sync-badge"
         className="absolute bottom-0.5 left-1 z-[12] cursor-pointer rounded-[3px] bg-red-600 px-1 font-mono text-[9px] leading-[14px] text-white tabular-nums"
         onPointerDown={stop}

package/src/player/components/Player.test.ts

@@ -10,6 +10,7 @@ import {
   shouldShowCompositionLoadingOverlay,
 } from "./Player";
 import { usePlayerStore } from "../store/playerStore";
+import { onPreviewDocumentLoaded } from "../sceneSwap";
 
 vi.mock("@hyperframes/player", () => ({}));
 
@@ -196,6 +197,49 @@ describe("callbacks after the player is already mounted", () => {
     expect(first).not.toHaveBeenCalled();
   });
 
+  it("loads the preview on the runtime's ready while a stalled font holds the window's load", async () => {
+    const onLoad = vi.fn();
+    const { player } = await mountPlayer({ onLoad });
+    const iframe = (player as TestHyperframesPlayer).iframeElement;
+    let page = {};
+    Object.defineProperty(iframe, "contentDocument", { get: () => page });
+    Object.defineProperty(iframe, "contentWindow", { get: () => ({ __playerReady: true }) });
+    const announced = vi.fn();
+    onPreviewDocumentLoaded(iframe, announced);
+
+    act(() => void player.dispatchEvent(new Event("ready")));
+    expect(onLoad).toHaveBeenCalledTimes(1);
+
+    act(() => void iframe.dispatchEvent(new Event("load")));
+    act(() => void player.dispatchEvent(new Event("ready")));
+    expect(onLoad).toHaveBeenCalledTimes(1);
+
+    page = {};
+    act(() => void player.dispatchEvent(new Event("ready")));
+    expect(onLoad).toHaveBeenCalledTimes(2);
+    expect(announced).toHaveBeenCalledTimes(2);
+  });
+
+  it("leaves a ready that arrives before the page's runtime boots to the page's own load", async () => {
+    const onLoad = vi.fn();
+    const { player } = await mountPlayer({ onLoad });
+    const iframe = (player as TestHyperframesPlayer).iframeElement;
+    const page = {};
+    let runtime: { __playerReady?: boolean } = {};
+    Object.defineProperty(iframe, "contentDocument", { get: () => page });
+    Object.defineProperty(iframe, "contentWindow", { get: () => runtime });
+
+    act(() => void player.dispatchEvent(new Event("ready")));
+    expect(onLoad).not.toHaveBeenCalled();
+
+    act(() => void iframe.dispatchEvent(new Event("load")));
+    expect(onLoad).toHaveBeenCalledTimes(1);
+
+    runtime = { __playerReady: true };
+    act(() => void player.dispatchEvent(new Event("ready")));
+    expect(onLoad).toHaveBeenCalledTimes(1);
+  });
+
   it("reports the preview error cause", async () => {
     const onPreviewError = vi.fn();
     const { player } = await mountPlayer({ onPreviewError });

package/src/player/components/Player.tsx

@@ -5,6 +5,8 @@ import { useMountEffect } from "../../hooks/useMountEffect";
 import { applyPreviewVariablesToUrl } from "../../hooks/previewVariablesStore";
 import { HyperframesLoader } from "../../components/ui";
 import { usePlayerStore } from "../store/playerStore";
+import { announcePreviewDocumentLoaded } from "../sceneSwap";
+import type { IframeWindow } from "../lib/playbackTypes";
 // Importing "@hyperframes/player" registers a class extending HTMLElement at
 // module load, which throws under SSR, hence the dynamic import behind a
 // `typeof window` guard. Kicking it here rather than in the mount effect puts
@@ -128,6 +130,9 @@ export function hasUnloadedAssets(iframe: HTMLIFrameElement, lastResult: boolean
   }
 }
 
+const runtimeBootedIn = (iframe: HTMLIFrameElement) =>
+  (iframe.contentWindow as IframeWindow | null)?.__playerReady === true;
+
 /**
  * Renders a composition preview using the <hyperframes-player> web component.
  *
@@ -228,9 +233,11 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
           const loading = getShaderTransitionLoading(event);
           if (loading !== null) setShaderTransitionLoading(loading);
         };
+        let loadedDocument: Document | null = null;
         const handleReady = () => {
           setPreviewError(null);
           setCompositionLoading(false);
+          if (iframe.contentDocument && runtimeBootedIn(iframe)) handleLoad();
         };
         const handlePainted = () => {
           setPainted(true);
@@ -243,6 +250,9 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
           setCompositionLoading(false);
         };
         const handleLoad = () => {
+          const doc = iframe.contentDocument;
+          if (doc && doc === loadedDocument) return;
+          loadedDocument = doc;
           loadCountRef.current++;
           setLoaded(true);
           setPreviewError(null);
@@ -258,6 +268,7 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
             container.addEventListener("animationend", onEnd, { once: true });
           }
           onLoadRef.current();
+          announcePreviewDocumentLoaded(iframe);
 
           // Show a loading overlay until every `<video>`/`<audio>` and Lottie
           // asset is ready. Without this users can click play before audio has
@@ -287,7 +298,7 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
               if (!lastUnloaded || attempts > 100) {
                 if (lastUnloaded && attempts > 100) {
                   console.debug(
-                    "[studio] asset readiness poll hit the 10s cap — continuing with unloaded assets",
+                    "[studio] asset readiness poll hit the 10s cap, continuing with unloaded assets",
                   );
                 }
                 if (assetPollRef.current) clearInterval(assetPollRef.current);

package/src/player/components/ShortcutsPanel.tsx

@@ -182,7 +182,7 @@ export const ShortcutsPanel = memo(function ShortcutsPanel({
                       </Tooltip>
                     </>
                   ) : (
-                    <span className="text-[10px] text-neutral-600">—</span>
+                    <span className="text-[10px] text-neutral-600">Not set</span>
                   )}
                 </div>
               </div>
@@ -220,7 +220,7 @@ export const ShortcutsPanel = memo(function ShortcutsPanel({
                       </Tooltip>
                     </>
                   ) : (
-                    <span className="text-[10px] text-neutral-600">—</span>
+                    <span className="text-[10px] text-neutral-600">Not set</span>
                   )}
                 </div>
               </div>

package/src/player/components/Timeline.virtualization.test.tsx

@@ -167,7 +167,7 @@ describe("Timeline row virtualization", { timeout: 30_000 }, () => {
       const clip = host.querySelector<HTMLElement>('[data-el-id="clip-0"]');
       expect(scroller).not.toBeNull();
       expect(clip).not.toBeNull();
-      expect(clip?.title).toBe("Clip 0 • 0.0s – 10.0s");
+      expect(clip?.title).toBe("Clip 0 • 0.0s to 10.0s");
       const picture = host.querySelector("[data-rich-content]");
       expect(picture).not.toBeNull();
 

package/src/player/components/TimelineAutomationLaneSlot.tsx

@@ -110,7 +110,7 @@ function ClipAutomationLanes({
             // — because "not editable" without that reads as broken.
             readOnlyNote={
               isCarveLane(lane.target, bound.chain)
-                ? "Owned by the voiceover carve — re-derived on every analysis. Change strength in the FX rack, or turn the carve off to edit these by hand."
+                ? "Owned by the voiceover carve and re-derived on every analysis. Change strength in the FX rack, or turn the carve off to edit these by hand."
                 : bound.readOnly
                   ? "Read-only here."
                   : undefined

package/src/player/components/TimelineClip.tsx

@@ -170,7 +170,7 @@ export const TimelineClip = memo(function TimelineClip({
       title={
         isComposition
           ? `${el.compositionSrc} • Double-click to open`
-          : `${displayLabel} • ${startLabel}s – ${endLabel}s`
+          : `${displayLabel} • ${startLabel}s to ${endLabel}s`
       }
       onPointerEnter={onHoverStart}
       onPointerLeave={onHoverEnd}

package/src/player/components/TimelineFxButton.tsx

@@ -213,7 +213,7 @@ export function TimelineFxButton(props: TimelineFxButtonProps) {
           type="button"
           tabIndex={-1}
           ref={buttonRef}
-          aria-label="Effects — group these clips first"
+          aria-label="Effects: group these clips first"
           title="Group these clips to add effects to all of them"
           className="flex h-6 items-center justify-center rounded-sm border-0 bg-transparent px-1 text-[10px] font-semibold text-[var(--timeline-text-faint)] hover:text-[var(--timeline-text-soft)]"
           onPointerDown={(event) => event.stopPropagation()}
@@ -253,7 +253,7 @@ export function TimelineFxButton(props: TimelineFxButtonProps) {
         type="button"
         tabIndex={-1}
         ref={buttonRef}
-        aria-label={nodeCount > 0 ? `Effects — ${nodeCount} applied` : "Effects"}
+        aria-label={nodeCount > 0 ? `Effects: ${nodeCount} applied` : "Effects"}
         title="Effects"
         className={`flex h-6 items-center justify-center gap-0.5 rounded border-0 bg-transparent px-1 text-[10px] font-semibold transition-colors ${
           open || nodeCount > 0

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

@@ -851,7 +851,7 @@ describe("TimelineTrackHeader", () => {
         isAudioTrack: true,
       };
       const pointer = (host: HTMLElement) =>
-        host.querySelector('button[aria-label="Effects — group these clips first"]');
+        host.querySelector('button[aria-label="Effects: group these clips first"]');
       const view = renderHeader(opts);
       expect(pointer(view.host)).not.toBeNull();
       // One clip needs no grouping — the real FX button takes its place.
@@ -886,7 +886,7 @@ describe("TimelineTrackHeader", () => {
       };
       const pointer = (host: HTMLElement) =>
         host.querySelector<HTMLButtonElement>(
-          'button[aria-label="Effects — group these clips first"]',
+          'button[aria-label="Effects: group these clips first"]',
         );
       const view = renderHeader(opts);
       const button = pointer(view.host);
@@ -955,7 +955,7 @@ describe("TimelineTrackHeader", () => {
       const controls = line?.lastElementChild as HTMLElement | null;
       expect(controls?.className).toContain("ml-auto");
       expect(
-        controls?.querySelector('button[aria-label="Effects — group these clips first"]'),
+        controls?.querySelector('button[aria-label="Effects: group these clips first"]'),
       ).not.toBeNull();
       // And the clip count is beside the name, not out with the controls.
       expect(controls?.querySelector('[aria-label="2 clips"]')).toBeNull();

package/src/player/components/timelineClipDragCommit.ts

@@ -130,8 +130,8 @@ export function persistMoveEdits(
   if (!onMoveElements) {
     console.warn(
       onMoveElement
-        ? `[Timeline] persistMoveEdits: only single-clip onMoveElement wired — this ${edits.length}-clip move degrades to a per-clip persist race (no atomic single-undo)`
-        : `[Timeline] persistMoveEdits: no move persist handler wired — ${edits.length} edit(s) applied to the store only, not saved`,
+        ? `[Timeline] persistMoveEdits: only single-clip onMoveElement wired, so this ${edits.length}-clip move degrades to a per-clip persist race (no atomic single-undo)`
+        : `[Timeline] persistMoveEdits: no move persist handler wired, so ${edits.length} edit(s) applied to the store only, not saved`,
     );
   }
   const prev = edits.map((e) => ({

package/src/player/components/trackHeaderLabelRows.tsx

@@ -286,7 +286,7 @@ export function AutomationLaneHeaderRow({
           <span
             data-automation-lane-also=""
             className="truncate text-[9px] text-warning-ink"
-            title={`${alsoAutomatedBy} is also fading this — the two multiply.`}
+            title={`${alsoAutomatedBy} is also fading this. The two multiply.`}
           >
             {alsoAutomatedBy} is also fading this.
           </span>

package/src/player/lib/playbackAdapter.ts

@@ -183,7 +183,7 @@ export function resolveStaticSeekFallback(opts: {
   if (!warned.current) {
     warned.current = true;
     console.warn(
-      `[useTimelinePlayer] Selected adapter duration (${getAdapterDuration(bestAdapter)}s) does not cover the document duration (${docDuration}s); falling back to seek-driven playback, which never starts media elements or WebAudio. Audio will not play in preview — extend the GSAP timeline to cover the declared data-duration.`,
+      `[useTimelinePlayer] Selected adapter duration (${getAdapterDuration(bestAdapter)}s) does not cover the document duration (${docDuration}s); falling back to seek-driven playback, which never starts media elements or WebAudio. Audio will not play in preview. Extend the GSAP timeline to cover the declared data-duration.`,
     );
   }
   const adapter = createStaticSeekPlaybackAdapter(

package/src/player/lib/playbackTypes.ts

@@ -59,6 +59,7 @@ export interface ClipManifest {
 
 export type IframeWindow = Window & {
   __player?: RuntimePlaybackAdapter;
+  __playerReady?: boolean;
   __timeline?: TimelineLike;
   __timelines?: Record<string, TimelineLike>;
   __clipManifest?: ClipManifest;

package/src/player/sceneSwap.test.ts

@@ -1,6 +1,11 @@
 // @vitest-environment happy-dom
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { SCENE_SWAP_MS, sceneSwapFor } from "./sceneSwap";
+import {
+  SCENE_SWAP_MS,
+  announcePreviewDocumentLoaded,
+  onPreviewContentReplaced,
+  sceneSwapFor,
+} from "./sceneSwap";
 
 afterEach(() => {
   vi.useRealTimers();
@@ -93,3 +98,24 @@ describe("sceneSwapFor", () => {
     expect(swap).toHaveBeenCalledWith("<html></html>", expect.anything());
   });
 });
+
+describe("onPreviewContentReplaced", () => {
+  it("reports Player's document-loaded announcement and a scene swap, never a raw load", () => {
+    const iframe = document.createElement("iframe");
+    const replaced = vi.fn();
+    const stop = onPreviewContentReplaced(iframe, replaced);
+
+    iframe.dispatchEvent(new Event("load"));
+    expect(replaced).not.toHaveBeenCalled();
+
+    announcePreviewDocumentLoaded(iframe);
+    expect(replaced).toHaveBeenCalledTimes(1);
+
+    iframe.dispatchEvent(new Event("hf-scenes-swapped"));
+    expect(replaced).toHaveBeenCalledTimes(2);
+
+    stop();
+    announcePreviewDocumentLoaded(iframe);
+    expect(replaced).toHaveBeenCalledTimes(2);
+  });
+});

package/src/player/sceneSwap.ts

@@ -6,14 +6,28 @@ type SwapWindow = Window & {
 const SCENES_SWAPPED = "hf-scenes-swapped";
 export const SCENE_SWAP_MS = 5000;
 
+const PREVIEW_DOCUMENT_LOADED = "hf-preview-document-loaded";
+
+export function announcePreviewDocumentLoaded(iframe: HTMLIFrameElement): void {
+  iframe.dispatchEvent(new Event(PREVIEW_DOCUMENT_LOADED));
+}
+
+export function onPreviewDocumentLoaded(
+  iframe: HTMLIFrameElement,
+  onLoaded: () => void,
+): () => void {
+  iframe.addEventListener(PREVIEW_DOCUMENT_LOADED, onLoaded);
+  return () => iframe.removeEventListener(PREVIEW_DOCUMENT_LOADED, onLoaded);
+}
+
 export function onPreviewContentReplaced(
   iframe: HTMLIFrameElement,
   onReplaced: () => void,
 ): () => void {
-  iframe.addEventListener("load", onReplaced);
+  const stopLoaded = onPreviewDocumentLoaded(iframe, onReplaced);
   iframe.addEventListener(SCENES_SWAPPED, onReplaced);
   return () => {
-    iframe.removeEventListener("load", onReplaced);
+    stopLoaded();
     iframe.removeEventListener(SCENES_SWAPPED, onReplaced);
   };
 }

package/src/utils/hmrStableContext.ts

@@ -51,7 +51,7 @@ export function createStableContext<T>(name: string, defaultValue: T): Context<T
     // Not on the HMR path: a re-evaluated module hands back the SAME default it
     // registered, which is how a hot reload keeps its context alive.
     console.warn(
-      `[hmrStableContext] "${name}" was registered twice with different defaults — ` +
+      `[hmrStableContext] "${name}" was registered twice with different defaults: ` +
         "two contexts are sharing one identity. Use module path + export name.",
     );
   }

package/src/utils/razorSplitTransaction.ts

@@ -18,7 +18,6 @@ interface CutTarget {
   elementDuration: number;
   playbackStart?: number;
   playbackRate?: number;
-  isComposition?: boolean;
   track?: number;
 }
 
@@ -71,7 +70,6 @@ function buildCutTarget(
     elementDuration: element.duration,
     ...(element.playbackStart != null ? { playbackStart: element.playbackStart } : {}),
     ...(element.playbackRate != null ? { playbackRate: element.playbackRate } : {}),
-    ...(element.kind === "composition" ? { isComposition: true } : {}),
     // Pin both halves to the current track: unstamped, the runtime's positional
     // fallback (parseAuthoredTrack) renumbers the new sibling onto a new row.
     track: resolveElementTrack(element),

package/src/utils/sdkCutover.linkedTiming.test.ts

@@ -43,7 +43,7 @@ describe("a linked trim the SDK refuses", () => {
       thrown = error;
     }
     expect(getStudioSaveErrorMessage(thrown)).toBe(
-      "Linked audio would start after the new end — unlink or trim the audio first.",
+      "Linked audio would start after the new end. Unlink or trim the audio first.",
     );
     expect(deps.writeProjectFile).not.toHaveBeenCalled();
     expect(deps.editHistory.recordEdit).not.toHaveBeenCalled();