@hyperframes/studio 0.8.4 → 0.8.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "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.5",
+    "@hyperframes/parsers": "0.8.5",
+    "@hyperframes/player": "0.8.5",
+    "@hyperframes/sdk": "0.8.5",
+    "@hyperframes/studio-server": "0.8.5"
   },
   "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.5"
   },
   "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) {