@hyperframes/studio 0.8.139 → 0.8.141

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

@@ -0,0 +1,164 @@
+// @vitest-environment happy-dom
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { StyleSections } from "./propertyPanelStyleSections";
+import { FlatStyleSection } from "./propertyPanelFlatStyleSections";
+import type { DomEditSelection } from "./domEditing";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+function mount(
+  Panel: typeof StyleSections | typeof FlatStyleSection,
+  tag = "img",
+  sourceFile = "index.html",
+  src = "assets/old.png",
+) {
+  const selected = document.createElement(tag);
+  selected.id = "picture";
+  selected.setAttribute("src", src);
+  document.body.append(selected);
+  const element: DomEditSelection = {
+    element: selected,
+    id: "picture",
+    selector: "#picture",
+    label: "Picture",
+    tagName: tag,
+    sourceFile,
+    compositionPath: sourceFile,
+    isCompositionHost: false,
+    isInsideLockedComposition: false,
+    boundingBox: { x: 0, y: 0, width: 320, height: 180 },
+    textContent: "",
+    dataAttributes: {},
+    inlineStyles: {},
+    computedStyles: {},
+    textFields: [],
+    capabilities: {
+      canSelect: true,
+      canEditStyles: true,
+      canCrop: true,
+      canMove: true,
+      canResize: true,
+      canApplyManualOffset: true,
+      canApplyManualSize: true,
+      canApplyManualRotation: true,
+    },
+  };
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  const onSetStyle = vi.fn((prop: string, value: string) =>
+    selected.style.setProperty(prop, value),
+  );
+  const onSetHtmlAttribute = vi.fn((attr: string, value: string | null) => {
+    if (value !== null) selected.setAttribute(attr, value);
+  });
+  act(() =>
+    root.render(
+      <Panel
+        projectId="fixture"
+        element={element}
+        styles={{}}
+        assets={["assets/old.png", "assets/new.png"]}
+        onSetStyle={onSetStyle}
+        onSetHtmlAttribute={onSetHtmlAttribute}
+      />,
+    ),
+  );
+  const image = Array.from(host.querySelectorAll("button")).find(
+    (button) => button.textContent === "Image",
+  );
+  if (!image) throw new Error("Image control must exist");
+  act(() => image.click());
+  // The Image asset select is the one whose options include the fixture asset.
+  const assetSelect = Array.from(host.querySelectorAll("select")).find((node) =>
+    Array.from(node.options).some((option) => option.value === "assets/new.png"),
+  );
+  if (!assetSelect) throw new Error("Project asset control must exist");
+  function choose(value: string) {
+    const control = assetSelect;
+    if (!control) throw new Error("Asset control must exist");
+    act(() => {
+      control.value = value;
+      control.dispatchEvent(new Event("change", { bubbles: true }));
+    });
+  }
+  return { host, selected, root, choose, assetSelect, onSetStyle, onSetHtmlAttribute };
+}
+
+describe.each([
+  ["classic", StyleSections],
+  ["flat", FlatStyleSection],
+] as const)("%s Image fill", (_name, Panel) => {
+  it("shows the img source as the current project asset", () => {
+    const view = mount(Panel);
+    expect(view.assetSelect.value).toBe("assets/old.png");
+    act(() => view.root.unmount());
+  });
+  it.each([
+    "assets/100%.png",
+    'data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="100%"></svg>',
+  ])("shows an authored source containing a literal percent: %s", (src) => {
+    const view = mount(Panel, "img", "index.html", src);
+    const input = Array.from(view.host.querySelectorAll("label"))
+      .find((node) => node.querySelector("span")?.textContent === "External URL")
+      ?.querySelector("input");
+    expect(input?.value).toBe(src);
+    act(() => view.root.unmount());
+  });
+  it("replaces the img source rather than writing a hidden background", () => {
+    const view = mount(Panel);
+    view.choose("assets/new.png");
+    expect(view.selected.getAttribute("src")).toBe("assets/new.png");
+    expect(view.onSetHtmlAttribute).toHaveBeenCalledExactlyOnceWith("src", "assets/new.png");
+    expect(view.onSetStyle).not.toHaveBeenCalled();
+    act(() => view.root.unmount());
+  });
+  it("replaces an img with an external URL without CSS wrapping", () => {
+    const view = mount(Panel);
+    const row = Array.from(view.host.querySelectorAll("label")).find(
+      (node) =>
+        node.querySelector("span")?.textContent === "External URL" && node.querySelector("input"),
+    );
+    const input = row?.querySelector("input");
+    if (!input) throw new Error("External URL input must exist");
+    act(() => {
+      Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")?.set?.call(
+        input,
+        "https://example.com/new.png",
+      );
+      input.dispatchEvent(new Event("input", { bubbles: true }));
+    });
+    act(() => input.dispatchEvent(new FocusEvent("focusout", { bubbles: true })));
+    expect(view.selected.getAttribute("src")).toBe("https://example.com/new.png");
+    expect(view.onSetStyle).not.toHaveBeenCalled();
+    act(() => view.root.unmount());
+  });
+  it("keeps the img source when cleared", () => {
+    const view = mount(Panel);
+    view.choose("");
+    expect(view.selected.getAttribute("src")).toBe("assets/old.png");
+    expect(view.onSetHtmlAttribute).not.toHaveBeenCalled();
+    expect(view.onSetStyle).not.toHaveBeenCalled();
+    act(() => view.root.unmount());
+  });
+  it("uses source-relative image paths in nested compositions", () => {
+    const view = mount(Panel, "img", "compositions/scene.html");
+    view.choose("assets/new.png");
+    expect(view.selected.getAttribute("src")).toBe("../assets/new.png");
+    act(() => view.root.unmount());
+  });
+  it("keeps background-image replacement and clearing for ordinary elements", () => {
+    const view = mount(Panel, "div");
+    view.choose("assets/new.png");
+    expect(view.selected.style.backgroundImage).toBe('url("assets/new.png")');
+    view.choose("");
+    expect(view.selected.style.backgroundImage).toBe("none");
+    expect(view.onSetHtmlAttribute).not.toHaveBeenCalled();
+    act(() => view.root.unmount());
+  });
+});

