@hyperframes/studio 0.8.4 → 0.8.6

package/package.json

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

package/src/components/storyboard/FramePoster.test.tsx

@@ -0,0 +1,61 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it } from "vitest";
+import { FramePoster } from "./FramePoster";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const roots: Root[] = [];
+
+afterEach(() => {
+  act(() => roots.splice(0).forEach((root) => root.unmount()));
+  document.body.replaceChildren();
+});
+
+// A fresh host per render: several cases compare two surfaces side by side.
+function renderPoster(surface?: "tile" | "hero"): HTMLImageElement {
+  const host = document.createElement("div");
+  document.body.appendChild(host);
+  const root = createRoot(host);
+  roots.push(root);
+  act(() => {
+    root.render(
+      <FramePoster
+        projectId="demo"
+        src="frames/01-hero.html"
+        seconds={3}
+        title="hero"
+        surface={surface}
+      />,
+    );
+  });
+  const img = host.querySelector("img");
+  if (!img) throw new Error("poster did not render an <img>");
+  return img;
+}
+
+describe("FramePoster", () => {
+  // Regression: the contact sheet stretched a 240x135 capture across a wide,
+  // high-density card, making body copy, thin lines, and sprite details blurry.
+  it.each([
+    [undefined, "storyboard"],
+    ["tile", "storyboard"],
+    ["hero", "source"],
+  ] as const)("captures the %s surface at %s density", (surface, output) => {
+    const url = new URL(renderPoster(surface).src);
+
+    expect(url.searchParams.get("output")).toBe(output);
+    expect(url.pathname).toBe("/api/projects/demo/thumbnail/frames/01-hero.html");
+  });
+
+  it("defaults to the tile surface", () => {
+    expect(renderPoster().className).toBe(renderPoster("tile").className);
+  });
+
+  it("letterboxes only the hero, so a tile still fills its cell", () => {
+    expect(renderPoster("hero").className).toContain("object-contain");
+    expect(renderPoster("tile").className).toContain("object-cover");
+  });
+});

package/src/components/storyboard/FramePoster.tsx

