Skip to content

Write HTML. Render video. Built for agents.

feat(studio): let a host app keep paint order in step with timeline rows (#4647)

Miguel Ángel93ab2899f13a
diff --git a/packages/studio/src/index.ts b/packages/studio/src/index.ts
index 2e7e1639e7..cae9bd0ef3 100644
--- a/packages/studio/src/index.ts
+++ b/packages/studio/src/index.ts
@@ -154,7 +154,10 @@ export { parseStyleString, mergeStyleIntoTag, findElementBlock } from "./utils/h
export { usePersistentEditHistory } from "./hooks/usePersistentEditHistory";
export type { UsePersistentEditHistoryOptions } from "./hooks/usePersistentEditHistory";
export { useTimelineEditing } from "./hooks/useTimelineEditing";
-export type { UseTimelineEditingOptions } from "./hooks/useTimelineEditingTypes";
+export type {
+ TimelineZIndexReorderCommit,
+ UseTimelineEditingOptions,
+} from "./hooks/useTimelineEditingTypes";
// A host's own waitForPendingDomEditSaves must also call this, or undo/redo
// can race a write still in flight (see useTrackPendingTimelineEdit.ts).
export { flushStudioPendingEdits } from "./utils/studioPendingEdits";
diff --git a/packages/studio/src/player/components/TimelineTypes.ts b/packages/studio/src/player/components/TimelineTypes.ts
index 7a65cdaab0..21f7691699 100644
--- a/packages/studio/src/player/components/TimelineTypes.ts
+++ b/packages/studio/src/player/components/TimelineTypes.ts
@@ -4,13 +4,15 @@ import type { TimelineTimeRange } from "../store/rangeSelectionSlice";
import type { TimelineDropCallbacks } from "./timelineCallbacks";
import type { TimelineTheme } from "./timelineTheme";
import type { TimelineEditOverrides } from "./useResolvedTimelineEditCallbacks";
+import type { TimelineStackingSyncProps } from "./useTimelineStackingSync";
export interface TimelineClipRenderContext {
priority: "overscan" | "visible" | "interaction";
rich: boolean;
}
-export interface TimelineProps extends TimelineDropCallbacks, TimelineEditOverrides {
+export interface TimelineProps
+ extends TimelineDropCallbacks, TimelineEditOverrides, TimelineStackingSyncProps {
/** Project-scoped reset boundary; soft source refreshes retain the same epoch. */
sessionEpoch?: number;
onSeek?: (time: number, options?: { keepPlaying?: boolean }) => void;
diff --git a/packages/studio/src/player/components/useTimelineProviderState.tsx b/packages/studio/src/player/components/useTimelineProviderState.tsx
index eb28433a9c..98408d255b 100644
--- a/packages/studio/src/player/components/useTimelineProviderState.tsx
+++ b/packages/studio/src/player/components/useTimelineProviderState.tsx
@@ -71,6 +71,8 @@ export function useTimelineProviderState({
canPasteClip,
theme: themeOverrides,
sessionEpoch = 0,
+ previewIframeRef,
+ onZIndexReorder,
}: TimelineProps = {}): TimelineContextValue {
const {
onMoveElement,
@@ -184,6 +186,8 @@ export function useTimelineProviderState({
});
const { readClipZIndex, applyStackingPatches, zSyncEnabled } = useTimelineStackingSync({
expandedElementsRef: timelineElementsRef,
+ previewIframeRef,
+ onZIndexReorder,
});
const {
draggedClip,
diff --git a/packages/studio/src/player/components/useTimelineStackingSync.test.tsx b/packages/studio/src/player/components/useTimelineStackingSync.test.tsx
index 11eb0f32a3..b343589b44 100644
--- a/packages/studio/src/player/components/useTimelineStackingSync.test.tsx
+++ b/packages/studio/src/player/components/useTimelineStackingSync.test.tsx
@@ -73,4 +73,50 @@ describe("useTimelineStackingSync", () => {
mocks.actions = null;
iframe.remove();
});
+
+ it("uses a host's iframe and commit over Studio's own", async () => {
+ const studioCommit = vi.fn().mockResolvedValue(undefined);
+ mocks.actions = {
+ previewIframeRef: { current: null },
+ handleDomZIndexReorderCommit: studioCommit,
+ };
+ const iframe = document.createElement("iframe");
+ document.body.appendChild(iframe);
+ const node = iframe.contentDocument!.createElement("div");
+ node.id = "a";
+ iframe.contentDocument!.body.appendChild(node);
+ const hostCommit = vi.fn().mockResolvedValue(undefined);
+ const element: TimelineElement = {
+ id: "a",
+ key: "a",
+ tag: "div",
+ start: 0,
+ duration: 2,
+ track: 0,
+ };
+ let sync: ReturnType<typeof useTimelineStackingSync> | null = null;
+ function Harness() {
+ sync = useTimelineStackingSync({
+ expandedElementsRef: { current: [element] },
+ previewIframeRef: { current: iframe },
+ onZIndexReorder: hostCommit,
+ });
+ return null;
+ }
+ const root = mountReactHarness(<Harness />);
+
+ await act(async () => {
+ await sync!.applyStackingPatches([{ key: "a", zIndex: 3 }]);
+ });
+
+ expect(sync!.zSyncEnabled).toBe(true);
+ expect(hostCommit).toHaveBeenCalledWith(
+ [expect.objectContaining({ element: node, zIndex: 3 })],
+ undefined,
+ );
+ expect(studioCommit).not.toHaveBeenCalled();
+ act(() => root.unmount());
+ mocks.actions = null;
+ iframe.remove();
+ });
});
diff --git a/packages/studio/src/player/components/useTimelineStackingSync.ts b/packages/studio/src/player/components/useTimelineStackingSync.ts
index f68aa68a83..32b82bd8da 100644
--- a/packages/studio/src/player/components/useTimelineStackingSync.ts
+++ b/packages/studio/src/player/components/useTimelineStackingSync.ts
@@ -5,23 +5,30 @@ import { useStudioShellContextOptional } from "../../contexts/StudioContext";
import { findElementForSelection } from "../../components/editor/domEditingElement";
import { readEffectiveZIndex } from "../../components/editor/canvasContextMenuZOrder";
import type { StackingPatch } from "./timelineStackingSync";
+import type { TimelineZIndexReorderCommit } from "../../hooks/useTimelineEditingTypes";
-interface UseTimelineStackingSyncInput {
+/** With both set, a lane move restacks the preview's z-index to match the rows; each overrides Studio's own. */
+export interface TimelineStackingSyncProps {
+ previewIframeRef?: RefObject<HTMLIFrameElement | null>;
+ onZIndexReorder?: TimelineZIndexReorderCommit;
+}
+
+interface UseTimelineStackingSyncInput extends TimelineStackingSyncProps {
expandedElementsRef: RefObject<TimelineElement[]>;
}
-// Lane ↔ stacking unification (research/STAGE3-NEEDED-WIRING.md). Provision the
-// two deps commitDraggedClipMove accepts so a lane-change drag also patches the
-// edited clip's z-index. Both read the SAME preview iframe + z-order persist path
-// the canvas right-click menu / LayersPanel use, so a timeline lane move and a
-// menu z-edit produce one shared inline-style commit shape. Optional contexts:
-// outside the NLE (standalone <Timeline>) these are null ⇒ deps undefined ⇒ the
-// commit's z-sync is a no-op (backward compatible).
-export function useTimelineStackingSync({ expandedElementsRef }: UseTimelineStackingSyncInput) {
+// Lane ↔ stacking sync: the two deps commitDraggedClipMove takes so a lane-change drag also patches
+// z-index, through the same iframe + z persist path the canvas menu and LayersPanel use. Either missing ⇒ no-op.
+export function useTimelineStackingSync({
+ expandedElementsRef,
+ previewIframeRef,
+ onZIndexReorder,
+}: UseTimelineStackingSyncInput) {
const domEditActions = useDomEditActionsContextOptional();
const shell = useStudioShellContextOptional();
- const zSyncPreviewIframeRef = domEditActions?.previewIframeRef ?? null;
- const handleDomZIndexReorderCommit = domEditActions?.handleDomZIndexReorderCommit;
+ const zSyncPreviewIframeRef = previewIframeRef ?? domEditActions?.previewIframeRef ?? null;
+ const handleDomZIndexReorderCommit =
+ onZIndexReorder ?? domEditActions?.handleDomZIndexReorderCommit;
const zSyncActiveCompPath = shell?.activeCompPath ?? null;
// Resolve a TimelineElement to its live iframe HTMLElement via the same
diff --git a/packages/studio/src/timelineStackingSyncExport.test.tsx b/packages/studio/src/timelineStackingSyncExport.test.tsx
new file mode 100644
index 0000000000..adaed4b523
--- /dev/null
+++ b/packages/studio/src/timelineStackingSyncExport.test.tsx
@@ -0,0 +1,67 @@
+// @vitest-environment happy-dom
+// Mounts the timeline by package name with no Studio shell, as a host app does.
+import { act } from "react";
+import { expect, it, vi } from "vitest";
+import { Timeline, usePlayerStore, type TimelineZIndexReorderCommit } from "@hyperframes/studio";
+import { installReactActEnvironment, mountReactHarness } from "./hooks/domSelectionTestHarness";
+
+installReactActEnvironment();
+// happy-dom has no layout; the timeline only renders clips inside a sized viewport.
+for (const [prop, px] of [
+ ["clientWidth", 1000],
+ ["clientHeight", 400],
+ ["offsetWidth", 1000],
+ ["offsetHeight", 400],
+] as const) {
+ vi.spyOn(HTMLElement.prototype, prop, "get").mockReturnValue(px);
+}
+
+const settle = () => act(async () => new Promise((r) => setTimeout(r, 50)));
+const pointer = (type: string, clientY: number) =>
+ new PointerEvent(type, { bubbles: true, button: 0, pointerId: 1, clientX: 150, clientY });
+
+it("restacks the host's preview when a lane move puts a clip below another", async () => {
+ const iframe = document.createElement("iframe");
+ document.body.appendChild(iframe);
+ const doc = iframe.contentDocument!;
+ // No authored z: DOM order paints tag over title, which matches the rows until the move.
+ doc.body.innerHTML = '<div id="title"></div><div id="tag"></div><div id="note"></div>';
+ const clip = (id: string, start: number, duration: number, track: number) =>
+ ({ id, key: id, domId: id, tag: "div", start, duration, track }) as const;
+ usePlayerStore.setState({
+ duration: 10,
+ timelineReady: true,
+ elements: [clip("title", 0, 4, 1), clip("tag", 0, 4, 0), clip("note", 6, 2, 2)],
+ });
+ const commit = vi.fn<TimelineZIndexReorderCommit>(async (entries) => {
+ for (const e of entries) e.element.style.zIndex = String(e.zIndex);
+ });
+ const root = mountReactHarness(
+ <Timeline
+ previewIframeRef={{ current: iframe }}
+ onZIndexReorder={commit}
+ onMoveElement={async () => {}}
+ onMoveElements={async () => {}}
+ />,
+ );
+ await settle();
+ const tagClip = document.querySelector<HTMLElement>('.timeline-clip[aria-label^="tag,"]')!;
+ vi.spyOn(tagClip, "getBoundingClientRect").mockReturnValue(new DOMRect(80, 77, 360, 42));
+
+ // Drag tag from the top row to the bottom row, clear of note in time.
+ act(() => void tagClip.dispatchEvent(pointer("pointerdown", 98)));
+ act(() => {
+ window.dispatchEvent(pointer("pointermove", 140));
+ window.dispatchEvent(pointer("pointermove", 194));
+ });
+ await act(async () => void window.dispatchEvent(pointer("pointerup", 194)));
+ await settle();
+
+ expect(usePlayerStore.getState().elements.find((e) => e.id === "tag")?.track).toBe(2);
+ expect(commit).toHaveBeenCalledTimes(1);
+ expect(commit.mock.calls[0]![0].every((e) => e.element.ownerDocument === doc)).toBe(true);
+ const z = (id: string) => Number(doc.getElementById(id)!.style.zIndex || 0);
+ expect(z("title")).toBeGreaterThan(z("tag"));
+ await act(async () => root.unmount());
+ usePlayerStore.setState({ elements: [], timelineReady: false });
+});