@hyperframes/studio 0.8.101 → 0.8.102

package/src/domEditExports.test.tsx

@@ -9,13 +9,17 @@ import {
   PreviewReadOnlyProvider,
   useDomEditSelectionContext,
   useDomEditSession,
+  useDomEditZOrder,
   usePreviewPersistence,
   type ConnectedDomEditOverlayProps,
   type DomEditCapabilities,
   type DomEditSelection,
+  type DomEditZOrder,
   type UseDomEditSessionParams,
   type UsePreviewPersistenceParams,
+  type ZOrderAction,
 } from "@hyperframes/studio";
+import { makeSelection } from "./hooks/domSelectionTestHarness";
 
 Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
 
@@ -66,4 +70,92 @@ describe("DOM editing package exports", () => {
     expect(canvas?.className).toContain("pointer-events-none");
     await act(async () => root.unmount());
   });
+
+  it("gives a host the canvas menu's z-order: enabled, then one step through the session's commit", async () => {
+    const parent = document.createElement("div");
+    const back = document.createElement("div");
+    back.id = "back";
+    const front = document.createElement("div");
+    front.id = "front";
+    parent.append(back, front);
+    document.body.append(parent);
+    const commitZ = vi.fn(() => Promise.resolve());
+    const session = {
+      handleDomZIndexReorderCommit: commitZ,
+    } as unknown as Parameters<typeof DomEditProvider>[0]["value"];
+    let zOrder: DomEditZOrder | undefined;
+    function Probe() {
+      zOrder = useDomEditZOrder();
+      return null;
+    }
+    const el = document.createElement("div");
+    document.body.append(el);
+    const root = createRoot(el);
+    await act(async () =>
+      root.render(
+        <DomEditProvider value={session}>
+          <Probe />
+        </DomEditProvider>,
+      ),
+    );
+    const sel = makeSelection("Back", back);
+    const toFront: ZOrderAction = "bring-to-front";
+    expect(zOrder?.enabled(sel, "send-to-back")).toBe(false);
+    expect(zOrder?.enabled(sel, toFront)).toBe(true);
+    expect(zOrder?.apply(sel, "send-to-back")).toBe(false);
+    expect(commitZ).not.toHaveBeenCalled();
+    await act(async () => {
+      expect(zOrder?.apply(sel, toFront)).toBe(true);
+    });
+    expect(commitZ).toHaveBeenCalledTimes(1);
+    expect(commitZ).toHaveBeenCalledWith(
+      expect.arrayContaining([expect.objectContaining({ element: back, id: "back" })]),
+      expect.stringContaining(toFront),
+      toFront,
+    );
+    await act(async () => root.unmount());
+    parent.remove();
+  });
+
+  it("gives a read-only preview or a detached element no z-order, and never asks the session", async () => {
+    const parent = document.createElement("div");
+    const back = document.createElement("div");
+    back.id = "back";
+    parent.append(back, document.createElement("div"));
+    document.body.append(parent);
+    const commitZ = vi.fn(() => Promise.resolve());
+    const session = {
+      handleDomZIndexReorderCommit: commitZ,
+    } as unknown as Parameters<typeof DomEditProvider>[0]["value"];
+    let zOrder: DomEditZOrder | undefined;
+    function Probe() {
+      zOrder = useDomEditZOrder();
+      return null;
+    }
+    const el = document.body.appendChild(document.createElement("div"));
+    const root = createRoot(el);
+    const mount = (readOnly: boolean) =>
+      act(async () =>
+        root.render(
+          <PreviewReadOnlyProvider readOnly={readOnly}>
+            <DomEditProvider value={session}>
+              <Probe />
+            </DomEditProvider>
+          </PreviewReadOnlyProvider>,
+        ),
+      );
+    const sel = makeSelection("Back", back);
+    await mount(true);
+    expect(zOrder?.enabled(sel, "bring-to-front")).toBe(false);
+    expect(zOrder?.apply(sel, "bring-to-front")).toBe(false);
+    expect(zOrder?.commit(sel, [{ element: back, zIndex: 1 }], "bring-to-front", null)).toBe(false);
+    await mount(false);
+    // A reload leaves the old nodes connected to their old document, one no window shows.
+    document.implementation.createHTMLDocument().body.append(parent);
+    expect(back.isConnected).toBe(true);
+    expect(zOrder?.enabled(sel, "bring-to-front"), "a selection from before a reload").toBe(false);
+    expect(zOrder?.apply(sel, "bring-to-front")).toBe(false);
+    expect(commitZ).not.toHaveBeenCalled();
+    await act(async () => root.unmount());
+  });
 });

package/src/hooks/gsapRuntimeKeyframes.ts

@@ -419,6 +419,12 @@ export const POSITION_CHANNELS: string[] = [
 ];
 const MOVE_CHANNELS = [...POSITION_CHANNELS, "motionPath"];
 
