@morshoto/framekit 0.2.2 → 0.2.4

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 (160) hide show
  1. package/dist-package/adapters/final-cut/typescript/src/analyzers.d.ts +58 -0
  2. package/dist-package/adapters/final-cut/typescript/src/analyzers.js +52 -13
  3. package/dist-package/adapters/final-cut/typescript/src/assets.d.ts +24 -0
  4. package/dist-package/adapters/final-cut/typescript/src/background-export.d.ts +98 -0
  5. package/dist-package/adapters/final-cut/typescript/src/background-materialization.d.ts +47 -0
  6. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery-guard.d.ts +32 -0
  7. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery.d.ts +22 -0
  8. package/dist-package/adapters/final-cut/typescript/src/canonical-verification.d.ts +11 -0
  9. package/dist-package/adapters/final-cut/typescript/src/canonical.d.ts +184 -0
  10. package/dist-package/adapters/final-cut/typescript/src/canonical.js +33 -1
  11. package/dist-package/adapters/final-cut/typescript/src/connection.d.ts +103 -0
  12. package/dist-package/adapters/final-cut/typescript/src/disposable-native.d.ts +90 -0
  13. package/dist-package/adapters/final-cut/typescript/src/documents.d.ts +3 -0
  14. package/dist-package/adapters/final-cut/typescript/src/documents.js +3 -0
  15. package/dist-package/adapters/final-cut/typescript/src/experimental.d.ts +8 -0
  16. package/dist-package/adapters/final-cut/typescript/src/export.d.ts +125 -0
  17. package/dist-package/adapters/final-cut/typescript/src/fcpxml-console-experiment.d.ts +54 -0
  18. package/dist-package/adapters/final-cut/typescript/src/fcpxml.d.ts +75 -0
  19. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +6 -1
  20. package/dist-package/adapters/final-cut/typescript/src/index.d.ts +22 -0
  21. package/dist-package/adapters/final-cut/typescript/src/library-inspection.d.ts +101 -0
  22. package/dist-package/adapters/final-cut/typescript/src/live.d.ts +101 -0
  23. package/dist-package/adapters/final-cut/typescript/src/live.js +8 -0
  24. package/dist-package/adapters/final-cut/typescript/src/media.d.ts +12 -0
  25. package/dist-package/adapters/final-cut/typescript/src/native-operation.d.ts +6 -0
  26. package/dist-package/adapters/final-cut/typescript/src/native-recovery-inspection.d.ts +77 -0
  27. package/dist-package/adapters/final-cut/typescript/src/native-session.d.ts +130 -0
  28. package/dist-package/adapters/final-cut/typescript/src/native.d.ts +828 -0
  29. package/dist-package/adapters/final-cut/typescript/src/native.js +274 -107
  30. package/dist-package/adapters/final-cut/typescript/src/pasteboard-snapshot.d.ts +114 -0
  31. package/dist-package/adapters/final-cut/typescript/src/publish-readback.d.ts +26 -0
  32. package/dist-package/adapters/final-cut/typescript/src/publish-readback.js +18 -2
  33. package/dist-package/adapters/final-cut/typescript/src/publisher.d.ts +215 -0
  34. package/dist-package/adapters/final-cut/typescript/src/session.d.ts +43 -0
  35. package/dist-package/adapters/final-cut/typescript/src/shadow-mutation.d.ts +51 -0
  36. package/dist-package/adapters/final-cut/typescript/src/sqlite-experiment.d.ts +156 -0
  37. package/dist-package/adapters/final-cut/typescript/src/sqlite-inspection.d.ts +134 -0
  38. package/dist-package/adapters/final-cut/typescript/src/sqlite-materialization.d.ts +110 -0
  39. package/dist-package/adapters/final-cut/typescript/src/sqlite-wal-observation.d.ts +132 -0
  40. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.d.ts +61 -0
  41. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +28 -4
  42. package/dist-package/adapters/final-cut/typescript/src/unattended-editing.d.ts +54 -0
  43. package/dist-package/adapters/headless/typescript/src/audio-output.d.ts +3 -0
  44. package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.d.ts +11 -0
  45. package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.js +26 -2
  46. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.d.ts +27 -0
  47. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +7 -2
  48. package/dist-package/adapters/headless/typescript/src/ffmpeg-storyboard.d.ts +28 -0
  49. package/dist-package/adapters/headless/typescript/src/ffmpeg-storyboard.js +120 -0
  50. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.d.ts +15 -0
  51. package/dist-package/adapters/headless/typescript/src/index.d.ts +4 -0
  52. package/dist-package/adapters/headless/typescript/src/index.js +1 -0
  53. package/dist-package/apps/cli/src/dev-doctor.d.ts +25 -0
  54. package/dist-package/apps/cli/src/headless-projects.d.ts +3 -0
  55. package/dist-package/apps/cli/src/main.d.ts +10 -0
  56. package/dist-package/apps/mcp-server/runtime/ffmpeg-audio-backend.py +129 -0
  57. package/dist-package/apps/mcp-server/runtime/whisper-speech-backend.py +92 -2
  58. package/dist-package/apps/mcp-server/src/build-alignment.d.ts +10 -0
  59. package/dist-package/apps/mcp-server/src/build-identity.d.ts +7 -0
  60. package/dist-package/apps/mcp-server/src/build-identity.json +2 -2
  61. package/dist-package/apps/mcp-server/src/canonical-native-snapshot.d.ts +8 -0
  62. package/dist-package/apps/mcp-server/src/final-cut-runtime-config.d.ts +5 -0
  63. package/dist-package/apps/mcp-server/src/headless-project-snapshot.d.ts +3 -0
  64. package/dist-package/apps/mcp-server/src/headless-sessions.d.ts +89 -0
  65. package/dist-package/apps/mcp-server/src/main.d.ts +1 -0
  66. package/dist-package/apps/mcp-server/src/main.js +2 -1
  67. package/dist-package/apps/mcp-server/src/materialization-jobs.d.ts +204 -0
  68. package/dist-package/apps/mcp-server/src/readback-policy.d.ts +18 -0
  69. package/dist-package/apps/mcp-server/src/routing.d.ts +90 -0
  70. package/dist-package/apps/mcp-server/src/server.d.ts +75 -0
  71. package/dist-package/apps/mcp-server/src/server.js +93 -9
  72. package/dist-package/apps/mcp-server/src/tools/skills/catalog.d.ts +19 -0
  73. package/dist-package/apps/mcp-server/src/tools/skills/metadata.d.ts +37 -0
  74. package/dist-package/apps/mcp-server/src/tools/skills/register.d.ts +11 -0
  75. package/dist-package/apps/mcp-server/src/version.d.ts +4 -0
  76. package/dist-package/packages/headless-application/src/external-edit.d.ts +30 -0
  77. package/dist-package/packages/headless-application/src/external-edit.js +72 -0
  78. package/dist-package/packages/headless-application/src/headless-projects.d.ts +259 -0
  79. package/dist-package/packages/headless-application/src/headless-projects.js +15 -2
  80. package/dist-package/packages/headless-application/src/index.d.ts +2 -0
  81. package/dist-package/packages/headless-application/src/index.js +1 -0
  82. package/dist-package/packages/runtime/src/application/duration-policy-service.d.ts +4 -0
  83. package/dist-package/packages/runtime/src/application/local-media.d.ts +46 -0
  84. package/dist-package/packages/runtime/src/application/media-analysis-service.d.ts +40 -0
  85. package/dist-package/packages/runtime/src/application/media-analysis-service.js +105 -15
  86. package/dist-package/packages/runtime/src/application/project-service.d.ts +35 -0
  87. package/dist-package/packages/runtime/src/application/project-store.d.ts +56 -0
  88. package/dist-package/packages/runtime/src/application/project-transactions.d.ts +51 -0
  89. package/dist-package/packages/runtime/src/application/runtime-options.d.ts +15 -0
  90. package/dist-package/packages/runtime/src/application/semantic-media-index-store.d.ts +28 -0
  91. package/dist-package/packages/runtime/src/application/transaction-store.d.ts +10 -0
  92. package/dist-package/packages/runtime/src/audio/analysis.d.ts +3 -0
  93. package/dist-package/packages/runtime/src/audio/analysis.js +95 -0
  94. package/dist-package/packages/runtime/src/audio/dialogue-normalization.d.ts +47 -0
  95. package/dist-package/packages/runtime/src/audio/noise-reduction.d.ts +34 -0
  96. package/dist-package/packages/runtime/src/capabilities.d.ts +45 -0
  97. package/dist-package/packages/runtime/src/color-correction.d.ts +33 -0
  98. package/dist-package/packages/runtime/src/context/context-engine.d.ts +28 -0
  99. package/dist-package/packages/runtime/src/context/context-service.d.ts +20 -0
  100. package/dist-package/packages/runtime/src/context/project-catalog.d.ts +12 -0
  101. package/dist-package/packages/runtime/src/context/revision.d.ts +2 -0
  102. package/dist-package/packages/runtime/src/domain/capabilities.d.ts +170 -0
  103. package/dist-package/packages/runtime/src/domain/context.d.ts +179 -0
  104. package/dist-package/packages/runtime/src/domain/diff.d.ts +104 -0
  105. package/dist-package/packages/runtime/src/domain/duration.d.ts +63 -0
  106. package/dist-package/packages/runtime/src/domain/editing.d.ts +227 -0
  107. package/dist-package/packages/runtime/src/domain/incremental-sync.d.ts +67 -0
  108. package/dist-package/packages/runtime/src/domain/index.d.ts +14 -0
  109. package/dist-package/packages/runtime/src/domain/media.d.ts +406 -0
  110. package/dist-package/packages/runtime/src/domain/ports.d.ts +62 -0
  111. package/dist-package/packages/runtime/src/domain/primitives.d.ts +21 -0
  112. package/dist-package/packages/runtime/src/domain/project.d.ts +119 -0
  113. package/dist-package/packages/runtime/src/domain/rough-cut.d.ts +27 -0
  114. package/dist-package/packages/runtime/src/domain/skills.d.ts +145 -0
  115. package/dist-package/packages/runtime/src/domain/timeline-target.d.ts +57 -0
  116. package/dist-package/packages/runtime/src/domain/timeline-target.js +19 -1
  117. package/dist-package/packages/runtime/src/domain/types.d.ts +5 -0
  118. package/dist-package/packages/runtime/src/domain/verification.d.ts +92 -0
  119. package/dist-package/packages/runtime/src/editing/dialogue-normalization-service.d.ts +18 -0
  120. package/dist-package/packages/runtime/src/editing/duration-policy.d.ts +3 -0
  121. package/dist-package/packages/runtime/src/editing/edit-service.d.ts +44 -0
  122. package/dist-package/packages/runtime/src/editing/filler-removal-service.d.ts +23 -0
  123. package/dist-package/packages/runtime/src/editing/intent.d.ts +97 -0
  124. package/dist-package/packages/runtime/src/editing/music-service.d.ts +9 -0
  125. package/dist-package/packages/runtime/src/index.d.ts +32 -0
  126. package/dist-package/packages/runtime/src/index.js +1 -0
  127. package/dist-package/packages/runtime/src/planning/rough-cut.d.ts +3 -0
  128. package/dist-package/packages/runtime/src/render/render-and-verify.d.ts +71 -0
  129. package/dist-package/packages/runtime/src/render/render-contract.d.ts +96 -0
  130. package/dist-package/packages/runtime/src/runtime.d.ts +85 -0
  131. package/dist-package/packages/runtime/src/skills/builtin.d.ts +2 -0
  132. package/dist-package/packages/runtime/src/skills/index.d.ts +3 -0
  133. package/dist-package/packages/runtime/src/skills/registry.d.ts +10 -0
  134. package/dist-package/packages/runtime/src/skills/requirements.d.ts +38 -0
  135. package/dist-package/packages/runtime/src/skills/runtime.d.ts +38 -0
  136. package/dist-package/packages/runtime/src/speech/analysis.d.ts +18 -0
  137. package/dist-package/packages/runtime/src/speech/analysis.js +67 -0
  138. package/dist-package/packages/runtime/src/speech/filler-detector.d.ts +49 -0
  139. package/dist-package/packages/runtime/src/speech/filler-removal.d.ts +37 -0
  140. package/dist-package/packages/runtime/src/speech/mapping.d.ts +56 -0
  141. package/dist-package/packages/runtime/src/speech/mapping.js +27 -4
  142. package/dist-package/packages/runtime/src/speech/safe-cut-resolver.d.ts +52 -0
  143. package/dist-package/packages/runtime/src/timeline/drift-reconciliation.d.ts +42 -0
  144. package/dist-package/packages/runtime/src/timeline/editing-session.d.ts +271 -0
  145. package/dist-package/packages/runtime/src/timeline/editing-session.js +32 -2
  146. package/dist-package/packages/runtime/src/timeline/fast-observation.d.ts +77 -0
  147. package/dist-package/packages/runtime/src/timeline/rational-time.d.ts +11 -0
  148. package/dist-package/packages/runtime/src/timeline/reorder-preview.d.ts +32 -0
  149. package/dist-package/packages/runtime/src/timeline/reorder-preview.js +202 -0
  150. package/dist-package/packages/runtime/src/timeline/snapshot-diff.d.ts +3 -0
  151. package/dist-package/packages/runtime/src/timeline/snapshot-diff.js +1 -0
  152. package/dist-package/packages/runtime/src/timeline/snapshot-digest.d.ts +3 -0
  153. package/dist-package/packages/runtime/src/timeline/snapshot-digest.js +1 -1
  154. package/dist-package/packages/runtime/src/verification/verification.d.ts +6 -0
  155. package/dist-package/packages/testkit/src/fixture-analyzers.d.ts +37 -0
  156. package/dist-package/packages/testkit/src/in-memory-editor.d.ts +55 -0
  157. package/dist-package/packages/testkit/src/index.d.ts +4 -0
  158. package/dist-package/packages/testkit/src/sender-lifecycle-fixture.d.ts +47 -0
  159. package/dist-package/packages/testkit/src/skill-fixtures.d.ts +3 -0
  160. package/package.json +17 -12