@@ -8,8 +8,13 @@ export interface FramePosterProps {
   /** Time (seconds) to seek to for the poster. */
   seconds: number;
   title: string;
-  /** `cover` fills+crops (contact-sheet tile); `contain` letterboxes (focus hero). */
-  fit?: "cover" | "contain";
+  /**
+   * Where this poster is rendered. A contact-sheet tile is ~300px wide and there
+   * are many of them; the focus hero is up to 900px wide and there is exactly
+   * one. Tiles use a bounded high-density capture; the hero uses source density.
+   * The surface also decides whether the result fills or letterboxes its cell.
+   */
+  surface?: "tile" | "hero";
   /**
    * Project content signature to key the poster URL on. The thumbnail route
    * regenerates when the frame's source changes, but the browser only refetches
@@ -30,14 +35,14 @@ export function FramePoster({
   src,
   seconds,
   title,
-  fit = "cover",
+  surface = "tile",
   posterVersion,
 }: FramePosterProps) {
   const [failed, setFailed] = useState(false);
   // The <img> is reused (no key) when a tile/hero swaps to a different frame, so a
   // prior load error would stick. Reset when the poster target changes — including
   // a new posterVersion, so a frame that failed mid-write retries once it settles.
-  useEffect(() => setFailed(false), [src, seconds, posterVersion]);
+  useEffect(() => setFailed(false), [src, seconds, posterVersion, surface]);
   if (failed) {
     return (
       <div className="flex h-full w-full items-center justify-center text-[11px] text-neutral-600">
@@ -50,6 +55,10 @@ export function FramePoster({
     seekTime: seconds,
     duration: 0,
     origin: window.location.origin,
+    // The normal 240x135 preview is unreadable in the contact sheet, while source
+    // density is unbounded across all tiles. Give tiles a capped review density
+    // and reserve true source output for the single focus hero.
+    output: surface === "hero" ? "source" : "storyboard",
   });
   if (posterVersion) {
     const withVersion = new URL(url, window.location.origin);
@@ -63,7 +72,7 @@ export function FramePoster({
       draggable={false}
       loading="lazy"
       onError={() => setFailed(true)}
-      className={`h-full w-full ${fit === "contain" ? "object-contain" : "object-cover"}`}
+      className={`h-full w-full ${surface === "hero" ? "object-contain" : "object-cover"}`}
     />
   );
 }

package/src/components/storyboard/StoryboardFrameFocus.tsx

@@ -224,7 +224,7 @@ export function StoryboardFrameFocus({
                 src={frame.src}
                 seconds={posterTime(frame)}
                 title={title}
-                fit="contain"
+                surface="hero"
                 posterVersion={posterVersion}
               />
             ) : (

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

@@ -76,6 +76,21 @@ describe("buildCompositionThumbnailUrl", () => {
       "http://localhost:3000/api/projects/demo/thumbnail/index.html?t=2.00&v=v3&selector=.card&selectorIndex=2",
     );
   });
+
+  it("asks for source density only when a caller opts in", () => {
+    const base = {
+      previewUrl: "/api/projects/demo/preview",
+      seekTime: 1,
+      duration: 0,
+      origin: "http://localhost:3000",
+    };
+
+    expect(buildCompositionThumbnailUrl(base)).not.toContain("output=");
+    expect(buildCompositionThumbnailUrl({ ...base, output: "source" })).toContain("output=source");
+    expect(buildCompositionThumbnailUrl({ ...base, output: "storyboard" })).toContain(
+      "output=storyboard",
+    );
+  });
 });
 
 describe("CompositionThumbnail", () => {

package/src/player/components/CompositionThumbnail.tsx

@@ -31,6 +31,7 @@ export function buildCompositionThumbnailUrl({
   selector,
   selectorIndex,
   origin,
+  output,
 }: {
   previewUrl: string;
   seekTime?: number;
@@ -38,6 +39,13 @@ export function buildCompositionThumbnailUrl({
   selector?: string;
   selectorIndex?: number;
   origin: string;
+  /**
+   * Capture density. Omitted, the route bounds the image to its preview cap —
+   * right for the timeline, where thumbnails are small and numerous and their
+   * decoded bytes are budgeted. `"storyboard"` caps the longest side at a
+   * high-density review size; `"source"` uses the composition's own dimensions.
+   */
+  output?: "source" | "storyboard";
 }): string {
   const thumbnailBase = previewUrl
     .replace("/preview/comp/", "/thumbnail/")
@@ -45,6 +53,7 @@ export function buildCompositionThumbnailUrl({
   const thumbnailUrl = new URL(thumbnailBase, origin);
   thumbnailUrl.searchParams.set("t", (seekTime + duration / 2).toFixed(2));
   thumbnailUrl.searchParams.set("v", THUMBNAIL_URL_VERSION);
+  if (output) thumbnailUrl.searchParams.set("output", output);
   if (selector) {
     thumbnailUrl.searchParams.set("selector", selector);
     if (selectorIndex != null && selectorIndex > 0) {

package/src/player/hooks/useExpandedTimelineElements.test.ts

@@ -1,12 +1,19 @@
-import { describe, expect, it } from "vitest";
+// @vitest-environment happy-dom
+
+import React, { act, useEffect } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it } from "vitest";
 import {
   buildExpandedElements,
   resolveTimelineExpansionRawId,
+  useExpandedTimelineElements,
 } from "./useExpandedTimelineElements";
 import { buildTimelineElementKey } from "../lib/timelineElementHelpers";
-import type { TimelineElement } from "../store/playerStore";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import type { ClipManifestClip } from "../lib/playbackTypes";
 
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
 const clip = (over: Partial<ClipManifestClip>): ClipManifestClip => ({
   id: "x",
   label: "x",
@@ -31,6 +38,19 @@ const el = (over: Partial<TimelineElement>): TimelineElement => ({
   ...over,
 });
 
+function TimelineExpansionHarness({ onValue }: { onValue: (value: TimelineElement[]) => void }) {
+  const value = useExpandedTimelineElements();
+  useEffect(() => {
+    onValue(value);
+  }, [onValue, value]);
+  return null;
+}
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  usePlayerStore.getState().reset();
+});
+
 describe("buildExpandedElements", () => {
   it("rebases a 1-level child onto its sub-comp host (start + sourceFile)", () => {
     // host s3 at absolute 16 → stats-panel.html; children live in that file.
@@ -357,7 +377,7 @@ describe("buildExpandedElements", () => {
   it("keeps the host row present at every playhead position (keyframe lane repro)", () => {
     // Live repro with no drag at all: seek 0 gave 3 diamonds, seek 7.68 gave 0,
     // seek 0.2 gave 3. Diamonds render per row from keyframeCache.get(elementKey),
-    // so the whole lane went with the host row whenever the paused drill-in
+    // so the whole lane went with the host row whenever the store-time drill-in
     // substituted it for its children.
     const elements = [
       el({ id: "scene", domId: "scene", key: "index.html#scene", start: 0, duration: 12 }),
@@ -371,7 +391,6 @@ describe("buildExpandedElements", () => {
     for (const currentTime of [0, 7.68, 0.2]) {
       const rawId = resolveTimelineExpansionRawId({
         selectedElementId: null,
-        isPlaying: false,
         currentTime,
         manifest,
         parentMap,
@@ -424,13 +443,12 @@ describe("buildExpandedElements", () => {
 });
 
 describe("resolveTimelineExpansionRawId", () => {
-  it("returns null when paused inside a childless top-level clip", () => {
+  it("returns null inside a childless top-level clip", () => {
     const manifest = [clip({ id: "title", start: 0, duration: 4 })];
 
     expect(
       resolveTimelineExpansionRawId({
         selectedElementId: null,
-        isPlaying: false,
         currentTime: 2,
         manifest,
         parentMap: new Map(),
@@ -438,7 +456,7 @@ describe("resolveTimelineExpansionRawId", () => {
     ).toBeNull();
   });
 
-  it("auto-expands an active composition with children when paused and nothing is selected", () => {
+  it("auto-expands an active composition with children when nothing is selected", () => {
     const manifest = [
       clip({ id: "scene", start: 1, duration: 5 }),
       clip({ id: "headline", start: 1.5, duration: 2 }),
@@ -448,7 +466,6 @@ describe("resolveTimelineExpansionRawId", () => {
     expect(
       resolveTimelineExpansionRawId({
         selectedElementId: null,
-        isPlaying: false,
         currentTime: 2,
         manifest,
         parentMap,
@@ -468,7 +485,6 @@ describe("resolveTimelineExpansionRawId", () => {
     expect(
       resolveTimelineExpansionRawId({
         selectedElementId: null,
-        isPlaying: false,
         currentTime: 12,
         manifest,
         parentMap,
@@ -491,7 +507,6 @@ describe("resolveTimelineExpansionRawId", () => {
     expect(
       resolveTimelineExpansionRawId({
         selectedElementId: null,
-        isPlaying: false,
         currentTime: 5,
         manifest,
         parentMap,
@@ -499,7 +514,7 @@ describe("resolveTimelineExpansionRawId", () => {
     ).toBe("second");
   });
 
-  it("auto-expands the innermost active nested composition when paused", () => {
+  it("auto-expands the innermost active nested composition", () => {
     const manifest = [
       clip({ id: "outer", start: 0, duration: 10 }),
       clip({ id: "inner", start: 2, duration: 5 }),
@@ -513,7 +528,6 @@ describe("resolveTimelineExpansionRawId", () => {
     expect(
       resolveTimelineExpansionRawId({
         selectedElementId: null,
-        isPlaying: false,
         currentTime: 3.5,
         manifest,
         parentMap,
@@ -521,7 +535,7 @@ describe("resolveTimelineExpansionRawId", () => {
     ).toBe("inner");
   });
 
-  it("does not auto-expand an active composition while playing", () => {
+  it("resolves an active composition from the current store time", () => {
     const manifest = [
       clip({ id: "scene", start: 0, duration: 5 }),
       clip({ id: "headline", start: 1, duration: 2 }),
@@ -531,15 +545,49 @@ describe("resolveTimelineExpansionRawId", () => {
     expect(
       resolveTimelineExpansionRawId({
         selectedElementId: null,
-        isPlaying: true,
         currentTime: 2,
         manifest,
         parentMap,
       }),
-    ).toBeNull();
+    ).toBe("scene");
+  });
+
+  it("keeps inline children visible when the master timeline is playing", () => {
+    const elements = [
+      el({ id: "scene", domId: "scene", key: "index.html#scene", start: 0, duration: 5 }),
+    ];
+    const manifest = [
+      clip({ id: "scene", start: 0, duration: 5, compositionSrc: "scene.html" }),
+      clip({ id: "headline", start: 1, duration: 2 }),
+    ];
+    const parentMap = new Map([["headline", "scene"]]);
+    let rows: TimelineElement[] | undefined;
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+
+    act(() => {
+      usePlayerStore.setState({
+        elements,
+        clipManifest: manifest,
+        clipParentMap: parentMap,
+        currentTime: 2,
+        isPlaying: true,
+      });
+      root.render(
+        React.createElement(TimelineExpansionHarness, {
+          onValue: (value) => (rows = value),
+        }),
+      );
+    });
+
+    expect(usePlayerStore.getState().isPlaying).toBe(true);
+    expect(rows?.map((row) => row.domId ?? row.id)).toEqual(["scene", "headline"]);
+
+    act(() => root.unmount());
   });
 
-  it("keeps selected elements ahead of paused active composition auto-expansion", () => {
+  it("keeps selected elements ahead of active composition auto-expansion", () => {
     const manifest = [
       clip({ id: "scene", start: 0, duration: 6 }),
       clip({ id: "headline", start: 1, duration: 2 }),
@@ -553,7 +601,6 @@ describe("resolveTimelineExpansionRawId", () => {
     expect(
       resolveTimelineExpansionRawId({
         selectedElementId: "caption",
-        isPlaying: false,
         currentTime: 1.5,
         manifest,
         parentMap,

package/src/player/hooks/useExpandedTimelineElements.ts

@@ -35,7 +35,6 @@ function resolveRawId(
 
 interface TimelineExpansionRawIdInput {
   selectedElementId: string | null;
-  isPlaying: boolean;
   currentTime: number;
   manifest: ClipManifestClip[];
   parentMap: Map<string, string>;
@@ -97,14 +96,12 @@ function findActiveExpandableCompositionId(
 
 export function resolveTimelineExpansionRawId({
   selectedElementId,
-  isPlaying,
   currentTime,
   manifest,
   parentMap,
 }: TimelineExpansionRawIdInput): string | null {
   const selectedRawId = resolveRawId(selectedElementId, manifest, parentMap);
   if (selectedRawId) return selectedRawId;
-  if (isPlaying) return null;
   return findActiveExpandableCompositionId(currentTime, manifest, parentMap);
 }
 
@@ -334,7 +331,7 @@ export function buildExpandedElements(
       : (el.key ?? el.id) === parentKey;
 
   // ADDITIVE drill-in: the host row stays and its children are appended under
-  // it. Expansion is also triggered by the playhead alone (paused auto-expand),
+  // it. Expansion is also triggered by the playhead alone (active auto-expand),
   // so substituting the host row made it vanish on an ordinary seek, and with
   // it the host's keyframe lane, since diamonds render per row from
   // `keyframeCache.get(elementKey)`. The synthetic fractional lanes above sit
@@ -356,13 +353,14 @@ export function useExpandedTimelineElements(): TimelineElement[] {
   const clipParentMap = usePlayerStore((s) => s.clipParentMap);
   const domClipChildren = usePlayerStore((s) => s.domClipChildren);
   const selectedElementId = usePlayerStore((s) => s.selectedElementId);
-  const isPlaying = usePlayerStore((s) => s.isPlaying);
   const currentTime = usePlayerStore((s) => s.currentTime);
 
-  // Resolve which raw clip drives expansion. This reads currentTime (for paused
-  // auto-expand) so it re-runs each scrub tick, but it's a cheap manifest scan and
-  // its RESULT only changes when the playhead crosses a composition boundary. Keying
-  // the expensive build below on these ids (not raw currentTime) avoids re-allocating
+  // Resolve which raw clip drives expansion from the store's committed playhead
+  // time. The RAF loop keeps live time out of React and Zustand during playback,
+  // so this target deliberately stays stable until the loop commits or a seek /
+  // pause updates the store. The scan re-runs on scrub ticks, but its RESULT only
+  // changes when the playhead crosses a composition boundary. Keying the expensive
+  // build below on these ids (not raw currentTime) avoids re-allocating
   // expandedElements — and cascading TimelineClip re-renders — on every tick.
   const { rawId, selectedRawId } = useMemo(() => {
     if (!clipManifest || clipManifest.length === 0 || clipParentMap.size === 0) {
@@ -371,14 +369,13 @@ export function useExpandedTimelineElements(): TimelineElement[] {
     return {
       rawId: resolveTimelineExpansionRawId({
         selectedElementId,
-        isPlaying,
         currentTime,
         manifest: clipManifest,
         parentMap: clipParentMap,
       }),
       selectedRawId: resolveRawId(selectedElementId, clipManifest, clipParentMap),
     };
-  }, [clipManifest, clipParentMap, selectedElementId, isPlaying, currentTime]);
+  }, [clipManifest, clipParentMap, selectedElementId, currentTime]);
 
   return useMemo(() => {
     if (!clipManifest || clipManifest.length === 0 || clipParentMap.size === 0) {