+export const GSAP_TRANSFORM_KEYS = new Set(
+  "x,y,z,scale,scaleX,scaleY,xPercent,yPercent,rotation,rotationX,rotationY,skewX,skewY,transformOrigin,svgOrigin,force3D,smoothOrigin,transformPerspective,translateX,translateY,translateZ,rotate,rotationZ,rotateZ,rotateX,rotateY".split(
+    ",",
+  ),
+);
+
 /** Whether a live timeline tween or hold writes any of `channels` on `el`. Sync, no fetch. */
 function gsapWritesChannels(el: Element, channels: string[]): boolean {
   const win = el.ownerDocument.defaultView as { __timelines?: Record<string, RuntimeTimeline> };

package/src/hooks/useDomEditCommits.test.tsx

@@ -42,6 +42,7 @@ interface RenderDomEditCommitsOptions {
   onTrySdkPersist?: () => Promise<CutoverResult>;
   queueDomEditSave?: <T>(save: () => Promise<T>) => Promise<T>;
   projectIdRef?: MutableRefObject<string | null>;
+  readOnlyPreview?: boolean;
 }
 
 type FetchHandler = (
@@ -232,7 +233,7 @@ function renderDomEditCommits(
         target === selection.element ? selection : null,
       ),
       onTrySdkPersist: options.onTrySdkPersist,
-      readOnlyPreview: false,
+      readOnlyPreview: options.readOnlyPreview ?? false,
     });
     return null;
   }
@@ -266,97 +267,100 @@ describe("useDomEditCommits z-index reorder persistence", () => {
     document.body.replaceChildren();
   });
 
