@hyperframes/studio 0.9.41 → 0.9.43

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/dist/assets/{codec-B_mpbc4w.js → codec-DHChmhF2.js} +1 -1
  2. package/dist/assets/{hyperframes-player-Dvi3I_mv.js → hyperframes-player-CdbweVDs.js} +1 -1
  3. package/dist/assets/{index-B5ExwsOp.js → index-CjWDrWWG.js} +166 -166
  4. package/dist/assets/{index-BrFm9Y5k.js → index-l-ti2dV8.js} +1 -1
  5. package/dist/assets/{pausedVideoDecoder-MHQ57yZ6.js → pausedVideoDecoder-xqOQ0ciK.js} +1 -1
  6. package/dist/index.d.ts +9 -1
  7. package/dist/index.html +1 -1
  8. package/dist/index.js +1380 -989
  9. package/package.json +10 -10
  10. package/src/components/editor/LayersPanel.opaque.test.ts +176 -0
  11. package/src/components/editor/LayersPanel.tsx +41 -10
  12. package/src/components/editor/domEditInlineText.ts +1 -16
  13. package/src/components/editor/domEditOverlayGeometry.ts +2 -0
  14. package/src/components/editor/domEditOverlayStartGesture.ts +31 -7
  15. package/src/components/editor/domEditingTypes.ts +7 -1
  16. package/src/components/editor/gestureUndoRevert.ts +18 -1
  17. package/src/components/editor/inlineTextStyleRange.fill.test.ts +129 -0
  18. package/src/components/editor/inlineTextStyleRange.test.ts +0 -82
  19. package/src/components/editor/layerKind.ts +2 -19
  20. package/src/components/editor/layersPanelSort.ts +2 -2
  21. package/src/components/editor/manualEdits.ts +1 -0
  22. package/src/components/editor/manualEditsSnapshot.ts +10 -0
  23. package/src/components/editor/manualOffsetDrag.test.ts +1 -1
  24. package/src/components/editor/manualOffsetDrag.ts +17 -6
  25. package/src/components/editor/marqueeCommit.ts +47 -4
  26. package/src/components/editor/plainTranslate.ts +37 -16
  27. package/src/components/editor/previewDrafts.test.ts +263 -0
  28. package/src/components/editor/previewDrafts.ts +73 -0
  29. package/src/components/editor/previewGestureStartRead.test.ts +279 -0
  30. package/src/components/editor/previewGestureStartRead.ts +67 -0
  31. package/src/components/editor/previewGestureStarts.ts +21 -15
  32. package/src/components/editor/previewLayers.test.ts +308 -0
  33. package/src/components/editor/previewLayers.ts +164 -0
  34. package/src/components/editor/previewOverlayRects.test.ts +62 -0
  35. package/src/components/editor/previewOverlayRects.ts +23 -8
  36. package/src/components/editor/previewPointerTargets.test.ts +68 -1
  37. package/src/components/editor/previewSelection.ts +55 -11
  38. package/src/components/editor/resizeDraft.ts +38 -0
  39. package/src/components/editor/snapTargetCollection.ts +26 -62
  40. package/src/components/editor/useDomEditOverlayGestures.ts +2 -2
  41. package/src/components/editor/useLayerDrag.ts +1 -1
  42. package/src/components/nle/NLEPreview.slowBoot.test.ts +0 -1
  43. package/src/hooks/domEditDeleteMembers.test.ts +7 -0
  44. package/src/hooks/domSelectionTimelineMirror.ts +3 -1
  45. package/src/hooks/timelineTimingSync.ts +4 -1
  46. package/src/hooks/useDomSelection.ts +2 -0
  47. package/src/hooks/useEditorSave.test.tsx +22 -1
  48. package/src/hooks/useEditorSave.ts +3 -1
  49. package/src/hooks/usePreviewInteraction.ts +4 -1
  50. package/src/hooks/useProjectFileWriter.ts +7 -3
  51. package/src/hooks/useTimelineSelectionPreviewSync.test.tsx +30 -0
  52. package/src/hooks/useTimelineSelectionPreviewSync.ts +7 -2
  53. package/src/player/lib/layerOrdering.ts +2 -11
  54. package/src/player/lib/previewElements.ts +68 -0
  55. package/src/test-setup.ts +2 -0
  56. package/src/utils/gsapSoftReload.ts +1 -1
  57. package/src/utils/studioFileHistory.ts +1 -1
  58. package/src/utils/studioHelpers.ts +27 -4
  59. package/src/utils/studioSaveDiagnostics.test.ts +34 -0
  60. package/src/utils/studioSaveDiagnostics.ts +35 -6
  61. package/src/utils/timelineCompositionInsert.ts +3 -1