@@ -3,7 +3,7 @@ import { createHash } from "node:crypto";
3
3
  import { execFile as execFileCallback } from "node:child_process";
4
4
  import { access, constants, readdir, stat } from "node:fs/promises";
5
5
  import { homedir } from "node:os";
6
- import { basename, dirname, extname, resolve } from "node:path";
6
+ import { basename, dirname, extname, isAbsolute, resolve } from "node:path";
7
7
  import { promisify } from "node:util";
8
8
  import { assertValidTimelineTarget } from "../../../../packages/runtime/src/index.js";
9
9
  const execFile = promisify(execFileCallback);
@@ -88,6 +88,7 @@ export class FinalCutNativeAutomationAdapter {
88
88
  nativeMouseExecutor;
89
89
  canDriveNativeMouse;
90
90
  liveState;
91
+ importSourceObserver;
91
92
  nativeOperationLease;
92
93
  suspendLiveConnection;
93
94
  resumeLiveConnection;
@@ -123,6 +124,7 @@ export class FinalCutNativeAutomationAdapter {
123
124
  this.nativeMouseExecutor = options.nativeMouseExecutor;
124
125
  this.canDriveNativeMouse = options.executor === undefined;
125
126
  this.liveState = options.liveState;
127
+ this.importSourceObserver = options.importSourceObserver;
126
128
  this.nativeOperationLease = options.nativeOperationLease;
127
129
  this.suspendLiveConnection = options.suspendLiveConnection;
128
130
  this.resumeLiveConnection = options.resumeLiveConnection;
@@ -138,7 +140,7 @@ export class FinalCutNativeAutomationAdapter {
138
140
  selectionEdit: this.enabled,
139
141
  undo: this.enabled,
140
142
  mediaLibrarySearch: this.enabled,
141
- mediaImport: this.enabled,
143
+ mediaImport: this.enabled && Boolean(this.importSourceObserver),
142
144
  mediaSelection: this.enabled,
143
145
  mediaAppendSelected: this.enabled,
144
146
  timelineOccurrenceLocate: this.enabled,
@@ -401,8 +403,40 @@ export class FinalCutNativeAutomationAdapter {
401
403
  throw new Error(`FINAL_CUT_NATIVE_UNDO_UNAVAILABLE: unknown operation ${operationId}`);
402
404
  if (this.latestOperationId !== operationId)
403
405
  throw new Error("FINAL_CUT_NATIVE_UNDO_STALE: operation is no longer the latest native edit");
406
+ if (operation.kind === "blade" && operation.undoDispatched) {
407
+ throw new Error("FINAL_CUT_NATIVE_UNDO_OUTCOME_UNCERTAIN: Blade Undo may already have been dispatched; recovery is required");
408
+ }
409
+ if (operation.kind === "media-insertion" && operation.undoDispatched) {
410
+ throw new Error("FINAL_CUT_NATIVE_UNDO_UNCERTAIN: placement Undo may already have been dispatched");
411
+ }
404
412
  const before = await this.requireTimelineContext();
405
413
  const currentLive = await this.readLiveState();
414
+ if (operation.kind === "blade") {
415
+ const projectId = operation.beforeLive?.project?.id;
416
+ const sequenceId = operation.beforeLive?.sequence?.id;
417
+ if (!projectId || !sequenceId || operation.afterLive?.project?.id !== projectId
418
+ || operation.afterLive?.sequence?.id !== sequenceId || currentLive?.project?.id !== projectId
419
+ || currentLive?.sequence?.id !== sequenceId || before.target.projectId !== projectId
420
+ || before.target.sequenceId !== sequenceId || before.target.revision?.id !== currentLive?.revision.id
421
+ || before.target.revision?.sequence !== currentLive?.revision.sequence
422
+ || operation.afterLive.revision.sequence !== currentLive?.revision.sequence) {
423
+ throw new Error("FINAL_CUT_NATIVE_UNDO_TARGET_CHANGED: Blade target or revision is unavailable or changed");
424
+ }
425
+ }
426
+ if (operation.kind === "media-insertion") {
427
+ const expectedProject = operation.beforeLive?.project?.id;
428
+ const expectedSequence = operation.beforeLive?.sequence?.id;
429
+ if (!expectedProject || !expectedSequence
430
+ || operation.afterLive?.project?.id !== expectedProject || operation.afterLive?.sequence?.id !== expectedSequence
431
+ || currentLive?.project?.id !== expectedProject || currentLive?.sequence?.id !== expectedSequence
432
+ || before.target.projectId !== expectedProject || before.target.sequenceId !== expectedSequence
433
+ || !before.target.revision?.id || before.target.revision.id !== currentLive.revision?.id
434
+ || before.target.revision.sequence !== currentLive.revision?.sequence
435
+ || operation.afterLive.revision.id !== currentLive.revision?.id
436
+ || operation.afterLive.revision.sequence !== currentLive.revision?.sequence) {
437
+ throw new Error("FINAL_CUT_NATIVE_UNDO_TARGET_CHANGED: placement target is unavailable or changed");
438
+ }
439
+ }
406
440
  if (operation.afterLive && currentLive && operation.afterLive.revision.id !== currentLive.revision.id) {
407
441
  throw new Error("FINAL_CUT_NATIVE_UNDO_STALE: Final Cut timeline changed after the native edit");
408
442
  }
@@ -422,16 +456,33 @@ export class FinalCutNativeAutomationAdapter {
422
456
  throw new Error("FINAL_CUT_NATIVE_UNDO_COMMAND_CHANGED: Final Cut's current Undo command does not match the native edit");
423
457
  }
424
458
  try {
425
- await this.executeNativeCommand(undoScript(operation.undoCommand), (recovered) => {
426
- this.assertRetryContext(before, recovered);
427
- if (!recovered.undoAvailable || recovered.undoCommand !== operation.undoCommand) {
428
- throw new Error("FINAL_CUT_NATIVE_UNDO_COMMAND_CHANGED: Final Cut's current Undo command does not match the native edit");
459
+ if (operation.kind === "blade" || operation.kind === "media-insertion") {
460
+ if (operation.undoDispatched) {
461
+ throw new Error(operation.kind === "blade"
462
+ ? "FINAL_CUT_NATIVE_UNDO_OUTCOME_UNCERTAIN: Blade Undo may already have been dispatched; recovery is required"
463
+ : "FINAL_CUT_NATIVE_UNDO_UNCERTAIN: placement Undo may already have been dispatched");
429
464
  }
430
- });
465
+ // Once invocation begins, neither an error nor stale readback proves Undo did not run.
466
+ operation.undoDispatched = true;
467
+ await this.executeNativeScript(undoScript(operation.undoCommand));
468
+ }
469
+ else {
470
+ await this.executeNativeCommand(undoScript(operation.undoCommand), (recovered) => {
471
+ this.assertRetryContext(before, recovered);
472
+ if (!recovered.undoAvailable || recovered.undoCommand !== operation.undoCommand) {
473
+ throw new Error("FINAL_CUT_NATIVE_UNDO_COMMAND_CHANGED: Final Cut's current Undo command does not match the native edit");
474
+ }
475
+ });
476
+ }
431
477
  }
432
478
  catch (error) {
479
+ if (operation.kind === "blade")
480
+ throw new Error(`FINAL_CUT_NATIVE_UNDO_OUTCOME_UNCERTAIN: Blade Undo may have been applied; recovery is required: ${String(error)}`);
433
481
  throw new Error(`${nativeErrorCode(error)}: ${String(error)}`);
434
482
  }
483
+ if (operation.kind === "blade") {
484
+ throw new Error("FINAL_CUT_NATIVE_UNDO_VERIFICATION_FAILED: canonical restoration and source coverage are unavailable; recovery is required");
485
+ }
435
486
  const after = await this.requireTimelineContext();
436
487
  const afterLive = await this.waitForUndo(operation);
437
488
  const verification = verifyNativeUndo(operation, after, afterLive);
@@ -442,7 +493,19 @@ export class FinalCutNativeAutomationAdapter {
442
493
  return { operationId, undone: true, context: after, verification };
443
494
  }
444
495
  async importMedia(sourcePath, options = {}) {
445
- return this.withNativeUi(() => this.importMediaNative(sourcePath), options.signal);
496
+ this.assertEnabled();
497
+ if (!this.importSourceObserver) {
498
+ throw new NativeFinalCutMediaImportError("CAPABILITY_UNAVAILABLE", "native media import requires independently observed original source binding", {
499
+ stage: "pre-import-browser-discovery", elapsedMs: 0, stageElapsedMs: 0, partialImportPossible: false,
500
+ });
501
+ }
502
+ const expectedTarget = normalizeNativeImportTarget(options.expectedImportTarget);
503
+ if (!expectedTarget) {
504
+ throw new NativeFinalCutMediaImportError("TARGET_MISMATCH", "an approved native import target is required", {
505
+ stage: "pre-import-browser-discovery", elapsedMs: 0, stageElapsedMs: 0, partialImportPossible: false,
506
+ });
507
+ }
508
+ return this.withNativeUi(() => this.importMediaNative(sourcePath, expectedTarget), options.signal);
446
509
  }
447
510
  async previewImportMediaDirectory(directoryPath, options = {}) {
448
511
  return this.requestContext.run(options, () => this.previewImportMediaDirectoryNative(directoryPath));
@@ -454,12 +517,14 @@ export class FinalCutNativeAutomationAdapter {
454
517
  throw new Error("INVALID_OPERATION: local media directory path cannot be empty");
455
518
  const normalizedPath = resolveLocalPath(trimmedPath, this.homeDirectory);
456
519
  const snapshot = await snapshotSupportedVideoFiles(normalizedPath);
520
+ const expectedImportTarget = normalizeNativeImportTarget(this.requestContext.getStore()?.expectedImportTarget);
457
521
  const expiresAt = this.now() + 30_000;
458
522
  const previewToken = opaqueHandle("media-directory-preview");
459
523
  this.mediaImportDirectoryPreviews.set(previewToken, {
460
524
  directoryPath: normalizedPath,
461
525
  files: snapshot.files,
462
526
  fileIdentities: snapshot.fileIdentities,
527
+ ...(expectedImportTarget ? { expectedImportTarget } : {}),
463
528
  expiresAt,
464
529
  });
465
530
  return {
@@ -467,13 +532,19 @@ export class FinalCutNativeAutomationAdapter {
467
532
  directoryPath: normalizedPath,
468
533
  files: structuredClone(snapshot.files),
469
534
  command: "Import all previewed video files",
535
+ ...(expectedImportTarget ? { expectedImportTarget } : {}),
470
536
  expiresAt: new Date(expiresAt).toISOString(),
471
537
  };
472
538
  }
473
539
  async executeImportMediaDirectory(previewToken, confirm, options = {}) {
540
+ if (!this.importSourceObserver)
541
+ return this.executeImportMediaDirectoryNative(previewToken, confirm);
542
+ if (!this.mediaImportDirectoryPreviews.get(previewToken)?.expectedImportTarget) {
543
+ throw new Error("TARGET_MISMATCH: an approved native import target must be bound to the directory preview");
544
+ }
474
545
  return this.withNativeUi(() => this.executeImportMediaDirectoryNative(previewToken, confirm), options.signal);
475
546
  }
476
- async importMediaNative(sourcePath) {
547
+ async importMediaNative(sourcePath, approvedTarget) {
477
548
  this.assertEnabled();
478
549
  const importStartedAt = this.now();
479
550
  let stage = "pre-import-browser-discovery";
@@ -510,6 +581,14 @@ export class FinalCutNativeAutomationAdapter {
510
581
  throw new Error(`FINAL_CUT_NATIVE_MEDIA_PATH_UNAVAILABLE: ${normalizedPath} is not a readable local media file (${String(error)})`);
511
582
  }
512
583
  try {
584
+ const observer = this.importSourceObserver;
585
+ if (!observer)
586
+ return fail("CAPABILITY_UNAVAILABLE", "independent original source observation is unavailable", false);
587
+ const expectedTarget = normalizeNativeImportTarget(await observer.captureTarget());
588
+ if (!expectedTarget)
589
+ return fail("CAPABILITY_UNAVAILABLE", "independent native import target observation is unavailable", false);
590
+ if (!sameNativeImportTarget(approvedTarget, expectedTarget))
591
+ return fail("TARGET_MISMATCH", "observed native import target does not match approval", false);
513
592
  const beforeDiscoveryDeadline = this.now() + this.mediaImportDiscoveryTimeoutMs;
514
593
  await this.ensureBrowserReady(beforeDiscoveryDeadline, "FINAL_CUT_NATIVE_MEDIA_IMPORT_DISCOVERY_TIMEOUT");
515
594
  const beforeMatches = await this.searchMediaNative(name, beforeDiscoveryDeadline, "FINAL_CUT_NATIVE_MEDIA_IMPORT_DISCOVERY_TIMEOUT");
@@ -521,6 +600,12 @@ export class FinalCutNativeAutomationAdapter {
521
600
  if (hasIndistinguishablePreExistingMatch) {
522
601
  fail("FINAL_CUT_NATIVE_MEDIA_IMPORT_IDENTITY_UNAVAILABLE", `Final Cut did not expose an immutable Browser source identity for pre-existing ${name}`, false);
523
602
  }
603
+ // Browser discovery can change the active context. Recheck immediately
604
+ // before dispatch; this does not replace receiver-side target fencing.
605
+ const dispatchTarget = normalizeNativeImportTarget(await observer.captureTarget());
606
+ if (!sameNativeImportTarget(expectedTarget, dispatchTarget)) {
607
+ return fail("TARGET_MISMATCH", "native import target changed during Browser discovery", false);
608
+ }
524
609
  beginStage("native-import-ui");
525
610
  partialImportPossible = true;
526
611
  try {
@@ -568,6 +653,19 @@ export class FinalCutNativeAutomationAdapter {
568
653
  fail("FINAL_CUT_NATIVE_MEDIA_IMPORT_IDENTITY_UNAVAILABLE", `Final Cut did not expose an immutable Browser source identity for ${name}`, true);
569
654
  throw new Error("unreachable");
570
655
  }
656
+ // The observer receives only the independently identified Browser item,
657
+ // never the requested source path. A matching name or requested path is
658
+ // not evidence that the item actually references the original source.
659
+ const observed = await observer.observeImportedSource(identity);
660
+ const observedTarget = normalizeNativeImportTarget(observed?.target);
661
+ const currentTarget = normalizeNativeImportTarget(await observer.captureTarget());
662
+ if (!observed || observed.sourceIdentity !== identity
663
+ || typeof observed.originalSourcePath !== "string" || !isAbsolute(observed.originalSourcePath)
664
+ || observed.originalSourcePath !== normalizedPath
665
+ || !sameNativeImportTarget(expectedTarget, observedTarget)
666
+ || !sameNativeImportTarget(expectedTarget, currentTarget)) {
667
+ return fail("FINAL_CUT_NATIVE_MEDIA_IMPORT_SOURCE_MISMATCH", "independent original source or native target observation does not match the approved import", true);
668
+ }
571
669
  const mediaHandle = this.stableMediaHandle(identity);
572
670
  const stableMatch = { ...match, handle: mediaHandle };
573
671
  this.stableMediaHandles.set(identity, mediaHandle);
@@ -581,7 +679,7 @@ export class FinalCutNativeAutomationAdapter {
581
679
  verification: {
582
680
  verified: true,
583
681
  stage: "post-import-browser-discovery",
584
- detail: "Final Cut exposed one newly imported Browser asset with immutable source identity",
682
+ detail: "An independent observation bound the imported Browser identity to the original source and native target",
585
683
  },
586
684
  };
587
685
  }
@@ -614,9 +712,14 @@ export class FinalCutNativeAutomationAdapter {
614
712
  throw new Error("FINAL_CUT_NATIVE_PREVIEW_STALE: media directory preview has expired");
615
713
  await assertMediaImportDirectoryPreviewFresh(preview);
616
714
  const results = [];
715
+ let stopped = false;
617
716
  for (const file of preview.files) {
717
+ if (stopped) {
718
+ results.push({ sourcePath: file.sourcePath, name: file.name, status: "not-attempted" });
719
+ continue;
720
+ }
618
721
  try {
619
- const media = await this.importMedia(file.sourcePath);
722
+ const media = await this.importMedia(file.sourcePath, { expectedImportTarget: preview.expectedImportTarget });
620
723
  results.push({
621
724
  sourcePath: file.sourcePath,
622
725
  name: file.name,
@@ -625,6 +728,9 @@ export class FinalCutNativeAutomationAdapter {
625
728
  });
626
729
  }
627
730
  catch (error) {
731
+ // A failed provider may have dispatched or scheduled work even when
732
+ // it did not acknowledge it. Do not start another file in this batch.
733
+ stopped = true;
628
734
  const serializedError = serializeNativeFinalCutMediaImportError(error);
629
735
  results.push({
630
736
  sourcePath: file.sourcePath,
@@ -638,7 +744,8 @@ export class FinalCutNativeAutomationAdapter {
638
744
  }
639
745
  }
640
746
  const importedCount = results.filter((result) => result.status === "imported").length;
641
- const failedCount = results.length - importedCount;
747
+ const failedCount = results.filter((result) => result.status === "failed").length;
748
+ const notAttemptedCount = results.filter((result) => result.status === "not-attempted").length;
642
749
  return {
643
750
  previewToken,
644
751
  directoryPath: preview.directoryPath,
@@ -646,6 +753,7 @@ export class FinalCutNativeAutomationAdapter {
646
753
  results,
647
754
  importedCount,
648
755
  failedCount,
756
+ ...(notAttemptedCount > 0 ? { notAttemptedCount } : {}),
649
757
  partial: importedCount > 0 && failedCount > 0,
650
758
  status: failedCount === 0 ? "completed" : importedCount > 0 ? "partial" : "failed",
651
759
  };
@@ -671,11 +779,24 @@ export class FinalCutNativeAutomationAdapter {
671
779
  throw new Error("FINAL_CUT_NATIVE_NOT_FRONTMOST: Final Cut's Browser must be frontmost");
672
780
  try {
673
781
  const searchDeadline = deadline ?? this.now() + this.mediaImportDiscoveryTimeoutMs;
674
- const output = await this.executeNativeScript(searchMediaScript(query), searchDeadline, timeoutCode);
782
+ const response = await this.executeNativeScript(searchMediaScript(query), searchDeadline, timeoutCode);
783
+ if (!response.trim())
784
+ throw new Error("FINAL_CUT_NATIVE_SEARCH_UNAVAILABLE: missing Browser media scan output");
785
+ const output = response.trim() === "__FRAMEKIT_BROWSER_SCAN_EMPTY__" ? "" : response;
786
+ if (output.split(String.fromCharCode(30)).some((record) => record === "__FRAMEKIT_BROWSER_SCAN_INCOMPLETE__")) {
787
+ throw new Error("FINAL_CUT_NATIVE_SEARCH_UNAVAILABLE: Browser media scan was incomplete");
788
+ }
675
789
  const explicitFailure = output.trim();
676
790
  if (explicitFailure.startsWith("FINAL_CUT_NATIVE_SEARCH_UNAVAILABLE")) {
677
791
  throw new Error(explicitFailure);
678
792
  }
793
+ if (explicitFailure && (!explicitFailure.endsWith(String.fromCharCode(30))
794
+ || explicitFailure.slice(0, -1).split(String.fromCharCode(30)).some((record) => {
795
+ const fields = record.split(String.fromCharCode(31));
796
+ return fields.length !== 4 || !fields[0]?.trim() || !fields[1]?.trim();
797
+ }))) {
798
+ throw new Error("FINAL_CUT_NATIVE_SEARCH_UNAVAILABLE: malformed Browser media scan output");
799
+ }
679
800
  const rawMatches = parseMediaMatches(output);
680
801
  const normalizedQuery = query.toLocaleLowerCase();
681
802
  if (rawMatches.some((match) => !browserMediaIdentity(match) && match.name.toLocaleLowerCase().includes(normalizedQuery))) {
@@ -992,12 +1113,17 @@ export class FinalCutNativeAutomationAdapter {
992
1113
  if (context.target.name && context.target.name !== occurrence.name) {
993
1114
  throw new Error("FINAL_CUT_NATIVE_OCCURRENCE_HANDLE_STALE: selected timeline occurrence changed");
994
1115
  }
1116
+ if (!occurrence.nativeIdentity || context.target.identity !== occurrence.nativeIdentity) {
1117
+ throw new Error("FINAL_CUT_NATIVE_OCCURRENCE_HANDLE_STALE: selected timeline occurrence identity is unavailable or changed");
1118
+ }
995
1119
  await this.validateOccurrenceBinding(occurrence);
996
1120
  if (!context.bladeAvailable)
997
1121
  throw new Error("FINAL_CUT_NATIVE_PLAYHEAD_OUTSIDE_OCCURRENCE: Final Cut has disabled Blade for the current selection/playhead");
1122
+ const live = await this.readLiveState();
1123
+ const media = this.mediaHandles.get(occurrence.mediaHandle);
998
1124
  const expiresAtMs = this.now() + 30_000;
999
1125
  const previewToken = opaqueHandle("blade-preview");
1000
- this.bladePreviews.set(previewToken, { occurrence, expiresAt: expiresAtMs });
1126
+ this.bladePreviews.set(previewToken, { occurrence: structuredClone(occurrence), ...(media ? { media: structuredClone(media) } : {}), context: structuredClone(context), ...(live ? { live: structuredClone(live) } : {}), expiresAt: expiresAtMs });
1001
1127
  return {
1002
1128
  previewToken,
1003
1129
  occurrence,
@@ -1167,51 +1293,88 @@ export class FinalCutNativeAutomationAdapter {
1167
1293
  if (before.target.name && before.target.name !== preview.occurrence.name) {
1168
1294
  throw new Error("FINAL_CUT_NATIVE_OCCURRENCE_HANDLE_STALE: selected timeline occurrence changed");
1169
1295
  }
1296
+ this.assertBladePreviewBinding(preview, before, beforeLive);
1170
1297
  await this.validateOccurrenceBinding(preview.occurrence);
1171
- if (!before.bladeAvailable)
1298
+ const finalContext = await this.requireNativeWriteContext();
1299
+ const finalLive = await this.readLiveState();
1300
+ this.assertBladePreviewBinding(preview, finalContext, finalLive);
1301
+ if (!finalContext.frontmost)
1302
+ throw new Error("FINAL_CUT_NATIVE_NOT_FRONTMOST: Final Cut's timeline must be frontmost");
1303
+ if (!finalContext.bladeAvailable)
1172
1304
  throw new Error("FINAL_CUT_NATIVE_PLAYHEAD_OUTSIDE_OCCURRENCE: Final Cut has disabled Blade for the current selection/playhead");
1305
+ const media = this.mediaHandles.get(preview.occurrence.mediaHandle);
1306
+ if (!preview.media || !media || media.name !== preview.occurrence.name || media.name !== preview.media.name
1307
+ || !browserMediaIdentity(media) || browserMediaIdentity(media) !== browserMediaIdentity(preview.media)) {
1308
+ throw new Error("FINAL_CUT_NATIVE_MEDIA_HANDLE_STALE: Blade Browser identity is unavailable or changed");
1309
+ }
1173
1310
  try {
1174
- await this.executeNativeCommand(bladeScript(), async (recovered) => {
1175
- this.assertRetryContext(before, recovered, true);
1176
- await this.validateOccurrenceBinding(preview.occurrence);
1177
- if (!recovered.bladeAvailable)
1178
- throw new Error("FINAL_CUT_NATIVE_PLAYHEAD_OUTSIDE_OCCURRENCE: Final Cut has disabled Blade for the current selection/playhead");
1179
- });
1311
+ await this.executeNativeScript(bladeScript());
1180
1312
  }
1181
1313
  catch (error) {
1182
- throw new Error(`${nativeErrorCode(error)}: ${String(error)}`);
1314
+ throw new Error(`FINAL_CUT_NATIVE_BLADE_OUTCOME_UNCERTAIN: Blade may have been applied; do not retry without recovery: ${String(error)}`);
1183
1315
  }
1184
- const after = await this.requireTimelineContext();
1185
- if (!after.frontmost)
1186
- throw new Error("FINAL_CUT_NATIVE_VERIFICATION_FAILED: Final Cut changed focus during Blade");
1187
- const afterLive = await this.readLiveState();
1188
- const resultingSegments = parseOccurrences(await this.executeNativeScript(locateOccurrenceScript({ handle: preview.occurrence.mediaHandle, name: preview.occurrence.name }, true)), preview.occurrence.mediaHandle);
1189
- normalizeOccurrenceTimes(resultingSegments, afterLive?.sequence);
1190
- if (resultingSegments.length < 2) {
1191
- throw new Error("FINAL_CUT_NATIVE_VERIFICATION_FAILED: Final Cut did not expose two resulting timeline segments after Blade");
1316
+ try {
1317
+ const after = await this.requireTimelineContext();
1318
+ if (!after.frontmost)
1319
+ throw new Error("FINAL_CUT_NATIVE_VERIFICATION_FAILED: Final Cut changed focus during Blade");
1320
+ const afterLive = await this.readLiveState();
1321
+ const resultingSegments = parseOccurrences(await this.executeNativeScript(locateOccurrenceScript(media, true)), preview.occurrence.mediaHandle);
1322
+ normalizeOccurrenceTimes(resultingSegments, afterLive?.sequence);
1323
+ if (resultingSegments.length < 2) {
1324
+ throw new Error("FINAL_CUT_NATIVE_VERIFICATION_FAILED: Final Cut did not expose two resulting timeline segments after Blade");
1325
+ }
1326
+ const operationId = opaqueHandle("native-blade");
1327
+ const operation = {
1328
+ kind: "blade",
1329
+ before: finalContext,
1330
+ after,
1331
+ beforeLive: finalLive,
1332
+ afterLive,
1333
+ undoCommand: after.undoCommand,
1334
+ };
1335
+ this.rememberOperation(operationId, operation);
1336
+ this.assertNativeRollbackReady(operationId, "Blade", operation);
1337
+ return {
1338
+ operationId,
1339
+ previewToken,
1340
+ occurrence: preview.occurrence,
1341
+ resultingSegments,
1342
+ before: finalContext,
1343
+ after,
1344
+ verification: { verified: false, detail: "Final Cut exposed UI rows after Blade; original source and canonical split remain unverified; do not retry without recovery" },
1345
+ undoAvailable: after.undoAvailable,
1346
+ ...(after.undoCommand ? { undoCommand: after.undoCommand } : {}),
1347
+ };
1348
+ }
1349
+ catch (error) {
1350
+ if (error instanceof NativeFinalCutPartialMutationError)
1351
+ throw error;
1352
+ throw new Error(`FINAL_CUT_NATIVE_BLADE_OUTCOME_UNCERTAIN: Blade may have been applied; do not retry without recovery: ${String(error)}`);
1353
+ }
1354
+ }
1355
+ assertBladePreviewBinding(preview, before, beforeLive) {
1356
+ const original = preview.live;
1357
+ const originalScope = preview.context.target;
1358
+ const currentScope = before.target;
1359
+ if (!original?.project?.id || !original.sequence?.id || !original.playheadTime
1360
+ || !beforeLive?.project?.id || !beforeLive.sequence?.id || !beforeLive.playheadTime
1361
+ || !preview.context.playheadTime || !before.playheadTime
1362
+ || currentScope.kind !== "selected-clip" || !preview.occurrence.nativeIdentity
1363
+ || originalScope.identity !== preview.occurrence.nativeIdentity || currentScope.identity !== preview.occurrence.nativeIdentity
1364
+ || currentScope.name !== originalScope.name
1365
+ || originalScope.projectId !== original.project.id || originalScope.sequenceId !== original.sequence.id
1366
+ || originalScope.revision?.id !== original.revision.id || originalScope.revision?.sequence !== original.revision.sequence
1367
+ || currentScope.projectId !== beforeLive.project.id || currentScope.sequenceId !== beforeLive.sequence.id
1368
+ || currentScope.revision?.id !== beforeLive.revision.id || currentScope.revision?.sequence !== beforeLive.revision.sequence
1369
+ || original.project.id !== beforeLive.project.id || original.sequence.id !== beforeLive.sequence.id
1370
+ || original.revision.id !== beforeLive.revision.id || original.revision.sequence !== beforeLive.revision.sequence
1371
+ || compareRational(parseRationalString(preview.context.playheadTime, "preview playhead"), original.playheadTime) !== 0
1372
+ || compareRational(parseRationalString(before.playheadTime, "current playhead"), beforeLive.playheadTime) !== 0
1373
+ || compareRational(original.playheadTime, beforeLive.playheadTime) !== 0
1374
+ || compareRational(original.sequence.startTime, beforeLive.sequence.startTime) !== 0
1375
+ || compareRational(original.sequence.frameDuration, beforeLive.sequence.frameDuration) !== 0) {
1376
+ throw new Error("FINAL_CUT_NATIVE_PREVIEW_STALE: Blade target, frame grid, revision, or playhead changed or is unavailable");
1192
1377
  }
1193
- const operationId = opaqueHandle("native-blade");
1194
- const operation = {
1195
- kind: "blade",
1196
- before,
1197
- after,
1198
- beforeLive,
1199
- afterLive,
1200
- undoCommand: after.undoCommand,
1201
- };
1202
- this.rememberOperation(operationId, operation);
1203
- this.assertNativeRollbackReady(operationId, "Blade", operation);
1204
- return {
1205
- operationId,
1206
- previewToken,
1207
- occurrence: preview.occurrence,
1208
- resultingSegments,
1209
- before,
1210
- after,
1211
- verification: { verified: true, detail: "Final Cut accepted the Blade command while the target remained frontmost" },
1212
- undoAvailable: after.undoAvailable,
1213
- ...(after.undoCommand ? { undoCommand: after.undoCommand } : {}),
1214
- };
1215
1378
  }
1216
1379
  async previewDeleteRange(range, options = {}) {
1217
1380
  return this.withNativeUi(() => this.previewRangeNative("delete-range", range), options.signal);
@@ -1853,6 +2016,10 @@ export class FinalCutNativeAutomationAdapter {
1853
2016
  if (!context.frontmost)
1854
2017
  throw new Error("FINAL_CUT_NATIVE_NOT_FRONTMOST: Final Cut's timeline must be frontmost");
1855
2018
  const live = await this.requireLiveState();
2019
+ if (!live.project?.id)
2020
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project identity is required for media insertion");
2021
+ if (!live.sequence?.id)
2022
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut sequence identity is required for media insertion");
1856
2023
  const sequenceStart = live.sequenceTimeRange?.start ?? live.sequence?.startTime;
1857
2024
  const beforeDuration = live.sequenceTimeRange?.duration ?? live.sequence?.duration;
1858
2025
  if (!sequenceStart || !beforeDuration)
@@ -1870,7 +2037,8 @@ export class FinalCutNativeAutomationAdapter {
1870
2037
  selectionMode,
1871
2038
  beforeDuration,
1872
2039
  insertionTime,
1873
- sequenceId: live.sequence?.id,
2040
+ projectId: live.project.id,
2041
+ sequenceId: live.sequence.id,
1874
2042
  revision: live.revision.id,
1875
2043
  expiresAt,
1876
2044
  });
@@ -1916,21 +2084,19 @@ export class FinalCutNativeAutomationAdapter {
1916
2084
  if (preview.selectionMode === "handle")
1917
2085
  await this.selectMediaNative(preview.mediaHandle);
1918
2086
  await this.focusTimelineForMediaInsertion();
1919
- await this.executeNativeCommand(mediaInsertionScript(preview.operation), async (recovered) => {
1920
- this.assertRetryContext(before, recovered, preview.operation === "insert");
1921
- if (preview.selectionMode === "handle")
1922
- await this.selectMediaNative(preview.mediaHandle);
1923
- const refocused = await this.prepareNativeRetry();
1924
- this.assertRetryContext(before, refocused, preview.operation === "insert");
1925
- await this.focusTimelineForMediaInsertion();
1926
- this.validateMediaInsertionBinding(preview, await this.requireLiveState());
1927
- if (preview.selectionMode === "selected")
1928
- await this.validateSelectedMediaBinding(media);
1929
- });
2087
+ this.validateMediaInsertionBinding(preview, await this.requireLiveState());
1930
2088
  }
1931
2089
  catch (error) {
1932
2090
  throw new Error(`${nativeErrorCode(error)}: ${String(error)}`);
1933
2091
  }
2092
+ try {
2093
+ // A transport or focus error can arrive after the shortcut was issued.
2094
+ // Without a receiver completion receipt, retrying can duplicate the edit.
2095
+ await this.executeNativeScript(mediaInsertionScript(preview.operation));
2096
+ }
2097
+ catch (error) {
2098
+ throw new Error(`FINAL_CUT_NATIVE_PLACEMENT_OUTCOME_UNCERTAIN: placement may have been applied; recovery is required before retry: ${String(error)}`);
2099
+ }
1934
2100
  const operationId = opaqueHandle(`native-${preview.operation}-media`);
1935
2101
  let after;
1936
2102
  let afterLive;
@@ -1939,30 +2105,10 @@ export class FinalCutNativeAutomationAdapter {
1939
2105
  afterLive = await this.waitForMediaInsertion(preview.beforeDuration, beforeLive.revision.id);
1940
2106
  }
1941
2107
  catch (error) {
1942
- const observedContext = after ?? await this.inspectRawNative();
1943
- const observedLive = afterLive ?? await this.readLiveState();
1944
- if (observedLive && mediaInsertionMutationObserved(beforeLive, observedLive) && observedContext.undoCommand) {
1945
- this.rememberOperation(operationId, {
1946
- kind: "media-insertion",
1947
- before,
1948
- after: observedContext,
1949
- beforeLive,
1950
- afterLive: observedLive,
1951
- beforeDuration: preview.beforeDuration,
1952
- undoCommand: observedContext.undoCommand,
1953
- });
1954
- try {
1955
- await this.undo(operationId);
1956
- }
1957
- catch (rollbackError) {
1958
- throw new Error(`${nativeErrorCode(error)}: ${String(error)}; operationId=${operationId}; native rollback failed: ${String(rollbackError)}`);
1959
- }
1960
- throw new Error(`${nativeErrorCode(error)}: ${String(error)}; insertion was rolled back`);
1961
- }
1962
- throw new Error(`${nativeErrorCode(error)}: ${String(error)}; post-command state was not safely recoverable, so no Undo handle was retained`);
2108
+ throw new Error(`${nativeErrorCode(error)}: ${String(error)}; placement may have been applied and recovery is required before retry`);
1963
2109
  }
1964
2110
  const afterDuration = afterLive.sequenceTimeRange?.duration ?? afterLive.sequence?.duration;
1965
- const verification = mediaInsertionVerificationDetail(afterDuration, preview.beforeDuration, afterLive.revision.id, beforeLive.revision.id);
2111
+ const observation = mediaInsertionVerificationDetail(afterDuration, preview.beforeDuration, afterLive.revision.id, beforeLive.revision.id);
1966
2112
  const operation = {
1967
2113
  kind: "media-insertion",
1968
2114
  before,
@@ -1972,18 +2118,8 @@ export class FinalCutNativeAutomationAdapter {
1972
2118
  beforeDuration: preview.beforeDuration,
1973
2119
  undoCommand: after.undoCommand,
1974
2120
  };
1975
- if (!verification.verified) {
1976
- if (mediaInsertionMutationObserved(beforeLive, afterLive) && after.undoAvailable && after.undoCommand) {
1977
- this.rememberOperation(operationId, operation);
1978
- try {
1979
- await this.undo(operationId);
1980
- }
1981
- catch (rollbackError) {
1982
- throw new Error(`FINAL_CUT_NATIVE_VERIFICATION_FAILED: ${verification.detail}; operationId=${operationId}; native rollback failed: ${String(rollbackError)}`);
1983
- }
1984
- throw new Error(`FINAL_CUT_NATIVE_VERIFICATION_FAILED: ${verification.detail}; insertion was rolled back`);
1985
- }
1986
- throw new Error(`FINAL_CUT_NATIVE_VERIFICATION_FAILED: ${verification.detail}`);
2121
+ if (!observation.verified) {
2122
+ throw new Error(`FINAL_CUT_NATIVE_VERIFICATION_FAILED: ${observation.detail}; placement may have been applied and recovery is required before retry`);
1987
2123
  }
1988
2124
  this.rememberOperation(operationId, operation);
1989
2125
  this.assertNativeRollbackReady(operationId, `${preview.operation} media insertion`, operation);
@@ -1998,7 +2134,7 @@ export class FinalCutNativeAutomationAdapter {
1998
2134
  afterDuration: afterDuration,
1999
2135
  beforeRevision: beforeLive.revision,
2000
2136
  afterRevision: afterLive.revision,
2001
- verification,
2137
+ verification: { verified: false, detail: `${observation.detail}; canonical source and placement are unverified; recovery is required` },
2002
2138
  undoAvailable: after.undoAvailable,
2003
2139
  ...(after.undoCommand ? { undoCommand: after.undoCommand } : {}),
2004
2140
  };
@@ -2164,7 +2300,9 @@ export class FinalCutNativeAutomationAdapter {
2164
2300
  return this.liveState();
2165
2301
  }
2166
2302
  validateMediaInsertionBinding(preview, live) {
2167
- if (preview.sequenceId && live.sequence?.id !== preview.sequenceId)
2303
+ if (live.project?.id !== preview.projectId)
2304
+ throw new Error("FINAL_CUT_NATIVE_PREVIEW_STALE: active project changed");
2305
+ if (live.sequence?.id !== preview.sequenceId)
2168
2306
  throw new Error("FINAL_CUT_NATIVE_PREVIEW_STALE: active sequence changed");
2169
2307
  if (live.revision.id !== preview.revision)
2170
2308
  throw new Error("FINAL_CUT_NATIVE_PREVIEW_STALE: playhead or timeline revision changed");
@@ -2172,6 +2310,10 @@ export class FinalCutNativeAutomationAdapter {
2172
2310
  if (!currentDuration || compareRational(currentDuration, preview.beforeDuration) !== 0) {
2173
2311
  throw new Error("FINAL_CUT_NATIVE_PREVIEW_STALE: sequence duration changed");
2174
2312
  }
2313
+ const currentStart = live.sequenceTimeRange?.start ?? live.sequence?.startTime;
2314
+ if (preview.operation === "append" && (!currentStart || compareRational(addRational(currentStart, currentDuration), preview.insertionTime) !== 0)) {
2315
+ throw new Error("FINAL_CUT_NATIVE_PREVIEW_STALE: append insertion position changed");
2316
+ }
2175
2317
  if (preview.operation === "insert" && (!live.playheadTime || compareRational(live.playheadTime, preview.insertionTime) !== 0)) {
2176
2318
  throw new Error("FINAL_CUT_NATIVE_PREVIEW_STALE: playhead changed");
2177
2319
  }
@@ -2834,6 +2976,14 @@ function nativeRollbackEvidence(record) {
2834
2976
  };
2835
2977
  }
2836
2978
  function verifyNativeUndo(operation, after, afterLive) {
2979
+ if (operation.kind === "media-insertion") {
2980
+ const expectedProject = operation.beforeLive?.project?.id;
2981
+ const expectedSequence = operation.beforeLive?.sequence?.id;
2982
+ if (!expectedProject || !expectedSequence || afterLive?.project?.id !== expectedProject || afterLive?.sequence?.id !== expectedSequence) {
2983
+ return { verified: false, detail: "project or sequence target changed during Undo" };
2984
+ }
2985
+ return { verified: false, detail: "canonical restoration and source integrity are unavailable; recovery is required" };
2986
+ }
2837
2987
  const liveRevisionAdvanced = Boolean(operation.afterLive
2838
2988
  && afterLive
2839
2989
  && afterLive.revision.id !== operation.afterLive.revision.id);
@@ -4002,6 +4152,7 @@ function searchMediaScript(query) {
4002
4152
  key code 36
4003
4153
  delay 0.5
4004
4154
  set output to my collectBrowserMedia(browserRoot, 0, searchQuery, origin, browserRootContext, {}, "root")
4155
+ if output is "" then return "__FRAMEKIT_BROWSER_SCAN_EMPTY__"
4005
4156
  return output
4006
4157
  end tell
4007
4158
  end tell`;
@@ -4454,7 +4605,15 @@ function browserMediaTraversalScript() {
4454
4605
  on collectBrowserMedia(containerItem, depth, searchQuery, origin, inheritedContext, seenIdentities, browserPath)
4455
4606
  set maxDepth to 12
4456
4607
  if inheritedContext then set maxDepth to 6
4457
- if depth > maxDepth then return ""
4608
+ if depth > maxDepth then
4609
+ try
4610
+ tell application "System Events" to set remainingItems to UI elements of containerItem
4611
+ if (count of remainingItems) > 0 then return "__FRAMEKIT_BROWSER_SCAN_INCOMPLETE__" & (ASCII character 30)
4612
+ return ""
4613
+ on error
4614
+ return "__FRAMEKIT_BROWSER_SCAN_INCOMPLETE__" & (ASCII character 30)
4615
+ end try
4616
+ end if
4458
4617
  set output to ""
4459
4618
  set mediaContext to my mediaContainer(containerItem, inheritedContext)
4460
4619
  tell application "System Events"
@@ -4514,7 +4673,8 @@ function browserMediaTraversalScript() {
4514
4673
  end if
4515
4674
  set output to output & my collectBrowserMedia(candidate, depth + 1, searchQuery, origin, candidateMediaContext, seenIdentities, candidatePath)
4516
4675
  on error
4517
- -- Ignore inaccessible descendants and continue enumerating Browser results.
4676
+ -- Preserve incomplete-scan evidence rather than reporting an empty result.
4677
+ set output to output & "__FRAMEKIT_BROWSER_SCAN_INCOMPLETE__" & (ASCII character 30)
4518
4678
  end try
4519
4679
  end repeat
4520
4680
  on error
@@ -6088,6 +6248,18 @@ function classifyNativeFocusTarget(focusedRole, focusedDescription, focusedName)
6088
6248
  return "browser";
6089
6249
  return "unknown";
6090
6250
  }
6251
+ function normalizeNativeImportTarget(value) {
6252
+ if (!value || typeof value !== "object")
6253
+ return undefined;
6254
+ const { libraryId, eventId, projectId, sequenceId, revision } = value;
6255
+ if (![libraryId, eventId, projectId, sequenceId, revision].every((item) => typeof item === "string" && item.trim().length > 0))
6256
+ return undefined;
6257
+ return { libraryId, eventId, projectId, sequenceId, revision };
6258
+ }
6259
+ function sameNativeImportTarget(expected, actual) {
6260
+ return Boolean(actual && expected.libraryId === actual.libraryId && expected.eventId === actual.eventId
6261
+ && expected.projectId === actual.projectId && expected.sequenceId === actual.sequenceId && expected.revision === actual.revision);
6262
+ }
6091
6263
  function parseMediaMatches(output) {
6092
6264
  return output
6093
6265
  .split(String.fromCharCode(30))
@@ -6373,11 +6545,6 @@ function mediaInsertionVerificationDetail(actual, before, revision, previousRevi
6373
6545
  return { verified: false, detail: "Final Cut did not expose a new revision after media insertion" };
6374
6546
  return { verified: true, detail: `Final Cut exposed resulting duration ${actual.value}/${actual.timescale} at revision ${revision}` };
6375
6547
  }
6376
- function mediaInsertionMutationObserved(before, after) {
6377
- const beforeDuration = before.sequenceTimeRange?.duration ?? before.sequence?.duration;
6378
- const afterDuration = after.sequenceTimeRange?.duration ?? after.sequence?.duration;
6379
- return Boolean(beforeDuration && afterDuration && compareRational(afterDuration, beforeDuration) > 0);
6380
- }
6381
6548
  function readinessForContext(context) {
6382
6549
  const selectedTarget = context.target.kind !== "none" && context.target.kind !== "unknown";
6383
6550
  const targetBound = context.target.kind === "selected-clip"