Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
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.tsindex 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/hexport { 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.tsindex 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.tsxindex 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.tsxindex 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.tsindex 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 samediff --git a/packages/studio/src/timelineStackingSyncExport.test.tsx b/packages/studio/src/timelineStackingSyncExport.test.tsxnew file mode 100644index 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 });+});