@morshoto/framekit 0.1.4 → 0.1.5

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 (24) hide show
  1. package/README.md +2 -2
  2. package/dist-package/adapters/final-cut/typescript/src/analyzers.js +29 -2
  3. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +16 -5
  4. package/dist-package/adapters/final-cut/typescript/src/publisher.js +207 -30
  5. package/dist-package/adapters/final-cut/typescript/src/session.js +69 -8
  6. package/dist-package/apps/mcp-server/src/main.js +1 -0
  7. package/dist-package/apps/mcp-server/src/server.js +136 -68
  8. package/dist-package/apps/mcp-server/src/version.js +34 -0
  9. package/dist-package/packages/runtime/src/application/media-analysis-service.js +117 -14
  10. package/dist-package/packages/runtime/src/application/project-service.js +21 -2
  11. package/dist-package/packages/runtime/src/capabilities.js +85 -10
  12. package/dist-package/packages/runtime/src/context/context-engine.js +10 -1
  13. package/dist-package/packages/runtime/src/domain/media.js +1 -0
  14. package/dist-package/packages/runtime/src/editing/edit-service.js +40 -4
  15. package/dist-package/packages/runtime/src/editing/filler-removal-service.js +31 -7
  16. package/dist-package/packages/runtime/src/index.js +2 -0
  17. package/dist-package/packages/runtime/src/planning/rough-cut.js +9 -3
  18. package/dist-package/packages/runtime/src/runtime.js +2 -2
  19. package/dist-package/packages/runtime/src/speech/analysis.js +301 -0
  20. package/dist-package/packages/runtime/src/speech/mapping.js +227 -0
  21. package/dist-package/packages/runtime/src/timeline/rational-time.js +5 -0
  22. package/dist-package/packages/testkit/src/fixture-analyzers.js +1 -0
  23. package/dist-package/packages/testkit/src/in-memory-editor.js +1 -0
  24. package/package.json +3 -2
package/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  <p align="center">
6
6
  <img src="https://img.shields.io/badge/Node.js-20%2B-339933?logo=node.js&logoColor=white" alt="Node.js 20 or newer" />
7
- <img src="https://img.shields.io/badge/pnpm-11.10.0-F69220?logo=pnpm&logoColor=white" alt="pnpm 11.10.0" />
7
+ <img src="https://img.shields.io/badge/pnpm-12.3.4-F69220?logo=pnpm&logoColor=white" alt="pnpm 12.3.4" />
8
8
  <img src="https://img.shields.io/badge/Final%20Cut%20Pro-macOS-000000?logo=apple&logoColor=white" alt="Final Cut Pro on macOS" />
9
9
  <a href="https://discord.gg/Dmp8FSF4vg"><img src="https://img.shields.io/badge/Discord-Join%20Chat-5865F2?logo=discord&logoColor=white" alt="Join the Framekit Discord" /></a>
10
10
  </p>
@@ -18,7 +18,7 @@ Agentic video editing runtime and MCP server for Final Cut Pro.
18
18
  For repository development, you need:
19
19
 
20
20
  - Node.js 20 or newer;
21
- - pnpm 11.10.0;
21
+ - pnpm 12.3.4;
22
22
  - Xcode 16.4 and the macOS 15.5 SDK for native Final Cut work.
23
23
 
24
24
  The Xcode requirement is only needed for the native Workflow Extension. For the
@@ -1,5 +1,6 @@
1
1
  import { spawn } from "node:child_process";
2
2
  import { access } from "node:fs/promises";
