@hyperframes/studio 0.8.100 → 0.8.102

package/src/components/editor/ConnectedDomEditOverlay.tsx

@@ -4,12 +4,7 @@ import {
   useDomEditActionsContext,
   useDomEditSelectionContext,
 } from "../../contexts/DomEditContext";
-import { readHfId, type DomEditSelection } from "./domEditing";
-import { buildStableSelector } from "./domEditingDom";
-import { deriveTimelineStoreKey } from "../../player/lib/timelineElementHelpers";
-import { zReorderCoalesceKey } from "../../hooks/useElementLifecycleOps";
-import { useCanvasZOrderTimelineMirror } from "../nle/useCanvasZOrderTimelineMirror";
-import { runZLaneGesture } from "../nle/zLaneGesture";
+import { useDomEditZOrder } from "./useDomEditZOrder";
 
 type HostInputProps = Pick<
   ComponentProps<typeof DomEditOverlay>,
@@ -25,94 +20,6 @@ export interface ConnectedDomEditOverlayProps extends HostInputProps {
   onTextEditingChange?: (editing: boolean) => void;
 }
 
-type ZIndexReorderEntry = {
-  element: HTMLElement;
-  zIndex: number;
-  id?: string;
-  selector?: string;
-  selectorIndex?: number;
-  sourceFile: string;
-  /** Timeline store key — lets the commit update the store zIndex synchronously. */
-  key?: string;
-};
-
-/** Can this element be robustly re-targeted for a persisted z change? */
-function canTargetZIndexElement(
-  element: HTMLElement,
-  id: string | undefined,
-  selector: string | undefined,
-): boolean {
-  return Boolean(id || selector || readHfId(element));
-}
-
-/** The selected element carries its full selection identity. */
-function selectedZIndexEntry(sel: DomEditSelection, zIndex: number): ZIndexReorderEntry {
-  return {
-    element: sel.element,
-    zIndex,
-    id: sel.id ?? undefined,
-    selector: sel.selector,
-    selectorIndex: sel.selectorIndex,
-    sourceFile: sel.sourceFile,
-    key: deriveTimelineStoreKey({
-      domId: sel.id ?? undefined,
-      selector: sel.selector,
-      selectorIndex: sel.selectorIndex,
-      sourceFile: sel.sourceFile,
-    }),
-  };
-}
-
-/** A raw iframe sibling in the selection's file; null with no id or selector (z stays live). */
-function siblingZIndexEntry(
-  element: HTMLElement,
-  zIndex: number,
-  sourceFile: string,
-): ZIndexReorderEntry | null {
-  const id = element.id || undefined;
-  const selector = buildStableSelector(element);
-  if (!canTargetZIndexElement(element, id, selector)) return null;
-  return {
-    element,
-    zIndex,
-    id,
-    selector,
-    selectorIndex: undefined,
-    sourceFile,
-    key: deriveTimelineStoreKey({ domId: id, selector, sourceFile }),
-  };
-}
-
-/** Short human-readable label for a dropped sibling, for the console warning below. */
-function describeZIndexElement(element: HTMLElement): string {
-  if (element.id) return `#${element.id}`;
-  const firstClass = element.classList.item(0);
-  return firstClass
-    ? `${element.tagName.toLowerCase()}.${firstClass}`
-    : element.tagName.toLowerCase();
-}
-
-// Resolve z-index patches into commit entries; a sibling with no stable
-// id/selector can't be written to source, so it is returned as `dropped` for
-// the revert-on-reload warning. Exported so tests can drive the menu → commit path.
-export function resolveZIndexEntries(
-  sel: DomEditSelection,
-  patches: ReadonlyArray<{ element: HTMLElement; zIndex: number }>,
-): { entries: ZIndexReorderEntry[]; dropped: Array<{ element: HTMLElement; zIndex: number }> } {
-  const entries: ZIndexReorderEntry[] = [];
-  const dropped: Array<{ element: HTMLElement; zIndex: number }> = [];
-  for (const patch of patches) {
-    if (patch.element === sel.element) {
-      entries.push(selectedZIndexEntry(sel, patch.zIndex));
-      continue;
-    }
-    const entry = siblingZIndexEntry(patch.element, patch.zIndex, sel.sourceFile);
-    if (entry) entries.push(entry);
-    else dropped.push(patch);
-  }
-  return { entries, dropped };
-}
-
 // Studio's DomEditOverlay wired to the session in DomEditProvider, so a host
 // outside EditorShell mounts the same canvas editing without its own callbacks.
 export function ConnectedDomEditOverlay({
@@ -142,9 +49,8 @@ export function ConnectedDomEditOverlay({
     handleDomStyleCommit,
     applyMarqueeSelection,
     handleDomEditElementDelete,
-    handleDomZIndexReorderCommit,
   } = useDomEditActionsContext();
-  const mirrorZOrderToTimeline = useCanvasZOrderTimelineMirror();
+  const zOrder = useDomEditZOrder();
 
   return (
     <DomEditOverlay
@@ -170,38 +76,7 @@ export function ConnectedDomEditOverlay({
       onRotationCommit={handleDomRotationCommit}
       onStyleCommit={handleDomStyleCommit}
       onDeleteSelection={handleDomEditElementDelete}
-      onApplyZIndex={(sel, patches, action, crossed) => {
-        const { entries, dropped } = resolveZIndexEntries(sel, patches);
-        if (dropped.length > 0) {
-          // These siblings can't be written to source. Apply their live z
-          // anyway so the resolved stacking order renders coherently — it
-          // just reverts to the prior order on the next reload.
-          for (const patch of dropped) patch.element.style.zIndex = String(patch.zIndex);
-          console.warn(
-            "[studio] z-index reorder: dropping sibling(s) with no stable id/selector " +
-              "(will revert on reload):",
-            dropped.map((patch) => describeZIndexElement(patch.element)).join(", "),
-          );
-        }
-        if (entries.length === 0) return;
-        // One coalesce key for the z persist AND the lane mirror folds both into one undo entry;
-        // passed explicitly so the mirror shares it by construction, not by formula duplication.
-        const coalesceKey = zReorderCoalesceKey(entries, action);
-        // One serialized z→lane transaction: the mirror runs only AFTER a durable z commit and
-        // no second gesture interleaves (see runZLaneGesture). A failed z commit has already
-        // toasted and rolled back, so the catch only keeps its rejection from going unhandled.
-        runZLaneGesture({
-          commitZ: () => handleDomZIndexReorderCommit(entries, coalesceKey, action),
-          mirror: () =>
-            mirrorZOrderToTimeline({
-              selectionKey: entries.find((e) => e.element === sel.element)?.key,
-              action,
-              crossed,
-              sourceFile: sel.sourceFile,
-              coalesceKey,
-            }),
-        }).catch(() => undefined);
-      }}
+      onApplyZIndex={zOrder.commit}
       onMarqueeSelect={applyMarqueeSelection}
     />
   );

package/src/components/editor/canvasContextMenuZOrder.ts

@@ -511,3 +511,16 @@ export function isZOrderActionEnabled(
 ): boolean {
   return resolveZOrderChange(target, action, options) !== null;
 }
+
+/**
+ * One z-order step: the patches plus the sibling it crosses, both read from the
+ * same pre-change render order. Null when the action is a no-op.
+ */
+export function resolveZOrderStep(
+  target: HTMLElement,
+  action: ZOrderAction,
+): { patches: ZOrderPatch[]; crossed: HTMLElement | null } | null {
+  const patches = resolveZOrderChange(target, action);
+  if (patches === null) return null;
+  return { patches, crossed: resolveCrossedNeighbor(target, action) };
+}

package/src/components/editor/gsapAnimatesProperty.ts

@@ -1,32 +1,3 @@
-// GSAP's CSSPlugin takes ownership of the element's entire transform stack
-// when it tweens ANY of these — it bakes the CSS `translate` longhand into
-// style.transform at init and writes `translate: none` every tick. Position
-// reapply/strip logic must therefore stand down for all of them, not just x/y.
-const GSAP_TRANSFORM_PROPS = [
-  "x",
-  "y",
-  "xPercent",
-  "yPercent",
-  "scale",
-  "scaleX",
-  "scaleY",
-  "rotation",
-  "rotate",
-  "rotationX",
-  "rotationY",
-  "skewX",
-  "skewY",
-  "transform",
-];
-
-/**
- * True when GSAP animates any transform-affecting property on the element,
- * meaning GSAP owns `style.transform` and has neutralized CSS `translate`.
- */
-export function gsapAnimatesTransform(el: HTMLElement): boolean {
-  return gsapAnimatesProperty(el, ...GSAP_TRANSFORM_PROPS);
-}
-
 /**
  * Checks whether GSAP actively animates one or more CSS/GSAP properties on
  * the given element by inspecting all registered `__timelines`.

package/src/components/editor/gsapLivePreview.test.ts

@@ -1,10 +1,15 @@
 // @vitest-environment happy-dom
-import { expect, it, vi } from "vitest";
+import { afterEach, expect, it, vi } from "vitest";
 import { createGsapLivePreview } from "./gsapLivePreview";
 import type { DomEditSelection } from "./domEditingTypes";
 import type { GsapAnimation } from "@hyperframes/parsers/gsap-parser";
 import { readGsapRuntimeValuesForPanel } from "./propertyPanelHelpers";
 
+afterEach(() => {
+  delete (window as { gsap?: unknown }).gsap;
+  delete (window as { __timelines?: unknown }).__timelines;
+});
+
 it("previews on the selected element, not an earlier same-id copy in a sub-composition", () => {
   document.body.innerHTML =
     '<div data-composition-id="strip"><div id="card" data-hf-id="hf-inner"></div></div>' +
@@ -61,3 +66,43 @@ it("the panel reads GSAP values off the node the live preview moves", () => {
   });
   expect(getProperty.mock.calls[0]?.[0]).toBe(root);
 });
+
+it.each([
+  ["fades it", { opacity: 0 }, ["opacity"]],
+  ["fades it about its corner", { opacity: 0, transformOrigin: "0 0" }, ["opacity"]],
+  [
+    "moves it",
+    { x: 100 },
+    [
+      "x",
+      "y",
+      "rotation",
+      "rotationX",
+      "rotationY",
+      "rotationZ",
+      "z",
+      "scale",
+      "transformPerspective",
+      "opacity",
+    ],
+  ],
+])(
+  "the panel reads GSAP's transform only off an element GSAP positions: a tween that %s",
+  (_, vars, read) => {
+    document.body.innerHTML = '<div id="card"></div>';
+    const card = document.querySelector<HTMLElement>("#card");
+    const tween = { targets: () => [card], vars, duration: () => 1 };
+    const getProperty = vi.fn(() => 1);
+    const contentWindow = Object.assign(window, {
+      gsap: { getProperty },
+      __timelines: { main: { getChildren: () => [tween] } },
+    });
+    const selection = { id: "card", sourceFile: "index.html", element: card } as DomEditSelection;
+    const animations = [{ properties: vars }] as unknown as GsapAnimation[];
+    readGsapRuntimeValuesForPanel("anim", animations, selection, {
+      current: { contentWindow, contentDocument: document } as unknown as HTMLIFrameElement,
+    });
+    const props = getProperty.mock.calls.map((call) => (call as unknown[])[1]);
+    expect(props).toEqual(read);
+  },
+);

package/src/components/editor/propertyPanelHelpers.ts

@@ -9,6 +9,7 @@ import {
   playbackStartAttributeForElement,
   readPlaybackStartAttributes,
 } from "../../player/lib/timelineElementHelpers";
+import { GSAP_TRANSFORM_KEYS, gsapWritesPosition } from "../../hooks/gsapRuntimeKeyframes";
 
 export type {
   BackgroundRemovalProgress,
@@ -496,8 +497,10 @@ export function readGsapRuntimeValuesForPanel(
     const el = findPreviewNode(iframe.contentDocument, element);
     if (!el) return null;
     const propKeys = collectPanelPropKeys(gsapAnimations);
+    const readsTransform = gsapWritesPosition(el);
     const result: Record<string, number> = {};
     for (const prop of propKeys) {
+      if (!readsTransform && GSAP_TRANSFORM_KEYS.has(prop)) continue;
       const v = Number(gsap.getProperty(el, prop));
       if (Number.isFinite(v)) result[prop] = roundToCenti(v);
     }

package/src/components/editor/useDomEditZOrder.ts

@@ -0,0 +1,185 @@
+import { useCallback, useMemo } from "react";
+import { useDomEditActionsContext } from "../../contexts/DomEditContext";
+import { readHfId, type DomEditSelection } from "./domEditing";
+import { buildStableSelector, getSelectorIndex } from "./domEditingDom";
+import { usePreviewReadOnly } from "./previewReadOnlyContext";
+import { useStudioShellContextOptional } from "../../contexts/StudioContext";
+import { deriveTimelineStoreKey } from "../../player/lib/timelineElementHelpers";
+import { zReorderCoalesceKey } from "../../hooks/useElementLifecycleOps";
+import { useCanvasZOrderTimelineMirror } from "../nle/useCanvasZOrderTimelineMirror";
+import { runZLaneGesture } from "../nle/zLaneGesture";
+import {
+  isZOrderActionEnabled,
+  resolveZOrderStep,
+  type ZOrderAction,
+  type ZOrderPatch,
+} from "./canvasContextMenuZOrder";
+
+type ZIndexReorderEntry = {
+  element: HTMLElement;
+  zIndex: number;
+  id?: string;
+  selector?: string;
+  selectorIndex?: number;
+  sourceFile: string;
+  /** Timeline store key — lets the commit update the store zIndex synchronously. */
+  key?: string;
+};
+
+/** Can this element be robustly re-targeted for a persisted z change? */
+function canTargetZIndexElement(
+  element: HTMLElement,
+  id: string | undefined,
+  selector: string | undefined,
+): boolean {
+  return Boolean(id || selector || readHfId(element));
+}
+
+/** The selected element carries its full selection identity. */
+function selectedZIndexEntry(sel: DomEditSelection, zIndex: number): ZIndexReorderEntry {
+  return {
+    element: sel.element,
+    zIndex,
+    id: sel.id ?? undefined,
+    selector: sel.selector,
+    selectorIndex: sel.selectorIndex,
+    sourceFile: sel.sourceFile,
+    key: deriveTimelineStoreKey({
+      domId: sel.id ?? undefined,
+      selector: sel.selector,
+      selectorIndex: sel.selectorIndex,
+      sourceFile: sel.sourceFile,
+    }),
+  };
+}
+
+/** A raw iframe sibling in the selection's file; null with no id or selector (z stays live). Its selector index
+ * picks it among same-class siblings, the way the lane mirror keys `crossed`. */
+function siblingZIndexEntry(
+  element: HTMLElement,
+  zIndex: number,
+  sourceFile: string,
+  activeCompPath: string | null,
+): ZIndexReorderEntry | null {
+  const id = element.id || undefined;
+  const selector = buildStableSelector(element);
+  if (!canTargetZIndexElement(element, id, selector)) return null;
+  const selectorIndex = id
+    ? undefined
+    : getSelectorIndex(element.ownerDocument, element, selector, sourceFile, activeCompPath);
+  return {
+    element,
+    zIndex,
+    id,
+    selector,
+    selectorIndex,
+    sourceFile,
+    key: deriveTimelineStoreKey({ domId: id, selector, selectorIndex, sourceFile }),
+  };
+}
+
+/** Short human-readable label for a dropped sibling, for the console warning below. */
+function describeZIndexElement(element: HTMLElement): string {
+  if (element.id) return `#${element.id}`;
+  const firstClass = element.classList.item(0);
+  return firstClass
+    ? `${element.tagName.toLowerCase()}.${firstClass}`
+    : element.tagName.toLowerCase();
+}
+
+// Patches as commit entries; a sibling with no id or selector is `dropped` and reverts on reload.
+export function resolveZIndexEntries(
+  sel: DomEditSelection,
+  patches: ReadonlyArray<{ element: HTMLElement; zIndex: number }>,
+  activeCompPath: string | null,
+): { entries: ZIndexReorderEntry[]; dropped: Array<{ element: HTMLElement; zIndex: number }> } {
+  const entries: ZIndexReorderEntry[] = [];
+  const dropped: Array<{ element: HTMLElement; zIndex: number }> = [];
+  for (const patch of patches) {
+    if (patch.element === sel.element) {
+      entries.push(selectedZIndexEntry(sel, patch.zIndex));
+      continue;
+    }
+    const entry = siblingZIndexEntry(patch.element, patch.zIndex, sel.sourceFile, activeCompPath);
+    if (entry) entries.push(entry);
+    else dropped.push(patch);
+  }
+  return { entries, dropped };
+}
+
+export interface DomEditZOrder {
+  /** False in a read-only preview, for an element no longer in the live preview, or at that end of its stacking set. */
+  enabled: (sel: DomEditSelection, action: ZOrderAction) => boolean;
+  /** Resolve and commit one step; false when nothing is sent to be saved. */
+  apply: (sel: DomEditSelection, action: ZOrderAction) => boolean;
+  /** Commit patches already resolved (the canvas menu resolves its own); false when none could be sent to be saved. */
+  commit: (
+    sel: DomEditSelection,
+    patches: ReadonlyArray<ZOrderPatch>,
+    action: ZOrderAction,
+    crossed: HTMLElement | null,
+  ) => boolean;
+}
+
+/** A selection from before a preview reload holds an element of a document no window shows, with stale z values. */
+const isLive = (element: HTMLElement) =>
+  element.isConnected && element.ownerDocument.defaultView !== null;
+
+// The canvas menu's z-order (write, undo, lane mirror) for any caller in DomEditProvider.
+export function useDomEditZOrder(): DomEditZOrder {
+  const { handleDomZIndexReorderCommit } = useDomEditActionsContext();
+  const mirrorZOrderToTimeline = useCanvasZOrderTimelineMirror();
+  const readOnly = usePreviewReadOnly();
+  const activeCompPath = useStudioShellContextOptional()?.activeCompPath ?? null;
+
+  const enabled = useCallback<DomEditZOrder["enabled"]>(
+    (sel, action) => !readOnly && isLive(sel.element) && isZOrderActionEnabled(sel.element, action),
+    [readOnly],
+  );
+
+  const commit = useCallback<DomEditZOrder["commit"]>(
+    (sel, patches, action, crossed) => {
+      if (readOnly) return false;
+      const { entries, dropped } = resolveZIndexEntries(sel, patches, activeCompPath);
+      if (dropped.length > 0) {
+        // Not writable to source: their live z still applies, so the order renders, until a reload.
+        for (const patch of dropped) patch.element.style.zIndex = String(patch.zIndex);
+        console.warn(
+          "[studio] z-index reorder: dropping sibling(s) with no stable id/selector " +
+            "(will revert on reload):",
+          dropped.map((patch) => describeZIndexElement(patch.element)).join(", "),
+        );
+      }
+      if (entries.length === 0) return false;
+      // One coalesce key for the z write and the lane mirror: one undo entry.
+      const coalesceKey = zReorderCoalesceKey(entries, action);
+      // One serialized z→lane transaction: the mirror runs only AFTER a durable z commit and
+      // no second gesture interleaves (see runZLaneGesture). A failed z commit has already
+      // toasted and rolled back, so the catch only keeps its rejection from going unhandled.
+      runZLaneGesture({
+        commitZ: () => handleDomZIndexReorderCommit(entries, coalesceKey, action),
+        mirror: () =>
+          mirrorZOrderToTimeline({
+            selectionKey: entries.find((e) => e.element === sel.element)?.key,
+            action,
+            crossed,
+            sourceFile: sel.sourceFile,
+            coalesceKey,
+          }),
+      }).catch(() => undefined);
+      return true;
+    },
+    [activeCompPath, handleDomZIndexReorderCommit, mirrorZOrderToTimeline, readOnly],
+  );
+
+  const apply = useCallback<DomEditZOrder["apply"]>(
+    (sel, action) => {
+      if (!isLive(sel.element)) return false;
+      const step = resolveZOrderStep(sel.element, action);
+      return step !== null && commit(sel, step.patches, action, step.crossed);
+    },
+    [commit],
+  );
+
+  return useMemo(() => ({ enabled, apply, commit }), [enabled, apply, commit]);
+}

package/src/components/nle/PreviewOverlaysTestMocks.ts

@@ -8,6 +8,10 @@ export const iframeRef = { current: null as HTMLIFrameElement | null };
 
 vi.mock("../../contexts/StudioContext", () => ({
   useStudioShellContext: () => ({ activeCompPath: "index.html", previewIframeRef: iframeRef }),
+  useStudioShellContextOptional: () => ({
+    activeCompPath: "index.html",
+    previewIframeRef: iframeRef,
+  }),
   useStudioPlaybackContext: () => ({
     captionEditMode: previewState.captionEditMode,
     compositionLoading: false,

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/appHotkeysDispatch.ts

@@ -14,13 +14,7 @@ import { STUDIO_PLAIN_KEYS } from "../player/components/studioShortcuts";
 // following useTimelineDeleteOps's precedent. Pure functions, no hooks — the
 // hook still owns the actual keydown listeners and calls into these.
 
-/** Exported so useAppHotkeys's own history-only preview listener can reuse
- *  the same undo/redo key arbitration without duplicating it. */
-export function handleUndoRedoKey(
-  event: KeyboardEvent,
-  onUndo: () => void,
-  onRedo: () => void,
-): boolean {
+function handleUndoRedoKey(event: KeyboardEvent, onUndo: () => void, onRedo: () => void): boolean {
   const key = event.key.toLowerCase();
   if (key === "z" && !event.shiftKey) {
     event.preventDefault();

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> };