Skip to content

Commit 5262062

Browse files
feat(studio): export timeline editing for a host outside EditorShell (#4201)
* fix(studio): undo waits for in-flight hand edits before consuming history * docs(studio): trim comments to the 3-line house rule * feat(studio): export timeline editing, undo/redo, conflict banner and TimelinePane for a host * docs(studio): trim comments to the 3-line house rule * refactor(studio): simplify exports pass * docs(studio): trim comments to the 3-line house rule * fix(studio): resolve canEdit targets against expanded timeline rows * docs(studio): trim comment to the 3-line house rule * fix(studio): guard razor-split-all and the audio-group attribute write * fix(studio): gate the audio-group attribute for sub-composition-only members * fix(studio): keep blocked timeline edits truthful Refresh cached permission checks from the current host policy, gate auto-grouping before live patches, and restore optimistic attribute previews when a guarded commit is refused. * fix(studio): publish desktop compatibility exports Expose range selection and the canonical loader from the built Studio package while retaining timeline editing seams. * fix(studio): gate timeline drop writes Route asset, file, and composition drops through the shared edit permission gate before any side effect. * fix(studio): preserve release-owned style exports * fix(studio): clear file and Fallow gates * fix(studio): keep the carve gate and range slice under the size budgets * style(studio): format playerStore
1 parent d11907c commit 5262062

26 files changed

Lines changed: 1678 additions & 227 deletions

‎packages/studio/src/components/nle/TimelinePane.tsx‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
import { useCallback, type ReactNode } from "react";
22
import { Timeline } from "../../player";
3-
import type { TimelineElement } from "../../player";
3+
import type { TimelineElement, TimelineTimeRange } from "../../player";
44
import type { BlockedTimelineEditIntent } from "../../player/components/timelineEditing";
55
import { useTimelineEditContext } from "../../contexts/TimelineEditContext";
66
import { trackStudioExpandedClipEdit } from "../../telemetry/events";
@@ -77,6 +77,9 @@ export interface TimelinePaneProps {
7777
timelineToolbar?: ReactNode;
7878
/** Slot rendered below the timeline tracks */
7979
timelineFooter?: ReactNode;
80+
/** Slot for a host's own overlay spanning the whole timeline area (e.g. a draft/ghost
81+
* clip), positioned absolutely the same way PreviewPane's previewOverlay is. */
82+
timelineOverlay?: ReactNode;
8083
/** Custom clip content renderer for timeline (thumbnails, waveforms, etc.) */
8184
renderClipContent?: (
8285
element: TimelineElement,
@@ -101,6 +104,7 @@ export interface TimelinePaneProps {
101104
) => Promise<void> | void;
102105
onBlockedEditAttempt?: (element: TimelineElement, intent: BlockedTimelineEditIntent) => void;
103106
onSelectTimelineElement?: (element: TimelineElement | null) => void;
107+
onRangeSelect?: (range: TimelineTimeRange | null) => void;
104108
/** Copy/paste/duplicate act on the store's own selection, not a passed
105109
* element, so unlike onDeleteElement they need no composition-basis wrapper. */
106110
onCopyClip?: () => boolean;
@@ -113,6 +117,7 @@ export interface TimelinePaneProps {
113117
export function TimelinePane({
114118
timelineToolbar,
115119
timelineFooter,
120+
timelineOverlay,
116121
renderClipContent,
117122
onFileDrop,
118123
onDeleteElement,
@@ -121,6 +126,7 @@ export function TimelinePane({
121126
onCompositionDrop,
122127
onBlockedEditAttempt,
123128
onSelectTimelineElement,
129+
onRangeSelect,
124130
onCopyClip,
125131
onPasteClip,
126132
onDuplicateClip,
@@ -278,13 +284,17 @@ export function TimelinePane({
278284
onBlockedEditAttempt={onBlockedEditAttempt}
279285
onSplitElement={handleSplitElement}
280286
onSelectElement={onSelectTimelineElement}
287+
onRangeSelect={onRangeSelect}
281288
onCopyClip={onCopyClip}
282289
onPasteClip={onPasteClip}
283290
onDuplicateClip={onDuplicateClip}
284291
canPasteClip={canPasteClip}
285292
/>
286293
</div>
287294
{timelineFooter && <div className="shrink-0">{timelineFooter}</div>}
295+
{timelineOverlay && (
296+
<div className="pointer-events-none absolute inset-0 z-20">{timelineOverlay}</div>
297+
)}
288298
{timelineDisabled && (
289299
<div
290300
className="absolute inset-0 z-30 cursor-not-allowed bg-black/18 flex items-center justify-center"

‎packages/studio/src/hooks/timelineAudioGroupCreate.ts‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,19 @@ import {
2828
type UseTimelineElementVisibilityEditingInput,
2929
} from "./timelineTrackVisibility";
3030

31+
interface AudioGroupCarveInput extends UseTimelineElementVisibilityEditingInput {
32+
checkEditable?: (elements: readonly TimelineElement[]) => boolean;
33+
}
34+
35+
function assertAudioGroupEditable(
36+
checkEditable: AudioGroupCarveInput["checkEditable"],
37+
elements: readonly TimelineElement[],
38+
): void {
39+
if (checkEditable && !checkEditable(elements)) {
40+
throw new Error("Timeline edit blocked");
41+
}
42+
}
43+
3144
/**
3245
* Assign (or restore) `data-audio-group` across a set of members.
3346
*
@@ -267,7 +280,8 @@ export function useAudioGroupCarveAssignment({
267280
previewIframeRef,
268281
pendingTimelineEditPathRef,
269282
isRecordingRef,
270-
}: UseTimelineElementVisibilityEditingInput): (
283+
checkEditable,
284+
}: AudioGroupCarveInput): (
271285
clipIds: readonly string[],
272286
groupId: string,
273287
groupLabel?: string,
@@ -289,6 +303,7 @@ export function useAudioGroupCarveAssignment({
289303
const domId = runtimeAudioId(item);
290304
return domId !== null && wanted.has(domId);
291305
});
306+
if (elements.length === wanted.size) assertAudioGroupEditable(checkEditable, elements);
292307
try {
293308
// Loud, not silent: an unresolved id used to leave `elements` short,
294309
// `createAudioGroupAndAssignMembers` returning early with no write, and
@@ -333,6 +348,7 @@ export function useAudioGroupCarveAssignment({
333348
isRecordingRef,
334349
showToast,
335350
projectIdRef,
351+
checkEditable,
336352
],
337353
);
338354
}

‎packages/studio/src/hooks/timelineAudioGroupVolume.ts‎

Lines changed: 35 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import { useCallback } from "react";
1+
import { useCallback, useRef } from "react";
22
import { HF_AUDIO_FX_ATTR } from "@hyperframes/core/audio-fx";
33
import { HF_AUDIO_AUTOMATION_ATTR } from "@hyperframes/core/audio-automation";
44
import { usePlayerStore } from "../player";
@@ -29,6 +29,10 @@ function patchLiveGroupAttribute(
2929
invalidateGroupInfoCache(iframe?.contentDocument);
3030
}
3131

32+
function audioGroupAttributeLiveKey(groupId: string, attr: string): string {
33+
return `${groupId}\0${attr}`;
34+
}
35+
3236
/**
3337
* `data-volume` exactly as core reads it (`readAudioGroupVolume`): an absent or
3438
* empty attribute is UNITY, not zero.
@@ -210,9 +214,16 @@ export function useSetAudioGroupAttribute({
210214
}: UseTimelineElementVisibilityEditingInput): {
211215
setLive: (groupId: string, attr: string, value: string | null) => void;
212216
setQuiet: (groupId: string, attr: string, value: string | null, label: string) => Promise<void>;
217+
revertLive: (groupId: string, attr: string) => void;
213218
} {
219+
const liveBeforeRef = useRef(new Map<string, string | null>());
214220
const setLive = useCallback(
215221
(groupId: string, attr: string, value: string | null) => {
222+
const key = audioGroupAttributeLiveKey(groupId, attr);
223+
const target = previewIframeRef.current?.contentDocument?.getElementById(groupId);
224+
if (!liveBeforeRef.current.has(key)) {
225+
liveBeforeRef.current.set(key, target?.getAttribute(attr) ?? null);
226+
}
216227
patchLiveGroupAttribute(previewIframeRef.current, groupId, attr, value);
217228
// Live too, not just on commit: a fader drag is `setLive` per frame and
218229
// `setQuiet` once on release, so without this the strip's own readout
@@ -221,6 +232,26 @@ export function useSetAudioGroupAttribute({
221232
},
222233
[previewIframeRef],
223234
);
235+
const revertLive = useCallback(
236+
(groupId: string, attr: string) => {
237+
const key = audioGroupAttributeLiveKey(groupId, attr);
238+
if (!liveBeforeRef.current.has(key)) return;
239+
patchLiveGroupAttribute(
240+
previewIframeRef.current,
241+
groupId,
242+
attr,
243+
liveBeforeRef.current.get(key) ?? null,
244+
);
245+
syncStoredGroupAttribute(
246+
groupId,
247+
attr,
248+
previewIframeRef.current?.contentDocument?.getElementById(groupId)?.getAttribute(attr) ??
249+
null,
250+
);
251+
liveBeforeRef.current.delete(key);
252+
},
253+
[previewIframeRef],
254+
);
224255
const setQuiet = useCallback(
225256
async (groupId: string, attr: string, value: string | null, label: string) => {
226257
if (isRecordingRef?.current) {
@@ -242,6 +273,7 @@ export function useSetAudioGroupAttribute({
242273
recordEdit,
243274
pendingTimelineEditPathRef,
244275
});
276+
liveBeforeRef.current.delete(audioGroupAttributeLiveKey(groupId, attr));
245277
syncStoredGroupAttribute(groupId, attr, value);
246278
} catch (error) {
247279
// `persistElementAttribute` leaves the live DOM at the previous value
@@ -257,6 +289,7 @@ export function useSetAudioGroupAttribute({
257289
console.error("[Timeline] Failed to set group attribute", error);
258290
const message = error instanceof Error ? error.message : "Failed to update group";
259291
showToast(message);
292+
liveBeforeRef.current.delete(audioGroupAttributeLiveKey(groupId, attr));
260293
}
261294
},
262295
[
@@ -270,5 +303,5 @@ export function useSetAudioGroupAttribute({
270303
projectIdRef,
271304
],
272305
);
273-
return { setLive, setQuiet };
306+
return { setLive, setQuiet, revertLive };
274307
}
Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
import { useCallback } from "react";
2+
import type { TimelineElement } from "../player";
3+
4+
/** A host's verdict on one element: editable, or blocked with a reason to show. */
5+
export type TimelineEditPermission = true | { blocked: true; reason: string };
6+
7+
export type CanEditTimelineElement = (element: TimelineElement) => TimelineEditPermission;
8+
9+
/**
10+
* Refuses a write when any target element is blocked, toasting the host's
11+
* reason. Absent `canEdit` never refuses, so Studio itself is unchanged.
12+
*/
13+
export function useTimelineEditGate(
14+
canEdit: CanEditTimelineElement | undefined,
15+
showToast: (message: string, tone?: "error" | "info") => void,
16+
) {
17+
return useCallback(
18+
(targets: readonly TimelineElement[]): boolean => {
19+
if (!canEdit) return true;
20+
for (const element of targets) {
21+
const verdict = canEdit(element);
22+
if (verdict !== true) {
23+
showToast(verdict.reason, "error");
24+
return false;
25+
}
26+
}
27+
return true;
28+
},
29+
[canEdit, showToast],
30+
);
31+
}

‎packages/studio/src/hooks/timelineElementFxAttribute.ts‎

Lines changed: 34 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
* shared core `setAudioGroupAttribute` also uses.
88
*/
99

10-
import { useCallback } from "react";
10+
import { useCallback, useRef } from "react";
1111
import type { TimelineElement } from "../player";
1212
import {
1313
buildPatchTarget,
@@ -32,6 +32,14 @@ function patchLiveElementAttribute(
3232
else target.setAttribute(attr, value);
3333
}
3434

35+
function elementAttributeLiveKey(
36+
element: TimelineElement,
37+
activeCompPath: string | null,
38+
attr: string,
39+
): string {
40+
return `${element.sourceFile || activeCompPath || "index.html"}\0${element.key ?? element.domId ?? element.id}\0${attr}`;
41+
}
42+
3543
interface SetElementAttributeInput {
3644
projectId: string;
3745
activeCompPath: string | null;
@@ -92,13 +100,35 @@ export function useSetElementAttribute({
92100
value: string | null,
93101
label: string,
94102
) => Promise<void>;
103+
revertLive: (element: TimelineElement, attr: string) => void;
95104
} {
105+
const liveBeforeRef = useRef(new Map<string, string | null>());
96106
const setLive = useCallback(
97107
(element: TimelineElement, attr: string, value: string | null) => {
108+
const key = elementAttributeLiveKey(element, activeCompPath, attr);
109+
const target = findTimelineElementInIframe(previewIframeRef.current, element, activeCompPath);
110+
if (!liveBeforeRef.current.has(key)) {
111+
liveBeforeRef.current.set(key, target?.getAttribute(attr) ?? null);
112+
}
98113
patchLiveElementAttribute(previewIframeRef.current, element, attr, value, activeCompPath);
99114
},
100115
[previewIframeRef, activeCompPath],
101116
);
117+
const revertLive = useCallback(
118+
(element: TimelineElement, attr: string) => {
119+
const key = elementAttributeLiveKey(element, activeCompPath, attr);
120+
if (!liveBeforeRef.current.has(key)) return;
121+
patchLiveElementAttribute(
122+
previewIframeRef.current,
123+
element,
124+
attr,
125+
liveBeforeRef.current.get(key) ?? null,
126+
activeCompPath,
127+
);
128+
liveBeforeRef.current.delete(key);
129+
},
130+
[previewIframeRef, activeCompPath],
131+
);
102132
const setQuiet = useCallback(
103133
async (element: TimelineElement, attr: string, value: string | null, label: string) => {
104134
if (isRecordingRef?.current) {
@@ -120,10 +150,12 @@ export function useSetElementAttribute({
120150
recordEdit,
121151
pendingTimelineEditPathRef,
122152
});
153+
liveBeforeRef.current.delete(elementAttributeLiveKey(element, activeCompPath, attr));
123154
} catch (error) {
124155
console.error("[Timeline] Failed to set element attribute", error);
125156
const message = error instanceof Error ? error.message : "Failed to update effect";
126157
showToast(message);
158+
liveBeforeRef.current.delete(elementAttributeLiveKey(element, activeCompPath, attr));
127159
}
128160
},
129161
[
@@ -137,5 +169,5 @@ export function useSetElementAttribute({
137169
projectIdRef,
138170
],
139171
);
140-
return { setLive, setQuiet };
172+
return { setLive, setQuiet, revertLive };
141173
}

0 commit comments

Comments
 (0)