feat(studio): hosts can seal the preview frames NLEPreview draws (#7817)

* feat(studio): hosts can seal the preview frames NLEPreview draws

* refactor(studio): Player builds its frame src in a helper, keeping its complexity at main's
This commit is contained in:
Miguel Ángel
2026-11-15 17:15:24 +00:00
committed by GitHub
parent 5341d7255c
commit a73ecff2be
8 changed files with 125 additions and 12 deletions
@@ -86,4 +86,11 @@ export const STUDIO_API_SAME_ORIGIN_CREDENTIALS = resolveStudioBooleanEnvFlag(
false,
);
// Off until every Studio reader of the preview frame has its editing-port path.
export const STUDIO_OPAQUE_PREVIEW_ENABLED = resolveStudioBooleanEnvFlag(
env,
["VITE_STUDIO_OPAQUE_PREVIEW_ENABLED"],
false,
);
import { resolveEnabledSdkFamilies } from "../../utils/sdkCutoverPolicy";
@@ -29,6 +29,7 @@ vi.mock("../../player", async () => {
onReadyToShowChange?: (ready: boolean) => void;
suppressLoadingOverlay?: boolean;
style?: React.CSSProperties;
sandboxOrigin?: "opaque";
},
ref: React.ForwardedRef<HTMLIFrameElement>,
) {
@@ -41,6 +42,7 @@ vi.mock("../../player", async () => {
return React.createElement("div", {
ref: ref as React.ForwardedRef<HTMLDivElement>,
"data-testid": "mock-player",
"data-sandbox-origin": props.sandboxOrigin,
style: props.style,
});
}),
@@ -89,10 +91,12 @@ function renderPreview(
box = { width: 800, height: 600 },
fillBox,
compositionSizeHint,
sandboxOrigin,
}: {
box?: { width: number; height: number };
fillBox?: boolean;
compositionSizeHint?: { width: number; height: number };
sandboxOrigin?: "opaque";
} = {},
) {
resizeCallbacks = [];
@@ -116,6 +120,7 @@ function renderPreview(
resetPreviewSlots: () => {},
fillBox,
compositionSizeHint,
sandboxOrigin,
}),
);
});
@@ -533,6 +538,26 @@ describe("NLEPreview", () => {
view.cleanup();
});
it.each([["opaque" as const], [undefined]])(
"gives every player it draws the host's sandbox origin (%s)",
(sandboxOrigin) => {
const view = renderPreview(
[
{ gen: 0, role: "live" },
{ gen: 1, role: "shadow", url: "/api/projects/p/preview?_t=1" },
],
{ sandboxOrigin },
);
view.render("/api/projects/p/preview/components/card.html", "p");
const players = [...view.stage.querySelectorAll('[data-testid="mock-player"]')];
expect(players).toHaveLength(3);
for (const player of players) {
expect(player.getAttribute("data-sandbox-origin")).toBe(sandboxOrigin ?? null);
}
view.cleanup();
},
);
it("covers the live preview with the cached frame-0 poster until it is ready to show", () => {
const view = renderPreview();
const poster = () =>
@@ -58,6 +58,7 @@ interface NLEPreviewProps extends Pick<
/** Draws the picture edge to edge in this box, without Studio's inset band. */
fillBox?: boolean;
compositionSizeHint?: PreviewCompositionSize;
sandboxOrigin?: "opaque";
}
export function getPreviewPlayerKey({
@@ -92,6 +93,7 @@ export const NLEPreview = memo(function NLEPreview({
onCompositionSizeChange,
fillBox,
compositionSizeHint,
sandboxOrigin,
}: NLEPreviewProps) {
const activeKey = getPreviewPlayerKey({ projectId, directUrl });
const viewportRef = useRef<HTMLDivElement>(null);
@@ -487,6 +489,7 @@ export const NLEPreview = memo(function NLEPreview({
onLoad={() => {}}
portrait={portrait}
suppressLoadingOverlay
sandboxOrigin={sandboxOrigin}
style={{ position: "absolute", inset: 0, zIndex: 0 }}
/>
)}
@@ -509,6 +512,7 @@ export const NLEPreview = memo(function NLEPreview({
portrait={portrait}
suppressLoadingOverlay={suppressLoadingOverlay}
loadingUi={loadingUi}
sandboxOrigin={sandboxOrigin}
style={
directUrl?.includes("/components/")
? { position: "absolute", inset: 0, zIndex: 1 }
@@ -528,6 +532,7 @@ export const NLEPreview = memo(function NLEPreview({
portrait={portrait}
suppressLoadingOverlay
noLoadTimeout
sandboxOrigin={sandboxOrigin}
style={SHADOW_IFRAME_STYLE}
/>
),
@@ -8,6 +8,7 @@ import { useNLEContext } from "./NLEContext";
import { AssetPreviewOverlay } from "./AssetPreviewOverlay";
import { PreviewGuides } from "../editor/PreviewGuides";
import { PreviewOverlayProvider } from "../editor/PreviewOverlayProvider";
import { STUDIO_OPAQUE_PREVIEW_ENABLED } from "../editor/manualEditingAvailability";
function subscribeFullscreen(cb: () => void) {
document.addEventListener("fullscreenchange", cb);
@@ -150,6 +151,7 @@ export function PreviewPane({
suppressLoadingOverlay={hasLoadedOnceRef.current}
onStageRef={handleStageRef}
onCompositionSizeChange={setPreviewCompositionSize}
sandboxOrigin={STUDIO_OPAQUE_PREVIEW_ENABLED ? "opaque" : undefined}
/>
{previewDragOver && (
<div className="absolute inset-2 z-40 rounded-lg border-2 border-dashed border-studio-accent/50 bg-studio-accent/4 pointer-events-none" />
@@ -1,5 +1,5 @@
import { buildProjectApiPath } from "../../utils/projectRouting";
import { studioApiFetch } from "../../utils/studioApiFetch";
import { fetchFrameToken } from "../../player/lib/frameToken";
import { memo, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
import { useThumbnailLease } from "../../hooks/useThumbnailLease";
import {
@@ -72,13 +72,9 @@ function useFreshFrameToken(projectId: string, wanted: boolean): string | null |
useEffect(() => {
if (!wanted) return setKnown(undefined);
let live = true;
void studioApiFetch(buildProjectApiPath(projectId, "/frame-token"))
.then((res) => (res.ok ? res.json() : null))
.then((body: { token?: unknown } | null) =>
typeof body?.token === "string" ? body.token : null,
)
.catch(() => null)
.then((token) => live && setKnown({ token }));
void fetchFrameToken(buildProjectApiPath(projectId, "/frame-token")).then(
(token) => live && setKnown({ token }),
);
return () => {
live = false;
};
@@ -198,6 +198,55 @@ describe("preview errors", () => {
});
});
describe("a host's sandbox origin", () => {
const token = "T".repeat(43);
const stubFrameToken = (body: { token?: string } | null) =>
vi.spyOn(globalThis, "fetch").mockImplementation(async (input) => {
expect(String(input)).toBe("/api/projects/demo/frame-token");
return { ok: body !== null, json: async () => body } as Response;
});
const settle = () =>
act(async () => {
for (let i = 0; i < 10; i += 1) await Promise.resolve();
});
afterEach(() => vi.restoreAllMocks());
it.each([
["/api/projects/demo/preview", `/api/projects/demo/preview/~${token}`],
[
"/api/projects/demo/preview/comp/scene.html",
`/api/projects/demo/preview/~${token}/comp/scene.html`,
],
["/api/projects/demo/preview?_t=1", `/api/projects/demo/preview/~${token}?_t=1`],
])(
"seals an opaque preview of %s and loads it under its project's frame token",
async (directUrl, sealed) => {
stubFrameToken({ token });
const { player } = await mountPlayer({ directUrl, sandboxOrigin: "opaque" });
await settle();
expect(player.hasAttribute("sandbox-origin")).toBe(true);
expect(player.getAttribute("src")).toBe(sealed);
},
);
it("still seals the preview when the project has no frame token to give", async () => {
stubFrameToken(null);
const { player } = await mountPlayer({ sandboxOrigin: "opaque" });
await settle();
expect(player.hasAttribute("sandbox-origin")).toBe(true);
expect(player.getAttribute("src")).toBe("/api/projects/demo/preview");
});
it("leaves a same-origin preview on its plain path without asking for a token", async () => {
const fetch = vi.spyOn(globalThis, "fetch");
const { player } = await mountPlayer();
await settle();
expect(player.hasAttribute("sandbox-origin")).toBe(false);
expect(player.getAttribute("src")).toBe("/api/projects/demo/preview");
expect(fetch).not.toHaveBeenCalled();
});
});
describe("callbacks after the player is already mounted", () => {
it("runs the latest onLoad on a later load, not the one captured at mount", async () => {
const first = vi.fn();
@@ -9,6 +9,7 @@ import { usePlayerStore } from "../store/playerStore";
import { announcePreviewDocumentLoaded } from "../sceneSwap";
import type { IframeWindow } from "../lib/playbackTypes";
import { watchPreviewFrame } from "../lib/bridgePlayback";
import { previewUnderFrameToken } from "../lib/frameToken";
// Importing "@hyperframes/player" registers a class extending HTMLElement at
// module load, which throws under SSR, hence the dynamic import behind a
// `typeof window` guard. Kicking it here rather than in the mount effect puts
@@ -43,6 +44,7 @@ interface PlayerProps {
suppressLoadingOverlay?: boolean;
loadingUi?: "studio" | "host";
noLoadTimeout?: boolean;
sandboxOrigin?: "opaque";
}
interface HyperframesPlayerElement extends HTMLElement {
@@ -139,6 +141,13 @@ export function hasUnloadedAssets(iframe: HTMLIFrameElement, lastResult: boolean
}
}
async function playerSrc(previewSource: string, opaque: boolean): Promise<string> {
const url = new URL(previewSource, window.location.origin);
applyPreviewVariablesToUrl(url);
const src = url.pathname + url.search;
return opaque ? previewUnderFrameToken(src) : src;
}
const runtimeBootedIn = (iframe: HTMLIFrameElement) =>
(iframe.contentWindow as IframeWindow | null)?.__playerReady === true;
@@ -219,14 +228,13 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
let canceled = false;
let cleanup: (() => void) | undefined;
void loadPlayerModule().then(() => {
const opaque = host.sandboxOrigin === "opaque";
void Promise.all([loadPlayerModule(), playerSrc(previewSource, opaque)]).then(([, src]) => {
if (canceled) return;
// Create the web component imperatively to avoid JSX custom-element typing.
const player = document.createElement("hyperframes-player") as HyperframesPlayerElement;
const srcUrl = new URL(previewSource, window.location.origin);
applyPreviewVariablesToUrl(srcUrl);
const src = srcUrl.pathname + srcUrl.search;
const retryPreview = () => {
retryCountRef.current += 1;
const retryUrl = new URL(src, window.location.origin);
@@ -344,6 +352,7 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
player.setAttribute("shader-loading", "player");
player.setAttribute("low-power-idle", "");
player.toggleAttribute("no-load-timeout", noLoadTimeout === true);
player.toggleAttribute("sandbox-origin", opaque);
player.setAttribute("width", String(portrait ? 1080 : 1920));
player.setAttribute("height", String(portrait ? 1920 : 1080));
player.style.width = "100%";
@@ -0,0 +1,20 @@
import { studioApiFetch } from "../../utils/studioApiFetch";
const PREVIEW_PATH = /^(\/api\/projects\/[^/?#]+)\/preview(?=[/?#]|$)/;
export function fetchFrameToken(frameTokenPath: string): Promise<string | null> {
return studioApiFetch(frameTokenPath)
.then((res) => (res.ok ? res.json() : null))
.then((body: { token?: unknown } | null) =>
typeof body?.token === "string" ? body.token : null,
)
.catch(() => null);
}
/** The preview path under its project's frame token, where an opaque frame's own loads are let through. */
export async function previewUnderFrameToken(src: string): Promise<string> {
const project = PREVIEW_PATH.exec(src)?.[1];
if (!project) return src;
const token = await fetchFrameToken(`${project}/frame-token`);
return token ? src.replace(PREVIEW_PATH, `$1/preview/~${token}`) : src;
}