3
+ import { bindSpeechAnalysis } from "../../../../packages/runtime/src/index.js";
3
4
  export function createCommandAnalyzers(options) {
4
5
  return {
5
6
  ...(options.speechCommand ? { speechAnalyzer: new CommandSpeechAnalyzer({ command: options.speechCommand, timeoutMs: options.timeoutMs }) } : {}),
@@ -11,11 +12,18 @@ export function createCommandAnalyzers(options) {
11
12
  export class CommandSpeechAnalyzer {
12
13
  options;
13
14
  descriptor = { id: "command.speech", provider: "command" };
15
+ capabilities = { transcription: true, vad: false };
14
16
  constructor(options) {
15
17
  this.options = options;
16
18
  }
17
19
  async analyze(input, range) {
18
- return runCommand(this.options, { ...input, range }, "speech");
20
+ const result = await runCommand(this.options, { ...input, range }, "speech");
21
+ try {
22
+ return bindSpeechAnalysis(result, { input, range, provider: this.descriptor });
23
+ }
24
+ catch (error) {
25
+ throw new Error(`ANALYZER_INVALID_OUTPUT: speech analyzer returned invalid JSON or schema: ${String(error)}`);
26
+ }
19
27
  }
20
28
  }
21
29
  export class CommandAudioAnalyzer {
@@ -97,9 +105,28 @@ async function runCommand(options, request, kind) {
97
105
  reject(new Error(`ANALYZER_INVALID_OUTPUT: ${kind} analyzer returned invalid JSON or schema: ${String(error)}`));
98
106
  }
99
107
  });
100
- child.stdin.end(JSON.stringify(request));
108
+ child.stdin.end(JSON.stringify(commandRequest(request, kind)));
101
109
  });
102
110
  }
111
+ function commandRequest(request, kind) {
112
+ if (kind !== "speech")
113
+ return request;
114
+ return {
115
+ schemaVersion: 1,
116
+ media: sourceIdentityOf(request.media),
117
+ revision: request.project.revision,
118
+ ...(request.range ? { range: structuredClone(request.range) } : {}),
119
+ };
120
+ }
121
+ function sourceIdentityOf(media) {
122
+ return {
123
+ mediaId: media.mediaId,
124
+ source: media.source,
125
+ ...(media.sourceDigest ? { sourceDigest: media.sourceDigest } : {}),
126
+ ...(media.mediaKind ? { mediaKind: media.mediaKind } : {}),
127
+ ...(media.duration !== undefined ? { duration: media.duration } : {}),
128
+ };
129
+ }
103
130
  function validateResult(value, kind) {
104
131
  if (!value || typeof value !== "object")
105
132
  throw new Error("result must be an object");
@@ -171,7 +171,8 @@ export class FcpxmlDocumentAdapter {
171
171
  }
172
172
  this.applyOperation(operation);
173
173
  }
174
- return this.readProject();
174
+ const preview = await this.readProject();
175
+ return preview;
175
176
  }
