@morshoto/framekit 0.1.11 → 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.
@@ -2,6 +2,8 @@ export * from "./fcpxml.js";
2
2
  export * from "./live.js";
3
3
  export * from "./connection.js";
4
4
  export * from "./canonical.js";
5
+ export * from "./canonical-recovery.js";
6
+ export * from "./canonical-verification.js";
5
7
  export * from "./session.js";
6
8
  export * from "./analyzers.js";
7
9
  export * from "./assets.js";
@@ -14,6 +16,7 @@ export * from "./background-export.js";
14
16
  export * from "./background-materialization.js";
15
17
  export * from "./library-inspection.js";
16
18
  export * from "./sqlite-inspection.js";
19
+ export * from "./sqlite-experiment.js";
17
20
  export * from "./shadow-mutation.js";
18
21
  export * from "./native-operation.js";
19
22
  export * from "./native-session.js";
@@ -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, { kind: "selection", before, after, beforeLive, afterLive, undoCommand: after.undoCommand });
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 (!operation.undoCommand || before.undoCommand !== operation.undoCommand) {
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
- this.rememberOperation(operationId, { kind: "blade", before, after, beforeLive: undefined, afterLive, undoCommand: after.undoCommand });
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
- this.rememberOperation(operationId, {
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
- if (!context.undoAvailable) {
2209
- throw new Error("FINAL_CUT_NATIVE_UNDO_UNAVAILABLE: Final Cut has no available Undo command; native writes require an available Undo command");
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 && context.undoAvailable
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
- : !context.undoAvailable
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
- : firstMissing === "undo"
5741
- ? "Enable an Undo command in Final Cut Pro and retry"
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
  }