package/src/components/editor/propertyPanelStyleSections.tsx

@@ -45,6 +45,7 @@ export function StyleSections({
   styles,
   assets,
   onSetStyle,
+  onSetHtmlAttribute,
   onImportAssets,
   gsapBorderRadius,
   hideFlex = false,
@@ -54,6 +55,7 @@ export function StyleSections({
   styles: Record<string, string>;
   assets: string[];
   onSetStyle: (prop: string, value: string) => void | Promise<unknown>;
+  onSetHtmlAttribute: (attr: string, value: string | null) => void | Promise<void>;
   onImportAssets?: (files: FileList) => Promise<string[]>;
   gsapBorderRadius?: { tl: number; tr: number; br: number; bl: number } | null;
   // When true, the Flex `Section` is suppressed. The flat inspector renders
@@ -108,12 +110,12 @@ export function StyleSections({
   const backgroundImage = styles["background-image"] ?? "none";
   const hasTextControls = isTextEditableSelection(element);
 
-  const fillMode =
-    backgroundImage && backgroundImage !== "none"
-      ? backgroundImage.includes("gradient")
-        ? "Gradient"
-        : "Image"
-      : "Solid";
+  let fillMode = "Solid";
+  if (element.tagName === "img") {
+    fillMode = "Image";
+  } else if (backgroundImage && backgroundImage !== "none") {
+    fillMode = backgroundImage.includes("gradient") ? "Gradient" : "Image";
+  }
   const [preferredFillMode, setPreferredFillMode] = useState(fillMode);
   const imageUrl = extractBackgroundImageUrl(backgroundImage);
   // Remember the last authored gradient so an exploratory Solid↔Gradient
@@ -488,7 +490,8 @@ export function StyleSections({
           ) : (
             <ImageFillField
               projectId={projectId}
-              sourceFile={element.sourceFile}
+              element={element}
+              onSetHtmlAttribute={onSetHtmlAttribute}
               value={imageUrl}
               assets={assets}
               disabled={styleEditingDisabled}

package/src/components/nle/NLEPreview.test.ts

@@ -12,6 +12,12 @@ globalThis.IS_REACT_ACT_ENVIRONMENT = true;
 const playerMounts: string[] = [];
 let livePlayerProps: { onReadyToShowChange?: (ready: boolean) => void } = {};
 
+const measured = vi.hoisted(() => ({ size: null as { width: number; height: number } | null }));
+vi.mock("../../utils/previewCompositionSize", async (original) => ({
+  ...(await original<typeof import("../../utils/previewCompositionSize")>()),
+  readPreviewCompositionSize: () => measured.size,
+}));
+
 vi.mock("../../player", async () => {
   const React = await import("react");
 
@@ -81,7 +87,12 @@ function renderPreview(
   {
     box = { width: 800, height: 600 },
     fillBox,
-  }: { box?: { width: number; height: number }; fillBox?: boolean } = {},
+    compositionSizeHint,
+  }: {
+    box?: { width: number; height: number };
+    fillBox?: boolean;
+    compositionSizeHint?: { width: number; height: number };
+  } = {},
 ) {
   resizeCallbacks = [];
   const host = document.createElement("div");
@@ -103,6 +114,7 @@ function renderPreview(
           setShadowIframeNode: () => {},
           resetPreviewSlots: () => {},
           fillBox,
+          compositionSizeHint,
         }),
       );
     });
@@ -332,6 +344,22 @@ describe("NLEPreview", () => {
       view.cleanup();
     });
 
+    it("tells the preview how large it shows once a zoom settles, which the player cannot see", () => {
+      const view = renderPreview();
+      const frame = view.host.querySelector<HTMLElement>('[data-testid="mock-player"]')!;
+      const postMessage = vi.fn();
+      Object.defineProperty(frame, "contentWindow", { value: { postMessage } });
+      Object.defineProperty(frame, "offsetWidth", { value: 800 });
+      frame.getBoundingClientRect = () => ({ width: 1600 }) as DOMRect;
+
+      pinchIn(view, 10);
+      expect(postMessage).toHaveBeenLastCalledWith(
+        expect.objectContaining({ action: "set-display-scale", scale: 2 }),
+        "*",
+      );
+      view.cleanup();
+    });
+
     it("says how far it is zoomed, shows where in the frame, and Fit puts it back", () => {
       const view = renderPreview();
       expect([chip(view), navigator(view)]).toEqual([null, null]);
@@ -378,6 +406,37 @@ describe("NLEPreview", () => {
     filled.cleanup();
   });
 
+  it("takes the host's composition size as the stage's shape until the preview measures its own", () => {
+    const box = { width: 800, height: 600 };
+    const plain = renderPreview(undefined, { box });
+    expect([plain.stage.style.width, plain.stage.style.height]).toEqual(["784px", "441px"]);
+    plain.cleanup();
+
+    const hinted = renderPreview(undefined, {
+      box,
+      compositionSizeHint: { width: 1276, height: 1078 },
+    });
+    const shape = parseFloat(hinted.stage.style.width) / parseFloat(hinted.stage.style.height);
+    expect(shape).toBeCloseTo(1276 / 1078, 3);
+    expect(hinted.stage.style.height).toBe("584px");
+    hinted.cleanup();
+  });
+
+  it("lets the size the preview measures win over the host's hint", () => {
+    measured.size = { width: 1920, height: 1080 };
+    try {
+      const box = { width: 800, height: 600 };
+      const hinted = renderPreview(undefined, {
+        box,
+        compositionSizeHint: { width: 1276, height: 1078 },
+      });
+      expect([hinted.stage.style.width, hinted.stage.style.height]).toEqual(["784px", "441px"]);
+      hinted.cleanup();
+    } finally {
+      measured.size = null;
+    }
+  });
+
   it("clips a shadow reload so its own loading overlay cannot paint over the live frame", () => {
     const view = renderPreview([
       { gen: 0, role: "live" },

package/src/components/nle/NLEPreview.tsx

@@ -12,6 +12,7 @@ import {
   type RefObject,
 } from "react";
 import { Player } from "../../player";
+import { postFrameDisplayScale } from "../../player/lib/runtimeProtocol";
 import type { NLEContextValue } from "./NLEContext";
 import {
   DEFAULT_PREVIEW_ZOOM,
@@ -50,6 +51,7 @@ interface NLEPreviewProps extends Pick<
   onCompositionSizeChange?: (size: PreviewCompositionSize | null) => void;
   /** Draws the picture edge to edge in this box, without Studio's inset band. */
   fillBox?: boolean;
+  compositionSizeHint?: PreviewCompositionSize;
 }
 
 export function getPreviewPlayerKey({
@@ -127,6 +129,7 @@ export const NLEPreview = memo(function NLEPreview({
   onStageRef,
   onCompositionSizeChange,
   fillBox,
+  compositionSizeHint,
 }: NLEPreviewProps) {
   const activeKey = getPreviewPlayerKey({ projectId, directUrl });
   const viewportRef = useRef<HTMLDivElement>(null);
@@ -151,9 +154,12 @@ export const NLEPreview = memo(function NLEPreview({
   const gutterPx = usePreviewGuidesStore((s) => (s.rulerVisible ? RULER_GUTTER_PX : 0));
   const insetPx = fillBox ? 0 : PREVIEW_STAGE_INSET_PX;
   const [stageSize, setStageSize] = useState(() => resolvePreviewStageSize(0, 0, null, portrait));
+  const hintWidth = compositionSizeHint?.width;
+  const hintHeight = compositionSizeHint?.height;
 
   const zoomRef = useRef<PreviewZoomState>(DEFAULT_PREVIEW_ZOOM);
   const [settledZoom, setSettledZoom] = useState<PreviewZoomState>(DEFAULT_PREVIEW_ZOOM);
+  useEffect(() => postFrameDisplayScale(previewIframeRef.current), [settledZoom]);
   const hudRef = useRef<HTMLDivElement>(null);
   const hudTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const settleTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
@@ -183,7 +189,8 @@ export const NLEPreview = memo(function NLEPreview({
         resolvePreviewStageSize(
           rect.width,
           rect.height,
-          compositionSize,
+          compositionSize ??
+            (hintWidth && hintHeight ? { width: hintWidth, height: hintHeight } : null),
           portrait,
           gutterPx,
           insetPx,
@@ -195,7 +202,7 @@ export const NLEPreview = memo(function NLEPreview({
     const observer = new ResizeObserver(updateStageSize);
     observer.observe(viewport);
     return () => observer.disconnect();
-  }, [compositionSize, portrait, gutterPx, insetPx]);
+  }, [compositionSize, hintWidth, hintHeight, portrait, gutterPx, insetPx]);
 
   const onCompositionSizeChangeRef = useRef(onCompositionSizeChange);
   onCompositionSizeChangeRef.current = onCompositionSizeChange;

package/src/components/sidebar/CompositionsTab.thumbnails.test.tsx

@@ -247,6 +247,49 @@ describe("composition card thumbnails", () => {
     expect(URL.revokeObjectURL).not.toHaveBeenCalledWith("blob:frame-2");
   });
 
+  it("tell a hover preview how large it shows, so its videos are not copied at source size", () => {
+    vi.useFakeTimers();
+    try {
+      const host = mount();
+      const card = host.querySelector<HTMLElement>('[aria-label^="Open composition"]')!;
+      act(() => {
+        card.dispatchEvent(
+          new MouseEvent("pointerover", { bubbles: true, relatedTarget: document.body }),
+        );
+      });
+      act(() => vi.advanceTimersByTime(300));
+      const frame = host.querySelector("iframe")!;
+      const postMessage = vi.fn();
+      Object.defineProperty(frame, "contentWindow", { value: { postMessage } });
+      Object.defineProperty(frame, "offsetWidth", { value: 1920 });
+      frame.getBoundingClientRect = () => ({ width: 80 }) as DOMRect;
+      act(() => {
+        frame.dispatchEvent(new Event("load"));
+      });
+      expect(postMessage).toHaveBeenCalledWith(
+        expect.objectContaining({ action: "set-display-scale", scale: 80 / 1920 }),
+        "*",
+      );
+
+      // A module-script composition starts listening only after load, then says it is ready.
+      postMessage.mockClear();
+      act(() => {
+        window.dispatchEvent(
+          new MessageEvent("message", {
+            source: frame.contentWindow,
+            data: { source: "hf-preview", type: "ready" },
+          }),
+        );
+      });
+      expect(postMessage).toHaveBeenCalledWith(
+        expect.objectContaining({ action: "set-display-scale", scale: 80 / 1920 }),
+        "*",
+      );
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
   it("show a fallback when the render fails, and retry it at the next content revision", async () => {
     const host = mount();
     renders[0]!.answer(500);

package/src/components/sidebar/CompositionsTab.tsx

@@ -13,6 +13,7 @@ import {
   THUMBNAIL_SEEK_TIME_SECONDS,
 } from "../../player/components/CompositionThumbnail";
 import { setPreviewMediaMuted } from "../../player/lib/timelineIframeHelpers";
+import { postFrameDisplayScale } from "../../player/lib/runtimeProtocol";
 import { usePlayerStore } from "../../player/store/playerStore";
 import { thumbnailRevisionOf } from "../../player/store/thumbnailSlice";
 import { encodePreviewPath } from "../../player/components/thumbnailUtils";
@@ -258,6 +259,22 @@ function CompCard({
     if (hovered) requestIframePlaybackSync(true);
   }, [hovered, requestIframePlaybackSync]);
 
+  useEffect(() => {
+    if (livePreviewLoaded) postFrameDisplayScale(iframeRef.current);
+  }, [livePreviewLoaded, previewScale]);
+
+  useEffect(() => {
+    if (!hovered) return;
+    const onRuntimeReady = (event: MessageEvent) => {
+      const frame = iframeRef.current;
+      if (frame && event.source === frame.contentWindow && event.data?.type === "ready") {
+        postFrameDisplayScale(frame);
+      }
+    };
+    window.addEventListener("message", onRuntimeReady);
+    return () => window.removeEventListener("message", onRuntimeReady);
+  }, [hovered]);
+
   useEffect(() => {
     return () => {
       if (hoverTimer.current) clearTimeout(hoverTimer.current);

package/src/hooks/externalFileChangeOwnership.test.ts

@@ -21,9 +21,30 @@ describe("external file-change subscription ownership", () => {
       new URL("./useExternalFileChangeCoordinator.ts", import.meta.url),
       "utf8",
     );
-    // vitest defines `import.meta.hot`, so the selection is the one claim left to
-    // the source; the channel's own behaviour is exercised below.
-    expect(coordinator.match(/sseFileChangeChannel\(handler\)/g)).toHaveLength(1);
+    expect(coordinator.match(/sseFileChangeChannel\(handler, catchUp\)/g)).toHaveLength(1);
+  });
+
+  it("asks to catch up on every reconnect, since changes made while disconnected are never resent", () => {
+    const listeners = new Map<string, (event: unknown) => void>();
+    class FakeEventSource {
+      addEventListener(type: string, listener: (event: unknown) => void) {
+        listeners.set(type, listener);
+      }
+      close = vi.fn();
+    }
+    vi.stubGlobal("EventSource", FakeEventSource);
+    try {
+      const onReconnect = vi.fn();
+      sseFileChangeChannel(vi.fn(), onReconnect);
+      listeners.get("open")?.(new Event("open"));
+      expect(onReconnect).not.toHaveBeenCalled();
+      listeners.get("error")?.(new Event("error"));
+      listeners.get("open")?.(new Event("open"));
+      listeners.get("open")?.(new Event("open"));
+      expect(onReconnect).toHaveBeenCalledTimes(2);
+    } finally {
+      vi.unstubAllGlobals();
+    }
   });
 
   it("delivers the raw file-change event from EventSource to the handler and closes on cleanup", () => {
@@ -42,7 +63,7 @@ describe("external file-change subscription ownership", () => {
     vi.stubGlobal("EventSource", FakeEventSource);
     try {
       const onDelivery = vi.fn();
-      const stop = sseFileChangeChannel(onDelivery);
+      const stop = sseFileChangeChannel(onDelivery, vi.fn());
       const event = new MessageEvent("file-change", { data: JSON.stringify({ path: "a.html" }) });
       listeners.get("file-change")?.(event);
       expect(opened).toEqual(["/api/events"]);

package/src/hooks/gsapValueAtPlayhead.browser.test.ts

@@ -1,18 +1,14 @@
 // @vitest-environment happy-dom
 // Real Chrome with the built runtime: its seek, not a plain GSAP seek, decides what a saved edit shows.
-import { readFileSync } from "node:fs";
-import { createRequire } from "node:module";
 import { gsap } from "gsap";
 import { parseGsapScriptAcorn } from "@hyperframes/parsers/gsap-parser-acorn";
 import { replaceTweenWithKeyframesInScript } from "@hyperframes/parsers/gsap-writer-acorn";
-import puppeteer from "puppeteer-core";
 import { expect, it, vi } from "vitest";
-import { findSystemChrome } from "../../vite.browser";
+import { launchTestChrome, showWithRuntime } from "../../tests/chromeTestUtils";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { usePlayerStore } from "../player/store/playerStore";
 import { planValueEdit } from "./gsapValueAtPlayhead";
 
-const require = createRequire(import.meta.url);
 vi.setConfig({ testTimeout: 60_000 });
 
 const SRC = `var tl = gsap.timeline({ paused: true });
@@ -49,25 +45,10 @@ const page = (script: string) => `<!doctype html><html><body>
 
 it("a drag on a fromTo's start shows the dropped x there once the runtime seeks", async () => {
   const written = writeDrag(90, 2);
-  const executablePath = findSystemChrome();
-  if (!executablePath) throw new Error("no Chrome found: set HYPERFRAMES_BROWSER_PATH");
-  const browser = await puppeteer.launch({
-    executablePath,
-    headless: true,
-    args: ["--no-sandbox"],
-  });
+  const browser = await launchTestChrome();
   try {
     const tab = await browser.newPage();
-    await tab.setRequestInterception(true);
-    // Only the GSAP script is served; anything else is refused, never fetched.
-    tab.on("request", (request) =>
-      request.url().endsWith("/gsap.min.js")
-        ? request.respond({ body: readFileSync(require.resolve("gsap/dist/gsap.min.js"), "utf8") })
-        : request.abort("blockedbyclient"),
-    );
-    await tab.setContent(page(written), { waitUntil: "load" });
-    await tab.evaluate(readFileSync(require.resolve("@hyperframes/core/runtime"), "utf8"));
-    await tab.waitForFunction(() => "__player" in window);
+    await showWithRuntime(tab, page(written));
     const shown = await tab.evaluate(() => {
       const w = window as unknown as {
         __player: { seek(t: number): void };