@hyperframes/studio 0.7.77 → 0.7.79

package/src/player/components/Player.tsx

@@ -38,11 +38,19 @@ function getShaderTransitionLoading(event: Event): boolean | null {
 }
 
 const COMPOSITION_LOADING_OVERLAY_DELAY_MS = 400;
+const DEFAULT_PREVIEW_ERROR = "The composition preview did not become ready.";
 
 export function shouldShowCompositionLoadingOverlay(compositionLoading: boolean): boolean {
   return compositionLoading;
 }
 
+export function readPreviewErrorMessage(event: Event): string {
+  if (!(event instanceof CustomEvent) || !isRecord(event.detail)) return DEFAULT_PREVIEW_ERROR;
+  return typeof event.detail.message === "string" && event.detail.message.trim()
+    ? event.detail.message
+    : DEFAULT_PREVIEW_ERROR;
+}
+
 function enableInteractiveIframe(player: HyperframesPlayerElement): void {
   const root = player.shadowRoot;
   if (!root) return;
@@ -122,12 +130,15 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
     const loadCountRef = useRef(0);
     const assetPollRef = useRef<ReturnType<typeof setInterval> | null>(null);
     const assetFadeRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+    const retryPreviewRef = useRef<(() => void) | null>(null);
+    const retryCountRef = useRef(0);
     const [assetsLoading, setAssetsLoading] = useState(false);
     const [assetOverlayVisible, setAssetOverlayVisible] = useState(false);
     const [assetOverlayFading, setAssetOverlayFading] = useState(false);
     const [shaderTransitionLoading, setShaderTransitionLoading] = useState(false);
     const [compositionLoading, setCompositionLoading] = useState(true);
     const [compositionOverlayDeferred, setCompositionOverlayDeferred] = useState(true);
+    const [previewError, setPreviewError] = useState<string | null>(null);
 
     // eslint-disable-next-line no-restricted-syntax
     useEffect(() => {
@@ -161,62 +172,32 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
         );
         applyPreviewVariablesToUrl(srcUrl);
         const src = srcUrl.pathname + srcUrl.search;
-        player.setAttribute("shader-capture-scale", "1");
-        player.setAttribute("shader-loading", "player");
-        player.setAttribute("src", src);
-        player.setAttribute("width", String(portrait ? 1080 : 1920));
-        player.setAttribute("height", String(portrait ? 1920 : 1080));
-        player.style.width = "100%";
-        player.style.height = "100%";
-        player.style.display = "block";
-        player.style.background = "transparent";
-        container.appendChild(player);
-
-        // Inject pasteboard shadow: let the shadow around the canvas bleed
-        // into the surrounding pasteboard area (overflow: visible on the container)
-        // and add a subtle outline + drop-shadow so the canvas boundary reads
-        // against the gray pasteboard, consistent with professional editors.
-        if (player.shadowRoot) {
-          const pasteboardStyle = document.createElement("style");
-          pasteboardStyle.textContent =
-            ".hfp-container{overflow:visible}" +
-            ".hfp-iframe{box-shadow:0 0 0 1px rgba(255,255,255,0.08),0 4px 32px rgba(0,0,0,.7)}";
-          player.shadowRoot.appendChild(pasteboardStyle);
-        }
-
-        enableInteractiveIframe(player);
-
-        // Bridge the inner iframe to the forwarded ref for useTimelinePlayer.
+        const retryPreview = () => {
+          retryCountRef.current += 1;
+          const retryUrl = new URL(src, window.location.origin);
+          retryUrl.searchParams.set("_hfStudioRetry", String(retryCountRef.current));
+          setPreviewError(null);
+          setCompositionLoading(true);
+          player.setAttribute("src", retryUrl.pathname + retryUrl.search);
+        };
+        retryPreviewRef.current = retryPreview;
         const iframe = player.iframeElement;
-        if (typeof ref === "function") {
-          ref(iframe);
-        } else if (ref) {
-          (ref as React.MutableRefObject<HTMLIFrameElement | null>).current = iframe;
-        }
-
-        // Prevent the web component's built-in click-to-toggle behavior.
-        // The studio manages playback exclusively via useTimelinePlayer.
         const preventToggle = (e: Event) => e.stopImmediatePropagation();
-        player.addEventListener("click", preventToggle, { capture: true });
-
         const handleShaderTransitionState = (event: Event) => {
           const loading = getShaderTransitionLoading(event);
           if (loading !== null) setShaderTransitionLoading(loading);
         };
-        player.addEventListener("shadertransitionstate", handleShaderTransitionState);
-
         const handleReady = () => {
+          setPreviewError(null);
           setCompositionLoading(false);
         };
-        const handleError = () => {
+        const handleError = (event: Event) => {
+          setPreviewError(readPreviewErrorMessage(event));
           setCompositionLoading(false);
         };
-        player.addEventListener("ready", handleReady);
-        player.addEventListener("error", handleError);
-
-        // Forward the iframe's native load event to the studio's onIframeLoad.
         const handleLoad = () => {
           loadCountRef.current++;
+          setPreviewError(null);
           setShaderTransitionLoading(false);
           setCompositionLoading(true);
           // Reveal animation on reload (hot-reload, composition switch)
@@ -264,7 +245,47 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
             setAssetsLoading(false);
           }
         };
+
+        // Attach lifecycle listeners before assigning src or connecting the
+        // custom element. A warm local iframe can otherwise finish before
+        // Studio observes its load and never initialize the timeline.
         iframe.addEventListener("load", handleLoad);
+        player.addEventListener("click", preventToggle, { capture: true });
+        player.addEventListener("shadertransitionstate", handleShaderTransitionState);
+        player.addEventListener("ready", handleReady);
+        player.addEventListener("error", handleError);
+
+        // Bridge the inner iframe to the forwarded ref for useTimelinePlayer.
+        if (typeof ref === "function") {
+          ref(iframe);
+        } else if (ref) {
+          (ref as React.MutableRefObject<HTMLIFrameElement | null>).current = iframe;
+        }
+
+        player.setAttribute("shader-capture-scale", "1");
+        player.setAttribute("shader-loading", "player");
+        player.setAttribute("width", String(portrait ? 1080 : 1920));
+        player.setAttribute("height", String(portrait ? 1920 : 1080));
+        player.style.width = "100%";
+        player.style.height = "100%";
+        player.style.display = "block";
+        player.style.background = "transparent";
+        player.setAttribute("src", src);
+        container.appendChild(player);
+
+        // Inject pasteboard shadow: let the shadow around the canvas bleed
+        // into the surrounding pasteboard area (overflow: visible on the container)
+        // and add a subtle outline + drop-shadow so the canvas boundary reads
+        // against the gray pasteboard, consistent with professional editors.
+        if (player.shadowRoot) {
+          const pasteboardStyle = document.createElement("style");
+          pasteboardStyle.textContent =
+            ".hfp-container{overflow:visible}" +
+            ".hfp-iframe{box-shadow:0 0 0 1px rgba(255,255,255,0.08),0 4px 32px rgba(0,0,0,.7)}";
+          player.shadowRoot.appendChild(pasteboardStyle);
+        }
+
+        enableInteractiveIframe(player);
 
         cleanup = () => {
           iframe.removeEventListener("load", handleLoad);
@@ -275,6 +296,7 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
           if (assetPollRef.current) clearInterval(assetPollRef.current);
           assetPollRef.current = null;
           container.removeChild(player);
+          if (retryPreviewRef.current === retryPreview) retryPreviewRef.current = null;
           // Clear the forwarded ref only if it still points to THIS iframe.
           // During crossfade refreshes the retiring Player unmounts after the
           // new Player has already assigned its iframe to the same ref — blindly
@@ -381,6 +403,25 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
             />
           </div>
         )}
+        {previewError && (
+          <div
+            className="absolute inset-0 z-40 flex items-center justify-center bg-black/90 px-6 text-center"
+            data-hyperframes-ignore=""
+            data-testid="composition-preview-error"
+          >
+            <div className="max-w-sm">
+              <p className="text-sm font-semibold text-white">Preview failed to load</p>
+              <p className="mt-1 text-xs text-neutral-400">{previewError}</p>
+              <button
+                type="button"
+                className="mt-4 rounded-md bg-white px-3 py-1.5 text-xs font-semibold text-black transition-colors hover:bg-neutral-200"
+                onClick={() => retryPreviewRef.current?.()}
+              >
+                Retry preview
+              </button>
+            </div>
+          </div>
+        )}
       </div>
     );
   },

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

