@hyperframes/studio 0.8.129 → 0.8.131

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.129",
+  "version": "0.8.131",
   "description": "",
   "repository": {
     "type": "git",
@@ -60,12 +60,12 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.129",
-    "@hyperframes/parsers": "0.8.129",
-    "@hyperframes/player": "0.8.129",
-    "@hyperframes/shader-transitions": "0.8.129",
-    "@hyperframes/studio-server": "0.8.129",
-    "@hyperframes/sdk": "0.8.129"
+    "@hyperframes/core": "0.8.131",
+    "@hyperframes/parsers": "0.8.131",
+    "@hyperframes/player": "0.8.131",
+    "@hyperframes/shader-transitions": "0.8.131",
+    "@hyperframes/sdk": "0.8.131",
+    "@hyperframes/studio-server": "0.8.131"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -81,7 +81,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.129"
+    "@hyperframes/producer": "0.8.131"
   },
   "peerDependencies": {
     "react": "19",

package/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: [],

package/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

package/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);

package/src/hooks/usePersistentEditHistory.test.ts

@@ -62,7 +62,7 @@ async function studio({ withHistory = true } = {}) {
   const file = () => readFileSync(join(dir, "index.html"), "utf8");
   const save = (content: string) => writeFileSync(join(dir, "index.html"), content);
   const readFile = async (path: string) => readFileSync(join(dir, path), "utf8");
-  return { dir, hook: () => hook, file, save, readFile };
+  return { dir, history, hook: () => hook, file, save, readFile };
 }
 
 it("an edit Studio saved is undone and redone by the project's history, with the preview's before and after", async () => {
@@ -411,6 +411,30 @@ it("a key one page holds does not join another page's edit under the same key",
   expect(file()).toBe("B");
 });
 
+it("a host's write claimed under claimKey joins Studio's save under the same key: one undo takes back both", async () => {
+  const { dir, history, hook, file, save, readFile } = await studio();
+  const key = "drop:1";
+  writeFileSync(join(dir, "clip.mp4"), "media");
+  await history.claim({ kind: "person", name: "You" }, "Dropped on timeline", ["clip.mp4"], {
+    coalesceKey: hook().claimKey(key),
+    idleMs: Infinity,
+  });
+  save("B");
+  await act(() =>
+    hook().recordEdit({
+      label: "Dropped on timeline",
+      coalesceKey: key,
+      coalesceMs: Infinity,
+      files: { "index.html": { before: "A", after: "B" } },
+    }),
+  );
+
+  await act(() => hook().undo({ readFile }));
+
+  expect(file()).toBe("A");
+  expect(existsSync(join(dir, "clip.mp4"))).toBe(false);
+});
+
 it("an undo before the history view shows a drag's held claim still waits on the files it wrote", async () => {
   const { hook, save, readFile } = await studio();
   const server = globalThis.fetch;

package/src/hooks/usePersistentEditHistory.ts

@@ -209,6 +209,7 @@ export function usePersistentEditHistory({ projectId }: UsePersistentEditHistory
   projectIdRef.current = projectId;
   const [own] = useState(createOwnHistory);
   const [pageKeyScope] = useState(generateId);
+  const claimKey = useCallback((key: string) => `${pageKeyScope}:${key}`, [pageKeyScope]);
 
   const refresh = useCallback(async () => {
     if (!projectId) return;
@@ -246,7 +247,7 @@ export function usePersistentEditHistory({ projectId }: UsePersistentEditHistory
         paths,
         overwrote: await overwroteVersions(files),
         ...(coalesceKey && {
-          coalesceKey: `${pageKeyScope}:${coalesceKey}`,
+          coalesceKey: claimKey(coalesceKey),
           idleMs: coalesceMs ?? DEFAULT_COALESCE_MS,
         }),
       });
@@ -258,7 +259,7 @@ export function usePersistentEditHistory({ projectId }: UsePersistentEditHistory
       heldClaimRef.current = claimed && coalesceKey ? { paths, at: Date.now() } : null;
       await refresh();
     },
-    [projectId, refresh, own, pageKeyScope],
+    [projectId, refresh, own, claimKey],
   );
 
   const step = useCallback(
@@ -341,6 +342,7 @@ export function usePersistentEditHistory({ projectId }: UsePersistentEditHistory
     redoPaths: view.forward?.paths ?? [],
     state,
     recordEdit,
+    claimKey,
     undo,
     redo,
     predict: own.predict,

package/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";

package/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());
+});