@morshoto/framekit 0.1.10 → 0.1.12
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.
- package/README.md +1 -0
- package/dist-package/adapters/final-cut/typescript/src/analyzers.js +68 -5
- package/dist-package/adapters/final-cut/typescript/src/background-materialization.js +175 -0
- package/dist-package/adapters/final-cut/typescript/src/canonical-recovery.js +31 -0
- package/dist-package/adapters/final-cut/typescript/src/canonical-verification.js +16 -0
- package/dist-package/adapters/final-cut/typescript/src/canonical.js +600 -56
- package/dist-package/adapters/final-cut/typescript/src/connection.js +52 -14
- package/dist-package/adapters/final-cut/typescript/src/fcpxml-console-experiment.js +74 -0
- package/dist-package/adapters/final-cut/typescript/src/index.js +9 -0
- package/dist-package/adapters/final-cut/typescript/src/live.js +11 -4
- package/dist-package/adapters/final-cut/typescript/src/native.js +321 -19
- package/dist-package/adapters/final-cut/typescript/src/session.js +19 -1
- package/dist-package/adapters/final-cut/typescript/src/shadow-mutation.js +174 -0
- package/dist-package/adapters/final-cut/typescript/src/sqlite-experiment.js +472 -0
- package/dist-package/adapters/final-cut/typescript/src/sqlite-inspection.js +433 -0
- package/dist-package/adapters/final-cut/typescript/src/sqlite-materialization.js +230 -0
- package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +372 -0
- package/dist-package/adapters/final-cut/typescript/src/unattended-editing.js +66 -0
- package/dist-package/apps/mcp-server/src/headless-sessions.js +112 -0
- package/dist-package/apps/mcp-server/src/main.js +36 -2
- package/dist-package/apps/mcp-server/src/materialization-jobs.js +326 -0
- package/dist-package/apps/mcp-server/src/routing.js +17 -0
- package/dist-package/apps/mcp-server/src/server.js +146 -12
- package/dist-package/packages/runtime/src/application/media-analysis-service.js +52 -6
- package/dist-package/packages/runtime/src/context/project-catalog.js +46 -1
- package/dist-package/packages/runtime/src/index.js +2 -0
- package/dist-package/packages/runtime/src/skills/builtin.js +99 -8
- package/dist-package/packages/runtime/src/skills/runtime.js +1 -0
- package/dist-package/packages/runtime/src/timeline/drift-reconciliation.js +295 -0
- package/dist-package/packages/runtime/src/timeline/editing-session.js +490 -0
- package/package.json +10 -6
|
@@ -52,6 +52,24 @@ export class NativeFinalCutMediaImportDirectoryError extends Error {
|
|
|
52
52
|
}
|
|
53
53
|
}
|
|
54
54
|
export const SUPPORTED_VIDEO_EXTENSIONS = Object.freeze([".m4v", ".mov", ".mp4"]);
|
|
55
|
+
export class NativeFinalCutPartialMutationError extends Error {
|
|
56
|
+
details;
|
|
57
|
+
code = "FINAL_CUT_NATIVE_PARTIAL_MUTATION";
|
|
58
|
+
constructor(details) {
|
|
59
|
+
super(`FINAL_CUT_NATIVE_PARTIAL_MUTATION: ${details.cause.message}; operationId=${details.operationId}; mutationApplied=true; safeToRetry=false; recoveryHandle=${details.recoveryHandle}`);
|
|
60
|
+
this.details = details;
|
|
61
|
+
this.name = "NativeFinalCutPartialMutationError";
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
export function serializeNativeFinalCutPartialMutationError(error) {
|
|
65
|
+
if (!(error instanceof NativeFinalCutPartialMutationError))
|
|
66
|
+
return undefined;
|
|
67
|
+
return {
|
|
68
|
+
code: error.code,
|
|
69
|
+
message: error.message,
|
|
70
|
+
details: error.details,
|
|
71
|
+
};
|
|
72
|
+
}
|
|
55
73
|
export class FinalCutNativeAutomationAdapter {
|
|
56
74
|
enabled;
|
|
57
75
|
titleDiscoveryAvailable;
|
|
@@ -193,12 +211,73 @@ export class FinalCutNativeAutomationAdapter {
|
|
|
193
211
|
}
|
|
194
212
|
}
|
|
195
213
|
rememberOperation(operationId, record) {
|
|
214
|
+
record.rollbackEvidence ??= nativeRollbackEvidence(record);
|
|
196
215
|
this.operations.set(operationId, record);
|
|
197
216
|
this.latestOperationId = operationId;
|
|
198
217
|
}
|
|
199
218
|
async edit(operation, options = {}) {
|
|
200
219
|
return this.withNativeUi(() => this.editNative(operation), options.signal);
|
|
201
220
|
}
|
|
221
|
+
async trimSelectedClipToRange(range, options = {}) {
|
|
222
|
+
return this.withNativeUi(() => this.trimSelectedClipToRangeNative(range), options.signal);
|
|
223
|
+
}
|
|
224
|
+
async trimSelectedClipToRangeNative(range) {
|
|
225
|
+
this.assertEnabled();
|
|
226
|
+
const live = await this.requireLiveState();
|
|
227
|
+
const sequenceStart = live.sequenceTimeRange?.start ?? live.sequence?.startTime;
|
|
228
|
+
const sequenceDuration = live.sequenceTimeRange?.duration ?? live.sequence?.duration;
|
|
229
|
+
const frameDuration = live.sequence?.frameDuration;
|
|
230
|
+
if (!sequenceStart || !sequenceDuration || !frameDuration) {
|
|
231
|
+
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut sequence frame rate and duration are unavailable");
|
|
232
|
+
}
|
|
233
|
+
const duration = subtractRational(range.end, range.start);
|
|
234
|
+
const sequenceEnd = addRational(sequenceStart, sequenceDuration);
|
|
235
|
+
if (compareRational(duration, zeroRational()) <= 0) {
|
|
236
|
+
throw new Error("INVALID_OPERATION: canonical trim range must have start before end");
|
|
237
|
+
}
|
|
238
|
+
if (compareRational(range.start, sequenceStart) < 0 || compareRational(range.end, sequenceEnd) > 0) {
|
|
239
|
+
throw new Error("FINAL_CUT_NATIVE_RANGE_OUT_OF_BOUNDS: canonical trim range must be inside the active sequence");
|
|
240
|
+
}
|
|
241
|
+
if (!isFrameAligned(range.start, sequenceStart, frameDuration) || !isFrameAligned(range.end, sequenceStart, frameDuration)) {
|
|
242
|
+
throw new Error("INVALID_OPERATION: canonical trim range must be frame-aligned");
|
|
243
|
+
}
|
|
244
|
+
await this.requireTimelineTarget({ type: "trim-selected-clip-to-playhead", edge: "end" });
|
|
245
|
+
if (!live.sequence?.id)
|
|
246
|
+
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut sequence identity is unavailable");
|
|
247
|
+
await this.executeNativeScript(setPlayheadScript(this.toTimecode(range.end, live)));
|
|
248
|
+
await this.waitForPlayhead(range.end, live.sequence.id);
|
|
249
|
+
return this.editNative({ type: "trim-selected-clip-to-playhead", edge: "end" });
|
|
250
|
+
}
|
|
251
|
+
async addMarkerAtTime(marker, options = {}) {
|
|
252
|
+
return this.withNativeUi(async () => {
|
|
253
|
+
this.assertEnabled();
|
|
254
|
+
const live = await this.requireLiveState();
|
|
255
|
+
const sequenceStart = live.sequenceTimeRange?.start ?? live.sequence?.startTime;
|
|
256
|
+
const sequenceDuration = live.sequenceTimeRange?.duration ?? live.sequence?.duration;
|
|
257
|
+
const frameDuration = live.sequence?.frameDuration;
|
|
258
|
+
if (!sequenceStart || !sequenceDuration || !frameDuration) {
|
|
259
|
+
throw new Error("CAPABILITY_UNAVAILABLE: Final Cut sequence timing is unavailable");
|
|
260
|
+
}
|
|
261
|
+
validateNativeMarkerRange(marker, sequenceStart, sequenceDuration, frameDuration);
|
|
262
|
+
await this.requireNativeWriteContext();
|
|
263
|
+
const startTimecode = this.toTimecode(marker.start, live);
|
|
264
|
+
await this.executeNativeScript(setPlayheadScript(startTimecode));
|
|
265
|
+
await this.waitForPlayhead(marker.start, live.sequence?.id);
|
|
266
|
+
if (compareRational(marker.duration, zeroRational()) > 0) {
|
|
267
|
+
const end = addRational(marker.start, marker.duration);
|
|
268
|
+
const endTimecode = this.toTimecode(end, live);
|
|
269
|
+
await this.executeNativeScript(markRangeStartScript());
|
|
270
|
+
await this.executeNativeScript(setPlayheadScript(endTimecode));
|
|
271
|
+
await this.waitForPlayhead(end, live.sequence?.id);
|
|
272
|
+
await this.executeNativeScript(markRangeEndScript());
|
|
273
|
+
}
|
|
274
|
+
return this.editNative({
|
|
275
|
+
type: "add-marker-at-playhead",
|
|
276
|
+
name: marker.name,
|
|
277
|
+
duration: rationalSeconds(marker.duration),
|
|
278
|
+
});
|
|
279
|
+
}, options.signal);
|
|
280
|
+
}
|
|
202
281
|
async editNative(operation) {
|
|
203
282
|
this.assertEnabled();
|
|
204
283
|
const before = await this.requireTimelineTarget(operation);
|
|
@@ -215,10 +294,36 @@ export class FinalCutNativeAutomationAdapter {
|
|
|
215
294
|
const after = await this.requireTimelineContext();
|
|
216
295
|
const afterLive = await this.readLiveState();
|
|
217
296
|
const verification = verifyNativeEdit(operation, before, after);
|
|
297
|
+
const operationRecord = {
|
|
298
|
+
kind: "selection",
|
|
299
|
+
before,
|
|
300
|
+
after,
|
|
301
|
+
beforeLive,
|
|
302
|
+
afterLive,
|
|
303
|
+
undoCommand: after.undoCommand,
|
|
304
|
+
};
|
|
218
305
|
if (!verification.verified) {
|
|
306
|
+
const evidence = nativeRollbackEvidence(operationRecord);
|
|
307
|
+
if (evidence.mutationObserved) {
|
|
308
|
+
this.rememberOperation(operationId, operationRecord);
|
|
309
|
+
throw new NativeFinalCutPartialMutationError({
|
|
310
|
+
operationId,
|
|
311
|
+
recoveryHandle: operationId,
|
|
312
|
+
operation: command,
|
|
313
|
+
mutationApplied: true,
|
|
314
|
+
safeToRetry: false,
|
|
315
|
+
recovery: { tool: "editor.native.undo", operationId },
|
|
316
|
+
evidence,
|
|
317
|
+
cause: {
|
|
318
|
+
code: "FINAL_CUT_NATIVE_VERIFICATION_FAILED",
|
|
319
|
+
message: verification.detail,
|
|
320
|
+
},
|
|
321
|
+
});
|
|
322
|
+
}
|
|
219
323
|
throw new Error(`FINAL_CUT_NATIVE_VERIFICATION_FAILED: ${verification.detail}`);
|
|
220
324
|
}
|
|
221
|
-
this.rememberOperation(operationId,
|
|
325
|
+
this.rememberOperation(operationId, operationRecord);
|
|
326
|
+
this.assertNativeRollbackReady(operationId, command, operationRecord);
|
|
222
327
|
return { operationId, operation, command, before, after, verification, undoAvailable: after.undoAvailable, ...(after.undoCommand ? { undoCommand: after.undoCommand } : {}) };
|
|
223
328
|
}
|
|
224
329
|
async undo(operationId, options = {}) {
|
|
@@ -238,7 +343,17 @@ export class FinalCutNativeAutomationAdapter {
|
|
|
238
343
|
}
|
|
239
344
|
if (!before.undoAvailable || !before.undoCommand)
|
|
240
345
|
throw new Error("FINAL_CUT_NATIVE_UNDO_UNAVAILABLE: Final Cut has no available Undo command");
|
|
241
|
-
if (
|
|
346
|
+
if ((operation.before.undoAvailable || operation.before.undoCommand)
|
|
347
|
+
&& (!operation.before.undoCommand || operation.undoCommand === operation.before.undoCommand)) {
|
|
348
|
+
throw new Error("FINAL_CUT_NATIVE_UNDO_UNBOUND: operation does not have an Undo command distinct from pre-existing Final Cut history");
|
|
349
|
+
}
|
|
350
|
+
if (!operation.undoCommand) {
|
|
351
|
+
if (operation.before.undoAvailable || operation.before.undoCommand) {
|
|
352
|
+
throw new Error("FINAL_CUT_NATIVE_UNDO_UNBOUND: operation does not have an Undo command distinct from pre-existing Final Cut history");
|
|
353
|
+
}
|
|
354
|
+
operation.undoCommand = before.undoCommand;
|
|
355
|
+
}
|
|
356
|
+
if (before.undoCommand !== operation.undoCommand) {
|
|
242
357
|
throw new Error("FINAL_CUT_NATIVE_UNDO_COMMAND_CHANGED: Final Cut's current Undo command does not match the native edit");
|
|
243
358
|
}
|
|
244
359
|
try {
|
|
@@ -838,6 +953,7 @@ export class FinalCutNativeAutomationAdapter {
|
|
|
838
953
|
undoCommand: observedAfter.undoCommand,
|
|
839
954
|
};
|
|
840
955
|
this.rememberOperation(operationId, operation);
|
|
956
|
+
this.assertNativeRollbackReady(operationId, "Mask", operation);
|
|
841
957
|
return {
|
|
842
958
|
operationId,
|
|
843
959
|
previewToken,
|
|
@@ -854,6 +970,8 @@ export class FinalCutNativeAutomationAdapter {
|
|
|
854
970
|
};
|
|
855
971
|
}
|
|
856
972
|
catch (error) {
|
|
973
|
+
if (error instanceof NativeFinalCutPartialMutationError)
|
|
974
|
+
throw error;
|
|
857
975
|
const rollback = await this.rollbackFailedMask(before, beforeLive, previewToken, error, observedAfter, observedLive);
|
|
858
976
|
const failure = `${nativeErrorCode(error)}: ${String(error)}`;
|
|
859
977
|
if (rollback.rolledBack)
|
|
@@ -907,6 +1025,7 @@ export class FinalCutNativeAutomationAdapter {
|
|
|
907
1025
|
if (this.now() > preview.expiresAt)
|
|
908
1026
|
throw new Error("FINAL_CUT_NATIVE_PREVIEW_STALE: Blade preview has expired");
|
|
909
1027
|
const before = await this.requireNativeWriteContext();
|
|
1028
|
+
const beforeLive = await this.readLiveState();
|
|
910
1029
|
if (!before.frontmost)
|
|
911
1030
|
throw new Error("FINAL_CUT_NATIVE_NOT_FRONTMOST: Final Cut's timeline must be frontmost");
|
|
912
1031
|
if (before.target.kind !== "selected-clip")
|
|
@@ -938,7 +1057,16 @@ export class FinalCutNativeAutomationAdapter {
|
|
|
938
1057
|
throw new Error("FINAL_CUT_NATIVE_VERIFICATION_FAILED: Final Cut did not expose two resulting timeline segments after Blade");
|
|
939
1058
|
}
|
|
940
1059
|
const operationId = opaqueHandle("native-blade");
|
|
941
|
-
|
|
1060
|
+
const operation = {
|
|
1061
|
+
kind: "blade",
|
|
1062
|
+
before,
|
|
1063
|
+
after,
|
|
1064
|
+
beforeLive,
|
|
1065
|
+
afterLive,
|
|
1066
|
+
undoCommand: after.undoCommand,
|
|
1067
|
+
};
|
|
1068
|
+
this.rememberOperation(operationId, operation);
|
|
1069
|
+
this.assertNativeRollbackReady(operationId, "Blade", operation);
|
|
942
1070
|
return {
|
|
943
1071
|
operationId,
|
|
944
1072
|
previewToken,
|
|
@@ -971,11 +1099,11 @@ export class FinalCutNativeAutomationAdapter {
|
|
|
971
1099
|
if (compareRational(duration, zeroRational()) <= 0)
|
|
972
1100
|
throw new Error("INVALID_OPERATION: target duration must be positive");
|
|
973
1101
|
if (compareRational(duration, currentDuration) >= 0) {
|
|
974
|
-
const token = this.createRangePreview("trim-to-duration", { start: sequenceStart, end: sequenceStart }, currentDuration, currentDuration, live);
|
|
1102
|
+
const token = this.createRangePreview("trim-to-duration", { start: sequenceStart, end: sequenceStart }, currentDuration, currentDuration, live, undefined, context.target.identity);
|
|
975
1103
|
return { ...token, command: "Trim sequence to duration" };
|
|
976
1104
|
}
|
|
977
1105
|
const range = { start: addRational(sequenceStart, duration), end: addRational(sequenceStart, currentDuration) };
|
|
978
|
-
return this.createRangePreview("trim-to-duration", range, currentDuration, duration, live, duration);
|
|
1106
|
+
return this.createRangePreview("trim-to-duration", range, currentDuration, duration, live, duration, context.target.identity);
|
|
979
1107
|
}, options.signal);
|
|
980
1108
|
}
|
|
981
1109
|
async executeTrimToDuration(previewToken, options = {}) {
|
|
@@ -1212,6 +1340,7 @@ export class FinalCutNativeAutomationAdapter {
|
|
|
1212
1340
|
throw new Error(`FINAL_CUT_NATIVE_VERIFICATION_FAILED: ${verification.detail}`);
|
|
1213
1341
|
}
|
|
1214
1342
|
this.rememberOperation(operationId, operation);
|
|
1343
|
+
this.assertNativeRollbackReady(operationId, "Transition", operation);
|
|
1215
1344
|
return {
|
|
1216
1345
|
operationId,
|
|
1217
1346
|
previewToken,
|
|
@@ -1353,6 +1482,7 @@ export class FinalCutNativeAutomationAdapter {
|
|
|
1353
1482
|
throw new Error(`FINAL_CUT_NATIVE_VERIFICATION_FAILED: ${verification.detail}`);
|
|
1354
1483
|
}
|
|
1355
1484
|
this.rememberOperation(operationId, operation);
|
|
1485
|
+
this.assertNativeRollbackReady(operationId, "Title", operation);
|
|
1356
1486
|
return {
|
|
1357
1487
|
operationId,
|
|
1358
1488
|
previewToken,
|
|
@@ -1528,6 +1658,7 @@ export class FinalCutNativeAutomationAdapter {
|
|
|
1528
1658
|
throw new Error(`FINAL_CUT_NATIVE_VERIFICATION_FAILED: ${verification.detail}`);
|
|
1529
1659
|
}
|
|
1530
1660
|
this.rememberOperation(operationId, operation);
|
|
1661
|
+
this.assertNativeRollbackReady(operationId, "Picture-in-picture", operation);
|
|
1531
1662
|
return {
|
|
1532
1663
|
operationId,
|
|
1533
1664
|
previewToken,
|
|
@@ -1552,6 +1683,8 @@ export class FinalCutNativeAutomationAdapter {
|
|
|
1552
1683
|
};
|
|
1553
1684
|
}
|
|
1554
1685
|
catch (error) {
|
|
1686
|
+
if (error instanceof NativeFinalCutPartialMutationError)
|
|
1687
|
+
throw error;
|
|
1555
1688
|
const observedContext = after ?? await this.inspectRawNative();
|
|
1556
1689
|
const observedLive = afterLive ?? await this.readLiveState();
|
|
1557
1690
|
if (observedLive && observedLive.revision.id !== beforeLive.revision.id && observedContext.undoCommand) {
|
|
@@ -1719,6 +1852,7 @@ export class FinalCutNativeAutomationAdapter {
|
|
|
1719
1852
|
throw new Error(`FINAL_CUT_NATIVE_VERIFICATION_FAILED: ${verification.detail}`);
|
|
1720
1853
|
}
|
|
1721
1854
|
this.rememberOperation(operationId, operation);
|
|
1855
|
+
this.assertNativeRollbackReady(operationId, `${preview.operation} media insertion`, operation);
|
|
1722
1856
|
return {
|
|
1723
1857
|
operationId,
|
|
1724
1858
|
previewToken,
|
|
@@ -1777,9 +1911,9 @@ export class FinalCutNativeAutomationAdapter {
|
|
|
1777
1911
|
throw new Error("FINAL_CUT_NATIVE_RANGE_OUT_OF_BOUNDS: delete range must be inside the active sequence");
|
|
1778
1912
|
}
|
|
1779
1913
|
const expectedAfterDuration = subtractRational(currentDuration, duration);
|
|
1780
|
-
return this.createRangePreview(operation, range, currentDuration, expectedAfterDuration, live);
|
|
1914
|
+
return this.createRangePreview(operation, range, currentDuration, expectedAfterDuration, live, undefined, context.target.identity);
|
|
1781
1915
|
}
|
|
1782
|
-
createRangePreview(operation, range, beforeDuration, expectedAfterDuration, live, targetDuration) {
|
|
1916
|
+
createRangePreview(operation, range, beforeDuration, expectedAfterDuration, live, targetDuration, targetIdentity) {
|
|
1783
1917
|
const expiresAt = this.now() + 30_000;
|
|
1784
1918
|
const previewToken = opaqueHandle(`${operation}-preview`);
|
|
1785
1919
|
this.rangePreviews.set(previewToken, {
|
|
@@ -1789,6 +1923,7 @@ export class FinalCutNativeAutomationAdapter {
|
|
|
1789
1923
|
expectedAfterDuration,
|
|
1790
1924
|
sequenceId: live.sequence?.id,
|
|
1791
1925
|
revision: live.revision.id,
|
|
1926
|
+
...(targetIdentity ? { targetIdentity } : {}),
|
|
1792
1927
|
expiresAt,
|
|
1793
1928
|
});
|
|
1794
1929
|
return {
|
|
@@ -1799,6 +1934,7 @@ export class FinalCutNativeAutomationAdapter {
|
|
|
1799
1934
|
expectedAfterDuration: targetDuration ?? expectedAfterDuration,
|
|
1800
1935
|
...(live.sequence?.id ? { sequenceId: live.sequence.id } : {}),
|
|
1801
1936
|
revision: live.revision.id,
|
|
1937
|
+
...(targetIdentity ? { targetIdentity } : {}),
|
|
1802
1938
|
command: operation === "delete-range" ? "Delete primary storyline range" : "Trim sequence to duration",
|
|
1803
1939
|
expiresAt: new Date(expiresAt).toISOString(),
|
|
1804
1940
|
};
|
|
@@ -1815,7 +1951,7 @@ export class FinalCutNativeAutomationAdapter {
|
|
|
1815
1951
|
throw new Error("FINAL_CUT_NATIVE_PREVIEW_STALE: preview operation does not match execute operation");
|
|
1816
1952
|
const before = await this.requireNativeWriteContext();
|
|
1817
1953
|
const beforeLive = await this.requireLiveState();
|
|
1818
|
-
this.validateRangeBinding(preview, beforeLive);
|
|
1954
|
+
this.validateRangeBinding(preview, beforeLive, before);
|
|
1819
1955
|
const rangeDuration = subtractRational(preview.range.end, preview.range.start);
|
|
1820
1956
|
if (compareRational(rangeDuration, zeroRational()) === 0) {
|
|
1821
1957
|
return {
|
|
@@ -1828,6 +1964,8 @@ export class FinalCutNativeAutomationAdapter {
|
|
|
1828
1964
|
beforeDuration: preview.beforeDuration,
|
|
1829
1965
|
afterDuration: preview.beforeDuration,
|
|
1830
1966
|
expectedAfterDuration: preview.expectedAfterDuration,
|
|
1967
|
+
beforeRevision: beforeLive.revision,
|
|
1968
|
+
afterRevision: beforeLive.revision,
|
|
1831
1969
|
verification: { verified: true, detail: "Requested duration is already at or below the active sequence duration" },
|
|
1832
1970
|
undoAvailable: false,
|
|
1833
1971
|
};
|
|
@@ -1846,7 +1984,7 @@ export class FinalCutNativeAutomationAdapter {
|
|
|
1846
1984
|
if (!detail.verified)
|
|
1847
1985
|
throw new Error(`FINAL_CUT_NATIVE_VERIFICATION_FAILED: ${detail.detail}`);
|
|
1848
1986
|
const operationId = opaqueHandle(`native-${preview.operation}`);
|
|
1849
|
-
|
|
1987
|
+
const operation = {
|
|
1850
1988
|
kind: "range",
|
|
1851
1989
|
before,
|
|
1852
1990
|
after,
|
|
@@ -1854,7 +1992,9 @@ export class FinalCutNativeAutomationAdapter {
|
|
|
1854
1992
|
afterLive,
|
|
1855
1993
|
beforeDuration: preview.beforeDuration,
|
|
1856
1994
|
undoCommand: after.undoCommand,
|
|
1857
|
-
}
|
|
1995
|
+
};
|
|
1996
|
+
this.rememberOperation(operationId, operation);
|
|
1997
|
+
this.assertNativeRollbackReady(operationId, preview.operation, operation);
|
|
1858
1998
|
return {
|
|
1859
1999
|
operationId,
|
|
1860
2000
|
previewToken,
|
|
@@ -1865,16 +2005,21 @@ export class FinalCutNativeAutomationAdapter {
|
|
|
1865
2005
|
beforeDuration: preview.beforeDuration,
|
|
1866
2006
|
afterDuration: afterLive.sequenceTimeRange?.duration ?? afterLive.sequence?.duration ?? preview.expectedAfterDuration,
|
|
1867
2007
|
expectedAfterDuration: preview.expectedAfterDuration,
|
|
2008
|
+
beforeRevision: beforeLive.revision,
|
|
2009
|
+
afterRevision: afterLive.revision,
|
|
1868
2010
|
verification: { verified: true, detail: detail.detail },
|
|
1869
2011
|
undoAvailable: after.undoAvailable,
|
|
1870
2012
|
...(after.undoCommand ? { undoCommand: after.undoCommand } : {}),
|
|
1871
2013
|
};
|
|
1872
2014
|
}
|
|
1873
|
-
validateRangeBinding(preview, live) {
|
|
2015
|
+
validateRangeBinding(preview, live, context) {
|
|
1874
2016
|
if (preview.sequenceId && live.sequence?.id !== preview.sequenceId)
|
|
1875
2017
|
throw new Error("FINAL_CUT_NATIVE_PREVIEW_STALE: active sequence changed");
|
|
1876
2018
|
if (preview.revision && live.revision.id !== preview.revision)
|
|
1877
2019
|
throw new Error("FINAL_CUT_NATIVE_PREVIEW_STALE: playhead or timeline revision changed");
|
|
2020
|
+
if (preview.targetIdentity && context && context.target.identity !== preview.targetIdentity) {
|
|
2021
|
+
throw new Error("FINAL_CUT_NATIVE_PREVIEW_STALE: native target changed");
|
|
2022
|
+
}
|
|
1878
2023
|
const currentDuration = live.sequenceTimeRange?.duration ?? live.sequence?.duration;
|
|
1879
2024
|
if (!currentDuration || compareRational(currentDuration, preview.beforeDuration) !== 0)
|
|
1880
2025
|
throw new Error("FINAL_CUT_NATIVE_PREVIEW_STALE: sequence duration changed");
|
|
@@ -2205,8 +2350,84 @@ export class FinalCutNativeAutomationAdapter {
|
|
|
2205
2350
|
if (!context.readiness.selectedTarget) {
|
|
2206
2351
|
throw new Error("FINAL_CUT_NATIVE_SELECTION_REQUIRED: position the playhead or select a timeline target in Final Cut Pro");
|
|
2207
2352
|
}
|
|
2208
|
-
|
|
2209
|
-
|
|
2353
|
+
}
|
|
2354
|
+
assertNativeRollbackReady(operationId, operation, record) {
|
|
2355
|
+
const evidence = record.rollbackEvidence ?? nativeRollbackEvidence(record);
|
|
2356
|
+
record.rollbackEvidence = evidence;
|
|
2357
|
+
if (!evidence.timelineScopeBound) {
|
|
2358
|
+
throw new NativeFinalCutPartialMutationError({
|
|
2359
|
+
operationId,
|
|
2360
|
+
recoveryHandle: operationId,
|
|
2361
|
+
operation,
|
|
2362
|
+
mutationApplied: true,
|
|
2363
|
+
safeToRetry: false,
|
|
2364
|
+
recovery: { tool: "editor.native.undo", operationId },
|
|
2365
|
+
evidence,
|
|
2366
|
+
cause: {
|
|
2367
|
+
code: "FINAL_CUT_NATIVE_TARGET_CHANGED",
|
|
2368
|
+
message: `Final Cut project or sequence changed during ${operation}; the applied mutation requires recovery before retry`,
|
|
2369
|
+
},
|
|
2370
|
+
});
|
|
2371
|
+
}
|
|
2372
|
+
if (!evidence.mutationObserved) {
|
|
2373
|
+
throw new NativeFinalCutPartialMutationError({
|
|
2374
|
+
operationId,
|
|
2375
|
+
recoveryHandle: operationId,
|
|
2376
|
+
operation,
|
|
2377
|
+
mutationApplied: true,
|
|
2378
|
+
safeToRetry: false,
|
|
2379
|
+
recovery: { tool: "editor.native.undo", operationId },
|
|
2380
|
+
evidence,
|
|
2381
|
+
cause: {
|
|
2382
|
+
code: "FINAL_CUT_NATIVE_MUTATION_EVIDENCE_UNAVAILABLE",
|
|
2383
|
+
message: `Final Cut did not expose mutation-bound revision, target, or Undo evidence after ${operation}`,
|
|
2384
|
+
},
|
|
2385
|
+
});
|
|
2386
|
+
}
|
|
2387
|
+
if (!evidence.targetBound) {
|
|
2388
|
+
throw new NativeFinalCutPartialMutationError({
|
|
2389
|
+
operationId,
|
|
2390
|
+
recoveryHandle: operationId,
|
|
2391
|
+
operation,
|
|
2392
|
+
mutationApplied: true,
|
|
2393
|
+
safeToRetry: false,
|
|
2394
|
+
recovery: { tool: "editor.native.undo", operationId },
|
|
2395
|
+
evidence,
|
|
2396
|
+
cause: {
|
|
2397
|
+
code: "FINAL_CUT_NATIVE_TARGET_BINDING_UNAVAILABLE",
|
|
2398
|
+
message: `Final Cut did not preserve the native target binding after ${operation}; the applied mutation requires recovery before retry`,
|
|
2399
|
+
},
|
|
2400
|
+
});
|
|
2401
|
+
}
|
|
2402
|
+
if (!record.after.undoAvailable || !record.after.undoCommand) {
|
|
2403
|
+
throw new NativeFinalCutPartialMutationError({
|
|
2404
|
+
operationId,
|
|
2405
|
+
recoveryHandle: operationId,
|
|
2406
|
+
operation,
|
|
2407
|
+
mutationApplied: true,
|
|
2408
|
+
safeToRetry: false,
|
|
2409
|
+
recovery: { tool: "editor.native.undo", operationId },
|
|
2410
|
+
evidence,
|
|
2411
|
+
cause: {
|
|
2412
|
+
code: "FINAL_CUT_NATIVE_UNDO_UNAVAILABLE",
|
|
2413
|
+
message: `Final Cut did not expose operation-specific Undo after ${operation}; the applied mutation requires recovery before retry`,
|
|
2414
|
+
},
|
|
2415
|
+
});
|
|
2416
|
+
}
|
|
2417
|
+
if ((record.before.undoAvailable || record.before.undoCommand) && (!record.before.undoCommand || record.after.undoCommand === record.before.undoCommand)) {
|
|
2418
|
+
throw new NativeFinalCutPartialMutationError({
|
|
2419
|
+
operationId,
|
|
2420
|
+
recoveryHandle: operationId,
|
|
2421
|
+
operation,
|
|
2422
|
+
mutationApplied: true,
|
|
2423
|
+
safeToRetry: false,
|
|
2424
|
+
recovery: { tool: "editor.native.undo", operationId },
|
|
2425
|
+
evidence,
|
|
2426
|
+
cause: {
|
|
2427
|
+
code: "FINAL_CUT_NATIVE_UNDO_UNBOUND",
|
|
2428
|
+
message: `Final Cut's post-mutation Undo command was not distinguishable from pre-existing history after ${operation}; the applied mutation requires recovery before retry`,
|
|
2429
|
+
},
|
|
2430
|
+
});
|
|
2210
2431
|
}
|
|
2211
2432
|
}
|
|
2212
2433
|
async requireTimelineContext() {
|
|
@@ -2403,6 +2624,57 @@ export class FinalCutNativeAutomationAdapter {
|
|
|
2403
2624
|
}
|
|
2404
2625
|
}
|
|
2405
2626
|
}
|
|
2627
|
+
function nativeRollbackEvidence(record) {
|
|
2628
|
+
const beforeRevision = record.beforeLive?.revision.id;
|
|
2629
|
+
const afterRevision = record.afterLive?.revision.id;
|
|
2630
|
+
const revisionAdvanced = Boolean(beforeRevision && afterRevision && beforeRevision !== afterRevision);
|
|
2631
|
+
const timelineScopeBound = !record.beforeLive || !record.afterLive
|
|
2632
|
+
|| Boolean(record.beforeLive.project?.id
|
|
2633
|
+
&& record.afterLive.project?.id
|
|
2634
|
+
&& record.beforeLive.project.id === record.afterLive.project.id
|
|
2635
|
+
&& record.beforeLive.sequence?.id
|
|
2636
|
+
&& record.afterLive.sequence?.id
|
|
2637
|
+
&& record.beforeLive.sequence.id === record.afterLive.sequence.id);
|
|
2638
|
+
const beforeTargetIdentity = record.before.target.identity;
|
|
2639
|
+
const afterTargetIdentity = record.after.target.identity;
|
|
2640
|
+
const sameTargetBound = record.before.target.kind === record.after.target.kind
|
|
2641
|
+
&& (beforeTargetIdentity && afterTargetIdentity
|
|
2642
|
+
? beforeTargetIdentity === afterTargetIdentity
|
|
2643
|
+
: !beforeTargetIdentity && !afterTargetIdentity
|
|
2644
|
+
&& record.before.target.kind !== "selected-clip"
|
|
2645
|
+
&& (record.before.target.kind === "playhead" || record.before.target.name === record.after.target.name));
|
|
2646
|
+
const insertedTargetBound = (record.kind === "title-placement"
|
|
2647
|
+
|| record.kind === "picture-in-picture"
|
|
2648
|
+
|| record.kind === "transition-placement")
|
|
2649
|
+
&& (record.before.target.kind === "playhead" || record.before.target.kind === "selected-clip")
|
|
2650
|
+
&& record.after.target.kind === "selected-clip"
|
|
2651
|
+
&& Boolean(afterTargetIdentity);
|
|
2652
|
+
const targetBound = sameTargetBound || insertedTargetBound;
|
|
2653
|
+
const undoCommandChanged = record.before.undoCommand !== record.after.undoCommand;
|
|
2654
|
+
const beforeDuration = record.beforeDuration;
|
|
2655
|
+
const afterDuration = record.afterLive?.sequenceTimeRange?.duration ?? record.afterLive?.sequence?.duration;
|
|
2656
|
+
const durationChanged = Boolean(beforeDuration
|
|
2657
|
+
&& afterDuration
|
|
2658
|
+
&& compareRational(beforeDuration, afterDuration) !== 0);
|
|
2659
|
+
const targetChanged = record.before.target.name !== record.after.target.name;
|
|
2660
|
+
return {
|
|
2661
|
+
...(beforeRevision ? { beforeRevision } : {}),
|
|
2662
|
+
...(afterRevision ? { afterRevision } : {}),
|
|
2663
|
+
revisionAdvanced,
|
|
2664
|
+
...(record.beforeLive?.project?.id ? { projectId: record.beforeLive.project.id } : {}),
|
|
2665
|
+
...(record.beforeLive?.sequence?.id ? { sequenceId: record.beforeLive.sequence.id } : {}),
|
|
2666
|
+
timelineScopeBound,
|
|
2667
|
+
...(beforeTargetIdentity ? { beforeTargetIdentity } : {}),
|
|
2668
|
+
...(afterTargetIdentity ? { afterTargetIdentity } : {}),
|
|
2669
|
+
targetBound,
|
|
2670
|
+
...(record.before.undoCommand ? { beforeUndoCommand: record.before.undoCommand } : {}),
|
|
2671
|
+
...(record.after.undoCommand ? { afterUndoCommand: record.after.undoCommand } : {}),
|
|
2672
|
+
undoCommandChanged,
|
|
2673
|
+
mutationObserved: revisionAdvanced || undoCommandChanged || targetChanged || durationChanged,
|
|
2674
|
+
...(beforeDuration ? { beforeDuration: structuredClone(beforeDuration) } : {}),
|
|
2675
|
+
...(afterDuration ? { afterDuration: structuredClone(afterDuration) } : {}),
|
|
2676
|
+
};
|
|
2677
|
+
}
|
|
2406
2678
|
function verifyNativeUndo(operation, after, afterLive) {
|
|
2407
2679
|
if (operation.afterLive && (!afterLive || afterLive.revision.id === operation.afterLive.revision.id)) {
|
|
2408
2680
|
return { verified: false, detail: "Final Cut did not expose a new revision after Undo" };
|
|
@@ -2413,6 +2685,9 @@ function verifyNativeUndo(operation, after, afterLive) {
|
|
|
2413
2685
|
if (!detail.verified)
|
|
2414
2686
|
return detail;
|
|
2415
2687
|
}
|
|
2688
|
+
if (operation.before.target.identity && after.target.identity !== operation.before.target.identity) {
|
|
2689
|
+
return { verified: false, detail: "native target identity changed during Undo" };
|
|
2690
|
+
}
|
|
2416
2691
|
if (operation.kind === "selection" && operation.before.target.name !== after.target.name) {
|
|
2417
2692
|
return {
|
|
2418
2693
|
verified: false,
|
|
@@ -5288,6 +5563,16 @@ tell application "System Events"
|
|
|
5288
5563
|
end tell
|
|
5289
5564
|
end tell`;
|
|
5290
5565
|
}
|
|
5566
|
+
function markRangeEndScript() {
|
|
5567
|
+
return `
|
|
5568
|
+
tell application "System Events"
|
|
5569
|
+
tell process "Final Cut Pro"
|
|
5570
|
+
${requireFrontmostAppleScript()}
|
|
5571
|
+
keystroke "o"
|
|
5572
|
+
delay 0.2
|
|
5573
|
+
end tell
|
|
5574
|
+
end tell`;
|
|
5575
|
+
}
|
|
5291
5576
|
function markRangeEndAndDeleteScript() {
|
|
5292
5577
|
return `
|
|
5293
5578
|
tell application "System Events"
|
|
@@ -5596,6 +5881,10 @@ function parseRationalNumber(value) {
|
|
|
5596
5881
|
function zeroRational() {
|
|
5597
5882
|
return { value: "0", timescale: "1" };
|
|
5598
5883
|
}
|
|
5884
|
+
function rationalSeconds(value) {
|
|
5885
|
+
const [numerator, denominator] = rationalParts(value);
|
|
5886
|
+
return Number(numerator) / Number(denominator);
|
|
5887
|
+
}
|
|
5599
5888
|
function rationalParts(value) {
|
|
5600
5889
|
const numerator = BigInt(value.value);
|
|
5601
5890
|
const denominator = BigInt(value.timescale);
|
|
@@ -5693,7 +5982,7 @@ function mediaInsertionMutationObserved(before, after) {
|
|
|
5693
5982
|
function readinessForContext(context) {
|
|
5694
5983
|
const selectedTarget = context.target.kind !== "none" && context.target.kind !== "unknown";
|
|
5695
5984
|
const state = context.error?.state
|
|
5696
|
-
?? (context.available && context.frontmost && context.timelineWindowAvailable && context.timelineFocused && !context.overlayBlocked && selectedTarget
|
|
5985
|
+
?? (context.available && context.frontmost && context.timelineWindowAvailable && context.timelineFocused && !context.overlayBlocked && selectedTarget
|
|
5697
5986
|
? "ready"
|
|
5698
5987
|
: "unavailable");
|
|
5699
5988
|
const overlay = context.overlayBlocked
|
|
@@ -5717,9 +6006,7 @@ function readinessForContext(context) {
|
|
|
5717
6006
|
? "timeline-focus"
|
|
5718
6007
|
: !selectedTarget
|
|
5719
6008
|
? "target"
|
|
5720
|
-
:
|
|
5721
|
-
? "undo"
|
|
5722
|
-
: undefined;
|
|
6009
|
+
: undefined;
|
|
5723
6010
|
const retryable = context.error?.retryable ?? state !== "ready";
|
|
5724
6011
|
const nextAction = state === "ready"
|
|
5725
6012
|
? "none"
|
|
@@ -5737,8 +6024,8 @@ function readinessForContext(context) {
|
|
|
5737
6024
|
? "Focus the Final Cut Pro timeline and retry"
|
|
5738
6025
|
: firstMissing === "target"
|
|
5739
6026
|
? "Select a single timeline target and retry"
|
|
5740
|
-
:
|
|
5741
|
-
? "
|
|
6027
|
+
: state === "ready"
|
|
6028
|
+
? "Native Final Cut is ready for a guarded mutation; verify operation-specific Undo after execution"
|
|
5742
6029
|
: state === "timeout"
|
|
5743
6030
|
? "Final Cut did not respond before the native deadline; retry"
|
|
5744
6031
|
: state === "cancelled"
|
|
@@ -5805,6 +6092,21 @@ function verifyNativeEdit(operation, before, after) {
|
|
|
5805
6092
|
}
|
|
5806
6093
|
return { verified: true, level: "native-command-accepted", detail: "Final Cut accepted the native menu command" };
|
|
5807
6094
|
}
|
|
6095
|
+
function validateNativeMarkerRange(marker, sequenceStart, sequenceDuration, frameDuration) {
|
|
6096
|
+
if (!marker.name.trim())
|
|
6097
|
+
throw new Error("INVALID_OPERATION: marker name cannot be empty");
|
|
6098
|
+
if (compareRational(marker.duration, zeroRational()) < 0) {
|
|
6099
|
+
throw new Error("INVALID_OPERATION: marker duration must be non-negative");
|
|
6100
|
+
}
|
|
6101
|
+
if (!isFrameAligned(marker.start, sequenceStart, frameDuration)
|
|
6102
|
+
|| !isFrameAligned(marker.duration, zeroRational(), frameDuration)) {
|
|
6103
|
+
throw new Error("INVALID_OPERATION: marker position and duration must be frame-aligned");
|
|
6104
|
+
}
|
|
6105
|
+
if (compareRational(marker.start, sequenceStart) < 0
|
|
6106
|
+
|| compareRational(addRational(marker.start, marker.duration), addRational(sequenceStart, sequenceDuration)) > 0) {
|
|
6107
|
+
throw new Error("INVALID_OPERATION: marker range must fit inside the active sequence");
|
|
6108
|
+
}
|
|
6109
|
+
}
|
|
5808
6110
|
function requiresClip(operation) {
|
|
5809
6111
|
return operation.type === "rename-selected-clip" || operation.type === "trim-selected-clip-to-playhead" || operation.type === "set-selected-clip-gain";
|
|
5810
6112
|
}
|
|
@@ -17,6 +17,10 @@ export class FinalCutSessionAdapter {
|
|
|
17
17
|
}
|
|
18
18
|
if (this.options.snapshot)
|
|
19
19
|
return this.options.snapshot.getIdentity();
|
|
20
|
+
const liveOnly = this.pureLiveProvider();
|
|
21
|
+
if (liveOnly) {
|
|
22
|
+
return liveOnly.getIdentity();
|
|
23
|
+
}
|
|
20
24
|
if (this.options.live) {
|
|
21
25
|
try {
|
|
22
26
|
return await this.options.live.getIdentity();
|
|
@@ -38,7 +42,10 @@ export class FinalCutSessionAdapter {
|
|
|
38
42
|
async getCapabilities(options = {}) {
|
|
39
43
|
const snapshot = await this.options.snapshot?.getCapabilities(options);
|
|
40
44
|
const mutation = await this.options.mutation?.getCapabilities(options);
|
|
41
|
-
const
|
|
45
|
+
const liveOnly = this.pureLiveProvider();
|
|
46
|
+
const live = liveOnly
|
|
47
|
+
? withCanonicalTimelineMode(await liveOnly.getCapabilities(options))
|
|
48
|
+
: await optionalCapabilities(this.options.live, options);
|
|
42
49
|
const hasExplicitDocumentPair = Boolean(this.options.snapshot && this.options.mutation);
|
|
43
50
|
const useLiveCanonical = !this.options.snapshot && !this.options.mutation;
|
|
44
51
|
const liveSnapshot = Boolean(useLiveCanonical
|
|
@@ -328,6 +335,17 @@ export class FinalCutSessionAdapter {
|
|
|
328
335
|
throw new Error("CAPABILITY_UNAVAILABLE: live Final Cut editor state");
|
|
329
336
|
return this.options.live.liveChangesSince(revision, waitMs);
|
|
330
337
|
}
|
|
338
|
+
pureLiveProvider() {
|
|
339
|
+
if (!this.options.live
|
|
340
|
+
|| this.options.snapshot
|
|
341
|
+
|| this.options.mutation
|
|
342
|
+
|| this.options.assets
|
|
343
|
+
|| this.options.media
|
|
344
|
+
|| this.options.backgroundCatalog) {
|
|
345
|
+
return undefined;
|
|
346
|
+
}
|
|
347
|
+
return this.options.live;
|
|
348
|
+
}
|
|
331
349
|
async routedTransactionProvider() {
|
|
332
350
|
if (this.options.snapshot && this.options.mutation)
|
|
333
351
|
return this.options.mutation;
|