Skip to content

Write HTML. Render video. Built for agents.

feat(studio): a host app can mount the Layers panel outside Studio (#5049)

Miguel Ángel618fd7684b3c
diff --git a/packages/studio/src/components/editor/LayersPanel.test.ts b/packages/studio/src/components/editor/LayersPanel.test.ts
index 3b12b6c66e..033eb98aa4 100644
--- a/packages/studio/src/components/editor/LayersPanel.test.ts
+++ b/packages/studio/src/components/editor/LayersPanel.test.ts
@@ -21,12 +21,12 @@ const mocks = vi.hoisted(() => ({
}));
vi.mock("../../contexts/StudioContext", () => ({
- useStudioShellContext: () => ({
+ useStudioShellContextOptional: () => ({
previewIframeRef: mocks.previewIframeRef,
activeCompPath: "index.html",
showToast: mocks.showToast,
}),
- useStudioPlaybackContext: () => ({
+ useStudioPlaybackContextOptional: () => ({
refreshKey: 0,
compositionLoading: true,
timelineElements: [],
diff --git a/packages/studio/src/components/editor/LayersPanel.tsx b/packages/studio/src/components/editor/LayersPanel.tsx
index 7a006d6afe..fc98b41c9c 100644
--- a/packages/studio/src/components/editor/LayersPanel.tsx
+++ b/packages/studio/src/components/editor/LayersPanel.tsx
@@ -8,7 +8,12 @@ import {
resolveDomEditSelection,
type DomEditLayerItem,
} from "./domEditing";
-import { useStudioPlaybackContext, useStudioShellContext } from "../../contexts/StudioContext";
+import {
+ useStudioPlaybackContextOptional,
+ useStudioShellContextOptional,
+ type StudioPlaybackValue,
+ type StudioShellValue,
+} from "../../contexts/StudioContext";
import { useDomEditContext } from "../../contexts/DomEditContext";
import { usePlayerStore, liveTime } from "../../player";
import {
@@ -94,11 +99,36 @@ interface CollapsedState {
[key: string]: boolean;
}
+/** Studio state the panel reads; passed by hosts outside Studio's providers. Keep previewIframeRef stable,
+ * and bump refreshKey when the preview document is rebuilt without an iframe load. */
+export type LayersPanelHost = Pick<
+ StudioShellValue,
+ "previewIframeRef" | "activeCompPath" | "showToast"
+> &
+ Pick<StudioPlaybackValue, "timelineElements" | "isPlaying"> &
+ Partial<Pick<StudioPlaybackValue, "refreshKey" | "compositionLoading">>;
+
+function useLayersPanelHost(host: LayersPanelHost | undefined): LayersPanelHost {
+ const shell = useStudioShellContextOptional();
+ const playback = useStudioPlaybackContextOptional();
+ if (host) return host;
+ if (!shell || !playback) {
+ throw new Error("LayersPanel needs a host prop outside Studio's shell and playback providers");
+ }
+ return { ...shell, ...playback };
+}
+
// fallow-ignore-next-line complexity
-export const LayersPanel = memo(function LayersPanel() {
- const { previewIframeRef, activeCompPath, showToast } = useStudioShellContext();
- const { refreshKey, compositionLoading, timelineElements, isPlaying } =
- useStudioPlaybackContext();
+export const LayersPanel = memo(function LayersPanel({ host }: { host?: LayersPanelHost }) {
+ const {
+ previewIframeRef,
+ activeCompPath,
+ showToast,
+ refreshKey,
+ compositionLoading,
+ timelineElements,
+ isPlaying,
+ } = useLayersPanelHost(host);
const currentTime = usePlayerStore((s) => s.currentTime);
// Flashless z commits (canvas menu, timeline lane-drag z-sync) mutate iframe
// z-indexes with no reload and no refreshKey bump — while paused, nothing
diff --git a/packages/studio/src/components/nle/useCanvasZOrderTimelineMirror.ts b/packages/studio/src/components/nle/useCanvasZOrderTimelineMirror.ts
index 9f1528a452..75098eaade 100644
--- a/packages/studio/src/components/nle/useCanvasZOrderTimelineMirror.ts
+++ b/packages/studio/src/components/nle/useCanvasZOrderTimelineMirror.ts
@@ -145,8 +145,8 @@ function useMirrorLaneMoveCommit(): (
(selectionKey, coalesceKey, resolveMove) => {
const els = elementsRef.current;
const element = selectionKey ? els.find((e) => (e.key ?? e.id) === selectionKey) : undefined;
- // Not a timeline clip (canvas-only decoration) → z-only action, unchanged.
- if (!element) return Promise.resolve(false);
+ // Canvas-only decoration, or no handler to save a lane move (no TimelineEditProvider): z-only.
+ if (!element || !onMoveElements) return Promise.resolve(false);
const move = resolveMove(element, els);
if (!move) return Promise.resolve(false);
diff --git a/packages/studio/src/index.ts b/packages/studio/src/index.ts
index 8fcc854080..1c1696b710 100644
--- a/packages/studio/src/index.ts
+++ b/packages/studio/src/index.ts
@@ -206,6 +206,8 @@ export type { UsePreviewPersistenceParams } from "./hooks/usePreviewPersistence"
export { DomEditProvider, useDomEditSelectionContext } from "./contexts/DomEditContext";
export { PreviewReadOnlyProvider } from "./components/editor/previewReadOnlyContext";
export { ConnectedDomEditOverlay } from "./components/editor/ConnectedDomEditOverlay";
+export { LayersPanel } from "./components/editor/LayersPanel";
+export type { LayersPanelHost } from "./components/editor/LayersPanel";
export type { ConnectedDomEditOverlayProps } from "./components/editor/ConnectedDomEditOverlay";
export { useDomEditZOrder } from "./components/editor/useDomEditZOrder";
export type { DomEditZOrder } from "./components/editor/useDomEditZOrder";
diff --git a/packages/studio/src/layersPanelExport.test.tsx b/packages/studio/src/layersPanelExport.test.tsx
new file mode 100644
index 0000000000..7e8378ea7f
--- /dev/null
+++ b/packages/studio/src/layersPanelExport.test.tsx
@@ -0,0 +1,115 @@
+// @vitest-environment happy-dom
+// Mounts the Layers panel by package name with no Studio shell, as a host app does.
+import { act, type ReactNode } from "react";
+import { afterEach, expect, it, vi } from "vitest";
+import {
+ DomEditProvider,
+ LayersPanel,
+ TimelineEditProvider,
+ usePlayerStore,
+ type LayersPanelHost,
+} from "@hyperframes/studio";
+import { installReactActEnvironment, mountReactHarness } from "./hooks/domSelectionTestHarness";
+import { deriveTimelineStoreKeyForDomId } from "./player/lib/timelineElementHelpers";
+
+installReactActEnvironment();
+
+const flush = () => act(async () => {});
+const rowLabels = () =>
+ [...document.querySelectorAll("[data-layer-index]")].map((row) => row.textContent);
+const clip = (id: string, track: number) => {
+ const key = deriveTimelineStoreKeyForDomId(id, "index.html");
+ return { id: key, key, domId: id, tag: "div", start: 0, duration: 4, track };
+};
+const bgTrack = () => usePlayerStore.getState().elements.find((e) => e.domId === "bg")?.track;
+
+afterEach(() => {
+ usePlayerStore.setState({ elements: [] });
+ document.body.innerHTML = "";
+});
+
+/** The host's preview (title in front of bg, rows to match) and its edit session, mounted around the panel. */
+async function mountPanel(wrap: (panel: ReactNode) => ReactNode = (panel) => panel) {
+ const iframe = document.createElement("iframe");
+ document.body.appendChild(iframe);
+ const doc = iframe.contentDocument!;
+ doc.body.innerHTML =
+ '<div data-composition-id="main"><div id="bg" style="z-index:1"></div><div id="title" style="z-index:2"></div></div>';
+ usePlayerStore.setState({ elements: [clip("title", 0), clip("bg", 1)] });
+ const session = {
+ domEditSelection: null,
+ activeGroupElement: null,
+ applyDomSelection: vi.fn(),
+ updateDomEditHoverSelection: vi.fn(),
+ handleDomZIndexReorderCommit: vi.fn(async () => ({
+ durable: true,
+ allMatched: true,
+ changed: true,
+ })),
+ setActiveGroupElement: vi.fn(),
+ } as unknown as Parameters<typeof DomEditProvider>[0]["value"];
+ const host: LayersPanelHost = {
+ previewIframeRef: { current: iframe },
+ activeCompPath: null,
+ showToast: vi.fn(),
+ timelineElements: usePlayerStore.getState().elements,
+ isPlaying: false,
+ };
+ const root = mountReactHarness(
+ <DomEditProvider value={session}>{wrap(<LayersPanel host={host} />)}</DomEditProvider>,
+ );
+ await flush();
+ return { doc, session, root };
+}
+
+/** Drags the back row (bg) above the front one. */
+async function dragBackRowToFront() {
+ const rows = document.querySelectorAll<HTMLElement>("[data-layer-index]");
+ rows.forEach((row, i) =>
+ vi.spyOn(row, "getBoundingClientRect").mockReturnValue(new DOMRect(0, i * 24, 200, 24)),
+ );
+ const pointer = (type: string, clientY: number) =>
+ new PointerEvent(type, { bubbles: true, button: 0, pointerId: 1, clientX: 10, clientY });
+ const list = rows[0]!.parentElement!;
+ list.setPointerCapture = () => {};
+ act(() => void rows[1]!.dispatchEvent(pointer("pointerdown", 36)));
+ act(() => {
+ list.dispatchEvent(pointer("pointermove", 20));
+ list.dispatchEvent(pointer("pointermove", 2));
+ });
+ await act(async () => void list.dispatchEvent(pointer("pointerup", 2)));
+ await flush();
+}
+
+it("lists, selects and reorders the host's preview layers through the host's session", async () => {
+ const { doc, session, root } = await mountPanel();
+
+ expect(rowLabels()).toEqual(["DiTitle", "DiBg"]);
+
+ const rows = document.querySelectorAll<HTMLElement>("[data-layer-index]");
+ await act(async () => rows[0]!.click());
+ expect(session.applyDomSelection).toHaveBeenCalledWith(
+ expect.objectContaining({ element: doc.getElementById("title") }),
+ );
+
+ await dragBackRowToFront();
+ expect(session.handleDomZIndexReorderCommit).toHaveBeenCalledTimes(1);
+ const [entries] = vi.mocked(session.handleDomZIndexReorderCommit).mock.calls[0]!;
+ const z = Object.fromEntries(entries.map((e) => [e.element.id, e.zIndex]));
+ expect(z.bg).toBeGreaterThan(Number(doc.getElementById("title")!.style.zIndex));
+ // No TimelineEditProvider, so nothing can save a lane move: the row stays where the file says.
+ expect(bgTrack()).toBe(1);
+ await act(async () => root.unmount());
+});
+
+it("mirrors the reorder into the timeline rows through the host's move handler", async () => {
+ const onMoveElements = vi.fn(async () => {});
+ const { root } = await mountPanel((panel) => (
+ <TimelineEditProvider value={{ onMoveElements }}>{panel}</TimelineEditProvider>
+ ));
+
+ await dragBackRowToFront();
+ expect(onMoveElements).toHaveBeenCalledTimes(1);
+ expect(bgTrack()).not.toBe(1);
+ await act(async () => root.unmount());
+});