176
177
  finally {
177
178
  this.xml = originalXml;
@@ -294,12 +295,18 @@ export class FcpxmlDocumentAdapter {
294
295
  clipFromXml(entry, timelineId) {
295
296
  const { node, kind, path, startTime, durationTime } = entry;
296
297
  const gain = firstChild(node, "adjust-volume");
298
+ const sourceStartValue = attribute(node, "start");
299
+ const sourceStartTime = sourceStartValue === undefined ? undefined : parseRational(sourceStartValue);
300
+ const sourceStart = sourceStartTime === undefined ? undefined : rationalSeconds(sourceStartTime);
301
+ if (sourceStart !== undefined && sourceStart < 0)
302
+ throw new Error("FCPXML_INVALID_TIME: source clip start cannot be negative");
297
303
  return {
298
304
  id: this.instanceId(node, kind, path, timelineId),
299
305
  mediaId: attribute(node, "ref") === undefined ? undefined : String(attribute(node, "ref")),
300
306
  name: String(attribute(node, "name") ?? attribute(node, "ref") ?? `Clip ${path.includes(".") ? path : path + 1}`),
301
307
  start: rationalSeconds(startTime),
302
308
  duration: rationalSeconds(durationTime),
309
+ ...(sourceStart !== undefined ? { sourceStart, sourceStartTime } : {}),
303
310
  track: Number(attribute(node, "lane") ?? 0),
304
311
  startTime,
305
312
  durationTime,
@@ -362,10 +369,14 @@ export class FcpxmlDocumentAdapter {
362
369
  const resources = findElement(this.xml ?? [], "resources");
363
370
  return storyEntries(resources ?? {})
364
371
  .filter(({ kind }) => kind === "asset" || kind === "media" || kind === "effect")
365
- .map(({ node }) => ({
366
- mediaId: String(attribute(node, "id") ?? ""),
367
- source: resolveMediaSource(String(attribute(node, "src") ?? attribute(node, "name") ?? attribute(node, "id") ?? ""), this.filePath),
368
- }))
372
+ .map(({ node }) => {
373
+ const durationValue = attribute(node, "duration");
374
+ return {
375
+ mediaId: String(attribute(node, "id") ?? ""),
376
+ source: resolveMediaSource(String(attribute(node, "src") ?? attribute(node, "name") ?? attribute(node, "id") ?? ""), this.filePath),
377
+ ...(durationValue !== undefined ? { duration: parseSeconds(durationValue) } : {}),
378
+ };
379
+ })
369
380
  .filter((media) => media.mediaId.length > 0);
370
381
  }
371
382
  revision() {
@@ -11,13 +11,15 @@ export class FinalCutProjectPublisher {
11
11
  sourcePath;
12
12
  executor;
13
13
  liveState;
14
- waitMs;
14
+ verificationTimeoutMs;
15
+ pollIntervalMs;
15
16
  constructor(options) {
16
17
  this.enabled = options.enabled ?? false;
17
18
  this.sourcePath = options.sourcePath;
18
19
  this.executor = options.executor ?? runAppleScript;
19
20
  this.liveState = options.liveState;
20
- this.waitMs = options.waitMs ?? 1_500;
21
+ this.verificationTimeoutMs = Math.max(0, options.verificationTimeoutMs ?? 15_000);
22
+ this.pollIntervalMs = Math.max(0, options.pollIntervalMs ?? options.waitMs ?? 100);
21
23
  }
22
24
  isAvailable() {
23
25
  return this.enabled;
@@ -41,41 +43,40 @@ export class FinalCutProjectPublisher {
41
43
  if (!source.includes("<fcpxml") || !source.includes("<project")) {
42
44
  throw new Error("FINAL_CUT_PUBLISH_VALIDATION_FAILED: source is not a valid FCPXML project artifact");
43
45
  }
44
- const projectName = projectNameFromXml(source);
45
- const beforeLive = this.liveState ? await this.liveState() : undefined;
46
+ const identity = projectIdentityFromXml(source);
47
+ if (!this.liveState) {
48
+ throw new Error("FINAL_CUT_PUBLISH_VERIFICATION_UNAVAILABLE: live project and sequence state is required");
49
+ }
50
+ const beforeLive = await readLiveState(this.liveState, "before import");
46
51
  const directory = await mkdtemp(join(tmpdir(), "framekit-finalcut-publish-"));
47
52
  const importedPath = join(directory, basename(this.sourcePath));
48
53
  await writeFile(importedPath, source, "utf8");
49
54
  try {
50
55
  await this.executor(importXmlScript(importedPath));
51
- await delay(this.waitMs);
52
- const live = this.liveState ? await this.liveState() : undefined;
53
- if (live && live.project?.name !== projectName) {
54
- throw new Error(`FINAL_CUT_PUBLISH_VERIFICATION_FAILED: expected new project ${projectName}, observed ${live.project?.name ?? "none"}`);
55
- }
56
+ const live = await waitForImportedProject(this.liveState, identity, beforeLive, this.verificationTimeoutMs, this.pollIntervalMs);
56
57
  return {
57
58
  sourceTransactionId: request.sourceTransactionId,
58
59
  sourcePath: this.sourcePath,
59
60
  sourceTarget: { kind: "artifact", artifactPath: this.sourcePath },
60
61
  importedPath,
61
- projectName,
62
+ projectName: identity.projectName,
62
63
  createdTarget: {
63
64
  kind: "editor.project",
64
65
  ...(live?.project?.id ? { projectId: live.project.id } : {}),
65
66
  ...(live?.sequence?.id ? { sequenceId: live.sequence.id } : {}),
66
- projectName,
67
+ projectName: identity.projectName,
67
68
  ...(live?.sequence?.name ? { sequenceName: live.sequence.name } : {}),
68
69
  },
69
70
  activeProject: {
70
- ...(beforeLive?.project ? { before: beforeLive.project } : {}),
71
- ...(live?.project ? { after: live.project } : {}),
72
- ...(beforeLive?.project && live?.project
71
+ ...(beforeLive.project ? { before: beforeLive.project } : {}),
72
+ ...(live.project ? { after: live.project } : {}),
73
+ ...(beforeLive.project && live.project
73
74
  ? { changed: beforeLive.project.id !== live.project.id || beforeLive.project.name !== live.project.name }
74
75
  : {}),
75
76
  },
76
77
  verified: true,
77
- ...(live?.project?.name ? { liveProject: live.project.name } : {}),
78
- ...(live?.sequence?.name ? { liveSequence: live.sequence.name } : {}),
78
+ ...(live.project?.name ? { liveProject: live.project.name } : {}),
79
+ ...(live.sequence?.name ? { liveSequence: live.sequence.name } : {}),
79
80
  };
80
81
  }
81
82
  finally {
@@ -98,25 +99,157 @@ async function runAppleScript(script) {
98
99
  }
99
100
  function importXmlScript(path) {
100
101
  return `
102
+ using terms from application "System Events"
103
+
104
+ on waitForMenuItem(container, expectedNames, timeoutSeconds, timeoutMessage)
105
+ set deadline to (current date) + timeoutSeconds
106
+ repeat
107
+ repeat with candidate in (menu items of container)
108
+ try
109
+ set candidateName to name of candidate as text
110
+ repeat with expectedName in expectedNames
111
+ if candidateName is (expectedName as text) then return candidate
112
+ end repeat
113
+ end try
114
+ end repeat
115
+ if (current date) > deadline then error timeoutMessage
116
+ delay 0.1
117
+ end repeat
118
+ end waitForMenuItem
119
+
120
+ on waitForSubmenu(menuItem, submenuName, timeoutSeconds, timeoutMessage)
121
+ set deadline to (current date) + timeoutSeconds
122
+ repeat
123
+ try
124
+ if exists menu submenuName of menuItem then return menu submenuName of menuItem
125
+ end try
126
+ if (current date) > deadline then error timeoutMessage
127
+ delay 0.1
128
+ end repeat
129
+ end waitForSubmenu
130
+
131
+ on waitForWindow(finalCut, windowName, timeoutSeconds, timeoutMessage)
132
+ set deadline to (current date) + timeoutSeconds
133
+ repeat
134
+ try
135
+ if exists window windowName of finalCut then return window windowName of finalCut
136
+ end try
137
+ if (current date) > deadline then error timeoutMessage
138
+ delay 0.1
139
+ end repeat
140
+ end waitForWindow
141
+
142
+ on waitForImportSheet(importWindow, timeoutSeconds)
143
+ set deadline to (current date) + timeoutSeconds
144
+ repeat
145
+ try
146
+ if exists sheet 1 of importWindow then return sheet 1 of importWindow
147
+ end try
148
+ if (current date) > deadline then error "FINAL_CUT_PUBLISH_IMPORT_SHEET_TIMEOUT: Import XML sheet did not appear"
149
+ delay 0.1
150
+ end repeat
151
+ end waitForImportSheet
152
+
153
+ on matchesImportPathField(candidate)
154
+ set candidateIdentifier to ""
155
+ set candidateDescription to ""
156
+ try
157
+ set candidateIdentifier to value of attribute "AXIdentifier" of candidate as text
158
+ end try
159
+ try
160
+ set candidateDescription to description of candidate as text
161
+ end try
162
+ if candidateIdentifier is "path" or candidateIdentifier is "location" then return true
163
+ if candidateDescription contains "Go to the folder" then return true
164
+ if candidateDescription contains "path" or candidateDescription contains "location" then return true
165
+ return false
166
+ end matchesImportPathField
167
+
168
+ on locateImportPathField(pathSheet)
169
+ set matchingFields to {}
170
+ repeat with candidate in (text fields of pathSheet)
171
+ if matchesImportPathField(candidate) then set end of matchingFields to candidate
172
+ end repeat
173
+ if (count of matchingFields) is 0 then error "FINAL_CUT_PUBLISH_PATH_CONTROL_UNAVAILABLE: Import XML path control had no accessibility identifier or description"
174
+ if (count of matchingFields) is not 1 then error "FINAL_CUT_PUBLISH_PATH_CONTROL_AMBIGUOUS: Import XML path control was not unique"
175
+ return item 1 of matchingFields
176
+ end locateImportPathField
177
+
178
+ on waitForImportSheetDismissal(importWindow, timeoutSeconds)
179
+ set deadline to (current date) + timeoutSeconds
180
+ repeat
181
+ try
182
+ if not (exists sheet 1 of importWindow) then return
183
+ end try
184
+ if (current date) > deadline then error "FINAL_CUT_PUBLISH_IMPORT_SHEET_DISMISS_TIMEOUT: Import XML sheet did not disappear"
185
+ delay 0.1
186
+ end repeat
187
+ end waitForImportSheetDismissal
188
+
189
+ on waitForImportWindowDismissal(finalCut, timeoutSeconds)
190
+ set deadline to (current date) + timeoutSeconds
191
+ repeat
192
+ try
193
+ if not (exists window "Import XML" of finalCut) then return
194
+ end try
195
+ if (current date) > deadline then error "FINAL_CUT_PUBLISH_IMPORT_TIMEOUT: Import XML window did not close"
196
+ delay 0.1
197
+ end repeat
198
+ end waitForImportWindowDismissal
199
+
200
+ on cancelImportIfOpen(finalCut)
201
+ try
202
+ if exists window "Import XML" of finalCut then
203
+ set importWindow to window "Import XML" of finalCut
204
+ repeat with candidate in (buttons of importWindow)
205
+ try
206
+ if (name of candidate as text) is "Cancel" then
207
+ perform action "AXPress" of candidate
208
+ exit repeat
209
+ end if
210
+ end try
211
+ end repeat
212
+ end if
213
+ end try
214
+ end cancelImportIfOpen
215
+
216
+ end using terms from
217
+
101
218
  tell application "System Events"
102
219
  tell process "Final Cut Pro"
103
- if not frontmost then error number -1719
104
- click menu item "XML..." of menu item "Import" of menu "File" of menu bar 1
105
- delay 0.4
106
- keystroke "g" using {command down}
107
- delay 0.2
108
- set value of first text field of front window to ${appleScriptString(path)}
109
- key code 36
110
- delay 0.5
111
- key code 36
220
+ set finalCut to it
221
+ set importWindow to missing value
222
+ try
223
+ if not frontmost then error number -1719
224
+ set fileMenu to menu "File" of menu bar 1
225
+ set importMenuItem to my waitForMenuItem(fileMenu, {"Import"}, 10, "FINAL_CUT_PUBLISH_IMPORT_MENU_TIMEOUT: File > Import was not exposed")
226
+ perform action "AXPress" of importMenuItem
227
+ set importMenu to my waitForSubmenu(importMenuItem, "Import", 10, "FINAL_CUT_PUBLISH_IMPORT_MENU_TIMEOUT: Import submenu was not exposed")
228
+ set xmlMenuItem to my waitForMenuItem(importMenu, {"XML…", "XML..."}, 10, "FINAL_CUT_PUBLISH_IMPORT_MENU_TIMEOUT: Import XML command was not exposed")
229
+ perform action "AXPress" of xmlMenuItem
230
+ set importWindow to my waitForWindow(finalCut, "Import XML", 10, "FINAL_CUT_PUBLISH_IMPORT_SHEET_TIMEOUT: Import XML sheet did not appear")
231
+ keystroke "g" using {command down, shift down}
232
+ set pathSheet to my waitForImportSheet(importWindow, 10)
233
+ set pathField to my locateImportPathField(pathSheet)
234
+ set value of pathField to ${appleScriptString(path)}
235
+ key code 36
236
+ my waitForImportSheetDismissal(importWindow, 10)
237
+ key code 36
238
+ my waitForImportWindowDismissal(finalCut, 60)
239
+ on error errorMessage number errorNumber
240
+ my cancelImportIfOpen(finalCut)
241
+ error errorMessage number errorNumber
242
+ end try
112
243
  end tell
113
244
  end tell`;
114
245
  }
115
- function projectNameFromXml(source) {
116
- const match = source.match(/<project\b[^>]*\bname="([^"]+)"/);
117
- if (!match?.[1])
246
+ function projectIdentityFromXml(source) {
247
+ const projectMatch = source.match(/<project\b[^>]*\bname="([^"]+)"/);
248
+ if (!projectMatch?.[1])
118
249
  throw new Error("FINAL_CUT_PUBLISH_VALIDATION_FAILED: FCPXML project has no name");
119
- return decodeXml(match[1]);
250
+ const projectName = decodeXml(projectMatch[1]);
251
+ const sequenceMatch = source.match(/<sequence\b[^>]*\bname="([^"]+)"/);
252
+ return { projectName, sequenceName: sequenceMatch?.[1] ? decodeXml(sequenceMatch[1]) : projectName };
120
253
  }
121
254
  function decodeXml(value) {
122
255
  return value
@@ -127,7 +260,51 @@ function decodeXml(value) {
127
260
  .replaceAll("&amp;", "&");
128
261
  }
129
262
  function appleScriptString(value) {
130
- return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replace(/[\\r\\n]/g, " ")}"`;
263
+ return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replace(/[\r\n]/g, " ")}"`;
264
+ }
265
+ async function readLiveState(liveState, phase) {
266
+ try {
267
+ return await liveState();
268
+ }
269
+ catch (error) {
270
+ const detail = error instanceof Error ? error.message : String(error);
271
+ throw new Error(`FINAL_CUT_PUBLISH_STATE_UNAVAILABLE: ${phase}: ${detail}`);
272
+ }
273
+ }
274
+ async function waitForImportedProject(liveState, identity, before, timeoutMs, pollIntervalMs) {
275
+ const deadline = Date.now() + timeoutMs;
276
+ let latest;
277
+ let lastError;
278
+ do {
279
+ try {
280
+ latest = await readLiveState(liveState, "after import");
281
+ lastError = undefined;
282
+ if (isImportedProject(latest, identity, before))
283
+ return latest;
284
+ }
285
+ catch (error) {
286
+ lastError = error;
287
+ }
288
+ if (Date.now() >= deadline)
289
+ break;
290
+ await delay(Math.min(pollIntervalMs, Math.max(0, deadline - Date.now())));
291
+ } while (true);
292
+ if (lastError)
293
+ throw lastError;
294
+ const observedProject = latest?.project?.name ?? "none";
295
+ const observedSequence = latest?.sequence?.name ?? "none";
296
+ throw new Error(`FINAL_CUT_PUBLISH_VERIFICATION_FAILED: expected new project ${identity.projectName} / sequence ${identity.sequenceName}, observed ${observedProject} / ${observedSequence}`);
297
+ }
298
+ function isImportedProject(live, identity, before) {
299
+ if (!live.project || !live.sequence)
300
+ return false;
301
+ if (live.project.name !== identity.projectName || live.sequence.name !== identity.sequenceName)
302
+ return false;
303
+ if (before.project && live.project.id === before.project.id)
304
+ return false;
305
+ if (before.sequence && live.sequence.id === before.sequence.id)
306
+ return false;
307
+ return true;
131
308
  }
132
309
  function delay(milliseconds) {
133
310
  return new Promise((resolvePromise) => setTimeout(resolvePromise, milliseconds));
@@ -43,21 +43,42 @@ export class FinalCutSessionAdapter {
43
43
  && live?.editor.canonicalTimelineMode === "canonical-write"
44
44
  && this.options.live?.apply
45
45
  && this.options.live.restore);
46
- const applyProviderCapabilities = hasExplicitDocumentPair
46
+ const operationRuntimeCapabilities = hasExplicitDocumentPair
47
47
  ? mutation
48
48
  : liveMutation
49
49
  ? live
50
50
  : snapshot;
51
+ const operationCapabilities = operationRuntimeCapabilities?.editor;
52
+ const operationAdapter = hasExplicitDocumentPair
53
+ ? this.options.mutation
54
+ : liveMutation
55
+ ? this.options.live
56
+ : this.options.snapshot;
57
+ const readCapabilities = snapshot ?? (liveSnapshot ? live : undefined);
58
+ const readAdapter = this.options.snapshot ?? (liveSnapshot ? this.options.live : undefined);
59
+ const hasTransactionMethods = Boolean(operationAdapter
60
+ && typeof operationAdapter.previewTransaction === "function"
61
+ && typeof operationAdapter.applyTransaction === "function");
62
+ const canReadAfterWrite = Boolean(readAdapter?.readProject
63
+ && readCapabilities?.editor.readAfterWrite
64
+ && operationCapabilities?.readAfterWrite
65
+ && operationAdapter?.restore
66
+ && operationCapabilities?.rollback);
67
+ const compositeTransactions = Boolean(operationCapabilities?.compositeTransactions
68
+ && hasTransactionMethods
69
+ && canReadAfterWrite);
70
+ const operationFamilies = operationRuntimeCapabilities?.families;
71
+ const readFamilies = readCapabilities?.families;
51
72
  return withCapabilityFamilies({
52
73
  editor: {
74
+ ...operationCapabilities,
53
75
  projectRead: Boolean(snapshot?.editor.projectRead || (liveSnapshot && live?.editor.projectRead)),
54
- timelineSnapshotRead: Boolean(snapshot?.editor.timelineSnapshotRead || liveSnapshot),
55
- timelineWrite: Boolean((hasExplicitDocumentPair && mutation?.editor.timelineWrite) || liveMutation),
56
- timelineArtifactWrite: Boolean(applyProviderCapabilities?.editor.timelineArtifactWrite),
57
- readAfterWrite: Boolean((hasExplicitDocumentPair && snapshot?.editor.readAfterWrite && mutation?.editor.readAfterWrite)
58
- || (liveMutation && live?.editor.readAfterWrite)),
76
+ timelineSnapshotRead: Boolean(readCapabilities?.editor.timelineSnapshotRead),
77
+ timelineWrite: Boolean(operationCapabilities?.timelineWrite),
78
+ timelineArtifactWrite: Boolean(operationCapabilities?.timelineArtifactWrite),
79
+ readAfterWrite: canReadAfterWrite,
59
80
  incrementalChanges: Boolean(live?.editor.incrementalChanges),
60
- rollback: Boolean((hasExplicitDocumentPair && mutation?.editor.rollback) || liveMutation),
81
+ rollback: Boolean(operationCapabilities?.rollback && operationAdapter?.restore),
61
82
  assetDiscovery: Boolean(snapshot?.editor.assetDiscovery || this.options.assets?.listAssets),
62
83
  liveStateRead: Boolean(live?.editor.liveStateRead),
63
84
  playheadWrite: Boolean(live?.editor.playheadWrite),
@@ -65,6 +86,7 @@ export class FinalCutSessionAdapter {
65
86
  playbackControl: Boolean(live?.editor.playbackControl),
66
87
  projectCatalogRead: Boolean(snapshot?.editor.projectCatalogRead || (!this.options.snapshot && live?.editor.projectCatalogRead)),
67
88
  projectSelection: Boolean(snapshot?.editor.projectSelection || (!this.options.snapshot && live?.editor.projectSelection)),
89
+ compositeTransactions,
68
90
  },
69
91
  analyzers: {
70
92
  speechTranscribe: Boolean(snapshot?.analyzers.speechTranscribe || mutation?.analyzers.speechTranscribe || live?.analyzers.speechTranscribe),
@@ -72,7 +94,35 @@ export class FinalCutSessionAdapter {
72
94
  audioLoudness: Boolean(snapshot?.analyzers.audioLoudness || mutation?.analyzers.audioLoudness || live?.analyzers.audioLoudness),
73
95
  visualTrack: Boolean(snapshot?.analyzers.visualTrack || mutation?.analyzers.visualTrack || live?.analyzers.visualTrack),
74
96
  },
75
- }, { backend: "final-cut-session" });
97
+ }, {
98
+ backend: "final-cut-session",
99
+ canonicalDocument: {
100
+ read: readFamilies?.canonicalDocument.read ?? Boolean(readCapabilities?.editor.timelineSnapshotRead),
101
+ write: operationFamilies?.canonicalDocument.write ?? Boolean(operationCapabilities?.timelineWrite),
102
+ artifactWrite: operationFamilies?.canonicalDocument.artifactWrite ?? Boolean(operationCapabilities?.timelineArtifactWrite),
103
+ },
104
+ editing: {
105
+ compositeTransactions: compositeTransactions,
106
+ titlePlacement: operationFamilies?.editing.titlePlacement ?? Boolean(operationCapabilities?.titlePlacement),
107
+ pictureInPicture: operationFamilies?.editing.pictureInPicture ?? false,
108
+ masking: operationFamilies?.editing.masking ?? false,
109
+ },
110
+ editingBackend: operationFamilies?.editing.compositeTransactions.backend,
111
+ });
112
+ }
113
+ async previewTransaction(operations, expectedRevision) {
114
+ const provider = await this.routedTransactionProvider();
115
+ if (!provider?.previewTransaction) {
116
+ throw new Error("CAPABILITY_UNAVAILABLE: editor composite transaction preview");
117
+ }
118
+ return provider.previewTransaction(operations, expectedRevision);
119
+ }
120
+ async applyTransaction(operations, expectedRevision) {
121
+ const provider = await this.routedTransactionProvider();
122
+ if (!provider?.applyTransaction) {
123
+ throw new Error("CAPABILITY_UNAVAILABLE: editor composite transaction execution");
124
+ }
125
+ await provider.applyTransaction(operations, expectedRevision);
76
126
  }
77
127
  async read() {
78
128
  return this.readProject();
@@ -158,6 +208,17 @@ export class FinalCutSessionAdapter {
158
208
  throw new Error("CAPABILITY_UNAVAILABLE: live Final Cut editor state");
159
209
  return this.options.live.liveChangesSince(revision, waitMs);
160
210
  }
211
+ async routedTransactionProvider() {
212
+ if (this.options.snapshot && this.options.mutation)
213
+ return this.options.mutation;
214
+ const liveCapabilities = await optionalCapabilities(this.options.live);
215
+ const liveMutation = Boolean(liveCapabilities?.editor.canonicalTimelineMode === "canonical-write"
216
+ && this.options.live?.apply
217
+ && this.options.live.restore);
218
+ if (liveMutation && this.options.live)
219
+ return this.options.live;
220
+ return this.options.snapshot;
221
+ }
161
222
  }
162
223
  async function optionalCapabilities(live) {
163
224
  if (!live)
@@ -124,6 +124,7 @@ const videoExporter = liveMode && !headlessFinalCut && process.env.FRAMEKIT_FINA
124
124
  })
125
125
  : undefined;
126
126
  const server = createMcpServer(runtime, {
127
+ processMode: liveMode && !headlessFinalCut ? "headed" : "headless",
127
128
  connectionStatus: () => connection?.getStatus(),
128
129
  nativeEditor,
129
130
  disposableNative,