-  it("persists an N-element reorder with one batch POST, one undo entry, and NO iframe reload", async () => {
-    const original =
-      '<div id="a" style="z-index: 1"></div><div id="b" style="z-index: 2"></div><div id="c" style="z-index: 3"></div>';
-    const after =
-      '<div id="a" style="z-index: 3"></div><div id="b" style="z-index: 2"></div><div id="c" style="z-index: 1"></div>';
-    const fetchMock = vi.fn(
-      async (
-        input: Parameters<typeof fetch>[0],
-        _init?: Parameters<typeof fetch>[1],
-      ): Promise<Response> => {
-        const url = requestUrl(input);
-        if (url.endsWith("/file-mutations/patch-element-batches")) {
-          return jsonResponse({
-            durable: true,
-            files: [
-              {
-                sourceFile: "index.html",
-                changed: true,
-                matched: [true, true, true],
-                before: original,
-                after,
-              },
-            ],
-          });
-        }
-        throw new Error(`Unexpected fetch: ${url}`);
-      },
-    );
-    vi.stubGlobal("fetch", fetchMock);
-    const { iframe, element } = createPreviewElement(
-      '<div data-hf-id="hf-card"></div><div id="b"></div><div id="c"></div>',
-    );
-    element.id = "a";
-    const elements = [
-      element,
-      iframe.contentDocument!.getElementById("b")!,
-      iframe.contentDocument!.getElementById("c")!,
-    ];
-    const rendered = renderDomEditCommits(createSelection(element), iframe);
-
-    try {
-      await act(async () => {
-        await rendered.hook.handleDomZIndexReorderCommit(
-          elements.map((item, index) => ({
-            element: item,
-            zIndex: 3 - index,
-            id: item.id,
-            sourceFile: "index.html",
-          })),
-          "z-reorder:test",
-        );
-      });
-
-      const batchPosts = fetchMock.mock.calls.filter(([input]) =>
-        requestUrl(input).endsWith("/file-mutations/patch-element-batches"),
+  it.each([false, true])(
+    "persists an N-element reorder with one batch POST, one undo entry, and NO iframe reload (read-only preview %s: the timeline's z sync stays editable)",
+    async (readOnlyPreview) => {
+      const original =
+        '<div id="a" style="z-index: 1"></div><div id="b" style="z-index: 2"></div><div id="c" style="z-index: 3"></div>';
+      const after =
+        '<div id="a" style="z-index: 3"></div><div id="b" style="z-index: 2"></div><div id="c" style="z-index: 1"></div>';
+      const fetchMock = vi.fn(
+        async (
+          input: Parameters<typeof fetch>[0],
+          _init?: Parameters<typeof fetch>[1],
+        ): Promise<Response> => {
+          const url = requestUrl(input);
+          if (url.endsWith("/file-mutations/patch-element-batches")) {
+            return jsonResponse({
+              durable: true,
+              files: [
+                {
+                  sourceFile: "index.html",
+                  changed: true,
+                  matched: [true, true, true],
+                  before: original,
+                  after,
+                },
+              ],
+            });
+          }
+          throw new Error(`Unexpected fetch: ${url}`);
+        },
       );
-      const singlePosts = fetchMock.mock.calls.filter(([input]) =>
-        requestUrl(input).includes("/file-mutations/patch-elements-batch/"),
+      vi.stubGlobal("fetch", fetchMock);
+      const { iframe, element } = createPreviewElement(
+        '<div data-hf-id="hf-card"></div><div id="b"></div><div id="c"></div>',
       );
-      expect(batchPosts).toHaveLength(1);
-      expect(singlePosts).toHaveLength(0);
-      expect(JSON.parse(String(batchPosts[0]?.[1]?.body))).toEqual({
-        batches: [
-          {
-            sourceFile: "index.html",
-            patches: expect.arrayContaining([
-              expect.objectContaining({ target: expect.objectContaining({ id: "a" }) }),
-              expect.objectContaining({ target: expect.objectContaining({ id: "b" }) }),
-              expect.objectContaining({ target: expect.objectContaining({ id: "c" }) }),
-            ]),
-          },
-        ],
-      });
-      expect(rendered.recordEdit).toHaveBeenCalledTimes(1);
-      expect(rendered.recordEdit).toHaveBeenCalledWith({
-        label: "Reorder layers",
-        coalesceKey: "z-reorder:test",
-        // Unbounded per-gesture fold window (keys are unique per gesture):
-        // the z entry and its mirror/lane counterpart fold across the server
-        // round-trip that separates them.
-        coalesceMs: Number.POSITIVE_INFINITY,
-        files: { "index.html": { before: original, after } },
-      });
-      // FIX: a z-only reorder must NOT remount the preview iframe ("the blink").
-      // The live DOM + store already hold the final state and the server matched
-      // every style-only patch, so the reload is provably redundant.
-      expect(rendered.reloadPreview).not.toHaveBeenCalled();
-    } finally {
-      rendered.cleanup();
-    }
-  });
+      element.id = "a";
+      const elements = [
+        element,
+        iframe.contentDocument!.getElementById("b")!,
+        iframe.contentDocument!.getElementById("c")!,
+      ];
+      const rendered = renderDomEditCommits(createSelection(element), iframe, { readOnlyPreview });
+
+      try {
+        await act(async () => {
+          await rendered.hook.handleDomZIndexReorderCommit(
+            elements.map((item, index) => ({
+              element: item,
+              zIndex: 3 - index,
+              id: item.id,
+              sourceFile: "index.html",
+            })),
+            "z-reorder:test",
+          );
+        });
+
+        const batchPosts = fetchMock.mock.calls.filter(([input]) =>
+          requestUrl(input).endsWith("/file-mutations/patch-element-batches"),
+        );
+        const singlePosts = fetchMock.mock.calls.filter(([input]) =>
+          requestUrl(input).includes("/file-mutations/patch-elements-batch/"),
+        );
+        expect(batchPosts).toHaveLength(1);
+        expect(singlePosts).toHaveLength(0);
+        expect(JSON.parse(String(batchPosts[0]?.[1]?.body))).toEqual({
+          batches: [
+            {
+              sourceFile: "index.html",
+              patches: expect.arrayContaining([
+                expect.objectContaining({ target: expect.objectContaining({ id: "a" }) }),
+                expect.objectContaining({ target: expect.objectContaining({ id: "b" }) }),
+                expect.objectContaining({ target: expect.objectContaining({ id: "c" }) }),
+              ]),
+            },
+          ],
+        });
+        expect(rendered.recordEdit).toHaveBeenCalledTimes(1);
+        expect(rendered.recordEdit).toHaveBeenCalledWith({
+          label: "Reorder layers",
+          coalesceKey: "z-reorder:test",
+          // Unbounded per-gesture fold window (keys are unique per gesture):
+          // the z entry and its mirror/lane counterpart fold across the server
+          // round-trip that separates them.
+          coalesceMs: Number.POSITIVE_INFINITY,
+          files: { "index.html": { before: original, after } },
+        });
+        // FIX: a z-only reorder must NOT remount the preview iframe ("the blink").
+        // The live DOM + store already hold the final state and the server matched
+        // every style-only patch, so the reload is provably redundant.
+        expect(rendered.reloadPreview).not.toHaveBeenCalled();
+      } finally {
+        rendered.cleanup();
+      }
+    },
+  );
 
   it("falls back to reloading when the server response omits matched[]", async () => {
     // Without a matched[] confirmation the persist can't be proven in sync with

package/src/index.ts

@@ -187,6 +187,9 @@ export { DomEditProvider, useDomEditSelectionContext } from "./contexts/DomEditC
 export { PreviewReadOnlyProvider } from "./components/editor/previewReadOnlyContext";
 export { ConnectedDomEditOverlay } from "./components/editor/ConnectedDomEditOverlay";
 export type { ConnectedDomEditOverlayProps } from "./components/editor/ConnectedDomEditOverlay";
+export { useDomEditZOrder } from "./components/editor/useDomEditZOrder";
+export type { DomEditZOrder } from "./components/editor/useDomEditZOrder";
+export type { ZOrderAction } from "./components/editor/canvasContextMenuZOrder";
 export type { DomEditCapabilities, DomEditSelection } from "./components/editor/domEditingTypes";
 export { useDomStyleCommit } from "./hooks/useDomStyleCommit";
 export type { UseDomStyleCommitOptions } from "./hooks/useDomStyleCommit";