@@ -0,0 +1,158 @@
+// @vitest-environment happy-dom
+
+import React, { act, Profiler } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { ShortcutsPanel } from "./ShortcutsPanel";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const roots: Root[] = [];
+
+afterEach(() => {
+  for (const root of roots.splice(0)) act(() => root.unmount());
+  document.body.innerHTML = "";
+});
+
+function renderPanel(onRender = vi.fn()) {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  roots.push(root);
+  act(() => {
+    root.render(
+      <Profiler id="shortcuts-panel" onRender={onRender}>
+        <ShortcutsPanel
+          disabled={false}
+          duration={10}
+          inPoint={null}
+          outPoint={null}
+          setInPoint={vi.fn()}
+          setOutPoint={vi.fn()}
+          onSeek={vi.fn()}
+        />
+      </Profiler>,
+    );
+  });
+
+  const trigger = host.querySelector<HTMLButtonElement>(
+    'button[aria-label="Shortcuts and tools"]',
+  )!;
+  return { host, trigger, onRender };
+}
+
+function pressAndClick(target: HTMLElement): void {
+  target.dispatchEvent(
+    new PointerEvent("pointerdown", { bubbles: true, cancelable: true, button: 0 }),
+  );
+  target.dispatchEvent(new MouseEvent("mousedown", { bubbles: true, cancelable: true, button: 0 }));
+  target.dispatchEvent(new MouseEvent("mouseup", { bubbles: true, cancelable: true, button: 0 }));
+  target.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true, button: 0 }));
+}
+
+function openPanel(trigger: HTMLButtonElement): void {
+  act(() => pressAndClick(trigger));
+  expect(trigger.getAttribute("aria-expanded")).toBe("true");
+}
+
+describe("ShortcutsPanel", () => {
+  it.each(["page", "button", "panel"] as const)(
+    "closes with Escape from the %s-focused position",
+    (focusPosition) => {
+      const { host, trigger } = renderPanel();
+      openPanel(trigger);
+
+      let eventTarget: Document | HTMLElement;
+      if (focusPosition === "page") {
+        document.body.tabIndex = -1;
+        document.body.focus();
+        eventTarget = document;
+        expect(document.activeElement).toBe(document.body);
+      } else if (focusPosition === "button") {
+        trigger.focus();
+        eventTarget = trigger;
+        expect(document.activeElement).toBe(trigger);
+      } else {
+        const panelInput = host.querySelector<HTMLInputElement>('[aria-label="Jump to frame"]')!;
+        panelInput.focus();
+        eventTarget = panelInput;
+        expect(document.activeElement).toBe(panelInput);
+      }
+
+      act(() => {
+        eventTarget.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape", bubbles: true }));
+      });
+
+      expect(trigger.getAttribute("aria-expanded")).toBe("false");
+      expect(host.querySelector('[aria-label="Jump to frame"]')).toBeNull();
+    },
+  );
+
+  it("closes on capture-phase pointerdown even when its default is prevented", () => {
+    const preventDefault = (event: Event) => event.preventDefault();
+    document.addEventListener("pointerdown", preventDefault, true);
+    const { host, trigger } = renderPanel();
+    openPanel(trigger);
+    const outside = document.createElement("div");
+    document.body.append(outside);
+    const pointerDown = new PointerEvent("pointerdown", {
+      bubbles: true,
+      cancelable: true,
+      button: 0,
+    });
+
+    act(() => outside.dispatchEvent(pointerDown));
+
+    document.removeEventListener("pointerdown", preventDefault, true);
+    expect(pointerDown.defaultPrevented).toBe(true);
+    expect(trigger.getAttribute("aria-expanded")).toBe("false");
+    expect(host.querySelector('[aria-label="Jump to frame"]')).toBeNull();
+  });
+
+  it("does not close on a click inside the panel", () => {
+    const { host, trigger } = renderPanel();
+    openPanel(trigger);
+    const panelInput = host.querySelector<HTMLInputElement>('[aria-label="Jump to frame"]')!;
+
+    act(() => pressAndClick(panelInput));
+
+    expect(trigger.getAttribute("aria-expanded")).toBe("true");
+    expect(host.querySelector('[aria-label="Jump to frame"]')).not.toBeNull();
+  });
+
+  it("toggles once per trigger click", () => {
+    const { trigger } = renderPanel();
+
+    act(() => pressAndClick(trigger));
+    expect(trigger.getAttribute("aria-expanded")).toBe("true");
+
+    act(() => pressAndClick(trigger));
+    expect(trigger.getAttribute("aria-expanded")).toBe("false");
+  });
+
+  it("does not re-render when Escape is pressed while closed", () => {
+    const { trigger, onRender } = renderPanel();
+    expect(onRender).toHaveBeenCalledTimes(1);
+
+    act(() => {
+      document.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape", bubbles: true }));
+    });
+
+    expect(trigger.getAttribute("aria-expanded")).toBe("false");
+    expect(onRender).toHaveBeenCalledTimes(1);
+  });
+
+  it("connects the trigger to the dialog with aria-controls", () => {
+    const { host, trigger } = renderPanel();
+    openPanel(trigger);
+    const panelId = trigger.getAttribute("aria-controls");
+    const panel = panelId ? host.querySelector<HTMLElement>(`#${CSS.escape(panelId)}`) : null;
+
+    expect(panelId).not.toBeNull();
+    expect(panel?.getAttribute("role")).toBe("dialog");
+    // Non-modal on purpose: focus is not trapped and the editor behind stays
+    // operable, so aria-modal would lie to assistive tech about inertness.
+    expect(panel?.getAttribute("aria-modal")).toBeNull();
+    expect(panel?.id).toBe(panelId);
+  });
+});