@@ -74,6 +74,7 @@ export function usePreviewInteraction({
74
74
  }: UsePreviewInteractionParams) {
75
75
  const cycleRef = useRef<ClickCycleState | null>(null);
76
76
  const lastDownRef = useRef<{ t: number; x: number; y: number } | null>(null);
77
+ const hoverSeqRef = useRef(0);
77
78
 
78
79
  const pausePreviewPlayback = useCallback(() => {
79
80
  const pausedTime = pauseStudioPreviewPlayback(previewIframeRef.current);
@@ -238,6 +239,7 @@ export function usePreviewInteraction({
238
239
  const handlePreviewCanvasPointerMove = useCallback(
239
240
  // fallow-ignore-next-line complexity
240
241
  async (e: React.PointerEvent<HTMLDivElement>, options?: { preferClipAncestor?: boolean }) => {
242
+ const seq = ++hoverSeqRef.current;
241
243
  if (captionEditMode || compositionLoading) {
242
244
  updateDomEditHoverSelection(null);
243
245
  return null;
@@ -247,7 +249,7 @@ export function usePreviewInteraction({
247
249
  preferClipAncestor: options?.preferClipAncestor ?? false,
248
250
  skipSourceProbe: true,
249
251
  });
250
- updateDomEditHoverSelection(nextSelection);
252
+ if (seq === hoverSeqRef.current) updateDomEditHoverSelection(nextSelection);
251
253
  return nextSelection;
252
254
  },
253
255
  [
@@ -259,6 +261,7 @@ export function usePreviewInteraction({
259
261
  );
260
262
 
261
263
  const handlePreviewCanvasPointerLeave = useCallback(() => {
264
+ hoverSeqRef.current += 1;
262
265
  updateDomEditHoverSelection(null);
263
266
  }, [updateDomEditHoverSelection]);
264
267
 
@@ -17,7 +17,8 @@ async function fetchProjectFile(projectId: string | null, path: string, query: s
17
17
  const response = await studioApiFetch(
18
18
  `/api/projects/${encodeURIComponent(projectId)}/files/${encodeURIComponent(path)}${query}`,
19
19
  );
20
- if (!response.ok) throw new Error(`Failed to read ${path}`);
20
+ if (!response.ok)
21
+ throw await createStudioSaveHttpError(response, `Failed to read ${path}`, { path });
21
22
  const data = (await response.json()) as { content?: string; version?: string };
22
23
  return { content: data.content, version: data.version ?? response.headers.get("etag") };
23
24
  }
@@ -78,7 +79,9 @@ export function useProjectFileWriter({ projectId }: UseProjectFileWriterOptions)
78
79
  } else if (preflight.status === 404) {
79
80
  expectedVersion = null;
80
81
  } else {
81
- throw await createStudioSaveHttpError(preflight, `Failed to read ${path} before save`);
82
+ throw await createStudioSaveHttpError(preflight, `Failed to read ${path} before save`, {
83
+ path,
84
+ });
82
85
  }
83
86
  }
84
87
  // fallow-ignore-next-line complexity
@@ -121,7 +124,8 @@ export function useProjectFileWriter({ projectId }: UseProjectFileWriterOptions)
121
124
  attemptedContent: content,
122
125
  });
123
126
  }
124
- if (!response.ok) throw await createStudioSaveHttpError(response, `Failed to save ${path}`);
127
+ if (!response.ok)
128
+ throw await createStudioSaveHttpError(response, `Failed to save ${path}`, { path });
125
129
  const result = (await response.json()) as { version?: string };
126
130
  const version = result.version ?? response.headers.get("etag");
127
131
  if (!version)
@@ -80,6 +80,36 @@ function makeSyncFixture() {
80
80
  }
81
81
 
82
82
  describe("useTimelineSelectionPreviewSync", () => {
83
+ it("keeps an opaque frame's selection that matches a clip known only by its id", async () => {
84
+ // An opaque frame's rows carry only the clip id; its selections carry the frame's handle.
85
+ const timelineElements = [
86
+ { id: "clip-1", tag: "div", start: 0, duration: 1, track: 0 },
87
+ ] as TimelineElement[];
88
+ const element = document.createElement("div");
89
+ element.id = "clip-1";
90
+ const selection = { ...makeSelection("First", element), handle: "0123456789abcdef:1" };
91
+ const applyDomSelection = vi.fn();
92
+ const applyMarqueeSelection = vi.fn();
93
+ const buildDomSelectionForTimelineElement = vi.fn(async () => null);
94
+ const harness = renderHarness();
95
+
96
+ await harness.rerender({
97
+ selectedElementId: "clip-1",
98
+ selectedElementIds: new Set(["clip-1"]),
99
+ timelineElements,
100
+ domEditSelection: selection,
101
+ domEditGroupSelections: [selection],
102
+ buildDomSelectionForTimelineElement,
103
+ applyDomSelection,
104
+ applyMarqueeSelection,
105
+ onSelectionNotFound: vi.fn(),
106
+ });
107
+
108
+ expect(buildDomSelectionForTimelineElement).not.toHaveBeenCalled();
109
+ expect(applyDomSelection).not.toHaveBeenCalled();
110
+ harness.cleanup();
111
+ });
112
+
83
113
  it("syncs a multi-id timeline selection into preview group selections", async () => {
84
114
  const { firstSelection, secondSelection, timelineElements, selectionById } = makeSyncFixture();
85
115
  const applyDomSelection = vi.fn();
@@ -139,11 +139,16 @@ export function useTimelineSelectionPreviewSync({
139
139
  : [];
140
140
  const currentIds = currentSelections
141
141
  .map((selection) =>
142
- resolveTimelineIdForSelection(selection, timelineElements, activeCompPath),
142
+ resolveTimelineIdForSelection(selection, timelineElements, activeCompPath, true),
143
143
  )
144
144
  .filter((id): id is string => Boolean(id));
145
145
  const currentAnchor = currentDomEditSelection
146
- ? resolveTimelineIdForSelection(currentDomEditSelection, timelineElements, activeCompPath)
146
+ ? resolveTimelineIdForSelection(
147
+ currentDomEditSelection,
148
+ timelineElements,
149
+ activeCompPath,
150
+ true,
151
+ )
147
152
  : null;
148
153
 
149
154
  if (selectedIds.length === 0) {
@@ -1,3 +1,4 @@
1
+ import { elementZIndex } from "@hyperframes/core/runtime/editing-port";
1
2
  import { readLayerRevealPriorZ } from "./timelineElementHelpers";
2
3
 
3
4
  export interface StackingContextDescriptor {
@@ -16,17 +17,7 @@ export function getElementZIndex(element: HTMLElement): number {
16
17
  // An active Layers-panel reveal lift reports the element's TRUE z.
17
18
  const prior = readLayerRevealPriorZ(element);
18
19
  if (prior != null) return prior;
19
- const inline = element.style?.zIndex;
20
- if (inline && inline !== "auto") {
21
- const parsed = parseInt(inline, 10);
22
- if (Number.isFinite(parsed)) return parsed;
23
- }
24
- const win = element.ownerDocument?.defaultView;
25
- if (!win) return 0;
26
- const value = win.getComputedStyle(element).zIndex;
27
- if (value === "auto" || value === "") return 0;
28
- const parsed = parseInt(value, 10);
29
- return Number.isFinite(parsed) ? parsed : 0;
20
+ return elementZIndex(element);
30
21
  } catch {
31
22
  return 0;
32
23
  }
@@ -8,12 +8,15 @@ import {
8
8
  MAX_ELEMENT_ENTRIES,
9
9
  MAX_ELEMENT_VALUE,
10
10
  MAX_GEOMETRY_CHILDREN,
11
+ MAX_SNAP_TARGETS,
11
12
  type EditingElementBox,
12
13
  type EditingElementDescription,
13
14
  type EditingElementGeometry,
15
+ type EditingGestureStart,
14
16
  type EditingElementHit,
15
17
  type EditingElementMatch,
16
18
  type EditingElementSource,
19
+ type EditingLayer,
17
20
  } from "@hyperframes/core/runtime/editing-port";
18
21
  import { resolveElementSourceFile } from "../../components/editor/domEditingDom";
19
22
  import { previewRequest } from "./previewChannel";
@@ -224,3 +227,68 @@ export async function previewGeometry(
224
227
  children: children && childrenOk ? (boxes as EditingElementBox[]) : null,
225
228
  };
226
229
  }
230
+
231
+ const isFlag = (value: unknown) => typeof value === "boolean";
232
+ const isFiniteFields = (value: unknown, keys: string[]) =>
233
+ isFields(value) && keys.every((key) => Number.isFinite(value[key]));
234
+
235
+ const readGestureStart = (value: unknown): EditingGestureStart | null => {
236
+ if (!readGeometry(value) || !isFields(value)) return null;
237
+ const { layout, move, gsap } = value;
238
+ const valid = [
239
+ isFiniteFields(layout, ["width", "height"]),
240
+ move === null || isFiniteFields(move, ["a", "b", "c", "d"]),
241
+ gsap === null || (isFields(gsap) && isFiniteFields(gsap, ["x", "y"]) && isFlag(gsap.moving)),
242
+ ];
243
+ return valid.includes(false) ? null : (value as unknown as EditingGestureStart);
244
+ };
245
+
246
+ export interface PreviewGestureStartReply {
247
+ /** One entry per handle, in order: null for an element the frame no longer has. */
248
+ elements: Array<EditingGestureStart | null>;
249
+ snap: EditingElementBox[];
250
+ }
251
+
252
+ /** What a gesture on `handles` starts from, in one read; null when the runtime cannot answer. */
253
+ export async function previewGestureStart(
254
+ iframe: HTMLIFrameElement,
255
+ handles: readonly string[],
256
+ ): Promise<PreviewGestureStartReply | null> {
257
+ if (!handles.length || handles.length > MAX_DESCRIBE_HANDLES) return null;
258
+ const reply = await previewRequest(iframe, "gesture-start", { handles: [...handles] });
259
+ const elements: unknown = reply?.elements;
260
+ const snap: unknown = reply?.snap;
261
+ if (!Array.isArray(elements) || elements.length !== handles.length) return null;
262
+ if (!Array.isArray(snap) || snap.length > MAX_SNAP_TARGETS || !snap.every(isBox)) return null;
263
+ return { elements: elements.map(readGestureStart), snap };
264
+ }
265
+
266
+ const LAYER_KINDS = new Set(["image", "video", "audio", "vector", "group", "text", "shape"]);
267
+ const isLayer = (value: unknown): value is EditingLayer =>
268
+ isFields(value) &&
269
+ isHandle(value.handle) &&
270
+ isCount(value.depth) &&
271
+ isCount(value.childCount) &&
272
+ Number.isFinite(value.zIndex) &&
273
+ LAYER_KINDS.has(value.kind as string);
274
+
275
+ export interface PreviewLayers {
276
+ layers: EditingLayer[];
277
+ truncated: boolean;
278
+ missingGroup: boolean;
279
+ }
280
+
281
+ /** One page of the frame's layers in document order from `offset`, scoped to `group` when given; null when the runtime cannot answer. */
282
+ export async function previewLayers(
283
+ iframe: HTMLIFrameElement,
284
+ group?: string,
285
+ offset = 0,
286
+ ): Promise<PreviewLayers | null> {
287
+ const params = { ...(group ? { group } : {}), ...(offset ? { offset } : {}) };
288
+ const reply = await previewRequest(iframe, "layers", params);
289
+ const layers: unknown = reply?.layers;
290
+ const { truncated, missingGroup } = reply ?? {};
291
+ if (!Array.isArray(layers) || typeof truncated !== "boolean") return null;
292
+ if (typeof missingGroup !== "boolean") return null;
293
+ return layers.every(isLayer) ? { layers, truncated, missingGroup } : null;
294
+ }
package/src/test-setup.ts CHANGED
@@ -12,3 +12,5 @@ if (typeof CSS.escape !== "function") {
12
12
  if (typeof globalThis.confirm !== "function") {
13
13
  (globalThis as Record<string, unknown>).confirm = () => false;
14
14
  }
15
+
16
+ (globalThis as Record<string, unknown>).BASE_UI_ANIMATIONS_DISABLED = true;
@@ -286,8 +286,8 @@ export function applySoftReloadFinalization(
286
286
  currentTime: number,
287
287
  ): boolean {
288
288
  const win = iframe?.contentWindow as IframeWindow | null;
289
- if (!win?.__hfForceTimelineRebind) return false;
290
289
  try {
290
+ if (!win?.__hfForceTimelineRebind) return false;
291
291
  if (win.__hfSuppressSceneMutations) {
292
292
  win.__hfSuppressSceneMutations(() => finalizeSoftReload(win, currentTime));
293
293
  } else {
@@ -75,7 +75,7 @@ export async function readProjectFileContent(pid: string, path: string): Promise
75
75
  buildProjectApiPath(pid, `/files/${encodeURIComponent(path)}`),
76
76
  );
77
77
  if (!response.ok) {
78
- throw await createStudioSaveHttpError(response, `Failed to read ${path}`);
78
+ throw await createStudioSaveHttpError(response, `Failed to read ${path}`, { path });
79
79
  }
80
80
  const data = (await response.json()) as { content?: string };
81
81
  if (typeof data.content !== "string") {
@@ -133,14 +133,30 @@ export type ElementMatchSelection = Pick<
133
133
  | "sourceFile"
134
134
  | "compositionSrc"
135
135
  | "isCompositionHost"
136
- >;
136
+ > &
137
+ Partial<Pick<DomEditSelection, "handle">>;
138
+
139
+ function matchesByClipId(
140
+ selection: ElementMatchSelection,
141
+ element: TimelineElement,
142
+ file: string,
143
+ value: string | undefined,
144
+ clipIdScope: string | undefined,
145
+ ) {
146
+ if (!clipIdScope || !selection.handle) return false;
147
+ if (element.domId || element.hfId || element.selector) return false;
148
+ return element.id === value && (element.sourceFile || clipIdScope) === file;
149
+ }
137
150
 
138
151
  function matchesByDomId(
139
152
  selection: ElementMatchSelection,
140
153
  element: TimelineElement,
141
154
  selectionSourceFile: string,
155
+ clipIdScope?: string,
142
156
  ): boolean {
143
157
  if (!selection.id) return false;
158
+ if (matchesByClipId(selection, element, selectionSourceFile, selection.id, clipIdScope))
159
+ return true;
144
160
  return (
145
161
  element.domId === selection.id && (element.sourceFile || "index.html") === selectionSourceFile
146
162
  );
@@ -150,8 +166,11 @@ function matchesByHfId(
150
166
  selection: ElementMatchSelection,
151
167
  element: TimelineElement,
152
168
  selectionSourceFile: string,
169
+ clipIdScope?: string,
153
170
  ): boolean {
154
171
  if (!selection.hfId) return false;
172
+ if (matchesByClipId(selection, element, selectionSourceFile, selection.hfId, clipIdScope))
173
+ return true;
155
174
  return (
156
175
  element.hfId === selection.hfId && (element.sourceFile || "index.html") === selectionSourceFile
157
176
  );
@@ -174,9 +193,11 @@ function matchesBySelector(selection: ElementMatchSelection, element: TimelineEl
174
193
  );
175
194
  }
176
195
 
196
+ /** `clipIdScope` matches opaque picks to clip-id-only rows, which have no patch target: select/seek only. */
177
197
  export function findMatchingTimelineElementId(
178
198
  selection: ElementMatchSelection,
179
199
  elements: TimelineElement[],
200
+ clipIdScope?: string,
180
201
  ): string | null {
181
202
  const selectionSourceFile = selection.sourceFile || "index.html";
182
203
  // Priority matters, not just "any of the three": a composition-host
@@ -191,7 +212,7 @@ export function findMatchingTimelineElementId(
191
212
  // first; only fall back to the coarser compositionSrc-only match when
192
213
  // none of them identifies a specific element.
193
214
  const byId = selection.id
194
- ? elements.find((el) => matchesByDomId(selection, el, selectionSourceFile))
215
+ ? elements.find((el) => matchesByDomId(selection, el, selectionSourceFile, clipIdScope))
195
216
  : undefined;
196
217
  if (byId) return byId.key ?? byId.id;
197
218
 
@@ -199,7 +220,7 @@ export function findMatchingTimelineElementId(
199
220
  // whether it has a real DOM id — the only correlator for an element like
200
221
  // an ungroup child that has neither an authored id nor a selector.
201
222
  const byHfId = selection.hfId
202
- ? elements.find((el) => matchesByHfId(selection, el, selectionSourceFile))
223
+ ? elements.find((el) => matchesByHfId(selection, el, selectionSourceFile, clipIdScope))
203
224
  : undefined;
204
225
  if (byHfId) return byHfId.key ?? byHfId.id;
205
226
 
@@ -267,9 +288,11 @@ export function resolveTimelineIdForSelection(
267
288
  selection: DomEditSelection,
268
289
  elements: TimelineElement[],
269
290
  activeCompPath: string | null,
291
+ byClipId = false,
270
292
  ): string | null {
293
+ const clipIdScope = byClipId ? activeCompPath || "index.html" : undefined;
271
294
  return (
272
- findMatchingTimelineElementId(selection, elements) ??
295
+ findMatchingTimelineElementId(selection, elements, clipIdScope) ??
273
296
  findTimelineIdByAncestor(
274
297
  selection.element,
275
298
  elements,
@@ -7,12 +7,46 @@ import {
7
7
  StudioFileConflictError,
8
8
  StudioSaveHttpError,
9
9
  StudioSaveNetworkError,
10
+ createStudioSaveHttpError,
10
11
  buildStudioSaveFailureProperties,
11
12
  getStudioSaveStatusCode,
12
13
  retryStudioSave,
13
14
  trackStudioEditBlocked,
14
15
  } from "./studioSaveDiagnostics";
15
16
 
17
+ describe("a file the server says is held or protected", () => {
18
+ // fails without the fix: the person read 'Failed to read ... (423): {"error":"file in use",...}' or no status at all.
19
+ it.each([
20
+ [423, "busy", "index.html is open in another program. Close it there, then try again."],
21
+ [
22
+ 403,
23
+ "permission",
24
+ "index.html can't be changed: it is read-only or protected. Check its permissions, then try again.",
25
+ ],
26
+ ])("tells a %i %s in words naming the file, not the folder", async (status, why, words) => {
27
+ const response = new Response(JSON.stringify({ error: "x", why }), { status });
28
+ const error = await createStudioSaveHttpError(response, "Failed to save a/b/index.html", {
29
+ path: "a/b/index.html",
30
+ });
31
+ expect(error.message).toBe(words);
32
+ expect(error.statusCode).toBe(status);
33
+ });
34
+
35
+ it("keeps the status and body for any other answer, and without a path", async () => {
36
+ const other = await createStudioSaveHttpError(
37
+ new Response("boom", { status: 500 }),
38
+ "Failed to save index.html",
39
+ { path: "index.html" },
40
+ );
41
+ expect(other.message).toBe("Failed to save index.html (500): boom");
42
+ const noPath = await createStudioSaveHttpError(
43
+ new Response(JSON.stringify({ why: "busy" }), { status: 423 }),
44
+ "Failed to save index.html",
45
+ );
46
+ expect(noPath.message).toMatch(/^Failed to save index.html \(423\)/);
47
+ });
48
+ });
49
+
16
50
  describe("studio save diagnostics", () => {
17
51
  it("preserves conflict versions and both sides for explicit recovery UI", () => {
18
52
  const error = new StudioFileConflictError({
@@ -19,12 +19,18 @@ export interface StudioSaveFailureInput {
19
19
  export class StudioSaveHttpError extends Error {
20
20
  readonly statusCode: number;
21
21
  readonly alreadyToasted: boolean;
22
+ readonly heldFile: boolean;
22
23
 
23
- constructor(message: string, statusCode: number, options: { alreadyToasted?: boolean } = {}) {
24
+ constructor(
25
+ message: string,
26
+ statusCode: number,
27
+ options: { alreadyToasted?: boolean; heldFile?: boolean } = {},
28
+ ) {
24
29
  super(message);
25
30
  this.name = "StudioSaveHttpError";
26
31
  this.statusCode = statusCode;
27
32
  this.alreadyToasted = options.alreadyToasted ?? false;
33
+ this.heldFile = options.heldFile ?? false;
28
34
  }
29
35
  }
30
36
 
@@ -188,10 +194,27 @@ export function trackStudioEditBlocked(input: StudioSaveFailureInput): void {
188
194
  trackStudioEvent("edit_blocked", buildStudioSaveFailureProperties(input));
189
195
  }
190
196
 
197
+ const HELD_FILE_WORDS = {
198
+ busy: (file: string) => `${file} is open in another program. Close it there, then try again.`,
199
+ permission: (file: string) =>
200
+ `${file} can't be changed: it is read-only or protected. Check its permissions, then try again.`,
201
+ } as const;
202
+
203
+ function heldFileMessage(body: string, path: string | undefined): string | null {
204
+ if (!path) return null;
205
+ try {
206
+ const why: unknown = (JSON.parse(body) as { why?: unknown }).why;
207
+ if (why !== "busy" && why !== "permission") return null;
208
+ return HELD_FILE_WORDS[why](path.split(/[\\/]/).pop() ?? path);
209
+ } catch {
210
+ return null;
211
+ }
212
+ }
213
+
191
214
  export async function createStudioSaveHttpError(
192
215
  response: Response,
193
216
  fallbackMessage: string,
194
- options: { alreadyToasted?: boolean } = {},
217
+ options: { alreadyToasted?: boolean; path?: string } = {},
195
218
  ): Promise<StudioSaveHttpError> {
196
219
  let body = "";
197
220
  try {
@@ -200,12 +223,18 @@ export async function createStudioSaveHttpError(
200
223
  body = "";
201
224
  }
202
225
  const detail = body.trim().slice(0, 300);
203
- const message = detail
204
- ? `${fallbackMessage} (${response.status}): ${detail}`
205
- : `${fallbackMessage} (${response.status})`;
206
- return new StudioSaveHttpError(message, response.status, options);
226
+ const held = heldFileMessage(body, options.path);
227
+ const message =
228
+ held ??
229
+ (detail
230
+ ? `${fallbackMessage} (${response.status}): ${detail}`
231
+ : `${fallbackMessage} (${response.status})`);
232
+ return new StudioSaveHttpError(message, response.status, { ...options, heldFile: held !== null });
207
233
  }
208
234
 
235
+ export const heldFileWords = (error: unknown): string | null =>
236
+ error instanceof StudioSaveHttpError && error.heldFile ? error.message : null;
237
+
209
238
  export async function retryStudioSave<T>(
210
239
  operation: (attempt: number) => Promise<T>,
211
240
  options: {
@@ -25,7 +25,9 @@ async function insertTimelineComposition(input: {
25
25
  buildProjectApiPath(input.projectId, `/files/${encodeURIComponent(input.targetPath)}`),
26
26
  );
27
27
  if (!current.ok) {
28
- throw await createStudioSaveHttpError(current, `Failed to read ${input.targetPath}`);
28
+ throw await createStudioSaveHttpError(current, `Failed to read ${input.targetPath}`, {
29
+ path: input.targetPath,
30
+ });
29
31
  }
30
32
  const snapshot = (await current.json()) as { version?: string };
31
33
  if (typeof snapshot.version !== "string") throw new Error("Missing composition file version");