@hyperframes/studio 0.8.8 → 0.8.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.8",
+  "version": "0.8.10",
   "description": "",
   "repository": {
     "type": "git",
@@ -47,11 +47,11 @@
     "gsap": "^3.13.0",
     "marked": "^14.1.4",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.8",
-    "@hyperframes/parsers": "0.8.8",
-    "@hyperframes/player": "0.8.8",
-    "@hyperframes/studio-server": "0.8.8",
-    "@hyperframes/sdk": "0.8.8"
+    "@hyperframes/core": "0.8.10",
+    "@hyperframes/parsers": "0.8.10",
+    "@hyperframes/player": "0.8.10",
+    "@hyperframes/sdk": "0.8.10",
+    "@hyperframes/studio-server": "0.8.10"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -68,7 +68,7 @@
     "vite": "^6.4.2",
     "vitest": "^3.2.4",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.8"
+    "@hyperframes/producer": "0.8.10"
   },
   "peerDependencies": {
     "react": "19",

package/src/components/editor/CanvasContextMenu.test.tsx

@@ -92,7 +92,7 @@ describe("CanvasContextMenu — handler gating", () => {
 
     // No menu opened at all — no buttons, no dead-end items, no DOM mutation.
     expect(menuButtons()).toHaveLength(0);
-    expect(document.body.querySelector(".fixed.z-50")).toBeNull();
+    expect(document.body.querySelector(".fixed.z-\\[200\\]")).toBeNull();
     expect(el.style.zIndex).toBe("3");
   });
 

package/src/components/editor/CanvasContextMenu.tsx

@@ -212,7 +212,7 @@ export const CanvasContextMenu = memo(function CanvasContextMenu({
   return createPortal(
     <div
       ref={menuRef}
-      className="fixed z-50 bg-neutral-900 border border-neutral-700 rounded-md shadow-lg py-1 min-w-[180px]"
+      className="fixed z-[200] bg-neutral-900 border border-neutral-700 rounded-md shadow-lg py-1 min-w-[180px]"
       style={{ left: adjustedX, top: adjustedY }}
       onPointerDown={stopBubble}
       onMouseDown={stopBubble}

package/src/components/editor/TimelineFxPopover.test.tsx

@@ -10,6 +10,28 @@ import { TimelineFxPopover } from "./TimelineFxPopover.js";
 const EMPTY_CHAIN: HfAudioFxChain = { version: 1, nodes: [] };
 const RECT = { left: 0, top: 0, right: 0, bottom: 0 } as DOMRect;
 
+function rect(top: number, bottom: number): DOMRect {
+  return { left: 0, top, right: 0, bottom } as DOMRect;
+}
+
+/** Pin the viewport height: every expected number below is derived from it, and
+ *  happy-dom's 768 default is not something this file should silently inherit. */
+function withViewportHeight<T>(value: number, run: () => T): T {
+  const previous = window.innerHeight;
+  Object.defineProperty(window, "innerHeight", { value, configurable: true });
+  try {
+    return run();
+  } finally {
+    Object.defineProperty(window, "innerHeight", { value: previous, configurable: true });
+  }
+}
+
+function dialogOf(host: HTMLElement): HTMLElement {
+  const el = host.querySelector('[role="dialog"]');
+  if (!el) throw new Error("no dialog");
+  return el as HTMLElement;
+}
+
 function byTextButton(host: HTMLElement, text: string): HTMLButtonElement | undefined {
   return Array.from(host.querySelectorAll("button")).find((b) => b.textContent?.includes(text));
 }
@@ -102,6 +124,73 @@ describe("TimelineFxPopover", () => {
     expect(onClose).not.toHaveBeenCalled();
   });
 
+  // These guard the regression that shipped once already: an uncapped
+  // popover grew past the gap it opened into, ran under the timeline chrome and
+  // took its footer with it, and nothing scrolled.
+  it("caps its height to the space below when it opens downward", () => {
+    // spaceBelow 738 > spaceAbove 10, so it opens down: 738 - margin(8) - gap(4).
+    const dialog = withViewportHeight(768, () =>
+      dialogOf(mount({ anchorRect: rect(10, 30) }).host),
+    );
+    expect(dialog.style.top).toBe("34px");
+    expect(dialog.style.maxHeight).toBe("726px");
+  });
+
+  it("caps its height to the space above when it flips upward", () => {
+    // spaceBelow 48 < 260 and spaceAbove 700 is larger, so it flips up.
+    const dialog = withViewportHeight(768, () =>
+      dialogOf(mount({ anchorRect: rect(700, 720) }).host),
+    );
+    expect(dialog.style.bottom).toBe("72px");
+    expect(dialog.style.maxHeight).toBe("688px");
+  });
+
+  it("never caps below a usable minimum, however tight the gap", () => {
+    // Both gaps are tiny (80 below / 100 above); the cap must not collapse.
+    const dialog = withViewportHeight(200, () =>
+      dialogOf(mount({ anchorRect: rect(100, 120) }).host),
+    );
+    expect(dialog.style.maxHeight).toBe("160px");
+  });
+
+  it("keeps both edges in the viewport when the minimum exceeds the gap", () => {
+    // The case the minimum used to lose: at 200px of viewport (roughly 400% zoom
+    // on a laptop) neither gap can hold 160px, so honouring the floor has to
+    // slide the box in rather than hang its top edge off-screen.
+    const dialog = withViewportHeight(200, () =>
+      dialogOf(mount({ anchorRect: rect(100, 120) }).host),
+    );
+    // bottom:32 + maxHeight:160 puts the box at y = 8..168 — a margin on each side.
+    expect(dialog.style.bottom).toBe("32px");
+    const bottom = Number.parseFloat(dialog.style.bottom);
+    const height = Number.parseFloat(dialog.style.maxHeight);
+    expect(bottom).toBeGreaterThanOrEqual(8);
+    expect(200 - bottom - height).toBeGreaterThanOrEqual(8);
+  });
+
+  it("shrinks below the minimum only when the whole window is shorter", () => {
+    // A floor against a tight gap is not a floor against a tight window: 120px of
+    // viewport cannot hold 160px, and hanging off the edge is worse than short.
+    const dialog = withViewportHeight(120, () =>
+      dialogOf(mount({ anchorRect: rect(60, 80) }).host),
+    );
+    expect(dialog.style.maxHeight).toBe("104px");
+    expect(dialog.style.bottom).toBe("8px");
+  });
+
+  it("scrolls the preset list and leaves the footer outside the scroller", () => {
+    const { host } = mount();
+    const dialog = dialogOf(host);
+    const scroller = dialog.querySelector(".overflow-y-auto");
+    expect(scroller).toBeTruthy();
+    // The footer must be a SIBLING of the scroller, not inside it — otherwise it
+    // scrolls away instead of staying put, which is the original bug.
+    const footer = byTextButton(host, "Open rack");
+    expect(footer).toBeDefined();
+    expect(scroller?.contains(footer as Node)).toBe(false);
+    expect(dialog.contains(footer as Node)).toBe(true);
+  });
+
   it("the footer opens the rack and closes the popover", () => {
     const { host, onOpenRack, onClose } = mount();
     const openRack = byTextButton(host, "Open rack");

package/src/components/editor/TimelineFxPopover.tsx

@@ -17,6 +17,8 @@ import { useFxAudition } from "./useFxAudition.js";
 
 const POPOVER_WIDTH = 260;
 const VIEWPORT_MARGIN = 8;
+/** Below this the popover is useless anyway; it scrolls instead of vanishing. */
+const MIN_POPOVER_HEIGHT = 160;
 
 function clampedStyle(anchorRect: DOMRect): CSSProperties {
   const left = Math.min(
@@ -24,14 +26,41 @@ function clampedStyle(anchorRect: DOMRect): CSSProperties {
     Math.max(VIEWPORT_MARGIN, window.innerWidth - POPOVER_WIDTH - VIEWPORT_MARGIN),
   );
   const spaceBelow = window.innerHeight - anchorRect.bottom;
-  const openUpward = spaceBelow < 260 && anchorRect.top > spaceBelow;
+  // Named, because the height cap below needs the same quantity the flip does.
+  // (`spaceAbove === anchorRect.top` for a viewport-relative rect, so the flip
+  // condition itself is unchanged — this is a rename, not a behaviour fix.)
+  const spaceAbove = anchorRect.top;
+  const openUpward = spaceBelow < 260 && spaceAbove > spaceBelow;
+  // Flipping direction alone is not enough: the preset list is taller than either
+  // gap on a short window, so the popover ran off the top or the bottom and its
+  // footer ("+ effect" / "Open rack") went with it. Cap to whatever the chosen
+  // side actually has and let the list scroll inside that.
+  const available = (openUpward ? spaceAbove : spaceBelow) - VIEWPORT_MARGIN - 4;
+  // The minimum is a floor against a tight GAP, not against a tight window: keep
+  // a usable list when the gap is smaller than 160px, but never ask for more
+  // height than the viewport itself can hold.
+  const height = Math.min(
+    Math.max(MIN_POPOVER_HEIGHT, available),
+    window.innerHeight - VIEWPORT_MARGIN * 2,
+  );
+  // A floor larger than the gap would hang the box off the edge it opened away
+  // from — reachable at high browser zoom, where both gaps fall under ~172px.
+  // Slide it back in-bounds the way `left` is already clamped, rather than
+  // shrinking below the floor: the offset that keeps BOTH edges inside is
+  // `innerHeight - height - VIEWPORT_MARGIN`, from either side.
+  const inset = (desired: number) =>
+    Math.max(
+      VIEWPORT_MARGIN,
+      Math.min(desired, Math.max(VIEWPORT_MARGIN, window.innerHeight - height - VIEWPORT_MARGIN)),
+    );
   return {
     position: "fixed",
     left,
     width: POPOVER_WIDTH,
+    maxHeight: height,
     ...(openUpward
-      ? { bottom: window.innerHeight - anchorRect.top + 4 }
-      : { top: anchorRect.bottom + 4 }),
+      ? { bottom: inset(window.innerHeight - anchorRect.top + 4) }
+      : { top: inset(anchorRect.bottom + 4) }),
   };
 }
 
@@ -96,22 +125,27 @@ export function TimelineFxPopover({
       ref={rootRef}
       role="dialog"
       aria-label="Effects"
-      className="z-50 rounded-md border border-white/10 bg-[#1b1b1f] p-2 shadow-xl"
+      className="z-[200] flex flex-col overflow-hidden rounded-md border border-white/10 bg-[#1b1b1f] p-2 shadow-xl"
       style={clampedStyle(anchorRect)}
       onKeyDown={onKeyDown}
       onPointerDown={(event) => event.stopPropagation()}
     >
-      <FxPresetMenu
-        trackKind={trackKind}
-        onPick={applyPreset}
-        onAudition={
-          onChainPreview
-            ? (id) =>
-                audition(id ? (base) => applyPresetToChain(base, id, trackKind) ?? base : null)
-            : undefined
-        }
-      />
-      <div className="mt-2 flex items-center justify-between border-t border-white/10 pt-2 text-[10px] text-white/55">
+      {/* The list scrolls; the footer below stays put. `min-h-0` is load-bearing
+          — a flex child defaults to min-height:auto and would refuse to shrink,
+          pushing the footer out of the popover instead of scrolling. */}
+      <div className="min-h-0 flex-1 overflow-y-auto">
+        <FxPresetMenu
+          trackKind={trackKind}
+          onPick={applyPreset}
+          onAudition={
+            onChainPreview
+              ? (id) =>
+                  audition(id ? (base) => applyPresetToChain(base, id, trackKind) ?? base : null)
+              : undefined
+          }
+        />
+      </div>
+      <div className="mt-2 flex shrink-0 items-center justify-between border-t border-white/10 pt-2 text-[10px] text-white/55">
         <button
           type="button"
           className="hover:text-white"

package/src/components/renders/useRenderQueue.ts

@@ -250,12 +250,19 @@ export function useRenderQueue(projectId: string | null) {
           headers: { "Content-Type": "application/json" },
           body: JSON.stringify(body),
         });
-      } catch {
+      } catch (err) {
+        // The cause used to be discarded. Every failure — a dead server, an
+        // aborted request, a DNS error, a mid-render crash — surfaced as the
+        // same sentence, and this string is what travels into the feedback
+        // report too, so field reports of a render that fails *every time*
+        // still carried nothing to act on. Keep the CLI guidance, name the
+        // cause after it.
+        const cause = err instanceof Error ? err.message : String(err);
         const failedJob: RenderJob = {
           id: generateId(),
           status: "failed",
           progress: 0,
-          error: "Could not reach render server. Use `hyperframes render` from the CLI instead.",
+          error: `Could not reach render server: ${cause}. Use \`hyperframes render\` from the CLI instead.`,
           filename: "Export failed",
           createdAt: startTime,
         };

package/src/components/renders/useRenderQueueTransportError.test.tsx

@@ -0,0 +1,49 @@
+// @vitest-environment happy-dom
+
+// The render POST's catch used to discard its error, so a dead server, a DNS
+// failure and a mid-render crash all produced one sentence. That string is also
+// what travels into the feedback report, so three field reports — one of them a
+// render that failed EVERY time — arrived with nothing to act on.
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { mountRenderQueue } from "./renderQueueTestHarness";
+
+vi.mock("./useFfmpegStatus", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("./useFfmpegStatus")>()),
+  useFfmpegStatus: () => ({ status: { ok: true }, checking: false, recheck: vi.fn() }),
+}));
+vi.mock("../../telemetry/events", () => ({ trackStudioRenderStart: vi.fn() }));
+
+const { useRenderQueue } = await import("./useRenderQueue");
+
+let queue: ReturnType<typeof mountRenderQueue> | null = null;
+
+beforeEach(() => {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(() => Promise.reject(new TypeError("Failed to fetch"))),
+  );
+});
+
+afterEach(() => {
+  queue?.unmount();
+  queue = null;
+  document.body.innerHTML = "";
+  vi.unstubAllGlobals();
+});
+
+describe("useRenderQueue transport failure", () => {
+  it("names the cause instead of collapsing every failure into one sentence", async () => {
+    queue = mountRenderQueue(useRenderQueue);
+    const { act } = await import("react");
+    await act(async () => {
+      await queue?.api().startRender({});
+    });
+
+    const job = queue.api().jobs.at(-1);
+    expect(job?.status).toBe("failed");
+    expect(job?.error).toContain("Failed to fetch");
+    // The CLI guidance still earns its place; it just no longer stands alone.
+    expect(job?.error).toContain("hyperframes render");
+  });
+});

package/src/player/components/AutomationSelectionMenu.tsx

@@ -41,7 +41,7 @@ export const AutomationSelectionMenu = memo(function AutomationSelectionMenu({
   return createPortal(
     <div
       ref={menuRef}
-      className="hf-automation-menu fixed z-50 min-w-[140px] rounded border border-panel-border-input bg-panel-bg-2 py-1 shadow-lg"
+      className="hf-automation-menu fixed z-[200] min-w-[140px] rounded border border-panel-border-input bg-panel-bg-2 py-1 shadow-lg"
       style={{ left: adjustedX, top: adjustedY }}
     >
       {AUTOMATION_SHAPES.map((shape) => (

package/src/player/components/ClipContextMenu.tsx

@@ -48,7 +48,7 @@ export const ClipContextMenu = memo(function ClipContextMenu({
       ref={menuRef}
       role="menu"
       aria-label="Clip actions"
-      className="fixed z-50 bg-neutral-900 border border-neutral-700 rounded-md shadow-lg py-1 min-w-[180px]"
+      className="fixed z-[200] bg-neutral-900 border border-neutral-700 rounded-md shadow-lg py-1 min-w-[180px]"
       style={{ left: adjustedX, top: adjustedY }}
     >
       {splitLabel && (

package/src/player/components/KeyframeDiamondContextMenu.tsx

@@ -96,7 +96,7 @@ export function KeyframeDiamondContextMenu({
       ref={menuRef}
       role="menu"
       aria-label="Keyframe actions"
-      className="fixed z-50 bg-neutral-900 border border-neutral-700 rounded-md shadow-lg py-1 min-w-[180px] overflow-y-auto"
+      className="fixed z-[200] bg-neutral-900 border border-neutral-700 rounded-md shadow-lg py-1 min-w-[180px] overflow-y-auto"
       style={{ left: adjustedX, top: adjustedY, maxHeight: `calc(100vh - ${adjustedY + 8}px)` }}
     >
       {onMoveToPlayhead && (

package/src/player/components/TimelineFxButton.tsx

@@ -79,7 +79,7 @@ export function TimelineFxButton(props: TimelineFxButtonProps) {
             <div
               role="dialog"
               aria-label="Group these clips to add effects"
-              className="z-50 w-56 rounded-md border border-white/10 bg-[#1b1b1f] p-2.5 text-[11px] text-white/75 shadow-xl"
+              className="z-[200] w-56 rounded-md border border-white/10 bg-[#1b1b1f] p-2.5 text-[11px] text-white/75 shadow-xl"
               style={{ position: "fixed", left: anchorRect.left, top: anchorRect.bottom + 4 }}
               onPointerDown={(event) => event.stopPropagation()}
             >

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

@@ -0,0 +1,76 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { TimelineGroupHeader } from "./TimelineGroupHeader";
+import { defaultTimelineTheme } from "./timelineTheme";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+function renderHeader(
+  overrides: Partial<React.ComponentProps<typeof TimelineGroupHeader>> = {},
+): HTMLElement {
+  const host = document.createElement("div");
+  document.body.append(host);
+  act(() => {
+    createRoot(host).render(
+      <TimelineGroupHeader
+        label="Voiceover"
+        memberCount={5}
+        isExpanded={false}
+        onToggleExpanded={vi.fn()}
+        laneCount={0}
+        isLaneOpen={false}
+        onToggleLanes={vi.fn()}
+        hidden={false}
+        onToggleHidden={vi.fn()}
+        isSoloed={false}
+        isHalfLitSolo={false}
+        onToggleSolo={vi.fn()}
+        onFxChainChange={vi.fn()}
+        onOpenFxRack={vi.fn()}
+        columnWidth={220}
+        theme={defaultTimelineTheme}
+        {...overrides}
+      />,
+    );
+  });
+  return host;
+}
+
+/** The structural disclosure — the caret, not the `∿` lane toggle. */
+function caret(host: HTMLElement): HTMLButtonElement {
+  const el = Array.from(host.querySelectorAll("button")).find((b) =>
+    b.getAttribute("aria-label")?.includes("tracks"),
+  );
+  if (!el) throw new Error("no disclosure caret");
+  return el as HTMLButtonElement;
+}
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+describe("TimelineGroupHeader disclosure caret", () => {
+  // Guards a regression that shipped once: the caret silently reverted to a
+  // smaller, non-mono, rotated glyph unlike the property panel's carets.
+  it("swaps the glyph rather than rotating one", () => {
+    expect(caret(renderHeader({ isExpanded: false })).textContent).toContain("▸");
+    expect(caret(renderHeader({ isExpanded: true })).textContent).toContain("▾");
+  });
+
+  it("does not rotate the glyph", () => {
+    const glyph = caret(renderHeader({ isExpanded: true })).querySelector("span");
+    expect(glyph?.getAttribute("style") ?? "").not.toContain("rotate");
+  });
+
+  it("keeps the caret mono at 13px, not back down at the 11px the row inherits", () => {
+    // Only this component's own className — the panel carets are not read here,
+    // and this does not claim to pin a match against them.
+    const className = caret(renderHeader()).className;
+    expect(className).toContain("font-mono");
+    expect(className).toContain("text-[13px]");
+    expect(className).not.toContain("text-[11px]");
+  });
+});

package/src/player/components/TimelineGroupHeader.tsx

@@ -77,7 +77,11 @@ export function TimelineGroupHeader({
         aria-expanded={isExpanded}
         aria-label={`${isExpanded ? "Hide" : "Show"} ${label} tracks`}
         title={`${isExpanded ? "Hide" : "Show"} tracks`}
-        className={`flex h-6 w-6 shrink-0 items-center justify-center rounded border-0 bg-transparent p-0 text-[11px] focus-visible:outline focus-visible:outline-1 focus-visible:outline-[#3CE6AC] ${
+        // Mono, like both of the property panel's disclosure carets. The size is
+        // this row's own call and not a match to either of them: the node-body
+        // caret sits under `text-[9px]`, and `hf-fx-preset-run-caret` has no
+        // size rule at all, so there is no measured target to match.
+        className={`flex h-6 w-6 shrink-0 items-center justify-center rounded border-0 bg-transparent p-0 font-mono text-[13px] focus-visible:outline focus-visible:outline-1 focus-visible:outline-[#3CE6AC] ${
           isExpanded ? "text-white" : "text-white/55 hover:text-white"
         }`}
         onPointerDown={(event) => event.stopPropagation()}
@@ -86,9 +90,9 @@ export function TimelineGroupHeader({
           onToggleExpanded();
         }}
       >
-        <span aria-hidden="true" style={{ transform: isExpanded ? "rotate(90deg)" : undefined }}>
-          ▸
-        </span>
+        {/* Swapped, not rotated: both panel carets swap, and a rotated ▸ sits
+            off-centre in its box because the glyph is not square. */}
+        <span aria-hidden="true">{isExpanded ? "▾" : "▸"}</span>
       </button>
       <span aria-hidden="true" className="shrink-0 text-[12px] leading-none text-white/50">
         ▤

package/src/player/components/TrackGapContextMenu.tsx

@@ -75,7 +75,7 @@ export const TrackGapContextMenu = memo(function TrackGapContextMenu({
   return createPortal(
     <div
       ref={menuRef}
-      className="fixed z-50 bg-neutral-900 border border-neutral-700 rounded-md shadow-lg py-1 min-w-[180px]"
+      className="fixed z-[200] bg-neutral-900 border border-neutral-700 rounded-md shadow-lg py-1 min-w-[180px]"
       style={{ left: adjustedX, top: adjustedY }}
       onPointerLeave={() => onHoverAction(null)}
     >