package/src/player/components/ShortcutsPanel.tsx

@@ -1,6 +1,7 @@
-import { useState, useCallback, useRef, useEffect, memo } from "react";
+import { useState, useCallback, useId, memo } from "react";
 import { formatTime, frameToSeconds } from "../lib/time";
 import { Tooltip } from "../../components/ui";
+import { useContextMenuDismiss } from "../../hooks/useContextMenuDismiss";
 
 const SHORTCUT_SECTIONS = [
   {
@@ -108,20 +109,9 @@ export const ShortcutsPanel = memo(function ShortcutsPanel({
 }: ShortcutsPanelProps) {
   const [showShortcuts, setShowShortcuts] = useState(false);
   const [jumpFrame, setJumpFrame] = useState("");
-  const shortcutsPanelRef = useRef<HTMLDivElement>(null);
-
-  useEffect(() => {
-    if (!showShortcuts) return;
-    const handleMouseDown = (e: MouseEvent) => {
-      if (shortcutsPanelRef.current && !shortcutsPanelRef.current.contains(e.target as Node)) {
-        setShowShortcuts(false);
-      }
-    };
-    document.addEventListener("mousedown", handleMouseDown);
-    return () => {
-      document.removeEventListener("mousedown", handleMouseDown);
-    };
-  }, [showShortcuts]);
+  const shortcutsPanelId = useId();
+  const closeShortcuts = useCallback(() => setShowShortcuts(false), []);
+  const shortcutsPanelRef = useContextMenuDismiss(closeShortcuts);
 
   const commitJumpFrame = useCallback(() => {
     if (disabled) return;
@@ -158,6 +148,7 @@ export const ShortcutsPanel = memo(function ShortcutsPanel({
           }`}
           aria-label="Shortcuts and tools"
           aria-expanded={showShortcuts}
+          aria-controls={shortcutsPanelId}
         >
           <svg
             width="11"
@@ -177,6 +168,11 @@ export const ShortcutsPanel = memo(function ShortcutsPanel({
       </Tooltip>
       {showShortcuts && (
         <div
+          id={shortcutsPanelId}
+          role="dialog"
+          // Deliberately NOT aria-modal. This is a non-modal disclosure: focus is
+          // not trapped and the rest of the editor stays operable, so claiming
+          // modality would make assistive tech treat the whole app as inert.
           className="absolute bottom-full right-0 mb-2 z-50 rounded-lg shadow-xl min-w-[220px] overflow-y-auto"
           style={{
             background: "#161618",

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

@@ -293,7 +293,9 @@ describe("Timeline provider boundary", () => {
     // mounted before we query it.
     act(() => {});
 
-    const button = host.querySelector<HTMLButtonElement>('button[aria-label="Show track 0"]');
+    // "1", not "0": the label carries the 1-based display row, while the
+    // callback below still routes by the track's own key.
+    const button = host.querySelector<HTMLButtonElement>('button[aria-label="Show track 1"]');
     expect(button).not.toBeNull();
     if (!button) throw new Error("Expected a track visibility toggle");
 

package/src/player/components/TimelineCanvas.tsx

@@ -20,7 +20,8 @@ import { type MultiDragPreviewInput } from "./timelineMultiDragPreview";
 import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
 import type { Rect } from "../../utils/marqueeGeometry";
 import { TimelineClip } from "./TimelineClip";
-import { TimelineLanes, type TimelineLaneBaseProps } from "./TimelineLanes";
+import { TimelineLanes } from "./TimelineLanes";
+import type { TimelineLaneBaseProps } from "./timelineLaneProps";
 import { renderClipChildren } from "./timelineClipChildren";
 import { useTimelineRevealClip } from "./useTimelineRevealClip";
 import type { TimelineLaneGapStrips } from "./useTimelineGapHighlights";

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

@@ -641,7 +641,7 @@ describe("TimelineClipDiamonds", () => {
     act(() => root.unmount());
   });
 
-  const renderSegmentLane = (lastAmbiguous: boolean) => {
+  const renderSegmentLane = (lastAmbiguous: boolean, clipWidthPx = 200) => {
     const host = document.createElement("div");
     document.body.append(host);
     const root = createRoot(host);
@@ -660,7 +660,7 @@ describe("TimelineClipDiamonds", () => {
             format: "percentage",
             keyframes: [kf(0), kf(50), kf(100, { easeAmbiguous: lastAmbiguous })],
           }}
-          clipWidthPx={200}
+          clipWidthPx={clipWidthPx}
           clipHeightPx={48}
           accentColor="#4ba3d2"
           isSelected
@@ -698,6 +698,21 @@ describe("TimelineClipDiamonds", () => {
     expect(segment?.style.pointerEvents).toBe("none");
     expect(ease?.style.pointerEvents).toBe("auto");
     expect(Number(segment?.style.zIndex)).toBeGreaterThan(Number(diamond?.style.zIndex));
+    // Room to spare here, so the button carries the 24x24 WCAG 2.5.8 overlay.
+    expect(ease?.className).toContain("before:h-6");
+    act(() => root.unmount());
+  });
+
+  it("drops the 24x24 ease overlay when the segment is too narrow to hold it", () => {
+    // The segment wrapper outranks the diamonds, so an overlay wider than the
+    // clear span between them would steal their clicks at fit zoom. 40px of clip
+    // across three keyframes leaves well under 24px of clear span per segment.
+    const { host, root } = renderSegmentLane(false, 40);
+    const ease = host.querySelector<HTMLButtonElement>("[data-keyframe-ease-button]");
+
+    expect(ease).not.toBeNull();
+    expect(ease?.className).not.toContain("before:h-6");
+    expect(ease?.style.width).toBe("16px");
     act(() => root.unmount());
   });
 

package/src/player/components/TimelineClipDiamonds.tsx

@@ -27,6 +27,12 @@ export type { TimelineDiamondKeyframe } from "./timelineDiamondTypes";
 // stops there: at the zoom floor the gap alone left a ~7px target, which is
 // neither hittable nor selectable with any accuracy. Boxes may overlap slightly
 // below this width; each diamond still owns the half-gap around its own centre.
+//
+// Deliberately below the 24px WCAG 2.2 (2.5.8) minimum, under that criterion's
+// own spacing exception: at normal keyframe density the neighbour gap is under
+// 24px, so a 24px floor would make adjacent diamonds' hit boxes OVERLAP — one
+// diamond swallowing its neighbour's clicks is a worse 2.5.8 failure than a
+// small target. Do not "fix" this to 24.
 const KF_MIN_HIT_W = 12;
 
 /** A clip-% is a float division, so a raw tooltip reads `25.032499999999995%`. */
@@ -141,6 +147,10 @@ export const TimelineDiamondLane = memo(function TimelineDiamondLane({
     ? Math.round(clipHeightPx * 0.45)
     : Math.round(LANE_H * DIAMOND_RATIO);
   const centerY = beatsActive ? BEAT_BAND_H + (clipHeightPx - BEAT_BAND_H) / 2 : clipHeightPx / 2;
+  // Hit-box height only — the glyph keeps `marker.visualSize`. 24 is the WCAG 2.2
+  // (2.5.8) minimum and still fits the 28px lane. Beat-strip lanes keep the
+  // shrunken box: 24px there would reach up into the beat strip.
+  const hitHeight = beatsActive ? diamondSize : 24;
   const sorted = keyframesData.keyframes
     .filter((kf) => kf.percentage >= KF_MIN_PCT && kf.percentage <= KF_MAX_PCT)
     .sort((a, b) => a.percentage - b.percentage);
@@ -412,7 +422,7 @@ export const TimelineDiamondLane = memo(function TimelineDiamondLane({
               top: centerY,
               transform: "translateY(-50%)",
               width: marker.hitWidth,
-              height: diamondSize,
+              height: hitHeight,
               zIndex: isHighlighted ? 2 : 1,
               pointerEvents: "auto",
               background: "none",

package/src/player/components/TimelineDiamondConnectors.tsx

@@ -62,6 +62,12 @@ export function TimelineDiamondConnectors({
         // no source animation id (runtime-scanned) so there is no tween to target.
         const target = keyframeTarget(kf);
         const ease = kf.ease ?? globalEase;
+        // connectorWidth is the clear span between the two diamonds' edges, so a
+        // 24x24 target centred in it overhangs a diamond as soon as the span is
+        // narrower than 24. The segment wrapper sits at z-index 3, above the
+        // diamonds, so that overhang would win the hit test and steal their
+        // clicks at fit zoom. Grow the target only where the room exists.
+        const roomForFullTarget = connectorWidth >= 24;
         return (
           <Fragment key={`line-${i}-${previous.keyframe.percentage}-${kf.percentage}`}>
             <div
@@ -103,7 +109,14 @@ export function TimelineDiamondConnectors({
                   data-keyframe-ease-button=""
                   aria-label={`Edit ${ease} easing`}
                   title={`Edit ${ease} easing`}
-                  className="absolute flex items-center justify-center rounded opacity-0 transition-opacity group-hover:opacity-100 focus-visible:opacity-100"
+                  // A visible 24x24 badge would collide with the diamonds either
+                  // side, so the WCAG 2.2 (2.5.8) target is met with a centered
+                  // transparent ::before overlay; the box stays 16x16. Where the
+                  // segment is too narrow for that overlay the button keeps its
+                  // 16x16 hit area, which is WCAG's target-spacing exception:
+                  // the neighbouring diamonds are themselves the reason it
+                  // cannot grow, and stealing their clicks is the worse failure.
+                  className={`absolute flex items-center justify-center rounded opacity-0 transition-opacity group-hover:opacity-100 focus-visible:opacity-100 ${roomForFullTarget ? "before:absolute before:left-1/2 before:top-1/2 before:h-6 before:w-6 before:-translate-x-1/2 before:-translate-y-1/2 before:content-['']" : ""}`}
                   style={{
                     left: "50%",
                     top: "50%",